@wrtnlabs/evidence 0.0.0

package/lib/structures/IEvidenceListCommand.d.ts

@@ -0,0 +1,55 @@
+import type { EvidenceArtifactType } from "../typings/EvidenceArtifactType";
+import type { EvidenceReportFormat } from "../typings/EvidenceReportFormat";
+import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
+/**
+ * Parsed request to enumerate addressable units from a configured analysis.
+ *
+ * Language and kind filter displayed rows after the complete check is analyzed.
+ * They do not narrow evaluation or erase diagnostics from populations omitted
+ * by the list filters.
+ */
+export interface IEvidenceListCommand {
+    /**
+     * Discriminator selecting target discovery.
+     *
+     * The result includes public spellings and structural selection state for each row.
+     */
+    operation: "list";
+    /**
+     * Command working directory resolved against the invocation base.
+     *
+     * It anchors configuration, output, and file-qualified target display without
+     * mutating the process working directory.
+     */
+    cwd: string;
+    /**
+     * Configuration path relative to the resolved command directory.
+     *
+     * Parsing uses evidence.config.ts when the caller does not supply an override.
+     */
+    config: string;
+    /**
+     * Text or JSON representation of the discovery report.
+     *
+     * The parser defaults to text while both formats retain the analysis outcome.
+     */
+    format: EvidenceReportFormat;
+    /**
+     * Optional destination file relative to the command directory.
+     *
+     * Omission returns report content through the command's standard output channel.
+     */
+    output?: string;
+    /**
+     * Optional artifact-family filter for returned rows.
+     *
+     * Omission retains every family; supplied values must have a shipped adapter.
+     */
+    language?: EvidenceArtifactType;
+    /**
+     * Optional symbol-kind filter applied to discovered units.
+     *
+     * Omission retains all kinds; filtering does not recompute the coverage denominator.
+     */
+    kind?: EvidenceSymbol;
+}

package/lib/structures/IEvidenceListCommand.js

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

package/lib/structures/IEvidenceListItem.d.ts

@@ -0,0 +1,69 @@
+import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
+import type { EvidenceUnitSelection } from "../typings/EvidenceUnitSelection";
+import type { IEvidenceQueryScope } from "./IEvidenceQueryScope";
+import type { IEvidenceSourceLocation } from "./IEvidenceSourceLocation";
+/**
+ * Discoverable semantic unit within one configured population.
+ *
+ * A row groups public aliases and physical declaration locations under one unit
+ * identity. Its population-qualified ID distinguishes appearances across claims
+ * and references, while selection state separates required units from addressable
+ * structural ancestors.
+ */
+export interface IEvidenceListItem {
+    /**
+     * Query-row identity combining configuration scope and semantic unit identity.
+     *
+     * The same unit in another configured population receives a different row ID.
+     */
+    id: string;
+    /**
+     * Configured claim or reference boundary containing this row.
+     *
+     * Coverage and selection must be interpreted within this boundary.
+     */
+    scope: IEvidenceQueryScope;
+    /**
+     * Semantic identity assigned by extraction and inventory normalization.
+     *
+     * Aliases and merged declaration sites retain this identity without adding units.
+     */
+    unitId: string;
+    /**
+     * Artifact-specific declaration kind used by symbol selection.
+     *
+     * List filtering compares this value without changing the underlying analysis.
+     */
+    symbol: EvidenceSymbol;
+    /**
+     * Declaration name retained for human-readable output.
+     *
+     * Use target or aliases for citations because a local name alone may be ambiguous.
+     */
+    name: string;
+    /**
+     * Relationship of the identity to the configured symbol selection.
+     *
+     * Ancestors support aggregate addressing without entering the selected denominator;
+     * inspection can also expose an unselected child or hidden candidate.
+     */
+    selection: EvidenceUnitSelection;
+    /**
+     * First deterministically ordered public target spelling for this row.
+     *
+     * It follows the artifact grammar and query base directory where applicable.
+     */
+    target: string;
+    /**
+     * All accepted public spellings, deduplicated and sorted.
+     *
+     * This includes target itself; choosing another alias does not change semantic identity.
+     */
+    aliases: string[];
+    /**
+     * Physical declaration locations contributing to the identity.
+     *
+     * Merged declarations retain multiple sites even when list output contains one row.
+     */
+    locations: IEvidenceSourceLocation[];
+}

