@richscripts/richtexteditor 2.4.0 → 2.4.1

package/migration/README.md

@@ -0,0 +1,100 @@
+# Migration helpers
+
+`@richscripts/richtexteditor/migration` is a server-safe CommonJS entry point for moving common configuration and content from TinyMCE, CKEditor 5, Froala, Quill, Tiptap, or Lexical.
+
+```js
+const { createMigrationReport, migrateConfig, migrateEditor } = require("@richscripts/richtexteditor/migration");
+
+const plan = migrateConfig("tinymce", legacyConfig);
+console.table(plan.unmapped);
+
+const result = migrateEditor("tinymce", legacyEditor, richTextEditor);
+console.table(result.warnings);
+
+const report = createMigrationReport("tinymce", { config: legacyConfig, content: legacyHtml });
+console.table(report.blockers);
+if (!report.readyForCutover) process.exitCode = 1;
+```
+
+- HTML-native editors transfer their HTML for RichTextEditor's normal loading pipeline.
+- Quill Delta, Tiptap JSON, and Lexical JSON receive semantic HTML conversion for common blocks and marks, including mixed multi-level ordered/bullet lists and source checklist state.
+- TinyMCE, CKEditor, and Froala HTML passes through without schema rewriting, while private runtime bookkeeping attributes (`data-mce-*`, `data-ck-*`, CKEditor list IDs, and `data-fr-*`) are removed before handoff.
+- Unknown toolbar items, embeds, nodes, and marks are reported. They are not silently presented as migrated.
+- `createMigrationReport` combines configuration and content findings into blockers, warnings, and a stable manual-review checklist for a pre-cutover inventory.
+- Custom plugins, schemas, collaboration state, comments, tracked changes, uploads, permissions, and application data remain explicit integration work.
+
+Always run representative production documents through both editors and compare saved output before cutover.
+
+## Custom structured-model converters
+
+Use explicit programmatic converters to resolve inventoried Quill embeds or Tiptap/Lexical nodes and marks without forking the adapter:
+
+```js
+const report = createMigrationReport("quill", {
+  content: legacyDelta,
+  converters: {
+    quill: {
+      embeds: {
+        mention(value) {
+          const id = escapeAttribute(value.id);
+          const label = escapeHtml(value.label);
+          return `<span data-mention="${id}">@${label}</span>`;
+        }
+      }
+    }
+  }
+});
+
+console.table(report.appliedConverters);
+```
+
+Registries support `quill.embeds`, `tiptap.nodes`, `tiptap.marks`, and `lexical.nodes`. A converter returns an HTML string or `{ html, warnings }`. Returning `null` deliberately falls through to the normal unsupported-content blocker. Successful applications are counted in `appliedConverters`; each entry also includes stable source-model `paths` and the converter receives the current `context.path`.
+
+Converter output is trusted application code and is not sanitized by the migration helper. Escape external values, sanitize generated HTML under your own policy, and keep representative-output review in the cutover gate.
+
+## File and batch inventory CLI
+
+The package also installs `rte-migration-report`. A single-document inventory accepts an HTML file for TinyMCE, CKEditor, or Froala, and a JSON export for Quill, Tiptap, or Lexical:
+
+```sh
+rte-migration-report --source quill --config quill-config.json --content article.delta.json --output report.json
+```
+
+For a batch, create a manifest. File references are resolved relative to the manifest, so the inventory is portable in CI:
+
+```json
+{
+  "entries": [
+    { "id": "terms", "source": "ckeditor", "configFile": "config.json", "contentFile": "terms.html" },
+    { "id": "guide", "source": "tiptap", "contentFile": "guide.json" }
+  ]
+}
+```
+
+```sh
+rte-migration-report --input migration-inventory.json --output migration-report.json
+```
+
+To reuse the programmatic converter registry in single-file or batch CI runs, opt into a local CommonJS module:
+
+```sh
+rte-migration-report --input migration-inventory.json --converters ./migration-converters.cjs --converter-sha256 "$REVIEWED_SHA256" --output migration-report.json
+```
+
+The module must export the same `quill`/`tiptap`/`lexical` registry object documented above. The CLI resolves this path from its invoking working directory and validates every registry group and converter function before reading the inventory. This flag executes local code with the permissions of the CLI process; use only a reviewed, trusted module from your repository. Pin reviewed bytes with `--converter-sha256 <64-character digest>`: a malformed value or content mismatch fails before the module can execute. Without `--converters`, the CLI remains data-only and preserves every unsupported-content blocker.
+
+CLI artifacts use report schema version `2` and include a stable `generator` object with the producing `@richscripts/richtexteditor` package version. Both single-document and batch output include `converterModule`: `null` for the default data-only path, or a non-sensitive file label, SHA-256 digest, and `hashVerifiedBeforeExecution` flag. Store the generator version and digest with CI artifacts and review schema-version changes before consuming new report fields. The label intentionally omits the local absolute path; the digest proves byte identity, not that the module is safe or correct.
+
+Reports intentionally omit a current-time field, so identical inputs, package code, and converter bytes serialize identically. Let the CI artifact store provide creation/retention timestamps; this keeps readiness diffs meaningful and reproducible.
+
+Print the packaged Draft 2020-12 JSON Schema with `rte-migration-report --print-schema`. The schema covers both single-document and batch artifacts, including generator identity, converter provenance, structured findings, aggregate totals, and nested document reports. The command is standalone so schema discovery cannot accidentally execute converters or read migration inputs.
+
+Validate a stored artifact with `rte-migration-report --validate-report ./migration-report.json`. This dependency-free mode checks schema/generator compatibility, document field shapes, readiness-versus-blocker consistency, and batch totals/unsupported inventories against the nested reports. It does not load converter modules or source migration files. A valid artifact exits `0` and emits compact JSON containing its exact-byte SHA-256; malformed, incompatible, or internally inconsistent artifacts exit `1` with the failed invariant.
+
+For promotion gates, add `--report-sha256 <64-character digest>`. The CLI compares the expected digest with the stored bytes before JSON parsing or validation and rejects mismatches. The output records `hashVerifiedBeforeValidation` so downstream jobs can distinguish a computed digest from an enforced pin. SHA-256 establishes byte identity and detects unintended artifact changes; it does not identify or authenticate a signer, and validation still does not replace content-fidelity acceptance.
+
+To gate only newly introduced migration debt, add `--baseline-report ./accepted-baseline.json` to `--validate-report`. Both artifacts are validated first. Comparison output lists new blocker messages and new/increased unsupported findings by document ID, source, kind, name, added count, and exact new source paths. Exit `0` means no new detected debt; exit `2` means regressions were found; exit `1` means an artifact or option was invalid. Existing accepted blockers remain visible in the reports, and a regression-free comparison is not production acceptance.
+
+Each document report includes a structured `unsupportedContent` inventory whose entries identify the unsupported `kind` (`node`, `mark`, or `embed`), name, occurrence count, and stable source-model paths such as `ops[4].insert.mention` or `$.content[2].marks[0]`. Batch output also provides document totals, `summary.unsupportedByDocument`, and source/kind/name rollups in `summary.unsupportedTotals`, including affected-document counts. CI and migration owners can locate, size, and assign custom conversion work without parsing warning text.
+
+The command exits `0` when every report has no automated blocker, `2` when blockers are present, and `1` for invalid input or I/O errors. Use `--allow-blockers` when generating an informational artifact should not fail CI. A zero exit code is not production acceptance: every report retains the manual-review checklist.

