@descryy/core 0.4.0 → 0.5.1

package/dist/sources/git/incidents.js

@@ -1,95 +1,29 @@
 /**
- * Which commits in a history describe a failure, and how we know.
- *
- * Split out of `source.ts` when the answer stopped being one regex. The git
- * source minted an `INCIDENT` for exactly one thing — a commit body carrying
- * `This reverts commit <40 hex>` — and that produced **zero** incidents across
- * three measured repositories (734/459/203 commits) and two in a real product
- * repository. `similarIncidents` was therefore built, tested, correct and
- * starved: its recall is not 0%, it is not computable, because it has never
- * been given a real incident to find.
- *
- * ## The rule every mechanism here answers to
- *
- * `INCIDENT` is an EARNED node (DEC-017). It is never dropped, it survives
- * every rebuild, and `INCIDENT_CORRELATED` biases diff-scoping traversal toward
- * the files it names for as long as the store exists. A wrong incident is not a
- * bad answer that a later run corrects — it is unrecoverable pollution in the
- * one table that cannot be recomputed away. So:
- *
- * **Every mechanism rests on something a person declared. None rests on
- * something Descry inferred.**
- *
- * A revert trailer is written by `git revert`. A `Revert "…"` subject is typed
- * by a person or by GitHub's own button on their behalf. `Fixes #123` is a
- * developer stating that something was broken and this commit fixed it. What is
- * deliberately *not* here is any reading of "fix", "hotfix" or "bug" in prose —
- * the original mechanism's own comment says why, and it applies unchanged to
- * every mechanism added since: matching on the word "fix" would classify
- * ordinary work as an incident.
- *
- * ## Refusals, not guesses
- *
- * A `Revert "X"` naming a subject this history does not contain, or containing
- * twice, produces a `DetectedRefusal` rather than a ranked guess. Two candidates
- * is a genuine ambiguity and picking the nearer one would be recency standing in
- * for evidence — the same discipline every resolver in this project follows.
- *
- * See `DEC-NEXT-incident-minting-beyond-explicit-reverts`.
+ * Which commits describe a failure. `INCIDENT` is EARNED (DEC-017, never dropped, biases traversal permanently), so every mechanism rests on something a person declared — never Descry inferring "fix"/"bug" from prose.
+ * An ambiguous Revert is a DetectedRefusal, not a ranked guess. See DEC-NEXT-incident-minting-beyond-explicit-reverts.
  */
 /** `git revert` writes this. Machine-generated, and the strongest signal available. */
 const REVERT_TRAILER = /This reverts commit ([0-9a-f]{40})/;
-/**
- * `Revert "the original subject"` — the subject form, written by a person or by
- * GitHub's Revert button, often with no sha anywhere in the commit.
- *
- * Anchored at the start and requiring the quotes: `Revert the auth change` is
- * prose about what the commit does, not a reference to a specific commit, and
- * reading it as one would be exactly the inference this module refuses to make.
- */
+/** `Revert "the original subject"` form, written by a person or GitHub's
+ *  button. Anchored + requires quotes: unquoted `Revert the auth change` is
+ *  prose, not a commit reference, and reading it as one is the inference refused here. */
 const REVERT_SUBJECT = /^Revert\s+"(.+)"\s*$/;
-/**
- * A closed list of fix-shaped verbs, and only immediately before the reference.
- *
- * `Fixes #123` is a developer stating that something was broken. `See #123` and
- * `Part of #124` are not — they relate a commit to an issue and say nothing
- * about a defect. The verb is what carries the claim, so the verb is what is
- * matched; a bare `#123` mints nothing.
- *
- * `GH-123` is GitHub's own cross-reference form and means the same thing.
- */
+/** Closed list of fix-shaped verbs, immediately before the reference. `Fixes
+ *  #123` claims a defect; `See #123` doesn't — a bare `#123` mints nothing.
+ *  `GH-123` is GitHub's equivalent cross-reference form. */
 const ISSUE_VERBS = "fix|fixes|fixed|close|closes|closed|resolve|resolves|resolved";
 /** In the subject, anywhere: a subject is a claim about the commit itself. */
 const SUBJECT_ISSUE = new RegExp(`\\b(?:${ISSUE_VERBS})\\s+(?:#|GH-)(\\d+)\\b`, "gi");
