@newt-kit/plan 0.0.0-stage → 0.10.0

package/plan/compare.ts

@@ -0,0 +1,127 @@
+import type { AppMap } from '../map/app-map'
+import type { Plan } from './plan.schema'
+import { piecesNamed } from './resolve'
+
+/**
+ * - `done`: the branch does what the plan says.
+ * - `missing`: the plan says it, the branch does not.
+ * - `different`: the branch does something else with it (removes what was to change).
+ * - `unplanned`: the branch does it, the plan does not say it.
+ */
+export type Verdict = 'done' | 'missing' | 'different' | 'unplanned'
+
+export type Check = {
+  /** A module's, a piece's id, or a relation as `<from> <kind> <to>`. */
+  id: string
+  what: 'module' | 'piece' | 'relation'
+  planned?: 'new' | 'modified' | 'removed'
+  found?: 'new' | 'modified' | 'removed'
+  verdict: Verdict
+  /** Whether it fails the review: what is missing or different, and a module or a piece unplanned. */
+  failing: boolean
+}
+
+export type StepState = 'done' | 'partial' | 'notStarted' | 'nothingToCheck'
+/** A step and how many of the things it names are done. */
+export type StepCheck = { title: string, state: StepState, done: number, of: number }
+
+export type Comparison = { checks: Check[], steps: StepCheck[], failing: number }
+
+/**
+ * A plan held against what a branch did (`diffMaps(base, head)`): each thing it says, done
+ * or not, what the branch did that it does not say, and each step done when its pieces are.
+ */
+export function comparePlan(plan: Plan, found: Plan, head: AppMap): Comparison {
+  const checks: Check[] = []
+  const foundModules = new Map(found.modules.map(module => [module.id, module.status]))
+  const foundPieces = new Map(found.pieces.map(piece => [piece.id, piece.status]))
+  const keyOf = (relation: { kind: string, from: string, to: string }) => `${relation.from} ${relation.kind} ${relation.to}`
+  const foundRelations = new Map(found.relations.map(relation => [keyOf(relation), relation.status]))
+  const headPieces = new Map(head.modules.flatMap(module => module.pieces.map(piece => [piece.id, piece] as const)))
+  // A use case whose calls or emits changed, or that an event now triggers, is modified too.
+  const touched = new Set(found.relations.flatMap(relation => relation.kind === 'triggers' ? [relation.to] : [relation.from]))
+  const foundStatusOf = (id: string) => foundPieces.get(id) ?? (touched.has(id) && headPieces.has(id) ? 'modified' as const : undefined)
+
+  const verdictOf = (planned: Check['planned'], status: Check['found']): Verdict => {
+    if (planned === status) {
+      return 'done'
+    }
+    if (planned === 'modified' && status === 'new') {
+      return 'done'
+    }
+    if (status === undefined) {
+      return 'missing'
+    }
+    return 'different'
+  }
+  const add = (check: Omit<Check, 'failing'>) => {
+    const failing = check.verdict === 'missing' || check.verdict === 'different' || (check.verdict === 'unplanned' && check.what !== 'relation' && check.found !== 'modified')
+    checks.push({ ...check, failing })
+  }
+
+  const plannedModules = new Set<string>()
+  for (const module of plan.modules) {
+    if (!module.status) {
+      continue
+    }
+    plannedModules.add(module.id)
+    add({ id: module.id, what: 'module', planned: module.status, ...found_(foundModules.get(module.id)), verdict: verdictOf(module.status, foundModules.get(module.id)) })
+  }
+  for (const [id, status] of foundModules) {
+    if (!plannedModules.has(id)) {
+      add({ id, what: 'module', ...found_(status), verdict: 'unplanned' })
+    }
+  }
+
+  const plannedPieces = new Set<string>()
+  for (const piece of plan.pieces) {
+    if (!piece.status) {
+      continue
+    }
+    plannedPieces.add(piece.id)
+    const status = foundStatusOf(piece.id)
+    const kindChanged = piece.status === 'new' && headPieces.has(piece.id) && headPieces.get(piece.id)!.kind !== piece.kind
+    add({ id: piece.id, what: 'piece', planned: piece.status, ...found_(status), verdict: kindChanged ? 'different' : verdictOf(piece.status, status) })
+  }
+  for (const [id, status] of foundPieces) {
+    if (!plannedPieces.has(id)) {
+      add({ id, what: 'piece', ...found_(status), verdict: 'unplanned' })
+    }
+  }
+
+  const plannedRelations = new Set<string>()
+  for (const relation of plan.relations) {
+    const key = keyOf(relation)
+    plannedRelations.add(key)
+    add({ id: key, what: 'relation', planned: relation.status, ...found_(foundRelations.get(key)), verdict: verdictOf(relation.status, foundRelations.get(key)) })
+  }
+  for (const [key, status] of foundRelations) {
+    if (!plannedRelations.has(key)) {
+      add({ id: key, what: 'relation', found: status, verdict: 'unplanned' })
+    }
+  }
+
+  // A step is done when the pieces it names are, and the relations between them.
+  const planned = checks.filter(check => check.planned !== undefined)
+  const steps = plan.steps.map(step => {
+    const named = new Set(step.focus ?? piecesNamed(`${step.title} ${step.text ?? ''}`))
+    const own = planned.filter(check => {
+      if (check.what === 'piece') {
+        return named.has(check.id)
+      }
+      if (check.what !== 'relation') {
+        return false
+      }
+      const [from, , to] = check.id.split(' ')
+      return named.has(from!) && named.has(to!)
+    })
+    const done = own.filter(check => check.verdict === 'done').length
+    const state: StepState = own.length === 0 ? 'nothingToCheck' : done === own.length ? 'done' : done === 0 ? 'notStarted' : 'partial'
+    return { title: step.title, state, done, of: own.length }
+  })
+
+  return { checks, steps, failing: checks.filter(check => check.failing).length }
+}
+
+const found_ = (status: Check['found']) => status === undefined ? {} : { found: status }
+

