Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

11.6 KB
Raw Blame
#!/usr/bin/env node
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// bento/dash document model rig.
//
//   node scripts/test-dash-model.ts        (Node ≥ 23.6 strips types natively)
//
// WHAT THIS PROVES. The format is permanent — additive forever, with no server
// to migrate a single file (PLATFORM §3) — so the two ways it can be got wrong
// are both unrecoverable once files exist:
//
//   1. LOSS ON READ. A field, a per-node key or a transform op this build does
//      not recognise must survive parse → serialize. An older build meeting a
//      future op keeps it; it does not quietly drop it and then save the
//      result over the user's file.
//   2. THE STARTER OVER LIVE DATA. `parseDoc` returning null let spaces' caller
//      fall back to the starter, so opening a slides file gave you an empty
//      document over real content and the first ⌘S made it permanent. Only an
//      ABSENT or EMPTY block may reach the starter. Everything else refuses and
//      says what it found.
//
// Both are checked from both sides: the rig asserts the good case AND that a
// naive implementation (reconstruct-the-known-fields; return null on failure)
// would fail these very assertions.

import {
  FORMAT, FORMAT_VERSION, parseDoc, docBytes, rowCount, docBudget,
  DOC_BUDGET_FSA, DOC_BUDGET_DOWNLOAD,
  type DashDoc,
} from '../dash/src/model.ts'

let failures = 0
let checks = 0
function ok(cond: boolean, msg: string) {
  checks++
  if (!cond) { failures++; console.log(`  FAIL  ${msg}`) }
  else console.log(`  ok    ${msg}`)
}

const minimal = () => ({
  format: FORMAT,
  version: FORMAT_VERSION,
  policy: 'bento-dash-1',
  docId: 'doc-test',
  title: 'test',
  sheets: [{
    id: 'sh1', name: 'Sheet 1', kind: 'table',
    rids: [[1, 3]],
    columns: [{ id: 'c1', name: 'Region', type: 'text' }],
    data: { c1: { enc: 'dict', dict: ['North', 'South'], idx: [0, 1, 0] } },
    steps: [{ op: 'import', from: 'q3.csv', at: '2026-08-03T00:00:00Z', rows: 3 }],
  }],
})

// ---------------------------------------------------------------- the states
ok(parseDoc('').ok === false && (parseDoc('') as any).err === 'empty',
  'an empty block is err:"empty" — the ONLY state that may boot the starter')
ok((parseDoc('   ') as any).err === 'empty', 'whitespace is empty too')
ok((parseDoc('{oops') as any).err === 'json', 'malformed JSON is err:"json", not empty')
ok((parseDoc('[]') as any).err === 'shape', 'a JSON array is err:"shape", not empty')
ok((parseDoc('{"format":"bento/slides","slides":[]}') as any).err === 'format',
  'a slides document is err:"format", not empty')
ok((parseDoc('{"format":"bento/slides","slides":[]}') as any).found === 'bento/slides',
  'the format failure reports what it actually found, so the gate can name it')
ok((parseDoc(JSON.stringify({ format: FORMAT, version: 1, docId: 'd', title: 't' })) as any).err === 'shape',
  'a bento/dash document with no sheets array is err:"shape"')
ok(parseDoc(JSON.stringify(minimal())).ok === true, 'a well-formed document parses')

// THE POINT OF THE TYPE: every failure is distinguishable from 'empty'.
const failures_ = ['{oops', '[]', '{"format":"bento/slides"}', '{"format":"bento/dash","version":1}']
ok(failures_.every((j) => { const r = parseDoc(j) as any; return r.ok === false && r.err !== 'empty' }),
  'NO malformed input is ever reported as empty — the starter is unreachable from a parse failure')

// The tag the kernel cannot produce: present-but-unreadable is not empty.
// (kernel readEmbeddedDoc collapses both to null; the boot site must distinguish.)
type PR = ReturnType<typeof parseDoc>
const unreadable: PR = { ok: false, err: 'unreadable', detail: 'block present, body unreadable' }
ok(unreadable.ok === false && unreadable.err === 'unreadable',
  'the ParseResult type can express "present but unreadable" as distinct from "empty"')

