@wrtnlabs/evidence 0.0.0

package/lib/programmers/EvidenceQueryProgrammer.js

@@ -0,0 +1,970 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceQueryProgrammer = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const EvidenceFileTarget_1 = require("../targets/EvidenceFileTarget");
+const EvidenceFingerprint_1 = require("../graph/EvidenceFingerprint");
+const EvidenceLanguageRegistry_1 = require("../parsers/EvidenceLanguageRegistry");
+const EvidenceTargetResolver_1 = require("../targets/EvidenceTargetResolver");
+const InventoryMerge_1 = require("../internal/InventoryMerge");
+const EvidenceQueryPopulationContext_1 = require("../contexts/EvidenceQueryPopulationContext");
+const MarkdownTarget_1 = require("../adapters/markdown/MarkdownTarget");
+/**
+ * Projects one completed checker analysis into query-command reports.
+ *
+ * Query operations never re-evaluate graph policy or mutate inventories. They
+ * retain the claim/reference coordinates established during checking, so a list,
+ * target inspection, and exported graph all describe the same independent
+ * obligation boundaries and diagnostic set.
+ *
+ * @example
+ *   const report = EvidenceQueryProgrammer.list(queryContext, "typescript");
+ *   const inspection = await EvidenceQueryProgrammer.inspect(
+ *     queryContext,
+ *     "src/user.ts#UserService",
+ *   );
+ */
+var EvidenceQueryProgrammer;
+(function (EvidenceQueryProgrammer) {
+    /**
+     * Lists configured identities and the structural ancestors needed to address them.
+     *
+     * Language and symbol filters apply after each population is projected, so they
+     * do not change configured selection or graph coverage. Rows are sorted by
+     * stable query identity, and checker diagnostics are passed through unchanged
+     * because a list command is an observation of the existing analysis.
+     */
+    function list(context, language, kind) {
+        const { analysis } = context;
+        const root = context.cwd;
+        const items = context.populations
+            .flatMap((population) => listPopulation(population, root))
+            .filter((item) => (language === undefined || item.scope.type === language) &&
+            (kind === undefined || item.symbol === kind))
+            .sort((left, right) => compare(left.id, right.id));
+        return {
+            schemaVersion: 1,
+            command: "list",
+            configFile: analysis.report.configFile,
+            status: analysis.report.status,
+            success: analysis.report.success,
+            exitCode: analysis.report.exitCode,
+            ...(language === undefined ? {} : { language }),
+            ...(kind === undefined ? {} : { kind }),
+            total: items.length,
+            items,
+            diagnostics: analysis.report.diagnostics,
+        };
+    }
+    EvidenceQueryProgrammer.list = list;
+    /**
+     * Inspects one CLI-relative target across the populations that can interpret it.
+     *
+     * Exact indexed spellings take precedence over grammar inference, preventing a
+     * target alias from being hidden by a broad file-extension match. Resolution is
+     * isolated per population; the report is resolved only when every selected
+     * boundary resolves, and preserves incomplete checker state as exit code 2.
+     */
+    async function inspect(context, target) {
+        const { analysis } = context;
+        const root = context.cwd;
+        const all = context.populations;
+        const exact = new Set(all.flatMap((population) => populationHasTarget(population, target, root)
+            ? [scopeId(population.scope)]
+            : []));
+        // An indexed spelling is authoritative: grammar inference is only a fallback
+        // when no configured identity exposes this exact public target.
+        const selected = exact.size === 0
+            ? applicablePopulations(all, target)
+            : all.filter((population) => exact.has(scopeId(population.scope)));
+        const inspections = (await Promise.all(selected.map((population) => inspectPopulation(analysis, population, root, target)))).sort((left, right) => compare(scopeId(left.scope), scopeId(right.scope)));
+        const diagnostics = uniqueDiagnostics([
+            ...analysis.report.diagnostics,
+            ...inspections.flatMap((inspection) => inspection.diagnostics),
+        ]);
+        const resolved = inspections.length !== 0 &&
+            inspections.every((inspection) => inspection.status === "resolved");
+        const incomplete = analysis.report.status === "incomplete" ||
+            inspections.some((inspection) => inspection.status === "incomplete");
+        const exitCode = incomplete
+            ? 2
+            : !resolved
+                ? 1
+                : analysis.report.exitCode;
+        return {
+            schemaVersion: 1,
+            command: "inspect",
+            configFile: analysis.report.configFile,
+            status: incomplete ? "incomplete" : "complete",
+            success: resolved && exitCode === 0,
+            exitCode,
+            target,
+            inspections,
+            diagnostics,
+        };
+    }
+    EvidenceQueryProgrammer.inspect = inspect;
+    /**
+     * Exports the evaluated graph as boundaries, nodes, acknowledgement edges, and reviews.
+     *
+     * Each claim/reference pair receives its own boundary even when it reuses an
+     * inventory. Nodes are keyed by boundary and role so coverage cannot visually
+     * leak between obligations, while documentation-host nodes represent evidence
+     * attached outside any selected claim unit.
+     */
+    function graph(context) {
+        const { analysis } = context;
+        const root = context.cwd;
+        const configured = context.populations;
+        const nodes = new Map();
+        const boundaries = [];
+        const edges = [];
+        const reviews = [];
+        // Join inputs, results, and report labels by construction order. A positional
+        // mismatch violates analysis invariants and is rejected by the require helpers.
+        analysis.graphInput.claims.forEach((claim, claimPosition) => {
+            const reportClaim = requireReportClaim(analysis, claimPosition);
+            const claimPopulation = requirePopulation(configured, "claim", reportClaim.claim);
+            claim.references.forEach((reference, referencePosition) => {
+                const reportObligation = requireReportObligation(analysis, claimPosition, referencePosition);
+                const obligation = requireResultObligation(analysis, claimPosition, referencePosition);
+                const referencePopulation = requirePopulation(configured, "reference", reportClaim.claim, reportObligation.reference);
+                const boundaryId = boundary(reportClaim.claim, reportObligation.reference);
+                boundaries.push({
+                    id: boundaryId,
+                    claim: claimPopulation.scope,
+                    reference: referencePopulation.scope,
+                    policy: graphPolicy(reference),
+                    active: obligation.active,
+                    complete: obligation.complete,
+                    unitIds: obligation.unitIds,
+                    coveredUnitIds: obligation.coveredUnitIds,
+                    missingUnitIds: obligation.missingUnitIds,
+                    hostCoverage: obligation.hostCoverage,
+                });
+                for (const item of listPopulation(claimPopulation, root))
+                    if (item.selection === "selected")
+                        nodes.set(graphUnitNodeId(boundaryId, "claim", item.unitId), graphUnitNode(boundaryId, "claim", item, obligation.edges.some((edge) => edge.hostUnitIds.includes(item.unitId)), false));
+                for (const item of listPopulation(referencePopulation, root))
+                    nodes.set(graphUnitNodeId(boundaryId, "reference", item.unitId), graphUnitNode(boundaryId, "reference", item, covered(referencePopulation, item.unitId), missing(referencePopulation, item.unitId)));
+                for (const edge of obligation.edges) {
+                    const declaration = requireDeclaration(claim.inventory, edge.declarationId);
+                    const sourceNodeIds = graphSourceNodes(nodes, boundaryId, claimPopulation, declaration.hostId, edge.hostUnitIds, root);
+                    const targetNodeId = graphUnitNodeId(boundaryId, "reference", edge.targetUnitId);
+                    ensureUnitNode(nodes, boundaryId, "reference", referencePopulation, edge.targetUnitId, root);
+                    edges.push({
+                        id: `${boundaryId}:edge:${edge.declarationId}:${edge.targetUnitId}`,
+                        boundaryId,
+                        kind: edge.kind,
+                        declaration,
+                        sourceNodeIds,
+                        hostUnitIds: edge.hostUnitIds,
+                        targetNodeId,
+                        targetUnitId: edge.targetUnitId,
+                        unitIds: edge.unitIds,
+                        fingerprint: edge.fingerprint,
+                    });
+                }
+                for (const resolution of reference.reviewResolutions ?? []) {
+                    const review = requireReview(claim.inventory, resolution.reviewId);
+                    const sourceNodeIds = graphSourceNodes(nodes, boundaryId, claimPopulation, review.hostId, requireHost(claim.inventory.hosts, review.hostId).unitIds, root);
+                    const targetNodeIds = resolution.resolution.units.map((unit) => {
+                        ensureUnitNode(nodes, boundaryId, "reference", referencePopulation, unit.id, root);
+                        return graphUnitNodeId(boundaryId, "reference", unit.id);
+                    });
+                    reviews.push({
+                        id: `${boundaryId}:review:${review.id}`,
+                        boundaryId,
+                        reviews: review.reviews,
+                        review,
+                        status: resolution.resolution.status,
+                        sourceNodeIds,
+                        targetNodeIds,
+                    });
+                }
+            });
+        });
+        return {
+            schemaVersion: 1,
+            command: "graph",
+            configFile: analysis.report.configFile,
+            status: analysis.report.status,
+            success: analysis.report.success,
+            exitCode: analysis.report.exitCode,
+            boundaries,
+            nodes: Array.from(nodes.values()).sort((left, right) => compare(left.id, right.id)),
+            edges: edges.sort((left, right) => compare(left.id, right.id)),
+            reviews: reviews.sort((left, right) => compare(left.id, right.id)),
+            diagnostics: analysis.report.diagnostics,
+        };
+    }
+    EvidenceQueryProgrammer.graph = graph;
+    /**
+     * Lists artifact adapters that the installed runtime can actually analyze.
+     *
+     * Registry entries without an adapter remain parser metadata and are omitted.
+     * Language and database entries are combined then ordered by type, providing a
+     * stable capability report without depending on registry declaration order.
+     */
+    function languages() {
+        const languages = [
+            ...EvidenceLanguageRegistry_1.EvidenceLanguageRegistry.list().flatMap((language) => language.adapter === undefined
+                ? []
+                : [
+                    {
+                        type: language.type,
+                        name: language.name,
+                        grammars: language.grammars,
+                        adapter: language.adapter,
+                    },
+                ]),
+            ...EvidenceLanguageRegistry_1.EvidenceLanguageRegistry.databases().flatMap((language) => language.adapter === undefined
+                ? []
+                : [
+                    {
+                        type: language.type,
+                        name: language.name,
+                        grammars: language.grammars,
+                        adapter: language.adapter,
+                    },
+                ]),
+        ].sort((left, right) => compare(left.type, right.type));
+        return {
+            schemaVersion: 1,
+            command: "languages",
+            total: languages.length,
+            languages,
+        };
+    }
+    EvidenceQueryProgrammer.languages = languages;
+    /**
+     * Builds a query context for every configured claim and reference entry.
+     *
+     * The context list preserves graph-input order and gives each reference its own
+     * wrapper, even when several entries share the same inventory. This preserves
+     * obligation-specific selection, policies, and coverage during later queries.
+     */
+    function populations(analysis) {
+        const output = [];
+        analysis.graphInput.claims.forEach((claim, claimPosition) => {
+            const reportClaim = requireReportClaim(analysis, claimPosition);
+            output.push({
+                scope: {
+                    role: "claim",
+                    claim: reportClaim.claim,
+                    ...(reportClaim.name === undefined ? {} : { name: reportClaim.name }),
+                    type: reportClaim.type,
+                },
+                inventory: claim.inventory,
+                unitIds: claim.unitIds,
+            });
+            claim.references.forEach((reference, referencePosition) => {
+                const reportObligation = requireReportObligation(analysis, claimPosition, referencePosition);
+                output.push({
+                    scope: {
+                        role: "reference",
+                        claim: reportClaim.claim,
+                        reference: reportObligation.reference,
+                        type: reportObligation.type,
+                    },
+                    inventory: reference.inventory,
+                    unitIds: reference.unitIds,
+                    reference,
+                    obligation: requireResultObligation(analysis, claimPosition, referencePosition),
+                });
+            });
+        });
+        return output.map((population) => new EvidenceQueryPopulationContext_1.EvidenceQueryPopulationContext(population));
+    }
+    EvidenceQueryProgrammer.populations = populations;
+    /**
+     * Lists one population's selected identities and visible structural ancestors.
+     *
+     * Visibility is owned by {@link EvidenceQueryPopulationContext}; this helper
+     * only turns visible units into public rows. Units without a public address are
+     * excluded because list output must contain targets that inspect can accept.
+     */
+    function listPopulation(population, cwd) {
+        const visible = population.visible;
+        return population.inventory.units.flatMap((unit) => {
+            if (!visible.has(unit.id))
+                return [];
+            const item = listItem(population, unit, cwd);
+            return item === undefined ? [] : [item];
+        });
+    }
+    /**
+     * Creates one public list row for an addressable inventory unit.
+     *
+     * The first sorted alias becomes the canonical target, while every alias is
+     * retained for callers that need an exact spelling. Returning `undefined` for
+     * an unaddressable unit lets list operations omit internal identities without
+     * manufacturing a target that the resolver cannot round-trip.
+     */
+    function listItem(population, unit, cwd) {
+        const aliases = targets(population, unit.id, cwd);
+        const target = aliases[0];
+        if (target === undefined)
+            return undefined;
+        return {
+            id: `${scopeId(population.scope)}:unit:${unit.id}`,
+            scope: population.scope,
+            unitId: unit.id,
+            symbol: unit.symbol,
+            name: unit.name,
+            selection: selection(population, unit.id),
+            target,
+            aliases,
+            locations: unit.sites.map((site) => ({
+                file: site.file,
+                range: site.range,
+            })),
+        };
+    }
+    /**
+     * Resolves a target and gathers its query evidence within one population boundary.
+     *
+     * A synthetic attached host gives the shared resolver a CLI-relative source
+     * context without pretending that the query came from a real documentation
+     * comment. The returned units, coverage, acknowledgements, reviews, and
+     * diagnostics all remain scoped to this one claim or reference context.
+     */
+    async function inspectPopulation(analysis, population, cwd, target) {
+        const host = commandHost(cwd);
+        const statement = {
+            target,
+            hostId: host.id,
+            location: { file: host.file, range: host.range },
+        };
+        const resolution = await new EvidenceTargetResolver_1.EvidenceTargetResolver([population.inventory], population.scope.type).resolve(statement, host, population.unitIds);
+        const units = resolution.units.map((unit) => inspectedUnit(population, unit, cwd));
+        const unitIds = new Set(units.map((unit) => unit.item.unitId));
+        return {
+            scope: population.scope,
+            status: resolution.status,
+            addresses: InventoryMerge_1.InventoryMerge.unique(resolution.addresses.flatMap((address) => formatAddress(population, address.file, address.segments, cwd)), (address) => address).sort(compare),
+            units,
+            withdrawals: resolution.withdrawals,
+            obligations: inspectedObligations(population, unitIds),
+            acknowledgements: inspectedAcknowledgements(analysis, population, unitIds),
+            reviews: inspectedReviews(analysis, population, unitIds),
+            diagnostics: resolution.diagnostics.map((diagnostic) => scopedDiagnostic(diagnostic, population.scope)),
+        };
+    }
+    /**
+     * Builds the detailed inspection record for one resolved unit.
+     *
+     * Only direct children are included so recursive client views can choose their
+     * own expansion. A fingerprint is exposed only from a complete inventory: an
+     * incomplete parse cannot safely provide a stable review identity.
+     */
+    function inspectedUnit(population, unit, cwd) {
+        const item = listItem(population, unit, cwd);
+        if (item === undefined)
+            throw new Error(`Evidence identity '${unit.id}' has no public address.`);
+        const children = population.inventory.units.flatMap((candidate) => {
+            if (candidate.parentId !== unit.id)
+                return [];
+            const child = listItem(population, candidate, cwd);
+            return child === undefined ? [] : [child];
+        });
+        return {
+            item,
+            children,
+            hosts: population.inventory.hosts
+                .filter((host) => host.unitIds.includes(unit.id))
+                .sort((left, right) => compare(left.id, right.id)),
+            ...(population.inventory.complete
+                ? {
+                    fingerprint: EvidenceFingerprint_1.EvidenceFingerprint.inspect(population.inventory, unit.id),
+                }
+                : {}),
+        };
+    }
+    /**
+     * Reports the reference obligations that govern inspected selected identities.
+     *
+     * Claim populations own no coverage obligation, and unselected resolved units
+     * must not imply coverage. Missing graph policy data returns no rows so an
+     * inconsistent query context cannot be presented as a passing obligation.
+     */
+    function inspectedObligations(population, unitIds) {
+        if (population.scope.role !== "reference")
+            return [];
+        const obligation = population.obligation;
+        const reference = population.scope.reference;
+        if (obligation === undefined || reference === undefined)
+            return [];
+        return Array.from(unitIds).flatMap((unitId) => {
+            const unit = population.inventory.units.find((candidate) => candidate.id === unitId);
+            if (unit === undefined)
+                return [];
+            const state = selection(population, unitId);
+            if (state === "unselected")
+                return [];
+            return [
+                {
+                    claim: population.scope.claim,
+                    reference,
+                    policy: graphPolicy(requirePopulationReference(population)),
+                    active: obligation.active,
+                    complete: obligation.complete,
+                    selection: state,
+                    covered: covered(population, unitId),
+                    missing: missing(population, unitId),
+                },
+            ];
+        });
+    }
+    /**
+     * Collects acknowledgement edges relevant to inspected reference identities.
+     *
+     * The search joins graph results to the matching claim input by configured
+     * coordinates, preserving duplicate reference obligations. Broken graph links
+     * are omitted here because checker construction already owns their diagnostics.
+     */
+    function inspectedAcknowledgements(analysis, population, unitIds) {
+        if (population.scope.role !== "reference" ||
+            population.scope.reference === undefined)
+            return [];
+        return analysis.graph.claims.flatMap((claim, claimPosition) => {
+            if (claim.claim !== population.scope.claim)
+                return [];
+            const input = analysis.graphInput.claims[claimPosition];
+            if (input === undefined)
+                return [];
+            return claim.obligations.flatMap((obligation) => {
+                if (obligation.reference !== population.scope.reference)
+                    return [];
+                return obligation.edges.flatMap((edge) => {
+                    if (!unitIds.has(edge.targetUnitId) &&
+                        !edge.unitIds.some((unitId) => unitIds.has(unitId)))
+                        return [];
+                    const declaration = input.inventory.declarations.find((candidate) => candidate.id === edge.declarationId);
+                    if (declaration === undefined)
+                        return [];
+                    const host = input.inventory.hosts.find((candidate) => candidate.id === declaration.hostId);
+                    if (host === undefined)
+                        return [];
+                    return [
+                        {
+                            claim: obligation.claim,
+                            reference: obligation.reference,
+                            declaration,
+                            host,
+                            hostUnitIds: edge.hostUnitIds,
+                            targetUnitId: edge.targetUnitId,
+                            unitIds: edge.unitIds,
+                            fingerprint: edge.fingerprint,
+                        },
+                    ];
+                });
+            });
+        });
+    }
+    /**
+     * Collects review resolutions whose target contains an inspected identity.
+     *
+     * Descendant matching lets an inspection of a child expose a review on its
+     * selected ancestor. The report retains the reference coordinates so review
+     * status cannot be attributed to a different population with the same units.
+     */
+    function inspectedReviews(analysis, population, unitIds) {
+        if (population.scope.role !== "reference" ||
+            population.scope.reference === undefined)
+            return [];
+        return analysis.graphInput.claims.flatMap((claim, claimPosition) => claim.references.flatMap((reference, referencePosition) => {
+            const reportClaim = requireReportClaim(analysis, claimPosition);
+            const reportReference = requireReportObligation(analysis, claimPosition, referencePosition);
+            if (reportClaim.claim !== population.scope.claim ||
+                reportReference.reference !== population.scope.reference)
+                return [];
+            return (reference.reviewResolutions ?? []).flatMap((entry) => {
+                if (!entry.resolution.units.some((target) => Array.from(unitIds).some((unitId) => population.descends(unitId, target.id))))
+                    return [];
+                const review = claim.inventory.reviews.find((candidate) => candidate.id === entry.reviewId);
+                if (review === undefined)
+                    return [];
+                const host = claim.inventory.hosts.find((candidate) => candidate.id === review.hostId);
+                if (host === undefined)
+                    return [];
+                return [
+                    {
+                        claim: reportClaim.claim,
+                        reference: reportReference.reference,
+                        review,
+                        host,
+                        status: entry.resolution.status,
+                        unitIds: entry.resolution.units.map((unit) => unit.id),
+                    },
+                ];
+            });
+        }));
+    }
+    /**
+     * Narrows target inspection to populations whose artifact grammar can accept it.
+     *
+     * Prisma and Swagger have unmistakable target forms; file targets consult the
+     * installed registry. When inference finds no type, every population remains
+     * eligible so the resolver can return its own actionable diagnostics.
+     */
+    function applicablePopulations(populations, target) {
+        if (target.startsWith("prisma:"))
+            return populations.filter((population) => population.scope.type === "prisma");
+        if (swaggerLike(target))
+            return populations.filter((population) => population.scope.type === "swagger");
+        const file = targetFile(target);
+        const types = new Set();
+        if (/\.(?:md|markdown|mdx)$/iu.test(file))
+            types.add("markdown");
+        for (const language of [
+            ...EvidenceLanguageRegistry_1.EvidenceLanguageRegistry.list(),
+            ...EvidenceLanguageRegistry_1.EvidenceLanguageRegistry.databases(),
+        ])
+            try {
+                EvidenceLanguageRegistry_1.EvidenceLanguageRegistry.select(language.type, file);
+                types.add(language.type);
+            }
+            catch {
+                continue;
+            }
+        const selected = populations.filter((population) => types.has(population.scope.type));
+        return selected.length === 0 ? populations : selected;
+    }
+    /**
+     * Classifies an identity by its configured and query-visible membership.
+     *
+     * Selection is owned by the population context: ancestors exist only to make
+     * selected descendants addressable, while unselected identities must not gain
+     * coverage semantics merely because they share an inventory.
+     */
+    function selection(population, unitId) {
+        if (population.selected.has(unitId))
+            return "selected";
+        return population.visible.has(unitId) ? "ancestor" : "unselected";
+    }
+    /**
+     * Formats the public aliases for one semantic identity in deterministic order.
+     *
+     * Inventory aliases may render to the same artifact target, so deduplication
+     * occurs after formatting. The sorted result supplies the canonical list target
+     * and makes exact-target matching stable across adapter traversal order.
+     */
+    function targets(population, unitId, cwd) {
+        return InventoryMerge_1.InventoryMerge.unique((population.addresses.get(unitId) ?? []).flatMap((address) => formatAddress(population, address.file, address.segments, cwd)), (target) => target).sort(compare);
+    }
+    /**
+     * Tests whether a configured identity exposes the exact requested target spelling.
+     *
+     * Only configured addresses participate because an ancestor's visible address
+     * must not override grammar inference for a target that names no obligation.
+     * A match is used solely to choose populations; resolution remains authoritative.
+     */
+    function populationHasTarget(population, target, cwd) {
+        const configured = population.configured;
+        return population.inventory.addresses.some((address) => configured.has(address.unitId) &&
+            formatAddress(population, address.file, address.segments, cwd).includes(target));
+    }
+    /**
+     * Renders one indexed address with the target grammar of its population.
+     *
+     * Prisma and Swagger do not use file-qualified accessors, while Markdown must
+     * preserve selected logical aliases for a physical file. Other artifacts are
+     * made CLI-relative; an unrenderable Swagger address is omitted from query output.
+     */
+    function formatAddress(population, file, segments, cwd) {
+        if (population.scope.type === "prisma")
+            return [`prisma:${segments.join(".")}`];
+        if (population.scope.type === "swagger")
+            return segments.length === 1 && segments[0] !== undefined
+                ? [segments[0]]
+                : [];
+        if (population.scope.type === "markdown") {
+            const logical = population.inventory.sources.flatMap((source) => source.addresses.flatMap((address) => address.selected !== false &&
+                EvidenceFileTarget_1.EvidenceFileTarget.normalize(address.absolute) ===
+                    EvidenceFileTarget_1.EvidenceFileTarget.normalize(file)
+                ? [address.relative]
+                : []));
+            const files = logical.length === 0 ? [file] : logical;
+            return files.map((candidate) => segments.length === 0
+                ? MarkdownTarget_1.MarkdownTarget.normalize(candidate)
+                : `${MarkdownTarget_1.MarkdownTarget.normalize(candidate)}#${segments.join("#")}`);
+        }
+        return [
+            EvidenceFileTarget_1.EvidenceFileTarget.format({
+                file: node_path_1.default.relative(cwd, file),
+                segments,
+            }),
+        ];
+    }
+    /**
+     * Creates the attached synthetic host used for command-line target resolution.
+     *
+     * Its file anchors relative paths at the query working directory without adding
+     * a document to any inventory. The fixed identity prevents command hosts from
+     * being confused with authored annotation hosts in resolver diagnostics.
+     */
+    function commandHost(cwd) {
+        const file = node_path_1.default.join(cwd, ".evidence-inspect");
+        return {
+            id: "evidence:inspect:host",
+            file,
+            origins: [file],
+            range: zeroLocation(file).range,
+            unitIds: [],
+            attachment: "attached",
+        };
+    }
+    /**
+     * Creates the zero-width coordinate assigned to a synthetic command host.
+     *
+     * Query input has no authored source span, but downstream diagnostics require a
+     * complete location. Line and column one with offset zero provides that boundary
+     * without claiming a real character exists in the synthetic file.
+     */
+    function zeroLocation(file) {
+        return {
+            file,
+            range: {
+                start: { line: 1, column: 1, offset: 0 },
+                end: { line: 1, column: 1, offset: 0 },
+            },
+        };
+    }
+    /**
+     * Projects an addressable query row into a boundary-specific graph unit node.
+     *
+     * The caller supplies coverage state because it differs by reference obligation
+     * even when the underlying inventory unit is shared. The generated node carries
+     * the public target and source locations needed by graph consumers.
+     */
+    function graphUnitNode(boundaryId, role, item, isCovered, isMissing) {
+        return {
+            id: graphUnitNodeId(boundaryId, role, item.unitId),
+            boundaryId,
+            role,
+            unitId: item.unitId,
+            symbol: item.symbol,
+            name: item.name,
+            target: item.target,
+            selection: item.selection,
+            covered: isCovered,
+            missing: isMissing,
+            locations: item.locations,
+        };
+    }
+    /**
+     * Returns graph source nodes for an annotation host within one boundary.
+     *
+     * Hosts attached to units reuse claim nodes, preserving unit-level edges. A
+     * detached-from-selection host becomes a dedicated node so evidence remains
+     * visible without inventing a claim unit; absent hosts fail the graph invariant.
+     */
+    function graphSourceNodes(nodes, boundaryId, population, hostId, unitIds, cwd) {
+        if (unitIds.length !== 0) {
+            for (const unitId of unitIds)
+                ensureUnitNode(nodes, boundaryId, "claim", population, unitId, cwd);
+            return unitIds.map((unitId) => graphUnitNodeId(boundaryId, "claim", unitId));
+        }
+        const host = requireHost(population.inventory.hosts, hostId);
+        const id = `${boundaryId}:host:${host.id}`;
+        const node = {
+            id,
+            boundaryId,
+            role: "host",
+            hostId: host.id,
+            name: host.id,
+            location: { file: host.file, range: host.range },
+        };
+        nodes.set(id, node);
+        return [id];
+    }
+    /**
+     * Ensures a boundary-specific graph node exists for a referenced identity.
+     *
+     * Existing nodes are retained to preserve their coverage state. An absent unit
+     * or missing public address is an invalid graph projection, so this throws
+     * instead of exporting an edge that a consumer cannot inspect.
+     */
+    function ensureUnitNode(nodes, boundaryId, role, population, unitId, cwd) {
+        const id = graphUnitNodeId(boundaryId, role, unitId);
+        if (nodes.has(id))
+            return;
+        const unit = population.inventory.units.find((candidate) => candidate.id === unitId);
+        if (unit === undefined)
+            throw new Error(`Graph identity '${unitId}' is absent from its inventory.`);
+        const item = listItem(population, unit, cwd);
+        if (item === undefined)
+            throw new Error(`Graph identity '${unitId}' has no public address.`);
+        nodes.set(id, graphUnitNode(boundaryId, role, item, false, false));
+    }
+    /**
+     * Tests whether a reference unit is covered in its obligation.
+     *
+     * Directly selected units use graph coverage. A visible ancestor is covered
+     * only when it has selected descendants and all are covered, preventing an
+     * empty structural container from appearing complete.
+     */
+    function covered(population, unitId) {
+        const obligation = population.obligation;
+        if (obligation === undefined)
+            return false;
+        if (obligation.coveredUnitIds.includes(unitId))
+            return true;
+        if (selection(population, unitId) !== "ancestor")
+            return false;
+        const descendants = population.selectedDescendants(unitId);
+        return (descendants.length !== 0 &&
+            descendants.every((id) => obligation.coveredUnitIds.includes(id)));
+    }
+    /**
+     * Tests whether a reference unit exposes missing coverage in its obligation.
+     *
+     * Direct missing identities and ancestors with any missing selected descendant
+     * are both marked missing. Without an obligation, the population owns no
+     * coverage state and therefore returns false.
+     */
+    function missing(population, unitId) {
+        const obligation = population.obligation;
+        if (obligation === undefined)
+            return false;
+        if (obligation.missingUnitIds.includes(unitId))
+            return true;
+        return population
+            .selectedDescendants(unitId)
+            .some((id) => obligation.missingUnitIds.includes(id));
+    }
+    /**
+     * Retrieves the query population at an exact claim/reference coordinate.
+     *
+     * Role is part of the key because one inventory can serve both sides of an
+     * obligation. A missing entry means analysis and query context lost positional
+     * alignment, so graph export throws rather than relabelling its data.
+     */
+    function requirePopulation(entries, role, claim, reference) {
+        const population = entries.find((entry) => entry.scope.role === role &&
+            entry.scope.claim === claim &&
+            entry.scope.reference === reference);
+        if (population === undefined)
+            throw new Error(`Missing query population '${role}:${claim}:${reference ?? -1}'.`);
+        return population;
+    }
+    /**
+     * Retrieves graph reference policy input from a reference population.
+     *
+     * Only reference contexts own this data. Its absence signals a context assembly
+     * invariant failure, and throwing prevents a graph report from silently using
+     * fabricated defaults.
+     */
+    function requirePopulationReference(population) {
+        if (population.reference === undefined)
+            throw new Error("A reference query population has no graph input.");
+        return population.reference;
+    }
+    /**
+     * Projects effective reference policy flags into a public graph boundary.
+     *
+     * Optional graph-input flags become explicit booleans so report consumers need
+     * not reproduce configuration defaults. Severity is retained unchanged because
+     * it controls the consequence of coverage diagnostics.
+     */
+    function graphPolicy(reference) {
+        return {
+            severity: reference.severity,
+            noEvidenceExclude: reference.noEvidenceExclude === true,
+            uniqueEvidence: reference.uniqueEvidence === true,
+            singleEvidencePerSymbol: reference.singleEvidencePerSymbol === true,
+            checklist: reference.checklist === true,
+            requireReview: reference.requireReview === true,
+        };
+    }
+    /**
+     * Retrieves the checker report claim at a graph-input position.
+     *
+     * Graph export joins report labels by construction order. A missing row exposes
+     * a broken checker-analysis invariant and throws before coordinates can be
+     * assigned to a wrong boundary.
+     */
+    function requireReportClaim(analysis, position) {
+        const claim = analysis.report.claims[position];
+        if (claim === undefined)
+            throw new Error(`Missing report claim at position ${position}.`);
+        return claim;
+    }
+    /**
+     * Retrieves the evaluated graph claim at a graph-input position.
+     *
+     * This preserves the checker’s positional join with its input and report. A
+     * missing result is an internal invariant failure, not an empty claim suitable
+     * for graph serialization.
+     */
+    function requireResultClaim(analysis, position) {
+        const claim = analysis.graph.claims[position];
+        if (claim === undefined)
+            throw new Error(`Missing graph claim at position ${position}.`);
+        return claim;
+    }
+    /**
+     * Retrieves the report obligation for exact claim and reference positions.
+     *
+     * The returned row supplies public coordinates for graph export. Throwing on a
+     * missing position prevents edges and policies from being emitted under an
+     * unrelated reference label.
+     */
+    function requireReportObligation(analysis, claim, reference) {
+        const obligation = requireReportClaim(analysis, claim).obligations[reference];
+        if (obligation === undefined)
+            throw new Error(`Missing report obligation at position ${claim}:${reference}.`);
+        return obligation;
+    }
+    /**
+     * Retrieves the evaluated obligation for exact claim and reference positions.
+     *
+     * Graph export uses its coverage, edges, and completion state together with the
+     * matching report row. Missing positional state is fatal because an empty
+     * substitute could falsely make a boundary look complete.
+     */
+    function requireResultObligation(analysis, claim, reference) {
+        const obligation = requireResultClaim(analysis, claim).obligations[reference];
+        if (obligation === undefined)
+            throw new Error(`Missing graph obligation at position ${claim}:${reference}.`);
+        return obligation;
+    }
+    /**
+     * Retrieves an acknowledgement by its inventory-local identity.
+     *
+     * Graph edges retain only this identity, while export needs the authored target,
+     * reason, and location. A missing record breaks that graph-to-inventory link and
+     * throws instead of emitting an unverifiable edge.
+     */
+    function requireDeclaration(inventory, id) {
+        const declaration = inventory.declarations.find((candidate) => candidate.id === id);
+        if (declaration === undefined)
+            throw new Error(`Missing graph acknowledgement '${id}'.`);
+        return declaration;
+    }
+    /**
+     * Retrieves a review by its inventory-local identity.
+     *
+     * Review resolutions refer back to the authored annotation through this value.
+     * A missing record indicates invalid graph input and is fatal because the public
+     * report cannot accurately represent the review without it.
+     */
+    function requireReview(inventory, id) {
+        const review = inventory.reviews.find((candidate) => candidate.id === id);
+        if (review === undefined)
+            throw new Error(`Missing graph review '${id}'.`);
+        return review;
+    }
+    /**
+     * Retrieves the documentation host identified by an annotation.
+     *
+     * Hosts supply source locations and attached claim units for graph nodes. An
+     * absent host violates inventory ownership, so callers throw before exporting
+     * a source edge with a fabricated or incomplete origin.
+     */
+    function requireHost(hosts, id) {
+        const host = hosts.find((candidate) => candidate.id === id);
+        if (host === undefined)
+            throw new Error(`Missing graph host '${id}'.`);
+        return host;
+    }
+    /**
+     * Adds the query population’s configured coordinates to a diagnostic.
+     *
+     * Resolver diagnostics are inventory-local; query output must identify the
+     * independent claim and reference obligation that produced them. Claim scope is
+     * always present, while reference scope remains absent for claim populations.
+     */
+    function scopedDiagnostic(diagnostic, scope) {
+        return {
+            ...diagnostic,
+            claim: scope.claim,
+            ...(scope.reference === undefined ? {} : { reference: scope.reference }),
+        };
+    }
+    /**
+     * Deduplicates diagnostics whose complete public content is identical.
+     *
+     * Inspection combines checker and per-population diagnostics, which can reach
+     * the same error through several compatible populations. Serialization includes
+     * coordinates and repair text, preserving distinct actionable failures.
+     */
+    function uniqueDiagnostics(diagnostics) {
+        return InventoryMerge_1.InventoryMerge.unique(diagnostics, (diagnostic) => JSON.stringify(diagnostic));
+    }
+    /**
+     * Formats the stable key for a claim scope or one of its reference scopes.
+     *
+     * The key is internal to query ordering and exact-population selection. Omitting
+     * the reference segment for claims preserves the distinct coordinate shape and
+     * prevents a claim from colliding with its first reference.
+     */
+    function scopeId(scope) {
+        return scope.reference === undefined
+            ? `claim:${scope.claim}`
+            : `claim:${scope.claim}:reference:${scope.reference}`;
+    }
+    /**
+     * Formats the graph boundary identity for one claim/reference obligation.
+     *
+     * Boundary IDs are intentionally coordinate-based, even when populations share
+     * an inventory, so exported nodes and edges cannot leak coverage across policy
+     * boundaries.
+     */
+    function boundary(claim, reference) {
+        return `claim:${claim}:reference:${reference}`;
+    }
+    /**
+     * Formats a graph node identity for one unit within a boundary and role.
+     *
+     * Claim and reference nodes need separate IDs because the same semantic unit can
+     * appear on both sides of an obligation with different selection and coverage
+     * state.
+     */
+    function graphUnitNodeId(boundaryId, role, unitId) {
+        return `${boundaryId}:${role}:${unitId}`;
+    }
+    /**
+     * Extracts the decoded file portion from a possibly qualified target.
+     *
+     * Type inference examines only the physical-looking file prefix, leaving accessor
+     * syntax untouched. Invalid percent encoding is retained verbatim so inference
+     * can fail normally and the resolver can report the authored target.
+     */
+    function targetFile(target) {
+        const separator = target.indexOf("#");
+        const encoded = separator < 0 ? target : target.slice(0, separator);
+        try {
+            return decodeURIComponent(encoded);
+        }
+        catch {
+            return encoded;
+        }
+    }
+    /**
+     * Recognizes target spellings reserved for Swagger operation resolution.
+     *
+     * HTTP method prefixes and non-single-letter scheme-like prefixes distinguish
+     * these targets from ordinary file paths. This early classification keeps a
+     * Swagger target from being needlessly sent to unrelated language adapters.
+     */
+    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));
+    }
+    /**
+     * Orders query identities and rendered targets by code-unit comparison.
+     *
+     * Avoiding locale collation makes list, inspection, and graph output reproducible
+     * across operating systems and independent of the invoking process locale.
+     */
+    function compare(left, right) {
+        return left < right ? -1 : left > right ? 1 : 0;
+    }
+})(EvidenceQueryProgrammer || (exports.EvidenceQueryProgrammer = EvidenceQueryProgrammer = {}));