@erclx/aitk 0.20.0 → 0.22.0

package/src/commands/context.ts

@@ -0,0 +1,321 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import {
+  type EntryReport,
+  LENGTH_CHECKPOINT,
+  measureFolders,
+  RUN_CHECKPOINT,
+} from '@/context/audit'
+import { auditCitations, type CitationReport } from '@/context/citations'
+import {
+  type AuditedFolder,
+  DEFAULT_FOLDERS,
+  presentNames,
+  resolveFolders,
+} from '@/context/folders'
+import { auditIndexes, type FolderDrift } from '@/context/index-drift'
+import {
+  frameError,
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+} from '@/ui'
+
+/** Returned when an unresolved citation is found, which is the gating check. */
+const EXIT_UNRESOLVED = 2
+
+/** A name of dots alone is `.` or `..`, both of which escape the audit root. */
+const FOLDER_NAME = /^(?!\.+$)[A-Za-z0-9._-]+$/
+
+interface AuditCommandOptions {
+  readonly json?: boolean
+  readonly folder?: string
+  readonly citationsOnly?: boolean
+}
+
+export function register(program: Command): void {
+  const context = program
+    .command('context')
+    .description('Report the structural state of the context folders')
+    .helpOption('-h, --help', 'Show this help message')
+
+  context
+    .command('audit')
+    .description('Report entry length, depth, citations, and index drift')
+    .argument('[path]', 'Project root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--folder <list>', `Comma-separated folder names under .claude/`)
+    .option('--citations-only', 'Run the gating citation check alone')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the audit completed with every cited path resolving',
+        '  1  refused, with the reason on stderr',
+        '  2  a cited path did not resolve',
+        '',
+        'Only unresolved citations set a failing exit code. Length, depth,',
+        'table, and index findings are advisory.',
+        '',
+        'Examples:',
+        '  aitk context audit',
+        '  aitk context audit --json',
+        '  aitk context audit --citations-only',
+        '  aitk context audit --folder context,diagrams',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: AuditCommandOptions) => {
+      process.exitCode = await runAudit(path, opts)
+    })
+}
+
+function parseFolders(list: string | undefined): string[] | string {
+  if (!list) return [...DEFAULT_FOLDERS]
+
+  const names = list
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean)
+
+  if (names.length === 0) return 'Empty --folder list. Pass at least one name.'
+
+  // `..` would resolve the audit root above `.claude/`, where `presentNames`
+  // has no folder name to slice out and hands the citation pattern undefined.
+  const invalid = names.filter((name) => !FOLDER_NAME.test(name))
+  if (invalid.length > 0) {
+    return `--folder takes folder names under .claude/, not paths: ${invalid.join(', ')}`
+  }
+
+  return names
+}
+
+async function runAudit(
+  path: string | undefined,
+  opts: AuditCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const names = parseFolders(opts.folder)
+  const gateOnly = opts.citationsOnly ?? false
+
+  if (typeof names === 'string') return refuse(names, gateOnly)
+
+  const folders = await resolveFolders(root, names)
+  if (folders.length === 0) {
+    return refuse(
+      `No audited folder found under .claude/. Looked for: ${names.join(', ')}.`,
+      gateOnly,
+    )
+  }
+
+  const citations = await auditCitations(root, presentNames(folders))
+  if (citations.kind === 'unavailable') {
+    return refuse(
+      'git could not list the tree, so no citation was checked. Run inside a git repository.',
+      gateOnly,
+    )
+  }
+
+  const entries = gateOnly ? [] : await measureFolders(root, folders)
+  const drift = gateOnly ? [] : await auditIndexes(folders)
+
+  if (gateOnly) {
+    reportGate(citations)
+  } else {
+    intro('aitk context audit')
+    reportScope(folders)
+    reportCitations(citations)
+    reportLength(entries)
+    reportDepth(entries)
+    reportTables(entries)
+    reportDrift(drift)
+    outro()
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        folders: folders.map((folder) => ({
+          path: folder.rel,
+          entries: folder.entries.length,
+        })),
+        citations: {
+          scanned: citations.scanned,
+          total: citations.total,
+          unresolved: citations.unresolved,
+        },
+        entries,
+        indexDrift: drift,
+        checkpoints: {
+          lines: LENGTH_CHECKPOINT,
+          run: RUN_CHECKPOINT,
+          runCountsBlankLines: true,
+        },
+      })}\n`,
+    )
+  }
+
+  return citations.unresolved.length > 0 ? EXIT_UNRESOLVED : 0
+}
+
+function refuse(message: string, gateOnly: boolean): number {
+  if (gateOnly) {
+    frameError(message)
+    return 1
+  }
+
+  intro('aitk context audit')
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  return 1
+}
+
+/**
+ * Prints nothing when every path resolves.
+ *
+ * `--citations-only` is what `verify.sh` runs on every push, and that script
+ * pipes a stage's whole output into its own frame. A passing gate that printed
+ * its frame would nest one inside the other on every contributor's push.
+ */
+function reportGate(report: ScannedCitations): void {
+  const count = report.unresolved.length
+  if (count === 0) return
+
+  intro('aitk context audit')
+  logError(
+    count === 1
+      ? '1 cited path does not resolve'
+      : `${count} cited paths do not resolve`,
+  )
+  pipeOutput(
+    report.unresolved
+      .map((citation) => `${citation.file}:${citation.line}  ${citation.path}`)
+      .join('\n'),
+  )
+  outro()
+}
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`
+}
+
+function reportScope(folders: readonly AuditedFolder[]): void {
+  logStep('Scope')
+
+  for (const folder of folders) {
+    logInfo(`${folder.rel}: ${folder.entries.length} entries`)
+  }
+}
+
+type ScannedCitations = Extract<CitationReport, { kind: 'scanned' }>
+
+function reportCitations(report: ScannedCitations): void {
+  logStep('Citations')
+  logInfo(
+    `${plural(report.total, 'cited path')} across ${plural(report.scanned, 'file')}, fixtures and fenced examples excluded`,
+  )
+
+  if (report.unresolved.length === 0) {
+    logInfo('Every cited path resolves.')
+    return
+  }
+
+  logWarn(`${report.unresolved.length} unresolved`)
+  pipeOutput(
+    report.unresolved
+      .map((citation) => `${citation.file}:${citation.line}  ${citation.path}`)
+      .join('\n'),
+  )
+}
+
+function reportLength(entries: readonly EntryReport[]): void {
+  logStep('Length')
+
+  const over = entries
+    .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
+    .sort((a, b) => b.lines - a.lines)
+
+  if (over.length === 0) {
+    logInfo(`No entry past the ${LENGTH_CHECKPOINT}-line checkpoint.`)
+    return
+  }
+
+  logWarn(`${over.length} past the ${LENGTH_CHECKPOINT}-line checkpoint`)
+  pipeOutput(
+    over.map((entry) => `${entry.rel}  ${entry.lines} lines`).join('\n'),
+  )
+}
+
+/**
+ * Names the blank-line convention on every run.
+ *
+ * The standard settles heading level and fenced blocks and stops there, so a
+ * hand reader who drops blank lines lands a line or two below this number.
+ * Stating it is what keeps the two measurements reconcilable.
+ */
+function reportDepth(entries: readonly EntryReport[]): void {
+  logStep('Depth')
+  logInfo('Runs count blank lines. Fenced blocks and peer lists are excluded.')
+
+  const over = entries
+    .filter((entry) => entry.longestRun > RUN_CHECKPOINT)
+    .sort((a, b) => b.longestRun - a.longestRun)
+
+  if (over.length === 0) {
+    logInfo(`No run past the ${RUN_CHECKPOINT}-line checkpoint.`)
+    return
+  }
+
+  logWarn(`${over.length} past the ${RUN_CHECKPOINT}-line checkpoint`)
+  pipeOutput(
+    over
+      .map(
+        (entry) =>
+          `${entry.rel}:${entry.longestRunLine}  ${entry.longestRun} lines unbroken`,
+      )
+      .join('\n'),
+  )
+}
+
+function reportTables(entries: readonly EntryReport[]): void {
+  logStep('Tables')
+
+  const candidates = entries.flatMap((entry) =>
+    entry.catalogTables.map(
+      (table) => `${entry.rel}:${table.line}  ${table.rows} rows`,
+    ),
+  )
+
+  if (candidates.length === 0) {
+    logInfo('No table reads as a catalog that grows a row per shipped thing.')
+    return
+  }
+
+  logWarn(`${plural(candidates.length, 'candidate')} for a bullet list`)
+  pipeOutput(candidates.join('\n'))
+}
+
+function reportDrift(drift: readonly FolderDrift[]): void {
+  logStep('Index drift')
+
+  const lines = drift.flatMap((folder) => [
+    ...folder.unlisted.map((name) => `${folder.rel}  unlisted: ${name}`),
+    ...folder.missing.map((name) => `${folder.rel}  missing: ${name}`),
+  ])
+
+  if (lines.length === 0) {
+    logInfo('Every index agrees with its siblings.')
+    return
+  }
+
+  logWarn(plural(lines.length, 'disagreement'))
+  pipeOutput(lines.join('\n'))
+}

