@wrtnlabs/evidence 0.0.0

package/lib/internal/TreeSitterAssetCache.d.ts

@@ -0,0 +1,35 @@
+import type { IEvidenceGrammar } from "../structures/IEvidenceGrammar";
+import type { ITreeSitterAssetOptions } from "./ITreeSitterAssetOptions";
+/**
+ * Acquires immutable upstream grammars and validates every cache read before loading WASM.
+ *
+ * Concurrent callers share transfer work by destination but receive independent
+ * byte arrays. Atomic publication and lock recovery prevent partial or abandoned
+ * downloads from becoming trusted cache entries across processes.
+ */
+export declare class TreeSitterAssetCache {
+    private readonly options;
+    /**
+     * Tracks process-local transfers by immutable cache destination.
+     *
+     * Concurrent bytes calls share this pending record so they do not download the
+     * same pinned grammar independently, while consumer counts govern cancellation.
+     */
+    private static readonly pending;
+    /**
+     * Captures asset-acquisition controls without performing filesystem or network work.
+     *
+     * bytes applies these controls when it resolves the cache location, downloads a
+     * grammar, and reports progress for this cache instance.
+     */
+    constructor(options: ITreeSitterAssetOptions);
+    /**
+     * Returns verified caller-owned grammar bytes, repairing missing or damaged cache entries.
+     *
+     * The method shares a transfer with concurrent callers but slices its result so
+     * no caller can mutate another caller's buffer.
+     */
+    bytes(grammar: IEvidenceGrammar): Promise<Uint8Array>;
+    private acquire;
+    private download;
+}

package/lib/internal/TreeSitterAssetCache.js

