@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/prisma/EvidencePrismaSyntax.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidencePrismaSyntax = void 0;
+const LETTER = /^\p{L}$/u;
+const NUMBER = /^\p{N}$/u;
+/**
+ * Shared lexical rules that do not determine Prisma schema semantics.
+ *
+ * Target and position helpers use these checks for safe identifier spelling;
+ * the Prisma WASM parser remains the authority on whether a schema is valid.
+ */
+var EvidencePrismaSyntax;
+(function (EvidencePrismaSyntax) {
+    function identifier(value) {
+        const characters = Array.from(value);
+        const first = characters[0];
+        return (first !== undefined &&
+            initial(first) &&
+            characters
+                .slice(1)
+                .every((character) => initial(character) || character === "_" || character === "-"));
+    }
+    EvidencePrismaSyntax.identifier = identifier;
+    function initial(character) {
+        return LETTER.test(character) || NUMBER.test(character);
+    }
+})(EvidencePrismaSyntax || (exports.EvidencePrismaSyntax = EvidencePrismaSyntax = {}));

package/lib/adapters/prisma/EvidencePrismaTarget.d.ts

@@ -0,0 +1,11 @@
+import type { IEvidenceAddress } from "../../structures/IEvidenceAddress";
+/**
+ * Parses one file-independent Prisma model or member target.
+ *
+ * Prisma references use the `prisma:` prefix because their parser-established
+ * identities can span files, leaving the returned file key as a fixed
+ * namespace.
+ */
+export declare namespace EvidencePrismaTarget {
+    function parse(target: string): IEvidenceAddress;
+}

package/lib/adapters/prisma/EvidencePrismaTarget.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidencePrismaTarget = void 0;
+const EvidencePrismaSyntax_1 = require("./EvidencePrismaSyntax");
+/**
+ * Parses one file-independent Prisma model or member target.
+ *
+ * Prisma references use the `prisma:` prefix because their parser-established
+ * identities can span files, leaving the returned file key as a fixed
+ * namespace.
+ */
+var EvidencePrismaTarget;
+(function (EvidencePrismaTarget) {
+    function parse(target) {
+        if (!target.startsWith("prisma:"))
+            throw new Error("Start a Prisma target with 'prisma:'.");
+        const segments = target.slice("prisma:".length).split(".");
+        if ((segments.length !== 1 && segments.length !== 2) ||
+            segments.some((segment) => !EvidencePrismaSyntax_1.EvidencePrismaSyntax.identifier(segment)))
+            throw new Error("Use prisma:Model or prisma:Model.member with valid Prisma identifiers.");
+        return { file: "prisma:", segments };
+    }
+    EvidencePrismaTarget.parse = parse;
+})(EvidencePrismaTarget || (exports.EvidencePrismaTarget = EvidencePrismaTarget = {}));

package/lib/adapters/prisma/IEvidencePrismaBlockHead.d.ts

@@ -0,0 +1,22 @@
+/**
+ * One recognized Prisma top-level block declaration.
+ *
+ * The position scanner records only the head needed to associate parser-owned
+ * semantic models with their original source spans.
+ */
+export interface IEvidencePrismaBlockHead {
+    /**
+     * Prisma block kind, such as `model` or `view`.
+     *
+     * The position scanner combines this keyword with `name` to recognize only
+     * block forms that can be paired with parser-established semantic models.
+     */
+    keyword: string;
+    /**
+     * Declared block name following the recognized keyword.
+     *
+     * This authored spelling supplies the physical lookup key; semantic validity
+     * still belongs to the whole-schema parser rather than this lexical scan.
+     */
+    name: string;
+}

package/lib/adapters/prisma/IEvidencePrismaCacheEntry.d.ts

