jackherd 0.0.1 → 1.0.1

package/src/check/command.ts

@@ -0,0 +1,136 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { findProjectRoot, globalConfigPath, locateConfigFile } from '../config/location'
+import { readRepositoryFacts } from '../config/repository-facts'
+import { baseRefOf } from '../plans/settings'
+import { type ChangedFile, parsePorcelain, STATUS_COMMAND } from './changes'
+import { deferralArrowCheck } from './deferral-arrows'
+import { runCheck, runProcess } from './execute'
+import { type CheckPlan, type Filesystem, isSlow, planChecks } from './plan'
+import { planStructureChecks } from './plan-structure-check'
+import { publicContentCheck } from './public-content-check'
+import { artifactResult, formatPlanHeader, formatResults, skippedSlowResult, summarize } from './report'
+import { type CheckResult, SKIP_SLOW_FLAG } from './result'
+import { type CheckSettings, CONFIG_PATH, parseCheckSettings } from './settings'
+
+type CheckTarget = { root: string; configPath: string }
+
+const TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/
+
+/**
+ * Where the checks run and which config they read: the nearest project with `.jackherd/config.json`, else the
+ * repository's top level with `~/.jackherd/config.json` (a global install in a repository without the kit).
+ */
+export const resolveCheckTarget = (
+  start: string,
+  home: string,
+  exists: (path: string) => boolean,
+  gitTopLevel: (start: string) => string | null,
+): CheckTarget | null => {
+  const project = findProjectRoot(start, home, exists)
+  const projectConfig = project && locateConfigFile([project], home, exists)
+  if (project && projectConfig) return { root: project, configPath: projectConfig }
+  const global = globalConfigPath(home)
+  if (!exists(global)) return null
+  const root = gitTopLevel(start)
+  return root ? { root, configPath: global } : null
+}
+
+const gitTopLevelOf = (start: string): string | null => {
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: start, encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+/** A file as `ref` holds it; null when the ref lacks it (a new file) or git cannot answer. */
+const contentAt =
+  (root: string, ref: string) =>
+  (path: string): string | null => {
+    const result = spawnSync('git', ['show', `${ref}:${path}`], { cwd: root, encoding: 'utf8' })
+    return result.status === 0 ? result.stdout : null
+  }
+
+const filesystemAt = (root: string): Filesystem => ({
+  hasPackageJson: (dir) => existsSync(join(root, dir, 'package.json')),
+  hasTsconfig: (dir) => existsSync(join(root, dir, 'tsconfig.json')),
+  hasTests: (dir) => existsSync(join(root, dir)) && readdirSync(join(root, dir)).some((entry) => TEST_FILE.test(entry)),
+})
+
+const print = (lines: readonly string[]): void => {
+  for (const line of lines) console.log(line)
+}
+
+const loadSettings = (configPath: string, root: string): CheckSettings | string => {
+  try {
+    return parseCheckSettings(JSON.parse(readFileSync(configPath, 'utf8')), readRepositoryFacts(root))
+  } catch (error) {
+    return `${configPath} is not valid: ${error instanceof Error ? error.message : String(error)}`
+  }
+}
+
+const changedFiles = async (root: string): Promise<ChangedFile[] | string> => {
+  const status = await runProcess(STATUS_COMMAND, root)
+  return status.ok ? parsePorcelain(status.output) : status.output
+}
+
+const executePlan = async (
+  plan: CheckPlan,
+  root: string,
+  skipSlow: boolean,
+  ownChecks: readonly (CheckResult | null)[],
+): Promise<CheckResult[]> => {
+  const [slow, quick] = [plan.checks.filter(isSlow), plan.checks.filter((check) => !isSlow(check))]
+  return [
+    artifactResult(plan.artifacts),
+    ...ownChecks.filter((result) => result !== null),
+    ...(await Promise.all(quick.map((check) => runCheck(check, root)))),
+    ...(skipSlow ? [skippedSlowResult()] : await Promise.all(slow.map((check) => runCheck(check, root)))),
+  ]
+}
+
+/**
+ * Runs the configured checks over the files `git status` reports. Exit code 1 when any check fails
+ * or the configuration cannot be read.
+ */
+export const run = async (args: string[], home: string = homedir()): Promise<number> => {
+  const target = resolveCheckTarget(process.cwd(), home, existsSync, gitTopLevelOf)
+  if (!target) {
+    console.error(`No ${CONFIG_PATH} found in this directory or above it, and no ~/${CONFIG_PATH} in a git repository.`)
+    return 1
+  }
+  const { root, configPath } = target
+  const settings = loadSettings(configPath, root)
+  const files = await changedFiles(root)
+  if (typeof settings === 'string' || typeof files === 'string') {
+    console.error(typeof settings === 'string' ? settings : files)
+    return 1
+  }
+  print(settings.notes)
+  if (files.length === 0) {
+    console.log('Nothing changed.')
+    return 0
+  }
+
+  const plan = planChecks(files, settings.commands, settings.check, filesystemAt(root))
+  print(formatPlanHeader(files, plan))
+  const publicContent = publicContentCheck(root, plan.paths, settings.check.publicContent, home)
+  const deferralArrows = deferralArrowCheck(root, plan.paths, settings.planDirectory)
+  const planStructure = planStructureChecks({
+    root,
+    paths: plan.paths,
+    planDirectory: settings.planDirectory,
+    language: settings.planLanguage,
+    previousOf: contentAt(root, 'HEAD'),
+    baseOf: contentAt(root, baseRefOf(settings)),
+  })
+  const results = await executePlan(plan, root, args.includes(SKIP_SLOW_FLAG), [
+    publicContent,
+    deferralArrows,
+    ...planStructure,
+  ])
+  print(formatResults(results))
+  const summary = summarize(results)
+  console.log(`\n${summary.line}`)
+  return summary.failed === 0 ? 0 : 1
+}

package/src/check/deferral-arrows.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, posix } from 'node:path'
+import { type MisplacedDeferral, misplacedDeferrals } from '../plan-format'
+import { CHECK_STATUS, type CheckResult } from './result'
+
+type DeferralFinding = MisplacedDeferral & { path: string }
+
+/** The changed Markdown files under the plan directory: the plans (and boards) this diff touches. */
+export const changedPlansOf = (paths: readonly string[], planDirectory: string): string[] => {
+  const directory = posix.normalize(planDirectory).replace(/\/+$/, '')
+  return paths.filter((path) => path.startsWith(`${directory}/`) && path.endsWith('.md'))
+}
+
+const deferralArrowResult = (findings: readonly DeferralFinding[], plans: number, durationMs: number): CheckResult => ({
+  name: 'Plan deferral arrows',
+  command: `${plans} changed ${plans === 1 ? 'plan' : 'plans'}, open checkboxes with → P<n>`,
+  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.fail,
+  detail:
+    findings
+      .map(({ path, line, corrected }) => `${path}:${line} has the phase arrow inside the line; write: ${corrected}`)
+      .join('\n') || 'every phase arrow ends its line',
+  durationMs,
+})
+
+/**
+ * Open checkboxes in the changed plans whose `→ P<n>` is not at the end of the line, where the plans view reads
+ * it. Plans outside the diff are not read. Null when no plan changed.
+ */
+export const deferralArrowCheck = (
+  root: string,
+  paths: readonly string[],
+  planDirectory: string,
+): CheckResult | null => {
+  const plans = changedPlansOf(paths, planDirectory)
+  if (plans.length === 0) return null
+  const started = Date.now()
+  const findings = plans
+    .filter((path) => existsSync(join(root, path)))
+    .flatMap((path) => misplacedDeferrals(readFileSync(join(root, path), 'utf8')).map((found) => ({ ...found, path })))
+  return deferralArrowResult(findings, plans.length, Date.now() - started)
+}

