@erclx/canon 5.65.0 → 5.67.0

package/src/intake/drive-check.ts

@@ -0,0 +1,355 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { basename, isAbsolute, join, normalize } from 'node:path'
+import {
+  changedSince,
+  readWorktreeStatus,
+  type StatusEntry,
+} from '@/git/status'
+import { extractOrdinal, type IntakeRefused, openFolder } from '@/intake/folder'
+import { requirementsRel } from '@/context/requirements'
+import { bodyLines } from '@/markdown/scan'
+
+/** The record a drive leaves in its intake folder, which this check reads. */
+export const DRIVE_RECORD = 'drive.json'
+
+/** The one folder inside an intake folder that evidence may live in. */
+export const EVIDENCE_DIR = 'evidence'
+
+const SCRATCH = join('.canon', 'tmp', 'app-drive')
+
+/**
+ * The refusals this check adds to the folder lookup's own, which reach a
+ * caller unchanged as an `IntakeRefused`.
+ */
+export const DRIVE_REFUSALS = [
+  'bad-input',
+  'no-record',
+  'bad-record',
+  'no-requirements',
+  'no-baseline',
+  'unreadable-tree',
+] as const
+
+export type DriveRefusal = (typeof DRIVE_REFUSALS)[number]
+
+export interface DriveRefused {
+  readonly ok: false
+  readonly reason: DriveRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export interface BaselineRecorded {
+  readonly ok: true
+  readonly slug: string
+  readonly path: string
+  readonly entries: number
+}
+
+/** Each list names what failed, and an empty list is a clean axis. */
+export interface DriveFindings {
+  /** Goals the record carries no entry for. */
+  readonly unmapped: readonly string[]
+  /** Goals marked `not-driven` with no reason given. */
+  readonly unreasoned: readonly string[]
+  /** Entries naming a goal the requirements record does not hold. */
+  readonly unknown: readonly string[]
+  /** Paths in the main checkout that differ from the baseline. */
+  readonly changed: readonly string[]
+  /** Evidence paths that resolve outside the folder's `evidence/`. */
+  readonly strayEvidence: readonly string[]
+  /** Evidence paths inside `evidence/` that hold no file. */
+  readonly missingEvidence: readonly string[]
+  /** The drive's worktree, when the record names one still on disk. */
+  readonly worktreeLeft: readonly string[]
+}
+
+export interface DriveChecked {
+  readonly ok: true
+  readonly slug: string
+  readonly reason: 'clean' | 'failed'
+  readonly goals: number
+  readonly findings: DriveFindings
+}
+
+export type BaselineOutcome = BaselineRecorded | DriveRefused
+export type CheckOutcome = DriveChecked | DriveRefused | IntakeRefused
+
+type GoalStatus = 'driven' | 'not-driven'
+
+interface DriveGoal {
+  readonly goal: string
+  readonly status: GoalStatus
+  readonly reason?: string
+}
+
+interface DriveRecord {
+  readonly goals: readonly DriveGoal[]
+  readonly evidence: readonly string[]
+  readonly worktree?: string
+}
+
+function refuse(
+  reason: DriveRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): DriveRefused {
+  return { ok: false, reason, message, detail }
+}
+
+/**
+ * A goal as both sides compare it: a leading bold label and a trailing period
+ * dropped, and whitespace collapsed. Requirements records carry no goal ids,
+ * so the text is the identity, and stripping the label lets a drive record
+ * paste the bullet whole or name the sentence alone.
+ */
+function normalizeGoal(text: string): string {
+  return text
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^\*\*[^*]+\*\*\s*/, '')
+    .replace(/\.$/, '')
+    .trim()
+}
+
+/**
+ * Every top-level bullet under `## Goals`, through any H3 grouping, up to the
+ * next H2. A wrapped bullet's indented continuation joins it, and a nested
+ * bullet is detail of its parent rather than a goal of its own.
+ */
+export function readGoals(source: string): string[] {
+  const goals: string[] = []
+  let inGoals = false
+  let current: string | undefined
+  let appending = false
+
+  const close = () => {
+    if (current !== undefined) goals.push(normalizeGoal(current))
+    current = undefined
+    appending = false
+  }
+
+  for (const line of bodyLines(source)) {
+    if (line.fenced) continue
+    const text = line.text
+
+    if (/^#{1,2}\s/.test(text)) {
+      close()
+      inGoals = /^##\s+Goals\s*$/.test(text)
+      continue
+    }
+    if (!inGoals) continue
+
+    const bullet = /^[-*]\s+(.*)$/.exec(text)
+    if (bullet) {
+      close()
+      current = bullet[1]
+      appending = true
+    } else if (/^\s+[-*]\s/.test(text) || text.trim() === '') {
+      appending = false
+    } else if (appending && /^\s+\S/.test(text)) {
+      current = `${current} ${text.trim()}`
+    } else if (/^#{3,}\s/.test(text)) {
+      appending = false
+    }
+  }
+  close()
+
+  return goals
+}
+
+function parseRecord(raw: string): DriveRecord | string {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return `${DRIVE_RECORD} does not parse as JSON.`
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return `${DRIVE_RECORD} is not an object.`
+  }
+
+  const { goals, evidence, worktree } = parsed as Record<string, unknown>
+  if (!Array.isArray(goals)) {
+    return `${DRIVE_RECORD} carries no "goals" list.`
+  }
+
+  const entries: DriveGoal[] = []
+  for (const [index, entry] of goals.entries()) {
+    const { goal, status, reason } = (entry ?? {}) as Record<string, unknown>
+    if (typeof goal !== 'string' || goal.trim() === '') {
+      return `${DRIVE_RECORD} goals[${index}] carries no "goal" text.`
+    }
+    if (status !== 'driven' && status !== 'not-driven') {
+      return `${DRIVE_RECORD} goals[${index}] has a "status" other than "driven" or "not-driven".`
+    }
+    entries.push({
+      goal,
+      status,
+      ...(typeof reason === 'string' && { reason }),
+    })
+  }
+
+  if (
+    evidence !== undefined &&
+    (!Array.isArray(evidence) ||
+      !evidence.every((item): item is string => typeof item === 'string'))
+  ) {
+    return `${DRIVE_RECORD} carries an "evidence" field that is not a list of paths.`
+  }
+  if (worktree !== undefined && typeof worktree !== 'string') {
+    return `${DRIVE_RECORD} carries a "worktree" that is not a path.`
+  }
+
+  return {
+    goals: entries,
+    evidence: evidence ?? [],
+    ...(worktree !== undefined && { worktree }),
+  }
+}
+
+function isEvidencePath(path: string): boolean {
+  if (isAbsolute(path)) return false
+  const segments = normalize(path).split(/[\\/]/)
+  return (
+    segments[0] === EVIDENCE_DIR &&
+    segments.length > 1 &&
+    !segments.includes('..')
+  )
+}
+
+/**
+ * The scratch key for a topic, with any ordinal dropped, so a baseline taken
+ * before the intake folder is numbered and a check naming the numbered folder
+ * meet at one file. Undefined for a slug that could leave scratch.
+ */
+function bareSlug(slug: string): string | undefined {
+  if (!/^[a-z0-9][a-z0-9.-]*$/i.test(slug) || slug.includes('..')) {
+    return undefined
+  }
+  const ordinal = extractOrdinal(slug)
+  return ordinal === '' ? slug : slug.slice(ordinal.length + 1)
+}
+
+function baselinePath(root: string, bare: string): string {
+  return join(root, SCRATCH, bare, 'baseline.json')
+}
+
+function badSlug(slug: string): DriveRefused {
+  return refuse(
+    'bad-input',
+    `Not an intake slug: ${slug}. Pass the folder's topic, as in app-drive-1-0.`,
+  )
+}
+
+/**
+ * Stores the main checkout's status before a drive, so the check can tell a
+ * write the drive made from one already in the tree. Scratch rather than the
+ * intake folder, since the baseline is safe to lose once the check passes and
+ * the folder holds findings alone. A second call replaces the first.
+ */
+export async function recordBaseline(
+  root: string,
+  slug: string,
+): Promise<BaselineOutcome> {
+  const bare = bareSlug(slug)
+  if (bare === undefined) return badSlug(slug)
+
+  const status = await readWorktreeStatus(root)
+  if (status === undefined) {
+    return refuse('unreadable-tree', `git cannot read the status of ${root}.`)
+  }
+
+  const path = baselinePath(root, bare)
+  await mkdir(join(path, '..'), { recursive: true })
+  await writeFile(path, `${JSON.stringify(status)}\n`)
+
+  return { ok: true, slug: bare, path, entries: status.length }
+}
+
+/**
+ * Checks a finished drive against its intake folder's `drive.json`: every
+ * goal mapped or skipped with a reason, the main checkout unchanged since the
+ * baseline, the evidence inside the folder's `evidence/`, and the drive's
+ * worktree gone. It reports what failed and never reverts a changed path,
+ * since only the operator knows which of them to keep.
+ */
+export async function checkDrive(
+  root: string,
+  slug: string,
+): Promise<CheckOutcome> {
+  const bare = bareSlug(slug)
+  if (bare === undefined) return badSlug(slug)
+
+  const folder = await openFolder(root, slug)
+  if (typeof folder !== 'string') return folder
+
+  const recordPath = join(folder, DRIVE_RECORD)
+  if (!existsSync(recordPath)) {
+    return refuse(
+      'no-record',
+      `No ${DRIVE_RECORD} in ${basename(folder)}, so no drive was recorded.`,
+    )
+  }
+  const record = parseRecord(await readFile(recordPath, 'utf8'))
+  if (typeof record === 'string') return refuse('bad-record', record)
+
+  const requirements = join(root, requirementsRel(root))
+  if (!existsSync(requirements)) {
+    return refuse(
+      'no-requirements',
+      `No requirements record at ${requirementsRel(root)}, so no goal can be checked.`,
+    )
+  }
+  const goals = readGoals(await readFile(requirements, 'utf8'))
+
+  let baseline: readonly StatusEntry[]
+  try {
+    baseline = JSON.parse(await readFile(baselinePath(root, bare), 'utf8'))
+  } catch {
+    return refuse(
+      'no-baseline',
+      `No baseline for ${bare}. Run canon intake drive-check ${bare} --baseline before the drive.`,
+    )
+  }
+  const current = await readWorktreeStatus(root)
+  if (current === undefined) {
+    return refuse('unreadable-tree', `git cannot read the status of ${root}.`)
+  }
+
+  const entries = new Map(
+    record.goals.map((entry) => [normalizeGoal(entry.goal), entry]),
+  )
+  const known = new Set(goals)
+  const unreasoned = goals.filter((goal) => {
+    const entry = entries.get(goal)
+    return entry?.status === 'not-driven' && !entry.reason?.trim()
+  })
+
+  const findings: DriveFindings = {
+    unmapped: goals.filter((goal) => !entries.has(goal)),
+    unreasoned,
+    unknown: record.goals
+      .filter((entry) => !known.has(normalizeGoal(entry.goal)))
+      .map((entry) => entry.goal),
+    changed: changedSince(baseline, current),
+    strayEvidence: record.evidence.filter((path) => !isEvidencePath(path)),
+    missingEvidence: record.evidence.filter(
+      (path) => isEvidencePath(path) && !existsSync(join(folder, path)),
+    ),
+    worktreeLeft:
+      record.worktree !== undefined && existsSync(record.worktree)
+        ? [record.worktree]
+        : [],
+  }
+  const failed = Object.values(findings).some((list) => list.length > 0)
+
+  return {
+    ok: true,
+    slug: basename(folder),
+    reason: failed ? 'failed' : 'clean',
+    goals: goals.length,
+    findings,
+  }
+}

