dw-sdlc 0.16.1 → 0.18.0

package/README.md

@@ -35,6 +35,10 @@ lines, exit codes and document.
 }
 ```
 
+A Step is a command string, or `{ "command": "…", "hint": "…" }`; a `gate.checks.run` entry takes a
+`hint` beside `name` and `command`. When the Step or script fails, the Gate prints `hint: <text>` under
+its failure line, and `--json` carries `hint` on every Step and Check, `null` where there is none.
+
 ```json
 { "scripts": { "check": "dw-sdlc gate" } }
 ```
@@ -42,6 +46,23 @@ lines, exit codes and document.
 Under `gate.checks`, a Check the package ships is `true` for its defaults or an object of its options.
 `comment-budget` holds each comment block in the JavaScript, TypeScript and shell (`.sh`) files under
 its `roots` to `maxProseLines` lines of prose, 3 by default.
+`disable-directives` fails every Disable directive in a comment that gives no reason: `oxlint-disable*`,
+`eslint-disable*`, `@ts-expect-error`, `@ts-ignore`, `rubocop:disable` and `noqa`. A reason follows `--`
+on the directive's line, follows an `@ts-` directive, or is a comment on the line above.
+
+`skill-sections` holds each README section a skill copies to its source. A part sits between two
+markers, each on its own line, and `dw-sdlc check skill-sections --write` fills an empty pair:
+
+```md
+<!-- README.md#errors -->
+<!-- /README.md#errors -->
+```
+
+The anchor is GitHub's, and the section runs from its heading to the next heading of its level or
+above, in the `README.md` beside the `skills` directory that holds the file, or beside the file
+outside one. The Check fails a part that differs from its section, a part whose anchor names no
+heading of the README, a part from a section no Primitive in `.ai/primitives.json` names among its
+docs, a marker without its pair, and a code fence that never closes above a marker, which hides it.
 
 ## The Ship script
 
@@ -87,7 +108,7 @@ buys one more Review past it.
 | ------------------ | ------------------------------------------------------------------------------------------ |
 | `gate`             | the Steps of `gate.steps` in order, then every Check under `gate.checks`                   |
 | `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks                  |
-| `primitives`       | the Primitives that own each path, with their summaries and documents                      |
+| `primitives`       | the Primitives that own each path, or that a change removes, adds or extends               |
 | `setup`            | this machine's local config layer, the git excludes and the permission rules               |
 | `doctor`           | one PASS / WARN / FAIL line per machine check the guardrails rely on                       |
 | `config`           | the resolved agentic config, or one file validated against the schema                      |

package/config/agentic.config.schema.json

@@ -42,6 +42,11 @@
           "description": "`deny` refuses a `git commit`, `merge`, `cherry-pick` or `revert` on a branch listed in `protectedBranches`, so every change starts on a branch of its own. `allow` lets it through, for a repository that commits small fixes on its protected branch and pushes them from a person's terminal. Default `allow`. Strictest first: deny, allow.",
           "enum": ["deny", "allow"]
         },
