@wrtnlabs/evidence 0.0.0

package/lib/structures/IEvidenceGraphClaim.d.ts

@@ -0,0 +1,65 @@
+import type { EvidenceSeverity } from "../typings/EvidenceSeverity";
+import type { IEvidenceGraphReference } from "./IEvidenceGraphReference";
+import type { IEvidenceInventory } from "./IEvidenceInventory";
+/**
+ * A materialized claim's semantic hosts and independent evidence requirements.
+ *
+ * The inventory supplies physical declarations and annotations; `unitIds` selects
+ * the semantic hosts that participate. Reference entries supply their own target
+ * inventories, selectors, and policies. Shared source files or labels do not
+ * combine the coverage owed by different claims.
+ *
+ * Exclusion carrier restrictions narrow eligible positions within this claim.
+ * They do not create hosts or widen the claim's selected population.
+ */
+export interface IEvidenceGraphClaim {
+    /**
+     * Original zero-based position in the configuration's claim array.
+     *
+     * Omission uses this record's array position for direct graph callers. Explicit
+     * indices preserve attribution after the checker filters inactive claims.
+     */
+    index?: number;
+    /**
+     * Optional human-readable label for claim diagnostics.
+     *
+     * Labels do not participate in identity. Two claims with equal names still
+     * retain independent hosts, references, and coverage findings.
+     */
+    name?: string;
+    /**
+     * Effective claim severity, including the inactive off state.
+     *
+     * An off claim skips reference evaluation. Active claims attach this level to
+     * findings originating from their own inventory and host participation.
+     */
+    severity: EvidenceSeverity;
+    /**
+     * Captured declaration and documentation inventory for the claim.
+     *
+     * Evaluation reconciles its records and validates ownership before selecting
+     * hosts. Incompleteness prevents its references from producing a coverage pass.
+     */
+    inventory: IEvidenceInventory;
+    /**
+     * Semantic identities selected as evidence hosts.
+     *
+     * Eligible hosts without tags remain part of this population, allowing zero
+     * acknowledgements to fail cardinality and checklist policies.
+     */
+    unitIds: string[];
+    /**
+     * Carrier IDs permitted to write exclusions for this claim.
+     *
+     * Omission permits every otherwise eligible attached public host. An explicit
+     * selection restricts carriers without granting attachment to an invalid host.
+     */
+    exclusionHostIds?: string[];
+    /**
+     * Target populations this claim must acknowledge independently.
+     *
+     * Repeated selections retain separate policies and diagnostic boundaries. An
+     * acknowledgement accepted by one reference may still be refused by another.
+     */
+    references: IEvidenceGraphReference[];
+}

package/lib/structures/IEvidenceGraphClaim.js

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

package/lib/structures/IEvidenceGraphClaimResult.d.ts

@@ -0,0 +1,36 @@
+import type { IEvidenceGraphObligation } from "./IEvidenceGraphObligation";
+/**
+ * Graph evaluation result for a claim and its independent references.
+ *
+ * This retains activation and extraction state without carrying display labels
+ * from configuration. `EvidenceCheckProgrammer` later joins it to the plan to
+ * produce a report. A complete claim population does not imply complete or
+ * covered reference obligations.
+ */
+export interface IEvidenceGraphClaimResult {
+    /**
+     * Authored claim index identifying this result.
+     *
+     * It remains stable when planning filters disabled configuration entries.
+     */
+    claim: number;
+    /**
+     * Whether the claim participates in graph evaluation.
+     *
+     * Inactive claims do not impose active reference coverage requirements.
+     */
+    active: boolean;
+    /**
+     * Whether the active claim population was materialized completely.
+     *
+     * Reference extraction and target resolution have their own completeness state
+     * on each obligation, so callers must inspect both levels.
+     */
+    complete: boolean;
+    /**
+     * Results for the claim's planned reference boundaries.
+     *
+     * Each entry keeps its own coverage ledger even when references share units.
+     */
+    obligations: IEvidenceGraphObligation[];
+}

package/lib/structures/IEvidenceGraphClaimResult.js

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

package/lib/structures/IEvidenceGraphCommand.d.ts

