@newt-kit/plan 0.0.0-stage → 0.10.0

package/map/read-map.ts

@@ -0,0 +1,453 @@
+import { dirname, resolve, sep } from 'node:path'
+import ts from 'typescript'
+import { moduleOf, type AppMap, type MapModule, type MapPiece, type MapRelation } from './app-map'
+
+/**
+ * The map of an application, read from its code with TypeScript's checker, never run.
+ *
+ * newt's layout makes it readable: a module is the `<Name>_Module` class of
+ * `<context>/modules/<module>/<module>.module.ts`, its use cases its `@UseCase` methods, its
+ * events those of `eventsOf(…)` and its schedules `schedules.define(…)`. A worker is
+ * `module.on(event, 'useCase')`. From each use case every call is followed into the entity
+ * and the module's own helpers: `trackEvent(new X(…))` emits, another module's use case or
+ * a port (`this.deps.mailer.send`) is a call. What falls outside this is a warning.
+ */
+export type ReadMap = { map: AppMap, warnings: string[] }
+
+type ModuleInfo = {
+  module: MapModule
+  /** Its fields that hold a schedule or an event: `nightly` → its id. */
+  fields: Map<string, string>
+  /** Its fields that hold `eventsOf(…)`: `events` → `created` → its id. */
+  groups: Map<string, Map<string, string>>
+  declaration: ts.ClassDeclaration
+}
+
+const lowerFirst = (text: string) => text.charAt(0).toLowerCase() + text.slice(1)
+const hashOf = (texts: string[]) => Bun.hash(texts.join('\n')).toString(36)
+
+/** The context a file is of, by newt's layout: the folder that holds `modules/`. */
+export function contextOfFile(fileName: string): string | null {
+  const parts = resolve(fileName).split(sep)
+  const at = parts.lastIndexOf('modules')
+  const insideAModule = at > 0 && at < parts.length - 2
+  return insideAModule ? parts[at - 1]! : null
+}
+
+/** `Card_Module` → `card`. */
+const moduleNameOfClass = (className: string) => lowerFirst(className.replace(/_Module$/, ''))
+
+/** The programs of a tsconfig: its own files, and those of the projects it references. */
+function programsOf(tsconfigPath: string, seen = new Set<string>()): ts.Program[] {
+  const path = resolve(tsconfigPath)
+  if (seen.has(path)) {
+    return []
+  }
+  seen.add(path)
+  const config = ts.getParsedCommandLineOfConfigFile(path, {}, {
+    ...ts.sys,
+    onUnRecoverableConfigFileDiagnostic: diagnostic => {
+      throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
+    },
+  })
+  if (!config) {
+    throw new Error(`No TypeScript project at ${tsconfigPath}`)
+  }
+  const own = config.fileNames.length ? [ts.createProgram(config.fileNames, config.options)] : []
+  const referenced = (config.projectReferences ?? []).flatMap(reference => programsOf(ts.resolveProjectReferencePath(reference), seen))
+  return [...own, ...referenced]
+}
+
+/** Reads the map of the application whose code `tsconfigPath` holds, under `within` if given. */
+export function readMap(tsconfigPath: string, within?: string): ReadMap {
+  const root = within === undefined ? null : resolve(within)
+  const warnings: string[] = []
+  const modules = new Map<string, ModuleInfo>()
+  const pieces = new Map<string, MapPiece>()
+  const relations = new Map<string, MapRelation>()
+  const uses = new Map<string, Set<string>>()
+  const readFiles = new Set<string>()
+
+  const relate = (relation: MapRelation) => {
+    const key = `${relation.kind} ${relation.from} ${relation.to}`
+    const found = relations.get(key)
+    // Emitted always somewhere wins over emitted under a condition elsewhere.
+    if (found?.conditional && !relation.conditional) {
+      delete found.conditional
+    }
+    if (!found) {
+      relations.set(key, relation)
+    }
+  }
+  const addPiece = (piece: MapPiece): void => {
+    const module = modules.get(moduleOf(piece.id))?.module
+    if (!module) {
+      warnings.push(`${piece.id} is of no module the code has`)
+      return
+    }
+    if (pieces.has(piece.id)) {
+      return
+    }
+    pieces.set(piece.id, piece)
+    module.pieces.push(piece)
+  }
+  const portModule = (name: string): ModuleInfo => {
+    const id = `ports/${name}`
+    let found = modules.get(id)
+    if (!found) {
+      found = { module: { id, context: 'ports', name, port: true, pieces: [] }, fields: new Map(), groups: new Map(), declaration: undefined as never }
+      modules.set(id, found)
+    }
+    return found
+  }
+
+  for (const program of programsOf(tsconfigPath)) {
+    const checker = program.getTypeChecker()
+    const sources = program.getSourceFiles().filter(source => {
+      const file = resolve(source.fileName)
+      const isApplicationCode = !file.includes(`${sep}node_modules${sep}`) && !source.isDeclarationFile
+      const isWithin = root === null || file.startsWith(root + sep)
+      return isApplicationCode && isWithin && contextOfFile(file) !== null && !readFiles.has(file)
+    })
+    sources.forEach(source => readFiles.add(resolve(source.fileName)))
+
+    const keyOfClass = (declaration: ts.ClassDeclaration) => `${resolve(declaration.getSourceFile().fileName)}#${declaration.name?.text}`
+    const byClass = new Map<string, ModuleInfo>()
+
+    const classOf = (node: ts.Node | undefined): ts.ClassDeclaration | undefined => {
+      for (let at = node; at; at = at.parent) {
+        if (ts.isClassDeclaration(at)) {
+          return at
+        }
+      }
+      return undefined
+    }
+    const aliased = (symbol: ts.Symbol | undefined) => symbol && symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol
+    const isModuleClass = (node: ts.Node | undefined): node is ts.ClassDeclaration & { name: ts.Identifier } =>
+      node !== undefined && ts.isClassDeclaration(node) && node.name !== undefined && /_Module$/.test(node.name.text)
+    const isUseCase = (node: ts.Node): node is ts.MethodDeclaration =>
+      ts.isMethodDeclaration(node) && (ts.getDecorators(node) ?? []).some(each => {
+        const expression = ts.isCallExpression(each.expression) ? each.expression.expression : each.expression
+        return ts.isIdentifier(expression) && expression.text === 'UseCase'
+      })
+    /** The module class a value's type is: `deps.sales.order` → Order_Module. */
+    const moduleOfType = (expression: ts.Expression): ModuleInfo | undefined => {
+      const declaration = checker.getTypeAtLocation(expression).getSymbol()?.declarations?.find(isModuleClass)
+      return declaration ? byClass.get(keyOfClass(declaration)) : undefined
+    }
+
+    /** An event class's id and hash: its `static eventName`, in the context of its file. */
+    const eventOfClass = (expression: ts.Expression, near: string): { id: string, hash: string } | null => {
+      const declaration = aliased(checker.getSymbolAtLocation(expression))?.declarations?.find(ts.isClassDeclaration)
+      const text = expression.getText()
+      if (!declaration) {
+        warnings.push(`${near}: the event class ${text} is not found`)
+        return null
+      }
+      const nameMember = declaration.members.find(member => ts.isPropertyDeclaration(member) && member.name.getText() === 'eventName')
+      const initializer = nameMember && ts.isPropertyDeclaration(nameMember) ? nameMember.initializer : undefined
+      const context = contextOfFile(declaration.getSourceFile().fileName)
+      if (!initializer || !ts.isStringLiteralLike(initializer) || context === null) {
+        warnings.push(`${near}: the event class ${text} has no static eventName = '<module>.<what>' in a module's folder`)
+        return null
+      }
+      return { id: `${context}/${initializer.text}`, hash: hashOf([declaration.getText()]) }
+    }
+
+    // The modules, their events and schedules.
+    for (const source of sources) {
+      const file = resolve(source.fileName)
+      if (!file.endsWith('.module.ts')) {
+        continue
+      }
+      const context = contextOfFile(file)!
+      const classes = source.statements.filter(isModuleClass)
+      if (!classes.length) {
+        warnings.push(`${file}: a .module.ts with no <Name>_Module class`)
+        continue
+      }
+      for (const declaration of classes) {
+        const constructor = declaration.members.find(ts.isConstructorDeclaration)
+        let name = moduleNameOfClass(declaration.name.text)
+        constructor?.body?.forEachChild(function find(node): void {
+          const callsSuper = ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.SuperKeyword
+          if (callsSuper && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) {
+            name = node.arguments[0].text
+          }
+          node.forEachChild(find)
+        })
+        const info: ModuleInfo = { module: { id: `${context}/${name}`, context, name, port: false, pieces: [] }, fields: new Map(), groups: new Map(), declaration }
+        modules.set(info.module.id, info)
+        byClass.set(keyOfClass(declaration), info)
+      }
+    }
+
+    for (const info of [...byClass.values()]) {
+      const { declaration, module } = info
+      const assignments: [string, ts.Expression][] = []
+      for (const member of declaration.members) {
+        if (ts.isPropertyDeclaration(member) && member.initializer) {
+          assignments.push([member.name.getText(), member.initializer])
+        }
+      }
+      declaration.members.find(ts.isConstructorDeclaration)?.body?.forEachChild(function find(node): void {
+        const assignsAField = ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken
+          && ts.isPropertyAccessExpression(node.left) && node.left.expression.kind === ts.SyntaxKind.ThisKeyword
+        if (assignsAField) {
+          assignments.push([(node.left as ts.PropertyAccessExpression).name.text, node.right])
+        }
+        node.forEachChild(find)
+      })
+      for (const [field, value] of assignments) {
+        if (!ts.isCallExpression(value) || !ts.isPropertyAccessExpression(value.expression) && !ts.isIdentifier(value.expression)) {
+          continue
+        }
+        const callee = value.expression.getText()
+        const [first, second] = value.arguments
+        if (/(^|\.)eventsOf$/.test(callee) && second && ts.isObjectLiteralExpression(second)) {
+          const group = new Map<string, string>()
+          for (const property of second.properties) {
+            const eventClass = ts.isPropertyAssignment(property) ? property.initializer : ts.isShorthandPropertyAssignment(property) ? property.name : undefined
+            const event = eventClass && eventOfClass(eventClass, module.id)
+            if (!event) {
+              continue
+            }
+            group.set(property.name!.getText(), event.id)
+            if (moduleOf(event.id) !== module.id) {
+              warnings.push(`${module.id}: its event ${event.id} is named after another module`)
+            }
+            addPiece({ id: event.id, kind: 'event', name: event.id.slice(event.id.indexOf('.') + 1), hash: event.hash })
+          }
+          info.groups.set(field, group)
+        }
+        if (/\.schedules\.define$/.test(callee) && first && second && ts.isStringLiteralLike(first) && ts.isStringLiteralLike(second)) {
+          const id = `${module.context}/${first.text}`
+          info.fields.set(field, id)
+          if (moduleOf(id) !== module.id) {
+            warnings.push(`${module.id}: its schedule ${first.text} is named after another module`)
+          }
+          addPiece({ id, kind: 'schedule', name: id.slice(id.indexOf('.') + 1), cron: second.text })
+        }
+      }
+    }
+
+    // What each use case emits and calls.
+    const isEntity = (start: ts.ClassDeclaration): boolean => {
+      for (let at: ts.ClassDeclaration | undefined = start, depth = 0; at && depth < 10; depth++) {
+        const heritage: ts.ExpressionWithTypeArguments | undefined = at.heritageClauses?.find(each => each.token === ts.SyntaxKind.ExtendsKeyword)?.types[0]
+        if (!heritage) {
+          return false
+        }
+        if (heritage.expression.getText() === 'Entity') {
+          return true
+        }
+        at = aliased(checker.getSymbolAtLocation(heritage.expression))?.declarations?.find(ts.isClassDeclaration)
+      }
+      return false
+    }
+    const isConditional = (node: ts.Node, within: ts.Node): boolean => {
+      for (let at = node.parent; at && at !== within; at = at.parent) {
+        if (ts.isIfStatement(at) || ts.isConditionalExpression(at) || ts.isCaseClause(at) || ts.isCatchClause(at)) {
+          return true
+        }
+        if (ts.isBinaryExpression(at) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(at.operatorToken.kind)) {
+          return true
+        }
+        if (ts.isForStatement(at) || ts.isForOfStatement(at) || ts.isForInStatement(at) || ts.isWhileStatement(at)) {
+          return true
+        }
+      }
+      return false
+    }
+    const isApplicationCode = (node: ts.Node) => contextOfFile(node.getSourceFile().fileName) !== null
+    const declarationOf = (call: ts.CallExpression): ts.Declaration | undefined =>
+      checker.getResolvedSignature(call)?.declaration ?? aliased(checker.getSymbolAtLocation(call.expression))?.declarations?.[0]
+    /**
+     * A port: a method an interface of the application declares, reached from the module
+     * (`this.deps.mailer.send`, `this.options.mailer.send`, `this.search.index`), named by
+     * the field it is reached through.
+     */
+    const portOf = (callee: ts.Expression, target: ts.Declaration | undefined): [string, string] | null => {
+      const declaredByAnInterface = target !== undefined && (ts.isMethodSignature(target) || ts.isPropertySignature(target))
+      const file = target?.getSourceFile()
+      const ofTheApplication = file !== undefined && !file.isDeclarationFile && !resolve(file.fileName).includes(`${sep}node_modules${sep}`)
+      const match = /^this\.(?:(?:options|deps)\.)?((?:[A-Za-z_$][\w$]*\.)*[A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/.exec(callee.getText())
+      if (!declaredByAnInterface || !ofTheApplication || !match) {
+        return null
+      }
+      return [match[1]!.split('.').pop()!, match[2]!]
+    }
+
+    for (const info of byClass.values()) {
+      const { declaration, module } = info
+      for (const member of declaration.members) {
+        if (!isUseCase(member)) {
+          continue
+        }
+        const useCase = `${module.id}.${member.name.getText()}`
+        const texts: string[] = []
+        const seen = new Set<ts.Node>()
+        const follow = (fn: ts.FunctionLikeDeclaration, underCondition: boolean): void => {
+          if (seen.has(fn) || !fn.body) {
+            return
+          }
+          seen.add(fn)
+          texts.push(fn.getText())
+          fn.body.forEachChild(function visit(child): void {
+            if (ts.isCallExpression(child)) {
+              const conditional = underCondition || isConditional(child, fn)
+              const callee = child.expression
+              const tracked = child.arguments[0]
+              const tracksAnEvent = ts.isPropertyAccessExpression(callee) && callee.name.text === 'trackEvent' && tracked !== undefined && ts.isNewExpression(tracked)
+              if (tracksAnEvent) {
+                const event = eventOfClass((tracked as ts.NewExpression).expression, useCase)
+                if (event) {
+                  addPiece({ id: event.id, kind: 'event', name: event.id.slice(event.id.indexOf('.') + 1), hash: event.hash })
+                  relate({ kind: 'emits', from: useCase, to: event.id, ...(conditional ? { conditional: true } : {}) })
+                }
+              } else {
+                const target = declarationOf(child)
+                const owner = classOf(target)
+                const hasBody = target !== undefined && ts.isFunctionLike(target) && 'body' in target && target.body !== undefined
+                if (hasBody && owner && isModuleClass(owner) && isUseCase(target)) {
+                  const called = byClass.get(keyOfClass(owner))
+                  if (called) {
+                    relate({ kind: 'calls', from: useCase, to: `${called.module.id}.${target.name!.getText()}` })
+                  }
+                } else if (hasBody && (owner === declaration || (owner && isEntity(owner)) || (!owner && isApplicationCode(target)))) {
+                  follow(target as ts.FunctionLikeDeclaration, conditional)
+                } else if (!hasBody) {
+                  const port = portOf(callee, target)
+                  if (port) {
+                    const [name, method] = port
+                    portModule(name)
+                    const id = `ports/${name}.${method}`
+                    addPiece({ id, kind: 'useCase', name: method })
+                    relate({ kind: 'calls', from: useCase, to: id })
+                  }
+                }
+              }
+            }
+            child.forEachChild(visit)
+          })
+        }
+        follow(member, false)
+        addPiece({ id: useCase, kind: 'useCase', name: member.name.getText(), hash: hashOf(texts) })
+      }
+      // Its deps: the contexts it uses.
+      const depsType = declaration.members.find(ts.isConstructorDeclaration)?.parameters.find(parameter => parameter.name.getText() === 'deps')
+      if (depsType) {
+        const walk = (type: ts.Type, depth: number): void => {
+          const target = type.getSymbol()?.declarations?.find(isModuleClass)
+          const used = target && byClass.get(keyOfClass(target))
+          if (used) {
+            if (used.module.context !== module.context) {
+              (uses.get(module.context) ?? uses.set(module.context, new Set()).get(module.context)!).add(used.module.context)
+            }
+            return
+          }
+          if (depth > 3) {
+            return
+          }
+          for (const property of type.getProperties()) {
+            walk(checker.getTypeOfSymbolAtLocation(property, depsType), depth + 1)
+          }
+        }
+        walk(checker.getTypeAtLocation(depsType), 0)
+      }
+    }
+
+    /** The event or schedule an expression holds: `deps.sales.order.events.created`, `orders.nightly`. */
+    const emitterOf = (expression: ts.Expression): string | undefined => {
+      const name = ts.isPropertyAccessExpression(expression) ? expression.name : expression
+      for (const declaration of checker.getSymbolAtLocation(name)?.declarations ?? []) {
+        const inEventsOf = ts.isPropertyAssignment(declaration) || ts.isShorthandPropertyAssignment(declaration)
+        const owner = classOf(declaration)
+        if (inEventsOf) {
+          const eventClass = ts.isPropertyAssignment(declaration) ? declaration.initializer : declaration.name
+          const event = eventOfClass(eventClass, 'a worker')
+          if (event) {
+            return event.id
+          }
+        }
+        if (ts.isPropertyDeclaration(declaration) && isModuleClass(owner)) {
+          const found = byClass.get(keyOfClass(owner))?.fields.get(declaration.name.getText())
+          if (found) {
+            return found
+          }
+        }
+      }
+      if (!ts.isPropertyAccessExpression(expression)) {
+        return undefined
+      }
+      const holder = expression.expression
+      const direct = moduleOfType(holder)?.fields.get(expression.name.text)
+      if (direct) {
+        return direct
+      }
+      if (ts.isPropertyAccessExpression(holder)) {
+        return moduleOfType(holder.expression)?.groups.get(holder.name.text)?.get(expression.name.text)
+      }
+      return undefined
+    }
+
+    // The workers: `module.on(event, 'useCase')`.
+    for (const source of sources) {
+      source.forEachChild(function visit(node): void {
+        const isOn = ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'on' && node.arguments.length >= 2
+        const listener = isOn ? moduleOfType((node.expression as ts.PropertyAccessExpression).expression) : undefined
+        if (isOn && listener) {
+          const [emitter, useCase] = node.arguments as unknown as [ts.Expression, ts.Expression]
+          const event = emitterOf(emitter)
+          const where = `${resolve(source.fileName)}: ${node.getText().split('\n')[0]}`
+          if (!ts.isStringLiteralLike(useCase)) {
+            warnings.push(`${where}: the use case is not named by a string`)
+          } else if (!event) {
+            warnings.push(`${where}: the event it listens to is not found`)
+          } else {
+            const eventName = event.slice(event.indexOf('/') + 1)
+            relate({ kind: 'triggers', from: event, to: `${listener.module.id}.${useCase.text}`, queue: `${listener.module.name}.${useCase.text}.on.${eventName}` })
+          }
+        }
+        node.forEachChild(visit)
+      })
+    }
+  }
+
+  for (const relation of relations.values()) {
+    for (const end of [relation.from, relation.to]) {
+      if (!pieces.has(end)) {
+        warnings.push(`${relation.from} ${relation.kind} ${end}, which the code has not`)
+      }
+    }
+  }
+  const relationsOfKnown = [...relations.values()].filter(relation => pieces.has(relation.from) && pieces.has(relation.to))
+  // A listener uses the context it listens to.
+  for (const relation of relationsOfKnown) {
+    const [from, to] = relation.kind === 'triggers' ? [relation.to, relation.from] : [relation.from, relation.to]
+    const a = modules.get(moduleOf(from))!.module.context, b = modules.get(moduleOf(to))!.module.context
+    if (a !== b && b !== 'ports') {
+      (uses.get(a) ?? uses.set(a, new Set()).get(a)!).add(b)
+    }
+  }
+
+  const sortedModules = [...modules.values()].map(info => info.module).sort((a, b) => a.id.localeCompare(b.id))
+  const order = { useCase: 0, event: 1, schedule: 2 }
+  for (const module of sortedModules) {
+    module.pieces.sort((a, b) => order[a.kind] - order[b.kind] || a.name.localeCompare(b.name))
+  }
+  // The ports last.
+  const contextNames = [...new Set(sortedModules.map(module => module.context))].sort((a, b) => Number(a === 'ports') - Number(b === 'ports') || a.localeCompare(b))
+  return {
+    map: {
+      version: 1,
+      contexts: contextNames.map(name => ({ name, uses: [...uses.get(name) ?? []].sort() })),
+      modules: sortedModules,
+      relations: relationsOfKnown.sort((a, b) => `${a.kind} ${a.from} ${a.to}`.localeCompare(`${b.kind} ${b.from} ${b.to}`)),
+    },
+    warnings: [...new Set(warnings)],
+  }
+}
+
+/** The folder a tsconfig is in. */
+export const projectFolder = (tsconfigPath: string) => dirname(resolve(tsconfigPath))

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@newt-kit/plan",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "description": "A newt application drawn from its code: `newt map` and `newt review`, a feature's plan checked against the code and newt's rules, and a branch held against its plan.",
+  "license": "MIT",
+  "author": "Angel Romero",
+  "homepage": "https://aromero86.github.io/newt/manual/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aromero86/newt.git",
+    "directory": "packages/newt-plan"
+  },
+  "bugs": "https://github.com/aromero86/newt/issues",
+  "keywords": [
+    "bun",
+    "newt",
+    "architecture",
+    "planning",
+    "code-review",
+    "claude"
+  ],
+  "files": [
+    "**/*.ts",
+    "render/template.html",
+    "skills",
+    "!**/*.test.ts",
+    "!**/fixtures/**",
+    "!tsconfig.json"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./index.ts",
+    "./cli": "./cli/commands.ts"
+  },
+  "newt": {
+    "skills": [
+      "skills/newt-plan",
+      "skills/newt-review"
+    ]
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "dependencies": {
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@newt-kit/newt": "0.10.0"
+  }
+}

package/plan/check.ts

@@ -0,0 +1,154 @@
+import { moduleOf, splitModuleId } from '../map/app-map'
+import type { ResolvedPlan, ResolvedRelation } from './resolve'
+
+export type Rule = { ok: boolean, text: string }
+
+type Words = Record<'cycle' | 'noCycle' | 'uses' | 'usesOk' | 'writes' | 'writesOk' | 'irreversible' | 'irreversibleOk' | 'unheard', (...args: string[]) => string>
+
+const WORDS: Record<ResolvedPlan['language'], Words> = {
+  en: {
+    cycle: path => `Modules depend on each other in a cycle: ${path}. Break it with an event.`,
+    noCycle: () => 'No cycle between modules: what it adds depends on what was there, never back.',
+    uses: (from, to) => `The context ${from} does not use ${to} yet: add it to contexts.uses in the lint, or reach it through an event.`,
+    usesOk: () => 'Every context it reaches across is one its context already uses.',
+    writes: (from, to) => `${from} writes into ${to} outside a worker: react to an event instead.`,
+    writesOk: () => 'It writes into another module only from a worker reacting to an event.',
+    irreversible: (from, to) => `${from} calls ${to}, which cannot be undone, outside a worker: leave it from a worker.`,
+    irreversibleOk: () => 'What cannot be undone (a port) is called only from a worker.',
+    unheard: event => `Nothing listens to ${event} yet.`,
+  },
+  es: {
+    cycle: path => `Hay módulos que dependen unos de otros en ciclo: ${path}. Rómpelo con un evento.`,
+    noCycle: () => 'Sin ciclos entre módulos: lo nuevo depende de lo que había, nunca al revés.',
+    uses: (from, to) => `El contexto ${from} aún no usa ${to}: añádelo a contexts.uses del lint, o llega a él con un evento.`,
+    usesOk: () => 'Cada contexto al que llega es uno que su contexto ya usa.',
+    writes: (from, to) => `${from} escribe en ${to} fuera de un worker: reacciona a un evento.`,
+    writesOk: () => 'Solo escribe en otro módulo desde un worker que reacciona a un evento.',
+    irreversible: (from, to) => `${from} llama a ${to}, que no se puede deshacer, fuera de un worker: hazlo desde un worker.`,
+    irreversibleOk: () => 'Lo que no se puede deshacer (un puerto) solo se llama desde un worker.',
+    unheard: event => `Nadie escucha ${event} todavía.`,
+  },
+}
+
+/**
+ * What newt's rules say of what a plan adds, checked on its map: no cycle between modules
+ * (rule 9), a context reaches only those it uses, a use case writes into another module
+ * only from a worker (rule 6) and calls what cannot be undone only from one (rule 7). And,
+ * to know, the new events nothing listens to.
+ */
+export function checkPlan(plan: ResolvedPlan): Rule[] {
+  const words = WORDS[plan.language]
+  const live = plan.relations.filter(relation => relation.status !== 'removed')
+  const added = plan.relations.filter(relation => relation.status === 'new')
+  const pieces = new Map(plan.modules.flatMap(module => module.pieces.map(piece => [piece.id, piece] as const)))
+  const ports = new Set(plan.modules.filter(module => module.port).map(module => module.id))
+  const rules: Rule[] = []
+
+  // Rule 9: the modules' graph, by calls (a listener depends on the module it listens to).
+  const edges = new Map<string, Set<string>>()
+  const depend = (from: string, to: string) => {
+    if (from !== to && !ports.has(to)) {
+      (edges.get(from) ?? edges.set(from, new Set()).get(from)!).add(to)
+    }
+  }
+  for (const relation of live) {
+    if (relation.kind === 'calls') {
+      depend(moduleOf(relation.from), moduleOf(relation.to))
+    }
+    if (relation.kind === 'triggers') {
+      depend(moduleOf(relation.to), moduleOf(relation.from))
+    }
+  }
+  const cycles = new Set<string>()
+  for (const relation of added) {
+    if (relation.kind === 'emits') {
+      continue
+    }
+    const [from, to] = relation.kind === 'calls' ? [moduleOf(relation.from), moduleOf(relation.to)] : [moduleOf(relation.to), moduleOf(relation.from)]
+    const path = pathBetween(edges, to, from)
+    if (path && from !== to) {
+      cycles.add([from, ...path].join(' → '))
+    }
+  }
+  if (cycles.size) {
+    for (const path of cycles) {
+      rules.push({ ok: false, text: words.cycle(path) })
+    }
+  } else {
+    rules.push({ ok: true, text: words.noCycle() })
+  }
+
+  // A context reaches only the contexts it uses.
+  const uses = new Map(plan.contexts.map(context => [context.name, new Set(context.uses)]))
+  const reaches = new Set<string>()
+  for (const relation of added) {
+    if (relation.kind === 'emits') {
+      continue
+    }
+    const [from, to] = relation.kind === 'calls' ? [relation.from, relation.to] : [relation.to, relation.from]
+    const a = splitModuleId(moduleOf(from)).context, b = splitModuleId(moduleOf(to)).context
+    if (a !== b && b !== 'ports' && !uses.get(a)?.has(b)) {
+      reaches.add(`${a} ${b}`)
+    }
+  }
+  for (const pair of reaches) {
+    rules.push({ ok: false, text: words.uses(...pair.split(' ')) })
+  }
+  if (!reaches.size) {
+    rules.push({ ok: true, text: words.usesOk() })
+  }
+
+  // Rules 6 and 7: a worker is a use case some event or schedule triggers.
+  const isWorker = (id: string) => live.some(relation => relation.kind === 'triggers' && relation.to === id)
+  const writes = (id: string) => live.some(relation => relation.kind === 'emits' && relation.from === id)
+  const outside: ResolvedRelation[] = [], irreversible: ResolvedRelation[] = []
+  for (const relation of added) {
+    if (relation.kind !== 'calls' || isWorker(relation.from)) {
+      continue
+    }
+    if (ports.has(moduleOf(relation.to))) {
+      irreversible.push(relation)
+    } else if (moduleOf(relation.from) !== moduleOf(relation.to) && writes(relation.to)) {
+      outside.push(relation)
+    }
+  }
+  for (const relation of outside) {
+    rules.push({ ok: false, text: words.writes(relation.from, relation.to) })
+  }
+  if (!outside.length) {
+    rules.push({ ok: true, text: words.writesOk() })
+  }
+  for (const relation of irreversible) {
+    rules.push({ ok: false, text: words.irreversible(relation.from, relation.to) })
+  }
+  if (!irreversible.length && added.some(relation => relation.kind === 'calls' && ports.has(moduleOf(relation.to)))) {
+    rules.push({ ok: true, text: words.irreversibleOk() })
+  }
+
+  for (const [id, piece] of pieces) {
+    if (piece.kind === 'event' && piece.status === 'new' && !live.some(relation => relation.kind === 'triggers' && relation.from === id)) {
+      rules.push({ ok: false, text: words.unheard(id) })
+    }
+  }
+  return rules
+}
+
+/** A path of modules from `from` to `to`, if there is one. */
+function pathBetween(edges: Map<string, Set<string>>, from: string, to: string): string[] | null {
+  const queue: string[][] = [[from]]
+  const seen = new Set([from])
+  while (queue.length) {
+    const path = queue.shift()!
+    const last = path[path.length - 1]!
+    if (last === to) {
+      return path
+    }
+    for (const next of edges.get(last) ?? []) {
+      if (!seen.has(next)) {
+        seen.add(next)
+        queue.push([...path, next])
+      }
+    }
+  }
+  return null
+}