// ------------------------------------------------------------- additivity
const exotic = {
  ...minimal(),
  futureTopLevel: { anything: [1, 2, 3] },
  sheets: [{
    ...minimal().sheets[0],
    futureSheetKey: 'kept',
    columns: [{ id: 'c1', name: 'Region', type: 'text', futureColumnKey: 42 }],
    steps: [
      { op: 'import', from: 'q3.csv', at: '2026-08-03T00:00:00Z' },
      { op: 'kanban-pivot', mystery: true, nested: { deep: ['x'] } },
    ],
  }],
}
const parsedExotic = parseDoc(JSON.stringify(exotic))
ok(parsedExotic.ok === true, 'a document carrying unknown fields and an unknown op still parses')
if (parsedExotic.ok) {
  const d = parsedExotic.doc as any
  ok(d.futureTopLevel?.anything?.length === 3, 'an unknown TOP-LEVEL field survives')
  ok(d.sheets[0].futureSheetKey === 'kept', 'an unknown SHEET field survives')
  ok(d.sheets[0].columns[0].futureColumnKey === 42, 'an unknown COLUMN field survives')
  ok(d.sheets[0].steps[1].op === 'kanban-pivot' && d.sheets[0].steps[1].nested.deep[0] === 'x',
    'an unknown transform OP survives whole, including nested values')
  // the assertion a reconstruct-the-known-fields parser fails
  ok(JSON.stringify(d) === JSON.stringify({ ...exotic, format: FORMAT, version: FORMAT_VERSION }),
    'parse → serialize is byte-identical for a document with nothing to repair')
}

// ------------------------------------------------------------------ frozen
const futureVersion = parseDoc(JSON.stringify({ ...minimal(), version: FORMAT_VERSION + 1 }))
ok(futureVersion.ok === true && futureVersion.frozen === 'version',
  'a future version OPENS, frozen — it does not refuse')
const futurePolicy = parseDoc(JSON.stringify({ ...minimal(), policy: 'bento-dash-2' }))
ok(futurePolicy.ok === true && futurePolicy.frozen === 'policy', 'an unknown policy opens frozen')
const both = parseDoc(JSON.stringify({ ...minimal(), version: 9, policy: 'bento-dash-9' }))
ok(both.ok === true && both.frozen === 'version', 'version wins when both are unknown')

// A frozen document is never rewritten, not even a duplicate id: the file
// declares rules this build does not have, so it round-trips byte-exact.
const dupFrozen = parseDoc(JSON.stringify({
  ...minimal(), version: 9,
  sheets: [{ ...minimal().sheets[0], id: 'same' }, { ...minimal().sheets[0], id: 'same' }],
}))
ok(dupFrozen.ok === true && dupFrozen.repairs.length === 0,
  'a FROZEN document repairs nothing, even a duplicate id')

// -------------------------------------------------------------- id repair
const dup = JSON.stringify({
  ...minimal(),
  sheets: [{ ...minimal().sheets[0], id: 'same' }, { ...minimal().sheets[0], id: 'same' }],
})
const r1 = parseDoc(dup)
const r2 = parseDoc(dup)
ok(r1.ok === true && r1.repairs.length === 1, 'a duplicate sheet id is repaired, and reported')
ok(r1.ok === true && r2.ok === true
  && JSON.stringify(r1.repairs) === JSON.stringify(r2.repairs),
  'repair is DETERMINISTIC — two readers of one file produce the same ids')
if (r1.ok && r2.ok) {
  ok((r1.doc.sheets[1] as any).id === (r2.doc.sheets[1] as any).id,
    'and therefore two readers agree on what the repaired sheet is called')
  ok((r1.doc.sheets[0] as any).id === 'same', 'the FIRST claimant keeps the id')
}
const missing = parseDoc(JSON.stringify({
  ...minimal(), sheets: [{ ...minimal().sheets[0], id: undefined }],
}))
ok(missing.ok === true && missing.repairs[0]?.what === 'missing-id',
  'a missing id is repaired and reported as missing, not as a duplicate')

// ------------------------------------------- column ids are SHEET-scoped
// Two sheets may both call a column `c1`. Sharing a namespace would rename the
// second, and a renamed column orphans its own data — measured: the column kept
// the new id, `data` kept the old key, and the column rendered EMPTY.
const twoSheets = (id: string) => ({
  id, name: 'S', kind: 'table', rids: [[1, 2]],
  columns: [{ id: 'c1', name: 'Region', type: 'text' }],
  data: { c1: { enc: 'raw', v: ['North', 'South'] } },
  cells: { 'c1:1': { note: 'checked' } },
  totals: { c1: 'count' },
  steps: [],
})
const scoped = parseDoc(JSON.stringify({
  ...minimal(), sheets: [twoSheets('a'), twoSheets('b')],
}))
ok(scoped.ok === true && scoped.repairs.length === 0,
  'the same column id in two different sheets is NOT a collision')
