@descryy/core 0.1.0

package/dist/contracts/index.d.ts

@@ -0,0 +1,9 @@
+export { nearestMiss, sameEndpoint } from "./paths.ts";
+export type { EndpointKey, NearMiss, NearMissKind } from "./paths.ts";
+export { readShape, compareShapes } from "./shapes.ts";
+export type { Shape, ShapeField, ShapeComparison, ShapeDifference, ShapeDifferenceKind, } from "./shapes.ts";
+export { findContractOrphans } from "./orphans.ts";
+export type { ContractFinding, ContractFindingKind, ContractReport, OrphanOptions, } from "./orphans.ts";
+export { checkContracts } from "./engine.ts";
+export type { ContractCheck, ContractOptions, ShapeCheck, ShapeDirection, ShapeMismatch, } from "./engine.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EACV,KAAK,EACL,UAAU,EACV,eAAe,EACf,eAAe,EACf,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,aAAa,EACb,eAAe,EACf,UAAU,EACV,cAAc,EACd,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/contracts/index.js

@@ -0,0 +1,5 @@
+export { nearestMiss, sameEndpoint } from "./paths.js";
+export { readShape, compareShapes } from "./shapes.js";
+export { findContractOrphans } from "./orphans.js";
+export { checkContracts } from "./engine.js";
+//# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGvD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AASvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAQnD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/contracts/orphans.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The contract engine's R2 half: who calls what, and who serves it.
+ *
+ * §13's mechanism is shape comparison at R3. This is the part that works
+ * **below** it, and the architecture is explicit that it should exist: at R2,
+ * report path-level orphans only, and say so. Splitting the engine this way
+ * means half the value lands on graphs no type checker has touched, and the R3
+ * half does not hold it hostage.
+ *
+ * ## Three findings, and the reason there are only three
+ *
+ * ```
+ *   API_ROUTE ──SERVES_API──▶ API_ENDPOINT ◀──USES_API── caller
+ * ```
+ *
+ * An `API_ENDPOINT` is the join. Every question here is about which of its two
+ * sides is present:
+ *
+ * | both sides | one side | finding |
+ * | --- | --- | --- |
+ * | caller + route | — | the contract holds at path level |
+ * | — | caller only | **the call reaches nothing that is served** |
+ * | — | route only | **nothing in this graph calls the route** |
+ *
+ * ## The trap, and it is the whole design
+ *
+ * On two real repositories: **117 callers, 24 routes, 16 joined.** The other 101
+ * callers are, overwhelmingly, calls to services that are not in the graph at
+ * all — a third-party API, a backend nobody analysed. Reporting them as "no
+ * route serves this" would be 101 confident wrong statements that bury the
+ * handful that are real.
+ *
+ * So an unmatched caller is a **finding** only when a served route exists that
+ * it nearly matches (see `paths.ts`, where every rule is a specific mechanical
+ * mistake rather than a similarity threshold). Everything else is counted and
+ * disclosed as *not analysable*, because the honest description of it is "the
+ * provider side of this call was never read", not "the provider side is wrong".
+ *
+ * Two more refusals in the same spirit:
+ *
+ * - **No routes at all in the graph → no caller findings, at all.** With nothing
+ *   on the provider side, every caller is unmatched by construction and the
+ *   comparison has no content. Reported as not analysable, with the reason.
+ * - **`ROUTE_NOT_CALLED` is stated weakly on purpose.** A route nothing calls is
+ *   usually a route called by something outside this graph — a mobile client,
+ *   another service, curl. It is a lead, not a defect, and the wording says so.
+ */
+import type { IRNode, ResolutionLevel } from "@descryy/ir";
+import type { AdjacencyProvider, QueryResult } from "../query/provider.ts";
+import { type NearMiss } from "./paths.ts";
+export type ContractFindingKind = "CALL_NOT_SERVED" | "ROUTE_NOT_CALLED";
+export interface ContractFinding {
+    readonly kind: ContractFindingKind;
+    readonly endpoint: IRNode;
+    readonly method: string;
+    readonly pathTemplate: string;
+    /** Callers reaching this endpoint. Populated for `CALL_NOT_SERVED`. */
+    readonly callers: readonly IRNode[];
+    /** Routes serving it. Populated for `ROUTE_NOT_CALLED`. */
+    readonly routes: readonly IRNode[];
+    /** Why this is reportable rather than merely unmatched. Null for `ROUTE_NOT_CALLED`. */
+    readonly nearMiss: NearMiss | null;
+    /** The sentence a developer reads. */
+    readonly detail: string;
+    /** Lowest resolution among the edges this finding rests on. Caps its class. */
+    readonly resolution: ResolutionLevel;
+}
+export interface ContractReport {
+    readonly findings: readonly ContractFinding[];
+    readonly checked: {
+        readonly endpoints: number;
+        readonly withCallers: number;
+        readonly withRoutes: number;
+        readonly joined: number;
+    };
+    /**
+     * Unmatched callers with nothing on the provider side that resembles them.
+     *
+     * Not findings, and the number matters: it is the size of the region this
+     * analysis could not speak about.
+     */
+    readonly unmatchedWithoutNearMiss: number;
+    /** True when the R3 shape comparison did not run. Always true in this half. */
+    readonly shapesCompared: boolean;
+}
+export interface OrphanOptions {
+    /** Cap on endpoints enumerated. Truncation is reported, never silent. */
+    readonly limit?: number;
+    /**
+     * Cap on findings returned — rule 5's "a few high-confidence findings, never
+     * an exhaustive maybe-list". Overflow is disclosed, not dropped quietly.
+     */
+    readonly maxFindings?: number;
+}
+export declare function findContractOrphans(provider: AdjacencyProvider, options?: OrphanOptions): QueryResult<ContractReport>;
+//# sourceMappingURL=orphans.d.ts.map

