tspl-cli 0.0.0-stage → 0.1.1

package/src/task/hooks.js

@@ -0,0 +1,82 @@
+'use strict'
+
+const Fs = require('fs')
+const Path = require('path')
+const { execFileSync } = require('child_process')
+
+const BIN = Path.join(__dirname, '..', '..', 'bin', 'tspl.js')
+const HOOKS = ['pre-commit', 'pre-push']
+const MARK = '# tspl edit lock'
+
+const hooksDir = repoPath => {
+  const dir = execFileSync('git', ['-C', repoPath, 'rev-parse', '--git-path', 'hooks'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  return Path.isAbsolute(dir) ? dir : Path.join(repoPath, dir)
+}
+
+const script = hook =>
+  [
+    '#!/bin/sh',
+    MARK,
+    `export TSPL_HOME="${process.env.TSPL_HOME || Path.join(require('os').homedir(), '.tspl')}"`,
+    'prev="$0.tspl-prev"',
+    'if [ -x "$prev" ]; then "$prev" "$@" || exit $?; fi',
+    `NODE="${process.execPath}"`,
+    '[ -x "$NODE" ] || NODE=node',
+    `exec "$NODE" "${BIN}" guard ${hook} "$@"`,
+    '',
+  ].join('\n')
+
+const ours = file => {
+  try {
+    return Fs.readFileSync(file, 'utf8').includes(MARK)
+  } catch (err) {
+    return false
+  }
+}
+
+const installHooks = repoPath => {
+  const dir = hooksDir(repoPath)
+  Fs.mkdirSync(dir, { recursive: true })
+  HOOKS.forEach(hook => {
+    const file = Path.join(dir, hook)
+    if (Fs.existsSync(file) && !ours(file)) Fs.renameSync(file, `${file}.tspl-prev`)
+    Fs.writeFileSync(file, script(hook), { mode: 0o755 })
+    Fs.chmodSync(file, 0o755)
+  })
+  return dir
+}
+
+const removeHooks = repoPath => {
+  let dir
+  try {
+    dir = hooksDir(repoPath)
+  } catch (err) {
+    return false
+  }
+  let removed = false
+  HOOKS.forEach(hook => {
+    const file = Path.join(dir, hook)
+    if (ours(file)) {
+      Fs.rmSync(file, { force: true })
+      removed = true
+    }
+    if (Fs.existsSync(`${file}.tspl-prev`) && !Fs.existsSync(file)) Fs.renameSync(`${file}.tspl-prev`, file)
+  })
+  return removed
+}
+
+const hooksInstalled = repoPath => {
+  try {
+    const dir = hooksDir(repoPath)
+    return HOOKS.every(hook => ours(Path.join(dir, hook)))
+  } catch (err) {
+    return false
+  }
+}
+
+module.exports = {
+  HOOKS,
+  installHooks,
+  removeHooks,
+  hooksInstalled,
+}

package/src/task/plan-draft.js

@@ -0,0 +1,43 @@
+'use strict'
+
+const Fs = require('fs')
+const Os = require('os')
+const Path = require('path')
+const { hashValue, approachBasis } = require('../shared')
+
+/**
+ * The plan drafted alongside the approaches, kept on this computer until the user chooses. It is only valid for the
+ * same requirements, the same offered options and the same code context; anything else plans afresh.
+ */
+const dirOf = () => Path.join(process.env.TSPL_HOME || Path.join(Os.homedir(), '.tspl'), 'plan-drafts')
+const fileOf = (projectId, task) => Path.join(dirOf(), `${hashValue({ project: String(projectId), task: task.key || task.id })}.json`)
+const fingerprint = (card, approaches, brief) => hashValue({
+  requirements: approachBasis(card),
+  options: approaches.options.map(option => [option.id, option.title, option.summary]),
+  recommendedId: approaches.recommendedId,
+  brief: brief || '',
+})
+
+const saveDraft = (projectId, task, proposal, plan, brief) => {
+  Fs.mkdirSync(dirOf(), { recursive: true, mode: 0o700 })
+  const file = fileOf(projectId, task)
+  Fs.writeFileSync(file, JSON.stringify({ fingerprint: fingerprint(task.card, proposal, brief), optionId: proposal.recommendedId, plan }), { mode: 0o600 })
+  Fs.chmodSync(file, 0o600)
+}
+
+/** Returns { optionId, plan } once, or null; a used or stale draft is removed so a re-plan never repeats it. */
+const takeDraft = (projectId, task, brief) => {
+  const file = fileOf(projectId, task)
+  let draft
+  try {
+    draft = JSON.parse(Fs.readFileSync(file, 'utf8'))
+  } catch (err) {
+    if (err.code === 'ENOENT' || err instanceof SyntaxError) return null
+    throw err
+  }
+  Fs.rmSync(file, { force: true })
+  if (!task.approaches || draft.fingerprint !== fingerprint(task.card, task.approaches, brief)) return null
+  return { optionId: draft.optionId, plan: draft.plan }
+}
+
+module.exports = { saveDraft, takeDraft }

package/src/task/plan-page.js

@@ -0,0 +1,123 @@
+'use strict'
+
+const { byRepo, countLine, changesSince } = require('./plan')
+
+const escape = value =>
+  String(value === undefined || value === null ? '' : value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+
+const STATUS_LABELS = {
+  draft: 'No plan yet',
+  'plan-review': 'Waiting for the developer',
+  'pm-review': 'Waiting for the PM',
+  approved: 'Approved — ready to build',
+  'changes-requested': 'Changes requested',
+  building: 'Building',
+  done: 'Done',
+}
+
+const KIND_LABELS = { edit: 'edit', create: 'new', remove: 'remove' }
+
+const approvalsHtml = task => {
+  const decision = stage => [...(task.decisions || [])].reverse().find(item => item.stage === stage && item.planVersion === (task.plan && task.plan.version))
+  const row = (stage, label) => {
+    const found = decision(stage)
+    if (!found) return `<li class="pending">${label}: waiting</li>`
+    const when = found.at ? new Date(found.at).toLocaleString() : ''
+    return `<li class="${found.approved ? 'yes' : 'no'}">${label}: ${found.approved ? 'approved' : 'asked for changes'} by ${escape(found.userName || 'someone')} ${escape(when)}${found.note ? ` — “${escape(found.note)}”` : ''}</li>`
+  }
+  return `<ul class="approvals">${row('developer', 'Developer')}${task.requirePmApproval === false ? '<li class="skip">PM: not required for this project</li>' : row('pm', 'PM')}</ul>`
+}
+
+const renderPlanPage = (task, projectName) => {
+  const plan = task.plan
+  const card = task.card || {}
+  const review = {
+    edit: (plan && plan.edit) || [],
+    create: (plan && plan.create) || [],
+    remove: (plan && plan.remove) || [],
+    tests: (plan && plan.tests) || [],
+  }
+  const testsFor = n => review.tests.filter(test => (test.checks || []).includes(n)).map(test => test.name)
+  const repos = []
+  byRepo(review).forEach((items, repo) => {
+    repos.push(`<section class="repo"><h3>${escape(repo)}</h3><ul class="files">${items
+      .map(item => `<li class="${item.kind}"><span class="badge ${item.kind}">${KIND_LABELS[item.kind]}</span><code>${escape(item.path)}</code>${item.why ? `<span class="why">${escape(item.why)}</span>` : ''}</li>`)
+      .join('')}</ul></section>`)
+  })
+  const versions = (task.plans || [])
+    .map((previous, i) => {
+      const next = i + 1 < (task.plans || []).length ? task.plans[i + 1] : plan
+      const changes = changesSince(previous, { edit: next.edit || [], create: next.create || [], remove: next.remove || [], tests: next.tests || [] })
+      return `<li>v${escape(previous.version)} → v${escape(next.version)}: ${changes.length ? changes.map(escape).join(', ') : 'no file changes'}</li>`
+    })
+    .join('')
+  const fields = [
+    ['Who', card.who],
+    ['Where', (card.apps || []).join(', ')],
+    ['How it works', card.how],
+    ['Steps', card.steps],
+    ['Now', card.now],
+    ['Expected', card.expected],
+  ].filter(([, value]) => value)
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Plan ${escape(task.key)}</title>
+<style>
+:root { --bg: #f7f7f5; --card: #ffffff; --text: #1d1d1b; --muted: #6b6b66; --line: #e3e3de;
+  --edit: #b26b00; --edit-bg: #fff4e0; --new: #1f7a3a; --new-bg: #e6f5ea; --remove: #b3261e; --remove-bg: #fde8e6; --accent: #2f5bd3; }
+@media (prefers-color-scheme: dark) { :root { --bg: #151514; --card: #1f1f1d; --text: #ecece8; --muted: #a2a29b; --line: #34342f;
+  --edit: #f0b35a; --edit-bg: #3a2a10; --new: #6fd08c; --new-bg: #13301c; --remove: #ff8a80; --remove-bg: #3b1714; --accent: #8fb0ff; } }
+* { box-sizing: border-box; }
+body { margin: 0; padding: 24px 16px 48px; background: var(--bg); color: var(--text); font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+main { max-width: 960px; margin: 0 auto; }
+h1 { font-size: 22px; margin: 4px 0 8px; } h2 { font-size: 16px; margin: 28px 0 10px; } h3 { font-size: 14px; margin: 0 0 8px; color: var(--muted); }
+.meta { color: var(--muted); font-size: 13px; } .status { display: inline-block; padding: 2px 10px; border-radius: 999px; background: var(--card); border: 1px solid var(--line); font-weight: 600; }
+.card { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 16px; margin: 12px 0; }
+dl { display: grid; grid-template-columns: max-content 1fr; gap: 6px 16px; margin: 0; } dt { color: var(--muted); } dd { margin: 0; }
+.count { font-weight: 600; margin-bottom: 8px; } .repo { margin-top: 14px; }
+.files { list-style: none; padding: 0; margin: 0; } .files li { display: flex; flex-wrap: wrap; gap: 8px; align-items: baseline; padding: 6px 0; border-top: 1px solid var(--line); }
+code { font: 13px ui-monospace, SFMono-Regular, Menlo, monospace; word-break: break-all; } .why { color: var(--muted); flex-basis: 100%; padding-left: 64px; font-size: 13px; }
+.badge { font-size: 11px; font-weight: 700; text-transform: uppercase; padding: 1px 8px; border-radius: 6px; min-width: 56px; text-align: center; }
+.badge.edit { color: var(--edit); background: var(--edit-bg); } .badge.create { color: var(--new); background: var(--new-bg); } .badge.remove { color: var(--remove); background: var(--remove-bg); }
+table { width: 100%; border-collapse: collapse; } td, th { text-align: left; padding: 6px 8px; border-top: 1px solid var(--line); vertical-align: top; } th { color: var(--muted); font-weight: 600; }
+.missing { color: var(--remove); } ul.approvals { list-style: none; padding: 0; margin: 0; } .approvals li { padding: 4px 0; }
+.approvals .yes::before { content: "✓ "; color: var(--new); } .approvals .no::before { content: "✗ "; color: var(--remove); } .approvals .pending::before { content: "○ "; color: var(--muted); } .approvals .skip { color: var(--muted); }
+.warn li { color: var(--edit); } pre { white-space: pre-wrap; background: var(--bg); padding: 10px; border-radius: 8px; }
+@media (max-width: 600px) { .why { padding-left: 0; } dl { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<main>
+<div class="meta">${escape(projectName)} · ${escape(task.key)}${task.ticket ? ` · ${escape(task.ticket)}` : ''} · ${escape(task.type || '')}${plan ? ` · plan v${escape(plan.version)}` : ''}</div>
+<h1>${escape(task.title || card.what || 'Task')}</h1>
+<span class="status">${escape(STATUS_LABELS[task.status] || task.status)}</span>
+<div class="card"><h2 style="margin-top:0">Approvals</h2>${approvalsHtml(task)}</div>
+${fields.length ? `<div class="card"><dl>${fields.map(([label, value]) => `<dt>${label}</dt><dd>${escape(value)}</dd>`).join('')}</dl></div>` : ''}
+${plan ? `<h2>Files</h2><div class="card"><div class="count">${escape(countLine({ ...review, edit: review.edit, create: review.create, remove: review.remove }))}</div>${repos.join('') || '<p>No files.</p>'}</div>` : '<p>No plan submitted yet.</p>'}
+${(card.doneWhen || []).length ? `<h2>Done when</h2><div class="card"><table><tr><th>#</th><th>Check</th><th>Tested by</th></tr>${card.doneWhen
+    .map((check, i) => `<tr><td>${i + 1}</td><td>${escape(check)}</td><td>${testsFor(i + 1).length ? testsFor(i + 1).map(escape).join('<br>') : '<span class="missing">no test yet</span>'}</td></tr>`)
+    .join('')}</table></div>` : ''}
+${plan && (plan.screens || []).length ? `<h2>Screens</h2><div class="card"><ul>${plan.screens.map(screen => `<li>${escape(screen)}</li>`).join('')}</ul></div>` : ''}
+${plan && plan.notes ? `<h2>Notes</h2><div class="card">${escape(plan.notes)}</div>` : ''}
+${plan && (plan.warnings || []).length ? `<h2>tspl checks</h2><div class="card"><ul class="warn">${plan.warnings.map(warning => `<li>${escape(warning)}</li>`).join('')}</ul></div>` : ''}
+${versions ? `<h2>Earlier versions</h2><div class="card"><ul>${versions}</ul></div>` : ''}
+<h2>Decide</h2>
+<div class="card"><pre>tspl plan approve ${escape(task.key)}
+tspl plan reject ${escape(task.key)} --note "what should change"</pre></div>
+</main>
+</body>
+</html>
+`
+}
+
+module.exports = {
+  renderPlanPage,
+}

package/src/task/plan.js

@@ -0,0 +1,293 @@
+'use strict'
+
+const Path = require('path').posix
+const { editDistance } = require('../find/text')
+const { TEST_FILE } = require('../shared')
+const { styleOf, majority } = require('./conventions')
+const { findProjectConfig, snapshotProject } = require('../project-config')
+
+const KIND_FILE = /^(.+?)\.([a-z][a-z0-9-]*)\.([a-z]+)$/
+const USED_BY = new Set(['imports', 'uses', 'renders', 'calls-api', 'template'])
+
+const keyOf = file => String(file || '').trim().replace(/^([^:/\s]+):\s*/, '$1/')
+
+const items = (plan, kind) =>
+  (Array.isArray(plan[kind]) ? plan[kind] : [])
+    .map(item => (typeof item === 'string' ? { file: item } : item || {}))
+    .map(item => ({ file: keyOf(item.file), why: String(item.why || '').trim() }))
+    .filter(item => item.file)
+
+const closestPath = (graph, key) => {
+  const repo = key.split('/')[0]
+  const base = Path.basename(key)
+  const candidates = graph.files
+    .map(file => ({ file, distance: editDistance(Path.basename(file.path), base, 2) + (file.repo === repo ? 0 : 1) }))
+    .filter(item => item.distance <= 2)
+    .sort((a, b) => a.distance - b.distance)
+  return candidates.length ? ` Did you mean ${candidates[0].file.repo}/${candidates[0].file.path}?` : ''
+}
+
+const placementNote = (graph, key) => {
+  const repo = key.split('/')[0]
+  const path = key.slice(repo.length + 1)
+  const match = Path.basename(path).match(KIND_FILE)
+  if (!match) return null
+  const suffix = `.${match[2]}.${match[3]}`
+  const sameKind = graph.files.filter(file => file.repo === repo && file.path.endsWith(suffix))
+  if (!sameKind.length) return null
+  const parts = Path.dirname(path).split('/')
+  const area = parts.slice(0, Math.max(1, parts.length - 2)).join('/')
+  const nearby = sameKind.some(file => file.path.startsWith(`${area}/`))
+  if (nearby) return null
+  const folders = new Map()
+  sameKind.forEach(file => {
+    const folder = Path.basename(Path.dirname(file.path)) === file.path.split('/').pop().split('.')[0]
+      ? Path.dirname(Path.dirname(file.path))
+      : Path.dirname(file.path)
+    folders.set(folder, (folders.get(folder) || 0) + 1)
+  })
+  const [folder, count] = [...folders.entries()].sort((a, b) => b[1] - a[1])[0]
+  return `Create ${key}: no *${suffix} files live near there; most (${count}) are in ${repo}/${folder}.`
+}
+
+const namingNote = (graph, key) => {
+  const repo = key.split('/')[0]
+  const match = Path.basename(key).match(KIND_FILE)
+  if (!match) return null
+  const suffix = `.${match[2]}.${match[3]}`
+  const sameKind = graph.files.filter(file => file.repo === repo && file.path.endsWith(suffix))
+  if (sameKind.length < 3) return null
+  const styles = sameKind.map(file => styleOf(Path.basename(file.path).match(KIND_FILE)[1])).filter(value => value && value !== 'lowercase')
+  const [style, count] = majority(styles)
+  const mine = styleOf(match[1])
+  if (!style || !mine || mine === 'lowercase' || mine === style || count < styles.length * 0.7) return null
+  const example = sameKind.map(file => file.path).sort((a, b) => a.length - b.length)[0]
+  return `Create ${key}: files like it are named in ${style} (for example ${example}); "${match[1]}" is ${mine}.`
+}
+
+/** briefFiles: the files tspl's search found for the task; an edit outside them may mean the search, or the plan, is off. */
+const reviewPlan = (plan, card, graph, { briefFiles = null } = {}) => {
+  const byKey = new Map(graph.files.map(file => [`${file.repo}/${file.path}`, file]))
+  const edit = items(plan, 'edit')
+  const create = items(plan, 'create')
+  const remove = items(plan, 'remove')
+  const planned = new Set([...edit, ...create, ...remove].map(item => item.file))
+  const removed = new Set(remove.map(item => item.file))
+  const warnings = []
+  const companions = []
+
+  const found = briefFiles && briefFiles.length ? new Set(briefFiles) : null
+  edit.forEach(item => {
+    if (!byKey.has(item.file)) warnings.push(`Edit ${item.file}: not in tspl's copy of the code (new, uncommitted, or a typo?).${closestPath(graph, item.file)}`)
+    else if (found && !found.has(item.file) && !TEST_FILE.test(item.file)) warnings.push(`Edit ${item.file}: tspl's search did not find this file for the task; check that the change belongs here, or reword the task so the search finds it.`)
+    if (!item.why) warnings.push(`Edit ${item.file}: say what changes in it.`)
+  })
+  create.forEach(item => {
+    if (byKey.has(item.file)) warnings.push(`Create ${item.file}: this file already exists; edit it instead?`)
+    else {
+      const note = placementNote(graph, item.file)
+      if (note) warnings.push(note)
+      const naming = namingNote(graph, item.file)
+      if (naming) warnings.push(naming)
+    }
+  })
+  remove.forEach(item => {
+    const file = byKey.get(item.file)
+    if (!file) {
+      warnings.push(`Remove ${item.file}: not in tspl's copy of the code.${closestPath(graph, item.file)}`)
+      return
+    }
+    const users = graph.into[file.id]
+      .filter(edge => USED_BY.has(edge.type))
+      .map(edge => graph.files[edge.from])
+      .filter(user => !removed.has(`${user.repo}/${user.path}`))
+    if (users.length) {
+      warnings.push(`Remove ${item.file}: still used by ${users.slice(0, 3).map(user => `${user.repo}/${user.path}`).join(', ')}${users.length > 3 ? ` and ${users.length - 3} more` : ''}.`)
+    }
+  })
+
+  edit.forEach(item => {
+    const file = byKey.get(item.file)
+    if (!file) return
+    const stem = Path.basename(file.path).split('.')[0]
+    const linked = [
+      ...graph.out[file.id].filter(edge => edge.type === 'template' || edge.type === 'imports').map(edge => graph.files[edge.to]),
+      ...graph.into[file.id].filter(edge => edge.type === 'template').map(edge => graph.files[edge.from]),
+    ]
+    linked
+      .filter(other => other.repo === file.repo && !planned.has(`${other.repo}/${other.path}`))
+      .filter(other => Path.basename(other.path).split('.')[0] === stem)
+      .forEach(other => {
+        const key = `${other.repo}/${other.path}`
+        if (!companions.some(entry => entry.file === key)) companions.push({ file: key, with: item.file })
+      })
+  })
+
+  const tests = (Array.isArray(plan.tests) ? plan.tests : [])
+    .map(test => (typeof test === 'string' ? { name: test } : test || {}))
+    .map(test => ({
+      name: String(test.name || '').trim(),
+      file: test.file ? keyOf(test.file) : '',
+      checks: (test.checks || []).map(Number).filter(Boolean),
+      ...(test.command ? { command: String(test.command).trim() } : {}),
+    }))
+    .filter(test => test.name)
+  const covered = new Set(tests.flatMap(test => test.checks))
+  const testCases = (Array.isArray(plan.testCases) ? plan.testCases : [])
+    .map(item => (typeof item === 'string' ? { title: item } : item || {}))
+    .map(item => ({
+      title: String(item.title || '').trim(),
+      steps: (Array.isArray(item.steps) ? item.steps : []).map(step => String(step).trim()).filter(Boolean),
+      expected: String(item.expected || '').trim(),
+    }))
+    .filter(item => item.title)
+    .slice(0, 30)
+  const doneWhen = (card.doneWhen || []).length ? card.doneWhen : testCases.map(item => item.title)
+  if (!(card.doneWhen || []).length && !testCases.length) warnings.push('The task has no test cases: propose them (testCases) so each can be proven.')
+  const uncovered = doneWhen.map((check, i) => ({ check, n: i + 1 })).filter(item => !covered.has(item.n))
+  uncovered.forEach(item => warnings.push(`Done-when ${item.n} "${item.check}" has no test.`))
+  if (!edit.length && !create.length && !remove.length) warnings.push('The plan changes no files.')
+
+  return {
+    edit,
+    create,
+    remove,
+    screens: (Array.isArray(plan.screens) ? plan.screens : []).map(String).filter(Boolean),
+    tests,
+    notes: String(plan.notes || '').trim(),
+    ...(testCases.length && !(card.doneWhen || []).length ? { testCases } : {}),
+    warnings,
+    companions,
+  }
+}
+
+const MARKS = { edit: '✎', create: '➕', remove: '➖' }
+
+const byRepo = review => {
+  const repos = new Map()
+  ;['edit', 'create', 'remove'].forEach(kind => {
+    review[kind].forEach(item => {
+      const repo = item.file.split('/')[0]
+      if (!repos.has(repo)) repos.set(repo, [])
+      repos.get(repo).push({ ...item, kind, path: item.file.slice(repo.length + 1) })
+    })
+  })
+  return repos
+}
+
+const countLine = review => {
+  const total = review.edit.length + review.create.length + review.remove.length
+  return `${total} file${total === 1 ? '' : 's'} in ${byRepo(review).size} repo${byRepo(review).size === 1 ? '' : 's'}:  ${MARKS.edit} ${review.edit.length} edit   ${MARKS.create} ${review.create.length} new   ${MARKS.remove} ${review.remove.length} remove`
+}
+
+const renderChecklist = (review, card, taskId) => {
+  const testsFor = n => review.tests.filter(test => test.checks.includes(n)).map(test => test.name)
+  const files = []
+  byRepo(review).forEach((items, repo) => {
+    files.push(repo)
+    items.forEach(item => files.push(`  ${MARKS[item.kind]} ${item.path}${item.why ? `  — ${item.why}` : ''}`))
+  })
+  return [
+    `PLAN ${taskId}${card.ticket ? ` · ${card.ticket}` : ''} · ${card.type} · ${card.what}`,
+    review.approach ? `Selected approach: ${review.approach.option ? review.approach.option.title : review.approach.optionId} [${review.approach.optionId}] (v${review.approach.version})` : null,
+    card.apps.length ? `Where: ${card.apps.join(', ')}${card.screen ? ` · screen: ${card.screen}` : ''}` : null,
+    '',
+    countLine(review),
+    ...(files.length ? files : ['  (no files)']),
+    ...(review.screens.length ? ['', 'SCREENS', ...review.screens.map(screen => `  • ${screen}`)] : []),
+    '',
+    `TESTS (${review.tests.length})`,
+    ...(review.tests.length
+      ? review.tests.map(test => `  ☐ ${test.name}${test.file ? `  (${test.file})` : ''}${test.command ? `  $ ${test.command}` : ''}${test.checks.length ? `  → done-when ${test.checks.join(', ')}` : ''}`)
+      : ['  —']),
+    ...(card.doneWhen.length
+      ? ['', 'DONE WHEN', ...card.doneWhen.map((check, i) => `  ${i + 1}. ${check}${testsFor(i + 1).length ? '' : '   ⚠ no test yet'}`)]
+      : []),
+    ...(review.notes ? ['', 'NOTES', `  ${review.notes}`] : []),
+    ...(review.companions.length
+      ? ['', 'OFTEN CHANGED TOGETHER (check if needed)', ...review.companions.map(entry => `  ? ${entry.file}  (with ${entry.with.split('/').pop()})`)]
+      : []),
+    '',
+    ...(review.warnings.length
+      ? ['TSPL CHECKS', ...review.warnings.map(warning => `  ⚠ ${warning}`)]
+      : ['TSPL CHECKS', '  ✓ files exist, new files sit with similar files, nothing removed is still used, every done-when has a test']),
+  ]
+    .filter(line => line !== null)
+    .join('\n')
+}
+
+const changesSince = (previous, review) => {
+  if (!previous) return []
+  const lines = []
+  ;['edit', 'create', 'remove'].forEach(kind => {
+    const before = new Set((previous[kind] || []).map(item => item.file))
+    const after = new Set(review[kind].map(item => item.file))
+    after.forEach(file => !before.has(file) && lines.push(`+ ${kind} ${file}`))
+    before.forEach(file => !after.has(file) && lines.push(`- ${kind} ${file}`))
+  })
+  const testsBefore = new Set((previous.tests || []).map(test => test.name))
+  review.tests.filter(test => !testsBefore.has(test.name)).forEach(test => lines.push(`+ test ${test.name}`))
+  ;(previous.tests || []).filter(test => !review.tests.some(item => item.name === test.name)).forEach(test => lines.push(`- test ${test.name}`))
+  return lines
+}
+
+const testParser = command => {
+  if (/\bplaywright\s+test\b/.test(command)) return 'playwright-json'
+  if (/node\s+(--[\w-]+\s+)*--test\b/.test(command)) return 'node-tap'
+  if (/\bjest\b/.test(command)) return 'jest-json'
+  // Vitest's JSON reporter writes the same summary as Jest's
+  if (/\bvitest\b/.test(command)) return 'jest-json'
+  return null
+}
+
+const withReporter = (command, parser) => {
+  if (parser === 'playwright-json' && !/--reporter[ =]json/.test(command)) return `${command} --reporter=json`
+  if (parser === 'jest-json' && /\bvitest\b/.test(command) && !/--reporter[ =]json/.test(command)) return `${command} --reporter=json`
+  return command
+}
+
+/**
+ * Freezes the project's checks, the plan's own runnable tests and the rules into the plan. A test that tspl cannot
+ * parse (or one with no command) is not executable evidence, so the done-when items it covers need a human check.
+ * Folders without a project file keep the legacy plan unchanged.
+ */
+const withSnapshot = (review, card, cwd) => {
+  const found = findProjectConfig(cwd)
+  if (!found) return review
+  const { root, config } = found
+  const names = config.repos.map(repo => repo.name)
+  const checks = []
+  review.tests.forEach((test, i) => {
+    const repo = test.file ? test.file.split('/')[0] : null
+    const parser = test.command ? testParser(test.command) : null
+    if (!parser || !names.includes(repo)) return
+    const browser = parser === 'playwright-json'
+    checks.push({
+      id: `task-test-${i + 1}`,
+      repo,
+      cwd: '.',
+      category: browser ? 'e2e' : 'unit',
+      command: withReporter(test.command, parser),
+      ...(browser ? { artifacts: 'test-results' } : {}),
+      timeoutMs: config.workflow.checkTimeoutMs,
+      required: true,
+      parser,
+      attested: false,
+      criteria: test.checks,
+    })
+  })
+  const acceptance = (card.doneWhen || []).length || (review.testCases || []).length
+  const covered = new Set([...config.checks, ...checks].filter(check => check.required).flatMap(check => check.criteria || []))
+  const manualCriteria = Array.from({ length: acceptance }, (_, i) => i + 1).filter(n => !covered.has(n))
+  return { ...review, workflow: snapshotProject(root, config, { checks, manualCriteria, acceptance }) }
+}
+
+module.exports = {
+  withSnapshot,
+  reviewPlan,
+  renderChecklist,
+  changesSince,
+  byRepo,
+  countLine,
+  MARKS,
+}