@wrtnlabs/evidence 0.0.0

package/lib/structures/index.d.ts

@@ -0,0 +1,105 @@
+export type * from "./IEvidenceAdapter";
+export type * from "./IEvidenceAddress";
+export type * from "./IEvidenceCommentSyntax";
+export type * from "./IEvidenceDeclaration";
+export type * from "./IEvidenceDiagnostic";
+export type * from "./IEvidenceDocumentation";
+export type * from "./IEvidenceHost";
+export type * from "./IEvidenceInventory";
+export type * from "./IEvidencePopulation";
+export type * from "./IEvidencePublicAddress";
+export type * from "./IEvidenceResolution";
+export type * from "./IEvidenceReview";
+export type * from "./IEvidenceSourceLocation";
+export type * from "./IEvidenceTagParseResult";
+export type * from "./IEvidenceTargetResolution";
+export type * from "./IEvidenceTargetStatement";
+export type * from "./IEvidenceUnit";
+export type * from "./IEvidenceUnitSite";
+export type * from "./IEvidenceWithdrawal";
+export type * from "./IEvidenceClaim";
+export type * from "./IEvidenceClaimBase";
+export type * from "./IEvidenceConfig";
+export type * from "./IEvidenceConfigPlan";
+export type * from "./IEvidenceConfigPlanClaim";
+export type * from "./IEvidenceConfigPlanReference";
+export type * from "./IEvidenceDatabaseClaim";
+export type * from "./IEvidenceDatabaseReference";
+export type * from "./IEvidenceDocumentedConfig";
+export type * from "./IEvidenceFingerprint";
+export type * from "./IEvidenceGrammar";
+export type * from "./IEvidenceGrammarAsset";
+export type * from "./IEvidenceGraphClaim";
+export type * from "./IEvidenceGraphBoundary";
+export type * from "./IEvidenceGraphClaimResult";
+export type * from "./IEvidenceGraphEdge";
+export type * from "./IEvidenceGraphExportEdge";
+export type * from "./IEvidenceGraphExportReview";
+export type * from "./IEvidenceGraphHostNode";
+export type * from "./IEvidenceGraphHostCoverage";
+export type * from "./IEvidenceGraphInput";
+export type * from "./IEvidenceGraphNode";
+export type * from "./IEvidenceGraphObligation";
+export type * from "./IEvidenceGraphPolicy";
+export type * from "./IEvidenceGraphReference";
+export type * from "./IEvidenceGraphReviewResolution";
+export type * from "./IEvidenceGraphResolution";
+export type * from "./IEvidenceGraphResult";
+export type * from "./IEvidenceGraphReport";
+export type * from "./IEvidenceLanguage";
+export type * from "./IEvidenceLanguageAdapter";
+export type * from "./IEvidenceLanguageCandidate";
+export type * from "./IEvidenceLanguageGrammar";
+export type * from "./IEvidenceMarkdownClaim";
+export type * from "./IEvidenceMarkdownReference";
+export type * from "./IEvidenceParserInput";
+export type * from "./IEvidenceParserOptions";
+export type * from "./IEvidenceParserState";
+export type * from "./IEvidenceProgrammingClaim";
+export type * from "./IEvidenceProgrammingReference";
+export type * from "./IEvidenceReference";
+export type * from "./IEvidenceReferenceBase";
+export type * from "./IEvidenceSourceAddress";
+export type * from "./IEvidenceSourceDependency";
+export type * from "./IEvidenceSourceDiagnostic";
+export type * from "./IEvidenceSourceFile";
+export type * from "./IEvidenceSourcePosition";
+export type * from "./IEvidenceSourceRange";
+export type * from "./IEvidenceSourceRoot";
+export type * from "./IEvidenceSourceSelection";
+export type * from "./IEvidenceSourceSnapshot";
+export type * from "./IEvidenceSwaggerClaim";
+export type * from "./IEvidenceSwaggerReference";
+export type * from "./IEvidenceCheckAnalysis";
+export type * from "./IEvidenceCheckClaim";
+export type * from "./IEvidenceCheckCommand";
+export type * from "./IEvidenceCheckCounts";
+export type * from "./IEvidenceCheckObligation";
+export type * from "./IEvidenceCheckReport";
+export type * from "./IEvidenceCommand";
+export type * from "./IEvidenceCommandFailure";
+export type * from "./IEvidenceCommandResult";
+export type * from "./IEvidenceHelpCommand";
+export type * from "./IEvidenceGraphCommand";
+export type * from "./IEvidenceInspectCommand";
+export type * from "./IEvidenceInspectReport";
+export type * from "./IEvidenceInspectedAcknowledgement";
+export type * from "./IEvidenceInspectedObligation";
+export type * from "./IEvidenceInspectedReview";
+export type * from "./IEvidenceInspectedUnit";
+export type * from "./IEvidenceInspection";
+export type * from "./IEvidenceInitCommand";
+export type * from "./IEvidenceLanguagesCommand";
+export type * from "./IEvidenceLanguagesReport";
+export type * from "./IEvidenceListCommand";
+export type * from "./IEvidenceListItem";
+export type * from "./IEvidenceListReport";
+export type * from "./IEvidenceQueryScope";
+export type * from "./IEvidenceSupportedLanguage";
+export type * from "./IEvidenceVersionCommand";
+export type * from "./IEvidenceWatchCheckCycle";
+export type * from "./IEvidenceWatchFailureCycle";
+export type * from "./IEvidenceWatchOptions";
+export type { IEvidenceDatabaseLanguage } from "./IEvidenceDatabaseLanguage";
+export type { IEvidenceDatabaseLanguageAdapter } from "./IEvidenceDatabaseLanguageAdapter";
+export type { IEvidenceSupportedDatabaseLanguage } from "./IEvidenceSupportedDatabaseLanguage";

