@descryy/core 0.1.0

package/dist/multipr/fingerprint.js.map

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

package/dist/multipr/hidden-dependency.d.ts

@@ -0,0 +1,120 @@
+/**
+ * §14.8 — the historically coupled file that was **not** touched.
+ *
+ * `CHANGES_WITH` queried in the opposite direction from diff scoping. Scoping
+ * asks *what else does this change reach*; this asks *what usually moves with
+ * this and did not this time*.
+ *
+ * ## Why this is the first multi-PR check built
+ *
+ * §14.8 calls it nearly free, and the reason is worth stating rather than
+ * assuming: **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. Every other check in §14 needs either a persisted per-PR
+ * subgraph (§14.2) or a UI framework extractor (§14.7).
+ *
+ * ## Everything here is Class C and that is not a limitation to be fixed
+ *
+ * DEC-033 is explicit: co-change is evidence about **people**, not about
+ * program structure. *"These two files usually change together"* is a hint for
+ * a human, never a claim about what breaks. The git source emits at R0,
+ * §11A.5 caps any finding resting on it at C, and no amount of support count
+ * changes that — a pair that co-changed two hundred times is a stronger hint
+ * and still a hint.
+ *
+ * So this module reports a *nudge* and says so in the words it hands back. A
+ * caller that renders these as defects has broken principle 4 at the last
+ * gate, and the note travels with the finding to make that hard.
+ *
+ * ## The empty answer is two different answers
+ *
+ * A pull request with no hidden dependencies and a graph that never read any
+ * history produce **the same empty list**. That conflation is the single most
+ * expensive defect this project has: an absent carrier read as an empty one
+ * shipped three static-validation checks dead, and a shape reader that
+ * filtered for the wrong spelling answered "no fields" for 77 of 77 nodes
+ * that visibly declared them.
+ *
+ * So `analysed` is false when the graph holds no `CHANGES_WITH` edge for any
+ * changed file, and the caller is told *the history was not read* rather than
+ * *nothing is coupled*. A repository younger than the support floor, a graph
+ * built without the git source, and a genuinely uncoupled change are three
+ * different statements.
+ */
+import type { IRNode } from "@descryy/ir";
+import type { ReliabilityClass } from "@descryy/ir";
+import type { AdjacencyProvider, QueryResult } from "../query/provider.ts";
+/** A file that historically moves with the change and did not move this time. */
+export interface HiddenDependency {
+    /** The coupled file that was not touched. */
+    readonly node: IRNode;
+    /** Which changed files it is coupled to, most-supported first. */
+    readonly coupledTo: readonly {
+        readonly node: IRNode;
+        /** Commits in which the two changed together. */
+        readonly support: number;
+        /** `support / max(times either file changed)`, as observed. */
+        readonly observedConfidence: number;
+    }[];
+    /** The strongest support across `coupledTo` — what the ranking uses. */
+    readonly strongestSupport: number;
+    /** Always `"C"`. Present so a caller cannot render this without it. */
+    readonly reliability: ReliabilityClass;
+    /** The sentence that must travel with the finding. */
+    readonly disclosure: string;
+}
+export interface HiddenDependencyReport {
+    readonly findings: readonly HiddenDependency[];
+    /** The count before `limit` capped it — P27's disclosed remainder: a structured field, not only a prose note. */
+    readonly findingsTotal: number;
+    /**
+     * False when no changed file had a single `CHANGES_WITH` edge.
+     *
+     * **An empty `findings` with `analysed: false` means the history was not
+     * read, not that nothing is coupled.** The two are different answers to
+     * different questions and collapsing them is §20.2's second category
+     * swallowing its fourth.
+     */
+    readonly analysed: boolean;
+    readonly checked: {
+        /** Changed paths the caller supplied. */
+        readonly changed: number;
+        /** Of those, how many resolved to a `FILE` node in the graph. */
+        readonly resolved: number;
+        /** Of those, how many carried at least one co-change edge. */
+        readonly withHistory: number;
+        /** Coupled files considered before the support floor and the cap. */
+        readonly candidates: number;
+    };
+    /**
+     * Changed paths with no `FILE` node in the graph.
+     *
+     * Not "these have no hidden dependencies" — nothing looked at them. A path
+     * the graph never read is a path with no blast radius only if you conflate
+     * the two.
+     */
+    readonly unresolvedChanged: readonly string[];
+}
+export interface HiddenDependencyOptions {
+    /**
+     * Minimum co-change support to surface. Defaults to the edge's own floor,
+     * because an edge that exists already cleared DEC-033's support and
+     * confidence floors — raising it here is a second, separate judgement and
+     * belongs to the caller.
+     */
+    readonly minSupport?: number;
+    /**
+     * Hard cap on findings, per rule 5. Truncation is reported, never silent.
+     */
+    readonly limit?: number;
+}
+/**
+ * Files coupled to the change that the change did not touch.
+ *
+ * @param changedIds `FILE` node ids the pull request touched
+ * @param unresolvedChanged paths the caller could not resolve to a node — passed
+ *   in rather than discovered, because only the caller knows what it asked for
+ */
+export declare function findHiddenDependencies(provider: AdjacencyProvider, changedIds: readonly string[], unresolvedChanged?: readonly string[], options?: HiddenDependencyOptions): QueryResult<HiddenDependencyReport>;
+//# sourceMappingURL=hidden-dependency.d.ts.map

