@wrtnlabs/evidence 0.0.0

package/lib/internal/SourceCollector.d.ts

@@ -0,0 +1,62 @@
+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

@@ -0,0 +1,301 @@
+"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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,23 @@
+"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

@@ -0,0 +1,43 @@
+/**
+ * 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

@@ -0,0 +1,93 @@
+"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 = {}));

package/lib/internal/SourceText.d.ts

@@ -0,0 +1,40 @@
+import type { IEvidenceSourcePosition } from "../structures/IEvidenceSourcePosition";
+import type { IEvidenceSourceRange } from "../structures/IEvidenceSourceRange";
+/**
+ * Maps original UTF-16 offsets to source coordinates without rewriting text.
+ *
+ * Parser and documentation positions both use JavaScript string offsets, so
+ * preserving BOM and line-ending bytes avoids a later location translation.
+ */
+export declare class SourceText {
+    readonly content: string;
+    private readonly lines;
+    /**
+     * Indexes line starts in the supplied immutable source content.
+     *
+     * Range conversion uses this table to translate parser UTF-16 offsets without
+     * rescanning the source string for every diagnostic or host position.
+     */
+    constructor(content: string);
+    /**
+     * Resolves one bounded UTF-16 offset to one-based line and column coordinates.
+     *
+     * Parser and documentation mapping consumers use this conversion when emitting
+     * source ranges with human-readable positions.
+     */
+    position(offset: number): IEvidenceSourcePosition;
+    /**
+     * Builds a validated half-open range from offsets in this exact source string.
+     *
+     * The result includes positions derived from the same immutable content, so
+     * adapters cannot pair offsets from one source snapshot with another.
+     */
+    range(start: number, end: number): IEvidenceSourceRange;
+    /**
+     * Checks whether positions and offsets agree with this source.
+     *
+     * It returns false for malformed or cross-content ranges, allowing callers to
+     * reject invalid parser output before it enters an inventory.
+     */
+    contains(range: IEvidenceSourceRange): boolean;
+}

package/lib/internal/SourceText.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourceText = void 0;
+/**
+ * Maps original UTF-16 offsets to source coordinates without rewriting text.
+ *
+ * Parser and documentation positions both use JavaScript string offsets, so
+ * preserving BOM and line-ending bytes avoids a later location translation.
+ */
+class SourceText {
+    content;
+    lines = [0];
+    /**
+     * Indexes line starts in the supplied immutable source content.
+     *
+     * Range conversion uses this table to translate parser UTF-16 offsets without
+     * rescanning the source string for every diagnostic or host position.
+     */
+    constructor(content) {
+        this.content = content;
+        for (let index = 0; index < content.length; ++index)
+            if (content[index] === "\n")
+                this.lines.push(index + 1);
+    }
+    /**
+     * Resolves one bounded UTF-16 offset to one-based line and column coordinates.
+     *
+     * Parser and documentation mapping consumers use this conversion when emitting
+     * source ranges with human-readable positions.
+     */
+    position(offset) {
+        if (!Number.isSafeInteger(offset) ||
+            offset < 0 ||
+            offset > this.content.length)
+            throw new Error("The source offset is outside the original string.");
+        let left = 0;
+        let right = this.lines.length;
+        while (left + 1 < right) {
+            const middle = Math.floor((left + right) / 2);
+            if ((this.lines[middle] ?? 0) <= offset)
+                left = middle;
+            else
+                right = middle;
+        }
+        return {
+            offset,
+            line: left + 1,
+            column: offset - (this.lines[left] ?? 0) + 1,
+        };
+    }
+    /**
+     * Builds a validated half-open range from offsets in this exact source string.
+     *
+     * The result includes positions derived from the same immutable content, so
+     * adapters cannot pair offsets from one source snapshot with another.
+     */
+    range(start, end) {
+        if (end < start)
+            throw new Error("The source range ends before it starts.");
+        return { start: this.position(start), end: this.position(end) };
+    }
+    /**
+     * Checks whether positions and offsets agree with this source.
+     *
+     * It returns false for malformed or cross-content ranges, allowing callers to
+     * reject invalid parser output before it enters an inventory.
+     */
+    contains(range) {
+        try {
+            const expected = this.range(range.start.offset, range.end.offset);
+            return (expected.start.line === range.start.line &&
+                expected.start.column === range.start.column &&
+                expected.end.line === range.end.line &&
+                expected.end.column === range.end.column);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.SourceText = SourceText;