@wrtnlabs/evidence 0.0.0

package/lib/structures/IEvidenceCheckCounts.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Aggregate participation and coverage totals for a check report.
+ *
+ * Unit counts sum active obligations rather than deduplicating across the whole
+ * graph. Two references to the same population therefore retain two requirements.
+ * Diagnostic totals include every reported finding at the corresponding severity.
+ */
+export interface IEvidenceCheckCounts {
+    /**
+     * Number of claim results retained by the plan.
+     *
+     * Disabled authored entries removed before evaluation are not included.
+     */
+    claims: number;
+    /**
+     * Number of retained claims activated during evaluation.
+     *
+     * This is the numerator displayed beside the total claim count.
+     */
+    activeClaims: number;
+    /**
+     * Number of reference results across retained claims.
+     *
+     * Repeated reference entries count separately even when their populations match.
+     */
+    obligations: number;
+    /**
+     * Number of obligations participating in coverage totals.
+     *
+     * Inactive obligations remain in the total count but do not contribute units.
+     */
+    activeObligations: number;
+    /**
+     * Number of active obligations whose analysis could not complete.
+     *
+     * This exposes incomplete extraction separately from ordinary missing evidence.
+     */
+    incompleteObligations: number;
+    /**
+     * Sum of selected reference-unit counts in active obligations.
+     *
+     * The same semantic identity can contribute to several independent requirements.
+     */
+    units: number;
+    /**
+     * Sum of covered-unit counts in active obligations.
+     *
+     * Coverage accepted in one obligation does not satisfy another automatically.
+     */
+    coveredUnits: number;
+    /**
+     * Sum of uncovered-unit counts in active obligations.
+     *
+     * This reports missing requirements within the materialized populations;
+     * completeness still determines whether those populations are trustworthy.
+     */
+    missingUnits: number;
+    /**
+     * Number of error diagnostics in the report.
+     *
+     * Any error makes a complete check fail with exit code one.
+     */
+    errors: number;
+    /**
+     * Number of warning diagnostics in the report.
+     *
+     * Warnings remain visible without making an otherwise complete check fail.
+     */
+    warnings: number;
+}

package/lib/structures/IEvidenceCheckCounts.js

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

package/lib/structures/IEvidenceCheckObligation.d.ts

@@ -0,0 +1,67 @@
+import type { EvidenceActiveSeverity } from "../typings/EvidenceActiveSeverity";
+import type { EvidenceArtifactType } from "../typings/EvidenceArtifactType";
+/**
+ * Compact coverage result for one claim/reference boundary.
+ *
+ * This projects a graph obligation into counts for command output. It retains
+ * activation and completeness because a zero-sized result is not proof that
+ * extraction succeeded, and severity determines whether findings fail the check.
+ */
+export interface IEvidenceCheckObligation {
+    /**
+     * Authored index of the claim that owes this evidence.
+     *
+     * Combined with the reference index, it identifies the diagnostic boundary.
+     */
+    claim: number;
+    /**
+     * Authored reference index within the claim.
+     *
+     * Identical populations at different indices impose separate obligations.
+     */
+    reference: number;
+    /**
+     * Artifact family on the required reference side.
+     *
+     * This can differ from the claim family, such as code cited from Markdown.
+     */
+    type: EvidenceArtifactType;
+    /**
+     * Effective severity after configuration inheritance.
+     *
+     * Off references are removed during planning; remaining findings are warnings
+     * or errors according to this policy.
+     */
+    severity: EvidenceActiveSeverity;
+    /**
+     * Whether this obligation participates in aggregate coverage.
+     *
+     * Inactive entries retain their result shape but are excluded from totals.
+     */
+    active: boolean;
+    /**
+     * Whether analysis could establish the obligation's full population.
+     *
+     * An incomplete active obligation causes exit code two regardless of its counts.
+     */
+    complete: boolean;
+    /**
+     * Number of selected semantic reference units.
+     *
+     * Aliases do not enlarge this denominator; another reference counts its own
+     * selection independently.
+     */
+    units: number;
+    /**
+     * Number of selected units acknowledged under this reference's policy.
+     *
+     * Repeated citations to one identity do not add another covered unit.
+     */
+    coveredUnits: number;
+    /**
+     * Number of selected units still lacking required evidence.
+     *
+     * Read this together with completeness before treating the result as exhaustive.
+     */
+    missingUnits: number;
+}

