@deepagents/text2sql 4.3.0 → 6.0.0

package/dist/lib/adapters/bigquery/index.js

@@ -2,10 +2,10 @@
 import { format as formatSql } from "sql-formatter";
 
 // packages/text2sql/src/lib/agents/exceptions.ts
-var sqlValidationMarker = Symbol("SQLValidationError");
-var unanswerableSqlMarker = Symbol("UnanswerableSQLError");
-var sqlScopeMarker = Symbol("SQLScopeError");
-var sqlReadOnlyMarker = Symbol("SQLReadOnlyError");
+var sqlValidationMarker = /* @__PURE__ */ Symbol("SQLValidationError");
+var unanswerableSqlMarker = /* @__PURE__ */ Symbol("UnanswerableSQLError");
+var sqlScopeMarker = /* @__PURE__ */ Symbol("SQLScopeError");
+var sqlReadOnlyMarker = /* @__PURE__ */ Symbol("SQLReadOnlyError");
 var SQLValidationError = class _SQLValidationError extends Error {
   [sqlValidationMarker];
   constructor(message) {
@@ -170,159 +170,15 @@ function createGroundingContext(options = {}) {
   };
 }
 
-// packages/text2sql/src/lib/adapters/runtime-scope.ts
-import nodeSqlParser from "node-sql-parser";
-var { Parser } = nodeSqlParser;
-var parser = new Parser();
-function parseStatementTypes(sql, dialect) {
-  const ast = parser.astify(sql, { database: dialect });
-  const statements = Array.isArray(ast) ? ast : [ast];
-  return statements.flatMap(
-    (statement) => isAstLike(statement) && typeof statement.type === "string" ? [statement.type] : []
-  );
-}
-function extractBaseEntityReferences(sql, dialect) {
-  const ast = parser.astify(sql, { database: dialect });
-  const state = {
-    cteNames: /* @__PURE__ */ new Set(),
-    references: /* @__PURE__ */ new Map()
-  };
-  visitNode(ast, state);
-  return Array.from(state.references.values());
-}
-function buildOutOfScopePayload(sql, referencedEntities, allowedEntities) {
-  return {
-    error: `Query references entities outside grounded scope: ${referencedEntities.join(", ")}`,
-    error_type: "OUT_OF_SCOPE",
-    suggestion: "Restrict the query to grounded tables/views or expand grounding to include the referenced entities.",
-    sql_attempted: sql,
-    referenced_entities: referencedEntities,
-    allowed_entities: allowedEntities
-  };
-}
-function buildScopeParseErrorPayload(sql, dialect, error) {
-  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
-  return {
-    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
-    error_type: "SQL_SCOPE_PARSE_ERROR",
-    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
-    sql_attempted: sql,
-    parser_dialect: dialect,
-    parser_error: parserError
-  };
-}
-function visitNode(node, state) {
-  if (Array.isArray(node)) {
-    for (const item of node) {
-      visitNode(item, state);
-    }
-    return;
-  }
-  if (!isAstLike(node)) {
-    return;
-  }
-  if (isStatementNode(node)) {
-    visitStatement(node, state);
-    return;
-  }
-  if (isTableReferenceNode(node)) {
-    addReference(node, state);
-  }
-  for (const value of Object.values(node)) {
-    visitNode(value, state);
-  }
-}
-function visitStatement(node, parentState) {
-  const localState = {
-    cteNames: new Set(parentState.cteNames),
-    references: parentState.references
-  };
-  const withItems = Array.isArray(node.with) ? node.with : [];
-  for (const item of withItems) {
-    if (!isAstLike(item)) {
-      continue;
-    }
-    const cteName = readCteName(item);
-    if (cteName) {
-      localState.cteNames.add(caseFold(cteName));
-    }
-  }
-  for (const item of withItems) {
-    if (!isAstLike(item)) {
-      continue;
-    }
-    visitNode(item.stmt, localState);
-  }
-  for (const [key, value] of Object.entries(node)) {
-    if (key === "with") {
-      continue;
-    }
-    visitNode(value, localState);
-  }
-}
-function addReference(node, state) {
-  const table2 = typeof node.table === "string" ? node.table : null;
-  if (!table2) {
-    return;
-  }
-  if (state.cteNames.has(caseFold(table2))) {
-    return;
-  }
-  const db = typeof node.db === "string" ? node.db : null;
-  const key = db ? `${db}.${table2}` : table2;
-  if (!state.references.has(key)) {
-    state.references.set(key, { db, table: table2 });
-  }
-}
-function readCteName(node) {
-  const name = node.name;
-  if (typeof name === "string") {
-    return name;
-  }
-  if (!isAstLike(name)) {
-    return void 0;
-  }
-  const value = name.value;
-  return typeof value === "string" ? value : void 0;
-}
-function isStatementNode(node) {
-  const type = node.type;
-  return typeof type === "string" && ["delete", "insert", "replace", "select", "update"].includes(type);
-}
-function isTableReferenceNode(node) {
-  if (node.type === "column_ref") {
-    return false;
-  }
-  if (typeof node.table !== "string") {
-    return false;
-  }
-  return "addition" in node || "as" in node || "db" in node || "join" in node || "operator" in node || "surround" in node || "table_hint" in node || "temporal_table" in node;
-}
-function isAstLike(value) {
-  return typeof value === "object" && value !== null;
-}
-function caseFold(value) {
-  return value.toLowerCase();
-}
-
 // packages/text2sql/src/lib/adapters/adapter.ts
-var PARSER_DIALECTS_BY_FORMATTER_LANGUAGE = {
-  sqlite: ["sqlite", "mysql"],
-  postgresql: ["postgresql"],
-  bigquery: ["bigquery"],
-  transactsql: ["transactsql"],
-  mysql: ["mysql"]
-};
-function parserDialectsFor(formatterLanguage) {
-  const candidates = PARSER_DIALECTS_BY_FORMATTER_LANGUAGE[formatterLanguage];
-  if (!candidates) {
-    throw new TypeError(
-      `No scope dialect mapping for formatter language "${formatterLanguage}". Add it to PARSER_DIALECTS_BY_FORMATTER_LANGUAGE in adapter.ts.`
-    );
-  }
-  return candidates;
-}
 var Adapter = class {
+  #policyAnalyzer;
+  /**
+   * Injects the strategy that guards validate() and execute().
+   */
+  constructor(policyAnalyzer) {
+    this.#policyAnalyzer = policyAnalyzer;
+  }
   /**
    * Introspect the database schema and return context fragments.
    *
@@ -358,14 +214,14 @@ var Adapter = class {
   }
   /**
    * Resolve the allowed entity names (tables + views) from grounding config.
-   * Runs all configured groundings and returns the resolved set of names.
+   * Asks each grounding to contribute its entities; annotators contribute
+   * nothing, so their metadata scans are skipped.
    * Results are NOT cached — call once and store the result.
    */
   async resolveAllowedEntities() {
     const ctx = createGroundingContext();
     for (const fn of this.grounding) {
-      const grounding = fn(this);
-      await grounding.execute(ctx);
+      await fn(this).contributeEntities(ctx);
     }
     return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
   }
@@ -542,120 +398,33 @@ var Adapter = class {
   #decodeShellEscapes(sql) {
     return sql.replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\([().*])/g, "$1").replace(/\\(?=$)/gm, "");
   }
-  #checkReadOnly(sql) {
-    const statementTypes = this.#readParsedStatementTypes(sql);
-    if (statementTypes) {
-      if (statementTypes.length === 1 && statementTypes[0] === "select") {
-        return null;
-      }
-      return "only SELECT or WITH queries allowed";
-    }
-    const keyword = this.#firstStatementKeyword(sql);
-    if (keyword === "SELECT" || keyword === "WITH") return null;
-    return "only SELECT or WITH queries allowed";
-  }
-  #readParsedStatementTypes(sql) {
-    for (const dialect of parserDialectsFor(this.formatterLanguage)) {
-      try {
-        return parseStatementTypes(sql, dialect);
-      } catch {
-      }
-    }
-    return null;
-  }
-  #firstStatementKeyword(sql) {
-    let offset = 0;
-    while (offset < sql.length) {
-      if (/\s/.test(sql[offset])) {
-        offset++;
-        continue;
-      }
-      if (sql.startsWith("--", offset)) {
-        offset += 2;
-        while (offset < sql.length && sql[offset] !== "\n" && sql[offset] !== "\r") {
-          offset++;
-        }
-        continue;
-      }
-      if (sql.startsWith("/*", offset)) {
-        const commentEnd = sql.indexOf("*/", offset + 2);
-        if (commentEnd === -1) return null;
-        offset = commentEnd + 2;
-        continue;
-      }
-      const keyword = /^[A-Za-z]+/.exec(sql.slice(offset));
-      return keyword ? keyword[0].toUpperCase() : null;
-    }
-    return null;
-  }
   #cachedAllowedEntities = null;
   async #resolveScope() {
     if (this.#cachedAllowedEntities) return this.#cachedAllowedEntities;
     this.#cachedAllowedEntities = await this.resolveAllowedEntities();
     return this.#cachedAllowedEntities;
   }