if (scoped.ok) {
  const s2 = scoped.doc.sheets[1] as any
  ok(s2.columns[0].id === 'c1' && Object.keys(s2.data)[0] === 'c1',
    'and neither sheet is rewritten, so no column is orphaned')
}

// When a column id genuinely IS duplicated within one sheet, the repair must
// carry the data with it or the repair is itself the loss.
const dupCol = parseDoc(JSON.stringify({
  ...minimal(),
  sheets: [{
    id: 'sh1', name: 'S', kind: 'table', rids: [[1, 2]],
    columns: [
      { id: 'c1', name: 'A', type: 'text' },
      { id: 'c1', name: 'B', type: 'number' },
    ],
    data: { c1: { enc: 'raw', v: [1, 2] } },
    cells: { 'c1:1': { note: 'kept' } },
    totals: { c1: 'sum' },
    steps: [],
  }],
}))
ok(dupCol.ok === true && dupCol.repairs.length === 1,
  'a duplicate column id WITHIN one sheet is repaired once')
if (dupCol.ok) {
  const sh = dupCol.doc.sheets[0] as any
  const ids = sh.columns.map((c: any) => c.id)
  ok(new Set(ids).size === 2, 'the two columns end up with distinct ids')
  ok(Object.keys(sh.data).every((k: string) => ids.includes(k)),
    'every data key still names a column that exists — no orphaned column data')
  ok(Object.keys(sh.cells).every((k: string) => ids.includes(k.split(':')[0])),
    'cell overrides follow the rename ("<colId>:<rid>" — only the column half moves)')
  ok(Object.keys(sh.totals).every((k: string) => ids.includes(k)),
    'the totals row follows the rename')
}

// --------------------------------------------------------------- budgets
const doc = (parseDoc(JSON.stringify(minimal())) as any).doc as DashDoc
ok(rowCount(doc) === 3, 'rowCount reads the run-length encoded ids')
ok(docBytes(doc) === JSON.stringify(doc).length,
  'docBytes is the serialized length — #bento-doc is plaintext, so file size IS JSON size')
ok(docBudget(true) === DOC_BUDGET_FSA && docBudget(false) === DOC_BUDGET_DOWNLOAD,
  'the budget scales with whether this browser can write in place')
ok(DOC_BUDGET_DOWNLOAD < DOC_BUDGET_FSA,
  'and the download-only budget is the SMALLER one — every save rewrites the whole file')
ok(!Object.keys({ FORMAT, FORMAT_VERSION }).includes('ROW_MAX'),
  'there is no row cap: rows are the wrong unit (1M x 12 is 65 MB; 1M x 2 is ~10 MB)')

// ADDITIVITY OF THE SHEET KIND (PLATFORM §3). A build that has never heard of a
// sheet kind must keep the file intact. This branch used to fall through, so
// every non-canvas sheet came back as `kind: 'table'` with empty
// rids/columns/data/steps bolted on — the sheet was rewritten into a different
// thing and what made it one was dropped. Old builds are frozen code, so a file
// from a newer dash has to survive a round trip through them untouched.
{
  const r = parseDoc(JSON.stringify({
    format: 'bento/dash', version: 1, policy: 'bento-dash-1', docId: 'd', title: 't',
    sheets: [
      { id: 'p1', name: 'P', kind: 'pivot', pivot: { from: 's1', rows: ['region'] } },
      { id: 'f1', name: 'F', kind: 'from-the-future', mystery: { a: 1 } },
    ],
  }))
  ok(r.ok, 'a workbook of unknown sheet kinds still parses')
  if (r.ok) {
    const [p, f] = r.doc.sheets as unknown as Array<Record<string, unknown>>
    ok(p.kind === 'pivot', 'an unrecognised kind is PRESERVED, not coerced to table')
    ok(!!p.pivot, 'and the field that makes it that kind survives')
    ok(!('rids' in p) && !('columns' in p) && !('data' in p),
      'with no table scaffolding bolted on to a sheet that is not a table')
    ok(f.kind === 'from-the-future' && JSON.stringify(f.mystery) === '{"a":1}',
      'a kind this build has never heard of round-trips whole')
  }
}

console.log(`\n${checks - failures}/${checks} checks passed`)
if (failures) process.exit(1)