@erclx/canon 5.32.0 → 5.33.0

package/src/commands/labels.ts

@@ -1,11 +1,18 @@
 import { resolve } from 'node:path'
+import { $ } from 'bun'
 import type { Command } from 'commander'
+import { execa } from 'execa'
+import { gitEnv } from '@/git/env'
+import { diffLabels } from '@/labels/apply'
 import { type LabelAuditRefusal, auditLabels } from '@/labels/audit'
 import { resolveScanInput } from '@/labels/event'
 import { checkTitleFormat, type TitleFormatIssue } from '@/labels/format'
 import { MAP_REL } from '@/labels/map'
-import { scanPhaseLabels } from '@/labels/phase'
+import { isReleasePullRequest, scanPhaseLabels } from '@/labels/phase'
+import { checkSections } from '@/labels/sections'
 import { scanTitleSpelling } from '@/labels/spelling'
+import { BAN_SETS } from '@/markdown/bans'
+import { bodyLines, scanBans } from '@/markdown/scan'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
 
 interface AuditOptions {
@@ -14,6 +21,14 @@ interface AuditOptions {
   readonly json?: boolean
 }
 
+interface ApplyOptions extends AuditOptions {
+  readonly check?: boolean
+}
+
+type ApplyRefusal = 'bad-number' | 'no-branch' | 'gh-failed' | 'head-mismatch'
+
+const GH_TIMEOUT_MS = 30_000
+
 interface ScanOptions {
   readonly event?: string
   readonly title?: string
@@ -47,6 +62,16 @@ const REFUSALS: Record<LabelAuditRefusal, string> = {
     'git could not list what this branch changed, so the set is unknown.',
 }
 
+const APPLY_REFUSALS: Record<ApplyRefusal, string> = {
+  'bad-number': 'The pull request number must be a positive whole number.',
+  'no-branch':
+    'This checkout is on no branch, so there is no head to bind the pull request to.',
+  'gh-failed':
+    'gh could not read the pull request or the labels, so nothing was written.',
+  'head-mismatch':
+    'That pull request is not open on the current branch. Nothing was written to it.',
+}
+
 export function register(program: Command): void {
   const labels = program
     .command('labels')
@@ -99,6 +124,48 @@ export function register(program: Command): void {
       process.exitCode = await runAudit(paths, opts)
     })
 
+  labels
+    .command('apply')
+    .description(
+      'Add the labels this branch earns to its open pull request, adding what is missing and never removing',
+    )
+    .argument('<number>', "This branch's open pull request")
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--check', 'Report the labels owed and write nothing')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Resolves the earned set the way `canon labels audit` does, binds to the',
+        'pull request only when its head is the current branch and it is open,',
+        'and adds each earned label the pull request lacks over REST.',
+        '',
+        'It adds and never removes, so a label a person applied by hand stays.',
+        'A label the remote does not carry is reported under missingOnRemote and',
+        'skipped, never created. A project declaring no map earns nothing and',
+        'exits 0.',
+        '',
+        'Record: number, earned, present, added, owed, missingOnRemote, uncovered',
+        '',
+        'Exit codes:',
+        '  0  nothing is owed after the run',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  labels are still owed, being any under --check, or a label the',
+        '     remote lacks or a failed add otherwise',
+        '',
+        'Examples:',
+        '  canon labels apply 123 --json',
+        '  canon labels apply 123 --check',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string, opts: ApplyOptions) => {
+      process.exitCode = await runApply(number, opts)
+    })
+
   labels
     .command('scan')
     .description(
@@ -152,19 +219,27 @@ export function register(program: Command): void {
         'a target project carries none, rather than reaching the network or',
         'forcing a new dependency.',
         '',
-        "It also grades the title alone against standards/pr.md's ## Title",
+        "It also grades the title alone against claude/skills/git-pr/references/pr.md's ## Title",
         'section: the `<type>(<scope>)[!]: <subject>` structure, lowercase casing',
         'for the type, the scope, and the first subject word, and a 72-',
         'character length cap. A scan given no title, whether from a review',
         'or from a bare --body or --body-file invocation, skips this check',
         'rather than grading an empty string.',
         '',
+        'It grades the body of an ordinary pull request against the closed',
+        'section list: a level-two heading outside it, or a missing',
+        '## Summary or ## Key changes, fails. A review, a release-please body,',
+        'and a scan carrying no title skip this check. It also fails a banned',
+        'character, an em dash or a semicolon, in the title or body of a pull',
+        'request or a review, outside a code span or a link.',
+        '',
         'Exit codes:',
-        '  0  none of the five found',
+        '  0  none of the seven found',
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  the title or body carries a phase label, a board identifier, a',
-        '     session link, a title word no dictionary holds, or a title',
-        "     breaking standards/pr.md's format, casing, or length",
+        '     session link, a banned character, a heading outside the closed',
+        '     list or a required one missing, a title word no dictionary holds, or a title',
+        "     breaking claude/skills/git-pr/references/pr.md's format, casing, or length",
         '',
         'Examples:',
         '  canon labels scan --event "$GITHUB_EVENT_PATH"',
@@ -265,6 +340,177 @@ async function runAudit(paths: string[], opts: AuditOptions): Promise<number> {
   return coverage.uncovered.length === 0 ? 0 : 2
 }
 
+/** Runs one `gh` call under the stripped environment, null when it failed. */
+async function gh(
+  cwd: string,
+  args: readonly string[],
+): Promise<string | null> {
+  try {
+    const result = await execa('gh', [...args], {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    return result.stdout
+  } catch {
+    return null
+  }
+}
+
+function nonEmptyLines(text: string): string[] {
+  return text.split('\n').filter((line) => line !== '')
+}
+
+async function runApply(number: string, opts: ApplyOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const isCheck = opts.check ?? false
+
+  intro('canon labels apply')
+
+  const refuse = (reason: ApplyRefusal | LabelAuditRefusal): number => {
+    const message =
+      reason in APPLY_REFUSALS
+        ? APPLY_REFUSALS[reason as ApplyRefusal]
+        : REFUSALS[reason as LabelAuditRefusal]
+    logStep('Refused')
+    logWarn(message)
+    outro()
+    if (emitJson) {
+      process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+    }
+    return 1
+  }
+
+  if (!/^[1-9][0-9]*$/.test(number)) return refuse('bad-number')
+
+  const branch = await $`git -C ${root} symbolic-ref --short -q HEAD`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  const head = branch.exitCode === 0 ? branch.text().trim() : ''
+  if (head === '') return refuse('no-branch')
+
+  // Binding runs ahead of the audit, every label read, and every write, under
+  // --check and a project with no map as well, so a number this branch does
+  // not own costs the run and nothing else.
+  const target = await gh(root, [
+    'api',
+    `repos/{owner}/{repo}/pulls/${number}`,
+    '--jq',
+    '"\\(.head.ref) \\(.state)"',
+  ])
+  if (target === null) return refuse('gh-failed')
+  if (target.trim() !== `${head} open`) return refuse('head-mismatch')
+
+  const report = await auditLabels(root, { base: opts.base })
+
+  // A project declaring no map earns nothing and is labelled silently, which
+  // is an answer and exits clean rather than reading as a break.
+  if (report.kind === 'refused' && report.reason === 'no-map') {
+    logStep('Labels')
+    logInfo(REFUSALS['no-map'])
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          number: Number(number),
+          reason: 'no-map',
+          earned: [],
+          present: [],
+          added: [],
+          owed: [],
+          missingOnRemote: [],
+          uncovered: [],
+        })}\n`,
+      )
+    }
+    return 0
+  }
+  if (report.kind === 'refused') return refuse(report.reason)
+
+  const presentRaw = await gh(root, [
+    'api',
+    '--paginate',
+    `repos/{owner}/{repo}/issues/${number}/labels`,
+    '--jq',
+    '.[].name',
+  ])
+  const remoteRaw = await gh(root, [
+    'api',
+    '--paginate',
+    'repos/{owner}/{repo}/labels',
+    '--jq',
+    '.[].name',
+  ])
+  if (presentRaw === null || remoteRaw === null) return refuse('gh-failed')
+
+  const earned = report.coverage.labels
+  const present = nonEmptyLines(presentRaw)
+  const diff = diffLabels(earned, present, nonEmptyLines(remoteRaw))
+
+  let added: string[] = []
+  let failed: string[] = []
+
+  if (!isCheck && diff.toAdd.length > 0) {
+    const wrote = await gh(root, [
+      'api',
+      '-X',
+      'POST',
+      `repos/{owner}/{repo}/issues/${number}/labels`,
+      ...diff.toAdd.flatMap((label) => ['-f', `labels[]=${label}`]),
+      '--silent',
+    ])
+    if (wrote === null) failed = [...diff.toAdd]
+    else added = [...diff.toAdd]
+  }
+
+  logStep('Labels')
+  logInfo(earned.length === 0 ? 'this set earns no label' : earned.join(', '))
+
+  if (isCheck) {
+    logStep(diff.owed.length === 0 ? 'Nothing owed' : 'Owed')
+    for (const label of diff.owed) logWarn(label)
+  } else {
+    logStep('Added')
+    logInfo(added.length === 0 ? 'no label was added' : added.join(', '))
+  }
+
+  for (const label of diff.missingOnRemote) {
+    logWarn(
+      `${label} is not on the remote. Create it with: gh label create ${label}`,
+    )
+  }
+  for (const label of failed) logWarn(`Label apply failed: ${label}`)
+
+  if (report.coverage.uncovered.length > 0) {
+    logWarn(
+      `${plural(report.coverage.uncovered.length, 'path')} reached by no row of ${MAP_REL}.`,
+    )
+  }
+
+  outro()
+
+  const owed = diff.owed.filter((label) => !added.includes(label))
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        number: Number(number),
+        earned,
+        present,
+        added,
+        owed,
+        missingOnRemote: diff.missingOnRemote,
+        uncovered: report.coverage.uncovered,
+      })}\n`,
+    )
+  }
+
+  return owed.length === 0 ? 0 : 2
+}
+
 async function runScan(opts: ScanOptions): Promise<number> {
   const emitJson = opts.json ?? false
 
@@ -363,6 +609,74 @@ async function runScan(opts: ScanOptions): Promise<number> {
 
   const titleFormatIssues = titleFormat?.issues ?? []
 
+  // A review carries its own headings, a release-please body opens on a
+  // version link, and a scan with no title is a reply or a review body rather
+  // than a pull request description, so none of the three has the closed list
+  // to grade against.
+  const sectionsChecked =
+    resolved.source === 'pull-request' &&
+    resolved.title !== '' &&
+    !isReleasePullRequest(resolved)
+  const sections = sectionsChecked
+    ? checkSections(resolved.body)
+    : { outside: [], missing: [] }
+
+  logStep(
+    !sectionsChecked
+      ? 'Sections not checked'
+      : sections.outside.length === 0 && sections.missing.length === 0
+        ? 'Clean'
+        : 'Section issue found',
+  )
+  if (!sectionsChecked) {
+    logInfo(
+      'only an ordinary pull request body is graded against the closed section list',
+    )
+  } else if (sections.outside.length === 0 && sections.missing.length === 0) {
+    logInfo(
+      'every heading is in the closed list and the required pair is there',
+    )
+  } else {
+    if (sections.outside.length > 0) {
+      logWarn(
+        `${plural(sections.outside.length, 'heading')} outside the closed list in the pull request standard. Rename or drop each.`,
+      )
+      for (const heading of sections.outside) logWarn(heading)
+    }
+    if (sections.missing.length > 0) {
+      logWarn(
+        `${plural(sections.missing.length, 'required heading')} missing from the body.`,
+      )
+      for (const heading of sections.missing) logWarn(heading)
+    }
+  }
+
+  const banFindings = [
+    ...scanBans(
+      [{ number: 1, text: resolved.title, fenced: false }],
+      BAN_SETS,
+    ).map((finding) => ({ ...finding, where: 'title' })),
+    ...scanBans(bodyLines(resolved.body), BAN_SETS).map((finding) => ({
+      ...finding,
+      where: 'body',
+    })),
+  ]
+  const bannedCharacters = [
+    ...new Set(banFindings.map((finding) => finding.term)),
+  ]
+
+  logStep(banFindings.length === 0 ? 'Clean' : 'Banned character found')
+  if (banFindings.length === 0) {
+    logInfo('no banned character outside a code span or a link')
+  } else {
+    logWarn(
+      `${plural(banFindings.length, 'banned character')} in the title or body. Rewrite the sentence rather than swapping the character.`,
+    )
+    for (const finding of banFindings) {
+      logWarn(`${finding.where} line ${finding.line}: ${finding.term}`)
+    }
+  }
+
   logStep(
     titleFormat === undefined
       ? 'Title format not checked'
@@ -378,7 +692,7 @@ async function runScan(opts: ScanOptions): Promise<number> {
     )
   } else {
     logWarn(
-      `${plural(titleFormatIssues.length, 'title format issue')} against standards/pr.md's ## Title section.`,
+      `${plural(titleFormatIssues.length, 'title format issue')} against claude/skills/git-pr/references/pr.md's ## Title section.`,
     )
     for (const issue of titleFormatIssues) logWarn(TITLE_FORMAT_MESSAGES[issue])
   }
@@ -396,6 +710,8 @@ async function runScan(opts: ScanOptions): Promise<number> {
         unspelledWords,
         spellingChecked,
         titleFormatIssues,
+        sections: { checked: sectionsChecked, ...sections },
+        bannedCharacters,
       })}\n`,
     )
   }
@@ -404,7 +720,10 @@ async function runScan(opts: ScanOptions): Promise<number> {
     result.boardReferences.length === 0 &&
     result.sessionLinks.length === 0 &&
     unspelledWords.length === 0 &&
-    titleFormatIssues.length === 0
+    titleFormatIssues.length === 0 &&
+    sections.outside.length === 0 &&
+    sections.missing.length === 0 &&
+    banFindings.length === 0
     ? 0
     : 2
 }

package/src/commands/migrate.ts

@@ -25,7 +25,11 @@ import {
   type RuleLayoutPlan,
   walkFlatRules,
 } from '@/migrate/rule-layout'
-import { SKILL_NAME_MAP, SKILL_NAME_RULES } from '@/migrate/skill-names'
+import {
+  SKILL_CITATION_MAP,
+  SKILL_NAME_MAP,
+  SKILL_NAME_RULES,
+} from '@/migrate/skill-names'
 import {
   planSurfaceRootsMove,
   type SurfaceRootsPlan,
@@ -1250,6 +1254,7 @@ export function register(program: Command): void {
       [
         '',
         `Rewrites ${Object.keys(SKILL_NAME_MAP).length} skill names and moves the folders that carry them.`,
+        `It also carries ${Object.keys(SKILL_CITATION_MAP).length} namespaced-only rows for a skill renamed from a single word.`,
         'It takes no scope. The skill folders it moves are authored in the',
         'toolkit and no target holds a copy of that catalog, so in a target it',
         'rewrites citations of a renamed skill and moves nothing.',

package/src/commands/pr.ts

@@ -389,7 +389,7 @@ export function register(program: Command): void {
         '  unresolved a path written partially, or one past its first comma,',
         '             which can credit a changed file and never accuse one',
         '',
-        `Only ## ${KEY_CHANGES} is read. ## Technical Context legitimately names`,
+        `Only ## ${KEY_CHANGES} is read. ## Technical context legitimately names`,
         'files a branch never touched, so widening the read manufactures findings.',
         '',
         'One class survives the reader: a bullet citing where something is defined',