dw-sdlc 0.1.0 → 0.2.0

package/dist/checks/file-size-ratchet.js

@@ -0,0 +1,194 @@
+// `file-size-ratchet`: each file within the line limit of its group or, listed in the baseline, within
+// the count recorded there. A refresh only tightens the baseline: it lowers and drops, and adds no file.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, matchesGlob } from "node:path";
+import { CannotRun } from "./check.js";
+import { lineCount } from "./markdown-budget.js";
+import { matching, treeFiles } from "./tree.js";
+const BASELINE = ".ai/file-size-ratchet.baseline.json";
+const REFRESH = "dw-sdlc gate --update-baseline";
+const REMEDIES = {
+    record: `record it with ${REFRESH}`,
+    shape: `make it an object of file paths and line counts, as ${REFRESH} writes it`,
+    twice: "keep one entry for it, the lower count",
+    stale: `run ${REFRESH}, which drops it`,
+    unreadable: "fix the failures it names"
+};
+/** A committed baseline gone from the tree: recording a new one would let every grown file back in. */
+const DELETED = {
+    file: BASELINE,
+    message: "the baseline is committed but gone from the tree",
+    remedy: `restore it with git restore ${BASELINE}`
+};
+function show(value) {
+    return JSON.stringify(value);
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function inBaseline(line) {
+    return line === undefined ? { file: BASELINE } : { file: BASELINE, line };
+}
+/** The first group with a glob that matches `path`. */
+function groupOf(path, groups) {
+    return groups.find(({ files }) => files.some((glob) => matchesGlob(path, glob)));
+}
+function measure(root, groups) {
+    const measured = new Map();
+    for (const path of matching(root, treeFiles(root), groups.flatMap(({ files }) => files))) {
+        const group = groupOf(path, groups);
+        if (group !== undefined && statSync(join(root, path)).isFile()) {
+            measured.set(path, { group, lines: lineCount(readFileSync(join(root, path), "utf8")) });
+        }
+    }
+    return measured;
+}
+/** The line of each `"<path>":` key in `text`; JSON keeps only the last of a key it reads twice. */
+function keyLines(text, path) {
+    const key = show(path).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return Array.from(text.matchAll(new RegExp(`(?<!\\\\)${key}\\s*:`, "g")), ({ index }) => {
+        return text.slice(0, index).split("\n").length;
+    });
+}
+function readBaseline(root) {
+    const path = join(root, BASELINE);
+    if (!existsSync(path)) {
+        const committed = spawnSync("git", ["-C", root, "cat-file", "-e", `HEAD:${BASELINE}`]).status === 0;
+        return { state: "missing", committed };
+    }
+    const text = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        const message = `not JSON: ${error instanceof Error ? error.message : String(error)}`;
+        return { state: "invalid", findings: [{ file: BASELINE, message, remedy: REMEDIES.shape }] };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { state: "invalid", findings: [{ file: BASELINE, message: "not an object", remedy: REMEDIES.shape }] };
+    }
+    const findings = [];
+    const entries = new Map();
+    for (const [file, count] of Object.entries(parsed)) {
+        const lines = keyLines(text, file);
+        if (lines.length > 1) {
+            const times = lines.length === 2 ? "twice" : `${lines.length} times`;
+            findings.push({ ...inBaseline(lines[1]), message: `lists ${show(file)} ${times}`, remedy: REMEDIES.twice });
+        }
+        if (typeof count === "number" && Number.isInteger(count) && count >= 1) {
+            entries.set(file, { count, line: lines[0] });
+        }
+        else {
+            const message = `${show(file)} is at ${show(count)}, not a line count`;
+            findings.push({ ...inBaseline(lines.at(-1)), message, remedy: REMEDIES.shape });
+        }
+    }
+    return findings.length > 0 ? { state: "invalid", findings } : { state: "valid", entries };
+}
+/** The entries that excuse nothing: a file no group holds, or a count within its group's limit. */
+function contradictions(entries, groups) {
+    const findings = [];
+    for (const [file, { count, line }] of entries) {
+        const group = groupOf(file, groups);
+        if (group === undefined) {
+            const message = `lists ${show(file)}, which no group holds`;
+            findings.push({ ...inBaseline(line), message, remedy: REMEDIES.stale });
+        }
+        else if (count <= group.maxLines) {
+            const message = `lists ${show(file)} at ${count} lines, within the ${group.maxLines}-line limit of the ${group.name} group`;
+            findings.push({ ...inBaseline(line), message, remedy: REMEDIES.stale });
+        }
+    }
+    return findings;
+}
+function run(root, { groups }) {
+    const read = readBaseline(root);
+    if (read.state === "missing") {
+        const missing = { file: BASELINE, message: "the baseline does not exist", remedy: REMEDIES.record };
+        throw new CannotRun(read.committed ? DELETED : missing);
+    }
+    if (read.state === "invalid") {
+        return read.findings;
+    }
+    const findings = contradictions(read.entries, groups);
+    for (const [file, { group, lines }] of measure(root, groups)) {
+        const recorded = read.entries.get(file)?.count;
+        if (recorded !== undefined && lines > recorded) {
+            const message = `${lines} lines, over the ${recorded} the baseline holds it to`;
+            findings.push({ file, message, remedy: `cut it back to ${recorded} lines or fewer` });
+        }
+        else if (recorded === undefined && lines > group.maxLines) {
+            const message = `${lines} lines, over the ${group.maxLines}-line limit of the ${group.name} group`;
+            findings.push({ file, message, remedy: `split it, or cut it to ${group.maxLines} lines` });
+        }
+    }
+    return findings;
+}
+function write(root, entries) {
+    const sorted = entries.toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    mkdirSync(dirname(join(root, BASELINE)), { recursive: true });
+    writeFileSync(join(root, BASELINE), `${JSON.stringify(Object.fromEntries(sorted), null, 2)}\n`);
+}
+/**
+ * Records every file over its limit where there is no baseline; else lowers each count that shrank
+ * and drops each entry that excuses nothing, adding none.
+ */
+function refresh(root, { groups }) {
+    const read = readBaseline(root);
+    if (read.state === "invalid") {
+        throw new CannotRun({
+            file: BASELINE,
+            message: "it is not a baseline the Ratchet can read",
+            remedy: REMEDIES.unreadable
+        });
+    }
+    if (read.state === "missing" && read.committed) {
+        throw new CannotRun(DELETED);
+    }
+    const measured = measure(root, groups);
+    if (read.state === "missing") {
+        const over = [...measured].filter(([, { group, lines }]) => lines > group.maxLines);
+        write(root, over.map(([file, { lines }]) => [file, lines]));
+        return `recorded — ${plural(over.length, "file")} over ${over.length === 1 ? "its" : "their"} limit`;
+    }
+    const kept = [];
+    let dropped = 0;
+    let lowered = 0;
+    for (const [file, { count }] of read.entries) {
+        const now = measured.get(file);
+        const tighter = now === undefined ? 0 : Math.min(now.lines, count);
+        if (now === undefined || tighter <= now.group.maxLines) {
+            dropped += 1;
+        }
+        else {
+            lowered += tighter < count ? 1 : 0;
+            kept.push([file, tighter]);
+        }
+    }
+    if (dropped === 0 && lowered === 0) {
+        return "unchanged";
+    }
+    write(root, kept);
+    const parts = [
+        ...(dropped > 0 ? [`${plural(dropped, "file")} dropped`] : []),
+        ...(lowered > 0 ? [`${plural(lowered, "count")} lowered`] : [])
+    ];
+    return `tightened — ${parts.join(", ")}`;
+}
+const TESTS = ["**/{test,tests,__tests__}/**", "**/*.{test,spec}.*"];
+const AGENT_DOCS = ["**/{AGENTS,CLAUDE,GLOSSARY}.md", "docs/agents/**/*.md"];
+const SOURCE = ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,sh}"];
+export const fileSizeRatchet = {
+    name: "file-size-ratchet",
+    defaults: {
+        groups: [
+            { name: "tests", maxLines: 2000, files: TESTS },
+            { name: "agent-docs", maxLines: 120, files: AGENT_DOCS },
+            { name: "source", maxLines: 500, files: SOURCE }
+        ]
+    },
+    run,
+    baseline: { file: BASELINE, refresh }
+};

