@erclx/aitk 3.0.0 → 3.2.0

package/src/git-files.ts

@@ -1,6 +1,80 @@
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
 
+/**
+ * Preferred first, matching `src/gov/test-order.ts` and `src/tasks/trunk.ts`. A
+ * local `main` trailing the remote pulls other people's merged commits into the
+ * range, so a check reading it decides against files the branch never touched.
+ */
+const TRUNK_REFS = ['origin/main', 'main'] as const
+
+/** Runs git under `root` with the resolution variables a hook exports stripped. */
+async function git(
+  root: string,
+  args: readonly string[],
+): Promise<string | undefined> {
+  const result = await $`git -C ${root} ${args}`.env(gitEnv()).quiet().nothrow()
+  return result.exitCode === 0 ? result.text().trimEnd() : undefined
+}
+
+/**
+ * The far side of a branch range: the ref a caller named, or the merge base
+ * against the first trunk this repository carries.
+ *
+ * A named ref that resolves to nothing refuses rather than falling back, since
+ * measuring the trunk range instead would answer a question nobody asked.
+ */
+export async function resolveBaseRef(
+  root: string,
+  ref?: string,
+): Promise<string | undefined> {
+  if (ref !== undefined) {
+    const resolved = await git(root, [
+      'rev-parse',
+      '--verify',
+      '--quiet',
+      `${ref}^{commit}`,
+    ])
+    return resolved === undefined || resolved === '' ? undefined : resolved
+  }
+
+  for (const trunk of TRUNK_REFS) {
+    const merged = await git(root, ['merge-base', 'HEAD', trunk])
+    if (merged !== undefined && merged !== '') return merged
+  }
+
+  return undefined
+}
+
+/**
+ * Every path a branch has touched since `base`: the diff against the working
+ * tree, plus untracked files git does not ignore.
+ *
+ * The working tree rather than `HEAD` on purpose. A check that runs before the
+ * branch is committed has to see the surface a session just added, and reading
+ * `HEAD` there returns a set the working tree has already moved past. Since the
+ * range is a superset of `base..HEAD`, a caller running after the commits still
+ * gets the whole branch.
+ *
+ * Returns undefined when git cannot answer, for the reason
+ * `listRepositoryFiles` states: an empty list reads as a clean branch.
+ */
+export async function listChangedFiles(
+  root: string,
+  base: string,
+): Promise<string[] | undefined> {
+  const changed = await git(root, ['diff', '--name-only', base])
+  const untracked = await git(root, [
+    'ls-files',
+    '--others',
+    '--exclude-standard',
+  ])
+  if (changed === undefined || untracked === undefined) return undefined
+
+  const paths = [...changed.split('\n'), ...untracked.split('\n')]
+  return [...new Set(paths.filter(Boolean))].sort()
+}
+
 /**
  * Lists the files under `root`: tracked, plus untracked files git does not
  * ignore. The untracked half is what keeps a file added on this branch in scope

package/src/labels/audit.ts

@@ -0,0 +1,82 @@
+import { listChangedFiles, resolveBaseRef } from '@/git-files'
+import { type Coverage, resolveCoverage } from '@/labels/coverage'
+import { type MapRefusal, readLabelMap } from '@/labels/map'
+
+/**
+ * Why an audit produced no reading.
+ *
+ * `no-map` travels through from the map reader and stays an answer rather than
+ * a fault. The git reasons are the opposite: a range this check asked for and
+ * could not get, which is a broken invocation rather than a project that
+ * declared nothing.
+ *
+ * A named ref that will not resolve is its own reason. Folding it into
+ * `no-base` sends the caller who already passed `--base` a message telling
+ * them to pass `--base`.
+ */
+export type LabelAuditRefusal =
+  | MapRefusal
+  | 'no-base'
+  | 'bad-base'
+  | 'unreadable-changes'
+
+export type LabelAudit =
+  | {
+      readonly kind: 'measured'
+      /** Absent when the caller supplied the changed set rather than a range. */
+      readonly base?: string
+      readonly changed: readonly string[]
+      readonly coverage: Coverage
+    }
+  | { readonly kind: 'refused'; readonly reason: LabelAuditRefusal }
+
+export interface LabelAuditOptions {
+  /** Far side of the range, defaulting to the merge base against the trunk. */
+  readonly base?: string
+  /** A changed set the caller already holds, which skips git entirely. */
+  readonly paths?: readonly string[]
+}
+
+/**
+ * Resolves a changed set against the map a project declares, and reports both
+ * what it earns and what it leaves uncovered.
+ *
+ * One verb for two readers by design. `git-pr` reads the labels at open time
+ * and the audit aggregate reads the uncovered count, and a verb shaped for the
+ * first alone returns nothing the second can retain.
+ */
+export async function auditLabels(
+  root: string,
+  options: LabelAuditOptions = {},
+): Promise<LabelAudit> {
+  const map = readLabelMap(root)
+  if (map.kind === 'refused') return { kind: 'refused', reason: map.reason }
+
+  if (options.paths !== undefined) {
+    return {
+      kind: 'measured',
+      changed: [...options.paths],
+      coverage: resolveCoverage(map, options.paths),
+    }
+  }
+
+  const base = await resolveBaseRef(root, options.base)
+  if (base === undefined) {
+    return {
+      kind: 'refused',
+      reason: options.base === undefined ? 'no-base' : 'bad-base',
+    }
+  }
+
+  const changed = await listChangedFiles(root, base)
+  if (changed === undefined) {
+    return { kind: 'refused', reason: 'unreadable-changes' }
+  }
+
+  return {
+    kind: 'measured',
+    base,
+    changed,
+    coverage: resolveCoverage(map, changed),
+  }
+}

