@descryy/mcp 0.11.5 → 0.11.6

package/dist/tools/similar-incidents.js

@@ -0,0 +1,190 @@
+/** `similar_incidents` ranks existing `INCIDENT` nodes against a failure with no graph node yet,
+ *  deterministically (file/token Jaccard, no vector store). DEC-274 found zero `INCIDENT` nodes
+ *  across three repos (734/459/203 commits): recall is 0/0, not 0% — an empty result never means
+ *  "no similar incident exists" (DEC-279). §1.3a: a zero-incident graph is `refused`, never `empty`
+ *  — the same split `contracts` and `propagation` apply to their own zero-population case. */
+import { similarIncidents } from "@descryy/core";
+import { answer, briefNode, optionalInteger, optionalString, optionalStringArray, ToolInputError, } from "./kit.js";
+import { capBySize, sizeCapNote } from "../capped.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        touchedFiles: {
+            type: "array",
+            items: { type: "string" },
+            description: "Paths the failure touched — a stack trace, a failing test's imports, or a diff.",
+        },
+        errorMessage: {
+            type: "string",
+            description: "The failure's error or exception text.",
+        },
+        minScore: {
+            type: "number",
+            minimum: 0,
+            maximum: 1,
+            description: "Drop candidates scoring below this. Default 0 (any signal returned, ranked).",
+        },
+        limit: { type: "integer", minimum: 1, description: "Cap on matches in the reply. Default 20." },
+    },
+    additionalProperties: false,
+};
+/** The mandatory disclosure sentence, shaped per branch. Written once here rather than inline at
+ *  three return sites, so no branch can forget it. */
+function recallDisclosure(incidentsInGraph) {
+    return ((incidentsInGraph === 0
+        ? "This graph holds no INCIDENT node at all, so nothing was compared. "
+        : `${incidentsInGraph} INCIDENT node(s) were available to compare against. `) +
+        "Absence is not evidence here, and the reason is measured rather than assumed. An INCIDENT is " +
+        "minted only where somebody declared a failure or a machine witnessed one: a revert (written " +
+        "by git or by hand), a \"Fixes #123\", a service dying during an observed run, or " +
+        "\"mark_incident\". An ordinary fix-forward commit — how most bugs are actually fixed — mints " +
+        "nothing, and the heuristic that would have changed that was built, measured at 25% precision " +
+        "against a 90% threshold, and refused. DEC-274 found zero INCIDENT nodes across three real " +
+        "repositories of 734, 459 and 203 commits. So this matcher's recall is not computable (0/0) " +
+        "rather than 0%, and a failure this repository has genuinely hit before can be absent from " +
+        "these results entirely. The corpus grows fastest through \"mark_incident\": one call, at the " +
+        "moment you already know the answer.");
+}
+/**
+ * `fitToBudget` — `matches` grows with how many incidents the graph holds and
+ * how much text each one's signals carry, unbounded by `limit` alone (a
+ * caller may raise it, and even at the default a graph with thousands of
+ * revert-derived incidents can still overflow). Every match row is already
+ * self-contained, so shrinking means dropping trailing rows only.
+ */
+function fitSimilarIncidents(rest, shownMatches, budgetBytes) {
+    const scaffoldBytes = Buffer.byteLength(JSON.stringify({ ...rest, matches: [] }), "utf8");
+    const fit = capBySize(shownMatches, budgetBytes, scaffoldBytes);
+    const notes = fit.droppedForSize === 0
+        ? []
+        : [sizeCapNote("match", fit.shown.length, shownMatches.length, fit.droppedForSize)];
+    return {
+        data: { ...rest, matches: fit.shown },
+        notes,
+        ...(fit.droppedForSize === 0
+            ? {}
+            : { truncatedDetail: { shown: fit.shown.length, total: rest.matchesTotal, more: null } }),
+    };
+}
+async function run(args, ctx) {
+    const touchedFiles = optionalStringArray(args, "touchedFiles") ?? [];
+    const errorMessage = optionalString(args, "errorMessage");
+    const limit = optionalInteger(args, "limit", 1) ?? 20;
+    const rawMinScore = args["minScore"];
+    if (rawMinScore !== undefined && rawMinScore !== null) {
+        if (typeof rawMinScore !== "number" || rawMinScore < 0 || rawMinScore > 1) {
+            throw new ToolInputError('"minScore" must be a number between 0 and 1');
+        }
+    }
+    const minScore = typeof rawMinScore === "number" ? rawMinScore : undefined;
+    // Describing nothing and being told "0 matches" is the empty-denominator
+    // defect at the input side: the reply would be indistinguishable from a real
+    // search that found nothing.
+    if (touchedFiles.length === 0 && (errorMessage === undefined || errorMessage === "")) {
+        throw new ToolInputError('give at least one of "touchedFiles" or "errorMessage" — with neither, there is nothing to ' +
+            "compare an incident against, and an empty answer would look like a search that ran");
+    }
+    const provider = ctx.session.provider();
+    // The population, read for its own sake. `similarIncidents` scans the same
+    // set internally but returns only what matched, and the count of what did
+    // *not* match is the number this tool's honesty rests on.
+    ctx.progress("Reading the incident population");
+    const population = provider.nodesOfType("INCIDENT");
+    const incidentsInGraph = population.nodes.length;
+    const base = provider.baseStamp();
+    if (incidentsInGraph === 0) {
+        return answer({
+            headline: "No incident is recorded in this graph, so nothing was compared against the failure you " +
+                "described. This is not a finding that the failure is new.",
+            // A refusal, not an empty result — §1.3a. `not_analysable` is the value
+            // today's envelope has for it; §1.1 renames it `refused` in P2.
+            state: "refused",
+            // Whether an incident resembles a failure is a claim about names and
+            // paths, not about shapes — the same class as `history`'s co-change
+            // rows. R0 is the honest floor: an INCIDENT is minted from a commit
+            // log, which is R0 by nature rather than by degradation.
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes: [recallDisclosure(0)],
+            data: {
+                query: { touchedFiles, errorMessage: errorMessage ?? null },
+                matches: [],
+                matchesTotal: 0,
+                incidentsInGraph: 0,
+                analysed: false,
+            },
+        });
+    }
+    ctx.progress(`Ranking ${incidentsInGraph} incident(s) against the failure`);
+    const ranked = similarIncidents(provider, {
+        ...(touchedFiles.length === 0 ? {} : { touchedFiles }),
+        ...(errorMessage === undefined ? {} : { errorMessage }),
+    }, { ...(minScore === undefined ? {} : { minScore }) });
+    const shown = ranked.data.slice(0, limit);
+    const notes = [...ranked.notes, recallDisclosure(incidentsInGraph)];
+    if (shown.length < ranked.data.length) {
+        notes.push(`${ranked.data.length - shown.length} further match(es) scored above the threshold but are ` +
+            `not listed — the reply is capped at ${limit}.`);
+    }
+    if (population.truncated) {
+        notes.push("The incident read was capped, so some INCIDENT nodes were never scored. The counts here " +
+            "are a lower bound.");
+    }
+    const shapedMatches = shown.map((match) => ({
+        incident: briefNode(match.incident),
+        fix: match.fix === null ? null : briefNode(match.fix),
+        // Read off the node rather than inferred from anything about the
+        // match: which mechanism minted an incident is a fact about the
+        // incident, not about how well it scored.
+        detectedVia: typeof match.incident.attrs?.["detectedVia"] === "string"
+            ? match.incident.attrs["detectedVia"]
+            : null,
+        signals: match.signals.map((s) => ({ kind: s.kind, score: Number(s.score.toFixed(4)) })),
+        score: Number(match.combinedScore.toFixed(4)),
+    }));
+    const restOfData = {
+        query: { touchedFiles, errorMessage: errorMessage ?? null },
+        matchesTotal: ranked.data.length,
+        incidentsInGraph,
+        analysed: true,
+    };
+    return {
+        result: {
+            data: { ...restOfData, matches: shapedMatches },
+            stamp: ranked.stamp,
+            truncated: ranked.truncated || shown.length < ranked.data.length || population.truncated,
+            notes,
+        },
+        ...(ranked.data.length === 0 ? { state: "empty" } : {}),
+        ...(shown.length < ranked.data.length
+            ? { truncatedDetail: { shown: shown.length, total: ranked.data.length, more: null } }
+            : {}),
+        nameLevel: true,
+        fitToBudget: (budgetBytes) => fitSimilarIncidents(restOfData, shapedMatches, budgetBytes),
+        headline: ranked.data.length === 0
+            ? `None of the ${incidentsInGraph} incident(s) in this graph share a file or a phrase with ` +
+                "the failure you described. That is a statement about this graph's incident record, not " +
+                "about the failure."
+            : `${ranked.data.length} of ${incidentsInGraph} recorded incident(s) resemble this failure; ` +
+                `closest: ${shown[0].incident.name}` +
+                `${shown[0].fix === null ? "" : ` (fixed by: ${shown[0].fix.name})`}.`,
+    };
+}
+export const similarIncidentsTool = {
+    name: "similar_incidents",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Past incidents that resemble a failure happening now",
+    description: "Rank recorded incidents by resemblance to files touched and/or error text. Use for a " +
+        "failure with no graph node yet; use code_context's impact verb for one linked to an " +
+        "existing symbol. Read-only.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=similar-incidents.js.map

package/dist/tools/similar-incidents.js.map

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

package/dist/tools/validate.d.ts

@@ -0,0 +1,133 @@
+/**
+ * `validate` — §15 static validation: env/config checks.
+ * Omits a var unless its read fails-on-absence AND declaration surface is complete
+ * (18/107 wrong findings measured otherwise); refuses rather than `ok` when no reads
+ * exist. Pass `files` for NEW_READ_UNDECLARED — catches accessor-shape-independent reads.
+ * Add `changedLines` (from get_git_diff's patch) to verify against an added line rather
+ * than a file scope, and get `defect` instead of `lead` back for it — see C2, UAT phase 4. */
+import type { AttributeFinding, AttributeReport, ConfigGraph, ConfigReadSite, EnvClaim, EnvEvidence, EnvFindingKind, EnvReport, MigrationIntegrityFinding, MigrationIntegrityReport, ObservedRouteFinding, OrmRegistrationFinding, OrmRegistrationReport, RollbackFinding, RollbackReport } from "@descryy/core";
+import type { ResolutionLevel } from "@descryy/ir";
+import { type ToolDefinition } from "./kit.ts";
+/** One env/config finding. `claim` distinguishes `defect` (code contradiction) from
+ *  `lead` (worth a look) — conflating them caused 18/107 wrong findings on two repos. */
+export interface EnvFindingReport {
+    readonly kind: EnvFindingKind;
+    readonly name: string;
+    readonly claim: EnvClaim;
+    readonly detail: string;
+    /** Every location the finding rests on. Never empty. */
+    readonly evidence: readonly EnvEvidence[];
+    readonly resolution: ResolutionLevel;
+}
+/** A variable and how much of the repo depends on it (§15.3's third check feeding
+ *  the first). Only variables with a computable dependent set appear — unknown ≠ zero. */
+export interface ConfigDependencyReport {
+    readonly name: string;
+    /** A lower bound, never a total. */
+    readonly dependents: number | null;
+    /** True when the traversal's budget stopped it short. */
+    readonly truncated: boolean;
+    /** Up to three read sites. */
+    readonly readAt: readonly ConfigReadSite[];
+    /** A few dependent files, for a reader who wants to look. */
+    readonly sample: readonly string[];
+}
+export interface ValidateData {
+    readonly findings: readonly EnvFindingReport[];
+    /** The count before `maxFindings` capped it — P27's disclosed remainder (§4 technique 5). */
+    readonly findingsTotal: number;
+    readonly surfaces: EnvReport["surfaces"];
+    readonly reads: EnvReport["reads"];
+    /** Null when no read existed at all, so the coverage guard could not be evaluated. */
+    readonly coverage: EnvReport["coverage"];
+    /** Declared and read nowhere. A dead-configuration lead, not a finding. */
+    readonly declaredNeverRead: number;
+    /** False when no adapter supplied environment reads — otherwise "no missing
+     *  variables" would misstate code that was never read as clean. */
+    readonly readsAvailable: boolean;
+    readonly configGraph: {
+        readonly counts: ConfigGraph["counts"];
+        /** True when the graph carried at least one resolved import edge. */
+        readonly importsAvailable: boolean;
+        /** The ten most-depended-on variables that had a computable dependent set. */
+        readonly mostDependedOn: readonly ConfigDependencyReport[];
+    };
+    readonly rollback: {
+        readonly findings: readonly RollbackFinding[];
+        /** The count before `maxFindings` capped it — P27's disclosed remainder (§4 technique 5). */
+        readonly findingsTotal: number;
+        readonly examined: RollbackReport["examined"];
+        /** Operations this check declined to report, by reason. The size of what it did not say. */
+        readonly withheld: RollbackReport["withheld"];
+        /** False when no source supplied migration operations. */
+        readonly ran: boolean;
+        /** Named in plain words when `ran` is false. */
+        readonly blockers: readonly string[];
+    };
+    /** §"attribute read, type doesn't declare it" — always a defect (graph-provable
+     *  contradiction between two producers), never a lead. */
+    readonly attributeExistence: {
+        readonly findings: readonly AttributeFinding[];
+        readonly findingsTotal: number;
+        readonly examined: AttributeReport["examined"];
+        /** False when no READS edge onto a type-like node carried field-existence info at all. */
+        readonly ran: boolean;
+    };
+    /** §"migration outside its directory, or broken revision chain" — both always
+     *  defects, both graph-provable. */
+    readonly migrationIntegrity: {
+        readonly findings: readonly MigrationIntegrityFinding[];
+        readonly findingsTotal: number;
+        readonly examined: MigrationIntegrityReport["examined"];
+        readonly migrationsDirectory: string | null;
+        /** False when no module in the graph carried migration revision attrs. */
+        readonly ran: boolean;
+        readonly withheld: MigrationIntegrityReport["withheld"];
+    };
+    /** §"ORM model inherits the declarative base but no __init__.py in its package
+     *  reaches its module" — always a lead, never a defect: a model registered by an
+     *  explicit scan rather than by import, or deliberately excluded from migrations,
+     *  triggers this without being a bug. See `orm-registration.ts`'s header. */
+    readonly ormRegistration: {
+        readonly findings: readonly OrmRegistrationFinding[];
+        readonly findingsTotal: number;
+        readonly examined: OrmRegistrationReport["examined"];
+        /** False when no MODEL node in the graph carried an outgoing INHERITS edge. */
+        readonly ran: boolean;
+        readonly withheld: OrmRegistrationReport["withheld"];
+    };
+    /** §"an observed HTTP response against a path no route serves" — UAT phase 5 §5
+     *  (D2). Always a lead: a status code and path alone can never rule out a
+     *  legitimately missing resource. See `@descryy/core`'s `observed-routes.ts`. */
+    readonly observedRoutes: {
+        readonly findings: readonly ObservedRouteFinding[];
+        readonly findingsTotal: number;
+        readonly examined: number;
+        /** False when no evidence database exists yet, or it holds no NETWORK_RESPONSE/
+         *  HTTP_ERROR events — never created here: this is a read tool. */
+        readonly ran: boolean;
+    };
+}
+/** The minimal shape every one of `validate`'s finding sources satisfies — enough
+ *  for a composer to count and rank without knowing which producer emitted an item. */
+export interface ValidateFinding {
+    readonly claim: "defect" | "lead";
+    readonly detail: string;
+}
+/**
+ * Flattens every one of `validate`'s finding sources into one array: the
+ * top-level env array plus the nested reports (`rollback`, `attributeExistence`,
+ * `migrationIntegrity`, `ormRegistration`, `observedRoutes`).
+ *
+ * `validate` publishes findings across several separate sub-objects because
+ * each check examines a different kind of evidence and discloses its own
+ * `ran`/`examined`/`withheld` detail alongside its findings. A composer that
+ * reads only one of them silently drops the rest — the exact failure UAT
+ * phase 5 §4 found in `pre_push`, which read `data.findings` and nothing
+ * else. This function is the one place that knows the full list, so a new
+ * sub-check added here is inherited by every composer automatically instead
+ * of requiring a second, easily-forgotten edit at each call site.
+ */
+export declare function collectValidateFindings(data: ValidateData): readonly ValidateFinding[];
+export declare const validateTool: ToolDefinition;
+//# sourceMappingURL=validate.d.ts.map

package/dist/tools/validate.d.ts.map

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