-/**
- * In the body, **only in trailer position** — the start of a line, with nothing
- * but whitespace before it.
- *
- * Measured, not supposed. Run over this repository's own history, the
- * anywhere-in-the-body form matched three commits, and all three were prose
- * *about* the convention rather than uses of it: a sentence quoting
- * `"Fixes #123"` as an example, and a bullet reading
- * `- issue-reference: \`Fixes #123\` and its closed list…`. A commit message
- * discussing the convention is not a commit message using it, and an EARNED
- * node minted from one is permanent.
- *
- * The trailer position is where the convention actually lives — it is what
- * GitHub's own tooling emits and what a template puts there — so this costs
- * almost no real recall and removes a whole class of false positive. Rule 2:
- * when in doubt, omit.
+/** In the body, only in trailer position (line start). Measured: the
+ *  anywhere-in-body form matched 3 commits here, all prose *about* the
+ *  convention, not uses of it — and an EARNED node minted from one is permanent. Trailer position is where the convention actually lives. Rule 2.
  */
 const BODY_ISSUE = new RegExp(`^[ \\t]*(?:${ISSUE_VERBS})\\s+(?:#|GH-)(\\d+)\\b`, "gim");
 function pathsOf(commit) {
     return [...new Set(commit.changes.map((c) => c.path))].sort();
 }