@@ -0,0 +1,25 @@
+import type { IEvidencePrismaModel } from "./IEvidencePrismaModel";
+/**
+ * Remembered Prisma parse outcome for one parser and schema digest.
+ *
+ * Parser version and complete schema content form the external cache key so
+ * stale parser behavior cannot be reused for a changed schema set.
+ */
+export interface IEvidencePrismaCacheEntry {
+    /**
+     * Parser-normalized models after a successful parse.
+     *
+     * A cache entry stores this branch for a parser-version and schema-set
+     * digest, allowing callers to receive a cloned semantic model without
+     * reparsing.
+     */
+    models?: IEvidencePrismaModel[];
+    /**
+     * Stable parser failure for the cached input when parsing failed.
+     *
+     * `EvidencePrismaModelLoader` rethrows this remembered diagnostic for the
+     * same cache key so repeated scans do not hide or reformat a deterministic
+     * parse error.
+     */
+    problem?: string;
+}

package/lib/adapters/prisma/IEvidencePrismaCommentRun.d.ts

@@ -0,0 +1,60 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { EvidencePrismaCommentForm } from "./EvidencePrismaCommentForm";
+/**
+ * Represents consecutive Prisma comments considered as one documentation run.
+ *
+ * The position scanner groups fragments before semantic parsing so downstream
+ * attachment can retain both the mapped text and the exact source comments.
+ */
+export interface IEvidencePrismaCommentRun {
+    /**
+     * Identifies the syntax form shared by comments in this run.
+     *
+     * The form determines whether the run can document a declaration or is kept
+     * as an unsupported or detached annotation carrier.
+     */
+    form: EvidencePrismaCommentForm;
+    /**
+     * Names the declaration location to which this run is attached.
+     *
+     * An empty key means no declaration received the run.
+     */
+    key: string;
+    /**
+     * Marks a documentation run attached to the schema file itself.
+     *
+     * This is true only for top-level `///` runs with no declaration key.
+     */
+    fileLevel: boolean;
+    /**
+     * Stores normalized run text in source-line order.
+     *
+     * Inserted newlines retain coordinate entries in `offsets` and `ends`.
+     */
+    text: string;
+    /**
+     * Maps each text character to its original UTF-16 start offset.
+     *
+     * The final sentinel maps the end of the run for mapped documentation.
+     */
+    offsets: number[];
+    /**
+     * Maps each text character to its original UTF-16 end offset.
+     *
+     * Its positions correspond to `offsets` and preserve source discontinuities.
+     */
+    ends: number[];
+    /**
+     * Covers the complete comment run in original source coordinates.
+     *
+     * This includes delimiters and line gaps between retained fragments.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Lists the physical range of each original comment fragment.
+     *
+     * Consumers use these ranges when a grouped run must report individual source
+     * carriers.
+     */
+    commentRanges: IEvidenceSourceRange[];
+}

package/lib/adapters/prisma/IEvidencePrismaDatamodel.d.ts

@@ -0,0 +1,17 @@
+import type { IEvidencePrismaDatamodelModel } from "./IEvidencePrismaDatamodelModel";
+/**
+ * Prisma parser payload needed by the Evidence adapter.
+ *
+ * Evidence deliberately consumes the parser's semantic model rather than
+ * inferring model structure from source text.
+ */
+export interface IEvidencePrismaDatamodel {
+    /**
+     * Parsed models and views in parser-provided order.
+     *
+     * `EvidencePrismaModelLoader` converts these semantic roots into detached
+     * Evidence models before later source scanning associates them with physical
+     * sites.
+     */
+    models: IEvidencePrismaDatamodelModel[];
+}

package/lib/adapters/prisma/IEvidencePrismaDatamodelField.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One resolved model member returned by Prisma's schema parser.
+ *
+ * This reduced parser payload contains only information that affects Evidence
+ * unit selection, documentation, and fingerprints.
+ */
+export interface IEvidencePrismaDatamodelField {
+    /**
+     * Parser-resolved field name within its owning model.
+     *
+     * The loader retains this parser-approved spelling for the model member's
+     * identity instead of attempting to classify source tokens independently.
+     */
+    name: string;
+    /**
+     * Parser classification used to select supported database members.
+     *
+     * `EvidencePrismaModelLoader` maps object fields to relations and every other
+     * retained field to columns when it creates the adapter's normalized field
+     * contract.
+     */
+    kind: string;
+    /**
+     * Parser-attached documentation, when source supplied it.
+     *
+     * `null` and omission both mean no parser documentation is available.
+     */
+    documentation?: string | null;
+}

