@wrtnlabs/evidence 0.0.0

package/lib/internal/IEvaluateTypeScriptConfigOptions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Optional diagnostic routing for isolated TypeScript configuration evaluation.
+ *
+ * `evaluateTypeScriptConfig` passes this sink to its child evaluator so callers
+ * can collect or redirect compiler and runtime output without changing the
+ * evaluated configuration result.
+ */
+export interface IEvaluateTypeScriptConfigOptions {
+    /**
+     * Receives each stdout or stderr chunk emitted by the evaluator process.
+     *
+     * When omitted, evaluation writes diagnostics to the parent process's stderr
+     * and preserves the child process's original formatting.
+     */
+    writeDiagnostic?: ((content: string) => void) | undefined;
+}

package/lib/internal/IEvaluateTypeScriptConfigOptions.js

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

package/lib/internal/IEvidenceMaterializedClaim.d.ts

@@ -0,0 +1,47 @@
+import type { IEvidenceConfigPlanClaim } from "../structures/IEvidenceConfigPlanClaim";
+import type { IEvidenceInventory } from "../structures/IEvidenceInventory";
+import type { IEvidenceMaterializedReference } from "./IEvidenceMaterializedReference";
+/**
+ * One enabled claim with the inventories needed to resolve its acknowledgements.
+ *
+ * This record belongs to a single analysis pass. It retains configuration order
+ * and selected identities so later graph construction never needs to rediscover
+ * files or reinterpret a mutable user configuration.
+ */
+export interface IEvidenceMaterializedClaim {
+    /**
+     * Validated, enabled claim policy that owns this population's configuration position.
+     *
+     * Later graph construction reads its effective policy without revisiting the
+     * mutable configuration document that produced this analysis pass.
+     */
+    plan: IEvidenceConfigPlanClaim;
+    /**
+     * Extracted claim inventory, including contextual units outside the denominator.
+     *
+     * Structural parents remain available for host and withdrawal decisions even
+     * when only the selected units contribute claim obligations.
+     */
+    inventory: IEvidenceInventory;
+    /**
+     * Semantic identities selected by the claim, in configured selection order.
+     *
+     * This collection is the claim denominator and remains narrower than the
+     * inventory's contextual population.
+     */
+    unitIds: string[];
+    /**
+     * Hosts that may carry exclusions when exclusion scope differs from selected units.
+     *
+     * Omission means the selected unit IDs also define every eligible exclusion
+     * host, so graph processing needs no separate structural population.
+     */
+    exclusionHostIds?: string[];
+    /**
+     * Reference inventories evaluated against this claim in authored reference order.
+     *
+     * The order preserves independent configuration occurrences for diagnostics
+     * and query rows even when they resolve to overlapping identities.
+     */
+    references: IEvidenceMaterializedReference[];
+}

package/lib/internal/IEvidenceMaterializedClaim.js

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

package/lib/internal/IEvidenceMaterializedReference.d.ts

@@ -0,0 +1,31 @@
+import type { IEvidenceConfigPlanReference } from "../structures/IEvidenceConfigPlanReference";
+import type { IEvidenceInventory } from "../structures/IEvidenceInventory";
+/**
+ * One enabled reference population after source extraction.
+ *
+ * References preserve their own inventory because identical semantic IDs may be
+ * addressed under different roots, symbols, and severity policies.
+ */
+export interface IEvidenceMaterializedReference {
+    /**
+     * Validated configuration and effective severity for this reference occurrence.
+     *
+     * The graph preserves this plan entry separately when repeated references share
+     * an inventory but have distinct authored positions or inherited policy.
+     */
+    plan: IEvidenceConfigPlanReference;
+    /**
+     * Extracted reference inventory used for target lookup and ancestor closure.
+     *
+     * It remains attached to this occurrence because the same unit identity can
+     * have a different public address under another configured population.
+     */
+    inventory: IEvidenceInventory;
+    /**
+     * Identities selected as referenceable units by this population.
+     *
+     * Their order follows the configured selection and defines the denominator
+     * before structural ancestors are added for context.
+     */
+    unitIds: string[];
+}

package/lib/internal/IEvidenceMaterializedReference.js

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

package/lib/internal/IEvidenceQueryPopulation.d.ts

