Sort includes when formatting

[ewels]

Adds include sorting to the nf-lang formatter, resolving nextflow-io/language-server#54. When the sort-declarations option is enabled, include { ... } from '...' statements are sorted alphabetically by their source path. This is one of the formatter follow-ups deferred from #7346.

Sorting happens within blank-line-separated groups: groups stay in place and keep their blank-line separators, and only the includes inside a group are reordered. This preserves the common convention of grouping includes (e.g. local modules vs nf-core modules) rather than collapsing everything into one alphabetised block.

The main subtlety is that, in the current comment architecture, blank lines are derived from each node's original source line, so naively reordering nodes misplaces the surrounding blank lines. The sorted path therefore emits group separators and leading comments explicitly (via small Formatter/CommentAttacher helpers) instead of relying on source positions. Comments travel with their include; a comment above the first include of a group is treated as a group header and pinned to the top of the group. That header heuristic is the one debatable behaviour here — it favours the common "section header above a group" case at the cost of a first-include-specific comment, and is easy to drop if reviewers prefer comments always stick to their include.

This is the first of a short stack of formatter follow-up PRs (the others cover blank-line normalisation, line wrapping, and fmt: directives).

Assisted-by: Claude Opus 4.8 (Claude Code)

Example

With -sort-declarations enabled, each blank-line-separated block of includes is sorted alphabetically by source path, independently of the others — so the two blocks below are each ordered internally but never merged.

Before:

include { MULTIQC } from './modules/local/multiqc.nf'
include { FASTQC } from './modules/local/fastqc.nf'
include { TRIMGALORE } from './modules/local/trimgalore.nf'

// sorting happens within each blank-line-separated block, never across blocks
include { SAMTOOLS_SORT } from './modules/nf-core/samtools/sort'
include { BWA_MEM } from './modules/nf-core/bwa/mem'
include { PICARD_MARKDUPLICATES } from './modules/nf-core/picard/markduplicates'

After:

include { FASTQC } from './modules/local/fastqc.nf'
include { MULTIQC } from './modules/local/multiqc.nf'
include { TRIMGALORE } from './modules/local/trimgalore.nf'

// sorting happens within each blank-line-separated block, never across blocks
include { BWA_MEM } from './modules/nf-core/bwa/mem'
include { PICARD_MARKDUPLICATES } from './modules/nf-core/picard/markduplicates'
include { SAMTOOLS_SORT } from './modules/nf-core/samtools/sort'

[netlify]

✅ Deploy Preview for nextflow-docs canceled.

Name	Link
🔨 Latest commit	118d30d
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs/deploys/6a88026f2261150008599e91