@descryy/mcp 0.11.5 → 0.11.7

package/dist/tools/contracts.js

@@ -0,0 +1,214 @@
+/**
+ * `contracts` — path half (name-level, R2→A) runs today; shape half (§13)
+ * needs producer-attached shapes, reporting `refused` with named blockers
+ * rather than an empty list. `defect` is provable here alone; `lead` is not.
+ */
+import { checkContracts, withProminence } from "@descryy/core";
+import { briefNode, optionalInteger, optionalStringArray, } from "./kit.js";
+import { capBySize, sizeCapNote } from "../capped.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Restrict to endpoints whose path contains one of these substrings, e.g. \"/orders\".",
+        },
+        files: {
+            type: "array",
+            items: { type: "string" },
+            description: "Restrict to findings touching these files — e.g. a diff about to be pushed.",
+        },
+        pathsOnly: {
+            type: "boolean",
+            description: "Skip the shape comparison. Faster; honest when there's no type checker.",
+        },
+        maxFindings: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap on findings. Default 25; overflow disclosed, not dropped.",
+        },
+    },
+    additionalProperties: false,
+};
+/** True when at least one of `nodes` has a `file` in `scope`. No scope given means every node passes. */
+function touchesFiles(nodes, scope) {
+    return scope === undefined || nodes.some((n) => n.file !== null && scope.includes(n.file));
+}
+function fitContracts(rest, findings, shapeMismatches, budgetBytes) {
+    const scaffoldBytes = Buffer.byteLength(JSON.stringify({ ...rest, findings: [], shapeMismatches: [] }), "utf8");
+    let budget = Math.max(budgetBytes - scaffoldBytes, 0);
+    const findingsFit = capBySize(findings, budget, 0);
+    budget = Math.max(budget - Buffer.byteLength(JSON.stringify(findingsFit.shown), "utf8"), 0);
+    const mismatchesFit = capBySize(shapeMismatches, budget, 0);
+    const notes = [];
+    if (findingsFit.droppedForSize > 0) {
+        notes.push(sizeCapNote("finding", findingsFit.shown.length, findings.length, findingsFit.droppedForSize));
+    }
+    if (mismatchesFit.droppedForSize > 0) {
+        notes.push(sizeCapNote("shape mismatch", mismatchesFit.shown.length, shapeMismatches.length, mismatchesFit.droppedForSize));
+    }
+    const droppedNow = findingsFit.droppedForSize + mismatchesFit.droppedForSize;
+    const shownNow = findingsFit.shown.length + mismatchesFit.shown.length;
+    const preFitTotal = findings.length + shapeMismatches.length;
+    return {
+        data: { ...rest, findings: findingsFit.shown, shapeMismatches: mismatchesFit.shown },
+        notes,
+        ...(droppedNow === 0 ? {} : { truncatedDetail: { shown: shownNow, total: preFitTotal, more: null } }),
+    };
+}
+async function run(args, ctx) {
+    const filters = optionalStringArray(args, "paths");
+    const fileScope = optionalStringArray(args, "files");
+    const maxFindings = optionalInteger(args, "maxFindings", 1);
+    const pathsOnly = args["pathsOnly"] === true;
+    const provider = ctx.session.provider();
+    ctx.progress("Matching callers against routes");
+    const checked = checkContracts(provider, {
+        ...(maxFindings === undefined ? {} : { maxFindings }),
+        ...(pathsOnly ? { pathsOnly: true } : {}),
+    });
+    const { paths, shapes } = checked.data;
+    const notes = [...checked.notes];
+    // Filtering happens after the check so the counts describe the whole graph
+    // — a shrinking denominator would make a narrow query look healthy.
+    const matchesPath = (template) => filters === undefined || filters.some((f) => template.includes(f));
+    const findings = paths.findings.filter((f) => matchesPath(f.pathTemplate) && touchesFiles([...f.callers, ...f.routes], fileScope));
+    const mismatches = shapes.mismatches.filter((m) => matchesPath(String(m.endpoint.attrs["pathTemplate"] ?? m.endpoint.name)) &&
+        touchesFiles([m.reader, m.writer], fileScope));
+    if (filters !== undefined) {
+        notes.push(`Filtered to endpoints matching ${filters.map((f) => `"${f}"`).join(", ")}. The counts ` +
+            "below describe the whole graph; the lists describe the filter.");
+    }
+    if (fileScope !== undefined) {
+        notes.push(`Filtered to findings touching ${fileScope.length} named file(s). The counts below describe ` +
+            "the whole graph; the lists describe the filter.");
+    }
+    // A `paths` filter matching zero endpoints means it named something never
+    // parsed as a route/endpoint — a different claim than "checked, fine."
+    // API_ROUTE is checked too: an unmounted route has no API_ENDPOINT at all.
+    let pathsMatchedNothing = false;
+    if (filters !== undefined) {
+        const endpoints = provider.nodesOfType("API_ENDPOINT");
+        const routes = provider.nodesOfType("API_ROUTE");
+        const matched = (n) => matchesPath(String(n.attrs["pathTemplate"] ?? n.name));
+        pathsMatchedNothing = !endpoints.nodes.some(matched) && !routes.nodes.some(matched);
+    }
+    const defects = findings.filter((f) => f.claim === "defect").length + mismatches.length;
+    const leads = findings.filter((f) => f.claim === "lead").length;
+    if (findings.length > 0) {
+        notes.push("findings are ranked by evidence strength — their own resolution, strongest first — not by " +
+            "claim. A call reaching no route and a route nothing calls can each rest on strong or weak " +
+            "evidence; which of them is a defect versus a lead is a separate axis (claim), not a ranking.");
+    }
+    // Zero API_ENDPOINT nodes usually means nothing to check — but not when the
+    // mount check found an independent ROUTE_NOT_MOUNTED finding with no
+    // endpoint in the graph; refusing then would bury a real finding.
+    const nothingToCheck = paths.checked.endpoints === 0 && paths.findingsTotal === 0;
+    // MK-7: graded on `claim` — a lead is worth a look; a defect is provable
+    // from this graph alone (`nearMiss` keeps a mere typo out of the count).
+    const verdict = defects > 0
+        ? `${defects} defect(s) found`
+        : leads > 0
+            ? `No defects; ${leads} lead(s) to review`
+            : "Clean at path level";
+    // render.ts refuses a `truncated` answer with no `truncatedDetail`, so this
+    // must be supplied whenever `checked.truncated` is set; `total` is the
+    // whole unfiltered graph, an honest upper bound on `shown`.
+    const truncatedDetail = checked.truncated
+        ? { shown: findings.length, total: Math.max(paths.findingsTotal, findings.length), more: null }
+        : undefined;
+    const shapedFindings = withProminence(
+    // Sorted before ranking, because `withProminence` deliberately does
+    // not sort: rank must follow the order the reply actually reports.
+    // Ties keep the checker's own order, which is stable.
+    [...findings]
+        .sort((a, b) => b.resolution - a.resolution)
+        .map((f) => ({
+        kind: f.kind,
+        // Whether this asserts a fault. Carried as a field because the
+        // sentence below already said it and nothing could read prose.
+        claim: f.claim,
+        method: f.method,
+        path: f.pathTemplate,
+        detail: f.detail,
+        resolution: f.resolution,
+        ...(f.nearMiss === null
+            ? {}
+            : { nearMiss: { kind: f.nearMiss.kind, against: f.nearMiss.against } }),
+        callers: f.callers.slice(0, 5).map(briefNode),
+        routes: f.routes.slice(0, 5).map(briefNode),
+    })));
+    const shapedMismatches = mismatches.map((m) => ({
+        endpoint: m.endpoint.name,
+        direction: m.direction,
+        reader: briefNode(m.reader),
+        writer: briefNode(m.writer),
+        differences: m.differences,
+        resolution: m.resolution,
+        // A field the reading side needs and the writing side does not
+        // supply. There is no benign reading of that, so every mismatch is a
+        // fault claim — unlike an uncalled route, whose usual explanation is
+        // a consumer outside the graph.
+        claim: m.claim,
+    }));
+    const restOfData = {
+        checked: paths.checked,
+        shapes: {
+            ran: shapes.ran,
+            comparable: shapes.comparable,
+            consumerOnly: shapes.consumerOnly,
+            providerOnly: shapes.providerOnly,
+            unroledDtos: shapes.unroledDtos,
+            blockers: shapes.blockers,
+        },
+        unmatchedWithoutNearMiss: paths.unmatchedWithoutNearMiss,
+        defects,
+        leads,
+    };
+    return {
+        result: {
+            ...checked,
+            data: { ...restOfData, findings: shapedFindings, shapeMismatches: shapedMismatches },
+            notes: pathsMatchedNothing
+                ? [
+                    `0 endpoint(s) matched ${(filters ?? []).map((f) => `"${f}"`).join(", ")}. Nothing in ` +
+                        "this graph was parsed as a route or endpoint under that filter, so there is nothing " +
+                        "for \"clean\" to describe — this is not a statement about whether the endpoint you " +
+                        "meant is correct.",
+                    ...notes,
+                ]
+                : notes,
+        },
+        // A path finding is a name-level claim (R2 fully supports); a shape
+        // mismatch is not — `engine.ts` caps each individually. This flags the
+        // answer's own headline claim, the path half.
+        nameLevel: true,
+        ...(truncatedDetail === undefined ? {} : { truncatedDetail }),
+        ...(nothingToCheck
+            ? { state: "refused" }
+            : pathsMatchedNothing
+                ? { state: "empty" }
+                : {}),
+        fitToBudget: (budgetBytes) => fitContracts(restOfData, shapedFindings, shapedMismatches, budgetBytes),
+        headline: nothingToCheck
+            ? "No API endpoints are in the graph, so there is no contract to check."
+            : pathsMatchedNothing
+                ? `0 endpoint(s) matched this filter. Not checked, not clean.`
+                : `${verdict}. ${paths.checked.joined} of ${paths.checked.endpoints} endpoint(s) have both ` +
+                    `a caller and a route${shapes.ran ? "" : "; request and response shapes were not compared"}.`,
+    };
+}
+export const contractsTool = {
+    name: "contracts",
+    class: "read",
+    tier: "conclusion",
+    version: "1.0.0",
+    title: "Frontend/backend contract mismatches",
+    description: "Match every API caller against its route. Reports calls that reach no route, routes " +
+        "nothing calls, and fields one side reads that the other doesn't send. Shape comparison " +
+        "needs type info; reported not-run otherwise. States a verdict.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=contracts.js.map

package/dist/tools/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/tools/contracts.ts"],"names":[],"mappings":"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"}

package/dist/tools/cross-pr.d.ts

@@ -0,0 +1,178 @@
+/**
+ * `cross-pr` — "what does this change collide with, that reading the diff alone
+ * would not show?"
+ *
+ * §14's multi-PR engine, at the protocol level. Four checks exist behind it,
+ * for a reason worth stating rather than discovering: a check is available
+ * exactly when something already produces its input.
+ *
+ * | check | § | input | today |
+ * | --- | --- | --- | --- |
+ * | hidden dependency | 14.8 | `CHANGES_WITH` edges, already in the graph | **runs** |
+ * | overlap scoring | 14.3 | stored PR scopes | **runs, over whatever is stored** |
+ * | superseded | 14.5 | git blob ids at head and at base's tip | **runs** |
+ * | migration heads | 14.6 | base's and head's migration files, read directly from git | **runs** |
+ *
+ * §14.8 is first because it is the one that costs nothing: the edges already
+ * exist, it needs no per-PR storage, and it works at R0 in any language with no
+ * adapter beyond file paths. For a repository whose language has no adapter at
+ * all, this is the check that still fires.
+ *
+ * **Migration heads answers the diff-precise question this section once said
+ * was out of scope for an MCP tool call** — `readMigrationsAcrossChange`
+ * (`sources/migrations/across-change.ts`) reads base's and head's migration
+ * files directly with `git ls-tree`/`git show`, so it needs no language
+ * adapter and no re-resolution of the graph against two commits. `ran` is
+ * false only when neither side has a migration format this producer
+ * recognises — never because a producer has not run yet.
+ *
+ * ## Why a check that still cannot run is declared rather than omitted
+ *
+ * `contracts.ts` set this precedent and the reasoning transfers unchanged: a
+ * tool that silently offers three of four checks lets a caller read "nothing
+ * found" as "nothing there". A blocked check names the producer it is
+ * waiting for, so the gap is actionable rather than mysterious.
+ *
+ * ## Everything here is Class C and that is not a defect to be fixed
+ *
+ * Co-change is evidence about **people**, not program structure — a pair that
+ * moved together two hundred times is a stronger hint and is still a hint. The
+ * checks compute their own reliability rather than being told it, and each
+ * finding carries the sentence that must travel with it. A caller rendering
+ * these as defects has broken principle 4 at the last gate. Migration heads is
+ * the one exception worth naming: a genuine fork in the revision chain is
+ * closer to a defect than a hint, but it is left at Class C here too, because
+ * this check cannot yet tell a legitimate two-branch merge-in-progress from an
+ * actual conflict — that distinction is left to the migration-integrity
+ * checks in `validate`, which are provable from the graph alone.
+ */
+import type { DiffType, HiddenDependencyReport, MigrationsAcrossChange, IncomparablePair, NodeVerdict, OverlapFinding, SupersededReport } from "@descryy/core";
+import type { ReliabilityClass } from "@descryy/ir";
+import { type BriefNode, type ToolDefinition } from "./kit.ts";
+/**
+ * A check whose input no producer writes yet.
+ *
+ * Declared rather than omitted, and `needs` says what would have to exist —
+ * a tool silently offering three of four checks lets a caller read "nothing
+ * found" as "nothing there".
+ */
+export interface BlockedCheck {
+    readonly check: string;
+    /** The architecture section that specifies it. */
+    readonly section: string;
+    readonly question: string;
+    readonly needs: string;
+}
+/**
+ * A file that historically moves with the change and was not touched this time.
+ *
+ * Class C, always, and `disclosure` is the sentence that must travel with it:
+ * co-change is evidence about **people**, not program structure. A caller
+ * rendering this as a defect has broken principle 4 at the last gate.
+ */
+export interface HiddenDependencyFinding extends BriefNode {
+    readonly coupledTo: readonly {
+        readonly file: string | null;
+        readonly support: number;
+    }[];
+    readonly strongestSupport: number;
+    readonly reliability: ReliabilityClass;
+    readonly disclosure: string;
+}
+export interface HiddenDependencyCheck {
+    /** False when no changed file had a single CHANGES_WITH edge: the history was not read. */
+    readonly ran: boolean;
+    readonly findings: readonly HiddenDependencyFinding[];
+    /** The count before `limit` capped it — P27's disclosed remainder (§4 technique 5). */
+    readonly findingsTotal: number;
+    readonly checked: HiddenDependencyReport["checked"];
+    /** Changed paths with no FILE node. Nothing looked at them. */
+    readonly unresolvedChanged: readonly string[];
+}
+export interface OverlapCheck {
+    /** False when fewer than two stored scopes exist: no pair could be compared. */
+    readonly ran: boolean;
+    readonly scopesCompared: number;
+    readonly findings: readonly OverlapFinding[];
+    /** The count before `limit` capped it — P27's disclosed remainder (§4 technique 5). */
+    readonly findingsTotal: number;
+    /** Pairs refused before comparison. An incomparable pair and a clean pair look identical otherwise. */
+    readonly incomparable: readonly IncomparablePair[];
+    readonly checked: OverlapReportChecked;
+}
+/** Named separately because `OverlapReport` itself is not re-exported field by field. */
+export type OverlapReportChecked = {
+    readonly scopes: number;
+    readonly pairs: number;
+    readonly pairsOverlapping: number;
+    readonly belowThreshold: number;
+    readonly incomparable: number;
+};
+export interface SupersededCheck {
+    /** False when there was nothing to compare — not the same as "not superseded". */
+    readonly ran: boolean;
+    readonly verdict: boolean;
+    readonly counts: SupersededReport["counts"];
+    readonly reliability: ReliabilityClass;
+    readonly disclosure: string;
+    /** Everything not already on base, so a reader sees what is left rather than what matched. */
+    readonly remaining: readonly {
+        /** Undefined for a comparison whose candidate carried no path. */
+        readonly file: string | undefined;
+        readonly diffType: DiffType;
+        readonly verdict: NodeVerdict;
+    }[];
+}
+/** git rejected the range: no diff-dependent check ran, and `blocked` is all there is to say. */
+export interface CrossPrGitFailure {
+    readonly blocked: readonly BlockedCheck[];
+    readonly migrationHeads: MigrationHeadCheck;
+}
+/** The diff is empty. A real answer: there is nothing to collide with. */
+export interface CrossPrEmptyDiff extends CrossPrGitFailure {
+    readonly changedFiles: number;
+}
+/**
+ * §14.6 — the heads this merge would leave.
+ *
+ * The set is base's migrations plus this change's, because that is the set the
+ * migration runner sees after the merge. `ran` is false when neither side had a
+ * migration format this producer recognises, which is **not** the same as a
+ * clean answer: a repository whose framework declares no DAG cannot have this
+ * failure at all, and one whose files were unreadable simply was not read.
+ */
+export interface MigrationHeadCheck {
+    readonly ran: boolean;
+    /** Base's single head, or null when base has none or already forks. */
+    readonly baseHead: string | null;
+    /** At most one — either the merged set has a single head or it does not. */
+    readonly conflict: MigrationsAcrossChange["report"]["conflict"];
+    readonly dependencies: MigrationsAcrossChange["report"]["dependencies"];
+    readonly duplicateRevisions: MigrationsAcrossChange["report"]["duplicateRevisions"];
+    /** False when any parent list could not be read, so the DAG read is partial. */
+    readonly complete: boolean;
+    readonly checked: MigrationsAcrossChange["report"]["checked"];
+    /** Files declined, with the reason recorded rather than guessed. */
+    readonly refused: readonly {
+        file: string;
+        reason: string;
+    }[];
+    /**
+     * Well-formed migrations sitting where no migration tool looks.
+     *
+     * Reported separately from the head computation because they are not in it —
+     * the runner cannot see them either, so "the merge leaves one head" can be
+     * true and incomplete in the same breath.
+     */
+    readonly misplaced: MigrationsAcrossChange["misplaced"];
+}
+export interface CrossPrReport extends CrossPrEmptyDiff {
+    readonly resolvedNodes: number;
+    readonly hiddenDependencies: HiddenDependencyCheck;
+    readonly overlaps: OverlapCheck;
+    readonly superseded: SupersededCheck;
+    readonly migrationHeads: MigrationHeadCheck;
+}
+export type CrossPrData = CrossPrGitFailure | CrossPrEmptyDiff | CrossPrReport;
+export declare const crossPrTool: ToolDefinition;
+//# sourceMappingURL=cross-pr.d.ts.map

package/dist/tools/cross-pr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-pr.d.ts","sourceRoot":"","sources":["../../src/tools/cross-pr.ts"],"names":[],"mappings":"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"}