@hanna84/mcp-writing 2.12.4 → 2.12.6

package/src/sync/metadata-lint.js

@@ -0,0 +1,468 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import {
+  inferProjectAndUniverse,
+  isCanonicalWorldEntityFile,
+  isWorldFile,
+  parseFile,
+  sidecarPath,
+  walkFiles,
+  walkSidecars,
+  worldEntityFolderKey,
+  worldEntityKindForPath,
+} from "./sync.js";
+import yaml from "js-yaml";
+
+const { load: parseYaml } = yaml;
+
+const metadataKindSchema = z.enum(["scene", "character", "place"]);
+
+const threadLinkSchema = z.object({
+  thread_id: z.string().min(1),
+  beat: z.string().min(1).optional(),
+  thread_name: z.string().min(1).optional(),
+  status: z.string().min(1).optional(),
+});
+
+const sceneSchema = z.object({
+  scene_id: z.string().min(1),
+  external_source: z.string().min(1).optional(),
+  external_id: z.string().min(1).optional(),
+  title: z.string().min(1).optional(),
+  part: z.number().int().positive().optional(),
+  chapter: z.number().int().positive().optional(),
+  chapter_title: z.string().min(1).optional(),
+  pov: z.string().min(1).optional(),
+  logline: z.string().min(1).optional(),
+  save_the_cat_beat: z.string().min(1).optional(),
+  status: z.string().min(1).optional(),
+  timeline_position: z.number().int().optional(),
+  story_time: z.string().min(1).optional(),
+  word_count: z.number().int().nonnegative().optional(),
+  scene_change: z.string().min(1).optional(),
+  causality: z.string().min(1).optional(),
+  stakes: z.string().min(1).optional(),
+  scene_functions: z.array(z.string().min(1)).optional(),
+  characters: z.array(z.string().min(1)).optional(),
+  places: z.array(z.string().min(1)).optional(),
+  tags: z.array(z.string().min(1)).optional(),
+  versions: z.array(z.string().min(1)).optional(),
+  threads: z.array(threadLinkSchema).optional(),
+});
+
+const characterSchema = z.object({
+  character_id: z.string().min(1),
+  canonical: z.boolean().optional(),
+  name: z.string().min(1).optional(),
+  role: z.string().min(1).optional(),
+  group: z.string().min(1).optional(),
+  arc_summary: z.string().min(1).optional(),
+  first_appearance: z.string().min(1).optional(),
+  traits: z.array(z.string().min(1)).optional(),
+  tags: z.array(z.string().min(1)).optional(),
+});
+
+const placeSchema = z.object({
+  place_id: z.string().min(1),
+  canonical: z.boolean().optional(),
+  name: z.string().min(1).optional(),
+  associated_characters: z.array(z.string().min(1)).optional(),
+  tags: z.array(z.string().min(1)).optional(),
+});
+
+const sceneAllowedKeys = new Set(Object.keys(sceneSchema.shape));
+const characterAllowedKeys = new Set(Object.keys(characterSchema.shape));
+const placeAllowedKeys = new Set(Object.keys(placeSchema.shape));
+const sceneLegacyKeys = new Set(["synopsis", "save_the_cat", "change"]);
+
+function uniqueItems(items = []) {
+  return new Set(items).size === items.length;
+}
+
+export function detectMetadataKind(meta) {
+  if (meta && typeof meta === "object") {
+    if (typeof meta.character_id === "string") return "character";
+    if (typeof meta.place_id === "string") return "place";
+    return "scene";
+  }
+  return "scene";
+}
+
+function allowedKeysFor(kind) {
+  if (kind === "character") return characterAllowedKeys;
+  if (kind === "place") return placeAllowedKeys;
+  return sceneAllowedKeys;
+}
+
+function schemaFor(kind) {
+  if (kind === "character") return characterSchema;
+  if (kind === "place") return placeSchema;
+  return sceneSchema;
+}
+
+function validateUniqueArrays(meta, kind, issues) {
+  const fields = kind === "scene"
+    ? ["characters", "places", "tags", "scene_functions", "versions"]
+    : kind === "character"
+      ? ["traits", "tags"]
+      : ["associated_characters", "tags"];
+
+  for (const key of fields) {
+    if (Array.isArray(meta[key]) && !uniqueItems(meta[key])) {
+      issues.push({
+        level: "warning",
+        code: "DUPLICATE_ARRAY_ITEMS",
+        message: `Array '${key}' contains duplicate values.`,
+      });
+    }
+  }
+}
+
+function validateSceneCharacterReferenceStyle(meta, issues) {
+  if (!Array.isArray(meta.characters) || meta.characters.length === 0) return;
+
+  if (!meta.characters.every(value => typeof value === "string")) return;
+
+  const hasCanonicalIds = meta.characters.some(value => /^char-/.test(String(value).trim()));
+  const hasNonCanonicalEntries = meta.characters.some(value => !/^char-/.test(String(value).trim()));
+
+  if (!hasCanonicalIds || !hasNonCanonicalEntries) return;
+
+  issues.push({
+    level: "warning",
+    code: "MIXED_CHARACTER_REFERENCE_STYLE",
+    message: "Scene characters contain mixed canonical and non-canonical references. Prefer canonical character_id values only.",
+  });
+}
+
+export function validateMetadataObject(meta, { sourcePath, kindHint } = {}) {
+  const issues = [];
+  const kind = metadataKindSchema.parse(kindHint ?? detectMetadataKind(meta));
+  const schema = schemaFor(kind);
+  const allowed = allowedKeysFor(kind);
+
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+    return {
+      ok: false,
+      kind,
+      issues: [{
+        level: "error",
+        code: "INVALID_METADATA_OBJECT",
+        message: "Metadata must be a YAML mapping/object.",
+      }],
+    };
+  }
+
+  const parsed = schema.safeParse(meta);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      issues.push({
+        level: "error",
+        code: "SCHEMA_VALIDATION_ERROR",
+        message: `${issue.path.join(".") || "metadata"}: ${issue.message}`,
+      });
+    }
+  }
+
+  for (const key of Object.keys(meta)) {
+    if (kind === "scene" && sceneLegacyKeys.has(key)) {
+      issues.push({
+        level: "warning",
+        code: "LEGACY_SCENE_KEY",
+        message: `Legacy scene key '${key}' found. Prefer canonical sidecar keys.`,
+      });
+      continue;
+    }
+    if (!allowed.has(key)) {
+      issues.push({
+        level: "warning",
+        code: "UNKNOWN_KEY",
+        message: `Unknown key '${key}' for ${kind} metadata.`,
+      });
+    }
+  }
+
+  validateUniqueArrays(meta, kind, issues);
+
+  if (kind === "scene") {
+    validateSceneCharacterReferenceStyle(meta, issues);
+  }
+
+  if (kind === "scene" && sourcePath) {
+    const sidecar = sourcePath.endsWith(".meta.yaml");
+    if (sidecar && !meta.scene_id) {
+      issues.push({
+        level: "error",
+        code: "MISSING_SCENE_ID",
+        message: "Scene sidecar is missing required 'scene_id'.",
+      });
+    }
+  }
+
+  const hasErrors = issues.some(i => i.level === "error");
+  return { ok: !hasErrors, kind, issues };
+}
+
+function loadYamlFile(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseYaml(raw);
+    return { ok: true, value: parsed ?? {} };
+  } catch (err) {
+    return {
+      ok: false,
+      error: {
+        level: "error",
+        code: "YAML_PARSE_ERROR",
+        message: `Failed to parse YAML: ${err.message}`,
+      },
+    };
+  }
+}
+
+function lintSidecar(filePath) {
+  const loaded = loadYamlFile(filePath);
+  if (!loaded.ok) {
+    return {
+      file: filePath,
+      kind: "scene",
+      issues: [loaded.error],
+    };
+  }
+  const result = validateMetadataObject(loaded.value, { sourcePath: filePath });
+  return { file: filePath, kind: result.kind, issues: result.issues };
+}
+
+function lintFrontmatter(filePath) {
+  try {
+    const { data } = parseFile(filePath);
+    if (!data || !Object.keys(data).length) return null;
+    const result = validateMetadataObject(data, { sourcePath: filePath });
+    return { file: filePath, kind: result.kind, issues: result.issues };
+  } catch (err) {
+    return {
+      file: filePath,
+      kind: "scene",
+      issues: [{
+        level: "error",
+        code: "FRONTMATTER_PARSE_ERROR",
+        message: `Failed to parse frontmatter: ${err.message}`,
+      }],
+    };
+  }
+}
+
+function loadMetadataForFile(filePath) {
+  const sidecar = sidecarPath(filePath);
+  if (fs.existsSync(sidecar)) {
+    const loaded = loadYamlFile(sidecar);
+    return loaded.ok ? loaded.value : null;
+  }
+
+  try {
+    const { data } = parseFile(filePath);
+    return data && Object.keys(data).length ? data : {};
+  } catch {
+    return null;
+  }
+}
+
+function reportPathForFile(filePath) {
+  const sidecar = sidecarPath(filePath);
+  return fs.existsSync(sidecar) ? sidecar : filePath;
+}
+
+function addIssueToReport(reports, filePath, kind, issue) {
+  const reportFile = reportPathForFile(filePath);
+  const report = reports.find(r => r.file === reportFile);
+  if (report) {
+    report.issues.push(issue);
+    return;
+  }
+  reports.push({ file: reportFile, kind, issues: [issue] });
+}
+
+function shouldWarnNoMetadata(syncDir, filePath) {
+  if (!isWorldFile(syncDir, filePath)) return true;
+
+  const kind = worldEntityKindForPath(syncDir, filePath);
+  if (!kind) return false;
+
+  return isCanonicalWorldEntityFile(syncDir, filePath, {});
+}
+
+function compareSidecarAndFrontmatter(filePath, reports) {
+  const sidecar = sidecarPath(filePath);
+  if (!fs.existsSync(sidecar)) return;
+  const sc = reports.find(r => r.file === sidecar);
+  if (!sc) return;
+
+  try {
+    const { data } = parseFile(filePath);
+    if (!data || !Object.keys(data).length) return;
+    const sidecarData = parseYaml(fs.readFileSync(sidecar, "utf8")) ?? {};
+
+    if (typeof data.scene_id === "string" && typeof sidecarData.scene_id === "string" && data.scene_id !== sidecarData.scene_id) {
+      sc.issues.push({
+        level: "warning",
+        code: "SCENE_ID_MISMATCH",
+        message: `scene_id mismatch between frontmatter ('${data.scene_id}') and sidecar ('${sidecarData.scene_id}').`,
+      });
+    }
+  } catch {
+    // Parsing failures are already surfaced by individual report entries.
+  }
+}
+
+export function lintMetadataInSyncDir(syncDir) {
+  const reports = [];
+  const files = walkFiles(syncDir);
+
+  for (const sidecar of walkSidecars(syncDir)) {
+    reports.push(lintSidecar(sidecar));
+  }
+
+  for (const file of files) {
+    if (fs.existsSync(sidecarPath(file))) {
+      continue;
+    }
+    const frontmatterReport = lintFrontmatter(file);
+    if (frontmatterReport) {
+      reports.push(frontmatterReport);
+    } else if (shouldWarnNoMetadata(syncDir, file)) {
+      // No sidecar and no frontmatter — file will be silently skipped during sync
+      reports.push({
+        file,
+        kind: "scene",
+        issues: [{
+          level: "warning",
+          code: "NO_METADATA",
+          message: "File has no sidecar and no frontmatter — will be skipped during sync (no scene_id).",
+        }],
+      });
+    }
+  }
+
+  for (const file of files) {
+    compareSidecarAndFrontmatter(file, reports);
+  }
+
+  // --- Duplicate scene_id detection (cross-file, errors) ---
+  const sceneIdToFiles = new Map(); // scene_id → [filePath, ...]
+
+  for (const sidecar of walkSidecars(syncDir)) {
+    try {
+      const raw = fs.readFileSync(sidecar, "utf8");
+      const meta = parseYaml(raw) ?? {};
+      if (typeof meta.scene_id === "string" && meta.scene_id) {
+        const arr = sceneIdToFiles.get(meta.scene_id) ?? [];
+        arr.push(sidecar);
+        sceneIdToFiles.set(meta.scene_id, arr);
+      }
+    } catch { /* empty */ }
+  }
+  for (const file of files) {
+    if (fs.existsSync(sidecarPath(file))) continue; // already counted via sidecar
+    try {
+      const { data } = parseFile(file);
+      if (typeof data.scene_id === "string" && data.scene_id) {
+        const arr = sceneIdToFiles.get(data.scene_id) ?? [];
+        arr.push(file);
+        sceneIdToFiles.set(data.scene_id, arr);
+      }
+    } catch { /* empty */ }
+  }
+
+  for (const [sceneId, dupeFiles] of sceneIdToFiles) {
+    if (dupeFiles.length < 2) continue;
+    const relPaths = dupeFiles.map(f => path.relative(syncDir, f)).join(", ");
+    for (const f of dupeFiles) {
+      const report = reports.find(r => r.file === f);
+      const issue = {
+        level: "error",
+        code: "DUPLICATE_SCENE_ID",
+        message: `scene_id "${sceneId}" is used by ${dupeFiles.length} files: ${relPaths}`,
+      };
+      if (report) {
+        report.issues.push(issue);
+      } else {
+        reports.push({ file: f, kind: "scene", issues: [issue] });
+      }
+    }
+  }
+
+  const entityIdToFiles = new Map();
+  const canonicalFilesByFolder = new Map();
+
+  for (const file of files) {
+    const kind = worldEntityKindForPath(syncDir, file);
+    if (!kind) continue;
+
+    const meta = loadMetadataForFile(file);
+    if (!meta) continue;
+    if (!isCanonicalWorldEntityFile(syncDir, file, meta)) continue;
+
+    const folderKey = worldEntityFolderKey(syncDir, file, kind);
+    if (folderKey) {
+      const current = canonicalFilesByFolder.get(folderKey) ?? [];
+      current.push(file);
+      canonicalFilesByFolder.set(folderKey, current);
+    }
+
+    const entityId = kind === "character" ? meta.character_id : meta.place_id;
+    if (typeof entityId === "string" && entityId) {
+      const { universe_id, project_id } = inferProjectAndUniverse(syncDir, file);
+      const scopeKey = `${kind}:${universe_id ?? "-"}:${project_id ?? "-"}:${entityId}`;
+      const current = entityIdToFiles.get(scopeKey) ?? [];
+      current.push(file);
+      entityIdToFiles.set(scopeKey, current);
+    } else {
+      addIssueToReport(reports, file, kind, {
+        level: "warning",
+        code: kind === "character" ? "MISSING_CHARACTER_ID" : "MISSING_PLACE_ID",
+        message: `Canonical ${kind} file is missing required '${kind}_id'.`,
+      });
+    }
+  }
+
+  for (const [folderKey, canonicalFiles] of canonicalFilesByFolder) {
+    if (canonicalFiles.length < 2) continue;
+    const relPaths = canonicalFiles.map(f => path.relative(syncDir, f)).join(", ");
+    for (const file of canonicalFiles) {
+      addIssueToReport(reports, file, worldEntityKindForPath(syncDir, file), {
+        level: "error",
+        code: "MULTIPLE_CANONICAL_FILES",
+        message: `Multiple canonical files found in entity folder '${folderKey}': ${relPaths}`,
+      });
+    }
+  }
+
+  for (const [scopeKey, dupeFiles] of entityIdToFiles) {
+    if (dupeFiles.length < 2) continue;
+    const entityId = scopeKey.split(":").at(-1);
+    const kind = scopeKey.split(":")[0];
+    const relPaths = dupeFiles.map(f => path.relative(syncDir, f)).join(", ");
+    for (const file of dupeFiles) {
+      addIssueToReport(reports, file, kind, {
+        level: "error",
+        code: kind === "character" ? "DUPLICATE_CHARACTER_ID" : "DUPLICATE_PLACE_ID",
+        message: `${kind}_id '${entityId}' is used by ${dupeFiles.length} canonical files: ${relPaths}`,
+      });
+    }
+  }
+
+  const errors = reports.flatMap(r => r.issues.map(i => ({ ...i, file: r.file, kind: r.kind }))).filter(i => i.level === "error");
+  const warnings = reports.flatMap(r => r.issues.map(i => ({ ...i, file: r.file, kind: r.kind }))).filter(i => i.level === "warning");
+
+  return {
+    ok: errors.length === 0,
+    syncDir: path.resolve(syncDir),
+    files_checked: reports.length,
+    error_count: errors.length,
+    warning_count: warnings.length,
+    errors,
+    warnings,
+    reports,
+  };
+}