@@ -0,0 +1,456 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeSitterAssetCache = void 0;
+const _isTypeUint32_1 = __importStar(require("typia/lib/internal/_isTypeUint32"));
+const _validateReport_1 = __importStar(require("typia/lib/internal/_validateReport"));
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const promises_2 = require("node:timers/promises");
+const typia_1 = __importDefault(require("typia"));
+const EvidenceParserError_1 = require("../parsers/EvidenceParserError");
+/**
+ * Acquires immutable upstream grammars and validates every cache read before loading WASM.
+ *
+ * Concurrent callers share transfer work by destination but receive independent
+ * byte arrays. Atomic publication and lock recovery prevent partial or abandoned
+ * downloads from becoming trusted cache entries across processes.
+ */
+class TreeSitterAssetCache {
+    options;
+    /**
+     * Tracks process-local transfers by immutable cache destination.
+     *
+     * Concurrent bytes calls share this pending record so they do not download the
+     * same pinned grammar independently, while consumer counts govern cancellation.
+     */
+    static pending = new Map();
+    /**
+     * Captures asset-acquisition controls without performing filesystem or network work.
+     *
+     * bytes applies these controls when it resolves the cache location, downloads a
+     * grammar, and reports progress for this cache instance.
+     */
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Returns verified caller-owned grammar bytes, repairing missing or damaged cache entries.
+     *
+     * The method shares a transfer with concurrent callers but slices its result so
+     * no caller can mutate another caller's buffer.
+     */
+    async bytes(grammar) {
+        const destination = node_path_1.default.join(cacheDirectory(this.options.cacheDirectory), "grammars-v1", `${String(grammar.wasm.sha256)}.wasm`);
+        try {
+            if (this.options.signal !== undefined)
+                this.options.signal.throwIfAborted();
+            const cached = await verified(destination, grammar.wasm);
+            if (cached !== undefined)
+                return cached;
+            let pending = TreeSitterAssetCache.pending.get(destination);
+            if (pending === undefined || pending.controller.signal.aborted) {
+                const controller = new AbortController();
+                pending = {
+                    controller,
+                    consumers: 0,
+                    promise: this.acquire(grammar, destination, controller.signal),
+                };
+                TreeSitterAssetCache.pending.set(destination, pending);
+            }
+            ++pending.consumers;
+            try {
+                this.options.progress?.(`Preparing ${grammar.id} parser (${grammar.version})...`);
+                const bytes = await consume(pending.promise, this.options.signal);
+                return bytes.slice();
+            }
+            finally {
+                if (--pending.consumers === 0) {
+                    pending.controller.abort();
+                    // Complete owned filesystem cleanup before a cancelled caller can dispose its execution.
+                    await pending.promise.catch(() => undefined);
+                    if (TreeSitterAssetCache.pending.get(destination) === pending)
+                        TreeSitterAssetCache.pending.delete(destination);
+                }
+            }
+        }
+        catch (cause) {
+            if (this.options.signal?.aborted === true)
+                throw new EvidenceParserError_1.EvidenceParserError("asset-cancelled", grammar.id, "Parser preparation was cancelled.", undefined, { cause });
+            if (cause instanceof EvidenceParserError_1.EvidenceParserError)
+                throw cause;
+            throw new EvidenceParserError_1.EvidenceParserError("asset-cache", destination, "Cannot prepare the parser cache. Restore write access or set EVIDENCE_CACHE_DIR to an absolute writable directory.", undefined, { cause });
+        }
+    }
+    /**
+     * Acquires a cross-process cache lock, verifies downloaded bytes, and atomically publishes one entry.
+     *
+     * The finally block removes only files owned by this acquisition, preserving
+     * another process's active lock and completed cache entry.
+     */
+    async acquire(grammar, destination, signal) {
+        await (0, promises_1.mkdir)(node_path_1.default.dirname(destination), { recursive: true });
+        const lock = `${destination}.lock`;
+        const owner = {
+            pid: process.pid,
+            token: (0, node_crypto_1.randomUUID)(),
+        };
+        const deadline = Date.now() + 120_000;
+        for (;;) {
+            signal.throwIfAborted();
+            const cached = await verified(destination, grammar.wasm);
+            if (cached !== undefined)
+                return cached;
+            try {
+                const handle = await (0, promises_1.open)(lock, "wx");
+                try {
+                    try {
+                        await handle.writeFile(JSON.stringify(owner));
+                    }
+                    finally {
+                        await handle.close();
+                    }
+                }
+                catch (cause) {
+                    await (0, promises_1.rm)(lock, { force: true });
+                    throw cause;
+                }
+                break;
+            }
+            catch (cause) {
+                if (!fileError(cause, "EEXIST"))
+                    throw cause;
+                await recoverLock(lock);
+                if (Date.now() >= deadline)
+                    throw new EvidenceParserError_1.EvidenceParserError("asset-cache", destination, "Another process is still preparing this parser. Retry after it completes or stops.");
+                await (0, promises_2.setTimeout)(100, undefined, { signal });
+            }
+        }
+        const temporary = `${destination}.${owner.token}.tmp`;
+        try {
+            const cached = await verified(destination, grammar.wasm);
+            if (cached !== undefined)
+                return cached;
+            const bytes = await this.download(grammar, signal);
+            signal.throwIfAborted();
+            const handle = await (0, promises_1.open)(temporary, "wx");
+            try {
+                await handle.writeFile(bytes);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            signal.throwIfAborted();
+            await (0, promises_1.rename)(temporary, destination);
+            return bytes;
+        }
+        finally {
+            await (0, promises_1.rm)(temporary, { force: true });
+            if ((await readLock(lock))?.token === owner.token)
+                await (0, promises_1.rm)(lock, { force: true });
+        }
+    }
+    /**
+     * Downloads one pinned grammar with bounded retries, response size, and cancellation.
+     *
+     * Hash verification remains in the caller so every cache and fresh-download
+     * path shares the same immutable-asset check.
+     */
+    async download(grammar, signal) {
+        const attempts = this.options.attempts ?? 3;
+        let failure;
+        for (let attempt = 0; attempt < attempts; ++attempt) {
+            signal.throwIfAborted();
+            if (attempt !== 0)
+                await (0, promises_2.setTimeout)(100 * 2 ** (attempt - 1), undefined, { signal });
+            const timeout = new AbortController();
+            const timer = setTimeout(() => timeout.abort(), this.options.timeoutMilliseconds ?? 30_000);
+            try {
+                const response = await (this.options.fetch ?? globalThis.fetch)(grammar.wasm.url, {
+                    signal: AbortSignal.any([signal, timeout.signal]),
+                    headers: { Accept: "application/wasm, application/octet-stream" },
+                });
+                if (!response.ok) {
+                    if (response.body !== null)
+                        await response.body.cancel();
+                    const error = new Error(`HTTP ${response.status}`);
+                    if (response.status === 408 ||
+                        response.status === 429 ||
+                        response.status >= 500)
+                        throw error;
+                    throw new EvidenceParserError_1.EvidenceParserError("asset-download", grammar.id, `The pinned parser URL returned HTTP ${response.status}. Restore access to ${grammar.wasm.url} and retry.`, undefined, { cause: error });
+                }
+                const bytes = await boundedBody(response, grammar.wasm.size);
+                if (!matches(bytes, grammar.wasm))
+                    throw new EvidenceParserError_1.EvidenceParserError("asset-corrupt", grammar.id, "Downloaded parser bytes do not match the pinned size and SHA-256. Restore unmodified access to the pinned asset and retry.");
+                return bytes;
+            }
+            catch (cause) {
+                if (cause instanceof EvidenceParserError_1.EvidenceParserError)
+                    throw cause;
+                failure = cause;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        signal.throwIfAborted();
+        throw new EvidenceParserError_1.EvidenceParserError("asset-download", grammar.id, `Cannot download the pinned parser after ${attempts} attempts. Restore network access to ${grammar.wasm.url} and retry; verified cached parsers work offline.`, undefined, { cause: failure });
+    }
+}
+exports.TreeSitterAssetCache = TreeSitterAssetCache;
+/**
+ * Selects the explicit, environment, or platform cache root without creating it.
+ *
+ * Acquisition owns directory creation so resolving a location never changes the
+ * project or user cache as a side effect.
+ */
+function cacheDirectory(override) {
+    const configured = override ?? process.env["EVIDENCE_CACHE_DIR"];
+    if (configured !== undefined) {
+        if (!node_path_1.default.isAbsolute(configured))
+            throw new EvidenceParserError_1.EvidenceParserError("asset-cache", configured, "EVIDENCE_CACHE_DIR must be an absolute writable directory.");
+        return node_path_1.default.normalize(configured);
+    }
+    if (process.platform === "win32")
+        return node_path_1.default.join(process.env["LOCALAPPDATA"] ?? node_path_1.default.join((0, node_os_1.homedir)(), "AppData", "Local"), "wrtnlabs", "evidence", "Cache");
+    if (process.platform === "darwin")
+        return node_path_1.default.join((0, node_os_1.homedir)(), "Library", "Caches", "wrtnlabs", "evidence");
+    const xdg = process.env["XDG_CACHE_HOME"];
+    return node_path_1.default.join(xdg !== undefined && node_path_1.default.isAbsolute(xdg)
+        ? xdg
+        : node_path_1.default.join((0, node_os_1.homedir)(), ".cache"), "wrtnlabs", "evidence");
+}
+/**
+ * Reads a cache file only when its size and SHA-256 match pinned provenance.
+ *
+ * Checking metadata first avoids loading a corrupted or unexpectedly large
+ * file before immutable-asset validation.
+ */
+async function verified(file, asset) {
+    try {
+        if ((await (0, promises_1.stat)(file)).size !== asset.size)
+            return undefined;
+        const bytes = await (0, promises_1.readFile)(file);
+        return matches(bytes, asset) ? bytes : undefined;
+    }
+    catch (cause) {
+        if (fileError(cause, "ENOENT"))
+            return undefined;
+        throw cause;
+    }
+}
+/**
+ * Verifies immutable bytes against the exact declared size and digest.
+ *
+ * Response headers cannot establish grammar provenance, so this comparison is
+ * the shared trust boundary for cached and downloaded data.
+ */
+function matches(bytes, asset) {
+    return (bytes.length === asset.size &&
+        (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex") === asset.sha256);
+}
+/**
+ * Streams a response with a byte cap so a bad server cannot exhaust the process before validation.
+ *
+ * The reader is always released, including when the advertised asset is too
+ * large or the stream ends unexpectedly.
+ */
+async function boundedBody(response, size) {
+    if (response.body === null)
+        throw new Error("The parser response has no body.");
+    const reader = response.body.getReader();
+    const output = new Uint8Array(size);
+    let length = 0;
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done !== false)
+                break;
+            if (length + part.value.length > size)
+                throw new EvidenceParserError_1.EvidenceParserError("asset-corrupt", "parser download", "The parser response exceeds its pinned size.");
+            output.set(part.value, length);
+            length += part.value.length;
+        }
+        return output.subarray(0, length);
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+/**
+ * Races a shared transfer against one caller's cancellation without cancelling peers.
+ *
+ * Other parser sessions may still consume the same destination promise, so a
+ * single abort cannot own the shared controller.
+ */
+async function consume(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    let cancel;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                cancel = function abort() {
+                    reject(new Error("Parser preparation was cancelled."));
+                };
+                signal.addEventListener("abort", cancel, { once: true });
+                if (signal.aborted)
+                    cancel();
+            }),
+        ]);
+    }
+    finally {
+        if (cancel !== undefined)
+            signal.removeEventListener("abort", cancel);
+    }
+}
+/**
+ * Narrows expected filesystem error codes used for cache recovery decisions.
+ *
+ * Unknown thrown values remain non-matches and are propagated by the caller.
+ */
+function fileError(cause, code) {
+    return cause instanceof Error && "code" in cause && cause.code === code;
+}
+/**
+ * Reads and validates lock ownership, treating malformed locks as recoverable stale state.
+ *
+ * Incomplete writes flow into age-based recovery instead of being trusted as a
+ * live owner.
+ */
+async function readLock(file) {
+    try {
+        const parsed = (() => {
+            const _io0 = input => "number" === typeof input.pid && (_isTypeUint32_1._isTypeUint32(input.pid) && 1 <= input.pid) && "string" === typeof input.token;
+            const _vo0 = (input, _path, _exceptionable = true) => ["number" === typeof input.pid && (_isTypeUint32_1._isTypeUint32(input.pid) || _report(_exceptionable, {
+                    path: _path + ".pid",
+                    expected: "number & Type<\"uint32\">",
+                    value: input.pid
+                })) && (1 <= input.pid || _report(_exceptionable, {
+                    path: _path + ".pid",
+                    expected: "number & Minimum<1>",
+                    value: input.pid
+                })) || _report(_exceptionable, {
+                    path: _path + ".pid",
+                    expected: "(number & Type<\"uint32\"> & Minimum<1>)",
+                    value: input.pid
+                }), "string" === typeof input.token || _report(_exceptionable, {
+                    path: _path + ".token",
+                    expected: "string",
+                    value: input.token
+                })].every(flag => flag);
+            const __is = input => "object" === typeof input && null !== input && _io0(input);
+            let errors;
+            let _report;
+            const __validate = input => {
+                if (false === __is(input)) {
+                    errors = [];
+                    _report = _validateReport_1._validateReport(errors);
+                    ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input || _report(true, {
+                        path: _path + "",
+                        expected: "ITreeSitterAssetLock",
+                        value: input
+                    })) && _vo0(input, _path + "", true) || _report(true, {
+                        path: _path + "",
+                        expected: "ITreeSitterAssetLock",
+                        value: input
+                    }))(input, "$input", true);
+                    const success = 0 === errors.length;
+                    return success ? {
+                        success,
+                        data: input
+                    } : {
+                        success,
+                        errors,
+                        data: input
+                    };
+                }
+                return {
+                    success: true,
+                    data: input
+                };
+            };
+            return input => __validate(JSON.parse(input));
+        })()(await (0, promises_1.readFile)(file, "utf8"));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch (cause) {
+        if (fileError(cause, "ENOENT"))
+            return undefined;
+        throw cause;
+    }
+}
+/**
+ * Removes only stale lock files after checking owner liveness and acquisition age.
+ *
+ * A live process keeps its lock regardless of age, preventing one slow download
+ * from being replaced by a competing acquisition.
+ */
+async function recoverLock(file) {
+    const owner = await readLock(file);
+    if (owner !== undefined) {
+        try {
+            process.kill(owner.pid, 0);
+            return;
+        }
+        catch (cause) {
+            if (!fileError(cause, "ESRCH"))
+                return;
+        }
+        if ((await readLock(file))?.token !== owner.token)
+            return;
+    }
+    else {
+        try {
+            if (Date.now() - (await (0, promises_1.stat)(file)).mtimeMs < 120_000)
+                return;
+        }
+        catch (cause) {
+            if (fileError(cause, "ENOENT"))
+                return;
+            throw cause;
+        }
+    }
+    await (0, promises_1.rm)(file, { force: true });
+}

