jackherd 1.12.7 → 1.14.0

package/src/check/roots.ts

@@ -1,26 +1,63 @@
 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'
 
 /**
- * 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.
+ * Whether a parsed `WORKSPACE_MANIFEST` gathers workspaces. Such a root only holds packages: a test run from
+ * there walks the whole monorepo.
  */
-export const packageRootOf = (path: string, hasPackageJson: (dir: string) => boolean): string | null => {
+export const isWorkspaceManifest = (manifest: unknown): boolean =>
+  typeof manifest === 'object' && manifest !== null && Object.hasOwn(manifest, 'workspaces')
+
+/**
+ * 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, 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}/`)
+
+/**
+ * The deepest of `roots` above `path`; null when none is. Without a detected stack, a file no root marker holds
+ * belongs to the nearest `check.roots` entry, with the repository root `.` among them.
+ */
+export const nearestRootOf = (path: string, roots: readonly string[]): string | null =>
+  roots
+    .filter((root) => isUnder(path, root))
+    .reduce<string | null>((nearest, root) => (nearest === null || root.length > nearest.length ? root : nearest), null)
+
 /**
  * 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 +66,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)
 
@@ -20,6 +20,9 @@ const glob = nonEmpty.refine((value) => !/[{}[\]]/.test(value), 'Braces and brac
 
 const globs = z.array(glob).min(1)
 
+/** A directory from the repository root as the check compares it: `./crates/core/` reads as `crates/core`. */
+const directory = nonEmpty.transform((value) => value.replace(/^(\.\/)+/, '').replace(/\/+$/, '') || '.')
+
 /** Staged output that belongs to a build, never to a commit. */
 export const DEFAULT_BUILD_ARTIFACT_GLOBS = [
   '**/tsup.config.bundled_*',
@@ -40,6 +43,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 +75,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([]),
@@ -83,6 +91,15 @@ export const checkConfigSchema = z.strictObject({
   skillBudgets: skillBudgets.optional(),
   /** Also run tests in directories that hold test files but belong to no package. */
   looseTests: z.boolean().default(false),
+  /**
+   * Package roots, as directories from the repository root, read only where no stack is detected: a changed file
+   * belongs to the nearest one above it, else to the repository root `.`.
+   */
+  roots: z.array(directory).min(1).optional(),
+  /** The files a test covers; replaces the stack's pattern, or the rule of thumb where no stack is detected. */
+  sourceFiles: globs.optional(),
+  /** The test files; replaces the stack's pattern, or the rule of thumb where no stack is detected. */
+  testFiles: globs.optional(),
 })
 
 export type CheckConfig = z.infer<typeof checkConfigSchema>

package/src/check/settings.ts

@@ -1,9 +1,16 @@
 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'
+import type { NoStackFallback, PackageCommands } from './plan'
 import { type CheckConfig, checkConfigSchema } from './schema'
 
 export const CONFIG_PATH = PROJECT_CONFIG_PATH
@@ -16,13 +23,25 @@ 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)
+
+/** Without any detected stack: `check.roots` and the repository root `.` as fallback roots, `commands.lint` from the root. */
+export const noStackFallbackOf = ({ stack, check, commands }: CheckSettings): NoStackFallback | null =>
+  stack.kind === 'none' ? { roots: [...(check.roots ?? []), '.'], lintCommand: commands.lint } : 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
@@ -32,13 +51,15 @@ const baseBranchSchema = jackherdConfigSchema.shape.baseBranch
 export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckSettings => {
   const detected = withDetected(z.record(z.string(), z.unknown()).parse(raw), facts)
   const object = z.record(z.string(), z.unknown()).parse(detected.raw)
-  const { test, typecheck } = commandsSchema.parse(object.commands)
+  const { test, typecheck, lint } = commandsSchema.parse(object.commands)
   return {
-    commands: { test, typecheck },
+    commands: { test, typecheck, lint },
     check: checkConfigSchema.parse(object.check ?? {}),
     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,13 +20,15 @@ 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.
+  // Any language: a pointer in § 0 and a section in events.md for `plan missing`.
+  '.claude/skills/orchestrate/SKILL.md': 7929,
   '.claude/skills/orchestrate/references/acceptance.md': 200,
   '.claude/skills/orchestrate/references/close-lane.md': 250,
   '.claude/skills/orchestrate/references/coordinator-handover.md': 551,
   '.claude/skills/orchestrate/references/draft-review.md': 300,
   // P33: a source entry the user must read or decide becomes a row of what waits on them, and when it closes.
-  '.claude/skills/orchestrate/references/events.md': 1110,
+  '.claude/skills/orchestrate/references/events.md': 1166,
   '.claude/skills/orchestrate/references/herd.md': 299,
   '.claude/skills/orchestrate/references/lane-handover.md': 280,
   '.claude/skills/orchestrate/references/lane-session.md': 280,
@@ -39,10 +41,11 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/pre-commit/SKILL.md': 1003,
   '.claude/skills/review/SKILL.md': 319,
   '.claude/skills/security-audit/SKILL.md': 519,
-  '.claude/skills/start/SKILL.md': 607,
+  // Any language: step 3 points to proposing the missing commands from the CI; the proposal itself is a reference.
+  '.claude/skills/start/SKILL.md': 630,
   '.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': 8729,
   '.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
   }
 }