package/src/sync/scene-character-batch.js

@@ -0,0 +1,246 @@
+import fs from "node:fs";
+import matter from "gray-matter";
+import { buildCharacterNormalizationContext, escapeRegex, resolveCharacterReference } from "./scene-character-normalization.js";
+import { normalizeSceneMetaForPath, readMeta, writeMeta } from "./sync.js";
+
+function normalizeCharacterRows(rows) {
+  return buildCharacterNormalizationContext(rows);
+}
+
+function inferCharactersFromProse(prose, characterRows) {
+  const { clean, tokenMap } = characterRows;
+  const inferred = new Set();
+  const full_name_matches = new Set();
+  const ambiguous_tokens = [];
+
+  for (const row of clean) {
+    if (row.full_name_regex?.test(prose)) {
+      inferred.add(row.character_id);
+      full_name_matches.add(row.character_id);
+      continue;
+    }
+
+    // Precision-first v1 policy: multi-token names require a full phrase match.
+    if (row.phrase_tokens.length !== 1) {
+      continue;
+    }
+
+    for (const token of row.informative_tokens) {
+      const tokenRegex = new RegExp(`\\b${escapeRegex(token)}\\b`, "i");
+      if (!tokenRegex.test(prose)) continue;
+
+      const tokenIds = tokenMap.get(token) ?? [];
+      if (tokenIds.length === 1) {
+        inferred.add(row.character_id);
+      } else if (!ambiguous_tokens.includes(token)) {
+        ambiguous_tokens.push(token);
+      }
+    }
+  }
+
+  for (const [token, tokenIds] of tokenMap.entries()) {
+    if (tokenIds.length < 2) continue;
+    const tokenRegex = new RegExp(`\\b${escapeRegex(token)}\\b`, "i");
+    if (tokenRegex.test(prose) && !ambiguous_tokens.includes(token)) {
+      ambiguous_tokens.push(token);
+    }
+  }
+
+  return {
+    inferred_characters: [...inferred],
+    full_name_matches: [...full_name_matches],
+    ambiguous_tokens,
+  };
+}
+
+function resolveCharacterEntry(entry, characterRows) {
+  return resolveCharacterReference(entry, characterRows);
+}
+
+function pruneLessSpecificCharacters(characterIds, fullNameMatches, characterRows) {
+  const kept = new Set(characterIds);
+
+  for (const candidateId of [...kept]) {
+    const candidate = characterRows.byId.get(candidateId);
+    if (!candidate || candidate.informative_tokens.length < 2) continue;
+
+    for (const dominantId of fullNameMatches) {
+      if (candidateId === dominantId) continue;
+      const dominant = characterRows.byId.get(dominantId);
+      if (!dominant) continue;
+      if (candidate.informative_tokens.length >= dominant.informative_tokens.length) continue;
+
+      if (candidate.informative_tokens.every(token => dominant.informative_tokens.includes(token))) {
+        kept.delete(candidateId);
+        break;
+      }
+    }
+  }
+
+  return [...kept];
+}
+
+function nextTurn() {
+  return new Promise(resolve => setImmediate(resolve));
+}
+
+function getInterSceneDelayMs() {
+  const raw = Number(process.env.MCP_WRITING_SCENE_CHARACTER_BATCH_DELAY_MS ?? 0);
+  return Number.isFinite(raw) && raw > 0 ? raw : 0;
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function runSceneCharacterBatch({ syncDir, args, onProgress, shouldCancel }) {
+  const {
+    project_id,
+    dry_run = true,
+    replace_mode = "merge",
+    include_match_details = false,
+    project_exists = true,
+    target_scenes = [],
+    character_rows = [],
+  } = args;
+
+  const targetScenes = Array.isArray(target_scenes) ? target_scenes : [];
+  const characterRows = Array.isArray(character_rows) ? character_rows : [];
+  const normalizedCharacterRows = normalizeCharacterRows(characterRows);
+
+  const results = [];
+  let processed_scenes = 0;
+  let scenes_changed = 0;
+  let failed_scenes = 0;
+  let links_added = 0;
+  let links_removed = 0;
+  const interSceneDelayMs = getInterSceneDelayMs();
+
+  const emitProgress = () => {
+    if (typeof onProgress !== "function") return;
+    onProgress({
+      total_scenes: targetScenes.length,
+      processed_scenes,
+      scenes_changed,
+      failed_scenes,
+    });
+  };
+
+  emitProgress();
+
+  for (const scene of targetScenes) {
+    await nextTurn();
+
+    if (typeof shouldCancel === "function" && shouldCancel()) {
+      break;
+    }
+
+    try {
+      const raw = fs.readFileSync(scene.file_path, "utf8");
+      const { content: prose } = matter(raw);
+      const { meta } = readMeta(scene.file_path, syncDir, { writable: !dry_run });
+
+      const before_characters = [...new Set((meta.characters ?? []).map(String).filter(Boolean))];
+      const normalized_before_characters = [...new Set(
+        before_characters
+          .map(character => resolveCharacterEntry(character, normalizedCharacterRows))
+          .filter(Boolean)
+      )];
+      const inference = inferCharactersFromProse(prose, normalizedCharacterRows);
+      const inferred_characters = inference.inferred_characters;
+
+      const afterSet = new Set(normalized_before_characters);
+      if (replace_mode === "replace") {
+        afterSet.clear();
+      }
+      for (const characterId of inferred_characters) {
+        afterSet.add(characterId);
+      }
+
+      const after_characters = pruneLessSpecificCharacters(
+        [...afterSet],
+        inference.full_name_matches,
+        normalizedCharacterRows
+      );
+      const beforeSet = new Set(before_characters);
+      const added = after_characters.filter(id => !beforeSet.has(id));
+      const afterSetLookup = new Set(after_characters);
+      const removed = before_characters.filter(id => !afterSetLookup.has(id));
+      const changed = added.length > 0 || removed.length > 0;
+
+      if (!dry_run && changed) {
+        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
+          ...meta,
+          characters: after_characters,
+        }).meta;
+
+        writeMeta(scene.file_path, updatedMeta);
+      }
+
+      scenes_changed += changed ? 1 : 0;
+      links_added += added.length;
+      links_removed += removed.length;
+
+      const hasInferredMatches = inferred_characters.length > 0;
+      const sceneStatus = changed
+        ? "changed"
+        : (!hasInferredMatches && inference.ambiguous_tokens.length > 0 ? "skipped_ambiguous" : "unchanged");
+
+      results.push({
+        scene_id: scene.scene_id,
+        file_path: scene.file_path,
+        before_characters,
+        inferred_characters,
+        after_characters,
+        added,
+        removed,
+        changed,
+        status: sceneStatus,
+        ...(include_match_details ? { match_details: { ambiguous_tokens: inference.ambiguous_tokens } } : {}),
+      });
+    } catch (error) {
+      failed_scenes += 1;
+      results.push({
+        scene_id: scene.scene_id,
+        file_path: scene.file_path,
+        before_characters: [],
+        inferred_characters: [],
+        after_characters: [],
+        added: [],
+        removed: [],
+        changed: false,
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      processed_scenes += 1;
+      emitProgress();
+      if (interSceneDelayMs > 0) {
+        await delay(interSceneDelayMs);
+      }
+    }
+  }
+
+  const warnings = [];
+  if (failed_scenes > 0) {
+    warnings.push("PARTIAL_SUCCESS: one or more scenes failed to process.");
+  }
+  if (!project_exists && targetScenes.length === 0) {
+    warnings.push(`PROJECT_NOT_FOUND_WARNING: project '${project_id}' was not found; nothing to process.`);
+  }
+
+  return {
+    ok: true,
+    cancelled: Boolean(typeof shouldCancel === "function" && shouldCancel() && processed_scenes < targetScenes.length),
+    project_id,
+    dry_run: Boolean(dry_run),
+    total_scenes: targetScenes.length,
+    processed_scenes,
+    scenes_changed,
+    failed_scenes,
+    links_added,
+    links_removed,
+    results,
+    ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}),
+  };
+}