package/migration/cli.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+"use strict";
+
+var fs = require("node:fs");
+var path = require("node:path");
+var crypto = require("node:crypto");
+var migration = require("./index.js");
+var packageMetadata = require("../package.json");
+
+var REPORT_SCHEMA_VERSION = 2;
+var REPORT_GENERATOR = { name: "@richscripts/richtexteditor", version: packageMetadata.version };
+
+function usage() {
+  return [
+    "Usage:",
+    "  rte-migration-report --print-schema",
+    "  rte-migration-report --validate-report <report.json> [--report-sha256 <digest>] [--baseline-report <baseline.json>]",
+    "  rte-migration-report --source <editor> [--config <file>] [--content <file>] [--converters <module.cjs> --converter-sha256 <digest>] [--output <file>]",
+    "  rte-migration-report --input <manifest.json> [--converters <module.cjs> --converter-sha256 <digest>] [--output <file>] [--allow-blockers]",
+    "",
+    "Sources: " + migration.SOURCES.join(", "),
+    "Warning: --converters executes the specified local CommonJS module as trusted code.",
+    "Pin reviewed converter bytes with --converter-sha256; a mismatch is rejected before code execution.",
+    "Exit codes: 0 ready, 2 blockers found, 1 invalid input or I/O failure."
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  var options = { allowBlockers: false };
+  for (var index = 0; index < argv.length; index += 1) {
+    var arg = argv[index];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--print-schema") options.printSchema = true;
+    else if (arg === "--allow-blockers") options.allowBlockers = true;
+    else if (["--source", "--config", "--content", "--input", "--output", "--converters", "--converter-sha256", "--validate-report", "--report-sha256", "--baseline-report"].indexOf(arg) >= 0) {
+      if (!argv[index + 1] || /^--/.test(argv[index + 1])) throw new TypeError(arg + " requires a value");
+      options[arg === "--converter-sha256" ? "converterSha256" : arg === "--validate-report" ? "validateReport" : arg === "--report-sha256" ? "reportSha256" : arg === "--baseline-report" ? "baselineReport" : arg.slice(2)] = argv[index += 1];
+    } else throw new TypeError("Unknown option: " + arg);
+  }
+  return options;
+}
+
+function readJson(filePath, label) {
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch (error) { throw new Error("Unable to read " + label + " JSON at " + filePath + ": " + error.message); }
+}
+
+function readContent(filePath, source) {
+  var text;
+  try { text = fs.readFileSync(filePath, "utf8"); }
+  catch (error) { throw new Error("Unable to read content at " + filePath + ": " + error.message); }
+  return ["tinymce", "ckeditor", "ckeditor5", "froala"].indexOf(String(source).toLowerCase()) >= 0 ? text : (function () {
+    try { return JSON.parse(text); }
+    catch (error) { throw new Error("Structured content must be valid JSON at " + filePath + ": " + error.message); }
+  }());
+}
+
+function loadConverters(filePath, expectedSha256) {
+  var loaded, bytes, loadedBytes, digest, allowed = { quill: ["embeds"], tiptap: ["nodes", "marks"], lexical: ["nodes"] };
+  try { bytes = fs.readFileSync(filePath); }
+  catch (error) { throw new Error("Unable to read trusted converter module at " + filePath + ": " + error.message); }
+  digest = crypto.createHash("sha256").update(bytes).digest("hex");
+  if (expectedSha256 != null) {
+    expectedSha256 = String(expectedSha256).toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(expectedSha256)) throw new TypeError("--converter-sha256 must be a 64-character hexadecimal SHA-256 digest");
+    if (digest !== expectedSha256) throw new Error("Trusted converter module SHA-256 mismatch; refusing to execute " + path.basename(filePath));
+  }
+  try { loaded = require(filePath); }
+  catch (error) { throw new Error("Unable to load trusted converter module at " + filePath + ": " + error.message); }
+  try { loadedBytes = fs.readFileSync(filePath); }
+  catch (error) { throw new Error("Unable to verify trusted converter module at " + filePath + ": " + error.message); }
+  if (!bytes.equals(loadedBytes)) throw new Error("Trusted converter module changed while it was loading; rerun with a stable file: " + filePath);
+  if (loaded && loaded.__esModule && loaded.default) loaded = loaded.default;
+  if (!loaded || typeof loaded !== "object" || Array.isArray(loaded)) throw new TypeError("Trusted converter module must export a converter registry object");
+  Object.keys(loaded).forEach(function (source) {
+    if (!allowed[source]) throw new TypeError("Trusted converter module has unsupported source registry: " + source);
+    if (!loaded[source] || typeof loaded[source] !== "object" || Array.isArray(loaded[source])) throw new TypeError("Trusted converter source registry must be an object: " + source);
+    Object.keys(loaded[source]).forEach(function (group) {
+      if (allowed[source].indexOf(group) < 0) throw new TypeError("Trusted converter module has unsupported registry group: " + source + "." + group);
+      var registry = loaded[source][group];
+      if (!registry || typeof registry !== "object" || Array.isArray(registry)) throw new TypeError("Trusted converter registry must be an object: " + source + "." + group);
+      Object.keys(registry).forEach(function (name) { if (typeof registry[name] !== "function") throw new TypeError("Trusted converter must be a function: " + source + "." + group + "." + name); });
+    });
+  });
+  return {
+    converters: loaded,
+    provenance: {
+      label: path.basename(filePath),
+      sha256: digest,
+      hashVerifiedBeforeExecution: expectedSha256 != null
+    }
+  };
+}
+
+function resolveEntry(entry, baseDir, index, converters) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new TypeError("Inventory entry " + index + " must be an object");
+  if (!entry.source) throw new TypeError("Inventory entry " + index + " requires source");
+  var config = entry.config || {};
+  var content = entry.content;
+  if (entry.configFile) config = readJson(path.resolve(baseDir, entry.configFile), "config");
+  if (entry.contentFile) content = readContent(path.resolve(baseDir, entry.contentFile), entry.source);
+  var report = migration.createMigrationReport(entry.source, { config: config, content: content, converters: converters });
+  if (entry.id != null) report.id = String(entry.id);
+  return report;
+}
+
+function assertReport(condition, message) {
+  if (!condition) throw new TypeError("Invalid migration report: " + message);
+}
+
+function validateFindings(items, label) {
+  assertReport(Array.isArray(items), label + " must be an array");
+  items.forEach(function (item, index) {
+    var prefix = label + "[" + index + "]";
+    assertReport(item && typeof item === "object" && !Array.isArray(item), prefix + " must be an object");
+    assertReport(["embed", "node", "mark"].indexOf(item.kind) >= 0, prefix + ".kind is invalid");
+    assertReport(typeof item.name === "string" && item.name.length > 0, prefix + ".name is required");
+    assertReport(Number.isInteger(item.count) && item.count > 0, prefix + ".count must be a positive integer");
+    assertReport(Array.isArray(item.paths) && item.paths.every(function (value) { return typeof value === "string"; }), prefix + ".paths must be a string array");
+  });
+}
+
+function validateDocumentReport(report, label) {
+  assertReport(report && typeof report === "object" && !Array.isArray(report), label + " must be an object");
+  assertReport(typeof report.source === "string" && report.source.length > 0, label + ".source is required");
+  assertReport(typeof report.readyForCutover === "boolean", label + ".readyForCutover must be boolean");
+  assertReport(report.config && typeof report.config === "object" && !Array.isArray(report.config), label + ".config must be an object");
+  assertReport(typeof report.html === "string", label + ".html must be a string");
+  ["mappedCommands", "unmapped", "blockers", "warnings", "manualReview"].forEach(function (key) {
+    assertReport(Array.isArray(report[key]) && report[key].every(function (value) { return typeof value === "string"; }), label + "." + key + " must be a string array");
+  });
+  validateFindings(report.unsupportedContent, label + ".unsupportedContent");
+  validateFindings(report.appliedConverters, label + ".appliedConverters");
+  assertReport(report.readyForCutover === (report.blockers.length === 0), label + ".readyForCutover must agree with blockers");
+}
+
+function validateStoredReport(report) {
+  assertReport(report && typeof report === "object" && !Array.isArray(report), "root must be an object");
+  assertReport(report.schemaVersion === REPORT_SCHEMA_VERSION, "schemaVersion must be " + REPORT_SCHEMA_VERSION);
+  assertReport(report.generator && report.generator.name === REPORT_GENERATOR.name && typeof report.generator.version === "string" && report.generator.version.length > 0, "generator identity is invalid");
+  assertReport(report.converterModule === null || (report.converterModule && typeof report.converterModule.label === "string" && /^[a-f0-9]{64}$/.test(report.converterModule.sha256) && typeof report.converterModule.hashVerifiedBeforeExecution === "boolean"), "converterModule provenance is invalid");
+  if (!Array.isArray(report.reports)) {
+    validateDocumentReport(report, "report");
+    return report;
+  }
+  assertReport(report.reports.length > 0, "reports must not be empty");
+  report.reports.forEach(function (item, index) { validateDocumentReport(item, "reports[" + index + "]"); });
+  assertReport(report.summary && typeof report.summary === "object", "summary is required for batch reports");
+  var ready = report.reports.filter(function (item) { return item.readyForCutover; }).length;
+  assertReport(report.summary.documents === report.reports.length, "summary.documents does not match reports.length");
+  assertReport(report.summary.readyDocuments === ready, "summary.readyDocuments does not match reports");
+  assertReport(report.summary.blockedDocuments === report.reports.length - ready, "summary.blockedDocuments does not match reports");
+  assertReport(report.readyForCutover === (ready === report.reports.length), "readyForCutover does not match batch reports");
+  assertReport(Array.isArray(report.summary.unsupportedTotals), "summary.unsupportedTotals must be an array");
+  assertReport(Array.isArray(report.summary.unsupportedByDocument), "summary.unsupportedByDocument must be an array");
+  var expectedByDocument = report.reports.filter(function (item) { return item.unsupportedContent.length; }).map(function (item, index) {
+    return { id: item.id == null ? String(index) : item.id, source: item.source, items: item.unsupportedContent };
+  });
+  assertReport(JSON.stringify(report.summary.unsupportedByDocument) === JSON.stringify(expectedByDocument), "summary.unsupportedByDocument does not match reports");
+  var expectedTotals = [];
+  report.reports.forEach(function (item) {
+    item.unsupportedContent.forEach(function (finding) {
+      var total = expectedTotals.filter(function (candidate) { return candidate.source === item.source && candidate.kind === finding.kind && candidate.name === finding.name; })[0];
+      if (total) { total.count += finding.count; total.documents += 1; }
+      else expectedTotals.push({ source: item.source, kind: finding.kind, name: finding.name, count: finding.count, documents: 1 });
+    });
+  });
+  expectedTotals.sort(function (left, right) { return (left.source + "\0" + left.kind + "\0" + left.name).localeCompare(right.source + "\0" + right.kind + "\0" + right.name); });
+  assertReport(JSON.stringify(report.summary.unsupportedTotals) === JSON.stringify(expectedTotals), "summary.unsupportedTotals does not match reports");
+  return report;
+}
+
+function reportDocuments(report) { return Array.isArray(report.reports) ? report.reports : [report]; }
+
+function compareStoredReports(baseline, current) {
+  validateStoredReport(baseline);
+  validateStoredReport(current);
+  var baselineDocs = reportDocuments(baseline), currentDocs = reportDocuments(current), baselineBlockers = {}, baselineFindings = {};
+  baselineDocs.forEach(function (report, index) {
+    var id = report.id == null ? String(index) : String(report.id);
+    report.blockers.forEach(function (message) { baselineBlockers[id + "\0" + report.source + "\0" + message] = true; });
+    report.unsupportedContent.forEach(function (item) { baselineFindings[id + "\0" + report.source + "\0" + item.kind + "\0" + item.name] = item; });
+  });
+  var newBlockers = [], newUnsupported = [];
+  currentDocs.forEach(function (report, index) {
+    var id = report.id == null ? String(index) : String(report.id);
+    report.blockers.forEach(function (message) {
+      if (!baselineBlockers[id + "\0" + report.source + "\0" + message]) newBlockers.push({ id: id, source: report.source, message: message });
+    });
+    report.unsupportedContent.forEach(function (item) {
+      var old = baselineFindings[id + "\0" + report.source + "\0" + item.kind + "\0" + item.name], oldPaths = old ? old.paths : [];
+      var paths = item.paths.filter(function (value) { return oldPaths.indexOf(value) < 0; });
+      var addedCount = Math.max(0, item.count - (old ? old.count : 0));
+      if (addedCount || paths.length) newUnsupported.push({ id: id, source: report.source, kind: item.kind, name: item.name, addedCount: addedCount, paths: paths });
+    });
+  });
+  return { regressionFree: newBlockers.length === 0 && newUnsupported.length === 0, newBlockers: newBlockers, newUnsupported: newUnsupported };
+}
+
+function createOutput(options, cwd) {
+  if (options.input && options.source) throw new TypeError("Use either --input or --source, not both");
+  if (options.converterSha256 && !options.converters) throw new TypeError("--converter-sha256 requires --converters");
+  var loadedConverters = options.converters ? loadConverters(path.resolve(cwd, options.converters), options.converterSha256) : undefined;
+  var converters = loadedConverters && loadedConverters.converters;
+  if (options.input) {
+    var manifestPath = path.resolve(cwd, options.input);
+    var manifest = readJson(manifestPath, "manifest");
+    var entries = Array.isArray(manifest) ? manifest : manifest.entries;
+    if (!Array.isArray(entries) || !entries.length) throw new TypeError("Manifest must be a non-empty array or contain a non-empty entries array");
+    var reports = entries.map(function (entry, index) { return resolveEntry(entry, path.dirname(manifestPath), index, converters); });
+    var unsupportedTotals = [];
+    reports.forEach(function (report) {
+      report.unsupportedContent.forEach(function (item) {
+        var total = unsupportedTotals.filter(function (candidate) { return candidate.source === report.source && candidate.kind === item.kind && candidate.name === item.name; })[0];
+        if (total) { total.count += item.count; total.documents += 1; }
+        else unsupportedTotals.push({ source: report.source, kind: item.kind, name: item.name, count: item.count, documents: 1 });
+      });
+    });
+    unsupportedTotals.sort(function (left, right) { return (left.source + "\0" + left.kind + "\0" + left.name).localeCompare(right.source + "\0" + right.kind + "\0" + right.name); });
+    return {
+      schemaVersion: REPORT_SCHEMA_VERSION,
+      generator: REPORT_GENERATOR,
+      converterModule: loadedConverters ? loadedConverters.provenance : null,
+      readyForCutover: reports.every(function (report) { return report.readyForCutover; }),
+      summary: {
+        documents: reports.length,
+        readyDocuments: reports.filter(function (report) { return report.readyForCutover; }).length,
+        blockedDocuments: reports.filter(function (report) { return !report.readyForCutover; }).length,
+        unsupportedTotals: unsupportedTotals,
+        unsupportedByDocument: reports.filter(function (report) { return report.unsupportedContent.length; }).map(function (report, index) {
+          return { id: report.id == null ? String(index) : report.id, source: report.source, items: report.unsupportedContent };
+        })
+      },
+      reports: reports
+    };
+  }
+  if (!options.source) throw new TypeError("--source or --input is required");
+  var entry = { source: options.source };
+  if (options.config) entry.configFile = path.resolve(cwd, options.config);
+  if (options.content) entry.contentFile = path.resolve(cwd, options.content);
+  var report = resolveEntry(entry, cwd, 0, converters);
+  report.schemaVersion = REPORT_SCHEMA_VERSION;
+  report.generator = REPORT_GENERATOR;
+  report.converterModule = loadedConverters ? loadedConverters.provenance : null;
+  return report;
+}
+
+function run(argv, io) {
+  io = io || { cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr };
+  try {
+    var options = parseArgs(argv);
+    if (options.help) { io.stdout.write(usage() + "\n"); return 0; }
+    if (options.printSchema) {
+      if (Object.keys(options).some(function (key) { return key !== "allowBlockers" && key !== "printSchema"; }) || options.allowBlockers) throw new TypeError("--print-schema cannot be combined with report options");
+      io.stdout.write(fs.readFileSync(path.join(__dirname, "report-schema-v2.json"), "utf8").replace(/\s*$/, "\n"));
+      return 0;
+    }
+    if (options.validateReport) {
+      if (Object.keys(options).some(function (key) { return key !== "allowBlockers" && key !== "validateReport" && key !== "reportSha256" && key !== "baselineReport"; }) || options.allowBlockers) throw new TypeError("--validate-report cannot be combined with report-generation options");
+      var reportPath = path.resolve(io.cwd, options.validateReport), reportBytes, parsedReport;
+      try { reportBytes = fs.readFileSync(reportPath); }
+      catch (error) { throw new Error("Unable to read migration report at " + reportPath + ": " + error.message); }
+      var reportDigest = crypto.createHash("sha256").update(reportBytes).digest("hex");
+      if (options.reportSha256 != null) {
+        var expectedReportDigest = String(options.reportSha256).toLowerCase();
+        if (!/^[a-f0-9]{64}$/.test(expectedReportDigest)) throw new TypeError("--report-sha256 must be a 64-character hexadecimal SHA-256 digest");
+        if (reportDigest !== expectedReportDigest) throw new Error("Migration report SHA-256 mismatch; refusing to validate " + path.basename(reportPath));
+      }
+      try { parsedReport = JSON.parse(reportBytes.toString("utf8")); }
+      catch (error) { throw new Error("Unable to parse migration report JSON at " + reportPath + ": " + error.message); }
+      validateStoredReport(parsedReport);
+      var validationOutput = { valid: true, schemaVersion: parsedReport.schemaVersion, label: path.basename(options.validateReport), sha256: reportDigest, hashVerifiedBeforeValidation: options.reportSha256 != null };
+      if (options.baselineReport) {
+        var baselinePath = path.resolve(io.cwd, options.baselineReport), baselineReport = readJson(baselinePath, "baseline migration report");
+        validationOutput.comparison = compareStoredReports(baselineReport, parsedReport);
+      }
+      io.stdout.write(JSON.stringify(validationOutput) + "\n");
+      return validationOutput.comparison && !validationOutput.comparison.regressionFree ? 2 : 0;
+    }
+    if (options.reportSha256 || options.baselineReport) throw new TypeError((options.reportSha256 ? "--report-sha256" : "--baseline-report") + " requires --validate-report");
+    var output = createOutput(options, io.cwd);
+    var json = JSON.stringify(output, null, 2) + "\n";
+    if (options.output) fs.writeFileSync(path.resolve(io.cwd, options.output), json, "utf8");
+    else io.stdout.write(json);
+    return output.readyForCutover || options.allowBlockers ? 0 : 2;
+  } catch (error) {
+    io.stderr.write("rte-migration-report: " + error.message + "\n\n" + usage() + "\n");
+    return 1;
+  }
+}
+
+if (require.main === module) process.exitCode = run(process.argv.slice(2));
+
+module.exports = { REPORT_GENERATOR: REPORT_GENERATOR, REPORT_SCHEMA_VERSION: REPORT_SCHEMA_VERSION, compareStoredReports: compareStoredReports, createOutput: createOutput, loadConverters: loadConverters, parseArgs: parseArgs, run: run, usage: usage, validateStoredReport: validateStoredReport };

