@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/internal/EvidenceConfigFormat.d.ts

@@ -1,11 +1,16 @@
-/** Selects the evaluator supported by a configuration filename's explicit extension.
+/**
+ * Selects the evaluator supported by a configuration filename's explicit
+ * extension.
  *
- * Config loading calls this boundary before parsing so file content never changes the evaluator selected for a path.
+ * Config loading calls this boundary before parsing so file content never
+ * changes the evaluator selected for a path.
  */
 export declare namespace EvidenceConfigFormat {
-    /** Returns the evaluator selected by an explicit supported filename extension.
+    /**
+     * Returns the evaluator selected by an explicit supported filename extension.
      *
-     * Unsupported spellings fail here instead of causing configuration loading to guess a parser from file content.
+     * Unsupported spellings fail here instead of causing configuration loading to
+     * guess a parser from file content.
      */
     function get(file: string): "json" | "typescript";
 }

package/lib/internal/EvidenceConfigFormat.js

@@ -2,15 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceConfigFormat = void 0;
 const node_path_1 = require("node:path");
-/** Selects the evaluator supported by a configuration filename's explicit extension.
+/**
+ * Selects the evaluator supported by a configuration filename's explicit
+ * extension.
  *
- * Config loading calls this boundary before parsing so file content never changes the evaluator selected for a path.
+ * Config loading calls this boundary before parsing so file content never
+ * changes the evaluator selected for a path.
  */
 var EvidenceConfigFormat;
 (function (EvidenceConfigFormat) {
-    /** Returns the evaluator selected by an explicit supported filename extension.
+    /**
+     * Returns the evaluator selected by an explicit supported filename extension.
      *
-     * Unsupported spellings fail here instead of causing configuration loading to guess a parser from file content.
+     * Unsupported spellings fail here instead of causing configuration loading to
+     * guess a parser from file content.
      */
     function get(file) {
         const extension = (0, node_path_1.extname)(file);

package/lib/internal/EvidenceConfigModuleMode.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Node condition set used by one configuration module request.
+ *
+ * The dependency scanner carries this distinction from syntax into package
+ * resolution so its watch set names the same entry that the config evaluator
+ * executes. Losing it would turn an ESM import into a CommonJS observation.
+ */
+export type EvidenceConfigModuleMode = "import" | "require";

package/lib/internal/EvidenceConfigPackageMainError.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Marks an explicit CommonJS package main that exhausted its runtime fallbacks.
+ *
+ * A missing default index permits CommonJS lookup to try the next
+ * `node_modules` root. Once a manifest explicitly selects `main`, Node instead
+ * reports that package as broken after its own index fallback also fails.
+ */
+export declare class EvidenceConfigPackageMainError extends Error {
+    /**
+     * Creates an authoritative failure for one explicit legacy `main` target.
+     *
+     * The original resolution cause remains available to diagnostics while this
+     * error type prevents ancestor `node_modules` fallback from hiding the broken
+     * package selected at the current search root.
+     */
+    constructor(directory: string, target: string, cause: unknown);
+}

package/lib/internal/EvidenceConfigPackageMainError.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceConfigPackageMainError = void 0;
+/**
+ * Marks an explicit CommonJS package main that exhausted its runtime fallbacks.
+ *
+ * A missing default index permits CommonJS lookup to try the next
+ * `node_modules` root. Once a manifest explicitly selects `main`, Node instead
+ * reports that package as broken after its own index fallback also fails.
+ */
+class EvidenceConfigPackageMainError extends Error {
+    /**
+     * Creates an authoritative failure for one explicit legacy `main` target.
+     *
+     * The original resolution cause remains available to diagnostics while this
+     * error type prevents ancestor `node_modules` fallback from hiding the broken
+     * package selected at the current search root.
+     */
+    constructor(directory, target, cause) {
+        super(`Package '${directory}' declares an unusable main target '${target}'.`, { cause });
+        this.name = "EvidenceConfigPackageMainError";
+    }
+}
+exports.EvidenceConfigPackageMainError = EvidenceConfigPackageMainError;

package/lib/internal/EvidenceConfigPackageTargetError.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Marks one invalid package-map target that an array alternative may skip.
+ *
+ * Node permits array fallbacks after target-validation failures but still
+ * rejects malformed condition objects. EvidenceConfigDependencyScanner uses
+ * this error boundary to preserve that distinction without matching diagnostic
+ * text.
+ */
+export declare class EvidenceConfigPackageTargetError extends Error {
+    /**
+     * Creates a skippable target failure while retaining its validation cause.
+     *
+     * The original cause remains available when no later array alternative can be
+     * selected and the scanner must expose the package-resolution failure.
+     */
+    constructor(message: string, cause?: unknown);
+}

package/lib/internal/EvidenceConfigPackageTargetError.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceConfigPackageTargetError = void 0;
+/**
+ * Marks one invalid package-map target that an array alternative may skip.
+ *
+ * Node permits array fallbacks after target-validation failures but still
+ * rejects malformed condition objects. EvidenceConfigDependencyScanner uses
+ * this error boundary to preserve that distinction without matching diagnostic
+ * text.
+ */
+class EvidenceConfigPackageTargetError extends Error {
+    /**
+     * Creates a skippable target failure while retaining its validation cause.
+     *
+     * The original cause remains available when no later array alternative can be
+     * selected and the scanner must expose the package-resolution failure.
+     */
+    constructor(message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "EvidenceConfigPackageTargetError";
+    }
+}
+exports.EvidenceConfigPackageTargetError = EvidenceConfigPackageTargetError;

package/lib/internal/EvidenceFileGlob.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Matches the restricted Evidence glob language: `*`, `**`, `?`, and ordered
+ * negation.
+ *
+ * The matcher operates on portable path segments, keeping selection independent
+ * of host separator conventions and refusing patterns that escape a population
+ * root.
+ */
+export declare class EvidenceFileGlob {
+    private readonly patterns;
+    /**
+     * Compiles ordered patterns and requires at least one positive selection
+     * baseline.
+     *
+     * A population with only exclusions would have no defined initial set, so
+     * configuration validation rejects it at construction.
+     */
+    constructor(patterns: readonly string[]);
+    /**
+     * Applies every matching pattern in declaration order.
+     *
+     * Later matching positives or exclusions replace the inclusion decision made
+     * by earlier patterns.
+     */
+    matches(location: string): boolean;
+    /**
+     * Determines whether a directory can contain a selected descendant.
+     *
+     * Discovery uses this conservative result to prune traversal without
+     * excluding descendants restored by a later positive pattern.
+     */
+    couldMatchDescendant(directory: string): boolean;
+}

package/lib/internal/EvidenceFileGlob.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceFileGlob = void 0;
+/**
+ * Matches the restricted Evidence glob language: `*`, `**`, `?`, and ordered
+ * negation.
+ *
+ * The matcher operates on portable path segments, keeping selection independent
+ * of host separator conventions and refusing patterns that escape a population
+ * root.
+ */
+class EvidenceFileGlob {
+    patterns;
+    /**
+     * Compiles ordered patterns and requires at least one positive selection
+     * baseline.
+     *
+     * A population with only exclusions would have no defined initial set, so
+     * configuration validation rejects it at construction.
+     */
+    constructor(patterns) {
+        this.patterns = patterns.map(compile);
+        if (!this.patterns.some((pattern) => !pattern.exclude))
+            throw new Error("The files array must contain at least one positive glob.");
+    }
+    /**
+     * Applies every matching pattern in declaration order.
+     *
+     * Later matching positives or exclusions replace the inclusion decision made
+     * by earlier patterns.
+     */
+    matches(location) {
+        const segments = split(location);
+        let included = false;
+        for (const pattern of this.patterns)
+            if (match(pattern.segments, segments, false))
+                included = !pattern.exclude;
+        return included;
+    }
+    /**
+     * Determines whether a directory can contain a selected descendant.
+     *
+     * Discovery uses this conservative result to prune traversal without
+     * excluding descendants restored by a later positive pattern.
+     */
+    couldMatchDescendant(directory) {
+        const prefix = split(directory);
+        let possible = false;
+        for (const pattern of this.patterns)
+            if (!pattern.exclude) {
+                if (match(pattern.segments, prefix, true))
+                    possible = true;
+            }
+            else if (pattern.segments.at(-1) === "**" &&
+                match(pattern.segments, prefix, false))
+                possible = false;
+        return possible;
+    }
+}
+exports.EvidenceFileGlob = EvidenceFileGlob;
+/**
+ * Parses one authored glob into normalized segments while rejecting ambiguous
+ * root escapes.
+ *
+ * `EvidenceFileGlob` uses the result for portable matching relative to one
+ * selected population root.
+ */
+function compile(raw) {
+    if (raw.trim() === "")
+        throw new Error("Glob strings must not be empty.");
+    const exclude = raw.startsWith("!");
+    let value = (exclude ? raw.slice(1) : raw).replaceAll("\\", "/");
+    while (value.startsWith("./"))
+        value = value.slice(2);
+    if (value === "")
+        throw new Error("The exclusion marker '!' must be followed by a glob.");
+    if (value.startsWith("/") || /^[A-Za-z]:/.test(value))
+        throw new Error(`Glob '${raw}' must be relative to its population root.`);
+    if (value.endsWith("/"))
+        value = value.slice(0, -1);
+    const segments = value.split("/");
+    if (segments.includes("") || segments.includes(".."))
+        throw new Error(`Glob '${raw}' contains an empty segment or escapes its root.`);
+    return { segments, exclude };
+}
+/**
+ * Splits a candidate path into portable relative segments without filesystem
+ * resolution.
+ *
+ * Matching operates on these normalized segments so Windows and POSIX
+ * separators have identical selection semantics.
+ */
+function split(value) {
+    let normalized = value.replaceAll("\\", "/");
+    while (normalized.startsWith("./"))
+        normalized = normalized.slice(2);
+    normalized = normalized.replace(/^\/+|\/+$/g, "");
+    return normalized === "" || normalized === "." ? [] : normalized.split("/");
+}
+/**
+ * Matches a pattern with memoized globstar branches bounded by the pattern and
+ * path grid.
+ *
+ * Memoization prevents repeated `**` branches from causing exponential
+ * discovery work for long paths.
+ */
+function match(pattern, segments, descendant) {
+    const memo = new Map();
+    return visit(0, 0);
+    function visit(patternIndex, pathIndex) {
+        const key = `${patternIndex}:${pathIndex}`;
+        const cached = memo.get(key);
+        if (cached !== undefined)
+            return cached;
+        const token = pattern[patternIndex];
+        const segment = segments[pathIndex];
+        let result;
+        if (descendant && pathIndex === segments.length)
+            result = patternIndex < pattern.length;
+        else if (token === undefined)
+            result = pathIndex === segments.length;
+        else if (token === "**")
+            result =
+                visit(patternIndex + 1, pathIndex) ||
+                    (segment !== undefined && visit(patternIndex, pathIndex + 1));
+        else
+            result =
+                segment !== undefined &&
+                    matchSegment(token, segment) &&
+                    visit(patternIndex + 1, pathIndex + 1);
+        memo.set(key, result);
+        return result;
+    }
+}
+/**
+ * Matches one segment where star and question mark never cross a separator
+ * boundary.
+ *
+ * A question mark consumes one Unicode code point, as in the Go matcher.
+ */
+function matchSegment(pattern, value) {
+    const tokens = Array.from(pattern);
+    const characters = Array.from(value);
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starPattern = -1;
+    let starValue = 0;
+    while (valueIndex < characters.length)
+        if (tokens[patternIndex] === "*") {
+            starPattern = patternIndex++;
+            starValue = valueIndex;
+        }
+        else if (tokens[patternIndex] === "?" ||
+            tokens[patternIndex] === characters[valueIndex]) {
+            patternIndex++;
+            valueIndex++;
+        }
+        else if (starPattern >= 0) {
+            patternIndex = starPattern + 1;
+            valueIndex = ++starValue;
+        }
+        else
+            return false;
+    while (tokens[patternIndex] === "*")
+        patternIndex++;
+    return patternIndex === tokens.length;
+}

package/lib/internal/EvidenceFingerprintIndex.d.ts

@@ -1,49 +1,125 @@
 import type { IEvidenceFingerprint } from "../structures/IEvidenceFingerprint";
 import type { IEvidenceInventory } from "../structures/IEvidenceInventory";
 /**
- * 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.
  */
 export declare class EvidenceFingerprintIndex {
+    /**
+     * Annotation ranges grouped by their physical source file.
+     *
+     * Content hashing removes these mapped spans while preserving surrounding
+     * semantic source text.
+     */
     private readonly annotations;
+    /**
+     * Structurally owned child units grouped by parent identity.
+     *
+     * Subtree fingerprints traverse this index without rescanning the inventory.
+     */
     private readonly children;
+    /**
+     * 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.
+     */
     private readonly contentDigests;
+    /**
+     * Memoized public fingerprint result for each unit identity.
+     *
+     * Repeated review checks reuse both the presented prefix and full scope hash.
+     */
     private readonly fingerprints;
+    /**
+     * 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.
+     */
     private readonly sources;
+    /**
+     * 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.
+     */
     private readonly units;
-    /** 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: IEvidenceInventory);
     /**
-     * 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.
      */
     inspect(unitId: string): IEvidenceFingerprint;
-    /** Collects a cycle-safe structural subtree for one unit.
+    /**
+     * Describes a semantic declaration without process-local source or site IDs.
+     *
+     * 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.
+     */
+    private 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.
+     */
+    private declaringPaths;
+    /**
+     * 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.
+     */
+    private portableUnitId;
+    /**
+     * 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.
+     * The visited set prevents malformed parent links from looping fingerprint
+     * generation while preserving each reachable child once.
      */
     private collect;
-    /** 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.
      */
     private contribution;
-    /** 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.
      */
     private contentDigest;
-    /** 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.
      */
     private withoutAnnotations;
 }