@wrtnlabs/evidence 0.0.0

package/lib/structures/IEvidenceGraphPolicy.d.ts

@@ -0,0 +1,53 @@
+import type { EvidenceSeverity } from "../typings/EvidenceSeverity";
+/**
+ * Effective policy exposed for one independent claim/reference obligation.
+ *
+ * Queries and graph exports use this shape after optional settings have been
+ * resolved to explicit values. It explains why a statement contributes coverage
+ * in this boundary, or why another reference over the same units can reject it.
+ * The policy does not modify shared semantic identity or source inventories.
+ */
+export interface IEvidenceGraphPolicy {
+    /**
+     * Diagnostic severity of this obligation.
+     *
+     * Off denotes an inactive boundary. Active levels attribute findings to the
+     * reference after configuration inheritance has been resolved.
+     */
+    severity: EvidenceSeverity;
+    /**
+     * Whether exclusions are refused instead of acknowledged.
+     *
+     * Refusal is local to this reference and leaves positive evidence outstanding
+     * for its targets, even when another obligation accepts the same exclusion.
+     */
+    noEvidenceExclude: boolean;
+    /**
+     * Whether a selected target can have at most one positive semantic host.
+     *
+     * Repeated tags and overload positions count through semantic ownership.
+     * Exclusions do not provide positive host ownership.
+     */
+    uniqueEvidence: boolean;
+    /**
+     * Whether each selected claim host must cite exactly one selected unit.
+     *
+     * Untagged hosts count as zero. Aggregate citations count each selected
+     * descendant they acknowledge rather than counting as one target token.
+     */
+    singleEvidencePerSymbol: boolean;
+    /**
+     * Whether every host must independently answer every Markdown item.
+     *
+     * Positive evidence answers the named item only. Permitted exclusions can
+     * cascade within that host's scope without answering for other hosts.
+     */
+    checklist: boolean;
+    /**
+     * Whether acknowledgements need paired reviews with current fingerprints.
+     *
+     * Reviews match semantic host, resolved target, and acknowledgement kind.
+     * They validate coverage statements but never supply coverage themselves.
+     */
+    requireReview: boolean;
+}

package/lib/structures/IEvidenceGraphPolicy.js

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

package/lib/structures/IEvidenceGraphReference.d.ts

