@erclx/aitk 0.63.1 → 0.64.0

package/src/commands/context.ts

@@ -1,17 +1,13 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
-  BULLET_CHECKPOINT,
   type EntryReport,
   governsContent,
   LENGTH_CHECKPOINT,
   measureFolders,
   missingSections,
-  PEER_BULLET_CHECKPOINT,
   PROVENANCE_FOLDER,
-  RENDER_WIDTH,
   REQUIRED_SECTIONS,
-  RUN_CHECKPOINT,
   type SectionFinding,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -23,6 +19,7 @@ import {
 } from '@/context/folders'
 import { isGating } from '@/context/gate'
 import { auditIndexes, type FolderDrift } from '@/context/index-drift'
+import { RENDER_WIDTH } from '@/markdown/structure'
 import {
   frameError,
   intro,
@@ -57,7 +54,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, depth, bullet weight, citations, provenance, and index drift',
+      'Report required sections, entry length, citations, catalog tables, provenance, and index drift',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -82,8 +79,11 @@ export function register(program: Command): void {
         '',
         'An unresolved citation always gates. --gate widens the gate to the',
         'other two findings that are facts rather than judgments: a missing',
-        'required section and index drift. Length, depth, bullet, table, and',
-        'provenance findings are thresholds and stay advisory under both.',
+        'required section and index drift. Length, table, and provenance',
+        'findings are thresholds and stay advisory under both.',
+        '',
+        'Depth and bullet weight are stated over every markdown file rather',
+        'than over a context entry, so `aitk markdown audit` measures them.',
         '',
         'Examples:',
         '  aitk context audit',
@@ -192,8 +192,6 @@ async function runAudit(
     reportCitations(citations, cited)
     reportSections(sections, folders)
     reportLength(entries)
-    reportDepth(entries)
-    reportBullets(entries, folders)
     reportTables(entries)
     reportProvenance(entries, folders)
     reportDrift(drift)
@@ -221,11 +219,7 @@ async function runAudit(
         indexDrift: drift,
         checkpoints: {
           lines: LENGTH_CHECKPOINT,
-          run: RUN_CHECKPOINT,
-          runCountsBlankLines: true,
           renderWidth: RENDER_WIDTH,
-          peerBullet: PEER_BULLET_CHECKPOINT,
-          bullet: BULLET_CHECKPOINT,
           provenanceFolder: PROVENANCE_FOLDER,
           requiredSections: REQUIRED_SECTIONS,
         },
@@ -395,7 +389,7 @@ function reportLength(entries: readonly EntryReport[]): void {
     `Entries measure rendered lines at ${RENDER_WIDTH} columns, counting frontmatter and fenced blocks.`,
   )
   logInfo(
-    'A reference-heavy entry therefore ranks by its examples, which the depth check excludes.',
+    'A reference-heavy entry therefore ranks by its examples, which the depth check in `aitk markdown audit` excludes.',
   )
 
   const over = entries
@@ -415,107 +409,6 @@ function reportLength(entries: readonly EntryReport[]): void {
   )
 }
 
-/**
- * Names the render width and 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 both is what keeps the two measurements reconcilable, and the width
- * matters more than the blank lines because a number counted in rendered lines
- * cannot be reproduced without it.
- */
-function reportDepth(entries: readonly EntryReport[]): void {
-  logStep('Depth')
-  logInfo(
-    `Runs measure rendered lines at ${RENDER_WIDTH} columns and count blank lines.`,
-  )
-  logInfo(
-    `Fenced blocks are excluded, and so are peer lists averaging under ${PEER_BULLET_CHECKPOINT} characters a bullet.`,
-  )
-  logInfo(
-    'A run that is entirely table rows is excluded too, since a heading inside a table splits the table rather than the run.',
-  )
-
-  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} rendered lines unbroken`,
-      )
-      .join('\n'),
-  )
-}
-
-/**
- * Groups by entry, and states its reach on every run, for the reasons the
- * provenance report does both.
- *
- * Bullets past the checkpoint cluster in a handful of entries and the heaviest
- * entries carry them a dozen at a time, so a flat list of bullets buries the
- * entry holding one. What a reader acts on is which file to open.
- */
-function reportBullets(
-  entries: readonly EntryReport[],
-  folders: readonly AuditedFolder[],
-): void {
-  logStep('Bullets')
-
-  const governed = folders.filter(governsContent)
-  if (governed.length === 0) {
-    logInfo(
-      `Out of scope. The rule is stated in the standard governing .claude/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
-    )
-    return
-  }
-
-  logInfo(
-    `Covers .claude/${PROVENANCE_FOLDER}/ alone, since moving an incident out of a bullet needs a decision to keep.`,
-  )
-  logInfo(
-    'Top-level bullets measure characters, folding in continuation lines.',
-  )
-  logInfo(
-    'Nested items and fenced blocks are excluded. Weight is a judgment, never a defect.',
-  )
-
-  const carrying = entries
-    .filter((entry) => entry.heavyBullets.length > 0)
-    .sort((a, b) => b.heavyBullets.length - a.heavyBullets.length)
-
-  if (carrying.length === 0) {
-    logInfo(`No bullet past the ${BULLET_CHECKPOINT}-character checkpoint.`)
-    return
-  }
-
-  const total = carrying.reduce(
-    (sum, entry) => sum + entry.heavyBullets.length,
-    0,
-  )
-  logWarn(
-    `${plural(total, 'bullet')} past the ${BULLET_CHECKPOINT}-character checkpoint across ${carrying.length} ${carrying.length === 1 ? 'entry' : 'entries'}`,
-  )
-  pipeOutput(
-    carrying
-      .map(
-        (entry) =>
-          `${entry.rel}  ${plural(entry.heavyBullets.length, 'bullet')}\n${entry.heavyBullets
-            .map((found) => `  :${found.line}  ${found.characters} characters`)
-            .join('\n')}`,
-      )
-      .join('\n'),
-  )
-}
-
 function reportTables(entries: readonly EntryReport[]): void {
   logStep('Tables')
 

package/src/commands/markdown.ts

@@ -0,0 +1,383 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { type BanReport, banReport, loadStandards } from '@/markdown/bans'
+import { resolveMarkdown } from '@/markdown/files'
+import { type BanFinding, bodyLines, scanBans } from '@/markdown/scan'
+import {
+  type Checkpoints,
+  measureStructure,
+  parseCheckpoints,
+  type StructureReport,
+} from '@/markdown/structure'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface AuditCommandOptions {
+  readonly json?: boolean
+}
+
+interface FileReport {
+  readonly rel: string
+  readonly bans: readonly BanFinding[]
+  readonly structure: StructureReport
+}
+
+export function register(program: Command): void {
+  const markdown = program
+    .command('markdown')
+    .description('Report markdown files against the attribute standards')
+    .helpOption('-h, --help', 'Show this help message')
+
+  markdown
+    .command('audit')
+    .description(
+      'Report the character bans, the word bans, and bullet, paragraph, and depth weight',
+    )
+    .argument(
+      '[path...]',
+      'Markdown files, directories, or globs, defaulting to every markdown file git lists',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the audit completed',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Every finding reports and none gates. A banned character is a fact and',
+        'will gate once the corpus has been measured and fixed, which is the',
+        'follow-up rather than this command.',
+        '',
+        'Bans and checkpoints are read from markdown.md and prose.md, resolved',
+        'under .claude/standards/ then standards/. No folder has to resolve and',
+        'no index.md has to exist, so .claude/rules/, governance/, and snippets/',
+        'are in reach.',
+        '',
+        'Examples:',
+        '  aitk markdown audit',
+        '  aitk markdown audit --json',
+        '  aitk markdown audit .claude/rules governance',
+        '  aitk markdown audit docs/agents/commands.md',
+        "  aitk markdown audit 'snippets/**/*.md'",
+        '',
+      ].join('\n'),
+    )
+    .action(async (paths: string[], opts: AuditCommandOptions) => {
+      process.exitCode = await runAudit(paths, opts)
+    })
+}
+
+async function runAudit(
+  paths: string[],
+  opts: AuditCommandOptions,
+): Promise<number> {
+  const root = process.cwd()
+  const scope = await resolveMarkdown(root, paths)
+
+  if (scope.kind === 'unavailable') {
+    return refuse(
+      'git could not list the tree, so no corpus was built. Run inside a git repository.',
+    )
+  }
+
+  if (scope.files.length === 0) {
+    return refuse(
+      paths.length === 0
+        ? 'No markdown file in the tree.'
+        : `No markdown file matched: ${scope.unmatched.join(', ')}`,
+    )
+  }
+
+  const standards = await loadStandards(root)
+  const bans = banReport(standards)
+  const checkpoints = parseCheckpoints(standards.markdown?.text ?? '')
+
+  const reports: FileReport[] = await Promise.all(
+    scope.files.map(async (rel) => {
+      const lines = bodyLines(await readFile(resolve(root, rel), 'utf8'))
+      return {
+        rel,
+        bans: scanBans(lines, bans),
+        structure: measureStructure(rel, lines, checkpoints),
+      }
+    }),
+  )
+
+  intro('aitk markdown audit')
+  reportScope(scope.files, scope.unmatched)
+  reportBans(reports, bans)
+  reportBullets(reports, checkpoints)
+  reportParagraphs(reports, checkpoints)
+  reportDepth(reports, checkpoints)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        files: scope.files,
+        unmatchedPaths: scope.unmatched,
+        bans: {
+          characters: bans.characters,
+          words: bans.words,
+          spellings: bans.spellings,
+          sources: bans.sources,
+          missingStandards: bans.missing,
+        },
+        checkpoints: {
+          run: checkpoints.run,
+          peerBullet: checkpoints.peerBullet,
+          bullet: checkpoints.bullet,
+          paragraph: checkpoints.paragraph,
+          sentences: checkpoints.sentences,
+          renderWidth: checkpoints.renderWidth,
+          fellBack: checkpoints.fellBack,
+        },
+        entries: reports.map((report) => ({
+          path: report.rel,
+          bans: report.bans,
+          longestRun: report.structure.longestRun,
+          longestRunLine: report.structure.longestRunLine,
+          heavyBullets: report.structure.heavyBullets,
+          heavyParagraphs: report.structure.heavyParagraphs,
+        })),
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+function refuse(message: string): number {
+  intro('aitk markdown audit')
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  return 1
+}
+
+function reportScope(
+  files: readonly string[],
+  unmatched: readonly string[],
+): void {
+  logStep('Scope')
+  logInfo(`${plural(files.length, 'markdown file')}`)
+
+  if (unmatched.length === 0) return
+
+  logWarn(`Matched no markdown file: ${unmatched.join(', ')}`)
+}
+
+/**
+ * Names what the closed sets reach and what they leave to a reader.
+ *
+ * The two standards state bans in three shapes and only two of them are a
+ * closed set. A phrase ban carries a placeholder standing in for the rest of
+ * the sentence and every voice rule is a judgment, so a report listing hits
+ * without naming those would read as a verdict on the whole standard.
+ */
+function reportBans(reports: readonly FileReport[], bans: BanReport): void {
+  logStep('Bans')
+
+  if (bans.missing.length > 0) {
+    logWarn(
+      `Not measured. Found neither copy of: ${bans.missing.join(', ')}. Looked under .claude/standards/ then standards/.`,
+    )
+    if (bans.sources.length === 0) return
+  }
+
+  logInfo(
+    `${plural(bans.characters.length, 'character')}, ${plural(bans.words.length, 'word')}, and ${plural(bans.spellings.length, 'spelling')} read from ${bans.sources.join(' and ')}`,
+  )
+  logInfo(
+    'Frontmatter, fenced blocks, code spans, and link destinations are excluded.',
+  )
+  logInfo(
+    'Phrase bans and every voice rule are patterns rather than closed sets, and stay a judgment for the reader.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.bans.length > 0)
+    .sort((a, b) => b.bans.length - a.bans.length)
+
+  if (carrying.length === 0) {
+    logInfo('No banned character, word, or spelling.')
+    return
+  }
+
+  const total = carrying.reduce((sum, report) => sum + report.bans.length, 0)
+  logWarn(`${plural(total, 'hit')} across ${plural(carrying.length, 'file')}`)
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.bans.length, 'hit')}\n${report.bans
+            .map(
+              (found) =>
+                `  :${found.line}:${found.column + 1}  ${found.kind}  ${found.term}`,
+            )
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
+function reportBullets(
+  reports: readonly FileReport[],
+  checkpoints: Checkpoints,
+): void {
+  logStep('Bullets')
+  logInfo(
+    'Top-level bullets measure characters, folding in continuation lines.',
+  )
+  logInfo(
+    'Nested items and fenced blocks are excluded. Weight is a judgment, never a defect.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.structure.heavyBullets.length > 0)
+    .sort(
+      (a, b) =>
+        b.structure.heavyBullets.length - a.structure.heavyBullets.length,
+    )
+
+  if (carrying.length === 0) {
+    logInfo(`No bullet past the ${checkpoints.bullet}-character checkpoint.`)
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, report) => sum + report.structure.heavyBullets.length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'bullet')} past the ${checkpoints.bullet}-character checkpoint across ${plural(carrying.length, 'file')}`,
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.structure.heavyBullets.length, 'bullet')}\n${report.structure.heavyBullets
+            .map((found) => `  :${found.line}  ${found.characters} characters`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
+/**
+ * States both halves of the checkpoint on every run.
+ *
+ * The standard states a sentence cap and a weight, and a report naming only the
+ * first would leave a reader unable to tell why a two-sentence paragraph is
+ * listed.
+ */
+function reportParagraphs(
+  reports: readonly FileReport[],
+  checkpoints: Checkpoints,
+): void {
+  logStep('Paragraphs')
+  logInfo(
+    `Prose paragraphs report past ${checkpoints.sentences} sentences or past ${checkpoints.paragraph} characters.`,
+  )
+  logInfo(
+    'The standard states both. Weight matches the bullet checkpoint today and moves independently of it.',
+  )
+  logInfo(
+    'Bullets, headings, tables, quotes, and fenced blocks each end a paragraph, so a bullet is measured once.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.structure.heavyParagraphs.length > 0)
+    .sort(
+      (a, b) =>
+        b.structure.heavyParagraphs.length - a.structure.heavyParagraphs.length,
+    )
+
+  if (carrying.length === 0) {
+    logInfo('No paragraph past either checkpoint.')
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, report) => sum + report.structure.heavyParagraphs.length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'paragraph')} past a checkpoint across ${plural(carrying.length, 'file')}`,
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.structure.heavyParagraphs.length, 'paragraph')}\n${report.structure.heavyParagraphs
+            .map(
+              (found) =>
+                `  :${found.line}  ${found.sentences} sentences, ${found.characters} characters`,
+            )
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
+/**
+ * Names the render width and 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 both keeps the two measurements reconcilable, and the width matters
+ * more, since a number counted in rendered lines cannot be reproduced without
+ * it.
+ */
+function reportDepth(
+  reports: readonly FileReport[],
+  checkpoints: Checkpoints,
+): void {
+  logStep('Depth')
+  logInfo(
+    `Runs measure rendered lines at ${checkpoints.renderWidth} columns and count blank lines.`,
+  )
+  logInfo(
+    `Fenced blocks are excluded, and so are peer lists averaging under ${checkpoints.peerBullet} characters a bullet.`,
+  )
+  logInfo(
+    'A run that is entirely table rows is excluded too, since a heading inside a table splits the table rather than the run.',
+  )
+
+  if (checkpoints.fellBack.length > 0) {
+    logWarn(
+      `Read no number from the standard for: ${checkpoints.fellBack.join(', ')}. Measured against the shipped default instead.`,
+    )
+  }
+
+  const over = reports
+    .filter((report) => report.structure.longestRun > checkpoints.run)
+    .sort((a, b) => b.structure.longestRun - a.structure.longestRun)
+
+  if (over.length === 0) {
+    logInfo(`No run past the ${checkpoints.run}-line checkpoint.`)
+    return
+  }
+
+  logWarn(`${over.length} past the ${checkpoints.run}-line checkpoint`)
+  pipeOutput(
+    over
+      .map(
+        (report) =>
+          `${report.structure.rel}:${report.structure.longestRunLine}  ${report.structure.longestRun} rendered lines unbroken`,
+      )
+      .join('\n'),
+  )
+}

package/src/commands/records.ts

@@ -1,4 +1,3 @@
-import { $ } from 'bun'
 import type { Command } from 'commander'
 import {
   type Finding,
@@ -8,6 +7,7 @@ import {
   validateRecords,
 } from '@/records/validate'
 import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
 
 /** Returned when a record carries a finding, which is the gating result. */
 const EXIT_FINDINGS = 2
@@ -17,23 +17,6 @@ interface ValidateCommandOptions {
   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')