@cartanova/qgrid-cli 2.5.4 → 2.5.5

package/bundle/src/utils/providers/common/json-schema-keywords.ts

@@ -0,0 +1,72 @@
+/**
+ * JSON Schema 하위 스키마 위치 목록 — qgrid 의 스키마 순회 3곳이 공유하는 단일 정본.
+ *
+ *  - `tool-emulation-schema.rewriteSchemaNode`: 사용자 스키마의 local `$ref` 를 namespace 로 rebase
+ *  - `strictifier.assertNormalizationCompatibility`: provider 표현 가능성 검사
+ *  - `strictifier.strictifyNode`: strict 재작성
+ *
+ * 세 소비자가 각자 테이블을 들고 있으면 새 keyword 를 한쪽에만 추가하는 순간 조용히 어긋난다.
+ * 재작성 패스가 훑지 않는 위치의 `$ref` 는 rebase 되지 않은 채 남고, 검사 패스가 놓친 위치의
+ * tuple 은 정규화 없이 provider 로 샌다. 실제로 통합 전 `additionalItems` 가 그 상태였다.
+ * 위치 목록은 여기서만 관리한다.
+ *
+ * 왜 이런 순회가 필요한지는 스킬 문서 참고:
+ *   packages/cli/skills/qgrid/references/tool-calling-and-multiturn.md
+ *
+ * 소비자별로 다른 것은 위치 목록이 아니라 **각 위치를 어떻게 다루는가** 이므로(strictifier 의
+ * `normalizable` 플래그 등) 그 판단은 각 소비자가 이 목록 위에 얹는다.
+ */
+
+/** 이름 → 하위 스키마 맵. 예: `properties`, `$defs`. */
+export const SCHEMA_MAP_KEYWORDS = [
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties",
+] as const;
+
+/** 하위 스키마 배열. 예: `anyOf`, `prefixItems`. */
+export const SCHEMA_ARRAY_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
+
+/**
+ * 하위 스키마 하나를 직접 갖는 위치. `items` 와 `additionalItems` 는 Draft-7 tuple 형식에서
+ * 배열이 올 수 있으므로 소비자가 배열 분기를 따로 처리한다.
+ */
+export const SCHEMA_SINGLE_KEYWORDS = [
+  "additionalItems",
+  "additionalProperties",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+] as const;
+
+/**
+ * Draft-7 `dependencies` 는 값이 스키마이거나 property 이름 배열이라 위 분류에 들어가지 않는다.
+ * 배열 형태는 스키마가 아니므로 순회 대상이 아니다.
+ */
+export const SCHEMA_DEPENDENCIES_KEYWORD = "dependencies";
+
+/**
+ * qgrid 가 거부하는 참조/식별 keyword.
+ *
+ * 사용자 스키마는 envelope 의 `$defs` 아래로 옮겨지고 정의는 전역적으로 정규화되므로, base URI 를
+ * 새로 선언하거나(`$id`) 런타임 스코프로 대상이 정해지는 참조(`$dynamicRef` 등)는 옮긴 뒤의 의미를
+ * 보장할 수 없다. 조용히 잘못 rebase 하는 대신 명시적으로 거부한다.
+ */
+export const UNSUPPORTED_REFERENCE_KEYWORDS = [
+  "$id",
+  "id",
+  "$anchor",
+  "$dynamicAnchor",
+  "$recursiveAnchor",
+  "$dynamicRef",
+  "$recursiveRef",
+] as const;

package/bundle/src/utils/providers/common/strictifier.ts

@@ -8,6 +8,13 @@
  *  - recursive 처리 (nested objects, arrays, allOf/anyOf/oneOf)
  */
 
+import {
+  SCHEMA_ARRAY_KEYWORDS,
+  SCHEMA_MAP_KEYWORDS,
+  SCHEMA_SINGLE_KEYWORDS,
+  UNSUPPORTED_REFERENCE_KEYWORDS,
+} from "./json-schema-keywords";
+
 export type JsonSchema = Record<string, unknown>;
 
 export interface StrictifierOptions {
@@ -35,31 +42,38 @@ export function strictify(schema: JsonSchema, options: StrictifierOptions = {}):
   return result;
 }
 