-  async #checkScope(sql, allowedEntities) {
-    const candidates = parserDialectsFor(this.formatterLanguage);
-    let references = null;
-    let lastError;
-    let lastDialect = candidates[0];
-    for (const candidate of candidates) {
-      try {
-        references = extractBaseEntityReferences(sql, candidate);
-        break;
-      } catch (error) {
-        lastDialect = candidate;
-        lastError = error;
-      }
-    }
-    if (references === null) {
-      return buildScopeParseErrorPayload(sql, lastDialect, lastError);
-    }
-    if (references.length === 0) return null;
-    const allowedQualified = new Set(
-      allowedEntities.map((e) => e.toLowerCase())
-    );
-    const allowedUnqualified = /* @__PURE__ */ new Set();
-    for (const entity of allowedEntities) {
-      const dot = entity.lastIndexOf(".");
-      if (dot !== -1) {
-        allowedUnqualified.add(entity.slice(dot + 1).toLowerCase());
-      } else {
-        allowedUnqualified.add(entity.toLowerCase());
-      }
-    }
-    const outOfScope = references.map((ref) => ref.db ? `${ref.db}.${ref.table}` : ref.table).filter((name) => {
-      const lower = name.toLowerCase();
-      if (name.includes(".")) {
-        if (allowedQualified.has(lower)) return false;
-        const parts = lower.split(".");
-        if (parts.length >= 3) {
-          const datasetTable = parts.slice(-2).join(".");
-          if (allowedQualified.has(datasetTable)) return false;
-        }
-        return true;
-      }
-      return !allowedQualified.has(lower) && !allowedUnqualified.has(lower);
+  async #analyzePolicy(sql) {
+    return this.#policyAnalyzer.analyze(sql, {
+      resolveAllowedEntities: () => this.#resolveScope()
     });
