jackherd 1.9.0 → 1.11.0

package/kit/hooks/hooks/git-guard/decision.ts

@@ -1,32 +1,22 @@
 import { posix } from 'node:path'
-import { commandTextRunnerIndex, searchableText } from '../shared/command-text-runners'
 import {
   ASSIGNMENT,
   inlineScript,
   isOption,
   isProgramPosition,
   programName,
-  readsScriptFromInput,
   ruleStart,
-  runsInterpreterProgram,
 } from '../shared/program-position'
 import {
   expandingHereDocumentAdvice,
-  isExpanded,
   parseShell,
   ShellParseError,
   type SimpleCommand,
   UNREADABLE_ADVICE,
   type Word,
 } from '../shared/shell'
-import {
-  definesShellAlias,
-  mayRunDefinedFunction,
-  NO_DEFINITIONS,
-  type ShellDefinitions,
-  shellDefinitionAt,
-  shellDefinitionHint,
-} from '../shared/shell-aliases'
+import { NO_DEFINITIONS, type ShellDefinitions, shellDefinitionAt, shellDefinitionHint } from '../shared/shell-aliases'
+import { resolvePlainXargs } from '../shared/xargs-program'
 import { type PushCall, type PushContext, pushTargetDenial } from './push-target'
 
 export type GitGuardDecision = { kind: 'pass' } | { kind: 'deny'; reason: string }
@@ -83,8 +73,11 @@ type SplitArguments = { options: string[]; operands: string[] }
 
 const PASS: GitGuardDecision = { kind: 'pass' }
 
-/** The programs whose alias or function the guard refuses: one that runs git or gh hides it from the rules (D42). */
-const DEFINITION_PROGRAMS = ['git', 'gh']
+/**
+ * The programs the guard watches: an alias or function that runs one is refused, since it hides the call from the
+ * rules (D42), and `xargs` stays opaque in front of one (D77).
+ */
+const GUARDED_PROGRAMS = ['git', 'gh']
 
 const FORCE_PUSH =
   'A force push is refused. Use `--force-with-lease` instead, and only after the user agreed to rewrite the remote branch.'
@@ -99,8 +92,6 @@ const BRACE_HINT =
   'Refused: an option of this git call is written as a brace expansion, so neither the permission rules nor this hook can tell what git receives. Write the option plainly.'
 const INLINE_EXPANSION_HINT =
   'Refused: `eval` or `sh -c` runs a script held in a variable or a substitution, so neither the permission rules nor this hook can read it. Write the commands out.'
-const EXPANDED_FUNCTION_HINT =
-  'Refused: the program is expanded from a variable or a substitution, and it may name a shell function that runs git or gh, which hides the command from the permission rules. Run the command written out instead.'
 const ALIAS_HINT =
   'Refused: `-c alias.…` defines a git alias inline, which hides the verb from the permission rules. Run the git command it stands for directly.'
 
@@ -188,7 +179,6 @@ const BRANCH_MOVING_VERBS = new Set([
   'update-ref',
   'worktree',
 ])
-const PROTECTED_MENTION = new RegExp(`\\bgit\\b[\\s\\S]*\\b(${Object.values(PROTECTED_VERB).join('|')})\\b`)
 
 const isProtectedVerb = (value: string): value is ProtectedVerb =>
   (Object.values(PROTECTED_VERB) as string[]).includes(value)