+        "filteredOutput": {
+          "description": "`deny` refuses a check command whose output a pipe feeds to `head`, `tail`, `grep`, `egrep`, `fgrep`, `rg`, `sed`, `awk`, `less` or `more`: the pipe hides the failure and, with `pipefail` off, the exit code. A check command is the `gate.command`, a Step, a `gate.checks.run` command, `dw-sdlc gate`, `dw-sdlc check`, or a common runner such as `vitest`, `tsc` or `rspec`. `tee` and a redirect pass. `allow` turns the guard off, for a repository whose workflow pipes check output. Default `deny`.",
+          "enum": ["deny", "allow"],
+          "default": "deny"
+        },
         "envFiles": {
           "description": "Which env files (`.env`, `.env.*`, `.envrc`) an agent may read, edit or write. A candidate is judged in this order: listed in `deny` → refused; listed in `allow` → readable; `policy` `deny` → refused; `policy` `git` → readable when git tracks it, refused when git ignores it or does not know it. Entries are globs against the path relative to the repository root: `*` and `?` as in a shell pattern (`*` crosses `/`), a leading `**/` means at any depth, so `.env` is the one in the root and `**/.env.example` every file of that name. No brace groups. A path outside the repository root, or outside any repository, is judged by its basename against the `**/` entries alone. Defaults: policy `git`, allow the `.env.example`, `.env.sample` and `.env.template` names anywhere, deny nothing. The local override may drop `allow` entries and add `deny` entries, never the reverse.",
           "type": "object",
@@ -114,11 +119,25 @@
           "minLength": 1
         },
         "steps": {
-          "description": "The Steps: toolchain commands run in order from the repository root through `sh -c`; the first that does not pass ends the Gate and no Check runs. Each one's output is captured, and its last 50 lines are printed when it does not pass; `--verbose` passes the output through instead. A command the shell cannot find (exit 127) or execute (126) means the Gate cannot run.",
+          "description": "The Steps: toolchain commands run in order from the repository root through `sh -c`; the first that does not pass ends the Gate and no Check runs. A Step is a command string, or an object with its `command` and a `hint`. Each one's output is captured, and its last 50 lines are printed when it does not pass, with the `hint` under them; `--verbose` passes the output through instead. A command the shell cannot find (exit 127) or execute (126) means the Gate cannot run.",
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "type": ["string", "object"],
+            "minLength": 1,
+            "properties": {
+              "command": {
+                "description": "The command the Step runs.",
+                "type": "string",
+                "minLength": 1
+              },
+              "hint": {
+                "description": "What to try when the Step fails: one line the Gate prints as `hint: <text>` under the failure. A passing Step prints nothing.",
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": ["command"],
+            "additionalProperties": false
           }
         },
         "drift": {
@@ -144,6 +163,11 @@
                   "command": {
                     "type": "string",
                     "minLength": 1
+                  },
+                  "hint": {
+                    "description": "What to try when the script fails: one line the Gate prints as `hint: <text>` under the failure. A passing script prints nothing.",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "required": ["name", "command"],
@@ -379,6 +403,47 @@
                 }
               },
               "additionalProperties": false
+            },
+            "disable-directives": {
+              "description": "Every Disable directive in a comment gives a reason: `oxlint-disable*` and `eslint-disable*` in every form, `@ts-expect-error` and `@ts-ignore` in JavaScript and TypeScript, `rubocop:disable` in Ruby and `noqa` in Python. A reason is text after `--` on the directive's line; for `@ts-expect-error` and `@ts-ignore`, text after the directive, with or without `:`; or a comment on the line directly above. A directive inside a string or a template is none, and a rule set to `off` in a lint config is not judged. A hard fail, with no Ratchet; the Gate runs it, never a session hook.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the files to read, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default every JavaScript, TypeScript, Ruby (`.rb`, `.rake`, `.gemspec`, `.ru`, `Rakefile`, `Gemfile`) and Python file.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "exempt": {
+                  "description": "Globs of the files left out. Default `references/**`, `**/vendor/**` and `**/node_modules/**`; a list replaces the default.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "skill-sections": {
+              "description": "Every README section a skill copies matches its source. A part is the section of the README under the heading with GitHub's anchor `<anchor>`, up to the next heading of its level or above, copied whole between `<!-- README.md#<anchor> -->` and `<!-- /README.md#<anchor> -->`, each on its own line, with a blank line inside each. The README is the `README.md` of the directory that holds the `skills` directory the file is in, or of the file's own directory outside one. A part fails when it differs from its section, when the README has no heading with its anchor, and when no Primitive in the catalogue `primitives` reads names `<README>#<anchor>` among its docs; a marker without its pair fails too. A marker inside code is none, and a code fence that never closes above a marker fails, since it hides that marker. `dw-sdlc check skill-sections --write` writes each part from its section. A repository with no part passes without reading the catalogue; one with a part and no valid catalogue cannot run.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the skill files, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default `**/skills/**/*.md`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false

package/dist/agentic-config.d.ts

@@ -54,11 +54,21 @@ export type Guardrails = {
 export type GuardrailsLayer = Partial<Omit<Guardrails, "envFiles">> & {
     envFiles?: Partial<EnvFiles>;
 };
-/** A repository's own script under `gate.checks.run`, reported as a Check under `name`. */
+/** A repository's own script under `gate.checks.run`, reported as a Check under `name`; `hint` is what to try when it fails. */
 export type RunCheck = {
     name: string;
     command: string;
+    hint?: string;
 };
+/** A Step of `gate.steps`: its command, or the command with a `hint` on what to try when it fails. */
+export type Step = string | {
+    command: string;
+    hint?: string;
+};
+/** The command a Step runs. */
+export declare function stepCommand(step: Step): string;
+/** The Hint a Step carries, null where it has none. */
+export declare function stepHint(step: Step): string | null;
 /**
  * `run`, and under each other key a Check the package ships, as the schema takes it: `true`, `false` or
  * its options. `src/checks/` reads the setting of each.
@@ -72,14 +82,14 @@ export type DriftSetting = "fail" | "allow";
 /** The Gate: its command, the steps run in order, whether they may write the tree, the Checks run after them. */
 export type Gate = {
     command?: string;
-    steps: string[];
+    steps: Step[];
     drift: DriftSetting;
     checks: GateChecks;
 };
 /** `gate` as one layer writes it: every key optional, `checks` Check by Check. */
 export type GateLayer = {
     command?: string;
-    steps?: string[];
+    steps?: Step[];
     drift?: DriftSetting;
     checks?: Partial<GateChecks>;
 };

package/dist/agentic-config.js

@@ -15,6 +15,14 @@ export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
 export const REVIEW_DEPTHS = ["full", "light", "off"];
 /** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
 export const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+/** The command a Step runs. */
+export function stepCommand(step) {
+    return typeof step === "string" ? step : step.command;
+}
+/** The Hint a Step carries, null where it has none. */
+export function stepHint(step) {
+    return typeof step === "string" ? null : (step.hint ?? null);
+}
 /** Strictest value first; the local override may only move towards the front. */
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],

package/dist/catalogue.d.ts

@@ -27,6 +27,10 @@ export type CatalogueRead = {
     catalogue: Catalogue;
     text: string;
 };
+/** The catalogue `text` holds, or why it is not one. */
+export declare function parseCatalogue(text: string): Exclude<CatalogueRead, {
+    state: "missing";
+}>;
 /** The catalogue at `file` under `root`, or why there is none to read. */
 export declare function readCatalogue(root: string, file: string): CatalogueRead;
 /**

package/dist/catalogue.js

@@ -34,13 +34,8 @@ const SCHEMA = {
     },
     additionalProperties: false
 };
-/** The catalogue at `file` under `root`, or why there is none to read. */
-export function readCatalogue(root, file) {
-    const path = join(root, file);
-    if (!existsSync(path)) {
-        return { state: "missing" };
-    }
-    const text = readFileSync(path, "utf8");
+/** The catalogue `text` holds, or why it is not one. */
+export function parseCatalogue(text) {
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -55,6 +50,11 @@ export function readCatalogue(root, file) {
     // The schema above is the runtime twin of `Catalogue`: a document it accepts has this shape.
     return { state: "valid", catalogue: parsed, text };
 }
+/** The catalogue at `file` under `root`, or why there is none to read. */
+export function readCatalogue(root, file) {
+    const path = join(root, file);
+    return existsSync(path) ? parseCatalogue(readFileSync(path, "utf8")) : { state: "missing" };
+}
 /**
  * How near the `code` entry `entry`, a file or a directory, names `path`: the length of the entry when
  * it is the path or a directory above it, -1 when it is neither.

package/dist/checks/check.d.ts

@@ -22,6 +22,8 @@ export type Check<Options extends object> = {
     run: (root: string, options: Options) => Finding[];
     /** Present on a Ratchet. */
     baseline?: Baseline<Options>;
+    /** Present on a Check that derives files from their sources: writes them, says what it wrote. */
+    write?: (root: string, options: Options) => string;
 };
 /** The options `setting` turns the Check on with: the defaults under `true`, an object over them, else off. */
 export declare function optionsOf<Options extends object>(check: Check<Options>, setting: unknown): Options | undefined;

package/dist/checks/comment-budget.js

@@ -2,262 +2,11 @@
 // of `//` or shell `#` lines alone on theirs, carries at most `maxProseLines` lines with a letter or a digit.
 import { readFileSync } from "node:fs";
 import { join, matchesGlob } from "node:path";
+import { commentsOf, shellCommentsOf } from "./comments.js";
 import { matching, treeFiles } from "./tree.js";
 const SOURCE = ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"];
 const SHELL = "**/*.sh";
 const REMEDY = "cut it to what the code cannot say, or move the reasoning into a doc and point at it";
-/** The characters after which a `/` opens a regular expression, not a division. */
-const BEFORE_REGEX = new Set("(,=:[!&|?{};+-*%<>~^");
-const KEYWORD_BEFORE_REGEX = /(^|[^\w$])(return|typeof|instanceof|in|of|new|delete|void|throw|case|do|else|yield|await)$/;
-/** Where the regular expression whose `/` is at `start` ends, or undefined when the line ends first. */
-function regexEnd(text, start) {
-    let inClass = false;
-    for (let index = start + 1; index < text.length; index += 1) {
-        const char = text[index];
-        if (char === "\\") {
-            index += 1;
-        }
-        else if (char === "\n") {
-            return undefined;
-        }
-        else if (char === "[" || char === "]") {
-            inClass = char === "[";
-        }
-        else if (char === "/" && !inClass) {
-            return index + 1;
-        }
-    }
-    return undefined;
-}
-/** Whether the `/` at `index` opens a regular expression: the code before it ends where a value starts. */
-function opensRegex(text, index) {
-    const before = text.slice(0, index).trimEnd();
-    const last = before.at(-1);
-    return last === undefined || BEFORE_REGEX.has(last) || KEYWORD_BEFORE_REGEX.test(before);
-}
-/** Every comment in JavaScript or TypeScript `text`, skipping strings, template literals and regular expressions. */
-function commentsOf(text) {
-    const comments = [];
-    // The open quotes, and a `{` for each brace opened inside a template literal's `${…}`.
-    const stack = [];
-    let line = 1;
-    let index = 0;
-    while (index < text.length) {
-        const char = text[index];
-        const next = text[index + 1];
-        const top = stack.at(-1);
-        if (top === "'" || top === '"' || top === "`") {
-            if (char === "\\") {
-                line += next === "\n" ? 1 : 0;
-                index += 2;
-                continue;
-            }
-            if (top === "`" && char === "$" && next === "{") {
-                stack.push("{");
-                index += 2;
-                continue;
-            }
-            if (char === top) {
-                stack.pop();
-            }
-            line += char === "\n" ? 1 : 0;
-            index += 1;
-            continue;
-        }
-        if (char === "'" || char === '"' || char === "`" || (char === "{" && top === "{")) {
-            stack.push(char);
-        }
-        else if (char === "}" && top === "{") {
-            stack.pop();
-        }
-        else if (char === "/" && next === "/") {
-            const stop = text.indexOf("\n", index) === -1 ? text.length : text.indexOf("\n", index);
-            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
-            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, stop) });
-            index = stop;
-            continue;
-        }
-        else if (char === "/" && next === "*") {
-            const close = text.indexOf("*/", index + 2);
-            const body = text.slice(index, close === -1 ? text.length : close + 2);
-            const start = line;
-            line += body.split("\n").length - 1;
-            comments.push({ kind: "block", start, end: line, text: body });
-            index += body.length;
-            continue;
-        }
-        else if (char === "/" && opensRegex(text, index)) {
-            index = regexEnd(text, index) ?? index + 1;
-            continue;
-        }
-        line += char === "\n" ? 1 : 0;
-        index += 1;
-    }
-    return comments;
-}
-/** The characters that end a shell word, so a `#` after one opens a comment. */
-const WORD_BREAK = new Set(" \t\n;&|()<>");
-/** Where the line that holds `index` ends: at its newline, or at the end of `text`. */
-function lineEnd(text, index) {
-    const newline = text.indexOf("\n", index);
-    return newline === -1 ? text.length : newline;
-}
-/** Where a span that `closer` ends, read from `start`, stops, past the closer; `\` escapes a character when `escapes`. */
-function spanEnd(text, start, closer, escapes) {
-    for (let index = start; index < text.length; index += 1) {
-        if (escapes && text.charAt(index) === "\\") {
-            index += 1;
-        }
-        else if (text.charAt(index) === closer) {
-            return index + 1;
-        }
-    }
-    return text.length;
-}
-/** The heredoc whose `<<` is at `start`, its delimiter's quotes off, and where the delimiter's word ends. */
-function heredocAt(text, start) {
-    const strip = text.charAt(start + 2) === "-";
-    let index = start + (strip ? 3 : 2);
-    while (text.charAt(index) === " " || text.charAt(index) === "\t") {
-        index += 1;
-    }
-    let end = index;
-    while (end < text.length && !WORD_BREAK.has(text.charAt(end))) {
-        const char = text.charAt(end);
-        end = char === "'" || char === '"' ? spanEnd(text, end + 1, char, false) : end + (char === "\\" ? 2 : 1);
-    }
-    return { delimiter: text.slice(index, end).replace(/["'\\]/g, ""), strip, end };
-}
-/** Where the heredoc body that starts at `start` ends: past the line that is its delimiter. */
-function heredocEnd(text, start, { delimiter, strip }) {
-    for (let index = start; index < text.length;) {
-        const end = lineEnd(text, index);
-        const line = text.slice(index, end);
-        index = end + 1;
-        if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) {
-            return index;
-        }
-    }
-    return text.length;
-}
-/** The character that opens a nesting inside each frame and the one that closes it; a double quote has none. */
-const NESTING = {
-    code: ["(", ")"],
-    arithmetic: ["(", ")"],
-    expansion: ["{", "}"],
-    double: []
-};
-/**
- * Every `#` comment in shell `text`: a `#` that starts a word of code, never one in a quote, an
- * expansion, an arithmetic `((…))` or a heredoc body, nor the shebang on line 1.
- */
-function shellCommentsOf(text) {
-    const comments = [];
-    const newlines = [...text.matchAll(/\n/g)].map((match) => match.index);
-    const outer = [];
-    let frame = { kind: "code", depth: 0 };
-    const heredocs = [];
-    let wordStart = true;
-    let index = text.startsWith("#!") ? lineEnd(text, 0) : 0;
-    const open = (kind, length) => {
-        outer.push(frame);
-        frame = { kind, depth: 0 };
-        index += length;
-        wordStart = true;
-    };
-    const close = (length) => {
-        frame = outer.pop() ?? frame;
-        index += length;
-        wordStart = false;
-    };
-    const skipTo = (end) => {
-        index = end;
-        wordStart = false;
-    };
-    while (index < text.length) {
-        const char = text.charAt(index);
-        const next = text.charAt(index + 1);
-        const { kind } = frame;
-        const [opener, closer] = NESTING[kind];
-        if (char === "\\" && next === "\n") {
-            index += 2;
-        }
-        else if (char === "\\") {
-            skipTo(index + 2);
-        }
-        else if (kind === "double" && char === '"') {
-            close(1);
-        }
-        else if (char === "$" && text.startsWith("((", index + 1)) {
-            open("arithmetic", 3);
-        }
-        else if (char === "$" && next === "(") {
-            open("code", 2);
-        }
-        else if (char === "$" && next === "{") {
-            open("expansion", 2);
-        }
-        else if (char === "`") {
-            skipTo(spanEnd(text, index + 1, "`", true));
-        }
-        else if (kind === "double") {
-            index += 1;
-        }
-        else if (char === "$" && next === "'") {
-            skipTo(spanEnd(text, index + 2, "'", true));
-        }
-        else if (char === "'") {
-            skipTo(spanEnd(text, index + 1, "'", false));
-        }
-        else if (char === '"') {
-            open("double", 1);
-        }
-        else if (kind === "code" && char === "#" && wordStart) {
-            const end = lineEnd(text, index);
-            const line = newlines.filter((newline) => newline < index).length + 1;
-            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
-            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, end) });
-            index = end;
-        }
-        else if (kind === "code" && char === "\n") {
-            index += 1;
-            for (const heredoc of heredocs.splice(0)) {
-                index = heredocEnd(text, index, heredoc);
-            }
-            wordStart = true;
-        }
-        else if (kind === "code" && text.startsWith("<<<", index)) {
-            index += 3;
-            wordStart = true;
-        }
-        else if (kind === "code" && text.startsWith("<<", index)) {
-            const { end, ...heredoc } = heredocAt(text, index);
-            heredocs.push(heredoc);
-            skipTo(end);
-        }
-        else if (kind === "code" && text.startsWith("((", index)) {
-            open("arithmetic", 2);
-        }
-        else if (char === opener) {
-            frame.depth += 1;
-            index += 1;
-            wordStart = true;
-        }
-        else if (char === closer && frame.depth > 0) {
-            frame.depth -= 1;
-            index += 1;
-            wordStart = true;
-        }
-        else if (char === closer && outer.length > 0) {
-            close(kind === "arithmetic" && next === ")" ? 2 : 1);
-        }
-        else {
-            wordStart = WORD_BREAK.has(char);
-            index += 1;
-        }
-    }
-    return comments;
-}
 /** The comments as blocks: a run of `//` or `#` lines alone on consecutive lines is one; a comment after code is none. */
 function blocksOf(comments) {
     const blocks = [];

package/dist/checks/comments.d.ts

@@ -0,0 +1,29 @@
+/** A `//` or `#` comment alone on its line, one after code, or a block comment, by its lines and text. */
+export type Comment = {
+    kind: "line" | "trailing" | "block";
+    start: number;
+    end: number;
+    text: string;
+};
+/** Every comment in JavaScript or TypeScript `text`, skipping strings, template literals and regular expressions. */
+export declare function commentsOf(text: string): Comment[];
+/** Where the line that holds `index` ends: at its newline, or at the end of `text`. */
+export declare function lineEnd(text: string, index: number): number;
+/** Where a span that `closer` ends, read from `start`, stops, past the closer; `\` escapes a character when `escapes`. */
+export declare function spanEnd(text: string, start: number, closer: string, escapes: boolean): number;
+/** A heredoc whose body starts on the next line: its delimiter, and whether `<<-` strips the body's leading tabs. */
+export type Heredoc = {
+    delimiter: string;
+    strip: boolean;
+};
+/** The heredoc whose `<<` is at `start`, its delimiter's quotes off, and where the delimiter's word ends. */
+export declare function heredocAt(text: string, start: number): Heredoc & {
+    end: number;
+};
+/** Where the heredoc body that starts at `start` ends: past the line that is its delimiter. */
+export declare function heredocEnd(text: string, start: number, { delimiter, strip }: Heredoc): number;
+/**
+ * Every `#` comment in shell `text`: a `#` that starts a word of code, never one in a quote, an
+ * expansion, an arithmetic `((…))` or a heredoc body, nor the shebang on line 1.
+ */
+export declare function shellCommentsOf(text: string): Comment[];