package/plan/diff.ts

@@ -0,0 +1,50 @@
+import { moduleOf, type AppMap, type MapPiece } from '../map/app-map'
+import type { Plan } from './plan.schema'
+
+/**
+ * What `head` (a branch) adds to, changes in and takes away from `base` (main), said as a
+ * plan: laid on `base` by `resolvePlan`, it draws the change. A piece is modified when its
+ * code is (its hash), or a schedule's cron; one whose calls or emits change is found
+ * modified by `resolvePlan` too.
+ */
+export function diffMaps(base: AppMap, head: AppMap, words: { title: string, subtitle?: string, language?: Plan['language'] }): Plan {
+  const baseContexts = new Set(base.contexts.map(context => context.name))
+  const headContexts = new Set(head.contexts.map(context => context.name))
+  const baseModules = new Map(base.modules.map(module => [module.id, module]))
+  const headModules = new Map(head.modules.map(module => [module.id, module]))
+  const piecesOf = (map: AppMap) => new Map(map.modules.flatMap(module => module.pieces.map(piece => [piece.id, piece] as const)))
+  const basePieces = piecesOf(base), headPieces = piecesOf(head)
+  const keyOf = (relation: { kind: string, from: string, to: string }) => `${relation.kind} ${relation.from} ${relation.to}`
+  const baseRelations = new Map(base.relations.map(relation => [keyOf(relation), relation]))
+  const headRelations = new Map(head.relations.map(relation => [keyOf(relation), relation]))
+
+  const changed = (before: MapPiece, after: MapPiece) => before.kind !== after.kind || before.cron !== after.cron || before.hash !== after.hash
+
+  return {
+    version: 1,
+    language: words.language ?? 'en',
+    title: words.title,
+    ...(words.subtitle ? { subtitle: words.subtitle } : {}),
+    contexts: [
+      ...[...headContexts].filter(name => !baseContexts.has(name)).map(name => ({ name, status: 'new' as const })),
+      ...[...baseContexts].filter(name => !headContexts.has(name)).map(name => ({ name, status: 'removed' as const })),
+    ],
+    modules: [
+      ...[...headModules.values()].filter(module => !baseModules.has(module.id)).map(module => ({ id: module.id, status: 'new' as const, ...(module.port ? { port: true } : {}) })),
+      ...[...baseModules.values()].filter(module => !headModules.has(module.id)).map(module => ({ id: module.id, status: 'removed' as const })),
+    ],
+    pieces: [
+      ...[...headPieces.values()].filter(piece => !basePieces.has(piece.id)).map(piece => ({ id: piece.id, kind: piece.kind, status: 'new' as const, ...(piece.cron ? { cron: piece.cron } : {}) })),
+      // A piece of a module taken away goes with its module.
+      ...[...basePieces.values()].filter(piece => !headPieces.has(piece.id) && headModules.has(moduleOf(piece.id))).map(piece => ({ id: piece.id, kind: piece.kind, status: 'removed' as const })),
+      ...[...headPieces.values()].filter(piece => basePieces.has(piece.id) && changed(basePieces.get(piece.id)!, piece)).map(piece => ({ id: piece.id, kind: basePieces.get(piece.id)!.kind, status: 'modified' as const })),
+    ],
+    relations: [
+      ...[...headRelations.values()].filter(relation => !baseRelations.has(keyOf(relation))).map(({ kind, from, to }) => ({ kind, from, to, status: 'new' as const })),
+      // What a removed piece was in goes with it.
+      ...[...baseRelations.values()].filter(relation => !headRelations.has(keyOf(relation)) && headPieces.has(relation.from) && headPieces.has(relation.to)).map(({ kind, from, to }) => ({ kind, from, to, status: 'removed' as const })),
+    ],
+    steps: [],
+    rules: [],
+  }
+}

