@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/matlab/IEvidenceMatlabDeclaration.d.ts

@@ -0,0 +1,115 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+/**
+ * Represents a MATLAB declaration before class-folder and accessor
+ * reconciliation.
+ *
+ * MATLAB can separate a public signature, implementation file, and property
+ * accessors, so this record retains those physical facts until ownership is
+ * known.
+ */
+export interface IEvidenceMatlabDeclaration {
+    /**
+     * Identifies this physical declaration extracted from the selected source.
+     *
+     * Documentation attachments and later ownership links use it before unit IDs
+     * exist.
+     */
+    id: string;
+    /**
+     * Stores the literal MATLAB identifier from the declaration.
+     *
+     * The resolver appends it to its owner path when creating a public unit
+     * address.
+     */
+    name: string;
+    /**
+     * Classifies the declaration in Evidence's shared programming selector model.
+     *
+     * This distinguishes types, functions, and properties during graph selection.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Names package and lexical-owner segments that define semantic identity.
+     *
+     * Ownership reconciliation may replace this path for an external class
+     * method.
+     */
+    identity: string[];
+    /**
+     * Names the public accessor segments projected from a selected source file.
+     *
+     * The array remains distinct from identity because external methods have
+     * class-file aliases.
+     */
+    address: string[];
+    /**
+     * Identifies the physical file that establishes this declaration's ownership.
+     *
+     * The resolver uses this anchor to match external members with their class
+     * definition.
+     */
+    anchor: string;
+    /**
+     * States whether static MATLAB visibility exposes this declaration publicly.
+     *
+     * Ownership and accessor reconciliation can further restrict an initially
+     * visible record.
+     */
+    public: boolean;
+    /**
+     * Names the class-folder owner required by an external method declaration.
+     *
+     * The resolver uses this physical relationship to reject same-named methods
+     * from an unrelated class before assigning a semantic parent.
+     */
+    externalOwner?: string;
+    /**
+     * Identifies the selected implementation required by a nonabstract signature.
+     *
+     * Keeping the required file explicit lets incomplete input fail instead of
+     * silently shrinking the population to only declarations with bodies.
+     */
+    implementation?: string;
+    /**
+     * Identifies a getter or setter that contributes to an existing property
+     * unit.
+     *
+     * Omission means this declaration is independently materialized rather than
+     * an accessor.
+     */
+    accessor?: "get" | "set";
+    /**
+     * Records whether the declared property has public read access.
+     *
+     * It determines whether a matching getter can remain on the public surface.
+     */
+    getPublic?: boolean;
+    /**
+     * Records whether the declared property has public write access.
+     *
+     * It determines whether a matching setter can remain on the public surface.
+     */
+    setPublic?: boolean;
+    /**
+     * Lists additional public class-file projections for an external method.
+     *
+     * Each file supplies an address for the same semantic unit, rather than a
+     * duplicate declaration that would inflate coverage.
+     */
+    publicFiles?: string[];
+    /**
+     * References the scanner-local parent declaration when one exists.
+     *
+     * Omission denotes a top-level function or class before ownership
+     * reconciliation.
+     */
+    ownerDeclarationId?: string;
+    /**
+     * Holds physical declaration and content spans for hosts and fingerprints.
+     *
+     * Materialized units retain these ranges even when ownership joins several
+     * files.
+     */
+    site: IEvidenceUnitSite;
+}

package/lib/adapters/matlab/IEvidenceMatlabDocumentation.d.ts

@@ -0,0 +1,40 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceMatlabDocumentationAttachment } from "./IEvidenceMatlabDocumentationAttachment";
+/**
+ * Represents a MATLAB documentation carrier or tag-bearing unsupported carrier.
+ *
+ * MATLAB help placement has language-specific attachment rules, so this record
+ * preserves both accepted help and tagged text that needs an actionable
+ * failure.
+ */
+export interface IEvidenceMatlabDocumentation {
+    /**
+     * Identifies this physical documentation carrier within one source analysis.
+     *
+     * Attachments use the key before ownership maps declarations to public units.
+     */
+    id: string;
+    /**
+     * Locates the half-open UTF-16 source span occupied by the help text.
+     *
+     * Inventory fingerprints exclude this range when reviewing documented
+     * declarations.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Describes comment delimiters and annotation rules used to parse this
+     * carrier.
+     *
+     * EvidenceMatlabDocumentation relies on the syntax to preserve source offsets
+     * while masking examples.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Lists physical declaration sites that directly own this help text.
+     *
+     * Unsupported tagged carriers remain unattached so the adapter can report
+     * their placement.
+     */
+    attachments: IEvidenceMatlabDocumentationAttachment[];
+}

