@wrtnlabs/evidence 0.0.0

package/lib/internal/EvidenceFingerprintIndex.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceFingerprintIndex = void 0;
+const node_crypto_1 = require("node:crypto");
+const InventoryMerge_1 = require("./InventoryMerge");
+const VERSION = 1;
+const PRESENTED_LENGTH = 7;
+/**
+ * Computes and memoizes stable fingerprints for inventory units and descendants.
+ *
+ * Fingerprints exclude annotation text and presentation-only whitespace so an
+ * acknowledgement edit does not look like a specification change. The index
+ * owns only references to the immutable analysis inventory.
+ */
+class EvidenceFingerprintIndex {
+    annotations = new Map();
+    children = new Map();
+    contentDigests = new Map();
+    fingerprints = new Map();
+    sources = new Map();
+    units = new Map();
+    /** Builds source, annotation, and parent indexes once for one inventory snapshot.
+     *
+     * Fingerprint generation reuses these indexes to connect units to their physical content without repeatedly scanning inventory collections.
+     */
+    constructor(inventory) {
+        for (const source of inventory.sources)
+            this.sources.set(source.physicalPath, source);
+        for (const annotation of inventory.annotationRanges) {
+            if (annotation.range === undefined)
+                continue;
+            const ranges = this.annotations.get(annotation.file) ?? [];
+            ranges.push(annotation.range);
+            this.annotations.set(annotation.file, ranges);
+        }
+        for (const ranges of this.annotations.values())
+            ranges.sort(compareRanges);
+        for (const unit of inventory.units) {
+            if (this.units.has(unit.id))
+                continue;
+            this.units.set(unit.id, unit);
+            if (unit.parentId === undefined)
+                continue;
+            const children = this.children.get(unit.parentId) ?? [];
+            children.push(unit);
+            this.children.set(unit.parentId, children);
+        }
+    }
+    /**
+     * Returns the root content digest and subtree scope digest for one semantic identity.
+     *
+     * Unknown identities fail rather than producing an empty fingerprint, because
+     * absence would make a stale graph appear unchanged.
+     */
+    inspect(unitId) {
+        const remembered = this.fingerprints.get(unitId);
+        if (remembered !== undefined)
+            return remembered;
+        const root = this.units.get(unitId);
+        if (root === undefined)
+            throw new Error(`Cannot fingerprint unknown semantic identity: ${unitId}`);
+        const scope = this.collect(root).sort((x, y) => {
+            const identity = InventoryMerge_1.InventoryMerge.compare(x.id, y.id);
+            if (identity !== 0)
+                return identity;
+            const symbol = InventoryMerge_1.InventoryMerge.compare(x.symbol, y.symbol);
+            return symbol !== 0
+                ? symbol
+                : InventoryMerge_1.InventoryMerge.compare(this.contentDigest(x), this.contentDigest(y));
+        });
+        const hash = (0, node_crypto_1.createHash)("sha256");
+        hash.update(`@wrtnlabs/evidence:fingerprint:${VERSION}\0`);
+        for (const unit of scope) {
+            hash.update(unit.id);
+            hash.update("\0");
+            hash.update(unit.symbol);
+            hash.update("\0");
+            hash.update(this.contribution(unit));
+            hash.update("\0");
+        }
+        const scopeDigest = hash.digest("hex");
+        const output = {
+            version: VERSION,
+            unitId,
+            contentDigest: this.contentDigest(root),
+            scopeDigest,
+            fingerprint: scopeDigest.slice(0, PRESENTED_LENGTH),
+        };
+        this.fingerprints.set(unitId, output);
+        return output;
+    }
+    /** Collects a cycle-safe structural subtree for one unit.
+     *
+     * The visited set prevents malformed parent links from looping fingerprint generation while preserving each reachable child once.
+     */
+    collect(root) {
+        const output = [];
+        const queue = [root];
+        const visited = new Set();
+        for (let index = 0; index < queue.length; ++index) {
+            const unit = queue[index];
+            if (unit === undefined || visited.has(unit.id))
+                continue;
+            visited.add(unit.id);
+            output.push(unit);
+            queue.push(...(this.children.get(unit.id) ?? []));
+        }
+        return output;
+    }
+    /** Adds withdrawal tags to the content contribution because they alter effective scope.
+     *
+     * A unit's fingerprint must change when a withdrawal changes which declarations remain active, even if its source range is unchanged.
+     */
+    contribution(unit) {
+        const withdrawals = InventoryMerge_1.InventoryMerge.unique(unit.withdrawals.map((withdrawal) => withdrawal.tag), (tag) => tag);
+        return withdrawals.length === 0
+            ? this.contentDigest(unit)
+            : `${this.contentDigest(unit)}\0withdrawn:${withdrawals.join(",")}`;
+    }
+    /** Hashes source sites after stripping mapped annotations and normalizing presentation differences.
+     *
+     * Annotation edits are tracked separately, while substantive source changes remain stable across line-ending and trailing-space differences.
+     */
+    contentDigest(unit) {
+        if (unit.contentDigest !== undefined)
+            return unit.contentDigest;
+        const remembered = this.contentDigests.get(unit.id);
+        if (remembered !== undefined)
+            return remembered;
+        const parts = [];
+        const sites = [...unit.sites].sort((x, y) => InventoryMerge_1.InventoryMerge.compare(JSON.stringify([
+            x.file,
+            x.range.start.offset,
+            x.range.end.offset,
+            x.id,
+        ]), JSON.stringify([
+            y.file,
+            y.range.start.offset,
+            y.range.end.offset,
+            y.id,
+        ])));
+        for (const site of sites) {
+            const source = this.sources.get(site.file);
+            if (source === undefined)
+                throw new Error(`Cannot fingerprint missing source snapshot: ${site.file}`);
+            const content = [...site.content]
+                .sort(compareRanges)
+                .map((range) => this.withoutAnnotations(source, range));
+            parts.push(normalize(content.join("\n")));
+        }
+        const digest = (0, node_crypto_1.createHash)("sha256")
+            .update(normalize(parts.join("\0")))
+            .digest("hex");
+        this.contentDigests.set(unit.id, digest);
+        return digest;
+    }
+    /** Removes only overlapping annotation spans while retaining surrounding source exactly for semantic hashing.
+     *
+     * Ranges are ordered before removal so adjacent or overlapping tags cannot duplicate or erase unrelated source fragments.
+     */
+    withoutAnnotations(source, range) {
+        let cursor = range.start.offset;
+        const fragments = [];
+        for (const annotation of this.annotations.get(source.physicalPath) ?? []) {
+            if (annotation.end.offset <= cursor ||
+                annotation.start.offset >= range.end.offset)
+                continue;
+            const start = Math.max(cursor, annotation.start.offset);
+            const end = Math.min(range.end.offset, annotation.end.offset);
+            if (start > cursor)
+                fragments.push(source.content.slice(cursor, start));
+            cursor = Math.max(cursor, end);
+        }
+        if (cursor < range.end.offset)
+            fragments.push(source.content.slice(cursor, range.end.offset));
+        return fragments.join("");
+    }
+}
+exports.EvidenceFingerprintIndex = EvidenceFingerprintIndex;
+/** Orders source spans by position before content fragments are concatenated.
+ *
+ * Stable ordering makes a fingerprint independent of adapter collection order for sites in the same file.
+ */
+function compareRanges(x, y) {
+    const start = x.start.offset - y.start.offset;
+    return start !== 0 ? start : x.end.offset - y.end.offset;
+}
+/** Normalizes line endings and trailing whitespace without changing interior source content.
+ *
+ * Fingerprints ignore presentation differences that do not affect the authored declaration body.
+ */
+function normalize(text) {
+    const lines = text
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/u, ""));
+    while (lines.at(-1) === "")
+        lines.pop();
+    return lines.join("\n");
+}

