@deepagents/text2sql 0.29.1 → 0.30.0

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

@@ -1,6 +1,48 @@
 // packages/text2sql/src/lib/adapters/adapter.ts
 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 SQLValidationError = class _SQLValidationError extends Error {
+  [sqlValidationMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLValidationError";
+    this[sqlValidationMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[sqlValidationMarker] === true;
+  }
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  [unanswerableSqlMarker];
+  constructor(message) {
+    super(message);
+    this.name = "UnanswerableSQLError";
+    this[unanswerableSqlMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
+  }
+};
+var SQLScopeError = class _SQLScopeError extends Error {
+  [sqlScopeMarker];
+  payload;
+  errorType;
+  constructor(payload) {
+    super(JSON.stringify(payload));
+    this.name = "SQLScopeError";
+    this.payload = payload;
+    this.errorType = payload.error_type;
+    this[sqlScopeMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLScopeError && error[sqlScopeMarker] === true;
+  }
+};
+
 // packages/text2sql/src/lib/fragments/schema.ts
 function dialectInfo(input) {
   return {
@@ -104,6 +146,134 @@ function createGroundingContext() {
   };
 }
 
+// packages/text2sql/src/lib/adapters/runtime-scope.ts
+import nodeSqlParser from "node-sql-parser";
+var { Parser } = nodeSqlParser;
+var parser = new Parser();
+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 Adapter = class {
   /**
@@ -133,10 +303,7 @@ var Adapter = class {
       const grounding = fn(this);
       await grounding.execute(ctx);
     }
-    return [
-      ...ctx.tables.map((t) => t.name),
-      ...ctx.views.map((v) => v.name)
-    ];
+    return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
   }
   /**
    * Convert complete grounding context to schema fragments.
@@ -149,7 +316,8 @@ var Adapter = class {
         dialectInfo({
           dialect: ctx.info.dialect,
           version: ctx.info.version,
-          database: ctx.info.database
+          database: ctx.info.database,
+          details: ctx.info.details
         })
       );
     }
@@ -293,6 +461,78 @@ var Adapter = class {
       return sql;
     }
   }
+  #cachedAllowedEntities = null;
+  async #resolveScope() {
+    if (this.#cachedAllowedEntities) return this.#cachedAllowedEntities;
+    this.#cachedAllowedEntities = await this.resolveAllowedEntities();
+    return this.#cachedAllowedEntities;
+  }
+  async #checkScope(sql, allowedEntities) {
+    const dialect = this.formatterLanguage;
+    const scopeDialects = {
+      sqlite: "mysql",
+      postgresql: "postgresql",
+      bigquery: "bigquery",
+      transactsql: "transactsql",
+      mysql: "mysql"
+    };
+    const scopeDialect = scopeDialects[dialect];
+    if (!scopeDialect) {
+      throw new TypeError(
+        `No scope dialect mapping for formatter language "${dialect}". Add it to the scopeDialects map in Adapter.#checkScope.`
+      );
+    }
+    let references;
+    try {
+      references = extractBaseEntityReferences(sql, scopeDialect);
+    } catch (error) {
+      return buildScopeParseErrorPayload(
+        sql,
+        dialect,
+        error
+      );
+    }
+    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);
+    });
+    if (outOfScope.length === 0) return null;
+    return buildOutOfScopePayload(sql, outOfScope, allowedEntities);
+  }
+  async validate(sql) {
+    const allowed = await this.#resolveScope();
+    const scopeError = await this.#checkScope(sql, allowed);
+    if (scopeError) return JSON.stringify(scopeError);
+    return this.validateImpl(sql);
+  }
+  async execute(sql) {
+    const allowed = await this.#resolveScope();
+    const scopeError = await this.#checkScope(sql, allowed);
+    if (scopeError) throw new SQLScopeError(scopeError);
+    return this.executeImpl(sql);
+  }
   /**
    * Convert unknown database value to number.
    * Handles number, bigint, and string types.
@@ -1206,10 +1446,10 @@ var Sqlite = class extends Adapter {
     this.#options = options;
     this.grounding = options.grounding;
   }
-  async execute(sql) {
+  async executeImpl(sql) {
     return this.#options.execute(sql);
   }
-  async validate(sql) {
+  async validateImpl(sql) {
     const validator = this.#options.validate ?? (async (text) => {
       await this.#options.execute(`EXPLAIN ${text}`);
     });