@wrtnlabs/evidence 0.0.0

package/lib/structures/IEvidenceSupportedLanguage.d.ts

@@ -0,0 +1,36 @@
+import type { EvidenceProgrammingType } from "../typings/EvidenceProgrammingType";
+import type { IEvidenceLanguageAdapter } from "./IEvidenceLanguageAdapter";
+import type { IEvidenceLanguageGrammar } from "./IEvidenceLanguageGrammar";
+/**
+ * Programming capability entry with a certified adapter guaranteed present.
+ *
+ * Supported-language queries narrow the broader grammar catalog to entries that
+ * can extract Evidence inventories. Consumers can inspect adapter boundaries
+ * directly without mistaking a grammar-only entry for implemented graph support.
+ */
+export interface IEvidenceSupportedLanguage {
+    /**
+     * Configuration discriminator for the supported programming family.
+     *
+     * This is the value authors use to select the adapter in a population.
+     */
+    type: EvidenceProgrammingType;
+    /**
+     * Display name accompanying the family discriminator.
+     *
+     * It is intended for capability reports rather than target or identity matching.
+     */
+    name: string;
+    /**
+     * Registered grammar variants and accepted logical filenames.
+     *
+     * Several syntax variants can share one certified declaration adapter.
+     */
+    grammars: IEvidenceLanguageGrammar[];
+    /**
+     * Certified extraction and documentation-host contract for this family.
+     *
+     * Unlike the broader catalog entry, this supported entry always provides it.
+     */
+    adapter: IEvidenceLanguageAdapter;
+}

package/lib/structures/IEvidenceSupportedLanguage.js

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

package/lib/structures/IEvidenceSwaggerClaim.d.ts

@@ -0,0 +1,17 @@
+import type { IEvidenceClaimBase } from "./IEvidenceClaimBase";
+/**
+ * Swagger/OpenAPI operations that cite evidence from their descriptions.
+ *
+ * Each HTTP method and path identifies one semantic operation host. Description
+ * text provides its annotation carrier, but host participation does not depend on
+ * already having written documentation; otherwise undocumented operations could
+ * disappear from policies that require every selected host to answer.
+ *
+ * - File globs select local JSON/YAML documents. Each operation is a host
+ *   addressed as METHOD:/path.
+ * - Parse evidence, exclusion, and review tags from the operation's description.
+ *   Fenced examples and other JSON/YAML string fields do not host tags.
+ * - Operations without a description remain selected hosts for coverage policies.
+ */
+export interface IEvidenceSwaggerClaim extends IEvidenceClaimBase<"swagger", "operation"> {
+}

package/lib/structures/IEvidenceSwaggerClaim.js

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

package/lib/structures/IEvidenceSwaggerReference.d.ts

@@ -0,0 +1,23 @@
+import type { IEvidenceReferenceBase } from "./IEvidenceReferenceBase";
+/**
+ * Swagger/OpenAPI operations required by one reference obligation.
+ *
+ * Each operation is a separate unit addressed by a whitespace-free
+ * `METHOD:/path` token. The document boundary belongs to the reference entry,
+ * allowing identical operation tokens in different documents to impose independent
+ * coverage requirements.
+ *
+ * @example
+ * GET:/users/{id}
+ */
+export interface IEvidenceSwaggerReference extends IEvidenceReferenceBase<"swagger", "operation"> {
+    /**
+     * Exact local JSON/YAML path or HTTP(S) URL, not a glob or directory.
+     *
+     * - Relative paths resolve from root. Absolute paths are accepted; Windows
+     *   drive-relative paths are invalid.
+     * - Remote loading and document normalization failures are reported.
+     * - Use separate reference entries for independent coverage of multiple documents.
+     */
+    file: string;
+}

package/lib/structures/IEvidenceSwaggerReference.js

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

package/lib/structures/IEvidenceTagParseResult.d.ts