package/lib/adapters/matlab/IEvidenceMatlabDocumentationAttachment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Connects one MATLAB help carrier to a physical declaration site.
+ *
+ * The pair distinguishes source attachment from a unit's semantic identity;
+ * later ownership reconciliation may merge several sites into that one unit.
+ */
+export interface IEvidenceMatlabDocumentationAttachment {
+    /**
+     * Identifies the scanner-local declaration receiving this help carrier.
+     *
+     * Materialization resolves it to a semantic unit after class-folder ownership
+     * is known.
+     */
+    declarationId: string;
+    /**
+     * Identifies the physical declaration site owned by the eventual semantic
+     * unit.
+     *
+     * This keeps a shared class unit's source hosts distinct across selected
+     * files.
+     */
+    siteId: string;
+}

package/lib/adapters/matlab/IEvidenceMatlabFileAnalysis.d.ts

@@ -0,0 +1,47 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceMatlabDeclaration } from "./IEvidenceMatlabDeclaration";
+import type { IEvidenceMatlabDocumentation } from "./IEvidenceMatlabDocumentation";
+/**
+ * Holds the node-free MATLAB extraction retained after a parse session closes.
+ *
+ * Class-folder ownership is resolved from selected files after scanning, so the
+ * intermediate record retains physical declarations and diagnostics together.
+ */
+export interface IEvidenceMatlabFileAnalysis {
+    /**
+     * Retains the selected source snapshot represented by this extraction.
+     *
+     * Its physical path participates in class-folder ownership and diagnostic
+     * locations.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Lists extracted declarations, including non-public ownership boundaries.
+     *
+     * The resolver needs hidden records to determine whether descendants can be
+     * published.
+     */
+    declarations: IEvidenceMatlabDeclaration[];
+    /**
+     * Lists classified help text and unsupported annotation carriers.
+     *
+     * EvidenceMatlabAdapter creates hosts only after ownership reconciliation
+     * establishes eligible units.
+     */
+    documentation: IEvidenceMatlabDocumentation[];
+    /**
+     * Collects failures found while establishing the static public surface.
+     *
+     * These diagnostics propagate to the inventory rather than removing ambiguous
+     * declarations.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether the scanner classified every relevant MATLAB form.
+     *
+     * A false value remains a failed analysis through ownership reconciliation,
+     * preventing unsupported class layout from shrinking the selected surface.
+     */
+    complete: boolean;
+}

package/lib/adapters/mysql/EvidenceMysqlAdapter.d.ts

@@ -1,16 +1,35 @@
-import { SqlAdapter } from "../sql/SqlAdapter";
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
 /**
- * Extracts explicitly configured MySQL schema declarations with static ownership.
+ * Extracts explicitly configured MySQL schema declarations with static
+ * ownership.
  *
- * MysqlFileScanner supplies MySQL identifier, table, and member records to the
- * common SQL materializer. Schema meaning comes from selected source statements;
- * the adapter neither connects to a server nor executes migrations.
+ * EvidenceMysqlFileScanner supplies MySQL identifier, table, and member records
+ * to the common SQL materializer. Schema meaning comes from selected source
+ * statements; the adapter neither connects to a server nor executes
+ * migrations.
  */
