@jxsuite/schema 3.0.0 → 4.1.0

package/src/doc-ops.ts

@@ -15,18 +15,19 @@
  * @module @jxsuite/schema/doc-ops
  */
 
-import type { JxMutableNode, JxPath } from "../types.ts";
+import { isNonNullObject, isNumber, isString } from "./guards";
+import type { JsonValue, JxDocumentValue, JxMutableNode, JxPath } from "../types.ts";
 
 /** Value-carrying document mutation, replayable in either direction. */
 export type JxDocOp =
   /** Set (or delete, when value is undefined) a key on the node at path. */
-  | { op: "set-key"; path: JxPath; key: string; value?: unknown }
+  | { op: "set-key"; path: JxPath; key: string; value?: JxDocumentValue | undefined }
   /** Insert a node at parentPath.children[index]. */
-  | { op: "insert-child"; parentPath: JxPath; index: number; node: unknown }
+  | { op: "insert-child"; parentPath: JxPath; index: number; node: JxMutableNode | string }
   /** Remove parentPath.children[index]. */
   | { op: "remove-child"; parentPath: JxPath; index: number }
   /** Replace parentPath.children[index] with node. */
-  | { op: "set-child"; parentPath: JxPath; index: number; node: unknown }
+  | { op: "set-child"; parentPath: JxPath; index: number; node: JxMutableNode | string }
   /** Raw two-splice move: remove fromParent.children[fromIndex], insert at toParent[toIndex]. */
   | {
       op: "move-child";
@@ -43,27 +44,34 @@ export interface JxDocOpPair {
 
 /** JSON round-trip clone — also normalizes away reactive proxies / functions / undefined. */
 function jsonClone<T>(value: T): T {
+  /* SAFETY: every value cloned here is document data (a node, a children member, or a key's value),
+     which is JSON by contract; the round trip reproduces that shape and drops only functions and
+     `undefined` members, which the document types already treat as absent. */
   // oxlint-disable-next-line unicorn/prefer-structured-clone -- structuredClone throws on reactive proxies; JSON normalization is the point
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
 /** Deep-clone a recorded value (undefined/null pass through; reactive proxies are read through). */
 export function cloneValue<T>(v: T): T {
-  return v === undefined || v === null ? v : (jsonClone(v as object) as T);
+  return v === undefined || v === null ? v : jsonClone(v);
 }
 
 /**
- * Walk a plain document tree by path. Paths address nodes by construction; missing segments and
- * non-node leaves surface as undefined (typed as node for caller ergonomics, matching Studio's
- * historical helper).
+ * Walk a plain document tree by path. Paths address nodes by construction; a missing segment
+ * surfaces as undefined, so every caller checks the answer before treating it as a node.
  */
-export function getNodeAtPath(doc: JxMutableNode, path: JxPath): JxMutableNode {
-  let node = doc;
+export function getNodeAtPath(doc: JxMutableNode, path: JxPath): JxMutableNode | undefined {
+  let node: JxMutableNode | undefined = doc;
   for (const key of path) {
+    // `== null` also stops at a JSON `null` partway down the path.
     if (node == null) {
-      return undefined as unknown as JxMutableNode;
+      return undefined;
     }
-    node = node[key] as JxMutableNode;
+    /* SAFETY: a `JxPath` alternates node keys with a "children" key and an index, so each step
+       lands on a node, on a children array (whose only use is the next, numeric, lookup, which an
+       array answers as a node would), or on nothing. A path that wrongly ends on a string child or a
+       children array reaches a caller as one; `childArray` and `insertableChildren` refuse it. */
+    node = node[key] as JxMutableNode | undefined;
   }
   return node;
 }
@@ -90,44 +98,40 @@ export function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
  * aliases the op object. Throws (with a machine-readable reason) when a target path is missing.
  */
 export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
+  // Read before the switch: an op from outside may carry a kind the union does not name.
+  const { op: kind } = op;
   switch (op.op) {
     case "set-key": {
       const node = getNodeAtPath(doc, op.path);
       if (!node) {
         throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
       }
-      const target = node as Record<string, unknown>;
       if (op.value === undefined) {
-        delete target[op.key];
+        delete node[op.key];
       } else {
-        target[op.key] = cloneValue(op.value);
+        node[op.key] = cloneValue(op.value);
       }
       return;
     }
     case "insert-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 0, cloneValue(op.node) as JxMutableNode);
+      childArrayAt(doc, op.parentPath).splice(op.index, 0, cloneValue(op.node));
       return;
     }
     case "remove-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1);
+      childArrayAt(doc, op.parentPath).splice(op.index, 1);
       return;
     }
     case "set-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1, cloneValue(op.node) as JxMutableNode);
+      childArrayAt(doc, op.parentPath).splice(op.index, 1, cloneValue(op.node));
       return;
     }
     case "move-child": {
       assertNotIntoOwnSubtree(op);
-      const fromParent = getNodeAtPath(doc, op.fromParentPath);
-      const toParent = getNodeAtPath(doc, op.toParentPath);
       /* Both arrays are resolved BEFORE the source is spliced, so a move whose target cannot receive
          children throws with the document untouched rather than having detached the node it could
          not place. */
-      const from = childArray(fromParent);
-      const to = childArray(toParent);
+      const from = childArrayAt(doc, op.fromParentPath);
+      const to = childArrayAt(doc, op.toParentPath);
       const [node] = from.splice(op.fromIndex, 1);
       to.splice(op.toIndex, 0, node!);
       return;
@@ -136,7 +140,19 @@ export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
       break;
     }
   }
-  throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+  throw new Error(`unknown-doc-op:${kind}`);
+}
+
+/**
+ * The children array of the node at `parentPath`, lazily created (see {@link childArray}); throws a
+ * `TypeError` naming the path when no node is there.
+ */
+function childArrayAt(doc: JxMutableNode, parentPath: JxPath): (JxMutableNode | string)[] {
+  const parent = getNodeAtPath(doc, parentPath);
+  if (parent == null) {
+    throw new TypeError(`doc-op-node-not-found:${parentPath.join("/")}`);
+  }
+  return childArray(parent);
 }
 
 /**
@@ -145,8 +161,15 @@ export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
  * insertion (delta +1, inclusive) shifts them up. Returns `path` unchanged when the splice does not
  * affect it — including when `path` IS `parentPath`, since a splice moves a node's children, never
  * the node.
+ *
+ * @param {JxPath} parentPath - The node whose children were spliced
+ * @param {JxPath} path - The path to translate
+ * @param {number} spliceIndex - Where the splice happened
+ * @param {number} delta - -1 for a removal, +1 for an insertion
+ * @param {boolean} inclusive - Whether a path AT the index shifts (an insertion's rule)
+ * @returns {JxPath}
  */