@@ -354,41 +344,23 @@ const judgeExpandedProgram = (words: SimpleCommand): GitGuardDecision => {
 const firstDenial = (decisions: GitGuardDecision[]): GitGuardDecision =>
   decisions.find((decision) => decision.kind === 'deny') ?? PASS
 
-const denyIfMentionsProtectedVerb = (script: string, reason: string): GitGuardDecision => {
-  const verb = script.match(PROTECTED_MENTION)?.[1]
-  return verb ? deny(`Refused: ${reason}, and it mentions \`git ${verb}\`. ${plainInstead(verb)}`) : PASS
-}
-
 const judgeDefinition = (
   words: SimpleCommand,
   index: number,
   definitions: () => ShellDefinitions,
 ): GitGuardDecision => {
-  const definition = shellDefinitionAt(words, index, definitions, DEFINITION_PROGRAMS)
+  const definition = shellDefinitionAt(words, index, definitions, GUARDED_PROGRAMS)
   return definition ? deny(`Refused: ${shellDefinitionHint(definition)}`) : PASS
 }
 
-/**
- * A program that runs command text it is given (`watch '…'`, sed's `e`) is refused when that text names a protected
- * verb; when the text is itself an expansion, the searchable script is searched instead.
- */
-const judgeCommandText = (words: SimpleCommand, searchable: string): GitGuardDecision => {
-  const runner = commandTextRunnerIndex(words)
-  if (runner === -1) return PASS
-  const given = words.slice(runner + 1)
-  const text = given.some(({ value }) => isExpanded(value)) ? searchable : given.map(({ value }) => value).join(' ')
-  return denyIfMentionsProtectedVerb(text, 'a program runs command text it is given, which no rule inspects')
-}
-
 const judgeWord = (
   words: SimpleCommand,
   index: number,
   context: ScriptContext,
   definitions: () => ShellDefinitions,
-  searchable: string,
 ): GitGuardDecision => {
   const script = inlineScript(words, index)
-  if (script !== undefined) return judgeScript(script, SCRIPT_CONTEXT.nested, definitions, searchable)
+  if (script !== undefined) return judgeScript(script, SCRIPT_CONTEXT.nested, definitions)
   if (!isGit(words[index])) return judgeDefinition(words, index, definitions)
   const invocation = readInvocation(words, index)
   return invocation ? judgeInvocation(invocation, gitPosition(words, index, context)) : PASS
@@ -398,83 +370,58 @@ const judgeWord = (
 const judgeInlineExpansion = (words: SimpleCommand, context: ScriptContext): GitGuardDecision =>
   context === SCRIPT_CONTEXT.nested && runsExpandedProgram(words) ? deny(INLINE_EXPANSION_HINT) : PASS
 
-const judgeExpandedFunction = (
-  words: SimpleCommand,
-  definitions: () => ShellDefinitions,
-  searchable: string,
-): GitGuardDecision =>
-  mayRunDefinedFunction(words, definitions, DEFINITION_PROGRAMS, searchable) ? deny(EXPANDED_FUNCTION_HINT) : PASS
-
 const judgeCommand = (
   words: SimpleCommand,
   context: ScriptContext,
   definitions: () => ShellDefinitions,
-  searchable: string,
 ): GitGuardDecision =>
   firstDenial([
-    ...words.map((_word, index) => judgeWord(words, index, context, definitions, searchable)),
+    ...words.map((_word, index) => judgeWord(words, index, context, definitions)),
     judgeInlineExpansion(words, context),
     judgeExpandedProgram(words),
-    judgeCommandText(words, searchable),
-    judgeExpandedFunction(words, definitions, searchable),
   ])
 
+/** The first protected verb a parsed git call of the script runs, where a set git variable may reach it. */
+const protectedVerbRun = (commands: SimpleCommand[]): ProtectedVerb | undefined =>
+  commands
+    .flatMap((words) =>
+      words.flatMap((word, index) =>
+        isGit(word) && isProgramPosition(words, index) ? [readInvocation(words, index)?.verb.value ?? ''] : [],
+      ),
+    )
+    .find(isProtectedVerb)
+
 /**
- * What no single command shows. Each check reads the whole script, so a harmless git call beside
- * a shell that reads stdin, a set git variable or an expanded program is refused too: an accepted
- * over-refusal for rare shapes.
+ * A `HUSKY`, `LEFTHOOK`, `SKIP` or `GIT_*` variable set anywhere in the script may reach a later git call, not only
+ * the one it precedes: refused when a parsed git call of the script runs a protected verb. Text that only names the
+ * verb is no call (D108).
  */
-const judgeScriptWide = (script: string, commands: SimpleCommand[]): GitGuardDecision => {
-  if (commands.some(readsScriptFromInput)) {
-    return denyIfMentionsProtectedVerb(script, 'a shell reads its script from input here, which no rule inspects')
-  }
-  if (commands.some(runsInterpreterProgram)) {
-    return denyIfMentionsProtectedVerb(
-      script,
-      'an interpreter runs program text given inline or on its input, which no rule inspects',
-    )
-  }
-  if (commands.some(definesShellAlias)) {
-    return denyIfMentionsProtectedVerb(
-      script,
-      'the script defines a shell alias, which hides its command from the rules',
-    )
-  }
-  if (commands.some(setsGitVariable)) {
-    return denyIfMentionsProtectedVerb(
-      script,
-      'a `HUSKY`, `LEFTHOOK`, `SKIP` or `GIT_*` variable is set, which changes the git calls',
-    )
-  }
-  if (commands.some(runsExpandedProgram)) {
-    return denyIfMentionsProtectedVerb(
-      script,
-      'a program is expanded from a variable or a substitution and could be git',
-    )
-  }
-  return PASS
+const judgeGitVariables = (commands: SimpleCommand[]): GitGuardDecision => {
+  const verb = commands.some(setsGitVariable) ? protectedVerbRun(commands) : undefined
+  return verb
+    ? deny(
+        `Refused: a \`HUSKY\`, \`LEFTHOOK\`, \`SKIP\` or \`GIT_*\` variable is set, which changes the git calls, and the script runs \`git ${verb}\`. ${plainInstead(verb)}`,
+      )
+    : PASS
 }
 
-/** `whole` is the text the mention search reads at the outer level: a nested script's variables are set there. */
+/**
+ * Only the parsed script counts (D108): text handed to an interpreter, a shell's input, a program's command text
+ * (`watch '…'`, sed's `e`) and a definition in the script are not searched.
+ */
 const judgeParsed = (
   commands: SimpleCommand[],
   context: ScriptContext,
   definitions: () => ShellDefinitions,
-  whole: string,
-): GitGuardDecision => {
-  const text = searchableText(whole, commands)
-  return firstDenial([
-    ...commands.map((words) => judgeCommand(words, context, definitions, text)),
-    judgeScriptWide(text, commands),
-  ])
-}
+): GitGuardDecision =>
+  firstDenial([...commands.map((words) => judgeCommand(words, context, definitions)), judgeGitVariables(commands)])
 
-const judgeScript = (
-  script: string,
-  context: ScriptContext,
-  definitions: () => ShellDefinitions,
-  whole: string,
-): GitGuardDecision => judgeParsed(parseShell(script), context, definitions, whole)
+/** The script's commands, with `xargs` and a plain program read as that program's call (D77, D108). */
+const parseScript = (script: string): SimpleCommand[] =>
+  parseShell(script).map((words) => resolvePlainXargs(words, GUARDED_PROGRAMS))
+
+const judgeScript = (script: string, context: ScriptContext, definitions: () => ShellDefinitions): GitGuardDecision =>
+  judgeParsed(parseScript(script), context, definitions)
 
 /** A `cd` or a git call that switches, renames or reconfigures the branch: `HEAD` at a later push is another one. */
 const movesHead = (words: SimpleCommand): boolean =>
@@ -518,8 +465,8 @@ const withHereDocumentAdvice = (decision: GitGuardDecision, script: string): Git
 
 const judgeTop = (command: string, push: PushContext, definitions: () => ShellDefinitions): GitGuardDecision => {
   try {
-    const commands = parseShell(command)
-    const decision = judgeParsed(commands, SCRIPT_CONTEXT.top, definitions, command)
+    const commands = parseScript(command)
+    const decision = judgeParsed(commands, SCRIPT_CONTEXT.top, definitions)
     return decision.kind === 'deny' ? decision : judgePushes(commands, push)
   } catch (error) {
     if (error instanceof ShellParseError) return denyUnreadable(error)
@@ -530,11 +477,12 @@ const judgeTop = (command: string, push: PushContext, definitions: () => ShellDe
 /**
  * Decides on a Bash command before it runs. Denies a protected git verb that a permission rule
  * written as `git <verb> …` would not match (options or `GIT_*` variables before the verb, a
- * wrapper, a path to git, a quoted verb, a line continuation, `sh -c`, `eval`, a script piped into
- * a shell, an interpreter's program text), and denies a force push, a skipped hook and a hard reset in any
- * form. Denies a push that updates the base branch, or whose target it cannot tell, every script it cannot read,
- * and a shell alias or function (`definitions`, read only for a word that is no known program) that runs git or gh.
- * Everything else passes on to the project's own permission rules.
+ * wrapper, a path to git, a quoted verb, a line continuation, `sh -c`, `eval`), and denies a force push, a skipped
+ * hook and a hard reset in any form the parse shows. Denies a push that updates the base branch, or whose target it
+ * cannot tell, every script it cannot read, and a shell alias or function (`definitions`, read only for a word that
+ * is no known program) that runs git or gh. Only the parsed script counts (D108): an interpreter's program text, a
+ * script piped into a shell and a program's command text are not searched. Everything else passes on to the
+ * project's own permission rules.
  */
 export const decideBashCommand = (
   command: string,

package/kit/hooks/hooks/merge-guard/always-ask.ts

@@ -0,0 +1,63 @@
+/** Workflows and the actions they run. */
+const WORKFLOW_PATHS: readonly string[] = ['.github/**']
+
+/** Migrations, in a `migrations` folder or as SQL in a `drizzle` folder. */
+export const MIGRATION_PATHS: readonly string[] = ['**/migrations/**', '**/drizzle/*.sql']
+
+/** Env files: `.env`, `.env.local`, `prod.env`, `.dev.vars`. */
+export const ENV_PATHS: readonly string[] = ['**/.env*', '**/*.env', '**/.dev.vars']
+
+/**
+ * The guards and what runs before them: the project's hooks and settings, the jackherd config, git hooks and
+ * `bunfig.toml`, whose `preload` runs before every hook (they start in the project root, so only the root one).
+ */
+const GUARD_PATHS: readonly string[] = [
+  '.claude/hooks/**',
+  '.claude/settings*.json',
+  '.jackherd/**',
+  '.husky/**',
+  'lefthook.yml',
+  'bunfig.toml',
+]
+
+/**
+ * The paths a standing approval never covers: workflows, migrations, env files, and the guards themselves, so a pull
+ * request cannot loosen the guard that merges it. Skills, agents and rules stay covered.
+ */
+export const STANDING_ALWAYS_ASK: readonly string[] = [...WORKFLOW_PATHS, ...MIGRATION_PATHS, ...ENV_PATHS, ...GUARD_PATHS]
+
+/**
+ * The paths that always ask, whatever the project adds (`guard.alwaysAsk`): workflows, migrations, env files, the
+ * agent setup and its instructions, the jackherd config, `bunfig.toml`, git hooks, lockfiles, registry config and code
+ * owners. A `merge.withoutChecks` pattern never opens them, and the watcher never starts parallel work on them by itself.
+ */
+export const ALWAYS_ASK_PATHS: readonly string[] = [
+  ...WORKFLOW_PATHS,
+  ...MIGRATION_PATHS,
+  ...ENV_PATHS,
+  '.claude/**',
+  '.jackherd/**',
+  'bunfig.toml',
+  '**/CLAUDE.md',
+  '**/AGENTS.md',
+  '.agents/**',
+  '.mcp.json',
+  '.husky/**',
+  'lefthook.yml',
+  '**/bun.lock',
+  '**/bun.lockb',
+  '**/package-lock.json',
+  '**/pnpm-lock.yaml',
+  '**/yarn.lock',
+  '**/.npmrc',
+  '**/CODEOWNERS',
+]
+
+/**
+ * The files that lie on one of the patterns, compared in lower case: on a case-insensitive file system git writes
+ * `.GitHub/x` into the existing `.github/`, so a pattern must not miss it. Folding only ever adds a question.
+ */
+export const alwaysAskingFiles = (files: readonly string[], patterns: readonly string[]): string[] => {
+  const globs = patterns.map((pattern) => new Bun.Glob(pattern.toLowerCase()))
+  return files.filter((file) => globs.some((glob) => glob.match(file.toLowerCase())))
+}

package/kit/hooks/hooks/merge-guard/{plan-approval-settings.ts → board-settings.ts}

@@ -1,15 +1,14 @@
 import { baseBranchOf } from '../shared/base-branch'
 import { BOARD_WORDS, type BoardLanguage } from '../shared/board-lanes'
-import { isRecord, parseJsonObject } from '../shared/json'
+import { isRecord } from '../shared/json'
 import { isRepositoryDirectory } from '../shared/repository-directory'
 import { isControlCharacter } from './plain-path'
 
 /**
- * What plan approval needs: the paths that always ask (the defaults plus the project's own) and where plans, boards
- * and lanes live. `null` from `readPlanApprovalSettings` means plan approval is off and every merge asks.
+ * Where plans, boards and lanes live, the base branch, and the checks a standing approval waits for. `null` from
+ * `boardSettingsOf` means the standing approval is off and every merge asks.
  */
-export type PlanApprovalSettings = {
-  exceptPaths: readonly string[]
+export type BoardSettings = {
   planLanguage: BoardLanguage
   planDirectory: string
   board: { pattern: string; file: string }
@@ -19,46 +18,6 @@ export type PlanApprovalSettings = {
   requiredChecks: readonly string[] | undefined
 }
 
-/**
- * The paths that always ask, whatever the project adds: workflows, migrations, env files, the agent setup and its
- * instructions, the jackherd config, `bunfig.toml`, whose `preload` runs before every hook (they start in the project
- * root, so only the root one), git hooks, lockfiles, registry config and code owners.
- */
-export const PLAN_APPROVAL_ALWAYS_ASK: readonly string[] = [
-  '.github/**',
-  '**/migrations/**',
-  '**/.env*',
-  '.claude/**',
-  '.jackherd/**',
-  'bunfig.toml',
-  '**/CLAUDE.md',
-  '**/AGENTS.md',
-  '.agents/**',
-  '.mcp.json',
-  '.husky/**',
-  'lefthook.yml',
-  '**/bun.lock',
-  '**/bun.lockb',
-  '**/package-lock.json',
-  '**/pnpm-lock.yaml',
-  '**/yarn.lock',
-  '**/.npmrc',
-  '**/CODEOWNERS',
-]
-
-/** Where a project keeps its jackherd config, as a path inside the repository. */
-export const PROJECT_CONFIG = '.jackherd/config.json'
-
-/**
- * The same rules as `alwaysAskPattern` in the config schema: path words with wildcards, relative, no empty, `.` or
- * `..` segment (GitHub lists no file with one, so such a pattern would never ask). Broad on purpose (`.github/**`,
- * `**`): a pattern here only ever adds a question.
- */
-const isAlwaysAskPattern = (value: unknown): value is string =>
-  typeof value === 'string' &&
-  /^[A-Za-z0-9_.*/-]+$/.test(value) &&
-  value.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
-
 const MAX_CHECK_NAME = 200
 const BOARD_PATTERN = /^(?![-.])[A-Za-z0-9._*?-]+$/
 const BOARD_FILE = /^(?![-.])[A-Za-z0-9._-]+\.md$/
@@ -84,8 +43,6 @@ const isSectionOrAbsent = (config: Record<string, unknown>, key: string): boolea
 const sectionAt = (config: Record<string, unknown>, key: string): Record<string, unknown> =>
   isRecord(config[key]) ? config[key] : {}
 
-const isPathList = (value: unknown): value is string[] => Array.isArray(value) && value.every(isAlwaysAskPattern)
-
 /** The same rules as `checkName` in the config schema: a name with a visible character, no control character. */
 const isCheckName = (value: unknown): value is string =>
   typeof value === 'string' &&
@@ -100,13 +57,17 @@ const sectionsAreObjects = (config: Record<string, unknown>): boolean =>
   isSectionOrAbsent(sectionAt(config, 'guard'), 'planApproval') &&
   isSectionOrAbsent(config, 'board')
 
-/** Every value plan approval reads, with its default where absent; `undefined` stands for a present but invalid one. */
-const planApprovalValues = (config: Record<string, unknown>) => {
+/** `guard.requiredChecks`, else where configs before 1.10.0 kept it, `guard.planApproval.requiredChecks`. */
+const requiredChecksOf = (guard: Record<string, unknown>) =>
+  'requiredChecks' in guard
+    ? optionalValue(guard, 'requiredChecks', isCheckList)
+    : optionalValue(sectionAt(guard, 'planApproval'), 'requiredChecks', isCheckList)
+
+/** Every value the standing approval reads, with its default where absent; `undefined` stands for a present but invalid one. */
+const boardValues = (config: Record<string, unknown>) => {
   const board = sectionAt(config, 'board')
-  const planApproval = sectionAt(sectionAt(config, 'guard'), 'planApproval')
   return {
-    exceptPaths: valueOr(planApproval, 'exceptPaths', isPathList, []),
-    requiredChecks: optionalValue(planApproval, 'requiredChecks', isCheckList),
+    requiredChecks: requiredChecksOf(sectionAt(config, 'guard')),
     planLanguage: valueOr(config, 'planLanguage', isPlanLanguage, 'en'),
     planDirectory: valueOr(config, 'planDirectory', isRepositoryDirectory, 'docs/plans'),
     pattern: valueOr(board, 'pattern', matches(BOARD_PATTERN), 'board-*'),
@@ -116,27 +77,20 @@ const planApprovalValues = (config: Record<string, unknown>) => {
   }
 }
 
-type Values = ReturnType<typeof planApprovalValues>
+type Values = ReturnType<typeof boardValues>
 type ValidValues = { [Key in keyof Values]: Exclude<Values[Key], undefined> }
 
 const allValid = (values: Values): values is ValidValues => Object.values(values).every((value) => value !== undefined)
 
 /**
- * The plan approval settings of the project's `.jackherd/config.json` as the base commit holds it (`null`: it holds
- * none). Unlike the other guard settings, a missing config, one that is no JSON object, or any invalid value they read
- * turns plan approval off (`null`), so neither a mistyped project path nor a home config can shrink the list silently.
- * The project's paths add to `PLAN_APPROVAL_ALWAYS_ASK`.
+ * The board settings of the project's `.jackherd/config.json` (`null`: none could be read). Unlike the other guard
+ * settings, a config that is no JSON object or any invalid value it reads turns the standing approval off (`null`), so
+ * a mistyped path cannot point it at another board, nor a mistyped check name drop the checks it waits for.
  */
-export const planApprovalSettingsOf = (text: string | null): PlanApprovalSettings | null => {
-  const config = text === null ? null : (parseJsonObject(text) ?? null)
+export const boardSettingsOf = (config: Record<string, unknown> | null): BoardSettings | null => {
   if (config === null || !sectionsAreObjects(config)) return null
-  const values = planApprovalValues(config)
+  const values = boardValues(config)
   if (!allValid(values)) return null
-  const { exceptPaths, requiredChecks, pattern, file, ...where } = values
-  return {
-    exceptPaths: [...PLAN_APPROVAL_ALWAYS_ASK, ...exceptPaths],
-    board: { pattern, file },
-    ...where,
-    requiredChecks: requiredChecks.value,
-  }
+  const { requiredChecks, pattern, file, ...where } = values
+  return { ...where, board: { pattern, file }, requiredChecks: requiredChecks.value }
 }

package/kit/hooks/hooks/merge-guard/check-free.ts

@@ -4,6 +4,7 @@
  * "no", so the guard asks as before.
  */
 
+import { alwaysAskingFiles } from './always-ask'
 import { runGh } from './gh'
 import { isPlainPath } from './plain-path'
 import type { RepositoryFacts } from './pull-request'
@@ -46,6 +47,25 @@ export const allFilesMatch = (files: readonly string[], patterns: readonly strin
   return files.every((file) => isPlainPath(file) && globs.some((glob) => glob.match(file)))
 }
 
+/** Files that never merge unchecked: a manifest can drop `"private"` or add a dependency, a changelog can cut a release. */
+const NEVER_CHECK_FREE = ['package.json', 'changelog.md']
+
+const fileName = (file: string): string => file.slice(file.lastIndexOf('/') + 1).toLowerCase()
+
+/**
+ * Whether a pull request merges without a question and without checks: every file matches `patterns`
+ * (`allFilesMatch`), none lies on a path that always asks (`alwaysAsk`, the defaults plus the project's own), and none
+ * is a `package.json` or a changelog. A pattern that reaches such a path only ever adds the question back.
+ */
+export const isCheckFree = (
+  files: readonly string[],
+  patterns: readonly string[],
+  alwaysAsk: readonly string[],
+): boolean => {
+  if (!allFilesMatch(files, patterns)) return false
+  return files.every((file) => !NEVER_CHECK_FREE.includes(fileName(file))) && alwaysAskingFiles(files, alwaysAsk).length === 0
+}
+
 /**
  * Asks `gh api` for the files of pull request <number> of `facts.repository`, named in full; any failure answers nothing.
  */