package/plan/markdown.ts

@@ -0,0 +1,50 @@
+import type { Check } from './compare'
+import type { Review } from './review'
+
+const WORDS = {
+  en: {
+    title: (title: string) => `## Review: ${title}`, nothing: 'The branch changes no module, use case, event or schedule.',
+    changes: '### What the branch changes', steps: '### The plan\'s steps', checks: '### Against the plan', rules: '### Rules',
+    verdict: { done: '✓ done', missing: '✗ missing', different: '≠ different', unplanned: '+ not planned' },
+    state: { done: 'done', partial: 'half done', notStarted: 'not started', nothingToCheck: 'nothing to check' },
+    status: { new: 'new', modified: 'modified', removed: 'removed' },
+    failing: (n: number) => n ? `**${n} to look at.**` : '**The branch does what the plan says.**',
+  },
+  es: {
+    title: (title: string) => `## Revisión: ${title}`, nothing: 'La rama no cambia ningún módulo, caso de uso, evento ni tarea programada.',
+    changes: '### Lo que cambia la rama', steps: '### Los pasos del plan', checks: '### Frente al plan', rules: '### Reglas',
+    verdict: { done: '✓ cumplido', missing: '✗ falta', different: '≠ distinto', unplanned: '+ no planeado' },
+    state: { done: 'completo', partial: 'a medias', notStarted: 'sin empezar', nothingToCheck: 'nada que comprobar' },
+    status: { new: 'nuevo', modified: 'modificado', removed: 'eliminado' },
+    failing: (n: number) => n ? `**${n} cosa${n === 1 ? '' : 's'} que mirar.**` : '**La rama hace lo que dice el plan.**',
+  },
+}
+
+/** A review as Markdown, for a pull request's comment. */
+export function reviewMarkdown({ resolved, comparison }: Review): string {
+  const words = WORDS[resolved.language]
+  const lines = [words.title(resolved.title), '']
+  const changed = resolved.modules.flatMap(module => module.pieces).filter(piece => piece.status === 'new' || piece.status === 'modified' || piece.status === 'removed')
+  if (!comparison) {
+    lines.push(words.changes, '')
+    if (!changed.length) {
+      lines.push(words.nothing)
+    }
+    for (const piece of changed) {
+      lines.push(`- \`${piece.id}\` ${words.status[piece.status as 'new' | 'modified' | 'removed']}`)
+    }
+  } else {
+    lines.push(words.failing(comparison.failing), '', words.steps, '')
+    comparison.steps.forEach((step, at) => lines.push(`${at + 1}. ${step.title}: ${words.state[step.state]}${step.state === 'partial' ? ` (${step.done}/${step.of})` : ''}`))
+    lines.push('', words.checks, '')
+    const order = (check: Check) => Number(!check.failing)
+    for (const check of [...comparison.checks].sort((a, b) => order(a) - order(b))) {
+      lines.push(`- ${words.verdict[check.verdict]}: \`${check.id}\``)
+    }
+  }
+  lines.push('', words.rules, '')
+  for (const rule of resolved.rules) {
+    lines.push(`- ${rule.ok ? '✓' : '!'} ${rule.text}`)
+  }
+  return `${lines.join('\n')}\n`
+}

