@erclx/canon 5.47.0 → 5.49.0

package/src/pr/merge.ts

@@ -0,0 +1,175 @@
+import type { ChecksGate } from '@/pr/lift'
+import { readSection } from '@/pr/paths'
+import { UI_PASS_MARKER } from '@/pr/tick'
+
+/** Why the verb did not merge, in the order the refusals are read. */
+export type MergeRefusal =
+  | 'pull-closed'
+  | 'pull-draft'
+  | 'missing-summary'
+  | 'missing-key-changes'
+  | 'ci-failing'
+  | 'ci-conflicted'
+  | 'ci-pending'
+  | 'head-moved'
+  | 'not-mergeable'
+  | 'gh-failed'
+
+export interface MergePull {
+  readonly isOpen: boolean
+  readonly isDraft: boolean
+  readonly title: string
+  readonly body: string
+  /** The head the merge is pinned to, so a push after the read refuses. */
+  readonly head: string
+}
+
+export interface MergeRequest {
+  readonly title: string
+  readonly description: string
+  readonly sha: string
+}
+
+/** What the merge endpoint answered, with 409 and 405 told apart from a merge. */
+export type MergeOutcome =
+  | { readonly kind: 'merged'; readonly sha: string }
+  | { readonly kind: 'head-moved' }
+  | { readonly kind: 'not-mergeable' }
+  | { readonly kind: 'failed' }
+
+/**
+ * Everything the verb reads or writes, injected so every refusal runs without
+ * a network. A read that failed returns undefined, and the verb refuses
+ * `gh-failed` rather than reading absence as a pass.
+ */
+export interface MergeApi {
+  readPull(): Promise<MergePull | undefined>
+  readChecks(head: string): Promise<ChecksGate | undefined>
+  putMerge(request: MergeRequest): Promise<MergeOutcome>
+}
+
+export interface MergeOptions {
+  readonly number: number
+  readonly isDryRun: boolean
+}
+
+export interface MergeRecord {
+  readonly reason: 'merged' | 'dry-run' | MergeRefusal
+  readonly isOk: boolean
+  readonly number: number
+  readonly title?: string
+  readonly description?: string
+  /** The squash commit, present only on a merge. */
+  readonly sha?: string
+}
+
+export type Composed =
+  | { readonly kind: 'composed'; readonly description: string }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'missing-summary' | 'missing-key-changes'
+    }
+
+/** A section's text with the UI pass line dropped, or undefined when nothing is left. */
+function keptSection(body: string, title: string): string | undefined {
+  const text = readSection(body, title)
+    ?.split('\n')
+    .filter((line) => !line.includes(UI_PASS_MARKER))
+    .join('\n')
+    .trim()
+  return text === undefined || text === ''
+    ? undefined
+    : `## ${title}\n\n${text}`
+}
+
+/**
+ * The squash description: Summary, Key changes, and Technical context, in that
+ * order, under their headings. Testing, the reviewer requests, and the UI pass
+ * line describe the review rather than the change, so none reaches the trunk.
+ * Technical context is optional, and an empty one leaves no bare heading.
+ */
+export function composeDescription(body: string): Composed {
+  const summary = keptSection(body, 'Summary')
+  if (summary === undefined)
+    return { kind: 'refused', reason: 'missing-summary' }
+  const keyChanges = keptSection(body, 'Key changes')
+  if (keyChanges === undefined) {
+    return { kind: 'refused', reason: 'missing-key-changes' }
+  }
+  const context = keptSection(body, 'Technical context')
+  return {
+    kind: 'composed',
+    description: [summary, keyChanges, context]
+      .filter((block) => block !== undefined)
+      .join('\n\n'),
+  }
+}
+
+/** The suffix the web merge adds and the trunk log carries. */
+export function mergeTitle(title: string, number: number): string {
+  return `${title} (#${number})`
+}
+
+function refused(
+  reason: MergeRefusal,
+  number: number,
+  message: { title?: string; description?: string } = {},
+): MergeRecord {
+  return { reason, isOk: false, number, ...message }
+}
+
+/**
+ * Squash-merges one ready pull request with a message carrying only the
+ * change. Every refusal is read before the one write, and the write sends the
+ * head it read as `sha`, so GitHub refuses rather than merging a commit pushed
+ * after the checks were read. The verb reads the draft flag and not the review
+ * comments, since a ready pull request already passed the lift's gates.
+ */
+export async function merge(
+  api: MergeApi,
+  opts: MergeOptions,
+): Promise<MergeRecord> {
+  const { number } = opts
+
+  const pull = await api.readPull()
+  if (pull === undefined) return refused('gh-failed', number)
+  if (!pull.isOpen) return refused('pull-closed', number)
+  if (pull.isDraft) return refused('pull-draft', number)
+
+  const title = mergeTitle(pull.title, number)
+  const composed = composeDescription(pull.body)
+  if (composed.kind === 'refused') {
+    return refused(composed.reason, number, { title })
+  }
+  const message = { title, description: composed.description }
+
+  const checks = await api.readChecks(pull.head)
+  if (checks === undefined) return refused('gh-failed', number, message)
+  if (checks.state === 'failing') return refused('ci-failing', number, message)
+  if (checks.state !== 'passing') {
+    return refused(
+      checks.isConflicted ? 'ci-conflicted' : 'ci-pending',
+      number,
+      message,
+    )
+  }
+
+  if (opts.isDryRun)
+    return { reason: 'dry-run', isOk: true, number, ...message }
+
+  const outcome = await api.putMerge({ ...message, sha: pull.head })
+  if (outcome.kind === 'merged') {
+    return {
+      reason: 'merged',
+      isOk: true,
+      number,
+      ...message,
+      sha: outcome.sha,
+    }
+  }
+  return refused(
+    outcome.kind === 'failed' ? 'gh-failed' : outcome.kind,
+    number,
+    message,
+  )
+}

