@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/sql/EvidenceSqlFileScanner.js

@@ -0,0 +1,313 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSqlFileScanner = void 0;
+const EvidenceSourceText_1 = require("../../internal/EvidenceSourceText");
+const EvidenceSqlPolicy_1 = require("./EvidenceSqlPolicy");
+/**
+ * Extracts explicit SQL table declarations from a shared upstream syntax tree.
+ *
+ * The scanner records serializable declarations and comment carriers under a
+ * dialect policy. Unsupported syntax makes the analysis incomplete so omitted
+ * declarations cannot shrink the coverage population.
+ */
+class EvidenceSqlFileScanner {
+    session;
+    source;
+    policy;
+    /**
+     * Holds the mutable serializable result owned by this scan.
+     *
+     * Helpers append records and failures here before `scan` returns the final
+     * node-free analysis.
+     */
+    output;
+    /**
+     * Initializes one scan over a borrowed parse session and source snapshot.
+     *
+     * The default policy supplies generic SQL behavior; dialect adapters provide
+     * another policy when quoting, identities, or relation syntax differ.
+     */
+    constructor(session, source, policy = EvidenceSqlPolicy_1.EvidenceSqlPolicy) {
+        this.session = session;
+        this.source = source;
+        this.policy = policy;
+        this.output = {
+            source,
+            declarations: [],
+            documentation: [],
+            diagnostics: [],
+            complete: true,
+        };
+    }
+    /**
+     * Visits statements and comments, then returns their serializable analysis.
+     *
+     * Validation precedes extraction so unsupported constructs record a failure
+     * instead of yielding a deceptively complete smaller inventory.
+     */
+    scan() {
+        for (const root of this.session.root.namedChildren) {
+            if (this.comment(root))
+                continue;
+            const statement = root.type === "statement"
+                ? root.namedChildren.find((child) => !this.comment(child))
+                : root;
+            if (statement === undefined)
+                continue;
+            const problem = this.policy.validate(statement);
+            if (problem !== undefined) {
+                this.problem(statement, problem);
+                continue;
+            }
+            if (statement.type === "create_table")
+                this.table(statement);
+        }
+        const comments = this.session.root.descendantsOfType([
+            "comment",
+            "marginalia",
+        ]);
+        for (const comment of comments) {
+            const problem = this.policy.validate(comment);
+            if (problem !== undefined)
+                this.problem(comment, problem);
+        }
+        this.documentation(comments);
+        return this.output;
+    }
+    /**
+     * Extracts one table with its explicit columns and foreign-key relations.
+     *
+     * Endpoint checks require declared local columns and explicit remote columns
+     * because inferred schema state would make relation identity unreliable.
+     */
+    table(node) {
+        const reference = node.namedChildren.find((child) => child.type === "object_reference");
+        const columns = node.namedChildren.find((child) => child.type === "column_definitions");
+        if (reference === undefined || columns === undefined) {
+            this.problem(node, "An explicit table name and column list are required.");
+            return;
+        }
+        const address = this.reference(reference);
+        if (address === undefined)
+            return;
+        const table = this.declaration(node, "model", address);
+        const members = columns.namedChildren.filter((child) => child.type === "column_definition");
+        const declared = new Set();
+        for (const column of members) {
+            const name = column.childForFieldName("name");
+            const value = name === null ? undefined : this.identifier(name);
+            if (value === undefined)
+                continue;
+            declared.add(value);
+            const unit = this.declaration(column, "column", [...address, value], table);
+            if (column.namedChildren.some((child) => child.type === "keyword_references")) {
+                if (this.policy.inlineReferences === "reject")
+                    this.problem(column, "Inline REFERENCES is unsupported by this dialect policy.");
+                else if (this.policy.inlineReferences !== "ignore")
+                    this.relation(column, table, [value], unit);
+            }
+        }
+        for (const constraint of columns.descendantsOfType("constraint")) {
+            if (!constraint.namedChildren.some((child) => child.type === "keyword_references"))
+                continue;
+            if (!constraint.namedChildren.some((child) => child.type === "keyword_foreign")) {
+                this.problem(constraint, "Only FOREIGN KEY constraints can declare relations.");
+                continue;
+            }
+            const ordered = constraint.namedChildren.find((child) => child.type === "ordered_columns");
+            const local = ordered === undefined
+                ? undefined
+                : ordered
+                    .descendantsOfType("identifier")
+                    .map((child) => this.identifier(child));
+            if (local === undefined ||
+                local.length === 0 ||
+                local.some((name) => name === undefined || !declared.has(name))) {
+                this.problem(constraint, "Foreign-key endpoints must name explicit columns of their owning table.");
+                continue;
+            }
+            this.relation(constraint, table, local.filter((name) => name !== undefined));
+        }
+    }
+    /**
+     * Extracts a relation with explicit local and remote endpoint identities.
+     *
+     * Unnamed relations derive a stable segment from their endpoints; inline
+     * relations share their column's physical site for documentation ownership.
+     */
+    relation(node, table, local, column) {
+        const children = node.namedChildren;
+        const keyword = children.findIndex((child) => child.type === "keyword_references");
+        const target = children
+            .slice(keyword + 1)
+            .find((child) => child.type === "object_reference");
+        if (target === undefined) {
+            this.problem(node, "Foreign keys require an explicit referenced table.");
+            return;
+        }
+        const decodedRemote = this.reference(target);
+        const remoteTable = decodedRemote === undefined
+            ? undefined
+            : (this.policy.reference?.(decodedRemote, table.address) ??
+                decodedRemote);
+        const remoteNodes = children.filter((child) => child.type === "identifier" && child.startIndex >= target.endIndex);
+        const remote = remoteNodes.map((child) => this.identifier(child));
+        if (remoteTable === undefined ||
+            remote.length !== local.length ||
+            remote.some((name) => name === undefined)) {
+            this.problem(node, "Foreign keys require explicit local and referenced column lists with equal cardinality.");
+            return;
+        }
+        const name = node.childForFieldName("name");
+        const constraintName = this.policy.constraintNames !== false &&
+            column === undefined &&
+            name !== null
+            ? this.identifier(name)
+            : undefined;
+        const member = constraintName === undefined
+            ? `foreign-key:${JSON.stringify(local)}->${JSON.stringify(remoteTable)}(${JSON.stringify(remote)})`
+            : `constraint:${constraintName}`;
+        const relation = this.declaration(node, "relation", [...table.address, member], table);
+        // An inline relation shares its physical column site, making attached documentation acknowledge both declarations.
+        if (column !== undefined)
+            relation.site = structuredClone(column.site);
+    }
+    /**
+     * Creates one physical declaration record and records its model ownership.
+     *
+     * A policy can project public address spelling into a separate semantic
+     * identity without changing the source location retained in the record.
+     */
+    declaration(node, symbol, address, owner) {
+        const range = this.session.range(node);
+        const id = `${this.source.id}:${symbol}:${node.startIndex}`;
+        const record = {
+            id,
+            name: address.at(-1) ?? "",
+            symbol,
+            identity: this.policy.identity?.(address, symbol) ?? address,
+            address,
+            public: true,
+            site: {
+                id: `${id}:site`,
+                file: this.source.physicalPath,
+                range,
+                content: [range],
+            },
+            ...(owner === undefined ? {} : { ownerDeclarationId: owner.id }),
+        };
+        this.output.declarations.push(record);
+        return record;
+    }
+    /**
+     * Decodes a qualified reference into separate address segments.
+     *
+     * Individual identifier decoding preserves quoted dots as literal name
+     * content rather than treating them as extra path boundaries.
+     */
+    reference(node) {
+        const names = node.namedChildren
+            .filter((child) => child.type === "identifier")
+            .map((child) => this.identifier(child));
+        return names.length === 0 || names.some((name) => name === undefined)
+            ? undefined
+            : names.filter((name) => name !== undefined);
+    }
+    /**
+     * Decodes a dialect identifier and reports unsupported spelling.
+     *
+     * Returning no name prevents callers from inventing an address outside the
+     * dialect contract.
+     */
+    identifier(node) {
+        const name = this.policy.identifier(node.text);
+        if (name === undefined)
+            this.problem(node, "This identifier is outside the configured SQL dialect's quoting and name rules.");
+        return name;
+    }
+    /**
+     * Groups adjacent line comments and attaches leading runs to declaration
+     * sites.
+     *
+     * Detached and trailing carriers remain in the result so annotation handling
+     * can report them without attaching them to a later declaration.
+     */
+    documentation(nodes) {
+        const text = new EvidenceSourceText_1.EvidenceSourceText(this.source.content);
+        const groups = [];
+        for (const node of nodes) {
+            const range = this.session.range(node);
+            const previous = groups.at(-1);
+            if (node.type === "comment" &&
+                previous !== undefined &&
+                this.standalone(previous.range.start.offset) &&
+                this.standalone(range.start.offset) &&
+                this.source.content.slice(previous.range.start.offset, previous.range.start.offset + 2) === "--" &&
+                /^[ \t]*\r?\n[ \t]*$/u.test(this.source.content.slice(previous.range.end.offset, range.start.offset))) {
+                previous.range = text.range(previous.range.start.offset, range.end.offset);
+            }
+            else
+                groups.push({
+                    id: `${this.source.id}:documentation:${node.startIndex}`,
+                    range,
+                    attachments: [],
+                });
+        }
+        for (const documentation of groups) {
+            const start = documentation.range.start.offset;
+            // Trailing comments never document the next table or column.
+            if (this.standalone(start)) {
+                const next = this.output.declarations
+                    .filter((entry) => entry.site.range.start.offset >= documentation.range.end.offset)
+                    .sort((left, right) => left.site.range.start.offset - right.site.range.start.offset)[0];
+                if (next !== undefined &&
+                    /^[ \t]*(?:\r?\n[ \t]*)?$/u.test(this.source.content.slice(documentation.range.end.offset, next.site.range.start.offset)))
+                    documentation.attachments = this.output.declarations
+                        .filter((entry) => entry.site.range.start.offset === next.site.range.start.offset)
+                        .map((entry) => ({
+                        declarationId: entry.id,
+                        siteId: entry.site.id,
+                    }));
+            }
+            this.output.documentation.push(documentation);
+        }
+    }
+    /**
+     * Checks whether a comment starts before any source token on its line.
+     *
+     * Only such a standalone comment can be leading documentation.
+     */
+    standalone(start) {
+        const line = this.source.content.lastIndexOf("\n", start - 1) + 1;
+        return this.source.content.slice(line, start).trim() === "";
+    }
+    /**
+     * Identifies grammar nodes that represent SQL comments.
+     *
+     * Tree-sitter classification avoids mistaking comment-looking SQL literal
+     * text for documentation syntax.
+     */
+    comment(node) {
+        return node.type === "comment" || node.type === "marginalia";
+    }
+    /**
+     * Records a located unsupported construct and marks the result incomplete.
+     *
+     * This failure prevents partial extraction from being accepted as complete
+     * evidence coverage.
+     */
+    problem(node, message) {
+        this.output.complete = false;
+        this.output.diagnostics.push({
+            code: "sql-unsupported-syntax",
+            severity: "error",
+            message,
+            repair: "Use the documented explicit DDL subset or implement the configured dialect's missing syntax before checking coverage.",
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.EvidenceSqlFileScanner = EvidenceSqlFileScanner;

package/lib/adapters/sql/EvidenceSqlInventoryMaterializer.d.ts

@@ -0,0 +1,129 @@
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+import type { IEvidenceSqlAdapterOptions } from "./IEvidenceSqlAdapterOptions";
+/**
+ * Materializes SQL-family inventories using an explicitly selected dialect
+ * scanner.
+ *
+ * Dialect options own parsing and optional cross-file ownership resolution.
+ * This shared layer manages parser lifetime, semantic declaration grouping,
+ * public addresses, and documentation materialization. It analyzes source
+ * declarations without connecting to a database or executing the supplied SQL.
+ */
+export declare class EvidenceSqlInventoryMaterializer {
+    /**
+     * Dialect-specific grammar discriminator and extraction hooks.
+     *
+     * The resolver, when present, runs after all file scans and before unit
+     * publication.
+     */
+    private readonly options;
+    /**
+     * Selects a dialect scanner and its optional cross-file ownership resolver.
+     *
+     * Construction records extraction policy without loading source or allocating
+     * a parser runtime; analyze owns those resources for each snapshot.
+     */
+    constructor(
+    /**
+     * Dialect-specific grammar discriminator and extraction hooks.
+     *
+     * The resolver, when present, runs after all file scans and before unit
+     * publication.
+     */
+    options: IEvidenceSqlAdapterOptions);
+    /**
+     * Builds an owned SQL inventory through dialect scanning and shared
+     * materialization.
+     *
+     * Source and parser failures retain incomplete state. Optional ownership
+     * resolution precedes public grouping and annotation attachment, and native
+     * parser resources close in cleanup after accepted scans settle.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    /**
+     * Publishes public schema identities with explicit parents and physical
+     * aliases.
+     *
+     * Source-local declaration IDs are mapped before parents are assigned.
+     * Repeated declarations require an explicit merge allowance; otherwise a
+     * conflict remains a diagnostic instead of silently combining independent
+     * schema definitions.
+     */
+    private materializeUnits;
+    /**
+     * Resolves withdrawals before publishing attached annotation hosts.
+     *
+     * Hidden declaration sites cannot receive claim or review hosts in the
+     * inventory.
+     */
+    private materializeDocumentation;
+    /**
+     * Retains public declaration sites even when they carry no documentation.
+     *
+     * These hosts keep missing documentation visible to later graph evaluation.
+     */
+    private materializeUndocumentedHosts;
+    /**
+     * Groups published semantic owners by their physical declaration site.
+     *
+     * One comment can attach to merged declarations that share a single source
+     * range.
+     */
+    private attachmentGroups;
+    /**
+     * Creates an attached or explicitly unsupported documentation carrier.
+     *
+     * Unsupported carriers remain materialized so diagnostics can direct users to
+     * a valid site.
+     */
+    private host;
+    /**
+     * Parses Evidence tags only after the adapter establishes their host.
+     *
+     * Tag parsing needs the resolved host identity and attachment decision.
+     */
+    private parse;
+    /**
+     * Detects Evidence or withdrawal annotations outside masked examples.
+     *
+     * The result retains otherwise detached carriers that require a diagnostic
+     * host.
+     */
+    private annotation;
+    /**
+     * Detects acknowledgements and reviews on withdrawn carriers.
+     *
+     * Withdrawal-only carriers do not create ordinary claim hosts.
+     */
+    private claimAnnotation;
+    /**
+     * Recognizes supported annotation names at documentation line boundaries.
+     *
+     * Boundary matching prevents prose and examples from becoming annotation
+     * syntax.
+     */
+    private annotationPattern;
+    /**
+     * Follows explicit parent ownership to propagate withdrawal.
+     *
+     * A visited set preserves termination when malformed ownership would
+     * otherwise cycle.
+     */
+    private withdrawn;
+    /**
+     * Separates database kinds while unifying schema identities.
+     *
+     * Unit IDs remain stable across physical declaration sites for one database
+     * selector.
+     */
+    private unitId;
+    /**
+     * Marks a declaration conflict as incomplete analysis.
+     *
+     * A conflict must not allow the remaining declarations to appear as a
+     * complete population.
+     */
+    private problem;
+}