dw-sdlc 0.7.0 → 0.9.0

package/dist/checks/decision-records.js

@@ -1,23 +1,42 @@
 // `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";
+// `<number>-<slug>.md`, are numbered from 1 with no gap and no number taken twice, and each has a title,
+// a frontmatter status from the allowed set and the frontmatter fields the config turns on.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, matchesGlob, posix } from "node:path";
+import { frontmatter, frontmatterList, headings } from "../markdown.js";
 import { CannotRun } from "./check.js";
-import { treeFiles } from "./tree.js";
+import { directoriesOf, treeFiles } from "./tree.js";
+/** The frontmatter fields beyond `status` a record can be held to, in the order they are judged. */
+const FIELDS = ["date", "touches", "superseded-by", "amended-by"];
 /** A record's name in its directory: its number, a slug, `.md`, and no directory between. */
 const RECORD = /^(\d+)-[^/]+\.md$/;
+/** The first words of a status that put a record in force, so it governs the paths under its `touches`. */
+const IN_FORCE = new Set(["accepted", "active"]);
+/** A character that makes a path under `touches` a glob. */
+const GLOB = /[*?[\]{}]/;
 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"
+    title: "start it with a level-1 heading that names the decision",
+    noDate: "give its frontmatter the day the decision was made, as date: YYYY-MM-DD",
+    date: "write the day the decision was made as YYYY-MM-DD",
+    noTouches: "list under touches the paths it governs",
+    superseded: "drop touches: the record that replaces it governs those paths",
+    path: "fix the path or drop it from touches",
+    glob: "fix the glob or drop it from touches",
+    ignored: "name the paths git tracks that it governs, or drop it from touches",
+    noSuccessor: "name under superseded-by the number of each record that replaces it",
+    successor: "name the number of each record that replaces it",
+    amendment: "name the number of each record that amends it"
 };
 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. */
