@wrtnlabs/evidence 0.0.0

package/lib/targets/EvidenceTargetResolver.js

@@ -0,0 +1,403 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceTargetResolver = void 0;
+const promises_1 = require("node:fs/promises");
+const EvidenceAccessor_1 = require("./EvidenceAccessor");
+const EvidenceFileTarget_1 = require("./EvidenceFileTarget");
+const EvidenceInventory_1 = require("../graph/EvidenceInventory");
+const InventoryMerge_1 = require("../internal/InventoryMerge");
+const MarkdownTarget_1 = require("../adapters/markdown/MarkdownTarget");
+const PrismaTarget_1 = require("../adapters/prisma/PrismaTarget");
+const SwaggerTarget_1 = require("../adapters/swagger/SwaggerTarget");
+/**
+ * Resolves citation targets against one merged, selected reference population.
+ *
+ * A resolver combines scans for a reference, recognizes the target grammar used
+ * by its artifact type, then separates four outcomes: a malformed target, an
+ * inaccessible or missing file, a file outside the population, and an address
+ * that has no selected public declaration. Graph evaluation consumes the result
+ * rather than probing files or reinterpreting citation spelling itself.
+ *
+ * Resolution preserves all plausible origins and public file spellings until it
+ * can prove one semantic identity. That avoids making aliases, hard links, or
+ * multi-origin documentation silently select an arbitrary declaration.
+ *
+ * @example
+ * const resolver: EvidenceTargetResolver = new EvidenceTargetResolver([inventory]);
+ * const result: IEvidenceTargetResolution = await resolver.resolve(
+ *   statement,
+ *   host,
+ *   selectedIds,
+ * );
+ */
+class EvidenceTargetResolver {
+    /**
+     * Merged address index used for symbol and withdrawal lookup.
+     *
+     * It retains the inventory merger's alias and ambiguity semantics, which the
+     * resolver must not reproduce from a single physical-file spelling.
+     */
+    index;
+    /**
+     * Immutable snapshot from which membership and completeness are evaluated.
+     *
+     * All derived file maps come from this same snapshot, preventing a target
+     * decision from mixing metadata acquired at different inventory states.
+     */
+    inventory;
+    /**
+     * Configured artifact fallback when selected IDs reveal no unique type.
+     *
+     * A mixed selected population intentionally has no specialized grammar, so it
+     * falls back to ordinary file-qualified target parsing instead of guessing.
+     */
+    type;
+    /**
+     * Normalized public addresses admitted by the reference's selected sources.
+     *
+     * Ordinary targets may resolve only in this set; physical file existence alone
+     * never makes an unselected source part of the coverage denominator.
+     */
+    selectedFiles = new Set();
+    /**
+     * Normalized physical source files known to the merged inventory.
+     *
+     * This distinguishes an existing scanned-but-unselected file from a path that
+     * has disappeared or was never part of the evidence input.
+     */
+    physicalFiles = new Set();
+    /**
+     * Authored public file spellings grouped by their normalized file identity.
+     *
+     * A target must be tested through every public spelling because address lookup
+     * preserves authored paths as part of the public identity contract.
+     */
+    publicFiles = new Map();
+    /**
+     * Selected Markdown roots grouped by Markdown's root-relative path spelling.
+     *
+     * Markdown targets are intentionally resolved from reference roots rather than
+     * relative to the documentation host, so one logical target may map to several
+     * physical selected files before ambiguity is decided.
+     */
+    markdownFiles = new Map();
+    /**
+     * Builds lookup state for one reference's inventory snapshots.
+     *
+     * The optional type supplies a grammar only when selected unit IDs do not
+     * establish one. Construction records membership and aliases but performs no
+     * filesystem access; `resolve` defers that work until a citation needs it.
+     */
+    constructor(inventories, type) {
+        this.index = new EvidenceInventory_1.EvidenceInventory(inventories);
+        this.inventory = this.index.snapshot();
+        this.type = type;
+        for (const source of this.inventory.sources) {
+            this.physicalFiles.add(EvidenceFileTarget_1.EvidenceFileTarget.normalize(source.physicalPath));
+            for (const address of source.addresses)
+                if (address.selected !== false)
+                    this.selectedFiles.add(EvidenceFileTarget_1.EvidenceFileTarget.normalize(address.absolute));
+        }
+        // Preserve every public spelling for an address because the index resolves
+        // public addresses, while membership checks operate on normalized paths.
+        for (const address of this.inventory.addresses) {
+            const file = EvidenceFileTarget_1.EvidenceFileTarget.normalize(address.file);
+            let spellings = this.publicFiles.get(file);
+            if (spellings === undefined) {
+                spellings = new Set();
+                this.publicFiles.set(file, spellings);
+            }
+            spellings.add(address.file);
+        }
+        // Markdown references are rooted at selected source addresses. Identify their
+        // physical sources first so non-Markdown files cannot enter this path map.
+        const markdownSources = new Set(this.inventory.units
+            .filter((unit) => unit.type === "markdown")
+            .flatMap((unit) => unit.sites.map((site) => EvidenceFileTarget_1.EvidenceFileTarget.normalize(site.file))));
+        for (const source of this.inventory.sources) {
+            if (!markdownSources.has(EvidenceFileTarget_1.EvidenceFileTarget.normalize(source.physicalPath)))
+                continue;
+            for (const address of source.addresses) {
+                if (address.selected === false)
+                    continue;
+                const relative = MarkdownTarget_1.MarkdownTarget.normalize(address.relative);
+                let files = this.markdownFiles.get(relative);
+                if (files === undefined) {
+                    files = new Set();
+                    this.markdownFiles.set(relative, files);
+                }
+                files.add(address.absolute);
+            }
+        }
+    }
+    /**
+     * Resolves one statement using its owning host and selected unit IDs.
+     *
+     * The host must match the statement because diagnostics and relative origins
+     * belong to that attachment. Specialized Markdown, Prisma, and Swagger target
+     * forms are parsed only for a uniquely identified artifact type. Ordinary file
+     * targets are attempted for each declared host origin, then deduplicated before
+     * index lookup and filesystem classification.
+     *
+     * Incomplete inventories win before an empty or missing-member result. A scan
+     * that omitted declarations cannot prove coverage merely because the remaining
+     * selected population has no match.
+     */
+    async resolve(statement, host, ids) {
+        if (statement.hostId !== host.id)
+            throw new Error("The target statement does not belong to the supplied host.");
+        if (host.attachment !== "attached")
+            return this.failure("unsupported-host", [], [], [], this.diagnostic(statement, "target-unsupported-host", "The file-qualified target belongs to an unsupported documentation host.", host.problem ??
+                "Attach the annotation to documentation owned by a supported declaration."));
+        const type = this.referenceType(ids);
+        const addresses = [];
+        try {
+            if (type === "markdown") {
+                const target = MarkdownTarget_1.MarkdownTarget.parse(statement.target);
+                for (const file of this.markdownFiles.get(target.file) ?? [])
+                    addresses.push({ file, segments: target.segments });
+                if (addresses.length === 0) {
+                    if (!this.inventory.complete)
+                        return this.incomplete(statement, []);
+                    return this.failure("missing-file", [], [], [], this.diagnostic(statement, "target-missing-file", `Markdown target file '${target.file}' is not among the selected reference files.`, "Correct the root-relative Markdown path or include that file in the reference."));
+                }
+            }
+            else if (type === "prisma") {
+                addresses.push(PrismaTarget_1.PrismaTarget.parse(statement.target));
+            }
+            else if (type === "swagger") {
+                addresses.push(SwaggerTarget_1.SwaggerTarget.parse(statement.target));
+            }
+            else {
+                // A host can represent merged documentation origins. Retain every unique
+                // lexical origin until candidate resolution exposes a genuine ambiguity.
+                const origins = InventoryMerge_1.InventoryMerge.unique(host.origins ?? [host.file], (origin) => EvidenceFileTarget_1.EvidenceFileTarget.normalize(origin));
+                for (const origin of origins)
+                    addresses.push(EvidenceFileTarget_1.EvidenceFileTarget.parse(statement.target, origin));
+            }
+        }
+        catch (cause) {
+            return this.failure("malformed", [], [], [], this.diagnostic(statement, "target-malformed", `The file-qualified target '${statement.target}' is malformed.`, cause instanceof Error
+                ? cause.message
+                : "Use a valid file-qualified public accessor."));
+        }
+        const uniqueAddresses = InventoryMerge_1.InventoryMerge.unique(addresses, (address) => JSON.stringify([address.file, address.segments]));
+        // Completeness precedes any negative conclusion: a failed scan may have
+        // omitted the declaration that would otherwise satisfy this target.
+        if (!this.inventory.complete)
+            return this.incomplete(statement, uniqueAddresses);
+        if (type === "prisma" || type === "swagger") {
+            const candidates = uniqueAddresses.map((address) => ({
+                address,
+                resolution: this.index.resolve(address, ids),
+            }));
+            return this.resolveCandidates(statement, uniqueAddresses, candidates);
+        }
+        const candidates = [];
+        for (const address of uniqueAddresses) {
+            const file = EvidenceFileTarget_1.EvidenceFileTarget.normalize(address.file);
+            if (!this.selectedFiles.has(file))
+                continue;
+            const spellings = this.publicFiles.get(file) ?? new Set([address.file]);
+            for (const spelling of spellings)
+                candidates.push({
+                    address: { file: spelling, segments: address.segments },
+                    resolution: this.index.resolve({ file: spelling, segments: address.segments }, ids),
+                });
+        }
+        if (candidates.length !== 0)
+            return this.resolveCandidates(statement, uniqueAddresses, candidates);
+        // No selected address matched. Inspect the explicit candidate paths only to
+        // distinguish a missing file from a known but out-of-population source.
+        const existing = await Promise.all(uniqueAddresses.map((address) => this.exists(address.file)));
+        if (existing.includes("incomplete"))
+            return this.failure("incomplete", uniqueAddresses, [], [], this.diagnostic(statement, "target-file-access", "The target file could not be inspected while resolving the citation.", "Restore access to the target path and retry the Evidence check."));
+        const known = uniqueAddresses.some((address, index) => {
+            const file = EvidenceFileTarget_1.EvidenceFileTarget.normalize(address.file);
+            return this.physicalFiles.has(file) || existing[index] === "file";
+        });
+        return this.failure(known ? "out-of-population" : "missing-file", uniqueAddresses, [], [], this.diagnostic(statement, known ? "target-out-of-population" : "target-missing-file", known
+            ? `Target file '${this.files(uniqueAddresses)}' is outside the selected reference files.`
+            : `Target file '${this.files(uniqueAddresses)}' is not an existing regular file.`, known
+            ? "Add the file to this reference's files or cite a selected public address."
+            : "Correct the path relative to the citing file or restore the missing file."));
+    }
+    /**
+     * Converts address-index lookups into one semantic target resolution.
+     *
+     * Multiple candidates may be aliases of one unit, which resolves successfully.
+     * Multiple unit IDs or an index-level ambiguity remain ambiguous. A withdrawal
+     * shadows an otherwise found unit, because a citation cannot acknowledge a
+     * declaration that has been explicitly removed from public coverage.
+     */
+    resolveCandidates(statement, addresses, candidates) {
+        const units = this.uniqueUnits(candidates.flatMap((candidate) => candidate.resolution.units));
+        const withdrawals = this.uniqueWithdrawals(candidates.flatMap((candidate) => candidate.resolution.withdrawals));
+        if (units.length > 1 ||
+            candidates.some((candidate) => candidate.resolution.status === "ambiguous"))
+            return this.failure("ambiguous", addresses, units, withdrawals, this.diagnostic(statement, "target-ambiguous", `The file-qualified target '${statement.target}' names more than one semantic identity.`, "Select one symbol kind or cite an unambiguous public accessor."));
+        if (units.length === 1) {
+            const hidden = candidates.some((candidate) => candidate.resolution.status === "hidden");
+            if (hidden)
+                return this.failure("hidden", addresses, units, withdrawals, this.diagnostic(statement, "target-hidden", `The file-qualified target '${statement.target}' names a withdrawn declaration.`, "Cite a public selected declaration or remove the stale acknowledgement."));
+            return {
+                status: "resolved",
+                addresses,
+                units,
+                withdrawals: [],
+                diagnostics: [],
+            };
+        }
+        // Specialized pseudo-files choose a format-specific repair message only after
+        // ordinary candidate resolution found no selected semantic identity.
+        const prisma = addresses.every((address) => address.file === "prisma:");
+        const swagger = addresses.every((address) => address.file === "swagger:");
+        return this.failure("missing-member", addresses, [], [], this.diagnostic(statement, "target-missing-member", prisma
+            ? `The selected Prisma schema has no public selected address '${statement.target}'.`
+            : swagger
+                ? `The selected Swagger document has no operation '${statement.target}'.`
+                : `Selected target file '${this.files(addresses)}' has no public selected address '${this.accessor(addresses)}'.`, prisma
+            ? "Correct the model or member name, or include its symbol kind in this reference."
+            : swagger
+                ? "Correct the uppercase method or exact path, or select the intended Swagger document."
+                : "Correct the accessor, export a supported public declaration, or include its symbol kind in this reference."));
+    }
+    /**
+     * Creates a failed resolution with its one explanatory diagnostic.
+     *
+     * Callers receive candidate addresses, units, and withdrawals even for failure
+     * states so reports can explain the evidence considered without reconstructing
+     * this resolver's normalization and alias work.
+     */
+    failure(status, addresses, units, withdrawals, diagnostic) {
+        return {
+            status,
+            addresses,
+            units,
+            withdrawals,
+            diagnostics: [diagnostic],
+        };
+    }
+    /**
+     * Creates the conservative result required when inventory acquisition failed.
+     *
+     * Existing inventory diagnostics are retained with the target-specific error so
+     * authors see both the acquisition cause and why this citation was not trusted.
+     */
+    incomplete(statement, addresses) {
+        return {
+            status: "incomplete",
+            addresses,
+            units: [],
+            withdrawals: [],
+            diagnostics: [
+                ...this.inventory.diagnostics,
+                this.diagnostic(statement, "target-incomplete", "The target cannot be trusted because its reference inventory is incomplete.", "Resolve the reference inventory diagnostics before evaluating this citation."),
+            ],
+        };
+    }
+    /**
+     * Attaches target-resolution details to the statement's original source span.
+     *
+     * Keeping this construction centralized ensures every failure points to the
+     * authored target and owning host, rather than an internal normalized address.
+     */
+    diagnostic(statement, code, message, repair) {
+        return {
+            code,
+            severity: "error",
+            message,
+            repair,
+            location: statement.location,
+            hostId: statement.hostId,
+            target: statement.target,
+        };
+    }
+    /**
+     * Classifies one candidate path without treating access failure as absence.
+     *
+     * Only regular files can be citation targets. Permission and I/O errors become
+     * `incomplete` so a transient inspection failure cannot be reported as a user
+     * typo or shrink the reference population.
+     */
+    async exists(file) {
+        try {
+            return (await (0, promises_1.stat)(file)).isFile() ? "file" : "other";
+        }
+        catch (cause) {
+            const code = this.errorCode(cause);
+            return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "incomplete";
+        }
+    }
+    /**
+     * Finds the specialized target grammar implied by selected semantic units.
+     *
+     * An empty selection uses the configured fallback. A homogeneous selection
+     * supplies its own type; a mixed selection deliberately returns undefined so
+     * no one artifact grammar is applied to an unrelated citation.
+     */
+    referenceType(ids) {
+        const selected = new Set(ids);
+        const types = new Set();
+        for (const unit of this.inventory.units) {
+            if (!selected.has(unit.id))
+                continue;
+            types.add(unit.type);
+        }
+        if (types.size === 0)
+            return this.type;
+        return types.size === 1 ? types.values().next().value : undefined;
+    }
+    /**
+     * Extracts a Node-style error code without assuming an arbitrary thrown value.
+     *
+     * Filesystem APIs may reject with non-Error values, which must remain an
+     * incomplete inspection rather than cause the resolver's classifier to throw.
+     */
+    errorCode(cause) {
+        if (!(cause instanceof Error) || !("code" in cause))
+            return undefined;
+        const code = cause.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    /**
+     * Collapses alias candidates to their semantic unit identity.
+     *
+     * Address multiplicity does not make a target ambiguous when every spelling
+     * designates the same unit.
+     */
+    uniqueUnits(units) {
+        return InventoryMerge_1.InventoryMerge.unique(units, (unit) => unit.id);
+    }
+    /**
+     * Removes repeated withdrawal records gathered through alias candidates.
+     *
+     * Withdrawals lack one shared unit ID in this result shape, so structural
+     * serialization preserves the merger's full withdrawal identity.
+     */
+    uniqueWithdrawals(withdrawals) {
+        return InventoryMerge_1.InventoryMerge.unique(withdrawals, (withdrawal) => JSON.stringify(withdrawal));
+    }
+    /**
+     * Formats candidate files in stable lexical order for a diagnostic.
+     *
+     * Sorting prevents host-origin iteration order from changing a report's text.
+     */
+    files(addresses) {
+        return addresses
+            .map((address) => address.file)
+            .sort(InventoryMerge_1.InventoryMerge.compare)
+            .join("', '");
+    }
+    /**
+     * Formats the representative accessor after candidate paths share its segments.
+     *
+     * An empty array occurs only in defensive failure construction and deliberately
+     * produces an empty display rather than inventing an accessor.
+     */
+    accessor(addresses) {
+        const first = addresses[0];
+        return first === undefined ? "" : EvidenceAccessor_1.EvidenceAccessor.format(first.segments);
+    }
+}
+exports.EvidenceTargetResolver = EvidenceTargetResolver;

package/lib/typings/EvidenceAcknowledgementKind.d.ts

@@ -0,0 +1,7 @@
+/** Distinguishes an ordinary citation from an acknowledged exclusion.
+ *
+ * Both forms attach authored context to a graph obligation, but only `evidence`
+ * supplies coverage. `evidenceExclude` records an intentional exception and
+ * therefore follows the exclusion and review rules instead of crediting a unit.
+ */
+export type EvidenceAcknowledgementKind = "evidence" | "evidenceExclude";

package/lib/typings/EvidenceAcknowledgementKind.js

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

package/lib/typings/EvidenceActiveSeverity.d.ts

@@ -0,0 +1,7 @@
+/** Diagnostic severities that leave an obligation enabled in a resolved plan.
+ *
+ * Configuration planning drops `off` entries before graph evaluation. The two
+ * remaining values differ in report severity, but both retain their population
+ * in the denominator and can make a check fail according to policy.
+ */
+export type EvidenceActiveSeverity = "warning" | "error";

package/lib/typings/EvidenceActiveSeverity.js

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

package/lib/typings/EvidenceArtifactType.d.ts

@@ -0,0 +1,10 @@
+import type { EvidenceDatabaseType } from "./EvidenceDatabaseType";
+import type { EvidenceProgrammingType } from "./EvidenceProgrammingType";
+/** Artifact families that can provide graph units and annotation carriers.
+ *
+ * An adapter uses this discriminator to keep language-specific extraction and
+ * target spelling separate while the graph can process their common inventory.
+ * `markdown` and `swagger` are document artifacts; the other members identify
+ * programming or database dialect groups.
+ */
+export type EvidenceArtifactType = EvidenceProgrammingType | EvidenceDatabaseType | "markdown" | "swagger";

package/lib/typings/EvidenceArtifactType.js

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

package/lib/typings/EvidenceCheckStatus.d.ts

@@ -0,0 +1,8 @@
+/** Whether a check had complete enough input to make a coverage decision.
+ *
+ * `incomplete` protects callers from treating an interrupted scan, failed
+ * dependency, or unavailable parser result as a successful empty population.
+ * `complete` says evaluation reached a final result; it does not itself mean
+ * that every obligation passed.
+ */
+export type EvidenceCheckStatus = "complete" | "incomplete";

package/lib/typings/EvidenceCheckStatus.js

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

package/lib/typings/EvidenceCommandExitCode.d.ts

@@ -0,0 +1,8 @@
+/** Process exit codes reserved by the Evidence command-line interface.
+ *
+ * Command callers can distinguish a passing check, a completed check with
+ * reported violations, and an operational failure without parsing formatted
+ * output. The numeric values are part of the shell-facing compatibility
+ * contract.
+ */
+export type EvidenceCommandExitCode = 0 | 1 | 2;

package/lib/typings/EvidenceCommandExitCode.js

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

package/lib/typings/EvidenceDatabaseSymbol.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Database declaration kinds shared by Prisma, SQL, and DBML.
+ *
+ * - "model": a named record structure, such as a Prisma model, table, or view.
+ * - "column": a data field belonging to a model.
+ *   - Includes scalar fields and foreign-key values such as `authorId`.
+ *   - Excludes the relation declaration that describes the connection.
+ * - "relation": a declaration connecting models, including self-references.
+ *   - Includes Prisma relation fields, SQL foreign-key constraints, and DBML refs.
+ *   - Includes both Prisma relation fields, even when one omits `@relation`.
+ *   - Means a relationship, not the SQL use of "relation" for a table.
+ *
+ * Models contain their columns and relations. A model target covers its selected
+ * descendants even when the model itself is not selected. Each adapter retains
+ * its own declaration units; Prisma's two relation fields need not correspond to
+ * two SQL foreign-key constraints.
+ *
+ * Prisma targets use `prisma:Model` and `prisma:Model.field`, without a file path.
+ * Model names are unique across the schema; moving declarations between its
+ * files preserves their targets.
+ * Models and views share the "model" kind. Enums, composite types, indexes, and
+ * datasource/generator settings are outside the Prisma selection contract.
+ */
+export type EvidenceDatabaseSymbol = "model" | "column" | "relation";

package/lib/typings/EvidenceDatabaseSymbol.js

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

package/lib/typings/EvidenceDatabaseType.d.ts

@@ -0,0 +1,7 @@
+/** Database schema languages and SQL dialects supported by database adapters.
+ *
+ * This value selects a parser and adapter contract rather than inferring a
+ * dialect from a file extension. `sql` represents the generic SQL grammar;
+ * dialect-specific values retain syntax and target rules that differ from it.
+ */
+export type EvidenceDatabaseType = "prisma" | "sql" | "postgresql" | "mysql" | "sqlite" | "bigquery" | "dbml";

package/lib/typings/EvidenceDatabaseType.js

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

package/lib/typings/EvidenceGrammarWasmAvailability.d.ts

@@ -0,0 +1,7 @@
+/** How a researched grammar can provide WASM compatible with the packaged runtime.
+ *
+ * A release asset can be downloaded and pinned directly. A source build needs a
+ * reproducible compilation route before the candidate can become a certified
+ * adapter, so callers must not treat the two states as interchangeable.
+ */
+export type EvidenceGrammarWasmAvailability = "release-asset" | "source-build";

package/lib/typings/EvidenceGrammarWasmAvailability.js

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

package/lib/typings/EvidenceGraphFormat.d.ts

@@ -0,0 +1,7 @@
+/** Serialization formats accepted by the graph-report command.
+ *
+ * `json` preserves the report as structured data. `mermaid` and `dot` are
+ * visualization languages for rendering the same graph relationships and must
+ * not be used as a lossless replacement for the machine-readable report.
+ */
+export type EvidenceGraphFormat = "json" | "mermaid" | "dot";

package/lib/typings/EvidenceGraphFormat.js

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

package/lib/typings/EvidenceGraphNode.d.ts

@@ -0,0 +1,10 @@
+import type { IEvidenceGraphHostNode } from "../structures/IEvidenceGraphHostNode";
+import type { IEvidenceGraphNode } from "../structures/IEvidenceGraphNode";
+/** A serialized graph node representing a unit or its annotation carrier.
+ *
+ * Unit nodes participate in coverage and dependency edges. Host nodes preserve
+ * the physical source location where evidence, exclusions, or reviews were
+ * written, allowing graph exports to show annotations without changing the
+ * unit's semantic identity.
+ */
+export type EvidenceGraphNode = IEvidenceGraphHostNode | IEvidenceGraphNode;

package/lib/typings/EvidenceGraphNode.js

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

package/lib/typings/EvidenceLanguageCandidateId.d.ts

@@ -0,0 +1,7 @@
+/** Identifier for a language or embedded format still being researched.
+ *
+ * Candidate IDs are deliberately outside `EvidenceProgrammingType`: recording
+ * parser availability, grammar provenance, or extraction gaps must not imply
+ * that configurations can already select the language as a supported artifact.
+ */
+export type EvidenceLanguageCandidateId = "kotlin" | "swift" | "php" | "dart" | "scala" | "lua" | "objc" | "zig" | "matlab" | "vue" | "svelte";

package/lib/typings/EvidenceLanguageCandidateId.js

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

package/lib/typings/EvidenceLanguageCandidateKind.d.ts

@@ -0,0 +1,7 @@
+/** Broad research category for a non-certified language candidate.
+ *
+ * `embedded-format` marks syntax normally nested inside another source artifact;
+ * `programming-language` marks a potential top-level adapter. This classification
+ * guides certification work and does not change an active configuration.
+ */
+export type EvidenceLanguageCandidateKind = "programming-language" | "embedded-format";

package/lib/typings/EvidenceLanguageCandidateKind.js

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

package/lib/typings/EvidenceMarkdownSymbol.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Markdown document and section kinds.
+ *
+ * - "file": the document root.
+ * - "h1" through "h4": ATX sections at exactly that level. Setext and H5/H6
+ *   headings are excluded.
+ * - A section contains lower-level sections up to the next equal/higher heading.
+ *   Ordinary evidence and permitted exclusions cover selected descendants;
+ *   unselected ancestors remain addressable as aggregate targets.
+ *
+ * Target rules:
+ *
+ * - File paths are relative to the reference root. Both path separators are
+ *   accepted, but paths cannot contain whitespace.
+ * - Sections append "#<anchor>" to the file path.
+ *   - An explicit "{#anchor}" wins. It starts with an ASCII letter/digit, followed
+ *     by ASCII letters/digits, ".", "_", ":", or "-".
+ *   - Otherwise, lowercase the heading; retain letters, numbers, and "_"; collapse
+ *     whitespace/hyphens to "-"; remove other punctuation.
+ * - Duplicate selected heading targets are ambiguous and need explicit anchors.
+ */
+export type EvidenceMarkdownSymbol = "file" | "h1" | "h2" | "h3" | "h4";

package/lib/typings/EvidenceMarkdownSymbol.js

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

package/lib/typings/EvidenceParserErrorCode.d.ts

@@ -0,0 +1,8 @@
+/** Stable categories for failures that invalidate adapter extraction.
+ *
+ * Parser failures never quietly become an empty inventory: callers retain the
+ * category in diagnostics so an unavailable asset, malformed query, incomplete
+ * parse, or closed session cannot reduce the coverage denominator. The codes
+ * separate remediation of cache/runtime problems from source and query issues.
+ */
+export type EvidenceParserErrorCode = "unsupported-language" | "unsupported-extension" | "asset-manifest" | "asset-missing" | "asset-corrupt" | "asset-download" | "asset-cache" | "asset-cancelled" | "runtime-initialization" | "grammar-incompatible" | "parse-failed" | "parse-incomplete" | "query-invalid" | "query-incomplete" | "session-closed";

package/lib/typings/EvidenceParserErrorCode.js

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

package/lib/typings/EvidencePopulationRole.d.ts

@@ -0,0 +1,7 @@
+/** The side of an Evidence obligation to which a configured population belongs.
+ *
+ * A claim population provides units requiring coverage. A reference population
+ * provides targets that can satisfy those units. The same source may appear on
+ * both sides, but planning keeps their roles separate for validation and scope.
+ */
+export type EvidencePopulationRole = "claim" | "reference";

package/lib/typings/EvidencePopulationRole.js

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