dw-sdlc 0.0.0-stage → 0.2.0

package/dist/checks/index.d.ts

@@ -0,0 +1,12 @@
+import { type Finding } from "./check.ts";
+/** 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

@@ -0,0 +1,42 @@
+// The Checks the package ships, in the order the Gate runs them. A new Check is a module beside this
+// 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);
+            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),
+    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.d.ts

@@ -0,0 +1,8 @@
+import { type Check } from "./check.ts";
+export type PrimitivesOptions = {
+    file: string;
+    roots: string[];
+};
+export declare const primitives: Check<PrimitivesOptions>;
+/** The catalogue a resolved `gate.checks` points at: the `primitives` Check's file, on or off. */
+export declare function catalogueFile(checks: Record<string, unknown>): string;

package/dist/checks/primitives.js

@@ -0,0 +1,103 @@
+// `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 { existsSync } from "node:fs";
+import { join } from "node:path";
+import { CATALOGUE_FILE, primitivesNaming, readCatalogue } from "../catalogue.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)\.[^/]+$/;
+const REMEDIES = {
+    missing: "create it, or point gate.checks.primitives.file at the catalogue",
+    shape: "give it the catalogue's shape: version 1, groups of id and name, primitives of id, name, group, summary, code and docs",
+    duplicate: "give each Primitive an id of its own",
+    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"
+};
+function show(value) {
+    return JSON.stringify(value);
+}
+/** The line of the `nth` (0-based) `"id": "<id>"` under the `primitives` key, where a Primitive is declared. */
+function lineOf(text, id, nth) {
+    const start = Math.max(0, text.indexOf('"primitives"'));
+    const pattern = new RegExp(`"id"\\s*:\\s*${JSON.stringify(id).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g");
+    const match = Array.from(text.slice(start).matchAll(pattern))[nth];
+    return match?.index === undefined ? undefined : text.slice(0, start + match.index).split("\n").length;
+}
+/** 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;
+    const findings = [];
+    const fail = (message, remedy) => findings.push({ ...at, message, remedy });
+    if (!catalogue.groups.some((known) => known.id === group)) {
+        fail(`${show(id)} is in group ${show(group)}, which groups does not list`, REMEDIES.group);
+    }
+    const summaryLines = summary.split("\n").length;
+    if (summaryLines > 1) {
+        fail(`the summary of ${show(id)} runs over ${summaryLines} lines`, REMEDIES.summary);
+    }
+    else if ([...summary].length > MAX_SUMMARY) {
+        fail(`the summary of ${show(id)} is ${[...summary].length} characters, over ${MAX_SUMMARY}`, REMEDIES.summary);
+    }
+    for (const entry of code.filter((path) => !existsSync(join(root, path)))) {
+        fail(`${show(id)} names code at ${show(entry)}, which does not exist`, REMEDIES.path);
+    }
+    for (const entry of docs) {
+        const [path = "", anchor] = entry.split("#", 2);
+        if (!existsSync(join(root, path))) {
+            fail(`${show(id)} names the doc ${show(entry)}, which does not exist`, REMEDIES.path);
+        }
+        else if (anchor !== undefined && !anchorsOf(root, path, cache).has(anchor)) {
+            fail(`${show(id)} names the doc ${show(entry)}, which has no heading with that anchor`, REMEDIES.anchor);
+        }
+    }
+    return findings;
+}
+function run(root, { file, roots }) {
+    const read = readCatalogue(root, file);
+    if (read.state === "missing") {
+        throw new CannotRun({ file, message: "the catalogue does not exist", remedy: REMEDIES.missing });
+    }
+    if (read.state === "invalid") {
+        return read.problems.map((message) => ({ file, message, remedy: REMEDIES.shape }));
+    }
+    const { catalogue, text } = read;
+    const findings = [];
+    const seen = new Map();
+    const cache = new Map();
+    for (const primitive of catalogue.primitives) {
+        const nth = seen.get(primitive.id) ?? 0;
+        seen.set(primitive.id, nth + 1);
+        const line = lineOf(text, primitive.id, nth);
+        const at = line === undefined ? { file } : { file, line };
+        if (nth > 0) {
+            findings.push({
+                ...at,
+                message: `id ${show(primitive.id)} is taken by an earlier Primitive`,
+                remedy: REMEDIES.duplicate
+            });
+        }
+        findings.push(...judge(root, catalogue, primitive, at, cache));
+    }
+    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 });
+        }
+    }
+    return findings;
+}
+export const primitives = {
+    name: "primitives",
+    defaults: { file: CATALOGUE_FILE, roots: ["packages", "plugins", "scripts", "src"] },
+    run
+};
+/** The catalogue a resolved `gate.checks` points at: the `primitives` Check's file, on or off. */
+export function catalogueFile(checks) {
+    return (optionsOf(primitives, checks.primitives) ?? primitives.defaults).file;
+}

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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// The `dw-sdlc` bin: one row per subcommand, each a module under `commands/`. A plugin's hook or skill
+// reaches it through the plugin's `dw-sdlc` link.
+import * as config from "./commands/config.js";
+import * as doctor from "./commands/doctor.js";
+import * as gate from "./commands/gate.js";
+import * as primitives from "./commands/primitives.js";
+import * as referencesSetup from "./commands/references-setup.js";
+import * as referencesSync from "./commands/references-sync.js";
+import * as setup from "./commands/setup.js";
+const COMMANDS = new Map([
+    ["gate", gate],
+    ["primitives", primitives],
+    ["setup", setup],
+    ["doctor", doctor],
+    ["config", config],
+    ["references sync", referencesSync],
+    ["references setup", referencesSetup]
+]);
+function usage() {
+    const width = Math.max(...[...COMMANDS.keys()].map((name) => name.length)) + 2;
+    const rows = [...COMMANDS].map(([name, { summary }]) => `  ${name.padEnd(width)}${summary}`);
+    return `Usage: dw-sdlc <command> [options]\n\nCommands:\n${rows.join("\n")}\n\nRun dw-sdlc <command> --help for its options.`;
+}
+async function main(argv) {
+    const [first, second] = argv;
+    if (first === "--help" || first === "-h") {
+        process.stdout.write(`${usage()}\n`);
+        return 0;
+    }
+    // A two-word name, as `references sync`, before its first word alone.
+    const words = second !== undefined && COMMANDS.has(`${first} ${second}`) ? 2 : 1;
+    const command = COMMANDS.get(argv.slice(0, words).join(" "));
+    if (command === undefined) {
+        const problem = first === undefined ? "no command given" : `unknown command ${JSON.stringify(first)}`;
+        process.stderr.write(`dw-sdlc: ${problem}\n\n${usage()}\n`);
+        return 2;
+    }
+    return command.run(argv.slice(words));
+}
+if (import.meta.main) {
+    process.exitCode = await main(process.argv.slice(2));
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "resolve the repository's agentic config, or validate one file against the schema";
+export declare function run(argv: string[]): number;

package/dist/commands/config.js

@@ -0,0 +1,76 @@
+// `dw-sdlc config`, the config check: resolves a repository's agentic config, or validates one file
+// against the schema, and prints what the guards see.
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { COMMITTED_FILE, findRepository, LOCAL_FILE, repositoryRoot, resolveConfig, validateDocument } from "../agentic-config.js";
+export const summary = "resolve the repository's agentic config, or validate one file against the schema";
+const USAGE = `Usage: dw-sdlc config [--root <dir>] [file]
+  or:  pnpm agentic:check [--root <dir>] [file], in a checkout of dw-sdlc
+
+Without a file: resolves the agentic config of the repository holding --root (default: the current
+directory) — local over committed over inferred — and prints what the guards see. With a file:
+validates that one document against the schema. Exit 1 on any problem.`;
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function fail(message, code) {
+    console.error(`agentic:check: ${message}`);
+    process.exit(code);
+}
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: { help: { type: "boolean", short: "h" }, root: { type: "string" } }
+        });
+        if (positionals.length > 1) {
+            throw new Error("at most one file");
+        }
+        return { help: values.help === true, root: values.root, file: positionals[0] };
+    }
+    catch (error) {
+        fail(`${messageOf(error)}\n\n${USAGE}`, 2);
+    }
+}
+function report(problems) {
+    for (const { file, path, message } of problems) {
+        console.error(path === "" ? `${file}: ${message}` : `${file}: ${path}: ${message}`);
+    }
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if (cli.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (cli.file !== undefined) {
+        let text;
+        try {
+            text = readFileSync(cli.file, "utf8");
+        }
+        catch (error) {
+            fail(messageOf(error), 1);
+        }
+        const result = validateDocument(cli.file, text);
+        if ("problems" in result) {
+            report(result.problems);
+            return 1;
+        }
+        console.log(`${cli.file}: valid`);
+        return 0;
+    }
+    const root = cli.root === undefined
+        ? (findRepository(process.cwd()) ?? fail("not inside a git repository; pass --root <dir>", 1))
+        : repositoryRoot(cli.root);
+    const { config, problems, layers, sources } = resolveConfig(root);
+    const from = (source) => source === undefined || source === root ? "" : `, from ${source}`;
+    console.log(`committed  ${COMMITTED_FILE}  ${layers.committed}${from(sources.committed)}`);
+    console.log(`local      ${LOCAL_FILE}  ${layers.local}${from(sources.local)}`);
+    console.log(JSON.stringify(config, null, 2));
+    if (problems.length > 0) {
+        report(problems);
+        fail(`${problems.length} problem(s) above; the guards run on the strictest defaults until the file is fixed`, 1);
+    }
+    return 0;
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,57 @@
+export type Level = "PASS" | "WARN" | "FAIL" | "INFO";
+export type Check = {
+    name: string;
+    level: Level;
+    detail: string;
+};
+/** What the doctor asks the machine; the tests answer from canned data. */
+export type Probe = {
+    /** A command run directly, from `cwd` when given, with its exit status and stdout. */
+    run(command: string, args: string[], cwd?: string): {
+        status: number;
+        stdout: string;
+    };
+    /** A file's text, or undefined when it is absent. */
+    read(path: string): string | undefined;
+    /** One line of `command -v <tool>` from a non-interactive login shell, the shell the agent gets. */
+    shell(script: string): string;
+};
+export type RepositoryConfig = {
+    config: {
+        commit: {
+            convention: string;
+        };
+    };
+    problems: string[];
+    /** The checkout each layer was read from, as `resolveConfig` reports it. */
+    sources?: {
+        committed: string | undefined;
+        local: string | undefined;
+    };
+};
+export type Inputs = {
+    root: string;
+    home: string;
+    /** Claude Code's config dir; `<home>/.claude` when absent. */
+    claudeDir?: string;
+    probe: Probe;
+    /** Undefined when no repository holds `root`. */
+    config: RepositoryConfig | undefined;
+};
+/** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
+export declare function claudeConfigDir(env: Record<string, string | undefined>, home: string): string;
+/** The marketplace Claude Code registers this repository under, and the plugin id inside it. */
+export declare const MARKETPLACE = "dw-sdlc";
+export declare const PLUGIN_ID = "guardrails@dw-sdlc";
+/** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
+export declare const RTK_FIND_EXEC_FIXED = "0.46.0";
+export declare const PNPM_MINIMUM_RELEASE_AGE = 10080;
+export declare const realProbe: Probe;
+/** rtk's config.toml: Application Support on macOS, XDG or ~/.config elsewhere. */
+export declare function rtkConfigPath(home: string, platform?: string, env?: Record<string, string | undefined>): string;
+/** The `exclude_commands` list of an rtk config.toml, read with a regex: the file is small and ours. */
+export declare function rtkExcludes(toml: string | undefined): string[];
+export declare function diagnose(inputs: Inputs): Check[];
+export declare function render(checks: Check[]): string;
+export declare const summary = "one PASS / WARN / FAIL line per machine check the guardrails rely on";
+export declare function run(argv: string[]): number;