@@ -0,0 +1,43 @@
+import type { IEvidenceGraphObligation } from "../structures/IEvidenceGraphObligation";
+import type { IEvidenceGraphReference } from "../structures/IEvidenceGraphReference";
+import type { IEvidenceInventory } from "../structures/IEvidenceInventory";
+import type { IEvidenceQueryScope } from "../structures/IEvidenceQueryScope";
+/**
+ * Population input used to construct a reusable query index.
+ *
+ * Claim entries provide source and selection context; reference entries additionally
+ * join effective graph policy and evaluated coverage. All records belong to the
+ * containing query facade's owned analysis snapshot.
+ */
+export interface IEvidenceQueryPopulation {
+    /**
+     * Authored configuration boundary and population role.
+     *
+     * This distinguishes repeated references when query rows share semantic identities.
+     */
+    scope: IEvidenceQueryScope;
+    /**
+     * Extracted inventory supplying units, addresses, and structural parents.
+     *
+     * It can contain unselected units needed for context and exact target inspection.
+     */
+    inventory: IEvidenceInventory;
+    /**
+     * Configured semantic selection in its retained order.
+     *
+     * The query index derives ancestor closure separately rather than extending this denominator.
+     */
+    unitIds: string[];
+    /**
+     * Effective reference input when this population represents a requirement.
+     *
+     * Claim populations omit it; reference queries use it to present policy details.
+     */
+    reference?: IEvidenceGraphReference;
+    /**
+     * Evaluated coverage ledger for a reference population.
+     *
+     * Omission on claim entries means reference coverage cannot be inferred from them.
+     */
+    obligation?: IEvidenceGraphObligation;
+}

package/lib/internal/IEvidenceQueryPopulation.js

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

package/lib/internal/IEvidenceResolvedAcknowledgement.d.ts

@@ -0,0 +1,30 @@
+import type { IEvidenceDeclaration } from "../structures/IEvidenceDeclaration";
+/**
+ * An authored acknowledgement after target resolution.
+ *
+ * Resolution stores host identities separately from the target because one
+ * physical annotation can cover multiple selected descendants.
+ */
+export interface IEvidenceResolvedAcknowledgement {
+    /**
+     * Original acknowledgement declaration retained after target resolution.
+     *
+     * Diagnostics and reports use its authored wording and source position rather
+     * than reconstructing either from the resolved unit IDs.
+     */
+    declaration: IEvidenceDeclaration;
+    /**
+     * Claim units represented by the declaration's structural host.
+     *
+     * One physical annotation can acknowledge each selected descendant in this
+     * collection while retaining its single authored declaration record.
+     */
+    hostUnitIds: string[];
+    /**
+     * Unique reference unit named by the acknowledgement target.
+     *
+     * Resolution assigns this ID only after rejecting missing or ambiguous target
+     * spellings, allowing graph evaluation to link the two populations directly.
+     */
+    targetUnitId: string;
+}

package/lib/internal/IEvidenceResolvedAcknowledgement.js

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

package/lib/internal/IEvidenceResolvedReview.d.ts

@@ -0,0 +1,30 @@
+import type { IEvidenceReview } from "../structures/IEvidenceReview";
+/**
+ * A review annotation paired with its resolved reference target and claim hosts.
+ *
+ * Reviews retain the authored record so reporting can distinguish a missing
+ * review from an invalid target without re-parsing source text.
+ */
+export interface IEvidenceResolvedReview {
+    /**
+     * Original review declaration and source position.
+     *
+     * Reporting retains the authored annotation so an invalid review target can be
+     * distinguished from an absent review without reparsing its source file.
+     */
+    review: IEvidenceReview;
+    /**
+     * Claim units whose structural scope contains the review host.
+     *
+     * One review declaration can apply to multiple selected descendants that share
+     * its structural host position.
+     */
+    hostUnitIds: string[];
+    /**
+     * Reference unit named by the review target.
+     *
+     * The resolver assigns this identity after proving the target is unique within
+     * the configured reference population.
+     */
+    targetUnitId: string;
+}

package/lib/internal/IEvidenceResolvedReview.js

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

package/lib/internal/IEvidenceTargetBody.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The target token and remaining authored explanation from one annotation body.
+ *
+ * Splitting happens before artifact-specific parsing so whitespace in prose
+ * cannot alter a target's grammar or its diagnostic location.
+ */
+export interface IEvidenceTargetBody {
+    /**
+     * Non-whitespace target token as authored, before target resolution.
+     *
+     * Artifact-specific target parsing consumes this spelling while its original
+     * boundary remains available for precise diagnostics.
+     */
+    target: string;
+    /**
+     * Trimmed explanatory prose after the target.
+     *
+     * It may be empty and never participates in target grammar, selection, or
+     * resolution.
+     */
+    remainder: string;
+}