package/src/intake/folder.ts

@@ -142,7 +142,7 @@ export function extractOrdinal(name: string): string {
   return /^\d{2,}-/.exec(name)?.[0].slice(0, -1) ?? ''
 }
 
-async function openFolder(
+export async function openFolder(
   root: string,
   slug: string,
 ): Promise<string | IntakeRefused> {

package/src/labels/apply.ts

@@ -20,20 +20,25 @@ export interface LabelDiff {
  * A label the remote lacks is separated from the addable set rather than
  * dropped, because the REST add endpoint creates any label it is handed and
  * that write to the repository settings is not the map's call.
+ *
+ * Names match regardless of case, as GitHub holds them, so this agrees with
+ * `missingLabels` on which labels the remote carries.
  */
 export function diffLabels(
   earned: readonly string[],
   present: readonly string[],
   remote: readonly string[],
 ): LabelDiff {
-  const has = new Set(present)
-  const carried = new Set(remote)
+  const fold = (labels: readonly string[]): Set<string> =>
+    new Set(labels.map((label) => label.toLowerCase()))
+  const has = fold(present)
+  const carried = fold(remote)
 
-  const owed = earned.filter((label) => !has.has(label))
+  const owed = earned.filter((label) => !has.has(label.toLowerCase()))
 
   return {
     owed,
-    toAdd: owed.filter((label) => carried.has(label)),
-    missingOnRemote: owed.filter((label) => !carried.has(label)),
+    toAdd: owed.filter((label) => carried.has(label.toLowerCase())),
+    missingOnRemote: owed.filter((label) => !carried.has(label.toLowerCase())),
   }
 }

package/src/labels/sync.ts

@@ -0,0 +1,17 @@
+/**
+ * The labels a map names that the remote does not carry yet, in map order.
+ *
+ * Only ever a subset of the map, so a label a person made by hand never
+ * appears and nothing here can become an edit or a deletion on the remote.
+ *
+ * GitHub holds label names unique regardless of case, so a remote `Docs`
+ * counts as carrying `docs`. Creating it would be refused, and every later
+ * run would report the same failure.
+ */
+export function missingLabels(
+  mapLabels: readonly string[],
+  remote: readonly string[],
+): string[] {
+  const carried = new Set(remote.map((label) => label.toLowerCase()))
+  return mapLabels.filter((label) => !carried.has(label.toLowerCase()))
+}

package/src/markdown/scan.ts

@@ -122,6 +122,16 @@ export function bodyLines(source: string): BodyLine[] {
   )
 }
 
+/**
+ * Counts whitespace-delimited tokens, the unit a record's word cap is stated
+ * in. A code span counts as the tokens it holds, so a line citing a long path
+ * pays for it the way a reader does. A caller gating on the count hands in
+ * prose with fenced lines already dropped.
+ */
+export function wordCount(text: string): number {
+  return text.match(/\S+/g)?.length ?? 0
+}
+
 /**
  * Drops every fenced block from raw text, frontmatter included as content.
  *

package/src/pr/close.ts

@@ -0,0 +1,152 @@
+import { scanPhaseLabels } from '@/labels/phase'
+import { BAN_SETS } from '@/markdown/bans'
+import { type DensityFinding, densityFindings } from '@/markdown/density'
+import { bodyLines, scanBans } from '@/markdown/scan'
+
+/** Why the verb did not close, in the order the refusals are read. */
+export type CloseRefusal =
+  | 'no-reason'
+  | 'reason-unpublishable'
+  | 'gh-failed'
+  | 'pull-closed'
+  | 'head-mismatch'
+  | 'comment-failed'
+  | 'close-failed'
+
+export interface ClosePull {
+  readonly isOpen: boolean
+  /** The head branch name, which the caller's expected head is checked against. */
+  readonly branch: string
+  /** Whether the head lives in another repository, whose branch this one cannot delete. */
+  readonly isFork: boolean
+}
+
+/**
+ * Everything the verb reads or writes, injected so every refusal runs without
+ * a network. A read or write that failed returns undefined or false, never a
+ * guess.
+ */
+export interface CloseApi {
+  readPull(): Promise<ClosePull | undefined>
+  /** Posts the reason and answers the comment's URL. */
+  postComment(body: string): Promise<string | undefined>
+  patchClosed(): Promise<boolean>
+  deleteBranch(branch: string): Promise<boolean>
+}
+
+export interface CloseOptions {
+  readonly number: number
+  readonly reason: string
+  /** The head branch the caller means, so a mistyped number closes nothing. */
+  readonly head: string
+  readonly isKeepBranch: boolean
+}
+
+/** What the reason carries that a reader on the remote cannot use. */
+export interface ReasonFindings {
+  readonly isClean: boolean
+  readonly bannedCharacters: readonly string[]
+  readonly phaseLabels: readonly string[]
+  readonly boardReferences: readonly string[]
+  readonly sessionLinks: readonly string[]
+  readonly density: readonly DensityFinding[]
+}
+
+/** What happened to the head branch once the pull request closed. */
+export type BranchOutcome = 'deleted' | 'kept' | 'fork' | 'delete-failed'
+
+export interface CloseRecord {
+  readonly reason: 'closed' | CloseRefusal
+  readonly isOk: boolean
+  readonly number: number
+  readonly commentUrl?: string
+  readonly branch?: BranchOutcome
+  readonly findings?: ReasonFindings
+}
+
+/**
+ * Runs the checks `canon labels scan` runs on a pull request body, plus
+ * density measured on the reason itself.
+ *
+ * The scan's own post density reads a body only when it opens on a known
+ * post heading, and a closing comment carries none, so an overloaded reason
+ * would pass it unmeasured.
+ */
+export function checkReason(reason: string): ReasonFindings {
+  const lines = bodyLines(reason)
+  const bannedCharacters = scanBans(lines, BAN_SETS).map(
+    (finding) => finding.term,
+  )
+  const { phaseLabels, boardReferences, sessionLinks } = scanPhaseLabels({
+    title: '',
+    body: reason,
+    headRefName: '',
+  })
+  const density = densityFindings(lines)
+
+  return {
+    isClean:
+      bannedCharacters.length === 0 &&
+      phaseLabels.length === 0 &&
+      boardReferences.length === 0 &&
+      sessionLinks.length === 0 &&
+      density.length === 0,
+    bannedCharacters,
+    phaseLabels,
+    boardReferences,
+    sessionLinks,
+    density,
+  }
+}
+
+function refused(
+  reason: CloseRefusal,
+  number: number,
+  extra: Partial<CloseRecord> = {},
+): CloseRecord {
+  return { reason, isOk: false, number, ...extra }
+}
+
+/**
+ * Closes one pull request unmerged with its reason posted first.
+ *
+ * The comment lands before the close, so a failure between the two leaves a
+ * comment on an open pull request rather than a closed one carrying no
+ * reason, which is the defect this verb exists to remove. The branch delete
+ * runs last and never fails the close, since the pull request is already
+ * closed with its reason by then.
+ */
+export async function close(
+  api: CloseApi,
+  opts: CloseOptions,
+): Promise<CloseRecord> {
+  const { number } = opts
+  const reason = opts.reason.trim()
+
+  if (reason === '') return refused('no-reason', number)
+  const findings = checkReason(reason)
+  if (!findings.isClean) {
+    return refused('reason-unpublishable', number, { findings })
+  }
+
+  const pull = await api.readPull()
+  if (pull === undefined) return refused('gh-failed', number)
+  if (!pull.isOpen) return refused('pull-closed', number)
+  if (pull.branch !== opts.head) return refused('head-mismatch', number)
+
+  const commentUrl = await api.postComment(reason)
+  if (commentUrl === undefined) return refused('comment-failed', number)
+
+  if (!(await api.patchClosed())) {
+    return refused('close-failed', number, { commentUrl })
+  }
+
+  let branch: BranchOutcome
+  if (opts.isKeepBranch) branch = 'kept'
+  else if (pull.isFork) branch = 'fork'
+  else {
+    branch = (await api.deleteBranch(pull.branch)) ? 'deleted' : 'delete-failed'
+  }
+
+  return { reason: 'closed', isOk: true, number, commentUrl, branch }
+}