@flextudio/scenario 0.1.0

package/node_modules/@flextudio/contract-core/schemas.mjs

@@ -0,0 +1,474 @@
+// schema/v1 의 모든 *.schema.json 을 Ajv2020 에 등록하고
+// validate.mjs 와 동일한 ref 해석 규칙(file key | $id | shorthand | 부분일치)을 제공.
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+
+import { SCHEMA_ROOT } from './paths.mjs';
+
+function collectSchemaFiles(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) out.push(...collectSchemaFiles(full));
+    else if (entry.endsWith('.schema.json')) out.push(full);
+  }
+  return out;
+}
+
+export function buildAjv() {
+  const ajv = new Ajv2020.default({ allErrors: true, strict: false });
+  const ajvStrict = new Ajv2020.default({ allErrors: true, strict: false });
+  const schemaIndex = []; // [{ key, id, basename }]
+  const schemaCache = new Map(); // key -> raw JSON
+
+  // ─── Register phase ─────────────────────────────────────────────────────
+  const registerStart = Date.now();
+  for (const file of collectSchemaFiles(SCHEMA_ROOT)) {
+    const key = relative(SCHEMA_ROOT, file).split('\\').join('/');
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    ajv.addSchema(data, key);
+    schemaCache.set(key, data);
+    schemaIndex.push({
+      key,
+      id: data.$id || null,
+      basename: key.replace(/^.*\//, '').replace(/\.schema\.json$/, ''),
+    });
+
+    // 동일 schema 의 strict 변종 — additionalProperties:true 를 모두 false 로 뒤집어
+    // "스키마에 정의되지 않은 필드" 자체를 차단. 별도 Ajv 인스턴스라 $id 중복 무관.
+    ajvStrict.addSchema(stripAdditionalTrue(data), key);
+  }
+  const registerMs = Date.now() - registerStart;
+  console.error(
+    `[contract-core] schemas registered (${schemaIndex.length}) in ${registerMs}ms`,
+  );
+
+  // ─── Eager compile phase ───────────────────────────────────────────────
+  // AJV 의 lazy compile (getSchema 첫 호출 시 $ref 체인 따라 컴파일) 은 큰 스키마
+  // 트리에서 첫 validate 호출 latency 를 분 단위로 만든다. 부팅 시에 모두 컴파일
+  // 해서 첫 호출 latency 를 startup 으로 이동 (한 번 비용).
+  const compileStart = Date.now();
+  let compiledOk = 0;
+  const compileFailures = [];
+  for (const { key } of schemaIndex) {
+    try {
+      // AJV.getSchema 가 처음 호출되면 내부적으로 컴파일 실행 (idempotent).
+      ajv.getSchema(key);
+    } catch (e) {
+      compileFailures.push({ key, variant: 'ajv', error: e?.message ?? String(e) });
+      continue;
+    }
+    try {
+      ajvStrict.getSchema(key);
+    } catch (e) {
+      compileFailures.push({ key, variant: 'ajvStrict', error: e?.message ?? String(e) });
+      continue;
+    }
+    compiledOk += 1;
+  }
+  const compileMs = Date.now() - compileStart;
+  console.error(
+    `[contract-core] schemas eager-compiled (${compiledOk}/${schemaIndex.length}) in ${compileMs}ms`,
+  );
+  if (compileFailures.length > 0) {
+    console.error(
+      `[contract-core] WARN: ${compileFailures.length} schema(s) failed eager compile (lazy retry at request time):`,
+    );
+    for (const f of compileFailures.slice(0, 10)) {
+      console.error(`  - ${f.variant} ${f.key}: ${f.error}`);
+    }
+  }
+
+  return { ajv, ajvStrict, schemaIndex, schemaCache };
+}
+
+/**
+ * 스키마 객체를 깊은 복제하면서 `additionalProperties: true` 를
+ * `unevaluatedProperties: false` 로 뒤집되, **자유 형식 컨테이너는 건드리지 않는다**.
+ *
+ * 두 가지 `additionalProperties: true` 의도가 공존:
+ *  A) 정의된 키만 허용 + AI typo 차단용 (예: RadioBox 본체 — properties 많음).
+ *     → `unevaluatedProperties: false` 로 뒤집어 미정의 키 강제 차단.
+ *  B) 자유 형식 컨테이너 (예: ItemDesign / ItemBgStyle / Image — properties 없음).
+ *     → 뒤집으면 모든 inner field 가 거부되어 깨짐. 그대로 둔다.
+ *
+ * 판정 휴리스틱: 같은 노드 레벨에 다음 중 하나라도 있으면 Class A (뒤집기) —
+ *   - 비어있지 않은 `properties` (RadioBox 본체의 분기 properties 등)
+ *   - `patternProperties` (Panel.Category 의 키 검증 등)
+ *   - `allOf` / `oneOf` / `anyOf` (Control / Step / Scenario 의 분기 합성)
+ *   - `$ref` (다른 schema 위임)
+ *   - `if`/`then`/`else` (조건부 분기)
+ * 위 중 아무것도 없으면 순수 자유 객체 (Class B) — 그대로 둔다.
+ *
+ * `unevaluatedProperties: false` 는 allOf / oneOf / anyOf / $ref 로 평가된 속성도
+ * 알려진 것으로 간주 — 분기 합성 (Control / Step) 에서도 진짜 미정의 키만 거른다.
+ */
+function stripAdditionalTrue(node) {
+  if (node === null || typeof node !== 'object') return node;
+  if (Array.isArray(node)) return node.map(stripAdditionalTrue);
+
+  // Class A vs Class B 판정 — 같은 객체 레벨에서 schema 분기 구조가 있는지.
+  const hasNonEmptyProperties =
+    node.properties &&
+    typeof node.properties === 'object' &&
+    Object.keys(node.properties).length > 0;
+  const hasPatternProperties =
+    node.patternProperties &&
+    typeof node.patternProperties === 'object' &&
+    Object.keys(node.patternProperties).length > 0;
+  const hasCombinator =
+    Array.isArray(node.allOf) ||
+    Array.isArray(node.oneOf) ||
+    Array.isArray(node.anyOf);
+  const hasRef = typeof node.$ref === 'string';
+  const hasConditional =
+    node.if !== undefined ||
+    node.then !== undefined ||
+    node.else !== undefined;
+  const shouldRewriteHere =
+    hasNonEmptyProperties ||
+    hasPatternProperties ||
+    hasCombinator ||
+    hasRef ||
+    hasConditional;
+
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (k === 'additionalProperties' && v === true) {
+      if (shouldRewriteHere) {
+        // Class A — 정의된 키만 허용. 분기 합성 통과 가능한 unevaluatedProperties:false.
+        out['unevaluatedProperties'] = false;
+      } else {
+        // Class B — 자유 형식 컨테이너. 그대로 통과.
+        out['additionalProperties'] = true;
+      }
+    } else {
+      out[k] = stripAdditionalTrue(v);
+    }
+  }
+  return out;
+}
+
+/**
+ * 모든 등록된 schema 의 properties 키들을 한 Set 으로 모은다.
+ * — denoise 단계에서 "스키마 어딘가에는 정의된 키" 와 "정말 LLM 이 만든 unknown 키" 를
+ * 구분하는 데 사용.
+ *
+ * 사용 컨텍스트: strict 변종 (unevaluatedProperties:false) 가 oneOf 분기 결정 실패 시
+ * 정상 키들도 "unevaluated" 로 보고하는 cascade 현상이 있다. 어떤 schema 의 properties
+ * 에라도 등재된 키라면 진짜 unknown 이 아니라 cascade 노이즈로 판단 — 그런 에러는 LLM
+ * 응답에서 걸러낸다.
+ */
+export function buildKnownProps(schemaCache) {
+  const known = new Set();
+  function walk(node) {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      for (const n of node) walk(n);
+      return;
+    }
+    if (node.properties && typeof node.properties === 'object') {
+      for (const k of Object.keys(node.properties)) known.add(k);
+      for (const v of Object.values(node.properties)) walk(v);
+    }
+    if (node.$defs && typeof node.$defs === 'object') {
+      for (const v of Object.values(node.$defs)) walk(v);
+    }
+    if (node.allOf) walk(node.allOf);
+    if (node.oneOf) walk(node.oneOf);
+    if (node.anyOf) walk(node.anyOf);
+    if (node.then) walk(node.then);
+    if (node.else) walk(node.else);
+    if (node.items) walk(node.items);
+    if (node.patternProperties && typeof node.patternProperties === 'object') {
+      for (const v of Object.values(node.patternProperties)) walk(v);
+    }
+    if (node.additionalProperties && typeof node.additionalProperties === 'object') {
+      walk(node.additionalProperties);
+    }
+  }
+  for (const schema of schemaCache.values()) walk(schema);
+  return known;
+}
+
+/**
+ * AJV strict 변종이 oneOf 분기 결정 실패 시 쏟아내는 cascade 노이즈를 정리한다.
+ * (구 mcp-server/src/tools.mjs 의 inline denoiseErrors 를 core 로 추출 — CLI/MCP 공용.)
+ *  - 같은 (path, keyword, property/missing/allowed) 튜플 중복 제거.
+ *  - unevaluatedProperties/additionalProperties 에러 중 property 이름이 어딘가
+ *    스키마에 등재된 것이면 cascade 노이즈로 간주해 제거 (knownProps). 단 누구도
+ *    정의하지 않은 'UseMargin' 같은 오타는 그대로 살아남는다.
+ *  - oneOf 실패 path 의 자식 path 에서 const allowedValue 차별자 노이즈 제거.
+ *  - oneOf 실패 path 자신의 required / if / not 노이즈 제거.
+ * 모든 필터 통과 후 errors 가 비면 원본을 그대로 돌려준다 (safety net).
+ *
+ * @param {Array} rawErrors        ajv validator.errors
+ * @param {Set<string>} knownProps buildKnownProps(schemaCache) 결과 (없으면 prop 필터 비활성)
+ */
+export function denoiseErrors(rawErrors, knownProps = new Set()) {
+  if (!Array.isArray(rawErrors) || rawErrors.length === 0) return rawErrors;
+  const cascadePaths = new Set();
+  for (const e of rawErrors) {
+    if (e?.keyword === 'oneOf') cascadePaths.add(e.instancePath || '');
+  }
+  const isDescendantOfCascade = (path) => {
+    for (const cp of cascadePaths) {
+      if (cp === '' && path) return true;
+      if (cp && path.startsWith(cp + '/')) return true;
+    }
+    return false;
+  };
+  const seen = new Set();
+  const out = [];
+  for (const e of rawErrors) {
+    const p = e.instancePath || '';
+    // 분기 차별자 const 노이즈 — oneOf cascade 의 자식 path 에서만.
+    if (
+      e.keyword === 'const' &&
+      e.params?.allowedValue !== undefined &&
+      isDescendantOfCascade(p)
+    ) {
+      continue;
+    }
+    // cascade path 자신의 required 노이즈 (분기별 누락 필드 보고).
+    if (e.keyword === 'required' && cascadePaths.has(p)) {
+      continue;
+    }
+    // OtherControl fallback 의 not 차별자 — cascade 자신/자손 모두 노이즈.
+    if (
+      e.keyword === 'not' &&
+      (cascadePaths.has(p) || isDescendantOfCascade(p))
+    ) {
+      continue;
+    }
+    // cascade path 의 if/then 조건 분기 실패 노이즈 — 분기별 conditional 실패.
+    // 진짜 원인은 동일 path 의 다른 에러 (unevaluatedProperty 등) 로 충분.
+    if (e.keyword === 'if' && cascadePaths.has(p)) {
+      continue;
+    }
+    // 정상 키에 대한 unevaluated/additional 노이즈.
+    if (
+      e.keyword === 'unevaluatedProperties' ||
+      e.keyword === 'additionalProperties'
+    ) {
+      const prop =
+        e.params?.unevaluatedProperty ?? e.params?.additionalProperty;
+      if (prop && knownProps.has(prop)) continue;
+    }
+    // 중복 제거 — schemaPath 무시 (분기별 동일 에러).
+    const dedupeKey = `${p}|${e.keyword}|${
+      e.params?.unevaluatedProperty ??
+      e.params?.additionalProperty ??
+      e.params?.missingProperty ??
+      e.params?.allowedValue ??
+      ''
+    }`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    out.push(e);
+  }
+  return out.length > 0 ? out : rawErrors;
+}
+
+/**
+ * loose(ajv basic) 경로의 oneOf cascade 잔존 노이즈를 접는다.
+ * denoiseErrors 가 분기별 const/required/not/if 노이즈를 제거한 뒤에도,
+ * oneOf 결정 실패 wrapper("must match exactly one schema in oneOf") 가 path 마다
+ * 남아 cascade 를 부풀린다 (모델이 보는 oneOf 는 strict 가 전량 폐기하므로 전부 loose 산).
+ *
+ * 규칙: wrapper(keyword:'oneOf', instancePath P) 는 P 또는 그 자손 path 에 더
+ *       구체적인(non-oneOf) 에러가 하나라도 있으면 redundant 로 보고 fold —
+ *       진짜 원인은 가장 깊은 구체 에러에 있다(failure-discipline §"deepest first").
+ *       구체 에러가 전혀 없는 "단독 리프 oneOf" wrapper 는 유일한 실패 신호이므로 보존.
+ *
+ * 안전 (검증 단언과 정렬):
+ *  - keyword !== 'oneOf' 인 에러는 절대 건드리지 않음 → 비-oneOf 에러 집합 불변.
+ *  - 제거만 수행 → errorCount 비증가.
+ *  - 단독 리프 oneOf 미제거.
+ *  - 전부 접혀 빈 배열이 되면 원본을 그대로 반환 (safety net).
+ *
+ * @param {Array} errors  denoiseErrors 통과 후의 (ajv 형태) loose 에러 배열
+ */
+export function foldOneOfCascade(errors) {
+  if (!Array.isArray(errors) || errors.length === 0) return errors;
+  const concretePaths = [];
+  for (const e of errors) {
+    if (e?.keyword !== 'oneOf') concretePaths.push(e.instancePath || '');
+  }
+  const hasConcreteAtOrBelow = (p) => {
+    for (const cp of concretePaths) {
+      if (p === '') return true;                       // root wrapper + 구체 에러 ≥1 → redundant
+      if (cp === p || cp.startsWith(p + '/')) return true;
+    }
+    return false;
+  };
+  const out = errors.filter((e) => {
+    if (e?.keyword !== 'oneOf') return true;           // 비-oneOf: 통과(불변)
+    return !hasConcreteAtOrBelow(e.instancePath || ''); // 구체 원인 있으면 wrapper fold
+  });
+  return out.length > 0 ? out : errors;                // safety net
+}
+
+/* ControlType / 'Group'(ContentsType) → schema key 맵. control/*.schema.json 의
+ * ControlType const 를 스캔해 1회 빌드. (스캔 실패해도 빈 맵 → surface 비활성.) */
+function buildTypeSchemaMap(schemaCache) {
+  const map = {};
+  if (!schemaCache || typeof schemaCache.entries !== 'function') return map;
+  for (const [key, data] of schemaCache.entries()) {
+    if (!/^control\//.test(key)) continue;
+    let ct = null;
+    const find = (o) => {
+      if (!o || typeof o !== 'object' || ct) return;
+      if (o.properties?.ControlType?.const) { ct = o.properties.ControlType.const; return; }
+      for (const k of Object.keys(o)) find(o[k]);
+    };
+    find(data);
+    if (ct) map[ct] = key;
+  }
+  return map;
+}
+
+/* JSON-pointer 스타일 instancePath 로 payload 내부 노드를 해상. */
+function resolveInstancePath(root, path) {
+  if (!path) return root;
+  let node = root;
+  for (const raw of path.split('/').slice(1)) {
+    const seg = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (node == null || typeof node !== 'object') return undefined;
+    node = Array.isArray(node) ? node[Number(seg)] : node[seg];
+  }
+  return node;
+}
+
+/**
+ * leaf oneOf wrapper("must match exactly one schema in oneOf", 구체 자식 없음) 를
+ * actionable 한 에러로 치환한다. 모델은 bare wrapper 만 보면 무엇이 틀렸는지 모른다.
+ * 해당 노드의 실제 discriminator(ControlType / ContentsType:'Group')로 구체 스키마를
+ * 골라 재검증 → 의도한 브랜치의 concrete 에러(빠진 required 등)를 표면화.
+ *
+ * denoiseErrors 의 "분기별 노이즈 폴딩" 과 달리, 데이터의 실제 타입으로 의도 브랜치를
+ * 정확히 특정하므로 오접힘 없이 actionable 신호만 낸다.
+ *
+ * 안전:
+ *  - leaf oneOf wrapper 에만 작동 (이미 concrete 에러가 있으면 그게 표면화돼 있으므로 무시).
+ *  - 노드/스키마 미해상도, 재검증서 concrete 0 → 원본 wrapper 유지(신호 보존).
+ *  - non-oneOf 에러는 그대로 통과.
+ *
+ * @param {Array} errors  foldOneOfCascade 통과 후 (ajv 형태) loose 에러
+ * @param {object} payload 검증 대상 (materialized scenario)
+ * @param {object} ajv     buildAjv() 의 loose ajv
+ * @param {Map} schemaCache buildAjv() 의 schemaCache
+ */
+const SURFACE_LEAF_CAP = 3;
+
+export function surfaceControlBranchErrors(errors, payload, ajv, schemaCache) {
+  if (!Array.isArray(errors) || errors.length === 0 || !payload || !ajv) return errors;
+  const concretePaths = errors.filter((e) => e?.keyword !== 'oneOf').map((e) => e.instancePath || '');
+  const hasConcreteAtOrBelow = (p) =>
+    concretePaths.some((cp) => p === '' || cp === p || cp.startsWith(p + '/'));
+  // leaf oneOf wrapper(구체 자식 없는) 개수 — 너무 많으면(시나리오가 근본적으로 깨짐)
+  // 노드마다 missing-required 를 surface 하면 노이즈 폭증이라 비활성(wrapper 보존).
+  // near-clean(1~CAP 개) 케이스의 actionable 표면화에만 작동.
+  const leafCount = errors.filter(
+    (e) => e?.keyword === 'oneOf' && !hasConcreteAtOrBelow(e.instancePath || ''),
+  ).length;
+  if (leafCount === 0 || leafCount > SURFACE_LEAF_CAP) return errors;
+  let typeToKey = null;
+  const out = [];
+  for (const e of errors) {
+    if (e?.keyword !== 'oneOf' || hasConcreteAtOrBelow(e.instancePath || '')) { out.push(e); continue; }
+    const node = resolveInstancePath(payload, e.instancePath || '');
+    if (!node || typeof node !== 'object' || Array.isArray(node)) { out.push(e); continue; }
+    if (typeToKey === null) typeToKey = buildTypeSchemaMap(schemaCache);
+    const key = node.ContentsType === 'Group'
+      ? 'group.schema.json'
+      : (typeof node.ControlType === 'string' ? typeToKey[node.ControlType] : null);
+    const v = key && ajv.getSchema(key);
+    if (!v) { out.push(e); continue; }
+    v(node);
+    // 노드 자신의 top-level 무조건 required 누락만 표면화 (schemaPath '#/required').
+    // 중첩 allOf/oneOf 브랜치(예: Combo.Dialog.ComboList) 의 required/const cascade 는
+    // 재검증서 다시 폭발하므로 제외 — "이 컨트롤에 빠진 필수 키" 만 actionable 하게.
+    const concrete = (v.errors || []).filter(
+      (x) => x.keyword === 'required' && x.schemaPath === '#/required',
+    );
+    if (concrete.length === 0) { out.push(e); continue; } // 못 찾으면 wrapper 보존
+    const base = e.instancePath || '';
+    const seen = new Set();
+    for (const c of concrete) {
+      const ip = base + (c.instancePath || '');
+      const dk = `${ip}|${c.keyword}|${c.params?.missingProperty ?? c.params?.allowedValue ?? ''}`;
+      if (seen.has(dk)) continue;
+      seen.add(dk);
+      out.push({ ...c, instancePath: ip });
+    }
+  }
+  return out;
+}
+
+/**
+ * --schema=<ref> 의 ref 를 (key, fragment) 로 분해.
+ *  매칭 우선순위: file key → $id → basename(=shorthand) → 부분 일치 (1개).
+ */
+export function resolveSchemaRef(ref, schemaIndex) {
+  if (!ref) return { key: null, fragment: '', candidates: [] };
+  let baseRef = ref, fragment = '';
+  const hashIdx = ref.indexOf('#');
+  if (hashIdx >= 0) {
+    baseRef = ref.slice(0, hashIdx);
+    fragment = ref.slice(hashIdx);
+  }
+  if (!baseRef) return { key: null, fragment, candidates: [] };
+
+  const exactKey = schemaIndex.find(s => s.key === baseRef);
+  if (exactKey) return { key: exactKey.key, fragment, candidates: [] };
+
+  const exactId = schemaIndex.find(s => s.id === baseRef);
+  if (exactId) return { key: exactId.key, fragment, candidates: [] };
+
+  const exactBase = schemaIndex.filter(s => s.basename === baseRef);
+  if (exactBase.length === 1) return { key: exactBase[0].key, fragment, candidates: [] };
+  if (exactBase.length > 1) return { key: null, fragment, candidates: exactBase.map(s => s.key) };
+
+  const partial = schemaIndex.filter(s =>
+    s.key.includes(baseRef) || (s.id && s.id.includes(baseRef)) || s.basename.includes(baseRef)
+  );
+  if (partial.length === 1) return { key: partial[0].key, fragment, candidates: [] };
+  return { key: null, fragment, candidates: partial.map(s => s.key) };
+}
+
+/** key + fragment 에서 ajv validator 함수 획득 (없으면 null). */
+export function getValidatorFor(ajv, schemaIndex, key, fragment) {
+  const baseSchema = schemaIndex.find(s => s.key === key);
+  if (!baseSchema) return null;
+  if (!fragment) return ajv.getSchema(key);
+  if (baseSchema.id) {
+    const refUri = baseSchema.id + fragment;
+    const found = ajv.getSchema(refUri);
+    if (found) return found;
+  }
+  try {
+    return ajv.compile({ $ref: (baseSchema.id || key) + fragment });
+  } catch {
+    return null;
+  }
+}
+
+/** JSON Pointer 로 schema 부분 객체 추출 (#/$defs/foo → schema.$defs.foo). */
+export function extractFragment(schema, fragment) {
+  if (!fragment) return schema;
+  const pointer = fragment.replace(/^#/, '');
+  const parts = pointer.split('/').filter(Boolean).map(p => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let node = schema;
+  for (const p of parts) {
+    if (node && typeof node === 'object' && Object.prototype.hasOwnProperty.call(node, p)) {
+      node = node[p];
+    } else {
+      return undefined;
+    }
+  }
+  return node;
+}