SPB Git

Repository Public

index.ts 15.3 KB 253 lines typescript

1/**2 * Sheet Document Schema — parsing, migration, stable serialisation, traversal and structured patches.3 * Pure functions, no I/O.4 */5import { z } from "zod";6import { BlockSchema, LeafBlockSchema, MetadataSchema, SCHEMA_VERSION, SheetSchema, SourceSchema, ClaimSchema, FORMATS, THEMES, Tone, Id, type Block, type LeafBlock, type Sheet } from "./sheet";78export * from "./sheet";910// ── Parsing and migration ───────────────────────────────────────────────────────────────────────────1112export interface Issue { path: string; message: string }13export type ParseResult = { ok: true; sheet: Sheet } | { ok: false; issues: Issue[] };1415const issuesOf = (e: z.ZodError): Issue[] => e.issues.slice(0, 60).map((i) => ({ path: i.path.join("."), message: i.message }));1617/**18 * Upgrades a stored document to the current schema version, one step at a time. Published documents are never19 * rewritten in the database: they are migrated when read. Add a step here whenever SCHEMA_VERSION is bumped.20 */21type Migration = (doc: Record<string, unknown>) => Record<string, unknown>;22const MIGRATIONS: Record<number, Migration> = {23  // 0 → 1: pre-release drafts had no explicit version and kept `claims` under `evidence`.24  0: (doc) => { const { evidence, ...rest } = doc as { evidence?: unknown }; return { ...rest, claims: (rest as { claims?: unknown }).claims ?? evidence ?? [], schemaVersion: 1 }; },25};2627export function migrateSheet(raw: unknown): unknown {28  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;29  let doc = raw as Record<string, unknown>;30  let v = typeof doc.schemaVersion === "number" ? doc.schemaVersion : 0;31  if (v > SCHEMA_VERSION) throw new Error(`Document schema version ${v} is newer than this server (${SCHEMA_VERSION})`);32  while (v < SCHEMA_VERSION) { const step = MIGRATIONS[v]; if (!step) throw new Error(`No migration from schema version ${v}`); doc = step(doc); v++; }33  return doc;34}3536/** Migrates then validates. The only way a document enters the system. */37export function parseSheet(raw: unknown): ParseResult {38  let migrated: unknown;39  try { migrated = migrateSheet(raw); } catch (e) { return { ok: false, issues: [{ path: "schemaVersion", message: (e as Error).message }] }; }40  const r = SheetSchema.safeParse(migrated);41  return r.success ? { ok: true, sheet: r.data } : { ok: false, issues: issuesOf(r.error) };42}4344export function mustParseSheet(raw: unknown): Sheet {45  const r = parseSheet(raw);46  if (!r.ok) throw new Error("Invalid sheet document: " + r.issues.map((i) => `${i.path}: ${i.message}`).join("; "));47  return r.sheet;48}4950/** Deterministic JSON: object keys sorted, so equal documents serialise to equal bytes (hashing, diffing, tests). */51export function stableStringify(value: unknown, space?: number): string {52  const sort = (v: unknown): unknown => {53    if (Array.isArray(v)) return v.map(sort);54    if (v && typeof v === "object") return Object.fromEntries(Object.keys(v as object).sort().map((k) => [k, sort((v as Record<string, unknown>)[k])]));55    return v;56  };57  return JSON.stringify(sort(value), null, space);58}5960/** Works in Node and in the browser (the editor creates blocks client-side). */61export const newId = (prefix = "b") => `${prefix}-${Array.from(globalThis.crypto.getRandomValues(new Uint8Array(4)), (x) => x.toString(16).padStart(2, "0")).join("")}`;6263export function emptySheet(locale: "fr" | "en", title: string): Sheet {64  return mustParseSheet({ schemaVersion: SCHEMA_VERSION, metadata: { title, locale }, blocks: [{ id: newId(), type: "heading", level: 1, text: title }] });65}6667// ── Traversal ───────────────────────────────────────────────────────────────────────────────────────6869/** Every block in reading order, tab contents included. */70export function allBlocks(doc: Sheet): (Block | LeafBlock)[] {71  const out: (Block | LeafBlock)[] = [];72  for (const b of doc.blocks) { out.push(b); if (b.type === "tabs") for (const t of b.tabs) out.push(...t.blocks); }73  return out;74}75export const findBlock = (doc: Sheet, id: string) => allBlocks(doc).find((b) => b.id === id);7677const stripInline = (s: string) => s.replace(/\[\^[a-z0-9-]+\]/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\$([^$]+)\$/g, "$1").replace(/[*`]/g, "");7879/** Plain text of a block: search index, reading time, alt-text fallbacks. */80export function blockText(b: Block | LeafBlock): string {81  const parts: (string | undefined)[] = [];82  switch (b.type) {83    case "heading": parts.push(b.eyebrow, b.text); break;84    case "paragraph": parts.push(b.text); break;85    case "list": parts.push(...b.items); break;86    case "equation": parts.push(b.label, b.explanation, ...(b.variables ?? []).map((v) => v.meaning)); break;87    case "callout": parts.push(b.title, b.text); break;88    case "table": parts.push(b.caption, ...b.columns.map((c) => c.label), ...b.rows.flat()); break;89    case "cards": parts.push(...b.items.flatMap((i) => [i.title, i.text])); break;90    case "steps": parts.push(...b.items.flatMap((i) => [i.title, i.text])); break;91    case "legend": parts.push(b.title, ...b.items.map((i) => i.label)); break;92    case "diagram": parts.push(b.title, b.caption, ...b.nodes.flatMap((n) => [n.label, n.sublabel]), ...b.edges.map((e) => e.label), ...(b.animation?.steps ?? []).flatMap((s) => [s.title, s.text])); break;93    case "timeline": parts.push(...b.items.flatMap((i) => [i.when, i.title, i.text])); break;94    case "matrix": parts.push(b.title, b.caption, ...b.rowLabels, ...b.colLabels); break;95    case "code": parts.push(b.caption); break;96    case "chart": parts.push(b.title, b.caption, b.x.label, b.y.label, ...b.series.map((s) => s.name)); break;97    case "svg": case "image": parts.push(b.caption); break;98    case "comparison": parts.push(b.caption, ...b.columns.map((c) => c.title), ...b.rows.flatMap((r) => [r.label, ...r.cells]), b.verdict); break;99    case "accordion": parts.push(...b.items.flatMap((i) => [i.title, i.text])); break;100    case "quiz": parts.push(b.question, ...b.choices.flatMap((c) => [c.text, c.explanation])); break;101    case "simulation": parts.push(b.title, b.caption); break;102    case "references": parts.push(b.title); break;103    case "tabs": parts.push(...b.tabs.map((t) => t.label)); break;104    case "divider": break;105  }106  parts.push(b.alt);107  return parts.filter(Boolean).map((p) => stripInline(p!)).join(" ");108}109110export function sheetText(doc: Sheet): string {111  return [doc.metadata.title, doc.metadata.summary, ...doc.metadata.objectives, ...allBlocks(doc).map(blockText)].filter(Boolean).join("\n");112}113114/** 220 words a minute, plus half a minute per visual or interactive block; at least one minute. */115export function readingMinutes(doc: Sheet): number {116  const words = sheetText(doc).split(/\s+/).filter(Boolean).length;117  const visuals = allBlocks(doc).filter((b) => ["diagram", "chart", "matrix", "simulation", "svg", "image", "equation"].includes(b.type)).length;118  return Math.max(1, Math.round(words / 220 + visuals * 0.5));119}120121export interface TocEntry { id: string; level: 1 | 2 | 3; text: string }122export const tableOfContents = (doc: Sheet): TocEntry[] =>123  doc.blocks.filter((b): b is Extract<Block, { type: "heading" }> => b.type === "heading" && b.level <= 2).map((b) => ({ id: b.id, level: b.level, text: stripInline(b.text) }));124125export function slugify(s: string): string {126  return s.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 96).replace(/-+$/, "") || "fiche";127}128129// ── Structured patches ──────────────────────────────────────────────────────────────────────────────130131/**132 * The only way the AI changes an existing sheet: a list of operations addressed by block id. Each operation is133 * validated; blocks that are not named keep their exact bytes. The same operations drive undo and the visual diff.134 */135export const PatchOpSchema = z.discriminatedUnion("op", [136  z.object({ op: z.literal("replace_block"), id: Id, block: BlockSchema }).strict(),137  z.object({ op: z.literal("insert_block"), block: BlockSchema, afterId: Id.nullable().describe("null inserts at the top"), tabId: Id.optional() }).strict(),138  z.object({ op: z.literal("remove_block"), id: Id }).strict(),139  z.object({ op: z.literal("move_block"), id: Id, afterId: Id.nullable() }).strict(),140  z.object({ op: z.literal("set_metadata"), metadata: MetadataSchema.partial().omit({ author: true }) }).strict(),141  z.object({ op: z.literal("set_theme"), preset: z.enum(THEMES).optional(), accent: Tone.optional(), format: z.enum(FORMATS).optional() }).strict(),142  z.object({ op: z.literal("upsert_source"), source: SourceSchema }).strict(),143  z.object({ op: z.literal("remove_source"), id: Id }).strict(),144  z.object({ op: z.literal("set_claims"), claims: z.array(ClaimSchema).max(60) }).strict(),145]);146export type PatchOp = z.infer<typeof PatchOpSchema>;147export const PatchSchema = z.array(PatchOpSchema).max(120);148149export class PatchError extends Error { constructor(public opIndex: number, message: string) { super(`op ${opIndex}: ${message}`); } }150151/** Applies a patch to a copy of the document and re-validates the result. Throws PatchError on the first bad op. */152export function applyPatch(doc: Sheet, ops: PatchOp[], opts: { respectLocks?: boolean } = {}): Sheet {153  const next = structuredClone(doc) as Sheet;154  // A block is protected when it is locked itself or contains a locked block (a tab group with a locked child).155  const locked = (id: string) => {156    if (opts.respectLocks === false) return false;157    const b = allBlocks(doc).find((x) => x.id === id);158    return b?.locked === true || (b?.type === "tabs" && b.tabs.some((t) => t.blocks.some((c) => c.locked)));159  };160  const locate = (id: string): { list: (Block | LeafBlock)[]; index: number } | null => {161    const i = next.blocks.findIndex((b) => b.id === id);162    if (i >= 0) return { list: next.blocks, index: i };163    for (const b of next.blocks) if (b.type === "tabs") for (const t of b.tabs) { const k = t.blocks.findIndex((c) => c.id === id); if (k >= 0) return { list: t.blocks, index: k }; }164    return null;165  };166  ops.forEach((op, n) => {167    switch (op.op) {168      case "replace_block": {169        const at = locate(op.id); if (!at) throw new PatchError(n, `unknown block ${op.id}`);170        if (locked(op.id)) throw new PatchError(n, `block ${op.id} is locked`);171        if (at.list !== next.blocks && op.block.type === "tabs") throw new PatchError(n, "tabs cannot be nested");172        at.list[at.index] = { ...op.block, id: op.id } as Block;173        break;174      }175      case "insert_block": {176        let list: (Block | LeafBlock)[] = next.blocks;177        if (op.tabId) {178          const tab = next.blocks.flatMap((b) => (b.type === "tabs" ? b.tabs : [])).find((t) => t.id === op.tabId);179          if (!tab) throw new PatchError(n, `unknown tab ${op.tabId}`);180          if (op.block.type === "tabs") throw new PatchError(n, "tabs cannot be nested");181          list = tab.blocks;182        }183        if (allBlocks(next).some((b) => b.id === op.block.id)) throw new PatchError(n, `block id ${op.block.id} already exists`);184        if (op.afterId === null) list.unshift(op.block as LeafBlock);185        else {186          const i = list.findIndex((b) => b.id === op.afterId);187          if (i < 0) throw new PatchError(n, `unknown block ${op.afterId} in the target list`);188          list.splice(i + 1, 0, op.block as LeafBlock);189        }190        break;191      }192      case "remove_block": {193        const at = locate(op.id); if (!at) throw new PatchError(n, `unknown block ${op.id}`);194        if (locked(op.id)) throw new PatchError(n, `block ${op.id} is locked`);195        at.list.splice(at.index, 1);196        break;197      }198      case "move_block": {199        const i = next.blocks.findIndex((b) => b.id === op.id);200        if (i < 0) throw new PatchError(n, `unknown top-level block ${op.id}`);201        if (locked(op.id)) throw new PatchError(n, `block ${op.id} is locked`);202        const [b] = next.blocks.splice(i, 1);203        if (op.afterId === null) next.blocks.unshift(b);204        else { const k = next.blocks.findIndex((x) => x.id === op.afterId); if (k < 0) throw new PatchError(n, `unknown block ${op.afterId}`); next.blocks.splice(k + 1, 0, b); }205        break;206      }207      case "set_metadata": Object.assign(next.metadata, op.metadata); break;208      case "set_theme":209        if (op.preset) next.theme.preset = op.preset;210        if (op.accent) next.theme.accent = op.accent;211        if (op.format) next.layout.format = op.format;212        break;213      case "upsert_source": { const i = next.sources.findIndex((s) => s.id === op.source.id); if (i >= 0) next.sources[i] = op.source; else next.sources.push(op.source); break; }214      case "remove_source": {215        next.sources = next.sources.filter((s) => s.id !== op.id);216        for (const b of allBlocks(next)) if (b.sourceIds) b.sourceIds = b.sourceIds.filter((s) => s !== op.id);217        for (const c of next.claims) c.sourceIds = c.sourceIds.filter((s) => s !== op.id);218        break;219      }220      case "set_claims": next.claims = op.claims; break;221    }222  });223  const r = SheetSchema.safeParse(next);224  if (!r.success) throw new PatchError(ops.length, "result is not a valid sheet: " + issuesOf(r.error).map((i) => `${i.path}: ${i.message}`).join("; "));225  return r.data;226}227228// ── Diff ────────────────────────────────────────────────────────────────────────────────────────────229230export interface SheetDiff {231  added: string[]; removed: string[]; changed: string[]; moved: string[];232  metadata: string[]; theme: boolean; sources: boolean; claims: boolean;233}234235/** Block-level difference between two versions: what the revision history and the AI panel show. */236export function diffSheets(a: Sheet, b: Sheet): SheetDiff {237  const A = new Map(allBlocks(a).map((x) => [x.id, stableStringify(x)])), B = new Map(allBlocks(b).map((x) => [x.id, stableStringify(x)]));238  const added = [...B.keys()].filter((k) => !A.has(k)), removed = [...A.keys()].filter((k) => !B.has(k));239  const changed = [...B.keys()].filter((k) => A.has(k) && A.get(k) !== B.get(k));240  const orderA = a.blocks.map((x) => x.id).filter((k) => B.has(k)), orderB = b.blocks.map((x) => x.id).filter((k) => A.has(k));241  const moved = orderB.filter((k, i) => orderA[i] !== k);242  const metadata = (Object.keys({ ...a.metadata, ...b.metadata }) as (keyof Sheet["metadata"])[]).filter((k) => stableStringify(a.metadata[k]) !== stableStringify(b.metadata[k]));243  return {244    added, removed, changed, moved, metadata,245    theme: stableStringify([a.theme, a.layout]) !== stableStringify([b.theme, b.layout]),246    sources: stableStringify(a.sources) !== stableStringify(b.sources),247    claims: stableStringify(a.claims) !== stableStringify(b.claims),248  };249}250export const diffIsEmpty = (d: SheetDiff) => !d.added.length && !d.removed.length && !d.changed.length && !d.moved.length && !d.metadata.length && !d.theme && !d.sources && !d.claims;251252export { LeafBlockSchema };253
Files main
Menu

Theme