package/plan/plan.schema.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod'
+
+/**
+ * A plan: what a feature does to an application's map, and how to tell it. Only what it
+ * changes is written; everything else is the map's, and whatever a change touches but
+ * does not change (a use case it calls, an event it listens to) is found, not written.
+ *
+ * Written by hand or by an agent, read by `resolvePlan`, which refuses one that speaks of
+ * a piece the map has not, or adds one it has.
+ */
+
+/** `boards/card` */
+export const ModuleIdSchema = z.string().regex(/^[a-z][\w-]*\/[a-zA-Z][\w]*$/, 'A module id is <context>/<module>: boards/card')
+/** `boards/card.setDueDate` */
+export const PieceIdSchema = z.string().regex(/^[a-z][\w-]*\/[a-zA-Z][\w]*\.[a-zA-Z][\w]*$/, 'A piece id is <context>/<module>.<name>: boards/card.setDueDate')
+
+export const PieceKindSchema = z.enum(['useCase', 'event', 'schedule'])
+export const RelationKindSchema = z.enum(['emits', 'triggers', 'calls'])
+
+const why = z.string().min(1).optional()
+
+export const PlanSchema = z.strictObject({
+  version: z.literal(1),
+  /** The language of the page's own words; the plan's are in whatever it is written in. */
+  language: z.enum(['en', 'es']).default('en'),
+  title: z.string().min(1),
+  subtitle: z.string().min(1).optional(),
+  /** Contexts it adds or takes away. */
+  contexts: z.array(z.strictObject({ name: z.string().regex(/^[a-z][\w-]*$/), status: z.enum(['new', 'removed']) })).default([]),
+  /** Modules it adds or takes away; one with no status only says why it matters. */
+  modules: z.array(z.strictObject({
+    id: ModuleIdSchema,
+    status: z.enum(['new', 'removed']).optional(),
+    /** A port: something its modules call that is no module (a mailer, a search index). */
+    port: z.boolean().optional(),
+    why,
+  })).default([]),
+  /** Use cases, events and schedules it adds, changes or takes away; one with no status only says why it matters. */
+  pieces: z.array(z.strictObject({
+    id: PieceIdSchema,
+    kind: PieceKindSchema,
+    status: z.enum(['new', 'modified', 'removed']).optional(),
+    /** A new schedule's cron expression. */
+    cron: z.string().min(1).optional(),
+    why,
+  })).default([]),
+  /**
+   * How pieces meet, added or taken away: a use case `emits` an event of its module; an
+   * event or a schedule `triggers` a use case (a subscription, whose queue is found); a use
+   * case `calls` a use case of another module or of a port.
+   */
+  relations: z.array(z.strictObject({
+    kind: RelationKindSchema,
+    from: PieceIdSchema,
+    to: PieceIdSchema,
+    status: z.enum(['new', 'removed']),
+    why,
+  })).default([]),
+  /**
+   * How it is built, step by step: each one a commit that leaves the application working,
+   * the whole a branch and its pull request. A piece is named in braces,
+   * `{boards/card.setDueDate}`, and drawn as itself; a step's pieces are those it names,
+   * or those of `focus`. A review finds each step done when its pieces are.
+   */
+  steps: z.array(z.strictObject({
+    title: z.string().min(1),
+    text: z.string().min(1).optional(),
+    focus: z.array(PieceIdSchema).optional(),
+  })).default([]),
+  /** What was checked by hand; `checkPlan` adds what it checks itself. */
+  rules: z.array(z.strictObject({ ok: z.boolean(), text: z.string().min(1) })).default([]),
+})
+
+export type Plan = z.output<typeof PlanSchema>
+export type PlanInput = z.input<typeof PlanSchema>

