@erclx/canon 5.50.0 → 5.51.0

package/src/gov/detect.ts

@@ -99,25 +99,35 @@ function walkFiles(target: string): string[] {
   return files.sort()
 }
 
+interface Candidates {
+  readonly paths: readonly string[]
+  readonly folders: readonly string[]
+}
+
 /**
  * The paths a file glob is matched against: every file to depth two, plus
  * every folder on the way to any listed file, so an evidence folder such as
- * `.github/workflows` matches without naming the file inside it.
+ * `.github/workflows` matches without naming the file inside it. `folders`
+ * holds the folders alone, which a pattern ending in `/` is matched against.
  */
-async function candidatePaths(target: string): Promise<string[]> {
+async function candidatePaths(target: string): Promise<Candidates> {
   const listed = (await listRepositoryFiles(target)) ?? walkFiles(target)
   const paths = new Set<string>()
+  const folders = new Set<string>()
 
   for (const file of listed) {
     let dir = dirname(file)
     while (dir !== '.') {
-      if (depth(dir) <= MAX_DIRS) paths.add(dir)
+      if (depth(dir) <= MAX_DIRS) {
+        paths.add(dir)
+        folders.add(dir)
+      }
       dir = dirname(dir)
     }
     if (depth(file) <= MAX_DIRS) paths.add(file)
   }
 
-  return [...paths].sort()
+  return { paths: [...paths].sort(), folders: [...folders].sort() }
 }
 
 /** A PEP 508 requirement's distribution name, normalized per PEP 503. */
@@ -231,6 +241,11 @@ function readDependencies(
   return deps
 }
 
+/** A pattern ending in `/` matches folders only, so a file at that depth misses. */
+function isFolderPattern(pattern: string): boolean {
+  return pattern.endsWith('/')
+}
+
 /** A glob carrying no wildcard names one path rather than a pattern. */
 function isLiteral(pattern: string): boolean {
   return !/[*?[\]{}]/.test(pattern)
@@ -245,7 +260,7 @@ function matchEntry(
   entry: DetectEntry,
   target: string,
   deps: ReadonlyMap<string, readonly string[]>,
-  paths: readonly string[],
+  candidates: Candidates,
 ): Evidence[] {
   const evidence: Evidence[] = []
 
@@ -255,9 +270,12 @@ function matchEntry(
   }
 
   for (const pattern of entry.files) {
-    const glob = new Bun.Glob(pattern)
+    const folderOnly = isFolderPattern(pattern)
+    const glob = new Bun.Glob(folderOnly ? pattern.slice(0, -1) : pattern)
     const hit =
-      paths.find((path) => glob.match(path)) ??
+      (folderOnly ? candidates.folders : candidates.paths).find((path) =>
+        glob.match(path),
+      ) ??
       (isLiteral(pattern) && existsSync(join(target, pattern))
         ? pattern
         : undefined)
@@ -287,13 +305,13 @@ export async function detectRules(
   }
 
   const live = indexRuleSources(root)
-  const paths = await candidatePaths(target)
-  const deps = readDependencies(target, paths)
+  const candidates = await candidatePaths(target)
+  const deps = readDependencies(target, candidates.paths)
 
   const proposals = loadDetectEntries(root)
     .filter((entry) => live.has(entry.rule) && !covered.has(entry.rule))
     .flatMap((entry) => {
-      const evidence = matchEntry(entry, target, deps, paths)
+      const evidence = matchEntry(entry, target, deps, candidates)
       return evidence.length === 0 ? [] : [{ rule: entry.rule, evidence }]
     })
 

package/src/hooks/post-merge.ts

@@ -39,6 +39,7 @@ export interface PostMergeInput {
 export const STEP_VERBS = {
   archive: ['tasks', 'archive'],
   push: ['records', 'push'],
+  members: ['worktrees', 'retire-members'],
   reclaim: ['worktrees', 'reclaim'],
   upgrade: ['upgrade'],
   pluginUpdate: ['claude', 'plugin-update'],
@@ -225,6 +226,33 @@ function reclaimLines(fields: Fields): string | undefined {
   return lines.length > 0 ? lines : undefined
 }
 
+/**
+ * Keyed on the fields, like the reclaim, since a run that retires one member
+ * and fails on another exits 1 with a branch already deleted. A body naming no
+ * members is every merge but an integrator's, so it stays quiet.
+ */
+function memberLines(number: number, fields: Fields): string | undefined {
+  let lines = ''
+  const retired = count(fields, 'retired')
+  if (retired > 0) {
+    lines += `\n🌿 Retired ${retired} fan-in member(s) of #${number}.\n\n`
+  }
+
+  const hint = `Run canon worktrees retire-members --pull-request ${number} --dry-run to read why.\n\n`
+  const reason = text(fields, 'reason')
+  const unfinished = count(fields, 'kept') + count(fields, 'failed')
+  if (
+    reason !== undefined &&
+    reason !== 'no-members' &&
+    reason !== 'gh-missing'
+  ) {
+    lines += `\n🌿 Fan-in members of #${number} not retired: ${reason}\n${hint}`
+  } else if (unfinished > 0) {
+    lines += `\n🌿 ${unfinished} fan-in member(s) of #${number} kept or not fully deleted.\n${hint}`
+  }
+  return lines.length > 0 ? lines : undefined
+}
+
 /**
  * Shared by the binary reinstall and the plugin update. `current` is the
  * ordinary outcome on most merges and stays quiet, and `quiet` names the
@@ -271,8 +299,10 @@ async function step(
 }
 
 /**
- * Runs the five post-merge steps in order: archive, records push, reclaim,
- * upgrade, plugin update. The reclaim sits before the upgrade, since the
+ * Runs the six post-merge steps in order: archive, records push, member
+ * retirement, reclaim, upgrade, plugin update. The member retirement sits
+ * before the reclaim, so the reclaim reads a retired member's worktree as
+ * gone rather than racing it. Both sit before the upgrade, since the
  * upgrade reinstalls the binary every later child runs under, and the two
  * network-bound moves sit last so a slow registry delays nothing else.
  *
@@ -309,11 +339,20 @@ export async function runPostMerge(input: PostMergeInput): Promise<void> {
     pushLines,
   )
 
-  // No `--root` here, and that is load-bearing. The verb reads its own working
-  // directory to refuse the worktree it stands in, so a root would turn the
-  // running worktree into an ordinary candidate and let a pull inside a
-  // linked worktree delete the ground under itself.
+  // No `--root` on either worktree step, and that is load-bearing. Each verb
+  // reads its own working directory to refuse the worktree it stands in, so a
+  // root would turn the running worktree into an ordinary candidate and let a
+  // pull inside a linked worktree delete the ground under itself. One switch
+  // covers both, since both remove worktrees.
   if (!isSkipped('CANON_SKIP_RECLAIM')) {
+    for (const number of pullRequestNumbers(input.subjects)) {
+      await step(
+        input,
+        at([...STEP_VERBS.members, '--pull-request', String(number), '--json']),
+        (_, fields) => memberLines(number, fields),
+      )
+    }
+
     await step(input, at([...STEP_VERBS.reclaim, '--json']), (_, fields) =>
       reclaimLines(fields),
     )

package/src/migrate/status.ts

@@ -0,0 +1,128 @@
+import type { RunCommand } from '@/gate/measures'
+
+interface Migration {
+  readonly name: string
+  readonly flags: readonly string[]
+}
+
+/**
+ * Every `canon migrate` subcommand in the order a project runs them, records
+ * first. This is the source for that order, and `docs/target/migrations.md`
+ * cites the verb rather than keeping a second list. A new migration joins by
+ * one line here.
+ */
+export const MIGRATIONS: readonly Migration[] = [
+  { name: 'records', flags: [] },
+  { name: 'record-tree', flags: [] },
+  { name: 'scratch-evidence', flags: [] },
+  { name: 'record-layout', flags: [] },
+  { name: 'rule-layout', flags: [] },
+  { name: 'rename', flags: ['--scope', 'target'] },
+  { name: 'skill-names', flags: [] },
+  { name: 'surface-roots', flags: [] },
+  { name: 'session-defaults', flags: [] },
+]
+
+export type MigrationState = 'pending' | 'clean' | 'refused'
+
+export interface MigrationStatus {
+  readonly name: string
+  readonly verb: string
+  readonly state: MigrationState
+  /** The subcommand's own `--json` record, carried through unread. */
+  readonly record?: unknown
+  readonly reason?: string
+}
+
+export interface StatusReport {
+  readonly migrations: readonly MigrationStatus[]
+  readonly pending: number
+  readonly refused: number
+}
+
+function parseRecord(stdout: string): unknown {
+  try {
+    return JSON.parse(stdout)
+  } catch {
+    return undefined
+  }
+}
+
+const FRAME = /^[\s│├┌└]+/
+
+/**
+ * A refusing subcommand writes its stderr inside the CLI's frame, so the raw
+ * text would carry the glyphs into a record a skill reads as data. The error
+ * lines are the reason, and a stderr without a marker keeps every line.
+ */
+function refusalReason(stderr: string): string {
+  const lines = stderr.split('\n').map((line) => line.replace(FRAME, '').trim())
+  const errors = lines
+    .filter((line) => line.startsWith('✗'))
+    .map((line) => line.replace(/^✗\s*/, ''))
+  const kept = errors.length > 0 ? errors : lines.filter(Boolean)
+  return kept.map((line) => line.replace(/\.+$/, '')).join('. ')
+}
+
+async function readOne(
+  run: RunCommand,
+  migration: Migration,
+): Promise<MigrationStatus> {
+  const verb = `canon migrate ${migration.name}`
+  const result = await run([
+    'migrate',
+    migration.name,
+    ...migration.flags,
+    '--json',
+  ])
+
+  if (result.exitCode === 0) {
+    return { name: migration.name, verb, state: 'clean' }
+  }
+
+  if (result.exitCode === 2) {
+    return {
+      name: migration.name,
+      verb,
+      state: 'pending',
+      record: parseRecord(result.stdout),
+    }
+  }
+
+  const reason =
+    result.spawnError ??
+    (refusalReason(result.stderr) ||
+      `exited ${result.exitCode} with no message`)
+  return {
+    name: migration.name,
+    verb,
+    state: 'refused',
+    record: parseRecord(result.stdout),
+    reason,
+  }
+}
+
+/**
+ * Runs each migration's own dry run and sorts it by the exit contract every
+ * subcommand shares: 0 with nothing to move, 2 with a plan and no `--write`,
+ * anything else a refusal. It never passes `--write`, and it reads no count,
+ * since the records share no field to count from.
+ */
+export async function readMigrationStatus(
+  run: RunCommand,
+): Promise<StatusReport> {
+  const migrations = await Promise.all(
+    MIGRATIONS.map((migration) => readOne(run, migration)),
+  )
+  return {
+    migrations,
+    pending: migrations.filter((m) => m.state === 'pending').length,
+    refused: migrations.filter((m) => m.state === 'refused').length,
+  }
+}
+
+/** A refusal outranks a pending plan, since a refused read measured nothing. */
+export function statusExitCode(report: StatusReport): 0 | 1 | 2 {
+  if (report.refused > 0) return 1
+  return report.pending > 0 ? 2 : 0
+}

package/src/version/changelog.ts

@@ -0,0 +1,156 @@
+import { compareVersions, parseVersion } from '@/version/compare'
+
+export interface ChangelogEntry {
+  readonly version: string
+  /** The entry's heading line through its last line, trimmed. */
+  readonly markdown: string
+}
+
+export type ChangelogRange =
+  | { readonly kind: 'range'; readonly entries: readonly ChangelogEntry[] }
+  | { readonly kind: 'unknown-version'; readonly version: string }
+
+/**
+ * `release-please` writes each release as `## [x.y.z](compare-url) (date)`, so
+ * this is the one form the split reads. A heading in any other form is body
+ * text of the entry above it, and a change to that form in the release tool
+ * leaves the file reading as no entries at all.
+ */
+const HEADING = /^## \[([^\]]+)\]/
+
+/** Entries in file order, which `release-please` keeps newest first. */
+export function parseChangelog(text: string): ChangelogEntry[] {
+  const entries: ChangelogEntry[] = []
+  let current: { version: string; lines: string[] } | undefined
+
+  const close = () => {
+    if (current === undefined) return
+    entries.push({
+      version: current.version,
+      markdown: current.lines.join('\n').trim(),
+    })
+  }
+
+  for (const line of text.split('\n')) {
+    const match = HEADING.exec(line)
+    if (match !== null) {
+      close()
+      current = { version: match[1] ?? '', lines: [line] }
+    } else {
+      current?.lines.push(line)
+    }
+  }
+  close()
+
+  return entries
+}
+
+/**
+ * The releases after `since` up to and including `running`, oldest first so a
+ * reader meets them in the order they shipped.
+ *
+ * A version the file never listed, or one that does not parse, or a `since`
+ * newer than `running`, names no range. Each reads as `unknown-version` rather
+ * than an empty success, since an empty range reads as a target with nothing
+ * to catch up on. `since` equal to `running` is the one empty range, because
+ * that target is current.
+ */
+export function entriesSince(
+  entries: readonly ChangelogEntry[],
+  since: string,
+  running: string,
+): ChangelogRange {
+  const sinceParsed = parseVersion(since)
+  const runningParsed = parseVersion(running)
+  const listed = new Set(entries.map((entry) => entry.version))
+
+  if (sinceParsed === undefined || !listed.has(since)) {
+    return { kind: 'unknown-version', version: since }
+  }
+  if (runningParsed === undefined || !listed.has(running)) {
+    return { kind: 'unknown-version', version: running }
+  }
+  if (compareVersions(sinceParsed, runningParsed) > 0) {
+    return { kind: 'unknown-version', version: since }
+  }
+
+  const inRange = entries.filter((entry) => {
+    const parsed = parseVersion(entry.version)
+    return (
+      parsed !== undefined &&
+      compareVersions(parsed, sinceParsed) > 0 &&
+      compareVersions(parsed, runningParsed) <= 0
+    )
+  })
+
+  return { kind: 'range', entries: inRange.toReversed() }
+}
+
+export interface ChangelogInput {
+  /** The file's text, or undefined when it could not be read. */
+  readonly text: string | undefined
+  readonly running: string
+  /** An explicit start, which wins over the stamp. */
+  readonly since?: string
+  /** The version each stamped domain recorded. */
+  readonly stamped: readonly string[]
+}
+
+export type ChangelogReport =
+  | {
+      readonly kind: 'range'
+      readonly since: string
+      readonly running: string
+      readonly entries: readonly ChangelogEntry[]
+    }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'no-stamp' | 'no-changelog' | 'unknown-version'
+      readonly version?: string
+    }
+
+/**
+ * Every input arrives as a value, so the refusals are decided here rather than
+ * where the file and the stamp are read. A file with no release heading refuses
+ * as `no-changelog`, since the entries it would range over are not there.
+ */
+export function resolveChangelog(input: ChangelogInput): ChangelogReport {
+  const since = input.since ?? oldestVersion(input.stamped)
+  if (since === undefined) return { kind: 'refused', reason: 'no-stamp' }
+
+  const entries = input.text === undefined ? [] : parseChangelog(input.text)
+  if (entries.length === 0) return { kind: 'refused', reason: 'no-changelog' }
+
+  const range = entriesSince(entries, since, input.running)
+  if (range.kind === 'unknown-version') {
+    return {
+      kind: 'refused',
+      reason: 'unknown-version',
+      version: range.version,
+    }
+  }
+
+  return {
+    kind: 'range',
+    since,
+    running: input.running,
+    entries: range.entries,
+  }
+}
+
+/** The oldest version that parses, or undefined when none does. */
+export function oldestVersion(versions: readonly string[]): string | undefined {
+  let oldest:
+    | { raw: string; parsed: NonNullable<ReturnType<typeof parseVersion>> }
+    | undefined
+
+  for (const raw of versions) {
+    const parsed = parseVersion(raw)
+    if (parsed === undefined) continue
+    if (oldest === undefined || compareVersions(parsed, oldest.parsed) < 0) {
+      oldest = { raw, parsed }
+    }
+  }
+
+  return oldest?.raw
+}