package/lib/adapters/prisma/IEvidencePrismaDatamodelModel.d.ts

@@ -0,0 +1,31 @@
+import type { IEvidencePrismaDatamodelField } from "./IEvidencePrismaDatamodelField";
+/**
+ * One model or view returned by Prisma's schema parser.
+ *
+ * The loader later pairs this semantic result with a physical source location
+ * instead of treating parser output as an independently owned artifact.
+ */
+export interface IEvidencePrismaDatamodelModel {
+    /**
+     * Parser-resolved model or view name.
+     *
+     * This name joins a semantic model from the WASM parser to its separately
+     * scanned source declaration and to its materialized Evidence identity.
+     */
+    name: string;
+    /**
+     * Parser-attached block documentation when present.
+     *
+     * Omission or `null` means the parser found no block documentation;
+     * `EvidencePrismaModelLoader` normalizes both states to its detached empty
+     * text value.
+     */
+    documentation?: string | null;
+    /**
+     * Members belonging to this parser-established model.
+     *
+     * Their parser classifications are converted into Evidence columns or
+     * relations only after the containing model has been materialized.
+     */
+    fields: IEvidencePrismaDatamodelField[];
+}

package/lib/adapters/prisma/IEvidencePrismaField.d.ts

@@ -0,0 +1,40 @@
+import type { EvidenceDatabaseSymbol } from "../../typings/EvidenceDatabaseSymbol";
+/**
+ * One parser-classified Prisma model member.
+ *
+ * These detached records make the cross-file materializer independent of the
+ * WASM parser lifetime while preserving the member fingerprint boundary.
+ */
+export interface IEvidencePrismaField {
+    /**
+     * Name relative to the owning model identity.
+     *
+     * The materializer joins it with its containing model name to create the
+     * public address and semantic identity for this member.
+     */
+    name: string;
+    /**
+     * Evidence unit symbol selected from the parser field kind.
+     *
+     * Prisma scalar fields become columns and object fields become relations, so
+     * this normalized symbol controls selector matching without retaining WASM
+     * data.
+     */
+    symbol: Exclude<EvidenceDatabaseSymbol, "model">;
+    /**
+     * Documentation text used to recover directive and withdrawal state.
+     *
+     * The adapter parses this detached text after it establishes the field's
+     * host, keeping comment metadata separate from the semantic fingerprint
+     * payload.
+     */
+    documentation: string;
+    /**
+     * Semantic field digest excluding documentation metadata.
+     *
+     * Review fingerprints use this value to detect changes to the field itself
+     * without treating explanatory or Evidence annotation edits as semantic
+     * drift.
+     */
+    digest: string;
+}

package/lib/adapters/prisma/IEvidencePrismaFileAnalysis.d.ts

@@ -0,0 +1,33 @@
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidencePrismaCommentRun } from "./IEvidencePrismaCommentRun";
+import type { IEvidencePrismaLocation } from "./IEvidencePrismaLocation";
+/**
+ * Position-only scan of one Prisma schema source.
+ *
+ * This pass owns original ranges and comments; semantic declarations remain
+ * owned by the whole-schema parser result.
+ */
+export interface IEvidencePrismaFileAnalysis {
+    /**
+     * Immutable source snapshot whose coordinates the scan records.
+     *
+     * Every location and comment run in this analysis is valid only for this
+     * exact content and supplies its physical identity to later materialization.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Parser-matchable declaration spans in this physical file.
+     *
+     * These locations join parser-established model and field identities to their
+     * source sites without giving the position scanner semantic ownership.
+     */
+    locations: IEvidencePrismaLocation[];
+    /**
+     * Consecutive comment runs available for documentation attachment.
+     *
+     * Attachment logic uses these physical comment ranges to find eligible
+     * carriers after the parser result has identified the declaration they can
+     * document.
+     */
+    comments: IEvidencePrismaCommentRun[];
+}

