@wrtnlabs/evidence 0.0.0

package/lib/EvidenceChecker.d.ts

@@ -0,0 +1,85 @@
+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.
+ *
+ * Use `check` for the command report, or `analyze` when queries also need the
+ * captured inventories and graph relationships. Both operations reload the
+ * configured file. `evaluate` accepts an already resolved plan and captures its
+ * own copy before loading the selected populations.
+ *
+ * Each invocation owns its execution context. Reusing a checker does not retain
+ * coverage or diagnostics from a previous run, and concurrent evaluations can
+ * use different plans without sharing mutable claim state. Static methods offer
+ * 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();
+ */
+export declare class EvidenceChecker {
+    /**
+     * Configuration location used by `analyze` and `check`.
+     *
+     * Retaining a path does not retain its contents. Every invocation reloads the
+     * file so edits and recovery from an earlier load failure remain observable.
+     */
+    private readonly configFile;
+    /**
+     * 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.
+     */
+    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.
+     */
+    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
+     * subsequent list, inspection, or graph export without another source load.
+     */
+    static analyze(configFile?: string): Promise<IEvidenceCheckAnalysis>;
+    /**
+     * 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.
+     */
+    check(): Promise<IEvidenceCheckReport>;
+    /**
+     * Checks one configuration without retaining a facade.
+     *
+     * The configuration and its selected sources are loaded for this invocation.
+     * The returned report has the same status and diagnostic semantics as the
+     * instance `check` method.
+     */
+    static check(configFile?: string): Promise<IEvidenceCheckReport>;
+    /**
+     * Materializes and evaluates an explicitly supplied configuration plan.
+     *
+     * The plan is cloned before asynchronous extraction begins, isolating this
+     * invocation from caller mutation. It supplies resolved configuration policy;
+     * selected source inventories are still loaded afresh for the evaluation.
+     */
+    evaluate(input: IEvidenceConfigPlan): Promise<IEvidenceCheckAnalysis>;
+    /**
+     * 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.
+     */
+    static evaluate(input: IEvidenceConfigPlan): Promise<IEvidenceCheckAnalysis>;
+}

package/lib/EvidenceChecker.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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.
+ *
+ * Use `check` for the command report, or `analyze` when queries also need the
+ * captured inventories and graph relationships. Both operations reload the
+ * configured file. `evaluate` accepts an already resolved plan and captures its
+ * own copy before loading the selected populations.
+ *
+ * Each invocation owns its execution context. Reusing a checker does not retain
+ * coverage or diagnostics from a previous run, and concurrent evaluations can
+ * use different plans without sharing mutable claim state. Static methods offer
+ * 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();
+ */
+class EvidenceChecker {
+    /**
+     * Configuration location used by `analyze` and `check`.
+     *
+     * Retaining a path does not retain its contents. Every invocation reloads the
+     * file so edits and recovery from an earlier load failure remain observable.
+     */
+    configFile;
+    /**
+     * 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.
+     */
+    constructor(configFile = "evidence.config.ts") {
+        this.configFile = configFile;
+    }
+    /**
+     * 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.
+     */
+    async analyze() {
+        return this.evaluate(await EvidenceConfigLoader_1.EvidenceConfigLoader.plan(this.configFile));
+    }
+    /**
+     * 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
+     * subsequent list, inspection, or graph export without another source load.
+     */
+    static async analyze(configFile = "evidence.config.ts") {
+        return new EvidenceChecker(configFile).analyze();
+    }
+    /**
+     * 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.
+     */
+    async check() {
+        return (await this.analyze()).report;
+    }
+    /**
+     * Checks one configuration without retaining a facade.
+     *
+     * The configuration and its selected sources are loaded for this invocation.
+     * The returned report has the same status and diagnostic semantics as the
+     * instance `check` method.
+     */
+    static async check(configFile = "evidence.config.ts") {
+        return new EvidenceChecker(configFile).check();
+    }
+    /**
+     * Materializes and evaluates an explicitly supplied configuration plan.
+     *
+     * The plan is cloned before asynchronous extraction begins, isolating this
+     * invocation from caller mutation. It supplies resolved configuration policy;
+     * selected source inventories are still loaded afresh for the evaluation.
+     */
+    async evaluate(input) {
+        // Capture policy before awaiting extraction so a caller cannot change the
+        // plan halfway through building this invocation's independent populations.
+        const plan = structuredClone(input);
+        const context = {
+            plan,
+            claims: await EvidenceCheckProgrammer_1.EvidenceCheckProgrammer.materialize(plan),
+        };
+        return EvidenceCheckProgrammer_1.EvidenceCheckProgrammer.evaluate(context);
+    }
+    /**
+     * 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.
+     */
+    static async evaluate(input) {
+        return new EvidenceChecker(input.configFile).evaluate(input);
+    }
+}
+exports.EvidenceChecker = EvidenceChecker;

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

@@ -0,0 +1,14 @@
+import type { Node } 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 BigQueryColumnType {
+    /** 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: Node): boolean;
+}

package/lib/adapters/bigquery/BigQueryColumnType.js

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

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

@@ -0,0 +1,97 @@
+import type { ISqlFileAnalysis } from "../sql/ISqlFileAnalysis";
+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 BigQueryFileScanner {
+    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(): ISqlFileAnalysis;
+    /**
+     * 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;
+}