-export declare class EvidenceMysqlAdapter extends SqlAdapter {
+export declare class EvidenceMysqlAdapter implements IEvidenceAdapter<"mysql"> {
     /**
-     * Selects MySQL scanning within the shared parser and inventory lifecycle.
+     * MySQL grammar selected for this adapter.
      *
-     * Construction is inert; analyze later owns the parser runtime for its snapshot.
+     * This identity prevents a shared `.sql` extension from changing the
+     * declaration surface through dialect probing.
      */
-    constructor();
+    get type(): "mysql";
+    /**
+     * Materializes MySQL scanner records into graph-facing inventory records.
+     *
+     * The scanner owns MySQL syntax while this collaborator owns parser lifetime
+     * and syntax-independent SQL publication.
+     */
+    private readonly materializer;
+    /**
+     * Extracts MySQL declarations from one captured source snapshot.
+     *
+     * The adapter fixes dialect policy before analysis; parser allocation waits
+     * until this method receives a snapshot.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
 }

package/lib/adapters/mysql/EvidenceMysqlAdapter.js

@@ -1,23 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceMysqlAdapter = void 0;
-const MysqlFileScanner_1 = require("./MysqlFileScanner");
-const SqlAdapter_1 = require("../sql/SqlAdapter");
+const EvidenceMysqlFileScanner_1 = require("./EvidenceMysqlFileScanner");
+const EvidenceSqlInventoryMaterializer_1 = require("../sql/EvidenceSqlInventoryMaterializer");
+const EVID_MYSQL_TYPE = "mysql";
 /**
- * Extracts explicitly configured MySQL schema declarations with static ownership.
+ * Extracts explicitly configured MySQL schema declarations with static
+ * ownership.
  *
- * MysqlFileScanner supplies MySQL identifier, table, and member records to the
- * common SQL materializer. Schema meaning comes from selected source statements;
- * the adapter neither connects to a server nor executes migrations.
+ * EvidenceMysqlFileScanner supplies MySQL identifier, table, and member records
+ * to the common SQL materializer. Schema meaning comes from selected source
+ * statements; the adapter neither connects to a server nor executes
+ * migrations.
  */
-class EvidenceMysqlAdapter extends SqlAdapter_1.SqlAdapter {
+class EvidenceMysqlAdapter {
     /**
-     * Selects MySQL scanning within the shared parser and inventory lifecycle.
+     * MySQL grammar selected for this adapter.
      *
-     * Construction is inert; analyze later owns the parser runtime for its snapshot.
+     * This identity prevents a shared `.sql` extension from changing the
+     * declaration surface through dialect probing.
      */
-    constructor() {
-        super({ type: "mysql", scan: MysqlFileScanner_1.MysqlFileScanner.scan });
+    get type() {
+        return "mysql";
+    }
+    /**
+     * Materializes MySQL scanner records into graph-facing inventory records.
+     *
+     * The scanner owns MySQL syntax while this collaborator owns parser lifetime
+     * and syntax-independent SQL publication.
+     */
+    materializer = new EvidenceSqlInventoryMaterializer_1.EvidenceSqlInventoryMaterializer({
+        type: EVID_MYSQL_TYPE,
+        scan: EvidenceMysqlFileScanner_1.EvidenceMysqlFileScanner.scan,
+    });
+    /**
+     * Extracts MySQL declarations from one captured source snapshot.
+     *
+     * The adapter fixes dialect policy before analysis; parser allocation waits
+     * until this method receives a snapshot.
+     */
+    analyze(snapshot) {
+        return this.materializer.analyze(snapshot);
     }
 }
 exports.EvidenceMysqlAdapter = EvidenceMysqlAdapter;

package/lib/adapters/mysql/EvidenceMysqlDocumentation.d.ts

@@ -0,0 +1,19 @@
+import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+/**
+ * Maps an attached MySQL COMMENT literal without losing original UTF-16
+ * positions.
+ *
+ * The MySQL scanner supplies the literal range after it has established
+ * ownership.
+ */
+export declare namespace EvidenceMysqlDocumentation {
+    /**
+     * Decodes SQL doubled quotes while rejecting server-mode-dependent backslash
+     * escapes.
+     *
+     * Rejection avoids assigning annotation offsets under an unknown MySQL
+     * session mode.
+     */
+    function read(content: string, range: IEvidenceSourceRange, hostId: string): IEvidenceDocumentation | undefined;
+}

package/lib/adapters/mysql/EvidenceMysqlDocumentation.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceMysqlDocumentation = void 0;
+/**
+ * Maps an attached MySQL COMMENT literal without losing original UTF-16
+ * positions.
+ *
+ * The MySQL scanner supplies the literal range after it has established
+ * ownership.
+ */
+var EvidenceMysqlDocumentation;
+(function (EvidenceMysqlDocumentation) {
+    /**
+     * Decodes SQL doubled quotes while rejecting server-mode-dependent backslash
+     * escapes.
+     *
+     * Rejection avoids assigning annotation offsets under an unknown MySQL
+     * session mode.
+     */
+    function read(content, range, hostId) {
+        const raw = content.slice(range.start.offset, range.end.offset);
+        if (!/^'(?:[^'\\]|'')*'$/su.test(raw))
+            return undefined;
+        const result = {
+            hostId,
+            text: "",
+            offsets: [],
+            ends: [],
+            tagBoundaries: true,
+            allowWithdrawal: true,
+        };
+        for (let cursor = range.start.offset + 1; cursor < range.end.offset - 1; ++cursor) {
+            const character = content[cursor] ?? "";
+            result.text += character;
+            result.offsets.push(cursor);
+            if (character === "'" && content[cursor + 1] === "'")
+                ++cursor;
+            result.ends.push(cursor + 1);
+        }
+        result.offsets.push(range.end.offset - 1);
+        return result;
+    }
+    EvidenceMysqlDocumentation.read = read;
+})(EvidenceMysqlDocumentation || (exports.EvidenceMysqlDocumentation = EvidenceMysqlDocumentation = {}));

package/lib/adapters/mysql/EvidenceMysqlFileScanner.d.ts

@@ -0,0 +1,18 @@
+import type { IEvidenceSqlFileAnalysis } from "../sql/IEvidenceSqlFileAnalysis";
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+/**
+ * Enriches shared SQL extraction with MySQL COMMENT hosts and dialect policy.
+ *
+ * This namespace supplies the scanner callback used by the MySQL adapter.
+ */
+export declare namespace EvidenceMysqlFileScanner {
+    /**
+     * Attaches only table and column COMMENT strings to their exact declaration
+     * owner.
+     *
+     * Shared SQL scanning supplies declarations; this pass adds dialect-specific
+     * documentation.
+     */
+    function scan(session: EvidenceParseSession, source: IEvidenceSourceFile): IEvidenceSqlFileAnalysis;
+}

package/lib/adapters/mysql/EvidenceMysqlFileScanner.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceMysqlFileScanner = void 0;
+const EvidenceMysqlDocumentation_1 = require("./EvidenceMysqlDocumentation");
+const EvidenceMysqlPolicy_1 = require("./EvidenceMysqlPolicy");
+const EvidenceSqlFileScanner_1 = require("../sql/EvidenceSqlFileScanner");
+const EvidenceSourceText_1 = require("../../internal/EvidenceSourceText");
+/**
+ * Enriches shared SQL extraction with MySQL COMMENT hosts and dialect policy.
+ *
+ * This namespace supplies the scanner callback used by the MySQL adapter.
+ */
+var EvidenceMysqlFileScanner;
+(function (EvidenceMysqlFileScanner) {
+    /**
+     * Attaches only table and column COMMENT strings to their exact declaration
+     * owner.
+     *
+     * Shared SQL scanning supplies declarations; this pass adds dialect-specific
+     * documentation.
+     */
+    function scan(session, source) {
+        const analysis = new EvidenceSqlFileScanner_1.EvidenceSqlFileScanner(session, source, EvidenceMysqlPolicy_1.EvidenceMysqlPolicy).scan();
+        const text = new EvidenceSourceText_1.EvidenceSourceText(source.content);
+        for (const node of descendants(session.root)) {
+            if (node.type !== "column_definition" && node.type !== "create_table")
+                continue;
+            const owner = analysis.declarations.find((declaration) => declaration.site.range.start.offset === node.startIndex);
+            if (owner === undefined)
+                continue;
+            const ranges = node.type === "column_definition"
+                ? node.namedChildren
+                    .filter((child) => child.type !== "comment" && child.type !== "marginalia")
+                    .filter((child, index, children) => child.type === "literal" &&
+                    children[index - 1]?.type === "keyword_comment")
+                    .map((literal) => session.range(literal))
+                : node.namedChildren
+                    .filter((child) => child.type === "table_option" &&
+                    /^COMMENT\s*=/i.test(child.text))
+                    .map((child) => {
+                    // The upstream grammar hides table-option string tokens; ownership comes from the complete option node.
+                    const offset = child.text.indexOf("=") + 1;
+                    const value = child.text.slice(offset);
+                    const whitespace = value.length - value.trimStart().length;
+                    return text.range(child.startIndex + offset + whitespace, child.endIndex);
+                });
+            for (const range of ranges) {
+                const id = `${source.id}:mysql-comment:${range.start.offset}`;
+                const mapped = EvidenceMysqlDocumentation_1.EvidenceMysqlDocumentation.read(source.content, range, id);
+                if (mapped === undefined) {
+                    analysis.complete = false;
+                    analysis.diagnostics.push({
+                        code: "mysql-comment-mode",
+                        severity: "error",
+                        message: "The MySQL COMMENT literal requires an unsupported string or server escape mode.",
+                        repair: "Use a single-quoted COMMENT literal with doubled apostrophes and no backslash escapes.",
+                        location: { file: source.physicalPath, range },
+                    });
+                    continue;
+                }
+                analysis.documentation.push({
+                    id,
+                    range,
+                    mapped,
+                    attachments: [{ declarationId: owner.id, siteId: owner.site.id }],
+                });
+            }
+        }
+        return analysis;
+    }
+    EvidenceMysqlFileScanner.scan = scan;
+})(EvidenceMysqlFileScanner || (exports.EvidenceMysqlFileScanner = EvidenceMysqlFileScanner = {}));
+/**
+ * Visits named syntax while keeping all attachment decisions local to
+ * declarations.
+ *
+ * String contents remain opaque because they are not grammar nodes in the
+ * traversal.
+ */
+function descendants(node) {
+    return [node, ...node.namedChildren.flatMap(descendants)];
+}

package/lib/adapters/mysql/EvidenceMysqlIdentifier.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Defines source-spelled MySQL names without consulting server or filesystem
+ * settings.
+ *
+ * The adapter preserves this deterministic identity across hosts with different
+ * server policy.
+ */
+export declare namespace EvidenceMysqlIdentifier {
+    /**
+     * Unquotes backticks and rejects other dialect delimiters or ANSI quotes.
+     *
+     * Their interpretation can depend on server configuration outside a source
+     * snapshot.
+     */
+    function read(raw: string): string | undefined;
+}

package/lib/adapters/mysql/EvidenceMysqlIdentifier.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceMysqlIdentifier = void 0;
+/**
+ * Defines source-spelled MySQL names without consulting server or filesystem
+ * settings.
+ *
+ * The adapter preserves this deterministic identity across hosts with different
+ * server policy.
+ */
+var EvidenceMysqlIdentifier;
+(function (EvidenceMysqlIdentifier) {
+    /**
+     * Unquotes backticks and rejects other dialect delimiters or ANSI quotes.
+     *
+     * Their interpretation can depend on server configuration outside a source
+     * snapshot.
+     */
+    function read(raw) {
+        if (raw.includes("\0") || /[\uD800-\uDFFF]/.test(raw))
+            return undefined;
+        if (raw.startsWith("`")) {
+            if (!/^`(?:[^`]|``)+`$/u.test(raw))
+                return undefined;
+            const name = raw.slice(1, -1).replaceAll("``", "`");
+            return name.endsWith(" ") ? undefined : name;
+        }
+        return /^[A-Za-z_\u0080-\uFFFF][A-Za-z_0-9$\u0080-\uFFFF]*$/u.test(raw)
+            ? raw
+            : undefined;
+    }
+    EvidenceMysqlIdentifier.read = read;
+})(EvidenceMysqlIdentifier || (exports.EvidenceMysqlIdentifier = EvidenceMysqlIdentifier = {}));

package/lib/adapters/mysql/EvidenceMysqlPolicy.d.ts

@@ -0,0 +1,48 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import { EvidenceMysqlIdentifier } from "./EvidenceMysqlIdentifier";
+/**
+ * Validates the explicitly selected MySQL CREATE TABLE source subset.
+ *
+ * Shared SQL extraction asks this policy to fail closed when syntax depends on
+ * server state.
+ */
+export declare namespace EvidenceMysqlPolicy {
+    /**
+     * Retains source spelling independently of lower_case_table_names and host
+     * operating system.
+     *
+     * Snapshot identity cannot safely depend on a database server or filesystem
+     * setting.
+     */
+    const identifier: typeof EvidenceMysqlIdentifier.read;
+    /**
+     * Ignores column REFERENCES because MySQL does not create a foreign key from
+     * that syntax.
+     *
+     * Only a table-level FOREIGN KEY declaration contributes a relation unit.
+     */
+    const inlineReferences: "ignore";
+    /**
+     * Ignores FOREIGN KEY index names when identifying MySQL relations.
+     *
+     * The endpoint tuple is stable while an index name does not name the
+     * constraint.
+     */
+    const constraintNames = false;
+    /**
+     * Places an unqualified REFERENCES target in its explicitly qualified owning
+     * database.
+     *
+     * This supplies a deterministic semantic path without consulting the current
+     * database.
+     */
+    function reference(target: string[], owner: string[]): string[];
+    /**
+     * Rejects environment state and syntax from the shared grammar's other
+     * dialects.
+     *
+     * Returning a reason makes the source analysis incomplete rather than
+     * partially inferred.
+     */
+    function validate(node: EvidenceNode): string | undefined;
+}