package/lib/structures/IEvidenceListItem.js

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

package/lib/structures/IEvidenceListReport.d.ts

@@ -0,0 +1,82 @@
+import type { EvidenceArtifactType } from "../typings/EvidenceArtifactType";
+import type { EvidenceCheckStatus } from "../typings/EvidenceCheckStatus";
+import type { EvidenceCommandExitCode } from "../typings/EvidenceCommandExitCode";
+import type { EvidenceSymbol } from "../typings/EvidenceSymbol";
+import type { IEvidenceDiagnostic } from "./IEvidenceDiagnostic";
+import type { IEvidenceListItem } from "./IEvidenceListItem";
+/**
+ * Versioned target-discovery report over an existing Evidence analysis.
+ *
+ * Rows include selected identities and their addressable ancestors, optionally
+ * filtered by artifact family and symbol kind. Filters affect displayed rows only:
+ * completeness, success, and diagnostics still describe the underlying full check.
+ */
+export interface IEvidenceListReport {
+    /**
+     * Serialization version of the list result.
+     *
+     * Consumers inspect this before interpreting row and scope fields.
+     */
+    schemaVersion: 1;
+    /**
+     * Discriminator identifying target-discovery output.
+     *
+     * It separates this row collection from check, inspection, and graph reports.
+     */
+    command: "list";
+    /**
+     * Configuration anchor of the analyzed populations.
+     *
+     * Row scope indices refer to entries authored in this configuration.
+     */
+    configFile: string;
+    /**
+     * Completeness inherited from the full check analysis.
+     *
+     * Filtering away rows cannot turn incomplete extraction into a complete result.
+     */
+    status: EvidenceCheckStatus;
+    /**
+     * Success inherited from the analyzed check.
+     *
+     * Discovering usable targets does not suppress coverage errors elsewhere in that check.
+     */
+    success: boolean;
+    /**
+     * Process outcome inherited from the analyzed check.
+     *
+     * The list operation preserves incomplete and error states despite returning rows.
+     */
+    exitCode: EvidenceCommandExitCode;
+    /**
+     * Requested artifact-family filter, when supplied.
+     *
+     * Omission permits rows from every configured artifact family.
+     */
+    language?: EvidenceArtifactType;
+    /**
+     * Requested symbol-kind filter, when supplied.
+     *
+     * Omission retains all kinds within the selected language filter.
+     */
+    kind?: EvidenceSymbol;
+    /**
+     * Number of rows remaining after query filters.
+     *
+     * This counts population-qualified rows, including structural ancestors, rather
+     * than reporting the check's coverage denominator.
+     */
+    total: number;
+    /**
+     * Discoverable units ordered by their population-qualified row IDs.
+     *
+     * Each row retains its aliases and selection state for authoring exact citations.
+     */
+    items: IEvidenceListItem[];
+    /**
+     * Diagnostics inherited from the underlying full analysis.
+     *
+     * They remain visible even if language or kind filters omit the affected rows.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+}

package/lib/structures/IEvidenceListReport.js

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

package/lib/structures/IEvidenceMarkdownClaim.d.ts

@@ -0,0 +1,19 @@
+import type { EvidenceMarkdownSymbol } from "../typings/EvidenceMarkdownSymbol";
+import type { IEvidenceClaimBase } from "./IEvidenceClaimBase";
+/**
+ * Markdown documents that host evidence tags in HTML comments.
+ *
+ * Heading structure supplies semantic claim hosts, and comment placement assigns
+ * each annotation to a file or section. Selecting an exact heading level controls
+ * which subjects owe evidence without flattening nested sections into their
+ * parent's identity.
+ *
+ * - Every matching regular file is parsed as Markdown regardless of extension.
+ * - File hosts precede the first ATX heading. Section hosts belong to the nearest
+ *   preceding ATX heading, whose exact level must be selected.
+ * - Evidence and exclusions require a target and nonempty reason.
+ * - Ordinary exclusions belong to the claim's target scope, not their particular
+ *   eligible host position. Markdown checklists apply per-host rules instead.
+ */
+export interface IEvidenceMarkdownClaim extends IEvidenceClaimBase<"markdown", EvidenceMarkdownSymbol> {
+}

package/lib/structures/IEvidenceMarkdownClaim.js

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

package/lib/structures/IEvidenceMarkdownReference.d.ts

@@ -0,0 +1,48 @@
+import type { EvidenceMarkdownSymbol } from "../typings/EvidenceMarkdownSymbol";
+import type { IEvidenceReferenceBase } from "./IEvidenceReferenceBase";
+/**
+ * Markdown documents or outline items required by the owning claim.
+ *
+ * Ordinary coverage lets a citation acknowledge a selected section and its
+ * selected descendants. `checklist` adds a host dimension: every selected claim
+ * host must independently answer every selected Markdown item, and positive
+ * evidence answers only the named item.
+ *
+ * Use checklist mode for a review form each declaration must complete, rather
+ * than a requirement that any one implementation may satisfy. Configuration
+ * validation rejects cardinality and carrier combinations that conflict with
+ * this per-host interpretation.
+ *
+ * @example
+ * // With two selected test functions and three checklist headings, each
+ * // function owes three answers. Six required answers cannot be pooled into
+ * // three citations supplied by only one of the functions.
+ */
+export interface IEvidenceMarkdownReference extends IEvidenceReferenceBase<"markdown", EvidenceMarkdownSymbol> {
+    /**
+     * Markdown source globs relative to the reference root.
+     *
+     * Selection uses the claim glob rules. Every matching regular file is parsed
+     * regardless of extension, so explicitly exclude non-Markdown assets.
+     */
+    files: string[];
+    /**
+     * Require every selected claim host to answer every selected Markdown item.
+     *
+     * - Hosts without tags still owe every item.
+     * - Positive evidence answers only the named item, with no descendant coverage.
+     *   Aggregate targets naming no selected item are rejected.
+     * - Exclusions retain descendant coverage unless noEvidenceExclude refuses them.
+     * - Duplicates and conflicts are evaluated per host. Different hosts may give
+     *   different answers to the same item.
+     * - Tags without a selected host answer nothing here. Report them only if no
+     *   other obligation consumes them.
+     * - Reject uniqueEvidence and singleEvidencePerSymbol at configuration time.
+     * - Exclusion-carrier globs require noEvidenceExclude alongside this option.
+     * - With requireReview, each answer is reviewed against that item's fingerprint;
+     *   changing an item expires the answers to it.
+     *
+     * @default false
+     */
+    checklist?: boolean;
+}

package/lib/structures/IEvidenceMarkdownReference.js

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

package/lib/structures/IEvidenceParserInput.d.ts

@@ -0,0 +1,31 @@
+import type { EvidenceDatabaseType } from "../typings/EvidenceDatabaseType";
+import type { EvidenceProgrammingType } from "../typings/EvidenceProgrammingType";
+/**
+ * Immutable source values supplied to a borrowed Tree-sitter parse session.
+ *
+ * The artifact type and logical filename select the syntax variant, while content
+ * comes from the source snapshot rather than another filesystem read. Keeping
+ * that boundary prevents parsing newer bytes than the inventory fingerprints.
+ */
+export interface IEvidenceParserInput {
+    /**
+     * Programming or database family whose grammar should parse the source.
+     *
+     * The language registry combines this family with the filename to select variants
+     * such as TypeScript versus TSX.
+     */
+    type: EvidenceProgrammingType | EvidenceDatabaseType;
+    /**
+     * Logical source filename used for grammar selection and error attribution.
+     *
+     * A selected symlink can have a different extension from its physical target;
+     * the selected spelling determines the syntax variant.
+     */
+    file: string;
+    /**
+     * Decoded snapshot text to parse without further file I/O.
+     *
+     * Session ranges address UTF-16 positions in this exact string.
+     */
+    content: string;
+}

package/lib/structures/IEvidenceParserInput.js

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

package/lib/structures/IEvidenceParserOptions.d.ts

@@ -0,0 +1,19 @@
+import type { tags } from "typia";
+/**
+ * Admission limits for a parser runtime's native resources.
+ *
+ * A slot remains occupied throughout grammar acquisition, parsing, and the
+ * asynchronous extraction callback. Bounding callbacks therefore also bounds
+ * live parser/tree ownership, rather than only the synchronous parse operation.
+ */
+export interface IEvidenceParserOptions {
+    /**
+     * Maximum number of admitted parse sessions at once.
+     *
+     * Additional requests wait in FIFO order. Omission permits four sessions;
+     * zero and non-integer values are rejected during runtime construction.
+     *
+     * @default 4
+     */
+    concurrency?: number & tags.Type<"uint32"> & tags.Minimum<1>;
+}

package/lib/structures/IEvidenceParserOptions.js

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

package/lib/structures/IEvidenceParserState.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Point-in-time view of a parser runtime's admission and grammar state.
+ *
+ * This supports lifecycle inspection without allocating a parser or loading a
+ * grammar. Closing prevents new admission before accepted work finishes, so a
+ * closed runtime can temporarily retain active sessions and queued requests.
+ */
+export interface IEvidenceParserState {
+    /**
+     * Number of currently reserved parse slots.
+     *
+     * A reservation includes asynchronous extraction work until its callback settles.
+     */
+    active: number;
+    /**
+     * Number of accepted requests waiting for an available slot.
+     *
+     * These requests remain eligible to run after close begins draining the queue.
+     */
+    waiting: number;
+    /**
+     * Sorted grammar IDs successfully loaded by this runtime.
+     *
+     * Pending or failed acquisitions are absent, even if other runtimes have loaded
+     * the same grammar into a process-wide cache.
+     */
+    languages: string[];
+    /**
+     * Whether the runtime has stopped accepting new requests.
+     *
+     * This flag does not by itself mean every previously accepted callback finished.
+     */
+    closed: boolean;
+}

package/lib/structures/IEvidenceParserState.js

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

package/lib/structures/IEvidencePopulation.d.ts

@@ -0,0 +1,63 @@
+import type { IEvidenceDiagnostic } from "./IEvidenceDiagnostic";
+import type { IEvidenceHost } from "./IEvidenceHost";
+import type { IEvidenceUnit } from "./IEvidenceUnit";
+/**
+ * A selected coverage denominator together with its addressable structural context.
+ *
+ * `EvidenceInventory.select` projects explicit unit IDs from reconciled adapter
+ * output. Required units, aggregate scopes, and withdrawn identities remain
+ * separate so target resolution can explain a citation without changing what
+ * the population requires. Hosts are narrowed to the selected semantic owners.
+ *
+ * For example, selecting `Client.send` can retain `Client` as an aggregate scope
+ * while requiring only the method. A citation to the class can cover that selected
+ * descendant through its real parent relationship; it does not add the class or
+ * unrelated siblings to the denominator.
+ *
+ * Completeness and diagnostics belong to the underlying analysis. Narrowing a
+ * selector cannot turn an incomplete inventory into a trustworthy population.
+ */
+export interface IEvidencePopulation {
+    /**
+     * Selected identities that remain eligible after withdrawal propagation.
+     *
+     * These units form the denominator. Several public aliases or declaration
+     * sites do not make one semantic identity contribute more than once.
+     */
+    units: IEvidenceUnit[];
+    /**
+     * Selected units and the real ancestors needed for aggregate lookup.
+     *
+     * Ancestors need not be selected requirements. The closure follows parent IDs,
+     * preserving literal name segments that happen to contain dots.
+     */
+    scopes: IEvidenceUnit[];
+    /**
+     * Withdrawn identities within the requested selection and its original scopes.
+     *
+     * These units cannot supply ordinary coverage. Resolution keeps them to
+     * distinguish a withdrawn target from an address that never existed.
+     */
+    hidden: IEvidenceUnit[];
+    /**
+     * Attached documentation positions owned by selected identities.
+     *
+     * Each host's owner list is narrowed to this population. Eligible hosts without
+     * tags remain necessary for policies that detect a host with zero evidence.
+     */
+    hosts: IEvidenceHost[];
+    /**
+     * Whether the underlying inventory was analyzed completely.
+     *
+     * This status is inherited even if all requested IDs happen to be present.
+     * Partial extraction cannot establish that the selected denominator is complete.
+     */
+    complete: boolean;
+    /**
+     * Findings from the inventory underlying this projection.
+     *
+     * Selection preserves these findings so a query can explain why a seemingly
+     * valid subset still cannot support a complete coverage evaluation.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+}

package/lib/structures/IEvidencePopulation.js

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

package/lib/structures/IEvidenceProgrammingClaim.d.ts

@@ -0,0 +1,28 @@
+import type { EvidenceProgrammingSymbol } from "../typings/EvidenceProgrammingSymbol";
+import type { EvidenceProgrammingType } from "../typings/EvidenceProgrammingType";
+import type { IEvidenceClaimBase } from "./IEvidenceClaimBase";
+/**
+ * Public programming declarations that cite evidence in documentation comments.
+ *
+ * The language adapter extracts declaration identity and documentation ownership
+ * before the configured symbol selector chooses claim hosts. This lets one
+ * policy require evidence from public functions while still recognizing an
+ * exclusion authored on another eligible declaration in the selected files.
+ *
+ * - Evidence needs a target, a nonempty reason, and a selected declaration host.
+ * - Exclusions may use any supported public declaration in a selected file,
+ *   regardless of the claim's symbol selector.
+ * - Unsupported or unexported declarations host neither form. A TypeScript
+ *   variable statement containing callable and data declarations can host both
+ *   function and property evidence.
+ *
+ * @example
+ * const claim: IEvidenceProgrammingClaim = {
+ *   type: "typescript",
+ *   files: ["src/*.ts"],
+ *   symbol: "function",
+ *   reference: { type: "markdown", files: ["requirements.md"] },
+ * };
+ */
+export interface IEvidenceProgrammingClaim extends IEvidenceClaimBase<EvidenceProgrammingType, EvidenceProgrammingSymbol> {
+}

package/lib/structures/IEvidenceProgrammingClaim.js

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

package/lib/structures/IEvidenceProgrammingReference.d.ts

@@ -0,0 +1,20 @@
+import type { EvidenceProgrammingSymbol } from "../typings/EvidenceProgrammingSymbol";
+import type { EvidenceProgrammingType } from "../typings/EvidenceProgrammingType";
+import type { IEvidenceReferenceBase } from "./IEvidenceReferenceBase";
+/**
+ * Public programming declarations required by an independent reference obligation.
+ *
+ * The configured language selects the adapter, and symbol selection determines
+ * which extracted identities enter the denominator. Structural ancestors remain
+ * resolvable for aggregate citations without becoming extra selected units.
+ */
+export interface IEvidenceProgrammingReference extends IEvidenceReferenceBase<EvidenceProgrammingType, EvidenceProgrammingSymbol> {
+    /**
+     * Source-file globs relative to the reference root.
+     *
+     * These use claim glob rules. Files are read from disk without requiring
+     * TypeScript Program membership or package-entry resolution.
+     * The type selects the language; file names identify variants such as TSX.
+     */
+    files: string[];
+}

package/lib/structures/IEvidenceProgrammingReference.js

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

package/lib/structures/IEvidencePublicAddress.d.ts

@@ -0,0 +1,21 @@
+import type { IEvidenceAddress } from "./IEvidenceAddress";
+/**
+ * A public citation address associated with one semantic declaration.
+ *
+ * Adapters publish direct paths and supported aliases or re-exports in this
+ * shape. Keeping the unit ID separate from the inherited file and accessor lets
+ * resolution preserve every public spelling without duplicating coverage units.
+ *
+ * An address exposes a declaration but does not establish its structural owner.
+ * Parent relationships remain on the unit, even when an alias changes the apparent
+ * nesting of the public path.
+ */
+export interface IEvidencePublicAddress extends IEvidenceAddress {
+    /**
+     * Semantic identity exposed through the inherited address.
+     *
+     * The ID must exist in the inventory. Multiple addresses may share it; an exact
+     * address associated with different IDs remains an ambiguous target.
+     */
+    unitId: string;
+}

package/lib/structures/IEvidencePublicAddress.js

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

package/lib/structures/IEvidenceQueryScope.d.ts

@@ -0,0 +1,41 @@
+import type { EvidenceArtifactType } from "../typings/EvidenceArtifactType";
+import type { EvidencePopulationRole } from "../typings/EvidencePopulationRole";
+/**
+ * Configuration boundary identifying a population in query output.
+ *
+ * One semantic unit can appear in several claims or references with different
+ * selections and policies. Role and authored indices distinguish those appearances
+ * while the optional name remains a display label rather than graph identity.
+ */
+export interface IEvidenceQueryScope {
+    /**
+     * Whether the population supplies claim hosts or required reference units.
+     *
+     * Reference scopes also carry an index within the owning claim.
+     */
+    role: EvidencePopulationRole;
+    /**
+     * Zero-based authored claim index containing the population.
+     *
+     * Planning preserves this index even when disabled entries are removed.
+     */
+    claim: number;
+    /**
+     * Authored reference index when the population belongs to a reference.
+     *
+     * Claim scopes omit it because they do not identify a particular requirement.
+     */
+    reference?: number;
+    /**
+     * Optional configured label for the population.
+     *
+     * Omission leaves role and indices sufficient to identify its boundary.
+     */
+    name?: string;
+    /**
+     * Artifact family whose extraction and target grammar apply to this population.
+     *
+     * Queries use it to filter list rows and choose compatible target resolution.
+     */
+    type: EvidenceArtifactType;
+}

package/lib/structures/IEvidenceQueryScope.js

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

package/lib/structures/IEvidenceReference.d.ts

@@ -0,0 +1,12 @@
+import type { IEvidenceDatabaseReference } from "./IEvidenceDatabaseReference";
+import type { IEvidenceMarkdownReference } from "./IEvidenceMarkdownReference";
+import type { IEvidenceProgrammingReference } from "./IEvidenceProgrammingReference";
+import type { IEvidenceSwaggerReference } from "./IEvidenceSwaggerReference";
+/**
+ * Artifact-specific evidence populations required by an owning claim.
+ *
+ * Each entry supplies its own selection, target grammar, and effective policy.
+ * Repeated entries are independent obligations rather than a union that allows
+ * coverage accepted in one reference to satisfy another automatically.
+ */
+export type IEvidenceReference = IEvidenceDatabaseReference | IEvidenceMarkdownReference | IEvidenceProgrammingReference | IEvidenceSwaggerReference;

package/lib/structures/IEvidenceReference.js

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