package/src/check/execute.ts

@@ -0,0 +1,29 @@
+import { join } from 'node:path'
+import type { PlannedCheck } from './plan'
+import { type CheckResult, outcomeOf, type ProcessResult } from './result'
+
+/** Output is `trimEnd`ed only: a leading space can be significant (git status columns). */
+export const runProcess = async (argv: readonly string[], cwd: string): Promise<ProcessResult> => {
+  try {
+    const proc = Bun.spawn([...argv], { cwd, stdout: 'pipe', stderr: 'pipe' })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+    return { ok: exitCode === 0, output: `${stdout}${stderr}`.trimEnd() }
+  } catch (error) {
+    return { ok: false, output: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+export const runCheck = async (check: PlannedCheck, workspaceRoot: string): Promise<CheckResult> => {
+  const startedAt = performance.now()
+  const processResult = await runProcess(check.argv, join(workspaceRoot, check.cwd))
+  return {
+    name: check.name,
+    command: check.command,
+    ...outcomeOf(check, processResult),
+    durationMs: Math.round(performance.now() - startedAt),
+  }
+}

package/src/check/glob.ts

@@ -0,0 +1,15 @@
+const GLOB_TOKENS: Record<string, string> = {
+  '**/': '(?:.*/)?',
+  '**': '.*',
+  '*': '[^/]*',
+  '?': '[^/]',
+}
+
+/** One pass over the glob, so a literal `.` before a `*` is never mistaken for the `.*` a `**` produced. */
+export const matchesGlob = (path: string, glob: string): boolean => {
+  const pattern = glob.replace(/\*\*\/|\*\*|\*|\?|[.+^${}()|[\]\\]/g, (token) => GLOB_TOKENS[token] ?? `\\${token}`)
+  return new RegExp(`^${pattern}$`).test(path)
+}
+
+export const matchesAnyGlob = (path: string, globs: readonly string[]): boolean =>
+  globs.some((glob) => matchesGlob(path, glob))

package/src/check/plan-structure-check.ts

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  boardRowsWithoutPhase,
+  hasLanesTable,
+  type MergedPhaseWithOpenBoxes,
+  mergedPhasesWithOpenBoxes,
+  newPhasesWithoutReviewGate,
+  type PhaseWithoutGate,
+  PLAN_VOCABULARY,
+  type PlanLanguage,
+  phaseIdsOfPlan,
+  type RowWithoutPhase,
+} from '../plan-format'
+import { changedPlansOf } from './deferral-arrows'
+import { CHECK_STATUS, type CheckResult } from './result'
+
+/** The content of a file at a ref; null where the ref lacks the file. */
+export type ContentAt = (path: string) => string | null
+
+/**
+ * What the plan-structure checks read: the changed paths under `root`, the plan directory and language, and each
+ * changed file as it was before the change (`previousOf`, at `HEAD`) and on the base branch (`baseOf`).
+ */
+export type PlanCheckInput = {
+  root: string
+  paths: readonly string[]
+  planDirectory: string
+  language: PlanLanguage
+  previousOf: ContentAt
+  baseOf: ContentAt
+}
+
+type Changed = { path: string; current: string; previous: string | null; base: string | null; board: boolean }
+
+type Found<T> = T & { path: string }
+
+const gateResult = (
+  findings: readonly Found<PhaseWithoutGate>[],
+  plans: number,
+  language: PlanLanguage,
+  durationMs: number,
+): CheckResult => ({
+  name: 'Plan review gates',
+  command: `${plans} changed ${plans === 1 ? 'plan' : 'plans'}, new phases need a review gate`,
+  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.fail,
+  detail:
+    findings
+      .map(
+        ({ path, line, id, title }) =>
+          `${path}:${line} Phase ${id} ${title} has tasks but no review gate; add one, or a **${PLAN_VOCABULARY[language].noReviewGate}:** line with the reason`,
+      )
+      .join('\n') || 'every new phase has a review gate',
+  durationMs,
+})
+
+const rowResult = (findings: readonly Found<RowWithoutPhase>[], boards: number, durationMs: number): CheckResult => ({
+  name: 'Board rows without a phase',
+  command: `${boards} changed ${boards === 1 ? 'board' : 'boards'}, changed lane rows name a phase`,
+  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.warn,
+  detail:
+    findings
+      .map(
+        ({ path, line, lane, phases }) =>
+          `${path}:${line} lane ${lane}: "${phases}" names no phase (P<n>), so the view cannot tie the step to one`,
+      )
+      .join('\n') || 'every changed lane row names a phase',
+  durationMs,
+})
+
+const mergedResult = (
+  findings: readonly Found<MergedPhaseWithOpenBoxes>[],
+  plans: number,
+  durationMs: number,
+): CheckResult => ({
+  name: 'Merged phases with open boxes',
+  command: `${plans} changed ${plans === 1 ? 'plan' : 'plans'}, a merged phase ticks or moves on its open boxes`,
+  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.warn,
+  detail:
+    findings
+      .map(
+        ({ path, line, id, title, openLines }) =>
+          `${path}:${line} Phase ${id} ${title} is merged but has open boxes at ${openLines.join(', ')}; tick them or end them with → P<n>`,
+      )
+      .join('\n') || 'no merged phase has an open box left',
+  durationMs,
+})
+
+const withPath =
+  <T>(path: string) =>
+  (found: T): Found<T> => ({ ...found, path })
+
+const gatesOf = ({ path, current, previous }: Changed, language: PlanLanguage): Found<PhaseWithoutGate>[] =>
+  newPhasesWithoutReviewGate(current, language, previous ? phaseIdsOfPlan(previous, language) : new Set()).map(
+    withPath(path),
+  )
+
+const rowsOf = ({ path, current, previous }: Changed, language: PlanLanguage): Found<RowWithoutPhase>[] =>
+  boardRowsWithoutPhase(current, language, new Set(previous?.split('\n') ?? [])).map(withPath(path))
+
+const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Found<MergedPhaseWithOpenBoxes>[] =>
+  base ? mergedPhasesWithOpenBoxes(current, base, language).map(withPath(path)) : []
+
+const changedContents = ({ root, previousOf, baseOf, language }: PlanCheckInput, plans: readonly string[]): Changed[] =>
+  plans
+    .filter((path) => existsSync(join(root, path)))
+    .map((path) => {
+      const current = readFileSync(join(root, path), 'utf8')
+      return { path, current, previous: previousOf(path), base: baseOf(path), board: hasLanesTable(current, language) }
+    })
+
+/**
+ * The structure of the changed plans and boards: a phase the change added (against `HEAD`) with tasks and without
+ * a review gate fails; a lane row the change added or edited that names no phase warns; a phase whose tasks are
+ * all ticked on the base branch and that still has open boxes without `→ P<n>` warns. Empty when no plan changed;
+ * the row result is left out when no changed file has a lanes table, the merged result when every one has.
+ */
+export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
+  const files = changedPlansOf(input.paths, input.planDirectory)
+  if (files.length === 0) return []
+  const { language } = input
+  const started = Date.now()
+  const changed = changedContents(input, files)
+  const boards = changed.filter(({ board }) => board)
+  const plans = changed.filter(({ board }) => !board)
+  const gates = changed.flatMap((file) => gatesOf(file, language))
+  const rows = boards.flatMap((file) => rowsOf(file, language))
+  const merged = plans.flatMap((file) => mergedOf(file, language))
+  const durationMs = Date.now() - started
+  return [
+    gateResult(gates, files.length, language, durationMs),
+    ...(boards.length > 0 ? [rowResult(rows, boards.length, durationMs)] : []),
+    ...(plans.length > 0 ? [mergedResult(merged, plans.length, durationMs)] : []),
+  ]
+}

package/src/check/plan.ts

@@ -0,0 +1,106 @@
+import type { JackherdConfig } from '../config'
+import { type ChangedFile, generatorOwnedFiles, stagedBuildArtifacts } from './changes'
+import { tokenize } from './command-line'
+import { looseDirectories, packageRootsFor } from './roots'
+import { projectChecksFor, publicContentReviewers, reviewersFor } from './routing'
+import type { CheckConfig } from './schema'
+
+export const CHECK_KIND = { lint: 'lint', project: 'project', types: 'types', tests: 'tests' } as const
+
+export type CheckKind = (typeof CHECK_KIND)[keyof typeof CHECK_KIND]
+
+export type PlannedCheck = {
+  name: string
+  /** What the report shows; `argv` is what runs. */
+  command: string
+  argv: string[]
+  /** Relative to the workspace root. */
+  cwd: string
+  kind: CheckKind
+}
+
+export type PackageCommands = Pick<JackherdConfig['commands'], 'test' | 'typecheck'>
+
+export type Filesystem = {
+  hasPackageJson: (dir: string) => boolean
+  hasTsconfig: (dir: string) => boolean
+  hasTests: (dir: string) => boolean
+}
+
+export type CheckPlan = {
+  paths: string[]
+  roots: string[]
+  reviewers: string[]
+  generated: { path: string; generator: string }[]
+  artifacts: string[]
+  /** Fast checks first, then the ones that scale with the package; the runner starts each group together. */
+  checks: PlannedCheck[]
+}
+
+export const isSlow = (check: PlannedCheck): boolean =>
+  check.kind === CHECK_KIND.types || check.kind === CHECK_KIND.tests
+
+const lintCheck = (config: CheckConfig, paths: readonly string[]): PlannedCheck => ({
+  name: 'Lint & unused imports',
+  command: `${config.lintFilesCommand} (${paths.length} files)`,
+  argv: [...tokenize(config.lintFilesCommand), ...paths],
+  cwd: '.',
+  kind: CHECK_KIND.lint,
+})
+
+const projectChecks = (config: CheckConfig, paths: readonly string[]): PlannedCheck[] =>
+  projectChecksFor(paths, config.checks).map(({ name, command }) => ({
+    name,
+    command,
+    argv: tokenize(command),
+    cwd: '.',
+    kind: CHECK_KIND.project,
+  }))
+
+const inDirectory = (kind: CheckKind, label: string, command: string, dir: string): PlannedCheck => ({
+  name: `${label} (${dir})`,
+  command: `cd ${dir} && ${command}`,
+  argv: tokenize(command),
+  cwd: dir,
+  kind,
+})
+
+const typeChecks = (
+  roots: readonly string[],
+  command: string,
+  hasTsconfig: Filesystem['hasTsconfig'],
+): PlannedCheck[] => roots.filter(hasTsconfig).map((root) => inDirectory(CHECK_KIND.types, 'Types', command, root))
+
+const testChecks = (dirs: readonly string[], command: string): PlannedCheck[] =>
+  dirs.map((dir) => inDirectory(CHECK_KIND.tests, 'Tests', command, dir))
+
+/**
+ * Decides, without touching the disk or running anything, what a set of changed files calls for:
+ * which package roots to type-check and test, which project checks fire, which reviewers to start.
+ */
+export const planChecks = (
+  files: readonly ChangedFile[],
+  commands: PackageCommands,
+  config: CheckConfig,
+  filesystem: Filesystem,
+): CheckPlan => {
+  const paths = files.map((file) => file.path)
+  const roots = packageRootsFor(paths, filesystem.hasPackageJson).filter((root) => root !== '.')
+  const looseDirs = config.looseTests ? looseDirectories(paths, roots, filesystem.hasTests) : []
+  return {
+    paths,
+    roots,
+    reviewers: [...reviewersFor(paths, config.reviewerRoutes), ...publicContentReviewers(paths, config.publicContent)],
+    generated: generatorOwnedFiles(paths, config.generatorOwned),
+    artifacts: stagedBuildArtifacts(files, config.buildArtifacts),
+    checks:
+      paths.length === 0
+        ? []
+        : [
+            lintCheck(config, paths),
+            ...projectChecks(config, paths),
+            ...typeChecks(roots, commands.typecheck, filesystem.hasTsconfig),
+            ...testChecks([...roots, ...looseDirs], commands.test),
+          ],
+  }
+}

package/src/check/public-content-check.ts

@@ -0,0 +1,32 @@
+import { deriveTerms, findPublicLeaks, publicContentResult, withoutVocabulary } from './public-content'
+import {
+  readAddedLines,
+  readLocalPublicContent,
+  readPublicContentFacts,
+  readVocabulary,
+  trackedFiles,
+} from './public-content-facts'
+import type { CheckResult } from './result'
+import { isPublicPath, publicPathsOf } from './routing'
+import type { PublicContentConfig } from './schema'
+
+/**
+ * Added lines of changed published files against the names of the repositories around this one and of this
+ * project (`deriveTerms`), minus the words the published files already use. Null when no published file changed.
+ */
+export const publicContentCheck = (
+  root: string,
+  paths: readonly string[],
+  config: PublicContentConfig | undefined,
+  home: string,
+): CheckResult | null => {
+  const changed = publicPathsOf(paths, config)
+  if (changed.length === 0) return null
+  const started = Date.now()
+  const isPublic = (path: string) => isPublicPath(path, config)
+  const tracked = trackedFiles(root)
+  const facts = readPublicContentFacts(root, tracked, isPublic, readLocalPublicContent(home))
+  const terms = withoutVocabulary(deriveTerms(facts), readVocabulary(root, tracked.filter(isPublic)))
+  const leaks = findPublicLeaks(readAddedLines(root, changed, new Set(tracked)), terms)
+  return publicContentResult(leaks, { files: changed.length, terms: terms.length }, Date.now() - started)
+}

package/src/check/public-content-facts.ts

@@ -0,0 +1,177 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { legacyPublicContentPath } from '../config/legacy-names'
+import { TOOL_DIRECTORY } from '../config/location'
+import type { AddedLine, Neighbour, PublicContentFacts } from './public-content'
+import { addedLines } from './public-content'
+
+/** The user's own additions, outside every repository: work directories to treat as neighbours, and terms. */
+export type LocalPublicContent = { workDirectories: string[]; terms: string[] }
+
+const PUBLIC_CONTENT_FILE = 'public-content.json'
+
+const APP_FOLDERS = ['apps', 'services']
+
+const PROJECT_FOLDERS = [...APP_FOLDERS, 'packages']
+
+const ENV_EXAMPLE = /(^|\/)\.env[^/]*\.example$|(^|\/)[^/]*\.env\.example$/
+
+const git = (cwd: string, args: string[]): string | null => {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  return result.status === 0 ? result.stdout : null
+}
+
+const lines = (text: string | null): string[] => (text ?? '').split('\n').filter((line) => line !== '')
+
+const directoriesIn = (directory: string): string[] => {
+  try {
+    return readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(directory, entry.name))
+  } catch {
+    return []
+  }
+}
+
+const readJson = (path: string): unknown => {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+const stringsOf = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
+
+/**
+ * `~/.jackherd/public-content.json`, else the old `agent-kit/public-content.json` below `XDG_CONFIG_HOME` (or
+ * `~/.config`) until the global sync moves it; a missing or broken file adds nothing.
+ */
+export const readLocalPublicContent = (home: string, configHome = process.env.XDG_CONFIG_HOME): LocalPublicContent => {
+  const raw =
+    readJson(join(home, TOOL_DIRECTORY, PUBLIC_CONTENT_FILE)) ?? readJson(legacyPublicContentPath(home, configHome))
+  const object = typeof raw === 'object' && raw !== null ? (raw as Record<string, unknown>) : {}
+  const expand = (path: string) => (path.startsWith('~/') ? join(home, path.slice(2)) : path)
+  return { workDirectories: stringsOf(object.workDirectories).map(expand), terms: stringsOf(object.terms) }
+}
+
+/** The main checkout of the repository at `root`, also from inside a linked worktree. */
+const mainCheckoutOf = (root: string): string => {
+  const common = git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir'])
+  return common ? dirname(common.trim()) : resolve(root)
+}
+
+const neighbourAt = (directory: string): Neighbour => ({
+  name: directory.split('/').at(-1) ?? directory,
+  remotes: lines(git(directory, ['remote', '-v'])).map((line) => line.split(/\s+/)[1] ?? ''),
+  branches: lines(git(directory, ['for-each-ref', '--format=%(refname:short)', 'refs/heads', 'refs/remotes'])),
+})
+
+/** Git repositories beside this one and in the work directories, never this one itself. */
+const neighboursOf = (mainCheckout: string, workDirectories: readonly string[]): Neighbour[] => {
+  const candidates = [dirname(mainCheckout), ...workDirectories].flatMap(directoriesIn)
+  const unique = [...new Set(candidates.map((path) => resolve(path)))]
+  return unique.filter((path) => path !== mainCheckout && existsSync(join(path, '.git'))).map(neighbourAt)
+}
+
+const packageScope = (path: string): string | null => {
+  const name = (readJson(path) as { name?: unknown } | null)?.name
+  return typeof name === 'string' && name.startsWith('@') ? name.split('/')[0] : null
+}
+
+/** `package.json` of the root and of every folder below `apps/`, `services/` and `packages/`, relative to the root. */
+const manifestsOf = (root: string): string[] =>
+  ['', ...PROJECT_FOLDERS.flatMap((folder) => directoriesIn(join(root, folder)).map((path) => relative(root, path)))]
+    .map((directory) => join(directory, 'package.json'))
+    .filter((path) => existsSync(join(root, path)))
+
+/** Scopes of the project's package manifests, and of those inside the published paths (`isPublic`). */
+const scopesOf = (root: string, isPublic: (path: string) => boolean) => {
+  const scoped = manifestsOf(root).flatMap((path) => {
+    const scope = packageScope(join(root, path))
+    return scope ? [{ scope, isOwn: isPublic(path) }] : []
+  })
+  return {
+    scopes: scoped.map(({ scope }) => scope),
+    ownScopes: scoped.filter(({ isOwn }) => isOwn).map(({ scope }) => scope),
+  }
+}
+
+/**
+ * Blobs as `git cat-file --batch` prints them, headers included: `HEAD:<path>` for the last commit, `:<path>` for
+ * the index. Read from git, never through the working tree, so a symlink or a deleted file reads as git has it.
+ */
+const readBlobs = (root: string, specs: readonly string[]): string => {
+  if (specs.length === 0) return ''
+  const result = spawnSync('git', ['cat-file', '--batch'], {
+    cwd: root,
+    input: specs.join('\n'),
+    encoding: 'utf8',
+    maxBuffer: 256 * 1024 * 1024,
+  })
+  return result.status === 0 ? result.stdout : ''
+}
+
+const envExamplesOf = (root: string, tracked: readonly string[]): string[] => [
+  readBlobs(
+    root,
+    tracked.filter((path) => ENV_EXAMPLE.test(path)).map((path) => `:${path}`),
+  ),
+]
+
+/**
+ * What `deriveTerms` reads: the repositories around this one, the project's apps, scopes and env examples, and
+ * the user's local file. Read fresh on every run and kept in memory only.
+ */
+export const readPublicContentFacts = (
+  root: string,
+  tracked: readonly string[],
+  isPublic: (path: string) => boolean,
+  local: LocalPublicContent,
+): PublicContentFacts => ({
+  neighbours: neighboursOf(mainCheckoutOf(root), local.workDirectories),
+  apps: APP_FOLDERS.flatMap((folder) => directoriesIn(join(root, folder))).map((path) => path.split('/').at(-1) ?? ''),
+  ...scopesOf(root, isPublic),
+  envExamples: envExamplesOf(root, tracked),
+  localTerms: local.terms,
+})
+
+/** The text of the published files as `HEAD` has them: the words the kit already uses. */
+export const readVocabulary = (root: string, publicFiles: readonly string[]): string =>
+  readBlobs(
+    root,
+    publicFiles.map((path) => `HEAD:${path}`),
+  )
+
+/** Every file git tracks in the repository, read once per check; `-z` keeps unusual names unquoted. */
+export const trackedFiles = (root: string): string[] =>
+  (git(root, ['ls-files', '-z']) ?? '').split('\0').filter((path) => path !== '')
+
+/** A NUL byte near the start marks a binary file (an image, a video); SVG and other text files have none. */
+export const isBinary = (content: Buffer): boolean => content.subarray(0, 8000).includes(0)
+
+/** Every line of a new regular file; a binary file, a directory or one that cannot be read has none. */
+const linesOfTextFile = (root: string, path: string): AddedLine[] => {
+  try {
+    const target = join(root, path)
+    if (!lstatSync(target).isFile()) return []
+    const content = readFileSync(target)
+    if (isBinary(content)) return []
+    return content
+      .toString('utf8')
+      .split('\n')
+      .map((text, index) => ({ path, line: index + 1, text }))
+  } catch {
+    return []
+  }
+}
+
+/** Lines a change adds to the published files: the diff against `HEAD`, and every line of a new, untracked file. */
+export const readAddedLines = (root: string, changed: readonly string[], tracked: ReadonlySet<string>): AddedLine[] => {
+  const known = changed.filter((path) => tracked.has(path))
+  const diff = known.length > 0 ? git(root, ['diff', 'HEAD', '--unified=0', '--no-color', '--', ...known]) : ''
+  const untracked = changed.filter((path) => !tracked.has(path)).flatMap((path) => linesOfTextFile(root, path))
+  return [...addedLines(diff ?? ''), ...untracked]
+}