package/lib/adapters/prisma/IEvidencePrismaLineParts.d.ts

@@ -0,0 +1,30 @@
+import type { IEvidencePrismaPendingComment } from "./IEvidencePrismaPendingComment";
+/**
+ * Splits one Prisma source line into structural code and comment state.
+ *
+ * `EvidencePrismaFileScanner` carries the block-comment state to the next line
+ * while using `code` alone to locate declarations and braces.
+ */
+export interface IEvidencePrismaLineParts {
+    /**
+     * Contains source characters that remain structural code on this line.
+     *
+     * Comment delimiters and comment content are excluded so quoted or commented
+     * braces cannot change the scanner's nesting depth.
+     */
+    code: string;
+    /**
+     * Retains the comment fragment found on this line.
+     *
+     * Omission means the line contains no comment content, including continued
+     * block-comment state with no retained text.
+     */
+    comment?: IEvidencePrismaPendingComment;
+    /**
+     * States whether a block comment remains open after this line.
+     *
+     * The next call uses this state to avoid treating comment text as Prisma
+     * syntax.
+     */
+    commented: boolean;
+}

package/lib/adapters/prisma/IEvidencePrismaLoadResult.d.ts

@@ -0,0 +1,24 @@
+import type { IEvidencePrismaModel } from "./IEvidencePrismaModel";
+/**
+ * Parsed schema units beside the whole-set cache identity.
+ *
+ * Prisma resolves relations across schema files, so the cache and parser result
+ * belong to the selected file set rather than an individual source file.
+ */
+export interface IEvidencePrismaLoadResult {
+    /**
+     * Semantic models materialized from the entire selected schema set.
+     *
+     * Prisma resolves relations across files, so this collection belongs to the
+     * complete parser input rather than to one selected physical source file.
+     */
+    models: IEvidencePrismaModel[];
+    /**
+     * Digest identifying the parser version and complete selected source set.
+     *
+     * The loader returns this cache identity with its models so callers can
+     * retain a result only while every selected schema source and parser version
+     * agree.
+     */
+    digest: string;
+}

package/lib/adapters/prisma/IEvidencePrismaLocatedDeclaration.d.ts

@@ -0,0 +1,23 @@
+import type { IEvidencePrismaFileAnalysis } from "./IEvidencePrismaFileAnalysis";
+import type { IEvidencePrismaLocation } from "./IEvidencePrismaLocation";
+/**
+ * Couples a Prisma semantic declaration location with its source analysis.
+ *
+ * Consumers resolve parser-established identities through this pair without
+ * asking the position scanner to decide which Prisma declarations are valid.
+ */
+export interface IEvidencePrismaLocatedDeclaration {
+    /**
+     * Supplies source-wide locations and comment runs for the declaration.
+     *
+     * The analysis owns coordinate maps and remains the authority for its
+     * physical source snapshot.
+     */
+    analysis: IEvidencePrismaFileAnalysis;
+    /**
+     * Identifies the parser-matched physical span within that analysis.
+     *
+     * Its key connects the semantic parser result to a concrete declaration site.
+     */
+    location: IEvidencePrismaLocation;
+}

package/lib/adapters/prisma/IEvidencePrismaLocation.d.ts

@@ -0,0 +1,23 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+/**
+ * Source position found for one parser-established Prisma identity.
+ *
+ * Keys connect semantic parser output to physical content without making source
+ * scanning guess which declarations the Prisma parser accepts.
+ */
+export interface IEvidencePrismaLocation {
+    /**
+     * Adapter identity key for the model or model member at this location.
+     *
+     * Materialization uses this key to join a lexical declaration span with the
+     * semantic parser result without reinterpreting Prisma schema syntax.
+     */
+    key: string;
+    /**
+     * Exact physical source range used for the materialized site.
+     *
+     * The resulting Evidence site owns this range for diagnostics, fingerprints,
+     * and documentation attachment in the immutable source snapshot.
+     */
+    range: IEvidenceSourceRange;
+}