package/src/context/audit.ts

@@ -0,0 +1,227 @@
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+import type { AuditedFolder } from '@/context/folders'
+
+/** Checkpoints quoted from `standards/context.md`. Neither is a cap. */
+export const LENGTH_CHECKPOINT = 150
+export const RUN_CHECKPOINT = 40
+
+/**
+ * A table this size or larger whose first column mostly names artifacts reads
+ * as a catalog that grows a row per shipped thing, which is the shape the
+ * standard routes to a bullet list. Below it, a table is small enough that a
+ * reflow rewrites little.
+ */
+export const CATALOG_ROW_CHECKPOINT = 6
+
+/** Share of first cells that must name an artifact for a table to qualify. */
+const CATALOG_NAMED_RATIO = 0.6
+
+const FRONTMATTER = /^---\n[\s\S]*?\n---\n?/
+const FENCE = /^\s*(```|~~~)/
+const HEADING = /^#{1,6}\s/
+const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
+const TABLE_ROW = /^\s*\|/
+const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
+const NAMED_CELL = /`[^`]+`|\[[^\]]+\]\([^)]+\)/
+
+export interface TableFinding {
+  readonly line: number
+  readonly rows: number
+}
+
+export interface EntryReport {
+  readonly rel: string
+  readonly lines: number
+  readonly longestRun: number
+  /** First line of the longest run, or 0 when the entry has no run at all. */
+  readonly longestRunLine: number
+  readonly catalogTables: readonly TableFinding[]
+}
+
+interface BodyLine {
+  readonly number: number
+  readonly text: string
+}
+
+/**
+ * Drops the frontmatter while keeping every surviving line's original number,
+ * so a finding points at the line an editor opens rather than at an offset into
+ * the body.
+ */
+function bodyLines(source: string): BodyLine[] {
+  const match = source.match(FRONTMATTER)
+  const offset = match ? match[0].split('\n').length - 1 : 0
+
+  return source
+    .slice(match ? match[0].length : 0)
+    .replace(/\n$/, '')
+    .split('\n')
+    .map((text, index) => ({ number: offset + index + 1, text }))
+}
+
+/**
+ * Reports whether a run is the peer list the standard exempts.
+ *
+ * Every non-blank line has to be a list item at one indent. Prose mixed into
+ * the run or a nested level inside it ends the exemption, because either one
+ * means the block is no longer a flat set a reader can skim.
+ */
+function isPeerList(run: readonly BodyLine[]): boolean {
+  const indents = new Set<number>()
+
+  for (const line of run) {
+    if (line.text.trim() === '') continue
+
+    const match = line.text.match(LIST_ITEM)
+    if (!match) return false
+    indents.add(match[1].length)
+  }
+
+  return indents.size === 1
+}
+
+/**
+ * Measures the longest run of lines no heading breaks.
+ *
+ * Fenced blocks are skipped rather than treated as breaks, per the standard:
+ * they leave the count without ending the run, so prose either side of an
+ * example still measures as the one stretch a reader scrolls through. Blank
+ * lines do count, since the checkpoint is about how far a reader travels
+ * between signposts and a blank line is distance like any other. A hand reader
+ * measuring without them lands one or two lines lower, which the report legend
+ * states.
+ */
+function longestRun(lines: readonly BodyLine[]): {
+  length: number
+  line: number
+} {
+  let longest = 0
+  let longestLine = 0
+  let run: BodyLine[] = []
+  let fenced = false
+
+  const close = (): void => {
+    // The reported line is the run's first non-blank one, since that is what an
+    // editor should open. A run of nothing but blank lines is the gap between
+    // two headings rather than a stretch a reader travels, so it never counts.
+    const first = run.find((line) => line.text.trim() !== '')
+
+    if (first && run.length > longest && !isPeerList(run)) {
+      longest = run.length
+      longestLine = first.number
+    }
+    run = []
+  }
+
+  for (const line of lines) {
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    if (HEADING.test(line.text)) {
+      close()
+      continue
+    }
+
+    run.push(line)
+  }
+
+  close()
+
+  return { length: longest, line: longestLine }
+}
+
+function firstCell(row: string): string {
+  return row.split('|').slice(1)[0] ?? ''
+}
+
+/**
+ * Finds the tables whose rows name shipped artifacts.
+ *
+ * A bare table count reports mostly fixed comparison tables, where a reflow
+ * costs nothing because no row is ever added. The reflow problem belongs to a
+ * catalog that gains a row per artifact, and a first column carrying a path,
+ * command, or link is what separates the two without reading the prose.
+ */
+function catalogTables(lines: readonly BodyLine[]): TableFinding[] {
+  const findings: TableFinding[] = []
+  let fenced = false
+  let index = 0
+
+  while (index < lines.length) {
+    const line = lines[index]
+
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      index++
+      continue
+    }
+    if (fenced || !TABLE_ROW.test(line.text)) {
+      index++
+      continue
+    }
+
+    const separator = lines[index + 1]
+    if (!separator || !TABLE_SEPARATOR.test(separator.text)) {
+      index++
+      continue
+    }
+
+    const body: BodyLine[] = []
+    let cursor = index + 2
+    while (cursor < lines.length && TABLE_ROW.test(lines[cursor].text)) {
+      body.push(lines[cursor])
+      cursor++
+    }
+
+    const named = body.filter((row) => NAMED_CELL.test(firstCell(row.text)))
+    if (
+      body.length >= CATALOG_ROW_CHECKPOINT &&
+      named.length / body.length >= CATALOG_NAMED_RATIO
+    ) {
+      findings.push({ line: line.number, rows: body.length })
+    }
+
+    index = cursor
+  }
+
+  return findings
+}
+
+export function measureEntry(rel: string, source: string): EntryReport {
+  const lines = bodyLines(source)
+  const run = longestRun(lines)
+
+  return {
+    rel,
+    lines: source.replace(/\n$/, '').split('\n').length,
+    longestRun: run.length,
+    longestRunLine: run.line,
+    catalogTables: catalogTables(lines),
+  }
+}
+
+/**
+ * Measures every entry in the audited folders. A generated `index.md` is not
+ * among them, since its body is rewritten on every regen and no checkpoint
+ * describes a catalog.
+ */
+export async function measureFolders(
+  root: string,
+  folders: readonly AuditedFolder[],
+): Promise<EntryReport[]> {
+  const reports: EntryReport[] = []
+
+  for (const folder of folders) {
+    for (const path of folder.entries) {
+      reports.push(
+        measureEntry(relative(root, path), await readFile(path, 'utf8')),
+      )
+    }
+  }
+
+  return reports
+}