+/**
+ * The `status` of the frontmatter `text` opens with, its quotes dropped, and its 1-based line. It keeps a
+ * reader apart from `frontmatter`, which a status never goes through: a ` #` is part of it.
+ */
 function statusOf(text) {
     const lines = text.split("\n");
     if (lines[0]?.trim() !== "---") {
@@ -31,6 +50,76 @@ function statusOf(text) {
     }
     return undefined;
 }
+/** Whether `value` is a day of the calendar written `YYYY-MM-DD`. */
+function isDay(value) {
+    const date = new Date(`${value}T00:00:00Z`);
+    return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
+}
+function judgeDate({ file, keys }) {
+    const date = keys.get("date");
+    if (date === undefined || date.value === "") {
+        return [{ file, message: "has no date", remedy: REMEDIES.noDate }];
+    }
+    if (!isDay(date.value)) {
+        const message = `the date ${JSON.stringify(date.value)} is not a YYYY-MM-DD day`;
+        return [{ file, line: date.line, message, remedy: REMEDIES.date }];
+    }
+    return [];
+}
+function judgeTouches({ file, state, keys }, { root, tree }) {
+    const touches = keys.get("touches");
+    const paths = frontmatterList(touches);
+    if (state === "superseded") {
+        if (touches === undefined || paths.length === 0) {
+            return [];
+        }
+        return [{ file, line: touches.line, message: "is superseded and still names touches", remedy: REMEDIES.superseded }];
+    }
+    if (paths.length === 0) {
+        return IN_FORCE.has(state) ? [{ file, message: "names no path under touches", remedy: REMEDIES.noTouches }] : [];
+    }
+    return paths.flatMap(({ value, line }) => {
+        const path = posix.normalize(value).replace(/(.)\/$/, "$1");
+        const glob = GLOB.test(path);
+        if (tree().paths.has(path) || (glob && tree().files.some((candidate) => matchesGlob(candidate, path)))) {
+            return [];
+        }
+        const quoted = JSON.stringify(value);
+        if (path !== ".." && !path.startsWith("../") && existsSync(join(root, path))) {
+            return [{ file, line, message: `touches ${quoted}, which git ignores`, remedy: REMEDIES.ignored }];
+        }
+        return glob
+            ? [{ file, line, message: `touches ${quoted}, which matches no file`, remedy: REMEDIES.glob }]
+            : [{ file, line, message: `touches ${quoted}, which does not exist`, remedy: REMEDIES.path }];
+    });
+}
+/** Each value under the list key `name` of a record that is not the number of a record of its directory. */
+function judgeNumbers(name, remedy, { file, keys }, numbers) {
+    return frontmatterList(keys.get(name)).flatMap(({ value, line }) => {
+        if (/^\d+$/.test(value) && numbers.has(Number(value))) {
+            return [];
+        }
+        const message = `${name} names ${JSON.stringify(value)}, which is not the number of a record`;
+        return [{ file, line, message, remedy }];
+    });
+}
+function judgeSuccessors(record, { numbers }) {
+    if (record.state === "superseded" && frontmatterList(record.keys.get("superseded-by")).length === 0) {
+        const message = "is superseded but names no successor under superseded-by";
+        return [{ file: record.file, message, remedy: REMEDIES.noSuccessor }];
+    }
+    return judgeNumbers("superseded-by", REMEDIES.successor, record, numbers);
+}
+function judgeAmendments(record, { numbers }) {
+    return judgeNumbers("amended-by", REMEDIES.amendment, record, numbers);
+}
+/** What is wrong with each field of a record, when the config turns that field on. */
+const RULES = {
+    date: judgeDate,
+    touches: judgeTouches,
+    "superseded-by": judgeSuccessors,
+    "amended-by": judgeAmendments
+};
 /** 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 = [];
@@ -47,8 +136,8 @@ function gaps(taken, pad) {
     }
     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) {
+/** What is wrong with the records of `dir`: the numbers they skip, then each record's number, title, status and fields. */
+function judge(root, dir, { statuses, fields }, tree) {
     const prefix = `${dir.replace(/\/+$/, "")}/`;
     const records = treeFiles(root, [dir])
         .map((file) => ({ file, name: file.slice(prefix.length) }))
@@ -68,6 +157,8 @@ function judge(root, dir, statuses) {
         remedy: REMEDIES.gap
     }));
     const allowed = `one of ${statuses.join(", ")}`;
+    const context = { root, tree, numbers: new Set(owners.keys()) };
+    const judgedFields = FIELDS.filter((field) => fields.includes(field));
     for (const { file, digits } of records) {
         const owner = owners.get(Number(digits));
         if (owner !== file) {
@@ -78,28 +169,42 @@ function judge(root, dir, statuses) {
             findings.push({ file, message: "has no title", remedy: REMEDIES.title });
         }
         const status = statusOf(text);
+        const state = status?.value.split(/\s+/)[0] ?? "";
         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] ?? "")) {
+        else if (!statuses.includes(state)) {
             const message = `the status ${JSON.stringify(status.value)} is not allowed`;
             findings.push({ file, line: status.line, message, remedy: `set it to ${allowed}` });
         }
+        if (judgedFields.length > 0) {
+            const record = { file, state, keys: frontmatter(text) };
+            findings.push(...judgedFields.flatMap((field) => RULES[field](record, context)));
+        }
     }
     return findings;
 }
