@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/internal/ParserSlots.js

@@ -1,113 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ParserSlots = void 0;
-/**
- * FIFO admission queue for the lifetime of parser extraction callbacks.
- *
- * Acquire reserves ownership until the caller releases it in cleanup. Closing
- * rejects new requests while allowing already queued requests to drain, so the
- * parser runtime can wait for all accepted native-resource owners to finish.
- */
-class ParserSlots {
-    limit;
-    /**
-     * Number of reserved slots, including slots transferred to queued requests.
-     *
-     * A transfer keeps this count unchanged until the receiving request releases it.
-     */
-    active = 0;
-    /**
-     * Whether admission has closed to new requests.
-     *
-     * Accepted requests may still be active or queued while close waits for drainage.
-     */
-    closed = false;
-    /**
-     * Resolvers waiting for ownership in arrival order.
-     *
-     * Releasing a slot wakes the oldest request before reducing the active count.
-     */
-    queue = [];
-    /**
-     * Close callers waiting for the final reserved slot to be released.
-     *
-     * Retaining all resolvers makes repeated concurrent close calls await one drain.
-     */
-    drains = [];
-    /**
-     * Creates an empty queue with the parser runtime's validated concurrency limit.
-     *
-     * Validation belongs to the public parser options boundary; this queue only
-     * manages ownership and assumes a positive integer limit.
-     */
-    constructor(
-    /**
-     * Maximum simultaneously reserved slots.
-     *
-     * Requests beyond this bound wait until an existing owner releases its slot.
-     */
-    limit) {
-        this.limit = limit;
-    }
-    /**
-     * Counts accepted requests that do not yet own a slot.
-     *
-     * Runtime state inspection uses this separately from the active reservation count.
-     */
-    get waiting() {
-        return this.queue.length;
-    }
-    /**
-     * Reserves an available slot or waits for FIFO ownership transfer.
-     *
-     * Requests arriving after close reject immediately. A request accepted before
-     * close still resumes and must eventually call release exactly once.
-     */
-    async acquire() {
-        if (this.closed)
-            throw new Error("The parser runtime is closed.");
-        if (this.active < this.limit) {
-            ++this.active;
-            return;
-        }
-        const pending = new Promise((resolve) => {
-            this.queue.push(resolve);
-        });
-        await pending;
-    }
-    /**
-     * Relinquishes one acquired slot and advances accepted work.
-     *
-     * The caller must have acquired ownership. Once no queued successor or active
-     * owner remains, every pending close operation is released.
-     */
-    release() {
-        const next = this.queue.shift();
-        // Transfer ownership without lowering active: close must not observe a
-        // temporary zero while an already accepted request is about to resume.
-        if (next !== undefined)
-            next();
-        else {
-            --this.active;
-            if (this.active === 0)
-                for (const drain of this.drains.splice(0))
-                    drain();
-        }
-    }
-    /**
-     * Stops new admission and waits for every accepted request to release ownership.
-     *
-     * Call this outside an owned slot; awaiting close while holding a slot would
-     * wait for the caller's own release.
-     */
-    async close() {
-        this.closed = true;
-        if (this.active === 0)
-            return;
-        const pending = new Promise((resolve) => {
-            this.drains.push(resolve);
-        });
-        await pending;
-    }
-}
-exports.ParserSlots = ParserSlots;

package/lib/internal/SourceCollector.d.ts