package/lib/internal/IEvidenceTargetBody.js

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

package/lib/internal/IEvidenceTargetCandidate.d.ts

@@ -0,0 +1,23 @@
+import type { IEvidenceAddress } from "../structures/IEvidenceAddress";
+import type { IEvidenceResolution } from "../structures/IEvidenceResolution";
+/**
+ * Public address paired with its exact inventory lookup result.
+ *
+ * Target resolution can derive several addresses from a host's retained origins.
+ * Keeping each address beside its lookup outcome permits candidate aggregation
+ * without losing which spelling produced a visible, hidden, or missing match.
+ */
+export interface IEvidenceTargetCandidate {
+    /**
+     * Concrete public file key and accessor segments submitted to inventory lookup.
+     *
+     * This is already parsed under the applicable artifact target grammar.
+     */
+    address: IEvidenceAddress;
+    /**
+     * Lookup outcome within the selected reference's structural scope.
+     *
+     * The resolver combines candidates by semantic identity before deciding uniqueness.
+     */
+    resolution: IEvidenceResolution;
+}

package/lib/internal/IEvidenceTargetCandidate.js

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

package/lib/internal/IEvidenceUnhostedChecklist.d.ts

@@ -0,0 +1,38 @@
+import type { IEvidenceDeclaration } from "../structures/IEvidenceDeclaration";
+import type { EvidenceSeverity } from "../typings/EvidenceSeverity";
+/**
+ * A checklist annotation awaiting host assignment.
+ *
+ * Checklists are held while other declarations establish structural ownership,
+ * preventing a source-order coincidence from discarding a valid obligation.
+ */
+export interface IEvidenceUnhostedChecklist {
+    /**
+     * Authored checklist declaration retained for later attachment or diagnostics.
+     *
+     * The graph holds this source record until structural ownership establishes
+     * which selected claim units its host can affect.
+     */
+    declaration: IEvidenceDeclaration;
+    /**
+     * Effective severity after claim and reference policy inheritance.
+     *
+     * This resolved value lets later attachment report the applicable policy
+     * without repeating policy inheritance.
+     */
+    severity: EvidenceSeverity;
+    /**
+     * Index of the owning claim in the resolved configuration plan.
+     *
+     * It preserves the claim occurrence that supplied this checklist when plans
+     * contain repeated populations.
+     */
+    claim: number;
+    /**
+     * Index of the owning reference within that claim.
+     *
+     * Together with {@link claim}, this identifies the configured reference whose
+     * severity and selection apply to the deferred checklist.
+     */
+    reference: number;
+}

package/lib/internal/IEvidenceUnhostedChecklist.js

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

package/lib/internal/IEvidenceWatchAttempt.d.ts

@@ -0,0 +1,39 @@
+import type { IEvidenceSourceDependency } from "../structures/IEvidenceSourceDependency";
+import type { EvidenceWatchCycle } from "../typings/EvidenceWatchCycle";
+import type { WatchDependencySnapshot } from "./WatchDependencySnapshot";
+/**
+ * Stable unpublished result and dependency baseline for one watch attempt.
+ *
+ * Publication compares this snapshot after evaluation, preventing source edits
+ * during an asynchronous check from being reported as a coherent cycle.
+ */
+export interface IEvidenceWatchAttempt {
+    /**
+     * Completed check or operational failure produced by the attempt.
+     *
+     * Watch publication exposes this result only after verifying that its captured
+     * dependencies still match the associated snapshot.
+     */
+    cycle: EvidenceWatchCycle;
+    /**
+     * Full dependency set whose changes invalidate the unpublished result.
+     *
+     * This includes source and recoverable-missing dependencies needed to observe
+     * repairs as well as ordinary content edits.
+     */
+    dependencies: IEvidenceSourceDependency[];
+    /**
+     * Captured versions proving those dependencies stayed stable during evaluation.
+     *
+     * Comparing this snapshot before publication prevents an asynchronous check
+     * from reporting a result for an already changed source graph.
+     */
+    snapshot: WatchDependencySnapshot;
+    /**
+     * Whether parser preparation failed and should be retried independently of source edits.
+     *
+     * A true value schedules recovery for transient parser setup failures even
+     * when no watched source dependency changes.
+     */
+    retryParser: boolean;
+}

