[ewels]

The Nextflow adapter now links most of what the VS Code language server gives hover help for, and reads its names from the API index that each Nextflow language server release publishes (nextflow-io/language-server#201), instead of a reference bundled in this package. A new apiIndex() adapter links the names of any language or library that publishes an index in the same format. It also fixes ext linking in one nf-core blog code block and not in another.

• The ext bug
  • The tokenizer ended a string at the first newline, so a multi-line ${…} in a container string read as unbalanced code. The process body closed early, and nothing after it linked.
  • ${…} in double-quoted strings is now read as code, over any number of lines. Single quotes, ''' and \$ do not interpolate.
  • Names in $name and ${…} link as they do in code, so ${task.cpus}, $projectDir and ${workflow.runName} link.
• What links now
  • Keywords (process, workflow, include, params {, output {, enum, record) and the section labels of processes and workflows.
  • Legacy qualifiers and output options, and in a typed process, the stage directives and output functions (stageAs, file(), eval()).
  • task.* properties and directive values, feature flags, every config setting (dotted, in scope blocks, nested, and unscoped), and the members of the standard library types.
• Type tracking
  • Types come from name: Type declarations, legacy path inputs, and assignments from typed values. A variable that gets two different types has none.
  • The adapter follows the type that each member gives, so fasta.name.toUpperCase() links both members, and the members of a type's parents link too (List has the members of Iterable).
  • Operators link on process and workflow outputs: x = PROC(...), PROC.out.zip.collect() and typed Channel<…> inputs.
• Names from the language server
  • By default the adapter reads api-index.json of the latest language server release. The build fetches it once and keeps it in node_modules/.cache/starlight-codeblocks/, as it does Sphinx inventories.
  • version pins a release, such as 26.10.1, for the docs of an older Nextflow version. index takes another index: a URL, a file path, or the object itself.
  • If the index does not load, the build warns and the adapter links only the modules from the modules option.
  • Removed: nextflow-reference-data.ts (3,500 lines), the hand-written factories and operators, and scripts/nextflow-reference.mjs. The package no longer needs a release when Nextflow adds a directive or a setting.
• API index adapter
  • apiIndex({ languages, index, syntax? }) from starlight-codeblocks/adapters/api-index. The format is a JSON file of names, each with a kind, a docs link and, optionally, a signature, summary, type, the types it extends, and a context.
  • It links global names, each part of a dotted name, and members through type and extends, also on variables with a name: Type declaration or one type in every assignment.
  • Names with a context need an adapter that knows the language's grammar, as the Nextflow adapter does. The docs page describes the format, and the "Write an API link adapter" page points to it.
  • The tokenizer moved to tokens.ts, with settings for line comments, quotes and interpolated quotes.
• Changes to existing output
  • Card texts and signatures come from nf-lang, as in the VS Code hover: cpus reads "The cpus directive allows you to define the number of (logical) CPUs required by each task." Some nf-lang descriptions are imperative ("Get a file…"); that is for nf-lang to change.
  • docker.enabled links to the setting (reference/config/docker#dockerenabled), not the docker scope. docker { still links the scope.
  • each links as a legacy input qualifier, and a bracketed file(…) in an output: section reads as the typed function, because the legacy file qualifier is deprecated.
• Kept out
  • Members of closure parameters ({ bam -> bam.name }), operators after |, and names in config values other than task.*.
  • Anchors on qualifiers, type members and the standard library: their headings come from signatures, so those links go to the page or section.
  • The card shows a summary as plain text, so the backticks in nf-lang descriptions show. Rendering inline code in the card is a follow-up.
• Depends on Add an API index of the language as a release asset nextflow-io/language-server#201
  • Until a language server release has api-index.json, the default fetch fails: the build warns, the Nextflow examples on the docs site link only modules, and the API links e2e spec fails on them. Unit tests have no network and use test/fixtures/nextflow-api-index.json: the 140 names that the tests use, from the index that Add an API index of the language as a release asset nextflow-io/language-server#201 builds. They check the adapter's rules, since the language server checks the index itself.
• Verification
  • pnpm lint, pnpm test (508 tests), pnpm lint:docs, pnpm docs:build with no warnings and the api-links Playwright spec (30 tests) pass with the docs site reading the snapshot.
  • The blog post's samtools module gets the same 34 links as before the switch to the index.
  • No CHANGELOG entry, for the release.

🤖 Generated with Claude Code

[ewels]

Instead of vendoring all of this Nextflow stuff into every codeblocks install, I'd prefer to get it published by the Nextflow language server repo instead (or Nextflow) and load it dynamically, keeping this library as lightweight and generic as possible.

See nextflow-io/language-server#201