jackherd 1.12.6 → 1.13.0

package/src/check/report.ts

@@ -1,6 +1,8 @@
+import { STACKS, type StackDetection, stackOfCommand } from '../config/detect'
+import { CLI_NAME } from '../version/release'
 import { type ChangedFile, STATUS_COMMAND } from './changes'
 import type { CheckPlan } from './plan'
-import { CHECK_STATUS, type CheckResult, SKIP_SLOW_FLAG } from './result'
+import { CHECK_STATUS, type CheckResult, type CheckStatus, RUN_MODE, type RunMode, SKIP_SLOW_FLAG } from './result'
 
 const STATUS_ICON = { pass: '✅', fail: '❌', warn: '⚠️ ', skipped: '⏭️ ' } as const
 
@@ -20,10 +22,73 @@ export const skippedSlowResult = (): CheckResult => ({
   durationMs: 0,
 })
 
-export const formatPlanHeader = (files: readonly ChangedFile[], plan: CheckPlan): string[] => [
+const plural = (count: number, noun: string): string => `${count} ${noun}${count === 1 ? '' : 's'}`
+
+/** A full run fails on a changed source file no test covers; a quick one runs no test by design, so it warns. */
+export const UNTESTED_STATUS: Record<RunMode, CheckStatus> = {
+  [RUN_MODE.full]: CHECK_STATUS.fail,
+  [RUN_MODE.quick]: CHECK_STATUS.warn,
+}
+
+/** A changed source file of the stack with no test planned, with the status `UNTESTED_STATUS` gives the run mode. */
+export const untestedResult = (sources: readonly string[], mode: RunMode): CheckResult | null =>
+  sources.length === 0
+    ? null
+    : {
+        name: 'Tests',
+        command: 'commands.test',
+        status: UNTESTED_STATUS[mode],
+        detail: [
+          `no test ran for ${plural(sources.length, 'changed source file')}; set \`commands.test\` or a \`check.checks\` entry with \`kind: "tests"\``,
+          ...sources,
+        ].join('\n'),
+        durationMs: 0,
+      }
+
+/** The lock files of known stacks the repository holds; none means it has not installed yet. */
+const presentLockFiles = (detection: StackDetection): readonly string[] => {
+  if (detection.kind === 'found') return [detection.lockFile]
+  return detection.kind === 'ambiguous' ? detection.lockFiles : []
+}
+
+/**
+ * A failure when `commands.test` belongs to a known stack whose lock files the repository lacks (`bun test` beside
+ * only `composer.lock`): such a run finds no test and would read as green. Null for a command of no known stack,
+ * for no command, and in a repository without any lock file.
+ */
+export const testCommandResult = (command: string | undefined, detection: StackDetection): CheckResult | null => {
+  const stack = command === undefined ? undefined : stackOfCommand(command)
+  const present = presentLockFiles(detection)
+  if (stack === undefined || present.length === 0) return null
+  const { lockFiles } = STACKS[stack]
+  if (lockFiles.some((file) => present.includes(file))) return null
+  return {
+    name: 'Test command',
+    command: 'commands.test',
+    status: CHECK_STATUS.fail,
+    detail: `\`${command}\` needs ${lockFiles.join(' or ')}, which is missing; set \`commands.test\` for this repository's stack (\`${CLI_NAME} config test\` names the line)`,
+    durationMs: 0,
+  }
+}
+
+/** The stack line says how the stack was decided: by lock file, by manifest alone, none, or several lock files and so every stack's markers. */
+export const stackLine = (detection: StackDetection): string => {
+  if (detection.kind === 'found') return `Stack: ${detection.stack}`
+  if (detection.kind === 'manifest') return `Stack: ${detection.stack} (from ${detection.manifest}, no lock file yet)`
+  if (detection.kind === 'none')
+    return 'Stack: none detected (no lock file of a known stack, no manifest of a single stack)'
+  return `Stack: ambiguous (lock files of several stacks: ${detection.lockFiles.join(', ')}), checking with every stack's markers`
+}
+
+export const formatPlanHeader = (
+  files: readonly ChangedFile[],
+  plan: CheckPlan,
+  detection: StackDetection,
+): string[] => [
   `Changed files (${files.length}, ${files.filter((file) => file.staged).length} staged):`,
   ...files.map((file) => `   ${file.staged ? 'S' : ' '} ${file.path}`),
   '',
+  stackLine(detection),
   `Package roots: ${plan.roots.join(', ') || 'none'}`,
   `Reviewers: ${plan.reviewers.join(', ') || 'none'}`,
   ...(plan.generated.length > 0

package/src/check/result.ts

@@ -1,5 +1,7 @@
-import type { PlannedCheck } from './plan'
-import { CHECK_KIND } from './plan'
+/** What a planned check is; `types` and `tests` are the slow ones, and a project check may stand in for either. */
+export const CHECK_KIND = { lint: 'lint', project: 'project', types: 'types', tests: 'tests' } as const
+
+export type CheckKind = (typeof CHECK_KIND)[keyof typeof CHECK_KIND]
 
 /** `warn` reports a finding without failing the run. */
 export const CHECK_STATUS = { pass: 'pass', fail: 'fail', warn: 'warn', skipped: 'skipped' } as const
@@ -18,6 +20,14 @@ export type ProcessResult = { ok: boolean; output: string }
 
 export const SKIP_SLOW_FLAG = '--skip-slow'
 
+/** `quick` leaves every type check and test out (`--skip-slow`); `full` runs them. */
+export const RUN_MODE = { full: 'full', quick: 'quick' } as const
+
+export type RunMode = (typeof RUN_MODE)[keyof typeof RUN_MODE]
+
+export const runModeOf = (args: readonly string[]): RunMode =>
+  args.includes(SKIP_SLOW_FLAG) ? RUN_MODE.quick : RUN_MODE.full
+
 /**
  * Bun reports "there was nothing to run" in two shapes: a package whose files hold no test cases
  * summarises as `0 tests`, one with no matching files exits non-zero with `0 test files matching`.
@@ -30,7 +40,7 @@ export const lastLines = (output: string, count: number): string =>
 
 /** How a finished process reads for its check: an absent test suite is skipped, not failed. */
 export const outcomeOf = (
-  check: PlannedCheck,
+  check: { kind: CheckKind },
   { ok, output }: ProcessResult,
 ): Pick<CheckResult, 'status' | 'detail'> => {
   if (check.kind === CHECK_KIND.tests && reportsNoTests(output)) {

package/src/check/roots.ts

@@ -1,26 +1,54 @@
 import { dirname } from 'node:path'
+import { CLAUDE_DIRECTORY } from '../claude/paths'
+import { parseManifest } from '../sync/manifest'
+
+/** The manifest whose `workspaces` field gathers workspaces (npm, Yarn, Bun). */
+export const WORKSPACE_MANIFEST = 'package.json'
+
+/** pnpm lists its workspaces in a file of its own instead of `WORKSPACE_MANIFEST`. */
+export const WORKSPACE_LIST_FILE = 'pnpm-workspace.yaml'
+
+/**
+ * Whether a parsed `WORKSPACE_MANIFEST` gathers workspaces. Such a root only holds packages: a test run from
+ * there walks the whole monorepo.
+ */
+export const isWorkspaceManifest = (manifest: unknown): boolean =>
+  typeof manifest === 'object' && manifest !== null && Object.hasOwn(manifest, 'workspaces')
 
 /**
- * The nearest ancestor holding a `package.json`. Tests and `tsc` run from there and nowhere else:
- * Bun resolves `tsconfig.json` from the working directory, so descending below a package root
- * silently compiles `.tsx` against the wrong JSX runtime.
+ * The nearest ancestor holding the stack's root marker (`package.json`, `composer.json`), the repository
+ * root included. Tests and type checks run from there and nowhere else: Bun resolves `tsconfig.json`
+ * from the working directory, so descending below a package root silently compiles `.tsx` against the
+ * wrong JSX runtime.
  */
-export const packageRootOf = (path: string, hasPackageJson: (dir: string) => boolean): string | null => {
+export const packageRootOf = (path: string, isProjectRoot: (dir: string) => boolean): string | null => {
   let dir = dirname(path)
   while (dir !== '.' && dir !== '/' && dir !== '') {
-    if (hasPackageJson(dir)) return dir
+    if (isProjectRoot(dir)) return dir
     dir = dirname(dir)
   }
-  return hasPackageJson('.') ? '.' : null
+  return isProjectRoot('.') ? '.' : null
 }
 
-export const packageRootsFor = (paths: readonly string[], hasPackageJson: (dir: string) => boolean): string[] => [
-  ...new Set(paths.map((path) => packageRootOf(path, hasPackageJson)).filter((root): root is string => root !== null)),
+export const packageRootsFor = (paths: readonly string[], isProjectRoot: (dir: string) => boolean): string[] => [
+  ...new Set(paths.map((path) => packageRootOf(path, isProjectRoot)).filter((root): root is string => root !== null)),
 ]
 
+/**
+ * The repository paths of the files a parsed `.jackherd/lock.json` lists: copies whose tests run where the kit
+ * keeps their source. A missing or invalid lock lists none, so every changed source file needs its own test.
+ */
+export const kitCopyPaths = (manifest: unknown): string[] => {
+  const parsed = parseManifest(manifest)
+  return parsed.ok ? Object.keys(parsed.manifest.files).map((path) => `${CLAUDE_DIRECTORY}/${path}`) : []
+}
+
+/** Whether a test run from `root` reaches `path`; from `.` it reaches every path. */
+export const isUnder = (path: string, root: string): boolean => root === '.' || path.startsWith(`${root}/`)
+
 /**
  * Directories with test files that belong to no package root, which would otherwise be tested by
- * nobody. The workspace root is excluded: a test run from there walks the whole monorepo.
+ * nobody. The repository root `.` is excluded: a test run from there walks the whole repository.
  */
 export const looseDirectories = (
   paths: readonly string[],
@@ -29,7 +57,7 @@ export const looseDirectories = (
 ): string[] => [
   ...new Set(
     paths
-      .filter((path) => !roots.some((root) => path.startsWith(`${root}/`)))
+      .filter((path) => !roots.some((root) => isUnder(path, root)))
       .map((path) => dirname(path))
       .filter((dir) => dir !== '.' && hasTests(dir)),
   ),

package/src/check/schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { BUN_COMMANDS } from '../config/detect'
 import { tokenize } from './command-line'
+import { CHECK_KIND } from './result'
 
 const nonEmpty = z.string().min(1)
 
@@ -40,6 +40,11 @@ const projectCheck = z.strictObject({
   command,
   /** Without globs the check runs on every change; with them, only when a changed path matches. */
   globs: globs.optional(),
+  /**
+   * `tests` for a check that runs the project's tests, `types` for its type check; without one, a plain project check.
+   * A test run counts towards "no green without a test", and both run with the slow checks.
+   */
+  kind: z.enum([CHECK_KIND.tests, CHECK_KIND.types]).optional(),
 })
 
 const generatorOwned = z.strictObject({
@@ -67,9 +72,9 @@ const skillBudgets = z.record(glob, z.number().int().positive())
 export const checkConfigSchema = z.strictObject({
   /**
    * Run once over the changed files, which are appended as arguments. Separate from `commands.lint`,
-   * which lints the whole project.
+   * which lints the whole project. Detected from the repository when left out; without one, no lint runs.
    */
-  lintFilesCommand: command.default(BUN_COMMANDS.lintFiles),
+  lintFilesCommand: command.optional(),
   /** Project checks, run alongside lint; add repository-specific scripts here. */
   checks: z.array(projectCheck).default([]),
   generatorOwned: z.array(generatorOwned).default([]),

package/src/check/settings.ts

@@ -1,6 +1,13 @@
 import { z } from 'zod'
 import { jackherdConfigSchema } from '../config'
-import { type RepositoryFacts, withDetected } from '../config/detect'
+import {
+  detectStack,
+  isDecided,
+  type RepositoryFacts,
+  type Stack,
+  type StackDetection,
+  withDetected,
+} from '../config/detect'
 import { PROJECT_CONFIG_PATH } from '../config/location'
 import type { PlanLanguage } from '../vocabulary'
 import type { PackageCommands } from './plan'
@@ -16,13 +23,21 @@ export type CheckSettings = {
   planLanguage: PlanLanguage
   /** The branch on the remote whose plans count as merged. */
   baseBranch: string
+  /** Where the lane worktrees live, below the main checkout: a board's plans are read there too. */
+  worktreeDirectory: string
+  /** What the lock files (without one, the manifests) decide: one stack, none, or several (ambiguous); `stackOf` reads the stack from it. */
+  stack: StackDetection
   notes: string[]
 }
 
+/** The stack a detection decided, by lock file or manifest; null for none or several, where the check reads every stack's markers. */
+export const stackOf = (detection: StackDetection): Stack | null => (isDecided(detection) ? detection.stack : null)
+
 const commandsSchema = jackherdConfigSchema.shape.commands
 const planDirectorySchema = jackherdConfigSchema.shape.planDirectory
 const planLanguageSchema = jackherdConfigSchema.shape.planLanguage
 const baseBranchSchema = jackherdConfigSchema.shape.baseBranch
+const worktreeDirectorySchema = jackherdConfigSchema.shape.worktreeDirectory
 
 /**
  * The check runner's view of `.jackherd/config.json`: the shared `commands` block, `planDirectory`, `planLanguage` and `baseBranch` plus its own
@@ -39,6 +54,8 @@ export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckS
     planDirectory: planDirectorySchema.parse(object.planDirectory),
     planLanguage: planLanguageSchema.parse(object.planLanguage),
     baseBranch: baseBranchSchema.parse(object.baseBranch),
+    worktreeDirectory: worktreeDirectorySchema.parse(object.worktreeDirectory),
+    stack: detectStack(facts.lockFiles, facts.manifests),
     notes: detected.notes,
   }
 }

package/src/check/skill-budget-defaults.ts

@@ -20,7 +20,8 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/grill/SKILL.md': 685,
   '.claude/skills/implement/SKILL.md': 2190,
   // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
-  '.claude/skills/orchestrate/SKILL.md': 7880,
+  // Plain words: no plan code without its words in a short question.
+  '.claude/skills/orchestrate/SKILL.md': 7920,
   '.claude/skills/orchestrate/references/acceptance.md': 200,
   '.claude/skills/orchestrate/references/close-lane.md': 250,
   '.claude/skills/orchestrate/references/coordinator-handover.md': 551,
@@ -42,7 +43,7 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/start/SKILL.md': 607,
   '.claude/skills/uncle-bob/SKILL.md': 466,
   // P33: grows with the skill above.
-  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8680,
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8720,
   '.claude/agents/devops.md': 104,
   '.claude/agents/explore.md': 132,
   '.claude/agents/implement.md': 303,

package/src/config/base-branch.ts

@@ -0,0 +1,2 @@
+/** The base branch when the repository does not decide; the schema's default too. */
+export const DEFAULT_BASE_BRANCH = 'main'

package/src/config/command.ts

@@ -2,35 +2,54 @@ import { homedir } from 'node:os'
 import { mainCheckout, worktreeRoot } from '../plans/git'
 import { CLI_NAME } from '../version/release'
 import { readResolvedConfig } from './read-config'
-import { formatRepositoryValues, isRepositoryValue, REPOSITORY_VALUE, repositoryValuesOf } from './repository-values'
+import { readRepositoryFacts } from './repository-facts'
+import {
+  commandFindings,
+  formatRepositoryValues,
+  isRepositoryValue,
+  isRepositoryValueSet,
+  REPOSITORY_VALUE,
+  repositoryValuesOf,
+  valueFindings,
+} from './repository-values'
 
-const USAGE = `Usage: ${CLI_NAME} config [${Object.values(REPOSITORY_VALUE).join(' | ')}]`
+export const CONFIG_EXIT = { printed: 0, failed: 1, usage: 2, unset: 3 } as const
 
-const USAGE_EXIT = 2
+const USAGE = `Usage: ${CLI_NAME} config [${Object.values(REPOSITORY_VALUE).join(' | ')}]
+Exit codes: ${CONFIG_EXIT.printed} printed, ${CONFIG_EXIT.failed} failed, ${CONFIG_EXIT.usage} usage, ${CONFIG_EXIT.unset} the named value is not set (its finding goes to stderr).`
 
 export type ConfigOutput = { log: (line: string) => void; error: (line: string) => void }
 
 /**
  * Prints the values this repository decides, as the config sets them or detection finds them: all of them, or
- * the one `key` names. Notes about values the repository did not decide go to `error`, so a key's output stays
- * the bare value.
+ * the one `key` names. Notes about values the repository did not decide, and a finding for each command or lock
+ * file that is missing or contradicts the repository (`commandFindings`), go to `error`, so a key's output stays
+ * the bare value; for a `key`, only the finding about that key (the notes for `baseBranch`). A `key` whose value
+ * is unset prints nothing and returns `CONFIG_EXIT.unset`; its missing finding says where to set it.
  */
 export const printRepositoryValues = (args: string[], roots: string[], home: string, output: ConfigOutput): number => {
   const [key, extra] = args
   if (extra !== undefined) {
     output.error(USAGE)
-    return USAGE_EXIT
+    return CONFIG_EXIT.usage
   }
   if (key !== undefined && !isRepositoryValue(key)) {
     output.error(`Unknown key: ${key}\n${USAGE}`)
-    return USAGE_EXIT
+    return CONFIG_EXIT.usage
   }
-  const { config, notes } = readResolvedConfig(roots, home)
-  for (const note of notes) output.error(note)
+  const facts = readRepositoryFacts(roots[0])
+  const { config, notes } = readResolvedConfig(roots, home, facts)
   const values = repositoryValuesOf(config)
-  const lines = key === undefined ? formatRepositoryValues(values) : [values[key]]
-  for (const line of lines) output.log(line)
-  return 0
+  if (key === undefined) {
+    for (const note of [...notes, ...commandFindings(config, facts)]) output.error(note)
+    for (const line of formatRepositoryValues(values)) output.log(line)
+    return CONFIG_EXIT.printed
+  }
+  const diagnostics = key === REPOSITORY_VALUE.baseBranch ? notes : valueFindings(config, facts, key)
+  for (const line of diagnostics) output.error(line)
+  if (!isRepositoryValueSet(config, key)) return CONFIG_EXIT.unset
+  output.log(values[key])
+  return CONFIG_EXIT.printed
 }
 
 export const run = (args: string[]): number => {
@@ -40,6 +59,6 @@ export const run = (args: string[]): number => {
     return printRepositoryValues(args, [worktreeRoot(cwd), mainCheckout(cwd)], homedir(), output)
   } catch (error) {
     output.error(`${CLI_NAME} config failed: ${error instanceof Error ? error.message : String(error)}`)
-    return 1
+    return CONFIG_EXIT.failed
   }
 }