-const SCHEMA_SCAN_MAP_KEYWORDS = [
-  ["$defs", true],
-  ["definitions", true],
-  ["properties", true],
-  ["dependentSchemas", false],
-  ["patternProperties", false],
-] as const;
-const SCHEMA_SCAN_ARRAY_KEYWORDS = [
-  ["allOf", true],
-  ["anyOf", true],
-  ["oneOf", true],
-  ["prefixItems", true],
-] as const;
-const SCHEMA_SCAN_SINGLE_KEYWORDS = [
-  ["additionalProperties", false],
-  ["contains", false],
-  ["contentSchema", false],
-  ["else", false],
-  ["if", false],
-  ["not", false],
-  ["propertyNames", false],
-  ["then", false],
-  ["unevaluatedItems", false],
-  ["unevaluatedProperties", false],
-] as const;
+/**
+ * 위치 목록은 json-schema-keywords 가 소유하고, 여기서는 각 위치의 `normalizable` 여부만 얹는다.
+ * normalizable=true 는 strictifyNode 가 그 위치를 실제로 재작성한다는 뜻이다. `not`/`if` 처럼
+ * 재작성하면 caller 의미가 바뀌는 위치는 false 이고, 그 아래 tuple/`$ref` 는 정규화 대신 거부된다.
+ *
+ * `items`/`additionalItems` 는 tuple 판정과 함께 다뤄야 해서 아래 순회에서 개별 처리한다.
+ */
+const NON_NORMALIZABLE_POSITIONS = new Set<string>([
+  "dependentSchemas",
+  "patternProperties",
+  "additionalProperties",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "not",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+]);
+
+function positionEntries(keywords: readonly string[]): ReadonlyArray<readonly [string, boolean]> {
+  return keywords.map((keyword) => [keyword, !NON_NORMALIZABLE_POSITIONS.has(keyword)] as const);
+}
+
+const SCHEMA_SCAN_MAP_KEYWORDS = positionEntries(SCHEMA_MAP_KEYWORDS);
+const SCHEMA_SCAN_ARRAY_KEYWORDS = positionEntries(SCHEMA_ARRAY_KEYWORDS);
+// items/additionalItems 는 tuple 분기에서 직접 다루므로 단일 위치 스캔에서 제외한다.
+const SCHEMA_SCAN_SINGLE_KEYWORDS = positionEntries(
+  SCHEMA_SINGLE_KEYWORDS.filter((keyword) => keyword !== "items" && keyword !== "additionalItems"),
+);
 
 /**
  * Inspect every JSON Schema-bearing position without rewriting it.
@@ -191,16 +205,6 @@ function assertNormalizationCompatibility(
   assertReferenceTargets(schema, references);
 }
 
-const UNSUPPORTED_REFERENCE_KEYWORDS = [
-  "$id",
-  "id",
-  "$anchor",
-  "$dynamicAnchor",
-  "$recursiveAnchor",
-  "$dynamicRef",
-  "$recursiveRef",
-] as const;
-
 function assertUnsupportedReferenceKeywords(schema: JsonSchema, path: string): void {
   for (const keyword of UNSUPPORTED_REFERENCE_KEYWORDS) {
     if (Object.hasOwn(schema, keyword)) {
@@ -340,12 +344,14 @@ function strictifyNode(node: JsonSchema, path: string, provider?: string): JsonS
   return strictifySchemaArrays(result, path, provider);
 }
 
-const SCHEMA_MAP_KEYWORDS = ["$defs", "definitions"] as const;
+// 재작성 패스는 정의 맵만 재귀한다. properties 는 strictifyObject 가 별도로 처리하므로
+// 공유 위치 목록(SCHEMA_MAP_KEYWORDS)과 의도적으로 범위가 다르다.
+const DEFINITION_MAP_KEYWORDS = ["$defs", "definitions"] as const;
 
 function strictifySchemaMaps(node: JsonSchema, path: string, provider?: string): JsonSchema {
   const result = { ...node };
 
-  for (const keyword of SCHEMA_MAP_KEYWORDS) {
+  for (const keyword of DEFINITION_MAP_KEYWORDS) {
     const schemas = ownValue(node, keyword);
     if (!isSchemaObject(schemas)) continue;
 
@@ -362,12 +368,13 @@ function strictifySchemaMaps(node: JsonSchema, path: string, provider?: string):
   return result;
 }
 
-const SCHEMA_ARRAY_KEYWORDS = ["anyOf", "oneOf", "allOf"] as const;
+// prefixItems 는 strictifyArray 의 tuple 경로가 다루므로 여기서는 조합 keyword 만 재귀한다.
+const COMBINATOR_KEYWORDS = ["anyOf", "oneOf", "allOf"] as const;
 
 function strictifySchemaArrays(node: JsonSchema, path: string, provider?: string): JsonSchema {
   const result = { ...node };
 
-  for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
+  for (const keyword of COMBINATOR_KEYWORDS) {
     const schemas = ownValue(node, keyword);
     if (!schemas) continue;
     result[keyword] = (schemas as JsonSchema[]).map((schema, index) =>