@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/sql/SqlDocumentation.js

@@ -1,91 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SqlDocumentation = void 0;
-const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
-/**
- * Reads SQL documentation while preserving source mappings and masking code examples.
- *
- * Shared SQL adapters use the result before passing supported annotations to the tag parser.
- */
-var SqlDocumentation;
-(function (SqlDocumentation) {
-    /**
-     * Maps a classified carrier and removes ineligible example text without moving offsets.
-     *
-     * Preserved offsets keep tag diagnostics aligned with the original SQL source.
-     */
-    function read(source, documentation, hostId) {
-        if (documentation.mapped !== undefined)
-            return {
-                ...documentation.mapped,
-                hostId,
-                text: mask(documentation.mapped.text),
-            };
-        const raw = source.content.slice(documentation.range.start.offset, documentation.range.end.offset);
-        const syntax = documentation.syntax ?? {
-            opening: raw.startsWith("--")
-                ? "--"
-                : raw.startsWith("/**")
-                    ? "/**"
-                    : "/*",
-            closing: raw.startsWith("--") ? "" : "*/",
-            linePrefix: raw.startsWith("--") ? "--" : "*",
-            tagBoundaries: false,
-            allowWithdrawal: true,
-        };
-        const parsed = EvidenceDocumentation_1.EvidenceDocumentation.read(source.content, hostId, documentation.range, syntax);
-        return {
-            ...parsed,
-            text: mask(parsed.text),
-        };
-    }
-    SqlDocumentation.read = read;
-    /**
-     * Masks HTML examples and Markdown indented code while shared tag parsing handles fences.
-     *
-     * Masking replaces only visible characters so source line and UTF-16 positions remain stable.
-     */
-    function mask(input) {
-        const characters = input.split("");
-        const htmlCode = /<(pre|code)\b[^>]*>[\s\S]*?<\/\1\s*>/giu;
-        for (const match of input.matchAll(htmlCode))
-            hide(characters, match.index, match.index + match[0].length);
-        const lines = input.split("\n");
-        const indents = lines.filter((line) => line.trim() !== "").map(indentation);
-        const baseline = indents.reduce((minimum, indent) => Math.min(minimum, indent), Infinity);
-        let offset = 0;
-        for (const line of lines) {
-            if (indentation(line) >= baseline + 4)
-                hide(characters, offset, offset + line.length);
-            offset += line.length + 1;
-        }
-        return characters.join("");
-    }
-    /**
-     * Counts Markdown indentation after the documentation delimiter is removed.
-     *
-     * Tabs advance to the next four-column boundary before code-block comparison.
-     */
-    function indentation(line) {
-        let spaces = 0;
-        for (const character of line) {
-            if (character === " ")
-                ++spaces;
-            else if (character === "\t")
-                spaces += 4 - (spaces % 4);
-            else
-                break;
-        }
-        return spaces;
-    }
-    /**
-     * Replaces example characters with spaces while retaining original line boundaries.
-     *
-     * Newlines remain intact so later offset mapping still identifies the source carrier.
-     */
-    function hide(characters, start, end) {
-        for (let index = start; index < end; ++index)
-            if (characters[index] !== "\n" && characters[index] !== "\r")
-                characters[index] = " ";
-    }
-})(SqlDocumentation || (exports.SqlDocumentation = SqlDocumentation = {}));

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

@@ -1,86 +0,0 @@
-import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { ISqlFileAnalysis } from "./ISqlFileAnalysis";
-import type { ISqlPolicy } from "./ISqlPolicy";
-/** 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.
- */
-export declare class SqlFileScanner {
-    private readonly session;
-    private readonly source;
-    private readonly policy;
-    /** Holds the mutable serializable result owned by this scan.
-     *
-     * Helpers append records and failures here before `scan` returns the final
-     * node-free analysis.
-     */
-    private readonly 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: EvidenceParseSession, source: IEvidenceSourceFile, policy?: ISqlPolicy);
-    /** 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(): ISqlFileAnalysis;
-    /** 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.
-     */
-    private table;
-    /** 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.
-     */
-    private relation;
-    /** 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.
-     */
-    private declaration;
-    /** 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.
-     */
-    private reference;
-    /** Decodes a dialect identifier and reports unsupported spelling.
-     *
-     * Returning no name prevents callers from inventing an address outside the
-     * dialect contract.
-     */
-    private identifier;
-    /** 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.
-     */
-    private documentation;
-    /** Checks whether a comment starts before any source token on its line.
-     *
-     * Only such a standalone comment can be leading documentation.
-     */
-    private standalone;
-    /** Identifies grammar nodes that represent SQL comments.
-     *
-     * Tree-sitter classification avoids mistaking comment-looking SQL literal
-     * text for documentation syntax.
-     */
-    private comment;
-    /** Records a located unsupported construct and marks the result incomplete.
-     *
-     * This failure prevents partial extraction from being accepted as complete
-     * evidence coverage.
-     */
-    private problem;
-}

package/lib/adapters/sql/SqlFileScanner.js

@@ -1,299 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SqlFileScanner = void 0;
-const SourceText_1 = require("../../internal/SourceText");
-const SqlPolicy_1 = require("./SqlPolicy");
-/** 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 SqlFileScanner {
-    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 = SqlPolicy_1.SqlPolicy) {
-        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 SourceText_1.SourceText(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.SqlFileScanner = SqlFileScanner;

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

@@ -1,20 +0,0 @@
-import type { Node } from "web-tree-sitter";
-/**
- * Defines the portable subset independently of the broad SQL parser grammar.
- *
- * `SqlFileScanner` uses this policy to reject syntax whose meaning varies by dialect.
- */
-export declare namespace SqlPolicy {
-    /**
-     * Folds regular identifiers to upper case and preserves standard quoted identifiers.
-     *
-     * This yields portable semantic identity while retaining literal quoted spelling.
-     */
-    function identifier(raw: string): string | undefined;
-    /**
-     * Rejects every statement or extension outside explicit portable CREATE TABLE.
-     *
-     * The scanner reports the returned reason so unsupported syntax cannot shrink the population.
-     */
-    function validate(node: Node): string | undefined;
-}

package/lib/adapters/sql/SqlPolicy.js

@@ -1,111 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SqlPolicy = void 0;
-/**
- * Defines the portable subset independently of the broad SQL parser grammar.
- *
- * `SqlFileScanner` uses this policy to reject syntax whose meaning varies by dialect.
- */
-var SqlPolicy;
-(function (SqlPolicy) {
-    /**
-     * Folds regular identifiers to upper case and preserves standard quoted identifiers.
-     *
-     * This yields portable semantic identity while retaining literal quoted spelling.
-     */
-    function identifier(raw) {
-        if (/^"(?:[^"]|"")+"$/u.test(raw))
-            return raw.slice(1, -1).replaceAll('""', '"');
-        return /^[A-Za-z_][A-Za-z_0-9]*$/u.test(raw)
-            ? raw.toUpperCase()
-            : undefined;
-    }
-    SqlPolicy.identifier = identifier;
-    /**
-     * Rejects every statement or extension outside explicit portable CREATE TABLE.
-     *
-     * The scanner reports the returned reason so unsupported syntax cannot shrink the population.
-     */
-    function validate(node) {
-        if (node.type === "comment" || node.type === "marginalia")
-            return undefined;
-        if (node.type !== "create_table")
-            return "Portable SQL accepts only explicit CREATE TABLE declarations; select a dialect adapter or add support for this statement.";
-        const allowed = new Set([
-            "keyword_create",
-            "keyword_table",
-            "object_reference",
-            "column_definitions",
-            "comment",
-            "marginalia",
-        ]);
-        if (node.namedChildren.some((child) => !allowed.has(child.type)))
-            return "Portable SQL does not infer conditional, temporary, query-derived, or dialect-specific tables.";
-        const forbidden = new Set([
-            "keyword_index",
-            "keyword_auto_increment",
-            "keyword_generated",
-            "keyword_as",
-            "keyword_stored",
-            "keyword_virtual",
-            "keyword_comment",
-            "keyword_unsigned",
-            "keyword_zerofill",
-            "keyword_collate",
-            "keyword_nulls",
-            "direction",
-            "array_size",
-            "array_size_definition",
-            "array_type",
-        ]);
-        const stack = [...node.namedChildren];
-        while (stack.length !== 0) {
-            const child = stack.pop();
-            if (child === undefined)
-                continue;
-            if (child.type === "identifier" && identifier(child.text) === undefined)
-                return "Portable SQL accepts regular ASCII and standard double-quoted identifiers only.";
-            if (forbidden.has(child.type))
-                return `Portable SQL does not support '${child.text}' in table declarations.`;
-            if (child.type === "constraint") {
-                const forms = new Set(child.namedChildren.map((entry) => entry.type));
-                if (![
-                    "keyword_foreign",
-                    "keyword_primary",
-                    "keyword_unique",
-                    "keyword_check",
-                ].some((type) => forms.has(type)))
-                    return "Portable SQL supports only PRIMARY KEY, UNIQUE, CHECK, and FOREIGN KEY table constraints.";
-                if (forms.has("keyword_unique") && forms.has("keyword_key"))
-                    return "Portable SQL uses UNIQUE, not the dialect-specific UNIQUE KEY spelling.";
-                if (child.childForFieldName("name") !== null &&
-                    !forms.has("keyword_constraint"))
-                    return "Portable SQL names constraints with CONSTRAINT; dialect-specific index names are unsupported.";
-                if (forms.has("keyword_foreign") &&
-                    child.childForFieldName("name") !== null)
-                    return "Named foreign-key syntax is not supported by the portable SQL grammar; use an anonymous FOREIGN KEY or a certified dialect.";
-            }
-            if (child.type === "column_definition") {
-                const named = child.namedChildren.filter((entry) => entry.type !== "comment" && entry.type !== "marginalia");
-                for (let index = 0; index < named.length; ++index) {
-                    if (named[index]?.type !== "keyword_default")
-                        continue;
-                    const expression = named[index + 1];
-                    if (expression === undefined ||
-                        !/^(?:[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?|'(?:[^']|'')*'|TRUE|FALSE|NULL|CURRENT_TIMESTAMP)$/iu.test(expression.text.trim()))
-                        return "Portable SQL defaults require a scalar literal or CURRENT_TIMESTAMP; dialect function defaults are unsupported.";
-                }
-                if (named.some((entry) => entry.type === "keyword_constraint"))
-                    return "Named column constraints are outside the documented portable grammar subset.";
-                const type = child.childForFieldName("type");
-                if (child.childrenForFieldName("type").length !== 1 ||
-                    type === null ||
-                    !/^(?:SMALLINT|INTEGER|INT|BIGINT|DECIMAL|NUMERIC|REAL|DOUBLE\s+PRECISION|FLOAT|BOOLEAN|CHAR(?:ACTER)?|VARCHAR|CHARACTER\s+VARYING|DATE|TIME|TIMESTAMP)(?:\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\))?$/iu.test(type.text))
-                    return "Portable SQL columns require a documented standard scalar data type.";
-            }
-            stack.push(...child.namedChildren);
-        }
-        return undefined;
-    }
-    SqlPolicy.validate = validate;
-})(SqlPolicy || (exports.SqlPolicy = SqlPolicy = {}));