@@ -1,62 +0,0 @@
-import type { IEvidenceSourceSnapshot } from "../structures/IEvidenceSourceSnapshot";
-import type { FileGlob } from "./FileGlob";
-/**
- * Collects one configured filesystem population into a stable source snapshot.
- *
- * Logical aliases remain attached to a single physical file identity, while
- * dependency tracking retains intermediate paths so watch mode can recover from
- * missing files, symlink changes, and read failures.
- */
-export declare class SourceCollector {
-    private readonly directory;
-    private readonly root;
-    private readonly files;
-    private readonly versions;
-    private readonly dependencies;
-    private readonly diagnostics;
-    /**
-     * Initializes collection for one declared root relative to its configuration file.
-     *
-     * Construction records lexical and display paths only; scanning later resolves
-     * the filesystem so a caller can configure globs before any access occurs.
-     */
-    constructor(configFile: string, declared: string);
-    /**
-     * Recursively discovers files selected by ordered globs and records root failures.
-     *
-     * The collector retains failed root paths as dependencies so watch mode can
-     * observe the repair instead of requiring a configuration edit.
-     */
-    scan(globs: FileGlob): Promise<void>;
-    /**
-     * Loads one exact local source path and retains failures as watch dependencies.
-     *
-     * Exact selection rejects remote URLs and reports filesystem errors without
-     * aborting sibling source collection work.
-     */
-    exact(file: string): Promise<void>;
-    /**
-     * Returns collected files, dependencies, and diagnostics for one analysis pass.
-     *
-     * Addresses, files, and dependencies are sorted with bytewise comparisons so
-     * equivalent source snapshots do not vary with filesystem traversal order.
-     */
-    snapshot(): IEvidenceSourceSnapshot;
-    private walk;
-    private read;
-    private resolvePhysical;
-    /**
-     * Merges a dependency observation and retains recursive monitoring when required.
-     *
-     * Multiple reads of one path share a dependency record; any directory consumer
-     * can promote it to recursive watching without losing earlier observations.
-     */
-    private watch;
-    /**
-     * Converts an expected collection failure into a retained diagnostic.
-     *
-     * Sibling paths continue scanning, while `SourceFailure` preserves its specific
-     * diagnostic code instead of becoming the caller-supplied fallback category.
-     */
-    private report;
-}

package/lib/internal/SourceCollector.js

