dw-sdlc 0.1.0 → 0.2.0

package/config/agentic.config.schema.json

@@ -187,6 +187,169 @@
                 }
               },
               "additionalProperties": false
+            },
+            "markdown-budget": {
+              "description": "Each file a glob of `budgets` matches within that glob's `maxLines` and `maxBytes`, and every glob matching a file. A glob matches the files git tracks or would track, a symbolic link left out when the file it points at is matched too; `*` and `**` skip a name that starts with a dot.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "budgets": {
+                  "description": "Default `docs/agents/*.md` within 100 lines and 6144 bytes; a list replaces the default.",
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "glob": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "maxLines": {
+                        "type": "integer",
+                        "minimum": 1
+                      },
+                      "maxBytes": {
+                        "type": "integer",
+                        "minimum": 1
+                      }
+                    },
+                    "required": ["glob", "maxLines", "maxBytes"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "markdown-refs": {
+              "description": "Every relative link and image in the markdown files resolves: its path to a file or directory git tracks or would track, its heading anchor to a heading of the markdown file it names, and `#anchor` alone to a heading of its own file. A link with a scheme, such as `https:`, and a link inside code are not judged.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the markdown files whose links are judged, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default `**/*.md`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "exempt": {
+                  "description": "Globs of the files left out. Default none.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "temporal-language": {
+              "description": "No changelog phrase in a durable document, matched across a line break and never inside code: `now we`,`we now`, `we no longer`, `previously we`, `as before`, `were removed`, `was` or `were retired`, `no longer` before `support`, `accept`, `require`, `use`, `fan`, `carry`, `replay`, `incur`, `authoritative`, `insert` or `needed`,`is now a` or `the`, `are now`, `previously a` or `the`, `recently` before `changed`, `added`, `updated`, `removed` or `introduced`, and `used to support` or `require`.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the durable documents, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default `**/*.md`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "exempt": {
+                  "description": "Globs of the files that record a point in time. Default `docs/adr/**`, `docs/decisions/**`, `docs/research/**` and `**/CHANGELOG.md`; a list replaces the default.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "decision-records": {
+              "description": "The records of each directory of `dirs` that exists, the files in it git tracks or would track named `<number>-<slug>.md`: numbered from 1 with no gap and no number taken twice, each with a level-1 heading for its title and a frontmatter `status` whose first word is one of `statuses`, so `superseded by ADR 0008` reads as `superseded`. The Gate cannot run when none of `dirs` exists.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "dirs": {
+                  "description": "The directories of the records, relative to the repository root; one that does not exist holds none. Default `docs/adr` and `docs/decisions`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "statuses": {
+                  "description": "Default `proposed`, `accepted`, `active`, `deprecated` and `superseded`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
+            },
+            "file-size-ratchet": {
+              "description": "The file-size Ratchet: each file git tracks or would track within the line limit of its group, or, where `.ai/file-size-ratchet.baseline.json` lists it, within the count recorded there. A file belongs to the first group with a glob that matches it; a file no group matches has no limit, and a symbolic link is left out when the file it points at is matched too. The baseline is committed and lists the files over their limit; one that lists a file twice, at a count within its group's limit or in no group fails the Check. `dw-sdlc gate --update-baseline` records it where there is none and otherwise only tightens it, and only when every Step and every other Check passes: a file within its limit leaves it, a count that shrank is lowered, and no file joins.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "groups": {
+                  "description": "Default, in this order: `tests`, 2000 lines, a file under a `test`, `tests` or `__tests__` directory or named `*.test.*` or `*.spec.*`; `agent-docs`, 120 lines, `AGENTS.md`, `CLAUDE.md` and `GLOSSARY.md` anywhere and the markdown under `docs/agents`; `source`, 500 lines, JavaScript, TypeScript and shell.",
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "name": {
+                        "description": "The group's name, which its failure lines carry: lowercase words joined by hyphens.",
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+                      },
+                      "maxLines": {
+                        "type": "integer",
+                        "minimum": 1
+                      },
+                      "files": {
+                        "description": "Globs against the path from the repository root, as Node's `path.matchesGlob` reads them: `**` crosses directories, but no `*` matches a name that starts with a dot.",
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "minItems": 1,
+                        "uniqueItems": true
+                      }
+                    },
+                    "required": ["name", "maxLines", "files"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "comment-budget": {
+              "description": "The comment budget: each comment block in the JavaScript and TypeScript files under `roots` carries at most `maxProseLines` lines of prose, a line with a letter or a digit once the comment markers are off. A block is one `/* … */` comment or a run of `//` comments each alone on consecutive lines; a comment after code on its line is none.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "maxProseLines": {
+                  "description": "Default 3.",
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "roots": {
+                  "description": "The directories whose files it reads, relative to the repository root; one that does not exist holds no file. Default `packages`, `plugins`, `scripts` and `src`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false

package/dist/agentic-config.js

@@ -1,8 +1,6 @@
-// Reads what a repository declares for an agent: `.ai/agentic.config.json` (committed), then
-// `.ai/agentic.config.local.json` (one machine) over it, then what the repository itself implies. The
-// local file may tighten `guardrails` and never loosen it; any invalid layer is dropped whole and the
-// guards fall back to the strictest defaults until it is fixed. The guardrails plugin's `hooks/config.jq`
-// is the same merge for the guards; this file is the reference, and the plugin's tests run both.
+// Reads what a repository declares for an agent: the committed config, the machine's local layer over it,
+// and what the repository implies; an invalid layer is dropped whole. The guardrails plugin's
+// `hooks/config.jq` is the same merge for the guards; this file is the reference, and the tests run both.
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";

package/dist/checks/agents-map.js

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { resolveConfig } from "../agentic-config.js";
 import { codeSpans, tableRows } from "../markdown.js";
 import { CannotRun } from "./check.js";
+import { overBudget } from "./markdown-budget.js";
 import { catalogueFile } from "./primitives.js";
 const ROUTER = "Task Router";
 const AGENTS_SKILLS = ".agents/skills";
@@ -34,16 +35,8 @@ function escape(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /** The budget, the Gate command, the row to the catalogue and every path the Task Router points at. */
-function judgeMap(root, { file, maxLines, maxBytes }, text) {
-    const findings = [];
-    const lines = text.endsWith("\n") ? text.split("\n").length - 1 : text.split("\n").length;
-    if (lines > maxLines) {
-        findings.push({ file, message: `${lines} lines, over the ${maxLines}-line budget`, remedy: REMEDIES.budget });
-    }
-    const bytes = Buffer.byteLength(text);
-    if (bytes > maxBytes) {
-        findings.push({ file, message: `${bytes} bytes, over the ${maxBytes}-byte budget`, remedy: REMEDIES.budget });
-    }
+function judgeMap(root, { file, ...budget }, text) {
+    const findings = overBudget(text, budget).map((message) => ({ file, message, remedy: REMEDIES.budget }));
     const { gate } = resolveConfig(root).config;
     if (gate.command === undefined) {
         findings.push({ message: "the Gate has no command for the map to name", remedy: REMEDIES.noCommand });

package/dist/checks/check.d.ts

@@ -6,12 +6,22 @@ export declare class CannotRun extends Error {
     finding: Finding;
     constructor(finding: Finding);
 }
+/**
+ * A Ratchet's committed baseline: its file, and its refresh from the tree, which writes it tighter or
+ * records it where there is none, says what it did, and throws `CannotRun` when it cannot.
+ */
+export type Baseline<Options extends object> = {
+    file: string;
+    refresh: (root: string, options: Options) => string;
+};
 export type Check<Options extends object> = {
     /** The Check's key under `gate.checks`. */
     name: string;
     defaults: Options;
     /** Every failure of the tree at `root`, none when it passes; throws `CannotRun` when it cannot judge. */
     run: (root: string, options: Options) => Finding[];
+    /** Present on a Ratchet. */
+    baseline?: Baseline<Options>;
 };
 /** 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.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "./check.ts";
+export type CommentBudgetOptions = {
+    maxProseLines: number;
+    roots: string[];
+};
+export declare const commentBudget: Check<CommentBudgetOptions>;

package/dist/checks/comment-budget.js

@@ -0,0 +1,141 @@
+// `comment-budget`: a comment says what the code cannot, in a few lines. A block, one `/* … */` or a run
+// of `//` lines alone on theirs, carries at most `maxProseLines` lines with a letter or a digit.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { matching, treeFiles } from "./tree.js";
+const SOURCE = ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"];
+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 comments as blocks: a run of `//` lines alone on consecutive lines is one; a comment after code is none. */
+function blocksOf(comments) {
+    const blocks = [];
+    for (const comment of comments) {
+        const previous = blocks.at(-1);
+        if (comment.kind === "line" && previous?.kind === "line" && previous.end === comment.start - 1) {
+            previous.end = comment.end;
+            previous.text += `\n${comment.text}`;
+        }
+        else if (comment.kind !== "trailing") {
+            blocks.push({ ...comment });
+        }
+    }
+    return blocks;
+}
+/** The lines of a block that hold a letter or a digit once the comment markers around them are off. */
+function proseLines(block) {
+    return block
+        .replace(/^\/\*\*?/, "")
+        .replace(/\*\/$/, "")
+        .split("\n")
+        .map((line) => line
+        .trim()
+        .replace(/^\*\s?/, "")
+        .replace(/^\/\/\s?/, ""))
+        .filter((line) => /[\p{L}\p{N}]/u.test(line)).length;
+}
+function run(root, { maxProseLines, roots }) {
+    const findings = [];
+    for (const file of matching(root, treeFiles(root, roots), SOURCE)) {
+        for (const block of blocksOf(commentsOf(readFileSync(join(root, file), "utf8")))) {
+            const prose = proseLines(block.text);
+            if (prose > maxProseLines) {
+                const message = `a comment block of ${prose} prose lines, over the ${maxProseLines}-line budget`;
+                findings.push({ file, line: block.start, message, remedy: REMEDY });
+            }
+        }
+    }
+    return findings;
+}
+export const commentBudget = {
+    name: "comment-budget",
+    defaults: { maxProseLines: 3, roots: ["packages", "plugins", "scripts", "src"] },
+    run
+};

package/dist/checks/decision-records.d.ts

@@ -0,0 +1,6 @@
+import { type Check } from "./check.ts";
+export type DecisionRecordsOptions = {
+    dirs: string[];
+    statuses: string[];
+};
+export declare const decisionRecords: Check<DecisionRecordsOptions>;

package/dist/checks/decision-records.js

@@ -0,0 +1,105 @@
+// `decision-records`: the decisions directory stays a reliable index. Its records, the files named
+// `<number>-<slug>.md`, are numbered from 1 with no gap and no number taken twice, and each has a title
+// and a frontmatter status from the allowed set.
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { headings } from "../markdown.js";
+import { CannotRun } from "./check.js";
+import { treeFiles } from "./tree.js";
+/** A record's name in its directory: its number, a slug, `.md`, and no directory between. */
+const RECORD = /^(\d+)-[^/]+\.md$/;
+const REMEDIES = {
+    missing: "create the records directory, or point gate.checks.decision-records.dirs at it",
+    gap: "restore the missing records, or renumber the ones after the gap",
+    taken: "give each record a number of its own",
+    title: "start it with a level-1 heading that names the decision"
+};
+function isDirectory(path) {
+    return statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;
+}
+/** The `status` of the frontmatter `text` opens with, its quotes dropped, and its 1-based line. */
+function statusOf(text) {
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---") {
+        return undefined;
+    }
+    for (let index = 1; index < lines.length && lines[index]?.trim() !== "---"; index++) {
+        const value = /^status:\s*(.*?)\s*$/.exec(lines[index] ?? "")?.[1]?.replace(/^(["'])(.*)\1$/, "$2");
+        if (value !== undefined && value !== "") {
+            return { value, line: index + 1 };
+        }
+    }
+    return undefined;
+}
+/** Each run of numbers from 1 to the highest that no record takes, as `0004` or `0004 to 0006`. */
+function gaps(taken, pad) {
+    const runs = [];
+    const highest = Math.max(0, ...taken);
+    let start;
+    for (let number = 1; number <= highest; number++) {
+        if (!taken.has(number)) {
+            start ??= number;
+        }
+        else if (start !== undefined) {
+            runs.push(start === number - 1 ? pad(start) : `${pad(start)} to ${pad(number - 1)}`);
+            start = undefined;
+        }
+    }
+    return runs;
+}
+/** What is wrong with the records of `dir`: the numbers they skip, then each record's number, title and status. */
+function judge(root, dir, statuses) {
+    const prefix = `${dir.replace(/\/+$/, "")}/`;
+    const records = treeFiles(root, [dir])
+        .map((file) => ({ file, name: file.slice(prefix.length) }))
+        .filter(({ name }) => RECORD.test(name))
+        .map(({ file, name }) => ({ file, digits: RECORD.exec(name)?.[1] ?? "" }));
+    const width = records[0]?.digits.length ?? 4;
+    const pad = (number) => String(number).padStart(width, "0");
+    const owners = new Map();
+    for (const { file, digits } of records) {
+        if (!owners.has(Number(digits))) {
+            owners.set(Number(digits), file);
+        }
+    }
+    const findings = gaps(new Set(owners.keys()), pad).map((gap) => ({
+        file: dir,
+        message: `no record is numbered ${gap}`,
+        remedy: REMEDIES.gap
+    }));
+    const allowed = `one of ${statuses.join(", ")}`;
+    for (const { file, digits } of records) {
+        const owner = owners.get(Number(digits));
+        if (owner !== file) {
+            findings.push({ file, message: `${digits} is taken by ${owner}`, remedy: REMEDIES.taken });
+        }
+        const text = readFileSync(join(root, file), "utf8");
+        if (!headings(text).some(({ level, text: title }) => level === 1 && title.trim() !== "")) {
+            findings.push({ file, message: "has no title", remedy: REMEDIES.title });
+        }
+        const status = statusOf(text);
+        if (status === undefined) {
+            findings.push({ file, message: "has no status", remedy: `give its frontmatter a status, ${allowed}` });
+        }
+        else if (!statuses.includes(status.value.split(/\s+/)[0] ?? "")) {
+            const message = `the status ${JSON.stringify(status.value)} is not allowed`;
+            findings.push({ file, line: status.line, message, remedy: `set it to ${allowed}` });
+        }
+    }
+    return findings;
+}
+function run(root, { dirs, statuses }) {
+    const present = dirs.filter((dir) => isDirectory(join(root, dir)));
+    if (present.length === 0) {
+        throw new CannotRun({ message: `none of ${dirs.join(", ")} exists`, remedy: REMEDIES.missing });
+    }
+    return present.flatMap((dir) => judge(root, dir, statuses));
+}
+export const decisionRecords = {
+    name: "decision-records",
+    defaults: {
+        dirs: ["docs/adr", "docs/decisions"],
+        statuses: ["proposed", "accepted", "active", "deprecated", "superseded"]
+    },
+    run
+};

package/dist/checks/file-size-ratchet.d.ts

@@ -0,0 +1,10 @@
+import { type Check } from "./check.ts";
+export type Group = {
+    name: string;
+    maxLines: number;
+    files: string[];
+};
+export type FileSizeRatchetOptions = {
+    groups: Group[];
+};
+export declare const fileSizeRatchet: Check<FileSizeRatchetOptions>;