@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/internal/EvidenceWatchDependencySnapshot.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceWatchDependencySnapshot = void 0;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+/**
+ * Immutable filesystem versions used to validate a watch attempt before
+ * publication.
+ *
+ * Versions include symlink and directory-entry state because either can change
+ * which source is read; a content-only check would miss resolution changes.
+ */
+class EvidenceWatchDependencySnapshot {
+    versions;
+    /**
+     * Creates a snapshot from already captured dependency version strings.
+     *
+     * Capture and select are the only constructors because callers must not
+     * invent values that would falsely validate a watch attempt.
+     */
+    constructor(versions) {
+        this.versions = versions;
+    }
+    /**
+     * Captures every dependency asynchronously, encoding inaccessible paths as
+     * observable failures.
+     *
+     * Watch publication compares this baseline with a later capture so deletion,
+     * permission failure, and repair all count as distinct filesystem states.
+     */
+    static async capture(dependencies) {
+        const versions = new Map();
+        for (const dependency of dependencies)
+            versions.set(key(dependency), await version(dependency));
+        return new EvidenceWatchDependencySnapshot(versions);
+    }
+    /**
+     * States whether two snapshots cover the same dependencies at the same
+     * versions.
+     *
+     * Watch attempts publish only when this equality holds, preventing output
+     * from describing a source state that changed during analysis.
+     */
+    equals(other) {
+        if (this.versions.size !== other.versions.size)
+            return false;
+        for (const [location, value] of this.versions)
+            if (other.versions.get(location) !== value)
+                return false;
+        return true;
+    }
+    /**
+     * Returns a dependency subset captured by this stable baseline.
+     *
+     * Every requested key must exist in the baseline; omission throws rather than
+     * allowing a narrower snapshot to validate unrelated watch work.
+     */
+    select(dependencies) {
+        const selected = new Map();
+        for (const dependency of dependencies) {
+            const location = key(dependency);
+            const value = this.versions.get(location);
+            if (value === undefined)
+                throw new Error(`Watch dependency '${dependency.path}' was not captured.`);
+            selected.set(location, value);
+        }
+        return new EvidenceWatchDependencySnapshot(selected);
+    }
+}
+exports.EvidenceWatchDependencySnapshot = EvidenceWatchDependencySnapshot;
+/**
+ * Reads a stable watch version without throwing on ordinary filesystem
+ * disappearance.
+ *
+ * Capture uses this value for each dependency so failures become comparable
+ * state and a repaired path invalidates the prior failed snapshot.
+ */
+async function version(dependency) {
+    let link;
+    try {
+        link = await (0, promises_1.lstat)(dependency.path, { bigint: true });
+    }
+    catch (cause) {
+        return failure(cause);
+    }
+    const values = [metadata(link)];
+    let followed = link;
+    if (link.isSymbolicLink()) {
+        try {
+            values.push(`link:${await (0, promises_1.readlink)(dependency.path)}`);
+            values.push(`real:${await (0, promises_1.realpath)(dependency.path)}`);
+            followed = await (0, promises_1.stat)(dependency.path, { bigint: true });
+            values.push(metadata(followed));
+        }
+        catch (cause) {
+            values.push(failure(cause));
+            return values.join("\u0001");
+        }
+    }
+    try {
+        if (followed.isFile())
+            values.push(`content:${(0, node_crypto_1.createHash)("sha256")
+                .update(await (0, promises_1.readFile)(dependency.path))
+                .digest("hex")}`);
+        else if (followed.isDirectory() && dependency.recursive)
+            values.push(`entries:${(await (0, promises_1.readdir)(dependency.path, { withFileTypes: true }))
+                .sort(compareEntries)
+                .map(entryVersion)
+                .join("\u0000")}`);
+    }
+    catch (cause) {
+        values.push(failure(cause));
+    }
+    return values.join("\u0001");
+}
+/**
+ * Serializes metadata fields whose changes can affect filesystem resolution or
+ * reads.
+ *
+ * File and link versions include this component before content or directory
+ * entries so metadata-only replacement is observable to the watch baseline.
+ */
+function metadata(info) {
+    return [
+        info.mode,
+        info.size,
+        info.mtimeNs,
+        info.ctimeNs,
+        info.dev,
+        info.ino,
+    ].join(":");
+}
+/**
+ * Encodes a directory entry's name and coarse type for recursive invalidation.
+ *
+ * Recursive directory versions use this value after sorting, so additions,
+ * removals, and entry-type changes invalidate the dependency snapshot.
+ */
+function entryVersion(entry) {
+    const kind = entry.isDirectory()
+        ? "directory"
+        : entry.isFile()
+            ? "file"
+            : entry.isSymbolicLink()
+                ? "link"
+                : "other";
+    return `${kind}:${entry.name}`;
+}
+/**
+ * Sorts directory entries before deterministic concatenation.
+ *
+ * Filesystem enumeration order is not stable, so version derives the same
+ * string for an unchanged recursive directory across captures.
+ */
+function compareEntries(left, right) {
+    return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+}
+/**
+ * Distinguishes exact and recursive observations of the same filesystem path.
+ *
+ * Snapshot maps use this key so a file watch cannot be substituted for the
+ * broader directory observation required by a recursive dependency.
+ */
+function key(dependency) {
+    return `${dependency.recursive ? "recursive" : "exact"}:${dependency.path}`;
+}
+/**
+ * Turns a failed filesystem read into versioned state.
+ *
+ * The encoded error lets later repair produce a different snapshot instead of
+ * making disappearance invisible to the watch publication check.
+ */
+function failure(cause) {
+    return `error:${errorCode(cause)}:${errorMessage(cause)}`;
+}
+/**
+ * Extracts a platform error code without assuming every thrown value is an
+ * Error.
+ *
+ * Failure uses UNKNOWN for non-Error values and errors without string codes so
+ * opaque exceptions still become stable observable watch state.
+ */
+function errorCode(cause) {
+    if (!(cause instanceof Error) || !("code" in cause))
+        return "UNKNOWN";
+    const code = cause.code;
+    return typeof code === "string" ? code : "UNKNOWN";
+}
+/**
+ * Preserves a human-readable component for otherwise opaque watch failures.
+ *
+ * Together with errorCode, this distinguishes read failures in snapshot values
+ * while retaining useful context for diagnostics and change detection.
+ */
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/lib/internal/IEvidenceConfigDataModule.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Decoded dependency-bearing content of one Node data URL module.
+ *
+ * JavaScript modules expose source for recursive static scanning. JSON and Wasm
+ * modules are immutable leaves and therefore omit content.
+ */
+export interface IEvidenceConfigDataModule {
+    /**
+     * JavaScript source text that can contain further module requests.
+     *
+     * JSON and Wasm data modules omit this value because they cannot add static
+     * filesystem dependencies to the configuration watch set.
+     */
+    content?: string;
+}

