@descryy/mcp 0.11.5 → 0.11.7

package/dist/tools/pr-analysis.js

@@ -0,0 +1,365 @@
+/**
+ * `pr-analysis` — "what should I test before I open this PR?"
+ *
+ * The blast radius of a diff, intersected with the tests that cover it. The
+ * useful half of the answer is the second list: **what is affected and has no
+ * covering test.** A green suite proves nothing about that set, and it is the
+ * only part of a PR review that a test run cannot supply.
+ *
+ * ## `base...head`, three dots
+ *
+ * `changedFiles` diffs against the merge base rather than the two tips. On a
+ * branch a week behind `main`, two dots would fold every change made on `main`
+ * since the branch point into "this PR", and the blast radius would belong to
+ * somebody else's work. This is stated here as well as at the git call because
+ * it is the kind of thing that gets "simplified" later.
+ *
+ * ## Absence of a test is not evidence of absence
+ *
+ * `TESTS` edges come from adapters, and every adapter's recall is below 100% by
+ * design — precision over recall, when in doubt omit the edge. So "no covering
+ * test" means "no test that this graph can link", and the difference is
+ * disclosed. Reporting the untested list without it would turn a measured recall
+ * gap into a confident accusation.
+ *
+ * ## One node map, three id lists
+ *
+ * `affected`, `untested` and `tests` overlap heavily by construction — an
+ * affected node with no covering test is in two of them — and each used to
+ * carry the whole node inline, so the same fields were serialized up to three
+ * times in one reply. `indexPrAnalysisNodes` collapses that: the lists name
+ * ids, `nodes` holds each node once. Tool version 2.0.0 for it.
+ */
+import { addedLineRanges, changeRisk, gitDiff, gitWorkingTreeChange, NODE_BUDGETS, nodesInFiles, withProminence, } from "@descryy/core";
+import { answer, briefNode, optionalEnum, optionalInteger, descryOwnState, optionalString, ToolInputError, } from "./kit.js";
+import { sizeCapNote } from "../capped.js";
+/**
+ * Collapse three overlapping node lists into one map plus three id lists.
+ *
+ * Order within each list is preserved exactly — it is the ranking the query
+ * layer produced, and re-sorting it here would silently change which nodes a
+ * caller's own `limit` keeps.
+ */
+export function indexPrAnalysisNodes(affected, untested, tests) {
+    const nodes = {};
+    const remember = (node) => {
+        if (nodes[node.id] === undefined)
+            nodes[node.id] = briefNode(node);
+        return node.id;
+    };
+    return {
+        affected: withProminence(affected.map((entry) => ({
+            id: remember(entry.node),
+            score: Number(entry.score.toFixed(4)),
+            depth: entry.depth,
+        }))),
+        untested: untested.map(remember),
+        tests: tests.map(remember),
+        nodes,
+    };
+}
+/**
+ * `fitToBudget` for `PrAnalysisReport` — harder than a plain list because
+ * `nodes` is shared: dropping a trailing id from `affected` only saves bytes
+ * if that id is not also named by `untested` or `tests`. So this walks the
+ * three id-lists in priority order (`affected`, the point of the tool, first;
+ * `tests` last, since it is usually the smallest and least load-bearing),
+ * paying each node's cost once, the first time any list names it, and
+ * dropping an item the moment its own cost plus its node's first-time cost
+ * (if any) would not fit — never partially, and never over budget.
+ */
+function fitPrAnalysis(rest, affectedRefs, untestedIds, testIds, nodes, budgetBytes) {
+    const scaffoldBytes = Buffer.byteLength(JSON.stringify({ ...rest, affected: [], untested: [], tests: [], nodes: {} }), "utf8");
+    let budget = Math.max(budgetBytes - scaffoldBytes, 0);
+    const countedIds = new Set();
+    const nodeCost = (id) => {
+        const node = nodes[id];
+        if (node === undefined || countedIds.has(id))
+            return 0;
+        return Buffer.byteLength(JSON.stringify(id), "utf8") + Buffer.byteLength(JSON.stringify(node), "utf8") + 2;
+    };
+    function take(items, idOf) {
+        const shown = [];
+        for (const item of items) {
+            const id = idOf(item);
+            const cost = Buffer.byteLength(JSON.stringify(item), "utf8") + 1 + nodeCost(id);
+            if (cost > budget)
+                break;
+            budget -= cost;
+            countedIds.add(id);
+            shown.push(item);
+        }
+        return { shown, dropped: items.length - shown.length };
+    }
+    const affectedFit = take(affectedRefs, (a) => a.id);
+    const untestedFit = take(untestedIds, (id) => id);
+    const testsFit = take(testIds, (id) => id);
+    const prunedNodes = {};
+    for (const id of countedIds) {
+        const node = nodes[id];
+        if (node !== undefined)
+            prunedNodes[id] = node;
+    }
+    const notes = [];
+    if (affectedFit.dropped > 0) {
+        notes.push(sizeCapNote("affected node", affectedFit.shown.length, affectedRefs.length, affectedFit.dropped));
+    }
+    if (untestedFit.dropped > 0) {
+        notes.push(sizeCapNote("untested node", untestedFit.shown.length, untestedIds.length, untestedFit.dropped));
+    }
+    if (testsFit.dropped > 0) {
+        notes.push(sizeCapNote("covering test", testsFit.shown.length, testIds.length, testsFit.dropped));
+    }
+    const droppedNow = affectedFit.dropped + untestedFit.dropped + testsFit.dropped;
+    return {
+        data: {
+            ...rest,
+            affected: affectedFit.shown,
+            untested: untestedFit.shown,
+            tests: testsFit.shown,
+            nodes: prunedNodes,
+        },
+        notes,
+        ...(droppedNow === 0
+            ? {}
+            : {
+                truncatedDetail: {
+                    shown: affectedFit.shown.length + untestedFit.shown.length + testsFit.shown.length,
+                    total: affectedRefs.length + untestedIds.length + testIds.length,
+                    more: null,
+                },
+            }),
+    };
+}
+/** Path to the lines the diff actually added in it — `null` when the patch was
+ *  withheld (binary, or a size budget), which is not the same as "no lines added". */
+function addedLinesByFile(files) {
+    return new Map(files.map((f) => [f.path, f.patch === null ? null : addedLineRanges(f.patch)]));
+}
+/** Does this node's declared range land on a line the diff actually added?
+ *  `false` for anything unprovable — no range, no file, or a file whose patch
+ *  was withheld — never assumed true (F5, UAT Phase 5, rule 2). */
+function touchesAddedLine(node, addedByFile) {
+    if (node.file === null || node.range === null)
+        return false;
+    const ranges = addedByFile.get(node.file);
+    if (ranges === null || ranges === undefined)
+        return false;
+    return ranges.some((r) => node.range.startLine <= r.end && node.range.endLine >= r.start);
+}
+const TRIGGERS = ["pre-push", "pr", "nightly"];
+const SCHEMA = {
+    type: "object",
+    properties: {
+        base: {
+            type: "string",
+            description: "Branch/commit measured against, e.g. \"main\". Required unless workingTree is given.",
+        },
+        head: { type: "string", description: "The tip being reviewed. Default HEAD." },
+        workingTree: {
+            type: "string",
+            enum: ["unstaged", "staged", "all"],
+            description: "Review the working tree instead of two refs. Exclusive with base.",
+        },
+        includeUntracked: {
+            type: "boolean",
+            description: "With workingTree, include never-added files. On by default.",
+        },
+        trigger: {
+            type: "string",
+            enum: [...TRIGGERS],
+            description: "Node budget to use. Default pr (1000).",
+        },
+        limit: { type: "integer", minimum: 1, description: "Cap on nodes per list. Default 50." },
+    },
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    // One of the two questions has to be chosen, and neither has a defensible
+    // default: guessing would silently change which change set the whole answer
+    // describes. This tool's own reasoning is that the diff is what defines a
+    // change to review — a working tree *is* a diff, it is simply not a
+    // ref-to-ref one, so accepting it completes that principle rather than
+    // bending it. Which one ran is stated in the reply.
+    const workingTree = optionalString(args, "workingTree");
+    const includeUntracked = args["includeUntracked"] !== false;
+    const baseArg = optionalString(args, "base");
+    if (workingTree === undefined && baseArg === undefined) {
+        throw new ToolInputError('Give either "base" (a ref range) or "workingTree" (the change as it stands, uncommitted). ' +
+            "There is no defensible default, and guessing one silently changes which change set the " +
+            "answer describes.");
+    }
+    if (workingTree !== undefined && baseArg !== undefined) {
+        throw new ToolInputError('"base" and "workingTree" are mutually exclusive — they are two different questions. Ask one.');
+    }
+    if (workingTree !== undefined && !["unstaged", "staged", "all"].includes(workingTree)) {
+        throw new ToolInputError(`"workingTree" must be "unstaged", "staged" or "all" — got "${workingTree}".`);
+    }
+    const scope = (workingTree ?? "all");
+    const mode = baseArg === undefined ? "working-tree" : "range";
+    const base = baseArg ?? null;
+    const head = base === null ? null : optionalString(args, "head") ?? "HEAD";
+    const subject = base === null ? `the working tree (${scope})` : `${base}...${head}`;
+    /** Carried into every one of the four reply shapes, so none can omit it. */
+    const identity = {
+        mode,
+        base,
+        head,
+        ...(base === null ? { workingTree: { scope, includeUntracked } } : {}),
+    };
+    const trigger = optionalEnum(args, "trigger", TRIGGERS) ?? "pr";
+    const limit = optionalInteger(args, "limit", 1) ?? 50;
+    const session = ctx.session;
+    const stamp = session.provider().baseStamp();
+    ctx.progress(`Diffing ${subject}`);
+    let diffFiles;
+    try {
+        diffFiles =
+            base === null
+                ? (await gitWorkingTreeChange(session.repoPath, {
+                    scope,
+                    includeUntracked,
+                    exclude: descryOwnState(session.config.graph),
+                })).files
+                : await gitDiff(session.repoPath, base, head);
+    }
+    catch (error) {
+        return answer({
+            headline: `Could not diff ${subject}.`,
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: stamp.commitSha,
+            graphBuiltAt: stamp.graphBuiltAt,
+            irSchemaVersion: stamp.irSchemaVersion,
+            commitSpread: stamp.commitSpread,
+            repoCount: stamp.repoCount,
+            notes: [
+                (base === null
+                    ? `git rejected the working-tree read: ${error.message.trim()}.`
+                    : `git rejected the range: ${error.message.trim()}. Check that "${base}" ` +
+                        "exists locally — a shallow clone or a missing fetch is the usual cause."),
+            ],
+            data: { ...identity, files: [] },
+        });
+    }
+    const files = diffFiles.map((f) => f.path);
+    const addedByFile = addedLinesByFile(diffFiles);
+    const notes = [];
+    if (files.length === 0) {
+        return answer({
+            headline: `${subject} changes no files.`,
+            nameLevel: true,
+            // 0, not 4. Every other branch of this tool already stamps 0 for the same
+            // reason `get_git_diff` does — a live git read is not a graph-traversal
+            // claim — and this branch reads *less* than they do, not more. Stamping
+            // the strongest tier on the answer that rests on no graph evidence at all
+            // was the same leaked default `createResolutionFloor` exists to remove.
+            resolutionFloor: 0,
+            commitSha: stamp.commitSha,
+            graphBuiltAt: stamp.graphBuiltAt,
+            irSchemaVersion: stamp.irSchemaVersion,
+            commitSpread: stamp.commitSpread,
+            repoCount: stamp.repoCount,
+            notes: ["An empty diff is a real answer: there is nothing to assess."],
+            data: { ...identity, files: [], nodes: {}, affected: [], untested: [], tests: [] },
+        });
+    }
+    ctx.progress(`Resolving ${files.length} changed file(s)`, 1, 3);
+    const { nodes, missing } = nodesInFiles(session.store().driver, files);
+    if (missing.length > 0) {
+        notes.push(`${missing.length} of ${files.length} changed file(s) have no node in the graph ` +
+            `(${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ", …" : ""}). They are outside ` +
+            "what any configured adapter reads, or the graph predates them. Their impact is absent " +
+            "from this analysis and they are not being reported as safe.");
+    }
+    if (nodes.length === 0) {
+        return answer({
+            headline: `None of the ${files.length} file(s) changed in ${subject} are in the graph.`,
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: stamp.commitSha,
+            graphBuiltAt: stamp.graphBuiltAt,
+            irSchemaVersion: stamp.irSchemaVersion,
+            commitSpread: stamp.commitSpread,
+            repoCount: stamp.repoCount,
+            notes: [
+                ...notes,
+                "No blast radius was computed. Run analyze first; if it has already run, its disclosures " +
+                    "name the languages and paths it could not read.",
+            ],
+            data: { ...identity, files, missing, nodes: {}, affected: [], untested: [], tests: [] },
+        });
+    }
+    ctx.progress(`Assessing ${nodes.length} changed symbol(s)`, 2, 3);
+    // `changeRisk` takes a raw node budget rather than a trigger: the trigger is a
+    // scoping concept and the query layer deliberately does not know about it.
+    // Translating here keeps the tool's vocabulary the developer's ("this is a
+    // PR") and the engine's its own.
+    //
+    // Seeded from every symbol in a touched file, not only the ones whose range
+    // actually intersects an added line (F5, UAT Phase 5) — deliberately: a
+    // line-precise seed set would silently lose a deleted file's symbols (no
+    // added lines to intersect) and any file whose patch was withheld by the
+    // diff's own size budget. `changedSymbols` below reports the precise count;
+    // this traversal stays seeded from the broader, disclosed one.
+    const risk = changeRisk(session.provider(), nodes.map((n) => n.id), { budget: NODE_BUDGETS[trigger] });
+    const changedSymbols = nodes.filter((n) => touchesAddedLine(n, addedByFile)).length;
+    notes.push("\"Untested\" means no test is linked to the node in this graph. Adapters omit an edge they " +
+        "cannot prove, so a genuinely covered symbol can appear here — treat it as a gap to check, " +
+        "not as a proven hole.", `"changedSymbols" counts only nodes whose declared range intersects a line the diff actually ` +
+        `added; "symbolsInChangedFiles" (${nodes.length}) counts every node living in a touched ` +
+        "file, whichever lines moved — the blast radius below is seeded from that broader set, not " +
+        "only from changedSymbols, so a deleted file's callers and a size-capped file's symbols are " +
+        "not silently dropped from the analysis.");
+    const untested = risk.data.untested;
+    const affected = risk.data.affected.filter((entry) => entry.node.type !== "TEST_CASE");
+    // One node map, three id lists — see `indexPrAnalysisNodes`. Each list is
+    // capped by `limit` *before* indexing, so the map holds only what the reply
+    // actually names.
+    const lists = indexPrAnalysisNodes(affected.slice(0, limit), untested.slice(0, limit), risk.data.tests.slice(0, limit));
+    ctx.progress("Done", 3, 3);
+    const restOfReportData = {
+        ...identity,
+        files,
+        missing,
+        changedSymbols,
+        symbolsInChangedFiles: nodes.length,
+        affectedTotal: affected.length,
+        untestedTotal: untested.length,
+        testsTotal: risk.data.tests.length,
+    };
+    return {
+        result: {
+            ...risk,
+            data: { ...restOfReportData, ...lists },
+            notes: [...risk.notes, ...notes],
+        },
+        ...(affected.length === 0 ? { state: "empty" } : {}),
+        nameLevel: true,
+        fitToBudget: (budgetBytes) => fitPrAnalysis(restOfReportData, lists.affected, lists.untested, lists.tests, lists.nodes, budgetBytes),
+        headline: `Across ${subject}: ${changedSymbols} changed symbol(s)` +
+            (nodes.length > changedSymbols
+                ? ` (${nodes.length - changedSymbols} more live in the ${files.length} touched file(s) without being touched themselves)`
+                : "") +
+            ` affect ${affected.length} other node(s). ${risk.data.tests.length} test(s) cover part of ` +
+            `that; ${untested.length} affected node(s) have no covering test in the graph.`,
+    };
+}
+export const prAnalysisTool = {
+    name: "pr_analysis",
+    class: "read",
+    tier: "evidence",
+    // 2.0.0, not 1.0.1: the three node lists became id lists into a single
+    // `nodes` map. Nothing was added or removed from the answer, but a caller
+    // that read `affected[0].name` reads `nodes[affected[0].id].name` now, and
+    // a version that did not say so would be a silent break.
+    version: "2.0.0",
+    title: "What this change affects, and what is not covered",
+    description: "Diffs a branch against its merge base, computes blast radius, and splits it into tested " +
+        "and untested reach. The uncovered list is the point — a passing suite says nothing about it.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=pr-analysis.js.map

package/dist/tools/pr-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-analysis.js","sourceRoot":"","sources":["../../src/tools/pr-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EACL,eAAe,EACf,UAAU,EACV,OAAO,EACP,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,cAAc,GAGf,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,MAAM,EACN,SAAS,EACT,YAAY,EACZ,eAAe,EACf,cAAc,EACd,cAAc,EACd,cAAc,GAIf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAsD3C;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAqG,EACrG,QAAkC,EAClC,KAA+B;IAE/B,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAG,CAAC,IAAmB,EAAU,EAAE;QAC/C,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,cAAc,CACtB,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACvB,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;YACxB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACrC,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC,CAAC,CACJ;QACD,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC;QAChC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC1B,KAAK;KACN,CAAC;AACJ,CAAC;AAqGD;;;;;;;;;GASG;AACH,SAAS,aAAa,CACpB,IAAyE,EACzE,YAAoC,EACpC,WAA8B,EAC9B,OAA0B,EAC1B,KAA0C,EAC1C,WAAmB;IAEnB,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,CACrC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EAC7E,MAAM,CACP,CAAC;IACF,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,aAAa,EAAE,CAAC,CAAC,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAU,EAAE;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,CAAC,CAAC;QACvD,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7G,CAAC,CAAC;IAEF,SAAS,IAAI,CAAI,KAAmB,EAAE,IAAyB;QAC7D,MAAM,KAAK,GAAQ,EAAE,CAAC;QACtB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;YACtB,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;YAChF,IAAI,IAAI,GAAG,MAAM;gBAAE,MAAM;YACzB,MAAM,IAAI,IAAI,CAAC;YACf,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAE3C,MAAM,WAAW,GAA8B,EAAE,CAAC;IAClD,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS;YAAE,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACjD,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,WAAW,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/G,CAAC;IACD,IAAI,WAAW,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9G,CAAC;IACD,IAAI,QAAQ,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACpG,CAAC;IAED,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IAChF,OAAO;QACL,IAAI,EAAE;YACJ,GAAG,IAAI;YACP,QAAQ,EAAE,WAAW,CAAC,KAAK;YAC3B,QAAQ,EAAE,WAAW,CAAC,KAAK;YAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,KAAK,EAAE,WAAW;SACnB;QACD,KAAK;QACL,GAAG,CAAC,UAAU,KAAK,CAAC;YAClB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,eAAe,EAAE;oBACf,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM;oBAClF,KAAK,EAAE,YAAY,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM;oBAChE,IAAI,EAAE,IAAI;iBACX;aACF,CAAC;KACP,CAAC;AACJ,CAAC;AAED;sFACsF;AACtF,SAAS,gBAAgB,CAAC,KAA6B;IACrD,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACjG,CAAC;AAED;;mEAEmE;AACnE,SAAS,gBAAgB,CAAC,IAAY,EAAE,WAA6D;IACnG,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC5D,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC1D,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAM,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,KAAM,CAAC,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;AAC9F,CAAC;AAED,MAAM,QAAQ,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,CAAU,CAAC;AAExD,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,sFAAsF;SACpG;QACD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uCAAuC,EAAE;QAC9E,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAC;YACnC,WAAW,EAAE,mEAAmE;SACjF;QACD,gBAAgB,EAAE;YAChB,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,6DAA6D;SAC3E;QACD,OAAO,EAAE;YACP,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC;YACnB,WAAW,EAAE,wCAAwC;SACtD;QACD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,oCAAoC,EAAE;KAC1F;IACD,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAIX,KAAK,UAAU,GAAG,CAChB,IAA6B,EAC7B,GAAgB;IAEhB,0EAA0E;IAC1E,4EAA4E;IAC5E,0EAA0E;IAC1E,oEAAoE;IACpE,uEAAuE;IACvE,oDAAoD;IACpD,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACxD,MAAM,gBAAgB,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,KAAK,CAAC;IAC5D,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACvD,MAAM,IAAI,cAAc,CACtB,4FAA4F;YAC1F,yFAAyF;YACzF,mBAAmB,CACtB,CAAC;IACJ,CAAC;IACD,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACvD,MAAM,IAAI,cAAc,CACtB,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IACD,IAAI,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,cAAc,CAAC,8DAA8D,WAAW,IAAI,CAAC,CAAC;IAC1G,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,WAAW,IAAI,KAAK,CAAkC,CAAC;IACtE,MAAM,IAAI,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAE,cAAwB,CAAC,CAAC,CAAE,OAAiB,CAAC;IACpF,MAAM,IAAI,GAAG,OAAO,IAAI,IAAI,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC;IAC3E,MAAM,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,qBAAqB,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,IAAI,EAAE,CAAC;IACpF,4EAA4E;IAC5E,MAAM,QAAQ,GAAG;QACf,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;IACF,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC;IAChE,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC;IAE7C,GAAG,CAAC,QAAQ,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC;IACnC,IAAI,SAAiC,CAAC;IACtC,IAAI,CAAC;QACH,SAAS;YACP,IAAI,KAAK,IAAI;gBACX,CAAC,CAAC,CACE,MAAM,oBAAoB,CAAC,OAAO,CAAC,QAAQ,EAAE;oBAC3C,KAAK;oBACL,gBAAgB;oBAChB,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC9C,CAAC,CACH,CAAC,KAAK;gBACT,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAK,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,MAAM,CAAiB;YAC5B,QAAQ,EAAE,kBAAkB,OAAO,GAAG;YACtC,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,CAAC;YAClB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,KAAK,EAAE;gBACL,CAAC,IAAI,KAAK,IAAI;oBACZ,CAAC,CAAC,uCAAwC,KAAe,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG;oBAC3E,CAAC,CAAC,2BAA4B,KAAe,CAAC,OAAO,CAAC,IAAI,EAAE,iBAAiB,IAAI,IAAI;wBACnF,yEAAyE,CAAC;aAC/E;YACD,IAAI,EAAE,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;SACjC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,WAAW,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAEhD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,MAAM,CAAiB;YAC5B,QAAQ,EAAE,GAAG,OAAO,oBAAoB;YACxC,SAAS,EAAE,IAAI;YACf,0EAA0E;YAC1E,wEAAwE;YACxE,wEAAwE;YACxE,0EAA0E;YAC1E,wEAAwE;YACxE,eAAe,EAAE,CAAC;YAClB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,KAAK,EAAE,CAAC,6DAA6D,CAAC;YACtE,IAAI,EAAE,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;SACnF,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,QAAQ,CAAC,aAAa,KAAK,CAAC,MAAM,kBAAkB,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAChE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACvE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CACR,GAAG,OAAO,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,6CAA6C;YAC/E,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,sBAAsB;YAC1F,wFAAwF;YACxF,6DAA6D,CAChE,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,MAAM,CAAiB;YAC5B,QAAQ,EAAE,eAAe,KAAK,CAAC,MAAM,uBAAuB,OAAO,oBAAoB;YACvF,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,CAAC;YAClB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,KAAK,EAAE;gBACL,GAAG,KAAK;gBACR,0FAA0F;oBACxF,iDAAiD;aACpD;YACD,IAAI,EAAE,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;SACxF,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,QAAQ,CAAC,aAAa,KAAK,CAAC,MAAM,oBAAoB,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClE,+EAA+E;IAC/E,2EAA2E;IAC3E,2EAA2E;IAC3E,iCAAiC;IACjC,EAAE;IACF,4EAA4E;IAC5E,wEAAwE;IACxE,yEAAyE;IACzE,yEAAyE;IACzE,4EAA4E;IAC5E,+DAA+D;IAC/D,MAAM,IAAI,GAAG,UAAU,CACrB,OAAO,CAAC,QAAQ,EAAE,EAClB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACtB,EAAE,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAClC,CAAC;IAEF,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC;IACpF,KAAK,CAAC,IAAI,CACR,6FAA6F;QAC3F,4FAA4F;QAC5F,uBAAuB,EACzB,8FAA8F;QAC5F,mCAAmC,KAAK,CAAC,MAAM,0CAA0C;QACzF,4FAA4F;QAC5F,6FAA6F;QAC7F,yCAAyC,CAC5C,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IAEvF,0EAA0E;IAC1E,4EAA4E;IAC5E,kBAAkB;IAClB,MAAM,KAAK,GAAG,oBAAoB,CAChC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EACxB,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EACxB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAChC,CAAC;IAEF,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B,MAAM,gBAAgB,GAAG;QACvB,GAAG,QAAQ;QACX,KAAK;QACL,OAAO;QACP,cAAc;QACd,qBAAqB,EAAE,KAAK,CAAC,MAAM;QACnC,aAAa,EAAE,QAAQ,CAAC,MAAM;QAC9B,aAAa,EAAE,QAAQ,CAAC,MAAM;QAC9B,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM;KACnC,CAAC;IACF,OAAO;QACL,MAAM,EAAE;YACN,GAAG,IAAI;YACP,IAAI,EAAE,EAAE,GAAG,gBAAgB,EAAE,GAAG,KAAK,EAAE;YACvC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC;SACjC;QACD,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,CAAC,WAAmB,EAAE,EAAE,CACnC,aAAa,CAAC,gBAAgB,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC;QACxG,QAAQ,EACN,UAAU,OAAO,KAAK,cAAc,oBAAoB;YACxD,CAAC,KAAK,CAAC,MAAM,GAAG,cAAc;gBAC5B,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,cAAc,qBAAqB,KAAK,CAAC,MAAM,oDAAoD;gBACzH,CAAC,CAAC,EAAE,CAAC;YACP,WAAW,QAAQ,CAAC,MAAM,mBAAmB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,yBAAyB;YAC5F,SAAS,QAAQ,CAAC,MAAM,uDAAuD;KAClF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,IAAI,EAAE,aAAa;IACnB,KAAK,EAAE,MAAM;IACb,IAAI,EAAE,UAAU;IAChB,uEAAuE;IACvE,0EAA0E;IAC1E,2EAA2E;IAC3E,yDAAyD;IACzD,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,mDAAmD;IAC1D,WAAW,EACT,0FAA0F;QAC1F,8FAA8F;IAChG,WAAW,EAAE,MAA4C;IACzD,GAAG;CACJ,CAAC"}

package/dist/tools/pre-push.d.ts

@@ -0,0 +1,168 @@
+/**
+ * `pre_push` — one call where a developer about to push would otherwise make four.
+ *
+ * The UAT's own verdict was that in agentic use the gap is composition, not
+ * correctness: `scope`, `pr_analysis`, `contracts` and `validate` each answer
+ * well, and nothing puts them together at the moment someone actually wants
+ * them together. This is that composition, under the tightest budget the
+ * scoping tiers define.
+ *
+ * ## What "under the pre-push tier" actually means, per constituent
+ *
+ * The plan this comes from said the tier was "honoured by `scope`, `pr_analysis`
+ * and `contracts`". Two of those are true and the third is not, and the
+ * difference decides what this tool can pass down:
+ *
+ * - `scope` and `pr_analysis` take a `trigger`, and apply
+ *   `NODE_BUDGETS["pre-push"]` (200 nodes) to their traversal. Passed straight
+ *   through.
+ * - `contracts` has **no `trigger` and no node budget**, because it does not
+ *   traverse — it compares every endpoint in the graph. Its expensive half is
+ *   the shape comparison, and its own schema already names the answer:
+ *   `pathsOnly` is "the honest choice for a pre-push run". So that is what the
+ *   tier means here, and this tool sets it.
+ * - `validate` has no traversal budget either; it is bounded by `maxFindings`,
+ *   which this tool tightens rather than leaving at its default 25.
+ *
+ * ## Why findings are grouped by source and not merged into one ranking
+ *
+ * A single global ranking would need to say that a contract mismatch outranks
+ * an unset environment variable, or the reverse. Descry has no model that
+ * supports either claim, and inventing one would be a judgement presented as a
+ * measurement — the same reason `contracts` ranks by evidence strength rather
+ * than severity. So each source contributes its own top few, and the envelope
+ * says plainly that the sources are not ranked against each other.
+ *
+ * That is still one call, one envelope, and a short read. It just does not
+ * pretend to a comparison nobody has made.
+ *
+ * ## Blocking versus informational
+ *
+ * `blockingTotal` counts `contracts` and `validate` findings only, and — since
+ * UAT round 3, Suggestion 6 — only the ones each tool's own `claim` field
+ * marks a `defect`. `scope` and `pr_analysis` answer "what does this change
+ * touch" — real, useful, and not a defect, so counting them would make every
+ * change with a blast radius look like a failure. A `lead` (`ROUTE_NOT_CALLED`,
+ * `SET_BUT_UNDOCUMENTED`) is worth a look but is not provable from the graph
+ * alone, so it is counted separately in `leadTotal` rather than folded into
+ * the number a git hook branches on. `descry check` exits non-zero on
+ * `blockingTotal`, which is why the line has to be drawn here rather than
+ * left to the caller.
+ *
+ * ## Scoped to what you are pushing
+ *
+ * UAT round 3, B11. `contracts` did not receive the `files` this tool was
+ * called with, so `blockingTotal` counted the repository's entire standing
+ * backlog rather than the change being pushed — 15 pre-existing
+ * `ROUTE_NOT_CALLED` findings for unrelated paths, on a push touching three
+ * unrelated files. `contracts` now takes the same `files` this tool was
+ * given (it already accepted `paths`, a different axis — a URL template
+ * substring, not a source file), so both blocking sources answer about the
+ * files in front of the developer. `validate` already took `files`; only the
+ * threading into `contracts` was missing.
+ *
+ * ## Class and tier
+ *
+ * `read` — it runs four read tools and writes nothing. `evidence` — it reports
+ * what those four found and draws no conclusion of its own.
+ */
+import { type ToolDefinition } from "./kit.ts";
+export type PrePushSource = "scope" | "pr_analysis" | "contracts" | "validate";
+export interface PrePushSection {
+    readonly source: PrePushSource;
+    /** `ok`, `empty`, `refused`, `failed` — this constituent's own state, never flattened away. */
+    readonly state: string;
+    /** How many items this source found in total, before this tool took its top few. */
+    readonly total: number;
+    /** The top few, in the order that source reported them. */
+    readonly shown: readonly unknown[];
+    /**
+     * True when this source is **the kind that claims something is wrong** —
+     * a property of the source, not of what it found this time.
+     *
+     * **It was called `blocking`, sitting beside a `blockingTotal` that means the
+     * other thing.** `contracts` can be `blocking: true` with `total: 0`, and
+     * `validate` `blocking: true` with ten leads and a `blockingTotal` of zero,
+     * so the obvious consumer arithmetic — sum `total` over the blocking
+     * sections — is wrong in both directions. This tool's own test suite made
+     * exactly that mistake and passed, because the fixture happened to produce no
+     * leads.
+     *
+     * The name now says which question it answers. The other question — *did this
+     * section find anything that blocks?* — is `defects > 0`, and there is no
+     * longer a field whose name suggests it answers both.
+     */
+    readonly claimsFaults: boolean;
+    /** Of `total`, how many assert a fault. Zero for a source that claims none. */
+    readonly defects: number;
+    /** Of `total`, how many are worth a look without asserting one. */
+    readonly leads: number;
+    /** This source's own headline, kept verbatim. */
+    readonly headline: string;
+}
+/**
+ * Which change set the coverage section actually described.
+ *
+ * `pr_analysis` derives its own file list from `base...head` and takes none,
+ * deliberately. Three constituents therefore describe the files passed and one
+ * describes the branch's committed diff, and in a real run those were 2 files
+ * and 25. Both answers were right; presented side by side under one headline
+ * they read as one answer about one change.
+ *
+ * The disclosure explaining that has always been in the reply. It sat below a
+ * headline and a section total that both read as though they described the
+ * files passed, which is the wrong order for the most common working moment:
+ * before a commit, when the git-derived half can see none of the work.
+ */
+export interface PrePushCoverage {
+    /**
+     * What `pr_analysis` answered about: a ref-to-ref diff (`base...head`) when
+     * `base` was given, or the working tree (with its scope) when `workingTree`
+     * was given instead. Whichever it is, it is not necessarily the file list
+     * this tool itself was called with — see `filesOutsideDiff`.
+     */
+    readonly describes: string;
+    /** Files passed that the base diff does not contain — whatever the reason. */
+    readonly filesOutsideDiff: readonly string[];
+    /**
+     * Of those, the ones git reports as modified, staged or untracked.
+     *
+     * Separated because "not in the diff" has two causes and only one is about
+     * timing: uncommitted work the developer can commit, versus a file they named
+     * that this branch never touched.
+     */
+    readonly uncommitted: readonly string[];
+}
+export interface PrePushData {
+    readonly files: readonly string[];
+    readonly sections: readonly PrePushSection[];
+    /**
+     * Contract and environment findings that **assert a fault**.
+     *
+     * The doctrine that keeps `scope` and `pr_analysis` out of this number is the
+     * same one that keeps a lead out of it: a change with a large blast radius is
+     * not a broken change, and neither is a route no code in this graph calls.
+     * Both constituents already knew which of their findings claimed a fault —
+     * `validate` in a field, `contracts` in the prose of the finding itself — and
+     * this composite flattened them into one count a git hook exits on.
+     *
+     * "15 blocking findings" and "1 defect, 15 leads" are different sentences and
+     * only one is worth acting on. A check that cries wolf is worse than no
+     * check, because it also discredits the real findings underneath it.
+     */
+    readonly blockingTotal: number;
+    /** Findings worth a look that assert nothing. Reported, never exited on. */
+    readonly leadTotal: number;
+    /** The node budget actually applied to the traversing constituents. */
+    readonly nodeBudget: number;
+    /**
+     * What the coverage section was about, when one ran.
+     *
+     * `null` when neither `base` nor `workingTree` was given: `pr_analysis` is
+     * skipped entirely then, and a caveat about a section that did not run is a
+     * caveat about nothing.
+     */
+    readonly coverage: PrePushCoverage | null;
+}
+export declare const prePushTool: ToolDefinition;
+//# sourceMappingURL=pre-push.d.ts.map

package/dist/tools/pre-push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pre-push.d.ts","sourceRoot":"","sources":["../../src/tools/pre-push.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAKH,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAyDlB,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAE/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAC3C;AAmWD,eAAO,MAAM,WAAW,EAAE,cAiBzB,CAAC"}