-function shiftThroughSplice(
+export function shiftPrefixedIndex(
   parentPath: JxPath,
   path: JxPath,
   spliceIndex: number,
@@ -155,10 +178,10 @@ function shiftThroughSplice(
 ): JxPath {
   const depth = parentPath.length;
   const isProperPrefix = depth < path.length && parentPath.every((seg, i) => seg === path[i]);
-  if (!isProperPrefix || path[depth] !== "children" || typeof path[depth + 1] !== "number") {
+  const index = path[depth + 1];
+  if (!isProperPrefix || path[depth] !== "children" || !isNumber(index)) {
     return path;
   }
-  const index = path[depth + 1] as number;
   if (inclusive ? index < spliceIndex : index <= spliceIndex) {
     return path;
   }
@@ -185,7 +208,7 @@ function assertNotIntoOwnSubtree(op: Extract<JxDocOp, { op: "move-child" }>): vo
  * counts from the end and an index past the end appends. The applier inserts with `splice`, so an
  * inverse must name the slot the node really landed in, not the one the op asked for.
  */
-function insertionSlot(index: number, length: number): number {
+export function insertionSlot(index: number, length: number): number {
   return index < 0 ? Math.max(length + index, 0) : Math.min(index, length);
 }
 
@@ -218,13 +241,21 @@ function insertionSlot(index: number, length: number): number {
  * @returns {JxDocOp}
  */
 export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
+  // Read before the switch: an op from outside may carry a kind the union does not name.
+  const { op: kind } = op;
+  assertIntegerIndexes(op);
   switch (op.op) {
     case "set-key": {
       const node = getNodeAtPath(doc, op.path);
-      if (!node) {
+      if (node === undefined) {
         throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
       }
-      const before = cloneValue((node as Record<string, unknown>)[op.key]);
+      /* A key set on a text child or a children array lands nowhere a renderer reads, so the edit
+         would succeed without effect; on `null` it would throw mid-transaction. */
+      if (!isNonNullObject(node) || Array.isArray(node)) {
+        throw new TypeError(`doc-op-not-a-node:${op.path.join("/")}`);
+      }
+      const before = cloneValue(node[op.key]);
       return before === undefined
         ? { key: op.key, op: "set-key", path: op.path }
         : { key: op.key, op: "set-key", path: op.path, value: before };
@@ -255,7 +286,7 @@ export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
       return {
         fromIndex: toIndex,
         // The removal shifted paths under the source parent; the insertion, under the target.
-        fromParentPath: shiftThroughSplice(
+        fromParentPath: shiftPrefixedIndex(
           op.fromParentPath,
           op.toParentPath,
           op.fromIndex,
@@ -264,14 +295,34 @@ export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
         ),
         op: "move-child",
         toIndex: op.fromIndex,
-        toParentPath: shiftThroughSplice(op.toParentPath, op.fromParentPath, toIndex, 1, true),
+        toParentPath: shiftPrefixedIndex(op.toParentPath, op.fromParentPath, toIndex, 1, true),
       };
     }
     default: {
       break;
     }
   }
-  throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+  throw new Error(`unknown-doc-op:${kind}`);
+}
+
+/**
+ * Throw `doc-op-index:<path>` unless every index the op carries is an integer. A numeric string, a
+ * fraction or `NaN` would reach `splice`, which coerces or truncates it, so the op would land in a
+ * slot its recorded inverse does not name. Producers coerce canonical numeric strings before they
+ * build an op; this is the defence behind them.
+ */
+function assertIntegerIndexes(op: JxDocOp): void {
+  const indexes: [JxPath, unknown][] = [];
+  if (op.op === "move-child") {
+    indexes.push([op.fromParentPath, op.fromIndex], [op.toParentPath, op.toIndex]);
+  } else if (op.op === "insert-child" || op.op === "remove-child" || op.op === "set-child") {
+    indexes.push([op.parentPath, op.index]);
+  }
+  for (const [parentPath, index] of indexes) {
+    if (!Number.isInteger(index)) {
+      throw new TypeError(`doc-op-index:${[...parentPath, "children", String(index)].join("/")}`);
+    }
+  }
 }
 
 /** The node's existing children array, or null when it has none (or is not a node). */
@@ -292,10 +343,15 @@ function assertIndex(
 }
 
 /** A clone of `parentPath`'s child at `index`, or the applier's reason when there is none. */
-function existingChild(doc: JxMutableNode, parentPath: JxPath, index: number): unknown {
+function existingChild(
+  doc: JxMutableNode,
+  parentPath: JxPath,
+  index: number,
+): JxMutableNode | string {
   const children = childrenAt(doc, parentPath);
   assertIndex(children, parentPath, index);
-  return cloneValue(children[index]);
+  // `assertIndex` has just proven `index` is in range.
+  return cloneValue(children[index]!);
 }
 
 /**
@@ -304,8 +360,9 @@ function existingChild(doc: JxMutableNode, parentPath: JxPath, index: number): u
  * children array addressed as if it were a node, or a mapped-array `children`.
  */
 function insertableChildren(doc: JxMutableNode, parentPath: JxPath): (JxMutableNode | string)[] {
-  const node = getNodeAtPath(doc, parentPath) as unknown as { children?: unknown } | null;
-  if (!node || typeof node !== "object" || Array.isArray(node)) {
+  const node = getNodeAtPath(doc, parentPath);
+  // A path that ends on a string child or a children array is refused here, not just a missing one.
+  if (!isNonNullObject(node) || Array.isArray(node)) {
     throw new Error(`doc-op-node-not-found:${parentPath.join("/")}`);
   }
   if (node.children === undefined) {
@@ -314,7 +371,7 @@ function insertableChildren(doc: JxMutableNode, parentPath: JxPath): (JxMutableN
   if (!Array.isArray(node.children)) {
     throw new TypeError(`doc-op-mapped-children:${parentPath.join("/")}`);
   }
-  return node.children as (JxMutableNode | string)[];
+  return node.children;
 }
 
 /**
@@ -346,3 +403,197 @@ export function applyDocOpsWithInverse(doc: JxMutableNode, ops: readonly JxDocOp
   }
   return pairs;
 }
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+/**
+ * Whether `path` is an ancestor of (or equal to) `descendant`.
+ *
+ * @param {JxPath} path
+ * @param {JxPath} descendant
+ * @returns {boolean}
+ */
+export function isAncestor(path: JxPath, descendant: JxPath): boolean {
+  if (path.length > descendant.length) {
+    return false;
+  }
+  return path.every((v, i) => v === descendant[i]);
+}
+
+/**
+ * Order two paths the way the document reads: parents before children, siblings by index.
+ *
+ * Segments are compared pairwise; numbers numerically (so `children/10` follows `children/9`), and
+ * anything else by string order. A prefix sorts before what extends it.
+ *
+ * @param {JxPath} a
+ * @param {JxPath} b
+ * @returns {number}
+ */
+export function comparePaths(a: JxPath, b: JxPath): number {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const x = a[i]!;
+    const y = b[i]!;
+    if (x === y) {
+      continue;
+    }
+    if (isNumber(x) && isNumber(y)) {
+      return x - y;
+    }
+    return String(x) < String(y) ? -1 : 1;
+  }
+  return a.length - b.length;
+}
+
+/**
+ * Drop any path whose ancestor is also in the list.
+ *
+ * Deleting a `<section>` and one of its own paragraphs is one deletion, not two: the paragraph goes
+ * with its parent, and a second splice into coordinates that no longer exist is how a batch
+ * corrupts a document.
+ *
+ * @param {readonly JxPath[]} paths
+ * @returns {JxPath[]}
+ */
+export function topLevelSelection(paths: readonly JxPath[]): JxPath[] {
+  const top: JxPath[] = [];
+  for (const path of paths) {
+    if (!paths.some((q) => !samePath(q, path) && isAncestor(q, path))) {
+      top.push([...path]);
+    }
+  }
+  return top;
+}
+
+function samePath(a: JxPath, b: JxPath): boolean {
+  return a.length === b.length && isAncestor(a, b);
+}
+
+/** Where a structural verb splices: the parent element's path and the index in its children. */
+export interface SpliceCoordinate {
+  parentPath: JxPath;
+  index: number;
+}
+
+/**
+ * The splice coordinate `path` names, or `null` for no path and for every path
+ * {@link isSpliceablePath} refuses.
+ *
+ * @param {JxPath | null | undefined} path
+ * @returns {SpliceCoordinate | null}
+ */
+export function spliceCoordinate(path: JxPath | null | undefined): SpliceCoordinate | null {
+  const index = path?.at(-1);
+  return path && path.at(-2) === "children" && isNumber(index)
+    ? { index, parentPath: path.slice(0, -2) }
+    : null;
+}
+
+/**
+ * Whether `path` names a position a structural edit can splice: a tail of `"children"` + index.
+ *
+ * Every structural edit reaches its parent by dropping the last two segments and its position by
+ * taking the last. That produces a splice coordinate for exactly one path shape, and a document
+ * holds three others a caller can name: the document element (`[]`), a repeater's map template
+ * (`[…, "children", "map"]`) and a `$switch` case (`[…, "cases", "warn"]`). For the template, the
+ * parent resolves to a children ARRAY, so the splice throws mid-edit; for a case it splices at
+ * `NaN` and takes the wrong child.
+ *
+ * @param {JxPath} path
+ * @returns {boolean}
+ */
+export function isSpliceablePath(path: JxPath): boolean {
+  return spliceCoordinate(path) !== null;
+}
+
+/**
+ * The order a structural batch must run in: contained paths dropped, unspliceable paths dropped,
+ * then LAST node first.
+ *
+ * Descending document order is what makes a loop of splices safe. Removing or duplicating at index
+ * `n` renumbers every sibling after `n`, so a batch that starts at the end never touches a
+ * coordinate a later step still needs.
+ *
+ * Containment is decided BEFORE spliceability, on the paths as given: a repeater template still
+ * shadows its own descendants, so naming the template and something inside it yields nothing rather
+ * than quietly deleting the child nobody pointed at.
+ *
+ * @param {readonly JxPath[]} paths
+ * @returns {JxPath[]} Deepest/last first, every entry a splice coordinate.
+ */
+export function structuralBatch(paths: readonly JxPath[]): JxPath[] {
+  return topLevelSelection(paths)
+    .filter((path) => isSpliceablePath(path))
+    .toSorted((a, b) => comparePaths(b, a));
+}
+
+/**
+ * An index written as JSON a model or a form produced, as the integer it names: an integer passes,
+ * a canonical decimal string (`"0"`, `"12"`, never `"01"`, `"1.0"` or `" 2"`) becomes its number,
+ * and anything else is `null`. Negative integers pass; whether one is meaningful is the caller's.
+ *
+ * @param {JsonValue | undefined} value - A tool argument or form field, as parsed JSON
+ * @returns {number | null}
+ */
+export function coerceIndex(value: JsonValue | undefined): number | null {
+  if (isNumber(value) && Number.isInteger(value)) {
+    return value;
+  }
+  return isString(value) && /^(?:0|[1-9]\d*)$/.test(value) ? Number(value) : null;
+}
+
+/** A move's forward and inverse ops, both `move-child`. */
+export interface PlannedMove {
+  forward: Extract<JxDocOp, { op: "move-child" }>;
+  inverse: Extract<JxDocOp, { op: "move-child" }>;
+}
+
+/**
+ * The ops that move the node at `fromPath` to `toIndex` of `toParentPath`'s children, without
+ * moving anything; null when the move cannot happen (the source is no child in a static children
+ * array, or the target is no node).
+ *
+ * `toIndex` is read as the slot in the target's children BEFORE the move, the way a drop indicator
+ * names it, so a move later in the same parent lands one earlier once the source is gone. A slot
+ * past the end is clamped to the last one, so the forward names where the node really lands. Throws
+ * `doc-op-move-into-self` when the target is inside the moved node.
+ *
+ * @param {JxMutableNode} doc - The document the move applies to
+ * @param {JxPath} fromPath
+ * @param {JxPath} toParentPath
+ * @param {number} toIndex
+ * @returns {PlannedMove | null}
+ */
+export function planMove(
+  doc: JxMutableNode,
+  fromPath: JxPath,
+  toParentPath: JxPath,
+  toIndex: number,
+): PlannedMove | null {
+  const at = spliceCoordinate(fromPath);
+  const fromParent = at && getNodeAtPath(doc, at.parentPath);
+  const toParent = getNodeAtPath(doc, toParentPath);
+  if (!at || !fromParent || !Array.isArray(fromParent.children) || !toParent) {
+    return null;
+  }
+  if (fromParent.children[at.index] === undefined) {
+    return null;
+  }
+  const sameParent = fromParent === toParent;
+  const adjusted = sameParent && at.index < toIndex ? toIndex - 1 : toIndex;
+  const targetLength = Array.isArray(toParent.children) ? toParent.children.length : 0;
+  const forward: PlannedMove["forward"] = {
+    fromIndex: at.index,
+    fromParentPath: at.parentPath,
+    op: "move-child",
+    toIndex: insertionSlot(adjusted, targetLength - (sameParent ? 1 : 0)),
+    toParentPath,
+  };
+  /* Computed against the document the move applies to. The inverse runs against the post-move
+     document, so `inverseOf` writes both of its parent paths in post-move coordinates: the removal
+     shifted paths under the source parent, the insertion paths under the target. */
+  const inverse = inverseOf(doc, forward);
+  /* SAFETY: `inverseOf` answers a `move-child` for a `move-child`. */
+  return { forward, inverse: inverse as PlannedMove["inverse"] };
+}

package/src/extension-registry.ts

@@ -11,8 +11,10 @@
  * format-dispatch view reuses FormatRegistry (including its extension/capability conflict checks).
  */
 
-import { FormatEntry, FormatRegistry } from "./format-registry";
+import { FormatEntry, FormatRegistry, classDefFrom } from "./format-registry";
 import type { FormatHostIO } from "./format-registry";
+import { isJsonObject, isString } from "./guards";
+import type { JsonObject, JsonValue } from "../types";
 
 export type {
   CapabilityInfo,
@@ -240,18 +242,23 @@ async function loadExtension(
     }
   }
 
-  let manifest: ExtensionManifest;
+  let loaded: JsonValue;
   try {
-    manifest = (await io.loadJson(manifestPath)) as unknown as ExtensionManifest;
+    loaded = await io.loadJson(manifestPath);
   } catch (error) {
     throw new Error(
       `Extension "${specifier}": cannot read manifest ${manifestPath}: ${errorMessage(error)}`,
       { cause: error },
     );
   }
-  if (!manifest || typeof manifest !== "object" || typeof manifest.name !== "string") {
+  if (!isJsonObject(loaded) || !isString(loaded.name)) {
     throw new Error(`Extension "${specifier}": ${EXTENSION_MANIFEST} must declare a "name"`);
   }
+  /* SAFETY: `name` was just checked to be a string. The other members are the shapes
+     extension-manifest.schema.json declares (string `title`/`description`, a `classes` map of
+     paths, a `schemas` record of paths), which every first-party extension's manifest test
+     validates its manifest against; this module resolves only the paths. */
+  const manifest: ExtensionManifest = loaded as JsonObject & ExtensionManifest;
   if (!specifier.startsWith(".") && manifest.name !== specifier) {
     throw new Error(
       `Extension "${specifier}": manifest name "${manifest.name}" does not match the specifier`,
@@ -261,7 +268,7 @@ async function loadExtension(
   const classes: FormatEntry[] = [];
   for (const [name, ref] of Object.entries(manifest.classes ?? {})) {
     const classPath = io.resolvePath(manifestPath, ref);
-    let classDef: Record<string, unknown>;
+    let classDef: JsonValue;
     try {
       classDef = await io.loadJson(classPath);
     } catch (error) {
@@ -270,7 +277,7 @@ async function loadExtension(
         { cause: error },
       );
     }
-    classes.push(new FormatEntry(name, classPath, classDef, io));
+    classes.push(new FormatEntry(name, classPath, classDefFrom(classDef), io));
   }
 
   const schemas: ExtensionInfo["schemas"] = {};
@@ -287,6 +294,6 @@ async function loadExtension(
   return { specifier, manifestPath, manifest, classes, schemas };
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function errorMessage(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
 }