package/lib/structures/IEvidenceCheckObligation.js

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

package/lib/structures/IEvidenceCheckReport.d.ts

@@ -0,0 +1,74 @@
+import type { EvidenceCheckStatus } from "../typings/EvidenceCheckStatus";
+import type { EvidenceCommandExitCode } from "../typings/EvidenceCommandExitCode";
+import type { IEvidenceCheckClaim } from "./IEvidenceCheckClaim";
+import type { IEvidenceCheckCounts } from "./IEvidenceCheckCounts";
+import type { IEvidenceDiagnostic } from "./IEvidenceDiagnostic";
+/**
+ * Versioned coverage report shared by the checker and its output renderers.
+ *
+ * Completion describes whether the selected populations could be analyzed;
+ * success additionally requires no error diagnostics. A complete report can
+ * therefore fail coverage, while warning-only findings can still pass. Claims
+ * retain configuration indices so consumers can attribute each independent
+ * obligation without relying on an optional display name.
+ */
+export interface IEvidenceCheckReport {
+    /**
+     * Serialization contract understood by report consumers.
+     *
+     * Readers can check this discriminator before interpreting counts or claims.
+     */
+    schemaVersion: 1;
+    /**
+     * Operation that produced this report.
+     *
+     * This distinguishes check output from query reports and operational failures.
+     */
+    command: "check";
+    /**
+     * Configuration file resolved for this evaluation.
+     *
+     * The path provides context for claim indices and is retained in text output.
+     */
+    configFile: string;
+    /**
+     * Whether all active claims and obligations were analyzed completely.
+     *
+     * A complete analysis can still report missing evidence and return failure.
+     */
+    status: EvidenceCheckStatus;
+    /**
+     * Whether the complete analysis contains no error diagnostics.
+     *
+     * Warnings alone do not fail the check; incomplete analysis always does.
+     */
+    success: boolean;
+    /**
+     * Process outcome corresponding to completeness and error severity.
+     *
+     * Zero passes, one means a complete check found errors, and two means the
+     * analysis was incomplete.
+     */
+    exitCode: EvidenceCommandExitCode;
+    /**
+     * Aggregate participation, coverage, and diagnostic counts.
+     *
+     * Coverage totals sum active obligations, so a unit required by two references
+     * contributes once to each obligation rather than once to the whole report.
+     */
+    counts: IEvidenceCheckCounts;
+    /**
+     * Evaluated claims with their independent reference results.
+     *
+     * Entries carry authored indices even when configuration planning removed
+     * disabled entries before evaluation.
+     */
+    claims: IEvidenceCheckClaim[];
+    /**
+     * Findings sorted by configuration, source, and diagnostic coordinates.
+     *
+     * Both output formats consume this order so asynchronous extraction does not
+     * reorder otherwise equivalent reports.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+}

package/lib/structures/IEvidenceCheckReport.js

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

package/lib/structures/IEvidenceClaim.d.ts

@@ -0,0 +1,12 @@
+import type { IEvidenceDatabaseClaim } from "./IEvidenceDatabaseClaim";
+import type { IEvidenceMarkdownClaim } from "./IEvidenceMarkdownClaim";
+import type { IEvidenceProgrammingClaim } from "./IEvidenceProgrammingClaim";
+import type { IEvidenceSwaggerClaim } from "./IEvidenceSwaggerClaim";
+/**
+ * Artifact-specific populations that owe evidence to configured references.
+ *
+ * The type discriminator chooses extraction and host rules for code, schemas,
+ * Markdown, or API operations. Each claim retains its own policy and reference
+ * boundaries even when another claim selects the same physical files.
+ */
+export type IEvidenceClaim = IEvidenceDatabaseClaim | IEvidenceMarkdownClaim | IEvidenceProgrammingClaim | IEvidenceSwaggerClaim;

package/lib/structures/IEvidenceClaim.js

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

package/lib/structures/IEvidenceClaimBase.d.ts

@@ -0,0 +1,111 @@
+import type { EvidenceSeverity } from "../typings/EvidenceSeverity";
+import type { IEvidenceReference } from "./IEvidenceReference";
+/**
+ * Shared selection rules for declarations that carry a claim's evidence.
+ *
+ * A claim selects files and symbol kinds whose public declarations may host
+ * acknowledgements. Its references independently select the target units those
+ * hosts must answer. A host remains selected even without a tag, allowing
+ * checklist and cardinality policies to detect an unanswered declaration.
+ *
+ * Configuration planning resolves inherited severity and artifact defaults,
+ * validates disabled declarations, and omits inactive populations from loading
+ * and watch. The generic parameters restrict each artifact's discriminator and
+ * supported selector vocabulary without adding a separate language option.
+ *
+ * @example
+ * const claim: IEvidenceClaimBase<"typescript", "function"> = {
+ *   type: "typescript",
+ *   files: ["src/*.ts"],
+ *   symbol: "function",
+ *   reference: [
+ *     { type: "markdown", files: ["requirements.md"] },
+ *     { type: "swagger", file: "openapi.json" },
+ *   ],
+ * };
+ * // Both reference populations require independent coverage.
+ */
+export interface IEvidenceClaimBase<Type extends string, SymbolKind extends string> {
+    /**
+     * Artifact discriminator selecting the claim's extraction rules.
+     *
+     * This determines which adapter interprets public declarations and eligible
+     * documentation. References can independently select another artifact family.
+     */
+    type: Type;
+    /**
+     * Optional label identifying the claim in diagnostics.
+     *
+     * Names do not establish semantic identity or combine obligations. Two claims
+     * with the same label still require independent coverage.
+     */
+    name?: string;
+    /**
+     * Overrides the root configuration's diagnostic severity.
+     *
+     * Omit or use `undefined` to inherit. `"off"` disables this claim and its
+     * references after configuration validation, avoiding their source loading.
+     */
+    severity?: EvidenceSeverity | undefined;
+    /**
+     * Disables the claim without removing its authored configuration.
+     *
+     * Skip its populations, references, coverage obligations, and watched inputs.
+     * Its shape is still validated so reenabling it cannot reveal ignored malformed
+     * settings that were accepted only because the claim was inactive.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Base directory for file globs.
+     *
+     * - Defaults to the directory containing evidence.config.ts; relative roots
+     *   resolve from that directory.
+     * - Accepts absolute paths, directory symlinks, and Windows junctions.
+     * - Names one directory, not a glob. Windows drive-relative paths are invalid.
+     */
+    root?: string;
+    /**
+     * File globs relative to root.
+     *
+     * - Evaluate left to right: "!" removes matches; later positives may re-include.
+     *   At least one positive pattern is required.
+     * - "*" matches within one path segment, "**" crosses segments, and "?" matches
+     *   one character. Both path separators are accepted; identity is case-sensitive.
+     * - A bare directory does not include its children; use "src/**".
+     * - Resolved patterns define watched inputs, including files outside the project.
+     */
+    files: string[];
+    /**
+     * Symbol kinds eligible to host evidence; accepts one kind or a nonempty array.
+     *
+     * Omit to select every supported kind for the artifact:
+     *
+     * - Programming: the language's supported type, function, and property kinds.
+     * - Database: model, column, relation.
+     * - Markdown: file, h1, h2, h3, h4.
+     * - Swagger: operation.
+     *
+     * This selects claim hosts; each reference selects the units they must cover.
+     */
+    symbol?: SymbolKind | SymbolKind[];
+    /**
+     * Globs restricting exclusion carriers within the claim's selected files.
+     *
+     * - Use the same root and glob rules as files; never widen that population.
+     * - Omit to allow every eligible carrier. An exclusion outside these globs is
+     *   reported and provides no coverage.
+     * - Each reference may independently refuse all exclusions with noEvidenceExclude.
+     * - A Markdown checklist permits these globs only with noEvidenceExclude.
+     */
+    evidenceExcludeCarriers?: string[];
+    /**
+     * One reference or a nonempty array of independent evidence requirements.
+     *
+     * Every claim may reference any artifact family. Each reference requires complete
+     * coverage independently, including repeated entries selecting the same files.
+     * An acknowledgement accepted under one policy does not bypass another policy.
+     */
+    reference: IEvidenceReference | IEvidenceReference[];
+}

package/lib/structures/IEvidenceClaimBase.js

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

package/lib/structures/IEvidenceCommand.d.ts

@@ -0,0 +1,16 @@
+import type { IEvidenceCheckCommand } from "./IEvidenceCheckCommand";
+import type { IEvidenceGraphCommand } from "./IEvidenceGraphCommand";
+import type { IEvidenceHelpCommand } from "./IEvidenceHelpCommand";
+import type { IEvidenceInspectCommand } from "./IEvidenceInspectCommand";
+import type { IEvidenceInitCommand } from "./IEvidenceInitCommand";
+import type { IEvidenceLanguagesCommand } from "./IEvidenceLanguagesCommand";
+import type { IEvidenceListCommand } from "./IEvidenceListCommand";
+import type { IEvidenceVersionCommand } from "./IEvidenceVersionCommand";
+/**
+ * Validated operation selected from the complete CLI argument list.
+ *
+ * Parsing rejects unknown, repeated, or incompatible options before producing
+ * this discriminated union. Execution dispatches on operation without reinterpreting
+ * raw tokens or allowing trailing input to escape validation.
+ */
+export type IEvidenceCommand = IEvidenceCheckCommand | IEvidenceGraphCommand | IEvidenceHelpCommand | IEvidenceInspectCommand | IEvidenceInitCommand | IEvidenceLanguagesCommand | IEvidenceListCommand | IEvidenceVersionCommand;

package/lib/structures/IEvidenceCommand.js

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

package/lib/structures/IEvidenceCommandFailure.d.ts

@@ -0,0 +1,58 @@
+/**
+ * JSON envelope for a command that could not produce its normal report.
+ *
+ * Configuration loading, dependency, and execution failures use this shape so
+ * machine consumers still receive structured output. It is distinct from a
+ * completed check whose ordinary report contains coverage errors.
+ */
+export interface IEvidenceCommandFailure {
+    /**
+     * Version of the failure envelope's serialization contract.
+     *
+     * Consumers should inspect it before interpreting the remaining fields.
+     */
+    schemaVersion: 1;
+    /**
+     * Requested analysis operation that failed.
+     *
+     * This retains the command identity even though its normal report is unavailable.
+     */
+    command: "check" | "graph" | "inspect" | "list";
+    /**
+     * Discriminator identifying an operational failure.
+     *
+     * The normal check report instead describes analysis as complete or incomplete.
+     */
+    status: "failed";
+    /**
+     * Failed outcome exposed to consumers that inspect a common success field.
+     *
+     * No operational failure can certify coverage or a successful query.
+     */
+    success: false;
+    /**
+     * Process status reserved for unavailable or incomplete analysis.
+     *
+     * Exit code one is reserved for a completed check containing error findings.
+     */
+    exitCode: 2;
+    /**
+     * Resolved configuration path associated with the attempted command.
+     *
+     * It remains available when loading that file was itself the failing operation.
+     */
+    configFile: string;
+    /**
+     * Explanation derived from the caught operational error.
+     *
+     * This describes why the command could not produce its requested report.
+     */
+    message: string;
+    /**
+     * Guidance for correcting the failure and rerunning the command.
+     *
+     * Recovery requires a complete new analysis rather than treating partial work
+     * from the failed command as a successful result.
+     */
+    repair: string;
+}

package/lib/structures/IEvidenceCommandFailure.js

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

package/lib/structures/IEvidenceCommandResult.d.ts

@@ -0,0 +1,31 @@
+import type { EvidenceCommandExitCode } from "../typings/EvidenceCommandExitCode";
+/**
+ * Buffered output and process status returned by command execution.
+ *
+ * The CLI boundary writes these strings to their respective streams. Keeping
+ * execution separate from process I/O also lets callers inspect command behavior
+ * without replacing global streams or spawning another process.
+ */
+export interface IEvidenceCommandResult {
+    /**
+     * Outcome to propagate to the invoking process.
+     *
+     * Zero succeeds, one reports completed check errors, and two reports an
+     * operational failure or incomplete analysis.
+     */
+    exitCode: EvidenceCommandExitCode;
+    /**
+     * Content prepared for the standard output stream.
+     *
+     * The string already includes its intended formatting and line endings; it may
+     * be empty when output was written to a requested file.
+     */
+    stdout: string;
+    /**
+     * Content prepared for the standard error stream.
+     *
+     * Human-readable operational failures use this channel, while requested JSON
+     * failures remain structured command output.
+     */
+    stderr: string;
+}

package/lib/structures/IEvidenceCommandResult.js

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

package/lib/structures/IEvidenceCommentSyntax.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Comment-normalization rules supplied by an artifact adapter.
+ *
+ * The adapter must first establish that a source span is a documentation comment
+ * and determine its host. EvidenceDocumentation uses these rules to remove known
+ * syntax while preserving source mappings; it does not discover comments itself.
+ */
+export interface IEvidenceCommentSyntax {
+    /**
+     * Exact opening delimiter expected at the supplied source span's start.
+     *
+     * A mismatch rejects the span instead of stripping unrelated source characters.
+     */
+    opening: string;
+    /**
+     * Exact closing delimiter expected at the source span's end.
+     *
+     * An empty delimiter supports forms whose adapter already bounded the comment
+     * without a closing token.
+     */
+    closing: string;
+    /**
+     * Optional decoration removed after horizontal whitespace at each line start.
+     *
+     * Lines lacking the prefix keep their original leading text. Omission disables
+     * this removal while retaining delimiter normalization.
+     */
+    linePrefix?: string;
+    /**
+     * Whether unrelated line-start tags end the current annotation's reason.
+     *
+     * Enable this for JSDoc-like carriers where other tools' tags share the comment.
+     */
+    tagBoundaries: boolean;
+    /**
+     * Whether withdrawal annotations have a supported declaration owner here.
+     *
+     * The adapter determines eligibility from attachment; normalization must not
+     * infer public API ownership from the presence of tag text alone.
+     */
+    allowWithdrawal: boolean;
+}

package/lib/structures/IEvidenceCommentSyntax.js

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

package/lib/structures/IEvidenceConfig.d.ts

@@ -0,0 +1,42 @@
+import type { EvidenceSeverity } from "../typings/EvidenceSeverity";
+import type { IEvidenceClaim } from "./IEvidenceClaim";
+/**
+ * Configuration declaring the project's claims and required evidence populations.
+ *
+ * Each claim selects declarations that may carry evidence and references the
+ * populations they must acknowledge. Artifact families can differ across that
+ * boundary: TypeScript implementation may answer Markdown requirements, while
+ * another claim requires tests to acknowledge the implementation.
+ *
+ * The loader validates all declarations, resolves severity and selector defaults,
+ * then removes inactive populations from the execution plan. Relative roots are
+ * anchored to the configuration file. Repeated references remain independent
+ * obligations even when they select identical files.
+ *
+ * @example
+ * const config: IEvidenceConfig = {
+ *   claims: [{
+ *     type: "typescript",
+ *     files: ["src/*.ts"],
+ *     reference: { type: "markdown", files: ["requirements.md"], symbol: "h2" },
+ *   }],
+ * };
+ */
+export interface IEvidenceConfig {
+    /**
+     * Root diagnostic severity inherited by claims and their references.
+     *
+     * Omission uses error severity. A claim or reference can override its inherited
+     * value; off populations are validated but omitted from materialization.
+     *
+     * @default error
+     */
+    severity?: EvidenceSeverity | undefined;
+    /**
+     * Claim selections and the evidence each must acknowledge.
+     *
+     * At least one claim is required. Each reference inside each claim creates an
+     * independent obligation; shared names or files never pool their coverage.
+     */
+    claims: IEvidenceClaim[];
+}

package/lib/structures/IEvidenceConfig.js

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

package/lib/structures/IEvidenceConfigPlan.d.ts

@@ -0,0 +1,29 @@
+import type { IEvidenceConfigPlanClaim } from "./IEvidenceConfigPlanClaim";
+/**
+ * Validated configuration prepared for source materialization.
+ *
+ * `EvidenceConfigLoader.plan` resolves inherited severity and default symbol
+ * selectors and retains enabled claims and references. The checker consumes
+ * this plan to load sources; it has not yet extracted declarations or evaluated
+ * coverage. Authored indices survive filtering for accurate diagnostics.
+ *
+ * A plan may contain no enabled claims even though the original configuration
+ * required a nonempty claim array. Disabled or off declarations are validated
+ * before that filtering takes place.
+ */
+export interface IEvidenceConfigPlan {
+    /**
+     * Canonical configuration path anchoring relative population roots.
+     *
+     * Materialization uses its directory instead of the current working directory,
+     * keeping programmatic evaluation consistent with configuration loading.
+     */
+    configFile: string;
+    /**
+     * Enabled claims with effective policy and selectors.
+     *
+     * Entries retain their original configuration indices. Filtering inactive claims
+     * does not renumber later diagnostics or merge overlapping populations.
+     */
+    claims: IEvidenceConfigPlanClaim[];
+}

package/lib/structures/IEvidenceConfigPlan.js

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

package/lib/structures/IEvidenceConfigPlanClaim.d.ts

@@ -0,0 +1,49 @@
+import type { EvidenceActiveSeverity } from "../typings/EvidenceActiveSeverity";
+import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
+import type { IEvidenceClaim } from "./IEvidenceClaim";
+import type { IEvidenceConfigPlanReference } from "./IEvidenceConfigPlanReference";
+/**
+ * One enabled claim with resolved host selectors and reference policies.
+ *
+ * Planning preserves the authored population for paths and artifact-specific
+ * settings while recording effective severity and symbol choices separately.
+ * Materialization can therefore select hosts without repeating configuration
+ * inheritance or losing the original declaration used in diagnostics.
+ */
+export interface IEvidenceConfigPlanClaim {
+    /**
+     * Zero-based position in the authored claim array.
+     *
+     * This survives inactive-claim filtering so a finding still identifies the
+     * declaration the user wrote rather than its position in the filtered plan.
+     */
+    index: number;
+    /**
+     * Validated claim retaining authored paths and optional settings.
+     *
+     * Effective severity and selector defaults are stored separately. Keeping this
+     * declaration intact avoids replacing user intent with normalized defaults.
+     */
+    population: IEvidenceClaim;
+    /**
+     * Effective diagnostic severity after claim inheritance.
+     *
+     * This is always active because off claims have already been filtered. It
+     * becomes the inherited default for this claim's reference plans.
+     */
+    severity: EvidenceActiveSeverity;
+    /**
+     * Explicit or default symbol kinds eligible to host this claim's evidence.
+     *
+     * These are host selectors. Each reference has its own selector list for the
+     * target units that those hosts must acknowledge.
+     */
+    symbols: EvidenceSymbol[];
+    /**
+     * Enabled references that independently require evidence from this claim.
+     *
+     * Each retains its authored index and effective settings. Identical selections
+     * remain separate obligations and may apply different exclusion or review rules.
+     */
+    references: IEvidenceConfigPlanReference[];
+}

package/lib/structures/IEvidenceConfigPlanClaim.js

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