@erclx/aitk 3.9.0 → 3.11.0

package/src/audits/catalog.ts

@@ -1,4 +1,6 @@
+import type { SkillsAuditRefusal } from '@/claude/skills-audit'
 import type { ReachRefusal } from '@/claude/skills-reach'
+import type { ContextAuditRefusal } from '@/context/audit'
 import type { AuditRefusal } from '@/deps/audit'
 import type { RestatedRefusal } from '@/gov/restated'
 import type { LabelAuditRefusal } from '@/labels/audit'
@@ -405,6 +407,23 @@ function commentCounts(record: unknown): Record<string, number> | undefined {
   return { degradationHits }
 }
 
+/**
+ * Reads the census's three headline totals, leaving the extension breakdown
+ * out. The breakdown is what a caller reads for its own sake, and folding
+ * every extension into the retained baseline would grow the recorded key set
+ * with every language the tree ever picks up.
+ */
+function censusCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined || !Array.isArray(root.byExtension)) return undefined
+
+  return allOf({
+    files: typeof root.files === 'number' ? root.files : undefined,
+    skipped: typeof root.skipped === 'number' ? root.skipped : undefined,
+    lines: typeof root.lines === 'number' ? root.lines : undefined,
+  })
+}
+
 function testOrderCounts(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -448,6 +467,12 @@ export const AUDITS: readonly AuditSpec[] = [
     argv: ['context', 'audit', '--json'],
     gatingExits: [EXIT_FINDINGS],
     corpus: 'tracked',
+    // The one reason this verb refuses for that is an absence rather than a
+    // break, on the same test the reach check and the skill audit take: no
+    // target adopts `.claude/context/`, `.claude/diagrams/`, and
+    // `.claude/wireframes/` all at once, so without the allowance every such
+    // project reports the verb unmeasured on every run and never changes.
+    absentReasons: ['no-folders'] satisfies ContextAuditRefusal[],
     counts: contextCounts,
   },
   {
@@ -467,6 +492,10 @@ export const AUDITS: readonly AuditSpec[] = [
     argv: ['claude', 'skills', 'audit', '--json'],
     gatingExits: [EXIT_FINDINGS],
     corpus: 'tracked',
+    // The one reason this verb refuses for, and it is an absence for the same
+    // reason the reach check's is: a project carrying neither `claude/skills/`
+    // nor `.claude/skills/` has adopted no skill convention this audit reads.
+    absentReasons: ['no-corpus'] satisfies SkillsAuditRefusal[],
     counts: skillCounts,
   },
   {
@@ -503,6 +532,14 @@ export const AUDITS: readonly AuditSpec[] = [
     argv: ['records', 'validate', kind, '--json'],
     gatingExits: [],
     corpus,
+    // `standards` is the one tracked kind here, so it takes none of the
+    // per-machine default the other five inherit from their corpus. A target
+    // reads standards through `aitk standards` rather than a copy in its own
+    // tree, so carrying neither `standards/` nor `.claude/standards/` is the
+    // ordinary state of every project but this repository.
+    ...(kind === 'standards' && {
+      absentReasons: ['no-folder'] satisfies RecordRefusal[],
+    }),
     counts: findingsOnly,
   })),
   {
@@ -597,6 +634,17 @@ export const AUDITS: readonly AuditSpec[] = [
     ] satisfies RestatedRefusal[],
     counts: restatedCounts,
   },
+  {
+    id: 'census',
+    label: 'Codebase census',
+    argv: ['census', '--json'],
+    // Reports rather than gates. A file count is a measure, not a judgment, so
+    // registering it here exists to retain growth against the baseline rather
+    // than to fail a push on a number moving.
+    gatingExits: [],
+    corpus: 'tracked',
+    counts: censusCounts,
+  },
   {
     id: 'deps',
     label: 'Dependency advisories',

package/src/census/count.ts

@@ -0,0 +1,113 @@
+import { readFile } from 'node:fs/promises'
+import { extname, join } from 'node:path'
+import { isBinary } from '@/binary'
+import { listRepositoryFiles } from '@/git-files'
+
+export type CensusRefusal = 'no-git'
+
+export interface ExtensionCount {
+  readonly extension: string
+  readonly files: number
+  readonly lines: number
+}
+
+export interface CensusResult {
+  readonly kind: 'measured'
+  readonly files: number
+  /** Binary or unreadable, counted toward `files` and excluded from `lines`. */
+  readonly skipped: number
+  readonly lines: number
+  readonly byExtension: readonly ExtensionCount[]
+}
+
+export interface CensusFailure {
+  readonly kind: 'refused'
+  readonly reason: CensusRefusal
+}
+
+/**
+ * Open descriptors allowed at once while reading the tree, matching
+ * `src/comments/scan.ts`. A single `Promise.all` over every path opens one
+ * descriptor per file, which exhausts a default 1024 limit on a large
+ * repository and fails the whole census with EMFILE.
+ */
+const CONCURRENT_READS = 64
+
+interface ReadOutcome {
+  readonly path: string
+  /** Absent when the read failed: a symlink leaving the tree, or a file git
+   * listed and the working tree no longer holds. */
+  readonly text?: string
+}
+
+async function readOne(root: string, path: string): Promise<ReadOutcome> {
+  try {
+    return { path, text: await readFile(join(root, path), 'utf8') }
+  } catch {
+    return { path }
+  }
+}
+
+function extensionFor(path: string): string {
+  const ext = extname(path)
+  return ext === '' ? 'no-extension' : ext.slice(1).toLowerCase()
+}
+
+/**
+ * A trailing newline is the file's terminator rather than an empty final line,
+ * which is what keeps a file ending `a\nb\n` at two lines rather than three.
+ */
+function countLines(text: string): number {
+  if (text === '') return 0
+  const lines = text.split('\n')
+  return text.endsWith('\n') ? lines.length - 1 : lines.length
+}
+
+/**
+ * Censuses the tracked-plus-untracked tree under `root`: a file count, a
+ * breakdown by extension, and a line total that skips whatever reads as
+ * binary.
+ *
+ * Reads `listRepositoryFiles`, the same corpus the citation check, the
+ * markdown corpus, and the secret scan already share, so this is not a
+ * fourth definition of what counts.
+ */
+export async function census(
+  root: string,
+): Promise<CensusResult | CensusFailure> {
+  const listed = await listRepositoryFiles(root)
+  if (listed === undefined) return { kind: 'refused', reason: 'no-git' }
+
+  const totals = new Map<string, { files: number; lines: number }>()
+  let skipped = 0
+  let lines = 0
+
+  for (let start = 0; start < listed.length; start += CONCURRENT_READS) {
+    const batch = listed.slice(start, start + CONCURRENT_READS)
+    const outcomes = await Promise.all(batch.map((path) => readOne(root, path)))
+
+    for (const outcome of outcomes) {
+      const extension = extensionFor(outcome.path)
+      const entry = totals.get(extension) ?? { files: 0, lines: 0 }
+      entry.files += 1
+
+      // A read that failed and a file that read as binary are counted the
+      // same way: toward `files`, excluded from every line count.
+      if (outcome.text === undefined || isBinary(outcome.text)) {
+        skipped += 1
+      } else {
+        const counted = countLines(outcome.text)
+        entry.lines += counted
+        lines += counted
+      }
+
+      totals.set(extension, entry)
+    }
+  }
+
+  const byExtension = [...totals.entries()]
+    .map(([extension, counts]) => ({ extension, ...counts }))
+    .sort((a, b) => b.files - a.files || a.extension.localeCompare(b.extension))
+
+  return { kind: 'measured', files: listed.length, skipped, lines, byExtension }
+}

package/src/claude/skills-audit.ts

@@ -25,6 +25,13 @@ export const CORPORA: readonly string[] = [
   join('.claude', 'skills'),
 ]
 
+/**
+ * The one reason this audit refuses. A project carrying neither corpus is the
+ * ordinary state of a target that has not adopted either skills convention,
+ * the same absence `no-skills` reads for the shipped citation reach check.
+ */
+export type SkillsAuditRefusal = 'no-corpus'
+
 /** Kebab-case, which the standard states as no spaces, capitals, or underscores. */
 const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 

package/src/cli.ts

@@ -30,6 +30,7 @@ import { register as audits } from '@/commands/audits'
 import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
+import { register as census } from '@/commands/census'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { palette } from '@/ui'
@@ -71,6 +72,7 @@ function showHelp(): void {
     `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
+    `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
@@ -116,6 +118,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk secrets scan --json`,
     `${GREY}│${NC}    aitk deps audit --json`,
     `${GREY}│${NC}    aitk labels audit --json`,
+    `${GREY}│${NC}    aitk census --json`,
     `${GREY}│${NC}    aitk audits run --json`,
     `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
@@ -164,6 +167,7 @@ sessions(program)
 secrets(program)
 deps(program)
 labels(program)
+census(program)
 audits(program)
 upgrade(program)
 

package/src/commands/census.ts

@@ -0,0 +1,105 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { census, type CensusRefusal } from '@/census/count'
+import { intro, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+interface CensusCommandOptions {
+  readonly json?: boolean
+}
+
+const REFUSALS: Record<CensusRefusal, string> = {
+  'no-git': 'git could not list this tree, so the corpus is unknown.',
+}
+
+export function register(program: Command): void {
+  program
+    .command('census')
+    .description(
+      'Report tracked file count, a breakdown by extension, and line totals',
+    )
+    .argument('[path]', 'Tree to census, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        '  Tracked files plus untracked files git does not ignore, the same',
+        '  corpus the citation check, the markdown corpus, and the secret',
+        '  scan already read. A line total skips whatever reads as binary.',
+        '',
+        'Exit codes:',
+        '  0  the census completed',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  aitk census',
+        '  aitk census src --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: CensusCommandOptions) => {
+      process.exitCode = await runCensus(path, opts)
+    })
+}
+
+async function runCensus(
+  path: string | undefined,
+  opts: CensusCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('aitk census')
+
+  const result = await census(root)
+
+  if (result.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[result.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: result.reason,
+          message: REFUSALS[result.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  logStep('Files')
+  logInfo(
+    `${plural(result.files, 'file')}, ${result.skipped} skipped as binary or unreadable`,
+  )
+
+  logStep('By extension')
+  for (const entry of result.byExtension) {
+    logInfo(
+      `${entry.extension}: ${plural(entry.files, 'file')}, ${entry.lines} lines`,
+    )
+  }
+
+  logStep('Lines')
+  logInfo(`${result.lines} counted, skipping binary or unreadable files`)
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        files: result.files,
+        skipped: result.skipped,
+        lines: result.lines,
+        byExtension: result.byExtension,
+      })}\n`,
+    )
+  }
+
+  return 0
+}

package/src/commands/claude.ts

@@ -20,6 +20,7 @@ import {
   REQUIREMENT_SECTIONS,
   type SkillFinding,
   type SkillsAudit,
+  type SkillsAuditRefusal,
 } from '@/claude/skills-audit'
 import {
   type RoutingRefusal,
@@ -862,8 +863,11 @@ async function runSkillsAudit(
 
   if (report.corpora.length === 0) {
     return refuseAudit(
+      'no-corpus',
       `No skill corpus under ${root}. Looked for ${CORPORA.join(' and ')}.`,
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
@@ -910,16 +914,26 @@ async function runSkillsAudit(
   return auditExitCode(report)
 }
 
-function refuseAudit(message: string, gateOnly: boolean): number {
+function refuseAudit(
+  reason: SkillsAuditRefusal,
+  message: string,
+  gateOnly: boolean,
+  root: string,
+  emitJson: boolean,
+): number {
   if (gateOnly) {
     frameError(message)
-    return 1
+  } else {
+    intro('aitk claude skills audit')
+    logStep('Refused')
+    logWarn(message)
+    outro()
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
   }
 
-  intro('aitk claude skills audit')
-  logStep('Refused')
-  logWarn(message)
-  outro()
   return 1
 }
 

package/src/commands/comments.ts

@@ -88,6 +88,12 @@ async function runScan(
     logStep('Refused')
     logWarn(languages)
     outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ root, reason: 'bad-languages', message: languages })}\n`,
+      )
+    }
     return 1
   }
 

package/src/commands/context.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
+  type ContextAuditRefusal,
   type EntryReport,
   governsContent,
   type LengthCause,
@@ -157,12 +158,17 @@ async function runAudit(
   // short a required section, which is the pass a gate exists to prevent.
   if (gateOnly && widened) {
     return refuse(
+      'conflicting-options',
       '--citations-only runs the citation check alone, so --gate would widen the gate to findings the run never measures. Pass one.',
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
-  if (typeof names === 'string') return refuse(names, gateOnly)
+  if (typeof names === 'string') {
+    return refuse('bad-folder-list', names, gateOnly, root, opts.json ?? false)
+  }
 
   // The root base is opt-in. A target carrying a root `wireframes/` would
   // otherwise be audited against a standard it never adopted, on a bare run
@@ -173,8 +179,11 @@ async function runAudit(
   })
   if (folders.length === 0) {
     return refuse(
+      'no-folders',
       `No audited folder found ${named ? 'under .claude/ or the project root' : 'under .claude/'}. Looked for: ${names.join(', ')}.`,
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
@@ -190,16 +199,22 @@ async function runAudit(
   const cited = presentNames(folders)
   if (gateOnly && cited.length === 0) {
     return refuse(
+      'no-citation-scope',
       `The citation check spells the .claude/ prefix and no audited folder resolved there. Looked for: ${names.join(', ')}.`,
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
   const citations = await auditCitations(root, cited)
   if (citations.kind === 'unavailable') {
     return refuse(
+      'no-git',
       'git could not list the tree, so no citation was checked. Run inside a git repository.',
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
@@ -308,16 +323,26 @@ async function runAudit(
   return gating ? EXIT_GATE : 0
 }
 
-function refuse(message: string, gateOnly: boolean): number {
+function refuse(
+  reason: ContextAuditRefusal,
+  message: string,
+  gateOnly: boolean,
+  root: string,
+  emitJson: boolean,
+): number {
   if (gateOnly) {
     frameError(message)
-    return 1
+  } else {
+    intro('aitk context audit')
+    logStep('Refused')
+    logWarn(message)
+    outro()
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
   }
 
-  intro('aitk context audit')
-  logStep('Refused')
-  logWarn(message)
-  outro()
   return 1
 }
 

package/src/commands/gov.ts

@@ -506,12 +506,12 @@ function runTestOrder(opts: TestOrderOptions): number {
   if (report.kind === 'unreadable') {
     intro('aitk gov test-order')
     logStep('Refused')
-    logError(report.reason)
+    logError(report.message)
     outro()
 
     if (emitJson) {
       process.stdout.write(
-        `${JSON.stringify({ ok: false, reason: report.reason })}\n`,
+        `${JSON.stringify({ root, reason: report.reason, message: report.message })}\n`,
       )
     }
 

package/src/commands/markdown.ts

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
-import { resolveMarkdown } from '@/markdown/files'
+import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
 import {
   type BanFinding,
@@ -119,15 +119,21 @@ async function runAudit(
 
   if (scope.kind === 'unavailable') {
     return refuse(
+      'no-git',
       'git could not list the tree, so no corpus was built. Run inside a git repository.',
+      root,
+      opts.json ?? false,
     )
   }
 
   if (scope.files.length === 0) {
     return refuse(
+      paths.length === 0 ? 'no-markdown' : 'no-match',
       paths.length === 0
         ? 'No markdown file in the tree.'
         : `No markdown file matched: ${scope.unmatched.join(', ')}`,
+      root,
+      opts.json ?? false,
     )
   }
 
@@ -203,11 +209,21 @@ async function runAudit(
   return gating ? EXIT_GATE : 0
 }
 
-function refuse(message: string): number {
+function refuse(
+  reason: MarkdownAuditRefusal,
+  message: string,
+  root: string,
+  emitJson: boolean,
+): number {
   intro('aitk markdown audit')
   logStep('Refused')
   logWarn(message)
   outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+  }
+
   return EXIT_REFUSED
 }
 

package/src/context/audit.ts

@@ -15,6 +15,22 @@ import { isStubSeed } from '@/seed-marker'
  * any markdown file, so they are stated at the attribute tier and measured by
  * `aitk markdown audit` rather than here.
  */
+/**
+ * Every reason `aitk context audit` refuses for.
+ *
+ * `no-folders` is the one ordinary absence: a project that never adopted
+ * `.claude/context/`, `.claude/diagrams/`, or `.claude/wireframes/` names no
+ * corpus this audit can measure, the same state `no-skills` reads for the
+ * skill corpora. The other four are a malformed invocation or a checkout git
+ * cannot read, which stay a break rather than an absence.
+ */
+export type ContextAuditRefusal =
+  | 'conflicting-options'
+  | 'bad-folder-list'
+  | 'no-folders'
+  | 'no-citation-scope'
+  | 'no-git'
+
 export const LENGTH_CHECKPOINT = 150
 
 /**

package/src/gov/test-order.ts

@@ -44,6 +44,21 @@ export interface Scope {
   readonly testSuffixes: readonly string[]
 }
 
+/**
+ * Every reason `aitk gov test-order` refuses for.
+ *
+ * None is an ordinary absence. A depth-1 checkout falls back to the root
+ * commit and reports zero rather than reaching any of these, so what remains
+ * is a repository with no commit at all or a git operation that failed
+ * outright, both a broken checkout rather than a target's ordinary state.
+ */
+export type TestOrderRefusal =
+  | 'no-history'
+  | 'no-log'
+  | 'no-tree'
+  | 'bad-base'
+  | 'no-base'
+
 export type TestOrderReport =
   | {
       readonly kind: 'measured'
@@ -56,7 +71,11 @@ export type TestOrderReport =
       /** Changed paths outside the pairing's reach, named rather than counted. */
       readonly ignored: readonly string[]
     }
-  | { readonly kind: 'unreadable'; readonly reason: string }
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: TestOrderRefusal
+      readonly message: string
+    }
 
 export interface TestOrderOptions {
   /** The far side of the range, defaulting to the merge base against the trunk. */
@@ -258,7 +277,8 @@ export function readTestOrder(
   if (head === undefined) {
     return {
       kind: 'unreadable',
-      reason: `No git history under ${root}. History is the only surface carrying the ordering, so there is nothing to read.`,
+      reason: 'no-history',
+      message: `No git history under ${root}. History is the only surface carrying the ordering, so there is nothing to read.`,
     }
   }
 
@@ -277,7 +297,8 @@ export function readTestOrder(
   if (log === undefined) {
     return {
       kind: 'unreadable',
-      reason: `Reading history between ${base} and HEAD failed under ${root}.`,
+      reason: 'no-log',
+      message: `Reading history between ${base} and HEAD failed under ${root}.`,
     }
   }
 
@@ -285,7 +306,8 @@ export function readTestOrder(
   if (tree === undefined) {
     return {
       kind: 'unreadable',
-      reason: `Reading the tree at ${base} failed under ${root}. Without it a test written before the range reads as absent.`,
+      reason: 'no-tree',
+      message: `Reading the tree at ${base} failed under ${root}. Without it a test written before the range reads as absent.`,
     }
   }
 
@@ -323,13 +345,14 @@ function resolveBase(
   root: string,
   ref: string | undefined,
   head: string,
-): string | { kind: 'unreadable'; reason: string } {
+): string | { kind: 'unreadable'; reason: TestOrderRefusal; message: string } {
   if (ref !== undefined) {
     const resolved = revParse(root, ref)
     if (resolved === undefined) {
       return {
         kind: 'unreadable',
-        reason: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+        reason: 'bad-base',
+        message: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
       }
     }
     return resolved
@@ -345,7 +368,8 @@ function resolveBase(
   if (rootCommits === undefined || rootCommits === '') {
     return {
       kind: 'unreadable',
-      reason: `No base resolves against ${root}. Fetch origin or pass --base.`,
+      reason: 'no-base',
+      message: `No base resolves against ${root}. Fetch origin or pass --base.`,
     }
   }