package/lib/internal/IEvidenceWatchAttempt.js

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

package/lib/internal/IFileGlobPattern.d.ts

@@ -0,0 +1,22 @@
+/**
+ * One normalized include or exclusion rule in the ordered Evidence glob program.
+ *
+ * `FileGlob` creates these records while compiling configured file patterns,
+ * then applies them in order to determine a path's current inclusion decision.
+ */
+export interface IFileGlobPattern {
+    /**
+     * Portable relative path segments interpreted by the limited glob matcher.
+     *
+     * Compilation removes the exclusion marker and normalizes separators before
+     * storing these tokens, so matching never depends on host path separators.
+     */
+    segments: string[];
+    /**
+     * Whether a matching rule clears the current inclusion decision.
+     *
+     * This is true for patterns authored with `!`; a later positive rule can
+     * restore a path because `FileGlob` evaluates every rule in declaration order.
+     */
+    exclude: boolean;
+}

package/lib/internal/IFileGlobPattern.js

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

package/lib/internal/IPackageManifest.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Installed Evidence package manifest fields required by the version command.
+ *
+ * `EvidenceCommand` validates this narrow projection before reporting its own
+ * package version, keeping malformed installed metadata an actionable command
+ * failure instead of loading project configuration.
+ */
+export interface IPackageManifest {
+    /**
+     * Published package version presented by the command.
+     *
+     * This value comes from the installed package manifest and is returned as the
+     * version command's output rather than being derived from the running project.
+     */
+    version: string;
+}

package/lib/internal/IPackageManifest.js

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

package/lib/internal/IPendingEvidenceTag.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A recognized documentation annotation before semantic attachment.
+ *
+ * Parser offsets remain relative to normalized documentation so the mapper can
+ * recover the original source range after multiline bodies are assembled.
+ */
+export interface IPendingEvidenceTag {
+    /**
+     * Annotation spelling, including link and review variants with distinct later rules.
+     *
+     * Attachment dispatch uses this value to choose target parsing and graph
+     * handling without re-reading the normalized documentation text.
+     */
+    kind: "evidence" | "link" | "evidenceExclude" | "evidenceReview" | "evidenceExcludeReview";
+    /**
+     * Continued body text without the tag marker.
+     *
+     * The mapper joins continuation lines before target parsing while retaining
+     * offsets into the normalized documentation carrier.
+     */
+    body: string;
+    /**
+     * Inclusive UTF-16 offset of the annotation in normalized documentation.
+     *
+     * Source mapping combines this boundary with the carrier's normalized text to
+     * recover the authored location for diagnostics.
+     */
+    start: number;
+    /**
+     * Exclusive UTF-16 offset immediately after the tag's continued body.
+     *
+     * Together with {@link start}, this forms the half-open annotation range used
+     * when translating normalized offsets back to source positions.
+     */
+    end: number;
+}

package/lib/internal/IPendingEvidenceTag.js

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

package/lib/internal/ITreeSitterAssetLock.d.ts

@@ -0,0 +1,23 @@
+import type { tags } from "typia";
+/**
+ * Serialized ownership record for one cross-process grammar cache transfer.
+ *
+ * The token prevents an old owner from deleting a lock reacquired after a crash;
+ * the PID permits stale-lock recovery when that owner is no longer alive.
+ */
+export interface ITreeSitterAssetLock {
+    /**
+     * Positive operating-system process ID that acquired the transfer lock.
+     *
+     * Stale-lock recovery checks whether this owner remains alive before allowing
+     * another process to replace the serialized cache record.
+     */
+    pid: number & tags.Type<"uint32"> & tags.Minimum<1>;
+    /**
+     * Random acquisition token checked before releasing a lock with the same path.
+     *
+     * It prevents a former owner from deleting a lock that another process
+     * acquired after crash recovery reused the path.
+     */
+    token: string;
+}

package/lib/internal/ITreeSitterAssetLock.js

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