package/lib/structures/index.js

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

package/lib/targets/EvidenceAccessor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Converts the accessor portion of a file-qualified target between text and segments.
+ *
+ * Target resolution uses segments to distinguish lexical ownership from a literal
+ * dot in a member name. This namespace accepts the portable baseline syntax only:
+ * identifiers after dots, JSON strings in brackets, and non-negative integer
+ * bracket members. It neither resolves symbols nor interprets a segment as code.
+ *
+ * @example
+ * EvidenceAccessor.parse('Client.prototype["send.request"]');
+ * // ["Client", "prototype", "send.request"]
+ */
+export declare namespace EvidenceAccessor {
+    /**
+     * Parses one accessor spelling into the literal segments used by an address.
+     *
+     * A bracket string preserves characters that have structural meaning in dotted
+     * syntax. Invalid separators, unterminated brackets, and unsupported bracket
+     * content reject before a resolver can look up a different declaration.
+     */
+    function parse(value: string): string[];
+    /**
+     * Serializes literal accessor segments in the canonical target spelling.
+     *
+     * Identifier segments use dotted notation. Every other segment is JSON-quoted
+     * in brackets so formatting cannot turn a literal dot, bracket, or space into
+     * an accidental parent relationship. Empty paths are invalid because a target
+     * accessor must identify at least one declaration segment.
+     */
+    function format(segments: string[]): string;
+}

package/lib/targets/EvidenceAccessor.js