package/dist/contracts/orphans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphans.d.ts","sourceRoot":"","sources":["../../src/contracts/orphans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAc,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAiC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;;;;OAKG;IACH,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAYD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,aAAkB,GAC1B,WAAW,CAAC,cAAc,CAAC,CA6M7B"}

package/dist/contracts/orphans.js

@@ -0,0 +1,241 @@
+/**
+ * The contract engine's R2 half: who calls what, and who serves it.
+ *
+ * §13's mechanism is shape comparison at R3. This is the part that works
+ * **below** it, and the architecture is explicit that it should exist: at R2,
+ * report path-level orphans only, and say so. Splitting the engine this way
+ * means half the value lands on graphs no type checker has touched, and the R3
+ * half does not hold it hostage.
+ *
+ * ## Three findings, and the reason there are only three
+ *
+ * ```
+ *   API_ROUTE ──SERVES_API──▶ API_ENDPOINT ◀──USES_API── caller
+ * ```
+ *
+ * An `API_ENDPOINT` is the join. Every question here is about which of its two
+ * sides is present:
+ *
+ * | both sides | one side | finding |
+ * | --- | --- | --- |
+ * | caller + route | — | the contract holds at path level |
+ * | — | caller only | **the call reaches nothing that is served** |
+ * | — | route only | **nothing in this graph calls the route** |
+ *
+ * ## The trap, and it is the whole design
+ *
+ * On two real repositories: **117 callers, 24 routes, 16 joined.** The other 101
+ * callers are, overwhelmingly, calls to services that are not in the graph at
+ * all — a third-party API, a backend nobody analysed. Reporting them as "no
+ * route serves this" would be 101 confident wrong statements that bury the
+ * handful that are real.
+ *
+ * So an unmatched caller is a **finding** only when a served route exists that
+ * it nearly matches (see `paths.ts`, where every rule is a specific mechanical
+ * mistake rather than a similarity threshold). Everything else is counted and
+ * disclosed as *not analysable*, because the honest description of it is "the
+ * provider side of this call was never read", not "the provider side is wrong".
+ *
+ * Two more refusals in the same spirit:
+ *
+ * - **No routes at all in the graph → no caller findings, at all.** With nothing
+ *   on the provider side, every caller is unmatched by construction and the
+ *   comparison has no content. Reported as not analysable, with the reason.
+ * - **`ROUTE_NOT_CALLED` is stated weakly on purpose.** A route nothing calls is
+ *   usually a route called by something outside this graph — a mobile client,
+ *   another service, curl. It is a lead, not a defect, and the wording says so.
+ */
+import { nearestMiss } from "./paths.js";
+const DEFAULT_MAX_FINDINGS = 25;
+function keyOf(endpoint) {
+    const method = endpoint.attrs["method"];
+    const pathTemplate = endpoint.attrs["pathTemplate"];
+    return typeof method === "string" && typeof pathTemplate === "string"
+        ? { method, pathTemplate }
+        : null;
+}
+export function findContractOrphans(provider, options = {}) {
+    const maxFindings = options.maxFindings ?? DEFAULT_MAX_FINDINGS;
+    const set = provider.nodesOfType("API_ENDPOINT", ...(options.limit === undefined ? [] : [options.limit]));
+    const notes = [];
+    const sided = [];
+    let unkeyed = 0;
+    for (const endpoint of set.nodes) {
+        const key = keyOf(endpoint);
+        if (key === null) {
+            // An endpoint with no method or path template cannot be compared to
+            // anything. Counted rather than skipped: it means a producer emitted a
+            // join node without the two attributes the join is made of.
+            unkeyed += 1;
+            continue;
+        }
+        const callers = [];
+        const routes = [];
+        let resolution = 4;
+        for (const edge of provider.incoming(endpoint.id, { types: ["USES_API", "SERVES_API"] })) {
+            const other = provider.node(edge.from);
+            if (other === undefined)
+                continue;
+            if (edge.resolution < resolution)
+                resolution = edge.resolution;
+            (edge.type === "USES_API" ? callers : routes).push(other);
+        }
+        sided.push({ endpoint, key, callers, routes, resolution });
+    }
+    const withCallers = sided.filter((s) => s.callers.length > 0);
+    const withRoutes = sided.filter((s) => s.routes.length > 0);
+    const joined = sided.filter((s) => s.callers.length > 0 && s.routes.length > 0);
+    const servedKeys = withRoutes.map((s) => s.key);
+    // --- the refusals --------------------------------------------------------
+    if (sided.length === 0) {
+        notes.push("No API endpoints are in the graph, so there is no contract to check. Either no adapter " +
+            "read a route or a client call, or none of the configured adapters produces them. This " +
+            "is not a clean result.");
+        return report(provider, emptyReport(sided.length, 0, 0, 0), 0, false, notes);
+    }
+    const findings = [];
+    let unmatchedWithoutNearMiss = 0;
+    if (withRoutes.length === 0) {
+        // Every caller is unmatched by construction. Comparing against an empty
+        // provider side produces one finding per call site and means nothing.
+        unmatchedWithoutNearMiss = withCallers.length;
+        notes.push(`${withCallers.length} endpoint(s) are called and no route is in the graph at all, so no ` +
+            "comparison was possible. Every call would be reported as unserved for the same reason, " +
+            "which is a property of what was analysed rather than of the code. Add the service that " +
+            "serves these routes, or a published contract for it.");
+    }
+    else {
+        for (const entry of withCallers) {
+            if (entry.routes.length > 0)
+                continue;
+            const miss = nearestMiss(entry.key, servedKeys);
+            if (miss === null) {
+                // Nothing on the provider side resembles it. Far more likely an external
+                // service than a defect, and stating otherwise would be 101 confident
+                // wrong sentences on the repositories this was measured against.
+                unmatchedWithoutNearMiss += 1;
+                continue;
+            }
+            findings.push({
+                kind: "CALL_NOT_SERVED",
+                endpoint: entry.endpoint,
+                method: entry.key.method,
+                pathTemplate: entry.key.pathTemplate,
+                callers: entry.callers,
+                routes: [],
+                nearMiss: miss,
+                detail: `${entry.key.method} ${entry.key.pathTemplate} is called from ` +
+                    `${describeCallers(entry.callers)} and no route serves it — but ${miss.detail}`,
+                resolution: entry.resolution,
+            });
+        }
+    }
+    if (withCallers.length === 0) {
+        // The mirror of the refusal above, and it was missing until a per-source
+        // ablation on `bench/contracts-real.mjs` removed the consumer side: the
+        // engine reported 24 ROUTE_NOT_CALLED findings and no disclosure, about a
+        // graph containing no callers at all.
+        //
+        // "Nothing in this graph calls this route" is literally true there — and so
+        // is the sentence this engine declines to say in the other direction.
+        // Whichever side is empty, the cause is ONE fact about what was analysed,
+        // not N facts about the artefacts. It is not only an ablation state either:
+        // a workspace where only the backend has been indexed is the normal first
+        // day of a deployment.
+        notes.push(`${withRoutes.length} route(s) are served and no call site is in the graph at all, so no ` +
+            "comparison was possible. Every route would be reported as uncalled for the same reason, " +
+            "which is a property of what was analysed rather than of the code. Add the client that " +
+            "calls these routes.");
+    }
+    else {
+        for (const entry of withRoutes) {
+            if (entry.callers.length > 0)
+                continue;
+            findings.push({
+                kind: "ROUTE_NOT_CALLED",
+                endpoint: entry.endpoint,
+                method: entry.key.method,
+                pathTemplate: entry.key.pathTemplate,
+                callers: [],
+                routes: entry.routes,
+                nearMiss: null,
+                detail: `${entry.key.method} ${entry.key.pathTemplate} is served by ` +
+                    `${describeRoutes(entry.routes)} and nothing in this graph calls it. That is a lead, ` +
+                    "not a defect: a mobile client, another service or an external consumer would not " +
+                    "appear here.",
+                resolution: entry.resolution,
+            });
+        }
+    }
+    // Findings that rest on better evidence first, then the stronger kind, then by
+    // path so the order is identical between runs.
+    findings.sort((a, b) => b.resolution - a.resolution ||
+        (a.kind === b.kind ? 0 : a.kind === "CALL_NOT_SERVED" ? -1 : 1) ||
+        `${a.method} ${a.pathTemplate}`.localeCompare(`${b.method} ${b.pathTemplate}`));
+    const kept = findings.slice(0, maxFindings);
+    const truncated = set.truncated || kept.length < findings.length;
+    if (kept.length < findings.length) {
+        notes.push(`${findings.length - kept.length} further finding(s) were withheld: a report is capped at ` +
+            `${maxFindings} so that a short list stays worth reading. They were found, not missed — ` +
+            'raise "maxFindings" to see them.');
+    }
+    if (set.truncated) {
+        notes.push("More endpoints exist than were enumerated, so this report covers a prefix of the graph " +
+            "rather than all of it. Endpoints beyond the cap were not examined and are not clean.");
+    }
+    if (unkeyed > 0) {
+        notes.push(`${unkeyed} endpoint(s) carry no method or path template and could not be compared to ` +
+            "anything. A producer emitted a join node without the two attributes the join is made of.");
+    }
+    if (unmatchedWithoutNearMiss > 0 && withRoutes.length > 0) {
+        notes.push(`${unmatchedWithoutNearMiss} called endpoint(s) have no route in this graph and nothing on ` +
+            "the provider side that resembles them. They are not reported as broken: the likeliest " +
+            "explanation is a service outside this workspace, and the honest statement is that their " +
+            "provider was never read.");
+    }
+    notes.push("Path level only. Request and response shapes were not compared — that requires R3 on both " +
+        "sides, because it compares shapes rather than names.");
+    let floor = 4;
+    for (const finding of kept)
+        if (finding.resolution < floor)
+            floor = finding.resolution;
+    if (kept.length === 0)
+        floor = 2;
+    return report(provider, {
+        findings: kept,
+        checked: {
+            endpoints: sided.length,
+            withCallers: withCallers.length,
+            withRoutes: withRoutes.length,
+            joined: joined.length,
+        },
+        unmatchedWithoutNearMiss,
+        shapesCompared: false,
+    }, floor, truncated, notes);
+}
+function describeCallers(callers) {
+    const first = callers[0];
+    if (first === undefined)
+        return "an unknown caller";
+    const where = first.file === null ? first.name : `${first.name} (${first.file})`;
+    return callers.length === 1 ? where : `${where} and ${callers.length - 1} other(s)`;
+}
+function describeRoutes(routes) {
+    const first = routes[0];
+    if (first === undefined)
+        return "an unknown route";
+    return routes.length === 1 ? first.name : `${first.name} and ${routes.length - 1} other(s)`;
+}
+function emptyReport(endpoints, withCallers, withRoutes, joined) {
+    return {
+        findings: [],
+        checked: { endpoints, withCallers, withRoutes, joined },
+        unmatchedWithoutNearMiss: 0,
+        shapesCompared: false,
+    };
+}
+function report(provider, data, resolutionFloor, truncated, notes) {
+    const stamp = { ...provider.baseStamp(), resolutionFloor };
+    return { data, stamp, truncated, notes };
+}
+//# sourceMappingURL=orphans.js.map

