@newt-kit/plan 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angel Romero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @newt-kit/plan
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [newt](https://github.com/aromero86/newt) application drawn from its code: its contexts,
+modules, use cases, events and schedules, and how they meet. A story's plan checked against
+the code and newt's rules before it is written, and a branch held against its plan once it is.
+
+```sh
+bun add -d @newt-kit/plan
+```
+
+newt's command line runs it:
+
+```sh
+bunx newt map                                    # the application, drawn: newt-map.html
+bunx newt map --json                             # its map, as JSON
+bunx newt map --plan stories/12.plan.json        # the plan checked and drawn: stories/12.html
+bunx newt review --base main                     # what the branch changes, drawn: review.html
+bunx newt review --base main --plan stories/12.plan.json --format markdown
+```
+
+The map is read from the code, never run and never kept: the `<Name>_Module` classes of
+`<context>/modules/<module>/<module>.module.ts`, their `@UseCase` methods, `eventsOf(…)`,
+`schedules.define(…)`, the workers (`module.on(event, 'useCase')`), and, followed through
+the entity, what each use case emits and calls (another module's use case, or a port). What
+falls outside newt's layout is said as a warning.
+
+A plan says only what a story changes, in steps: each a commit that leaves the application
+working, the whole story a branch. `newt review --plan` tells each thing done, missing,
+different or not planned, and each step done, half done or not started, by what is in the
+code. It exits with 1 when something is missing or not planned (`--warn-only` does not).
+
+The pages are always the same template with their data in it. A plan's page saves its plan
+("Guardar plan"); a review's page loads one ("Cargar plan") and holds the branch against it.
+
+`newt init` and `newt agents` copy its Claude Code skills into `.claude/skills/`: `newt-plan` plans a story
+and `newt-review` reviews a branch.

package/cli/commands.ts

@@ -0,0 +1,184 @@
+// `newt map` and `newt review`: the map of an application read from its code, a plan laid
+// on it, a branch's change, and their pages. newt's command line runs them from here.
+
+import { mkdtemp, rm, stat, symlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, relative, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { readMap } from '../map/read-map'
+import { checkPlan } from '../plan/check'
+import { reviewMarkdown } from '../plan/markdown'
+import { PlanSchema, type Plan } from '../plan/plan.schema'
+import { PlanError, resolvePlan } from '../plan/resolve'
+import { reviewOf } from '../plan/review'
+import { pageData } from '../render/page-data'
+import { renderPage } from '../render/render'
+
+export const USAGE = `newt map [--plan <plan.json>] [--out <page.html>] [--json] [--tsconfig tsconfig.json] [--within <folder>] [--language en|es]
+  The application as its code is, drawn: its contexts, modules, use cases, events and
+  schedules, and how they meet. --json prints the map instead. With --plan, the plan laid
+  on it, checked against the code and newt's rules, and drawn (beside the plan unless --out).
+
+newt review [--base main] [--plan <plan.json>] [--format html|markdown|json] [--out <file>] [--warn-only]
+            [--tsconfig tsconfig.json] [--within <folder>] [--title <title>] [--language en|es]
+  What the code on disk changes from --base (a branch, a tag, origin/main), drawn. With
+  --plan, held against it: each thing done, missing, different or not planned, and each
+  step done or not. Exits with 1 when something is missing or not planned, unless --warn-only.
+  html is written to --out (review.html); markdown and json are printed, or written to --out.`
+
+export type Output = { lines: string[], code: number }
+
+const OPTIONS = {
+  plan: { type: 'string' }, out: { type: 'string' }, json: { type: 'boolean' }, tsconfig: { type: 'string' }, within: { type: 'string' },
+  language: { type: 'string' }, base: { type: 'string' }, format: { type: 'string' }, 'warn-only': { type: 'boolean' }, title: { type: 'string' },
+} as const
+
+const languageOf = (value: string | undefined) => value === 'es' ? 'es' as const : value === undefined || value === 'en' ? 'en' as const : null
+const warningsOf = (warnings: string[]) => warnings.map(warning => `warning: ${warning}`)
+
+async function readPlan(path: string): Promise<Plan | string[]> {
+  const file = Bun.file(path)
+  if (!await file.exists()) {
+    return [`No file ${path}`]
+  }
+  const parsed = PlanSchema.safeParse(await file.json())
+  if (parsed.success) {
+    return parsed.data
+  }
+  return ['The plan is not one:', ...parsed.error.issues.map(issue => `- ${issue.path.join('.')}: ${issue.message}`)]
+}
+
+/** Runs `map` or `review`, in `cwd`: what to print, and the exit code. */
+export async function run(args: string[], cwd: string): Promise<Output> {
+  const [command, ...rest] = args
+  if (command !== 'map' && command !== 'review') {
+    return { lines: [USAGE], code: command === undefined || command === 'help' ? 0 : 1 }
+  }
+  try {
+    const { values, positionals } = parseArgs({ args: rest, options: OPTIONS, allowPositionals: true })
+    const language = languageOf(values.language)
+    if (positionals.length || language === null) {
+      return { lines: [USAGE], code: 1 }
+    }
+    const at = (path: string) => resolve(cwd, path)
+    const tsconfig = at(values.tsconfig ?? 'tsconfig.json')
+    const within = values.within === undefined ? undefined : at(values.within)
+    return command === 'map'
+      ? await map({ cwd, tsconfig, within, plan: values.plan && at(values.plan), out: values.out && at(values.out), json: values.json ?? false, language })
+      : await review({ cwd, tsconfig, within, base: values.base ?? 'main', plan: values.plan && at(values.plan), out: values.out && at(values.out), format: values.format ?? 'html', warnOnly: values['warn-only'] ?? false, title: values.title, language: values.language === undefined ? undefined : language })
+  } catch (error) {
+    return { lines: [error instanceof Error ? error.message : String(error)], code: 1 }
+  }
+}
+
+/** An application's name: its package.json's, or its folder's. */
+async function nameOf(folder: string): Promise<string> {
+  const manifest = Bun.file(join(folder, 'package.json'))
+  const named = await manifest.exists() ? (await manifest.json() as { name?: string }).name : undefined
+  return named ?? basename(folder)
+}
+
+type MapOptions = { cwd: string, tsconfig: string, within: string | undefined, plan: string | undefined, out: string | undefined, json: boolean, language: 'en' | 'es' }
+
+async function map(options: MapOptions): Promise<Output> {
+  const { map, warnings } = readMap(options.tsconfig, options.within)
+  if (options.json) {
+    return { lines: [JSON.stringify(map, null, 2), ...warningsOf(warnings)], code: 0 }
+  }
+  if (!options.plan) {
+    const out = options.out ?? resolve(options.cwd, 'newt-map.html')
+    const title = await nameOf(dirname(options.tsconfig))
+    const resolved = resolvePlan(map, PlanSchema.parse({ version: 1, title, language: options.language }), 'map')
+    await Bun.write(out, await renderPage(pageData(resolved)))
+    return { lines: [`Written ${out}`, ...warningsOf(warnings)], code: 0 }
+  }
+  const plan = await readPlan(options.plan)
+  if (Array.isArray(plan)) {
+    return { lines: plan, code: 1 }
+  }
+  try {
+    const laid = resolvePlan(map, plan)
+    const resolved = { ...laid, rules: [...checkPlan(laid), ...laid.rules] }
+    const out = options.out ?? options.plan.replace(/(\.plan)?\.json$/, '') + '.html'
+    await Bun.write(out, await renderPage(pageData(resolved, { plan })))
+    return { lines: [...resolved.rules.map(rule => `${rule.ok ? '✓' : '!'} ${rule.text}`), `Written ${out}`, ...warningsOf(warnings)], code: 0 }
+  } catch (error) {
+    if (error instanceof PlanError) {
+      return { lines: [error.message, ...warningsOf(warnings)], code: 1 }
+    }
+    throw error
+  }
+}
+
+type ReviewOptions = {
+  cwd: string, tsconfig: string, within: string | undefined, base: string, plan: string | undefined, out: string | undefined
+  format: string, warnOnly: boolean, title: string | undefined, language: 'en' | 'es' | undefined
+}
+
+async function review(options: ReviewOptions): Promise<Output> {
+  if (!['html', 'markdown', 'json'].includes(options.format)) {
+    return { lines: [USAGE], code: 1 }
+  }
+  const plan = options.plan ? await readPlan(options.plan) : undefined
+  if (Array.isArray(plan)) {
+    return { lines: plan, code: 1 }
+  }
+
+  const head = readMap(options.tsconfig, options.within)
+  const base = await atRevision(options.cwd, options.base, (folder, root) => readMap(moved(options.tsconfig, root, folder), options.within && moved(options.within, root, folder)))
+  const branch = (await Bun.$`git rev-parse --abbrev-ref HEAD`.cwd(options.cwd).quiet().text()).trim()
+  const made = reviewOf(base.map, head.map, { title: options.title ?? `${branch} ← ${options.base}`, ...(options.language ? { language: options.language } : {}), ...(plan ? { plan } : {}) })
+  const failing = made.comparison?.failing ?? 0
+  const code = failing && !options.warnOnly ? 1 : 0
+  const warnings = warningsOf([...new Set([...base.warnings, ...head.warnings])])
+
+  const text = options.format === 'markdown' ? reviewMarkdown(made)
+    : options.format === 'json' ? `${JSON.stringify({ map: head.map, changes: made.resolved, comparison: made.comparison ?? null }, null, 2)}\n`
+    : await renderPage(made.data)
+  const summary = made.comparison ? [`${failing} to look at`] : []
+  if (options.format !== 'html' && !options.out) {
+    return { lines: [text.trimEnd(), ...warnings], code }
+  }
+  const out = options.out ?? resolve(options.cwd, 'review.html')
+  await Bun.write(out, text)
+  return { lines: [...summary, `Written ${out}`, ...warnings], code }
+}
+
+/** A path of the working tree (whose root is `root`), at the same place in `folder`. */
+const moved = (path: string, root: string, folder: string) => join(folder, relative(root, path))
+
+/**
+ * Runs `read` on the code of `revision`, written out to a folder of its own, with the
+ * working tree's node_modules beside it so its imports resolve as they do here.
+ */
+async function atRevision<T>(cwd: string, revision: string, read: (folder: string, root: string) => T): Promise<T> {
+  // The root as reached from cwd, not --show-toplevel's real path: through a symlink (macOS's
+  // /var is /private/var) the paths moved into the folder would not be under it.
+  const root = resolve(cwd, (await Bun.$`git rev-parse --show-cdup`.cwd(cwd).quiet().text()).trim())
+  const known = await Bun.$`git rev-parse --verify --quiet ${revision}^{commit}`.cwd(root).quiet().nothrow()
+  if (known.exitCode !== 0) {
+    throw new Error(`No revision ${revision}: in a shallow clone, fetch it (fetch-depth: 0)`)
+  }
+  const folder = await mkdtemp(join(tmpdir(), 'newt-review-'))
+  try {
+    await Bun.$`git archive ${revision} | tar -x -C ${folder}`.cwd(root).quiet()
+    for (const at of new Set([root, cwd])) {
+      const modules = join(at, 'node_modules')
+      const there = join(folder, relative(root, at), 'node_modules')
+      const exists = await stat(modules).then(() => true, () => false)
+      const already = await stat(there).then(() => true, () => false)
+      if (exists && !already) {
+        await symlink(modules, there).catch(() => undefined)
+      }
+    }
+    return read(folder, root)
+  } finally {
+    await rm(folder, { recursive: true, force: true })
+  }
+}
+
+if (import.meta.main) {
+  const { lines, code } = await run(Bun.argv.slice(2), process.cwd())
+  console[code === 0 ? 'log' : 'error'](lines.join('\n'))
+  process.exit(code)
+}

package/index.ts

@@ -0,0 +1,14 @@
+// @newt-kit/plan: a newt application drawn from its code, a plan laid on it and checked,
+// and a branch's change held against it. newt's command line runs it: `newt map`, `newt review`.
+export type { AppMap, MapContext, MapModule, MapPiece, MapRelation, PieceKind, RelationKind } from './map/app-map'
+export { readMap, contextOfFile, type ReadMap } from './map/read-map'
+export { PlanSchema, type Plan, type PlanInput } from './plan/plan.schema'
+export { resolvePlan, queueOf, piecesNamed, PlanError, type Mode, type ResolvedPlan, type ResolvedModule, type ResolvedPiece, type ResolvedRelation, type ResolvedStep, type Status } from './plan/resolve'
+export { diffMaps } from './plan/diff'
+export { checkPlan, type Rule } from './plan/check'
+export { comparePlan, type Check, type Comparison, type StepCheck, type StepState, type Verdict } from './plan/compare'
+export { reviewOf, type Review } from './plan/review'
+export { reviewMarkdown } from './plan/markdown'
+export { pageData, type PageData, type PageStep } from './render/page-data'
+export { renderPage, TEMPLATE } from './render/render'
+export { run, USAGE } from './cli/commands'

package/map/app-map.ts

@@ -0,0 +1,69 @@
+/**
+ * An application as a plan draws it, read from its code: its contexts, its modules, the
+ * pieces of each (use cases, events, schedules) and how they meet.
+ *
+ * A module's id is `<context>/<module>`; a piece's, `<context>/<module>.<name>`.
+ * A port is a module of the context `ports`: `ports/mailer.send`.
+ */
+export type AppMap = {
+  version: 1
+  contexts: MapContext[]
+  modules: MapModule[]
+  relations: MapRelation[]
+}
+
+export type MapContext = {
+  name: string
+  /** The contexts its modules depend on. */
+  uses: string[]
+}
+
+export type MapModule = {
+  id: string
+  context: string
+  name: string
+  /** A port: something the module calls that is no module of the application (a mailer). */
+  port: boolean
+  pieces: MapPiece[]
+}
+
+export type PieceKind = 'useCase' | 'event' | 'schedule'
+
+export type MapPiece = {
+  id: string
+  kind: PieceKind
+  /** Its name in its module: `create`, `created`. */
+  name: string
+  /** A schedule's cron expression. */
+  cron?: string
+  /** A short hash of its code (a use case and what it follows, an event's class): tells it changed. */
+  hash?: string
+}
+
+export type RelationKind = 'emits' | 'triggers' | 'calls'
+
+/**
+ * - `emits`: a use case to an event its module's entity tracks while it runs.
+ * - `triggers`: an event or a schedule to the use case a subscription to it runs.
+ * - `calls`: a use case to a use case of another module, or to a port.
+ */
+export type MapRelation = {
+  kind: RelationKind
+  from: string
+  to: string
+  /** `triggers`: the subscription's queue. */
+  queue?: string
+  /** `emits`: only under a condition (`if (diff) this.trackEvent(…)`). */
+  conditional?: boolean
+}
+
+/** The context a module id is of, and its name: `boards/card` → `boards`, `card`. */
+export function splitModuleId(id: string): { context: string, module: string } {
+  const at = id.indexOf('/')
+  return { context: id.slice(0, at), module: id.slice(at + 1) }
+}
+
+/** The module a piece is of: `boards/card.create` → `boards/card`. */
+export function moduleOf(pieceId: string): string {
+  return pieceId.slice(0, pieceId.indexOf('.'))
+}