@@ -0,0 +1,40 @@
+import type { EvidenceGraphFormat } from "../typings/EvidenceGraphFormat";
+/**
+ * Parsed request to export evaluated Evidence relationships.
+ *
+ * Execution retains independent obligation boundaries, semantic and carrier nodes,
+ * acknowledgement edges, and separate review relations. The selected formatter
+ * presents that analysis without changing its coverage or completeness status.
+ */
+export interface IEvidenceGraphCommand {
+    /**
+     * Discriminator selecting graph export.
+     *
+     * The command analyzes configured populations before serializing their relationships.
+     */
+    operation: "graph";
+    /**
+     * Command directory resolved against the invocation base.
+     *
+     * It anchors configuration, output paths, and file-qualified target display.
+     */
+    cwd: string;
+    /**
+     * Configuration path used to build the exported graph.
+     *
+     * Relative paths resolve from command cwd; parsing defaults to evidence.config.ts.
+     */
+    config: string;
+    /**
+     * Requested graph serialization or visualization format.
+     *
+     * The command parser validates the graph-specific vocabulary before analysis begins.
+     */
+    format: EvidenceGraphFormat;
+    /**
+     * Optional file destination for the formatted graph.
+     *
+     * Relative paths use command cwd; omission emits the result through standard output.
+     */
+    output?: string;
+}

package/lib/structures/IEvidenceGraphCommand.js

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

package/lib/structures/IEvidenceGraphEdge.d.ts

@@ -0,0 +1,56 @@
+import type { EvidenceAcknowledgementKind } from "../typings/EvidenceAcknowledgementKind";
+/**
+ * Accepted acknowledgement connecting a claim carrier to a reference scope.
+ *
+ * The named target can be an unselected structural ancestor whose selected
+ * descendants receive coverage. The edge therefore retains both the exact target
+ * and the selected identities it covers. Its fingerprint belongs to that exact
+ * cited scope, allowing review validation without turning reviews into evidence.
+ */
+export interface IEvidenceGraphEdge {
+    /**
+     * Identity of the accepted source statement.
+     *
+     * This links the coverage contribution back to the extracted acknowledgement.
+     */
+    declarationId: string;
+    /**
+     * Documentation position carrying the acknowledgement.
+     *
+     * A single physical carrier may represent more than one semantic claim unit.
+     */
+    hostId: string;
+    /**
+     * Selected semantic claim units represented by the carrier.
+     *
+     * Checklist evaluation attributes the answer to these subjects independently.
+     */
+    hostUnitIds: string[];
+    /**
+     * Accepted scope-selection form of the acknowledgement.
+     *
+     * The declaration form determines which part of the resolved target can supply
+     * selected units to this edge.
+     */
+    kind: EvidenceAcknowledgementKind;
+    /**
+     * Semantic identity of the exact resolved target.
+     *
+     * It can be a structural scope outside the selected coverage denominator.
+     */
+    targetUnitId: string;
+    /**
+     * Selected reference identities covered by the cited scope.
+     *
+     * These are the edge's contribution after selection and policy are applied;
+     * they need not consist solely of the named target.
+     */
+    unitIds: string[];
+    /**
+     * Current seven-character fingerprint of the exact cited scope.
+     *
+     * Review matching compares the expected fingerprint with this scope's content,
+     * rather than hashing only the selected coverage subset.
+     */
+    fingerprint: string;
+}

package/lib/structures/IEvidenceGraphEdge.js

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

package/lib/structures/IEvidenceGraphExportEdge.d.ts

@@ -0,0 +1,71 @@
+import type { EvidenceAcknowledgementKind } from "../typings/EvidenceAcknowledgementKind";
+import type { IEvidenceDeclaration } from "./IEvidenceDeclaration";
+/**
+ * Accepted acknowledgement exported with boundary-qualified graph endpoints.
+ *
+ * The relationship preserves the original declaration, exact target, and selected
+ * identities covered by its scope. Endpoint node IDs are distinct from semantic
+ * unit IDs because the same units can occur in several independent obligations.
+ */
+export interface IEvidenceGraphExportEdge {
+    /**
+     * Edge identity qualified by boundary, declaration, and exact target.
+     *
+     * Deterministic ordering uses this identity when serializing the graph.
+     */
+    id: string;
+    /**
+     * Obligation whose policy accepted this acknowledgement.
+     *
+     * Coverage is restricted to this boundary even if another reference shares the target.
+     */
+    boundaryId: string;
+    /**
+     * Accepted acknowledgement form determining the cited scope.
+     *
+     * Evidence and exclusion variants retain their authored distinction in export.
+     */
+    kind: EvidenceAcknowledgementKind;
+    /**
+     * Original acknowledgement with its reason and source coordinates.
+     *
+     * Consumers can explain the accepted edge without reverse-engineering its ID.
+     */
+    declaration: IEvidenceDeclaration;
+    /**
+     * Boundary-qualified claim nodes or standalone carrier node supplying the statement.
+     *
+     * A shared carrier can represent several semantic claim subjects.
+     */
+    sourceNodeIds: string[];
+    /**
+     * Selected semantic claim identities represented by the carrier.
+     *
+     * This list can be empty for an eligible exclusion carrier outside selected claim units.
+     */
+    hostUnitIds: string[];
+    /**
+     * Boundary-qualified reference node for the exact resolved target.
+     *
+     * It can identify an ancestor whose selected descendants receive coverage.
+     */
+    targetNodeId: string;
+    /**
+     * Semantic identity underlying the exact target endpoint.
+     *
+     * This remains comparable across exported boundaries without conflating their node IDs.
+     */
+    targetUnitId: string;
+    /**
+     * Selected reference identities covered by the accepted acknowledgement scope.
+     *
+     * Aggregate targets may cover several descendants rather than only the named unit.
+     */
+    unitIds: string[];
+    /**
+     * Current fingerprint of the exact cited scope.
+     *
+     * Review validation uses that scope's content rather than the exported selected subset.
+     */
+    fingerprint: string;
+}