package/lib/internal/IEvidenceConfigDependencyScan.d.ts

@@ -0,0 +1,27 @@
+import type { IEvidenceSourceDependency } from "../structures/IEvidenceSourceDependency";
+/**
+ * Dependencies found while scanning a configuration module graph.
+ *
+ * A failure does not erase prior discoveries: watch mode needs these paths to
+ * observe the repair that makes evaluation possible again.
+ */
+export interface IEvidenceConfigDependencyScan {
+    /**
+     * File and directory dependencies that must invalidate configuration
+     * evaluation.
+     *
+     * `EvidenceConfigDependencyScanner` records resolved module files, package
+     * boundaries, and missing resolution candidates here so watch mode can rerun
+     * evaluation after either a content edit or a filesystem-topology repair.
+     */
+    dependencies: IEvidenceSourceDependency[];
+    /**
+     * Read, parse, or resolution failure after recoverable dependencies were
+     * recorded.
+     *
+     * Omission means scanning completed. When present, callers retain
+     * `dependencies` instead of replacing them with an empty watch set that could
+     * miss the change which repairs the configuration graph.
+     */
+    cause?: unknown;
+}

package/lib/internal/IEvidenceConfigModuleSpecifier.d.ts

@@ -0,0 +1,25 @@
+import type { EvidenceConfigModuleMode } from "./EvidenceConfigModuleMode";
+/**
+ * Statically discoverable configuration dependency before filesystem
+ * resolution.
+ *
+ * EvidenceConfigDependencyScanner retains the loading mechanism beside the
+ * authored specifier because conditional package exports can map the same text
+ * to different physical files.
+ */
+export interface IEvidenceConfigModuleSpecifier {
+    /**
+     * Authored module specifier without its string-literal delimiters.
+     *
+     * Relative, file URL, package, and built-in forms remain intact until the
+     * resolver applies the same category boundary used during evaluation.
+     */
+    specifier: string;
+    /**
+     * Loading mechanism that selects package export conditions.
+     *
+     * Static imports inherit the evaluator's module kind. Literal `import()` and
+     * `require()` calls retain their own mechanism independently.
+     */
+    mode: EvidenceConfigModuleMode;
+}

