@rex0220/kintone-sql-tools 3.28.0 → 3.30.0

package/README.md

@@ -7,8 +7,14 @@ kintone アプリを SQL 風の構文で操作するツールセットです。
 - MCP サーバー（AI クライアントから kintone を SQL 操作。Claude Desktop 用 MCPB 同梱）
 - read-only エンジン・ライブラリ（ESM / CJS / UMD）
 
-他の kintone プラグインやカスタマイズへ read-only kSQL エンジンを組み込む場合は、
-[エンジン・ライブラリ利用ガイド](docs/ksql_engine_library.md)を参照してください。
+他の kintone プラグインやカスタマイズへ read-only kSQL エンジンを組み込む場合は、
+[エンジン・ライブラリ利用ガイド](docs/ksql_engine_library.md)を参照してください。
+
+engine ライブラリでは、`runQuery()` が単文の `SELECT` / `WITH` / `UNION` /
+`SHOW APPS` / `DESCRIBE` / 既存レコード `VALIDATE` を、`runBatch()` がそれらに加えて
+`CREATE` / `DROP TEMP TABLE`、`SET` / `DECLARE`、`ASSERT`、`EXPLAIN` を実行します。
+書き込み DML、DML `VALIDATE ONLY`、`IMPORT`、`APPLY` は対象外です。
+生成 AI が MCP で作った SQL を library で実行する場合は、この API 別の境界を確認してください。
 
 ## 機能概要
 

package/dist-cli/ksql.js

@@ -5341,20 +5341,36 @@ function caseResultHasAggregate(result) {
   if (result.type === "ARRAY" || result.type === "FIELD_REF" || result.type === "ARITH") return false;
   return scalarValueHasAggregate(result);
 }