@@ -1,301 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SourceCollector = void 0;
-const node_crypto_1 = require("node:crypto");
-const promises_1 = require("node:fs/promises");
-const node_path_1 = __importDefault(require("node:path"));
-const SourceFailure_1 = require("./SourceFailure");
-const SourcePath_1 = require("./SourcePath");
-/**
- * Collects one configured filesystem population into a stable source snapshot.
- *
- * Logical aliases remain attached to a single physical file identity, while
- * dependency tracking retains intermediate paths so watch mode can recover from
- * missing files, symlink changes, and read failures.
- */
-class SourceCollector {
-    directory;
-    root;
-    files = new Map();
-    versions = new Map();
-    dependencies = new Map();
-    diagnostics = [];
-    /**
-     * Initializes collection for one declared root relative to its configuration file.
-     *
-     * Construction records lexical and display paths only; scanning later resolves
-     * the filesystem so a caller can configure globs before any access occurs.
-     */
-    constructor(configFile, declared) {
-        this.directory = node_path_1.default.dirname(node_path_1.default.resolve(configFile));
-        const absolute = SourcePath_1.SourcePath.root(configFile, declared);
-        this.root = {
-            declared,
-            absolute,
-            display: SourcePath_1.SourcePath.display(this.directory, absolute),
-        };
-    }
-    /**
-     * Recursively discovers files selected by ordered globs and records root failures.
-     *
-     * The collector retains failed root paths as dependencies so watch mode can
-     * observe the repair instead of requiring a configuration edit.
-     */
-    async scan(globs) {
-        this.watch(this.root.absolute, true);
-        try {
-            const physical = await this.resolvePhysical(this.root.absolute);
-            const info = await (0, promises_1.stat)(physical, { bigint: true });
-            if (!info.isDirectory())
-                throw new Error("The population root is not a directory.");
-            this.root.physical = physical;
-            this.watch(physical, true);
-            await this.walk(this.root.absolute, "", physical, info, globs, new Set());
-        }
-        catch (cause) {
-            this.report("root-unreadable", this.root.absolute, cause);
-        }
-    }
-    /**
-     * Loads one exact local source path and retains failures as watch dependencies.
-     *
-     * Exact selection rejects remote URLs and reports filesystem errors without
-     * aborting sibling source collection work.
-     */
-    async exact(file) {
-        if (/^https?:\/\//i.test(file))
-            throw new Error("The filesystem source loader accepts local files; remote documents require their adapter.");
-        const absolute = SourcePath_1.SourcePath.resolve(this.root.absolute, file);
-        this.watch(absolute, false);
-        this.watch(SourcePath_1.SourcePath.slash(node_path_1.default.dirname(absolute)), false);
-        try {
-            const physical = await this.resolvePhysical(absolute);
-            const info = await (0, promises_1.stat)(physical, { bigint: true });
-            if (!info.isFile())
-                throw new SourceFailure_1.SourceFailure("not-file", "The selected path is not a regular file.");
-            await this.read(absolute, SourcePath_1.SourcePath.display(this.root.absolute, absolute), physical, info);
-        }
-        catch (cause) {
-            this.report("path-unreadable", absolute, cause);
-        }
-    }
-    /**
-     * Returns collected files, dependencies, and diagnostics for one analysis pass.
-     *
-     * Addresses, files, and dependencies are sorted with bytewise comparisons so
-     * equivalent source snapshots do not vary with filesystem traversal order.
-     */
-    snapshot() {
-        const files = [...this.files.values()];
-        for (const file of files)
-            file.addresses.sort((left, right) => compare(left.relative, right.relative));
-        files.sort((left, right) => compare(left.addresses[0]?.relative ?? left.physicalPath, right.addresses[0]?.relative ?? right.physicalPath));
-        return {
-            root: this.root,
-            files,
-            dependencies: [...this.dependencies.values()].sort((left, right) => compare(left.path, right.path)),
-            diagnostics: this.diagnostics,
-            complete: this.diagnostics.length === 0,
-        };
-    }
-    /**
-     * Walks a physical directory through its logical address while preventing symlink cycles.
-     *
-     * The traversal retains both spellings: logical paths form public addresses,
-     * while physical identity detects recursive links and duplicate files.
-     */
-    async walk(absolute, relative, physical, info, globs, ancestors) {
-        const id = identity(info, physical);
-        if (ancestors.has(id))
-            throw new SourceFailure_1.SourceFailure("symlink-cycle", "A directory link returns to an ancestor; remove the cycle or exclude this subtree.");
-        this.watch(absolute, true);
-        this.watch(physical, true);
-        const next = new Set(ancestors);
-        next.add(id);
-        const entries = (await (0, promises_1.readdir)(physical)).sort(compare);
-        for (const name of entries) {
-            const location = relative === "" ? name : relative + "/" + name;
-            const selected = globs.matches(location);
-            const descend = globs.couldMatchDescendant(location);
-            if (!selected && !descend)
-                continue;
-            const filename = SourcePath_1.SourcePath.slash(node_path_1.default.join(absolute, name));
-            const target = SourcePath_1.SourcePath.slash(node_path_1.default.join(physical, name));
-            this.watch(filename, false);
-            this.watch(target, false);
-            try {
-                // readdir supplies exact names under an already resolved parent.
-                const entry = await (0, promises_1.lstat)(target, { bigint: true });
-                const linked = entry.isSymbolicLink();
-                const resolved = linked
-                    ? await this.resolvePhysical(target, new Set(), false)
-                    : target;
-                const metadata = linked
-                    ? await (0, promises_1.stat)(resolved, { bigint: true })
-                    : entry;
-                if (metadata.isDirectory()) {
-                    if (descend)
-                        await this.walk(filename, location, resolved, metadata, globs, next);
-                }
-                else if (selected) {
-                    if (!metadata.isFile())
-                        throw new SourceFailure_1.SourceFailure("not-file", "The selected path is not a regular file.");
-                    await this.read(filename, location, resolved, metadata);
-                }
-            }
-            catch (cause) {
-                this.report("path-unreadable", filename, cause);
-            }
-        }
-    }
-    /**
-     * Reads one stable physical file after validating metadata before and after I/O.
-     *
-     * Alias addresses coalesce only when their device and inode version remains
-     * stable, preventing a changing file from yielding an incoherent snapshot.
-     */
-    async read(absolute, relative, physical, info) {
-        this.watch(absolute, false);
-        this.watch(physical, false);
-        const address = {
-            absolute,
-            relative,
-            display: SourcePath_1.SourcePath.display(this.directory, absolute),
-        };
-        const id = identity(info, physical);
-        const existing = this.files.get(id);
-        if (existing !== undefined) {
-            if (this.versions.get(id) !== version(info))
-                throw new SourceFailure_1.SourceFailure("source-changed", "The file changed between selected aliases; retry discovery.");
-            existing.addresses.push(address);
-            return;
-        }
-        const handle = await (0, promises_1.open)(physical, "r");
-        try {
-            const before = await handle.stat({ bigint: true });
-            const bytes = await handle.readFile();
-            const after = await handle.stat({ bigint: true });
-            if (identity(before, physical) !== id ||
-                before.size !== after.size ||
-                before.mtimeNs !== after.mtimeNs ||
-                before.ctimeNs !== after.ctimeNs ||
-                BigInt(bytes.length) !== after.size)
-                throw new SourceFailure_1.SourceFailure("source-changed", "The file changed while it was being read; retry discovery.");
-            let content;
-            try {
-                content = new TextDecoder("utf-8", {
-                    fatal: true,
-                    ignoreBOM: true,
-                }).decode(bytes);
-            }
-            catch {
-                throw new SourceFailure_1.SourceFailure("invalid-encoding", "The selected file is not valid UTF-8; save it as UTF-8 or correct the files selection.");
-            }
-            this.files.set(id, {
-                id,
-                physicalPath: physical,
-                content,
-                digest: (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex"),
-                addresses: [address],
-            });
-            this.versions.set(id, version(after));
-        }
-        finally {
-            await handle.close();
-        }
-    }
-    /**
-     * Resolves each symlink component while tracking links and configured path casing.
-     *
-     * Exact-case validation protects portable source identities, and link tracking
-     * reports cycles before recursive filesystem resolution can loop.
-     */
-    async resolvePhysical(absolute, links = new Set(), checkCase = true) {
-        const parsed = node_path_1.default.parse(absolute);
-        let current = parsed.root;
-        const segments = absolute
-            .slice(parsed.root.length)
-            .split(/[\\/]/)
-            .filter((part) => part !== "");
-        for (const segment of segments) {
-            this.watch(SourcePath_1.SourcePath.slash(current), false);
-            if (checkCase) {
-                const names = await (0, promises_1.readdir)(current);
-                if (!names.includes(segment)) {
-                    const actual = names.find((name) => name.toLowerCase() === segment.toLowerCase());
-                    if (actual !== undefined)
-                        throw new SourceFailure_1.SourceFailure("case-mismatch", `Path segment '${segment}' is spelled '${actual}' on disk; use that exact case.`);
-                }
-            }
-            current = node_path_1.default.join(current, segment);
-            this.watch(SourcePath_1.SourcePath.slash(current), false);
-            const entry = await (0, promises_1.lstat)(current);
-            if (entry.isSymbolicLink()) {
-                if (links.has(current))
-                    throw new SourceFailure_1.SourceFailure("symlink-cycle", "The selected path contains a cyclic symbolic link.");
-                const next = new Set(links);
-                next.add(current);
-                current = await this.resolvePhysical(node_path_1.default.resolve(node_path_1.default.dirname(current), await (0, promises_1.readlink)(current)), next, false);
-            }
-        }
-        return SourcePath_1.SourcePath.slash(await (0, promises_1.realpath)(current));
-    }
-    /**
-     * Merges a dependency observation and retains recursive monitoring when required.
-     *
-     * Multiple reads of one path share a dependency record; any directory consumer
-     * can promote it to recursive watching without losing earlier observations.
-     */
-    watch(location, recursive) {
-        const existing = this.dependencies.get(location);
-        this.dependencies.set(location, {
-            path: location,
-            recursive: recursive || existing?.recursive === true,
-        });
-    }
-    /**
-     * Converts an expected collection failure into a retained diagnostic.
-     *
-     * Sibling paths continue scanning, while `SourceFailure` preserves its specific
-     * diagnostic code instead of becoming the caller-supplied fallback category.
-     */
-    report(fallback, location, cause) {
-        const message = cause instanceof Error ? cause.message : String(cause);
-        this.diagnostics.push({
-            code: cause instanceof SourceFailure_1.SourceFailure ? cause.code : fallback,
-            path: location,
-            message: `Could not discover '${location}': ${message}`,
-        });
-    }
-}
-exports.SourceCollector = SourceCollector;
-/**
- * Produces stable file identity from device and inode metadata when available.
- *
- * Source collection falls back to the resolved physical path on filesystems
- * without inode support, allowing aliases to coalesce consistently per host.
- */
-function identity(info, physical) {
-    return info.ino === 0n ? "path:" + physical : `file:${info.dev}:${info.ino}`;
-}
-/**
- * Sorts filesystem names without locale rules.
- *
- * Bytewise ordering keeps source snapshots stable across machines whose locale
- * settings would otherwise order the same directory entries differently.
- */
-function compare(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}
-/**
- * Encodes metadata needed to detect a file changed through a second alias.
- *
- * Alias coalescing compares this value before accepting another address for a
- * file already captured in the current source snapshot.
- */
-function version(info) {
-    return `${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
-}

package/lib/internal/SourceFailure.d.ts

@@ -1,17 +0,0 @@
-import type { IEvidenceSourceDiagnostic } from "../structures/IEvidenceSourceDiagnostic";
-/**
- * Discovery failure carrying the source diagnostic category that callers report.
- *
- * The collector converts these failures at filesystem boundaries, separating
- * expected source conditions from unexpected operational errors.
- */
-export declare class SourceFailure extends Error {
-    readonly code: IEvidenceSourceDiagnostic["code"];
-    /**
-     * Creates a source-discovery failure with a reportable diagnostic code.
-     *
-     * `SourceCollector` catches this expected failure at filesystem boundaries and
-     * preserves its category instead of collapsing it into a generic read error.
-     */
-    constructor(code: IEvidenceSourceDiagnostic["code"], message: string);
-}

package/lib/internal/SourceFailure.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SourceFailure = void 0;
-/**
- * Discovery failure carrying the source diagnostic category that callers report.
- *
- * The collector converts these failures at filesystem boundaries, separating
- * expected source conditions from unexpected operational errors.
- */
-class SourceFailure extends Error {
-    code;
-    /**
-     * Creates a source-discovery failure with a reportable diagnostic code.
-     *
-     * `SourceCollector` catches this expected failure at filesystem boundaries and
-     * preserves its category instead of collapsing it into a generic read error.
-     */
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-    }
-}
-exports.SourceFailure = SourceFailure;

package/lib/internal/SourcePath.d.ts

@@ -1,43 +0,0 @@
-/**
- * Performs lexical path normalization without filesystem access or case folding.
- *
- * Source discovery owns physical resolution; these helpers preserve authored
- * spelling boundaries so logical addresses remain portable across platforms.
- */
-export declare namespace SourcePath {
-    /**
-     * Resolves a portable absolute or relative path and rejects drive-relative notation.
-     *
-     * Source collection uses the result for lexical addressing before physical
-     * resolution, preserving platform-independent configured path behavior.
-     */
-    function resolve(base: string, value: string): string;
-    /**
-     * Resolves a configured population root while keeping glob syntax confined to files.
-     *
-     * Roots must name concrete directories, so this boundary rejects glob markers
-     * before discovery can confuse a pattern with a filesystem location.
-     */
-    function root(configFile: string, declared: string): string;
-    /**
-     * Produces a slash-normalized diagnostic path relative to a stable display base.
-     *
-     * Diagnostic and public source addresses use this display spelling without
-     * changing the absolute path used for filesystem operations.
-     */
-    function display(base: string, absolute: string): string;
-    /**
-     * Tests both logical and resolved physical paths when bounding reexports.
-     *
-     * A path is inside the selected root only when neither authored symlink paths
-     * nor their resolved filesystem locations escape that boundary.
-     */
-    function contains(root: string, absolute: string): boolean;
-    /**
-     * Converts separators without canonicalizing dot segments or case.
-     *
-     * Callers use this narrow normalization for portable keys while physical path
-     * resolution remains responsible for filesystem-aware canonicalization.
-     */
-    function slash(value: string): string;
-}

package/lib/internal/SourcePath.js

@@ -1,93 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SourcePath = void 0;
-const node_path_1 = __importDefault(require("node:path"));
-/**
- * Performs lexical path normalization without filesystem access or case folding.
- *
- * Source discovery owns physical resolution; these helpers preserve authored
- * spelling boundaries so logical addresses remain portable across platforms.
- */
-var SourcePath;
-(function (SourcePath) {
-    /**
-     * Resolves a portable absolute or relative path and rejects drive-relative notation.
-     *
-     * Source collection uses the result for lexical addressing before physical
-     * resolution, preserving platform-independent configured path behavior.
-     */
-    function resolve(base, value) {
-        const normalized = value.replaceAll("\\", "/");
-        if (/^[A-Za-z]:(?!\/)/.test(normalized))
-            throw new Error(`Path '${value}' is drive-relative; write its full path.`);
-        if (process.platform !== "win32" && /^[A-Za-z]:/.test(normalized))
-            throw new Error(`Windows path '${value}' cannot be resolved on this platform.`);
-        return slash(node_path_1.default.resolve(base, normalized));
-    }
-    SourcePath.resolve = resolve;
-    /**
-     * Resolves a configured population root while keeping glob syntax confined to files.
-     *
-     * Roots must name concrete directories, so this boundary rejects glob markers
-     * before discovery can confuse a pattern with a filesystem location.
-     */
-    function root(configFile, declared) {
-        if (declared.trim() !== declared || declared === "")
-            throw new Error("A population root must not be empty or padded with whitespace.");
-        if (declared.includes("*") || declared.includes("?"))
-            throw new Error("A population root names one directory; put globs in files.");
-        return resolve(node_path_1.default.dirname(node_path_1.default.resolve(configFile)), declared);
-    }
-    SourcePath.root = root;
-    /**
-     * Produces a slash-normalized diagnostic path relative to a stable display base.
-     *
-     * Diagnostic and public source addresses use this display spelling without
-     * changing the absolute path used for filesystem operations.
-     */
-    function display(base, absolute) {
-        const relative = slash(node_path_1.default.relative(base, absolute));
-        return relative === "" ? "." : relative;
-    }
-    SourcePath.display = display;
-    /**
-     * Tests both logical and resolved physical paths when bounding reexports.
-     *
-     * A path is inside the selected root only when neither authored symlink paths
-     * nor their resolved filesystem locations escape that boundary.
-     */
-    function contains(root, absolute) {
-        const prefix = normalize(root);
-        const target = normalize(absolute);
-        return (target === prefix ||
-            target.startsWith(prefix.endsWith("/") ? prefix : prefix + "/"));
-    }
-    SourcePath.contains = contains;
-    /**
-     * Converts separators without canonicalizing dot segments or case.
-     *
-     * Callers use this narrow normalization for portable keys while physical path
-     * resolution remains responsible for filesystem-aware canonicalization.
-     */
-    function slash(value) {
-        return value.replaceAll("\\", "/");
-    }
-    SourcePath.slash = slash;
-    /**
-     * Selects the appropriate path flavor for lexical containment comparison.
-     *
-     * This helper deliberately avoids filesystem access, allowing root-boundary
-     * checks to operate on configured and resolved path spellings alike.
-     */
-    function normalize(value) {
-        const normalized = slash(value);
-        const flavor = /^[A-Za-z]:/.test(normalized) || normalized.startsWith("//")
-            ? node_path_1.default.win32
-            : node_path_1.default.posix;
-        const result = slash(flavor.normalize(normalized)).replace(/\/+$/, "");
-        return result === "" ? "/" : result;
-    }
-})(SourcePath || (exports.SourcePath = SourcePath = {}));