jackherd 1.7.0 → 1.8.0

package/kit/hooks/hooks/shared/board-lanes.ts

@@ -0,0 +1,93 @@
+/**
+ * The lanes table of a board, read the way the herd reads it (`parseSprintLanes` in the package), which a hook cannot
+ * import: the first table under `## <lanes>`, a row naming its lane in backticks or continuing the one above with `↳`,
+ * the plan as the link in the third cell. A test compares both on the repository's real boards.
+ */
+import { posix } from 'node:path'
+
+export type BoardLanguage = 'de' | 'en'
+
+/** The plan vocabulary's words for the lanes section and a closed lane, per plan language. */
+export const BOARD_WORDS: Record<BoardLanguage, { lanes: string; laneClosed: string }> = {
+  de: { lanes: 'Spuren', laneClosed: 'abgeräumt' },
+  en: { lanes: 'Lanes', laneClosed: 'cleaned up' },
+}
+
+/** A lane's rows: whether any says the lane was cleaned up, and the plans they link, relative to the repository. */
+export type LanePlans = { closed: boolean; plans: string[] }
+
+type Row = { lane: string; cells: string[] }
+
+const LANE_NAME = /`([^`]+)`/
+const CONTINUATION = '↳'
+const PLAN_LINK = /\[([^\]]+)\]\(([^)]+)\)/
+const SECTION_END = /^##\s/
+const TABLE_SEPARATOR = /^\|[\s|:-]+\|$/
+const PLAN_COLUMN = 2
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const sectionLines = (markdown: string, heading: string): string[] => {
+  const lines = markdown.split('\n')
+  const pattern = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`)
+  const start = lines.findIndex((line) => pattern.test(line))
+  if (start === -1) return []
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => SECTION_END.test(line))
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+const cellsOf = (line: string): string[] =>
+  line
+    .slice(1, line.endsWith('|') ? -1 : undefined)
+    .split('|')
+    .map((cell) => cell.trim())
+
+/** The body rows of the first table, header and separator rows dropped. */
+const firstTableLines = (lines: string[]): string[] => {
+  const start = lines.findIndex((line) => line.startsWith('|'))
+  if (start === -1) return []
+  const rest = lines.slice(start)
+  const end = rest.findIndex((line) => !line.startsWith('|'))
+  return (end === -1 ? rest : rest.slice(0, end)).slice(1).filter((line) => !TABLE_SEPARATOR.test(line))
+}
+
+const laneRows = (markdown: string, language: BoardLanguage): Row[] => {
+  const rows: Row[] = []
+  let previous: string | null = null
+  for (const line of firstTableLines(sectionLines(markdown, BOARD_WORDS[language].lanes))) {
+    const cells = cellsOf(line)
+    const first = cells[0] ?? ''
+    const lane: string | null = first.match(LANE_NAME)?.[1] ?? (first.startsWith(CONTINUATION) ? previous : null)
+    if (lane === null) continue
+    rows.push({ lane, cells })
+    previous = lane
+  }
+  return rows
+}
+
+/** The repository path of a plan link, relative to the board's directory. */
+const planPathOf = (boardDirectory: string, cell: string): string[] => {
+  const href = cell.match(PLAN_LINK)?.[2]
+  return href === undefined ? [] : [posix.normalize(posix.join(boardDirectory, href.split('#')[0]))]
+}
+
+/** Every lane the lanes table names, in table order. */
+export const laneNamesOf = (markdown: string, language: BoardLanguage): string[] => [
+  ...new Set(laneRows(markdown, language).map(({ lane }) => lane)),
+]
+
+/** The rows of `lane` in the board's lanes table; undefined when the table has no row for it. */
+export const lanePlansOf = (
+  markdown: string,
+  boardDirectory: string,
+  lane: string,
+  language: BoardLanguage,
+): LanePlans | undefined => {
+  const rows = laneRows(markdown, language).filter((row) => row.lane === lane)
+  if (rows.length === 0) return undefined
+  return {
+    closed: rows.some(({ cells }) => (cells[0] ?? '').includes(BOARD_WORDS[language].laneClosed)),
+    plans: [...new Set(rows.flatMap(({ cells }) => planPathOf(boardDirectory, cells[PLAN_COLUMN] ?? '')))],
+  }
+}

