@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -1,83 +0,0 @@
-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

@@ -1,285 +0,0 @@
-"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

@@ -1,26 +0,0 @@
-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

@@ -1,49 +0,0 @@
-"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/IRemoteSwaggerSource.d.ts

@@ -1,19 +0,0 @@
-/** Bounded UTF-8 response read from one configured Swagger URL.
- *
- * Remote loading owns the bytes and their digest together so later parsing and
- * caching describe the exact response that passed the size limit.
- */
-export interface IRemoteSwaggerSource {
-    /** Decoded response content.
-     *
-     * The reader accepts only valid UTF-8, so loaders may parse this text without
-     * applying a replacement-character normalization.
-     */
-    content: string;
-    /** SHA-256 identity of the received bytes.
-     *
-     * This remains byte-based because semantically equal decoded strings can have
-     * arrived from different invalid or normalized encodings.
-     */
-    digest: string;
-}

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

@@ -1,18 +0,0 @@
-import type { ISwaggerLoadResult } from "./ISwaggerLoadResult";
-/** Remembered normalization outcome for one exact document digest.
- *
- * The cache records failures as well as results so a malformed unchanged source
- * has deterministic behavior without repeating conversion work.
- */
-export interface ISwaggerCacheEntry {
-    /** Successful operation inventory, when normalization completed.
-     *
-     * Omission means this entry represents the failure below.
-     */
-    result?: ISwaggerLoadResult;
-    /** Stable failure message for the cached input.
-     *
-     * Omission means the result is safe to clone for a caller.
-     */
-    problem?: string;
-}

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

@@ -1,13 +0,0 @@
-import type { ISwaggerOperation } from "./ISwaggerOperation";
-/** Normalized operations from one Swagger or OpenAPI document.
- *
- * The loader converts accepted source versions to this version-neutral shape
- * before the adapter materializes public operation units.
- */
-export interface ISwaggerLoadResult {
-    /** Operations ordered by their public targets.
-     *
-     * Each target occurs at most once; duplicates are rejected during loading.
-     */
-    operations: ISwaggerOperation[];
-}

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

@@ -1,42 +0,0 @@
-import type { ISwaggerOperationLocation } from "./ISwaggerOperationLocation";
-/** One normalized Swagger operation and its semantic fingerprint input.
- *
- * This separates the public operation address from content used to detect a
- * schema change, while retaining optional source coordinates for diagnostics.
- */
-export interface ISwaggerOperation {
-    /**
-     * Stores the uppercase HTTP method forming the public target prefix.
-     *
-     * Normalization keeps OpenAPI method spelling independent from target matching.
-     */
-    method: string;
-    /**
-     * Stores the absolute OpenAPI path forming the public target suffix.
-     *
-     * Its literal path spelling remains distinct from the HTTP method identity.
-     */
-    path: string;
-    /**
-     * Provides the stable public address in `METHOD:/path` form.
-     *
-     * Evidence tags resolve operations through this combined method-and-path identity.
-     */
-    target: string;
-    /** Digest of canonical operation semantics.
-     *
-     * Description metadata and reference indirection are normalized before this
-     * value is computed, keeping review state tied to API meaning.
-     */
-    digest: string;
-    /** Original description text, when the operation supplies one.
-     *
-     * Omission distinguishes no description from an explicitly empty string.
-     */
-    description?: string;
-    /** Source coordinates for the operation and mapped description, when known.
-     *
-     * Converted or aliased YAML may not have a direct scalar location.
-     */
-    location?: ISwaggerOperationLocation;
-}

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

@@ -1,21 +0,0 @@
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-import type { IYamlScalarMapping } from "./IYamlScalarMapping";
-/** Source spans for one normalized Swagger operation and its description.
- *
- * Locations are optional on operations because OpenAPI conversion can preserve
- * semantics for values that do not map to one source token.
- */
-export interface ISwaggerOperationLocation {
-    /**
-     * Locates the full operation node used as the physical unit site.
-     *
-     * The range keeps diagnostics and fingerprints tied to the original document.
-     */
-    range: IEvidenceSourceRange;
-    /**
-     * Maps description characters when the scalar has a source-backed location.
-     *
-     * Omission means converted or aliased content has no direct scalar token.
-     */
-    description?: IYamlScalarMapping;
-}

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

@@ -1,36 +0,0 @@
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-/** Decoded YAML scalar with monotonic positions in its source token.
- *
- * Documentation handling uses the maps to convert decoded annotation offsets
- * back to the UTF-16 positions that users can edit.
- */
-export interface IYamlScalarMapping {
-    /**
-     * Decoded scalar text inspected for Evidence annotations.
-     *
-     * Annotation parsing uses this value while `offsets` and `ends` translate its
-     * decoded UTF-16 positions back into the original YAML source token.
-     */
-    text: string;
-    /**
-     * Complete scalar token span in the original document.
-     *
-     * This range bounds every decoded-offset mapping and supplies the source
-     * location when a YAML scalar's annotation needs a diagnostic.
-     */
-    range: IEvidenceSourceRange;
-    /**
-     * Source start offsets indexed by decoded UTF-16 code unit.
-     *
-     * Each entry identifies where the corresponding decoded unit begins, including
-     * escape sequences that occupy a wider physical spelling in the document.
-     */
-    offsets: number[];
-    /**
-     * Source end offsets paired with `offsets` entries.
-     *
-     * The matching interval permits annotation spans to include an entire escape
-     * spelling rather than pointing into only part of one YAML scalar token.
-     */
-    ends: number[];
-}

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

@@ -1,18 +0,0 @@
-/** Separates operation prose from Evidence metadata appended to a description.
- *
- * Fingerprints retain author-facing prose but exclude Evidence directives, which
- * control review state without changing the described API operation.
- */
-export declare namespace SwaggerDescription {
-    /** Returns description prose before the first active Evidence directive.
-     *
-     * Directive-looking lines inside fenced examples remain semantic prose.
-     */
-    function semantic(text: string): string;
-    /** Reports whether an active Evidence directive begins in this description.
-     *
-     * Callers use this to decide whether the mapped scalar must become a
-     * documentation carrier even when the visible prose is empty.
-     */
-    function hasMetadata(text: string): boolean;
-}