package/dist/checks/index.d.ts

@@ -1,8 +1,12 @@
 import { type Finding } from "./check.ts";
-/** A Check turned on by its setting, ready to judge a tree. */
+/** A Check turned on by its setting, ready to judge a tree, and to refresh its baseline if it is a Ratchet. */
 export type EnabledCheck = {
     name: string;
     run: (root: string) => Finding[];
+    baseline?: {
+        file: string;
+        refresh: (root: string) => string;
+    };
 };
 /** Every shipped Check a resolved `gate.checks` turns on with `true` or its options. */
 export declare function enabledChecks(checks: Record<string, unknown>): EnabledCheck[];

package/dist/checks/index.js

@@ -2,17 +2,40 @@
 // file, one row below and one key under `gate.checks` in the schema, listed in the same order.
 import { agentsMap } from "./agents-map.js";
 import { optionsOf } from "./check.js";
+import { commentBudget } from "./comment-budget.js";
+import { decisionRecords } from "./decision-records.js";
+import { fileSizeRatchet } from "./file-size-ratchet.js";
+import { markdownBudget } from "./markdown-budget.js";
+import { markdownRefs } from "./markdown-refs.js";
 import { primitives } from "./primitives.js";
+import { temporalLanguage } from "./temporal-language.js";
 function ship(check) {
     return {
         name: check.name,
         enable: (setting) => {
             const options = optionsOf(check, setting);
-            return options === undefined ? undefined : { name: check.name, run: (root) => check.run(root, options) };
+            if (options === undefined) {
+                return undefined;
+            }
+            const enabled = { name: check.name, run: (root) => check.run(root, options) };
+            const { baseline } = check;
+            if (baseline !== undefined) {
+                enabled.baseline = { file: baseline.file, refresh: (root) => baseline.refresh(root, options) };
+            }
+            return enabled;
         }
     };
 }