package/src/context/citations.ts

@@ -0,0 +1,167 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
+
+/**
+ * Suppresses citation checking for the source line carrying it.
+ *
+ * Prose that teaches a naming pattern displays a path rather than pointing at
+ * one, and no syntax separates the two: an illustration and a reference are
+ * both inline code in a sentence. Location covers the fixture trees and fenced
+ * examples, and this covers what is left, which is a sentence naming a
+ * hypothetical entry to show the shape of the name.
+ */
+export const IGNORE_MARKER = 'audit-ignore-citations'
+
+/**
+ * Trees holding content authored to be parsed rather than followed.
+ *
+ * Sandbox scenarios describe paths inside their own scratch fixtures and the
+ * eval harness names paths in its target project. Neither is a reference into
+ * this repository, so an unresolved path there is correct rather than stale.
+ */
+const FIXTURE_TREES: readonly string[] = ['scripts/sandbox/', 'scripts/eval/']
+
+const FIXTURE_SEGMENTS: readonly string[] = ['fixtures', '__fixtures__']
+
+const FENCE = /^\s*(```|~~~)/
+
+export interface Citation {
+  readonly file: string
+  readonly line: number
+  readonly path: string
+}
+
+export function isFixture(rel: string): boolean {
+  if (rel.endsWith('.test.ts')) return true
+  if (FIXTURE_TREES.some((tree) => rel.startsWith(tree))) return true
+  return rel.split('/').some((segment) => FIXTURE_SEGMENTS.includes(segment))
+}
+
+export function citationPattern(folders: readonly string[]): RegExp {
+  const names = folders.map((name) =>
+    name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+  )
+  return new RegExp(
+    `\\.claude/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
+    'g',
+  )
+}
+
+/**
+ * Pulls the cited paths out of one file's text.
+ *
+ * Fenced blocks are skipped for markdown only. A fence is markdown syntax, and
+ * applying it to a shell or TypeScript source would let a heredoc of triple
+ * backticks silently hide the rest of the file.
+ */
+export function collectCitations(
+  rel: string,
+  text: string,
+  pattern: RegExp,
+): Citation[] {
+  const isMarkdown = rel.endsWith('.md')
+  const found: Citation[] = []
+  let fenced = false
+
+  for (const [index, line] of text.split('\n').entries()) {
+    if (isMarkdown && FENCE.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced || line.includes(IGNORE_MARKER)) continue
+
+    for (const match of line.matchAll(pattern)) {
+      found.push({ file: rel, line: index + 1, path: match[0] })
+    }
+  }
+
+  return found
+}
+
+/**
+ * Lists the files a citation can live in: tracked, plus untracked files git
+ * does not ignore. The untracked half is what keeps a new entry's references
+ * checked on the branch that adds it rather than one push later.
+ *
+ * Returns undefined when git cannot answer, which the caller reports rather
+ * than smoothing into an empty list. An empty list resolves every one of its
+ * zero citations, so a degraded git would otherwise turn the push gate into an
+ * unconditional pass with output indistinguishable from a clean tree.
+ */
+async function listFiles(root: string): Promise<string[] | undefined> {
+  const run = async (args: string[]): Promise<string[] | undefined> => {
+    const result = await $`git -C ${root} ${args}`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+    if (result.exitCode !== 0) return undefined
+    return result.text().split('\n').filter(Boolean)
+  }
+
+  const tracked = await run(['ls-files'])
+  const untracked = await run(['ls-files', '--others', '--exclude-standard'])
+  if (!tracked || !untracked) return undefined
+
+  return [...new Set([...tracked, ...untracked])].sort()
+}
+
+/**
+ * `unavailable` is a distinct state from a clean scan.
+ *
+ * Finding nothing and being unable to look mean opposite things, and only one
+ * of them should let a push through.
+ */
+export type CitationReport =
+  | {
+      readonly kind: 'scanned'
+      readonly scanned: number
+      readonly total: number
+      readonly unresolved: readonly Citation[]
+    }
+  | { readonly kind: 'unavailable' }
+
+/**
+ * Resolves every cited path outside the fixture trees.
+ *
+ * This is the only check that gates the repository check, which makes it the
+ * only one whose false positives cost a contributor anything. It reports a
+ * finding solely for a path that does not resolve on disk, and the exclusions
+ * above are what keep that from firing on prose about paths.
+ */
+export async function auditCitations(
+  root: string,
+  folders: readonly string[],
+): Promise<CitationReport> {
+  const pattern = citationPattern(folders)
+  const listed = await listFiles(root)
+  if (!listed) return { kind: 'unavailable' }
+
+  const candidates = listed.filter((rel) => !isFixture(rel))
+  const citations: Citation[] = []
+
+  for (const rel of candidates) {
+    const path = resolve(root, rel)
+    if (!existsSync(path)) continue
+
+    let text: string
+    try {
+      text = await readFile(path, 'utf8')
+    } catch {
+      continue
+    }
+
+    citations.push(...collectCitations(rel, text, pattern))
+  }
+
+  return {
+    kind: 'scanned',
+    scanned: candidates.length,
+    total: citations.length,
+    unresolved: citations.filter(
+      (citation) => !existsSync(resolve(root, citation.path)),
+    ),
+  }
+}