-function collectRequiredFieldsByTable(stmt, plainGroupByPlan) {
+function collectSelectFieldReferencesBySource(stmt, plainGroupByPlan) {
+  const unqualified = /* @__PURE__ */ new Set();
+  const states = collectRequiredFieldsByTable(stmt, plainGroupByPlan, {
+    includeMaterialized: true,
+    unqualified
+  });
+  return {
+    bySource: new Map(
+      [...states.entries()].map(([table, state]) => [table, new Set(state.fields)])
+    ),
+    unqualified
+  };
+}
+function collectRequiredFieldsByTable(stmt, plainGroupByPlan, sourceAware) {
   const allTables = [stmt.from, ...stmt.joins.map((j) => j.table)];
   const physicalTables = [stmt.from, ...stmt.joins.map((j) => j.table)].filter((t) => t.cteName === null);
+  const targetTables = sourceAware ? allTables : physicalTables;
   const states = /* @__PURE__ */ new Map();
-  for (const table of physicalTables) {
+  for (const table of targetTables) {
     states.set(table, { table, allFields: false, fields: /* @__PURE__ */ new Set() });
   }
   if (states.size === 0) return states;
-  const firstPhysicalTable = physicalTables[0] ?? null;
-  const subtableTable = physicalTables.find((t) => !!t.subtableCode) ?? null;
+  const firstTargetTable = targetTables[0] ?? null;
+  const subtableTable = targetTables.find((t) => !!t.subtableCode) ?? null;
   const aliasToTable = /* @__PURE__ */ new Map();
-  for (const table of physicalTables) {
+  for (const table of targetTables) {
     if (table.alias) aliasToTable.set(table.alias, table);
-    if (!table.subtableCode) {
+    if (table.cteName !== null) {
+      aliasToTable.set(table.cteName, table);
+    } else if (!table.subtableCode) {
       aliasToTable.set(`APP${table.appId}`, table);
       aliasToTable.set(`app${table.appId}`, table);
     }
@@ -5366,11 +5382,11 @@ function collectRequiredFieldsByTable(stmt, plainGroupByPlan) {
     st.allFields = true;
     st.fields.clear();
   };
-  const markAllPhysicalTables = () => {
-    for (const t of physicalTables) markAll(t);
+  const markAllTargetTables = () => {
+    for (const t of targetTables) markAll(t);
   };
   const markAllSubtableTables = () => {
-    for (const t of physicalTables) {
+    for (const t of targetTables) {
       if (t.subtableCode) markAll(t);
     }
   };
@@ -5400,7 +5416,7 @@ function collectRequiredFieldsByTable(stmt, plainGroupByPlan) {
     if (rawName.endsWith(".*")) {
       const qualifier = rawName.slice(0, -2);
       if (!qualifier) {
-        markAllPhysicalTables();
+        markAllTargetTables();
         return;
       }
       if (qualifier === "_p") {
@@ -5417,7 +5433,7 @@ function collectRequiredFieldsByTable(stmt, plainGroupByPlan) {
     if (phase === "groupBy" && groupResolution !== void 0) {
       if (groupResolution.kind === "PHYSICAL") {
         const source = allTables[groupResolution.sourceIndex];
-        if (source?.cteName === null) {
+        if (source && (sourceAware || source.cteName === null)) {
           addFieldToTable(source, groupResolution.fieldCode);
         }
       }
@@ -5442,8 +5458,13 @@ function collectRequiredFieldsByTable(stmt, plainGroupByPlan) {
         addFieldToTable(target, field);
         return;
       }
+      if (sourceAware) return;
+    }
+    if (sourceAware) {
+      sourceAware.unqualified.add(rawName);
+    } else if (firstTargetTable) {
+      addFieldToTable(firstTargetTable, rawName);
     }
-    if (firstPhysicalTable) addFieldToTable(firstPhysicalTable, rawName);
   };
   const addFieldRef = (field, tableAlias, phase = "select") => {
     if (tableAlias) {
@@ -5456,6 +5477,7 @@ function collectRequiredFieldsByTable(stmt, plainGroupByPlan) {
         addFieldToTable(target, field);
         return;
       }
+      if (sourceAware) return;
     }
     addFieldName(field, phase);
   };
@@ -5611,7 +5633,7 @@ function collectRequiredFieldsByTable(stmt, plainGroupByPlan) {
   for (const col of stmt.columns) {
     switch (col.type) {
       case "WILDCARD":
-        markAllPhysicalTables();
+        markAllTargetTables();
         break;
       case "PARENT_WILDCARD":
         markAllSubtableTables();
@@ -9490,6 +9512,20 @@ function renderValidationValue(value) {
 }
 
 // src/core/existingRecordValidation.ts
+var VALIDATE_CONSTRAINT_CATEGORIES = [
+  "required",
+  "length",
+  "range",
+  "choice"
+];
+function getAuditableConstraintCategories(field) {
+  return [
+    ...field.required === true ? ["required"] : [],
+    ...field.minLength !== void 0 || field.maxLength !== void 0 ? ["length"] : [],
+    ...field.minValue !== void 0 || field.maxValue !== void 0 ? ["range"] : [],
+    ...field.optionOrder !== void 0 ? ["choice"] : []
+  ];
+}
 function buildValidationFieldMetadataIndex(fieldInfos) {
   const topLevel = fieldInfos.filter((field) => !field.inSubtable);
   const childrenByTable = /* @__PURE__ */ new Map();
@@ -9506,7 +9542,7 @@ function buildValidationFieldMetadataIndex(fieldInfos) {
   };
 }
 function hasAuditableConstraint(field) {
-  return field.required === true || field.minValue !== void 0 || field.maxValue !== void 0 || field.minLength !== void 0 || field.maxLength !== void 0 || field.optionOrder !== void 0;
+  return getAuditableConstraintCategories(field).length > 0;
 }
 function isExistingValidationAuditable(field) {
   return field.fieldType === "NUMBER" || hasAuditableConstraint(field);
@@ -15629,6 +15665,13 @@ async function executeExistingRecordValidationCore(stmt, client, options, cacheC
   const infoByCode = new Map(fieldInfos.filter((field) => !field.inSubtable).map((field) => [field.code, field]));
   const childCodes = new Set(fieldInfos.filter((field) => field.inSubtable).map((field) => field.code));
   const targets = resolveExistingValidationTargets(stmt, fieldInfos);
+  const presentConstraintCategories = new Set(
+    targets.flatMap((target) => getAuditableConstraintCategories(target.field))
+  );
+  const constraintMetadata = {
+    present: VALIDATE_CONSTRAINT_CATEGORIES.filter((category) => presentConstraintCategories.has(category)),
+    absent: VALIDATE_CONSTRAINT_CATEGORIES.filter((category) => !presentConstraintCategories.has(category))
+  };
   const checkGroups = stmt.checkGroups ?? [];
   const checkRefs2 = collectCheckFieldRefs(checkGroups);
   for (const ref of checkRefs2) {
@@ -15785,7 +15828,11 @@ async function executeExistingRecordValidationCore(stmt, client, options, cacheC
     columns: [...columns],
     rows,
     rowCount: rows.length,
-    validateStats: { errorRecords: errorRecordIds.size, errorCount }
+    validateStats: {
+      errorRecords: errorRecordIds.size,
+      errorCount,
+      constraintMetadata
+    }
   };
   materializedMetaBySelectResult.set(result, existingValidationColumnMeta(stmt.summary === true));
   return result;
@@ -16158,21 +16205,28 @@ async function runWithDeadline(work, remainingMs, onTimeout) {
   }
 }
 function toBatchStatementError(e) {
+  let error;
   if (e instanceof ApplyWritePartialFailureError) {
-    return { code: e.name, message: e.message, partialSuccess: e.partialSuccess };
-  }
-  if (e instanceof Error) {
+    error = { code: e.name, message: e.message, partialSuccess: e.partialSuccess };
+  } else if (e instanceof Error) {
     const name = e.name !== "Error" ? e.name : null;
-    return { code: name ?? codeFromMessagePrefix(e.message), message: e.message };
-  }
-  if (e !== null && typeof e === "object") {
+    error = { code: name ?? codeFromMessagePrefix(e.message), message: e.message };
+  } else if (e !== null && typeof e === "object") {
     const obj = e;
-    const message2 = typeof obj.message === "string" && obj.message.length > 0 ? obj.message : safeJsonStringify(e);
-    const code = typeof obj.code === "string" && obj.code.length > 0 ? obj.code : codeFromMessagePrefix(message2);
-    return { code, message: message2 };
+    const message = typeof obj.message === "string" && obj.message.length > 0 ? obj.message : safeJsonStringify(e);
+    const code = typeof obj.code === "string" && obj.code.length > 0 ? obj.code : codeFromMessagePrefix(message);
+    error = { code, message };
+  } else {
+    const message = String(e);
+    error = { code: codeFromMessagePrefix(message), message };
   }
-  const message = String(e);
-  return { code: codeFromMessagePrefix(message), message };
+  Object.defineProperty(error, "cause", {
+    value: e,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return error;
 }
 function codeFromMessagePrefix(message) {
   return message.match(/^([A-Za-z]+Error):/)?.[1] ?? "Error";
@@ -17086,6 +17140,159 @@ async function validateSelectFieldCodes(stmt, mode, client, cacheContext) {
     }
   }
 }
+function b86SourceLabel(table) {
+  return table.cteName ?? `APP${table.appId}`;
+}
+function b86SourceAliases(table) {
+  if (table.alias) return [table.alias];
+  if (table.cteName !== null) return [table.cteName];
+  return [`APP${table.appId}`, `app${table.appId}`];
+}
+function b86PhysicalFieldExists(schema, field) {
+  return isSystemLikeFieldCode(field) || schema.validCodes.has(field);
+}
+function b86FieldExists(schema, field) {
+  if (schema.table.cteName !== null) return schema.validCodes.has(field);
+  return b86PhysicalFieldExists(schema, field);
+}
+function collectB86Subqueries(stmt) {
+  const queries = [];
+  const visitWhere = (where) => {
+    if (where === null) return;
+    switch (where.type) {
+      case "BINARY":
+        if (where.right.type === "SUBQUERY_IN_LIST" || where.right.type === "SCALAR_SUBQUERY") {
+          queries.push(where.right.query);
+        }
+        return;
+      case "EXISTS":
+        queries.push(where.query);
+        return;
+      case "LOGICAL":
+        visitWhere(where.left);
+        visitWhere(where.right);
+        return;
+      case "NOT":
+      case "GROUP":
+        visitWhere(where.expr);
+        return;
+      case "NULL_CHECK":
+      case "BOOLEAN":
+        return;
+    }
+  };
+  visitWhere(stmt.where);
+  visitWhere(stmt.having);
+  for (const column of stmt.columns) {
+    if (column.type === "SCALAR_SUBQUERY_COL") {
+      queries.push(column.query);
+    } else if (column.type === "CASE_COL") {
+      for (const branch of column.expr.branches) visitWhere(branch.condition);
+    }
+  }
+  return queries;
+}
+async function validateB86SelectFieldCodes(stmt, client, cteCache, cacheContext) {
+  const tables = [stmt.from, ...stmt.joins.map((join2) => join2.table)];
+  const materializedByTable = /* @__PURE__ */ new Map();
+  const effectiveAliases = /* @__PURE__ */ new Set();
+  for (const table of tables) {
+    const alias = effectiveTableAlias(table);
+    if (alias === null) continue;
+    if (effectiveAliases.has(alias)) {
+      throw new Error(`ArgumentError: effective alias ${alias} is used by multiple tables.`);
+    }
+    effectiveAliases.add(alias);
+  }
+  for (const table of tables) {
+    if (table.cteName === null || table.cteName === NO_FROM_CTE_NAME) continue;
+    const materialized = cteCache.get(table.cteName);
+    if (!materialized) {
+      throw new Error(`ArgumentError: materialized source ${table.cteName} is not available.`);
+    }
+    if (materialized.rows.length > 0 && materialized.columns.length === 0) {
+      throw new Error(
+        `InternalError: materialized source ${table.cteName} has rows but no column schema.`
+      );
+    }
+    if (stmt.joins.length > 0 && materialized.rows.length === 0 && materialized.columns.length === 0) {
+      throw new Error(
+        `ArgumentError: column schema is unavailable for materialized JOIN source ${table.cteName}.`
+      );
+    }
+    materializedByTable.set(table, materialized);
+  }
+  const schemas = /* @__PURE__ */ new Map();
+  await Promise.all(tables.map(async (table) => {
+    const materialized = materializedByTable.get(table);
+    if (materialized) {
+      schemas.set(table, {
+        table,
+        label: b86SourceLabel(table),
+        validCodes: new Set(materialized.columns),
+        authoritative: true,
+        schemaUnavailable: materialized.rows.length === 0 && materialized.columns.length === 0
+      });
+      return;
+    }
+    if (table.cteName === NO_FROM_CTE_NAME) return;
+    const defs = await getFieldsCached(table.appId, client, cacheContext);
+    schemas.set(table, {
+      table,
+      label: b86SourceLabel(table),
+      validCodes: new Set(defs.map((def) => def.code)),
+      authoritative: defs.length > 0,
+      schemaUnavailable: false
+    });
+  }));
+  const sourceByAlias = /* @__PURE__ */ new Map();
+  for (const schema of schemas.values()) {
+    for (const alias of b86SourceAliases(schema.table)) sourceByAlias.set(alias, schema);
+  }
+  for (const join2 of stmt.joins) {
+    for (const ref of [join2.on.left, join2.on.right]) {
+      if (!ref.tableAlias) continue;
+      const schema = sourceByAlias.get(ref.tableAlias);
+      if (schema && schema.table.cteName !== null && !schema.schemaUnavailable && !b86FieldExists(schema, ref.field)) {
+        throw new Error(
+          `ArgumentError: JOIN key ${ref.tableAlias}.${ref.field} is not available in the materialized table.`
+        );
+      }
+    }
+  }
+  const references = collectSelectFieldReferencesBySource(stmt);
+  for (const [table, fields] of references.bySource) {
+    const schema = schemas.get(table);
+    if (!schema || schema.schemaUnavailable || !schema.authoritative) continue;
+    const unknown = [...fields].filter((field) => !b86FieldExists(schema, field));
+    if (unknown.length > 0) {
+      throw new Error(
+        `ArgumentError: unknown field code(s): ${unknown.join(", ")} (${schema.label})`
+      );
+    }
+  }
+  for (const field of references.unqualified) {
+    const candidates = [...schemas.values()].filter((schema) => !schema.schemaUnavailable);
+    if (candidates.some((schema) => b86FieldExists(schema, field))) continue;
+    if ([...schemas.values()].some((schema) => schema.schemaUnavailable)) continue;
+    if (candidates.some((schema) => schema.table.cteName === null && !schema.authoritative)) continue;
+    const labels = candidates.map((schema) => schema.label).join(", ");
+    throw new Error(`ArgumentError: unknown field code(s): ${field} (${labels})`);
+  }
+}
+async function preflightB86QueryWithCte(query, client, cteCache, cacheContext, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(query)) return;
+  seen.add(query);
+  if (query.type === "UNION") {
+    await preflightB86QueryWithCte(query.left, client, cteCache, cacheContext, seen);
+    await preflightB86QueryWithCte(query.right, client, cteCache, cacheContext, seen);
+    return;
+  }
+  await validateB86SelectFieldCodes(query, client, cteCache, cacheContext);
+  for (const subquery of collectB86Subqueries(query)) {
+    await preflightB86QueryWithCte(subquery, client, cteCache, cacheContext, seen);
+  }
+}
 function extractMainTypedPushdownCandidate(stmt) {
   if (stmt.where === null || stmt.from.subtableCode || stmt.from.cteName !== null) return null;
   if (stmt.joins.length === 0) {
@@ -17947,11 +18154,14 @@ async function executeWith(stmt, client, options, cacheContext, seed, captureCol
   }
   return executeQueryWithCte(stmt.query, client, options, cteCache, cacheContext, captureColumnMeta);
 }
-async function executeQueryWithCte(query, client, options, cteCache, cacheContext, captureColumnMeta = false) {
+async function executeQueryWithCte(query, client, options, cteCache, cacheContext, captureColumnMeta = false, b86PreflightComplete = false) {
+  if (!b86PreflightComplete) {
+    await preflightB86QueryWithCte(query, client, cteCache, cacheContext);
+  }
   if (query.type === "UNION") {
     const [leftResult, rightResult] = await Promise.all([
-      executeQueryWithCte(query.left, client, options, cteCache, cacheContext, captureColumnMeta),
-      executeQueryWithCte(query.right, client, options, cteCache, cacheContext, captureColumnMeta)
+      executeQueryWithCte(query.left, client, options, cteCache, cacheContext, captureColumnMeta, true),
+      executeQueryWithCte(query.right, client, options, cteCache, cacheContext, captureColumnMeta, true)
     ]);
     const leftCols = leftResult.columns;
     const rightCols = rightResult.columns;

package/dist-engine/batch.d.ts

@@ -0,0 +1,13 @@
+import type { BatchResult, RunBatchOptions } from "./publicTypes";
+/**
+ * Executes a read-only multi-statement batch.
+ *
+ * In addition to the row-returning statements accepted by runQuery, this API
+ * accepts CREATE/DROP TEMP TABLE, SET, DECLARE, ASSERT, and EXPLAIN. IMPORT,
+ * APPLY, DML VALIDATE ONLY, and writing DML remain outside the library boundary.
+ *
+ * If any statement fails, this function throws KsqlEngineError without
+ * returning partial results. statementIndex and statementType identify the
+ * failed statement.
+ */
+export declare function runBatch(sql: string, options: RunBatchOptions): Promise<BatchResult>;

package/dist-engine/errors.d.ts

@@ -1,8 +1,13 @@
 export declare class KsqlEngineError extends Error {
     readonly code: "PARSE_ERROR" | "READ_ONLY_VIOLATION" | "SEARCH_ABORTED" | "FETCH_LIMIT_EXCEEDED" | "CLIENT_ERROR" | "EXECUTION_ERROR";
     readonly cause?: unknown;
+    /** Zero-based index of the failed statement when raised by runBatch. */
+    readonly statementIndex?: number;
+    /** Parser statement type of the failed statement when raised by runBatch. */
+    readonly statementType?: string;
     constructor(code: KsqlEngineError["code"], message: string, cause?: unknown);
 }
+export declare function withStatementDiagnostic(error: KsqlEngineError, statementIndex: number, statementType: string): KsqlEngineError;
 export declare function readOnlyViolation(message: string): KsqlEngineError;
 export declare function parseError(message: string, cause?: unknown): KsqlEngineError;
 export declare function searchAborted(): KsqlEngineError;