-const SHIPPED = [ship(primitives), ship(agentsMap)];
+const SHIPPED = [
+    ship(primitives),
+    ship(agentsMap),
+    ship(markdownBudget),
+    ship(markdownRefs),
+    ship(temporalLanguage),
+    ship(decisionRecords),
+    ship(fileSizeRatchet),
+    ship(commentBudget)
+];
 /** Every shipped Check a resolved `gate.checks` turns on with `true` or its options. */
 export function enabledChecks(checks) {
     return SHIPPED.flatMap(({ name, enable }) => enable(checks[name]) ?? []);

package/dist/checks/markdown-budget.d.ts

@@ -0,0 +1,15 @@
+import type { Check } from "./check.ts";
+export type Budget = {
+    maxLines: number;
+    maxBytes: number;
+};
+export type MarkdownBudgetOptions = {
+    budgets: (Budget & {
+        glob: string;
+    })[];
+};
+/** The lines of `text`, a last line without its newline counted, the empty line after a final newline not. */
+export declare function lineCount(text: string): number;
+/** What `text` spends past its budget: `156 lines, over the 150-line budget`, then the bytes the same way. */
+export declare function overBudget(text: string, { maxLines, maxBytes }: Budget): string[];
+export declare const markdownBudget: Check<MarkdownBudgetOptions>;

package/dist/checks/markdown-budget.js

@@ -0,0 +1,42 @@
+// `markdown-budget`: each file a glob matches stays within that glob's line and byte budget, so the
+// docs an agent reads stay short enough to read whole.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { matching, treeFiles } from "./tree.js";
+const REMEDIES = {
+    budget: "cut it, or split a topic into a file of its own",
+    glob: "fix the glob, or drop its budget"
+};
+/** The lines of `text`, a last line without its newline counted, the empty line after a final newline not. */
+export function lineCount(text) {
+    const lines = text.split("\n").length;
+    return text.endsWith("\n") ? lines - 1 : lines;
+}
+/** What `text` spends past its budget: `156 lines, over the 150-line budget`, then the bytes the same way. */
+export function overBudget(text, { maxLines, maxBytes }) {
+    const lines = lineCount(text);
+    const bytes = Buffer.byteLength(text);
+    return [
+        ...(lines > maxLines ? [`${lines} lines, over the ${maxLines}-line budget`] : []),
+        ...(bytes > maxBytes ? [`${bytes} bytes, over the ${maxBytes}-byte budget`] : [])
+    ];
+}
+function run(root, { budgets }) {
+    const files = treeFiles(root);
+    return budgets.flatMap(({ glob, ...budget }) => {
+        const matched = matching(root, files, [glob]);
+        if (matched.length === 0) {
+            return [{ message: `${JSON.stringify(glob)} matches no file`, remedy: REMEDIES.glob }];
+        }
+        return matched.flatMap((file) => overBudget(readFileSync(join(root, file), "utf8"), budget).map((over) => ({
+            file,
+            message: `${over} of ${glob}`,
+            remedy: REMEDIES.budget
+        })));
+    });
+}
+export const markdownBudget = {
+    name: "markdown-budget",
+    defaults: { budgets: [{ glob: "docs/agents/*.md", maxLines: 100, maxBytes: 6144 }] },
+    run
+};

package/dist/checks/markdown-refs.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "./check.ts";
+export type MarkdownRefsOptions = {
+    files: string[];
+    exempt: string[];
+};
+export declare const markdownRefs: Check<MarkdownRefsOptions>;

package/dist/checks/markdown-refs.js

@@ -0,0 +1,73 @@
+// `markdown-refs`: every relative link and image in the markdown resolves, its path to a file or a
+// directory git tracks or would track and its heading anchor to a heading of the file it names, so a
+// link to an ignored file or to another case of a file's name fails here as it fails in CI.
+import { readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { anchorsOf, links } from "../markdown.js";
+import { matching, treeFiles } from "./tree.js";
+const REMEDIES = {
+    path: "fix the path or drop the link",
+    outside: "point it at a file of the repository",
+    anchor: "point it at a heading the file has"
+};
+/** A target with a scheme, such as `https:` or `mailto:`, or a host: no file of the tree answers it. */
+const EXTERNAL = /^([a-z][a-z\d+.-]*:|\/\/)/i;
+function decode(text) {
+    try {
+        return decodeURIComponent(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** Every directory above a file of `files`. */
+function directoriesOf(files) {
+    const directories = new Set();
+    for (const file of files) {
+        for (let dir = posix.dirname(file); dir !== "." && !directories.has(dir); dir = posix.dirname(dir)) {
+            directories.add(dir);
+        }
+    }
+    return directories;
+}
+/** The repository path `path` names from `file`, the root `.`; a path out of the repository starts with `..`. */
+function resolve(file, path) {
+    if (path === "") {
+        return file;
+    }
+    const joined = path.startsWith("/") ? path.slice(1) : posix.join(posix.dirname(file), path);
+    const normal = posix.normalize(joined === "" ? "." : joined);
+    return normal.length > 1 ? normal.replace(/\/$/, "") : normal;
+}
+/** What is wrong with one link of `file`: a path out of the repository or not in it, or an anchor with no heading. */
+function judge(repository, file, { target, line }) {
+    if (EXTERNAL.test(target)) {
+        return [];
+    }
+    const [beforeAnchor = "", anchor = ""] = target.split("#", 2);
+    const resolved = resolve(file, decode(beforeAnchor.split("?", 1)[0] ?? ""));
+    const quoted = JSON.stringify(target);
+    if (resolved === ".." || resolved.startsWith("../")) {
+        return [{ file, line, message: `links to ${quoted}, which is outside the repository`, remedy: REMEDIES.outside }];
+    }
+    if (resolved !== "." && !repository.files.has(resolved) && !repository.directories.has(resolved)) {
+        return [{ file, line, message: `links to ${quoted}, which does not exist`, remedy: REMEDIES.path }];
+    }
+    const namesHeading = anchor !== "" && repository.files.has(resolved) && /\.md$/i.test(resolved);
+    if (namesHeading && !anchorsOf(repository.root, resolved, repository.anchors).has(decode(anchor))) {
+        const message = `links to ${quoted}, but ${resolved} has no heading with that anchor`;
+        return [{ file, line, message, remedy: REMEDIES.anchor }];
+    }
+    return [];
+}
+function run(root, { files, exempt }) {
+    const tree = treeFiles(root);
+    const known = new Set(tree);
+    const repository = { root, files: known, directories: directoriesOf(known), anchors: new Map() };
+    return matching(root, tree, files, exempt).flatMap((file) => links(readFileSync(join(root, file), "utf8")).flatMap((link) => judge(repository, file, link)));
+}
+export const markdownRefs = {
+    name: "markdown-refs",
+    defaults: { files: ["**/*.md"], exempt: [] },
+    run
+};

package/dist/checks/primitives.js

@@ -1,12 +1,12 @@
 // `primitives`: the catalogue says what is true of the tree. Unique ids, a known group, a one-line
 // summary, every code and docs path on disk with its anchor resolving, and every file under the roots
 // named by a Primitive.
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { CATALOGUE_FILE, primitivesNaming, readCatalogue } from "../catalogue.js";
-import { headings } from "../markdown.js";
+import { anchorsOf } from "../markdown.js";
 import { CannotRun, optionsOf } from "./check.js";
+import { treeFiles } from "./tree.js";
 const MAX_SUMMARY = 120;
 /** A file a test runs, never shipped: under a test directory, or named as a test. */
 const TEST_FILE = /(^|\/)(test|tests|__tests__)\/|\.(test|spec)\.[^/]+$/;
@@ -17,8 +17,7 @@ const REMEDIES = {
     group: "add the group to groups, or move the Primitive into one listed there",
     summary: `keep the summary to one line of ${MAX_SUMMARY} characters or fewer`,
     path: "fix the path or drop it",
-    anchor: "point the entry at a heading the file has",
-    notGit: "run the Gate inside a git repository"
+    anchor: "point the entry at a heading the file has"
 };
 function show(value) {
     return JSON.stringify(value);
@@ -30,16 +29,6 @@ function lineOf(text, id, nth) {
     const match = Array.from(text.slice(start).matchAll(pattern))[nth];
     return match?.index === undefined ? undefined : text.slice(0, start + match.index).split("\n").length;
 }
-/** The anchors of the headings of `path`; none when it is not a file. */
-function anchorsOf(root, path, cache) {
-    let anchors = cache.get(path);
-    if (anchors === undefined) {
-        const full = join(root, path);
-        anchors = new Set(statSync(full).isFile() ? headings(readFileSync(full, "utf8")).map(({ anchor }) => anchor) : []);
-        cache.set(path, anchors);
-    }
-    return anchors;
-}
 /** What is wrong with one Primitive, declared at `at`: its group, its summary, each code and docs entry. */
 function judge(root, catalogue, primitive, at, cache) {
     const { id, group, summary, code, docs } = primitive;
@@ -69,20 +58,6 @@ function judge(root, catalogue, primitive, at, cache) {
     }
     return findings;
 }
-/** Every file under `roots` that git tracks or would track, and that is on disk. */
-function filesUnder(root, roots) {
-    const args = ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...roots];
-    const listed = spawnSync("git", args, { encoding: "utf8" });
-    if (listed.status !== 0) {
-        throw new CannotRun({
-            message: `cannot list the files under ${roots.join(", ")}: not a git repository`,
-            remedy: REMEDIES.notGit
-        });
-    }
-    return [...new Set(listed.stdout.split("\0").filter((path) => path !== ""))]
-        .filter((path) => existsSync(join(root, path)))
-        .toSorted();
-}
 function run(root, { file, roots }) {
     const read = readCatalogue(root, file);
     if (read.state === "missing") {
@@ -109,7 +84,7 @@ function run(root, { file, roots }) {
         }
         findings.push(...judge(root, catalogue, primitive, at, cache));
     }
-    for (const path of filesUnder(root, roots)) {
+    for (const path of treeFiles(root, roots)) {
         if (!TEST_FILE.test(path) && primitivesNaming(catalogue, path).length === 0) {
             const remedy = `name it, or a directory above it, in the code of a Primitive in ${file}`;
             findings.push({ file: path, message: "no Primitive names this file", remedy });

package/dist/checks/temporal-language.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "./check.ts";
+export type TemporalLanguageOptions = {
+    files: string[];
+    exempt: string[];
+};
+export declare const temporalLanguage: Check<TemporalLanguageOptions>;

package/dist/checks/temporal-language.js

@@ -0,0 +1,58 @@
+// `temporal-language`: a durable document says what is true, not what changed. A phrase of kody's list,
+// as `docs/research/gate/kody.md` records it, fails it across a line break and never inside code;
+// decision records, research notes and changelogs record a point in time and are exempt by default.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { prose } from "../markdown.js";
+import { matching, treeFiles } from "./tree.js";
+const REMEDY = "describe what is true, in the present tense, as if written from scratch";
+/** Between two words: one space, or a line break and the next line's indent. */
+const GAP = String.raw `(?: |\n[ \t]*)`;
+function phrase(...words) {
+    return new RegExp(String.raw `\b${words.join(GAP)}\b`, "gi");
+}
+const PHRASES = [
+    phrase("now", "we"),
+    phrase("we", "now"),
+    phrase("we", "no", "longer"),
+    phrase("previously", "we"),
+    phrase("as", "before"),
+    phrase("were", String.raw `\*{0,2}removed`),
+    phrase("(?:was|were)", String.raw `\*{0,2}retired`),
+    phrase("no", "longer", "(?:support|accept|require|use|fan|carry|replay|incur|authoritative|insert|needed)s?"),
+    phrase("is", "now", "(?:a|an|the)"),
+    phrase("are", "now"),
+    phrase("previously", "(?:a|the)"),
+    phrase("recently", "(?:changed|added|updated|removed|introduced)"),
+    phrase("used", "to", "(?:support|require)")
+];
+/** Each phrase in `text` in the order it reads, one that overlaps an earlier hit, as `we no longer support` does, folded into it. */
+function hits(text) {
+    let end = 0;
+    return PHRASES.flatMap((pattern) => Array.from(text.matchAll(pattern)))
+        .toSorted((a, b) => a.index - b.index)
+        .filter((hit) => {
+        const overlaps = hit.index < end;
+        end = Math.max(end, hit.index + hit[0].length);
+        return !overlaps;
+    });
+}
+function run(root, { files, exempt }) {
+    return matching(root, treeFiles(root), files, exempt).flatMap((file) => {
+        const text = prose(readFileSync(join(root, file), "utf8"));
+        return hits(text).map((hit) => ({
+            file,
+            line: text.slice(0, hit.index).split("\n").length,
+            message: `${JSON.stringify(hit[0].replace(/\s+/g, " "))} reads as a changelog`,
+            remedy: REMEDY
+        }));
+    });
+}
+export const temporalLanguage = {
+    name: "temporal-language",
+    defaults: {
+        files: ["**/*.md"],
+        exempt: ["docs/adr/**", "docs/decisions/**", "docs/research/**", "**/CHANGELOG.md"]
+    },
+    run
+};

package/dist/checks/tree.d.ts

@@ -0,0 +1,8 @@
+/** Every file under `pathspecs`, the whole tree when there are none, that git tracks or would track and that is on disk; sorted. */
+export declare function treeFiles(root: string, pathspecs?: string[]): string[];
+/**
+ * The files of `paths` that a glob of `globs` matches and none of `exempt` does. A symbolic link is left
+ * out when the file it points at is matched too, so one file is judged once. `*` and `**` skip a name
+ * that starts with a dot, as a shell does.
+ */
+export declare function matching(root: string, paths: string[], globs: string[], exempt?: string[]): string[];

package/dist/checks/tree.js

@@ -0,0 +1,30 @@
+// The files of a repository as git sees them, and the ones a Check's globs pick out of them: what the
+// Checks that judge many files read, so a file git ignores is never judged.
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { join, matchesGlob, relative } from "node:path";
+import { CannotRun } from "./check.js";
+/** Every file under `pathspecs`, the whole tree when there are none, that git tracks or would track and that is on disk; sorted. */
+export function treeFiles(root, pathspecs = []) {
+    const args = ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...pathspecs];
+    const listed = spawnSync("git", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (listed.status !== 0) {
+        const under = pathspecs.length === 0 ? "" : ` under ${pathspecs.join(", ")}`;
+        const message = `cannot list the files${under}: not a git repository`;
+        throw new CannotRun({ message, remedy: "run the Gate inside a git repository" });
+    }
+    return [...new Set(listed.stdout.split("\0").filter((path) => path !== ""))]
+        .filter((path) => existsSync(join(root, path)))
+        .toSorted();
+}
+/**
+ * The files of `paths` that a glob of `globs` matches and none of `exempt` does. A symbolic link is left
+ * out when the file it points at is matched too, so one file is judged once. `*` and `**` skip a name
+ * that starts with a dot, as a shell does.
+ */
+export function matching(root, paths, globs, exempt = []) {
+    const matched = paths.filter((path) => globs.some((glob) => matchesGlob(path, glob)) && !exempt.some((glob) => matchesGlob(path, glob)));
+    const judged = new Set(matched);
+    const realRoot = realpathSync(root);
+    return matched.filter((path) => !lstatSync(join(root, path)).isSymbolicLink() || !judged.has(relative(realRoot, realpathSync(join(root, path)))));
+}

package/dist/commands/doctor.js

@@ -1,10 +1,6 @@
-// `dw-sdlc doctor`: one PASS / WARN / FAIL line per machine check the guardrails rely on, read-only.
-// It diagnoses the repository holding --root and the user's home; it installs nothing. FAIL is a
-// guard that does not guard (no jq, plugin absent or disabled, an invalid config), WARN a layer that
-// is missing or loose (Safe Chain, the pnpm cooldown, signing, rtk excludes), INFO a check that does
-// not apply here. Every probe goes through one interface, so the tests fake each answer. The
-// machine-wide values are asked from the home directory: from a checkout, its own
-// pnpm-workspace.yaml would answer for the machine.
+// `dw-sdlc doctor`: one PASS / WARN / FAIL line per machine check the guardrails rely on, for the
+// repository holding --root and the user's home; it installs nothing. FAIL is a guard that does not guard
+// (no jq, plugin absent or disabled, an invalid config), WARN a layer missing or loose, INFO one that does not apply.
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -232,6 +228,10 @@ function checkSafeChain(probe) {
     }
     return { name: "safe chain", level: "PASS", detail: `${binary}, npm goes through it` };
 }
+/**
+ * pnpm's global `minimumReleaseAge`, asked from the home directory: from a checkout, its own
+ * pnpm-workspace.yaml would answer for the machine.
+ */
 function checkPnpmReleaseAge(probe, home) {
     if (probe.shell("command -v pnpm") === "") {
         return { name: "pnpm release age", level: "INFO", detail: "no pnpm in the shell" };