@wrtnlabs/evidence 0.0.0

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

@@ -0,0 +1,83 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { ISqlFileAnalysis } from "../sql/ISqlFileAnalysis";
+/** 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.
+ */
+export declare class SqliteFileScanner {
+    private readonly session;
+    private readonly source;
+    /** Collects declarations established by recognized SQLite grammar positions.
+     *
+     * The array remains private until `scan` returns its node-free analysis.
+     */
+    private readonly 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.
+     */
+    private readonly diagnostics;
+    /** Maps SQLite node offsets into original UTF-16 source coordinates.
+     *
+     * Documentation and declaration sites share this coordinate authority.
+     */
+    private readonly 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: EvidenceParseSession, source: IEvidenceSourceFile);
+    /** 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(): ISqlFileAnalysis;
+    /** 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.
+     */
+    private table;
+    /** 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.
+     */
+    private relation;
+    /** 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.
+     */
+    private declare;
+    /** 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.
+     */
+    private documentation;
+    /** 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.
+     */
+    private leading;
+    /** 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.
+     */
+    private adjacent;
+    /** 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.
+     */
+    private incomplete;
+}

package/lib/adapters/sqlite/SqliteFileScanner.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteFileScanner = void 0;
+const SourceText_1 = require("../../internal/SourceText");
+const SqliteSyntax_1 = require("./SqliteSyntax");
+/** 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 SqliteFileScanner {
+    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 SourceText_1.SourceText(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 = SqliteSyntax_1.SqliteSyntax.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 && SqliteSyntax_1.SqliteSyntax.fold(schema) !== "temp") {
+            this.incomplete(node, "A TEMP table may only name the temp schema.");
+            return;
+        }
+        if (SqliteSyntax_1.SqliteSyntax.fold(name).startsWith("sqlite_")) {
+            this.incomplete(node, "SQLite reserves table names beginning with sqlite_.");
+            return;
+        }
+        const identity = [schema, name].map(SqliteSyntax_1.SqliteSyntax.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 = SqliteSyntax_1.SqliteSyntax.names(column)[0];
+            return columnName === undefined ? [] : [SqliteSyntax_1.SqliteSyntax.fold(columnName)];
+        });
+        for (const column of columns) {
+            const columnName = SqliteSyntax_1.SqliteSyntax.names(column)[0];
+            if (columnName === undefined) {
+                this.incomplete(column, "The SQLite column has no readable name.");
+                continue;
+            }
+            this.declare(column, "column", [...names, columnName], [...identity, SqliteSyntax_1.SqliteSyntax.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 = SqliteSyntax_1.SqliteSyntax.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 = SqliteSyntax_1.SqliteSyntax.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(SqliteSyntax_1.SqliteSyntax.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, SqliteSyntax_1.SqliteSyntax.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.SqliteFileScanner = SqliteFileScanner;

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

@@ -0,0 +1,26 @@
+import type { Node } 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 SqliteSyntax {
+    /**
+     * 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: Node): 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: Node): string[];
+}

package/lib/adapters/sqlite/SqliteSyntax.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteSyntax = 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 SqliteSyntax;
+(function (SqliteSyntax) {
+    /**
+     * 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;
+    }
+    SqliteSyntax.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());
+    }
+    SqliteSyntax.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];
+        });
+    }
+    SqliteSyntax.names = names;
+})(SqliteSyntax || (exports.SqliteSyntax = SqliteSyntax = {}));

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

@@ -0,0 +1,55 @@
+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.
+ *
+ * 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.
+ */
+export declare class EvidenceSwaggerAdapter implements IEvidenceAdapter {
+    /**
+     * Artifact discriminator selecting API-operation extraction.
+     *
+     * Operations use method/path targets within each independent document population.
+     */
+    readonly type: EvidenceArtifactType;
+    /**
+     * 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.
+     */
+    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.
+     */
+    load(configFile: string, file: string, root?: string): Promise<IEvidenceInventory>;
+    /**
+     * 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.
+     */
+    private inventory;
+    /**
+     * Creates semantic operation units and mapped description carriers.
+     *
+     * Source identity qualifies each operation token so separate documents do not
+     * merge accidentally. Operations remain represented even when no description
+     * supplies an annotation, preserving per-host coverage requirements.
+     */
+    private materialize;
+    private parse;
+    private failure;
+    private message;
+}