@wrtnlabs/evidence 0.0.0

package/lib/structures/IEvidenceConfigPlanReference.d.ts

@@ -0,0 +1,40 @@
+import type { EvidenceActiveSeverity } from "../typings/EvidenceActiveSeverity";
+import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
+import type { IEvidenceReference } from "./IEvidenceReference";
+/**
+ * One enabled reference prepared to select its required evidence units.
+ *
+ * The plan keeps the authored reference alongside effective severity and symbol
+ * defaults. Materialization uses these resolved settings to construct a target
+ * population independently of the claim's host selection or neighboring references.
+ */
+export interface IEvidenceConfigPlanReference {
+    /**
+     * Zero-based position in the claim's authored reference declaration.
+     *
+     * Filtering inactive references does not renumber this value. A single reference
+     * has index zero after normalization to the execution sequence.
+     */
+    index: number;
+    /**
+     * Validated reference retaining its authored artifact settings.
+     *
+     * Paths and optional policy flags remain available for materialization. Resolved
+     * severity and symbol choices are recorded separately rather than written back.
+     */
+    population: IEvidenceReference;
+    /**
+     * Active severity after inheriting or overriding the claim's level.
+     *
+     * Off references do not enter the plan. This severity attributes findings from
+     * discovery, extraction, resolution, and coverage to this obligation.
+     */
+    severity: EvidenceActiveSeverity;
+    /**
+     * Explicit or artifact-default kinds forming the reference denominator.
+     *
+     * Unselected real ancestors can still become aggregate resolution scopes after
+     * inventory selection; they do not become additional required units.
+     */
+    symbols: EvidenceSymbol[];
+}

package/lib/structures/IEvidenceConfigPlanReference.js

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

package/lib/structures/IEvidenceDatabaseClaim.d.ts

@@ -0,0 +1,26 @@
+import type { EvidenceDatabaseSymbol } from "../typings/EvidenceDatabaseSymbol";
+import type { EvidenceDatabaseType } from "../typings/EvidenceDatabaseType";
+import type { IEvidenceClaimBase } from "./IEvidenceClaimBase";
+/**
+ * Database schema declarations that cite evidence in documentation comments.
+ *
+ * The database adapter determines schema identity, structural relationships, and
+ * eligible documentation carriers. Symbol selection then chooses which models,
+ * columns, or relations owe evidence; parsing failures retain an incomplete
+ * population instead of removing requirements from the check.
+ *
+ * Prisma host rules:
+ *
+ * - Matching files form one schema regardless of extension. A physical file
+ *   reached by multiple populations is parsed once.
+ * - Triple-slash and block documentation comments attach to the next declaration.
+ *   Ordinary double-slash comments do not host tags.
+ * - A blank line before a top-level block detaches the comment. Comments above
+ *   block attributes or closing braces also have no declaration host.
+ * - Evidence and exclusions require a target and nonempty reason. Invalid or
+ *   detached declarations are reported.
+ * - An unattached top-level triple-slash run may carry a file-level exclusion,
+ *   independently of the symbol selector. It cannot carry ordinary evidence.
+ */
+export interface IEvidenceDatabaseClaim extends IEvidenceClaimBase<EvidenceDatabaseType, EvidenceDatabaseSymbol> {
+}

package/lib/structures/IEvidenceDatabaseClaim.js

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

package/lib/structures/IEvidenceDatabaseLanguage.d.ts

@@ -0,0 +1,37 @@
+import type { EvidenceDatabaseType } from "../typings/EvidenceDatabaseType";
+import type { IEvidenceDatabaseLanguageAdapter } from "./IEvidenceDatabaseLanguageAdapter";
+import type { IEvidenceLanguageGrammar } from "./IEvidenceLanguageGrammar";
+/**
+ * Database-language catalog entry separating grammar availability from schema extraction.
+ *
+ * A parser recognizing schema syntax does not establish model, column, relation,
+ * or documentation ownership. Adapter metadata appears only when those Evidence
+ * boundaries are certified, allowing catalog inspection without overstating support.
+ */
+export interface IEvidenceDatabaseLanguage {
+    /**
+     * Database family discriminator used in population configuration.
+     *
+     * Grammar and adapter selection remain scoped to this configured family.
+     */
+    type: EvidenceDatabaseType;
+    /**
+     * Human-readable schema-language name.
+     *
+     * Capability reports display this label alongside the configuration discriminator.
+     */
+    name: string;
+    /**
+     * Pinned grammar variants and their accepted logical file spellings.
+     *
+     * Reading these selection rules does not acquire or initialize a grammar.
+     */
+    grammars: IEvidenceLanguageGrammar[];
+    /**
+     * Certified schema extraction capabilities, when available.
+     *
+     * Omission means grammar availability alone cannot certify Evidence units,
+     * structural ownership, or annotation hosts for the language.
+     */
+    adapter?: IEvidenceDatabaseLanguageAdapter;
+}