package/lib/structures/IEvidenceGraphExportEdge.js

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

package/lib/structures/IEvidenceGraphExportReview.d.ts

@@ -0,0 +1,55 @@
+import type { EvidenceAcknowledgementKind } from "../typings/EvidenceAcknowledgementKind";
+import type { EvidenceTargetResolutionStatus } from "../typings/EvidenceTargetResolutionStatus";
+import type { IEvidenceReview } from "./IEvidenceReview";
+/**
+ * Review relation exported separately from accepted acknowledgement edges.
+ *
+ * Target-resolution candidates become endpoints even when the result is ambiguous.
+ * The status describes identity lookup, not review freshness or successful pairing;
+ * no review relation creates coverage by itself.
+ */
+export interface IEvidenceGraphExportReview {
+    /**
+     * Review identity qualified by its independent obligation boundary.
+     *
+     * One source review can appear in several references with distinct resolution outcomes.
+     */
+    id: string;
+    /**
+     * Claim/reference obligation against which the review was resolved.
+     *
+     * Its policy determines how pairing and freshness affect evaluation.
+     */
+    boundaryId: string;
+    /**
+     * Acknowledgement form this review intends to validate.
+     *
+     * Matching also requires the relevant host, target scope, and fingerprint conditions.
+     */
+    reviews: EvidenceAcknowledgementKind;
+    /**
+     * Original review statement and its authored validation metadata.
+     *
+     * Source coordinates and description remain available for stale-review repair.
+     */
+    review: IEvidenceReview;
+    /**
+     * Resolution outcome for the review's authored target.
+     *
+     * Resolved status establishes target identity without claiming freshness or coverage.
+     */
+    status: EvidenceTargetResolutionStatus;
+    /**
+     * Boundary-qualified claim or standalone-carrier endpoints owning the review.
+     *
+     * Physical host ownership remains represented even without a selected semantic subject.
+     */
+    sourceNodeIds: string[];
+    /**
+     * Boundary-qualified reference nodes returned as target candidates.
+     *
+     * Ambiguous resolution can retain several endpoints; failures without candidates
+     * leave the collection empty.
+     */
+    targetNodeIds: string[];
+}

package/lib/structures/IEvidenceGraphExportReview.js

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

package/lib/structures/IEvidenceGraphHostCoverage.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-host answer ledger for a Markdown checklist obligation.
+ *
+ * Checklist mode requires each semantic claim host to answer the selected
+ * reference items. Keeping these ledgers separate prevents one host's answer
+ * from hiding another host's omissions. Explained IDs suppress redundant missing
+ * messages when a more direct aggregate diagnostic already describes the failure.
+ */
+export interface IEvidenceGraphHostCoverage {
+    /**
+     * Semantic claim unit that owes the checklist answers.
+     *
+     * This identifies the subject being checked, rather than a physical comment
+     * position that may carry statements for several units.
+     */
+    hostUnitId: string;
+    /**
+     * Selected reference identities answered by this host.
+     *
+     * An answer contributes here only under this obligation's acknowledgement policy.
+     */
+    coveredUnitIds: string[];
+    /**
+     * Selected reference identities still unanswered by this host.
+     *
+     * Another host's coverage does not remove an identity from this list.
+     */
+    missingUnitIds: string[];
+    /**
+     * Missing identities already attributed to a direct aggregate diagnostic.
+     *
+     * These remain missing coverage; the marker prevents duplicate explanations
+     * during checklist finalization.
+     */
+    explainedUnitIds: string[];
+}