@@ -0,0 +1,165 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceAccessor = void 0;
+const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
+const typia_1 = __importDefault(require("typia"));
+/**
+ * Converts the accessor portion of a file-qualified target between text and segments.
+ *
+ * Target resolution uses segments to distinguish lexical ownership from a literal
+ * dot in a member name. This namespace accepts the portable baseline syntax only:
+ * identifiers after dots, JSON strings in brackets, and non-negative integer
+ * bracket members. It neither resolves symbols nor interprets a segment as code.
+ *
+ * @example
+ * EvidenceAccessor.parse('Client.prototype["send.request"]');
+ * // ["Client", "prototype", "send.request"]
+ */
+var EvidenceAccessor;
+(function (EvidenceAccessor) {
+    /**
+     * Parses one accessor spelling into the literal segments used by an address.
+     *
+     * A bracket string preserves characters that have structural meaning in dotted
+     * syntax. Invalid separators, unterminated brackets, and unsupported bracket
+     * content reject before a resolver can look up a different declaration.
+     */
+    function parse(value) {
+        const segments = [];
+        let cursor = 0;
+        while (cursor < value.length) {
+            if (value[cursor] === "[") {
+                const start = ++cursor;
+                let quoted = false;
+                let escaped = false;
+                while (cursor < value.length) {
+                    const character = value[cursor];
+                    if (escaped)
+                        escaped = false;
+                    else if (quoted && character === "\\")
+                        escaped = true;
+                    else if (character === '"')
+                        quoted = !quoted;
+                    else if (!quoted && character === "]")
+                        break;
+                    ++cursor;
+                }
+                if (cursor === value.length)
+                    throw new Error("Close the bracket accessor and its quoted member name.");
+                const literal = value.slice(start, cursor++);
+                // JSON parsing handles escapes exactly as the canonical formatter emits
+                // them, while numeric brackets remain literal accessor segments.
+                if (literal.startsWith('"'))
+                    segments.push((() => {
+                        const __is = input => "string" === typeof input;
+                        let _errorFactory;
+                        const __assert = (input, errorFactory) => {
+                            if (false === __is(input)) {
+                                _errorFactory = errorFactory;
+                                ((input, _path, _exceptionable = true) => "string" === typeof input || _assertGuard_1._assertGuard(true, {
+                                    method: "typia.json.assertParse",
+                                    path: _path + "",
+                                    expected: "string",
+                                    value: input
+                                }, _errorFactory))(input, "$input", true);
+                            }
+                            return input;
+                        };
+                        return (input, errorFactory) => __assert(JSON.parse(input), errorFactory);
+                    })()(literal));
+                else if (/^(?:0|[1-9][0-9]*)$/.test(literal))
+                    segments.push(literal);
+                else
+                    throw new Error("A bracket accessor must contain a JSON string or an unsigned integer without leading zeroes.");
+            }
+            else {
+                const start = cursor;
+                while (cursor < value.length &&
+                    value[cursor] !== "." &&
+                    value[cursor] !== "[")
+                    ++cursor;
+                const segment = value.slice(start, cursor);
+                if (!identifier(segment))
+                    throw new Error("Use dotted identifiers or JSON-string brackets for literal member names.");
+                segments.push(segment);
+            }
+            if (cursor === value.length)
+                break;
+            if (value[cursor] === ".") {
+                ++cursor;
+                if (cursor === value.length || value[cursor] === "[")
+                    throw new Error("A dot must be followed by an identifier.");
+            }
+            else if (value[cursor] !== "[")
+                throw new Error("Separate accessor segments with a dot or a bracket.");
+        }
+        if (segments.length === 0)
+            throw new Error("Name a public declaration after '#'.");
+        return segments;
+    }
+    EvidenceAccessor.parse = parse;
+    /**
+     * Serializes literal accessor segments in the canonical target spelling.
+     *
+     * Identifier segments use dotted notation. Every other segment is JSON-quoted
+     * in brackets so formatting cannot turn a literal dot, bracket, or space into
+     * an accidental parent relationship. Empty paths are invalid because a target
+     * accessor must identify at least one declaration segment.
+     */
+    function format(segments) {
+        if (segments.length === 0)
+            throw new Error("An accessor needs at least one segment.");
+        let output = "";
+        for (const segment of segments)
+            output += identifier(segment)
+                ? (output === "" ? "" : ".") + segment
+                : "[" + JSON.stringify(segment) + "]";
+        return output;
+    }
+    EvidenceAccessor.format = format;
+    /**
+     * Determines whether one segment is safe in dotted accessor notation.
+     *
+     * The Unicode-aware expression matches the baseline's identifier subset. A
+     * segment outside that subset remains valid, but `format` must quote it.
+     */
+    function identifier(value) {
+        return /^(?:[$_]|\p{L})(?:[$_]|\p{L}|\p{Nd}|\p{M})*$/u.test(value);
+    }
+})(EvidenceAccessor || (exports.EvidenceAccessor = EvidenceAccessor = {}));

package/lib/targets/EvidenceFileTarget.d.ts