package/lib/structures/IEvidenceDatabaseLanguage.js

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

package/lib/structures/IEvidenceDatabaseLanguageAdapter.d.ts

@@ -0,0 +1,48 @@
+import type { EvidenceDatabaseSymbol } from "../typings/EvidenceDatabaseSymbol";
+/**
+ * Certified schema and documentation boundaries of a database adapter.
+ *
+ * This contract describes the units an adapter can extract and how citations name
+ * them. Capability reports keep these semantic guarantees separate from the
+ * grammar's ability to recognize a broader range of database syntax.
+ */
+export interface IEvidenceDatabaseLanguageAdapter {
+    /**
+     * Public constructor exposing this schema adapter.
+     *
+     * Programmatic consumers can connect the catalog entry to its extraction API.
+     */
+    entry: string;
+    /**
+     * Database symbol selectors supported by the adapter.
+     *
+     * These determine which extracted models, columns, or relations can be selected.
+     */
+    symbols: EvidenceDatabaseSymbol[];
+    /**
+     * Schema declarations included in the certified extraction surface.
+     *
+     * This qualifies grammar support with the semantic boundaries needed for a
+     * complete Evidence inventory.
+     */
+    publicSurface: string;
+    /**
+     * Canonical qualification used to address extracted schema units.
+     *
+     * Authors follow this policy when spelling model, column, or relation targets.
+     */
+    addressing: string;
+    /**
+     * Documentation forms accepted at supported schema declaration positions.
+     *
+     * Attachment rules determine which comments can carry evidence or withdrawal tags.
+     */
+    comments: string[];
+    /**
+     * Known schema capabilities outside certified extraction.
+     *
+     * Capability readers use these limitations when judging whether their input
+     * falls within the adapter's documented surface.
+     */
+    unsupported: string[];
+}

package/lib/structures/IEvidenceDatabaseLanguageAdapter.js

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

package/lib/structures/IEvidenceDatabaseReference.d.ts

@@ -0,0 +1,20 @@
+import type { EvidenceDatabaseSymbol } from "../typings/EvidenceDatabaseSymbol";
+import type { EvidenceDatabaseType } from "../typings/EvidenceDatabaseType";
+import type { IEvidenceReferenceBase } from "./IEvidenceReferenceBase";
+/**
+ * Database schema units required by the owning claim's reference policy.
+ *
+ * Model, column, and relation selectors choose the coverage denominator after
+ * schema extraction. Parent scopes remain available to resolve aggregate targets,
+ * while each reference entry evaluates its selected schema independently.
+ */
+export interface IEvidenceDatabaseReference extends IEvidenceReferenceBase<EvidenceDatabaseType, EvidenceDatabaseSymbol> {
+    /**
+     * Schema-file globs relative to the reference root.
+     *
+     * These use claim glob rules. Prisma files form one schema regardless of
+     * extension; repeated physical files are parsed once.
+     * Parsing failures must not produce empty populations.
+     */
+    files: string[];
+}

package/lib/structures/IEvidenceDatabaseReference.js

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

package/lib/structures/IEvidenceDeclaration.d.ts

@@ -0,0 +1,37 @@
+import type { EvidenceAcknowledgementKind } from "../typings/EvidenceAcknowledgementKind";
+import type { IEvidenceTargetStatement } from "./IEvidenceTargetStatement";
+/**
+ * A parsed positive or exclusion acknowledgement awaiting reference-specific resolution.
+ *
+ * The tag parser records the target, reason, host, and source location. Resolution
+ * identifies the cited scope, then each reference judges host eligibility,
+ * exclusion permission, and coverage of its selected descendants. Merely parsing
+ * a statement does not create a valid coverage edge.
+ *
+ * Reviews use a separate shape because they validate acknowledgements rather
+ * than substitute for them. Multiple statements may still belong to one semantic
+ * host for cardinality purposes.
+ */
+export interface IEvidenceDeclaration extends IEvidenceTargetStatement {
+    /**
+     * Identity of this physical acknowledgement statement.
+     *
+     * Target resolutions and accepted graph edges join through this ID. Repeated
+     * statements do not necessarily represent different semantic hosts.
+     */
+    id: string;
+    /**
+     * Whether the annotation supplies positive evidence or an exclusion.
+     *
+     * Both can cover ordinary obligations, but exclusions have independent carrier,
+     * refusal, and overlap rules. A review cannot be represented as either kind.
+     */
+    kind: EvidenceAcknowledgementKind;
+    /**
+     * Nonempty explanation accompanying the target.
+     *
+     * The parser requires prose so the citation records its purpose. Coverage checks
+     * establish structural acknowledgement, not the truth of this explanation.
+     */
+    reason: string;
+}

