@erclx/canon 5.20.0 → 5.22.0

package/src/commands/tasks.ts

@@ -65,6 +65,7 @@ const EXIT_FINDINGS = 2
 
 /** Matches `trunk.ts`'s bound on a git subprocess this verb also shells out to. */
 const GIT_TIMEOUT_MS = 10_000
+const GH_TIMEOUT_MS = 10_000
 
 const TRUNK_BRANCHES: readonly string[] = ['main', 'master']
 
@@ -522,7 +523,9 @@ export function register(program: Command): void {
         'Run from a branch other than main or master, a close that ticks a new',
         'box names that branch on a Pending branch: line, which holds the task',
         'against a merge-time archive until canon tasks pull-request records',
-        "the branch's own number.",
+        "the branch's own number. The marker is skipped once gh lists a pull",
+        "request for the branch whose number is already on the task's Pull",
+        'request: line, and a failed gh lookup writes it.',
         '',
         'Examples:',
         '  canon tasks outcome v28.1-trigger-escalation --close 1 --close 3',
@@ -728,6 +731,45 @@ async function workingBranch(): Promise<string | undefined> {
   return branch
 }
 
+/**
+ * The pull request numbers whose head is `branch`, open or not. A failed run,
+ * an unreadable answer, or no `gh` at all returns an empty list, which writes
+ * the marker, the direction that holds a task open rather than archiving it.
+ */
+async function branchPullNumbers(
+  branch: string | undefined,
+): Promise<readonly number[]> {
+  if (branch === undefined) return []
+
+  const result = await execa(
+    'gh',
+    ['pr', 'list', '--head', branch, '--state', 'all', '--json', 'number'],
+    {
+      cwd: process.cwd(),
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (result.exitCode !== 0) return []
+
+  try {
+    const rows: unknown = JSON.parse(result.stdout)
+    if (!Array.isArray(rows)) return []
+
+    return rows
+      .map((row: unknown) =>
+        typeof row === 'object' && row !== null && 'number' in row
+          ? row.number
+          : undefined,
+      )
+      .filter((number): number is number => Number.isInteger(number))
+  } catch {
+    return []
+  }
+}
+
 async function runPlanLink(
   task: string,
   plan: string,
@@ -789,11 +831,13 @@ async function runOutcome(
   }
 
   const root = opts.root ?? (await mainWorktreeRoot())
+  const branch = await workingBranch()
   const outcome = await closeOutcomes(
     root,
     selector,
     raw.map(Number),
-    await workingBranch(),
+    branch,
+    await branchPullNumbers(branch),
   )
 
   return reportOutcome(outcome, emitJson, root)

package/src/gov/citations.ts

@@ -266,8 +266,7 @@ export function collectCitations(text: string): RawCitation[] {
  *
  * A rule spelling a whole path there is declaring that exact artifact, and a
  * body line naming it again is naming what the rule governs rather than
- * pointing a reader somewhere. `governance/rules/standards/diagrams.md` tells
- * its reader to convert a `.claude/DIAGRAMS.md` left by an older install, which
+ * pointing a reader somewhere. Such a path names a file a target holds, so it
  * is correctly absent from this tree and correctly named in the rule.
  */
 function governedPaths(text: string): string[] {

package/src/migrate/skill-names.ts

@@ -33,6 +33,13 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
  * its name collided with `docs-sync`, which owns `docs/`. `claude-docs` is
  * retargeted onto `context-fold` for the same reason `claude-ui-test` was.
  *
+ * Five rows merge skills rather than rename one. `draft-docs`,
+ * `draft-context`, `draft-wireframes`, `draft-readme`, and `draft-wiki` ran
+ * one procedure five times over, differing only in the standard each read and
+ * the catalog each checked, so they became `draft-doc`, which picks the kind
+ * from where the document lands. Every retired name lands on the one skill, so
+ * a target citing any of them resolves after a single sweep.
+ *
  * Every name takes two words. Ten of these would have landed as a bare single
  * word under a plain strip, and a bare word such as `review` or `docs` is a
  * substring of ordinary prose with no token left for a later sweep to find.
@@ -79,6 +86,11 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'canon-slides-draft': 'draft-slides',
   'canon-record': 'record-screencast',
   'canon-frames-read': 'read-frames',
+  'draft-docs': 'draft-doc',
+  'draft-context': 'draft-doc',
+  'draft-wireframes': 'draft-doc',
+  'draft-readme': 'draft-doc',
+  'draft-wiki': 'draft-doc',
 }
 
 /**
@@ -110,11 +122,6 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
  * what shipped or what a session ran under whatever name was current then, so
  * rewriting one makes it testify to a release or a run that never happened.
  *
- * The pointer left at `docs-fold` is excluded because it exists to answer under
- * the old name, so a later run would move it onto the skill it points at. The
- * exclusion is only safe once the real body has moved, since excluding the path
- * ahead of the first sweep leaves that body behind.
- *
  * The record archives need no entry here. They are gitignored, so the tracked
  * listing every sweep reads never reaches them.
  */
@@ -127,7 +134,5 @@ export const SKILL_NAME_RULES: RenameRules = defineRenameRules({
     'CHANGELOG.md',
     'src/migrate/skill-names.ts',
     'src/migrate/skill-names.test.ts',
-    'claude/skills/docs-fold/SKILL.md',
-    'claude/skills/docs-fold/REQUIREMENT.md',
   ],
 })

package/src/slides/convert/chart.ts

@@ -0,0 +1,165 @@
+import type PptxGenJS from 'pptxgenjs'
+import { position, type Rect } from '@/slides/convert/shapes'
+
+/**
+ * A `<figure data-chart="...">` holding a `<table>` lands as a native chart.
+ * The table stays the page's accessible source and is not also drawn. Its
+ * header row names the series and its first column names the categories.
+ */
+
+export const CHART_TYPES = ['bar', 'line', 'area', 'pie', 'doughnut'] as const
+export type ChartType = (typeof CHART_TYPES)[number]
+
+export interface ChartRecord {
+  readonly selector: string
+  readonly box: Rect
+  /** The raw `data-chart` value, checked against `CHART_TYPES` here. */
+  readonly type: string
+  readonly hasLabels: boolean
+  /** The figure's `<figcaption>`, when it has one. */
+  readonly title?: string
+  readonly rows: readonly (readonly string[])[]
+}
+
+export interface ChartTheme {
+  /** Series colors in order, repeated past the last. */
+  readonly colors: readonly string[]
+  readonly ink: string
+  readonly muted: string
+  readonly face: string
+}
+
+export interface ChartSeries {
+  readonly name: string
+  readonly labels: readonly string[]
+  /** `null` is an empty cell, which the chart draws as a gap. */
+  readonly values: readonly (number | null)[]
+}
+
+export type ChartPlan =
+  | {
+      readonly status: 'chart'
+      readonly type: ChartType
+      readonly data: readonly ChartSeries[]
+      readonly options: PptxGenJS.IChartOpts
+    }
+  | {
+      readonly status: 'refused'
+      readonly selector: string
+      readonly message: string
+    }
+
+export interface ColorRole {
+  readonly name: string
+  readonly hex: string
+}
+
+/** The grounds a series would vanish into. */
+const GROUND_ROLES = new Set(['--color-background', '--color-surface'])
+
+const NUMBER = /^-?(\d+\.?\d*|\.\d+)$/
+
+/**
+ * A comma counts as a thousands separator only where it groups in threes, so a
+ * comma-decimal `3,5` refuses rather than reading as 35.
+ */
+const GROUPED = /^-?\d{1,3}(,\d{3})+(\.\d+)?$/
+
+const isChartType = (value: string): value is ChartType =>
+  (CHART_TYPES as readonly string[]).includes(value)
+
+/**
+ * The accent, then every other declared color role in token order except the
+ * grounds, each color once. No project declares a chart palette, so the
+ * project's own roles stand in for one.
+ */
+export function seriesColors(
+  accent: string,
+  roles: readonly ColorRole[],
+): string[] {
+  const colors = [accent]
+  for (const role of roles) {
+    if (GROUND_ROLES.has(role.name) || colors.includes(role.hex)) continue
+    colors.push(role.hex)
+  }
+  return colors
+}
+
+function cycle(colors: readonly string[], count: number): string[] {
+  return Array.from(
+    { length: count },
+    (_, index) => colors[index % colors.length] ?? '',
+  )
+}
+
+export function planChart(record: ChartRecord, theme: ChartTheme): ChartPlan {
+  const refuse = (message: string): ChartPlan => ({
+    status: 'refused',
+    selector: record.selector,
+    message,
+  })
+  if (!isChartType(record.type)) {
+    return refuse(
+      `data-chart "${record.type}" is not one of ${CHART_TYPES.join(', ')}`,
+    )
+  }
+  const [header = [], ...body] = record.rows
+  if (header.length < 2 || body.length === 0) {
+    return refuse(
+      'the table needs a header row and at least one data row of two cells',
+    )
+  }
+
+  const labels = body.map((row) => row[0] ?? '')
+  const data: ChartSeries[] = []
+  for (let column = 1; column < header.length; column += 1) {
+    const values: (number | null)[] = []
+    for (const [index, row] of body.entries()) {
+      const text = (row[column] ?? '').trim()
+      if (text === '') {
+        values.push(null)
+        continue
+      }
+      const bare = GROUPED.test(text) ? text.replace(/,/g, '') : text
+      if (!NUMBER.test(bare)) {
+        return refuse(
+          `cell "${text}" at row ${index + 2}, column ${column + 1} is not a number`,
+        )
+      }
+      values.push(Number(bare))
+    }
+    data.push({ name: header[column] ?? '', labels, values })
+  }
+
+  const isRound = record.type === 'pie' || record.type === 'doughnut'
+  return {
+    status: 'chart',
+    type: record.type,
+    data,
+    options: {
+      ...position(record.box),
+      chartColors: cycle(theme.colors, isRound ? labels.length : data.length),
+      displayBlanksAs: 'gap',
+      showValue: record.hasLabels,
+      dataLabelColor: theme.ink,
+      dataLabelFontFace: theme.face,
+      showLegend: isRound || data.length > 1,
+      legendPos: 'b',
+      legendColor: theme.ink,
+      legendFontFace: theme.face,
+      catAxisLabelColor: theme.muted,
+      catAxisLabelFontFace: theme.face,
+      valAxisLabelColor: theme.muted,
+      valAxisLabelFontFace: theme.face,
+      ...(record.title
+        ? {
+            showTitle: true,
+            title: record.title,
+            titleColor: theme.ink,
+            titleFontFace: theme.face,
+            altText: record.title,
+          }
+        : {}),
+    },
+  }
+}

package/src/slides/convert/deck.ts

@@ -0,0 +1,244 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { basename, isAbsolute, join, relative, resolve } from 'node:path'
+
+/**
+ * What belongs to the deck rather than to one slide, read from `deck.json`
+ * beside the slides. A slide overrides a band through attributes on its own
+ * `<body>`, which `walk.ts` reads.
+ */
+
+export const DECK_FILE = 'deck.json'
+
+export const BAND_SLOTS = ['left', 'center', 'right'] as const
+export type BandSlot = (typeof BAND_SLOTS)[number]
+
+export interface Band {
+  readonly show: boolean
+  readonly left?: string
+  readonly center?: string
+  readonly right?: string
+}
+
+export interface DeckConfig {
+  readonly title: string
+  readonly header: Band
+  readonly footer: Band
+  /** Drawn at the right of the footer, so they show only where it does. */
+  readonly slideNumbers: boolean
+  /** Absolute, resolved against the deck folder. */
+  readonly mark?: string
+  /** The faces the package step embeds, in the order the deck lists them. */
+  readonly fonts: readonly DeckFont[]
+}
+
+export interface DeckFont {
+  readonly family: string
+  readonly weight: number
+  readonly style: 'normal' | 'italic'
+  /** Absolute, resolved against the deck folder and kept inside it. */
+  readonly path: string
+  /** The path as `deck.json` wrote it, which a refusal names. */
+  readonly source: string
+}
+
+export type DeckRead =
+  | { readonly status: 'read'; readonly deck: DeckConfig }
+  | {
+      readonly status: 'refused'
+      readonly field: string
+      readonly message: string
+    }
+
+const DECK_FIELDS = new Set([
+  'title',
+  'header',
+  'footer',
+  'slideNumbers',
+  'mark',
+  'fonts',
+])
+const BAND_FIELDS = new Set<string>(['show', ...BAND_SLOTS])
+const FONT_FIELDS = new Set(['family', 'weight', 'style', 'path'])
+
+class FieldError extends Error {
+  constructor(
+    readonly field: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function rejectUnknown(
+  record: Record<string, unknown>,
+  known: ReadonlySet<string>,
+  prefix: string,
+): void {
+  const unknown = Object.keys(record).find((key) => !known.has(key))
+  if (unknown !== undefined) {
+    throw new FieldError(
+      `${prefix}${unknown}`,
+      `unknown field ${prefix}${unknown}`,
+    )
+  }
+}
+
+function stringField(value: unknown, field: string): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string') {
+    throw new FieldError(field, `${field} must be a string`)
+  }
+  return value
+}
+
+function booleanField(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'boolean') {
+    throw new FieldError(field, `${field} must be true or false`)
+  }
+  return value
+}
+
+/**
+ * A declared band merges over its default, so `{ "center": "x" }` keeps the
+ * footer's title on the left. Declaring any text turns a band on unless it
+ * also says `show: false`.
+ */
+function band(value: unknown, field: string, fallback: Band): Band {
+  if (value === undefined) return fallback
+  if (!isRecord(value)) {
+    throw new FieldError(field, `${field} must be an object`)
+  }
+  rejectUnknown(value, BAND_FIELDS, `${field}.`)
+  const slots: { -readonly [slot in BandSlot]?: string } = {}
+  for (const slot of BAND_SLOTS) {
+    const text = stringField(value[slot], `${field}.${slot}`)
+    if (text !== undefined) slots[slot] = text
+  }
+  const show =
+    booleanField(value.show, `${field}.show`) ??
+    (Object.keys(slots).length > 0 || fallback.show)
+  return { ...fallback, ...slots, show }
+}
+
+function parse(raw: unknown, folder: string): DeckConfig {
+  if (!isRecord(raw)) {
+    throw new FieldError(DECK_FILE, `${DECK_FILE} must hold an object`)
+  }
+  rejectUnknown(raw, DECK_FIELDS, '')
+  const title = stringField(raw.title, 'title') ?? basename(folder)
+  const header = band(raw.header, 'header', { show: false })
+  const footer = band(raw.footer, 'footer', { show: true, left: title })
+  const slideNumbers = booleanField(raw.slideNumbers, 'slideNumbers') ?? true
+  if (slideNumbers && footer.right !== undefined) {
+    throw new FieldError(
+      'footer.right',
+      'footer.right is where slide numbers sit. Set slideNumbers to false to use it',
+    )
+  }
+  const markPath = stringField(raw.mark, 'mark')
+  let mark: string | undefined
+  if (markPath !== undefined) {
+    mark = join(folder, markPath)
+    if (!existsSync(mark) || !statSync(mark).isFile()) {
+      throw new FieldError('mark', `mark ${mark} does not exist`)
+    }
+  }
+  const fonts = fontList(raw.fonts, folder)
+  return { title, header, footer, slideNumbers, mark, fonts }
+}
+
+function isWithin(folder: string, path: string): boolean {
+  const inside = relative(folder, path)
+  return inside !== '' && !inside.startsWith('..') && !isAbsolute(inside)
+}
+
+/**
+ * A face is read from the deck folder only, so a `deck.json` cannot point the
+ * export at a file elsewhere on the machine and carry it out inside the deck.
+ */
+function fontList(value: unknown, folder: string): DeckFont[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) {
+    throw new FieldError('fonts', 'fonts must be a list')
+  }
+  return value.map((entry: unknown, index): DeckFont => {
+    const field = `fonts[${index}]`
+    if (!isRecord(entry)) {
+      throw new FieldError(field, `${field} must be an object`)
+    }
+    rejectUnknown(entry, FONT_FIELDS, `${field}.`)
+    const family = stringField(entry.family, `${field}.family`)
+    if (!family) {
+      throw new FieldError(`${field}.family`, `${field}.family is required`)
+    }
+    const weight = entry.weight ?? 400
+    if (
+      typeof weight !== 'number' ||
+      !Number.isInteger(weight) ||
+      weight < 1 ||
+      weight > 1000
+    ) {
+      throw new FieldError(
+        `${field}.weight`,
+        `${field}.weight must be a whole number from 1 to 1000`,
+      )
+    }
+    const style = entry.style ?? 'normal'
+    if (style !== 'normal' && style !== 'italic') {
+      throw new FieldError(
+        `${field}.style`,
+        `${field}.style must be normal or italic`,
+      )
+    }
+    const source = stringField(entry.path, `${field}.path`)
+    if (!source) {
+      throw new FieldError(`${field}.path`, `${field}.path is required`)
+    }
+    const path = resolve(folder, source)
+    const outside = new FieldError(
+      `${field}.path`,
+      `${field}.path ${source} lies outside the deck folder`,
+    )
+    if (!isWithin(folder, path)) throw outside
+    if (!existsSync(path) || !statSync(path).isFile()) {
+      throw new FieldError(
+        `${field}.path`,
+        `${field}.path ${path} does not exist`,
+      )
+    }
+    // A link inside the folder can still lead out of it.
+    if (!isWithin(realpathSync(folder), realpathSync(path))) throw outside
+    return { family, weight, style, path, source }
+  })
+}
+
+export function readDeck(folder: string): DeckRead {
+  const path = join(folder, DECK_FILE)
+  let raw: unknown = {}
+  if (existsSync(path)) {
+    try {
+      raw = JSON.parse(readFileSync(path, 'utf8'))
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      return {
+        status: 'refused',
+        field: DECK_FILE,
+        message: `${path}: not valid JSON (${reason})`,
+      }
+    }
+  }
+  try {
+    return { status: 'read', deck: parse(raw, folder) }
+  } catch (error) {
+    if (!(error instanceof FieldError)) throw error
+    return {
+      status: 'refused',
+      field: error.field,
+      message: `${path}: ${error.message}`,
+    }
+  }
+}