@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/dbml/EvidenceDbmlFileScanner.js

@@ -0,0 +1,381 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceDbmlFileScanner = 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 EvidenceDbmlFileScanner {
+    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.EvidenceDbmlFileScanner = EvidenceDbmlFileScanner;

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

@@ -0,0 +1,43 @@
+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 IEvidenceDbmlDeclaration {
+    /**
+     * 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/IEvidenceDbmlDocumentation.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 IEvidenceDbmlDocumentation {
+    /**
+     * 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/IEvidenceDbmlEndpoint.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 IEvidenceDbmlEndpoint {
+    /**
+     * 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/IEvidenceDbmlEnum.d.ts

@@ -0,0 +1,28 @@
+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 IEvidenceDbmlEnum {
+    /**
+     * 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/IEvidenceDbmlFileAnalysis.d.ts

@@ -0,0 +1,61 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceDbmlDeclaration } from "./IEvidenceDbmlDeclaration";
+import type { IEvidenceDbmlDocumentation } from "./IEvidenceDbmlDocumentation";
+import type { IEvidenceDbmlEnum } from "./IEvidenceDbmlEnum";
+import type { IEvidenceDbmlRelation } from "./IEvidenceDbmlRelation";
+/**
+ * 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 IEvidenceDbmlFileAnalysis {
+    /**
+     * 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: IEvidenceDbmlDeclaration[];
+    /**
+     * Lists relations whose endpoints still need selected-schema resolution.
+     *
+     * A relation may refer to declarations owned by another scanned file.
+     */
+    relations: IEvidenceDbmlRelation[];
+    /**
+     * Retains mapped comments and notes, including unsupported attachment
+     * carriers.
+     *
+     * Later parsing can emit precise diagnostics instead of silently dropping
+     * annotations.
+     */
+    documentation: IEvidenceDbmlDocumentation[];
+    /**
+     * Lists enum semantics required by affected table fingerprints.
+     *
+     * The adapter applies these nonselectable dependencies to referring
+     * declarations.
+     */
+    enums: IEvidenceDbmlEnum[];
+    /**
+     * 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/IEvidenceDbmlRelation.d.ts

@@ -0,0 +1,60 @@
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceDbmlEndpoint } from "./IEvidenceDbmlEndpoint";
+/**
+ * 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 IEvidenceDbmlRelation {
+    /**
+     * 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: IEvidenceDbmlEndpoint;
+    /**
+     * Names the right endpoint paired with `from` in declared relation order.
+     *
+     * Composite columns remain ordered to preserve endpoint correspondence.
+     */
+    to: IEvidenceDbmlEndpoint;
+    /**
+     * 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[];
+}