@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/internal/EvidenceFingerprintIndex.js

@@ -2,26 +2,64 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceFingerprintIndex = void 0;
 const node_crypto_1 = require("node:crypto");
-const InventoryMerge_1 = require("./InventoryMerge");
-const VERSION = 1;
+const EvidenceInventoryMerge_1 = require("./EvidenceInventoryMerge");
+const VERSION = 2;
 const PRESENTED_LENGTH = 7;
 /**
- * Computes and memoizes stable fingerprints for inventory units and descendants.
+ * Computes and memoizes stable fingerprints for inventory units and
+ * descendants.
  *
  * Fingerprints exclude annotation text and presentation-only whitespace so an
  * acknowledgement edit does not look like a specification change. The index
  * owns only references to the immutable analysis inventory.
  */
 class EvidenceFingerprintIndex {
+    /**
+     * Annotation ranges grouped by their physical source file.
+     *
+     * Content hashing removes these mapped spans while preserving surrounding
+     * semantic source text.
+     */
     annotations = new Map();
+    /**
+     * Structurally owned child units grouped by parent identity.
+     *
+     * Subtree fingerprints traverse this index without rescanning the inventory.
+     */
     children = new Map();
+    /**
+     * Memoized content digest for each process-local unit identity.
+     *
+     * A single inventory snapshot owns the index, so unit IDs are safe cache keys
+     * even though the resulting digest excludes them.
+     */
     contentDigests = new Map();
+    /**
+     * Memoized public fingerprint result for each unit identity.
+     *
+     * Repeated review checks reuse both the presented prefix and full scope hash.
+     */
     fingerprints = new Map();
+    /**
+     * Source snapshots indexed by physical path for site content lookup.
+     *
+     * Fingerprint identity is read from each snapshot's checkout-stable declaring
+     * path after the physical site resolves here.
+     */
     sources = new Map();
+    /**
+     * Semantic units indexed by their process-local graph identity.
+     *
+     * Public callers request a unit by this ID before hashing replaces it with a
+     * portable declaration identity.
+     */
     units = new Map();
-    /** Builds source, annotation, and parent indexes once for one inventory snapshot.
+    /**
+     * Builds source, annotation, and parent indexes once for one inventory
+     * snapshot.
      *
-     * Fingerprint generation reuses these indexes to connect units to their physical content without repeatedly scanning inventory collections.
+     * Fingerprint generation reuses these indexes to connect units to their
+     * physical content without repeatedly scanning inventory collections.
      */
     constructor(inventory) {
         for (const source of inventory.sources)
@@ -47,7 +85,8 @@ class EvidenceFingerprintIndex {
         }
     }
     /**
-     * Returns the root content digest and subtree scope digest for one semantic identity.
+     * Returns the root content digest and subtree scope digest for one semantic
+     * identity.
      *
      * Unknown identities fail rather than producing an empty fingerprint, because
      * absence would make a stale graph appear unchanged.
@@ -60,18 +99,18 @@ class EvidenceFingerprintIndex {
         if (root === undefined)
             throw new Error(`Cannot fingerprint unknown semantic identity: ${unitId}`);
         const scope = this.collect(root).sort((x, y) => {
-            const identity = InventoryMerge_1.InventoryMerge.compare(x.id, y.id);
+            const identity = EvidenceInventoryMerge_1.EvidenceInventoryMerge.compare(this.identity(x), this.identity(y));
             if (identity !== 0)
                 return identity;
-            const symbol = InventoryMerge_1.InventoryMerge.compare(x.symbol, y.symbol);
+            const symbol = EvidenceInventoryMerge_1.EvidenceInventoryMerge.compare(x.symbol, y.symbol);
             return symbol !== 0
                 ? symbol
-                : InventoryMerge_1.InventoryMerge.compare(this.contentDigest(x), this.contentDigest(y));
+                : EvidenceInventoryMerge_1.EvidenceInventoryMerge.compare(this.contentDigest(x), this.contentDigest(y));
         });
         const hash = (0, node_crypto_1.createHash)("sha256");
-        hash.update(`@wrtnlabs/evidence:fingerprint:${VERSION}\0`);
+        hash.update(`evidence:fingerprint:${VERSION}\0`);
         for (const unit of scope) {
-            hash.update(unit.id);
+            hash.update(this.identity(unit));
             hash.update("\0");
             hash.update(unit.symbol);
             hash.update("\0");
@@ -89,9 +128,82 @@ class EvidenceFingerprintIndex {
         this.fingerprints.set(unitId, output);
         return output;
     }
-    /** Collects a cycle-safe structural subtree for one unit.
+    /**
+     * Describes a semantic declaration without process-local source or site IDs.
      *
-     * The visited set prevents malformed parent links from looping fingerprint generation while preserving each reachable child once.
+     * Each adapter's unit ID already decides whether a file, package, library, or
+     * schema owns semantic identity. Rewriting its physical tokens preserves that
+     * boundary: file-scoped declarations keep a portable path, while database
+     * declarations designed to survive file moves do not acquire a new one.
+     */
+    identity(unit) {
+        return JSON.stringify([
+            unit.type,
+            unit.type === "markdown"
+                ? this.declaringPaths(unit)
+                : this.portableUnitId(unit),
+            unit.symbol,
+            unit.identity,
+        ]);
+    }
+    /**
+     * Collects portable paths for Markdown's position-bearing unit IDs.
+     *
+     * Heading offsets are physical parser coordinates rather than semantic
+     * identity. Markdown declarations remain file-scoped, so their declaring
+     * paths replace that unstable suffix while still distinguishing equal anchors
+     * in separate files.
+     */
+    declaringPaths(unit) {
+        return EvidenceInventoryMerge_1.EvidenceInventoryMerge.unique(unit.sites.map((site) => {
+            const source = this.sources.get(site.file);
+            if (source === undefined)
+                throw new Error(`Cannot fingerprint missing source snapshot: ${site.file}`);
+            return source.fingerprintPath;
+        }), (value) => value).sort(EvidenceInventoryMerge_1.EvidenceInventoryMerge.compare);
+    }
+    /**
+     * Rewrites one adapter-owned unit ID into checkout-stable source coordinates.
+     *
+     * Source IDs may contain inode data, and several language resolvers retain an
+     * absolute source or module root in their semantic key. One longest-token
+     * pass keeps overlapping identities independent and prevents generated
+     * markers from participating in later replacements.
+     */
+    portableUnitId(unit) {
+        const sources = Array.from(this.sources.values());
+        const replacements = [];
+        for (const source of sources) {
+            const marker = `@source:${JSON.stringify(source.fingerprintPath)}`;
+            replacements.push([source.id, marker]);
+            replacements.push([
+                source.physicalPath,
+                `@file:${source.fingerprintPath}`,
+            ]);
+            if (source.fingerprintRoot !== undefined)
+                replacements.push([
+                    source.fingerprintRoot.physicalPath,
+                    `@root:${JSON.stringify(source.fingerprintRoot.fingerprintPath)}`,
+                ]);
+        }
+        const roots = EvidenceInventoryMerge_1.EvidenceInventoryMerge.unique(sources.flatMap((source) => {
+            if (source.fingerprintRoot !== undefined)
+                return [];
+            const suffix = `/${source.fingerprintPath}`;
+            return source.physicalPath.endsWith(suffix)
+                ? [source.physicalPath.slice(0, -suffix.length)]
+                : [];
+        }), (value) => value);
+        for (const root of roots)
+            if (root !== "")
+                replacements.push([root, "@root"]);
+        return replacePortableTokens(unit.id, replacements);
+    }
+    /**
+     * Collects a cycle-safe structural subtree for one unit.
+     *
+     * The visited set prevents malformed parent links from looping fingerprint
+     * generation while preserving each reachable child once.
      */
     collect(root) {
         const output = [];
@@ -107,19 +219,25 @@ class EvidenceFingerprintIndex {
         }
         return output;
     }
-    /** Adds withdrawal tags to the content contribution because they alter effective scope.
+    /**
+     * Adds withdrawal tags to the content contribution because they alter
+     * effective scope.
      *
-     * A unit's fingerprint must change when a withdrawal changes which declarations remain active, even if its source range is unchanged.
+     * A unit's fingerprint must change when a withdrawal changes which
+     * declarations remain active, even if its source range is unchanged.
      */
     contribution(unit) {
-        const withdrawals = InventoryMerge_1.InventoryMerge.unique(unit.withdrawals.map((withdrawal) => withdrawal.tag), (tag) => tag);
+        const withdrawals = EvidenceInventoryMerge_1.EvidenceInventoryMerge.unique(unit.withdrawals.map((withdrawal) => withdrawal.tag), (tag) => tag);
         return withdrawals.length === 0
             ? this.contentDigest(unit)
             : `${this.contentDigest(unit)}\0withdrawn:${withdrawals.join(",")}`;
     }
-    /** Hashes source sites after stripping mapped annotations and normalizing presentation differences.
+    /**
+     * Hashes source sites after stripping annotations and presentation
+     * differences.
      *
-     * Annotation edits are tracked separately, while substantive source changes remain stable across line-ending and trailing-space differences.
+     * Annotation edits are tracked separately, while substantive source changes
+     * remain stable across line-ending and trailing-space differences.
      */
     contentDigest(unit) {
         if (unit.contentDigest !== undefined)
@@ -128,17 +246,15 @@ class EvidenceFingerprintIndex {
         if (remembered !== undefined)
             return remembered;
         const parts = [];
-        const sites = [...unit.sites].sort((x, y) => InventoryMerge_1.InventoryMerge.compare(JSON.stringify([
-            x.file,
-            x.range.start.offset,
-            x.range.end.offset,
-            x.id,
-        ]), JSON.stringify([
-            y.file,
-            y.range.start.offset,
-            y.range.end.offset,
-            y.id,
-        ])));
+        const sites = [...unit.sites].sort((x, y) => {
+            const left = this.sources.get(x.file);
+            const right = this.sources.get(y.file);
+            const identity = EvidenceInventoryMerge_1.EvidenceInventoryMerge.compare(left?.fingerprintPath ?? x.file, right?.fingerprintPath ?? y.file);
+            if (identity !== 0)
+                return identity;
+            const start = x.range.start.offset - y.range.start.offset;
+            return start !== 0 ? start : x.range.end.offset - y.range.end.offset;
+        });
         for (const site of sites) {
             const source = this.sources.get(site.file);
             if (source === undefined)
@@ -154,9 +270,11 @@ class EvidenceFingerprintIndex {
         this.contentDigests.set(unit.id, digest);
         return digest;
     }
-    /** Removes only overlapping annotation spans while retaining surrounding source exactly for semantic hashing.
+    /**
+     * Removes overlapping annotation spans while retaining surrounding source.
      *
-     * Ranges are ordered before removal so adjacent or overlapping tags cannot duplicate or erase unrelated source fragments.
+     * Ranges are ordered before removal so adjacent or overlapping tags cannot
+     * duplicate or erase unrelated source fragments.
      */
     withoutAnnotations(source, range) {
         let cursor = range.start.offset;
@@ -177,17 +295,72 @@ class EvidenceFingerprintIndex {
     }
 }
 exports.EvidenceFingerprintIndex = EvidenceFingerprintIndex;
-/** Orders source spans by position before content fragments are concatenated.
+/**
+ * Replaces process-local identity tokens without revisiting generated text.
  *
- * Stable ordering makes a fingerprint independent of adapter collection order for sites in the same file.
+ * At each original input position, the longest matching token wins. Equal
+ * tokens must agree on their stable value so source collection order cannot
+ * choose a fingerprint silently.
+ */
+function replacePortableTokens(input, replacements) {
+    const unique = new Map();
+    for (const [token, value] of replacements) {
+        if (token === "")
+            continue;
+        const previous = unique.get(token);
+        if (previous !== undefined && previous !== value)
+            throw new Error(`Cannot fingerprint ambiguous portable token: ${JSON.stringify(token)}`);
+        unique.set(token, value);
+    }
+    const ordered = Array.from(unique.entries()).sort((left, right) => {
+        const lengthDifference = right[0].length - left[0].length;
+        return lengthDifference !== 0
+            ? lengthDifference
+            : EvidenceInventoryMerge_1.EvidenceInventoryMerge.compare(left[0], right[0]);
+    });
+    if (ordered.length === 0)
+        return input;
+    let output = "";
+    let cursor = 0;
+    while (cursor < input.length) {
+        let selected;
+        let selectedAt = -1;
+        for (const candidate of ordered) {
+            const found = input.indexOf(candidate[0], cursor);
+            if (found < 0)
+                continue;
+            if (selected === undefined ||
+                found < selectedAt ||
+                (found === selectedAt && candidate[0].length > selected[0].length)) {
+                selected = candidate;
+                selectedAt = found;
+            }
+        }
+        if (selected === undefined) {
+            output += input.slice(cursor);
+            break;
+        }
+        output += input.slice(cursor, selectedAt) + selected[1];
+        cursor = selectedAt + selected[0].length;
+    }
+    return output;
+}
+/**
+ * Orders source spans by position before content fragments are concatenated.
+ *
+ * Stable ordering makes a fingerprint independent of adapter collection order
+ * for sites in the same file.
  */
 function compareRanges(x, y) {
     const start = x.start.offset - y.start.offset;
     return start !== 0 ? start : x.end.offset - y.end.offset;
 }
-/** Normalizes line endings and trailing whitespace without changing interior source content.
+/**
+ * Normalizes line endings and trailing whitespace without changing interior
+ * source content.
  *
- * Fingerprints ignore presentation differences that do not affect the authored declaration body.
+ * Fingerprints ignore presentation differences that do not affect the authored
+ * declaration body.
  */
 function normalize(text) {
     const lines = text

package/lib/internal/EvidenceInventoryMerge.d.ts

@@ -0,0 +1,60 @@
+import type { IEvidenceInventory } from "../structures/IEvidenceInventory";
+import type { IEvidenceSourceAddress } from "../structures/IEvidenceSourceAddress";
+import type { IEvidenceUnitSite } from "../structures/IEvidenceUnitSite";
+/**
+ * Combines compatible adapter inventories into one analysis snapshot.
+ *
+ * Conflicts mark the result incomplete instead of choosing whichever adapter
+ * happened to run first, preserving the failure boundary for graph evaluation.
+ */
+export declare namespace EvidenceInventoryMerge {
+    /**
+     * Merges compatible source, unit, host, and declaration records into one
+     * inventory.
+     *
+     * Conflicting semantic identities remain diagnostics and mark the merged
+     * result incomplete, so input order cannot select an arbitrary graph
+     * population.
+     */
+    function combine(inputs: IEvidenceInventory[]): IEvidenceInventory;
+    /**
+     * Deduplicates values by semantic key and orders the result
+     * deterministically.
+     *
+     * Later records replace earlier records for the same key before bytewise key
+     * ordering removes source traversal order from serialized output.
+     */
+    function unique<T>(values: T[], key: (value: T) => string): T[];
+    /**
+     * Compares opaque identity strings without locale-dependent ordering.
+     *
+     * Inventory serialization uses this bytewise relation so the same graph sorts
+     * identically across machines with different locale settings.
+     */
+    function compare(x: string, y: string): number;
+    /**
+     * Deduplicates source addresses while preserving direct selection over
+     * dependency loading.
+     *
+     * When equivalent addresses collide, a selected address clears the dependency
+     * marker because it represents part of the configured public population.
+     */
+    function sourceAddresses(values: IEvidenceSourceAddress[]): IEvidenceSourceAddress[];
+    /**
+     * Serializes structural site identity without its independently merged
+     * content spans.
+     *
+     * Unit merging compares this key before unioning content ranges, so
+     * compatible declarations share a physical host without requiring identical
+     * extraction order.
+     */
+    function siteKey(site: IEvidenceUnitSite): string;
+    /**
+     * Serializes deduplicated content ranges for source-order-independent
+     * conflict detection.
+     *
+     * The range values are normalized through {@link unique} before a shared site
+     * can be accepted as equivalent across inventories.
+     */
+    function contentKey(site: IEvidenceUnitSite): string;
+}