package/migration/index.d.ts

@@ -0,0 +1,18 @@
+export type MigrationSource = "tinymce" | "ckeditor" | "ckeditor5" | "froala" | "quill" | "tiptap" | "lexical";
+export interface MigrationConfigResult { source: string; config: Record<string, unknown>; mappedCommands: string[]; unmapped: string[]; warnings: string[]; }
+export interface UnsupportedContentItem { kind: "embed" | "node" | "mark"; name: string; count: number; paths: string[]; }
+export interface AppliedConverterItem { kind: "embed" | "node" | "mark"; name: string; count: number; paths: string[]; }
+export type MigrationConverterResult = string | { html: string; warnings?: string[] } | null | undefined;
+export type MigrationConverter = (value: unknown, context: { source: MigrationSource; kind: "embed" | "node" | "mark"; name: string; path?: string; html?: string; childrenHtml?: string; node?: unknown; operation?: unknown; attributes?: Record<string, unknown> }) => MigrationConverterResult;
+export interface MigrationConverters { quill?: { embeds?: Record<string, MigrationConverter> }; tiptap?: { nodes?: Record<string, MigrationConverter>; marks?: Record<string, MigrationConverter> }; lexical?: { nodes?: Record<string, MigrationConverter> }; }
+export interface MigrationOptions { converters?: MigrationConverters; }
+export interface MigrationContentResult { source: string; html: string; warnings: string[]; unsupportedContent: UnsupportedContentItem[]; appliedConverters: AppliedConverterItem[]; }
+export interface MigrationReport { source: string; readyForCutover: boolean; config: Record<string, unknown>; html: string; mappedCommands: string[]; unmapped: string[]; unsupportedContent: UnsupportedContentItem[]; appliedConverters: AppliedConverterItem[]; blockers: string[]; warnings: string[]; manualReview: string[]; }
+export declare const SOURCES: string[];
+export declare const COMMANDS: Record<string, string>;
+export declare function mapToolbar(value: unknown): { commands: string[]; unmapped: string[] };
+export declare function migrateConfig(source: MigrationSource, config: Record<string, unknown>): MigrationConfigResult;
+export declare function convertContent(source: MigrationSource, value: unknown, options?: MigrationOptions): MigrationContentResult;
+export declare function createMigrationReport(source: MigrationSource, options?: { config?: Record<string, unknown>; content?: unknown; converters?: MigrationConverters }): MigrationReport;
+export declare function readLegacyContent(source: MigrationSource, editor: unknown): unknown;
+export declare function migrateEditor(source: MigrationSource, legacyEditor: unknown, richTextEditor: { setHTMLCode(html: string): void }, options?: MigrationOptions): MigrationContentResult;