package/lib/internal/ITreeSitterAssetOptions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Execution-local controls for immutable grammar acquisition.
+ *
+ * These options influence one caller's cache and transfer lifetime; they do
+ * not alter catalog provenance or the bytes accepted into the shared cache.
+ */
+export interface ITreeSitterAssetOptions {
+    /**
+     * Writable root for the immutable grammar cache.
+     *
+     * Omission first uses `EVIDENCE_CACHE_DIR`, then the platform user's cache
+     * location. `TreeSitterAssetCache` places verified grammar bytes below this
+     * root and never treats it as catalog provenance.
+     */
+    cacheDirectory?: string;
+    /**
+     * HTTP transport used to fetch a missing grammar asset.
+     *
+     * Omission uses the platform fetch implementation. Tests and embedding callers
+     * can supply a transport without changing checksum verification or cache keys.
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Maximum duration of one transfer, including its response body, in milliseconds.
+     *
+     * Omission defaults to 30 seconds. The limit applies to each attempt rather
+     * than the caller's complete retry lifetime.
+     */
+    timeoutMilliseconds?: number;
+    /**
+     * Maximum transfer attempts allowed for transient acquisition failures.
+     *
+     * Omission defaults to three. Shared callers join one immutable transfer, so
+     * this bound controls its retries instead of multiplying requests per caller.
+     */
+    attempts?: number;
+    /**
+     * Signal that stops this caller's wait for a grammar acquisition.
+     *
+     * Aborting one waiter does not cancel other callers sharing the immutable
+     * transfer; the cache cancels transfer work only after every waiter leaves.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Caller-owned sink for grammar acquisition progress messages.
+     *
+     * Omission keeps library acquisition silent. The cache reports progress through
+     * this callback without writing to process output or changing transfer results.
+     */
+    progress?: ((message: string) => void) | undefined;
+}

package/lib/internal/ITreeSitterAssetOptions.js

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

package/lib/internal/ITreeSitterAssetPending.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One process-wide transfer shared by callers targeting the same immutable cache entry.
+ *
+ * Consumer accounting lets an individual cancellation return promptly while
+ * transfer work continues for peers, then aborts only after the final waiter leaves.
+ */
+export interface ITreeSitterAssetPending {
+    /**
+     * Promise for verified bytes after successful atomic cache publication.
+     *
+     * Each joining caller awaits this shared result, so checksum verification and
+     * publication run once for the immutable cache entry.
+     */
+    promise: Promise<Uint8Array>;
+    /**
+     * Controller that cancels transfer work after every waiting consumer leaves.
+     *
+     * A single caller's cancellation removes only its own wait and leaves the
+     * shared transfer available to remaining consumers.
+     */
+    controller: AbortController;
+    /**
+     * Number of callers still awaiting this transfer's result.
+     *
+     * Asset-cache cancellation decrements this count and aborts the controller
+     * only when it reaches zero.
+     */
+    consumers: number;
+}

package/lib/internal/ITreeSitterAssetPending.js

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

package/lib/internal/ITtsxExecutables.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Executable mapping from the consumer-installed `ttsc` package manifest.
+ *
+ * The isolated configuration evaluator reads this projection through
+ * `ITtsxManifest` so it can invoke the consumer's compiler launcher instead of
+ * resolving a tool from Evidence's own dependency graph.
+ */
+export interface ITtsxExecutables {
+    /**
+     * Relative path to the `ttsx` launcher within the installed `ttsc` package.
+     *
+     * The evaluator resolves this path against the manifest directory before it
+     * starts the temporary project that evaluates the user's configuration.
+     */
+    ttsx: string;
+}

package/lib/internal/ITtsxExecutables.js

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

package/lib/internal/ITtsxManifest.d.ts

@@ -0,0 +1,17 @@
+import type { ITtsxExecutables } from "./ITtsxExecutables";
+/**
+ * Consumer-installed `ttsc` manifest fields required for isolated configuration evaluation.
+ *
+ * `evaluateTypeScriptConfig` validates this narrow manifest projection after
+ * resolving `ttsc` from the config's dependency graph, then uses its executable
+ * mapping to start the matching `ttsx` launcher.
+ */
+export interface ITtsxManifest {
+    /**
+     * Declared executable names and relative paths from the installed package.
+     *
+     * The evaluator consumes the `ttsx` entry in this mapping through
+     * `ITtsxExecutables`; no other package manifest fields affect the launch.
+     */
+    bin: ITtsxExecutables;
+}

package/lib/internal/ITtsxManifest.js

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