package/lib/structures/IEvidenceGraphHostCoverage.js

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

package/lib/structures/IEvidenceGraphHostNode.d.ts

@@ -0,0 +1,46 @@
+import type { IEvidenceSourceLocation } from "./IEvidenceSourceLocation";
+/**
+ * Annotation-carrier node used when a relationship has no semantic claim endpoint.
+ *
+ * Some eligible carriers, including file-level exclusions, have no selected claim
+ * unit. Export retains their physical host as an endpoint so the relationship does
+ * not disappear or invent a semantic declaration solely for visualization.
+ */
+export interface IEvidenceGraphHostNode {
+    /**
+     * Export identity qualified by obligation and physical host.
+     *
+     * Source endpoint lists use it when no semantic claim-node IDs are available.
+     */
+    id: string;
+    /**
+     * Independent obligation containing the carrier relationship.
+     *
+     * Another reference can represent the same physical host under a different node ID.
+     */
+    boundaryId: string;
+    /**
+     * Discriminator identifying a carrier rather than a semantic-unit node.
+     *
+     * Consumers use this role before reading host-specific location fields.
+     */
+    role: "host";
+    /**
+     * Extracted documentation-host identity.
+     *
+     * This links the endpoint back to acknowledgement or review source ownership.
+     */
+    hostId: string;
+    /**
+     * Display label assigned to the standalone carrier.
+     *
+     * The current exporter uses the host identity because no declaration name exists.
+     */
+    name: string;
+    /**
+     * Original file and range of the annotation carrier.
+     *
+     * This provides a repair location despite the absence of a semantic claim unit.
+     */
+    location: IEvidenceSourceLocation;
+}

package/lib/structures/IEvidenceGraphHostNode.js

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

package/lib/structures/IEvidenceGraphInput.d.ts

@@ -0,0 +1,24 @@
+import type { IEvidenceGraphClaim } from "./IEvidenceGraphClaim";
+/**
+ * Materialized populations and resolutions ready for graph policy evaluation.
+ *
+ * The checker has already loaded sources, extracted inventories, and resolved
+ * targets. `EvidenceGraph` consumes this record without source IO. Direct callers
+ * must provide consistent identity and ownership records; a resolved status alone
+ * cannot grant coverage to a unit absent from its reference inventory.
+ *
+ * @example
+ * // There are no obligations to evaluate until a materialized claim is supplied.
+ * const input: IEvidenceGraphInput = { claims: [] };
+ * const result: IEvidenceGraphResult = EvidenceGraph.evaluate(input);
+ * // result.success is true and result.claims is empty.
+ */
+export interface IEvidenceGraphInput {
+    /**
+     * Claim populations with independently configured reference obligations.
+     *
+     * Preserve repeated claims and references rather than merging equal file sets.
+     * An empty direct graph input has no obligations and evaluates successfully.
+     */
+    claims: IEvidenceGraphClaim[];
+}

package/lib/structures/IEvidenceGraphInput.js

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

package/lib/structures/IEvidenceGraphNode.d.ts

@@ -0,0 +1,82 @@
+import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
+import type { EvidencePopulationRole } from "../typings/EvidencePopulationRole";
+import type { EvidenceUnitSelection } from "../typings/EvidenceUnitSelection";
+import type { IEvidenceSourceLocation } from "./IEvidenceSourceLocation";
+/**
+ * Semantic-unit node within one obligation and population role.
+ *
+ * The export ID distinguishes the same unit appearing on several boundaries or
+ * on both sides of one pair. Selection marks denominator participation; structural
+ * ancestors can remain addressable nodes whose coverage summarizes descendants.
+ */
+export interface IEvidenceGraphNode {
+    /**
+     * Node identity qualified by boundary, role, and semantic unit.
+     *
+     * Edge endpoints use this value rather than the unqualified semantic identity.
+     */
+    id: string;
+    /**
+     * Independent obligation owning this node's displayed state.
+     *
+     * This joins the node to its effective policy and coverage ledger.
+     */
+    boundaryId: string;
+    /**
+     * Claim or reference side represented by the node.
+     *
+     * A unit serving both roles receives separate nodes with different coverage meaning.
+     */
+    role: EvidencePopulationRole;
+    /**
+     * Underlying semantic declaration identity.
+     *
+     * Multiple boundary-qualified nodes can share this ID without merging obligations.
+     */
+    unitId: string;
+    /**
+     * Artifact-specific symbol kind of the declaration.
+     *
+     * This explains the selection vocabulary used for the node's population.
+     */
+    symbol: EvidenceSymbol;
+    /**
+     * Human-readable declaration name retained by extraction.
+     *
+     * The separately formatted target supplies the complete citation spelling.
+     */
+    name: string;
+    /**
+     * Deterministically chosen public target spelling for display and citation.
+     *
+     * Formatting follows the artifact grammar and query base directory where applicable.
+     */
+    target: string;
+    /**
+     * Selection relationship of this identity to its configured population.
+     *
+     * Ancestors provide structural context; unselected nodes may be retained as
+     * relationship endpoints without increasing the coverage denominator.
+     */
+    selection: EvidenceUnitSelection;
+    /**
+     * Coverage participation displayed for this node within its boundary.
+     *
+     * Selected claim nodes indicate an accepted edge; reference nodes report direct
+     * coverage or complete coverage of an ancestor's selected descendants.
+     */
+    covered: boolean;
+    /**
+     * Whether a reference identity or one of its selected descendants lacks evidence.
+     *
+     * Claim nodes do not use this as a per-host checklist ledger; that state belongs
+     * to the boundary's hostCoverage collection.
+     */
+    missing: boolean;
+    /**
+     * Physical declaration sites represented by this semantic node.
+     *
+     * Merged declarations retain every contributing location within one identity.
+     */
+    locations: IEvidenceSourceLocation[];
+}