package/kit/hooks/hooks/shared/command-text-runners.ts

@@ -0,0 +1,71 @@
+import { isProgramPosition, programName } from './program-position'
+import type { SimpleCommand, Word } from './shell'
+
+/** Programs that run text they are given or read from elsewhere, so no parse of the shell sees what runs. */
+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',
+  'watch',
+  'osascript',
+])
+
+/** Package runners whose `-c`/`--call` hands a command string to a shell: `npx -c`, `npm exec -c`, `pnpm dlx -c`. */
+const PACKAGE_RUNNERS = new Set(['npx', 'npm', 'pnpm', 'yarn'])
+const CALL_OPTION = /^(-c|--call)(=|$)/
+const AWK_PROGRAMS = new Set(['awk', 'gawk', 'mawk', 'nawk'])
+/** An awk program that starts a command: `system(…)`, a pipe into or out of `getline`, `print … | "cmd"`. */
+const AWK_RUNS_COMMAND = /\bsystem\s*\(|\|\s*getline|\|&|print[^;}]*\|/
+/** sed's `e` command, alone or after an address: `1e cmd`, `/x/e cmd`, `;e`. */
+const SED_EXECUTE_COMMAND = /(^|[\s;{}!=\d$/])e(\s|;|$)/
+/** sed's `s///e` flag, which runs the pattern space as a command. */
+const SED_EXECUTE_FLAG = /^\s*s(.)(?:\\.|(?!\1).)*\1(?:\\.|(?!\1).)*\1[^;\s}]*e/
+
+const sedRunsCommand = (rest: Word[]): boolean =>
+  rest.some(
+    ({ value }) => SED_EXECUTE_COMMAND.test(value) || value.split(/[;\n]/).some((piece) => SED_EXECUTE_FLAG.test(piece)),
+  )
+
+const runsCommandText = (name: string, rest: Word[]): boolean =>
+  OPAQUE_RUNNERS.has(name) ||
+  (PACKAGE_RUNNERS.has(name) && rest.some(({ value }) => CALL_OPTION.test(value))) ||
+  (name === 'sed' && sedRunsCommand(rest)) ||
+  (AWK_PROGRAMS.has(name) && rest.some(({ value }) => AWK_RUNS_COMMAND.test(value)))
+
+/**
+ * The index of a program that runs command text it is given (`watch '…'`, `script -qc '…'`, `npx -c '…'`, sed's `e`,
+ * awk's `system()`), anywhere a program can stand; -1 when there is none.
+ */
+export const commandTextRunnerIndex = (words: SimpleCommand): number =>
+  words.findIndex(
+    (word, index) => isProgramPosition(words, index) && runsCommandText(programName(word), words.slice(index + 1)),
+  )
+
+/**
+ * The text a mention search reads: the script as written and, beside it, every word as the shell decodes it, so a word
+ * split by quotes (`pu""sh`) or written in `$'…'` escapes (`pu\x73h`) is found too.
+ */
+export const searchableText = (script: string, commands: SimpleCommand[]): string =>
+  [script, ...commands.map((words) => words.map(({ value }) => value).join(' '))].join('\n')

package/kit/hooks/hooks/shared/command.ts

@@ -1,6 +1,18 @@
-/** The trimmed stdout of a command run without a shell; throws when it fails, so the caller gives up. */
+/** Long enough for a local `git` or `herdr` answer, well below the deadline of the hook that waits for it. */
+export const COMMAND_TIMEOUT_MS = 3000
+
+/**
+ * The trimmed stdout of a command run without a shell; throws when it fails or outlives `COMMAND_TIMEOUT_MS`, so the
+ * caller gives up. A command past the limit is killed with SIGKILL, which it cannot ignore.
+ */
 export const commandOutput = (command: string[], cwd?: string): string => {
-  const result = Bun.spawnSync(command, { cwd, stdout: 'pipe', stderr: 'ignore' })
+  const result = Bun.spawnSync(command, {
+    cwd,
+    stdout: 'pipe',
+    stderr: 'ignore',
+    timeout: COMMAND_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+  })
   if (result.exitCode !== 0) throw new Error(`${command[0]} failed`)
   return result.stdout.toString().trim()
 }

