@ape-egg/codecane 0.0.0-stage → 1.1.0

package/core/patch.js

@@ -0,0 +1,115 @@
+import { lines, split } from './diff.js'
+
+const context = 3
+const header = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
+
+const before = hunk => hunk.rows.filter(([op]) => op !== '+').map(([, line]) => line)
+const after = hunk => hunk.rows.filter(([op]) => op !== '-').map(([, line]) => line)
+const startOf = hunk => hunk.from - (before(hunk).length ? 1 : 0)
+
+export const parse = text => {
+  const hunks = split(text.replace(/\n$/, '')).reduce((hunks, line) => {
+    const opened = line.match(header)
+    if (opened) return [...hunks, { from: Number(opened[1]), was: Number(opened[2] ?? 1), is: Number(opened[4] ?? 1), rows: [] }]
+    if (!hunks.length || line.startsWith('\\')) return hunks
+    hunks.at(-1).rows.push(line === '' ? [' ', ''] : [line[0], line.slice(1)])
+    return hunks
+  }, [])
+  const malformed = hunks.find(hunk => hunk.was !== before(hunk).length || hunk.is !== after(hunk).length || hunk.rows.some(([op]) => !' -+'.includes(op)))
+  if (malformed) throw new Error(`codecane: the hunk @@ -${malformed.from},${malformed.was} @@ has lines that don't match its counts or don't start with a space, - or +`)
+  return hunks.map(({ from, rows }) => ({ from, rows }))
+}
+
+export const format = hunks => {
+  let shift = 0
+  return hunks.map(hunk => {
+    const [was, is] = [before(hunk).length, after(hunk).length]
+    const to = hunk.from + shift + (was ? 0 : 1) - (is ? 0 : 1)
+    shift += is - was
+    return [`@@ -${hunk.from},${was} +${to},${is} @@`, ...hunk.rows.map(([op, line]) => `${op}${line}`)].join('\n')
+  }).join('\n') + (hunks.length ? '\n' : '')
+}
+
+export const made = (base, text) => {
+  const rows = lines(base, text)
+  const changed = rows.map(([op], at) => op !== ' ' ? at : -1).filter(at => at >= 0)
+  const ranges = changed.reduce((ranges, at) => {
+    const last = ranges.at(-1)
+    if (last && at - last[1] <= 2 * context + 1) last[1] = at
+    else ranges.push([at, at])
+    return ranges
+  }, [])
+  return ranges.map(([first, last]) => {
+    const [start, end] = [Math.max(0, first - context), Math.min(rows.length - 1, last + context)]
+    const kept = rows.slice(0, start).filter(([op]) => op !== '+').length
+    const hunk = rows.slice(start, end + 1)
+    return { from: kept + (hunk.some(([op]) => op !== '+') ? 1 : 0), rows: hunk }
+  })
+}
+
+export const applied = (hunks, text) => {
+  const base = split(text)
+  const result = []
+  let at = 0
+  for (const hunk of hunks) {
+    const start = startOf(hunk)
+    const expected = before(hunk)
+    const found = base.slice(start, start + expected.length)
+    if (start < at || start > base.length || expected.some((line, index) => line !== found[index])) return { conflict: { line: start + 1, expected, found } }
+    result.push(...base.slice(at, start), ...after(hunk))
+    at = start + expected.length
+  }
+  return { text: [...result, ...base.slice(at)].join('\n') }
+}
+
+const blocks = hunk => {
+  const found = []
+  let old = startOf(hunk)
+  let current = null
+  hunk.rows.forEach(([op, line]) => {
+    if (op === ' ') {
+      current = null
+      old++
+      return
+    }
+    if (!current) found.push(current = { at: old, removed: [], added: [] })
+    if (op === '-') {
+      current.removed.push(line)
+      old++
+    } else current.added.push(line)
+  })
+  return found
+}
+
+export const rebased = (hunks, was, is) => {
+  const [old, base] = [split(was), split(is)]
+  const mapped = { [-1]: -1, [old.length]: base.length }
+  let [at, now] = [0, 0]
+  lines(was, is).forEach(([op]) => {
+    if (op === ' ') mapped[at] = now
+    if (op !== '+') at++
+    if (op !== '-') now++
+  })
+  const placed = []
+  for (const block of hunks.flatMap(blocks)) {
+    const span = block.removed.length
+    const target = span ? mapped[block.at] : mapped[block.at - 1] + 1
+    const intact = span
+      ? block.removed.every((_, index) => mapped[block.at + index] === target + index)
+      : mapped[block.at] === target
+    if (!intact || Number.isNaN(target) || target === undefined) {
+      const first = span ? block.at : Math.max(0, block.at - 1)
+      const expected = old.slice(first, span ? block.at + span : block.at + 1)
+      const anchor = expected.map((_, index) => mapped[first + index] - index).find(position => position >= 0) ?? first
+      return { conflict: { line: first + 1, expected, found: base.slice(anchor, anchor + expected.length) } }
+    }
+    placed.push({ ...block, target })
+  }
+  let cursor = 0
+  const result = placed.flatMap(block => {
+    const kept = base.slice(cursor, block.target)
+    cursor = block.target + block.removed.length
+    return [...kept, ...block.added]
+  })
+  return { hunks: made(is, [...result, ...base.slice(cursor)].join('\n')) }
+}