package/dist/multipr/hidden-dependency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-dependency.d.ts","sourceRoot":"","sources":["../../src/multipr/hidden-dependency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAU,MAAM,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAG3E,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,SAAS;QAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,iDAAiD;QACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,+DAA+D;QAC/D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;KACrC,EAAE,CAAC;IACJ,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,iHAAiH;IACjH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE;QAChB,yCAAyC;QACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,iEAAiE;QACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,8DAA8D;QAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,qEAAqE;QACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAuCD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,iBAAiB,GAAE,SAAS,MAAM,EAAO,EACzC,OAAO,GAAE,uBAA4B,GACpC,WAAW,CAAC,sBAAsB,CAAC,CAyHrC"}

package/dist/multipr/hidden-dependency.js

@@ -0,0 +1,185 @@
+/**
+ * §14.8 — the historically coupled file that was **not** touched.
+ *
+ * `CHANGES_WITH` queried in the opposite direction from diff scoping. Scoping
+ * asks *what else does this change reach*; this asks *what usually moves with
+ * this and did not this time*.
+ *
+ * ## Why this is the first multi-PR check built
+ *
+ * §14.8 calls it nearly free, and the reason is worth stating rather than
+ * assuming: **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. Every other check in §14 needs either a persisted per-PR
+ * subgraph (§14.2) or a UI framework extractor (§14.7).
+ *
+ * ## Everything here is Class C and that is not a limitation to be fixed
+ *
+ * DEC-033 is explicit: co-change is evidence about **people**, not about
+ * program structure. *"These two files usually change together"* is a hint for
+ * a human, never a claim about what breaks. The git source emits at R0,
+ * §11A.5 caps any finding resting on it at C, and no amount of support count
+ * changes that — a pair that co-changed two hundred times is a stronger hint
+ * and still a hint.
+ *
+ * So this module reports a *nudge* and says so in the words it hands back. A
+ * caller that renders these as defects has broken principle 4 at the last
+ * gate, and the note travels with the finding to make that hard.
+ *
+ * ## The empty answer is two different answers
+ *
+ * A pull request with no hidden dependencies and a graph that never read any
+ * history produce **the same empty list**. That conflation is the single most
+ * expensive defect this project has: an absent carrier read as an empty one
+ * shipped three static-validation checks dead, and a shape reader that
+ * filtered for the wrong spelling answered "no fields" for 77 of 77 nodes
+ * that visibly declared them.
+ *
+ * So `analysed` is false when the graph holds no `CHANGES_WITH` edge for any
+ * changed file, and the caller is told *the history was not read* rather than
+ * *nothing is coupled*. A repository younger than the support floor, a graph
+ * built without the git source, and a genuinely uncoupled change are three
+ * different statements.
+ */
+import { reliabilityCap, reliabilityNote } from "@descryy/ir";
+const DEFAULT_LIMIT = 10;
+/**
+ * `CHANGES_WITH` is stored in one canonical direction (DEC-036), so both
+ * directions must be walked. Reading only `outgoing` halves the answer and
+ * produces no error — the same silent-halving shape as an undirected edge
+ * traversed one way in scoping, which is why `traverse.ts` carries the same
+ * set.
+ */
+function coupledNeighbours(provider, id) {
+    const out = [];
+    const seen = new Set();
+    const options = { types: ["CHANGES_WITH"] };
+    const walk = (edges, other) => {
+        for (const edge of edges) {
+            const id2 = other(edge);
+            if (id2 === id || seen.has(id2))
+                continue;
+            seen.add(id2);
+            const raw = edge.attrs ?? {};
+            out.push({
+                id: id2,
+                support: typeof raw["support"] === "number" ? raw["support"] : 0,
+                observedConfidence: typeof raw["observedConfidence"] === "number" ? raw["observedConfidence"] : 0,
+            });
+        }
+    };
+    walk(provider.outgoing(id, options), (e) => e.to);
+    walk(provider.incoming(id, options), (e) => e.from);
+    return out;
+}
+/**
+ * Files coupled to the change that the change did not touch.
+ *
+ * @param changedIds `FILE` node ids the pull request touched
+ * @param unresolvedChanged paths the caller could not resolve to a node — passed
+ *   in rather than discovered, because only the caller knows what it asked for
+ */
+export function findHiddenDependencies(provider, changedIds, unresolvedChanged = [], options = {}) {
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const minSupport = options.minSupport ?? 0;
+    const changed = new Set(changedIds);
+    const changedNodes = new Map();
+    for (const id of changed) {
+        const node = provider.node(id);
+        if (node !== undefined)
+            changedNodes.set(id, node);
+    }
+    // candidate id -> the changed files it is coupled to
+    const candidates = new Map();
+    let withHistory = 0;
+    for (const [id, node] of changedNodes) {
+        const neighbours = coupledNeighbours(provider, id);
+        if (neighbours.length > 0)
+            withHistory += 1;
+        for (const n of neighbours) {
+            // The coupled file WAS touched. That is the check passing, not a finding.
+            if (changed.has(n.id))
+                continue;
+            if (n.support < minSupport)
+                continue;
+            let entry = candidates.get(n.id);
+            if (entry === undefined) {
+                entry = { node: provider.node(n.id) ?? null, links: [] };
+                candidates.set(n.id, entry);
+            }
+            entry.links.push({ node, support: n.support, observedConfidence: n.observedConfidence });
+        }
+    }
+    // R0 evidence, and the claim is name-level: this file is or is not in the
+    // diff. §11A.5 caps it at C either way — R0's name-level row is still C, and
+    // only R2 buys the A carve-out. Computed rather than written down so that a
+    // change to the table cannot leave this stale.
+    const reliability = reliabilityCap(0, true);
+    const disclosure = `${reliabilityNote(0, true)} Co-change is evidence about how people have edited ` +
+        "this repository, not about what the program does — a strongly coupled pair is a " +
+        "stronger hint and is still a hint.";
+    const findings = [];
+    for (const [, entry] of candidates) {
+        if (entry.node === null)
+            continue;
+        const links = [...entry.links].sort((a, b) => b.support - a.support);
+        findings.push({
+            node: entry.node,
+            coupledTo: links.map((l) => ({
+                node: l.node,
+                support: l.support,
+                observedConfidence: l.observedConfidence,
+            })),
+            strongestSupport: links[0]?.support ?? 0,
+            reliability,
+            disclosure,
+        });
+    }
+    findings.sort((a, b) => b.strongestSupport - a.strongestSupport || a.node.file.localeCompare(b.node.file));
+    const kept = findings.slice(0, limit);
+    const truncated = findings.length > limit;
+    // The baseline precondition. Nothing was read, so nothing can be concluded —
+    // and "no hidden dependencies" is a conclusion.
+    const analysed = withHistory > 0;
+    const notes = [];
+    if (!analysed) {
+        notes.push("No co-change history was found for any changed file, so this check did not run. " +
+            "That is not a finding that nothing is coupled: a graph built without the git " +
+            "history source, a repository with fewer commits than the support floor, and a " +
+            "genuinely uncoupled change are three different situations and this answer " +
+            "cannot tell them apart.");
+    }
+    if (unresolvedChanged.length > 0) {
+        notes.push(`${unresolvedChanged.length} changed path(s) have no node in the graph and were not ` +
+            "examined: " +
+            `${unresolvedChanged.slice(0, 5).join(", ")}${unresolvedChanged.length > 5 ? ", …" : ""}. ` +
+            "Nothing looked at them, which is not the same as finding nothing in them.");
+    }
+    if (truncated) {
+        notes.push(`${findings.length} coupled files were surfaced and the ${kept.length} with the ` +
+            "strongest history are reported.");
+    }
+    if (analysed && kept.length > 0) {
+        notes.push(disclosure);
+    }
+    const stamp = { ...provider.baseStamp(), resolutionFloor: 0 };
+    return {
+        data: {
+            findings: kept,
+            findingsTotal: findings.length,
+            analysed,
+            checked: {
+                changed: changedIds.length,
+                resolved: changedNodes.size,
+                withHistory,
+                candidates: candidates.size,
+            },
+            unresolvedChanged,
+        },
+        stamp,
+        truncated,
+        notes,
+    };
+}
+//# sourceMappingURL=hidden-dependency.js.map