package/lib/structures/IEvidenceDeclaration.js

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

package/lib/structures/IEvidenceDiagnostic.d.ts

@@ -0,0 +1,66 @@
+import type { EvidenceSeverity } from "../typings/EvidenceSeverity";
+import type { IEvidenceSourceLocation } from "./IEvidenceSourceLocation";
+/**
+ * Actionable finding attributed to a source or configuration boundary.
+ *
+ * The code identifies the failure category while message and repair explain the
+ * observed problem and the author's next step. Optional coordinates allow the
+ * same structure to represent source-level findings and aggregate failures that
+ * have no single source span. Claim names are display labels, not identities.
+ */
+export interface IEvidenceDiagnostic {
+    /**
+     * Stable category used to identify the finding programmatically.
+     *
+     * Consumers should use this value instead of matching human-readable wording.
+     */
+    code: string;
+    /**
+     * Effective reporting level for this finding.
+     *
+     * Off policies emit no diagnostic; an emitted error contributes to check failure.
+     */
+    severity: Exclude<EvidenceSeverity, "off">;
+    /**
+     * Explanation of the observed failure or policy violation.
+     *
+     * Renderers present this separately from source coordinates and repair guidance.
+     */
+    message: string;
+    /**
+     * Concrete corrective action available to the author.
+     *
+     * This accompanies the finding so a stable code need not encode every remedy.
+     */
+    repair: string;
+    /**
+     * Source file and optional span associated with the finding.
+     *
+     * Omission indicates a configuration or aggregate graph context.
+     */
+    location?: IEvidenceSourceLocation;
+    /**
+     * Zero-based authored claim index owning the finding.
+     *
+     * Omission leaves the diagnostic outside a particular claim boundary.
+     */
+    claim?: number;
+    /**
+     * Zero-based authored reference index within the owning claim.
+     *
+     * Omission permits a claim-level or unscoped finding without inventing a pair.
+     */
+    reference?: number;
+    /**
+     * Documentation host implicated in the finding.
+     *
+     * When present, this connects a statement-level error to its extracted carrier.
+     */
+    hostId?: string;
+    /**
+     * Authored target text implicated in the finding.
+     *
+     * This can be retained even when parsing or resolution failed to identify a unit.
+     */
+    target?: string;
+}

package/lib/structures/IEvidenceDiagnostic.js

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

package/lib/structures/IEvidenceDocumentation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Adapter-normalized documentation with a map back to its source spelling.
+ *
+ * Removing comment prefixes or decoding string escapes changes text coordinates.
+ * The tag parser uses the parallel offset arrays to recover precise source spans
+ * for diagnostics and fingerprint exclusions. Host policy determines which tags
+ * terminate reasons and whether a withdrawal directive has declaration ownership.
+ */
+export interface IEvidenceDocumentation {
+    /**
+     * Identity of the documentation carrier represented by this text.
+     *
+     * Parsed statements retain this ID so adapters can attach them to semantic units.
+     */
+    hostId: string;
+    /**
+     * Normalized text to scan for annotations.
+     *
+     * Its UTF-16 indices address the mapping arrays rather than the original file
+     * directly, since delimiters and encoded characters may have been transformed.
+     */
+    text: string;
+    /**
+     * Original UTF-16 start for each text code unit and the final source boundary.
+     *
+     * The terminal entry permits mapping a position at the end of normalized text;
+     * removed prefixes can leave gaps between consecutive original offsets.
+     */
+    offsets: number[];
+    /**
+     * Original exclusive end corresponding to each normalized text code unit.
+     *
+     * Separate ends preserve escaped spellings and removed gaps that cannot be
+     * represented by adding one to the mapped start.
+     */
+    ends: number[];
+    /**
+     * Whether other tools' line-start tags terminate an acknowledgement reason.
+     *
+     * JSDoc-like hosts enable this boundary so unrelated tags are not absorbed into
+     * the preceding Evidence annotation's reason text.
+     */
+    tagBoundaries: boolean;
+    /**
+     * Whether the host owns a declaration that a withdrawal directive can exclude.
+     *
+     * Adapters enable this only at supported declaration documentation positions;
+     * arbitrary prose cannot hide unrelated semantic units.
+     */
+    allowWithdrawal: boolean;
+}