package/core/rebase.js

@@ -0,0 +1,80 @@
+import { format, made, parse, rebased } from './patch.js'
+import { beneath, changerOf, graphOf, layered, locate, replay, same, stack, under, unkeyed } from './stack.js'
+
+export const writes = (from, to) => {
+  const was = Object.fromEntries(from.map(step => [step.id, step]))
+  return Object.fromEntries(to.flatMap(step => {
+    const old = was[step.id]
+    const files = [...new Set([...Object.keys(old.files), ...Object.keys(step.files)])]
+      .filter(path => !same(old.files[path], step.files[path]))
+      .map(path => [`${step.folder}/${path}`, step.files[path] ?? null])
+    const patches = [...new Set([...Object.keys(old.patches), ...Object.keys(step.patches)])]
+      .filter(path => old.patches[path] !== step.patches[path])
+      .map(path => [`${step.folder}/${path}.patch`, step.patches[path] ?? null])
+    return [...files, ...patches]
+  }))
+}
+
+export const rebaseLater = (before, after) => {
+  const old = replay(before)
+  const was = Object.fromEntries(before.map(step => [step.id, step]))
+  const { ways, keyOf } = graphOf(after)
+  const now = {}
+  const moved = []
+  const conflicts = []
+  const steps = after.map(step => {
+    const lines = ways(step.id).map(through => [beneath(step, through, now, after), was[step.id] && beneath(was[step.id], through, old, before)])
+    const patches = Object.fromEntries(Object.entries(step.patches).map(([path, patch]) => {
+      const [below, oldBelow] = lines.find(([below, oldBelow]) => oldBelow?.files[path] && below.files[path] && !same(oldBelow.files[path], below.files[path])) ?? []
+      if (was[step.id]?.patches[path] !== patch || !below) return [path, patch]
+      const result = rebased(parse(patch), oldBelow.files[path].toString(), below.files[path].toString())
+      if (result.conflict) {
+        conflicts.push({ step: step.id, path, below: changerOf(below, path), ...result.conflict })
+        return [path, patch]
+      }
+      moved.push({ step: step.id, path })
+      return [path, format(result.hunks)]
+    }))
+    const rebasedStep = { ...step, patches }
+    ways(step.id).forEach(through => now[keyOf(step.id, through)] = layered(rebasedStep, through, now, after))
+    return rebasedStep
+  })
+  const strict = Object.entries(now).flatMap(([key, layered]) => layered.conflicts.filter(conflict => conflict.step === unkeyed(key).id))
+  return {
+    steps,
+    moved,
+    conflicts: [...conflicts, ...strict.filter(conflict => !conflicts.some(other => other.step === conflict.step && other.path === conflict.path))],
+  }
+}
+
+export const identical = (steps, id, path) => {
+  const step = steps.find(step => step.id === id)
+  return steps.filter(other => other.parents.join() === step.parents.join() && (path in step.patches ? other.patches[path] === step.patches[path] : same(other.files[path], step.files[path]))).map(other => other.id)
+}
+
+export const revise = (steps, address, path, text, forks = false) => {
+  const { id, through } = locate(steps, address)
+  const target = changerOf(stack(steps, id, through), path)
+  const targets = forks ? identical(steps, target, path) : [target]
+  const step = steps.find(step => step.id === target)
+  const patch = path in step.files ? '' : format(made(under(steps, target, through).files[path].toString(), text))
+  const edited = other => path in other.files
+    ? { ...other, files: { ...other.files, [path]: Buffer.from(text) } }
+    : { ...other, patches: Object.fromEntries(Object.entries({ ...other.patches, [path]: patch }).filter(([, body]) => body)) }
+  const result = rebaseLater(steps, steps.map(other => targets.includes(other.id) ? edited(other) : other))
+  return { targets, ...result, writes: writes(steps, result.steps) }
+}
+
+export const patchCopies = (steps, id, paths) => {
+  const step = steps.find(step => step.id === id)
+  if (!step) throw new Error(`codecane: there is no step ${id}`)
+  const below = under(steps, id)
+  const copies = (paths.length ? paths : Object.keys(step.files)).filter(path => path in below.files && path in step.files && !step.overrides.includes(path))
+  const edited = {
+    ...step,
+    files: Object.fromEntries(Object.entries(step.files).filter(([path]) => !copies.includes(path))),
+    patches: { ...step.patches, ...Object.fromEntries(copies.map(path => [path, format(made(below.files[path].toString(), step.files[path].toString()))]).filter(([, patch]) => patch)) },
+  }
+  const patched = steps.map(other => other.id === id ? edited : other)
+  return { copies, steps: patched, writes: writes(steps, patched) }
+}