package/lib/internal/TreeSitterAssetScope.d.ts

@@ -0,0 +1,23 @@
+import type { ITreeSitterAssetOptions } from "./ITreeSitterAssetOptions";
+/**
+ * Carries parser-asset controls through one asynchronous execution chain.
+ *
+ * Async-local inheritance lets nested checker and adapter instances share a
+ * caller's cache, cancellation, and progress policy without global mutable options.
+ */
+export declare namespace TreeSitterAssetScope {
+    /**
+     * Returns a defensive copy of the current asset controls, or an empty default outside a scope.
+     *
+     * TreeSitterAssets merges this result with constructor options so callers cannot
+     * mutate async-local state through the returned object.
+     */
+    function current(): ITreeSitterAssetOptions;
+    /**
+     * Runs work with inherited asset controls overridden for its asynchronous chain.
+     *
+     * Nested parser construction inherits the merged controls, while sibling tasks
+     * continue to observe the parent scope unchanged.
+     */
+    function run<T>(options: ITreeSitterAssetOptions, closure: () => T): T;
+}

package/lib/internal/TreeSitterAssetScope.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeSitterAssetScope = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * Carries parser-asset controls through one asynchronous execution chain.
+ *
+ * Async-local inheritance lets nested checker and adapter instances share a
+ * caller's cache, cancellation, and progress policy without global mutable options.
+ */
+var TreeSitterAssetScope;
+(function (TreeSitterAssetScope) {
+    /**
+     * Returns a defensive copy of the current asset controls, or an empty default outside a scope.
+     *
+     * TreeSitterAssets merges this result with constructor options so callers cannot
+     * mutate async-local state through the returned object.
+     */
+    function current() {
+        return { ...storage.getStore() };
+    }
+    TreeSitterAssetScope.current = current;
+    /**
+     * Runs work with inherited asset controls overridden for its asynchronous chain.
+     *
+     * Nested parser construction inherits the merged controls, while sibling tasks
+     * continue to observe the parent scope unchanged.
+     */
+    function run(options, closure) {
+        return storage.run({ ...current(), ...options }, closure);
+    }
+    TreeSitterAssetScope.run = run;
+    /**
+     * Stores asset controls for the active asynchronous execution chain.
+     *
+     * This module-level storage carries policy only; importing the scope does not
+     * initialize parsers or access the filesystem.
+     */
+    const storage = new node_async_hooks_1.AsyncLocalStorage();
+})(TreeSitterAssetScope || (exports.TreeSitterAssetScope = TreeSitterAssetScope = {}));