package/dist/multipr/hidden-dependency.js.map

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

package/dist/multipr/index.d.ts

@@ -0,0 +1,14 @@
+export { findHiddenDependencies } from "./hidden-dependency.ts";
+export type { HiddenDependency, HiddenDependencyReport, HiddenDependencyOptions, } from "./hidden-dependency.ts";
+export { findOverlaps, NODE_TYPE_WEIGHTS, DEFAULT_CONFLICT_THRESHOLD } from "./overlap.ts";
+export type { DiffType, PrScope, PrScopeEntry, SharedNode, OverlapFinding, OverlapReport, OverlapOptions, IncomparablePair, } from "./overlap.ts";
+export { ScopeStore, ScopeDecodeError } from "./scope-store.ts";
+export { findSuperseded } from "./superseded.ts";
+export { supersededCandidates } from "./fingerprint.ts";
+export type { CandidateReport } from "./fingerprint.ts";
+export type { SupersededCandidate, SupersededReport, SupersededOptions, NodeComparison, NodeVerdict, } from "./superseded.ts";
+export { classifyOverlaps, applyMechanical, pairReliability, CONTEXT_LINES } from "./mechanical.ts";
+export type { DiffHunk, MechanicalVerdict, KeepBothResolution, MechanicalClassification, MechanicalReport, MechanicalOptions, ApplyOutcome, ApplyHooks, } from "./mechanical.ts";
+export { findMigrationHeadConflicts } from "./migration-heads.ts";
+export type { MigrationRecord, MigrationHead, HeadConflict, CrossPrDependency, MigrationHeadReport, MigrationHeadOptions, } from "./migration-heads.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/multipr/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC3F,YAAY,EACV,QAAQ,EACR,OAAO,EACP,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpG,YAAY,EACV,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EACV,eAAe,EACf,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC"}