-    if (outOfScope.length === 0) return null;
-    return buildOutOfScopePayload(sql, outOfScope, allowedEntities);
   }
   async validate(sql) {
     const decoded = this.#decodeShellEscapes(sql);
-    const readOnlyError = this.#checkReadOnly(decoded);
-    if (readOnlyError) return readOnlyError;
-    const allowed = await this.#resolveScope();
-    const scopeError = await this.#checkScope(decoded, allowed);
-    if (scopeError) return JSON.stringify(scopeError);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") return violation.message;
+    if (violation?.kind === "scope") return JSON.stringify(violation.payload);
     return this.validateImpl(decoded);
   }
   async execute(sql) {
     const decoded = this.#decodeShellEscapes(sql);
-    const readOnlyError = this.#checkReadOnly(decoded);
-    if (readOnlyError) throw new SQLReadOnlyError(readOnlyError);
-    const allowed = await this.#resolveScope();
-    const scopeError = await this.#checkScope(decoded, allowed);
-    if (scopeError) throw new SQLScopeError(scopeError);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") {
+      throw new SQLReadOnlyError(violation.message);
+    }
+    if (violation?.kind === "scope") {
+      throw new SQLScopeError(violation.payload);
+    }
     return this.executeImpl(decoded);
   }
   /**
@@ -736,6 +505,16 @@ var AbstractGrounding = class {
     this.name = name;
     this.phase = phase;
   }
+  /**
+   * Populate ctx with the tables/views this grounding makes available for scope
+   * resolution. Annotators decorate entities other groundings produced and add
+   * no membership, so the default is a no-op; entity-producing groundings
+   * override it. This lets scope resolution skip the annotators' metadata scans.
+   *
+   * @param _ctx - Shared context for accumulating entity membership
+   */
+  async contributeEntities(_ctx) {
+  }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
@@ -869,6 +648,9 @@ var TableGrounding = class extends AbstractGrounding {
     this.#forward = config.forward;
     this.#backward = config.backward;
   }