package/kit/hooks/hooks/shared/commit.ts

@@ -0,0 +1,2 @@
+/** A full commit id as git and GitHub write it: 40 hex digits for SHA-1, 64 for SHA-256. */
+export const FULL_COMMIT = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/

package/kit/hooks/hooks/shared/dialog-answers.ts

@@ -3,6 +3,9 @@ import { isRecord, type JsonObject } from './json'
 
 export type { DialogAnswer } from './dialog-answer'
 
+/** The tool name of the dialog, as hook inputs and transcripts carry it. */
+export const ASK_USER_QUESTION_TOOL = 'AskUserQuestion'
+
 /**
  * The answers of the user's dialogs, read from a session transcript. The transcript is written by the agent's own
  * client, not by the agent: a dialog answer sits in it as the result of an `AskUserQuestion` call, with the question the
@@ -49,7 +52,7 @@ const askedQuestions = (entries: JsonObject[]): Map<string, AskedQuestion[]> =>
     entries
       .filter(isMainThread)
       .flatMap(contentOf)
-      .filter((block) => block.type === 'tool_use' && block.name === 'AskUserQuestion' && typeof block.id === 'string')
+      .filter((block) => block.type === 'tool_use' && block.name === ASK_USER_QUESTION_TOOL && typeof block.id === 'string')
       .map((block): [string, AskedQuestion[]] => [block.id as string, questionsOf(block.input)]),
   )
 

package/kit/hooks/hooks/shared/json.ts

@@ -2,3 +2,13 @@ export type JsonObject = Record<string, unknown>
 
 export const isRecord = (value: unknown): value is JsonObject =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/** The JSON text as an object; undefined for text that is no JSON or no object (an array included). */