package/lib/internal/TreeSitterAssets.d.ts

@@ -0,0 +1,67 @@
+import type { IEvidenceGrammar } from "../structures/IEvidenceGrammar";
+import type { ITreeSitterAssetOptions } from "./ITreeSitterAssetOptions";
+/**
+ * Reads compiled grammar provenance and lazily acquires verified pinned bytes.
+ *
+ * Metadata validation occurs before cache-key or URL use so a corrupted package
+ * catalog cannot redirect filesystem writes or downloads outside the asset boundary.
+ */
+export declare class TreeSitterAssets {
+    /**
+     * Caches grammar bytes under the inherited and constructor-provided acquisition controls.
+     *
+     * The constructor creates this instance after merging scope controls with local
+     * overrides, so every bytes request follows the same policy.
+     */
+    private readonly cache;
+    /**
+     * Captures optional acquisition overrides without accessing grammar assets.
+     *
+     * Scope controls supply defaults, and explicit constructor options take precedence
+     * before a later bytes call resolves a cache entry or download.
+     */
+    constructor(options?: ITreeSitterAssetOptions);
+    /**
+     * Returns validated grammar metadata without initializing WASM or acquiring bytes.
+     *
+     * Consumers can inspect the compiled catalog safely because readManifest rejects
+     * invalid records before they are returned.
+     */
+    list(): Promise<IEvidenceGrammar[]>;
+    /**
+     * Resolves one validated pinned grammar by its catalog ID.
+     *
+     * This lookup does not prepare or load the WASM bytes; unknown IDs become an
+     * asset-manifest error with repair guidance.
+     */
+    grammar(id: string): Promise<IEvidenceGrammar>;
+    /**
+     * Obtains a caller-owned copy of verified grammar bytes from the immutable cache.
+     *
+     * Input is cloned and validated before cache acquisition, preventing unsafe
+     * metadata from selecting a filesystem key or network destination.
+     */
+    bytes(input: IEvidenceGrammar): Promise<Uint8Array>;
+    /**
+     * Validates the packaged grammar pins and rejects duplicate identifiers.
+     *
+     * list delegates here before exposing metadata, ensuring each grammar has safe
+     * provenance paths and credential-free HTTPS asset URLs. The pins are imported
+     * from parser-grammars.json as a plain module; no payload bytes are read here.
+     */
+    private readManifest;
+    /**
+     * Rejects unsafe asset metadata before it chooses a filesystem key or network destination.
+     *
+     * Both grammar WASM and license records require relative provenance paths and
+     * credential-free HTTPS URLs to remain within the asset trust boundary.
+     */
+    private validate;
+    /**
+     * Requires a provenance path to remain relative on every supported platform.
+     *
+     * This lexical validation rejects empty, absolute, and parent-traversing paths
+     * without requiring the referenced asset file to exist locally.
+     */
+    private location;
+}