@@ -0,0 +1,37 @@
+import type { IEvidenceDeclaration } from "./IEvidenceDeclaration";
+import type { IEvidenceDiagnostic } from "./IEvidenceDiagnostic";
+import type { IEvidenceReview } from "./IEvidenceReview";
+import type { IEvidenceWithdrawal } from "./IEvidenceWithdrawal";
+/**
+ * Annotation records extracted from one mapped documentation host.
+ *
+ * Acknowledgements, reviews, and withdrawals remain separate because they affect
+ * coverage, freshness, and public visibility respectively. Invalid annotations
+ * retain diagnostics instead of being accepted as evidence or discarded silently.
+ */
+export interface IEvidenceTagParseResult {
+    /**
+     * Accepted acknowledgement statements that can contribute coverage.
+     *
+     * Their authored targets still require resolution against each reference.
+     */
+    declarations: IEvidenceDeclaration[];
+    /**
+     * Review statements awaiting citation pairing and fingerprint validation.
+     *
+     * These never enter the acknowledgement collection or supply coverage alone.
+     */
+    reviews: IEvidenceReview[];
+    /**
+     * Accepted directives withdrawing documented declarations from public API.
+     *
+     * Extraction records the original locations for inherited exclusion diagnostics.
+     */
+    withdrawals: IEvidenceWithdrawal[];
+    /**
+     * Findings produced while parsing annotation syntax and host constraints.
+     *
+     * Retaining them prevents malformed tags from disappearing as ordinary prose.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+}

package/lib/structures/IEvidenceTagParseResult.js

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

package/lib/structures/IEvidenceTargetResolution.d.ts

@@ -0,0 +1,51 @@
+import type { EvidenceTargetResolutionStatus } from "../typings/EvidenceTargetResolutionStatus";
+import type { IEvidenceAddress } from "./IEvidenceAddress";
+import type { IEvidenceDiagnostic } from "./IEvidenceDiagnostic";
+import type { IEvidenceUnit } from "./IEvidenceUnit";
+import type { IEvidenceWithdrawal } from "./IEvidenceWithdrawal";
+/**
+ * Resolution outcome for an authored target within one reference population.
+ *
+ * The resolver retains attempted addresses and candidate units even when it cannot
+ * accept a unique visible target. Diagnostics distinguish malformed spelling,
+ * unavailable files, selection boundaries, and incomplete extraction so callers
+ * do not report every failure as a missing member.
+ */
+export interface IEvidenceTargetResolution {
+    /**
+     * Classification of target parsing, population lookup, or access failure.
+     *
+     * Only a resolved outcome establishes a unique visible target; coverage and
+     * review policy still need to be evaluated afterward.
+     */
+    status: EvidenceTargetResolutionStatus;
+    /**
+     * Candidate public addresses produced by the artifact's target grammar.
+     *
+     * File-qualified targets can produce several absolute paths when a merged host
+     * retains multiple origins. Synthetic artifact grammars retain their own file
+     * keys, and malformed targets may produce no addresses.
+     */
+    addresses: IEvidenceAddress[];
+    /**
+     * Semantic candidates retained by the resolution outcome.
+     *
+     * Resolved results identify one visible unit; ambiguity retains competitors.
+     * Hidden results retain withdrawn candidates for an actionable explanation.
+     */
+    units: IEvidenceUnit[];
+    /**
+     * Withdrawal annotations explaining hidden candidate identities.
+     *
+     * Locations can belong to structural ancestors whose withdrawal propagates
+     * into the cited declaration.
+     */
+    withdrawals: IEvidenceWithdrawal[];
+    /**
+     * Findings explaining why resolution could not establish an accepted target.
+     *
+     * Incomplete outcomes retain underlying inventory failures so lost extraction
+     * cannot masquerade as an ordinary empty selection.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+}

package/lib/structures/IEvidenceTargetResolution.js

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

package/lib/structures/IEvidenceTargetStatement.d.ts

@@ -0,0 +1,32 @@
+import type { IEvidenceSourceLocation } from "./IEvidenceSourceLocation";
+/**
+ * Source attachment and target text shared by acknowledgements and reviews.
+ *
+ * Parsing establishes where a statement was written while leaving its target
+ * in authored form. Artifact-specific resolution later interprets the token from
+ * the host's source context. Sharing these fields does not let a review satisfy
+ * coverage: the derived record still determines the statement's role.
+ */
+export interface IEvidenceTargetStatement {
+    /**
+     * Physical documentation host containing this statement.
+     *
+     * The host table supplies semantic owners and citation origins. A matching
+     * target on another host is not interchangeable for review pairing.
+     */
+    hostId: string;
+    /**
+     * Target token preserved as written in the annotation.
+     *
+     * The referenced artifact determines its grammar and lookup rules. Keeping the
+     * authored spelling allows diagnostics to explain aliases and invalid targets.
+     */
+    target: string;
+    /**
+     * Original source position of the complete statement.
+     *
+     * Decoded documentation maps this location back to captured source characters,
+     * allowing a finding to identify the annotation rather than only its host.
+     */
+    location: IEvidenceSourceLocation;
+}

package/lib/structures/IEvidenceTargetStatement.js

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

package/lib/structures/IEvidenceUnit.d.ts

@@ -0,0 +1,96 @@
+import type { EvidenceArtifactType } from "../typings/EvidenceArtifactType";
+import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
+import type { IEvidenceUnitSite } from "./IEvidenceUnitSite";
+import type { IEvidenceWithdrawal } from "./IEvidenceWithdrawal";
+/**
+ * A semantic declaration that can participate in evidence coverage.
+ *
+ * Adapters create units for their public declarations, such as a class, database
+ * column, Markdown heading, or API operation. Coverage counts these identities,
+ * not their exported names: exposing a declaration through two aliases leaves
+ * one unit, while overloads merge only when the language establishes one family.
+ *
+ * Ownership, addressing, and source position are separate. `parentId` establishes
+ * structural containment; public addresses live in the inventory; `sites` records
+ * the physical declarations. Population selection and withdrawal follow parent
+ * links, so punctuation in a name cannot manufacture an ancestor.
+ *
+ * The same unit can serve as a claim host and as a reference target in different
+ * populations. Its review fingerprint belongs to its content and structural
+ * subtree, independently of those selections or aliases.
+ *
+ * @example
+ * // Exporting Client as PublicClient adds an address, not another class unit.
+ * // Client.send keeps the same parentId through either exported name.
+ * // A member named "send.request" occupies one identity segment, not two.
+ */
+export interface IEvidenceUnit {
+    /**
+     * Adapter-established identity of the declaration.
+     *
+     * Overloads or merged declarations share this ID only when language rules
+     * establish one unit. Public aliases and population selectors never change it.
+     */
+    id: string;
+    /**
+     * Identity of the direct structural owner.
+     *
+     * An omitted parent denotes a root. Scope closure and inherited withdrawals
+     * follow this link rather than comparing public accessor prefixes.
+     */
+    parentId?: string;
+    /**
+     * Artifact language or format that defines this declaration.
+     *
+     * The discriminator determines the adapter and selector family. It does not
+     * indicate whether a particular population uses the unit as claim or reference.
+     */
+    type: EvidenceArtifactType;
+    /**
+     * Selector category assigned by the adapter.
+     *
+     * Configuration uses this category to choose required units. An unselected
+     * parent can remain addressable as a scope without adding to that denominator.
+     */
+    symbol: EvidenceSymbol;
+    /**
+     * Literal segments of the semantic name.
+     *
+     * A segment may contain dots or spaces. These names describe the identity;
+     * `parentId` remains authoritative for its structural ownership.
+     *
+     * @example
+     * ["Client", "send.request"] // The last segment is one literal member name.
+     */
+    identity: string[];
+    /**
+     * Human-readable declaration name.
+     *
+     * Reports use this label without requiring it to be unique. Resolution uses
+     * public addresses and IDs, so unrelated declarations may share the label.
+     */
+    name: string;
+    /**
+     * Adapter-supplied digest of this unit's own semantic content.
+     *
+     * When omitted, fingerprinting derives content from the source sites after
+     * removing accepted annotations. This value excludes the separate structural
+     * subtree contribution and is not a whole-file cache digest.
+     */
+    contentDigest?: string;
+    /**
+     * Physical declarations contributing to this identity.
+     *
+     * Overloads and merged declarations retain their individual sites for host
+     * ownership checks and fingerprint content, even though coverage counts one unit.
+     */
+    sites: IEvidenceUnitSite[];
+    /**
+     * Withdrawal directives written on this unit's declarations.
+     *
+     * Inventory selection also inherits directives from structural ancestors.
+     * Keeping their locations allows hidden-target diagnostics to identify the
+     * documentation that removed the unit from eligible populations.
+     */
+    withdrawals: IEvidenceWithdrawal[];
+}

package/lib/structures/IEvidenceUnit.js

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

package/lib/structures/IEvidenceUnitSite.d.ts

@@ -0,0 +1,44 @@
+import type { IEvidenceSourceRange } from "./IEvidenceSourceRange";
+/**
+ * A physical declaration occurrence and its contribution to a unit's content.
+ *
+ * A merged unit can own several sites, while a statement declaring several
+ * variables can share one site ID across units. The site identifies the physical
+ * occurrence without deciding whether its declarations share semantic identity.
+ *
+ * The declaration range establishes ownership and diagnostic location. Content
+ * ranges identify the portions belonging to this unit's own fingerprint and may
+ * exclude sibling declarators. Inventory validation requires those portions to
+ * remain inside the declaration and checks hosts against the owned site IDs.
+ */
+export interface IEvidenceUnitSite {
+    /**
+     * Adapter identity of the physical declaration occurrence.
+     *
+     * Multi-variable statements may share this ID. Its source location must remain
+     * consistent across those records even when their content contributions differ.
+     */
+    id: string;
+    /**
+     * Captured source path containing the declaration.
+     *
+     * Fingerprinting resolves this path against inventory sources. Re-exporting
+     * the unit changes its public addresses without moving this physical site.
+     */
+    file: string;
+    /**
+     * Complete source span of this declaration occurrence.
+     *
+     * The half-open range establishes the bounds for owned content and host
+     * validation. Narrower fingerprint contributions are recorded in `content`.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Source portions contributing to this unit's own content digest.
+     *
+     * Sibling declarators need not contribute to one another's fingerprints.
+     * Accepted annotation spans are removed before the remaining text is normalized
+     * and hashed; structural descendants are combined separately afterward.
+     */
+    content: IEvidenceSourceRange[];
+}

package/lib/structures/IEvidenceUnitSite.js

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

package/lib/structures/IEvidenceVersionCommand.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parsed standalone request for the installed package version.
+ *
+ * The command reads package metadata without loading project configuration.
+ * Version flags cannot be combined with another operation or its options.
+ */
+export interface IEvidenceVersionCommand {
+    /**
+     * Discriminator selecting installed-version output.
+     *
+     * Execution reports a manifest failure if package metadata cannot be read.
+     */
+    operation: "version";
+}

package/lib/structures/IEvidenceVersionCommand.js

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

package/lib/structures/IEvidenceWatchCheckCycle.d.ts

@@ -0,0 +1,60 @@
+import type { IEvidenceCheckReport } from "./IEvidenceCheckReport";
+/**
+ * Published watch cycle containing a fresh, stable Evidence check report.
+ *
+ * The envelope identifies its place in the watch stream while mirroring the
+ * report's completeness, success, and exit status. A stable incomplete analysis
+ * is still publishable; operational exceptions use the separate failure envelope.
+ */
+export interface IEvidenceWatchCheckCycle {
+    /**
+     * Version of the watch envelope's serialization contract.
+     *
+     * Readers can validate it before interpreting the nested report and cycle fields.
+     */
+    schemaVersion: 1;
+    /**
+     * Operation reevaluated by the watcher.
+     *
+     * Watch publishes check outcomes rather than list, inspect, or graph queries.
+     */
+    command: "check";
+    /**
+     * Discriminator marking this result as part of a watch stream.
+     *
+     * Consumers use cycle numbers to distinguish repeated evaluations of one command.
+     */
+    watch: true;
+    /**
+     * One-based sequence number of the published result.
+     *
+     * Stable failures and successful analyses share the same publication sequence;
+     * discarded unstable attempts do not consume another number.
+     */
+    cycle: number;
+    /**
+     * Completeness state copied from the fresh check report.
+     *
+     * Complete describes analysis availability, not whether coverage errors were found.
+     */
+    status: "complete" | "incomplete";
+    /**
+     * Whether the complete report has no error diagnostics.
+     *
+     * Warning-only findings can pass, while incomplete analysis cannot.
+     */
+    success: boolean;
+    /**
+     * Check outcome copied into the watch envelope.
+     *
+     * Zero passes, one reports completed errors, and two reports incomplete analysis;
+     * publication itself does not end the watcher.
+     */
+    exitCode: 0 | 1 | 2;
+    /**
+     * Full check result underlying the envelope's outcome fields.
+     *
+     * It retains independent claims, counts, and actionable diagnostics for this cycle.
+     */
+    report: IEvidenceCheckReport;
+}

package/lib/structures/IEvidenceWatchCheckCycle.js

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

package/lib/structures/IEvidenceWatchFailureCycle.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Published watch cycle for a stable configuration or operational exception.
+ *
+ * The watcher cannot provide a normal check report for this attempt, but retains
+ * dependencies so a later repair can trigger another cycle. Parser acquisition
+ * failures also retry on a timer because recovery may require no source edit.
+ */
+export interface IEvidenceWatchFailureCycle {
+    /**
+     * Version of the failure envelope's serialization contract.
+     *
+     * It is inspected before interpreting the watch sequence and repair fields.
+     */
+    schemaVersion: 1;
+    /**
+     * Check operation that the watcher attempted.
+     *
+     * The failure belongs to reevaluation of the configured Evidence check.
+     */
+    command: "check";
+    /**
+     * Discriminator marking an ongoing watch-stream result.
+     *
+     * A failed cycle does not imply that the watcher has stopped observing repairs.
+     */
+    watch: true;
+    /**
+     * One-based publication sequence shared with normal check cycles.
+     *
+     * The next recovered result continues this sequence instead of restarting it.
+     */
+    cycle: number;
+    /**
+     * Operational-failure discriminator for an unavailable check report.
+     *
+     * An analyzed but incomplete population instead uses a check-cycle envelope.
+     */
+    status: "failed";
+    /**
+     * Failed outcome for consumers inspecting the common success field.
+     *
+     * An exception cannot certify complete coverage, even if an earlier cycle passed.
+     */
+    success: false;
+    /**
+     * Outcome code for unavailable analysis in this cycle.
+     *
+     * This is published as data and does not itself terminate ongoing observation.
+     */
+    exitCode: 2;
+    /**
+     * Resolved configuration path associated with the failed attempt.
+     *
+     * The path remains available even when configuration evaluation itself failed.
+     */
+    configFile: string;
+    /**
+     * Explanation derived from the configuration or operational exception.
+     *
+     * It identifies the current failure rather than repeating the previous cycle's report.
+     */
+    message: string;
+    /**
+     * Corrective guidance and the applicable retry behavior.
+     *
+     * Parser acquisition can retry automatically; other failures wait for a watched
+     * filesystem change that permits another complete attempt.
+     */
+    repair: string;
+}

package/lib/structures/IEvidenceWatchFailureCycle.js

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

package/lib/structures/IEvidenceWatchOptions.d.ts

@@ -0,0 +1,37 @@
+import type { tags } from "typia";
+/**
+ * Timing controls for dependency polling, edit settling, and parser recovery.
+ *
+ * The watcher compares dependency snapshots and waits for a quiet period before
+ * reevaluation. Parser acquisition has a separate retry clock because network or
+ * cache recovery may happen without any watched filesystem change.
+ */
+export interface IEvidenceWatchOptions {
+    /**
+     * Positive delay between dependency snapshots, in milliseconds.
+     *
+     * Shorter intervals detect changes sooner while performing filesystem inspection
+     * more often. Omission uses 250 milliseconds.
+     *
+     * @default 250
+     */
+    pollIntervalMilliseconds?: number & tags.Type<"uint32"> & tags.Minimum<1>;
+    /**
+     * Quiet period required before checking a changed snapshot, in milliseconds.
+     *
+     * Further changes restart settling. Zero skips the quiet wait; omission uses
+     * 100 milliseconds to coalesce a burst of related edits.
+     *
+     * @default 100
+     */
+    debounceMilliseconds?: number & tags.Type<"uint32">;
+    /**
+     * Positive delay before retrying failed parser acquisition, in milliseconds.
+     *
+     * The retry can trigger without a source edit, allowing download, cache, or
+     * integrity failures to recover. Omission waits five seconds.
+     *
+     * @default 5000
+     */
+    parserRetryMilliseconds?: number & tags.Type<"uint32"> & tags.Minimum<1>;
+}

package/lib/structures/IEvidenceWatchOptions.js

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

package/lib/structures/IEvidenceWithdrawal.d.ts

@@ -0,0 +1,24 @@
+import type { IEvidenceSourceLocation } from "./IEvidenceSourceLocation";
+/**
+ * Source annotation withdrawing a declaration from the public population.
+ *
+ * Inventory selection propagates withdrawal through structural descendants while
+ * retaining the original location. A citation can then explain why a declaration
+ * is hidden instead of presenting an excluded API as an unknown name.
+ */
+export interface IEvidenceWithdrawal {
+    /**
+     * Authored withdrawal directive accepted at a declaration documentation host.
+     *
+     * The three spellings share exclusion behavior but remain distinguishable in
+     * the retained annotation record.
+     */
+    tag: "internal" | "hidden" | "ignore";
+    /**
+     * Source location of the directive causing withdrawal.
+     *
+     * Descendant exclusions keep this origin so diagnostics point to the authoring
+     * decision rather than an arbitrary child declaration.
+     */
+    location: IEvidenceSourceLocation;
+}

package/lib/structures/IEvidenceWithdrawal.js

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