package/lib/structures/IEvidenceDocumentation.js

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

package/lib/structures/IEvidenceDocumentedConfig.d.ts

@@ -0,0 +1,20 @@
+import type { EvidenceProgrammingSymbol } from "../typings/EvidenceProgrammingSymbol";
+/**
+ * Requires documentation comments on selected public programming declarations.
+ *
+ * This policy checks whether declarations have documentation capable of hosting
+ * evidence. It does not judge prose quality or replace the repository's source
+ * documentation rules. A narrower selector can require documentation on functions
+ * without imposing the same presence check on every public property.
+ */
+export interface IEvidenceDocumentedConfig {
+    /**
+     * Symbol kinds requiring documentation; accepts one kind or a nonempty array.
+     *
+     * Omission checks types, functions, and properties. The selector applies to
+     * public programming declarations within the configured population.
+     *
+     * @default ["type", "function", "property"]
+     */
+    symbol?: EvidenceProgrammingSymbol | EvidenceProgrammingSymbol[];
+}

package/lib/structures/IEvidenceDocumentedConfig.js

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

package/lib/structures/IEvidenceFingerprint.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Versioned content identity of a cited declaration and its structural subtree.
+ *
+ * Fingerprinting derives each unit's own content from an adapter digest or its
+ * source ranges, excludes accepted annotation spans, then combines explicit
+ * descendants. A review token belongs to the cited scope, independently of a
+ * reference's symbol selector or the public alias used to reach it.
+ *
+ * Own content and subtree content remain separate so callers can distinguish a
+ * declaration edit from changes below it. Neither digest is a whole-file cache
+ * key: evidence prose can change without expiring its own recorded review.
+ */
+export interface IEvidenceFingerprint {
+    /**
+     * Version of the fingerprint construction algorithm.
+     *
+     * This identifies normalization and scope semantics for the token, independently
+     * of the inventory schema version or parser grammar revision.
+     */
+    version: number;
+    /**
+     * Semantic identity at the root of the cited scope.
+     *
+     * Aliases resolve to this same unit before fingerprinting. Reference selectors
+     * do not change which identity owns the token.
+     */
+    unitId: string;
+    /**
+     * Digest of the root unit's own normalized content.
+     *
+     * Structural descendants are combined separately in `scopeDigest`. Accepted
+     * annotation spans are excluded from source-derived content.
+     */
+    contentDigest: string;
+    /**
+     * Digest combining the root unit with its complete structural subtree.
+     *
+     * The scope follows explicit ownership and does not shrink to a reference's
+     * selected kinds. A descendant edit can therefore expire an aggregate review.
+     */
+    scopeDigest: string;
+    /**
+     * Review token representing this versioned content scope.
+     *
+     * Authors record the current token in review annotations. Graph evaluation
+     * compares it with the recomputed token when review freshness is required.
+     */
+    fingerprint: string;
+}

package/lib/structures/IEvidenceFingerprint.js

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

package/lib/structures/IEvidenceGrammar.d.ts

@@ -0,0 +1,47 @@
+import type { IEvidenceGrammarAsset } from "./IEvidenceGrammarAsset";
+/**
+ * Pinned provenance for a lazily acquired Tree-sitter syntax variant.
+ *
+ * The registry uses this record to associate a selectable grammar with upstream
+ * source, verified WASM bytes, and license provenance. Listing this metadata does
+ * not download the grammar or certify an artifact adapter's declaration coverage.
+ */
+export interface IEvidenceGrammar {
+    /**
+     * Unique syntax-variant key used by registry selection and parser caches.
+     *
+     * A language family may select different keys according to the source filename.
+     */
+    id: string;
+    /**
+     * Canonical upstream repository containing the grammar source.
+     *
+     * This establishes authorship and provenance independently of the download host.
+     */
+    repository: string;
+    /**
+     * Upstream release or reproducible build identifier pinned for this grammar.
+     *
+     * It explains the human-readable revision associated with the immutable assets.
+     */
+    version: string;
+    /**
+     * Full upstream source commit associated with the pinned release.
+     *
+     * The commit disambiguates provenance even if a release tag later moves.
+     */
+    commit: string;
+    /**
+     * WASM asset acquired when parsing first requires this variant.
+     *
+     * Its size and digest are verified before bytes enter the immutable grammar cache.
+     */
+    wasm: IEvidenceGrammarAsset;
+    /**
+     * Pinned upstream license asset retained with the grammar provenance.
+     *
+     * This identifies the exact license text associated with the selected revision,
+     * independently of whether a parse has acquired the WASM asset.
+     */
+    license: IEvidenceGrammarAsset;
+}