package/lib/adapters/prisma/IEvidencePrismaModel.d.ts

@@ -0,0 +1,38 @@
+import type { IEvidencePrismaField } from "./IEvidencePrismaField";
+/**
+ * One parser-normalized Prisma model or view.
+ *
+ * The model is the ownership root for materialized members and exposes only
+ * detached semantic data that can safely outlive the parser call.
+ */
+export interface IEvidencePrismaModel {
+    /**
+     * Public Prisma model or view name.
+     *
+     * This parser-normalized name forms the root of each model and member
+     * identity that the adapter later exposes through its Evidence inventory.
+     */
+    name: string;
+    /**
+     * Block documentation used for model-level review metadata.
+     *
+     * The empty string means the parser supplied no documentation; later
+     * attachment still uses the physical scanner to decide whether a carrier is
+     * eligible.
+     */
+    documentation: string;
+    /**
+     * Semantic block digest excluding documentation directives.
+     *
+     * This content contribution lets reviews detect a changed model declaration
+     * while annotations and prose do not alter the semantic fingerprint.
+     */
+    digest: string;
+    /**
+     * Parser-classified members owned by this model.
+     *
+     * The model owns their identity hierarchy, while each field retains a
+     * separate normalized symbol, documentation text, and semantic digest.
+     */
+    fields: IEvidencePrismaField[];
+}

package/lib/adapters/prisma/IEvidencePrismaOwnedUnit.d.ts

@@ -0,0 +1,39 @@
+import type { IEvidenceUnit } from "../../structures/IEvidenceUnit";
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+/**
+ * Prisma unit beside the parser documentation used to recover withdrawal state.
+ *
+ * Ownership is kept explicitly because unit materialization needs both semantic
+ * output and the comment text that established its review state.
+ */
+export interface IEvidencePrismaOwnedUnit {
+    /**
+     * Identity joining the unit to position and documentation records.
+     *
+     * This key connects parser-owned semantic output with the physical scan that
+     * establishes the site and comment carrier for the materialized unit.
+     */
+    key: string;
+    /**
+     * Parser documentation associated with this semantic unit.
+     *
+     * Withdrawal and review handling reads this value after it establishes a
+     * host, preserving the parser's documentation independently of source
+     * coordinates.
+     */
+    documentation: string;
+    /**
+     * Materialized public or internal Evidence unit.
+     *
+     * This unit carries the semantic identity and selection state that graph
+     * evaluation consumes after the Prisma adapter completes materialization.
+     */
+    unit: IEvidenceUnit;
+    /**
+     * Physical declaration site that owns the unit fingerprint.
+     *
+     * The site preserves position and content ranges from the scanner, which are
+     * required to compare review fingerprints against authored source changes.
+     */
+    site: IEvidenceUnitSite;
+}

package/lib/adapters/prisma/IEvidencePrismaParser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Resolved Prisma WASM parser and its diagnostic identity.
+ *
+ * The adapter records the parser implementation identity in cache keys because
+ * parser upgrades can change semantic output for unchanged schema text.
+ */
+export interface IEvidencePrismaParser {
+    /**
+     * Parses the complete schema parameter payload into serialized JSON.
+     *
+     * `EvidencePrismaModelLoader` supplies every selected file in the parser's
+     * expected payload shape, then validates the returned JSON as
+     * `IEvidencePrismaDatamodel`.
+     */
+    getDatamodel(parameters: string): string;
+    /**
+     * Parser version contributing to the whole-schema cache identity.
+     *
+     * A version change invalidates cached semantic output even when selected
+     * source content has not changed, because parser behavior can alter the
+     * datamodel.
+     */
+    version: string;
+    /**
+     * Human-readable implementation origin for diagnostics.
+     *
+     * The loader reports whether resolution selected the consumer project or the
+     * Evidence package copy when parser loading or parsing fails.
+     */
+    origin: string;
+}