package/lib/internal/IEvidenceConfigPackageBoundary.d.ts

@@ -0,0 +1,23 @@
+import type { IEvidenceConfigResolutionManifest } from "./IEvidenceConfigResolutionManifest";
+/**
+ * Nearest package scope governing one configuration module request.
+ *
+ * Package imports and self-references both need the manifest together with its
+ * directory so relative map targets cannot escape the scope that declared
+ * them.
+ */
+export interface IEvidenceConfigPackageBoundary {
+    /**
+     * Directory containing the governing package manifest.
+     *
+     * Relative map targets must remain descendants of this boundary.
+     */
+    directory: string;
+    /**
+     * Freshly validated package fields used by configuration resolution.
+     *
+     * Keeping the parsed value with its directory prevents a later cached lookup
+     * from pairing metadata with the wrong watch cycle or symlink target.
+     */
+    manifest: IEvidenceConfigResolutionManifest;
+}

package/lib/internal/IEvidenceConfigPackageScope.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Nearest package metadata relevant to the configuration evaluator's module
+ * decision.
+ *
+ * `configModule` reads this parsed projection while walking upward from a
+ * config file. It models only the package field that can change the temporary
+ * evaluator project's compiler module kind.
+ */
+export interface IEvidenceConfigPackageScope {
+    /**
+     * Node package module mode at this package boundary.
+     *
+     * The evaluator selects `ESNext` only when this value is `"module"`; omission
+     * and every other value retain the CommonJS fallback for an unqualified
+     * config.
+     */
+    type?: string;
+}

package/lib/internal/IEvidenceConfigResolutionManifest.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Package metadata that can redirect a configuration dependency.
+ *
+ * EvidenceConfigDependencyScanner validates this narrow projection from fresh
+ * manifest bytes on every watch cycle. Other package fields cannot select a
+ * runtime entry or package scope and therefore remain outside the scanner's
+ * resolution contract.
+ */
+export interface IEvidenceConfigResolutionManifest {
+    /**
+     * Module interpretation applied to JavaScript files in this package scope.
+     *
+     * The exact value `module` makes `.js` and `.jsx` dependencies use ESM static
+     * import conditions. Omission and every other value retain CommonJS.
+     */
+    type?: string;
+    /**
+     * Public package name used to recognize a self-reference.
+     *
+     * A matching bare request resolves against this manifest's exports without
+     * requiring a duplicate copy under an ancestor `node_modules` directory.
+     */
+    name?: string;
+    /**
+     * Legacy root entry used when the package has no export map.
+     *
+     * Only a string selects a target. Omission and non-string JSON values use
+     * Node's `index` fallback; subpath requests do not use this root field
+     * because they already name their legacy path.
+     */
+    main?: unknown;
+    /**
+     * Conditional or subpath export map controlling public package requests.
+     *
+     * Omission enables legacy `main` and direct-subpath lookup. Presence makes
+     * unexported or condition-incompatible requests explicit resolution
+     * failures.
+     */
+    exports?: unknown;
+    /**
+     * Internal `#` specifier map owned by this package scope.
+     *
+     * Values retain their authored shape until the scanner applies exact or
+     * pattern matching and the active import/require conditions.
+     */
+    imports?: unknown;
+}