@@ -0,0 +1,41 @@
+import type { IEvidenceAddress } from "../structures/IEvidenceAddress";
+/**
+ * Converts file-qualified Evidence targets between authored text and addresses.
+ *
+ * A target names either a file unit or a public accessor within a file. Parsing
+ * resolves the file portion relative to the documentation host without reading
+ * the filesystem; later resolution decides whether that normalized path belongs
+ * to the selected population. Formatting provides stable diagnostic and review
+ * text without changing literal accessor segments.
+ *
+ * @example
+ * EvidenceFileTarget.parse("../api/client.ts#Client.prototype.send", "/repo/docs/guide.md");
+ */
+export declare namespace EvidenceFileTarget {
+    /**
+     * Parses an authored file target relative to the documentation host's file.
+     *
+     * A missing hash selects the file unit; a hash must be followed by an accessor.
+     * The file component permits percent encoding for reserved path characters,
+     * whereas accessor parsing remains delegated to `EvidenceAccessor`. The origin
+     * must be absolute so the same citation cannot resolve differently by process
+     * working directory.
+     */
+    function parse(target: string, origin: string): IEvidenceAddress;
+    /**
+     * Formats a normalized address as canonical file-target text.
+     *
+     * Reserved path characters are percent-encoded, but directory separators and
+     * Windows drive separators stay readable. The accessor is formatted separately
+     * so literal segment characters cannot change the file/path boundary.
+     */
+    function format(address: IEvidenceAddress): string;
+    /**
+     * Normalizes separators and dot segments without consulting the filesystem.
+     *
+     * This is lexical normalization only: symlinks, case rules, and file existence
+     * remain the scanner's responsibility. The UNC guard preserves a leading pair
+     * of slashes only when the author actually supplied a UNC path.
+     */
+    function normalize(file: string): string;
+}

