@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/dbml/DbmlFileScanner.js

@@ -1,364 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DbmlFileScanner = void 0;
-/**
- * Extracts DBML schema facts from audited structural parser nodes.
- *
- * It records unsupported syntax as incomplete so selection cannot silently omit
- * declarations the adapter does not understand.
- */
-class DbmlFileScanner {
-    session;
-    /**
-     * Accumulates the serializable analysis for this source file.
-     *
-     * Later adapter stages resolve its relations, enum dependencies, and documentation carriers.
-     */
-    output;
-    /**
-     * Maps parser-node offsets to declaration identities they own.
-     *
-     * Notes and comments use this map to attach only at the matching syntax level.
-     */
-    owners = new Map();
-    /**
-     * Tracks line comments already included in a contiguous documentation carrier.
-     *
-     * Each comment can contribute to at most one attachment run.
-     */
-    comments = new Set();
-    /**
-     * Binds the parsed DBML session and its immutable source snapshot.
-     *
-     * Parser nodes are used only during extraction; the returned result contains serializable facts.
-     */
-    constructor(session, source) {
-        this.session = session;
-        this.output = {
-            source,
-            declarations: [],
-            relations: [],
-            documentation: [],
-            enums: [],
-            diagnostics: [],
-            complete: true,
-        };
-    }
-    /**
-     * Extracts top-level DBML constructs and their documentation attachments.
-     *
-     * A complete result contains every recognized declaration and explicit unsupported-syntax diagnostic.
-     */
-    scan() {
-        for (const node of this.session.root.namedChildren) {
-            if (node.type === "definition")
-                this.table(node);
-            else if (node.type === "reference")
-                this.relation(node);
-            else if (node.type === "enum")
-                this.enumeration(node);
-            else if (node.type === "table_partial" || node.type === "table_group")
-                this.problem(node, `DBML ${node.type} is outside the declared schema boundary. Expand reusable partials and remove groups from selected schema files before checking coverage.`);
-            else if (node.type !== "comment" && node.type !== "project")
-                this.problem(node, `Unsupported DBML construct '${node.type}'. Add adapter support before checking coverage.`);
-        }
-        for (const capture of this.session.captures("(comment) @comment"))
-            this.comment(capture.node);
-        for (const capture of this.session.captures("(note) @note"))
-            this.note(capture.node);
-        for (const capture of this.session.captures("(attribute) @attribute")) {
-            const identifier = capture.node.namedChildren.find((child) => child.type === "identifier");
-            if (identifier !== undefined &&
-                /^(ref|note|default)$/iu.test(identifier.text))
-                this.problem(capture.node, "A reserved DBML ref/note/default setting is missing its required value. Correct the setting before checking coverage.");
-        }
-        return this.output;
-    }
-    /**
-     * Retains enum semantic dependencies and validates their members.
-     *
-     * Duplicate values make the declared schema ambiguous for dependent fingerprints.
-     */
-    enumeration(node) {
-        const name = node.childForFieldName("name");
-        if (name === null)
-            throw new Error("A DBML enum has no name.");
-        const values = node.namedChildren
-            .filter((child) => child.type === "enum_item")
-            .map((child) => child.namedChildren.find((entry) => entry.type === "identifier"))
-            .filter((entry) => entry !== undefined)
-            .map((entry) => this.identifier(entry));
-        if (new Set(values).size !== values.length)
-            this.problem(node, "A DBML enum repeats a value. Use distinct enum values before checking coverage.");
-        this.output.enums.push({
-            identity: this.tableName(name),
-            content: this.semantic(node),
-            range: this.session.range(node),
-        });
-    }
-    /**
-     * Publishes a table and scalar columns directly owned by it.
-     *
-     * Nested constructs are handled separately so each declaration has an unambiguous owner.
-     */
-    table(node) {
-        const name = node.childForFieldName("name");
-        const body = node.childForFieldName("body");
-        if (name === null || body === null)
-            throw new Error("A DBML table has no name or body.");
-        const identity = this.tableName(name);
-        const alias = node.childForFieldName("alias");
-        this.output.declarations.push({
-            identity,
-            symbol: "model",
-            content: this.semantic(node),
-            range: this.session.range(node),
-            ...(alias === null ? {} : { alias: this.identifier(alias) }),
-        });
-        this.owners.set(node.startIndex, [identity]);
-        this.owners.set(body.startIndex, [identity]);
-        for (const child of body.namedChildren) {
-            if (child.type === "partial_injection") {
-                this.problem(child, "DBML partial injection can change columns and relations. Expand the partial in selected source or implement partial resolution before checking coverage.");
-                continue;
-            }
-            if (child.type !== "item")
-                continue;
-            const columnName = child.childForFieldName("name");
-            if (columnName === null)
-                throw new Error("A DBML column has no name.");
-            const column = [...identity, this.identifier(columnName)];
-            const owners = [column];
-            this.output.declarations.push({
-                identity: column,
-                symbol: "column",
-                content: this.semantic(child),
-                range: this.session.range(child),
-            });
-            this.owners.set(child.startIndex, owners);
-            for (const ref of child.descendantsOfType("inline_ref")) {
-                const key = ["$relation", String(ref.startIndex)];
-                owners.push(key);
-                const target = ref.namedChildren.find((entry) => entry.type === "column");
-                const cardinality = ref.namedChildren.find((entry) => entry.type === "cardinality");
-                if (target === undefined || cardinality === undefined)
-                    throw new Error("An inline DBML relation has no endpoint or cardinality.");
-                this.output.relations.push({
-                    identity: key,
-                    from: { table: identity, columns: [this.identifier(columnName)] },
-                    to: this.endpoint(target),
-                    cardinality: cardinality.text,
-                    inline: true,
-                    content: this.semantic(ref),
-                    range: this.session.range(child),
-                });
-            }
-        }
-    }
-    /**
-     * Retains relation endpoints until selected-schema declarations are available.
-     *
-     * Cross-file resolution occurs after every DBML source has been scanned.
-     */
-    relation(node) {
-        const body = node.namedChildren.find((child) => child.type === "relationship");
-        if (body === undefined)
-            throw new Error("A DBML relation has no body.");
-        const from = body.childForFieldName("from");
-        const to = body.childForFieldName("to");
-        const cardinality = body.namedChildren.find((child) => child.type === "cardinality");
-        if (from === null || to === null || cardinality === undefined)
-            throw new Error("A DBML relation has incomplete endpoints.");
-        const identity = ["$relation", String(node.startIndex)];
-        const name = node.childForFieldName("name");
-        this.owners.set(node.startIndex, [identity]);
-        this.output.relations.push({
-            identity,
-            ...(name === null ? {} : { name: this.identifier(name) }),
-            from: this.endpoint(from),
-            to: this.endpoint(to),
-            cardinality: cardinality.text,
-            inline: false,
-            content: this.semantic(node),
-            range: this.session.range(node),
-        });
-    }
-    /**
-     * Reads literal endpoint segments without resolving semantic existence.
-     *
-     * Deferring lookup permits relations between declarations in separate source files.
-     */
-    endpoint(node) {
-        const table = node.childForFieldName("table");
-        const columns = node.childForFieldName("columns");
-        if (table === null || columns === null)
-            throw new Error("A DBML endpoint is incomplete.");
-        return {
-            table: this.tableName(table),
-            columns: columns.type === "identifier"
-                ? [this.identifier(columns)]
-                : columns.namedChildren
-                    .filter((child) => child.type === "identifier")
-                    .map((child) => this.identifier(child)),
-        };
-    }
-    /**
-     * Builds a table identity while applying DBML's implicit public schema.
-     *
-     * Literal identifier dots remain part of their quoted segments rather than path separators.
-     */
-    tableName(node) {
-        const schema = node.namedChildren.find((child) => child.type === "schema");
-        const name = node.namedChildren.find((child) => child.type === "identifier");
-        const schemaName = schema === undefined
-            ? undefined
-            : schema.namedChildren.find((child) => child.type === "identifier");
-        if (name === undefined)
-            throw new Error("A DBML table identifier is incomplete.");
-        return [
-            schemaName === undefined ? "public" : this.identifier(schemaName),
-            this.identifier(name),
-        ];
-    }
-    /**
-     * Decodes quoted identifiers without altering their case or punctuation.
-     *
-     * Literal spelling is required to preserve the DBML identity used by resolution.
-     */
-    identifier(node) {
-        const text = node.text;
-        return text.startsWith('"')
-            ? text.slice(1, -1).replace(/\\(.)/gu, "$1")
-            : text;
-    }
-    /**
-     * Attaches adjacent comments only to a recognized declaration at the same level.
-     *
-     * This prevents comments inside nested syntax from documenting an enclosing declaration.
-     */
-    comment(node) {
-        if (this.comments.has(node.startIndex))
-            return;
-        const block = node.text.startsWith("/*");
-        let last = node;
-        if (!block && this.standalone(node))
-            while (last.nextNamedSibling?.type === "comment" &&
-                last.nextNamedSibling.text.startsWith("//") &&
-                this.standalone(last.nextNamedSibling) &&
-                this.adjacent(last, last.nextNamedSibling)) {
-                last = last.nextNamedSibling;
-                this.comments.add(last.startIndex);
-            }
-        let current = last;
-        let next = last.nextNamedSibling;
-        let adjacent = true;
-        while (next?.type === "comment") {
-            adjacent &&= this.adjacent(current, next);
-            current = next;
-            next = next.nextNamedSibling;
-        }
-        const owners = next === null ||
-            !this.standalone(node) ||
-            !adjacent ||
-            !this.adjacent(current, next)
-            ? []
-            : (this.owners.get(next.startIndex) ?? []);
-        const range = {
-            start: this.session.range(node).start,
-            end: this.session.range(last).end,
-        };
-        this.output.documentation.push({
-            owners,
-            range,
-            annotationRange: range,
-            syntax: {
-                opening: block ? "/*" : "//",
-                closing: block ? "*/" : "",
-                linePrefix: block ? "*" : "//",
-                tagBoundaries: true,
-                allowWithdrawal: owners.length !== 0,
-            },
-        });
-    }
-    /**
-     * Distinguishes trailing comments from leading documentation runs.
-     *
-     * A comment must start on otherwise blank text before it can attach forward.
-     */
-    standalone(node) {
-        const start = this.output.source.content.lastIndexOf("\n", node.startIndex - 1) + 1;
-        return (this.output.source.content.slice(start, node.startIndex).trim() === "");
-    }
-    /**
-     * Checks that a documentation run reaches its next declaration without a blank line.
-     *
-     * Separation means the comment has no unambiguous declaration owner.
-     */
-    adjacent(previous, next) {
-        const gap = this.output.source.content.slice(previous.endIndex, next.startIndex);
-        return gap.trim() === "" && (gap.match(/\n/gu)?.length ?? 0) <= 1;
-    }
-    /**
-     * Attaches supported table and column notes to their owners.
-     *
-     * Notes on enums, indexes, and projects remain explicit unsupported annotation carriers.
-     */
-    note(node) {
-        const value = node.namedChildren.find((child) => child.type === "string");
-        if (value === undefined)
-            throw new Error("A DBML note has no string value.");
-        let parent = node.parent;
-        if (parent?.type === "setting")
-            parent = parent.parent;
-        const owners = parent === null ? [] : (this.owners.get(parent.startIndex) ?? []);
-        const delimiter = value.text.startsWith("'''") ? "'''" : "'";
-        this.output.documentation.push({
-            owners,
-            range: this.session.range(value),
-            annotationRange: this.session.range(node),
-            syntax: {
-                opening: delimiter,
-                closing: delimiter,
-                tagBoundaries: true,
-                allowWithdrawal: owners.length !== 0,
-            },
-        });
-    }
-    /**
-     * Serializes enum semantics without including annotations.
-     *
-     * Documentation acknowledges declarations but does not change the enum fingerprint.
-     */
-    semantic(node) {
-        if (node.type === "comment" || node.type === "note")
-            return "";
-        if (node.type === "setting" &&
-            node.namedChildren.every((child) => child.type === "note" || child.type === "comment"))
-            return "";
-        if (node.childCount === 0)
-            return node.type === "," ? "" : node.text;
-        return node.children
-            .map((child) => this.semantic(child))
-            .filter((text) => text !== "")
-            .join("\u0000");
-    }
-    /**
-     * Marks unsupported source as incomplete and records a repairable diagnostic.
-     *
-     * The failure protects coverage from passing against a reduced obligation set.
-     */
-    problem(node, message) {
-        this.output.complete = false;
-        this.output.diagnostics.push({
-            code: "dbml-unsupported-syntax",
-            severity: "error",
-            message,
-            repair: "Add support for this construct or expand it to supported DBML declarations.",
-            location: {
-                file: this.output.source.physicalPath,
-                range: this.session.range(node),
-            },
-        });
-    }
-}
-exports.DbmlFileScanner = DbmlFileScanner;

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

@@ -1,38 +0,0 @@
-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/IDbmlDocumentation.d.ts

@@ -1,34 +0,0 @@
-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/IDbmlEndpoint.d.ts

@@ -1,20 +0,0 @@
-/**
- * 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/IDbmlEnum.d.ts

@@ -1,27 +0,0 @@
-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/IDbmlFileAnalysis.d.ts

@@ -1,56 +0,0 @@
-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/IDbmlRelation.d.ts

@@ -1,56 +0,0 @@
-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/ecmascript/EcmaScriptAdapter.d.ts

@@ -1,71 +0,0 @@
-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;
-}