@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/EvidenceChecker.d.ts

@@ -2,7 +2,8 @@ import type { IEvidenceCheckAnalysis } from "./structures/IEvidenceCheckAnalysis
 import type { IEvidenceCheckReport } from "./structures/IEvidenceCheckReport";
 import type { IEvidenceConfigPlan } from "./structures/IEvidenceConfigPlan";
 /**
- * Runs configuration-driven extraction, target resolution, and graph evaluation.
+ * Runs configuration-driven extraction, target resolution, and graph
+ * evaluation.
  *
  * Use `check` for the command report, or `analyze` when queries also need the
  * captured inventories and graph relationships. Both operations reload the
@@ -15,10 +16,12 @@ import type { IEvidenceConfigPlan } from "./structures/IEvidenceConfigPlan";
  * the same operations for callers that do not need to retain a facade.
  *
  * @example
- * const checker: EvidenceChecker = new EvidenceChecker("evidence.config.ts");
- * const report: IEvidenceCheckReport = await checker.check();
- * // A subsequent call reloads the configuration and selected source files.
- * const updated: IEvidenceCheckReport = await checker.check();
+ *   const checker: EvidenceChecker = new EvidenceChecker(
+ *     "evidence.config.ts",
+ *   );
+ *   const report: IEvidenceCheckReport = await checker.check();
+ *   // A subsequent call reloads the configuration and selected source files.
+ *   const updated: IEvidenceCheckReport = await checker.check();
  */
 export declare class EvidenceChecker {
     /**
@@ -31,23 +34,25 @@ export declare class EvidenceChecker {
     /**
      * Selects the configuration file for subsequent checks.
      *
-     * Construction performs no file access or parser initialization. Omission uses
-     * `evidence.config.ts`; the loader resolves the supplied path when work begins.
+     * Construction performs no file access or parser initialization. Omission
+     * uses `evidence.config.ts`; the loader resolves the supplied path when work
+     * begins.
      */
     constructor(configFile?: string);
     /**
      * Reloads configuration and returns the complete analysis of its populations.
      *
-     * The result retains graph input, graph evaluation, and the command report for
-     * queries against the same source snapshots. Configuration loading failures
-     * reject the call; materialized analysis findings remain in the result.
+     * The result retains graph input, graph evaluation, and the command report
+     * for queries against the same source snapshots. Configuration loading
+     * failures reject the call; materialized analysis findings remain in the
+     * result.
      */
     analyze(): Promise<IEvidenceCheckAnalysis>;
     /**
      * Analyzes one configuration through a temporary checker.
      *
-     * This is the static convenience form of the instance `analyze` operation.
-     * It returns captured graph context as well as the report, suitable for a
+     * This is the static convenience form of the instance `analyze` operation. It
+     * returns captured graph context as well as the report, suitable for a
      * subsequent list, inspection, or graph export without another source load.
      */
     static analyze(configFile?: string): Promise<IEvidenceCheckAnalysis>;
@@ -55,7 +60,8 @@ export declare class EvidenceChecker {
      * Runs a fresh analysis and returns its command-facing result.
      *
      * Use this when counts, diagnostics, and exit status are sufficient. Call
-     * `analyze` instead when the caller also needs materialized units for queries.
+     * `analyze` instead when the caller also needs materialized units for
+     * queries.
      */
     check(): Promise<IEvidenceCheckReport>;
     /**
@@ -78,8 +84,8 @@ export declare class EvidenceChecker {
      * Evaluates a resolved plan through a temporary checker.
      *
      * The plan supplies its configuration location and is copied by the instance
-     * operation. This entry point skips configuration loading while retaining fresh
-     * source materialization and per-invocation graph state.
+     * operation. This entry point skips configuration loading while retaining
+     * fresh source materialization and per-invocation graph state.
      */
     static evaluate(input: IEvidenceConfigPlan): Promise<IEvidenceCheckAnalysis>;
 }

package/lib/EvidenceChecker.js

@@ -4,7 +4,8 @@ exports.EvidenceChecker = void 0;
 const EvidenceConfigLoader_1 = require("./loaders/EvidenceConfigLoader");
 const EvidenceCheckProgrammer_1 = require("./programmers/EvidenceCheckProgrammer");
 /**
- * Runs configuration-driven extraction, target resolution, and graph evaluation.
+ * Runs configuration-driven extraction, target resolution, and graph
+ * evaluation.
  *
  * Use `check` for the command report, or `analyze` when queries also need the
  * captured inventories and graph relationships. Both operations reload the
@@ -17,10 +18,12 @@ const EvidenceCheckProgrammer_1 = require("./programmers/EvidenceCheckProgrammer
  * the same operations for callers that do not need to retain a facade.
  *
  * @example
- * const checker: EvidenceChecker = new EvidenceChecker("evidence.config.ts");
- * const report: IEvidenceCheckReport = await checker.check();
- * // A subsequent call reloads the configuration and selected source files.
- * const updated: IEvidenceCheckReport = await checker.check();
+ *   const checker: EvidenceChecker = new EvidenceChecker(
+ *     "evidence.config.ts",
+ *   );
+ *   const report: IEvidenceCheckReport = await checker.check();
+ *   // A subsequent call reloads the configuration and selected source files.
+ *   const updated: IEvidenceCheckReport = await checker.check();
  */
 class EvidenceChecker {
     /**
@@ -33,8 +36,9 @@ class EvidenceChecker {
     /**
      * Selects the configuration file for subsequent checks.
      *
-     * Construction performs no file access or parser initialization. Omission uses
-     * `evidence.config.ts`; the loader resolves the supplied path when work begins.
+     * Construction performs no file access or parser initialization. Omission
+     * uses `evidence.config.ts`; the loader resolves the supplied path when work
+     * begins.
      */
     constructor(configFile = "evidence.config.ts") {
         this.configFile = configFile;
@@ -42,9 +46,10 @@ class EvidenceChecker {
     /**
      * Reloads configuration and returns the complete analysis of its populations.
      *
-     * The result retains graph input, graph evaluation, and the command report for
-     * queries against the same source snapshots. Configuration loading failures
-     * reject the call; materialized analysis findings remain in the result.
+     * The result retains graph input, graph evaluation, and the command report
+     * for queries against the same source snapshots. Configuration loading
+     * failures reject the call; materialized analysis findings remain in the
+     * result.
      */
     async analyze() {
         return this.evaluate(await EvidenceConfigLoader_1.EvidenceConfigLoader.plan(this.configFile));
@@ -52,8 +57,8 @@ class EvidenceChecker {
     /**
      * Analyzes one configuration through a temporary checker.
      *
-     * This is the static convenience form of the instance `analyze` operation.
-     * It returns captured graph context as well as the report, suitable for a
+     * This is the static convenience form of the instance `analyze` operation. It
+     * returns captured graph context as well as the report, suitable for a
      * subsequent list, inspection, or graph export without another source load.
      */
     static async analyze(configFile = "evidence.config.ts") {
@@ -63,7 +68,8 @@ class EvidenceChecker {
      * Runs a fresh analysis and returns its command-facing result.
      *
      * Use this when counts, diagnostics, and exit status are sufficient. Call
-     * `analyze` instead when the caller also needs materialized units for queries.
+     * `analyze` instead when the caller also needs materialized units for
+     * queries.
      */
     async check() {
         return (await this.analyze()).report;
@@ -99,8 +105,8 @@ class EvidenceChecker {
      * Evaluates a resolved plan through a temporary checker.
      *
      * The plan supplies its configuration location and is copied by the instance
-     * operation. This entry point skips configuration loading while retaining fresh
-     * source materialization and per-invocation graph state.
+     * operation. This entry point skips configuration loading while retaining
+     * fresh source materialization and per-invocation graph state.
      */
     static async evaluate(input) {
         return new EvidenceChecker(input.configFile).evaluate(input);

package/lib/adapters/bigquery/EvidenceBigQueryAdapter.d.ts

@@ -1,17 +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 declared GoogleSQL tables, fields, and key relations for BigQuery populations.
+ * Extracts declared GoogleSQL tables, fields, and key relations for BigQuery
+ * populations.
  *
- * The BigQuery scanner applies GoogleSQL qualification and declaration rules before
- * shared SQL materialization creates public units and annotation hosts. Analysis
- * operates on source snapshots without querying a service or executing SQL.
+ * The BigQuery scanner applies GoogleSQL qualification and declaration rules
+ * before shared SQL materialization creates public units and annotation hosts.
+ * Analysis operates on source snapshots without querying a service or executing
+ * SQL.
  */
-export declare class EvidenceBigQueryAdapter extends SqlAdapter {
+export declare class EvidenceBigQueryAdapter implements IEvidenceAdapter<"bigquery"> {
     /**
-     * Selects the GoogleSQL grammar and BigQuery declaration scanner.
+     * GoogleSQL grammar selected for this adapter.
      *
-     * The configured dialect controls interpretation even when input shares the .sql
-     * suffix with other database families.
+     * The explicit discriminator preserves BigQuery's declaration semantics for
+     * files that otherwise share the `.sql` extension with other dialects.
      */
-    constructor();
+    get type(): "bigquery";
+    /**
+     * Materializes BigQuery scanner records into graph-facing inventory records.
+     *
+     * BigQuery-specific parsing remains in its scanner; this collaborator owns
+     * only parser lifetime and syntax-independent SQL publication.
+     */
+    private readonly materializer;
+    /**
+     * Extracts BigQuery declarations from one captured source snapshot.
+     *
+     * The configured grammar controls interpretation even when input shares the
+     * `.sql` suffix with other database families.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
 }

package/lib/adapters/bigquery/EvidenceBigQueryAdapter.js

@@ -1,27 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceBigQueryAdapter = void 0;
-const BigQueryFileScanner_1 = require("./BigQueryFileScanner");
-const SqlAdapter_1 = require("../sql/SqlAdapter");
+const EvidenceBigQueryFileScanner_1 = require("./EvidenceBigQueryFileScanner");
+const EvidenceSqlInventoryMaterializer_1 = require("../sql/EvidenceSqlInventoryMaterializer");
+const EVID_BIGQUERY_TYPE = "bigquery";
 /**
- * Extracts declared GoogleSQL tables, fields, and key relations for BigQuery populations.
+ * Extracts declared GoogleSQL tables, fields, and key relations for BigQuery
+ * populations.
  *
- * The BigQuery scanner applies GoogleSQL qualification and declaration rules before
- * shared SQL materialization creates public units and annotation hosts. Analysis
- * operates on source snapshots without querying a service or executing SQL.
+ * The BigQuery scanner applies GoogleSQL qualification and declaration rules
+ * before shared SQL materialization creates public units and annotation hosts.
+ * Analysis operates on source snapshots without querying a service or executing
+ * SQL.
  */
-class EvidenceBigQueryAdapter extends SqlAdapter_1.SqlAdapter {
+class EvidenceBigQueryAdapter {
     /**
-     * Selects the GoogleSQL grammar and BigQuery declaration scanner.
+     * GoogleSQL grammar selected for this adapter.
      *
-     * The configured dialect controls interpretation even when input shares the .sql
-     * suffix with other database families.
+     * The explicit discriminator preserves BigQuery's declaration semantics for
+     * files that otherwise share the `.sql` extension with other dialects.
      */
-    constructor() {
-        super({
-            type: "bigquery",
-            scan: (session, source) => new BigQueryFileScanner_1.BigQueryFileScanner(session, source).scan(),
-        });
+    get type() {
+        return EVID_BIGQUERY_TYPE;
+    }
+    /**
+     * Materializes BigQuery scanner records into graph-facing inventory records.
+     *
+     * BigQuery-specific parsing remains in its scanner; this collaborator owns
+     * only parser lifetime and syntax-independent SQL publication.
+     */
+    materializer = new EvidenceSqlInventoryMaterializer_1.EvidenceSqlInventoryMaterializer({
+        type: EVID_BIGQUERY_TYPE,
+        scan: (session, source) => new EvidenceBigQueryFileScanner_1.EvidenceBigQueryFileScanner(session, source).scan(),
+    });
+    /**
+     * Extracts BigQuery declarations from one captured source snapshot.
+     *
+     * The configured grammar controls interpretation even when input shares the
+     * `.sql` suffix with other database families.
+     */
+    analyze(snapshot) {
+        return this.materializer.analyze(snapshot);
     }
 }
 exports.EvidenceBigQueryAdapter = EvidenceBigQueryAdapter;

package/lib/adapters/bigquery/EvidenceBigQueryColumnType.d.ts

@@ -0,0 +1,17 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+/**
+ * Bounds the grammar's permissive type names to declared GoogleSQL schema
+ * types.
+ *
+ * Tree-sitter accepts broader syntax than this adapter can materialize safely,
+ * so the scanner rejects fields outside this explicit semantic surface.
+ */
+export declare namespace EvidenceBigQueryColumnType {
+    /**
+     * Checks scalar leaves and structural envelopes.
+     *
+     * Nested fields are validated separately by the scanner; replacing them with
+     * `FIELD` here verifies only the enclosing ARRAY or STRUCT shape.
+     */
+    function supported(node: EvidenceNode): boolean;
+}

package/lib/adapters/bigquery/EvidenceBigQueryColumnType.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceBigQueryColumnType = void 0;
+/**
+ * Bounds the grammar's permissive type names to declared GoogleSQL schema
+ * types.
+ *
+ * Tree-sitter accepts broader syntax than this adapter can materialize safely,
+ * so the scanner rejects fields outside this explicit semantic surface.
+ */
+var EvidenceBigQueryColumnType;
+(function (EvidenceBigQueryColumnType) {
+    /**
+     * Checks scalar leaves and structural envelopes.
+     *
+     * Nested fields are validated separately by the scanner; replacing them with
+     * `FIELD` here verifies only the enclosing ARRAY or STRUCT shape.
+     */
+    function supported(node) {
+        const nested = node.namedChildren.filter((child) => child.type === "column_definition");
+        let envelope = node.text;
+        for (const child of [...nested].reverse()) {
+            const from = child.startIndex - node.startIndex;
+            const until = child.endIndex - node.startIndex;
+            envelope = `${envelope.slice(0, from)}FIELD${envelope.slice(until)}`;
+        }
+        envelope = envelope.replace(/\s+/gu, "").toUpperCase();
+        if (nested.length !== 0)
+            return /^(?:STRUCT<FIELD(?:,FIELD)*>|ARRAY<STRUCT<FIELD(?:,FIELD)*>>)$/u.test(envelope);
+        if (envelope.startsWith("ARRAY<") && envelope.endsWith(">"))
+            envelope = envelope.slice(6, -1);
+        return (/^(?:INT64|INT|SMALLINT|INTEGER|BIGINT|TINYINT|BYTEINT|FLOAT64|FLOAT|BOOL|BOOLEAN|DATE|DATETIME|TIME|TIMESTAMP|INTERVAL|JSON|GEOGRAPHY)$/u.test(envelope) ||
+            /^(?:STRING|BYTES)(?:\(\d+\))?$/u.test(envelope) ||
+            /^(?:NUMERIC|DECIMAL|BIGNUMERIC|BIGDECIMAL)(?:\(\d+(?:,\d+)?\))?$/u.test(envelope));
+    }
+    EvidenceBigQueryColumnType.supported = supported;
+})(EvidenceBigQueryColumnType || (exports.EvidenceBigQueryColumnType = EvidenceBigQueryColumnType = {}));

package/lib/adapters/bigquery/EvidenceBigQueryFileScanner.d.ts

@@ -0,0 +1,112 @@
+import type { IEvidenceSqlFileAnalysis } from "../sql/IEvidenceSqlFileAnalysis";
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+/**
+ * Extracts supported BigQuery schema declarations from one parsed source file.
+ *
+ * The scanner publishes only explicit, complete DDL so unsupported syntax
+ * cannot reduce the inventory used to evaluate coverage.
+ */
+export declare class EvidenceBigQueryFileScanner {
+    private readonly session;
+    private readonly source;
+    /**
+     * Accumulates the serializable result for this source file.
+     *
+     * Every declaration, documentation carrier, and diagnostic returned by scan
+     * belongs here.
+     */
+    private readonly output;
+    /**
+     * Maps original source offsets without normalizing line endings.
+     *
+     * Comment attachment relies on the physical UTF-16 positions from this source
+     * snapshot.
+     */
+    private readonly text;
+    /**
+     * Binds one completed GoogleSQL tree to the source it represents.
+     *
+     * The scanner borrows both inputs for this extraction and never retains
+     * parser nodes in its result.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Extracts declarations and documentation from the supported BigQuery DDL
+     * surface.
+     *
+     * Unsupported statements mark the analysis incomplete before the result is
+     * returned.
+     */
+    scan(): IEvidenceSqlFileAnalysis;
+    /**
+     * Publishes a table only when its full schema is declared in this statement.
+     *
+     * Query-derived and inferred schemas cannot define a reliable Evidence
+     * inventory.
+     */
+    private table;
+    /**
+     * Publishes a column or nested STRUCT field under its table owner.
+     *
+     * Field paths preserve nested schema identity while ownership remains with
+     * the containing table.
+     */
+    private column;
+    /**
+     * Interprets constraints that affect the declared table surface.
+     *
+     * Primary keys remain table semantics, while foreign keys become
+     * independently selectable relations.
+     */
+    private constraint;
+    /**
+     * Publishes a foreign-key relation with a stable endpoint-based identity.
+     *
+     * Anonymous composite keys must not depend on their incidental statement
+     * order.
+     */
+    private relation;
+    /**
+     * Rejects key constraints that claim unsupported enforcement semantics.
+     *
+     * BigQuery keys still describe schema, but enforcement changes their
+     * operational meaning.
+     */
+    private enforcement;
+    /**
+     * Reads description strings from OPTIONS clauses attached to one declaration.
+     *
+     * Restricting the search to this node prevents nested or unrelated strings
+     * becoming documentation.
+     */
+    private options;
+    /**
+     * Attaches contiguous standalone comments to their following declarations.
+     *
+     * Comments embedded in examples or strings stay inert because they are not
+     * documentation carriers.
+     */
+    private comment;
+    /**
+     * Determines whether a comment begins on otherwise blank source text.
+     *
+     * Trailing comments must not be reassigned as documentation for the next
+     * declaration.
+     */
+    private standalone;
+    /**
+     * Constructs one serializable declaration site with exact source ranges.
+     *
+     * The site records physical location separately from the semantic identity
+     * used across files.
+     */
+    private declare;
+    /**
+     * Marks unsupported schema-changing syntax as an analysis failure.
+     *
+     * This preserves the failed scan instead of allowing a smaller inventory to
+     * pass coverage.
+     */
+    private fail;
+}