@wrtnlabs/evidence 0.0.0

package/lib/adapters/dbml/IDbmlDeclaration.d.ts

@@ -0,0 +1,38 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { EvidenceDatabaseSymbol } from "../../typings/EvidenceDatabaseSymbol";
+/** One declaration extracted from the DBML syntax tree.
+ *
+ * The scanner copies only stable declaration facts so later cross-file alias
+ * resolution can materialize units after the parser session is closed.
+ */
+export interface IDbmlDeclaration {
+    /** File-independent schema identity.
+     *
+     * This names semantic ownership and is deliberately distinct from a source
+     * range, which can appear in more than one selected file.
+     */
+    identity: string[];
+    /**
+     * Selects a model, scalar column, or separate relation declaration.
+     *
+     * The adapter maps this selector to the public database unit symbol.
+     */
+    symbol: EvidenceDatabaseSymbol;
+    /** Whitespace-independent syntax tokens excluding documentation.
+     *
+     * The adapter fingerprints this value so annotation edits do not invalidate
+     * the schema declaration they describe.
+     */
+    content: string;
+    /**
+     * Stores the exact original declaration span used for its physical site.
+     *
+     * This range anchors documentation and diagnostics in the selected source file.
+     */
+    range: IEvidenceSourceRange;
+    /** Explicit table alias, when declared.
+     *
+     * Omission means endpoint resolution uses the declaration's table identity.
+     */
+    alias?: string;
+}

package/lib/adapters/dbml/IDbmlDeclaration.js

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

package/lib/adapters/dbml/IDbmlDocumentation.d.ts

@@ -0,0 +1,34 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+/**
+ * Represents one DBML comment or note after its declaration owners are known.
+ *
+ * The scanner retains this carrier so later graph assembly can parse annotation
+ * tags without rediscovering DBML attachment rules.
+ */
+export interface IDbmlDocumentation {
+    /**
+     * Identifies declarations documented by this carrier.
+     *
+     * Each nested path preserves the literal DBML identity found by the scanner.
+     */
+    owners: string[][];
+    /**
+     * Locates the original comment or note string in the source file.
+     *
+     * Consumers use this range when reporting annotation syntax and diagnostics.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Covers complete annotation syntax excluded from semantic fingerprints.
+     *
+     * It can include delimiters outside the readable documentation range.
+     */
+    annotationRange: IEvidenceSourceRange;
+    /**
+     * Describes delimiters used to decode this documentation carrier.
+     *
+     * EvidenceDocumentation uses it to map decoded characters to source offsets.
+     */
+    syntax: IEvidenceCommentSyntax;
+}

package/lib/adapters/dbml/IDbmlDocumentation.js

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

package/lib/adapters/dbml/IDbmlEndpoint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Describes one ordered endpoint of a DBML relation awaiting resolution.
+ *
+ * The scanner preserves literal schema, table, and column segments so the
+ * resolver can match them against selected declarations across files.
+ */
+export interface IDbmlEndpoint {
+    /**
+     * Names the endpoint table with explicit schema and table segments.
+     *
+     * Omission of a DBML schema becomes the `public` schema before this value is stored.
+     */
+    table: string[];
+    /**
+     * Lists endpoint columns in composite-key order.
+     *
+     * Position pairs each local column with the column at the same position on the peer endpoint.
+     */
+    columns: string[];
+}

package/lib/adapters/dbml/IDbmlEndpoint.js

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

package/lib/adapters/dbml/IDbmlEnum.d.ts

@@ -0,0 +1,27 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+/**
+ * Retains DBML enum semantics that affect dependent table fingerprints.
+ *
+ * Enums are not independently selectable Evidence units, so their semantic
+ * content travels with declarations that refer to them.
+ */
+export interface IDbmlEnum {
+    /**
+     * Names the enum using its qualified DBML identity.
+     *
+     * Identifier spelling is preserved for matching table-field references.
+     */
+    identity: string[];
+    /**
+     * Stores whitespace-independent enum tokens without documentation.
+     *
+     * This value contributes schema meaning while ignoring annotation-only changes.
+     */
+    content: string;
+    /**
+     * Locates the enum declaration in the source file.
+     *
+     * Diagnostics use the range when an enum dependency cannot be applied.
+     */
+    range: IEvidenceSourceRange;
+}

package/lib/adapters/dbml/IDbmlEnum.js

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

package/lib/adapters/dbml/IDbmlFileAnalysis.d.ts

@@ -0,0 +1,56 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IDbmlDeclaration } from "./IDbmlDeclaration";
+import type { IDbmlDocumentation } from "./IDbmlDocumentation";
+import type { IDbmlEnum } from "./IDbmlEnum";
+import type { IDbmlRelation } from "./IDbmlRelation";
+/**
+ * Captures all DBML facts extracted from one source file.
+ *
+ * The adapter combines these serializable results after scanning every selected
+ * file, when cross-file relations and enum dependencies can resolve.
+ */
+export interface IDbmlFileAnalysis {
+    /**
+     * Provides the source snapshot that owns every range in this analysis.
+     *
+     * All ranges use this snapshot's UTF-16 offsets rather than normalized positions.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Lists table and column declarations established directly by DBML syntax.
+     *
+     * These declarations become candidates for later Evidence unit materialization.
+     */
+    declarations: IDbmlDeclaration[];
+    /**
+     * Lists relations whose endpoints still need selected-schema resolution.
+     *
+     * A relation may refer to declarations owned by another scanned file.
+     */
+    relations: IDbmlRelation[];
+    /**
+     * Retains mapped comments and notes, including unsupported attachment carriers.
+     *
+     * Later parsing can emit precise diagnostics instead of silently dropping annotations.
+     */
+    documentation: IDbmlDocumentation[];
+    /**
+     * Lists enum semantics required by affected table fingerprints.
+     *
+     * The adapter applies these nonselectable dependencies to referring declarations.
+     */
+    enums: IDbmlEnum[];
+    /**
+     * Records actionable parser failures and unsupported syntax.
+     *
+     * Consumers report these diagnostics before treating the file as complete.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether scanning understood every selected declaration.
+     *
+     * `false` prevents unsupported syntax from shrinking the coverage population.
+     */
+    complete: boolean;
+}