package/src/labels/coverage.ts

@@ -0,0 +1,79 @@
+import type { LabelMap } from '@/labels/map'
+
+/** A path a row leaves unlabelled on purpose, carrying the reason it gives. */
+export interface DeclinedPath {
+  readonly path: string
+  readonly reason: string
+}
+
+export interface Coverage {
+  /** Distinct labels the whole set earns, ordered as the map declares them. */
+  readonly labels: readonly string[]
+  /**
+   * Paths a `[declined]` row covers, which are a decision rather than a gap.
+   *
+   * Kept apart from `uncovered` because the response to the two differs. A
+   * surface nobody has gotten to wants a row, and one somebody decided against
+   * wants nothing, so a report folding them together is useful about neither.
+   */
+  readonly declined: readonly DeclinedPath[]
+  /** Paths no row of either table reaches, which is the finding. */
+  readonly uncovered: readonly string[]
+}
+
+/**
+ * Prefix-anchored, matching what the map's own comment describes and what the
+ * census behind its 41 prefixes was measured against.
+ *
+ * A glob would reach every existing prefix and invalidate that measurement, so
+ * the rule stays a `startsWith` even where a glob would read more naturally.
+ */
+function matches(path: string, prefixes: readonly string[]): boolean {
+  return prefixes.some((prefix) => path.startsWith(prefix))
+}
+
+/**
+ * Resolves what a changed set earns from a map, and what it leaves behind.
+ *
+ * One pass answers both readers. `git-pr` wants the labels to apply, and the
+ * audit wants the paths that earned none, and a function shaped for the first
+ * alone returns nothing the second can count.
+ */
+export function resolveCoverage(
+  map: Extract<LabelMap, { kind: 'map' }>,
+  paths: readonly string[],
+): Coverage {
+  const earned = new Set<string>()
+  const declined: DeclinedPath[] = []
+  const uncovered: string[] = []
+
+  for (const path of paths) {
+    const labels = map.domains.filter((row) => matches(path, row.prefixes))
+
+    // A label wins over a decline. A path both tables claim already carries a
+    // subject, so reporting it as deliberately unlabelled would contradict the
+    // label the same run is about to apply.
+    if (labels.length > 0) {
+      for (const row of labels) earned.add(row.label)
+      continue
+    }
+
+    const row = map.declined.find((entry) => matches(path, entry.prefixes))
+    if (row !== undefined) {
+      declined.push({ path, reason: row.reason })
+      continue
+    }
+
+    uncovered.push(path)
+  }
+
+  return {
+    // Read back off the map rather than out of the set, so two runs over one
+    // branch produce one order and one string.
+    labels: map.domains
+      .map((row) => row.label)
+      .filter((label) => earned.has(label)),
+    declined,
+    uncovered,
+  }
+}