+  async contributeEntities(ctx) {
+    await this.execute(ctx);
+  }
   /**
    * Execute the grounding process.
    * Writes discovered tables and relationships to the context.
@@ -1014,6 +796,264 @@ var TableGrounding = class extends AbstractGrounding {
   }
 };
 
+// packages/text2sql/src/lib/adapters/parser-sql-policy.ts
+import nodeSqlParser from "node-sql-parser";
+
+// packages/text2sql/src/lib/sql-scope-error.ts
+function buildScopeParseErrorPayload(sql, parserDialect, error) {
+  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
+  return {
+    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
+    error_type: "SQL_SCOPE_PARSE_ERROR",
+    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
+    sql_attempted: sql,
+    parser_dialect: parserDialect,
+    parser_error: parserError
+  };
+}
+
+// packages/text2sql/src/lib/adapters/parser-sql-policy.ts
+var READ_ONLY_MESSAGE = "only SELECT or WITH queries allowed";
+var { Parser } = nodeSqlParser;
+var parser = new Parser();
+var ParserSqlPolicyAnalyzer = class {
+  readOnlyPolicy = {};
+  async analyze(sql, context) {
+    if (!this.#isReadOnly(sql)) {
+      return { kind: "read-only", message: READ_ONLY_MESSAGE };
+    }
+    const scopeError = await this.#checkScope(sql, context);
+    return scopeError ? { kind: "scope", payload: scopeError } : null;
+  }
+  #isReadOnly(sql) {
+    const statements = this.#readParsedStatements(sql);
+    if (statements) {
+      return statements.length === 1 && statements[0]?.type === "select" && !containsBlockedOperation(statements[0], this.readOnlyPolicy);
+    }
+    const keyword = firstStatementKeyword(sql);
+    return keyword === "SELECT" || keyword === "WITH";
+  }
+  #readParsedStatements(sql) {
+    for (const dialect of this.dialects) {
+      try {
+        return parseStatements(sql, dialect);
+      } catch {
+      }
+    }
+    return null;
+  }
+  async #checkScope(sql, context) {
+    let references = null;
+    let lastError;
+    let lastDialect = this.dialects[0];
+    for (const dialect of this.dialects) {
+      try {
+        references = extractBaseEntityReferences(sql, dialect);
+        break;
+      } catch (error) {
+        lastDialect = dialect;
+        lastError = error;
+      }
+    }
+    if (references === null) {
+      return buildScopeParseErrorPayload(sql, lastDialect, lastError);
+    }
+    if (references.length === 0) return null;
+    const allowedEntities = await context.resolveAllowedEntities();
+    const allowedQualified = new Set(
+      allowedEntities.map((entity) => entity.toLowerCase())
+    );
+    const allowedUnqualified = /* @__PURE__ */ new Set();
+    for (const entity of allowedEntities) {
+      const dot = entity.lastIndexOf(".");
+      allowedUnqualified.add(
+        (dot === -1 ? entity : entity.slice(dot + 1)).toLowerCase()
+      );
+    }
+    const outOfScope = references.map(
+      (reference) => reference.db ? `${reference.db}.${reference.table}` : reference.table
+    ).filter((name) => {
+      const lower = name.toLowerCase();
+      if (!name.includes(".")) {
+        return !allowedQualified.has(lower) && !allowedUnqualified.has(lower);
+      }
+      if (allowedQualified.has(lower)) return false;
+      const parts = lower.split(".");
+      return parts.length < 3 || !allowedQualified.has(parts.slice(-2).join("."));
+    });
+    return outOfScope.length === 0 ? null : buildOutOfScopePayload(sql, outOfScope, [...allowedEntities]);
+  }
+};
+function parseStatements(sql, dialect) {
+  const ast = parser.astify(sql, { database: dialect });
+  const statements = Array.isArray(ast) ? ast : [ast];
+  return statements.filter(isAstLike);
+}
+function containsBlockedOperation(node, policy) {
+  if (Array.isArray(node)) {
+    return node.some((item) => containsBlockedOperation(item, policy));
+  }
+  if (!isAstLike(node)) return false;
+  if (policy.blockSelectInto && node.type === "select" && isAstLike(node.into) && node.into.type === "into") {
+    return true;
+  }
+  if (policy.blockLockingReads && node.locking_read != null) return true;
+  if (policy.blockAssignments && node.type === "assign") return true;
+  if (policy.blockServerQualifiedRelations && isTableReferenceNode(node) && typeof node.server === "string") {
+    return true;
+  }
+  if (policy.blockTableHints && node.table_hint != null) return true;
+  if (node.type === "function") {
+    const functionIdentifier = readFunctionIdentifier(node);
+    if (functionIdentifier && policy.blockQualifiedFunctions && functionIdentifier.parts.length > 1) {
+      return true;
+    }
+    if (functionIdentifier && policy.blockedFunctions?.some(
+      (blocked) => blocked.toLowerCase() === functionIdentifier.parts.at(-1)
+    )) {
+      return true;
+    }
+    if (functionIdentifier && policy.blockedFunctionPrefixes?.some(
+      (prefix) => functionIdentifier.parts.at(-1)?.startsWith(prefix.toLowerCase())
+    )) {
+      return true;
+    }
+  }
+  return Object.values(node).some(
+    (value) => containsBlockedOperation(value, policy)
+  );
+}
+function readFunctionIdentifier(node) {
+  if (!isAstLike(node.name)) return null;
+  const parts = [];
+  if (isAstLike(node.name.schema) && typeof node.name.schema.value === "string") {
+    appendIdentifierParts(parts, node.name.schema.value);
+  }
+  const names = Array.isArray(node.name.name) ? node.name.name : [];
+  for (const name of names) {
+    if (isAstLike(name) && typeof name.value === "string") {
+      appendIdentifierParts(parts, name.value);
+    }
+  }
+  return parts.length > 0 ? { parts } : null;
+}
+function appendIdentifierParts(parts, value) {
+  parts.push(
+    ...value.toLowerCase().split(".").filter((part) => part.length > 0)
+  );
+}
+function extractBaseEntityReferences(sql, dialect) {
+  const ast = parser.astify(sql, { database: dialect });
+  const state = {
+    cteNames: /* @__PURE__ */ new Set(),
+    references: /* @__PURE__ */ new Map()
+  };
+  visitNode(ast, state);
+  return Array.from(state.references.values());
+}
+function firstStatementKeyword(sql) {
+  let offset = 0;
+  while (offset < sql.length) {
+    if (/\s/.test(sql[offset])) {
+      offset++;
+      continue;
+    }
+    if (sql.startsWith("--", offset)) {
+      offset += 2;
+      while (offset < sql.length && sql[offset] !== "\n" && sql[offset] !== "\r") {
+        offset++;
+      }
+      continue;
+    }
+    if (sql.startsWith("/*", offset)) {
+      const commentEnd = sql.indexOf("*/", offset + 2);
+      if (commentEnd === -1) return null;
+      offset = commentEnd + 2;
+      continue;
+    }
+    const keyword = /^[A-Za-z]+/.exec(sql.slice(offset));
+    return keyword ? keyword[0].toUpperCase() : null;
+  }
+  return null;
+}
+function buildOutOfScopePayload(sql, referencedEntities, allowedEntities) {
+  return {
+    error: `Query references entities outside grounded scope: ${referencedEntities.join(", ")}`,
+    error_type: "OUT_OF_SCOPE",
+    suggestion: "Restrict the query to grounded tables/views or expand grounding to include the referenced entities.",
+    sql_attempted: sql,
+    referenced_entities: referencedEntities,
+    allowed_entities: allowedEntities
+  };
+}
+function visitNode(node, state) {
+  if (Array.isArray(node)) {
+    for (const item of node) visitNode(item, state);
+    return;
+  }
+  if (!isAstLike(node)) return;
+  if (isStatementNode(node)) {
+    visitStatement(node, state);
+    return;
+  }
+  if (isTableReferenceNode(node)) addReference(node, state);
+  for (const value of Object.values(node)) visitNode(value, state);
+}
+function visitStatement(node, parentState) {
+  const localState = {
+    cteNames: new Set(parentState.cteNames),
+    references: parentState.references
+  };
+  const withItems = Array.isArray(node.with) ? node.with : [];
+  for (const item of withItems) {
+    if (!isAstLike(item)) continue;
+    const cteName = readCteName(item);
+    if (cteName) localState.cteNames.add(caseFold(cteName));
+  }
+  for (const item of withItems) {
+    if (isAstLike(item)) visitNode(item.stmt, localState);
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key !== "with") visitNode(value, localState);
+  }
+}
+function addReference(node, state) {
+  const table2 = typeof node.table === "string" ? node.table : null;
+  if (!table2 || state.cteNames.has(caseFold(table2))) return;
+  const db = typeof node.db === "string" ? node.db : null;
+  const key = db ? `${db}.${table2}` : table2;
+  if (!state.references.has(key)) state.references.set(key, { db, table: table2 });
+}
+function readCteName(node) {
+  const name = node.name;
+  if (typeof name === "string") return name;
+  if (!isAstLike(name)) return void 0;
+  return typeof name.value === "string" ? name.value : void 0;
+}
+function isStatementNode(node) {
+  return typeof node.type === "string" && ["delete", "insert", "replace", "select", "update"].includes(node.type);
+}
+function isTableReferenceNode(node) {
+  if (node.type === "column_ref" || typeof node.table !== "string")
+    return false;
+  return "addition" in node || "as" in node || "db" in node || "join" in node || "operator" in node || "surround" in node || "table_hint" in node || "temporal_table" in node;
+}
+function isAstLike(value) {
+  return typeof value === "object" && value !== null;
+}
+function caseFold(value) {
+  return value.toLowerCase();
+}
+
+// packages/text2sql/src/lib/adapters/bigquery/bigquery.sql-policy.ts
+var BigQuerySqlPolicyAnalyzer = class extends ParserSqlPolicyAnalyzer {
+  dialects = ["bigquery"];
+  readOnlyPolicy = {
+    blockQualifiedFunctions: true,
+    blockedFunctions: ["EXTERNAL_QUERY"]
+  };
+};
+
 // packages/text2sql/src/lib/adapters/bigquery/bigquery.ts
 function formatBigQueryError(sql, error) {
   const errorMessage = error instanceof Error ? error.message : typeof error === "string" ? error : typeof error === "object" && error !== null ? error.message ?? JSON.stringify(error) : "Unknown error occurred";
@@ -1032,7 +1072,7 @@ var BigQuery = class extends Adapter {
   systemSchemas = [];
   formatterLanguage = "bigquery";
   constructor(options) {
-    super();
+    super(new BigQuerySqlPolicyAnalyzer());
     if (!options || typeof options.execute !== "function") {
       throw new Error("BigQuery adapter requires an execute(sql) function.");
     }
@@ -1770,6 +1810,9 @@ var ViewGrounding = class extends AbstractGrounding {
     this.#columns = config.columns;
     this.includeDefinition = config.includeDefinition ?? true;
   }
+  async contributeEntities(ctx) {
+    await this.execute(ctx);
+  }
   /**
    * Execute the grounding process.
    * Writes discovered views to the context.
@@ -1904,6 +1947,7 @@ var bigquery_default = {
 };
 export {
   BigQuery,
+  BigQuerySqlPolicyAnalyzer,
   constraints,
   bigquery_default as default,
   indexes,