@rex0220/kintone-sql-tools 3.73.0 → 3.75.0

package/README.md

@@ -267,7 +267,7 @@ npm パッケージは 2 つのサブパスを **semver 対象の公開 API**
 | サブパス | 用途 | 主な export |
 |---|---|---|
 | `@rex0220/kintone-sql-tools/engine` | **read-only** のクエリ実行（ダッシュボード等）。書込 API は構造的に遮断 | `runQuery` / `runBatch` / `explainQuery` / `createReadonlyKintoneClient` / `KsqlEngineError` / `version` |
-| `@rex0220/kintone-sql-tools/flow` | **Flow dialect 1**（→ [言語リファレンス §27](docs/ksql_language_reference.md)）のスクリプト解析・検証・**文単位実行**（バッチランナー向け・書込可能） | `parseScript` / `validateScript` / `explainScript`（`asOf`/`timezone` 注入可） / `createExecutionContext`（`onChunkWritten` 書込チャンク通知） / `executeStatement` / `previewStatement`（dry-run 差分プレビュー・書込 0 回） / `disposeExecutionContext` / `createKintoneClient` / `isDmlResult`（`FlowDmlResult` 型ガード） / `version` |
+| `@rex0220/kintone-sql-tools/flow` | **Flow dialect 1**（→ [言語リファレンス §27](docs/ksql_language_reference.md)）のスクリプト解析・検証・**文単位実行**（バッチランナー向け・書込可能） | `parseScript` / `validateScript` / `explainScript`（`asOf`/`timezone` 注入可） / `createExecutionContext`（`onChunkWritten` 書込チャンク通知） / `executeStatement` / `previewStatement`（dry-run 差分プレビュー・書込 0 回） / `disposeExecutionContext` / `createImportSourceResolver` / `FlowImportProviderError` / `createKintoneClient` / `isDmlResult`（`FlowDmlResult` 型ガード） / `version` |
 
 バッチ実行ランナー **kSQL Flow**（`/flow` API を使った公式ランナー・別リポジトリ）: https://github.com/rex0220/ksql-flow
 
@@ -289,6 +289,34 @@ try {
 }
 ```
 
+`/flow` から named `IMPORT` source を使う場合は、全APIへ `enableImport: true` を明示し、
+pathではなくlazy loaderが返す `Uint8Array` を登録します。省略または `false` は従来どおり
+`KSQL1202` で拒否し、resolverを渡すだけでは有効になりません。
+
+```ts
+import {
+  createImportSourceResolver,
+  parseScript,
+  createExecutionContext,
+} from "@rex0220/kintone-sql-tools/flow";
+
+const capability = { enableImport: true } as const;
+const importSource = createImportSourceResolver([{
+  name: "orders",
+  loader: { async load() { return { bytes, encoding: "sjis" }; } },
+}]);
+const parsed = parseScript(sql, capability);
+const ctx = createExecutionContext({
+  ...capability, client, statements: parsed.statements, meta: parsed.meta, importSource,
+});
+```
+
+source名は完全一致・case-sensitiveです。loaderは対象文の実行到達時だけ呼ばれます。
+CSVの文字コードは `SQL ENCODING` > loader metadata > UTF-8、payload上限は10 MiBです。
+path解決、通常ファイル・symlink・allowlist・hash検査、open/readは呼出側の責務であり、
+engineはpathを受け取りません。providerは `FlowImportProviderError` でread不能または通常ファイル外を
+分類でき、その他のsource境界エラーも `StatementResult.error.code` の安定codeで返ります。
+
 読取上限は既定 10,000 件（`maxRecords`）です。一時テーブルの実体化には**独立の** `tempTableMaxRows`（既定 10,000 行・超過は常にエラー）が適用されるため、大きなバッチでは両方を併せて指定してください:
 
 ```ts

package/dist-cli/ksql.js

@@ -17606,19 +17606,86 @@ var ImportSourceError = class extends Error {
     this.name = "ImportSourceError";
   }
 };