package/src/labels/map.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Where a project declares its pull request label map, spelled once.
+ *
+ * The file has already moved once, and that relocation rewrote every mention
+ * across four surfaces. Nothing in code spells it anywhere else, so the next
+ * move is one edit here rather than a sweep.
+ */
+export const MAP_REL = join('.claude', 'aitk', 'pr-labels.toml')
+
+/** A label name and the path prefixes that earn it, in the map's own order. */
+export interface DomainRow {
+  readonly label: string
+  readonly prefixes: readonly string[]
+}
+
+/** A reason a path is deliberately unlabelled, and the prefixes it covers. */
+export interface DeclinedRow {
+  readonly reason: string
+  readonly prefixes: readonly string[]
+}
+
+/**
+ * Why a map could not be read, which is never the same as a map with no rows.
+ *
+ * `no-map` is an answer rather than a fault. A project declaring no map is
+ * labelled silently by design, so a refusal read as a break would make the map
+ * mandatory for every target, which that decision declined. The other two are
+ * a file that exists and cannot be used, which is a defect in the map itself.
+ */
+export type MapRefusal = 'no-map' | 'unreadable-map' | 'no-domains'
+
+export type LabelMap =
+  | {
+      readonly kind: 'map'
+      readonly domains: readonly DomainRow[]
+      readonly declined: readonly DeclinedRow[]
+    }
+  | { readonly kind: 'refused'; readonly reason: MapRefusal }
+
+/**
+ * Reads a TOML table of string arrays into rows, dropping any key whose value
+ * carries no usable prefix.
+ *
+ * A malformed row is skipped rather than refused, because both tables are
+ * authored by hand and one bad entry should not blind the check to the other
+ * forty. What it costs is that a typo reads as a row nobody wrote, which the
+ * uncovered report surfaces from the other side.
+ */
+function readRows(table: unknown): { key: string; prefixes: string[] }[] {
+  if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+    return []
+  }
+
+  const rows: { key: string; prefixes: string[] }[] = []
+  for (const [key, value] of Object.entries(table)) {
+    if (!Array.isArray(value)) continue
+    const prefixes = value.filter(
+      (entry): entry is string => typeof entry === 'string' && entry !== '',
+    )
+    if (prefixes.length > 0) rows.push({ key, prefixes })
+  }
+
+  return rows
+}
+
+/** Parses map text, so a caller holding the bytes skips the filesystem. */
+export function parseLabelMap(source: string): LabelMap {
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(source) as Record<string, unknown>
+  } catch {
+    return { kind: 'refused', reason: 'unreadable-map' }
+  }
+
+  const domains = readRows(parsed.domains)
+  if (domains.length === 0) return { kind: 'refused', reason: 'no-domains' }
+
+  return {
+    kind: 'map',
+    domains: domains.map(({ key, prefixes }) => ({ label: key, prefixes })),
+    declined: readRows(parsed.declined).map(({ key, prefixes }) => ({
+      reason: key,
+      prefixes,
+    })),
+  }
+}
+
+/** Reads the map a project declares at `root`, or says why it could not. */
+export function readLabelMap(root: string): LabelMap {
+  let source: string
+  try {
+    source = readFileSync(join(root, MAP_REL), 'utf8')
+  } catch {
+    return { kind: 'refused', reason: 'no-map' }
+  }
+
+  return parseLabelMap(source)
+}

package/src/sync/check.ts