package/dist/multipr/index.js

@@ -0,0 +1,8 @@
+export { findHiddenDependencies } from "./hidden-dependency.js";
+export { findOverlaps, NODE_TYPE_WEIGHTS, DEFAULT_CONFLICT_THRESHOLD } from "./overlap.js";
+export { ScopeStore, ScopeDecodeError } from "./scope-store.js";
+export { findSuperseded } from "./superseded.js";
+export { supersededCandidates } from "./fingerprint.js";
+export { classifyOverlaps, applyMechanical, pairReliability, CONTEXT_LINES } from "./mechanical.js";
+export { findMigrationHeadConflicts } from "./migration-heads.js";
+//# sourceMappingURL=index.js.map

package/dist/multipr/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/multipr/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAMhE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAW3F,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AASxD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAWpG,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/multipr/mechanical.d.ts

@@ -0,0 +1,239 @@
+/**
+ * §14.4 — is this overlap two people adding lines, or two people disagreeing?
+ *
+ * `overlap.ts` surfaces a shared node and stops, and says why it stops: *"§14.4's
+ * mechanical-versus-semantic classification needs the actual diff lines at the
+ * shared node, which this module never sees … Guessing 'mechanical' without
+ * reading the lines would be the one place in this system where a wrong guess
+ * edits somebody's branch."* This is that module, and it reads the lines.
+ *
+ * ## The bar here is higher than anywhere else in §14, not lower
+ *
+ * §14.4 is the **single documented exception** to approval-before-code-change
+ * (§9, rule 8). Every other check in this package tells a human to look at
+ * something. A `MECHANICAL` verdict may be **auto-applied** — it edits a branch
+ * without asking.
+ *
+ * So rule 2 inverts in consequence, and the asymmetry is the whole design:
+ *
+ * > A missed mechanical resolution costs a human thirty seconds of `git
+ * > mergetool`. A false one silently rewrites two people's work into something
+ * > neither wrote and reports success.
+ *
+ * `MECHANICAL` is therefore claimed **only when every condition is affirmatively
+ * established**, never when nothing contradicts it. Absent hunks, a hunk whose
+ * shape cannot be read, a file this module cannot reason about — each produces
+ * `UNCLASSIFIABLE` with a reason, and `UNCLASSIFIABLE` never auto-applies.
+ * `SEMANTIC` is the answer when the lines were read and disagree; that is a
+ * different sentence from "the lines were not read", and the two are kept apart
+ * for the reason they are kept apart everywhere else in this package.
+ *
+ * ## What "only add new, non-overlapping lines" has to mean to be safe
+ *
+ * §14.4's diamond asks whether both changes *"only add new, non-overlapping
+ * lines"*. Read literally that is a test on the post-image, and the post-images
+ * of two branches are not comparable — they are two different files. The test
+ * that means anything is on the **base**:
+ *
+ *  1. **Every hunk on both sides is a pure insertion** — it consumes zero base
+ *     lines (`baseLines === 0`). One modified or deleted base line anywhere at
+ *     this node makes the whole overlap `SEMANTIC`. Not "the modified hunks are
+ *     semantic and the rest are mechanical": a partially auto-applied overlap is
+ *     a merge nobody reviewed.
+ *
+ *  2. **No two insertion points from opposite sides fall within the context
+ *     window.** Two insertions at base lines 10 and 12 do not touch the same
+ *     line and git still refuses them, because their three-line contexts
+ *     overlap. Matching git's own margin rather than testing for exact equality
+ *     is the difference between a rule about text and a rule about what the
+ *     merge will actually do.
+ *
+ * The margin is `CONTEXT_LINES`, and it is deliberately the *conservative*
+ * direction: a real mechanical case inside the margin is reported `SEMANTIC` and
+ * a human resolves it in half a minute.
+ *
+ * ## Two claims, two different sources of authority — and only one of them
+ * gates the apply
+ *
+ * This finding rests on two separate things and it is worth being exact about
+ * which does what, because conflating them would either block safe applies or
+ * permit unsafe ones:
+ *
+ * | claim | rests on | governs |
+ * | --- | --- | --- |
+ * | *both changes touch this node* | the graph | whether this is **surfaced**, and the reliability class |
+ * | *these hunks merge without conflict* | the diff text | whether this may be **applied** |
+ *
+ * The reliability class follows `overlap.ts` — the weaker of the two sides'
+ * resolutions, per DEC-058 and §11A.5 — and it describes how much to trust that
+ * this overlap *matters*. It does not gate the apply, and that is not a
+ * loosening: if the graph were wrong about the node, "keep both non-adjacent
+ * pure insertions" is still exactly as safe, because the textual claim never
+ * depended on the graph being right. Gating the apply on the graph's resolution
+ * would be borrowing authority from the wrong evidence.
+ *
+ * A caller wanting the stricter rule can require class A itself. The point is
+ * that the module states which evidence carries which claim rather than folding
+ * both into one number.
+ *
+ * ## Verify-after is not a recommendation and is not expressible as one
+ *
+ * §14.4 makes the post-apply verification **mandatory** (§19). A `verifyAfter:
+ * true` field on a result would be advisory, and an advisory obligation is one
+ * `if` away from being skipped by a caller in a hurry.
+ *
+ * So the apply path is `applyMechanical(plan, { apply, verify })` and **both
+ * callbacks are required by the type**. There is no overload that applies
+ * without verifying. A `verify` returning false produces `"reverted"`, and a
+ * `verify` that throws produces `"verification-failed"` — which is *not* the
+ * same outcome and is not collapsed into it, because "the change broke
+ * something" and "we could not tell whether the change broke something" are the
+ * two categories §20.2 exists to keep apart.
+ */
+import type { ResolutionLevel } from "@descryy/ir";
+import type { ReliabilityClass } from "@descryy/ir";
+import type { GraphStamp, QueryResult } from "../query/provider.ts";
+import type { SharedNode } from "./overlap.ts";
+/**
+ * git's default diff context. Two insertions closer than this on the base
+ * produce overlapping context and git declines to merge them, so this module
+ * declines too.
+ */
+export declare const CONTEXT_LINES = 3;
+/**
+ * One hunk of a change, described against the **base** image.
+ *
+ * Deliberately not a patch: this module never applies text, so it needs the
+ * *shape* of the change and not its content. Describing the shape against the
+ * base is what makes two branches comparable at all — their post-images are two
+ * different files and comparing those answers nothing.
+ */
+export interface DiffHunk {
+    readonly file: string;
+    /** First base line the hunk touches, 1-indexed. For a pure insertion, the line it follows. */
+    readonly baseStart: number;
+    /**
+     * Base lines consumed. **Zero means a pure insertion**; anything above zero
+     * means at least one existing line was modified or deleted.
+     */
+    readonly baseLines: number;
+    /** Lines produced. Reported, never used for classification — see the docstring. */
+    readonly headLines: number;
+}
+export type MechanicalVerdict = "MECHANICAL" | "SEMANTIC" | "UNCLASSIFIABLE";
+/** The resolution a `MECHANICAL` verdict proposes. Always "keep both". */
+export interface KeepBothResolution {
+    readonly kind: "keep-both";
+    /**
+     * The two sides' hunks in base order — the order an applier must write them
+     * in. Deterministic so that applying twice is applying the same thing.
+     */
+    readonly order: readonly {
+        readonly side: "a" | "b";
+        readonly hunk: DiffHunk;
+    }[];
+}
+export interface MechanicalClassification {
+    readonly nodeId: string;
+    readonly verdict: MechanicalVerdict;
+    /**
+     * Why, in one sentence, always present — including for `MECHANICAL`.
+     *
+     * A verdict that explains only its refusals trains a reader to skim the
+     * approvals, which are the ones that edit a branch.
+     */
+    readonly reason: string;
+    /** Present only for `MECHANICAL`. */
+    readonly resolution?: KeepBothResolution;
+    /** From the graph: how much to trust that this overlap matters. Never gates the apply. */
+    readonly reliability: ReliabilityClass;
+    readonly resolution_level: ResolutionLevel;
+    /** Hunks read, per side. Zero on either side is a refusal, not a pass. */
+    readonly hunksRead: readonly [number, number];
+    /** The sentence that must travel with the finding. */
+    readonly disclosure: string;
+}
+export interface MechanicalReport {
+    readonly classifications: readonly MechanicalClassification[];
+    /**
+     * False when no shared node had hunks on **both** sides.
+     *
+     * An empty `classifications` with `analysed: false` means the diffs were not
+     * supplied, not that nothing was mechanical — the same distinction
+     * `hidden-dependency.ts` draws for co-change history, and for the same reason.
+     */
+    readonly analysed: boolean;
+    readonly checked: {
+        readonly shared: number;
+        readonly withHunksBothSides: number;
+        readonly mechanical: number;
+        readonly semantic: number;
+        readonly unclassifiable: number;
+    };
+}
+export interface MechanicalOptions {
+    /** Override git's context margin. Raising it is conservative; lowering it is not. */
+    readonly contextLines?: number;
+    readonly stamp?: GraphStamp;
+}
+/**
+ * Classify every surfaced overlap between two changes.
+ *
+ * @param shared the nodes `findOverlaps` surfaced — this module does not decide
+ *   what is worth looking at, only what may be done about it
+ * @param aHunks side A's hunks, against the base both sides share
+ * @param bHunks side B's hunks, against the same base
+ */
+export declare function classifyOverlaps(shared: readonly SharedNode[], aHunks: readonly DiffHunk[], bHunks: readonly DiffHunk[], options?: MechanicalOptions): QueryResult<MechanicalReport>;
+/**
+ * What happened when a mechanical resolution was applied.
+ *
+ * `"reverted"` and `"verification-failed"` are separate on purpose. The first
+ * means verification ran and said no; the second means verification could not
+ * say. Collapsing them would report "the change was bad" for a case that is
+ * actually "we do not know", which is §20.2's second category swallowing its
+ * fourth — the most expensive defect shape in this project.
+ */
+export type ApplyOutcome = {
+    readonly status: "applied";
+    readonly verified: true;
+} | {
+    readonly status: "reverted";
+    readonly why: string;
+} | {
+    readonly status: "verification-failed";
+    readonly why: string;
+} | {
+    readonly status: "refused";
+    readonly why: string;
+};
+export interface ApplyHooks {
+    /** Perform the merge. Throwing is a refusal, not a crash — it is reported. */
+    readonly apply: (resolution: KeepBothResolution) => void | Promise<void>;
+    /** Mandatory. Return false to revert. There is no overload without this. */
+    readonly verify: () => boolean | Promise<boolean>;
+    /** Called when `verify` says no. Absent means the caller cannot undo, which is refused up front. */
+    readonly revert?: (() => void | Promise<void>) | undefined;
+}
+/**
+ * Apply one mechanical resolution, then verify — in that order, always both.
+ *
+ * The mandatory verification of §14.4/§19 is enforced by the *type*: `verify` is
+ * a required member of `ApplyHooks`, so a caller that wants to skip it has to
+ * write a function that lies, which is a different and more visible act than
+ * omitting an optional field.
+ *
+ * Refuses outright, before touching anything, when the verdict is not
+ * `MECHANICAL` or when no `revert` was supplied — auto-applying a change that
+ * cannot be undone if verification fails is the exception's precondition, not a
+ * detail of it.
+ */
+export declare function applyMechanical(classification: MechanicalClassification, hooks: ApplyHooks): Promise<ApplyOutcome>;
+/**
+ * The reliability class this module would report for a pair of resolutions.
+ *
+ * Exported so `overlap.ts`'s rule and this one cannot drift apart silently: both
+ * take the weaker of the two sides, per DEC-058.
+ */
+export declare function pairReliability(a: ResolutionLevel, b: ResolutionLevel): ReliabilityClass;
+//# sourceMappingURL=mechanical.d.ts.map

package/dist/multipr/mechanical.d.ts.map

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