package/core/serve.js

@@ -0,0 +1,170 @@
+import { existsSync, watch } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { createServer } from 'node:http'
+import { extname, join, normalize } from 'node:path'
+
+import { replayed } from './checks.js'
+import { entry, index } from './data.js'
+import { find } from './modules.js'
+import { patchCopies, rebaseLater, revise, writes } from './rebase.js'
+import { describe, locate, named, stack, tree } from './stack.js'
+import { persisted, read, stamp } from './steps.js'
+
+const types = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.woff2': 'font/woff2',
+  '.wasm': 'application/wasm',
+}
+
+const body = request => new Promise(done => {
+  const chunks = []
+  request.on('data', chunk => chunks.push(chunk)).on('end', () => done(Buffer.concat(chunks)))
+})
+
+const inside = path => {
+  if (normalize(path).split('/').includes('..')) throw new Error(`codecane: ${path} reaches outside its folder`)
+  return normalize(path)
+}
+
+const settle = 300
+
+const shapeOf = step => JSON.stringify([step.parents, step.merges, step.removes, step.overrides, step.story, step.check])
+const changedSince = (before, step) => {
+  const old = before.find(other => other.id === step.id)
+  return !old || shapeOf(old) !== shapeOf(step) || Object.keys(writes([old], [step])).length > 0
+}
+
+const reported = ({ stop, why, obsolete }) => {
+  if (stop) return console.error(`codecane: the replay stops at step ${named(stop)}:\n  ${why.join('\n  ').replaceAll('\n', '\n  ')}`)
+  obsolete.forEach(id => console.info(`codecane: the seam in step ${id} is no longer needed, so the timeline leaves it out.`))
+}
+
+const stacked = (steps, address) => tree(steps).addresses.includes(address)
+const stackedAt = (steps, path) => tree(steps).addresses.filter(address => path.startsWith(`${address}/`)).sort((a, b) => b.length - a.length)[0]
+
+const scriptsOf = html => (html.match(/<script\b[\s\S]*?<\/script>/g) ?? []).join('\n')
+
+export const serve = async ({ project, viewer, port }) => {
+  const listeners = new Set()
+  const announce = (event, data = {}) => listeners.forEach(response => response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`))
+  let snapshot = []
+  let queue = Promise.resolve()
+  const queued = work => {
+    const run = queue.then(work)
+    queue = Promise.allSettled([run])
+    return run
+  }
+
+  const synced = async () => {
+    await stamp(project)
+    const landed = await read(project)
+    const changed = landed.filter(step => changedSince(snapshot, step)).map(step => step.id)
+    if (!changed.length) return
+    const patched = changed.reduce((steps, id) => patchCopies(steps, id, []).steps, landed)
+    const { steps, moved, conflicts } = rebaseLater(snapshot, patched)
+    await persisted(project, writes(landed, steps))
+    moved.forEach(({ step, path }) => console.info(`codecane: rebased step ${step}'s patch of ${path}`))
+    conflicts.forEach(conflict => console.error(`codecane: ${describe(conflict)}`))
+    if (conflicts.length) return
+    snapshot = steps
+    reported(await replayed(steps, changed))
+    announce('steps-update')
+  }
+
+  await queued(synced)
+
+  let settling
+  watch(project, { recursive: true }, (_, path) => {
+    if (!/^(steps|parts)\//.test(path ?? '')) return
+    clearTimeout(settling)
+    settling = setTimeout(() => queued(synced).catch(error => console.error(error.message)), settle)
+  })
+
+  let shellScripts = scriptsOf(await readFile(join(viewer.dir, 'index.html'), 'utf8'))
+  const viewerChanged = async path => {
+    if (path.startsWith('components/') && path.endsWith('.html')) return announce('component-update', { path: `/codecane/ui/${path}` })
+    if (path.endsWith('.css')) return announce('style-update', { path: `/codecane/ui/${path}` })
+    if (path.endsWith('.js')) return announce('page-update', { scriptsChanged: true })
+    if (path !== 'index.html') return
+    const scripts = scriptsOf(await readFile(join(viewer.dir, 'index.html'), 'utf8'))
+    announce('page-update', { scriptsChanged: scripts !== shellScripts })
+    shellScripts = scripts
+  }
+
+  watch(viewer.dir, { recursive: true }, (_, path) => viewerChanged(path).catch(error => console.error(error.message)))
+
+  const saved = async (address, path, text, forks) => {
+    const steps = await read(project)
+    const { targets, moved, conflicts, writes: edits, steps: revised } = revise(steps, address, path, text, forks)
+    if (conflicts.length) return [409, [`Not saved: saving ${path} to ${targets.length > 1 ? 'steps' : 'step'} ${targets.join(', ')} would break later patches.`, ...conflicts.map(describe)].join('\n')]
+    await persisted(project, edits)
+    snapshot = revised
+    reported(await replayed(revised, targets))
+    return [200, JSON.stringify({ targets, moved }), '.json']
+  }
+
+  const routes = [
+    [/^\/codecane\/index\.json$/, async ({ steps, name }) => [JSON.stringify(await index(steps, { name, address: id => `${id}.json`, editable: true })), '.json']],
+    [/^\/codecane\/ui\/(.+)$/, async (_, path) => existsSync(join(viewer.dir, inside(path))) && [await readFile(join(viewer.dir, inside(path))), extname(path)]],
+    [/^\/codecane\/(.+)\.json$/, async ({ steps }, address) => stacked(steps, address) && [JSON.stringify(await entry(steps, address)), '.json']],
+    [/^\/steps\/(.+)$/, async ({ steps }, path) => {
+      const address = stackedAt(steps, path)
+      if (!address) return false
+      const { id, through } = locate(steps, address)
+      const { files } = stack(steps, id, through)
+      const file = path.slice(address.length + 1) || 'index.html'
+      return file in files && [files[file], extname(file)]
+    }],
+    [/^\/node_modules\/((?:@[^/]+\/)?[^/]+)\/(.+)$/, async (_, module, path) => {
+      const dir = find(module, project) ?? find(module, viewer.dir)
+      return dir && existsSync(join(dir, inside(path))) && [await readFile(join(dir, inside(path))), extname(path)]
+    }],
+    [/^\/(.*?)\/?$/, async ({ steps }, address) => (!address || address in tree(steps).located) && [await readFile(join(viewer.dir, 'index.html')), '.html']],
+  ]
+
+  return createServer(async (request, response) => {
+    const send = (status, content = '', extension = '.txt') => {
+      response.writeHead(status, { 'content-type': types[extension] ?? 'application/octet-stream', 'cache-control': 'no-store' })
+      response.end(content)
+    }
+    try {
+      const url = new URL(request.url, 'http://codecane')
+      const path = decodeURIComponent(url.pathname)
+      if (path === '/codecane/events') {
+        response.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store' }).flushHeaders()
+        listeners.add(response)
+        return request.on('close', () => listeners.delete(response))
+      }
+      const steps = await read(project)
+      const { name } = JSON.parse(await readFile(join(project, 'package.json'), 'utf8'))
+      if (request.method === 'PUT') {
+        const [, file] = path.match(/^\/codecane\/save\/(.+)$/) ?? []
+        const address = url.searchParams.get('at')
+        if (!stacked(steps, address)) return send(404, `codecane: there is no step ${address}`)
+        const text = (await body(request)).toString()
+        return send(...await queued(() => saved(address, inside(file), text, url.searchParams.has('forks'))))
+      }
+      if (path.startsWith('/steps/') && stacked(steps, path.slice('/steps/'.length))) {
+        response.writeHead(301, { location: `${path}/` })
+        return response.end()
+      }
+      for (const [pattern, route] of routes) {
+        const match = path.match(pattern)
+        const found = match && await route({ steps, name }, ...match.slice(1))
+        if (found) return send(200, ...found)
+      }
+      send(404, `codecane: nothing at ${path}`)
+    } catch (error) {
+      console.error(error)
+      send(500, error.message)
+    }
+  }).listen(port, () => console.info(`codecane: serving ${project} at http://localhost:${port}`))
+}

package/core/stack.js

@@ -0,0 +1,199 @@
+import { applied, parse } from './patch.js'
+
+const order = (a, b) => a.localeCompare(b, undefined, { numeric: true })
+
+export const same = (one, other) => one === other || Boolean(one && other && one.equals(other))
+
+export const unkeyed = key => {
+  const [id, ...through] = key.split('|')
+  return { id, through }
+}
+
+export const named = key => {
+  const { id, through } = unkeyed(key)
+  return through.length ? `${id} through ${through.join(', ')}` : id
+}
+
+const graphs = new WeakMap()
+
+export const graphOf = steps => {
+  if (graphs.has(steps)) return graphs.get(steps)
+  const byId = Object.fromEntries(steps.map(step => [step.id, step]))
+  const parentOf = (id, through = []) => byId[id].parents.find(parent => through.includes(parent)) ?? byId[id].parents[0] ?? null
+  const picks = (id, through) => {
+    const parent = parentOf(id, through)
+    return parent === null ? [] : [...picks(parent, through), ...parent === byId[id].parents[0] ? [] : [parent]]
+  }
+  const keyOf = (id, through = []) => [id, ...picks(id, through)].join('|')
+  const known = {}
+  const lineage = (id, through = []) => id === null ? [] : known[keyOf(id, through)] ??= (() => {
+    const own = picks(id, through)
+    return [...lineage(parentOf(id, own), own), ...brought(id, own), id]
+  })()
+  const brought = (id, through = []) => [...new Set(byId[id].merges.flatMap(other => lineage(other, through)))].filter(other => !lineage(parentOf(id, through), through).includes(other))
+  const paths = {}
+  const ways = id => paths[id] ??= byId[id].parents.length ? byId[id].parents.flatMap((parent, at) => ways(parent).map(through => at ? [...through, parent] : through)) : [[]]
+  const graph = { byId, parentOf, keyOf, lineage, brought, ways, keys: steps.flatMap(step => ways(step.id).map(through => [step.id, ...through].join('|'))) }
+  graphs.set(steps, graph)
+  return graph
+}
+
+export const tree = steps => {
+  const at = Object.fromEntries(steps.map((step, index) => [step.id, index]))
+  const orphan = steps.find(step => step.parents.some(parent => !(at[parent] < at[step.id])))
+  if (orphan) throw new Error(`codecane: step ${orphan.id} names parent ${orphan.parents.join(', ')}, which must be earlier steps`)
+  const late = steps.find(step => step.merges.some(id => !(at[id] < at[step.id])))
+  if (late) throw new Error(`codecane: step ${late.id} merges ${late.merges.join(', ')}, which must be earlier steps`)
+  const { byId, lineage, brought } = graphOf(steps)
+  const idle = steps.find(step => step.merges.length && !brought(step.id).length && !ownPaths(step).length)
+  if (idle) throw new Error(`codecane: step ${idle.id} merges ${idle.merges.join(', ')}, which its timeline already holds, and holds no seam`)
+  const children = id => steps.filter(step => id === null ? !step.parents.length : step.parents.includes(id)).map(step => step.id).sort(order)
+  const joins = id => steps.filter(step => step.merges.includes(id) && brought(step.id).length).map(step => step.id).sort(order)
+  const lines = id => {
+    const next = [...children(id), ...joins(id)]
+    return next.length ? next.flatMap(other => lines(other).map(line => [id, ...line])) : [[id]]
+  }
+  const loose = steps.find(step => seamed(step) && !step.part)
+  if (loose) throw new Error(`codecane: step ${loose.id} is a seam, so it lives in parts/${loose.hash}: move ${loose.folder} there, with its story, take the hash out of its codecane.json, and name ${loose.hash} wherever a step names ${loose.id}`)
+  const stray = steps.find(step => step.part && !seamed(step))
+  if (stray) throw new Error(`codecane: ${stray.folder} holds no seam, and parts/ holds only seams; move it into steps/ under a name`)
+  const timelines = children(null).flatMap(lines)
+  const ways = id => children(id).length + joins(id).length
+  const addressed = timeline => timeline.map((id, depth) => [id, ...timeline.slice(1, depth).filter((_, at) => ways(timeline[at]) > 1).map(chosen => byId[chosen].hash)].join('/'))
+  const stacks = timelines.map(addressed)
+  const place = (timeline, depth) => ({ id: timeline[depth], through: timeline.slice(0, depth).filter((parent, step) => byId[timeline[step + 1]].parents.indexOf(parent) > 0) })
+  const first = id => timelines.find(timeline => timeline.includes(id))
+  const located = {
+    ...Object.fromEntries(steps.map(({ id }) => [id, place(first(id), first(id).indexOf(id))])),
+    ...Object.fromEntries(timelines.flatMap((timeline, lane) => timeline.map((_, depth) => [stacks[lane][depth], place(timeline, depth)]))),
+  }
+  return { children, joins, lineage, brought, timelines, stacks, located, addresses: [...new Set(stacks.flat())] }
+}
+
+export const seamed = step => (step.merges.length > 0 || step.parents.length > 1) && ownPaths(step).length > 0
+
+export const locate = (steps, address) => {
+  const { located, stacks } = tree(steps)
+  if (!located[address]) throw new Error(`codecane: there is no step ${address}; the steps on the timelines are ${[...new Set(stacks.flat())].join(', ')}`)
+  return located[address]
+}
+
+export const empty = { files: {}, owners: {}, patchers: {}, overrides: [], conflicts: [] }
+
+export const changerOf = (layered, path) => layered.patchers[path]?.at(-1) ?? layered.owners[path]
+
+export const layer = (step, below, through = []) => {
+  const files = { ...below.files }
+  const owners = { ...below.owners }
+  const patchers = { ...below.patchers }
+  const overrides = [...below.overrides]
+  const conflicts = [...below.conflicts]
+  const fail = message => { throw new Error(`codecane: step ${step.id} ${message}`) }
+
+  step.removes.forEach(path => {
+    if (!(path in files)) fail(`removes ${path}, which no earlier step has`)
+    if (path in step.files) fail(`removes ${path} and brings it again; list it in overrides instead`)
+    delete files[path]
+    delete owners[path]
+    delete patchers[path]
+  })
+
+  Object.entries(step.files).forEach(([path, body]) => {
+    if (path in step.patches) fail(`brings ${path} and patches it too`)
+    if (path in files && !step.overrides.includes(path)) fail(`brings its own copy of ${path} from step ${changerOf({ owners, patchers }, path)}; turn it into a patch with codecane patch ${step.id} ${path}, or list it in overrides in its codecane.json if a full copy is deliberate`)
+    if (!(path in files) && step.overrides.includes(path)) fail(`overrides ${path}, which no earlier step has`)
+    if (path in files) overrides.push({ path, step: step.id, over: changerOf({ owners, patchers }, path) })
+    files[path] = body
+    owners[path] = step.id
+    delete patchers[path]
+  })
+
+  Object.entries(step.patches).forEach(([path, patch]) => {
+    if (!(path in files)) return conflicts.push({ step: step.id, through, path, missing: true })
+    const result = applied(parse(patch), files[path].toString())
+    if (result.conflict) return conflicts.push({ step: step.id, through, path, below: changerOf({ owners, patchers }, path), ...result.conflict })
+    files[path] = Buffer.from(result.text)
+    patchers[path] = [...(patchers[path] ?? []), step.id]
+  })
+
+  return { files, owners, patchers, overrides, conflicts }
+}
+
+const parentLayer = (step, through, layers, steps) => {
+  const { parentOf, keyOf } = graphOf(steps)
+  const parent = parentOf(step.id, through)
+  return parent === null ? empty : layers[keyOf(parent, through)]
+}
+
+const replayed = (below, step, through, layers, steps) => {
+  const [before, after] = [parentLayer(step, through, layers, steps), layers[graphOf(steps).keyOf(step.id, through)]]
+  const files = { ...below.files }
+  const owners = { ...below.owners }
+  const patchers = { ...below.patchers }
+  const clashes = []
+  const set = (path, body, owned) => {
+    if (!body) return [files, owners, patchers].forEach(map => delete map[path])
+    files[path] = body
+    if (!owned) return patchers[path] = [...(patchers[path] ?? []), step.id]
+    owners[path] = step.id
+    delete patchers[path]
+  }
+  ;[...new Set([...Object.keys(before.files), ...Object.keys(after.files)])].filter(path => !same(before.files[path], after.files[path])).forEach(path => {
+    const [was, now, here] = [before.files[path], after.files[path], files[path]]
+    if (same(here, now)) return
+    if (same(here, was)) return set(path, now, !was || path in step.files)
+    const patch = here && step.patches[path] && applied(parse(step.patches[path]), here.toString())
+    if (patch && !patch.conflict) return set(path, Buffer.from(patch.text), false)
+    clashes.push({ step: step.id, path, below: changerOf({ owners, patchers }, path) })
+  })
+  return { ...below, files, owners, patchers, clashes: [...below.clashes, ...clashes] }
+}
+
+export const merged = (step, through, layers, steps) => graphOf(steps).brought(step.id, through)
+  .map(id => steps.find(other => other.id === id))
+  .reduce((below, other) => replayed(below, other, through, layers, steps), { ...parentLayer(step, through, layers, steps), clashes: [] })
+
+export const ownPaths = step => [...Object.keys(step.files), ...Object.keys(step.patches), ...step.removes]
+
+export const beneath = (step, through, layers, steps) => {
+  if (!step.merges.length) return parentLayer(step, through, layers, steps)
+  const { clashes, ...below } = merged(step, through, layers, steps)
+  return below
+}
+
+export const layered = (step, through, layers, steps) => {
+  const own = unkeyed(graphOf(steps).keyOf(step.id, through)).through
+  if (!step.merges.length) return layer(step, parentLayer(step, own, layers, steps), own)
+  const { clashes, ...below } = merged(step, own, layers, steps)
+  const result = layer(step, below, own)
+  const open = clashes.filter(clash => !ownPaths(step).includes(clash.path))
+  return { ...result, conflicts: [...result.conflicts, ...open.map(clash => ({ ...clash, brought: clash.step, step: step.id, through: own, clash: true }))] }
+}
+
+export const describe = ({ step, through = [], path, below, line, expected, found, missing, clash, brought }) => {
+  const on = through.length ? ` on the timeline through ${through.join(', ')}` : ''
+  if (clash) return `step ${step} merges step ${brought}, whose change to ${path} doesn't replay onto ${path} as step ${below} leaves it${on}; the timelines differ there, so this merge needs a seam`
+  if (missing) return `step ${step} patches ${path}, which no earlier step on its timeline${on} has`
+  return [
+    `step ${step}'s patch of ${path} no longer applies at line ${line}, against ${path} as step ${below} leaves it${on}:`,
+    ...expected.map((text, index) => [text, found[index], line + index]).filter(([text, there]) => text !== there).map(([text, there, at]) => `  line ${at}: the patch expects ${JSON.stringify(text)}, the file has ${there === undefined ? 'no such line' : JSON.stringify(there)}`),
+  ].join('\n')
+}
+
+export const replay = steps => {
+  tree(steps)
+  const { keys, byId } = graphOf(steps)
+  return keys.map(unkeyed).reduce((layers, { id, through }) => ({ ...layers, [[id, ...through].join('|')]: layered(byId[id], through, layers, steps) }), {})
+}
+
+export const conflictsOf = layers => Object.entries(layers).flatMap(([key, layered]) => layered.conflicts.filter(conflict => conflict.step === unkeyed(key).id))
+
+const layersOf = (steps, ids, through) => steps.filter(step => ids.includes(step.id)).reduce((layers, step) => ({ ...layers, [graphOf(steps).keyOf(step.id, through)]: layered(step, through, layers, steps) }), {})
+
+export const under = (steps, id, through = []) => beneath(steps.find(step => step.id === id), through, layersOf(steps, tree(steps).lineage(id, through).slice(0, -1), through), steps)
+
+export const stack = (steps, id, through = []) => {
+  const result = layersOf(steps, tree(steps).lineage(id, through), through)[graphOf(steps).keyOf(id, through)]
+  if (result.conflicts.length) throw new Error(`codecane: the steps don't stack. Run codecane check.\n${result.conflicts.map(describe).join('\n')}`)
+  return result
+}

package/core/steps.js

@@ -0,0 +1,102 @@
+import { randomBytes } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+export const order = (a, b) => a.localeCompare(b, undefined, { numeric: true })
+
+export const patched = '.patch'
+
+const reserved = ['codecane', 'steps', 'parts', 'node_modules', 'index']
+const keys = ['hash', 'parent', 'merges', 'removes', 'overrides']
+
+const listed = async dir => (await readdir(dir, { recursive: true, withFileTypes: true }))
+  .filter(entry => entry.isFile() && !entry.name.startsWith('.'))
+  .map(entry => join(entry.parentPath, entry.name).slice(dir.length + 1))
+  .filter(path => path !== 'codecane.json')
+  .sort(order)
+
+const configured = async dir => {
+  if (!existsSync(join(dir, 'codecane.json'))) return {}
+  const config = JSON.parse(await readFile(join(dir, 'codecane.json'), 'utf8'))
+  const unknown = Object.keys(config).filter(key => !keys.includes(key))
+  if (unknown.length) throw new Error(`codecane: ${dir}/codecane.json has unknown keys ${unknown.join(', ')}; it knows ${keys.join(', ')}`)
+  return config
+}
+
+export const parentsFirst = steps => {
+  const known = new Set(steps.map(step => step.id))
+  const orphan = steps.find(step => step.parents.some(parent => !known.has(parent)))
+  if (orphan) throw new Error(`codecane: step ${orphan.id} names parent ${orphan.parents.filter(parent => !known.has(parent)).join(', ')}, which is no step`)
+  const children = id => steps.filter(step => id === null ? !step.parents.length : step.parents.includes(id))
+  const walked = id => children(id).flatMap(step => [step, ...walked(step.id)])
+  const pending = [...new Set(walked(null))]
+  const looped = steps.filter(step => !pending.includes(step)).map(step => step.id)
+  if (looped.length) throw new Error(`codecane: steps ${looped.join(', ')} name parents that lead back to themselves`)
+  const unknown = steps.find(step => step.merges.some(id => !known.has(id)))
+  if (unknown) throw new Error(`codecane: step ${unknown.id} merges ${unknown.merges.filter(id => !known.has(id)).join(', ')}, which is no step`)
+  const ordered = []
+  const placed = id => ordered.some(step => step.id === id)
+  while (pending.length) {
+    const ready = pending.findIndex(step => [...step.parents, ...step.merges].every(placed))
+    if (ready === -1) throw new Error(`codecane: steps ${pending.map(step => step.id).join(', ')} merge timelines that lead back to themselves`)
+    ordered.push(...pending.splice(ready, 1))
+  }
+  return ordered
+}
+
+const folders = async root => existsSync(root) ? (await readdir(root, { withFileTypes: true })).filter(entry => entry.isDirectory()).map(entry => entry.name).sort(order) : []
+
+export const stamp = async project => {
+  const named = await folders(join(project, 'steps'))
+  const configs = await Promise.all(named.map(id => configured(join(project, 'steps', id))))
+  const taken = new Set([...configs.map(config => config.hash), ...await folders(join(project, 'parts'))])
+  const fresh = () => {
+    const hash = randomBytes(4).toString('hex').slice(0, 7)
+    return taken.has(hash) ? fresh() : taken.add(hash) && hash
+  }
+  await Promise.all(named.map((id, at) => !configs[at].hash && writeFile(join(project, 'steps', id, 'codecane.json'), `${JSON.stringify({ hash: fresh(), ...configs[at] }, null, 2)}\n`)))
+}
+
+export const read = async project => {
+  const named = await folders(join(project, 'steps'))
+  const taken = named.filter(id => reserved.includes(id))
+  if (taken.length) throw new Error(`codecane: ${taken.join(', ')} is reserved, rename the step`)
+  const loaded = async (folder, id, before) => {
+    const dir = join(project, folder)
+    const config = await configured(dir)
+    const part = folder.startsWith('parts/')
+    if (!part && !config.hash) throw new Error(`codecane: ${folder} has no hash yet; codecane check, build and dev give every new step one`)
+    const story = existsSync(`${dir}.html`) ? await readFile(`${dir}.html`, 'utf8') : ''
+    const paths = await listed(dir)
+    const file = async path => [path, await readFile(join(dir, path))]
+    return {
+      id,
+      hash: part ? id : config.hash,
+      folder,
+      part,
+      parents: [('parent' in config ? config.parent : before) ?? []].flat(),
+      merges: config.merges ?? [],
+      title: part ? `Seam ${id}` : story.match(/<h1[^>]*>(.*?)<\/h1>/s)?.[1].replace(/<[^>]+>/g, '').trim() ?? id,
+      story,
+      check: existsSync(`${dir}.check.js`) ? `${dir}.check.js` : null,
+      removes: config.removes ?? [],
+      overrides: config.overrides ?? [],
+      files: Object.fromEntries(await Promise.all(paths.filter(path => !path.endsWith(patched)).map(file))),
+      patches: Object.fromEntries((await Promise.all(paths.filter(path => path.endsWith(patched)).map(file))).map(([path, body]) => [path.slice(0, -patched.length), body.toString()])),
+    }
+  }
+  const steps = await Promise.all([
+    ...named.map((id, at) => loaded(`steps/${id}`, id, named[at - 1])),
+    ...(await folders(join(project, 'parts'))).map(hash => loaded(`parts/${hash}`, hash)),
+  ])
+  const twice = steps.find((step, at) => steps.findIndex(other => other.hash === step.hash) !== at)
+  if (twice) throw new Error(`codecane: ${twice.folder} has hash ${twice.hash}, which another step has too; give it a new one`)
+  return parentsFirst(steps)
+}
+
+export const persisted = (root, writes) => Promise.all(Object.entries(writes).map(async ([path, body]) => {
+  if (body === null) return rm(join(root, path))
+  await mkdir(dirname(join(root, path)), { recursive: true })
+  await writeFile(join(root, path), body)
+}))