package/lib/targets/EvidenceFileTarget.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceFileTarget = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const EvidenceAccessor_1 = require("./EvidenceAccessor");
+/**
+ * Converts file-qualified Evidence targets between authored text and addresses.
+ *
+ * A target names either a file unit or a public accessor within a file. Parsing
+ * resolves the file portion relative to the documentation host without reading
+ * the filesystem; later resolution decides whether that normalized path belongs
+ * to the selected population. Formatting provides stable diagnostic and review
+ * text without changing literal accessor segments.
+ *
+ * @example
+ * EvidenceFileTarget.parse("../api/client.ts#Client.prototype.send", "/repo/docs/guide.md");
+ */
+var EvidenceFileTarget;
+(function (EvidenceFileTarget) {
+    /**
+     * Parses an authored file target relative to the documentation host's file.
+     *
+     * A missing hash selects the file unit; a hash must be followed by an accessor.
+     * The file component permits percent encoding for reserved path characters,
+     * whereas accessor parsing remains delegated to `EvidenceAccessor`. The origin
+     * must be absolute so the same citation cannot resolve differently by process
+     * working directory.
+     */
+    function parse(target, origin) {
+        const hash = target.indexOf("#");
+        if (hash === target.length - 1)
+            throw new Error("Name a public accessor after '#', or omit '#' when citing the file unit itself.");
+        const encoded = hash < 0 ? target : target.slice(0, hash);
+        if (encoded === "")
+            throw new Error("Name the file before '#'.");
+        let decoded;
+        try {
+            decoded = decodeURIComponent(encoded);
+        }
+        catch {
+            throw new Error("Use valid percent escapes in the file path; write %20 for a space and %23 for a literal '#'.");
+        }
+        if (decoded.includes("\0") ||
+            decoded.includes("\r") ||
+            decoded.includes("\n"))
+            throw new Error("Target paths cannot contain NUL or line breaks.");
+        return {
+            file: resolve(origin, decoded),
+            segments: hash < 0 ? [] : EvidenceAccessor_1.EvidenceAccessor.parse(target.slice(hash + 1)),
+        };
+    }
+    EvidenceFileTarget.parse = parse;
+    /**
+     * Formats a normalized address as canonical file-target text.
+     *
+     * Reserved path characters are percent-encoded, but directory separators and
+     * Windows drive separators stay readable. The accessor is formatted separately
+     * so literal segment characters cannot change the file/path boundary.
+     */
+    function format(address) {
+        const encoded = encodeURIComponent(normalize(address.file))
+            .replaceAll("%2F", "/")
+            .replace(/^([A-Za-z])%3A\//u, "$1:/");
+        return address.segments.length === 0
+            ? encoded
+            : encoded + "#" + EvidenceAccessor_1.EvidenceAccessor.format(address.segments);
+    }
+    EvidenceFileTarget.format = format;
+    /**
+     * Normalizes separators and dot segments without consulting the filesystem.
+     *
+     * This is lexical normalization only: symlinks, case rules, and file existence
+     * remain the scanner's responsibility. The UNC guard preserves a leading pair
+     * of slashes only when the author actually supplied a UNC path.
+     */
+    function normalize(file) {
+        const slash = file.replaceAll("\\", "/");
+        const flavor = windows(slash) ? node_path_1.default.win32 : node_path_1.default.posix;
+        const normalized = flavor.normalize(slash).replaceAll("\\", "/");
+        return normalized.startsWith("//") && !slash.startsWith("//")
+            ? normalized.slice(1)
+            : normalized;
+    }
+    EvidenceFileTarget.normalize = normalize;
+    /**
+     * Resolves a decoded file request using the host file's path flavor.
+     *
+     * Drive-relative requests are rejected because Windows interprets them against
+     * a process-local drive directory. Selecting POSIX or Windows semantics from
+     * either input keeps cross-platform inventories deterministic.
+     */
+    function resolve(origin, file) {
+        const base = normalize(origin);
+        if (!absolute(base))
+            throw new Error("The citing file origin must be an absolute path.");
+        const request = file.replaceAll("\\", "/");
+        if (/^[A-Za-z]:(?!\/)/u.test(request))
+            throw new Error("A target file path cannot be drive-relative.");
+        const flavor = windows(base) || windows(request) ? node_path_1.default.win32 : node_path_1.default.posix;
+        return flavor.resolve(flavor.dirname(base), request).replaceAll("\\", "/");
+    }
+    /**
+     * Checks the portable absolute-path forms accepted for documentation origins.
+     *
+     * Origins are scanner-owned absolute locations; accepting a relative origin
+     * would make a source annotation depend on the process working directory.
+     */
+    function absolute(file) {
+        return file.startsWith("/") || /^[A-Za-z]:\//u.test(file);
+    }
+    /**
+     * Detects Windows drive and UNC spellings after separators are normalized.
+     *
+     * This selects `path.win32` even when an inventory is inspected on a POSIX host.
+     */
+    function windows(file) {
+        return /^[A-Za-z]:\//u.test(file) || file.startsWith("//");
+    }
+})(EvidenceFileTarget || (exports.EvidenceFileTarget = EvidenceFileTarget = {}));

package/lib/targets/EvidenceTargetResolver.d.ts

@@ -0,0 +1,174 @@
+import type { IEvidenceHost } from "../structures/IEvidenceHost";
+import type { IEvidenceInventory } from "../structures/IEvidenceInventory";
+import type { IEvidenceTargetResolution } from "../structures/IEvidenceTargetResolution";
+import type { IEvidenceTargetStatement } from "../structures/IEvidenceTargetStatement";
+import type { EvidenceArtifactType } from "../typings/EvidenceArtifactType";
+/**
+ * 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,
+ * );
+ */
+export declare 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.
+     */
+    private readonly 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.
+     */
+    private readonly 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.
+     */
+    private readonly 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.
+     */
+    private readonly selectedFiles;
+    /**
+     * 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.
+     */
+    private readonly physicalFiles;
+    /**
+     * 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.
+     */
+    private readonly publicFiles;
+    /**
+     * 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.
+     */
+    private readonly markdownFiles;
+    /**
+     * 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: IEvidenceInventory[], type?: EvidenceArtifactType);
+    /**
+     * 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.
+     */
+    resolve(statement: IEvidenceTargetStatement, host: IEvidenceHost, ids: string[]): Promise<IEvidenceTargetResolution>;
+    /**
+     * 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.
+     */
+    private resolveCandidates;
+    /**
+     * 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.
+     */
+    private failure;
+    /**
+     * 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.
+     */
+    private incomplete;
+    /**
+     * 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.
+     */
+    private diagnostic;
+    private exists;
+    /**
+     * 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.
+     */
+    private referenceType;
+    /**
+     * 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.
+     */
+    private errorCode;
+    /**
+     * Collapses alias candidates to their semantic unit identity.
+     *
+     * Address multiplicity does not make a target ambiguous when every spelling
+     * designates the same unit.
+     */
+    private uniqueUnits;
+    /**
+     * 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.
+     */
+    private uniqueWithdrawals;
+    /**
+     * Formats candidate files in stable lexical order for a diagnostic.
+     *
+     * Sorting prevents host-origin iteration order from changing a report's text.
+     */
+    private files;
+    /**
+     * 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.
+     */
+    private accessor;
+}