Add module spec command

[jorgee]

Summary

• Adds nextflow module generate-meta CLI subcommand that parses a module's main.nf and generates a meta.yml template pre-populated with all inferable values
• Supports both V1 (classic qualifier syntax: val, path, tuple) and V2 (static type syntax: reads: Path, (meta, reads): Tuple<String, Path>)
• Implements two-pass static analysis for V2 output type inference: builds a symbol map from input parameters and exec block assignments, then resolves output types via declared type → symbol map lookup → RHS expression inference chain
• Adds -force flag to overwrite an existing meta.yml and -dry-run flag to print to stdout without writing

Changes

• CmdModule.groovy — registers the new generate-meta subcommand
• ModuleGenerateMeta.groovy — CLI entry point with path resolution, overwrite guard, dry-run routing
• MetaYmlGenerator.groovy — AST extraction (V1 + V2) and YAML rendering via SnakeYAML
• MetaYmlGeneratorTest.groovy — 14 Spock unit tests covering V1 qualifiers, V2 typed inputs, symbol map inference, tuple sub-entries, YAML rendering
• ModuleGenerateMetaTest.groovy — 10 Spock CLI tests covering generation, overwrite guard, dry-run, error cases
• VariableScopeVisitor.java — minor related fix

Test plan

• Run ./gradlew :nextflow:test --tests "nextflow.module.MetaYmlGeneratorTest" — all 14 tests pass
• Run ./gradlew :nextflow:test --tests "nextflow.cli.module.ModuleGenerateMetaTest" — CLI tests pass
• Manual: nextflow module generate-meta <module-dir> generates a valid meta.yml
• Manual: re-running without -force errors; with -force regenerates; -dry-run prints to stdout

🤖 Generated with Claude Code

[jorgee]

Changes since initial PR

MetaYmlGenerator.groovy

path() type resolution (extractPathMethodType)

• Wildcard patterns (*, ?, {}, []) → list
• Literal filenames → file
• arity: '1' → file; any other arity (e.g. '1..*') → list

Tuple rendering (buildChannelList)

• Tuples are now rendered as nested YAML lists instead of being flattened into the parent list
• Named tuples (declared with emit:) are wrapped under their emit identifier key: {emit_name: [sub_entries...]}
• Anonymous tuples (no emit name) render as a plain nested list: [[sub_entries...]]

V1 emit: support (extractV1Tuple)

• Reads the emit: named argument from V1 tuple outputs and uses it as the tuple's channel identifier

NamedArgumentListExpression handling

• extractIdentifierFromArgs now skips a leading named-argument map so qualifiers with options (e.g. path "*.bam", arity: '1') correctly extract the pattern as the identifier
• Same fix applied in extractTupleSubEntries

Tools placeholder removed

• The tools: section is no longer generated; it must be filled in manually

New RenderOptions class

• Holds the five required manifest fields: name, version, description, license, authors
• Any null field falls back to a TODO: placeholder; provided values are written as-is

Updated YAML header

• Now includes guidance on reviewing auto-detected val types and path patterns

ModuleGenerateMeta.groovy

Five new CLI flags for required manifest fields:

Flag	Description
-name	Module name in scope/name format
-version	Module version
-description	Short description
-license	SPDX license identifier
-author	Author name (repeatable)

Tests

MetaYmlGeneratorTest.groovy — expanded from 14 to 37 tests:

• Full coverage of all V1 input/output qualifiers: val, path, file (deprecated), env, stdin, stdout, tuple
• All glob wildcard variants (*, ?, {}, []) via parameterised test
• path arity combinations for both V1 and V2
• V2 path(), env(), and stdout() output expressions
• Tuple render tests using SnakeYAML round-trip assertion (parse YAML back and verify structure)
• RenderOptions tests: provided values used verbatim; null values fall back to TODO placeholders

ModuleGenerateMetaTest.groovy — two new tests:

• Provided CLI flags appear in the output with no TODO placeholders for those fields
• Omitted CLI flags produce TODO placeholders

Docs

• docs/cli.md — added ### Generating module metadata narrative section with flag table and type-detection guidance
• docs/reference/cli.md — added full generate-meta subcommand reference entry (anchor cli-module-generate-meta) with all flags, type hints, and examples

[jorgee]

Update:

• Rename generate-meta subcommand by spec
• Allow module reference as primary argument and add -scope when fullname is not possible
• Remove TODOS in module fields. Still in input/output descriptions or when no type could be inferred.
• Input/Output validation in ModuleSpec to avoid pushing arguments with TODOs
• Some refactor: ModuleGenerataMeta renamed to CmdModuleSpec and MetaYmlGenerator integrated in ModuleSpec

[pditommaso]

Nit, I'd likely call this create-meta there's a more canonical term for file creation (I understand that now "generate" feels trendy ..)

[pditommaso]

Code Review Findings

Critical (Must Fix)

1. Bug: authors guarded by license check in asMap()
ModuleSpec.groovy:293-294 — checks this.license instead of this.authors:

// CURRENT (wrong)
if( this.license )
    manifest['authors'] = this.authors

// FIX
if( this.authors )
    manifest['authors'] = this.authors

Authors will be silently dropped when license is null, or emit null when license is set but authors isn't.

2. Potential NPE in extractMethodCallType
ModuleSpec.groovy:776 — methodTarget can be null for unresolved method calls:

// CURRENT (missing null-safe on methodTarget)
return resolveTypeFromDeclaredType(simpleTypeName(methodExpr.methodTarget.returnType?.name))

// FIX
return resolveTypeFromDeclaredType(simpleTypeName(methodExpr.methodTarget?.returnType?.name))

---

Important (Should Fix)

#	Issue	Location
3	YAML header still says generate-meta instead of spec	ModuleSpec.groovy:58
4	moduleName field lacks type declaration in @CompileStatic class	CmdModuleSpec.groovy:71
5	validate() checks type.equals(DESCRIPTION_TODO) — should be description.equals(DESCRIPTION_TODO)	ModuleSpec.groovy:87
6	resolveAsPath uses args[0] instead of module param	CmdModuleSpec.groovy:129

---

Suggestions

• buildParamSpec always emits DESCRIPTION_TODO even if entry.description is already populated (line 323)
• load() doesn't close the InputStream from Files.newInputStream (line 141)
• Log messages reference $args (full list) instead of $module (lines 117, 119, 123)
• No test covering the authors field rendering in asMap() — would have caught bug A process that define only an input of type 'each' never stops #1

---

🤖 Generated with Claude Code

[jorgee]

Nit, I'd likely call this create-meta there's a more canonical term for file creation (I understand that now "generate" feels trendy ..)

@ben suggested to call it 'spec'. This is the name in the current implementation. 'create-meta', 'create-spec' are also good alternatives to me.

I fixed other issues and comments. Apart from the name, it is ready for review from my side

[netlify]

✅ Deploy Preview for nextflow-docs-staging canceled.

Name	Link
🔨 Latest commit	1b8ffcc
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/69d3dd2f02c313000895d667

[pditommaso]

What's the state of this?

[bentsherman]

Jorge has done his part. I'm going to test it, clean it up, and try to merge this week