-/**
- * Every incident this history declares, plus every revert whose target it does
- * not contain.
- *
- * `commits` is the history as `readHistory` returns it — newest first. Order is
- * not relied on for correctness: a revert's target is found by timestamp, so
- * the result is identical for any permutation of the same commits.
- */
+/** Every incident this history declares, plus every revert whose target it
+ *  lacks. Order-independent: a revert's target is found by timestamp. */
 export function detectIncidents(commits) {
     const incidents = [];
     const refusals = [];
@@ -104,9 +38,8 @@ export function detectIncidents(commits) {
             existing.push(commit);
     }
     for (const commit of commits) {
-        // The trailer first, and exclusively: `git revert` writes both the trailer
-        // and the `Revert "…"` subject, so reading the subject as an independent
-        // mechanism would mint one incident twice under two different names.
+        // Trailer first, exclusively: git revert writes both trailer and subject,
+        // so reading the subject too would mint one incident under two names.
         const revertedSha = REVERT_TRAILER.exec(commit.body)?.[1];
         if (revertedSha !== undefined) {
             const target = bySha.get(revertedSha);
@@ -125,9 +58,8 @@ export function detectIncidents(commits) {
         }
         const quoted = REVERT_SUBJECT.exec(commit.subject)?.[1];
         if (quoted !== undefined) {
-            // Backwards only. A commit cannot revert something that had not happened
-            // when it was written, and a same-subject commit landing afterwards is a
-            // different commit that happens to share a name.
+            // Backwards only: a commit can't revert something written after it, and
+            // a same-subject commit landing later just happens to share a name.
             const candidates = (bySubject.get(quoted) ?? []).filter((c) => c.timestamp < commit.timestamp);
             if (candidates.length === 1) {
                 const target = candidates[0];
@@ -157,10 +89,8 @@ export function detectIncidents(commits) {
             }
             continue;
         }
-        // An issue reference is a claim about a *defect*, made by the person who
-        // fixed it. Read from the subject anywhere and from the body only in
-        // trailer position — see `BODY_ISSUE` for the three false positives that
-        // distinction was measured against.
+        // An issue reference claims a defect. Read from the subject anywhere,
+        // from the body only in trailer position — see BODY_ISSUE's measurement.
         const refs = new Set();
         for (const match of commit.subject.matchAll(SUBJECT_ISSUE))
             refs.add(`#${match[1]}`);
@@ -176,8 +106,8 @@ export function detectIncidents(commits) {
             });
         }
     }
-    // Deterministic: two runs over the same history must produce a byte-identical
-    // batch, or the store's content hash moves for no reason.
+    // Deterministic: two runs must produce a byte-identical batch, or the
+    // store's content hash moves for no reason.
     incidents.sort((a, b) => a.fix.sha.localeCompare(b.fix.sha) || (a.issueRef ?? "").localeCompare(b.issueRef ?? ""));
     refusals.sort((a, b) => a.fixSha.localeCompare(b.fixSha) || a.rawTarget.localeCompare(b.rawTarget));
     unresolvedTrailers.sort((a, b) => a.fix.sha.localeCompare(b.fix.sha));

package/dist/sources/git/incidents.js.map

@@ -1 +1 @@
-{"version":3,"file":"incidents.js","sourceRoot":"","sources":["../../../src/sources/git/incidents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAiEH,uFAAuF;AACvF,MAAM,cAAc,GAAG,oCAAoC,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,GAAG,+DAA+D,CAAC;AAEpF,8EAA8E;AAC9E,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,SAAS,WAAW,yBAAyB,EAAE,IAAI,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,GAAG,IAAI,MAAM,CAAC,cAAc,WAAW,yBAAyB,EAAE,KAAK,CAAC,CAAC;AAEzF,SAAS,OAAO,CAAC,MAAc;IAC7B,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,MAAM,SAAS,GAAuB,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,MAAM,kBAAkB,GAAwB,EAAE,CAAC;IAEnD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC9C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,QAAQ,KAAK,SAAS;YAAE,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;;YAC/D,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,2EAA2E;QAC3E,yEAAyE;QACzE,qEAAqE;QACrE,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC1D,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACtC,IAAI,MAAM,KAAK,SAAS;gBAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;iBAC3E,CAAC;gBACJ,SAAS,CAAC,IAAI,CAAC;oBACb,SAAS,EAAE,iBAAiB;oBAC5B,GAAG,EAAE,MAAM;oBACX,cAAc,EAAE,MAAM;oBACtB,QAAQ,EAAE,IAAI;oBACd,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC;iBACjC,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACxD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,yEAAyE;YACzE,yEAAyE;YACzE,iDAAiD;YACjD,MAAM,UAAU,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/F,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAE,CAAC;gBAC9B,SAAS,CAAC,IAAI,CAAC;oBACb,SAAS,EAAE,eAAe;oBAC1B,GAAG,EAAE,MAAM;oBACX,cAAc,EAAE,MAAM;oBACtB,QAAQ,EAAE,IAAI;oBACd,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC;iBACjC,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACnC,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,MAAM,CAAC,GAAG;oBAClB,SAAS,EAAE,MAAM;oBACjB,MAAM,EACJ,qFAAqF;wBACrF,yFAAyF;iBAC5F,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,MAAM,CAAC,GAAG;oBAClB,SAAS,EAAE,MAAM;oBACjB,MAAM,EACJ,GAAG,UAAU,CAAC,MAAM,oEAAoE;wBACxF,gEAAgE;iBACnE,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QAED,yEAAyE;QACzE,qEAAqE;QACrE,yEAAyE;QACzE,oCAAoC;QACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;QACtF,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;QAChF,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACxC,SAAS,CAAC,IAAI,CAAC;gBACb,SAAS,EAAE,iBAAiB;gBAC5B,GAAG,EAAE,MAAM;gBACX,cAAc,EAAE,IAAI;gBACpB,QAAQ;gBACR,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC;aACjC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,0DAA0D;IAC1D,SAAS,CAAC,IAAI,CACZ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAC3F,CAAC;IACF,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACpG,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAEtE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,EAAE,CAAC;AACrD,CAAC;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"incidents.js","sourceRoot":"","sources":["../../../src/sources/git/incidents.ts"],"names":[],"mappings":"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"}

package/dist/sources/git/index.d.ts

@@ -1,9 +1,11 @@
 export { createGitSource, revertedShaOf, GIT_SOURCE_ID, GIT_SOURCE_VERSION, UNDIRECTED_EDGE_TYPES, } from "./source.ts";
 export type { GitSourceOptions } from "./source.ts";
-export { readHistory, gitHead, isGitRepository, filesInCommit, changedFiles, resolveCommitBySha, logForPath, } from "./history.ts";
+export { readHistory, gitHead, isGitRepository, GitUnavailableError, isPathTrackedByGit, filesInCommit, changedFiles, resolveCommitBySha, logForPath, } from "./history.ts";
 export type { Commit, CommitChange, HistoryOptions, PathLogCommit, PathLogOptions, PathLogResult, } from "./history.ts";
-export { gitDiff, gitWorkingTreeDiff, TOTAL_PATCH_BUDGET_REASON_PREFIX } from "./diff.ts";
-export type { GitDiffFile, GitDiffOptions, GitWorkingTreeDiffOptions } from "./diff.ts";
+export { addedLineRanges, gitDiff, gitWorkingTreeChange, gitWorkingTreeDiff, TOTAL_PATCH_BUDGET_REASON_PREFIX, } from "./diff.ts";
+export { uncommittedAmong, workingTreeChangedFiles } from "./history.ts";
+export type { WorkingTreeFilesOptions } from "./history.ts";
+export type { GitDiffFile, GitDiffOptions, GitWorkingTreeChange, GitWorkingTreeChangeOptions, GitWorkingTreeDiffOptions, LineRange, } from "./diff.ts";
 export { detectIncidents } from "./incidents.ts";
 export type { DetectedIncident, DetectedRefusal, IncidentDetection, IncidentMechanism, UnresolvedTrailer, } from "./incidents.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/sources/git/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sources/git/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EACL,WAAW,EACX,OAAO,EACP,eAAe,EACf,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,MAAM,EACN,YAAY,EACZ,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,gCAAgC,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAExF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sources/git/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EACL,WAAW,EACX,OAAO,EACP,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,MAAM,EACN,YAAY,EACZ,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,OAAO,EACP,oBAAoB,EACpB,kBAAkB,EAClB,gCAAgC,GACjC,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACzE,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EACV,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,EACzB,SAAS,GACV,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC"}

package/dist/sources/git/index.js

@@ -1,5 +1,6 @@
 export { createGitSource, revertedShaOf, GIT_SOURCE_ID, GIT_SOURCE_VERSION, UNDIRECTED_EDGE_TYPES, } from "./source.js";
-export { readHistory, gitHead, isGitRepository, filesInCommit, changedFiles, resolveCommitBySha, logForPath, } from "./history.js";
-export { gitDiff, gitWorkingTreeDiff, TOTAL_PATCH_BUDGET_REASON_PREFIX } from "./diff.js";
+export { readHistory, gitHead, isGitRepository, GitUnavailableError, isPathTrackedByGit, filesInCommit, changedFiles, resolveCommitBySha, logForPath, } from "./history.js";
+export { addedLineRanges, gitDiff, gitWorkingTreeChange, gitWorkingTreeDiff, TOTAL_PATCH_BUDGET_REASON_PREFIX, } from "./diff.js";
+export { uncommittedAmong, workingTreeChangedFiles } from "./history.js";
 export { detectIncidents } from "./incidents.js";
 //# sourceMappingURL=index.js.map

package/dist/sources/git/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sources/git/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,WAAW,EACX,OAAO,EACP,eAAe,EACf,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,UAAU,GACX,MAAM,cAAc,CAAC;AAUtB,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,gCAAgC,EAAE,MAAM,WAAW,CAAC;AAG1F,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sources/git/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,WAAW,EACX,OAAO,EACP,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,UAAU,GACX,MAAM,cAAc,CAAC;AAUtB,OAAO,EACL,eAAe,EACf,OAAO,EACP,oBAAoB,EACpB,kBAAkB,EAClB,gCAAgC,GACjC,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAWzE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/sources/git/source.d.ts

@@ -1,93 +1,23 @@
 /**
- * The git history `IRSource` — architecture §11.6 and §11.7.
- *
- * It is an `IRSource` and **not** a `LanguageAdapter`, which is the whole reason
- * that split exists: history is a producer of IR with no parser, no language and
- * no resolution beyond R0, and without the narrower interface it would need a
- * second write path — and a second write path is how un-provenanced rows reach
- * storage.
- *
- * ## Everything here is R0, and that is not a formality
- *
- * Co-change is not code analysis. It observes that two files were edited in the
- * same commit, which is evidence about *people*, not about program structure.
- * R0's confidence ceiling (DEC-019) therefore caps every edge this source emits
- * at 0.5, and §11A.5's reliability cap makes any finding resting on one Class C
- * — a behavioural prediction that must be live-confirmed or dropped. That is the
- * correct treatment: "these two files usually change together" is a hint for a
- * human, never a claim about what breaks.
- *
- * ## Precision over recall, applied three times
- *
- * 1. **Merge commits are excluded from co-change.** A merge's file list is the
- *    union of both branches, so counting it would report every file in a large
- *    merge as coupled to every other. This exclusion is scoped to co-change —
- *    it does **not** apply to resolving what a revert names (see below): a
- *    revert of "Merge pull request #N" is a real incident whose target
- *    happens to be a merge commit, and excluding it from co-change is not a
- *    reason to also make it unresolvable as an incident.
- * 2. **Large commits are excluded.** A commit touching hundreds of files is a
- *    reformat or a dependency bump; including it adds O(n²) edges that mean
- *    nothing.
- * 3. **Only explicit reverts become incidents.** A commit whose message merely
- *    contains "fix" is not evidence of an incident. `git revert` writes a
- *    machine-generated `This reverts commit <sha>.` line, and that is the only
- *    signal used.
- *
- * ## Resolving what a revert names
- *
- * `readHistory` indexes commits reachable from `HEAD`, minus merges. A revert
- * commit's target sha can miss that index for two reasons that have nothing to
- * do with whether the incident is real: the target is a merge commit (excluded
- * above), or the target was never merged as itself — a squash/rebase-merge
- * workflow (GitHub's default) discards the original commits and only the
- * squashed commit survives on `HEAD`, so "Revert PR #N" names a sha that is
- * either real-but-unreachable (still sitting on an abandoned branch) or
- * genuinely gone (garbage-collected after the branch was deleted). Measured
- * against 5 real repos, 6 of 9 real reverts fell into these two buckets and
- * were silently dropped by a naive index lookup.
- *
- * `resolveCommitBySha` is the fallback: it goes straight to the object
- * database (`git cat-file` / `git diff-tree`), which enforces neither
- * constraint `readHistory` applies. It resolves the merge case and the
- * unreachable-but-present case. Only the genuinely-gone case still fails, and
- * that failure is disclosed via `unresolved` (below) rather than dropped with
- * no trace — this is the fallback CLAUDE.md rule 7 requires labelling.
+ * Git history `IRSource` (§11.6/§11.7) — an `IRSource`, not a `LanguageAdapter`: one write path, no un-provenanced rows. Everything is R0; DEC-019 caps confidence at 0.5 and §11A.5 caps any finding at Class C — co-change is evidence about people, not code.
+ * Precision over recall: merge commits excluded from co-change (not from revert resolution below), large commits excluded, only explicit-revert trailers become incidents.
+ * `resolveCommitBySha` recovers reverts the primary index misses (6/9 real reverts, 5 repos, needed it); a genuinely-gone target is disclosed via `unresolved`, never dropped (rule 7).
  */
 import { type IRSource } from "@descryy/ir";
 import { type Commit, type HistoryOptions } from "./history.ts";
 export declare const GIT_SOURCE_ID = "git-history";
 export declare const GIT_SOURCE_VERSION = "0.1.0";
-/**
- * `CHANGES_WITH` is a symmetric relationship stored in one canonical direction.
- *
- * Emitting both directions would double the edge count and make the pair count
- * twice in any per-edge aggregate. The cost is that a caller must traverse it
- * undirected — `direction: "both"` — and forgetting that yields a *missing*
- * edge, which is a disclosed gap rather than a wrong answer. That asymmetry is
- * why this is the safe default and not the convenient one.
- */
+/** `CHANGES_WITH` is symmetric, stored one direction only — a caller must
+ *  traverse `direction: "both"`, or gets a disclosed missing edge, not a wrong one. */
 export declare const UNDIRECTED_EDGE_TYPES: readonly ["CHANGES_WITH"];
 export interface GitSourceOptions extends HistoryOptions {
     readonly repo: string;
     readonly cwd: string;
-    /**
-     * Minimum times two files must change together before an edge is emitted.
-     *
-     * **Provisional.** The architecture's own illustration is that 18x co-change
-     * is a warning and 2x is noise, which fixes the shape of the threshold but not
-     * its value; §32's tuning register has no number for it either. 5 is a
-     * defensible floor for a repo with a few hundred commits and is expected to
-     * move once measured. See DEC-033.
-     */
+    /** Minimum times two files must co-change before an edge is emitted.
+     *  Provisional — 5 is a defensible floor, expected to move once measured (DEC-033). */
     readonly minSupport?: number;
-    /**
-     * Minimum `support / timesTheSourceFileChanged`.
-     *
-     * Support alone over-reports the files that change constantly: a config file
-     * touched in half of all commits co-occurs with everything. Confidence is what
-     * separates "coupled" from "always busy".
-     */
+    /** Minimum `support / timesFileChanged` — support alone over-reports files
+     *  that change constantly; this separates "coupled" from "always busy". */
     readonly minConfidence?: number;
 }
 export declare function revertedShaOf(commit: Commit): string | null;

package/dist/sources/git/source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/sources/git/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAQL,KAAK,QAAQ,EAGd,MAAM,aAAa,CAAC;AAErB,OAAO,EAKL,KAAK,MAAM,EACX,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAGtB,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAC3C,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAG1C;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,2BAA4B,CAAC;AAE/D,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAiBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG3D;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,QAAQ,CA0WnE"}
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/sources/git/source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAQL,KAAK,QAAQ,EAGd,MAAM,aAAa,CAAC;AAErB,OAAO,EAKL,KAAK,MAAM,EACX,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAGtB,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAC3C,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAG1C;uFACuF;AACvF,eAAO,MAAM,qBAAqB,2BAA4B,CAAC;AAE/D,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;2FACuF;IACvF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;+EAC2E;IAC3E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAWD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG3D;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,QAAQ,CAkUnE"}

package/dist/sources/git/source.js

@@ -1,58 +1,7 @@
 /**
- * The git history `IRSource` — architecture §11.6 and §11.7.
- *
- * It is an `IRSource` and **not** a `LanguageAdapter`, which is the whole reason
- * that split exists: history is a producer of IR with no parser, no language and
- * no resolution beyond R0, and without the narrower interface it would need a
- * second write path — and a second write path is how un-provenanced rows reach
- * storage.
- *
- * ## Everything here is R0, and that is not a formality
- *
- * Co-change is not code analysis. It observes that two files were edited in the
- * same commit, which is evidence about *people*, not about program structure.
- * R0's confidence ceiling (DEC-019) therefore caps every edge this source emits
- * at 0.5, and §11A.5's reliability cap makes any finding resting on one Class C
- * — a behavioural prediction that must be live-confirmed or dropped. That is the
- * correct treatment: "these two files usually change together" is a hint for a
- * human, never a claim about what breaks.
- *
- * ## Precision over recall, applied three times
- *
- * 1. **Merge commits are excluded from co-change.** A merge's file list is the
- *    union of both branches, so counting it would report every file in a large
- *    merge as coupled to every other. This exclusion is scoped to co-change —
- *    it does **not** apply to resolving what a revert names (see below): a
- *    revert of "Merge pull request #N" is a real incident whose target
- *    happens to be a merge commit, and excluding it from co-change is not a
- *    reason to also make it unresolvable as an incident.
- * 2. **Large commits are excluded.** A commit touching hundreds of files is a
- *    reformat or a dependency bump; including it adds O(n²) edges that mean
- *    nothing.
- * 3. **Only explicit reverts become incidents.** A commit whose message merely
- *    contains "fix" is not evidence of an incident. `git revert` writes a
- *    machine-generated `This reverts commit <sha>.` line, and that is the only
- *    signal used.
- *
- * ## Resolving what a revert names
- *
- * `readHistory` indexes commits reachable from `HEAD`, minus merges. A revert
- * commit's target sha can miss that index for two reasons that have nothing to
- * do with whether the incident is real: the target is a merge commit (excluded
- * above), or the target was never merged as itself — a squash/rebase-merge
- * workflow (GitHub's default) discards the original commits and only the
- * squashed commit survives on `HEAD`, so "Revert PR #N" names a sha that is
- * either real-but-unreachable (still sitting on an abandoned branch) or
- * genuinely gone (garbage-collected after the branch was deleted). Measured
- * against 5 real repos, 6 of 9 real reverts fell into these two buckets and
- * were silently dropped by a naive index lookup.
- *
- * `resolveCommitBySha` is the fallback: it goes straight to the object
- * database (`git cat-file` / `git diff-tree`), which enforces neither
- * constraint `readHistory` applies. It resolves the merge case and the
- * unreachable-but-present case. Only the genuinely-gone case still fails, and
- * that failure is disclosed via `unresolved` (below) rather than dropped with
- * no trace — this is the fallback CLAUDE.md rule 7 requires labelling.
+ * Git history `IRSource` (§11.6/§11.7) — an `IRSource`, not a `LanguageAdapter`: one write path, no un-provenanced rows. Everything is R0; DEC-019 caps confidence at 0.5 and §11A.5 caps any finding at Class C — co-change is evidence about people, not code.
+ * Precision over recall: merge commits excluded from co-change (not from revert resolution below), large commits excluded, only explicit-revert trailers become incidents.
+ * `resolveCommitBySha` recovers reverts the primary index misses (6/9 real reverts, 5 repos, needed it); a genuinely-gone target is disclosed via `unresolved`, never dropped (rule 7).
  */
 import { edgeId, fileQsp, nodeId, } from "@descryy/ir";
 import { gitHead, isGitRepository, readHistory, resolveCommitBySha, } from "./history.js";
@@ -60,24 +9,11 @@ import { detectIncidents } from "./incidents.js";
 export const GIT_SOURCE_ID = "git-history";
 export const GIT_SOURCE_VERSION = "0.1.0";
 const PRODUCED_BY = `${GIT_SOURCE_ID}@${GIT_SOURCE_VERSION}`;
-/**
- * `CHANGES_WITH` is a symmetric relationship stored in one canonical direction.
- *
- * Emitting both directions would double the edge count and make the pair count
- * twice in any per-edge aggregate. The cost is that a caller must traverse it
- * undirected — `direction: "both"` — and forgetting that yields a *missing*
- * edge, which is a disclosed gap rather than a wrong answer. That asymmetry is
- * why this is the safe default and not the convenient one.
- */
+/** `CHANGES_WITH` is symmetric, stored one direction only — a caller must
+ *  traverse `direction: "both"`, or gets a disclosed missing edge, not a wrong one. */
 export const UNDIRECTED_EDGE_TYPES = ["CHANGES_WITH"];
-/**
- * Detect a revert and the commit it reverted.
- *
- * `git revert` writes `This reverts commit <40 hex>.` into the body. Nothing
- * else is trusted: matching on the word "fix" would classify ordinary work as an
- * incident, and an `INCIDENT` node is a durable, earned fact (DEC-017) that
- * outlives every rebuild.
- */
+/** Detects a revert and the commit it reverted, via `git revert`'s machine-written
+ *  trailer only — an `INCIDENT` node is a durable, earned fact (DEC-017). */
 const REVERTS = /This reverts commit ([0-9a-f]{40})/;
 export function revertedShaOf(commit) {
     const match = REVERTS.exec(commit.body);
@@ -92,18 +28,15 @@ export function createGitSource(options) {
         async emit(ctx) {
             const repo = options.repo || ctx.root.repo;
             const cwd = options.cwd;
-            // INCIDENT and FIX_PATTERN are workspace-scoped (DEC-054), FILE is
-            // repo-scoped, and `scopeOf` picks between them per type — this source does
-            // not choose, and must not.
+            // INCIDENT/FIX_PATTERN are workspace-scoped (DEC-054), FILE repo-scoped.
             const scope = { repo, workspace: ctx.root.workspace };
             if (!(await isGitRepository(cwd))) {
-                // Not an error. A repo with no history is a repo about which this source
-                // has nothing to say, and an empty batch says exactly that.
+                // Not an error — a repo with no history has nothing to say here.
                 return emptyBatch(repo, ctx.root.workspace, ctx.root.commitSha);
             }
             const commits = await readHistory(cwd, options);
             const head = await gitHead(cwd);
-            // --- co-change (§11.7) ------------------------------------------------
+            // Co-change (§11.7).
             const fileChanges = new Map();
             const pairs = new Map();
             const touched = new Set();
@@ -128,28 +61,17 @@ export function createGitSource(options) {
                     }
                 }
             }
-            // --- incidents (§11.6) ------------------------------------------------
+            // Incidents (§11.6).
             const maxFilesPerCommit = options.maxFilesPerCommit ?? 50;
-            // Which commits describe a failure, and how we know — `incidents.ts`.
-            // Three mechanisms now, all of them resting on something a person
-            // declared: the trailer `git revert` writes, the `Revert "…"` subject a
-            // person or GitHub's own button writes, and a `Fixes #123` a developer
-            // wrote to say something was broken. Nothing here reads "fix" out of
-            // prose; see that module's header for why an EARNED node cannot be minted
-            // from an inference.
+            // Three declared mechanisms (incidents.ts): a revert trailer, a `Revert
+            // "…"` subject, or a `Fixes #123` — never inferred from prose like "fix".
             const detected = detectIncidents(commits);
             const incidents = [...detected.incidents];
-            // A revert whose target sha could not be resolved by any means — real,
-            // per the commit's own machine-generated message, but with no commit to
-            // hang an INCIDENT on. Disclosed via `unresolved`, never dropped with no
-            // trace (CLAUDE.md rule 7).
+            // Real per the commit's own message but unresolvable to a commit — disclosed
+            // via `unresolved`, never silently dropped (rule 7).
             const unresolvedReverts = [];
             for (const trailer of detected.unresolvedTrailers) {
-                // Not in the primary, HEAD-reachable, --no-merges index. Try the
-                // object database directly before giving up — see the module doc's
-                // "Resolving what a revert names". `detectIncidents` is synchronous and
-                // cannot do this, which is why it hands the case back rather than
-                // refusing it itself.
+                // Not in the primary index — try the object database (see module doc).
                 const reverted = await resolveCommitBySha(cwd, trailer.revertedSha, maxFilesPerCommit);
                 if (reverted === null) {
                     unresolvedReverts.push({
@@ -168,9 +90,8 @@ export function createGitSource(options) {
                     correlatedPaths: [...new Set(reverted.changes.map((c) => c.path))].sort(),
                 });
             }
-            // A `Revert "…"` whose quoted subject this history does not contain, or
-            // contains twice. Not resolvable out of band the way a sha is — a subject
-            // is not an identity — so these are refusals as detected.
+            // A quoted subject not found (or found twice) — a subject isn't an
+            // identity, so unresolvable out of band, unlike a sha.
             for (const refusal of detected.refusals) {
                 const fix = commits.find((c) => c.sha === refusal.fixSha);
                 if (fix === undefined)
@@ -182,7 +103,7 @@ export function createGitSource(options) {
                 for (const path of found.correlatedPaths)
                     touched.add(path);
             }
-            // --- nodes ------------------------------------------------------------
+            // Nodes.
             const nodes = [];
             const sourceFiles = [...touched].sort();
             for (const path of sourceFiles) {
@@ -192,26 +113,16 @@ export function createGitSource(options) {
                     name: path.split("/").pop() ?? path,
                     file: path,
                     range: null,
-                    // History cannot tell what language a file is written in, and guessing
-                    // from the extension would be a language decision made by a source
-                    // that has no business making one (DEC-026).
+                    // Guessing language from the extension would be a language decision
+                    // made by a source with no business making one (DEC-026).
                     language: null,
                     producedBy: PRODUCED_BY,
                     resolution: 0,
                     attrs: { changeCount: fileChanges.get(path) ?? 0 },
                 });
             }
-            /**
-             * One incident can be reached by more than one fix — two commits both
-             * saying `Fixes #7` are one defect fixed twice, not two defects. So the
-             * `INCIDENT` node is keyed and emitted once; the `FIX_PATTERN` and the
-             * `FIXED_BY` edge are per-fix.
-             *
-             * The issue form's qualified symbol path carries the repository even
-             * though `INCIDENT` is workspace-scoped (DEC-054), because `#123` in one
-             * repository is not `#123` in another and a bare number would collide two
-             * unrelated defects into one node across a linked workspace.
-             */
+            /** One incident, multiple fixes — `INCIDENT` keyed and emitted once, `FIX_PATTERN`
+             *  per-fix. Issue id carries the repo (DEC-054) so `#123` doesn't collide across repos. */
             const incidentIdOf = (found) => found.incidentCommit !== null
                 ? nodeId(scope, "INCIDENT", found.incidentCommit.sha, null)
                 : nodeId(scope, "INCIDENT", `issue:${repo}${found.issueRef ?? ""}`, null);
@@ -239,10 +150,7 @@ export function createGitSource(options) {
                     : {
                         id,
                         type: "INCIDENT",
-                        // The issue reference and nothing more. Descry reads no tracker
-                        // and must not imply it knows the issue's title, or even that
-                        // the issue was filed as a defect — only that the developer who
-                        // closed it said their commit fixed something.
+                        // Issue reference only — no tracker is read, so no title or defect status is implied.
                         name: `${repo}${found.issueRef ?? ""}`,
                         file: null,
                         range: null,
@@ -275,13 +183,9 @@ export function createGitSource(options) {
                     },
                 });
             }
-            // The fix commit is real and independently verifiable (it exists, its
-            // sha and message are facts) even when its target is not — so it still
-            // earns a FIX_PATTERN node. What it does NOT get is an INCIDENT, a
-            // FIXED_BY edge or any INCIDENT_CORRELATED edge, because none of those
-            // can be built without a resolved target. The gap is recorded below in
-            // `unresolved`, not implied by a node that silently has no incoming
-            // FIXED_BY edge.
+            // The fix commit is real, so it earns a FIX_PATTERN node — but no INCIDENT,
+            // FIXED_BY or INCIDENT_CORRELATED edge, since none can be built without a
+            // resolved target; the gap is recorded in `unresolved` instead.
             for (const { fix } of unresolvedReverts) {
                 nodes.push({
                     id: nodeId(scope, "FIX_PATTERN", fix.sha, null),
@@ -295,7 +199,7 @@ export function createGitSource(options) {
                     attrs: { commitSha: fix.sha, revertedShaUnresolved: true },
                 });
             }
-            // --- edges ------------------------------------------------------------
+            // Edges.
             const nodeIds = new Set(nodes.map((n) => n.id));
             const edges = [];
             const unresolved = [];
@@ -313,9 +217,8 @@ export function createGitSource(options) {
                     to: nodeId(scope, "FILE", fileQsp(b), null),
                     type: "CHANGES_WITH",
                     resolution: 0,
-                    // Clamped to the R0 ceiling by the Normaliser. Passing the raw ratio
-                    // and letting it clamp is deliberate — the clamp is recorded, so the
-                    // graph shows that history was capped rather than that it was weak.
+                    // Raw ratio passed through; the Normaliser's R0 clamp is recorded,
+                    // showing history was capped rather than weak.
                     confidence,
                     producedBy: PRODUCED_BY,
                     attrs: {
@@ -339,9 +242,8 @@ export function createGitSource(options) {
                     attrs: { commitSha: fix.sha, refusalClass: "capability-gap" },
                 });
             }
-            // One INCIDENT_CORRELATED edge set per incident, not per fix: two commits
-            // closing one issue would otherwise write the same file edge twice, and
-            // the second write says nothing the first did not.
+            // Per incident, not per fix — two commits closing one issue would
+            // otherwise write the same file edge twice.
             const correlated = new Set();
             for (const found of incidents) {
                 const incidentId = incidentIdOf(found);
@@ -391,9 +293,7 @@ export function createGitSource(options) {
                     });
                 }
             }
-            // Deterministic ordering. Two runs over the same history must produce a
-            // byte-identical batch, or the store's content hash moves for no reason
-            // and the Step 6 determinism proof stops meaning anything.
+            // Deterministic ordering — two runs must produce a byte-identical batch.
             nodes.sort((a, b) => a.id.localeCompare(b.id));
             edges.sort((a, b) => edgeId(a.from, a.to, a.type).localeCompare(edgeId(b.from, b.to, b.type)));
             unresolved.sort((a, b) => `${a.fromNodeId}${a.rawTarget}`.localeCompare(`${b.fromNodeId}${b.rawTarget}`));