@@ -1,7 +1,9 @@
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { basename, join, sep } from 'node:path'
 import { execa } from 'execa'
-import { createGovAdapter } from '@/gov/adapter'
+import { gitEnv } from '@/git-env'
+import { createGovAdapter, rulesSourceDir } from '@/gov/adapter'
+import { loadGovStack } from '@/gov/stacks'
 import { createSnippetsAdapter } from '@/snippets/adapter'
 import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
 import {
@@ -154,6 +156,13 @@ export interface CheckReport {
   readonly superseded: readonly SupersededEntry[]
   readonly unmigrated: readonly UnmigratedDomain[]
   readonly newSkills: readonly string[]
+  /**
+   * Rules the toolkit authored after this target's governance anchor, filtered
+   * to what the target could receive. It rides beside `newSkills` rather than
+   * folding into it because the two answer the same question about different
+   * corpora and a reader acting on one runs a different command from the other.
+   */
+  readonly newRules: readonly string[]
   /**
    * The one section built by walking the target rather than the catalog. It
    * reports beside `superseded`, `unmigrated`, and `newSkills` rather than
@@ -336,6 +345,7 @@ export async function buildCheckReport(
       superseded: [],
       unmigrated: [],
       newSkills: [],
+      newRules: [],
       reverse: emptyReverseReport(),
       skew: await skewRead,
     }
@@ -350,6 +360,11 @@ export async function buildCheckReport(
     superseded: collectSuperseded(target),
     unmigrated,
     newSkills: await readNewSkills(toolkitRoot, anchors),
+    newRules: await readNewRules(
+      toolkitRoot,
+      target,
+      stampedCommit(stamp, 'governance'),
+    ),
     reverse: buildReverseReport(toolkitRoot, target),
     skew: await skewRead,
   }
@@ -411,6 +426,145 @@ export function parseNewSkills(paths: string): string[] {
   return [...new Set(names)].sort()
 }
 
+/**
+ * What the target's `.claude/rules/` proves about its entitlement. `held` is
+ * every rule name it carries and `bands` every band folder those names sit in.
+ *
+ * Read off the installed tree rather than off a stack name, because
+ * `gov install` records file hashes and never the stack it resolved, so the
+ * chain a target consumed survives nowhere else. `installRules` copies each
+ * rule into the subdirectory it was authored in, which is what makes the band
+ * folders legible as evidence.
+ */
+export function readInstalledRules(target: string): {
+  held: Set<string>
+  bands: Set<string>
+} {
+  const dir = join(target, ...INSTALL_MARKERS.governance)
+  const held = new Set<string>()
+  const bands = new Set<string>()
+  if (!isDirectory(dir)) return { held, bands }
+
+  for (const rel of new Bun.Glob('**/*.md').scanSync({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    const posix = rel.split(sep).join('/')
+    const boundary = posix.indexOf('/')
+
+    held.add(basename(posix, '.md'))
+    if (boundary > 0) bands.add(posix.slice(0, boundary))
+  }
+
+  return { held, bands }
+}
+
+/**
+ * Narrows rules added upstream to the ones this target could receive and does
+ * not already hold.
+ *
+ * The band test is the entitlement filter, and `bands` carries two sources: the
+ * folders the target already holds, and the folders the base stack takes whole.
+ * A rule authored under `lang/` or `ui/` is named by an individual stack, so it
+ * belongs to some targets and not others, and listing every added file would
+ * tell a base consumer about rules it was never entitled to. The test
+ * over-reports inside a band a target already carries, since one folder can be
+ * reached by more than one stack, and that costs a line where under-reporting
+ * would cost the whole point of the section.
+ *
+ * The `held` test is what keeps a rule that moved bands upstream out. A rename
+ * reaches this diff as an addition, and the target already has the file under
+ * its old folder, so matching by name is what tells the two apart.
+ */
+export function selectNewRules(
+  paths: string,
+  held: ReadonlySet<string>,
+  bands: ReadonlySet<string>,
+): string[] {
+  const prefix = 'governance/rules/'
+  const names = new Set<string>()
+
+  for (const line of paths.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith(prefix) || !trimmed.endsWith('.md')) continue
+
+    const rel = trimmed.slice(prefix.length)
+    const boundary = rel.indexOf('/')
+    const band = boundary === -1 ? '' : rel.slice(0, boundary)
+    const name = basename(rel, '.md')
+
+    if (held.has(name)) continue
+    if (band !== '' && !bands.has(band)) continue
+
+    names.add(name)
+  }
+
+  return [...names].sort()
+}
+
+/**
+ * Band folders the base stack takes whole. Every governance stack extends base,
+ * so a rule authored under one of these is entitled to every target.
+ *
+ * This is what covers a band no target can carry yet. Entitlement is otherwise
+ * read off folders the target already holds, and a folder added to base later
+ * exists in no installed tree, so without this the rules inside it would reach
+ * nobody. Read from the stack file rather than fixed, so that addition needs no
+ * code change here.
+ *
+ * A folder only a leaf stack names is deliberately absent. It is entitled to
+ * some targets and not others, which is the distinction the band test makes and
+ * the installed tree is the only evidence of.
+ */
+export function baseBands(root: string): Set<string> {
+  const stack = loadGovStack(root, 'base')
+  if (stack === undefined) return new Set()
+
+  return new Set(
+    stack.rules.filter((entry) =>
+      isDirectory(join(rulesSourceDir(root), entry)),
+    ),
+  )
+}
+
+/**
+ * Rules are domain-scoped, so this measures from governance's own anchor rather
+ * than from the oldest anchor across domains the way `readNewSkills` does. A
+ * shared anchor would let a snippets sync move the revision rules are measured
+ * from and drop a rule out of the read.
+ *
+ * A target carrying no governance anchor reports nothing. It has no date to
+ * measure against, and diffing from the beginning of history would read every
+ * rule the toolkit ships as new.
+ *
+ * An anchor this clone cannot resolve reports nothing by a different route and
+ * says so nowhere. `read` yields an empty string on a non-zero exit, so a stamp
+ * naming a revision a registry install or a shallow clone has never seen reads
+ * as a target holding everything. `readNewSkills` carries the same gap, and
+ * neither has the `historyUnavailable` flag the per-domain scan uses to tell an
+ * unmeasured result from a clean one.
+ */
+export async function readNewRules(
+  root: string,
+  target: string,
+  since: string | undefined,
+): Promise<string[]> {
+  if (since === undefined) return []
+
+  const paths = await read(root, [
+    'diff',
+    '--name-only',
+    '--diff-filter=A',
+    `${since}..HEAD`,
+    '--',
+    'governance/rules/',
+  ])
+
+  const { held, bands } = readInstalledRules(target)
+  return selectNewRules(paths, held, bands.union(baseBands(root)))
+}
+
 async function readUpstream(
   root: string,
   since: string,
@@ -474,7 +628,7 @@ async function isAncestor(
   const result = await execa(
     'git',
     ['-C', root, 'merge-base', '--is-ancestor', candidate, reference],
-    { reject: false },
+    { reject: false, env: gitEnv(), extendEnv: false },
   )
 
   return result.exitCode === 0
@@ -483,9 +637,18 @@ async function isAncestor(
 /**
  * A toolkit outside a git clone, or a stamped revision this clone has never
  * seen, yields no range. The per-file report still stands on its own.
+ *
+ * Scrubbed through `gitEnv` because a git hook exports `GIT_DIR` and its
+ * siblings into every process it runs and they outrank `-C`. A check invoked
+ * from a hook would otherwise diff the hook's repository and report a range for
+ * a tree nobody asked about, which reads as an ordinary answer.
  */
 async function read(root: string, args: readonly string[]): Promise<string> {
-  const result = await execa('git', ['-C', root, ...args], { reject: false })
+  const result = await execa('git', ['-C', root, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
   return result.exitCode === 0 ? result.stdout : ''
 }