-function run(root, { dirs, statuses }) {
-    const present = dirs.filter((dir) => isDirectory(join(root, dir)));
+function run(root, options) {
+    const present = options.dirs.filter((dir) => isDirectory(join(root, dir)));
     if (present.length === 0) {
-        throw new CannotRun({ message: `none of ${dirs.join(", ")} exists`, remedy: REMEDIES.missing });
+        throw new CannotRun({ message: `none of ${options.dirs.join(", ")} exists`, remedy: REMEDIES.missing });
     }
-    return present.flatMap((dir) => judge(root, dir, statuses));
+    let cached;
+    const tree = () => {
+        if (cached === undefined) {
+            const files = treeFiles(root);
+            cached = { files, paths: new Set([...files, ...directoriesOf(files)]) };
+        }
+        return cached;
+    };
+    return present.flatMap((dir) => judge(root, dir, options, tree));
 }
 export const decisionRecords = {
     name: "decision-records",
     defaults: {
         dirs: ["docs/adr", "docs/decisions"],
-        statuses: ["proposed", "accepted", "active", "deprecated", "superseded"]
+        statuses: ["proposed", "accepted", "active", "deprecated", "superseded"],
+        fields: []
     },
     run
 };

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

@@ -1,10 +1,9 @@
-// `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.
+// `file-size-ratchet`: each file of code 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";
@@ -34,6 +33,11 @@ function inBaseline(line) {
 function groupOf(path, groups) {
     return groups.find(({ files }) => files.some((glob) => matchesGlob(path, glob)));
 }
+/** The lines of `text`, a last line without its newline counted, the empty line after a final newline not. */
+function lineCount(text) {
+    const lines = text.split("\n").length;
+    return text.endsWith("\n") ? lines - 1 : lines;
+}
 function measure(root, groups) {
     const measured = new Map();
     for (const path of matching(root, treeFiles(root), groups.flatMap(({ files }) => files))) {
@@ -178,14 +182,12 @@ function refresh(root, { groups }) {
     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 }
         ]
     },

package/dist/checks/index.js

@@ -8,6 +8,7 @@ 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 { routedDocs } from "./routed-docs.js";
 import { temporalLanguage } from "./temporal-language.js";
 function ship(check) {
     return {
@@ -29,6 +30,7 @@ function ship(check) {
 const SHIPPED = [
     ship(primitives),
     ship(agentsMap),
+    ship(routedDocs),
     ship(markdownBudget),
     ship(markdownRefs),
     ship(temporalLanguage),

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

@@ -1,6 +1,5 @@
 import type { Check } from "./check.ts";
 export type Budget = {
-    maxLines: number;
     maxBytes: number;
 };
 export type MarkdownBudgetOptions = {
@@ -8,8 +7,6 @@ export type MarkdownBudgetOptions = {
         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[];
+/** What `text` spends past its budget, `10651 bytes, over the 10240-byte budget`; nothing within it. */
+export declare function overBudget(text: string, { maxBytes }: Budget): string[];
 export declare const markdownBudget: Check<MarkdownBudgetOptions>;

package/dist/checks/markdown-budget.js

@@ -1,5 +1,5 @@
-// `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.
+// `markdown-budget`: each file a glob matches stays within that glob's 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";
@@ -7,19 +7,10 @@ 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);
+/** What `text` spends past its budget, `10651 bytes, over the 10240-byte budget`; nothing within it. */
+export function overBudget(text, { maxBytes }) {
     const bytes = Buffer.byteLength(text);
-    return [
-        ...(lines > maxLines ? [`${lines} lines, over the ${maxLines}-line budget`] : []),
-        ...(bytes > maxBytes ? [`${bytes} bytes, over the ${maxBytes}-byte budget`] : [])
-    ];
+    return bytes > maxBytes ? [`${bytes} bytes, over the ${maxBytes}-byte budget`] : [];
 }
 function run(root, { budgets }) {
     const files = treeFiles(root);
@@ -37,6 +28,6 @@ function run(root, { budgets }) {
 }
 export const markdownBudget = {
     name: "markdown-budget",
-    defaults: { budgets: [{ glob: "docs/agents/*.md", maxLines: 100, maxBytes: 6144 }] },
+    defaults: { budgets: [{ glob: "docs/agents/*.md", maxBytes: 6144 }] },
     run
 };

package/dist/checks/markdown-refs.js

@@ -4,7 +4,7 @@
 import { readFileSync } from "node:fs";
 import { join, posix } from "node:path";
 import { anchorsOf, links } from "../markdown.js";
-import { matching, treeFiles } from "./tree.js";
+import { directoriesOf, matching, treeFiles } from "./tree.js";
 const REMEDIES = {
     path: "fix the path or drop the link",
     outside: "point it at a file of the repository",
@@ -20,16 +20,6 @@ function decode(text) {
         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 === "") {

package/dist/checks/routed-docs.d.ts

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

package/dist/checks/routed-docs.js

@@ -0,0 +1,49 @@
+// `routed-docs`: a task leads an agent to every document that explains it. Each document is reached by
+// a Task Router row of the agent map, through a path, a directory above it or a glob, or by the docs of
+// a Primitive in the catalogue. It reads the file list, the Task Router and the catalogue, never prose.
+import { matchesGlob, posix } from "node:path";
+import { resolveConfig } from "../agentic-config.js";
+import { readCatalogue } from "../catalogue.js";
+import { mapFile, readMap, routes } from "./agents-map.js";
+import { catalogueFile } from "./primitives.js";
+import { matching, treeFiles } from "./tree.js";
+const REMEDIES = {
+    table: "add a Task Router section whose table names the docs",
+    unreached: "add a Task Router row, name it in a Primitive's docs, or exempt it"
+};
+/** `entry` as a path from the root: its heading anchor, a leading `./` or `/` and a trailing `/` dropped. */
+function fromRoot(entry) {
+    const [path = ""] = entry.split("#", 1);
+    return posix.join(".", path).replace(/\/+$/, "");
+}
+/** Whether `target`, a path a row points at, names `doc`, a directory above it or a glob that matches it. */
+function reaches(target, doc) {
+    return target.includes("*") ? matchesGlob(doc, target) : doc === target || doc.startsWith(`${target}/`);
+}
+/** The docs entries of the catalogue's Primitives; none when it is missing or not valid. */
+function catalogueDocs(root, file) {
+    const read = readCatalogue(root, file);
+    return read.state === "valid" ? read.catalogue.primitives.flatMap(({ docs }) => docs) : [];
+}
+function run(root, { files, exempt }) {
+    const { checks } = resolveConfig(root).config.gate;
+    const map = mapFile(checks);
+    const rows = routes(readMap(root, map));
+    const findings = [];
+    if (rows.length === 0) {
+        findings.push({ file: map, message: "has no Task Router table to reach a doc from", remedy: REMEDIES.table });
+    }
+    const targets = rows.flatMap(({ paths }) => paths).map(fromRoot);
+    const catalogued = new Set(catalogueDocs(root, catalogueFile(checks)).map(fromRoot));
+    for (const doc of matching(root, treeFiles(root), files, exempt)) {
+        if (!catalogued.has(doc) && !targets.some((target) => reaches(target, doc))) {
+            findings.push({ file: doc, message: "no Task Router row or Primitive reaches it", remedy: REMEDIES.unreached });
+        }
+    }
+    return findings;
+}
+export const routedDocs = {
+    name: "routed-docs",
+    defaults: { files: ["docs/**/*.md"], exempt: ["docs/research/**"] },
+    run
+};

package/dist/checks/tree.d.ts

@@ -1,5 +1,7 @@
 /** 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[];
+/** Every directory above a file of `files`. */
+export declare function directoriesOf(files: Iterable<string>): Set<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

package/dist/checks/tree.js

@@ -1,8 +1,8 @@
-// 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.
+// The files of a repository as git sees them, the directories above 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 { join, matchesGlob, posix, 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 = []) {
@@ -17,6 +17,16 @@ export function treeFiles(root, pathspecs = []) {
         .filter((path) => existsSync(join(root, path)))
         .toSorted();
 }
+/** Every directory above a file of `files`. */
+export 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 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

package/dist/commands/check.d.ts

@@ -1,2 +1,2 @@
 export declare const summary = "run one Check of the Gate by its name, without the Steps and the other Checks";
-export declare function run(argv: string[]): number;
+export declare function run(argv: string[]): Promise<number>;

package/dist/commands/check.js

@@ -2,6 +2,7 @@
 import { parseArgs } from "node:util";
 import { repositoryRoot } from "../agentic-config.js";
 import { CHECK_NAMES } from "../checks/index.js";
+import { TAIL_LINES } from "../run-command.js";
 import { printReport, runGate } from "./gate.js";
 export const summary = "run one Check of the Gate by its name, without the Steps and the other Checks";
 const USAGE = `Usage: dw-sdlc check <name> [--json] [--root <dir>]
@@ -10,8 +11,9 @@ Runs the Check named <name> in the Gate of the repository holding --root (defaul
 directory): a script under gate.checks.run, or a Check the package ships, one of
 ${CHECK_NAMES.join(", ")}. A name both carry runs both, as the Gate does. A
 shipped Check runs on the setting gate.checks gives it, and on its defaults where the config sets it
-false or leaves it out. No Step runs. Prints one line per failure, as the Gate does; --json prints
-the Gate's document, with no Step.
+false or leaves it out. No Step runs. A run script prints nothing of its own unless it does not
+pass: then its last ${TAIL_LINES} lines, both streams in the order written. Prints one line per failure,
+as the Gate does; --json prints the Gate's document alone, with no Step.
 
 A Ratchet's baseline is refreshed by dw-sdlc gate --update-baseline, which needs every other Check to
 pass.
@@ -39,7 +41,7 @@ function parseCli(argv) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
 }
-export function run(argv) {
+export async function run(argv) {
     const cli = parseCli(argv);
     if ("error" in cli) {
         process.stderr.write(`dw-sdlc check: ${cli.error}\n\n${USAGE}\n`);
@@ -54,6 +56,6 @@ export function run(argv) {
         return 2;
     }
     const { json, name } = cli;
-    const report = runGate(repositoryRoot(cli.root ?? process.cwd()), { json, only: name });
+    const report = await runGate(repositoryRoot(cli.root ?? process.cwd()), { json, only: name });
     return printReport(report, json, `check ${name}`);
 }

package/dist/commands/gate.d.ts

@@ -1,9 +1,10 @@
 import { type Failure } from "../report.ts";
+import { type Status } from "../run-command.ts";
 export declare const summary = "run the Gate: the Steps of gate.steps in order, then every Check under gate.checks";
-type Status = "pass" | "fail" | "error";
 type Outcome = {
     status: Status | "skipped";
     exitCode: number | null;
+    tail: string[] | null;
 };
 type StepReport = Outcome & {
     command: string;
@@ -16,23 +17,28 @@ type CheckReport = Outcome & {
 type GateReport = {
     status: Status;
     command: string | null;
+    /** Present on a run the cache skipped. */
+    cached?: true;
     steps: StepReport[];
     checks: CheckReport[];
     failures: Failure[];
 };
+/** How a run of the whole Gate goes: plain, refreshing each Ratchet's baseline, or cached on a green tree. */
+type Mode = "plain" | "update-baseline" | "cache";
 /** A run of the whole Gate, or of the Checks named `only` alone: no Step, no progress line, no refresh. */
 type RunOptions = {
     json: boolean;
 } & ({
-    updateBaseline: boolean;
+    mode: Mode;
+    verbose: boolean;
 } | {
     only: string;
 });
-export declare function runGate(root: string, options: RunOptions): GateReport;
+export declare function runGate(root: string, options: RunOptions): Promise<GateReport>;
 /**
  * Prints `report`: a line per failure and the verdict under `label`, or one document under `json`; under
  * GitHub Actions each failure is also an annotation. Returns the exit code.
  */
 export declare function printReport(report: GateReport, json: boolean, label: string): number;
-export declare function run(argv: string[]): number;
+export declare function run(argv: string[]): Promise<number>;
 export {};