package/lib/internal/IEvidenceEvaluateTypeScriptConfigOptions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Optional diagnostic routing for isolated TypeScript configuration evaluation.
+ *
+ * `evaluateTypeScriptConfig` passes this sink to its child evaluator so callers
+ * can collect or redirect compiler and runtime output without changing the
+ * evaluated configuration result.
+ */
+export interface IEvidenceEvaluateTypeScriptConfigOptions {
+    /**
+     * Receives each stdout or stderr chunk emitted by the evaluator process.
+     *
+     * When omitted, evaluation writes diagnostics to the parent process's stderr
+     * and preserves the child process's original formatting.
+     */
+    writeDiagnostic?: ((content: string) => void) | undefined;
+}

package/lib/internal/IEvidenceFileGlobPattern.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One normalized include or exclusion rule in the ordered Evidence glob
+ * program.
+ *
+ * `EvidenceFileGlob` creates these records while compiling configured file
+ * patterns, then applies them in order to determine a path's current inclusion
+ * decision.
+ */
+export interface IEvidenceFileGlobPattern {
+    /**
+     * Portable relative path segments interpreted by the limited glob matcher.
+     *
+     * Compilation removes the exclusion marker and normalizes separators before
+     * storing these tokens, so matching never depends on host path separators.
+     */
+    segments: string[];
+    /**
+     * Whether a matching rule clears the current inclusion decision.
+     *
+     * This is true for patterns authored with `!`; a later positive rule can
+     * restore a path because `EvidenceFileGlob` evaluates every rule in
+     * declaration order.
+     */
+    exclude: boolean;
+}

package/lib/internal/IEvidenceMaterializedClaim.d.ts

