@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/internal/EvidenceSourceCollector.d.ts

@@ -0,0 +1,70 @@
+import type { IEvidenceSourceSnapshot } from "../structures/IEvidenceSourceSnapshot";
+import type { EvidenceFileGlob } from "./EvidenceFileGlob";
+/**
+ * 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 EvidenceSourceCollector {
+    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: EvidenceFileGlob): 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 `EvidenceSourceFailure` preserves
+     * its specific diagnostic code instead of becoming the caller-supplied
+     * fallback category.
+     */
+    private report;
+}

package/lib/internal/EvidenceSourceCollector.js

@@ -0,0 +1,331 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSourceCollector = 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 EvidenceSourceFailure_1 = require("./EvidenceSourceFailure");
+const EvidenceSourcePath_1 = require("./EvidenceSourcePath");
+/**
+ * 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 EvidenceSourceCollector {
+    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 = EvidenceSourcePath_1.EvidenceSourcePath.root(configFile, declared);
+        this.root = {
+            declared,
+            absolute,
+            display: EvidenceSourcePath_1.EvidenceSourcePath.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 = EvidenceSourcePath_1.EvidenceSourcePath.resolve(this.root.absolute, file);
+        this.watch(absolute, false);
+        this.watch(EvidenceSourcePath_1.EvidenceSourcePath.slash(node_path_1.default.dirname(absolute)), false);
+        try {
+            const rootPhysical = await this.resolvePhysical(this.root.absolute);
+            const rootInfo = await (0, promises_1.stat)(rootPhysical, { bigint: true });
+            if (!rootInfo.isDirectory())
+                throw new EvidenceSourceFailure_1.EvidenceSourceFailure("root-unreadable", "The population root is not a directory.");
+            this.root.physical = rootPhysical;
+            this.watch(rootPhysical, true);
+            const physical = await this.resolvePhysical(absolute);
+            const info = await (0, promises_1.stat)(physical, { bigint: true });
+            if (!info.isFile())
+                throw new EvidenceSourceFailure_1.EvidenceSourceFailure("not-file", "The selected path is not a regular file.");
+            await this.read(absolute, EvidenceSourcePath_1.EvidenceSourcePath.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));
+            const declaring = file.addresses[0];
+            if (declaring !== undefined)
+                file.fingerprintPath = declaring.display;
+        }
+        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 EvidenceSourceFailure_1.EvidenceSourceFailure("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 = EvidenceSourcePath_1.EvidenceSourcePath.slash(node_path_1.default.join(absolute, name));
+            const target = EvidenceSourcePath_1.EvidenceSourcePath.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 EvidenceSourceFailure_1.EvidenceSourceFailure("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: EvidenceSourcePath_1.EvidenceSourcePath.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 EvidenceSourceFailure_1.EvidenceSourceFailure("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 EvidenceSourceFailure_1.EvidenceSourceFailure("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 EvidenceSourceFailure_1.EvidenceSourceFailure("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,
+                fingerprintPath: address.display,
+                ...(this.root.physical === undefined
+                    ? {}
+                    : {
+                        fingerprintRoot: {
+                            physicalPath: this.root.physical,
+                            fingerprintPath: this.root.display,
+                        },
+                    }),
+                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(EvidenceSourcePath_1.EvidenceSourcePath.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 EvidenceSourceFailure_1.EvidenceSourceFailure("case-mismatch", `Path segment '${segment}' is spelled '${actual}' on disk; use that exact case.`);
+                }
+            }
+            current = node_path_1.default.join(current, segment);
+            this.watch(EvidenceSourcePath_1.EvidenceSourcePath.slash(current), false);
+            const entry = await (0, promises_1.lstat)(current);
+            if (entry.isSymbolicLink()) {
+                if (links.has(current))
+                    throw new EvidenceSourceFailure_1.EvidenceSourceFailure("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 EvidenceSourcePath_1.EvidenceSourcePath.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 `EvidenceSourceFailure` 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 EvidenceSourceFailure_1.EvidenceSourceFailure ? cause.code : fallback,
+            path: location,
+            message: `Could not discover '${location}': ${message}`,
+        });
+    }
+}
+exports.EvidenceSourceCollector = EvidenceSourceCollector;
+/**
+ * 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/EvidenceSourceFailure.d.ts

@@ -0,0 +1,19 @@
+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 EvidenceSourceFailure extends Error {
+    readonly code: IEvidenceSourceDiagnostic["code"];
+    /**
+     * Creates a source-discovery failure with a reportable diagnostic code.
+     *
+     * `EvidenceSourceCollector` 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/EvidenceSourceFailure.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSourceFailure = 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 EvidenceSourceFailure extends Error {
+    code;
+    /**
+     * Creates a source-discovery failure with a reportable diagnostic code.
+     *
+     * `EvidenceSourceCollector` 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.EvidenceSourceFailure = EvidenceSourceFailure;

package/lib/internal/EvidenceSourcePath.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 EvidenceSourcePath {
+    /**
+     * 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/EvidenceSourcePath.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSourcePath = 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 EvidenceSourcePath;
+(function (EvidenceSourcePath) {
+    /**
+     * 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));
+    }
+    EvidenceSourcePath.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);
+    }
+    EvidenceSourcePath.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;
+    }
+    EvidenceSourcePath.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 + "/"));
+    }
+    EvidenceSourcePath.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("\\", "/");
+    }
+    EvidenceSourcePath.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;
+    }
+})(EvidenceSourcePath || (exports.EvidenceSourcePath = EvidenceSourcePath = {}));

package/lib/internal/EvidenceSourceText.d.ts

@@ -0,0 +1,42 @@
+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 EvidenceSourceText {
+    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;
+}