package/lib/structures/IEvidenceGrammar.js

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

package/lib/structures/IEvidenceGrammarAsset.d.ts

@@ -0,0 +1,37 @@
+import type { tags } from "typia";
+/**
+ * Immutable upstream asset identified by its size and SHA-256 digest.
+ *
+ * Grammar metadata uses the same shape for WASM and license provenance. Acquisition
+ * can bound a download before hashing it, and cache identity depends on verified
+ * bytes rather than trusting a mutable filename or the server response alone.
+ */
+export interface IEvidenceGrammarAsset {
+    /**
+     * Slash-separated filename retained from upstream provenance.
+     *
+     * It describes the source asset; it does not require a matching file in the
+     * published Evidence package.
+     */
+    file: string;
+    /**
+     * Release- or commit-qualified HTTPS URL for acquiring the asset.
+     *
+     * Downloaded content must still match the pinned size and digest before use.
+     */
+    url: string;
+    /**
+     * Lowercase SHA-256 digest of the exact upstream bytes.
+     *
+     * Verification rejects altered downloads, and immutable cache entries use this
+     * digest to distinguish content independently of its filename.
+     */
+    sha256: string & tags.Pattern<"^[0-9a-f]{64}$">;
+    /**
+     * Exact positive byte length expected from the asset.
+     *
+     * Acquisition uses this bound before checksum verification so an oversized
+     * response cannot be accepted as the pinned download.
+     */
+    size: number & tags.Type<"uint32"> & tags.Minimum<1>;
+}

package/lib/structures/IEvidenceGrammarAsset.js

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

package/lib/structures/IEvidenceGraphBoundary.d.ts

@@ -0,0 +1,73 @@
+import type { IEvidenceGraphHostCoverage } from "./IEvidenceGraphHostCoverage";
+import type { IEvidenceGraphPolicy } from "./IEvidenceGraphPolicy";
+import type { IEvidenceQueryScope } from "./IEvidenceQueryScope";
+/**
+ * Exported policy and coverage ledger for one independent claim/reference pair.
+ *
+ * All related nodes, acknowledgement edges, and reviews identify this boundary.
+ * Selected unit IDs establish its denominator; checklist mode additionally keeps
+ * each claim host's answer ledger so answers cannot be pooled between hosts.
+ */
+export interface IEvidenceGraphBoundary {
+    /**
+     * Export identity derived from authored claim and reference indices.
+     *
+     * Related nodes and relationships use this key to retain obligation ownership.
+     */
+    id: string;
+    /**
+     * Configured population supplying semantic claim hosts.
+     *
+     * Its role, artifact type, and authored index describe the citing side of the pair.
+     */
+    claim: IEvidenceQueryScope;
+    /**
+     * Configured population supplying required evidence units.
+     *
+     * Its reference index distinguishes repeated requirements under the same claim.
+     */
+    reference: IEvidenceQueryScope;
+    /**
+     * Effective acknowledgement, exclusion, and review rules for the pair.
+     *
+     * Inherited settings have been resolved into the booleans and severity used by evaluation.
+     */
+    policy: IEvidenceGraphPolicy;
+    /**
+     * Whether the pair participates in graph coverage evaluation.
+     *
+     * Inactive boundaries retain context without contributing active requirements.
+     */
+    active: boolean;
+    /**
+     * Whether the obligation's analysis established complete population data.
+     *
+     * False prevents interpreting apparent coverage as a trustworthy pass.
+     */
+    complete: boolean;
+    /**
+     * Selected semantic reference identities forming this boundary's denominator.
+     *
+     * Structural ancestors may appear as nodes without being added to this list.
+     */
+    unitIds: string[];
+    /**
+     * Selected reference identities covered under this boundary's policy.
+     *
+     * The same identity may remain missing in another independent boundary.
+     */
+    coveredUnitIds: string[];
+    /**
+     * Selected reference identities still lacking required acknowledgement.
+     *
+     * These retain the obligation's uncovered requirements rather than unresolved names.
+     */
+    missingUnitIds: string[];
+    /**
+     * Per-host answer ledgers when this obligation uses Markdown checklist mode.
+     *
+     * Ordinary coverage leaves the array empty; checklist answers remain attributable
+     * to each semantic claim subject.
+     */
+    hostCoverage: IEvidenceGraphHostCoverage[];
+}

package/lib/structures/IEvidenceGraphBoundary.js

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