@gotgenes/pi-permission-system 35.0.0 → 35.0.2

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [35.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.1...pi-permission-system-v35.0.2) (2026-09-28)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** deny a command written after a heredoc the grammar cannot parse ([8a01239](https://github.com/gotgenes/pi-packages/commit/8a012390b49605ec52ff4379a8f452d3ec48a69e)), closes [#985](https://github.com/gotgenes/pi-packages/issues/985)
+
+## [35.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.0...pi-permission-system-v35.0.1) (2026-09-27)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** check the words after a heredoc against the command's own rules ([0a88264](https://github.com/gotgenes/pi-packages/commit/0a882643bb5b1be1f546842e75ca3fac5cff1930)), closes [#979](https://github.com/gotgenes/pi-packages/issues/979)
+* **pi-permission-system:** gate the commands and redirects written after a heredoc ([b7b2709](https://github.com/gotgenes/pi-packages/commit/b7b27095606c07f684eca353c253b59ebdec4cb4)), closes [#979](https://github.com/gotgenes/pi-packages/issues/979)
+
 ## [35.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v34.0.1...pi-permission-system-v35.0.0) (2026-09-26)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "35.0.0",
+  "version": "35.0.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/bash/heredoc-free-lines.ts

@@ -0,0 +1,153 @@
+import { parseUnresolvedWithin } from "./parse-health";
+import { childrenOf } from "./parse-view";
+import type { TSNode } from "./parser";
+
+/**
+ * The heredoc-free spelling of each line whose heredoc sits in a statement the
+ * primary parse could not resolve, in source order.
+ *
+ * `tree-sitter-bash` 0.25.1's `heredoc_redirect` accepts one tail form after
+ * the delimiter, so valid bash such as `cat <<EOF ; rm -rf x` or
+ * `cat <<EOF arg > /tmp/o` yields an `ERROR` directly under the redirect. The
+ * innermost unresolved node is then the redirect itself, whose own text fails
+ * to re-parse too, so the region salvage recovers nothing and a `deny` on the
+ * command after the heredoc never fires. The same line with its heredoc
+ * operators cut out (`cat ; rm -rf x`, `cat arg > /tmp/o`) is what bash runs
+ * on that line, and it parses.
+ *
+ * A heredoc's host is its nearest `redirected_statement`, or, when no
+ * statement holds it, the nearest enclosing `ERROR` (`cat 0<<EOF | …` lexes
+ * `0<<EOF` as one delimiter inside a top-level `ERROR`). Only a host the parse
+ * could not resolve is spelled, so a clean heredoc beside an unrelated failure
+ * yields nothing. The spelling runs from the host statement's start, or the
+ * heredoc's line start for an `ERROR` host, to the end of the heredoc's line;
+ * the statement anchor is what recovers a heredoc inside a compound opened
+ * earlier on its line (`if true; then cat <<EOF ; rm x`).
+ *
+ * Each cut removes an operator the scanner tokenized: the `<<` / `<<-` token,
+ * a `file_descriptor` before it, the delimiter, and the blanks before them,
+ * so the result reads as its heredoc-free spelling (`cat arg`, not `cat  arg`)
+ * that a rule is written against. It only removes text, and the caller admits
+ * a spelling only when it re-parses cleanly (`unresolved-salvage.ts`).
+ */
+export function heredocFreeLinesWithin(root: TSNode): string[] {
+  const source = root.text;
+  const offset = root.startIndex;
+  const spans = new Map<number, HeredocLine>();
+  for (const heredoc of unresolvedHeredocsWithin(root)) {
+    const start =
+      heredoc.host.type === "redirected_statement"
+        ? heredoc.host.startIndex
+        : lineStartOf(source, offset, heredoc.delimiter.startIndex);
+    const end = lineEndOf(source, offset, heredoc.delimiter.endIndex);
+    const line = spans.get(start) ?? { start, end, cuts: [] };
+    line.cuts.push(operatorSpanOf(heredoc, source, offset, start));
+    spans.set(start, line);
+  }
+  return [...spans.values()].map((line) => spell(line, source, offset));
+}
+
+interface UnresolvedHeredoc {
+  /** The `heredoc_start` token. */
+  readonly delimiter: TSNode;
+  /** The delimiter's siblings, in order, so its operator can be found. */
+  readonly siblings: readonly TSNode[];
+  readonly index: number;
+  readonly host: TSNode;
+}
+
+interface HeredocLine {
+  readonly start: number;
+  readonly end: number;
+  readonly cuts: [number, number][];
+}
+
+function unresolvedHeredocsWithin(root: TSNode): UnresolvedHeredoc[] {
+  const found: UnresolvedHeredoc[] = [];
+  collectUnresolvedHeredocs(root, null, null, found);
+  return found;
+}
+
+/**
+ * Descends every node, `ERROR`s included: the `heredoc_start` token is the
+ * scanner's rather than recovery's invention, and it can sit inside one.
+ */
+function collectUnresolvedHeredocs(
+  node: TSNode,
+  statement: TSNode | null,
+  error: TSNode | null,
+  found: UnresolvedHeredoc[],
+): void {
+  const siblings = childrenOf(node);
+  siblings.forEach((child, index) => {
+    const host = statement ?? error;
+    if (
+      child.type === "heredoc_start" &&
+      host !== null &&
+      parseUnresolvedWithin(host)
+    ) {
+      found.push({ delimiter: child, siblings, index, host });
+    }
+    collectUnresolvedHeredocs(
+      child,
+      child.type === "redirected_statement" ? child : statement,
+      child.type === "ERROR" ? child : error,
+      found,
+    );
+  });
+}
+
+/**
+ * The span of a heredoc's operator: its delimiter, the `<<` / `<<-` token and
+ * a `file_descriptor` before it, and the blanks before those, but never
+ * reaching before the line's own start.
+ */
+function operatorSpanOf(
+  heredoc: UnresolvedHeredoc,
+  source: string,
+  offset: number,
+  lineStart: number,
+): [number, number] {
+  const { delimiter, siblings, index } = heredoc;
+  let start = delimiter.startIndex;
+  let before = index - 1;
+  const operator = siblings.at(before);
+  if (
+    before >= 0 &&
+    operator &&
+    !operator.isNamed &&
+    operator.text.startsWith("<<")
+  ) {
+    start = operator.startIndex;
+    before -= 1;
+    const descriptor = siblings.at(before);
+    if (before >= 0 && descriptor?.type === "file_descriptor") {
+      start = descriptor.startIndex;
+    }
+  }
+  while (start > lineStart && isBlank(source[start - 1 - offset])) start -= 1;
+  return [start, delimiter.endIndex];
+}
+
+function spell(line: HeredocLine, source: string, offset: number): string {
+  let text = "";
+  let at = line.start;
+  for (const [cutStart, cutEnd] of line.cuts.toSorted(([a], [b]) => a - b)) {
+    text += source.slice(at - offset, cutStart - offset);
+    at = cutEnd;
+  }
+  return text + source.slice(at - offset, line.end - offset);
+}
+
+function lineStartOf(source: string, offset: number, index: number): number {
+  return source.lastIndexOf("\n", index - offset - 1) + 1 + offset;
+}
+
+function lineEndOf(source: string, offset: number, index: number): number {
+  const newline = source.indexOf("\n", index - offset);
+  return (newline === -1 ? source.length : newline) + offset;
+}
+
+function isBlank(character: string | undefined): boolean {
+  return character === " " || character === "\t";
+}

package/src/access-intent/bash/heredoc-tails.ts

@@ -0,0 +1,277 @@
+import {
+  childrenOf,
+  rewriteStatements,
+  rewrittenNode,
+  type Source,
+  sourceOf,
+} from "./parse-view";
+import type { TSNode } from "./parser";
+
+/**
+ * `tree-sitter-bash`'s parse with the rest of each heredoc's line moved out of
+ * the heredoc, to where the grammar puts it when the heredoc is written as a
+ * plain input redirect.
+ *
+ * The grammar (0.25.1) lets a `heredoc_redirect` carry whatever follows its
+ * delimiter on the same line: further redirects (`cat <<EOF > /tmp/o`), a
+ * `| …` statement, or an `&& …` / `|| …` statement. They parse as children of
+ * the heredoc, which every walker reads only for the substitutions it hosts, so
+ * `cat <<EOF | rm -rf /tmp/x` would enumerate as `cat` alone and
+ * `cat <<EOF > /tmp/o` would project no path (#979).
+ *
+ * The corrected tree is the grammar's own parse of the same line with `< in` in
+ * place of `<<EOF`: a redirect becomes a sibling after the heredoc, and a
+ * `| …` or `&& …` statement is joined to the redirected statement the way the
+ * grammar joins it to `cat < in`. That reproduces the grammar's groupings
+ * rather than bash's where the two differ (a redirect on a list's last command
+ * hangs off the whole list), because every walker is already built to read
+ * those groupings.
+ *
+ * Words after the delimiter (`git <<EOF push --force`) stay in the heredoc:
+ * `reattachRedirectArguments` hands them to the command, exactly as it does for
+ * the words after a file redirect's target. The heredoc keeps its body, which
+ * is written after the rest of the line, so it ends after the nodes moved out
+ * of it.
+ *
+ * Returns `root` itself when no heredoc carries such a tail.
+ */
+export function hoistHeredocTails(root: TSNode): TSNode {
+  return rewriteStatements(root, hoistStatement);
+}
+
+/**
+ * `statement` with its heredoc's tail moved out, or `undefined` when no
+ * heredoc among `children` carries one.
+ */
+function hoistStatement(
+  statement: TSNode,
+  children: readonly TSNode[],
+): TSNode | undefined {
+  const heredocIndex = children.findIndex(
+    (child) => child.type === "heredoc_redirect" && tailOf(child) !== undefined,
+  );
+  const heredoc = children.at(heredocIndex);
+  const tail = heredoc && tailOf(heredoc);
+  if (!tail) return undefined;
+
+  const after = children.slice(heredocIndex + 1);
+  // A statement tail runs to the end of the line, so nothing of the statement
+  // can follow it; anything that does is a shape this correction does not know.
+  if (tail.joined && after.some((child) => child.isNamed)) return undefined;
+
+  const source = sourceOf(statement);
+  const redirected = rewrittenNode(
+    statement,
+    [
+      ...children.slice(0, heredocIndex),
+      rewrittenNode(
+        heredoc,
+        tail.kept,
+        heredoc.startIndex,
+        heredoc.endIndex,
+        source,
+      ),
+      ...tail.redirects,
+      ...after,
+    ],
+    statement.startIndex,
+    statement.endIndex,
+    source,
+  );
+  if (!tail.joined) return redirected;
+  return join(
+    redirected,
+    tail.joined.operator,
+    withTrailingRedirectsOutermost(tail.joined.statement, source),
+    source,
+  );
+}
+
+/**
+ * `statement` with a redirect written at its end hung off all of it, as the
+ * grammar hangs it when the same text is not a heredoc's tail.
+ *
+ * At the top level `a | b | c > o` parses as `(a | b | c) > o`, but in a
+ * heredoc's tail the grammar parses it as `a | ((b | c) > o)`. Left that way,
+ * the joined write would not reach the heredoc's own command, so
+ * `xargs grep foo <<EOF && a | b | c > o` would keep a floor exemption that
+ * `xargs grep foo < in && a | b | c > o` withholds.
+ */
+function withTrailingRedirectsOutermost(
+  statement: TSNode,
+  source: Source,
+): TSNode {
+  if (statement.type === "redirected_statement") return statement;
+  const detached = detachTrailingRedirects(statement, source);
+  if (!detached) return statement;
+  return rewrittenNode(
+    { type: "redirected_statement", isNamed: true },
+    [detached.body, ...detached.redirects],
+    statement.startIndex,
+    statement.endIndex,
+    source,
+  );
+}
+
+/**
+ * `node` without the `redirected_statement` that ends it, plus that
+ * statement's redirects, or `undefined` when `node` does not end in one.
+ *
+ * The walk follows the last element of each `list` and `pipeline`, and a
+ * pipeline left holding a pipeline is flattened into one, as the grammar
+ * parses `a | b | c`.
+ */
+function detachTrailingRedirects(
+  node: TSNode,
+  source: Source,
+): { body: TSNode; redirects: TSNode[] } | undefined {
+  const children = childrenOf(node);
+  if (node.type === "redirected_statement") {
+    const bodyIndex = children.findIndex((child) => child.isNamed);
+    return {
+      body: children[bodyIndex],
+      redirects: children.slice(bodyIndex + 1),
+    };
+  }
+  if (!GROUPING_TYPES.has(node.type)) return undefined;
+  const lastIndex = children.findLastIndex((child) => child.isNamed);
+  const inner = detachTrailingRedirects(children[lastIndex], source);
+  if (!inner) return undefined;
+  const replaced =
+    node.type === "pipeline" && inner.body.type === "pipeline"
+      ? [...children.slice(0, lastIndex), ...childrenOf(inner.body)]
+      : children.with(lastIndex, inner.body);
+  return {
+    body: rewrittenNode(
+      node,
+      replaced,
+      node.startIndex,
+      inner.body.endIndex,
+      source,
+    ),
+    redirects: inner.redirects,
+  };
+}
+
+/** The groupings whose last element a trailing redirect is written after. */
+const GROUPING_TYPES: ReadonlySet<string> = new Set(["list", "pipeline"]);
+
+/** What a heredoc carries after its delimiter, split by where each part goes. */
+interface HeredocTail {
+  /** The heredoc's own children: operator, delimiter, any words, and body. */
+  readonly kept: readonly TSNode[];
+  /** Redirects written after the delimiter. */
+  readonly redirects: readonly TSNode[];
+  /** A `| …`, `|& …`, `&& …`, or `|| …` statement after them, if any. */
+  readonly joined?: {
+    readonly operator: TSNode;
+    readonly statement: TSNode;
+  };
+}
+
+/**
+ * `heredoc`'s tail, or `undefined` when it carries neither a redirect nor a
+ * statement after its delimiter.
+ *
+ * The grammar spells a `| …` tail as one `pipeline` child holding the operator
+ * and the statement, and an `&& …` / `|| …` tail as the operator token and the
+ * statement as two children of the heredoc itself. That statement can be a
+ * pipeline too (`cat <<EOF && ls | rm x`), so a `pipeline` child is the `| …`
+ * form only when no operator came before it.
+ */
+function tailOf(heredoc: TSNode): HeredocTail | undefined {
+  const kept: TSNode[] = [];
+  const redirects: TSNode[] = [];
+  let operator: TSNode | undefined;
+  let statement: TSNode | undefined;
+  for (const child of childrenOf(heredoc)) {
+    if (TAIL_REDIRECT_TYPES.has(child.type)) {
+      redirects.push(child);
+    } else if (child.type === "pipeline" && !operator) {
+      const [pipe] = childrenOf(child);
+      operator = pipe;
+      statement = childrenOf(child).find((node) => node.isNamed);
+    } else if (LIST_OPERATORS.has(child.type) && !child.isNamed) {
+      operator = child;
+    } else if (operator && !statement && child.isNamed) {
+      statement = child;
+    } else {
+      kept.push(child);
+    }
+  }
+  if (operator && !statement) return undefined;
+  const joined = operator && statement ? { operator, statement } : undefined;
+  if (redirects.length === 0 && !joined) return undefined;
+  return joined ? { kept, redirects, joined } : { kept, redirects };
+}
+
+/** The redirects a heredoc can carry after its delimiter. */
+const TAIL_REDIRECT_TYPES: ReadonlySet<string> = new Set([
+  "file_redirect",
+  "herestring_redirect",
+]);
+
+/** The operators that join an `&& …` / `|| …` tail. */
+const LIST_OPERATORS: ReadonlySet<string> = new Set(["&&", "||"]);
+
+/** The operators that join a `| …` tail. */
+const PIPE_OPERATORS: ReadonlySet<string> = new Set(["|", "|&"]);
+
+/**
+ * `redirected` joined to `statement` by `operator`, grouped as the grammar
+ * groups `cat < in <operator> <statement>`.
+ *
+ * The grammar hangs a redirect off everything before it, so a joined
+ * `redirected_statement` keeps its redirects outermost. That holds inside a
+ * pipeline too: `cat < in && a > o | b` parses as `(cat < in && a > o) | b`,
+ * so a pipeline whose first stage is redirected is joined at that stage. A
+ * `list` is left-associative and binds looser than a pipe, so the join reaches
+ * its first element. A pipe tail onto any other pipeline extends it. Anything
+ * else becomes the operator's own two-element node.
+ *
+ * Each rebuilt node spans from `redirected`'s start to the furthest end beneath
+ * it, which is the heredoc's, since its body is written after the tail.
+ */
+function join(
+  redirected: TSNode,
+  operator: TSNode,
+  statement: TSNode,
+  source: Source,
+): TSNode {
+  const isPipe = PIPE_OPERATORS.has(operator.type);
+  const children = childrenOf(statement);
+  const end = Math.max(redirected.endIndex, statement.endIndex);
+  const rebuild = (type: Pick<TSNode, "type" | "isNamed">, kids: TSNode[]) =>
+    rewrittenNode(type, kids, redirected.startIndex, end, source);
+
+  const first = children.findIndex((child) => child.isNamed);
+  if (joinsAtFirstElement(statement, children[first])) {
+    return rebuild(
+      statement,
+      children.with(first, join(redirected, operator, children[first], source)),
+    );
+  }
+  if (isPipe && statement.type === "pipeline") {
+    return rebuild(statement, [redirected, operator, ...children]);
+  }
+  return rebuild({ type: isPipe ? "pipeline" : "list", isNamed: true }, [
+    redirected,
+    operator,
+    statement,
+  ]);
+}
+
+/**
+ * Whether the grammar joins what precedes `statement` to its first element
+ * rather than to `statement` as a whole.
+ */
+function joinsAtFirstElement(
+  statement: TSNode,
+  first: TSNode | undefined,
+): boolean {
+  if (statement.type === "redirected_statement") return true;
+  if (statement.type === "list") return true;
+  return (
+    statement.type === "pipeline" && first?.type === "redirected_statement"
+  );
+}

package/src/access-intent/bash/parse-view.ts

@@ -0,0 +1,180 @@
+import { parseUnresolvedWithin } from "./parse-health";
+import type { TSNode } from "./parser";
+
+/**
+ * A view of `tree-sitter-bash`'s parse tree that a correction pass can rewrite.
+ *
+ * The grammar hangs command-line material on the wrong node in more than one
+ * production (#977, #979), and each correction is a pass that rewrites the
+ * `redirected_statement`s it recognizes. Each pass builds its nodes from the
+ * primitives here, so a later pass reads an earlier one's output as the same
+ * kind of view and can re-parent its nodes in turn.
+ *
+ * A view reads its text from the source by absolute offsets, so every caller's
+ * `startIndex`/`endIndex` slicing still holds.
+ */
+
+/**
+ * `root` with each `redirected_statement` whose parse resolved replaced by what
+ * `rewrite` returns for it, or `root` itself when nothing beneath it changed.
+ *
+ * The walk is bottom-up: `rewrite` receives the statement's children already
+ * rewritten, and returns `undefined` to leave the statement as it is.
+ *
+ * A statement whose parse failed is never handed to `rewrite`. Its units are
+ * floored already, and moving a node out of an unresolvable region would hand it
+ * a proof in place of that region's refusal to prove one (#814).
+ */
+export function rewriteStatements(
+  root: TSNode,
+  rewrite: (
+    statement: TSNode,
+    children: readonly TSNode[],
+  ) => TSNode | undefined,
+): TSNode {
+  return rewriteBeneath(root, rewrite) ?? root;
+}
+
+/** The rewritten node, or `undefined` when nothing beneath `node` changed. */
+function rewriteBeneath(
+  node: TSNode,
+  rewrite: (
+    statement: TSNode,
+    children: readonly TSNode[],
+  ) => TSNode | undefined,
+): TSNode | undefined {
+  const children: TSNode[] = [];
+  let changed = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    const rewritten = rewriteBeneath(child, rewrite);
+    if (rewritten) changed = true;
+    children.push(rewritten ?? child);
+  }
+
+  if (node.type === "redirected_statement" && !parseUnresolvedWithin(node)) {
+    const rewritten = rewrite(node, children);
+    if (rewritten) return rewritten;
+  }
+  return changed
+    ? adoptingView(node, children, parseUnresolvedWithin(node))
+    : undefined;
+}
+
+/** A node a correction built, reading its text from the statement's source. */
+export function rewrittenNode(
+  original: Pick<TSNode, "type" | "isNamed">,
+  children: readonly TSNode[],
+  startIndex: number,
+  endIndex: number,
+  source: Source,
+): TSNode {
+  return adoptingView(
+    {
+      type: original.type,
+      isNamed: original.isNamed,
+      startIndex,
+      endIndex,
+      text: source(startIndex, endIndex),
+    },
+    children,
+    false,
+  );
+}
+
+/** A slice of the command by absolute offsets. */
+export type Source = (startIndex: number, endIndex: number) => string;
+
+/** The source slicer for every node within `statement`. */
+export function sourceOf(statement: TSNode): Source {
+  return (startIndex, endIndex) =>
+    statement.text.slice(
+      startIndex - statement.startIndex,
+      endIndex - statement.startIndex,
+    );
+}
+
+export function childrenOf(node: TSNode): TSNode[] {
+  const children: TSNode[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) children.push(child);
+  }
+  return children;
+}
+
+export function lastNamedChild(node: TSNode): TSNode | undefined {
+  return childrenOf(node).findLast((child) => child.isNamed);
+}
+
+/**
+ * A view whose children are views too, so each one's `previousSibling` is its
+ * neighbor in the rewritten tree rather than the one the grammar gave it.
+ */
+function adoptingView(
+  fields: NodeFields,
+  children: readonly TSNode[],
+  hasError: boolean,
+): TSNode {
+  return new NodeView(fields, children.map(asView), hasError);
+}
+
+/**
+ * `node` as a view, so a new parent can give it a new previous sibling.
+ *
+ * Its own children stay the grammar's nodes: nothing beneath it moved, so their
+ * siblings are still the grammar's too.
+ */
+function asView(node: TSNode): TSNode {
+  return node instanceof NodeView
+    ? node
+    : new NodeView(node, childrenOf(node), parseUnresolvedWithin(node));
+}
+
+/** The fields a {@link NodeView} copies from the node it stands for. */
+interface NodeFields {
+  readonly type: string;
+  readonly isNamed: boolean;
+  readonly startIndex: number;
+  readonly endIndex: number;
+  readonly text: string;
+}
+
+/**
+ * A parse-tree node a correction presents in place of the grammar's.
+ *
+ * Adopting its children sets each view child's `previousSibling` to the child
+ * before it, which is what lets a redirect moved into a command ask
+ * `parseUnresolvedAt` about its new neighbor.
+ */
+class NodeView implements TSNode {
+  readonly type: string;
+  readonly isNamed: boolean;
+  readonly startIndex: number;
+  readonly endIndex: number;
+  readonly text: string;
+  readonly childCount: number;
+  previousSibling: TSNode | null = null;
+
+  constructor(
+    fields: NodeFields,
+    private readonly children: readonly TSNode[],
+    readonly hasError: boolean,
+  ) {
+    this.type = fields.type;
+    this.isNamed = fields.isNamed;
+    this.startIndex = fields.startIndex;
+    this.endIndex = fields.endIndex;
+    this.text = fields.text;
+    this.childCount = children.length;
+    children.forEach((child, i) => {
+      if (child instanceof NodeView)
+        child.previousSibling = children[i - 1] ?? null;
+    });
+  }
+
+  child(index: number): TSNode | null {
+    return this.children[index] ?? null;
+  }
+}

package/src/access-intent/bash/parser.ts

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
 import { memoizeAsyncWithRetry } from "./async-cache";
+import { hoistHeredocTails } from "./heredoc-tails";
 import { reattachRedirectArguments } from "./redirect-arguments";
 
 /**
@@ -69,11 +70,19 @@ async function initParser(): Promise<TSParser> {
 /**
  * The parser every consumer reads the bash grammar through.
  *
- * Its trees are the grammar's with one correction applied where they enter the
- * package: a word `tree-sitter-bash` hung on a redirect is handed back to the
- * command it belongs to (`reattachRedirectArguments`, #977). Every walker, the
- * salvage re-parse, and the log masker read that corrected tree, so none of
- * them has to learn the grammar's quirk on its own.
+ * Its trees are the grammar's with two corrections applied where they enter the
+ * package, each moving command-line material `tree-sitter-bash` hangs on a
+ * redirect to where bash gives it:
+ *
+ * 1. `hoistHeredocTails` moves the redirects and the `| …` / `&& …` statement
+ *    written after a heredoc's delimiter out of the heredoc (#979).
+ * 2. `reattachRedirectArguments` hands the words a redirect carries, a file
+ *    redirect's or a heredoc's, back to the command (#977).
+ *
+ * The order matters: a redirect hoisted out of a heredoc can itself carry the
+ * command's words (`cat <<EOF 2>/dev/null arg`), which the second pass then
+ * hands back. Every walker, the salvage re-parse, and the log masker read the
+ * corrected tree, so none of them has to learn the grammar's quirks on its own.
  */
 export const getParser = memoizeAsyncWithRetry(async () =>
   correctingParser(await getGrammarParser()),
@@ -85,7 +94,7 @@ function correctingParser(grammar: TSParser): TSParser {
       const tree = grammar.parse(input);
       if (!tree) return null;
       return {
-        rootNode: reattachRedirectArguments(tree.rootNode),
+        rootNode: reattachRedirectArguments(hoistHeredocTails(tree.rootNode)),
         delete: () => {
           tree.delete();
         },

package/src/access-intent/bash/redirect-analysis.ts

@@ -138,18 +138,49 @@ export function redirectTargetIndex(redirect: TSNode): number | undefined {
  * The child index of the first word the grammar appended after `redirect`'s
  * own target, or `undefined` when none follows.
  *
- * Every named child from there on is a word bash passes to the redirected
- * command rather than a destination of the redirect: `f.txt` in
+ * Every {@link LITERAL_NODE_TYPES} child from there on is a word bash passes to
+ * the redirected command rather than a destination of the redirect: `f.txt` in
  * `grep pat 2>/dev/null f.txt`, and `arg` in `cmd >&- arg`, where the close
  * operator has no target at all (#977).
+ *
+ * A heredoc carries them the same way: `git <<EOF push --force` hangs `push`
+ * and `--force` after its delimiter, where its own target would be. Its body
+ * follows them and is not a word, and neither is any other tail the grammar
+ * lets a heredoc carry (a redirect, a `| …` or `&& …` statement), so the first
+ * child after the target counts only when it is a literal (#979).
  */
 export function trailingArgumentIndex(redirect: TSNode): number | undefined {
   const operator = redirectOperatorIndex(redirect);
   if (operator === undefined) return undefined;
   const target = redirectTargetIndex(redirect);
-  return namedChildIndexAfter(redirect, target ?? operator);
+  const index = namedChildIndexAfter(redirect, target ?? operator);
+  if (index === undefined) return undefined;
+  return LITERAL_NODE_TYPES.has(redirect.child(index)?.type ?? "")
+    ? index
+    : undefined;
 }
 
+/**
+ * The node types `tree-sitter-bash` 0.25.1 parses a literal word as: its
+ * `_literal` rule, which a file redirect's destinations and a heredoc's
+ * trailing words are both declared as.
+ */
+export const LITERAL_NODE_TYPES: ReadonlySet<string> = new Set([
+  "concatenation",
+  "word",
+  "string",
+  "raw_string",
+  "translated_string",
+  "ansi_c_string",
+  "number",
+  "expansion",
+  "simple_expansion",
+  "command_substitution",
+  "process_substitution",
+  "arithmetic_expansion",
+  "brace_expression",
+]);
+
 /** Operators that close a descriptor, naming no file (`>&-`, `<&-`). */
 const CLOSE_OPERATORS: ReadonlySet<string> = new Set([">&-", "<&-"]);
 

package/src/access-intent/bash/redirect-arguments.ts

@@ -1,6 +1,13 @@
-import { parseUnresolvedWithin } from "./parse-health";
+import {
+  childrenOf,
+  lastNamedChild,
+  rewriteStatements,
+  rewrittenNode,
+  type Source,
+  sourceOf,
+} from "./parse-view";
 import type { TSNode } from "./parser";
-import { trailingArgumentIndex } from "./redirect-analysis";
+import { LITERAL_NODE_TYPES, trailingArgumentIndex } from "./redirect-analysis";
 
 /**
  * `tree-sitter-bash`'s parse with each word it hung on a redirect handed back
@@ -21,6 +28,11 @@ import { trailingArgumentIndex } from "./redirect-analysis";
  * followed by its words; a redirect after the last word stays at the
  * statement, and a statement left with no redirect gives way to its body.
  *
+ * A heredoc carries words the same way (`git <<EOF push --force`), and they
+ * move into the command after it; its body stays in the heredoc, which is
+ * written after the words and so ends after them (#979). Every other tail a
+ * heredoc can carry is `heredoc-tails.ts`'s to move.
+ *
  * Three kinds of statement are left exactly as the grammar produced them:
  *
  * - One whose parse failed. Its units are floored already, and moving a word
@@ -35,28 +47,7 @@ import { trailingArgumentIndex } from "./redirect-analysis";
  * stay positions in the command string every caller already slices.
  */
 export function reattachRedirectArguments(root: TSNode): TSNode {
-  return correct(root) ?? root;
-}
-
-/** The corrected node, or `undefined` when nothing beneath `node` changed. */
-function correct(node: TSNode): TSNode | undefined {
-  const children: TSNode[] = [];
-  let changed = false;
-  for (let i = 0; i < node.childCount; i++) {
-    const child = node.child(i);
-    if (!child) continue;
-    const corrected = correct(child);
-    if (corrected) changed = true;
-    children.push(corrected ?? child);
-  }
-
-  if (node.type === "redirected_statement" && !parseUnresolvedWithin(node)) {
-    const reattached = reattachStatement(node, children);
-    if (reattached) return reattached;
-  }
-  return changed
-    ? adoptingView(node, children, parseUnresolvedWithin(node))
-    : undefined;
+  return rewriteStatements(root, reattachStatement);
 }
 
 /**
@@ -74,7 +65,7 @@ function reattachStatement(
 
   const lastCarrier = children.findLastIndex(
     (child) =>
-      child.type === "file_redirect" &&
+      WORD_CARRYING_TYPES.has(child.type) &&
       trailingArgumentIndex(child) !== undefined,
   );
   if (lastCarrier === -1) return undefined;
@@ -112,23 +103,34 @@ function reachesCommand(body: TSNode): boolean {
 /** The bodies whose last element a statement-level redirect belongs to. */
 const GROUPING_TYPES: ReadonlySet<string> = new Set(["list", "pipeline"]);
 
+/** The redirects the grammar can hang a command's words on. */
+const WORD_CARRYING_TYPES: ReadonlySet<string> = new Set([
+  "file_redirect",
+  "heredoc_redirect",
+]);
+
 /**
- * `redirect` as it belongs in the command: truncated after its own target and
- * followed by the words the grammar appended to it. A redirect carrying no
- * words, or a node that is not a file redirect, moves as it is.
+ * `redirect` as it belongs in the command: without the words the grammar
+ * appended to it, and followed by them. A redirect carrying no words, or a node
+ * that cannot carry any, moves as it is.
+ *
+ * A file redirect's words are the rest of its children, so it is truncated
+ * after its target. A heredoc keeps its body and delimiter, which follow the
+ * words in the source, so it keeps its own end.
  */
 function splitRedirect(redirect: TSNode, source: Source): TSNode[] {
-  const trailing =
-    redirect.type === "file_redirect"
-      ? trailingArgumentIndex(redirect)
-      : undefined;
+  const trailing = WORD_CARRYING_TYPES.has(redirect.type)
+    ? trailingArgumentIndex(redirect)
+    : undefined;
   if (trailing === undefined) return [redirect];
 
   const kept: TSNode[] = [];
   const words: TSNode[] = [];
   for (let i = 0; i < redirect.childCount; i++) {
     const child = redirect.child(i);
-    if (child) (i < trailing ? kept : words).push(child);
+    if (!child) continue;
+    const isWord = i >= trailing && LITERAL_NODE_TYPES.has(child.type);
+    (isWord ? words : kept).push(child);
   }
   const end = kept.at(-1)?.endIndex ?? redirect.startIndex;
   return [
@@ -139,8 +141,9 @@ function splitRedirect(redirect: TSNode, source: Source): TSNode[] {
 
 /**
  * `body` with `moved` appended to its rightmost command: the command itself,
- * or the last element of a `list` or `pipeline`, recursively. Each node on the way grows to
- * the end of the last moved node.
+ * or the last element of a `list` or `pipeline`, recursively. Each node on the
+ * way grows to the furthest end among the moved nodes, which is a heredoc's
+ * when one moved, since its body is written after the words that follow it.
  */
 function appendToRightmostCommand(
   body: TSNode,
@@ -148,7 +151,7 @@ function appendToRightmostCommand(
   source: Source,
 ): TSNode {
   const children = childrenOf(body);
-  const end = moved.at(-1)?.endIndex ?? body.endIndex;
+  const end = Math.max(body.endIndex, ...moved.map((node) => node.endIndex));
   if (body.type === "command") {
     return rewrittenNode(
       body,
@@ -166,120 +169,3 @@ function appendToRightmostCommand(
   );
   return rewrittenNode(body, replaced, body.startIndex, end, source);
 }
-
-/** A node the correction built, reading its text from the statement's source. */
-function rewrittenNode(
-  original: TSNode,
-  children: readonly TSNode[],
-  startIndex: number,
-  endIndex: number,
-  source: Source,
-): TSNode {
-  return adoptingView(
-    {
-      type: original.type,
-      isNamed: original.isNamed,
-      startIndex,
-      endIndex,
-      text: source(startIndex, endIndex),
-    },
-    children,
-    false,
-  );
-}
-
-/**
- * A view whose children are views too, so each one's `previousSibling` is its
- * neighbor in the corrected tree rather than the one the grammar gave it.
- */
-function adoptingView(
-  fields: NodeFields,
-  children: readonly TSNode[],
-  hasError: boolean,
-): TSNode {
-  return new NodeView(fields, children.map(asView), hasError);
-}
-
-/** A slice of the command by absolute offsets. */
-type Source = (startIndex: number, endIndex: number) => string;
-
-/** The source slicer for every node within `statement`. */
-function sourceOf(statement: TSNode): Source {
-  return (startIndex, endIndex) =>
-    statement.text.slice(
-      startIndex - statement.startIndex,
-      endIndex - statement.startIndex,
-    );
-}
-
-function childrenOf(node: TSNode): TSNode[] {
-  const children: TSNode[] = [];
-  for (let i = 0; i < node.childCount; i++) {
-    const child = node.child(i);
-    if (child) children.push(child);
-  }
-  return children;
-}
-
-function lastNamedChild(node: TSNode): TSNode | undefined {
-  return childrenOf(node).findLast((child) => child.isNamed);
-}
-
-/**
- * `node` as a view, so a new parent can give it a new previous sibling.
- *
- * Its own children stay the grammar's nodes: nothing beneath it moved, so their
- * siblings are still the grammar's too.
- */
-function asView(node: TSNode): TSNode {
-  return node instanceof NodeView
-    ? node
-    : new NodeView(node, childrenOf(node), parseUnresolvedWithin(node));
-}
-
-/** The fields a {@link NodeView} copies from the node it stands for. */
-interface NodeFields {
-  readonly type: string;
-  readonly isNamed: boolean;
-  readonly startIndex: number;
-  readonly endIndex: number;
-  readonly text: string;
-}
-
-/**
- * A parse-tree node the correction presents in place of the grammar's.
- *
- * Adopting its children sets each view child's `previousSibling` to the child
- * before it, which is what lets a redirect moved into a command ask
- * `parseUnresolvedAt` about its new neighbor.
- */
-class NodeView implements TSNode {
-  readonly type: string;
-  readonly isNamed: boolean;
-  readonly startIndex: number;
-  readonly endIndex: number;
-  readonly text: string;
-  readonly childCount: number;
-  previousSibling: TSNode | null = null;
-
-  constructor(
-    fields: NodeFields,
-    private readonly children: readonly TSNode[],
-    readonly hasError: boolean,
-  ) {
-    this.type = fields.type;
-    this.isNamed = fields.isNamed;
-    this.startIndex = fields.startIndex;
-    this.endIndex = fields.endIndex;
-    this.text = fields.text;
-    this.childCount = children.length;
-    children.forEach((child, i) => {
-      if (child instanceof NodeView)
-        child.previousSibling = children[i - 1] ?? null;
-    });
-  }
-
-  child(index: number): TSNode | null {
-    return this.children[index] ?? null;
-  }
-}

package/src/access-intent/bash/unresolved-salvage.ts

@@ -1,3 +1,4 @@
+import { heredocFreeLinesWithin } from "./heredoc-free-lines";
 import { parseUnresolvedWithin } from "./parse-health";
 import type { BashReparser, TSNode } from "./parser";
 
@@ -19,6 +20,12 @@ import type { BashReparser, TSNode } from "./parser";
  * grammar gap is in the *combination* — `2>&1 | rm -rf /tmp/x` parses
  * perfectly on its own.
  *
+ * A heredoc tail the grammar cannot parse at all (`cat <<EOF ; rm -rf x`)
+ * leaves no region whose own text re-parses: the innermost unresolved node is
+ * the heredoc redirect, whose text fails the same way. So each such heredoc's
+ * line is offered too, spelled without its heredoc operators
+ * (`heredoc-free-lines.ts`), after the regions.
+ *
  * The roots are handed to a callback rather than returned because each belongs
  * to a tree that must outlive its use and be released afterwards, exactly as
  * the primary parse's caller already does for its own tree.
@@ -33,14 +40,20 @@ export function withSalvagedRoots<T>(
 ): T {
   const trees: { rootNode: TSNode; delete(): void }[] = [];
   try {
-    for (const candidate of unresolvedRegionsWithin(primary)) {
-      const tree = reparser.parse(candidate.text);
+    const candidates = [
+      ...unresolvedRegionsWithin(primary).map((region) => region.text),
+      ...heredocFreeLinesWithin(primary),
+    ];
+    for (const text of candidates) {
+      const tree = reparser.parse(text);
       if (!tree) continue;
       // The whole safety argument: tree-sitter's error recovery *invents* the
       // structure inside an unresolved region (#742), and invented structure
       // does not re-parse. Without this check `cat <> rw.txt` salvages a
       // command unit whose text is `">"`, matched against the bash rules like
-      // any real command.
+      // any real command. A heredoc-free line is derived rather than sliced,
+      // but only by removing the operators the scanner tokenized, and it is
+      // held to the same condition.
       if (parseUnresolvedWithin(tree.rootNode)) {
         tree.delete();
         continue;