+var ImportSourceBoundaryError = class extends Error {
+  constructor(code, message, cause) {
+    super(`${code}: ${message}`);
+    this.name = code;
+    this.code = code;
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        enumerable: false,
+        configurable: false,
+        writable: false
+      });
+    }
+  }
+};
+function providerError(error) {
+  if (error === null || typeof error !== "object") return void 0;
+  const shaped = error;
+  const code = shaped.code === "ImportSourceReadError" || shaped.code === "ImportSourceNotRegularFileError" ? shaped.code : shaped.name === "ImportSourceReadError" || shaped.name === "ImportSourceNotRegularFileError" ? shaped.name : void 0;
+  if (!code) return void 0;
+  const fallback = code === "ImportSourceReadError" ? "IMPORT source could not be read." : "IMPORT source is not a regular file.";
+  return new ImportSourceBoundaryError(
+    code,
+    typeof shaped.message === "string" && shaped.message.length > 0 ? shaped.message : fallback,
+    error
+  );
+}
+function isUint8Array(value) {
+  return value !== null && typeof value === "object" && ArrayBuffer.isView(value) && Object.prototype.toString.call(value) === "[object Uint8Array]";
+}
 function resolveImportSource(name, resolver) {
-  if (!resolver) throw new ImportSourceError("IMPORT source capability is not available.");
-  const handle = resolver(name);
-  if (!handle) throw new ImportSourceError(`source "${name}" is not supplied.`);
-  return handle;
+  if (!resolver) {
+    throw new ImportSourceBoundaryError(
+      "ImportSourceNotSuppliedError",
+      `the named IMPORT source ${JSON.stringify(name)} was not supplied.`
+    );
+  }
+  try {
+    const handle = resolver(name);
+    if (!handle) {
+      throw new ImportSourceBoundaryError(
+        "ImportSourceNotSuppliedError",
+        `the named IMPORT source ${JSON.stringify(name)} was not supplied.`
+      );
+    }
+    if (typeof handle !== "object" || typeof handle.load !== "function") {
+      throw new ImportSourceBoundaryError(
+        "ImportSourceInvalidPayloadError",
+        "resolver must return a handle with a load function."
+      );
+    }
+    return handle;
+  } catch (error) {
+    if (error instanceof ImportSourceBoundaryError) throw error;
+    throw providerError(error) ?? new ImportSourceBoundaryError("ImportSourceReadError", "IMPORT source resolution failed.", error);
+  }
 }
 async function loadImportSource(handle, cache) {
   let pending = cache.get(handle);
   if (!pending) {
-    pending = handle.load().then((payload) => {
-      if (!(payload.bytes instanceof Uint8Array)) throw new ImportSourceError("loader must return Uint8Array bytes.");
+    pending = Promise.resolve().then(() => handle.load()).catch((error) => {
+      throw providerError(error) ?? new ImportSourceBoundaryError("ImportSourceReadError", "IMPORT source could not be read.", error);
+    }).then((payload) => {
+      if (payload === null || typeof payload !== "object" || !isUint8Array(payload.bytes)) {
+        throw new ImportSourceBoundaryError(
+          "ImportSourceInvalidPayloadError",
+          "loader must return Uint8Array bytes."
+        );
+      }
+      if (payload.encoding !== void 0 && payload.encoding !== "utf8" && payload.encoding !== "sjis") {
+        throw new ImportSourceBoundaryError(
+          "ImportSourceInvalidPayloadError",
+          "loader returned an unsupported encoding."
+        );
+      }
       if (payload.bytes.byteLength > IMPORT_MAX_BYTES) {
-        throw new ImportSourceError(`source exceeds the ${IMPORT_MAX_BYTES} byte limit.`);
+        throw new ImportSourceBoundaryError(
+          "ImportSourceTooLargeError",
+          `source exceeds the ${IMPORT_MAX_BYTES} byte limit.`
+        );
       }
       return payload;
     });
@@ -18837,6 +18904,7 @@ async function executeParsedStatement(stmt, client, options, cacheContext) {
         options.recursiveCteMaxDepth,
         options.recursiveCteMaxRows,
         options.recursiveCteMaxExpansions,
+        options.resolveMetadata !== false,
         hasNativeUpsertExecutionOption(options) ? {
           surface: "CLI",
           enableNativeUpsert: nativeUpsertExecutionEnabled(options),
@@ -26784,6 +26852,10 @@ async function buildExplainWhereAnalysis(query, client, cacheContext, maxRecords
       return;
     }
     const typed = node;
+    if (typed["type"] === "UPSERT" || typed["type"] === "UPSERT_SELECT") {
+      const upsert = node;
+      await getFieldsCached(upsert.appId, tracedClient, cacheContext);
+    }
     if (typed["type"] === "SELECT") {
       const select = node;
       await validateSelectGroupingPlanning(select, tracedClient, cacheContext);
@@ -27827,21 +27899,29 @@ var explainMaterializedTables = /* @__PURE__ */ new WeakMap();
 function defaultRecursiveExplainContext() {
   return { maxRecords: 1e4, recursiveLimits: resolveRecursiveCteLimits({}) };
 }
-async function executeExplain(stmt, client, cacheContext, maxRecords, cursorMaxActive, dmlMaxRows = 100, dmlMaxSubtableRows = DEFAULT_APPLY_MAX_SUBTABLE_ROWS, relativeDatePlan, recursiveCteMaxDepth, recursiveCteMaxRows, recursiveCteMaxExpansions, nativeUpsertOptions = { surface: "DOCUMENT_ONLY" }) {
+async function executeExplain(stmt, client, cacheContext, maxRecords, cursorMaxActive, dmlMaxRows = 100, dmlMaxSubtableRows = DEFAULT_APPLY_MAX_SUBTABLE_ROWS, relativeDatePlan, recursiveCteMaxDepth, recursiveCteMaxRows, recursiveCteMaxExpansions, resolveMetadata = true, nativeUpsertOptions = { surface: "DOCUMENT_ONLY" }) {
   const recursiveLimits = resolveRecursiveCteLimits({
     recursiveCteMaxDepth,
     recursiveCteMaxRows,
     recursiveCteMaxExpansions
   });
   const sharedPlan = relativeDatePlan ?? await resolveRelativeDateExecutionPlan(stmt.query, client, cacheContext);
-  const analysis = await buildExplainWhereAnalysis(
+  const analysis = resolveMetadata ? await buildExplainWhereAnalysis(
     stmt.query,
     client,
     cacheContext,
     maxRecords,
     sharedPlan,
     explainMaterializedTables.get(stmt)
-  );
+  ) : {
+    capabilities: /* @__PURE__ */ new Map(),
+    orderPlans: /* @__PURE__ */ new Map(),
+    plainGroupByPlans: /* @__PURE__ */ new Map(),
+    fieldApps: /* @__PURE__ */ new Set(),
+    processStatusApps: /* @__PURE__ */ new Set(),
+    numberPrecisionApps: /* @__PURE__ */ new Set(),
+    relativeDatePlan: sharedPlan
+  };
   const fetchCollector = { sources: [] };
   const relativeLines = relativeDateExplainLines(sharedPlan);
   const planLines = sharedPlan.hasServerOnlyWhereFunction && !sharedPlan.allowed ? [...explainMetadataLines(analysis), ...relativeLines] : [
@@ -29159,6 +29239,23 @@ function isSubtableRow(v) {
   return typeof obj.id === "string" && typeof obj.value === "object" && obj.value !== null;
 }
 
+// src/flow-library/importSources.ts
+var FlowImportProviderError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.name = code;
+    this.code = code;
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        enumerable: false,
+        configurable: false,
+        writable: false
+      });
+    }
+  }
+};
+
 // src/output/batchEnvelope.ts
 function toMutationSummary(result) {
   if (result.type === "INSERT") {
@@ -32626,7 +32723,8 @@ async function run() {
     appProfileByApp.set(appId, appBindingByMappedApp.get(appId)?.profile ?? profileName.toLowerCase());
   }
   const cacheContext = buildCacheContext(profileName, appBindingByMappedApp);
-  if (args.dryRun && (!dryRunNeedsMetadata || dryRunUsesStaticTypedPlan)) {
+  const fullyOfflineDryRun = args.dryRun && (!dryRunNeedsMetadata || dryRunUsesStaticTypedPlan);
+  if (fullyOfflineDryRun) {
     client = createDryRunClient();
   } else {
     for (const explicitProfile of appProfileByApp.values()) {
@@ -32894,7 +32992,7 @@ async function run() {
         Object.keys(args.importCsv).length > 0 || Object.keys(args.importJson).length > 0,
         dmlMaxRows,
         dmlMaxSubtableRows,
-        !dryRunUsesStaticTypedPlan,
+        !fullyOfflineDryRun,
         recursiveCteMaxDepth,
         recursiveCteMaxRows,
         recursiveCteMaxExpansions,
@@ -32946,7 +33044,38 @@ async function run() {
     const importEnabled = Object.keys(args.importCsv).length > 0 || Object.keys(args.importJson).length > 0;
     const importSource = importEnabled ? (name) => {
       const sourcePath = args.importCsv[name] ?? args.importJson[name];
-      return sourcePath === void 0 ? void 0 : { load: async () => ({ bytes: new Uint8Array((0, import_fs2.readFileSync)(sourcePath)) }) };
+      if (sourcePath === void 0) return void 0;
+      return {
+        load: async () => {
+          let sourceStat;
+          try {
+            sourceStat = (0, import_fs2.statSync)(sourcePath);
+          } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new FlowImportProviderError(
+              "ImportSourceReadError",
+              `failed to inspect IMPORT source "${sourcePath}": ${reason}`,
+              error
+            );
+          }
+          if (!sourceStat.isFile()) {
+            throw new FlowImportProviderError(
+              "ImportSourceNotRegularFileError",
+              `IMPORT source "${sourcePath}" is not a regular file.`
+            );
+          }
+          try {
+            return { bytes: new Uint8Array((0, import_fs2.readFileSync)(sourcePath)) };
+          } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new FlowImportProviderError(
+              "ImportSourceReadError",
+              `failed to read IMPORT source "${sourcePath}": ${reason}`,
+              error
+            );
+          }
+        }
+      };
     } : void 0;
     const confirm = async (count, operation, context) => {
       if (count > dmlMaxRows) {
@@ -33051,7 +33180,8 @@ query=${label}`);
       dmlMaxSubtableRows,
       recursiveCteMaxDepth,
       recursiveCteMaxRows,
-      recursiveCteMaxExpansions
+      recursiveCteMaxExpansions,
+      resolveMetadata: !fullyOfflineDryRun
     }, args.nativeUpsert, true)) : await execute(sql, client, withNativeUpsertExecutionOption({
       maxRecords,
       fetchParallel,