@erclx/canon 5.43.0 → 5.45.0

package/src/tasks/record.ts

@@ -16,6 +16,7 @@ import {
   readPullRequest,
   tasksDir,
 } from '@/tasks/archive'
+import { checkWaiting, type LinkPromotion, promoteOnLink } from '@/tasks/board'
 
 /**
  * Lines a task carries above its outcomes naming where the work came from. The
@@ -79,6 +80,8 @@ export interface PlanRecorded {
   readonly action: LineAction
   /** The target the line named before a correction. Undefined unless it differed. */
   readonly replaced: string | undefined
+  /** Whether the link moved the task's row out of `## Needs a plan`. */
+  readonly board: LinkPromotion
 }
 
 export type PlanOutcome = PlanRecorded | RecordRefused
@@ -472,7 +475,13 @@ export async function recordPlan(
   stem: string,
   reference: string,
   add = false,
+  waiting?: string,
 ): Promise<PlanOutcome> {
+  if (waiting !== undefined) {
+    const bad = checkWaiting(waiting)
+    if (bad) return refuse('bad-input', bad.message, bad.detail)
+  }
+
   const opened = await openTask(root, { kind: 'stem', stem })
   if ('ok' in opened) return opened
 
@@ -500,7 +509,17 @@ export async function recordPlan(
   const { text, action, replaced } = written
   if (action !== 'unchanged') await writeFile(path, text)
 
-  return { ok: true, stem: opened.stem, path, plan: target, action, replaced }
+  const board = await promoteOnLink(root, opened.stem, { waiting })
+
+  return {
+    ok: true,
+    stem: opened.stem,
+    path,
+    plan: target,
+    action,
+    replaced,
+    board,
+  }
 }
 
 /**

package/src/tasks/validate.ts

@@ -12,6 +12,12 @@ import {
   resolveLivePlan,
   tasksDir,
 } from '@/tasks/archive'
+import {
+  deriveCells,
+  GROUP_COLUMNS,
+  renderedLength,
+  WAITING_LIMIT,
+} from '@/tasks/board'
 import { gitTrunkReader, type TrunkReader } from '@/tasks/trunk'
 
 const ORDERING_FILE = 'priority.md'
@@ -50,6 +56,9 @@ export const FINDING_KINDS = [
   'row-misordered',
   'row-unranked',
   'touches-unstated',
+  'touches-stale',
+  'columns-mismatched',
+  'cell-long',
   'blocker-settled',
   'blocker-unresolved',
   'blocker-declined',
@@ -145,6 +154,8 @@ export interface BoardRow {
   readonly plan: string | undefined
   /** Absent when the group fixes no `Touches` column, empty when it read none. */
   readonly touches: readonly string[] | undefined
+  /** The `Touches` cell as written, which the stale check compares against the derivation. */
+  readonly touchesText: string | undefined
   /** Absent when the group fixes no `Waiting on` column, which is `## Run now`. */
   readonly waiting: string | undefined
   /** The ordinal phrase a `Waiting on` cell states about its own position, undefined when the cell carries none. */
@@ -271,8 +282,8 @@ function splitCells(line: string): string[] {
   return line
     .trim()
     .replace(/^\|/, '')
-    .replace(/\|$/, '')
-    .split('|')
+    .replace(/(?<!\\)\|$/, '')
+    .split(/(?<!\\)\|/)
     .map((cell) => cell.trim())
 }
 
@@ -288,6 +299,21 @@ function isGroup(heading: string): heading is BoardGroup {
   return (BOARD_GROUPS as readonly string[]).includes(heading)
 }
 
+/**
+ * Whether a header is the set of columns its group owns. Order is left to the
+ * reader, which resolves every column by name, so only a missing or a foreign
+ * column is a finding.
+ */
+function ownsColumns(group: BoardGroup, header: readonly string[]): boolean {
+  const owned = GROUP_COLUMNS[group].map((column) => column.toLowerCase())
+  const named = header.map((cell) => cell.toLowerCase())
+
+  return (
+    named.length === owned.length &&
+    owned.every((column) => named.includes(column))
+  )
+}
+
 const ORDINAL_WORDS = [
   'first',
   'second',
@@ -460,6 +486,14 @@ export function readBoard(text: string): {
       }
 
       header = cells
+      if (!ownsColumns(group, cells)) {
+        findings.push({
+          kind: 'columns-mismatched',
+          group,
+          subject: line.trim(),
+          message: `is not the ${GROUP_COLUMNS[group].join(', ')} header ${group} owns.`,
+        })
+      }
       continue
     }
 
@@ -489,6 +523,7 @@ export function readBoard(text: string): {
       stem: target ? stemOf(target) : undefined,
       plan,
       touches: touchesAt >= 0 ? readPaths(cells[touchesAt] ?? '') : undefined,
+      touchesText: touchesAt >= 0 ? (cells[touchesAt] ?? '') : undefined,
       waiting,
       ordinal: waiting ? readOrdinal(waiting) : undefined,
       ranked: waiting ? readRank(waiting) : false,
@@ -1125,6 +1160,83 @@ function citedStem(cell: string): string | undefined {
   return target ? stemOf(target) : undefined
 }
 
+/** The task stems in each folder a bare label can resolve through, live first. */
+interface LabelFolders {
+  readonly live: readonly string[]
+  readonly archived: readonly string[]
+  readonly declined: readonly string[]
+}
+
+type LabelCitation =
+  | { readonly kind: 'stems'; readonly stems: readonly string[] }
+  | { readonly kind: 'ambiguous'; readonly label: string }
+
+/**
+ * Reads every bare `vNNN.N` phase label a `Waiting on` cell names outside a
+ * link, each resolved to the one task it labels. The live folder answers first,
+ * since a live task and a declined one can share a label and the live one is
+ * what the row waits on. Two matches in the folder that answers leave the row
+ * untested rather than guessing between them, and a label no folder holds is
+ * read as prose rather than as a broken pointer, since a version number in a
+ * sentence is not always a citation.
+ */
+function bareLabels(cell: string, folders: LabelFolders): LabelCitation {
+  const prose = cell.replace(/\[[^\]]*\]\([^)]*\)/g, ' ')
+  const stems: string[] = []
+
+  for (const match of prose.matchAll(/\bv\d+\.\d+\b/g)) {
+    const prefix = `${match[0]}-`
+    for (const folder of [folders.live, folders.archived, folders.declined]) {
+      const hits = folder.filter((stem) => stem.startsWith(prefix))
+      if (hits.length > 1) return { kind: 'ambiguous', label: match[0] }
+      if (hits.length === 1) {
+        if (!stems.includes(hits[0])) stems.push(hits[0])
+        break
+      }
+    }
+  }
+
+  return { kind: 'stems', stems }
+}
+
+/**
+ * Tests every task a cell cites by bare label, and reports the row only when
+ * none of them is still open. A cell naming settled history beside its live
+ * blocker would otherwise read as settled on the history alone.
+ */
+async function checkCitedTasks(
+  group: BoardGroup,
+  subject: string,
+  stems: readonly string[],
+  root: string,
+  trunk: TrunkReader,
+): Promise<CitedResult> {
+  const results = await Promise.all(
+    stems.map((stem) => checkCitedTask(group, subject, stem, root, trunk)),
+  )
+  const open = results.some(
+    (result) => result.findings.length === 0 && result.untested.length === 0,
+  )
+  if (open) return nothing()
+
+  return {
+    findings: results.flatMap((result) => result.findings),
+    untested: results.flatMap((result) => result.untested),
+  }
+}
+
+async function readLabelFolders(root: string): Promise<LabelFolders> {
+  const read = async (dir: string): Promise<string[]> =>
+    existsSync(dir) ? listTaskStems(dir) : []
+  const [live, archived, declined] = await Promise.all([
+    read(tasksDir(root)),
+    read(archiveDir(root)),
+    read(declinedDir(root)),
+  ])
+
+  return { live, archived, declined }
+}
+
 /** What one blocker citation produced, since a row can be neither settled nor open. */
 interface CitedResult {
   readonly findings: readonly Finding[]
@@ -1288,17 +1400,29 @@ async function checkParked(
   const findings: Finding[] = []
   const untested: Untested[] = []
   const running = rows.filter((row) => row.group === 'Run now')
+  const folders = await readLabelFolders(root)
 
   for (const row of rows) {
     if (row.group === 'Run now') continue
 
     const subject = row.stem ?? row.label
     const cell = row.waiting ?? ''
-    const cited = citedStem(cell)
+    const linked = citedStem(cell)
+    const bare = linked ? undefined : bareLabels(cell, folders)
+    const cited = linked ? [linked] : bare?.kind === 'stems' ? bare.stems : []
     const contested = readPaths(cell)
 
-    if (cited) {
-      const result = await checkCitedTask(
+    if (bare?.kind === 'ambiguous') {
+      untested.push({
+        group: row.group,
+        subject,
+        message: `waits on ${bare.label}, which labels more than one task, so the blocker is not read.`,
+      })
+      continue
+    }
+
+    if (cited.length > 0) {
+      const result = await checkCitedTasks(
         row.group,
         subject,
         cited,
@@ -1324,7 +1448,7 @@ async function checkParked(
       })
     }
 
-    if (!cited && contested.length === 0) {
+    if (cited.length === 0 && contested.length === 0) {
       untested.push({
         group: row.group,
         subject,
@@ -1337,6 +1461,79 @@ async function checkParked(
   return { findings, untested }
 }
 
+/**
+ * Reports a `Waiting on` cell rendering past the cap. A verb refuses to write
+ * one, so a cell this long is a hand edit, which is why it moves the exit code.
+ */
+function checkCellWidth(rows: readonly BoardRow[]): Finding[] {
+  return rows.flatMap((row) => {
+    const width = row.waiting ? renderedLength(row.waiting) : 0
+    if (width <= WAITING_LIMIT) return []
+
+    return [
+      {
+        kind: 'cell-long' as const,
+        group: row.group,
+        subject: subjectOf(row),
+        message: `carries a Waiting on cell rendering ${width} characters, past the ${WAITING_LIMIT} a board cell holds.`,
+      },
+    ]
+  })
+}
+
+/**
+ * Reports a `Touches` cell that differs from what the task's plans derive. A
+ * verb writes the derivation on every call, so a difference is a hand edit or a
+ * plan that changed since the last write. An empty derivation is left alone,
+ * since a row with no live plan or no declared file is `plan-absent`,
+ * `plan-unresolved`, or `touches-unstated` to report, not stale.
+ */
+async function checkStaleTouches(
+  rows: readonly BoardRow[],
+  root: string,
+): Promise<Finding[]> {
+  const found = await Promise.all(
+    rows.map(async (row): Promise<Finding | undefined> => {
+      if (row.touchesText === undefined || !row.stem) return undefined
+
+      const { touches } = await deriveCells(root, {
+        stem: row.stem,
+        label: row.label,
+      })
+      if (touches === '' || touches === row.touchesText) return undefined
+
+      return {
+        kind: 'touches-stale',
+        group: row.group,
+        subject: row.stem,
+        message: `states ${row.touchesText || 'no file'}, and its plan derives ${touches}. A board verb rewrites the cell.`,
+      }
+    }),
+  )
+
+  return found.filter((finding): finding is Finding => finding !== undefined)
+}
+
+/**
+ * The claims a group name makes about a row, being a stated plan and file set
+ * under `## Run now`, a live plan under `## Up next`, and none under
+ * `## Needs a plan`. The board verbs read these same findings off the board
+ * they are about to write, so a placement and a validation cannot disagree on
+ * what a group allows.
+ */
+export async function groupRuleFindings(
+  rows: readonly BoardRow[],
+  root: string,
+): Promise<Finding[]> {
+  const dir = tasksDir(root)
+
+  return [
+    ...checkPlans(rows, dir, root),
+    ...(await checkGroupClaims(rows, dir, root)),
+    ...checkTouches(rows),
+  ]
+}
+
 function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
@@ -1397,10 +1594,10 @@ export async function validateBoard(
   const findings = [
     ...shapeFindings,
     ...checkMapping(rows, backlog, dir),
-    ...checkPlans(rows, dir, root),
+    ...(await groupRuleFindings(rows, root)),
     ...(await checkPlanAgreement(rows, dir, root)),
-    ...(await checkGroupClaims(rows, dir, root)),
-    ...checkTouches(rows),
+    ...(await checkStaleTouches(rows, root)),
+    ...checkCellWidth(rows),
     ...checkOrdering(rows),
     ...parked.findings,
   ]

package/src/tooling/inject.ts

@@ -16,6 +16,8 @@ import {
 import {
   applyScripts,
   collectDeps,
+  declaresInstalls,
+  minimalPackage,
   readPackage,
   serializePackage,
 } from '@/tooling/package'
@@ -156,15 +158,22 @@ export async function pruneGitignore(
 
 /**
  * Installs missing dev dependencies, fills package scripts, and merges
- * gitignore entries. A target with no package.json gets the gitignore alone,
- * plus a warning naming every install it skipped, since seeding a package.json
- * would pick a package manager and a project name on the target's behalf.
+ * gitignore entries. A target with no package.json gets a minimal one first
+ * when the chain installs anything. A package.json that exists but cannot be
+ * parsed is never rewritten, and the install is skipped with a warning.
  */
 export async function injectManifest(
   chain: readonly Manifest[],
   target: string,
 ): Promise<void> {
   const packagePath = join(target, 'package.json')
+
+  if (!existsSync(packagePath) && declaresInstalls(chain)) {
+    logStep('Writing package.json')
+    await writeFile(packagePath, serializePackage(minimalPackage(target)))
+    logAdd('package.json')
+  }
+
   const pkg = readPackage(packagePath)
 
   if (pkg) {
@@ -192,14 +201,22 @@ export async function injectManifest(
 
   await injectGitignore(chain, target)
 
-  if (!pkg) warnSkippedInstalls(chain, target)
+  if (!pkg) warnUnreadablePackage(chain, target)
 }
 
-function warnSkippedInstalls(chain: readonly Manifest[], target: string): void {
+/**
+ * Only an existing package.json that fails to parse reaches here with installs
+ * pending, since an absent one was written above. It is left untouched.
+ */
+function warnUnreadablePackage(
+  chain: readonly Manifest[],
+  target: string,
+): void {
+  if (!declaresInstalls(chain)) return
+
   const deps = collectDeps(chain, {}).map((dep) => dep.spec)
   const skipped = applyScripts({}, chain)
   const scripts = [...new Set([...skipped.added, ...skipped.overridden])]
-  if (deps.length === 0 && scripts.length === 0) return
 
   logStep('Skipped installs')
   if (deps.length > 0) {
@@ -208,5 +225,7 @@ function warnSkippedInstalls(chain: readonly Manifest[], target: string): void {
   if (scripts.length > 0) {
     logWarn(`Scripts not added: ${scripts.join(', ')}`)
   }
-  logWarn(`No package.json: run 'bun init' in ${target}, then sync again`)
+  logWarn(
+    `package.json is not valid JSON: fix it in ${target}, then sync again`,
+  )
 }

package/src/tooling/package.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
+import { basename } from 'node:path'
 import type { Manifest } from '@/tooling/manifest'
 
 export interface PackageJson {
@@ -28,6 +29,37 @@ export function readPackage(path: string): PackageJson | undefined {
   }
 }
 
+/**
+ * Whether the chain asks for any dev dependency or script, which is what makes
+ * a missing package.json worth writing. A stack that installs nothing, such as
+ * the one `canon claude` drives, leaves a project without a manifest alone.
+ */
+export function declaresInstalls(chain: readonly Manifest[]): boolean {
+  if (collectDeps(chain, {}).length > 0) return true
+
+  const scripts = applyScripts({}, chain)
+  return scripts.added.length > 0 || scripts.overridden.length > 0
+}
+
+/**
+ * The manifest a sync writes into a folder that has none. The name is the
+ * folder's, reduced to the characters npm accepts, so it is never empty or
+ * invalid.
+ */
+export function minimalPackage(target: string): PackageJson {
+  const name = basename(target)
+    .toLowerCase()
+    .replace(/[^a-z0-9-._]/g, '-')
+    .replace(/^[._]+/, '')
+    .slice(0, 214)
+
+  return {
+    name: name === '' ? 'project' : name,
+    version: '0.0.0',
+    type: 'module',
+  }
+}
+
 export function serializePackage(pkg: PackageJson): string {
   return `${JSON.stringify(pkg, null, 2)}\n`
 }

package/src/tooling/read.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { PROJECT_ROOT } from '@/roots/project'
+import { configFiles, type Manifest, seedFiles } from '@/tooling/manifest'
 
 /**
  * Spells the package root in a report where every other root spells a
@@ -11,6 +12,8 @@ import { PROJECT_ROOT } from '@/roots/project'
 const PACKAGE_LABEL = '<canon>'
 
 export interface ReferenceRoot {
+  /** The root whose `tooling/` this searches, as the manifest loader takes it. */
+  readonly root: string
   /** Absolute `tooling/` directory to search. */
   readonly dir: string
   /** How a report spells a copy found under this root. */
@@ -19,6 +22,8 @@ export interface ReferenceRoot {
 
 export interface ResolvedReference {
   readonly path: string
+  /** The root that won, so the manifest is read from the same copy. */
+  readonly root: string
   /** The label of the root that won, joined to the stack and filename. */
   readonly source: string
 }
@@ -36,8 +41,9 @@ function toolingSourceDir(root: string): string {
  */
 export function referenceRoots(root: string): ReferenceRoot[] {
   return [
-    { dir: toolingSourceDir(root), label: 'tooling' },
+    { root, dir: toolingSourceDir(root), label: 'tooling' },
     {
+      root: PROJECT_ROOT,
       dir: toolingSourceDir(PROJECT_ROOT),
       label: join(PACKAGE_LABEL, 'tooling'),
     },
@@ -49,10 +55,10 @@ export function resolveReference(
   root: string,
   stack: string,
 ): ResolvedReference | undefined {
-  for (const { dir, label } of referenceRoots(root)) {
+  for (const { root: owner, dir, label } of referenceRoots(root)) {
     const path = join(dir, stack, 'reference.md')
     if (existsSync(path)) {
-      return { path, source: join(label, stack, 'reference.md') }
+      return { path, root: owner, source: join(label, stack, 'reference.md') }
     }
   }
 
@@ -62,3 +68,40 @@ export function resolveReference(
 export function readReference(reference: ResolvedReference): string {
   return readFileSync(reference.path, 'utf8')
 }
+
+function codeList(items: readonly string[]): string {
+  return items.map((item) => `- \`${item}\``).join('\n')
+}
+
+/**
+ * The sections the verb prints after a stack's reference, read from its
+ * manifest so no reference keeps a hand list that drifts from it. A stack lists
+ * its own files and groups alone, since a parent's print under the parent's
+ * reference, and a section with nothing to list prints no heading.
+ */
+export function renderStackSections(manifest: Manifest): string {
+  const sections: string[] = []
+  const configs = configFiles(manifest)
+  const seeds = seedFiles(manifest)
+
+  if (configs.length > 0 || seeds.length > 0) {
+    const sync = ['## Sync']
+    if (configs.length > 0) {
+      sync.push('Sync keeps these current, from `configs/`:', codeList(configs))
+    }
+    if (seeds.length > 0) {
+      sync.push('Sync copies these once, from `seeds/`:', codeList(seeds))
+    }
+    sections.push(sync.join('\n\n'))
+  }
+
+  if (manifest.gitignore.length > 0) {
+    const groups = manifest.gitignore.map(
+      ({ header, entries }) =>
+        `- \`${header}\`: ${entries.map((entry) => `\`${entry}\``).join(', ')}`,
+    )
+    sections.push(`## Gitignore\n\n${groups.join('\n')}`)
+  }
+
+  return sections.map((section) => `\n${section}\n`).join('')
+}

package/src/tooling/scan.ts

@@ -12,6 +12,7 @@ import {
 import {
   collectDeps,
   collectScripts,
+  declaresInstalls,
   type DepState,
   readPackage,
   type ScriptState,
@@ -48,6 +49,7 @@ export interface ScanResult {
   readonly deps: readonly DepState[]
   readonly gitignore: readonly EntryState[]
   readonly hasPackageJson: boolean
+  readonly newManifest: boolean
   readonly totalChanges: number
 }
 
@@ -128,8 +130,10 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
 
   const packagePath = join(target, 'package.json')
   const pkg = readPackage(packagePath)
-  const scripts = pkg ? collectScripts(chain, pkg) : []
-  const deps = pkg ? collectDeps(chain, pkg) : []
+  const newManifest = !existsSync(packagePath) && declaresInstalls(chain)
+  const basis = pkg ?? (newManifest ? {} : undefined)
+  const scripts = basis ? collectScripts(chain, basis) : []
+  const deps = basis ? collectDeps(chain, basis) : []
 
   const gitignorePath = join(target, '.gitignore')
   const gitignoreContent = existsSync(gitignorePath)
@@ -138,6 +142,7 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const gitignore = scanGitignore(chain, gitignoreContent)
 
   const totalChanges =
+    (newManifest ? 1 : 0) +
     configs.filter((entry) => entry.state !== 'matching').length +
     seeds.filter((entry) => entry.state === 'missing').length +
     scripts.filter((entry) => entry.state !== 'matching').length +
@@ -152,6 +157,7 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
     deps,
     gitignore,
     hasPackageJson: pkg !== undefined,
+    newManifest,
     totalChanges,
   }
 }

package/tooling/astro/configs/card-src/pages/og-card.astro

@@ -7,7 +7,7 @@
  * an edit to one string here and a re-capture, not another pass through the
  * pick loop with an operator in it.
  *
- * `canon:draft-identity` writes the picked composition into the `.card`
+ * `canon:design-identity` writes the picked composition into the `.card`
  * element below and leaves everything around it alone. What ships is a working
  * placeholder, so the route serves before any pick has been taken.
  *