package/lib/internal/EvidenceTargetApplicability.d.ts

@@ -0,0 +1,16 @@
+import type { IEvidenceHost } from "../structures/IEvidenceHost";
+import type { IEvidenceTargetStatement } from "../structures/IEvidenceTargetStatement";
+import type { IEvidenceMaterializedReference } from "./IEvidenceMaterializedReference";
+/**
+ * Chooses reference populations that can interpret an authored target.
+ *
+ * The scoring is conservative: when no grammar signal distinguishes references,
+ * the declaration remains available to all of them rather than losing a valid acknowledgement.
+ */
+export declare namespace EvidenceTargetApplicability {
+    /** Selects the highest-affinity references while preserving configuration order.
+     *
+     * A tag is retained for every tied viable population when syntax cannot distinguish the intended reference artifact.
+     */
+    function select(statement: IEvidenceTargetStatement, host: IEvidenceHost, references: IEvidenceMaterializedReference[]): IEvidenceMaterializedReference[];
+}

package/lib/internal/EvidenceTargetApplicability.js

@@ -0,0 +1,144 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceTargetApplicability = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const EvidenceFileTarget_1 = require("../targets/EvidenceFileTarget");
+const EvidenceLanguageRegistry_1 = require("../parsers/EvidenceLanguageRegistry");
+const MarkdownTarget_1 = require("../adapters/markdown/MarkdownTarget");
+/**
+ * Chooses reference populations that can interpret an authored target.
+ *
+ * The scoring is conservative: when no grammar signal distinguishes references,
+ * the declaration remains available to all of them rather than losing a valid acknowledgement.
+ */
+var EvidenceTargetApplicability;
+(function (EvidenceTargetApplicability) {
+    /** Selects the highest-affinity references while preserving configuration order.
+     *
+     * A tag is retained for every tied viable population when syntax cannot distinguish the intended reference artifact.
+     */
+    function select(statement, host, references) {
+        if (statement.target.startsWith("prisma:"))
+            return references.filter((entry) => entry.plan.population.type === "prisma");
+        if (swaggerLike(statement.target))
+            return references.filter((entry) => entry.plan.population.type === "swagger");
+        const scores = references.map((reference) => ({
+            reference,
+            score: affinity(statement.target, host, reference),
+        }));
+        const maximum = Math.max(0, ...scores.map((entry) => entry.score));
+        if (maximum > 1)
+            return scores
+                .filter((entry) => entry.score === maximum)
+                .map((entry) => entry.reference);
+        if (references.length === 1)
+            return [...references];
+        const positive = scores
+            .filter((entry) => entry.score > 0)
+            .map((entry) => entry.reference);
+        return positive.length === 0 ? [...references] : positive;
+    }
+    EvidenceTargetApplicability.select = select;
+})(EvidenceTargetApplicability || (exports.EvidenceTargetApplicability = EvidenceTargetApplicability = {}));
+/** Scores a target by exact inventory file, recognizable grammar, and artifact spelling.
+ *
+ * Selection compares these scores to narrow an ambiguous target only when the available source evidence is decisive.
+ */
+function affinity(target, host, reference) {
+    const type = reference.plan.population.type;
+    if (type === "prisma" || type === "swagger")
+        return 0;
+    if (type === "markdown") {
+        let file;
+        try {
+            file = MarkdownTarget_1.MarkdownTarget.parse(target).file;
+        }
+        catch {
+            return 0;
+        }
+        const exact = reference.inventory.sources.some((source) => source.addresses.some((address) => address.selected !== false &&
+            MarkdownTarget_1.MarkdownTarget.normalize(address.relative) === file));
+        return exact ? 3 : markdownLike(file) ? 2 : 1;
+    }
+    const parsed = parseFileTargets(target, host);
+    if (parsed.length !== 0) {
+        const exact = reference.inventory.sources.some((source) => source.addresses.some((address) => address.selected !== false &&
+            parsed.some((targetAddress) => EvidenceFileTarget_1.EvidenceFileTarget.normalize(address.absolute) ===
+                EvidenceFileTarget_1.EvidenceFileTarget.normalize(targetAddress.file))));
+        if (exact)
+            return 3;
+    }
+    return isParsedType(type) && recognizes(type, targetFile(target)) ? 2 : 0;
+}
+/** Parses against every retained host origin because a physical host can have several logical paths.
+ *
+ * An exact source address may be reachable through multiple configured spellings, each of which can make a target applicable.
+ */
+function parseFileTargets(target, host) {
+    const output = [];
+    for (const origin of host.origins ?? [host.file])
+        try {
+            output.push(EvidenceFileTarget_1.EvidenceFileTarget.parse(target, origin));
+        }
+        catch {
+            continue;
+        }
+    return output;
+}
+/** Checks registry recognition without leaking parser-selection failures into affinity scoring.
+ *
+ * Affinity treats an unrecognized grammar spelling as no signal while adapter analysis reports actual parser failures elsewhere.
+ */
+function recognizes(type, file) {
+    try {
+        EvidenceLanguageRegistry_1.EvidenceLanguageRegistry.select(type, file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Narrows types backed by the language registry, excluding document artifacts with separate target grammars.
+ *
+ * The registry lookup is valid only for programming and database artifact types.
+ */
+function isParsedType(type) {
+    return [
+        ...EvidenceLanguageRegistry_1.EvidenceLanguageRegistry.list(),
+        ...EvidenceLanguageRegistry_1.EvidenceLanguageRegistry.databases(),
+    ].some((entry) => entry.type === type);
+}
+/** Extracts a decodable file portion while retaining a harmless basename for malformed escapes.
+ *
+ * Target affinity must not throw while inspecting incomplete authored text, because ordinary target parsing owns that diagnostic.
+ */
+function targetFile(target) {
+    const hash = target.indexOf("#");
+    const encoded = hash < 0 ? target : target.slice(0, hash);
+    try {
+        return decodeURIComponent(encoded);
+    }
+    catch {
+        return node_path_1.default.basename(encoded);
+    }
+}
+/** Identifies conventional Markdown names when no exact selected source is known.
+ *
+ * This supplies a weak affinity signal for Markdown references without claiming that the file exists in their inventory.
+ */
+function markdownLike(file) {
+    return /\.(?:md|markdown|mdx)$/iu.test(file);
+}
+/** Recognizes API operation spelling before a Swagger reference can parse it.
+ *
+ * The cheap lexical check avoids assigning Swagger affinity to ordinary path-like targets.
+ */
+function swaggerLike(target) {
+    const match = /^([^:\s/]+):\//u.exec(target);
+    const method = match?.[1];
+    return ((method !== undefined && !/^[A-Za-z]$/u.test(method)) ||
+        /^(?:GET|PUT|POST|DELETE|OPTIONS|HEAD|PATCH|TRACE)(?::|\s)/iu.test(target));
+}

package/lib/internal/EvidenceTargetBody.d.ts

@@ -0,0 +1,21 @@
+import type { IEvidenceTargetBody } from "./IEvidenceTargetBody";
+/**
+ * Splits and validates the syntax shared by all authored target bodies.
+ *
+ * Artifact resolution remains outside this helper because the same lexical
+ * token may be valid under more than one selected reference grammar.
+ */
+export declare namespace EvidenceTargetBody {
+    /** Separates the first unquoted target token from its optional explanation.
+     *
+     * Tag parsing calls this before target resolution so prose following the target cannot alter its authored address.
+     */
+    function split(value: string): IEvidenceTargetBody;
+    /**
+     * Rejects missing targets and validates forced file-qualified accessors.
+     *
+     * File path decoding is checked before accessor parsing to keep control
+     * characters out of filesystem resolution and subsequent diagnostics.
+     */
+    function check(target: string, forcedFile: boolean): void;
+}

package/lib/internal/EvidenceTargetBody.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceTargetBody = void 0;
+const EvidenceAccessor_1 = require("../targets/EvidenceAccessor");
+/**
+ * Splits and validates the syntax shared by all authored target bodies.
+ *
+ * Artifact resolution remains outside this helper because the same lexical
+ * token may be valid under more than one selected reference grammar.
+ */
+var EvidenceTargetBody;
+(function (EvidenceTargetBody) {
+    /** Separates the first unquoted target token from its optional explanation.
+     *
+     * Tag parsing calls this before target resolution so prose following the target cannot alter its authored address.
+     */
+    function split(value) {
+        const body = value.trim();
+        let cursor = 0;
+        let quoted = false;
+        let escaped = false;
+        while (cursor < body.length) {
+            const character = body[cursor] ?? "";
+            if (escaped)
+                escaped = false;
+            else if (quoted && character === "\\")
+                escaped = true;
+            else if (character === '"')
+                quoted = !quoted;
+            else if (!quoted && /\s/u.test(character))
+                break;
+            ++cursor;
+        }
+        return {
+            target: body.slice(0, cursor),
+            remainder: body.slice(cursor).trim(),
+        };
+    }
+    EvidenceTargetBody.split = split;
+    /**
+     * Rejects missing targets and validates forced file-qualified accessors.
+     *
+     * File path decoding is checked before accessor parsing to keep control
+     * characters out of filesystem resolution and subsequent diagnostics.
+     */
+    function check(target, forcedFile) {
+        if (target === "")
+            throw new Error("Name the target before explaining the acknowledgement.");
+        if (!forcedFile)
+            return;
+        const hash = target.indexOf("#");
+        if (hash < 0) {
+            throw new Error("Write a file path followed by '#' and a public accessor, such as ../calculator.ts#add.");
+        }
+        const file = target.slice(0, hash);
+        if (file === "")
+            throw new Error("Name the file before '#'.");
+        const decoded = decodeURIComponent(file);
+        if (decoded.includes("\0") ||
+            decoded.includes("\r") ||
+            decoded.includes("\n"))
+            throw new Error("Target paths cannot contain NUL or line breaks.");
+        EvidenceAccessor_1.EvidenceAccessor.parse(target.slice(hash + 1));
+    }
+    EvidenceTargetBody.check = check;
+})(EvidenceTargetBody || (exports.EvidenceTargetBody = EvidenceTargetBody = {}));

package/lib/internal/FileGlob.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Matches the restricted Evidence glob language: `*`, `**`, `?`, and ordered negation.
+ *
+ * The matcher operates on portable path segments, keeping selection independent
+ * of host separator conventions and refusing patterns that escape a population root.
+ */
+export declare class FileGlob {
+    private readonly patterns;
+    /** Compiles ordered patterns and requires at least one positive selection baseline.
+     *
+     * A population with only exclusions would have no defined initial set, so configuration validation rejects it at construction.
+     */
+    constructor(patterns: readonly string[]);
+    /** Applies every matching pattern in declaration order.
+     *
+     * Later matching positives or exclusions replace the inclusion decision made by earlier patterns.
+     */
+    matches(location: string): boolean;
+    /** Determines whether a directory can contain a selected descendant.
+     *
+     * Discovery uses this conservative result to prune traversal without excluding descendants restored by a later positive pattern.
+     */
+    couldMatchDescendant(directory: string): boolean;
+}

package/lib/internal/FileGlob.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileGlob = void 0;
+/**
+ * Matches the restricted Evidence glob language: `*`, `**`, `?`, and ordered negation.
+ *
+ * The matcher operates on portable path segments, keeping selection independent
+ * of host separator conventions and refusing patterns that escape a population root.
+ */
+class FileGlob {
+    patterns;
+    /** Compiles ordered patterns and requires at least one positive selection baseline.
+     *
+     * A population with only exclusions would have no defined initial set, so configuration validation rejects it at construction.
+     */
+    constructor(patterns) {
+        this.patterns = patterns.map(compile);
+        if (!this.patterns.some((pattern) => !pattern.exclude))
+            throw new Error("The files array must contain at least one positive glob.");
+    }
+    /** Applies every matching pattern in declaration order.
+     *
+     * Later matching positives or exclusions replace the inclusion decision made by earlier patterns.
+     */
+    matches(location) {
+        const segments = split(location);
+        let included = false;
+        for (const pattern of this.patterns)
+            if (match(pattern.segments, segments, false))
+                included = !pattern.exclude;
+        return included;
+    }
+    /** Determines whether a directory can contain a selected descendant.
+     *
+     * Discovery uses this conservative result to prune traversal without excluding descendants restored by a later positive pattern.
+     */
+    couldMatchDescendant(directory) {
+        const prefix = split(directory);
+        let possible = false;
+        for (const pattern of this.patterns)
+            if (!pattern.exclude) {
+                if (match(pattern.segments, prefix, true))
+                    possible = true;
+            }
+            else if (pattern.segments.at(-1) === "**" &&
+                match(pattern.segments, prefix, false))
+                possible = false;
+        return possible;
+    }
+}
+exports.FileGlob = FileGlob;
+/** Parses one authored glob into normalized segments while rejecting ambiguous root escapes.
+ *
+ * `FileGlob` uses the result for portable matching relative to one selected population root.
+ */
+function compile(raw) {
+    if (raw.trim() === "")
+        throw new Error("Glob strings must not be empty.");
+    const exclude = raw.startsWith("!");
+    let value = (exclude ? raw.slice(1) : raw).replaceAll("\\", "/");
+    while (value.startsWith("./"))
+        value = value.slice(2);
+    if (value === "")
+        throw new Error("The exclusion marker '!' must be followed by a glob.");
+    if (value.startsWith("/") || /^[A-Za-z]:/.test(value))
+        throw new Error(`Glob '${raw}' must be relative to its population root.`);
+    if (value.endsWith("/"))
+        value = value.slice(0, -1);
+    const segments = value.split("/");
+    if (segments.includes("") || segments.includes(".."))
+        throw new Error(`Glob '${raw}' contains an empty segment or escapes its root.`);
+    return { segments, exclude };
+}
+/** Splits a candidate path into portable relative segments without filesystem resolution.
+ *
+ * Matching operates on these normalized segments so Windows and POSIX separators have identical selection semantics.
+ */
+function split(value) {
+    let normalized = value.replaceAll("\\", "/");
+    while (normalized.startsWith("./"))
+        normalized = normalized.slice(2);
+    normalized = normalized.replace(/^\/+|\/+$/g, "");
+    return normalized === "" || normalized === "." ? [] : normalized.split("/");
+}
+/** Matches a pattern with memoized globstar branches bounded by the pattern and path grid.
+ *
+ * Memoization prevents repeated `**` branches from causing exponential discovery work for long paths.
+ */
+function match(pattern, segments, descendant) {
+    const memo = new Map();
+    return visit(0, 0);
+    function visit(patternIndex, pathIndex) {
+        const key = `${patternIndex}:${pathIndex}`;
+        const cached = memo.get(key);
+        if (cached !== undefined)
+            return cached;
+        const token = pattern[patternIndex];
+        const segment = segments[pathIndex];
+        let result;
+        if (descendant && pathIndex === segments.length)
+            result = patternIndex < pattern.length;
+        else if (token === undefined)
+            result = pathIndex === segments.length;
+        else if (token === "**")
+            result =
+                visit(patternIndex + 1, pathIndex) ||
+                    (segment !== undefined && visit(patternIndex, pathIndex + 1));
+        else
+            result =
+                segment !== undefined &&
+                    matchSegment(token, segment) &&
+                    visit(patternIndex + 1, pathIndex + 1);
+        memo.set(key, result);
+        return result;
+    }
+}
+/**
+ * Matches one segment where star and question mark never cross a separator boundary.
+ *
+ * A question mark consumes one Unicode code point, as in the Go matcher.
+ */
+function matchSegment(pattern, value) {
+    const tokens = Array.from(pattern);
+    const characters = Array.from(value);
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starPattern = -1;
+    let starValue = 0;
+    while (valueIndex < characters.length)
+        if (tokens[patternIndex] === "*") {
+            starPattern = patternIndex++;
+            starValue = valueIndex;
+        }
+        else if (tokens[patternIndex] === "?" ||
+            tokens[patternIndex] === characters[valueIndex]) {
+            patternIndex++;
+            valueIndex++;
+        }
+        else if (starPattern >= 0) {
+            patternIndex = starPattern + 1;
+            valueIndex = ++starValue;
+        }
+        else
+            return false;
+    while (tokens[patternIndex] === "*")
+        patternIndex++;
+    return patternIndex === tokens.length;
+}

package/lib/internal/IConfigDependencyScan.d.ts

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

package/lib/internal/IConfigDependencyScan.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/internal/IConfigPackageScope.d.ts

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

package/lib/internal/IConfigPackageScope.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });