@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/sqlite/EvidenceSqliteFileScanner.js

@@ -0,0 +1,300 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSqliteFileScanner = void 0;
+const EvidenceSourceText_1 = require("../../internal/EvidenceSourceText");
+const EvidenceSqliteSyntax_1 = require("./EvidenceSqliteSyntax");
+/**
+ * Extracts a static SQLite schema from declarative grammar nodes.
+ *
+ * The scanner does not execute migrations or queries. It records only syntax
+ * that establishes a stable schema and reports other constructs so they cannot
+ * make a partial inventory appear complete.
+ */
+class EvidenceSqliteFileScanner {
+    session;
+    source;
+    /**
+     * Collects declarations established by recognized SQLite grammar positions.
+     *
+     * The array remains private until `scan` returns its node-free analysis.
+     */
+    declarations = [];
+    /**
+     * Collects findings that prevent a smaller schema from appearing complete.
+     *
+     * Each diagnostic identifies syntax requiring runtime interpretation or a
+     * scanner capability that SQLite extraction does not support.
+     */
+    diagnostics = [];
+    /**
+     * Maps SQLite node offsets into original UTF-16 source coordinates.
+     *
+     * Documentation and declaration sites share this coordinate authority.
+     */
+    text;
+    /**
+     * Initializes one scanner over a borrowed session and immutable source.
+     *
+     * The session supplies grammar nodes only during the scan; the returned
+     * analysis contains no node references after this object finishes.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+        this.text = new EvidenceSourceText_1.EvidenceSourceText(source.content);
+    }
+    /**
+     * Returns declarations, documentation carriers, and truthful completeness.
+     *
+     * Every unsupported statement records a diagnostic before the result reports
+     * completion, preventing a reduced schema from passing coverage checks.
+     */
+    scan() {
+        for (const statement of this.session.root.namedChildren) {
+            if (statement.type === "comment")
+                continue;
+            if (statement.type !== "sql_stmt") {
+                this.incomplete(statement, "The SQLite statement is not recognized.");
+                continue;
+            }
+            const children = statement.namedChildren.filter((child) => child.type !== "comment");
+            const declaration = children[0];
+            if (children.length !== 1 || declaration?.type !== "create_table_stmt") {
+                this.incomplete(statement, "Only explicit CREATE TABLE declarations establish a static SQLite schema; execution, virtual tables, views, triggers, ATTACH, PRAGMA, and schema mutations require runtime interpretation.");
+                continue;
+            }
+            this.table(declaration);
+        }
+        return {
+            source: this.source,
+            declarations: this.declarations,
+            documentation: this.documentation(),
+            diagnostics: this.diagnostics,
+            complete: this.diagnostics.length === 0,
+        };
+    }
+    /**
+     * Creates one model and its explicitly declared columns and relations.
+     *
+     * The method rejects query-derived tables and ambiguous names because static
+     * identity must come from explicit SQLite schema syntax.
+     */
+    table(node) {
+        if (node.namedChildren.some((child) => child.type === "select_stmt")) {
+            this.incomplete(node, "CREATE TABLE AS requires query-derived columns.");
+            return;
+        }
+        const names = EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.names(node);
+        const name = names.at(-1);
+        const temporary = node.namedChildren.some((child) => child.type === "TEMP" || child.type === "TEMPORARY");
+        const schema = names.length === 2 ? names[0] : temporary ? "temp" : "main";
+        if (name === undefined || schema === undefined || names.length > 2) {
+            this.incomplete(node, "The SQLite table has no unambiguous schema name.");
+            return;
+        }
+        if (temporary && EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.fold(schema) !== "temp") {
+            this.incomplete(node, "A TEMP table may only name the temp schema.");
+            return;
+        }
+        if (EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.fold(name).startsWith("sqlite_")) {
+            this.incomplete(node, "SQLite reserves table names beginning with sqlite_.");
+            return;
+        }
+        const identity = [schema, name].map(EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.fold);
+        const model = this.declare(node, "model", names, identity);
+        const columns = node.namedChildren.filter((child) => child.type === "column_def");
+        const constraints = node.namedChildren.filter((child) => child.type === "table_constraint");
+        if (columns.length === 0)
+            this.incomplete(node, "A declared SQLite table requires explicit columns.");
+        const columnNames = columns.flatMap((column) => {
+            const columnName = EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.names(column)[0];
+            return columnName === undefined
+                ? []
+                : [EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.fold(columnName)];
+        });
+        for (const column of columns) {
+            const columnName = EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.names(column)[0];
+            if (columnName === undefined) {
+                this.incomplete(column, "The SQLite column has no readable name.");
+                continue;
+            }
+            this.declare(column, "column", [...names, columnName], [...identity, EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.fold(columnName)], model.id);
+            for (const constraint of column.namedChildren.filter((child) => child.type === "column_constraint"))
+                this.relation(constraint, model, [columnName], columnNames);
+        }
+        for (const constraint of constraints)
+            this.relation(constraint, model, undefined, columnNames);
+        const first = columns[0];
+        const last = [...columns, ...constraints].at(-1);
+        if (first !== undefined && last !== undefined)
+            model.site.content = [
+                this.text.range(node.startIndex, first.startIndex),
+                ...constraints
+                    .filter((constraint) => !constraint.namedChildren.some((child) => child.type === "foreign_key_clause"))
+                    .map((constraint) => this.session.range(constraint)),
+                this.text.range(last.endIndex, node.endIndex),
+            ];
+    }
+    /**
+     * Creates a relation from a foreign-key clause with explicit endpoints.
+     *
+     * Relations use a namespace below their model so a constraint does not
+     * collide with a column, and endpoint arity must remain verifiable.
+     */
+    relation(node, model, inline, columns) {
+        const clause = node.namedChildren.find((child) => child.type === "foreign_key_clause");
+        if (clause === undefined)
+            return;
+        const named = node.namedChildren.some((child) => child.type === "CONSTRAINT");
+        const names = EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.names(node);
+        const constraintName = named ? names[0] : undefined;
+        const local = inline ?? names.slice(named ? 1 : 0);
+        const action = clause.namedChildren.findIndex((child) => ["ON", "MATCH", "NOT", "DEFERRABLE"].includes(child.type));
+        const remote = clause.namedChildren
+            .slice(0, action < 0 ? undefined : action)
+            .flatMap((child) => {
+            const name = EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.identifier(child);
+            return name === undefined ? [] : [name];
+        });
+        const target = remote[0];
+        const endpoints = remote.slice(1);
+        if (local.length === 0 ||
+            target === undefined ||
+            local.some((name) => !columns.includes(EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.fold(name))) ||
+            (endpoints.length !== 0 && endpoints.length !== local.length)) {
+            this.incomplete(node, "The foreign key requires declared local columns and matching explicit endpoint arity.");
+            return;
+        }
+        const segment = constraintName === undefined
+            ? `foreign key:${JSON.stringify(local)}->${JSON.stringify([target, ...endpoints])}`
+            : `foreign key:${constraintName}`;
+        this.declare(node, "relation", [...model.address, segment], [...model.identity, EvidenceSqliteSyntax_1.EvidenceSqliteSyntax.fold(segment)], model.id);
+    }
+    /**
+     * Creates a physical declaration record distinct from normalized identity.
+     *
+     * SQLite case-folds semantic identity while preserving source spelling and
+     * ranges for public addresses, documentation, and review fingerprints.
+     */
+    declare(node, symbol, address, identity, ownerDeclarationId) {
+        const id = `${this.source.id}:${symbol}:${node.startIndex}`;
+        const range = this.session.range(node);
+        const declaration = {
+            id,
+            name: address.at(-1) ?? "",
+            symbol,
+            identity,
+            address,
+            ...(identity.length === address.length + 1
+                ? { aliases: [[identity[0] ?? "main", ...address]] }
+                : {}),
+            site: {
+                id: `${id}:site`,
+                file: this.source.physicalPath,
+                range,
+                content: [range],
+            },
+            ...(ownerDeclarationId === undefined ? {} : { ownerDeclarationId }),
+            public: true,
+        };
+        this.declarations.push(declaration);
+        return declaration;
+    }
+    /**
+     * Attaches adjacent leading comments while retaining detached carriers.
+     *
+     * Grouping is limited to standalone adjacent line comments so trailing text
+     * cannot accidentally document the declaration on the following line.
+     */
+    documentation() {
+        const comments = this.session
+            .captures("(comment) @comment")
+            .map((capture) => capture.node)
+            .sort((left, right) => left.startIndex - right.startIndex);
+        const groups = [];
+        for (const comment of comments) {
+            const group = groups.at(-1);
+            const previous = group === undefined ? undefined : group.at(-1);
+            if (group !== undefined &&
+                previous !== undefined &&
+                this.leading(previous) &&
+                this.leading(comment) &&
+                previous.text.startsWith("--") &&
+                comment.text.startsWith("--") &&
+                this.adjacent(previous.endIndex, comment.startIndex))
+                group.push(comment);
+            else
+                groups.push([comment]);
+        }
+        return groups.flatMap((group) => {
+            const first = group[0];
+            const last = group.at(-1);
+            if (first === undefined || last === undefined)
+                return [];
+            const attached = this.leading(first)
+                ? this.declarations.filter((declaration) => this.adjacent(last.endIndex, declaration.site.range.start.offset))
+                : [];
+            return [
+                {
+                    id: `${this.source.id}:documentation:${first.startIndex}`,
+                    range: this.text.range(first.startIndex, last.endIndex),
+                    attachments: attached.map((declaration) => ({
+                        declarationId: declaration.id,
+                        siteId: declaration.site.id,
+                    })),
+                    syntax: {
+                        opening: first.text.startsWith("--")
+                            ? "--"
+                            : first.text.startsWith("/**")
+                                ? "/**"
+                                : "/*",
+                        closing: first.text.startsWith("--") ? "" : "*/",
+                        linePrefix: first.text.startsWith("--") ? "--" : "*",
+                        tagBoundaries: false,
+                        allowWithdrawal: true,
+                    },
+                },
+            ];
+        });
+    }
+    /**
+     * Checks whether a comment begins before other content on its source line.
+     *
+     * Trailing comments fail this check and therefore cannot absorb the next
+     * declaration's leading documentation role.
+     */
+    leading(node) {
+        return (this.source.content
+            .slice(this.source.content.lastIndexOf("\n", node.startIndex - 1) + 1, node.startIndex)
+            .trim() === "");
+    }
+    /**
+     * Checks whether only one optional line break separates two source ranges.
+     *
+     * Blank lines and intervening syntax detach comments from declarations and
+     * from preceding line-comment fragments.
+     */
+    adjacent(start, end) {
+        return (start <= end &&
+            /^[\t ]*(?:\r?\n[\t ]*)?$/u.test(this.source.content.slice(start, end)));
+    }
+    /**
+     * Reports unsupported SQLite syntax without inferring runtime database state.
+     *
+     * The repair tells authors how to restore a declarative complete inventory
+     * while the diagnostic keeps the partial result from passing as complete.
+     */
+    incomplete(node, message) {
+        this.diagnostics.push({
+            code: "unsupported-sqlite-syntax",
+            severity: "error",
+            message,
+            repair: "Select a declarative SQLite schema with explicit CREATE TABLE statements, or implement this construct before relying on a complete inventory.",
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.EvidenceSqliteFileScanner = EvidenceSqliteFileScanner;

package/lib/adapters/sqlite/EvidenceSqliteSyntax.d.ts

@@ -0,0 +1,32 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+/**
+ * Decodes SQLite source identifiers without interpreting strings as executable
+ * SQL.
+ *
+ * The SQLite scanner uses these helpers only for grammar-established name
+ * nodes.
+ */
+export declare namespace EvidenceSqliteSyntax {
+    /**
+     * Returns a literal name, including SQLite's context-specific single-quote
+     * spelling.
+     *
+     * Callers pass identifier tokens, so string expressions cannot become schema
+     * names.
+     */
+    function identifier(node: EvidenceNode): string | undefined;
+    /**
+     * Folds SQLite identifier ASCII letters while preserving other code points.
+     *
+     * This matches the adapter's comparison boundary without changing Unicode
+     * spelling.
+     */
+    function fold(value: string): string;
+    /**
+     * Reads direct grammar-established names, excluding names inside expressions.
+     *
+     * The returned segments remain separate so quoted dots are not treated as
+     * path delimiters.
+     */
+    function names(node: EvidenceNode): string[];
+}

package/lib/adapters/sqlite/EvidenceSqliteSyntax.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceSqliteSyntax = void 0;
+/**
+ * Decodes SQLite source identifiers without interpreting strings as executable
+ * SQL.
+ *
+ * The SQLite scanner uses these helpers only for grammar-established name
+ * nodes.
+ */
+var EvidenceSqliteSyntax;
+(function (EvidenceSqliteSyntax) {
+    /**
+     * Returns a literal name, including SQLite's context-specific single-quote
+     * spelling.
+     *
+     * Callers pass identifier tokens, so string expressions cannot become schema
+     * names.
+     */
+    function identifier(node) {
+        if (node.type !== "identifier" && node.type !== "string_literal")
+            return undefined;
+        const raw = node.text;
+        const first = raw[0];
+        if (first === "[")
+            return raw.slice(1, -1);
+        if (first === '"' || first === "'" || first === "`")
+            return raw.slice(1, -1).replaceAll(first + first, first);
+        return raw;
+    }
+    EvidenceSqliteSyntax.identifier = identifier;
+    /**
+     * Folds SQLite identifier ASCII letters while preserving other code points.
+     *
+     * This matches the adapter's comparison boundary without changing Unicode
+     * spelling.
+     */
+    function fold(value) {
+        return value.replace(/[A-Z]/gu, (character) => character.toLowerCase());
+    }
+    EvidenceSqliteSyntax.fold = fold;
+    /**
+     * Reads direct grammar-established names, excluding names inside expressions.
+     *
+     * The returned segments remain separate so quoted dots are not treated as
+     * path delimiters.
+     */
+    function names(node) {
+        return node.namedChildren.flatMap((child) => {
+            const value = identifier(child);
+            return value === undefined ? [] : [value];
+        });
+    }
+    EvidenceSqliteSyntax.names = names;
+})(EvidenceSqliteSyntax || (exports.EvidenceSqliteSyntax = EvidenceSqliteSyntax = {}));

package/lib/adapters/swagger/EvidenceSwaggerAdapter.d.ts

@@ -1,44 +1,48 @@
 import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
 import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
 import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
-import type { EvidenceArtifactType } from "../../typings/EvidenceArtifactType";
 /**
- * Extracts Swagger/OpenAPI operations and their description-based annotation hosts.
+ * Extracts Swagger/OpenAPI operations and their description-based annotation
+ * hosts.
  *
  * Local snapshots and explicitly configured remote documents pass through the
- * same normalization and materialization path. Each method/path operation retains
- * its own identity even without a description, while supported description spans
- * map annotations back to source coordinates. Document failures remain incomplete.
+ * same normalization and materialization path. Each method/path operation
+ * retains its own identity even without a description, while supported
+ * description spans map annotations back to source coordinates.
+ * EvidenceDocument failures remain incomplete.
  */
-export declare class EvidenceSwaggerAdapter implements IEvidenceAdapter {
+export declare class EvidenceSwaggerAdapter implements IEvidenceAdapter<"swagger"> {
     /**
      * Artifact discriminator selecting API-operation extraction.
      *
-     * Operations use method/path targets within each independent document population.
+     * Operations use method/path targets within each independent document
+     * population.
      */
-    readonly type: EvidenceArtifactType;
+    get type(): "swagger";
     /**
      * Normalizes captured JSON/YAML documents into operation inventories.
      *
      * Each document failure is retained alongside successfully loaded documents.
-     * Input is cloned, and final inventory validation preserves incompleteness rather
-     * than treating failed normalization as a document with no operations.
+     * Input is cloned, and final inventory validation preserves incompleteness
+     * rather than treating failed normalization as a document with no
+     * operations.
      */
     analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
     /**
      * Loads one exact local document or explicitly configured HTTP(S) URL.
      *
-     * Local paths resolve from the configuration-relative root and use source-loader
-     * dependency tracking. Remote bytes become a synthetic source snapshot without
-     * filesystem dependencies. Access and normalization failures return incomplete
-     * inventory diagnostics for the requested document.
+     * Local paths resolve from the configuration-relative root and use
+     * source-loader dependency tracking. Remote bytes become a synthetic source
+     * snapshot without filesystem dependencies. Access and normalization failures
+     * return incomplete inventory diagnostics for the requested document.
      */
     load(configFile: string, file: string, root?: string): Promise<IEvidenceInventory>;
     /**
-     * Seeds an operation inventory with snapshot provenance and discovery failures.
+     * Seeds an operation inventory with snapshot provenance and discovery
+     * failures.
      *
-     * Operation and annotation collections remain empty until document normalization
-     * establishes supported API structure and source mappings.
+     * Operation and annotation collections remain empty until document
+     * normalization establishes supported API structure and source mappings.
      */
     private inventory;
     /**
@@ -49,7 +53,26 @@ export declare class EvidenceSwaggerAdapter implements IEvidenceAdapter {
      * supplies an annotation, preserving per-host coverage requirements.
      */
     private materialize;
+    /**
+     * Parses one mapped operation description into inventory annotations.
+     *
+     * Declarations, reviews, diagnostics, and their exact source ranges are
+     * copied together so fingerprinting can exclude metadata without dropping
+     * prose.
+     */
     private parse;
+    /**
+     * Creates an incomplete inventory for one safely described source failure.
+     *
+     * The diagnostic retains the requested source label while an empty population
+     * cannot be mistaken for a complete Swagger document.
+     */
     private failure;
+    /**
+     * Converts an unknown local analysis failure into diagnostic text.
+     *
+     * Remote load failures use EvidenceSwaggerRemoteReader's credential-safe
+     * boundary before they reach this adapter.
+     */
     private message;
 }