package/lib/structures/IEvidenceGraphNode.js

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

package/lib/structures/IEvidenceGraphObligation.d.ts

@@ -0,0 +1,79 @@
+import type { IEvidenceGraphEdge } from "./IEvidenceGraphEdge";
+import type { IEvidenceGraphHostCoverage } from "./IEvidenceGraphHostCoverage";
+/**
+ * Coverage ledger for one independently evaluated claim/reference pair.
+ *
+ * The selected, covered, and missing ID lists preserve the denominator and its
+ * outcome. Accepted edges explain how statements contributed coverage. Checklist
+ * mode additionally records each host's answers instead of pooling them across
+ * the claim.
+ *
+ * Activation and completeness are separate: an inactive obligation is skipped,
+ * while an incomplete active obligation cannot establish a coverage pass. A
+ * complete obligation can still fail because selected units remain missing.
+ */
+export interface IEvidenceGraphObligation {
+    /**
+     * Zero-based authored index of the owning claim.
+     *
+     * This attributes the result after inactive entries have been filtered and
+     * distinguishes claims that happen to share files or labels.
+     */
+    claim: number;
+    /**
+     * Zero-based authored reference index within the claim.
+     *
+     * Repeated reference entries keep separate indices, policies, and coverage even
+     * when they require the same semantic target population.
+     */
+    reference: number;
+    /**
+     * Whether this obligation participates in coverage evaluation.
+     *
+     * Skipped obligations retain their boundary but contribute no active coverage
+     * requirement. This does not by itself describe extraction completeness.
+     */
+    active: boolean;
+    /**
+     * Whether analysis was sufficient to evaluate this obligation.
+     *
+     * Incomplete inventories or resolution data cannot establish a successful
+     * denominator. Missing evidence in a fully analyzed population is a separate state.
+     */
+    complete: boolean;
+    /**
+     * Selected semantic identities forming this obligation's denominator.
+     *
+     * Public aliases and unselected structural ancestors do not add entries. Other
+     * references select and evaluate their own ID lists independently.
+     */
+    unitIds: string[];
+    /**
+     * Selected identities acknowledged under this reference's policy.
+     *
+     * Coverage belongs to this boundary. The same identity may remain missing in a
+     * stricter reference or under a different claim.
+     */
+    coveredUnitIds: string[];
+    /**
+     * Selected identities still lacking required acknowledgement.
+     *
+     * These are uncovered requirements, not unresolved source declarations. Inspect
+     * completeness before interpreting a partial evaluation's coverage lists.
+     */
+    missingUnitIds: string[];
+    /**
+     * Accepted acknowledgement relationships contributing to this obligation.
+     *
+     * Each edge retains its source host, named target, and covered selected units.
+     * Review records do not appear here as substitute coverage.
+     */
+    edges: IEvidenceGraphEdge[];
+    /**
+     * Per-host answer coverage when this obligation uses checklist mode.
+     *
+     * Ordinary obligations leave the list empty. Checklist entries preserve missing
+     * answers for each host even when another host covers the same target item.
+     */
+    hostCoverage: IEvidenceGraphHostCoverage[];
+}

package/lib/structures/IEvidenceGraphObligation.js

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