package/plan/resolve.ts

@@ -0,0 +1,314 @@
+import { moduleOf, splitModuleId, type AppMap, type MapRelation, type PieceKind, type RelationKind } from '../map/app-map'
+import type { Plan } from './plan.schema'
+
+/**
+ * - `new`, `modified`, `removed`: what the plan says it does.
+ * - `consumed`: there before and left as it is, but what is new or taken away meets it
+ *   (an event a new use case listens to, a use case a new one calls).
+ * - `unchanged`: the rest of the application.
+ */
+export type Status = 'new' | 'modified' | 'consumed' | 'unchanged' | 'removed'
+
+export type ResolvedPiece = {
+  id: string
+  kind: PieceKind
+  name: string
+  status: Status
+  cron?: string
+  why?: string
+}
+
+export type ResolvedModule = {
+  id: string
+  context: string
+  name: string
+  port: boolean
+  status: Status
+  why?: string
+  pieces: ResolvedPiece[]
+}
+
+export type ResolvedRelation = {
+  kind: RelationKind
+  from: string
+  to: string
+  status: 'new' | 'removed' | 'unchanged'
+  queue?: string
+  conditional?: boolean
+  why?: string
+}
+
+/** `map`: the application as it is; `plan`: a feature to build; `review`: a branch's change. */
+export type Mode = 'map' | 'plan' | 'review'
+
+export type ResolvedStep = { title: string, text?: string, focus: string[] }
+
+export type ResolvedPlan = {
+  mode: Mode
+  language: Plan['language']
+  title: string
+  subtitle?: string
+  contexts: { name: string, uses: string[], status: 'new' | 'removed' | 'unchanged' }[]
+  modules: ResolvedModule[]
+  relations: ResolvedRelation[]
+  steps: ResolvedStep[]
+  rules: { ok: boolean, text: string }[]
+}
+
+export class PlanError extends Error {
+  constructor(readonly problems: string[]) {
+    super(`The plan does not fit the map:\n- ${problems.join('\n- ')}`)
+  }
+}
+
+/** The queue newt names a subscription by: `reminder.schedule.on.card.dueDateSet`. */
+export function queueOf(from: string, to: string): string {
+  const name = (id: string) => id.slice(id.indexOf('/') + 1)
+  return `${name(to)}.on.${name(from)}`
+}
+
+/** The pieces a text names: `{boards/card.setDueDate}`. */
+export function piecesNamed(text: string): string[] {
+  return [...text.matchAll(/\{([a-z][\w-]*\/[a-zA-Z]\w*\.[a-zA-Z]\w*)\}/g)].map(match => match[1]!)
+}
+
+/**
+ * The plan laid on the map: every module and piece with its status, every relation with
+ * its own. Throws a `PlanError` saying each thing the plan says that the map contradicts.
+ */
+export function resolvePlan(map: AppMap, plan: Plan, mode: Mode = 'plan'): ResolvedPlan {
+  const problems: string[] = []
+  const contexts = new Map(map.contexts.map(context => [context.name, { name: context.name, uses: [...context.uses], status: 'unchanged' as 'new' | 'removed' | 'unchanged' }]))
+  const modules = new Map<string, ResolvedModule>()
+  const pieces = new Map<string, ResolvedPiece>()
+  for (const module of map.modules) {
+    const resolved: ResolvedModule = { id: module.id, context: module.context, name: module.name, port: module.port, status: 'unchanged', pieces: [] }
+    modules.set(module.id, resolved)
+    for (const piece of module.pieces) {
+      const each: ResolvedPiece = { id: piece.id, kind: piece.kind, name: piece.name, status: 'unchanged', ...(piece.cron ? { cron: piece.cron } : {}) }
+      resolved.pieces.push(each)
+      pieces.set(piece.id, each)
+    }
+  }
+
+  for (const context of plan.contexts) {
+    const found = contexts.get(context.name)
+    if (context.status === 'new') {
+      if (found) {
+        problems.push(`The context ${context.name} is new, but the map has it`)
+      } else {
+        contexts.set(context.name, { name: context.name, uses: [], status: 'new' })
+      }
+    } else if (!found) {
+      problems.push(`The context ${context.name} is removed, but the map has it not`)
+    } else {
+      found.status = 'removed'
+    }
+  }
+
+  for (const module of plan.modules) {
+    const found = modules.get(module.id)
+    const { context, module: name } = splitModuleId(module.id)
+    if (module.status === 'new') {
+      if (found) {
+        problems.push(`The module ${module.id} is new, but the map has it`)
+        continue
+      }
+      if (!contexts.has(context)) {
+        problems.push(`The module ${module.id} is of the context ${context}, which neither the map nor the plan has`)
+        continue
+      }
+      modules.set(module.id, { id: module.id, context, name, port: module.port ?? context === 'ports', status: 'new', pieces: [], ...(module.why ? { why: module.why } : {}) })
+      continue
+    }
+    if (!found) {
+      problems.push(`The plan speaks of the module ${module.id}, which the map has not`)
+      continue
+    }
+    if (module.status === 'removed') {
+      found.status = 'removed'
+    }
+    if (module.why) {
+      found.why = module.why
+    }
+  }
+
+  for (const piece of plan.pieces) {
+    const found = pieces.get(piece.id)
+    if (piece.status === 'new') {
+      if (found) {
+        problems.push(`${piece.id} is new, but the map has it: say modified`)
+        continue
+      }
+      const module = modules.get(moduleOf(piece.id))
+      if (!module) {
+        problems.push(`${piece.id} is of the module ${moduleOf(piece.id)}, which neither the map nor the plan has`)
+        continue
+      }
+      const each: ResolvedPiece = { id: piece.id, kind: piece.kind, name: piece.id.slice(piece.id.indexOf('.') + 1), status: 'new', ...(piece.cron ? { cron: piece.cron } : {}), ...(piece.why ? { why: piece.why } : {}) }
+      module.pieces.push(each)
+      pieces.set(piece.id, each)
+      continue
+    }
+    if (!found) {
+      problems.push(`The plan speaks of ${piece.id}, which the map has not`)
+      continue
+    }
+    if (found.kind !== piece.kind) {
+      problems.push(`${piece.id} is ${article(found.kind)} in the map, not ${article(piece.kind)}`)
+    }
+    if (piece.status) {
+      found.status = piece.status
+    }
+    if (piece.why) {
+      found.why = piece.why
+    }
+  }
+  for (const module of modules.values()) {
+    if (module.status === 'removed') {
+      for (const piece of module.pieces) {
+        piece.status = 'removed'
+      }
+    }
+    if (module.status === 'new') {
+      for (const piece of module.pieces) {
+        if (piece.status !== 'new') {
+          problems.push(`${piece.id} is in the new module ${module.id}, so it is new too`)
+        }
+      }
+    }
+  }
+
+  const relations = new Map<string, ResolvedRelation>()
+  const keyOf = (relation: { kind: string, from: string, to: string }) => `${relation.kind} ${relation.from} ${relation.to}`
+  for (const relation of map.relations) {
+    relations.set(keyOf(relation), withStatus(relation, 'unchanged'))
+  }
+
+  for (const relation of plan.relations) {
+    const from = pieces.get(relation.from), to = pieces.get(relation.to)
+    if (!from) {
+      problems.push(`A relation from ${relation.from}, which neither the map nor the plan has`)
+      continue
+    }
+    if (!to) {
+      problems.push(`A relation to ${relation.to}, which neither the map nor the plan has`)
+      continue
+    }
+    const found = relations.get(keyOf(relation))
+    if (relation.status === 'removed') {
+      if (!found) {
+        problems.push(`The plan takes away ${relation.from} ${relation.kind} ${relation.to}, which the map has not`)
+      } else {
+        found.status = 'removed'
+        if (relation.why) {
+          found.why = relation.why
+        }
+      }
+      continue
+    }
+    if (found) {
+      problems.push(`${relation.from} ${relation.kind} ${relation.to} is new, but the map has it`)
+      continue
+    }
+    const wrong = kindProblem(relation.kind, from, to)
+    if (wrong) {
+      problems.push(wrong)
+      continue
+    }
+    if (from.status === 'removed' || to.status === 'removed') {
+      problems.push(`${relation.from} ${relation.kind} ${relation.to} is new, but one of its ends is removed`)
+      continue
+    }
+    relations.set(keyOf(relation), {
+      kind: relation.kind, from: relation.from, to: relation.to, status: 'new',
+      ...(relation.kind === 'triggers' ? { queue: queueOf(relation.from, relation.to) } : {}),
+      ...(relation.why ? { why: relation.why } : {}),
+    })
+  }
+  // What a removed piece was in goes with it.
+  for (const relation of relations.values()) {
+    if (relation.status === 'unchanged' && (pieces.get(relation.from)?.status === 'removed' || pieces.get(relation.to)?.status === 'removed')) {
+      relation.status = 'removed'
+    }
+  }
+
+  // What changes meets what stays: the use case a new call or emit starts from has new
+  // code, so it is modified; whatever else a change meets is consumed.
+  for (const relation of relations.values()) {
+    if (relation.status === 'unchanged') {
+      continue
+    }
+    const from = pieces.get(relation.from)!, to = pieces.get(relation.to)!
+    if (from.status === 'unchanged') {
+      from.status = relation.kind === 'triggers' ? 'consumed' : 'modified'
+    }
+    if (to.status === 'unchanged') {
+      to.status = 'consumed'
+    }
+  }
+
+  for (const module of modules.values()) {
+    if (module.status !== 'unchanged') {
+      continue
+    }
+    const statuses = new Set(module.pieces.map(piece => piece.status))
+    // A new subscription is written in the module that listens: its workers change.
+    const listensAnew = [...relations.values()].some(relation => relation.kind === 'triggers' && relation.status !== 'unchanged' && moduleOf(relation.to) === module.id)
+    if (statuses.has('new') || statuses.has('modified') || statuses.has('removed') || listensAnew) {
+      module.status = 'modified'
+    } else if (statuses.has('consumed')) {
+      module.status = 'consumed'
+    }
+  }
+
+  const steps = plan.steps.map((step, at) => {
+    const named = piecesNamed(`${step.title} ${step.text ?? ''}`)
+    for (const id of [...named, ...step.focus ?? []]) {
+      if (!pieces.has(id)) {
+        problems.push(`Step ${at + 1} names ${id}, which neither the map nor the plan has`)
+      }
+    }
+    return { title: step.title, ...(step.text ? { text: step.text } : {}), focus: step.focus ?? named }
+  })
+
+  if (problems.length) {
+    throw new PlanError(problems)
+  }
+  return {
+    mode,
+    language: plan.language,
+    title: plan.title,
+    ...(plan.subtitle ? { subtitle: plan.subtitle } : {}),
+    contexts: [...contexts.values()],
+    modules: [...modules.values()],
+    relations: [...relations.values()],
+    steps,
+    rules: plan.rules,
+  }
+}
+
+const article = (kind: PieceKind) => kind === 'event' ? 'an event' : kind === 'schedule' ? 'a schedule' : 'a use case'
+
+function withStatus(relation: MapRelation, status: ResolvedRelation['status']): ResolvedRelation {
+  return { kind: relation.kind, from: relation.from, to: relation.to, status, ...(relation.queue ? { queue: relation.queue } : {}), ...(relation.conditional ? { conditional: true } : {}) }
+}
+
+function kindProblem(kind: RelationKind, from: ResolvedPiece, to: ResolvedPiece): string | null {
+  const says = `${from.id} ${kind} ${to.id}`
+  if (kind === 'emits') {
+    if (from.kind !== 'useCase' || to.kind !== 'event') {
+      return `${says}: a use case emits an event`
+    }
+    if (moduleOf(from.id) !== moduleOf(to.id)) {
+      return `${says}: a use case emits only its own module's events (its entity tracks them)`
+    }
+  }
+  if (kind === 'triggers' && (from.kind === 'useCase' || to.kind !== 'useCase')) {
+    return `${says}: an event or a schedule triggers a use case`
+  }
+  if (kind === 'calls' && (from.kind !== 'useCase' || to.kind !== 'useCase')) {
+    return `${says}: a use case calls a use case`
+  }
+  return null
+}

