@erclx/aitk 0.57.0 → 0.59.0

package/src/commands/records.ts

@@ -0,0 +1,159 @@
+import { $ } from 'bun'
+import type { Command } from 'commander'
+import {
+  type Finding,
+  isRecordKind,
+  RECORD_KINDS,
+  type ValidateOutcome,
+  validateRecords,
+} from '@/records/validate'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+/** Returned when a record carries a finding, which is the gating result. */
+const EXIT_FINDINGS = 2
+
+interface ValidateCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
+/**
+ * The session-record folders are shared scratch at the main worktree root, and
+ * `git worktree list` puts that root first. Trusting the working directory would
+ * validate a linked worktree's empty folder and report it clean.
+ */
+async function mainWorktreeRoot(): Promise<string> {
+  const result = await $`git worktree list --porcelain`.quiet().nothrow()
+  if (result.exitCode !== 0) return process.cwd()
+
+  const line = result.stdout
+    .toString()
+    .split('\n')
+    .find((entry) => entry.startsWith('worktree '))
+
+  return line ? line.slice('worktree '.length).trim() : process.cwd()
+}
+
+export function register(program: Command): void {
+  const records = program
+    .command('records')
+    .description('Check the gitignored session records under .claude/')
+    .helpOption('-h, --help', 'Show this help message')
+
+  records
+    .command('validate')
+    .description('Report where a record and the standard governing it disagree')
+    .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Checks:',
+        '  plans       filename, required sections, and the suggested-and-answer contract',
+        '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
+        '  intake      overview file, numbering, dating, and the four bullets every item carries',
+        '',
+        'Exit codes:',
+        '  0  every check passed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one record carries a finding',
+        '',
+        'It reports and never writes. Each folder is per-machine scratch with no',
+        'history behind it, so a session fixes the record the report names.',
+        '',
+        'Examples:',
+        '  aitk records validate plans',
+        '  aitk records validate intake --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (kind: string, opts: ValidateCommandOptions) => {
+      process.exitCode = await runValidate(kind, opts)
+    })
+}
+
+async function runValidate(
+  kind: string,
+  opts: ValidateCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!isRecordKind(kind)) {
+    return report(
+      {
+        ok: false,
+        reason: 'unknown-kind',
+        message: `Not a record kind: ${kind}. Expected one of: ${RECORD_KINDS.join(', ')}.`,
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+
+  return report(await validateRecords(root, kind), emitJson, root)
+}
+
+function report(
+  outcome: ValidateOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    // The framed branch below already reaches stderr through logError, so the
+    // bare write is what keeps the JSON mode from reporting the reason on
+    // stdout alone.
+    if (emitJson) {
+      process.stderr.write(`${outcome.message}\n`)
+      process.stdout.write(
+        `${JSON.stringify({
+          ok: false,
+          reason: outcome.reason,
+          message: outcome.message,
+        })}\n`,
+      )
+      return 1
+    }
+
+    intro('aitk records validate')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        kind: outcome.kind,
+        records: outcome.records,
+        findings: outcome.findings,
+      })}\n`,
+    )
+  } else {
+    intro('aitk records validate')
+    logStep(outcome.kind)
+    logInfo(`${outcome.records} record(s) read`)
+
+    logStep(outcome.findings.length === 0 ? 'Clean' : 'Findings')
+    if (outcome.findings.length === 0) {
+      logInfo('every record matches the shape its standard fixes')
+    } else {
+      for (const found of outcome.findings) logWarn(describe(found))
+    }
+    outro()
+  }
+
+  return outcome.findings.length > 0 ? EXIT_FINDINGS : 0
+}
+
+function describe(found: Finding): string {
+  const scope = found.record === found.subject ? '' : `${found.record}: `
+  return `${scope}${found.subject} ${found.message}`
+}

package/src/gov/install.ts

@@ -31,6 +31,37 @@ export function ruleSubdir(src: string, rulesRoot: string): string {
   return subdir === '.' ? '' : subdir
 }
 
+/**
+ * Lists every rule source path under `governance/rules/`, relative to it and
+ * sorted, so a caller walking the tree and a caller resolving one name read the
+ * same order.
+ */
+export function listRuleSourcePaths(root: string): string[] {
+  const rulesRoot = rulesSourceDir(root)
+  if (!existsSync(rulesRoot)) return []
+
+  return [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: rulesRoot, onlyFiles: true }),
+  ].sort()
+}
+
+/**
+ * Maps each rule name to its source file. First path wins, so a name appearing
+ * in two subdirectories resolves deterministically rather than by whichever
+ * entry the filesystem yielded first.
+ */
+function indexRuleSources(root: string): Map<string, string> {
+  const rulesRoot = rulesSourceDir(root)
+  const byName = new Map<string, string>()
+
+  for (const rel of listRuleSourcePaths(root)) {
+    const name = rel.slice(rel.lastIndexOf('/') + 1, -'.md'.length)
+    if (!byName.has(name)) byName.set(name, join(rulesRoot, rel))
+  }
+
+  return byName
+}
+
 /**
  * Finds each rule's source file by name across the `governance/rules/`
  * subfolders. A rule with no source is reported rather than dropped, matching
@@ -41,21 +72,7 @@ export function lookupRules(
   rules: readonly string[],
 ): RuleLookup {
   const rulesRoot = rulesSourceDir(root)
-  const byName = new Map<string, string>()
-
-  const relPaths = existsSync(rulesRoot)
-    ? [
-        ...new Bun.Glob('**/*.md').scanSync({
-          cwd: rulesRoot,
-          onlyFiles: true,
-        }),
-      ].sort()
-    : []
-
-  for (const rel of relPaths) {
-    const name = rel.slice(rel.lastIndexOf('/') + 1, -'.md'.length)
-    if (!byName.has(name)) byName.set(name, join(rulesRoot, rel))
-  }
+  const byName = indexRuleSources(root)
 
   const found: RuleSource[] = []
   const missing: string[] = []

package/src/gov/list.ts

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
+import {
+  expandStackEntry,
+  listGovStacks,
+  loadGovStack,
+  unreferencedRules,
+} from '@/gov/stacks'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+
+export interface StackEntry {
+  readonly name: string
+  readonly extends: string | null
+  readonly rules: string[]
+}
+
+export interface RuleEntry {
+  readonly name: string
+  readonly domain: string
+  readonly description: string
+  readonly paths: string[] | null
+}
+
+export interface GovCatalog {
+  readonly stacks: StackEntry[]
+  readonly rules: RuleEntry[]
+  readonly unreferenced: string[]
+}
+
+/**
+ * Reports each stack's own entries expanded, so a folder entry reaches a
+ * consumer as the rules it stands for. `setup-gov` dedupes `--add` extras
+ * against this list, and a stack answering `core` there would re-add every
+ * rule that folder already carries.
+ *
+ * The `extends` chain is deliberately not resolved, which is what the bash
+ * did. The list shows what each stack contributes beside the parent it
+ * inherits from, rather than repeating the ancestors under every descendant.
+ */
+export function buildStackEntries(root: string): StackEntry[] {
+  const entries: StackEntry[] = []
+
+  for (const name of listGovStacks(root)) {
+    const stack = loadGovStack(root, name)
+    if (!stack) continue
+
+    const seen = new Set<string>()
+    const rules: string[] = []
+
+    for (const entry of stack.rules) {
+      for (const rule of expandStackEntry(root, entry)) {
+        if (seen.has(rule)) continue
+        seen.add(rule)
+        rules.push(rule)
+      }
+    }
+
+    entries.push({ name, extends: stack.parent ?? null, rules })
+  }
+
+  return entries
+}
+
+/**
+ * Reads the catalog straight off the source tree. A rule's domain is the
+ * subdirectory it sits in, which is the band grouping install preserves.
+ */
+export function buildRuleEntries(root: string): RuleEntry[] {
+  const rulesRoot = rulesSourceDir(root)
+
+  return listRuleSourcePaths(root).map((rel) => {
+    const frontmatter = parseFrontmatter(
+      readFileSync(join(rulesRoot, rel), 'utf8'),
+    )
+    const paths = frontmatter?.fields.paths
+
+    return {
+      name: basename(rel, '.md'),
+      domain: rel.includes('/') ? rel.slice(0, rel.indexOf('/')) : '',
+      description: readField(frontmatter, 'description') ?? '',
+      paths: Array.isArray(paths)
+        ? paths.filter((entry): entry is string => typeof entry === 'string')
+        : null,
+    }
+  })
+}
+
+export function buildGovCatalog(root: string): GovCatalog {
+  return {
+    stacks: buildStackEntries(root),
+    rules: buildRuleEntries(root),
+    unreferenced: unreferencedRules(root),
+  }
+}
+
+export function describeStack(entry: StackEntry): string {
+  const count = `${entry.rules.length} rules`
+  return entry.extends === null
+    ? `${entry.name} (${count})`
+    : `${entry.name} (extends: ${entry.extends}, ${count})`
+}
+
+export function describeRule(entry: RuleEntry): string {
+  return `${entry.name} [${entry.domain}] ${entry.description}`
+}

package/src/gov/stacks.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
 
 export interface GovStack {
   readonly name: string
@@ -64,11 +65,33 @@ export function loadGovStack(
   }
 }
 
+/**
+ * Expands one stack entry. An entry naming a directory under
+ * `governance/rules/` resolves to every rule inside it, sorted, and any other
+ * entry resolves to itself, so a folder and a slug reach the caller as one
+ * shape rather than two the caller has to tell apart.
+ *
+ * The directory wins over a rule file of the same name. They cannot collide
+ * while `standards/rule.md` requires a numeric prefix on a rule slug, since a
+ * band folder carries none.
+ */
+export function expandStackEntry(root: string, entry: string): string[] {
+  const dir = join(rulesSourceDir(root), entry)
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [entry]
+
+  return [...new Bun.Glob('**/*.md').scanSync({ cwd: dir, onlyFiles: true })]
+    .sort()
+    .map((rel) => basename(rel, '.md'))
+}
+
 /**
  * Walks `extends` ancestors first, then the stack's own rules, deduped by
  * first appearance. Tooling's `resolveChain` returns full manifests nearest
  * first and carries `skipStack` truncation, so the two walks stay separate
  * rather than fitting one shape to both.
+ *
+ * Dedupe runs on expanded names rather than on the entries, so a stack naming
+ * a folder and an ancestor naming a rule inside it yield that rule once.
  */
 export function resolveRules(root: string, stack: string): RuleResolution {
   const rules: string[] = []
@@ -87,10 +110,12 @@ export function resolveRules(root: string, stack: string): RuleResolution {
       if (missing !== undefined) return missing
     }
 
-    for (const rule of loaded.rules) {
-      if (seen.has(rule)) continue
-      seen.add(rule)
-      rules.push(rule)
+    for (const entry of loaded.rules) {
+      for (const rule of expandStackEntry(root, entry)) {
+        if (seen.has(rule)) continue
+        seen.add(rule)
+        rules.push(rule)
+      }
     }
 
     return undefined
@@ -102,6 +127,30 @@ export function resolveRules(root: string, stack: string): RuleResolution {
   return { ok: true, rules }
 }
 
+/**
+ * Names every rule no stack reaches, sorted. A rule outside every stack still
+ * installs through `--add`, so this reports an opt-in library and an oversight
+ * alike and leaves telling them apart to the reader.
+ *
+ * A stack whose `extends` does not resolve contributes nothing rather than
+ * aborting the sweep, or one broken stack would report the whole catalog as
+ * unreferenced.
+ */
+export function unreferencedRules(root: string): string[] {
+  const reached = new Set<string>()
+
+  for (const stack of listGovStacks(root)) {
+    const resolution = resolveRules(root, stack)
+    if (!resolution.ok) continue
+    for (const rule of resolution.rules) reached.add(rule)
+  }
+
+  return listRuleSourcePaths(root)
+    .map((rel) => basename(rel, '.md'))
+    .filter((rule) => !reached.has(rule))
+    .sort()
+}
+
 /**
  * Layers `--add` names on top of a resolved stack. The bash trimmed a single
  * leading and trailing space per entry; trimming fully is the same result for