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 rule field of JSON output, 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 exist because v0.1.0-beta3 made $$ escaping and the $in/$out placeholders obsolete; see markers and shell dollars.

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.2.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/issue-592-v0-4-0-design-and-implement-a-netsukefile-linter-inspired-by-mbake/docs/netsuke-linter-rules.md#directory-dep-not-order-only",
        "primary_span": { "line": 24, "column": 7, "snippet": "      - \"{{ build_dir }}\"" }
      }
    ]
  }
}

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 the documentation is provably complete rather than aspirationally so. A future span-preserving YAML rewriter could add autofixes; that is a separate project and not part of this preview.