package/plan/review.ts

@@ -0,0 +1,34 @@
+import type { AppMap } from '../map/app-map'
+import { pageData, type PageData } from '../render/page-data'
+import { checkPlan } from './check'
+import { comparePlan, type Comparison } from './compare'
+import { diffMaps } from './diff'
+import type { Plan } from './plan.schema'
+import { piecesNamed, resolvePlan, type ResolvedPlan } from './resolve'
+
+export type Review = { resolved: ResolvedPlan, comparison?: Comparison, data: PageData }
+
+/**
+ * A branch's change, `head` against `base`, drawn on `base` with the rules checked; with a
+ * plan, held against it too: each thing it says done or not, and each of its steps. The
+ * command line and a review's page (when a plan is loaded in it) both make it here.
+ */
+export function reviewOf(base: AppMap, head: AppMap, options: { title: string, language?: Plan['language'], plan?: Plan }): Review {
+  const { plan } = options
+  const language = plan?.language ?? options.language ?? 'en'
+  const found = diffMaps(base, head, { title: plan?.title ?? options.title, language, ...(plan?.subtitle ? { subtitle: plan.subtitle } : {}) })
+  const drawn = resolvePlan(base, found, 'review')
+  const resolved = { ...drawn, rules: [...checkPlan(drawn), ...plan?.rules ?? []] }
+  if (!plan) {
+    return { resolved, data: pageData(resolved, { maps: { base, head } }) }
+  }
+
+  const comparison = comparePlan(plan, found, head)
+  const drawnPieces = new Set(resolved.modules.flatMap(module => module.pieces.map(piece => piece.id)))
+  const steps = plan.steps.map((step, at) => ({
+    ...(step.text ? { text: step.text } : {}),
+    focus: (step.focus ?? piecesNamed(`${step.title} ${step.text ?? ''}`)).filter(id => drawnPieces.has(id)),
+    ...comparison.steps[at]!,
+  }))
+  return { resolved, comparison, data: pageData(resolved, { steps, checks: comparison.checks, maps: { base, head } }) }
+}

package/render/browser.ts

@@ -0,0 +1,16 @@
+// What a review's page runs when a plan is loaded in it: the same review the command line makes.
+import { PlanSchema } from '../plan/plan.schema'
+import { reviewOf } from '../plan/review'
+import type { PageData } from './page-data'
+
+/** The page's data for a review held against the plan in `json`, or the problems with it. */
+function reviewWithPlan(data: PageData, json: unknown): { data: PageData } | { problems: string[] } {
+  const parsed = PlanSchema.safeParse(json)
+  if (!parsed.success) {
+    return { problems: parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`) }
+  }
+  const { base, head } = data.maps!
+  return { data: reviewOf(base, head, { title: data.title, plan: parsed.data }).data }
+}
+
+Object.assign(globalThis, { newtPlan: { reviewWithPlan } })