jackherd 1.7.0 → 1.8.0

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

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { baseBranchOf } from '../shared/base-branch'
+import { mainCheckoutOf } from '../shared/checkout'
+import { commandOutput } from '../shared/command'
+import { parseJsonObject } from '../shared/json'
+import type { PushContext } from './push-target'
+
+const CONFIG_PATH = join('.jackherd', 'config.json')
+
+/** `%(push)` is `refs/remotes/<remote>/<branch>`; the branch is what follows the remote's own prefix. */
+export const pushBranchOf = (remote: string, pushRef: string): string | undefined => {
+  const prefix = `refs/remotes/${remote}/`
+  return pushRef.startsWith(prefix) ? pushRef.slice(prefix.length) : undefined
+}
+
+const git = (cwd: string, ...args: string[]): string => commandOutput(['git', ...args], cwd)
+
+/**
+ * The checkout's `.jackherd/config.json`: `{}` when there is none, `null` when it cannot be read or holds no JSON
+ * object, so a broken config refuses the push instead of guarding `main` while the project means another branch.
+ */
+const projectConfigOf = (checkout: string): Record<string, unknown> | null => {
+  const path = join(checkout, CONFIG_PATH)
+  if (!existsSync(path)) return {}
+  try {
+    return parseJsonObject(readFileSync(path, 'utf8')) ?? null
+  } catch {
+    return null
+  }
+}
+
+const currentBranch = (cwd: string): string | undefined => {
+  try {
+    return git(cwd, 'symbolic-ref', '--quiet', '--short', 'HEAD')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The current branch and the branch its push goes to, as git's own push settings decide (`push.default`,
+ * `remote.pushDefault`, the upstream); undefined on a detached HEAD or a push ref git names oddly.
+ */
+const defaultPushBranches = (cwd: string): string[] | undefined => {
+  const branch = currentBranch(cwd)
+  if (branch === undefined) return undefined
+  const [remote = '', pushRef = ''] = git(
+    cwd,
+    'for-each-ref',
+    '--format=%(push:remotename)%00%(push)',
+    `refs/heads/${branch}`,
+  ).split('\0')
+  if (pushRef === '') return [branch]
+  const pushBranch = pushBranchOf(remote, pushRef)
+  return pushBranch === undefined ? undefined : [branch, pushBranch]
+}
+
+/** The repository at `cwd`: its git state, and the base branch from the main checkout's `.jackherd/config.json`. */
+export const repositoryPushContext = (cwd: string): PushContext => ({
+  baseBranch: () => baseBranchOf(projectConfigOf(mainCheckoutOf(cwd))),
+  defaultPushBranches: () => defaultPushBranches(cwd),
+})

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

@@ -5,6 +5,7 @@
  */
 
 import { runGh } from './gh'
+import { isPlainPath } from './plain-path'
 import type { RepositoryFacts } from './pull-request'
 
 /** What GitHub lists per file: the name, and the old name of a renamed file. */
@@ -13,19 +14,6 @@ const FILE_ENTRY_QUERY = '.[] | [.filename, .previous_filename] | @json'
 /** GitHub lists at most this many files of a pull request and says nothing when it stops there. */
 export const MAX_LISTED_FILES = 3000
 
-const isControlCharacter = (character: string): boolean => {
-  const code = character.charCodeAt(0)
-  return code < 0x20 || code === 0x7f
-}
-
-/** A repository path as GitHub lists it: relative, no empty, `.` or `..` segment, no backslash, no control character. */
-const isPlainPath = (file: string): boolean =>
-  file !== '' &&
-  !file.startsWith('/') &&
-  !file.includes('\\') &&
-  ![...file].some(isControlCharacter) &&
-  !file.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
-
 const isNameOrNull = (value: unknown): value is string | null => value === null || typeof value === 'string'
 
 /**

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

@@ -1,27 +1,68 @@
+import { commandTextRunnerIndex, searchableText } from '../shared/command-text-runners'
+import { FULL_COMMIT } from '../shared/commit'
 import {
   inlineScript,
   isOption,
   isProgramPosition,
   isShell,
   programName,
+  runsInterpreterProgram,
 } from '../shared/program-position'
-import { parseShell, ShellParseError, type SimpleCommand, type Word } from '../shared/shell'
+import {
+  expandingHereDocumentAdvice,
+  isExpanded,
+  parseShell,
+  ShellParseError,
+  type SimpleCommand,
+  UNREADABLE_ADVICE,
+  type Word,
+} from '../shared/shell'
+import {
+  definesShellAlias,
+  mayRunDefinedFunction,
+  NO_DEFINITIONS,
+  type ShellDefinitionHit,
+  type ShellDefinitions,
+  shellDefinitionAt,
+  shellDefinitionHint,
+} from '../shared/shell-aliases'
 
 export type MergeGuardDecision = { kind: 'pass' } | { kind: 'ask'; reason: string }
 
+/**
+ * A plain `gh pr merge <number>`, with the head commit it names in `--match-head-commit <sha>`, if any: GitHub then
+ * merges only that commit, so what was checked is what gets merged.
+ */
+export type PlainMerge = { pullRequest: number; headCommit: string | undefined }
+
+/** An approval that no longer covers the merge, and what the question should tell the user about it. */
+export type MergeNote = { note: string }
+
 export type GuardPolicy = {
   /** The guarded commands as words: a program and the plain words after it, such as `gh pr merge`. */
   commands: readonly string[]
   /**
-   * Whether the merge of this pull request may pass without a question: the user approved it, or every file of it
-   * matches `merge.withoutChecks`. Asked only for a plain `gh pr merge <number>`.
-   * A throw counts as not approved.
+   * Whether the merge of this pull request may pass without a question: the user approved its branch or the plan of
+   * its lane, or every file of it matches `merge.withoutChecks`. Asked only for a plain `gh pr merge <number>`.
+   * A throw counts as not approved; a note is not approved either, and the question carries it.
    */
-  isMergeApproved: (pullRequest: number) => boolean
+  isMergeApproved: (merge: PlainMerge) => boolean | MergeNote
+  /** The aliases and functions of the user's shell, read only when a word at a program position may be one; none by default. */
+  shellDefinitions?: () => ShellDefinitions
 }
 
-/** A guarded command the script runs or could run, and the pull request a merge names, when it names one plainly. */
-type Finding = { command: string; pullRequest: number | undefined }
+/**
+ * A guarded command the script runs or could run, and the pull request a merge names, when it names one plainly; or
+ * the shell alias or function that may run one (`definition`, whose name is then the `command`), or a program whose
+ * name is unknown (`note` says why it may run one).
+ */
+type Finding = { command: string; merge: PlainMerge | undefined; definition?: ShellDefinitionHit; note?: string }
+
+/** What the search looks for: the guarded commands, and the shell definitions that may stand for one of them. */
+type Search = { commands: readonly string[]; definitions: () => ShellDefinitions }
+
+/** The parts of a `gh api` call that decide whether it writes, and where. */
+type ApiCall = { method: Word | undefined; fields: boolean; override: boolean; endpoints: Word[] }
 
 /** The one command whose guard an approval can lift. Every other guarded command asks each time. */
 const MERGE_COMMAND = 'gh pr merge'
@@ -35,44 +76,59 @@ const OPTIONS_WITH_VALUE = new Set(['-R', '--repo', '--hostname'])
  */
 const APPROVABLE_FLAGS = new Set(['--squash', '-s', '--merge', '-m', '--rebase', '-r', '--delete-branch', '-d'])
 const PULL_REQUEST_NUMBER = /^[1-9]\d*$/
+const HEAD_COMMIT_FLAG = '--match-head-commit'
 const GLOB = /[*?[]/
 
-/** Programs that run text they are given or read from elsewhere, so the words may not stand at the program. */
-const OPAQUE_RUNNERS = new Set([
-  'xargs',
-  'find',
-  'trap',
-  'coproc',
-  'repeat',
-  'script',
-  'su',
-  'flock',
-  'ssh',
-  'parallel',
-  'ionice',
-  'chrt',
-  'taskset',
-  'strace',
-  'unbuffer',
-  'chroot',
-  'runuser',
-  'systemd-run',
-  'nsenter',
-  'unshare',
-  'firejail',
-  'pkexec',
-  'entr',
-  'watchexec',
-  'busybox',
-])
-
 const SOURCING = new Set(['source', '.'])
 
-/** Interpreters that run program text given on the command line, and the options that give it. */
-const INTERPRETERS = new Set(['python', 'python3', 'node', 'bun', 'deno', 'perl', 'ruby', 'php', 'lua'])
-const INLINE_PROGRAM_OPTIONS = new Set(['-c', '-e', '-E', '-p', '-pe', '--eval', '--command', '-r'])
 const INPUT_PATH = /^(\/dev\/stdin|\/dev\/fd\/|\/proc\/self\/fd\/)/
 
+/** `gh api` is guarded only for a write that merges, writes a file, starts or reruns a workflow or moves a ref (D43); every other call passes. */
+const API_COMMAND = 'gh api'
+const API_WORD = 'api'
+const READ_METHOD = 'GET'
+const API_METHOD_OPTIONS = new Set(['-X', '--method'])
+/** Options that add a request body, which makes the method POST unless one is named. */
+const API_BODY_OPTIONS = new Set(['-f', '-F', '--field', '--raw-field', '--input'])
+const API_OPTIONS_WITH_VALUE = new Set([
+  '-H',
+  '--header',
+  '-q',
+  '--jq',
+  '-t',
+  '--template',
+  '--hostname',
+  '--cache',
+  '-p',
+  '--preview',
+])
+/** A header that makes GitHub take another method than the request's own, so a GET may write. */
+const METHOD_OVERRIDE_HEADER = /^\s*x-http-method(-override)?\s*:/i
+const HEADER_OPTIONS = new Set(['-H', '--header'])
+/**
+ * Endpoints that merge a pull request or a branch, write a file (a commit), dispatch a workflow or repository event,
+ * rerun a workflow (a deploy), or create, move or delete a ref.
+ */
+const DANGEROUS_ENDPOINTS = [
+  /(^|\/)pulls\/[^/]+\/merge\/?$/,
+  /(^|\/)merges\/?$/,
+  /(^|\/)contents(\/|$)/,
+  /(^|\/)dispatches\/?$/,
+  /(^|\/)actions\/(runs|jobs)\/[^/]+\/(rerun|rerun-failed-jobs)\/?$/,
+  /(^|\/)git\/refs(\/|$)/,
+]
+/** What the fixed end of an endpoint after an expansion may be, when the expansion can stand for the rest of the path. */
+const DANGEROUS_ENDINGS = [
+  /(^|\/)merges?\/?$/,
+  /(^|\/)contents(\/|$)/,
+  /(^|\/)dispatches\/?$/,
+  /(^|\/)(rerun|rerun-failed-jobs)\/?$/,
+  /(^|\/)refs(\/|$)/,
+]
+const DANGEROUS_MENTION = /\b(merges?|contents|dispatches|rerun|refs)\b/
+const EXPANDED_FUNCTION_NOTE =
+  'The program is expanded from a variable or a substitution and may name a shell function that runs one of guard.commands in .jackherd/config.json, so the user confirms it.'
+
 const PASS: MergeGuardDecision = { kind: 'pass' }
 
 /**
@@ -109,30 +165,152 @@ const matchesFrom = (operands: Word[], expected: string[]): boolean => {
   return operand.value === expected[0] && matchesFrom(rest, expected.slice(1))
 }
 
-/** The number of `gh pr merge <number>` in its plain form: literal words only, merge-method and delete-branch flags. */
-const plainPullRequest = (words: SimpleCommand, expected: string[]): number | undefined => {
+/** The operands without one `--match-head-commit <full sha>`, and that sha; undefined for any other use of the flag. */
+const withoutHeadCommit = (operands: string[]): { rest: string[]; headCommit: string | undefined } | undefined => {
+  const at = operands.indexOf(HEAD_COMMIT_FLAG)
+  if (at === -1) return { rest: operands, headCommit: undefined }
+  const headCommit = operands[at + 1]
+  const rest = [...operands.slice(0, at), ...operands.slice(at + 2)]
+  const plain = headCommit !== undefined && FULL_COMMIT.test(headCommit) && !rest.includes(HEAD_COMMIT_FLAG)
+  return plain ? { rest, headCommit } : undefined
+}
+
+/**
+ * `gh pr merge <number>` in its plain form: literal words only, merge-method and delete-branch flags, and at most one
+ * `--match-head-commit <full sha>`.
+ */
+const plainMerge = (words: SimpleCommand, expected: string[]): PlainMerge | undefined => {
   const after = words.slice(1)
   const [first, second, ...rest] = after
   if (after.some(isWildcard) || first?.value !== expected[0] || second?.value !== expected[1]) return undefined
-  const numbers = rest.filter(({ value }) => !APPROVABLE_FLAGS.has(value))
-  const only = numbers.length === 1 && PULL_REQUEST_NUMBER.test(numbers[0].value) ? numbers[0].value : undefined
-  return only === undefined ? undefined : Number(only)
+  const bound = withoutHeadCommit(rest.map(({ value }) => value))
+  const numbers = bound?.rest.filter((value) => !APPROVABLE_FLAGS.has(value)) ?? []
+  const only = numbers.length === 1 && PULL_REQUEST_NUMBER.test(numbers[0]) ? numbers[0] : undefined
+  return only === undefined ? undefined : { pullRequest: Number(only), headCommit: bound?.headCommit }
+}
+
+/** An expansion in a word's value: the marker, with the name it keeps after it (`$REPO`, `${REPO}`). */
+const EXPANSION_IN_VALUE = /\$(\{[^}]*\}|\w+)?/g
+/** Everything up to and including the last expansion of a value. */
+const UP_TO_LAST_EXPANSION = /^[\s\S]*\$(\{[^}]*\}|\w+)?/
+
+/** A word that is nothing but expansions: it may become any number of words, options among them. */
+const isOpaque = ({ value }: Word): boolean => isExpanded(value) && value.replace(EXPANSION_IN_VALUE, '') === ''
+
+const isReadMethod = ({ value }: Word): boolean => !isExpanded(value) && value.toUpperCase() === READ_METHOD
+
+/** An option of `gh api` split into its name and the value attached with `=` (or glued to `-X`), if any. */
+const apiOption = ({ value, literal }: Word): { name: string; attached: Word | undefined } => {
+  if (value.startsWith('-X') && value.length > 2) return { name: '-X', attached: { value: value.slice(2), literal } }
+  const at = value.indexOf('=')
+  if (at === -1 || !value.startsWith('--')) return { name: value, attached: undefined }
+  return { name: value.slice(0, at), attached: { value: value.slice(at + 1), literal } }
+}
+
+/** A short body option with its value glued on, as in `-fbody=x`. */
+const isGluedBodyOption = (value: string): boolean => /^-[fF]./.test(value)
+
+const readApiCall = (args: Word[]): ApiCall => {
+  const call: ApiCall = { method: undefined, fields: false, override: false, endpoints: [] }
+  for (let index = 0; index < args.length; index++) {
+    if (!isOption(args[index])) {
+      call.endpoints.push(args[index])
+      continue
+    }
+    const { name, attached } = apiOption(args[index])
+    const takesNext =
+      attached === undefined &&
+      (API_METHOD_OPTIONS.has(name) || API_BODY_OPTIONS.has(name) || API_OPTIONS_WITH_VALUE.has(name))
+    if (API_METHOD_OPTIONS.has(name)) call.method = attached ?? args[index + 1]
+    if (API_BODY_OPTIONS.has(name) || isGluedBodyOption(name)) call.fields = true
+    const header = HEADER_OPTIONS.has(name) ? (attached ?? args[index + 1]) : undefined
+    if (header !== undefined && METHOD_OVERRIDE_HEADER.test(header.value)) call.override = true
+    if (takesNext) index++
+  }
+  return call
+}
+
+const decodePercent = (path: string): string => {
+  try {
+    return decodeURIComponent(path)
+  } catch {
+    return path
+  }
+}
+
+/** The path as GitHub routes it: without query and fragment, percent-decoded, in lower case, with single slashes. */
+const normalizedPath = (value: string): string =>
+  decodePercent(value.split(/[?#]/)[0])
+    .toLowerCase()
+    .replace(/\/{2,}/g, '/')
+
+/** After an expansion, only the endpoint's fixed end is known, and an empty end could be any path. */
+const isDangerousEndpoint = ({ value }: Word): boolean => {
+  const path = normalizedPath(value)
+  if (DANGEROUS_ENDPOINTS.some((pattern) => pattern.test(path))) return true
+  if (!isExpanded(path)) return false
+  const ending = path.replace(UP_TO_LAST_EXPANSION, '')
+  return ending === '' || DANGEROUS_ENDINGS.some((pattern) => pattern.test(ending))
+}
+
+/**
+ * Whether the arguments after `gh api` write to a dangerous endpoint: a method other than GET, named or implied by a
+ * request body. A word made only of expansions could be any argument, so it counts as such a write.
+ */
+const writesDangerously = (args: Word[]): boolean => {
+  if (args.some(isOpaque)) return true
+  const { method, fields, override, endpoints } = readApiCall(args)
+  const writes = override || (method === undefined ? fields : !isReadMethod(method))
+  return writes && endpoints.some(isDangerousEndpoint)
+}
+
+/** The words after the first plain `api` behind the program at `index`; all of them when `api` came from an expansion. */
+const apiArguments = (words: SimpleCommand, index: number): Word[] => {
+  const after = words.slice(index + 1)
+  const at = after.findIndex((word) => word.literal && word.value === API_WORD)
+  return at === -1 ? after : after.slice(at + 1)
+}
+
+/** Every guarded command counts wherever it is found, except a `gh api` call that does not write dangerously. */
+const isGuardedUse = (command: string, words: SimpleCommand, programIndex: number): boolean =>
+  command !== API_COMMAND || writesDangerously(apiArguments(words, programIndex))
+
+/** In text the parse cannot see, `api` followed by the end of a dangerous endpoint is the sign; the method is unknown. */
+const mentionsDangerousApiCall = (script: string): boolean => {
+  const at = findWord(script, API_WORD, 0)
+  return at !== -1 && DANGEROUS_MENTION.test(script.slice(at))
 }
 
 /** `sole`: the script is this one simple command, written plainly, the only shape an approval can lift. */
 const findingOf = (command: string, words: SimpleCommand, index: number, sole: boolean): Finding | undefined => {
   const expected = command.split(' ').slice(1)
   if (!operandLists(words.slice(index + 1)).some((operands) => matchesFrom(operands, expected))) return undefined
+  if (!isGuardedUse(command, words, index)) return undefined
   const plain = sole && words[index].literal && words[index].value === 'gh'
-  return { command, pullRequest: plain ? plainPullRequest(words.slice(index), expected) : undefined }
+  return { command, merge: plain ? plainMerge(words.slice(index), expected) : undefined }
+}
+
+const programsOf = (commands: readonly string[]): string[] => [
+  ...new Set(commands.map((command) => command.split(' ')[0])),
+]
+
+/** A shell alias or function at the word that may run one of the guarded programs: it hides the words after them. */
+const definitionFinding = (words: SimpleCommand, index: number, { commands, definitions }: Search): Finding[] => {
+  const definition = shellDefinitionAt(words, index, definitions, programsOf(commands))
+  return definition ? [{ command: definition.name, merge: undefined, definition }] : []
 }
 
-const callsOfWord = (words: SimpleCommand, index: number, commands: readonly string[], sole: boolean): Finding[] => {
+const expandedFunctionFinding = (words: SimpleCommand, { commands, definitions }: Search, text: string): Finding[] =>
+  mayRunDefinedFunction(words, definitions, programsOf(commands), text)
+    ? [{ command: '', merge: undefined, note: EXPANDED_FUNCTION_NOTE }]
+    : []
+
+const callsOfWord = (words: SimpleCommand, index: number, search: Search, sole: boolean): Finding[] => {
   if (!isProgramPosition(words, index)) return []
   const program = programName(words[index])
-  return commands
-    .filter((command) => command.split(' ')[0] === program)
-    .flatMap((command) => findingOf(command, words, index, sole && index === 0) ?? [])
+  const guarded = search.commands.filter((command) => command.split(' ')[0] === program)
+  if (guarded.length === 0) return definitionFinding(words, index, search)
+  return guarded.flatMap((command) => findingOf(command, words, index, sole && index === 0) ?? [])
 }
 
 const isWordCharacter = (character: string | undefined): boolean => character !== undefined && /\w/.test(character)
@@ -155,25 +333,19 @@ const namesInOrder = (script: string, words: string[]): boolean => {
   return true
 }
 
-const callsNaming = (script: string, commands: readonly string[], wordsOf: (command: string) => string[]): Finding[] =>
-  commands
-    .filter((command) => namesInOrder(script, wordsOf(command)))
-    .map((command) => ({ command, pullRequest: undefined }))
-
-/** Where the script cannot be parsed, a guarded program named as a whole word is enough to ask. */
-const namedPrograms = (script: string, commands: readonly string[]): Finding[] =>
-  callsNaming(script, commands, (command) => command.split(' ').slice(0, 1))
-
 /** Where the program is hidden or the words are handed over as text, the command words after the program are the sign. */
 const mentionedCommandWords = (script: string, commands: readonly string[]): Finding[] =>
-  callsNaming(script, commands, (command) => command.split(' ').slice(1))
+  commands
+    .filter((command) =>
+      command === API_COMMAND ? mentionsDangerousApiCall(script) : namesInOrder(script, command.split(' ').slice(1)),
+    )
+    .map((command) => ({ command, merge: undefined }))
 
 /** A program expanded from a variable or a substitution could be the guarded one. */
 const runsExpandedProgram = (words: SimpleCommand): boolean =>
   words.some((word, index) => !word.literal && isProgramPosition(words, index))
 
-const runsOpaquely = (words: SimpleCommand): boolean =>
-  words.some((word, index) => isProgramPosition(words, index) && OPAQUE_RUNNERS.has(programName(word)))
+const runsOpaquely = (words: SimpleCommand): boolean => commandTextRunnerIndex(words) !== -1
 
 /**
  * A shell, anywhere a program can stand, that reads its script from stdin (no operand, or `-s`), from a process
@@ -190,14 +362,14 @@ const readsScriptFromElsewhere = (words: SimpleCommand): boolean =>
     return fromInput || operands.some((each) => !each.literal || INPUT_PATH.test(each.value))
   })
 
-/** An interpreter handed program text (`python3 -c`, `node -e`) or git handed an alias runs text the parse cannot see. */
-const runsProgramText = (words: SimpleCommand): boolean =>
-  words.some((word, index) => {
-    if (!isProgramPosition(words, index)) return false
-    const rest = words.slice(index + 1)
-    if (programName(word) === 'git') return rest.some(({ value }) => value.startsWith('alias.'))
-    return INTERPRETERS.has(programName(word)) && rest.some(({ value }) => INLINE_PROGRAM_OPTIONS.has(value))
-  })
+/** Git handed an alias (`git -c alias.m=!…`) runs text the parse cannot see. */
+const definesGitAlias = (words: SimpleCommand): boolean =>
+  words.some(
+    (word, index) =>
+      isProgramPosition(words, index) &&
+      programName(word) === 'git' &&
+      words.slice(index + 1).some(({ value }) => value.startsWith('alias.')),
+  )
 
 /** An inline script that is itself an expansion (`eval "$X"`) hides its text from the parse of the call. */
 const runsInlineExpansion = (words: SimpleCommand): boolean =>
@@ -217,71 +389,139 @@ const containsInOrder = (words: SimpleCommand, command: string): boolean => {
     if (next === -1) return false
     from = next + 1
   }
-  return true
+  return isGuardedUse(command, words, at)
 }
 
-const callsInCommand = (words: SimpleCommand, commands: readonly string[], sole: boolean, whole: string): Finding[] => {
+/** `text` is the searchable text of the script around the command: a variable there may hold a function's name. */
+const callsInCommand = (words: SimpleCommand, search: Search, sole: boolean, whole: string, text: string): Finding[] => {
   const direct = words.flatMap((_word, index) => {
     const script = inlineScript(words, index)
-    return script === undefined ? callsOfWord(words, index, commands, sole) : callsIn(script, commands, false, whole)
+    return script === undefined ? callsOfWord(words, index, search, sole) : callsIn(script, search, false, whole)
   })
   const found = new Set(direct.map(({ command }) => command))
-  const byWords = commands
+  const byWords = search.commands
     .filter((command) => !found.has(command) && containsInOrder(words, command))
-    .map((command) => ({ command, pullRequest: undefined }))
-  return [...direct, ...byWords]
+    .map((command) => ({ command, merge: undefined }))
+  return [...direct, ...byWords, ...expandedFunctionFinding(words, search, text)]
 }
 
-/** Each check reads the whole script: a shell that reads stdin, an expanded program or an opaque runner hides what runs. */
+/**
+ * Each check reads the whole script: a shell that reads stdin, an expanded program, an opaque runner or an interpreter
+ * handed program text hides what runs.
+ */
 const hidesWhatRuns = (words: SimpleCommand): boolean =>
   runsExpandedProgram(words) ||
   runsOpaquely(words) ||
   readsScriptFromElsewhere(words) ||
   runsInlineExpansion(words) ||
-  runsProgramText(words)
+  runsInterpreterProgram(words) ||
+  definesGitAlias(words) ||
+  definesShellAlias(words)
 
 const callsInScriptWide = (whole: string, parsed: SimpleCommand[], commands: readonly string[]): Finding[] =>
-  parsed.some(hidesWhatRuns) ? mentionedCommandWords(whole, commands) : []
+  parsed.some(hidesWhatRuns) ? mentionedCommandWords(searchableText(whole, parsed), commands) : []
 
 /** `whole` is the text of the outermost script: a nested script's input comes from there, so the words are searched in it. */
-const callsIn = (script: string, commands: readonly string[], top: boolean, whole: string): Finding[] => {
-  try {
-    const parsed = parseShell(script)
-    const sole = top && parsed.length === 1 && !script.trimStart().startsWith('(')
-    return [
-      ...parsed.flatMap((words) => callsInCommand(words, commands, sole, whole)),
-      ...callsInScriptWide(whole, parsed, commands),
-    ]
-  } catch (error) {
-    if (error instanceof ShellParseError) return namedPrograms(whole, commands)
-    throw error
-  }
+const callsIn = (script: string, search: Search, top: boolean, whole: string): Finding[] => {
+  const parsed = parseShell(script)
+  const sole = top && parsed.length === 1 && !script.trimStart().startsWith('(')
+  const text = searchableText(whole, parsed)
+  return [
+    ...parsed.flatMap((words) => callsInCommand(words, search, sole, whole, text)),
+    ...callsInScriptWide(whole, parsed, search.commands),
+  ]
 }
 
-const isApproved = ({ command, pullRequest }: Finding, policy: GuardPolicy): boolean => {
-  if (command !== MERGE_COMMAND || pullRequest === undefined) return false
+const approvalOf = ({ command, merge }: Finding, policy: GuardPolicy): boolean | MergeNote => {
+  if (command !== MERGE_COMMAND || merge === undefined) return false
   try {
-    return policy.isMergeApproved(pullRequest)
+    return policy.isMergeApproved(merge)
   } catch {
     return false
   }
 }
 
-const askBecause = (commands: string[]): MergeGuardDecision => ({
+const guardedListSentence = (commands: string[]): string[] =>
+  commands.length === 0
+    ? []
+    : [
+        `${commands.map((command) => `\`${command}\``).join(' and ')} is on the project's guarded list (guard.commands in .jackherd/config.json), so the user confirms it.`,
+      ]
+
+const askBecause = (findings: Finding[], notes: string[], script: string): MergeGuardDecision => {
+  const guarded = findings
+    .filter(({ definition, note }) => definition === undefined && note === undefined)
+    .map(({ command }) => command)
+  const definitions = [
+    ...new Map(
+      findings.flatMap(({ definition }) => (definition ? [[definition.name, definition] as const] : [])),
+    ).values(),
+  ]
+  return {
+    kind: 'ask',
+    reason: [
+      ...guardedListSentence([...new Set(guarded)]),
+      ...definitions.map(
+        (definition) =>
+          `${shellDefinitionHint(definition)} It may run a command of guard.commands in .jackherd/config.json, so the user confirms it.`,
+      ),
+      ...new Set(findings.flatMap(({ note }) => note ?? [])),
+      ...notes,
+      expandingHereDocumentAdvice(script),
+    ]
+      .filter((part) => part !== '')
+      .join(' '),
+  }
+}
+
+/**
+ * Quotes split a word (`g''h`), a variable builds it, an expansion hides a command: in text the parse cannot follow,
+ * no word search can tell whether a guarded command runs, so every unreadable script asks (fail closed).
+ */
+const askUnreadable = ({ message }: ShellParseError, script: string): MergeGuardDecision => ({
   kind: 'ask',
-  reason: `${commands.map((command) => `\`${command}\``).join(' and ')} is on the project's guarded list (guard.commands in .jackherd/config.json), so the user confirms it.`,
+  reason: [
+    `The command could not be read (${message}), so it may run a command of guard.commands in .jackherd/config.json and the user confirms it.`,
+    UNREADABLE_ADVICE,
+    expandingHereDocumentAdvice(script),
+  ]
+    .filter((part) => part !== '')
+    .join(' '),
 })
 
+const findingsOrUnreadable = (command: string, search: Search): Finding[] | ShellParseError => {
+  try {
+    return callsIn(command, search, true, command)
+  } catch (error) {
+    if (error instanceof ShellParseError) return error
+    throw error
+  }
+}
+
 /**
  * Decides on a Bash command before it runs: `ask` when it runs, or could run, a guarded command (`gh pr merge`,
- * `gh workflow run` by default), also behind options before the verb, a chain, a wrapper, `sh -c`, `eval`, a
- * script piped into a shell or a program held in a variable. A script that is exactly
- * `gh pr merge <number>` with merge-method and delete-branch flags passes when the user approved it
- * (`isMergeApproved`); any other shape of the merge, and every other guarded command, asks. A command that merely names the words (an argument, a commit message) is none.
+ * `gh workflow run`, `gh run rerun` and a `gh api` write to a merge, a file, a dispatch, a rerun or a ref by default), also behind options before the
+ * verb, a chain, a wrapper, `sh -c`, `eval`, a script piped into a shell, an interpreter's program text, a shell alias
+ * or function, or a program held in a variable. A script that is exactly `gh pr merge <number>` with merge-method and
+ * delete-branch flags and at most one `--match-head-commit <sha>` passes when the user approved it
+ * (`isMergeApproved`); any other shape of the merge, and every other guarded command, asks. A command that merely
+ * names the words (an argument, a commit message) is none. A script the parse cannot read asks whatever it names,
+ * unless the list is empty.
  */
 export const decideBashCommand = (command: string, policy: GuardPolicy): MergeGuardDecision => {
-  const findings = callsIn(command, policy.commands, true, command)
+  if (policy.commands.length === 0) return PASS
+  const search = { commands: policy.commands, definitions: policy.shellDefinitions ?? (() => NO_DEFINITIONS) }
+  const findings = findingsOrUnreadable(command, search)
+  if (findings instanceof ShellParseError) return askUnreadable(findings, command)
   if (findings.length === 0) return PASS
-  const unapproved = findings.filter((finding) => !isApproved(finding, policy))
-  return unapproved.length === 0 ? PASS : askBecause([...new Set(unapproved.map(({ command: name }) => name))])
+  const unapproved = findings
+    .map((finding) => ({ finding, approval: approvalOf(finding, policy) }))
+    .filter(({ approval }) => approval !== true)
+  if (unapproved.length === 0) return PASS
+  const notes = unapproved.flatMap(({ approval }) => (typeof approval === 'object' ? [approval.note] : []))
+  return askBecause(
+    unapproved.map(({ finding }) => finding),
+    [...new Set(notes)],
+    command,
+  )
 }