package/src/pr/rest.ts

@@ -13,6 +13,7 @@ import type { ReviewRow } from '@/pr/review-scope'
 /** One row of `repos/{owner}/{repo}/pulls/<n>` or of the pulls listing. */
 export interface RestPull {
   readonly number?: number
+  readonly title?: string
   readonly body?: string | null
   readonly head?: { readonly ref?: string; readonly sha?: string }
   readonly base?: { readonly ref?: string }
@@ -24,6 +25,8 @@ export interface RestPull {
 
 /** One row of `repos/{owner}/{repo}/pulls/<n>/reviews`. */
 export interface RestReview {
+  /** The id the update call `pulls/<n>/reviews/<id>` names. */
+  readonly id?: number
   readonly body?: string | null
   readonly commit_id?: string | null
   readonly submitted_at?: string | null

package/src/pr/review-scope.ts

@@ -136,11 +136,21 @@ export const UI_HEADINGS = ['## UI review', '## UI review closed'] as const
 
 export type UiHeading = (typeof UI_HEADINGS)[number]
 
+/** The four totals on a verdict's count line. */
+export interface UiCounts {
+  readonly failed: number
+  readonly eyes: number
+  readonly passed: number
+  readonly notDriven: number
+}
+
 export interface UiScope {
   readonly heading?: UiHeading
   readonly state: ReviewState
   /** The head the verdict covered, a full or abbreviated sha. */
   readonly commit?: string
+  /** The counts the verdict wrote, absent when its count line does not parse. */
+  readonly counts?: UiCounts
   /** `marker` is the verdict's own record, `fallback` is GitHub's stamp. */
   readonly source: ScopeSource
 }
@@ -152,6 +162,32 @@ export interface UiScope {
  */
 const UI_MARKER = /^<!--\s*review-ui:\s*head=([0-9a-f]{7,40})\s*-->$/
 
+/**
+ * The count line `review-ui`'s `post.md` fixes as the verdict's first line
+ * under the heading. It is model-written prose, so a body that drifts from the
+ * form reads as no counts and a caller treats that as unchecked.
+ */
+const UI_COUNTS =
+  /^(\d+) failed · (\d+) need your eyes · (\d+) passed · (\d+) not driven$/
+
+export function readUiCounts(body: string): UiCounts | undefined {
+  for (const raw of body.split('\n').slice(1, 6)) {
+    const match = UI_COUNTS.exec(raw.trim())
+    if (match === null) continue
+    const [, failed, eyes, passed, notDriven] = match.map(Number)
+    if (
+      failed === undefined ||
+      eyes === undefined ||
+      passed === undefined ||
+      notDriven === undefined
+    ) {
+      return undefined
+    }
+    return { failed, eyes, passed, notDriven }
+  }
+  return undefined
+}
+
 function lastLine(body: string): string | undefined {
   const lines = body.split('\n')
 
@@ -185,9 +221,11 @@ export function resolveUiScope(listing: ReviewListing): UiScope {
   const line = lastLine(row.body ?? '')
   const match = line === undefined ? null : UI_MARKER.exec(line)
   const marked = match?.[1]
+  const counts = readUiCounts(row.body ?? '')
+  const counted = counts === undefined ? {} : { counts }
 
   if (marked !== undefined) {
-    return { heading, state, commit: marked, source: 'marker' }
+    return { heading, state, commit: marked, ...counted, source: 'marker' }
   }
 
   const oid = row.commit?.oid
@@ -195,6 +233,7 @@ export function resolveUiScope(listing: ReviewListing): UiScope {
     heading,
     state,
     ...(oid === undefined || oid === '' ? {} : { commit: oid }),
+    ...counted,
     source: 'fallback',
   }
 }

package/src/pr/tick.ts

@@ -1,4 +1,5 @@
 import {
+  type ChecklistBox,
   CHECKLIST_END,
   CHECKLIST_START,
   parseBoxLine,
@@ -7,7 +8,7 @@ import {
   writeBoxLine,
 } from '@/pr/evidence'
 
-const UI_PASS_MARKER = '<!-- pr-ui-pass -->'
+export const UI_PASS_MARKER = '<!-- pr-ui-pass -->'
 const TESTING_HEADING = /^## Testing\s*$/
 const SECTION_HEADING = /^## /
 const REVIEWER_HEADING = /^## For the reviewer\s*$/
@@ -48,6 +49,25 @@ export function uiPassLine(summary: UiPassSummary): string {
   return `- [${box}] UI pass, ${summary.passed} of ${summary.total} boxes passed at ${at}${tail} ${UI_PASS_MARKER}`
 }
 
+/**
+ * The driven boxes ticked at the head. A tick counts as this pass's only when
+ * stamped at the head, since an unstamped one is the author's claim and an
+ * older stamp names another head. Taste boxes are left out, as the body line
+ * leaves them out.
+ */
+export function countTicksAtHead(
+  boxes: readonly ChecklistBox[],
+  head: string,
+): number {
+  return boxes.filter(
+    (box) =>
+      !box.isTaste &&
+      box.isTicked &&
+      box.stamp !== undefined &&
+      head.startsWith(box.stamp),
+  ).length
+}
+
 /** The short sha the marked line names, absent when the body carries no such line. */
 export function readUiPassHead(body: string): string | undefined {
   const line = body.split('\n').find((row) => row.includes(UI_PASS_MARKER))

package/src/records/structure.ts

@@ -0,0 +1,147 @@
+import { type DensityKind, densityFindings } from '@/markdown/density'
+import { bodyLines } from '@/markdown/scan'
+import { isSectionMarker } from '@/markdown/structure'
+
+/**
+ * The criteria `plan.md`'s `### Structure` states for every hand-written
+ * record. `S6`, a full path in a section a parser reads, is not here, since
+ * `canon tasks plan-reach` already reports a bare filename as unclaimed.
+ */
+export const STRUCTURE_CRITERIA = ['S1', 'S2', 'S3', 'S4', 'S5'] as const
+
+export type StructureCriterion = (typeof STRUCTURE_CRITERIA)[number]
+
+/** One place a record misses a criterion, or an intake field spilling past its line. */
+export interface StructureEntry {
+  readonly criterion: StructureCriterion | 'intake-spill'
+  /** The line as an editor numbers it, frontmatter included. */
+  readonly line: number
+  readonly message: string
+}
+
+/**
+ * The density limits a record criterion takes over. The paragraph limits are
+ * left out, since the record standard caps no paragraph and names no run.
+ */
+const CRITERION_OF: Partial<Record<DensityKind, StructureCriterion>> = {
+  'bullet-run': 'S2',
+  'h3-opening': 'S3',
+  'bullet-length': 'S4',
+  'heading-depth': 'S5',
+}
+
+const MESSAGE: Record<StructureCriterion, string> = {
+  S1: 'is a bold label standing alone as a section marker. Write it as an H2.',
+  S2: 'opens a run of more than 5 plain bullets. Group them under H3s.',
+  S3: 'opens with no lead sentence carrying what its bullets share.',
+  S4: 'is a bullet past 200 characters. Make it a short paragraph, or split it.',
+  S5: 'is an H4 or deeper. Fold it into its H3.',
+}
+
+/**
+ * Every place a record misses `S1` to `S5`, in line order.
+ *
+ * `S2` to `S5` are the markdown density limits read on the record's own
+ * terms, so a labeled field run stays exempt from `S2` here as it does there.
+ * `S1` is any line `isSectionMarker` reads as a bold section marker, which an
+ * old plan carries on every section and still parses through.
+ */
+export function structureFindings(text: string): StructureEntry[] {
+  const lines = bodyLines(text)
+  const found: StructureEntry[] = []
+
+  for (const line of lines) {
+    if (!line.fenced && isSectionMarker(line.text)) {
+      found.push({ criterion: 'S1', line: line.number, message: MESSAGE.S1 })
+    }
+  }
+
+  for (const density of densityFindings(lines)) {
+    const criterion = CRITERION_OF[density.kind]
+    if (criterion) {
+      found.push({ criterion, line: density.line, message: MESSAGE[criterion] })
+    }
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}
+
+/** An item heading, as `readItems` in `src/intake/items.ts` reads one. */
+const ITEM_HEADING = /^###\s+\d+[a-z]*\.\s/i
+
+/** A bolded field bullet, the one line `readItems` takes from a field. */
+const FIELD = /^-\s+\*\*([^*]+):\*\*/
+
+/** Any heading, which closes the item above it. */
+const SECTION = /^#{1,6}\s/
+
+/**
+ * Every block of content sitting under an intake field rather than on its
+ * line, one entry at the block's first line.
+ *
+ * `canon intake list` reads a field's own line and nothing under it, so a
+ * nested list or a paragraph below a field never reaches the operator
+ * answering in chat. A trailing paragraph after the last field is reported
+ * too, since it is dropped the same way.
+ */
+export function intakeSpill(text: string): StructureEntry[] {
+  const found: StructureEntry[] = []
+  let item: string | undefined
+  let field: string | undefined
+  let spilling = false
+
+  for (const line of bodyLines(text)) {
+    if (line.fenced) continue
+
+    const heading = ITEM_HEADING.exec(line.text)
+    if (heading || SECTION.test(line.text)) {
+      item = heading
+        ? line.text.replace(/^###\s+/, '').split('.')[0]
+        : undefined
+      field = undefined
+      spilling = false
+      continue
+    }
+
+    if (item === undefined || line.text.trim() === '') continue
+
+    const match = FIELD.exec(line.text)
+    if (match) {
+      field = match[1].trim()
+      spilling = false
+      continue
+    }
+
+    if (spilling) continue
+    spilling = true
+
+    const under = field ? `the ${field} field of item ${item}` : `item ${item}`
+    found.push({
+      criterion: 'intake-spill',
+      line: line.number,
+      message: `sits under ${under}, and canon intake list reads only a field's own line. Keep the content on the line, or split the item.`,
+    })
+  }
+
+  return found
+}
+
+/**
+ * The structure report for an intake cluster file. Item headings open on
+ * their fields by the template's design, so `S3` skips them, and a field
+ * carries its whole content on one line, so `S4` skips it.
+ */
+export function intakeStructure(text: string): StructureEntry[] {
+  const lines = text.split('\n')
+  const exempt = (entry: StructureEntry): boolean => {
+    const source = lines[entry.line - 1] ?? ''
+    if (entry.criterion === 'S3') return ITEM_HEADING.test(source)
+    if (entry.criterion === 'S4') return FIELD.test(source)
+    return false
+  }
+
+  return [
+    ...structureFindings(text).filter((entry) => !exempt(entry)),
+    ...intakeSpill(text),
+  ].sort((a, b) => a.line - b.line)
+}

package/src/records/validate.ts

@@ -3,6 +3,11 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { linesOutsideFences } from '@/markdown/scan'
+import {
+  intakeStructure,
+  type StructureEntry,
+  structureFindings,
+} from '@/records/structure'
 import {
   recordDir as resolveRecordDir,
   recordDirs as resolveRecordDirs,
@@ -27,7 +32,11 @@ export type RecordKind = (typeof RECORD_KINDS)[number]
  * union covering only what the walk returns would type a record the command can
  * emit as impossible.
  */
-export const VALIDATE_REFUSALS = ['no-folder', 'unknown-kind'] as const
+export const VALIDATE_REFUSALS = [
+  'no-folder',
+  'no-record',
+  'unknown-kind',
+] as const
 
 export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
 
@@ -61,11 +70,24 @@ export interface Finding {
   readonly message: string
 }
 
+/**
+ * A place a record misses a structure criterion. It sits apart from `Finding`
+ * so it never sets the exit, since every record written before the criteria
+ * misses `S1` and a gate on it would fail them all.
+ */
+export interface StructureFinding extends StructureEntry {
+  /** The record the entry sits in, relative to the validated folder. */
+  readonly record: string
+  /** The file inside a folder record, or the record itself for a plan. */
+  readonly subject: string
+}
+
 export interface ValidateReport {
   readonly ok: true
   readonly kind: RecordKind
   readonly records: number
   readonly findings: readonly Finding[]
+  readonly structure: readonly StructureFinding[]
 }
 
 export interface ValidateRefused {
@@ -267,7 +289,7 @@ export function sectionMarker(line: string): PlanSection | undefined {
 
 /** The spelling a finding names, which is the one the standard's template ships. */
 export function preferredMarker(section: PlanSection): string {
-  return section === 'Summary' ? '## Summary' : `**${section}:**`
+  return `## ${section}`
 }
 
 export function splitPlanSections(text: string): Map<string, string[]> {
@@ -915,6 +937,42 @@ const FOLDER_CHECK: Readonly<
   teach: checkWorkspace,
 }
 
+/**
+ * The files of a folder record the structure report reads. A groundwork
+ * track's `evidence/`, `scripts/`, and `clones/` sit below the top level and
+ * hold copies and raw output, so only its index and numbered files are read.
+ * An intake folder's reserved files hold no items, so only clusters are.
+ */
+const STRUCTURE_FILES: Readonly<
+  Partial<Record<RecordKind, (file: string) => boolean>>
+> = {
+  groundwork: (file) => file === GROUNDWORK_INDEX || NUMBERED_FILE.test(file),
+  intake: (file) => file !== INTAKE_INDEX && file !== INTAKE_HANDOFF,
+}
+
+async function folderStructure(
+  dir: string,
+  kind: RecordKind,
+  slug: string,
+): Promise<StructureFinding[]> {
+  const reads = STRUCTURE_FILES[kind]
+  if (!reads) return []
+
+  const report = kind === 'intake' ? intakeStructure : structureFindings
+  const files = (await listMarkdown(dir)).filter(reads)
+  const perFile = await Promise.all(
+    files.map(async (file) =>
+      report(await readFile(join(dir, file), 'utf8')).map((entry) => ({
+        ...entry,
+        record: slug,
+        subject: file,
+      })),
+    ),
+  )
+
+  return perFile.flat()
+}
+
 function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
@@ -923,17 +981,42 @@ function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
 async function validateFiles(
   dir: string,
   kind: RecordKind,
+  files: readonly string[],
   check: (name: string, text: string) => Finding[],
 ): Promise<ValidateReport> {
-  const files = await listMarkdown(dir)
-
   const perFile = await Promise.all(
-    files.map(async (file) =>
-      check(file, await readFile(join(dir, file), 'utf8')),
-    ),
+    files.map(async (file) => {
+      const text = await readFile(join(dir, file), 'utf8')
+      return {
+        findings: check(file, text),
+        structure: structureFindings(text).map((entry) => ({
+          ...entry,
+          record: file,
+          subject: file,
+        })),
+      }
+    }),
   )
 
-  return { ok: true, kind, records: files.length, findings: perFile.flat() }
+  return {
+    ok: true,
+    kind,
+    records: files.length,
+    findings: perFile.flatMap((one) => one.findings),
+    structure: perFile.flatMap((one) => one.structure),
+  }
+}
+
+/**
+ * Narrows a listing to the one record a caller named, by a plan's stem or a
+ * folder's slug, so a writing skill reads its own record and not every old one.
+ */
+function narrow(
+  names: readonly string[],
+  record: string | undefined,
+): readonly string[] {
+  if (record === undefined) return names
+  return names.filter((name) => name === record || name === `${record}.md`)
 }
 
 /**
@@ -944,6 +1027,7 @@ async function validateFiles(
 export async function validateRecords(
   root: string,
   kind: RecordKind,
+  record?: string,
 ): Promise<ValidateOutcome> {
   const dir = recordsDir(root, kind)
 
@@ -954,13 +1038,30 @@ export async function validateRecords(
     )
   }
 
-  if (kind === 'plans') return validateFiles(dir, kind, checkPlan)
+  const names = narrow(
+    kind === 'plans' ? await listMarkdown(dir) : await listFolders(dir),
+    record,
+  )
+
+  if (record !== undefined && names.length === 0) {
+    return refuse('no-record', `No ${kind} record named ${record} in ${dir}.`)
+  }
+
+  if (kind === 'plans') return validateFiles(dir, kind, names, checkPlan)
 
-  const folders = await listFolders(dir)
   const check = FOLDER_CHECK[kind]
   const perFolder = await Promise.all(
-    folders.map((slug) => check(join(dir, slug), slug)),
+    names.map(async (slug) => ({
+      findings: await check(join(dir, slug), slug),
+      structure: await folderStructure(join(dir, slug), kind, slug),
+    })),
   )
 
-  return { ok: true, kind, records: folders.length, findings: perFolder.flat() }
+  return {
+    ok: true,
+    kind,
+    records: names.length,
+    findings: perFolder.flatMap((one) => one.findings),
+    structure: perFolder.flatMap((one) => one.structure),
+  }
 }