+export const parseJsonObject = (text: string): JsonObject | undefined => {
+  try {
+    const value: unknown = JSON.parse(text)
+    return isRecord(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}

package/kit/hooks/hooks/shared/lane.ts

@@ -0,0 +1,57 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import type { PaneAgent } from './pane-agent'
+
+/** herdr's agent names; a worktree whose directory has another name cannot be a lane. */
+const LANE_NAME = /^[a-z][a-z0-9_-]{0,31}$/
+
+export type LaneLocation = { cwd: string; main: string; worktreeDirectory: string }
+
+export type AgentLocation = {
+  /** The agent herdr runs in the pane the hook was called from. */
+  agent: PaneAgent
+  /** The session the hook was called for. */
+  session: string
+  main: string
+  worktreeDirectory: string
+}
+
+/** The session that merges, against the agent herdr runs in its pane. */
+export type MergingSession = {
+  /** The agent of the pane the hook runs in; null outside herdr. */
+  agent: PaneAgent | null
+  /** The `session_id` of the hook input. */
+  session: unknown
+  main: string
+  /** Whether a herdr name is a lane's, whose worktree exists. */
+  isLane: (name: string) => boolean
+}
+
+/** The lane whose worktree holds `cwd`: the first directory below the main checkout's worktree directory, else null. */
+export const laneOf = ({ cwd, main, worktreeDirectory }: LaneLocation): string | null => {
+  const path = relative(resolve(main, worktreeDirectory), resolve(cwd))
+  if (path === '' || path.startsWith('..') || isAbsolute(path)) return null
+  const [lane] = path.split(sep)
+  return LANE_NAME.test(lane) ? lane : null
+}
+
+/**
+ * The lane the agent of this pane is: an agent named after a worktree that it runs in, in the session the hook was
+ * called for. The shell's directory has no say: the coordinator's shell may stand in a lane's worktree.
+ */
+export const laneOfAgent = ({ agent, session, main, worktreeDirectory }: AgentLocation): string | null => {
+  if (agent.name === null || agent.cwd === null || agent.session === null || agent.session !== session) return null
+  return laneOf({ cwd: agent.cwd, main, worktreeDirectory }) === agent.name ? agent.name : null
+}
+
+/**
+ * Whether the session that merges is the coordinator: the agent of its pane, in this very session, started in the main
+ * checkout and not under a lane's name. A lane's transcript may lie beside the coordinator's when it was started in the
+ * main checkout; its name still tells it apart, so the plan approval never covers a lane's own merge.
+ */
+export const isCoordinatorAgent = ({ agent, session, main, isLane }: MergingSession): boolean =>
+  agent !== null &&
+  agent.session !== null &&
+  agent.session === session &&
+  agent.cwd !== null &&
+  resolve(agent.cwd) === resolve(main) &&
+  (agent.name === null || !isLane(agent.name))

package/kit/hooks/hooks/shared/once.ts

@@ -0,0 +1,8 @@
+/** The value of `compute`, computed at the first call and kept for every later one, undefined and throws aside. */
+export const once = <T>(compute: () => T): (() => T) => {
+  let kept: { value: T } | undefined
+  return () => {
+    kept ??= { value: compute() }
+    return kept.value
+  }
+}

package/kit/hooks/hooks/shared/own-pane.ts

@@ -0,0 +1,31 @@
+import { type PaneAgent, paneAgentOf } from './pane-agent'
+
+/** herdr's pane ids (`w2V:p1`); anything else never reaches the command line. */
+const PANE_ID = /^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/
+/** Well below the deadlines of the hooks that ask, which still have work to do after it. */
+const HERDR_TIMEOUT_MS = 2000
+
+/**
+ * The agent herdr runs in the pane this process was started in; null outside herdr and whenever herdr cannot be asked.
+ *
+ * Only the pane is fixed: herdr sets `HERDR_PANE_ID` in the client's environment, and no command the agent runs can
+ * change it there. herdr's answer about that pane is not: the agent's name and session are reported to herdr, and any
+ * process may report them. Only `cwd` herdr reads from the process itself. A caller trusts a name or a session only
+ * where a second fact binds it, such as the session of the hook input or a worktree of that name.
+ */
+export const ownPaneAgent = (env: Record<string, string | undefined> = process.env): PaneAgent | null => {
+  const paneId = env.HERDR_PANE_ID
+  if (paneId === undefined || !PANE_ID.test(paneId)) return null
+  try {
+    const result = Bun.spawnSync(['herdr', 'agent', 'get', paneId], {
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'ignore',
+      timeout: HERDR_TIMEOUT_MS,
+      env,
+    })
+    return result.exitCode === 0 ? paneAgentOf(JSON.parse(result.stdout.toString())) : null
+  } catch {
+    return null
+  }
+}

package/kit/hooks/hooks/shared/pane-agent.ts

@@ -0,0 +1,24 @@
+import { isRecord, type JsonObject } from './json'
+
+/** The agent herdr runs in a pane: its herdr name, the directory it started in and its client session, each null when unknown. */
+export type PaneAgent = { name: string | null; cwd: string | null; session: string | null }
+
+/** A client's session id as a UUID; nothing else may reach a path. */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** The client session of an agent or a pane herdr reports; null for a shell, or a session id of another shape. */
+export const sessionOf = (pane: JsonObject): string | null => {
+  const session = isRecord(pane.agent_session) ? pane.agent_session.value : undefined
+  return typeof pane.agent === 'string' && pane.agent !== '' && typeof session === 'string' && SESSION_ID.test(session)
+    ? session
+    : null
+}
+
+const textOrNull = (value: unknown): string | null => (typeof value === 'string' && value !== '' ? value : null)
+
+/** The agent of the answer of `herdr agent get <pane>`; null for an error or an answer of another shape. */
+export const paneAgentOf = (answer: unknown): PaneAgent | null => {
+  const agent = isRecord(answer) && isRecord(answer.result) ? answer.result.agent : undefined
+  if (!isRecord(agent)) return null
+  return { name: textOrNull(agent.name), cwd: textOrNull(agent.cwd), session: sessionOf(agent) }
+}

package/kit/hooks/hooks/shared/plan-open-phases.ts

@@ -0,0 +1,114 @@
+/**
+ * Whether a plan still has an open phase, read the way the herd reads phases (`parsePlanPhases` in the package),
+ * which a hook cannot import. A test compares both on the repository's real plans.
+ */
+
+/** A task of a phase, a checkbox or a row with a ⬜/✅ cell: whether it is open, and its text without the state. */
+export type PlanTask = { open: boolean; text: string }
+
+type Phase = { id: string; items: boolean[]; deferredOpen: boolean; pointer?: string }
+
+/** A phase's id, its heading without the leading hashes, and its lines up to the next heading that ends it. */
+export type PhaseBlock = { id: string; heading: string; lines: string[] }
+
+const PHASE_HEADING = /^###\s+Phase\s+(\d+[a-z]?)\b/i
+/** `## 10 — title`, and `## P15 — title` as a board names the phase. */
+const NUMBERED_SECTION = /^##\s+P?(\d+[a-z]?)\s*[—–:-]\s*(.*)$/
+const PHASE_END = /^#{1,3}\s/
+const SECTION_HEADING = /^##\s+(.+?)\s*$/
+const TOP_HEADING = /^#\s/
+const CHECKBOX = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/
+const DEFERRED_TO = /\s→\s*P(\d+[a-z]?)\s*$/i
+const SECTION_POINTER = /`##\s+([^`]+?)\s*`/
+const STATUS = { done: '✅', open: '⬜' } as const
+
+const collapsed = (text: string): string => text.trim().replace(/\s+/g, ' ')
+
+/** The task a line holds, null for a line that is none. */
+export const taskOf = (line: string): PlanTask | null => {
+  const checkbox = line.match(CHECKBOX)
+  if (checkbox) return { open: checkbox[1] === ' ', text: collapsed(checkbox[2]) }
+  const trimmed = line.trim()
+  if (!trimmed.startsWith('|')) return null
+  const cells = trimmed.replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim())
+  const status = cells.find((cell) => cell === STATUS.done || cell === STATUS.open)
+  if (status === undefined) return null
+  const text = cells.filter((cell) => cell !== STATUS.done && cell !== STATUS.open).join(' | ')
+  return { open: status === STATUS.open, text: collapsed(text) }
+}
+
+/** An item of a phase: `true` while open, `false` when done, null for a line that is none. */
+const itemOf = (line: string): boolean | null => taskOf(line)?.open ?? null
+
+/** An open checkbox moved on to another phase with `→ P<n>` at its end; it stays open, in that phase. */
+const isDeferred = (line: string, phaseId: string): boolean => {
+  const checkbox = line.match(CHECKBOX)
+  const target = checkbox?.[1] === ' ' ? checkbox[2].match(DEFERRED_TO)?.[1]?.toLowerCase() : undefined
+  return target !== undefined && target !== phaseId
+}
+
+const phaseIdOf = (line: string): string | undefined =>
+  (line.match(PHASE_HEADING) ?? line.match(NUMBERED_SECTION))?.[1]?.toLowerCase()
+
+const fileLine = (phase: Phase, line: string): void => {
+  phase.pointer ??= line.match(SECTION_POINTER)?.[1]
+  if (isDeferred(line, phase.id)) {
+    phase.deferredOpen = true
+    return
+  }
+  const item = itemOf(line)
+  if (item !== null) phase.items.push(item)
+}
+
+/** The phases of a plan as they stand, `### Phase <id>` and `## <id> — title` alike. */
+export const phaseBlocksOf = (markdown: string): PhaseBlock[] => {
+  const blocks: PhaseBlock[] = []
+  let open: PhaseBlock | null = null
+  for (const line of markdown.split('\n')) {
+    const id = phaseIdOf(line)
+    if (id !== undefined) {
+      open = { id, heading: collapsed(line.replace(/^#+/, '')), lines: [] }
+      blocks.push(open)
+    } else if (PHASE_END.test(line)) open = null
+    else open?.lines.push(line)
+  }
+  return blocks
+}
+
+const phasesOf = (markdown: string): Phase[] =>
+  phaseBlocksOf(markdown).map(({ id, lines }) => {
+    const phase: Phase = { id, items: [], deferredOpen: false }
+    for (const line of lines) fileLine(phase, line)
+    return phase
+  })
+
+/** The items of every `## ` section by heading, sub-headings included; the last of equal headings wins. */
+const sectionItems = (markdown: string): Map<string, boolean[]> => {
+  const sections = new Map<string, boolean[]>()
+  let open: boolean[] | null = null
+  for (const line of markdown.split('\n')) {
+    const heading = line.match(SECTION_HEADING)
+    if (heading) {
+      open = []
+      sections.set(heading[1], open)
+    } else if (TOP_HEADING.test(line)) open = null
+    else {
+      const item = itemOf(line)
+      if (item !== null) open?.push(item)
+    }
+  }
+  return sections
+}
+
+/**
+ * True when a phase (`### Phase <id>` or `## <id> — title`) holds an open checkbox or ⬜ row, a deferred one included;
+ * a phase without items of its own counts the section it points at (``Siehe `## Dokumentation` ``).
+ */
+export const hasOpenPhase = (markdown: string): boolean => {
+  const phases = phasesOf(markdown)
+  if (phases.some((phase) => phase.deferredOpen || phase.items.includes(true))) return true
+  const pointed = phases.filter((phase) => phase.items.length === 0 && phase.pointer !== undefined)
+  if (pointed.length === 0) return false
+  const sections = sectionItems(markdown)
+  return pointed.some((phase) => (sections.get(phase.pointer ?? '') ?? []).includes(true))
+}

package/kit/hooks/hooks/shared/program-position.ts

@@ -1,5 +1,5 @@
 import { posix } from 'node:path'
-import type { SimpleCommand, Word } from './shell'
+import { isExpanded, type SimpleCommand, type Word } from './shell'
 
 /**
  * Words Claude Code strips before it matches a Bash rule, so they do not hide the command. Its
@@ -11,10 +11,24 @@ export const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*\+?=/
 const DURATION = /^\d+(\.\d+)?[smhd]?$/
 const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'mksh', 'fish'])
 const SHELL_COMMAND_FLAG = /^-[a-z]*c[a-z]*$/
+const FUNCTION_KEYWORD = 'function'
+/** zsh's precommand, `- eval …`; as a word it is also stdin (`cat -`), so it counts only where a command stands. */
+const ZSH_PRECOMMAND = '-'
+/**
+ * Shell words that run a command after names or counts of their own: `function` opens a body (`function f g {`),
+ * `coproc` may take a name, zsh's `repeat` a count and `nocorrect` none.
+ */
+const SHELL_RUNNERS = [FUNCTION_KEYWORD, 'coproc', 'repeat', 'nocorrect']
+const SHELL_COMMAND_OPENERS = new Set([...SHELL_RUNNERS, ZSH_PRECOMMAND])
+/** The builtin that runs its arguments, joined, as a script in the same shell. */
+const EVAL_BUILTIN = 'eval'
+/** The builtin that runs its action text later in the same shell. */
+const TRAP_BUILTIN = 'trap'
 
 /** Programs that run their arguments as a command, so a program right after them is the one that runs. */
 const COMMAND_RUNNERS = new Set([
   ...RULE_TRANSPARENT_WRAPPERS,
+  ...SHELL_RUNNERS,
   'env',
   'sudo',
   'doas',
@@ -67,16 +81,145 @@ const shellCommandScript = (words: SimpleCommand, shellIndex: number): string |
   return words.slice(flag + 1).find((word) => !isOption(word))?.value
 }
 
+/** The action of `trap <action> <signal>…`: the first word after the options and `--`; the shell runs it later itself. */
+const trapAction = (words: SimpleCommand, trapIndex: number): string | undefined => {
+  const rest = words.slice(trapIndex + 1)
+  const start = rest.findIndex((word) => !isOption(word) || word.value === '--')
+  const action = rest[start]?.value === '--' ? rest[start + 1] : rest[start]
+  return action?.value
+}
+
+/**
+ * Whether a word before a builtin leaves it the command: an option or its value, an assignment, a duration
+ * (`sudo -u me`, `env X=1`, `timeout 30`, `repeat 1`), a reserved word, or the name after `function`.
+ */
+const leadsToBuiltin = (words: SimpleCommand, index: number): boolean => {
+  const { value } = words[index]
+  const previous = words[index - 1]
+  return (
+    isOption(words[index]) ||
+    isOption(previous) ||
+    ASSIGNMENT.test(value) ||
+    DURATION.test(value) ||
+    RESERVED_WORDS.has(value) ||
+    (previous !== undefined && programName(previous) === FUNCTION_KEYWORD)
+  )
+}
+
+/**
+ * Where in a command a builtin runs as the command itself: at the rule start, right after a runner that is itself the
+ * command (with its options), or anywhere after a shell word that opens a command and stands as the command itself,
+ * whatever names or counts follow it (`function f g {`, `coproc NAME {`, `repeat $n`, zsh's `- eval`). No external
+ * runner starts a builtin from a later argument, so `timeout 30 rg eval` searches for the word. One pass per command; each word looks back only to the runner before it.
+ */
+const builtinPositions = (words: SimpleCommand): boolean[] => {
+  const start = ruleStart(words)
+  const positions: boolean[] = []
+  let afterOpener = false
+  for (let index = 0; index < words.length; index++) {
+    let before = index - 1
+    while (before >= 0 && !COMMAND_RUNNERS.has(programName(words[before])) && leadsToBuiltin(words, before)) before--
+    const afterRunner = before >= 0 && COMMAND_RUNNERS.has(programName(words[before])) && positions[before]
+    positions[index] = index === start || afterRunner || afterOpener
+    if (positions[index] && SHELL_COMMAND_OPENERS.has(words[index].value)) afterOpener = true
+  }
+  return positions
+}
+
+/** One pass per command, since every word of it is asked: the positions of a command are its own. */
+const positionsByCommand = new WeakMap<SimpleCommand, boolean[]>()
+
+const isBuiltinPosition = (words: SimpleCommand, index: number): boolean => {
+  const known = positionsByCommand.get(words)
+  if (known) return known[index]
+  const positions = builtinPositions(words)
+  positionsByCommand.set(words, positions)
+  return positions[index]
+}
+
+/** Whether the word runs as `builtin`: named so where a command stands, also quoted (`'trap'`) or escaped (`\trap`). */
+const isBuiltinAt = (words: SimpleCommand, index: number, builtin: string): boolean =>
+  programName(words[index]) === builtin && isBuiltinPosition(words, index)
+
 export const inlineScript = (words: SimpleCommand, index: number): string | undefined => {
-  const word = words[index]
-  if (word.literal && word.value === 'eval') return words.slice(index + 1).map(({ value }) => value).join(' ')
-  return isShell(word) ? shellCommandScript(words, index) : undefined
+  if (isBuiltinAt(words, index, EVAL_BUILTIN))
+    return words
+      .slice(index + 1)
+      .map(({ value }) => value)
+      .join(' ')
+  if (isBuiltinAt(words, index, TRAP_BUILTIN)) return trapAction(words, index)
+  return isShell(words[index]) ? shellCommandScript(words, index) : undefined
 }
 
+/** Interpreters that run program text given on the command line or read from their input. */
+const INTERPRETERS = new Set(['python', 'python3', 'node', 'nodejs', 'bun', 'deno', 'perl', 'ruby', 'php', 'lua'])
+const INLINE_PROGRAM_OPTIONS = new Set(['-c', '-e', '-E', '-p', '-pe', '--eval', '--command', '--print', '-r'])
+const VERSIONED_PYTHON = /^python\d+(\.\d+)*$/
+/** A cluster of short options that ends in the one taking the program text: `python3 -Ic`, `perl -lne`. */
+const INLINE_PROGRAM_CLUSTER = /^-[A-Za-z]*[ce]$/
+/** An operand that names the interpreter's own input as the program file. */
+const INPUT_OPERAND = /^(-|\/dev\/stdin|\/dev\/fd\/0|\/proc\/self\/fd\/0)$/
+/** Options that print and exit, so an interpreter without an operand reads no program. */
+const PRINT_AND_EXIT = new Set(['--version', '-v', '-V', '--help', '-h'])
+/** Interpreters that, without an operand, print their help instead of reading a program; they read one after `run`. */
+const SUBCOMMAND_INTERPRETERS = new Set(['bun'])
+const RUN_SUBCOMMAND = 'run'
+/** An operand that names a script file: the words after it are the script's arguments, not the interpreter's options. */
+const SCRIPT_FILE = /\.(py|js|mjs|cjs|ts|mts|cts|jsx|tsx|rb|pl|pm|php|lua)$/i
+
+const isInterpreter = (word: Word): boolean => {
+  const name = programName(word)
+  return INTERPRETERS.has(name) || VERSIONED_PYTHON.test(name)
+}
+
+const isInlineProgramOption = ({ value }: Word): boolean =>
+  INLINE_PROGRAM_OPTIONS.has(value.split('=')[0]) || INLINE_PROGRAM_CLUSTER.test(value)
+
+/** The operand that names the program: the first one, or for `bun run` the one after `run`; `-` counts as one. */
+const programOperand = (interpreter: Word, rest: Word[]): Word | undefined => {
+  const operands = rest.filter((word) => !isOption(word) || word.value === '-')
+  const afterRun = SUBCOMMAND_INTERPRETERS.has(programName(interpreter)) && operands[0]?.value === RUN_SUBCOMMAND
+  return afterRun ? operands[1] : operands[0]
+}
+
+/**
+ * Whether the interpreter reads its program from its input (`python3 -`, `node` fed by a pipe, `bun -`) or from an
+ * expansion it cannot show (`python3 <(…)`).
+ */
+const readsProgramFromInput = (interpreter: Word, rest: Word[]): boolean => {
+  const operand = programOperand(interpreter, rest)
+  if (operand === undefined) {
+    return (
+      !SUBCOMMAND_INTERPRETERS.has(programName(interpreter)) && !rest.some(({ value }) => PRINT_AND_EXIT.has(value))
+    )
+  }
+  // A quoted operand is still a file name; only an expansion (`$f`, `<(…)`) hides where the program comes from.
+  return isExpanded(operand.value) || INPUT_OPERAND.test(operand.value)
+}
+
+/**
+ * The words up to a script file operand. Only a file name ends them: any other word could be an option's value
+ * (`python3 -W ignore -c …`), and stopping there would miss the `-c` behind it.
+ */
+const interpreterOptions = (rest: Word[]): Word[] => {
+  const scriptFile = rest.findIndex((word) => !isOption(word) && SCRIPT_FILE.test(word.value))
+  return scriptFile === -1 ? rest : rest.slice(0, scriptFile)
+}
+
+/**
+ * An interpreter, anywhere a program can stand, handed program text (`python3 -c`, `node -e`) or reading it from its
+ * input (`python3 - <<EOF`, `… | node`): the program can start any command, and no parse of the shell sees it.
+ */
+export const runsInterpreterProgram = (words: SimpleCommand): boolean =>
+  words.some((word, index) => {
+    if (!isProgramPosition(words, index) || !isInterpreter(word)) return false
+    const rest = words.slice(index + 1)
+    return interpreterOptions(rest).some(isInlineProgramOption) || readsProgramFromInput(word, rest)
+  })
+
 /** A shell at the rule start with no script argument reads its script from stdin: a pipe, a here-document. */
 export const readsScriptFromInput = (words: SimpleCommand): boolean => {
   const start = ruleStart(words)
   const shell = words[start]
   return shell !== undefined && isShell(shell) && words.slice(start + 1).every(isOption)
 }
-