@@ -0,0 +1,95 @@
+import type { EvidenceSeverity } from "../typings/EvidenceSeverity";
+import type { IEvidenceGraphResolution } from "./IEvidenceGraphResolution";
+import type { IEvidenceGraphReviewResolution } from "./IEvidenceGraphReviewResolution";
+import type { IEvidenceInventory } from "./IEvidenceInventory";
+/**
+ * One materialized target population and the policies governing its acknowledgements.
+ *
+ * Target resolutions join claim statements to units in this inventory. Selected
+ * IDs define the denominator, while real ancestors remain usable as aggregate
+ * scopes. Review resolutions remain separate because reviews validate evidence
+ * without contributing coverage.
+ *
+ * Every record is an independent obligation, even when another reference has the
+ * same inventory and selectors. An exclusion can cover a permissive reference
+ * while leaving a repeated, exclusion-forbidding reference missing.
+ */
+export interface IEvidenceGraphReference {
+    /**
+     * Original zero-based reference position within its claim.
+     *
+     * Omission uses the current array position for direct graph input. Explicit
+     * indices preserve attribution after inactive references have been filtered.
+     */
+    index?: number;
+    /**
+     * Effective diagnostic severity for this reference.
+     *
+     * Off skips the obligation. An active severity applies to findings attributed
+     * to its inventory, resolutions, coverage, and policy checks.
+     */
+    severity: EvidenceSeverity;
+    /**
+     * Captured target declarations and their public addresses.
+     *
+     * Evaluation reconciles the inventory before selection. Incomplete extraction
+     * cannot supply a passing denominator even if all written citations resolve.
+     */
+    inventory: IEvidenceInventory;
+    /**
+     * Semantic identities required by this reference's selector.
+     *
+     * Aliases do not duplicate requirements. Structural ancestors can be resolved
+     * as aggregate targets without becoming extra selected identities.
+     */
+    unitIds: string[];
+    /**
+     * Resolution outcomes for applicable acknowledgement statements.
+     *
+     * Each entry identifies a claim declaration and its target state in this
+     * population. The graph checks consistency before accepting a coverage edge.
+     */
+    resolutions: IEvidenceGraphResolution[];
+    /**
+     * Resolution outcomes for applicable review statements.
+     *
+     * Omission supplies no precomputed review resolutions. Review pairing uses
+     * these outcomes independently of acknowledgement resolution and coverage.
+     */
+    reviewResolutions?: IEvidenceGraphReviewResolution[];
+    /**
+     * Whether this obligation refuses exclusion acknowledgements.
+     *
+     * Omission permits eligible exclusions. A refused exclusion produces a finding
+     * and leaves its target needing positive evidence in this reference only.
+     */
+    noEvidenceExclude?: boolean;
+    /**
+     * Whether each selected unit permits at most one positive semantic host.
+     *
+     * Omission imposes no host limit. Repeated tags and overload positions do not
+     * create extra hosts; exclusions do not count as positive ownership.
+     */
+    uniqueEvidence?: boolean;
+    /**
+     * Whether every selected claim host must cite exactly one selected unit.
+     *
+     * Omission leaves cardinality unrestricted. Untagged hosts count as zero, repeated
+     * citations count once per target, and aggregates count each selected descendant.
+     */
+    singleEvidencePerSymbol?: boolean;
+    /**
+     * Whether each selected host must answer every selected Markdown item.
+     *
+     * Omission uses ordinary population coverage. Checklist evidence answers only
+     * the named item, while permitted exclusions retain host-local descendant scope.
+     */
+    checklist?: boolean;
+    /**
+     * Whether accepted acknowledgements need a current matching review.
+     *
+     * Omission leaves review optional. Pairing requires the same semantic host,
+     * target, and kind, followed by a fingerprint match for the cited content scope.
+     */
+    requireReview?: boolean;
+}

package/lib/structures/IEvidenceGraphReference.js

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

package/lib/structures/IEvidenceGraphReport.d.ts