package/lib/adapters/dbml/IDbmlFileAnalysis.js

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

package/lib/adapters/dbml/IDbmlRelation.d.ts

@@ -0,0 +1,56 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IDbmlEndpoint } from "./IDbmlEndpoint";
+/** A pending relation whose owning table is resolved across selected files.
+ *
+ * DBML relation syntax can name aliases outside its physical file, so this
+ * record defers ownership and public-address materialization until all selected
+ * declarations are available.
+ */
+export interface IDbmlRelation {
+    /** Declared optional relation name.
+     *
+     * Omission leaves endpoint and cardinality data to establish identity.
+     */
+    name?: string;
+    /**
+     * Names the left endpoint, including the inline declaring column.
+     *
+     * The adapter resolves its table alias and selected column ownership.
+     */
+    from: IDbmlEndpoint;
+    /**
+     * Names the right endpoint paired with `from` in declared relation order.
+     *
+     * Composite columns remain ordered to preserve endpoint correspondence.
+     */
+    to: IDbmlEndpoint;
+    /**
+     * Stores declared cardinality for semantic identity and fingerprints.
+     *
+     * Direction and ownership selection depend on this DBML relation marker.
+     */
+    cardinality: string;
+    /**
+     * Indicates whether DBML inline one-to-one ownership rules apply.
+     *
+     * Omission means the relation uses an ordinary standalone declaration.
+     */
+    inline: boolean;
+    /** Semantic relation syntax excluding documentation.
+     *
+     * This excludes annotation carriers so review metadata cannot change relation
+     * fingerprint content.
+     */
+    content: string;
+    /**
+     * Stores the full declaration site; inline relations share their column site.
+     *
+     * Shared sites allow a single documentation carrier to attach to both units.
+     */
+    range: IEvidenceSourceRange;
+    /** Temporary syntax identity replaced after endpoint resolution.
+     *
+     * It exists only until cross-file aliases identify the relation's owner.
+     */
+    identity: string[];
+}

package/lib/adapters/dbml/IDbmlRelation.js

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

package/lib/adapters/ecmascript/EcmaScriptAdapter.d.ts

@@ -0,0 +1,71 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+import type { EcmaScriptType } from "./EcmaScriptType";
+/**
+ * Shares declaration, export, and JSDoc materialization between TypeScript and JavaScript.
+ *
+ * JavaScript first resolves file/package module modes; TypeScript uses its static
+ * module rules. File scanning records units and physical comment attachment, then
+ * export resolution determines which identities are publicly reachable within
+ * the configured root. Only afterward are annotations materialized as hosts and
+ * statements, preserving aliases without duplicating semantic declarations.
+ *
+ * Source, package-scope, and syntax failures all contribute to completeness.
+ * Package dependencies remain observable for watch, and each analysis owns its
+ * parser and copied input rather than retaining prior mutable inventories.
+ */
+export declare class EcmaScriptAdapter implements IEvidenceAdapter {
+    /**
+     * Language variant controlling grammar and publication semantics.
+     *
+     * JavaScript additionally resolves module modes from file/package context;
+     * TypeScript follows the selected TypeScript/TSX source forms.
+     */
+    readonly type: EcmaScriptType;
+    /**
+     * Human-readable language name included in extraction diagnostics.
+     *
+     * The discriminator supplies behavior; this label explains failures without
+     * changing identity, selection, or target resolution.
+     */
+    private readonly name;
+    /**
+     * Selects the language variant and diagnostic name for the shared pipeline.
+     *
+     * Public JavaScript and TypeScript entry points supply these fixed values.
+     * Construction itself performs no package resolution or grammar acquisition.
+     */
+    constructor(
+    /**
+     * Language variant controlling grammar and publication semantics.
+     *
+     * JavaScript additionally resolves module modes from file/package context;
+     * TypeScript follows the selected TypeScript/TSX source forms.
+     */
+    type: EcmaScriptType, 
+    /**
+     * Human-readable language name included in extraction diagnostics.
+     *
+     * The discriminator supplies behavior; this label explains failures without
+     * changing identity, selection, or target resolution.
+     */
+    name: string);
+    /**
+     * Extracts a fresh public module inventory from the supplied source snapshots.
+     *
+     * The input is copied before package resolution or parsing. Export reachability
+     * filters semantic units only after all local declarations are available, and
+     * failures remain in completeness and diagnostics. Native parser resources close
+     * whether publication succeeds or throws.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    private materializeComments;
+    private materializeUndocumentedHosts;
+    private host;
+    private parse;
+    private annotation;
+    private claimAnnotation;
+    private withdrawn;
+}