Netsukefile Linter

The command

netsuke check analyses the manifest selected by the existing root --file and --directory flags, and adds four flags of its own. Machine output uses the global --json, not a check-specific flag.

$ netsuke check
$ netsuke check --explain
$ netsuke check --explain directory-dep-not-order-only
$ netsuke check --rule clarity=off --rule literal-recipe-path=error --fail-on warning
$ netsuke --json check

Rule catalogue

Twenty-four rules across nine categories. A rule is a stable, self-describing kebab-case name that is unique across every stage and category; the name is what appears in policy selectors, suppression directives, --explain, and the code and span label of each JSON finding, and it never changes. Category is metadata, so recategorizing a rule cannot invalidate a configuration file. Each finding also carries a diagnostic code of the form netsuke::lint::<name_in_snake_case> and a url into the rule reference.

Rules default to off only when they encode a project convention rather than a defect: building a target by name without declaring it a default is a legitimate workflow, and rule descriptions are a house style. The two migration rules catch stale workarounds. Doubling a dollar ($$PATH) became a bug once Netsuke escaped dollars at the Ninja writer (ADR-014, shipped in v0.1.0-beta3); see markers and shell dollars. On the branch, legacy-placeholder flags $in/$out because they were still substituted during lowering while the users’ guide documented only {{ ins }} and {{ outs }}. Main has since gone further: ADR-034 makes $in and $out plain shell variables in every recipe, so this rule’s rationale will need revising when #621 rebases.

One rule, worked

undeclared-target-input: Ninja schedules edges concurrently unless a dependency orders them. A recipe that reads a path another target produces, without declaring it, races — it succeeds whenever the producer happened to run first. Serial local builds hide this; a parallel or clean build does not.

targets:
  - name: app
    command: "cc build/main.o -o {{ outs }}"
  - name: build/main.o
    command: "cc -c src/main.c -o {{ outs }}"

targets:
  - name: app
    sources: build/main.o
    command: "cc {{ ins }} -o {{ outs }}"
  - name: build/main.o
    command: "cc -c src/main.c -o {{ outs }}"

Remediation, as the rule reference states it: declare the path under sources if the recipe reads it, or under deps if it only needs it to exist.

Policy and suppression

[cmds.check]
rule = ["clarity=off", "unreachable-target=warning"]
fail_on = "warning"

targets:
  # netsuke-lint: allow background-job -- the previewer is intentionally detached
  - name: preview
    script: |
      feh processed &

Output

Human findings render through the existing diagnostics reporter, so they inherit source snippets and the project's colour, emoji, and accessibility policies, followed by a summary line stating the count at each severity and any truncation. With --json the command emits exactly one document in the shared envelope. When no finding reaches the threshold, a result document goes to stdout; when one does, a diagnostic document goes to stderr with the same finding objects under diagnostics[0].related, preserving the envelope invariant every other command follows.

{
  "schema_version": 1,
  "generator": { "name": "netsuke", "version": "0.4.0" },
  "result": {
    "command": "check",
    "status": "pass",
    "fail_on": "error",
    "summary": { "error": 0, "warning": 2, "advice": 1,
                 "reported": 3, "suppressed": 1, "omitted": 0 },
    "truncated": false,
    "findings": [
      {
        "message": "depends on the directory `build` through `deps`",
        "code": "netsuke::lint::directory_dep_not_order_only",
        "severity": "warning",
        "help": "Move the directory to `order_only_deps`, which guarantees it exists first without tracking its timestamp.",
        "url": "https://github.com/leynos/netsuke/blob/main/docs/netsuke-linter-rules.md#directory-dep-not-order-only",
        "primary_span": { "line": 24, "column": 7, "snippet": "      - \"{{ build_dir }}\"" }
      }
    ]
  }
}

From the shallow end

The first step is one bare command with nothing to configure. netsuke check loads, expands, renders, and lowers the manifest through the same stages as a build, with impure template helpers disabled; no recipe runs and no build output is created. The branch’s migration note says it plainly: existing manifests need no changes, because checking is read-only. Everything past that first run is optional, and each step builds on the one before.

1. 1. Run it and read what it says

   No rule defaults to error and the default threshold is error, so on a manifest that compiles the first run reports findings without failing. Convention rules stay quiet: unreachable-target and rule-without-description are off until a selector enables them, because they encode a house style rather than a defect.

2. 2. Ask why

   netsuke check --explain directory-dep-not-order-only prints one rule’s summary, rationale, and remediation; --explain alone lists the catalogue. The explanation ships in the binary, so it matches the rules that binary runs.

3. 3. Make it a gate

   --fail-on warning turns warnings into a failing exit code, which is the point at which the linter starts guarding a CI pipeline. --fail-on never goes the other way and makes findings purely informational.

4. 4. Fix the policy once

   Category and rule selectors narrow in order, and the [cmds.check] table in netsuke.toml records them for the project (see policy and suppression). The table layers through the usual configuration precedence.

5. 5. Suppress with a reason

   Where a finding is deliberate, a # netsuke-lint: allow directive names the rule and says why. The suppression rules keep those directives honest after the code around them changes.

Accessibility and localization

The linter adds no output mode of its own. Human findings go through the existing diagnostics reporter, so they inherit the project’s colour, emoji, and accessible output policies. The design document practises the same habit: its architecture diagram is preceded by a prose description for screen-reader users.

Step 12.2 of the branch’s roadmap plans the migration: Fluent keys of the form lint.rule.<name>.summary, .rationale, and .remediation, with the English text kept as the fallback so a catalogue gap degrades to the source locale rather than to an empty diagnostic. Under --locale, a finding’s rule, category, severity, and code are to stay byte-identical across locales, and --explain --json stays in the source locale so an editor’s rule picker gets stable text. Translation follows the project’s localization glossary and style guide, leaving manifest identifiers such as order_only_deps verbatim.

How it works

The linter binds to four points in the pipeline described in How Netsuke Works. Manifest source flows into a span index and, in parallel, through the existing compiler stages; each lint stage consumes the artefact produced immediately above it, and all four feed one ordered finding sink.

A rule states what it found and where; the engine stamps the severity resolved from policy, so no rule can decide how loudly to speak. Every rule carries a summary, a rationale, and a remediation in its registry entry, and a contract test checks the rule reference against that registry in both directions, so it can neither omit a shipped rule nor document one that does not exist. A future span-preserving YAML rewriter could add autofixes; that is a separate project and not part of this preview.

How the design earns trust