@@ -0,0 +1,84 @@
+import type { EvidenceCheckStatus } from "../typings/EvidenceCheckStatus";
+import type { EvidenceCommandExitCode } from "../typings/EvidenceCommandExitCode";
+import type { EvidenceGraphNode } from "../typings/EvidenceGraphNode";
+import type { IEvidenceDiagnostic } from "./IEvidenceDiagnostic";
+import type { IEvidenceGraphBoundary } from "./IEvidenceGraphBoundary";
+import type { IEvidenceGraphExportEdge } from "./IEvidenceGraphExportEdge";
+import type { IEvidenceGraphExportReview } from "./IEvidenceGraphExportReview";
+/**
+ * Versioned graph export preserving every independent claim/reference obligation.
+ *
+ * Nodes are qualified by boundary and role, so shared semantic identities do not
+ * merge requirements across references. Accepted acknowledgement edges and review
+ * relations remain separate. Report status and diagnostics come from the same
+ * check analysis used to construct the graph.
+ */
+export interface IEvidenceGraphReport {
+    /**
+     * Serialization version for graph consumers.
+     *
+     * Readers check this before interpreting boundary-qualified node and edge IDs.
+     */
+    schemaVersion: 1;
+    /**
+     * Discriminator identifying a configured graph export.
+     *
+     * This report includes relationship records beyond the ordinary check summary.
+     */
+    command: "graph";
+    /**
+     * Configuration file whose planned populations were evaluated.
+     *
+     * Boundary indices refer to authored claims and references in this configuration.
+     */
+    configFile: string;
+    /**
+     * Completeness inherited from the underlying analysis.
+     *
+     * Exporting existing nodes cannot certify populations that failed extraction.
+     */
+    status: EvidenceCheckStatus;
+    /**
+     * Check success inherited from completeness and diagnostic severity.
+     *
+     * A graph can be exported for a failing check so consumers can explain its gaps.
+     */
+    success: boolean;
+    /**
+     * Process outcome retained from the analyzed check.
+     *
+     * Graph serialization does not replace coverage failure with output success.
+     */
+    exitCode: EvidenceCommandExitCode;
+    /**
+     * Independent obligations with their selection, policy, and coverage ledgers.
+     *
+     * Repeated references retain distinct entries even when they select identical units.
+     */
+    boundaries: IEvidenceGraphBoundary[];
+    /**
+     * Semantic-unit and standalone-carrier nodes ordered by export identity.
+     *
+     * IDs include the obligation boundary so one unit can appear in several contexts.
+     */
+    nodes: EvidenceGraphNode[];
+    /**
+     * Accepted acknowledgement relationships ordered by edge identity.
+     *
+     * Each edge identifies its carrier-side nodes, exact target, and selected coverage.
+     */
+    edges: IEvidenceGraphExportEdge[];
+    /**
+     * Review relationships retained separately from coverage edges.
+     *
+     * Resolution status can expose unresolved or ambiguous reviews without treating
+     * them as accepted acknowledgements.
+     */
+    reviews: IEvidenceGraphExportReview[];
+    /**
+     * Findings from the full check analysis in deterministic report order.
+     *
+     * These explain completeness, policy, and coverage failures visible in the graph.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+}

package/lib/structures/IEvidenceGraphReport.js

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

package/lib/structures/IEvidenceGraphResolution.d.ts

@@ -0,0 +1,22 @@
+import type { IEvidenceTargetResolution } from "./IEvidenceTargetResolution";
+/**
+ * Prepared target resolution for an acknowledgement in one reference inventory.
+ *
+ * Resolution is retained separately from accepted edges because an invalid,
+ * missing, or ambiguous target must still produce a diagnostic. The same source
+ * declaration can resolve differently across independent reference boundaries.
+ */
+export interface IEvidenceGraphResolution {
+    /**
+     * Identity of the acknowledgement whose target was resolved.
+     *
+     * The evaluator uses it to find the prepared result for that source statement.
+     */
+    declarationId: string;
+    /**
+     * Successful or failed resolution within the current reference boundary.
+     *
+     * Failure details remain available even when no accepted edge can be created.
+     */
+    resolution: IEvidenceTargetResolution;
+}

package/lib/structures/IEvidenceGraphResolution.js

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

package/lib/structures/IEvidenceGraphResult.d.ts

@@ -0,0 +1,37 @@
+import type { IEvidenceDiagnostic } from "./IEvidenceDiagnostic";
+import type { IEvidenceGraphClaimResult } from "./IEvidenceGraphClaimResult";
+/**
+ * Serializable outcome of one materialized graph evaluation.
+ *
+ * Claims retain their independent reference ledgers, while diagnostics collect
+ * the findings needed to explain failures across the graph. The result contains
+ * policy evaluation data; command status, severity aggregation, and rendering
+ * are supplied by later reporting layers.
+ *
+ * A result succeeds only when every active boundary is complete and no findings
+ * remain. Merely obtaining an empty missing-unit list from partial input does not
+ * establish success.
+ */
+export interface IEvidenceGraphResult {
+    /**
+     * Whether all active evaluation boundaries are complete and finding-free.
+     *
+     * Inactive claims do not make the graph incomplete. Any retained diagnostic or
+     * active incomplete obligation prevents this flag from becoming true.
+     */
+    success: boolean;
+    /**
+     * Per-claim outcomes with their independent reference obligations.
+     *
+     * The original claim indices remain in each record for attribution. Repeated
+     * references are preserved rather than merged into one aggregate coverage set.
+     */
+    claims: IEvidenceGraphClaimResult[];
+    /**
+     * Deduplicated findings from extraction integrity and policy evaluation.
+     *
+     * Finalization includes findings that depend on cross-reference participation.
+     * Consumers can render them without rerunning the graph traversal.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+}

package/lib/structures/IEvidenceGraphResult.js

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

package/lib/structures/IEvidenceGraphReviewResolution.d.ts

@@ -0,0 +1,23 @@
+import type { IEvidenceTargetResolution } from "./IEvidenceTargetResolution";
+/**
+ * Prepared reference-target resolution for a review statement.
+ *
+ * Reviews resolve through the same target grammar as acknowledgements but remain
+ * separate records: matching a review validates a paired citation and never
+ * creates coverage by itself. Failed resolution is retained for diagnostics.
+ */
+export interface IEvidenceGraphReviewResolution {
+    /**
+     * Identity of the review whose target was resolved.
+     *
+     * This keeps reviews distinguishable when several statements name one target.
+     */
+    reviewId: string;
+    /**
+     * Resolution outcome in the relevant reference inventory.
+     *
+     * A successful target still requires acknowledgement pairing and fingerprint
+     * validation before the review can satisfy review policy.
+     */
+    resolution: IEvidenceTargetResolution;
+}

package/lib/structures/IEvidenceGraphReviewResolution.js

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

package/lib/structures/IEvidenceHelpCommand.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parsed request to display command syntax and options.
+ *
+ * Help is resolved before configuration or project analysis. The parser refuses
+ * combining the help flag with other options instead of silently ignoring them.
+ */
+export interface IEvidenceHelpCommand {
+    /**
+     * Discriminator selecting the built-in help text.
+     *
+     * No filesystem or configuration context is needed to render this request.
+     */
+    operation: "help";
+}

package/lib/structures/IEvidenceHelpCommand.js

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

package/lib/structures/IEvidenceHost.d.ts

@@ -0,0 +1,78 @@
+import type { IEvidenceSourceRange } from "./IEvidenceSourceRange";
+/**
+ * A physical documentation carrier and the declarations that own its statements.
+ *
+ * Adapters establish attachment from language syntax before evidence tags are
+ * parsed. This record supplies the source location and semantic owners used to
+ * decide whether an acknowledgement belongs to a selected claim host. A nearby
+ * comment cannot acquire ownership merely by containing a recognized tag.
+ *
+ * Physical and semantic ownership need not be one-to-one:
+ *
+ * - A multi-variable statement can give one position several unit IDs.
+ * - Overload declarations can give one semantic host several physical positions.
+ * - An artifact's exclusion-only carrier can be attached without owning a unit.
+ *
+ * Unattached and unsupported carriers remain available for diagnostics. Graph
+ * cardinality counts the owning semantic identities, not the number of comments.
+ */
+export interface IEvidenceHost {
+    /**
+     * Identity of the physical documentation carrier.
+     *
+     * Parsed statements refer to this ID. It must remain distinct from semantic
+     * unit IDs because several carriers can belong to one merged declaration.
+     */
+    id: string;
+    /**
+     * Source file containing the carrier.
+     *
+     * This anchors diagnostics and supplies the default origin for relative
+     * citations when the host does not record explicit `origins`.
+     */
+    file: string;
+    /**
+     * Span of the documentation position in the captured source.
+     *
+     * Coordinates use the original UTF-16 text and an exclusive end. The carrier
+     * span is separate from its owner's declaration and fingerprint content ranges.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Source paths from which relative citations may resolve.
+     *
+     * Omission uses `file`. Reconciliation preserves every origin when equivalent
+     * carriers merge, so choosing one alias does not discard another valid base path.
+     */
+    origins?: string[];
+    /**
+     * Physical declaration site establishing the carrier's semantic ownership.
+     *
+     * An exclusion-only carrier can omit this link. For a semantic host, inventory
+     * validation requires the site to belong to its claimed unit owners.
+     */
+    siteId?: string;
+    /**
+     * Semantic declarations owning this documentation position.
+     *
+     * Retain all owners of shared declaration positions. Empty ownership is allowed
+     * only where the artifact's carrier rules permit evidence without a declaration,
+     * such as an eligible exclusion-only position.
+     */
+    unitIds: string[];
+    /**
+     * Result of the adapter's syntactic attachment analysis.
+     *
+     * Attached carriers participate under the artifact's rules, including allowed
+     * exclusion-only carriers with no unit IDs. Unattached or unsupported positions
+     * retain their status so their annotations can produce actionable findings.
+     */
+    attachment: "attached" | "unattached" | "unsupported";
+    /**
+     * Adapter explanation for an unsupported documentation position.
+     *
+     * Supply the source construct or ownership limitation that prevents this
+     * carrier from participating. Ordinary supported positions omit the explanation.
+     */
+    problem?: string;
+}

package/lib/structures/IEvidenceHost.js

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

package/lib/structures/IEvidenceInitCommand.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Parsed request to create a starter Evidence configuration.
+ *
+ * Execution resolves the destination from command cwd and creates it exclusively.
+ * Existing files are refused so initialization cannot overwrite an authored policy.
+ */
+export interface IEvidenceInitCommand {
+    /**
+     * Discriminator selecting configuration creation.
+     *
+     * Initialization writes a starter contract without running an Evidence check.
+     */
+    operation: "init";
+    /**
+     * Working directory anchoring the configuration destination.
+     *
+     * The command resolves this against its invocation base without changing process cwd.
+     */
+    cwd: string;
+    /**
+     * New configuration path, defaulting to evidence.config.ts during parsing.
+     *
+     * Execution validates the supported file format and rejects an existing destination.
+     */
+    config: string;
+}

package/lib/structures/IEvidenceInitCommand.js

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

package/lib/structures/IEvidenceInspectCommand.d.ts

@@ -0,0 +1,46 @@
+import type { EvidenceReportFormat } from "../typings/EvidenceReportFormat";
+/**
+ * Parsed request to resolve one target and explain its graph context.
+ *
+ * Inspection analyzes the configured populations before collecting candidates,
+ * related obligations, acknowledgements, and reviews. Target spelling follows the
+ * applicable artifact grammar, with file-qualified paths based on the command cwd.
+ */
+export interface IEvidenceInspectCommand {
+    /**
+     * Discriminator selecting detailed target inspection.
+     *
+     * Parsing requires exactly one positional target for this operation.
+     */
+    operation: "inspect";
+    /**
+     * Authored target token to resolve in applicable populations.
+     *
+     * Resolution preserves this spelling in the report alongside normalized addresses.
+     */
+    target: string;
+    /**
+     * Working directory resolved from the invocation base.
+     *
+     * File-qualified query targets use this anchor rather than a source comment's origin.
+     */
+    cwd: string;
+    /**
+     * Configuration path interpreted within the command directory.
+     *
+     * Parsing defaults to evidence.config.ts when no override is supplied.
+     */
+    config: string;
+    /**
+     * Text or JSON representation requested for inspection details.
+     *
+     * Both formats preserve the combined check and resolution outcome.
+     */
+    format: EvidenceReportFormat;
+    /**
+     * Optional report destination resolved from the command directory.
+     *
+     * Omission leaves the formatted report in standard output.
+     */
+    output?: string;
+}

package/lib/structures/IEvidenceInspectCommand.js

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

package/lib/structures/IEvidenceInspectReport.d.ts

@@ -0,0 +1,70 @@
+import type { EvidenceCheckStatus } from "../typings/EvidenceCheckStatus";
+import type { EvidenceCommandExitCode } from "../typings/EvidenceCommandExitCode";
+import type { IEvidenceDiagnostic } from "./IEvidenceDiagnostic";
+import type { IEvidenceInspection } from "./IEvidenceInspection";
+/**
+ * Versioned target-resolution report across applicable configured populations.
+ *
+ * Each inspection retains its own scope because identical target spellings can
+ * occur in independent references. Success requires every inspected boundary to
+ * resolve and the underlying analysis to pass; unavailable analysis takes
+ * precedence over ordinary target-resolution failures.
+ */
+export interface IEvidenceInspectReport {
+    /**
+     * Serialization version of the inspection report.
+     *
+     * Consumers inspect this before interpreting population-specific detail records.
+     */
+    schemaVersion: 1;
+    /**
+     * Discriminator identifying target-inspection output.
+     *
+     * The report expands one requested target rather than listing all discoverable units.
+     */
+    command: "inspect";
+    /**
+     * Configuration path anchoring the analyzed populations.
+     *
+     * Scope indices and inherited diagnostics refer to this check configuration.
+     */
+    configFile: string;
+    /**
+     * Combined completeness of the original check and target resolutions.
+     *
+     * Any incomplete inspection makes the report incomplete even if other boundaries resolve.
+     */
+    status: EvidenceCheckStatus;
+    /**
+     * Whether all inspected targets resolve and the combined outcome passes.
+     *
+     * An empty inspection set cannot establish success, nor can successful resolution
+     * hide an error from the underlying check.
+     */
+    success: boolean;
+    /**
+     * Outcome prioritizing incomplete analysis over unresolved targets.
+     *
+     * Incomplete analysis returns two, unresolved complete inspection returns one,
+     * and fully resolved inspection inherits the check's outcome.
+     */
+    exitCode: EvidenceCommandExitCode;
+    /**
+     * Exact authored target supplied to the query.
+     *
+     * Population entries retain their normalized address candidates separately.
+     */
+    target: string;
+    /**
+     * Resolution and graph context for each applicable population boundary.
+     *
+     * Entries are ordered by scope identity so asynchronous resolution stays deterministic.
+     */
+    inspections: IEvidenceInspection[];
+    /**
+     * Deduplicated findings from the check and the individual target inspections.
+     *
+     * These explain both global analysis failures and target-specific resolution problems.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+}

package/lib/structures/IEvidenceInspectReport.js

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

package/lib/structures/IEvidenceInspectedAcknowledgement.d.ts

@@ -0,0 +1,60 @@
+import type { IEvidenceDeclaration } from "./IEvidenceDeclaration";
+import type { IEvidenceHost } from "./IEvidenceHost";
+/**
+ * Accepted incoming acknowledgement relevant to an inspected reference identity.
+ *
+ * A statement is included when its exact target or covered selected units match
+ * the inspected candidate. The record retains both authored source context and
+ * evaluated scope, making aggregate citations explainable without flattening
+ * independent reference obligations.
+ */
+export interface IEvidenceInspectedAcknowledgement {
+    /**
+     * Authored index of the claim supplying the acknowledgement.
+     *
+     * Together with reference, this identifies the boundary that accepted the edge.
+     */
+    claim: number;
+    /**
+     * Authored reference index under the owning claim.
+     *
+     * Acceptance here does not imply acceptance under another reference's policy.
+     */
+    reference: number;
+    /**
+     * Extracted acknowledgement statement with target, reason, and source location.
+     *
+     * This preserves author intent alongside the evaluated target and coverage IDs.
+     */
+    declaration: IEvidenceDeclaration;
+    /**
+     * Documentation carrier owning the accepted statement.
+     *
+     * Its physical location and origins explain where the target was authored and resolved.
+     */
+    host: IEvidenceHost;
+    /**
+     * Selected semantic claim subjects represented by the carrier for this edge.
+     *
+     * Checklist answers are attributed to these subjects independently.
+     */
+    hostUnitIds: string[];
+    /**
+     * Exact semantic target named by the acknowledgement.
+     *
+     * An aggregate target can be an ancestor of the inspected selected identity.
+     */
+    targetUnitId: string;
+    /**
+     * Selected reference identities receiving coverage from the accepted scope.
+     *
+     * The collection can differ from the exact target when aggregate acknowledgement applies.
+     */
+    unitIds: string[];
+    /**
+     * Current fingerprint of the exact cited scope.
+     *
+     * Review validation concerns that scope rather than only the inspected descendant.
+     */
+    fingerprint: string;
+}

package/lib/structures/IEvidenceInspectedAcknowledgement.js

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