package/lib/adapters/prisma/IEvidencePrismaPendingComment.d.ts

@@ -0,0 +1,61 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { EvidencePrismaCommentForm } from "./EvidencePrismaCommentForm";
+/**
+ * Retains one Prisma comment fragment before it is grouped into a run.
+ *
+ * The line scanner records text and coordinate maps separately so grouping can
+ * insert line breaks without losing the original source positions.
+ */
+export interface IEvidencePrismaPendingComment {
+    /**
+     * Identifies the source syntax used for this comment fragment.
+     *
+     * Documentation runs distinguish `///` comments from ordinary lines and block
+     * comments using this form.
+     */
+    form: EvidencePrismaCommentForm;
+    /**
+     * Gives the zero-based source line that contains this fragment.
+     *
+     * Runs use it to preserve blank lines between comments.
+     */
+    line: number;
+    /**
+     * Stores the trimmed comment content without delimiters.
+     *
+     * Its characters correspond positionally to `offsets` and `ends`.
+     */
+    text: string;
+    /**
+     * Maps content characters to original UTF-16 start offsets.
+     *
+     * Whitespace trimming removes matching entries from this map.
+     */
+    offsets: number[];
+    /**
+     * Maps content characters to original UTF-16 end offsets.
+     *
+     * Entries preserve the source boundaries of the retained text.
+     */
+    ends: number[];
+    /**
+     * Covers the original comment syntax, including its delimiters.
+     *
+     * This range remains available even when trimming leaves no content.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Marks a comment that follows structural code on the same line.
+     *
+     * Trailing comments never attach as leading documentation for the next
+     * declaration.
+     */
+    trailing: boolean;
+    /**
+     * Marks a comment discovered while scanner depth is zero.
+     *
+     * This distinguishes eligible file-level documentation from a detached run
+     * nested inside a schema block.
+     */
+    topLevel: boolean;
+}

package/lib/adapters/prisma/IEvidencePrismaSchemaFile.d.ts

@@ -0,0 +1,24 @@
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+/**
+ * One deduplicated physical schema file and its parser-facing name.
+ *
+ * Parser-facing names provide stable schema-set references while the source
+ * snapshot remains the owner of content, digest, and physical coordinates.
+ */
+export interface IEvidencePrismaSchemaFile {
+    /**
+     * Unique normalized name supplied to the multi-file parser.
+     *
+     * The parser uses this stable schema-set key for cross-file resolution; it is
+     * derived independently of the source snapshot's physical filesystem path.
+     */
+    name: string;
+    /**
+     * Selected source snapshot represented by that parser-facing name.
+     *
+     * Its content enters the parser payload, while its digest and physical
+     * identity remain available for cache keys and later location
+     * materialization.
+     */
+    source: IEvidenceSourceFile;
+}

package/lib/adapters/prisma/IEvidenceTrimmedMapping.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Couples trimmed text with the coordinates of its retained characters.
+ *
+ * Prisma comment normalization uses this temporary value to remove surrounding
+ * whitespace without severing the documentation text from its source offsets.
+ */
+export interface IEvidenceTrimmedMapping {
+    /**
+     * Contains the retained text after leading and trailing whitespace removal.
+     *
+     * An empty value has empty coordinate arrays.
+     */
+    text: string;
+    /**
+     * Maps each retained character to its original UTF-16 start offset.
+     *
+     * Entries align one-for-one with `text`.
+     */
+    offsets: number[];
+    /**
+     * Maps each retained character to its original UTF-16 end offset.
+     *
+     * Entries align with `offsets` and preserve the source span of every
+     * character.
+     */
+    ends: number[];
+}