package/dist/contracts/orphans.js.map

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

package/dist/contracts/paths.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Comparing two endpoint paths, and knowing when not to.
+ *
+ * This file is small and is the most dangerous part of the contract engine, so
+ * it is separate and tested on its own.
+ *
+ * ## The problem it exists to solve
+ *
+ * A caller reaching an endpoint no route serves is *sometimes* a bug and
+ * *usually* not. Measured on two real repositories: 117 callers, 24 routes, 16
+ * joined. The other 101 are overwhelmingly calls to services that are simply not
+ * in this graph — a third-party API, a backend nobody has analysed. Reporting
+ * all 101 as "no route serves this" would be 101 confident wrong statements, and
+ * would bury the handful that are real.
+ *
+ * So an unmatched caller is only a **finding** when a served route exists that
+ * it nearly matches. Nothing similar on the provider side means the provider was
+ * probably never analysed, which belongs in §20.2's *not analysable* category
+ * and is disclosed as a count rather than enumerated as defects.
+ *
+ * ## The near-miss rules are deliberately narrow
+ *
+ * Each one describes a specific, common, *mechanical* mistake. None of them is a
+ * similarity score, because a threshold on a score is a knob that turns "is this
+ * a bug" into "how high did we set it".
+ *
+ * | rule | example | why it is a real mistake |
+ * | --- | --- | --- |
+ * | method differs, path identical | `POST /orders` vs `GET /orders` | someone changed the verb on one side |
+ * | exactly one **literal** segment differs, **and the two differ by a typo's worth of characters** | `/order/{param}/items` vs `/orders/{param}/items` | a typo or a rename applied on one side |
+ *
+ * ## Rule 2's similarity floor, and the measurement that set it
+ *
+ * That second clause was missing for the whole life of this file, and its
+ * absence was not a small thing. "Exactly one segment differs" says nothing at
+ * all about *how* it differs: `/api/hmac` and `/api/novu-agent` differ in
+ * exactly one segment, share a method and share arity. Precision came only
+ * incidentally, from `{param}` segments happening to sit where the paths
+ * diverge.
+ *
+ * `DEC-317` found this from the GraphQL side — every operation path is arity-2
+ * with no `{param}` and a first segment drawn from a set of size three, so the
+ * whole GraphQL surface of a repository collapsed into three buckets in which
+ * every member near-missed every other — and gated it rather than fixing it,
+ * because a threshold chosen carelessly costs the near-typo detections this
+ * rule exists for, and costs them invisibly.
+ *
+ * So it was measured, against 3,524 routes from 27 real repositories, by
+ * `bench/near-miss-similarity.mjs` — which pre-registers the metric, the
+ * candidate thresholds and the decision rule in its header, and was committed
+ * before it was run. What it found:
+ *
+ * - **The rule was not a precision rule.** Treating each real route as an
+ *   unmatched caller against the rest of its own application's table, it
+ *   reported a `ONE_SEGMENT` near miss for **1,796 of 3,524 routes — 51%.**
+ *   Every one is a false positive by construction: both sides are real,
+ *   deliberately distinct routes of the same service.
+ * - **On the genuinely reachable population it was worse.** Across every
+ *   unmatched `USES_API` caller in the corpus, the rule emitted **18 findings,
+ *   and all 18 were nonsense** — 15 of them naming the same `/api/novu-agent`
+ *   route from callers like `/api/hmac` and `/api/send-email`. There were no
+ *   true positives to lose.
+ *
+ * The floor is `1 - distance / max(len) >= 0.4`, with any distance of 1 or less
+ * admitted outright so that a one-character mistake in a short segment (`/v1`
+ * against `/v2`) is not scored away. It rejects **87.4%** of those 1,796 and
+ * retains **100%** of a seeded near-typo population of 49,405 — real route
+ * segments mutated by transposition, deletion, insertion, substitution,
+ * singular/plural and separator variance. Not one seeded typo is lost, in any
+ * class.
+ *
+ * **The distance counts an adjacent transposition as one edit, not two, and
+ * that is load-bearing.** With plain Levenshtein a swap costs two, so `api` →
+ * `aip` scores `1 - 2/3 = 0.33` and every candidate threshold silently deleted
+ * the entire transposition class — 2,916 real detections, all on segments of
+ * three characters. The first measurement pass rejected every threshold for
+ * exactly this reason, and the reason was a defect in the metric rather than a
+ * fact about the corpus.
+ *
+ * **What the floor is not.** It is a similarity test, not an oracle. `activate`
+ * and `deactivate` are two real routes in one API and score 0.80, so they are
+ * still reported. Nothing here can distinguish a two-character prefix from a
+ * typo, and this does not claim to — it buys precision against *unrelated*
+ * words, which is what the corpus says the problem was.
+ *
+ * **A trailing-slash rule was written and then deleted, and the reason is worth
+ * keeping.** `/orders/` and `/orders` look like the classic contract mismatch,
+ * but `normaliseEndpointPath` strips the trailing slash *before hashing*, so the
+ * two sides mint the **same `API_ENDPOINT` id** and join correctly. The rule
+ * could never fire. It was caught by a test that asserted it would.
+ *
+ * That unification is the right default — the two paths mean the same endpoint
+ * to everyone who writes them — but it does make one real class of bug
+ * invisible here: a framework configured for strict routing genuinely serves
+ * only one of them. Whether it does depends on router configuration this graph
+ * does not read, so the limit is stated rather than papered over with a rule
+ * that fires on nothing.
+ *
+ * **Deliberately not a rule: a parameter where the other side has a literal.**
+ * `/orders/{param}` and `/orders/recent` legitimately coexist in every routing
+ * framework on earth — the literal is matched first and the parameter catches
+ * the rest. Treating that as a near miss would report the single most common
+ * correct pattern in REST routing as a defect.
+ *
+ * Segment counts must be equal for the segment rule. `/orders` and
+ * `/orders/{param}` are two different endpoints, not a near miss, and a rule
+ * that ignored length would pair every collection route with its item route.
+ */
+export interface EndpointKey {
+    readonly method: string;
+    /** Normalised: `:id`, `{id}` and `<int:id>` have all become `{param}`. */
+    readonly pathTemplate: string;
+}
+export type NearMissKind = "METHOD" | "ONE_SEGMENT";
+export interface NearMiss {
+    readonly kind: NearMissKind;
+    /** The served endpoint this one nearly matches. */
+    readonly against: EndpointKey;
+    /** One sentence naming the exact difference. Goes straight into the report. */
+    readonly detail: string;
+}
+export declare function sameEndpoint(a: EndpointKey, b: EndpointKey): boolean;
+/**
+ * The closest served endpoint to `wanted`, or null if nothing is close enough.
+ *
+ * Rules are tried in order of how certain they are, and the first hit wins —
+ * a method mismatch on an otherwise identical path is a better explanation than
+ * a one-segment difference somewhere else, and reporting both would be reporting
+ * one mistake twice.
+ */
+export declare function nearestMiss(wanted: EndpointKey, served: readonly EndpointKey[]): NearMiss | null;
+//# sourceMappingURL=paths.d.ts.map

package/dist/contracts/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/contracts/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AAkEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEpD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAWD,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,QAAQ,GAAG,IAAI,CA0DjB"}