@erclx/canon 5.50.0 → 5.52.0

package/src/migrate/status.ts

@@ -0,0 +1,132 @@
+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> {
+  // The flags ride in the verb, since a caller appending --write to a bare
+  // name would apply a different plan than the one this dry run read.
+  const verb = ['canon', 'migrate', migration.name, ...migration.flags].join(
+    ' ',
+  )
+  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
+}