@@ -2,7 +2,8 @@ import type { IEvidenceConfigPlanClaim } from "../structures/IEvidenceConfigPlan
 import type { IEvidenceInventory } from "../structures/IEvidenceInventory";
 import type { IEvidenceMaterializedReference } from "./IEvidenceMaterializedReference";
 /**
- * One enabled claim with the inventories needed to resolve its acknowledgements.
+ * One enabled claim with the inventories needed to resolve its
+ * acknowledgements.
  *
  * This record belongs to a single analysis pass. It retains configuration order
  * and selected identities so later graph construction never needs to rediscover
@@ -10,14 +11,16 @@ import type { IEvidenceMaterializedReference } from "./IEvidenceMaterializedRefe
  */
 export interface IEvidenceMaterializedClaim {
     /**
-     * Validated, enabled claim policy that owns this population's configuration position.
+     * Validated, enabled claim policy that owns this population's configuration
+     * position.
      *
      * Later graph construction reads its effective policy without revisiting the
      * mutable configuration document that produced this analysis pass.
      */
     plan: IEvidenceConfigPlanClaim;
     /**
-     * Extracted claim inventory, including contextual units outside the denominator.
+     * Extracted claim inventory, including contextual units outside the
+     * denominator.
      *
      * Structural parents remain available for host and withdrawal decisions even
      * when only the selected units contribute claim obligations.
@@ -31,14 +34,16 @@ export interface IEvidenceMaterializedClaim {
      */
     unitIds: string[];
     /**
-     * Hosts that may carry exclusions when exclusion scope differs from selected units.
+     * Hosts that may carry exclusions when exclusion scope differs from selected
+     * units.
      *
      * Omission means the selected unit IDs also define every eligible exclusion
      * host, so graph processing needs no separate structural population.
      */
     exclusionHostIds?: string[];
     /**
-     * Reference inventories evaluated against this claim in authored reference order.
+     * Reference inventories evaluated against this claim in authored reference
+     * order.
      *
      * The order preserves independent configuration occurrences for diagnostics
      * and query rows even when they resolve to overlapping identities.

package/lib/internal/IEvidenceMaterializedReference.d.ts

@@ -8,10 +8,12 @@ import type { IEvidenceInventory } from "../structures/IEvidenceInventory";
  */
 export interface IEvidenceMaterializedReference {
     /**
-     * Validated configuration and effective severity for this reference occurrence.
+     * Validated configuration and effective severity for this reference
+     * occurrence.
      *
-     * The graph preserves this plan entry separately when repeated references share
-     * an inventory but have distinct authored positions or inherited policy.
+     * The graph preserves this plan entry separately when repeated references
+     * share an inventory but have distinct authored positions or inherited
+     * policy.
      */
     plan: IEvidenceConfigPlanReference;
     /**

package/lib/internal/IEvidencePackageManifest.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Installed evidence package manifest fields required by the version command.
+ *
+ * `EvidenceCommand` validates this narrow projection before reporting its own
+ * package version, keeping malformed installed metadata an actionable command
+ * failure instead of loading project configuration.
+ */
+export interface IEvidencePackageManifest {
+    /**
+     * Published package version presented by the command.
+     *
+     * This value comes from the installed package manifest and is returned as the
+     * version command's output rather than being derived from the running
+     * project.
+     */
+    version: string;
+}

package/lib/internal/IEvidencePendingEvidenceTag.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A recognized documentation annotation before semantic attachment.
+ *
+ * Parser offsets remain relative to normalized documentation so the mapper can
+ * recover the original source range after multiline bodies are assembled.
+ */
+export interface IEvidencePendingEvidenceTag {
+    /**
+     * Annotation spelling, including link and review variants with distinct later
+     * rules.
+     *
+     * Attachment dispatch uses this value to choose target parsing and graph
+     * handling without re-reading the normalized documentation text.
+     */
+    kind: "evidence" | "link" | "evidenceExclude" | "evidenceReview" | "evidenceExcludeReview";
+    /**
+     * Continued body text without the tag marker.
+     *
+     * The mapper joins continuation lines before target parsing while retaining
+     * offsets into the normalized documentation carrier.
+     */
+    body: string;
+    /**
+     * Inclusive UTF-16 offset of the annotation in normalized documentation.
+     *
+     * Source mapping combines this boundary with the carrier's normalized text to
+     * recover the authored location for diagnostics.
+     */
+    start: number;
+    /**
+     * Exclusive UTF-16 offset immediately after the tag's continued body.
+     *
+     * Together with {@link start}, this forms the half-open annotation range used
+     * when translating normalized offsets back to source positions.
+     */
+    end: number;
+}

package/lib/internal/IEvidenceQueryPopulation.d.ts

@@ -5,39 +5,44 @@ import type { IEvidenceQueryScope } from "../structures/IEvidenceQueryScope";
 /**
  * Population input used to construct a reusable query index.
  *
- * Claim entries provide source and selection context; reference entries additionally
- * join effective graph policy and evaluated coverage. All records belong to the
- * containing query facade's owned analysis snapshot.
+ * Claim entries provide source and selection context; reference entries
+ * additionally join effective graph policy and evaluated coverage. All records
+ * belong to the containing query facade's owned analysis snapshot.
  */
 export interface IEvidenceQueryPopulation {
     /**
      * Authored configuration boundary and population role.
      *
-     * This distinguishes repeated references when query rows share semantic identities.
+     * This distinguishes repeated references when query rows share semantic
+     * identities.
      */
     scope: IEvidenceQueryScope;
     /**
      * Extracted inventory supplying units, addresses, and structural parents.
      *
-     * It can contain unselected units needed for context and exact target inspection.
+     * It can contain unselected units needed for context and exact target
+     * inspection.
      */
     inventory: IEvidenceInventory;
     /**
      * Configured semantic selection in its retained order.
      *
-     * The query index derives ancestor closure separately rather than extending this denominator.
+     * The query index derives ancestor closure separately rather than extending
+     * this denominator.
      */
     unitIds: string[];
     /**
      * Effective reference input when this population represents a requirement.
      *
-     * Claim populations omit it; reference queries use it to present policy details.
+     * Claim populations omit it; reference queries use it to present policy
+     * details.
      */
     reference?: IEvidenceGraphReference;
     /**
      * Evaluated coverage ledger for a reference population.
      *
-     * Omission on claim entries means reference coverage cannot be inferred from them.
+     * Omission on claim entries means reference coverage cannot be inferred from
+     * them.
      */
     obligation?: IEvidenceGraphObligation;
 }

package/lib/internal/IEvidenceResolvedReview.d.ts

@@ -1,6 +1,7 @@
 import type { IEvidenceReview } from "../structures/IEvidenceReview";
 /**
- * A review annotation paired with its resolved reference target and claim hosts.
+ * A review annotation paired with its resolved reference target and claim
+ * hosts.
  *
  * Reviews retain the authored record so reporting can distinguish a missing
  * review from an invalid target without re-parsing source text.
@@ -9,22 +10,22 @@ export interface IEvidenceResolvedReview {
     /**
      * Original review declaration and source position.
      *
-     * Reporting retains the authored annotation so an invalid review target can be
-     * distinguished from an absent review without reparsing its source file.
+     * Reporting retains the authored annotation so an invalid review target can
+     * be distinguished from an absent review without reparsing its source file.
      */
     review: IEvidenceReview;
     /**
      * Claim units whose structural scope contains the review host.
      *
-     * One review declaration can apply to multiple selected descendants that share
-     * its structural host position.
+     * One review declaration can apply to multiple selected descendants that
+     * share its structural host position.
      */
     hostUnitIds: string[];
     /**
      * Reference unit named by the review target.
      *
-     * The resolver assigns this identity after proving the target is unique within
-     * the configured reference population.
+     * The resolver assigns this identity after proving the target is unique
+     * within the configured reference population.
      */
     targetUnitId: string;
 }

package/lib/internal/IEvidenceTargetCandidate.d.ts

@@ -3,13 +3,15 @@ import type { IEvidenceResolution } from "../structures/IEvidenceResolution";
 /**
  * Public address paired with its exact inventory lookup result.
  *
- * Target resolution can derive several addresses from a host's retained origins.
- * Keeping each address beside its lookup outcome permits candidate aggregation
- * without losing which spelling produced a visible, hidden, or missing match.
+ * Target resolution can derive several addresses from a host's retained
+ * origins. Keeping each address beside its lookup outcome permits candidate
+ * aggregation without losing which spelling produced a visible, hidden, or
+ * missing match.
  */
 export interface IEvidenceTargetCandidate {
     /**
-     * Concrete public file key and accessor segments submitted to inventory lookup.
+     * Concrete public file key and accessor segments submitted to inventory
+     * lookup.
      *
      * This is already parsed under the applicable artifact target grammar.
      */
@@ -17,7 +19,8 @@ export interface IEvidenceTargetCandidate {
     /**
      * Lookup outcome within the selected reference's structural scope.
      *
-     * The resolver combines candidates by semantic identity before deciding uniqueness.
+     * The resolver combines candidates by semantic identity before deciding
+     * uniqueness.
      */
     resolution: IEvidenceResolution;
 }

package/lib/internal/IEvidenceTreeSitterAssetLock.d.ts

@@ -0,0 +1,25 @@
+import type { tags } from "typia";
+/**
+ * Serialized ownership record for one cross-process grammar cache transfer.
+ *
+ * The token prevents an old owner from deleting a lock reacquired after a
+ * crash; the PID permits stale-lock recovery when that owner is no longer
+ * alive.
+ */
+export interface IEvidenceTreeSitterAssetLock {
+    /**
+     * Positive operating-system process ID that acquired the transfer lock.
+     *
+     * Stale-lock recovery checks whether this owner remains alive before allowing
+     * another process to replace the serialized cache record.
+     */
+    pid: number & tags.Type<"uint32"> & tags.Minimum<1>;
+    /**
+     * Random acquisition token checked before releasing a lock with the same
+     * path.
+     *
+     * It prevents a former owner from deleting a lock that another process
+     * acquired after crash recovery reused the path.
+     */
+    token: string;
+}