@patronage/factory-ci 0.2.1 → 1.0.0-alpha.13

package/src/workflow-shell-lint.ts

@@ -0,0 +1,462 @@
+import { execFileSync } from "node:child_process";
+
+/**
+ * Parse-check the shell embedded in generated workflow YAML (#376).
+ *
+ * The generated-workflow lint validates YAML shape. It never parses the shell
+ * inside a `run:` block, so a script that cannot execute at all — a stray
+ * `fi`, an unclosed quote, a `then` with no `if` — passes every local check
+ * and only fails when the runner reaches it. That is not hypothetical:
+ * paitronage#1090 shipped a stray `fi` into a generated workflow and made
+ * every automated preview destroy a parse-time no-op for five days.
+ *
+ * `bash -n` is the whole control: it parses without executing. It lives here,
+ * once, rather than as a contract test in each consumer, because a guard
+ * copied per repository is a guard that exists in some of them.
+ */
+
+/** One `run:` block that bash refuses to parse. */
+export interface WorkflowShellParseFailure {
+  /** The step's `name:` when the YAML carried one. */
+  readonly step?: string;
+  /** The script as bash saw it, expressions already neutralized. */
+  readonly script: string;
+  /** What bash said. */
+  readonly stderr: string;
+}
+
+/** A `run:` block lifted out of generated YAML, with its step's `shell:`. */
+interface RunBlock {
+  readonly script: string;
+  readonly shell?: string;
+  readonly step?: string;
+}
+
+const RUN_KEY = /^(?<indent>\s*)(?:-\s+)?run:(?<inline>.*)$/u;
+
+/**
+ * GitHub evaluates `${{ }}` before bash ever sees the script, and what it
+ * substitutes is not knowable here. Neutralizing each expression to one plain
+ * word is what the runner's *shape* looks like: a value in argument position.
+ * Leaving them in would make every workflow fail to parse; expanding them to
+ * nothing would silently change quoting.
+ *
+ * Scanned rather than matched with a lazy regex, because `}}` occurs inside
+ * Actions string literals: `format('refs/{{0}}', github.ref_name)` escapes a
+ * literal brace pair that way, and stopping there would leave half an
+ * expression in the script and report a parse error the runner never sees.
+ */
+const neutralizeExpressions = (script: string): string => {
+  let out = "";
+  let cursor = 0;
+
+  while (cursor < script.length) {
+    const start = script.indexOf("${{", cursor);
+    if (start === -1) {
+      out += script.slice(cursor);
+      break;
+    }
+    out += script.slice(cursor, start);
+
+    let scan = start + 3;
+    let quote: string | undefined;
+    let end = -1;
+    while (scan < script.length) {
+      const char = script[scan];
+      if (quote === undefined) {
+        if (char === "'" || char === '"') {
+          quote = char;
+        } else if (char === "}" && script[scan + 1] === "}") {
+          end = scan + 2;
+          break;
+        }
+      } else if (char === quote) {
+        // Doubling is how both Actions string literals escape their quote.
+        if (script[scan + 1] === quote) {
+          scan += 1;
+        } else {
+          quote = undefined;
+        }
+      }
+      scan += 1;
+    }
+
+    if (end === -1) {
+      // Unterminated: leave it verbatim so bash reports the truth about a
+      // script GitHub would also refuse to substitute.
+      out += script.slice(start);
+      break;
+    }
+    out += "FACTORY_ACTIONS_EXPRESSION";
+    cursor = end;
+  }
+
+  return out;
+};
+
+/** Strip one layer of YAML single quoting from a scalar value. */
+const unquote = (raw: string): string => {
+  const value = raw.trim();
+  if (value.startsWith("'") && value.endsWith("'") && value.length > 1) {
+    return value.slice(1, -1).replaceAll("''", "'");
+  }
+  return value;
+};
+
+const indentOf = (line: string): number =>
+  line.length - line.trimStart().length;
+
+/**
+ * Where a mapping key sits, counting the `- ` sequence marker as indentation:
+ * `- name:` and the `run:` below it are siblings in the same step even though
+ * their raw columns differ by two.
+ */
+const keyIndentOf = (line: string): number =>
+  indentOf(line) + (line.trimStart().startsWith("- ") ? 2 : 0);
+
+/** A sibling scalar of the `run:` key under inspection, when the line is one. */
+const keyValueAt = (
+  line: string,
+  indent: number,
+  key: string
+): string | undefined => {
+  if (keyIndentOf(line) !== indent) {
+    return undefined;
+  }
+  const rest = line.trimStart().replace(/^-\s+/u, "");
+  return rest.startsWith(`${key}:`) ? rest.slice(key.length + 1) : undefined;
+};
+
+/** A `defaults.run.shell` and the span of workflow it governs. */
+interface DefaultShellScope {
+  readonly depth: number;
+  readonly end: number;
+  readonly shell: string;
+  readonly start: number;
+}
+
+/**
+ * Every `defaults: { run: { shell } }` in the document, with the span it
+ * governs: the mapping that declares it, which is the whole workflow at the
+ * top level and one job under `jobs:`.
+ *
+ * GitHub resolves a step's interpreter as step `shell:`, then the job's
+ * default, then the workflow's, then bash. A scanner that only looked at the
+ * step would call every step in a `defaults.run.shell: sh` workflow bash and
+ * report a pass for scripts `sh` cannot parse — the very false negative this
+ * control exists to close.
+ */
+const defaultShellScopes = (lines: string[]): DefaultShellScope[] => {
+  const scopes: DefaultShellScope[] = [];
+
+  for (const [index, line] of lines.entries()) {
+    if (line.trim() !== "defaults:") {
+      continue;
+    }
+    const depth = keyIndentOf(line);
+
+    const shell = (() => {
+      let inRun = false;
+      for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+        const candidate = lines[cursor];
+        if (candidate.trim().length === 0) {
+          continue;
+        }
+        if (keyIndentOf(candidate) <= depth) {
+          return;
+        }
+        if (keyValueAt(candidate, depth + 2, "run") !== undefined) {
+          inRun = true;
+          continue;
+        }
+        if (keyIndentOf(candidate) <= depth + 2) {
+          inRun = false;
+          continue;
+        }
+        const value = inRun
+          ? keyValueAt(candidate, depth + 4, "shell")
+          : undefined;
+        if (value !== undefined) {
+          return unquote(value);
+        }
+      }
+    })();
+    if (shell === undefined) {
+      continue;
+    }
+
+    // The governed span is the mapping `defaults:` belongs to: back to its
+    // parent key, forward to the next sibling of that parent.
+    let start = 0;
+    for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+      if (
+        lines[cursor].trim().length > 0 &&
+        keyIndentOf(lines[cursor]) < depth
+      ) {
+        start = cursor;
+        break;
+      }
+    }
+    let end = lines.length;
+    for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+      if (
+        lines[cursor].trim().length > 0 &&
+        keyIndentOf(lines[cursor]) < depth
+      ) {
+        end = cursor;
+        break;
+      }
+    }
+
+    scopes.push({ depth, end, shell, start });
+  }
+
+  return scopes;
+};
+
+/** The innermost `defaults.run.shell` governing a line, if any. */
+const inheritedShell = (
+  scopes: readonly DefaultShellScope[],
+  index: number
+): string | undefined =>
+  scopes
+    .filter((scope) => index >= scope.start && index < scope.end)
+    .toSorted((left, right) => right.depth - left.depth)
+    .at(0)?.shell;
+
+/**
+ * Every `run:` block in a generated workflow, paired with the `shell:` its
+ * step declares.
+ *
+ * Deliberately a scanner over the emitted text and not a YAML parse: this
+ * package takes no dependency it does not need, and the emitted shape is one
+ * generator's output, not arbitrary YAML. It reads both block scalars
+ * (`run: |-`) and inline scripts.
+ */
+export const workflowRunBlocks = (yaml: string): RunBlock[] => {
+  const lines = yaml.split("\n");
+  const scopes = defaultShellScopes(lines);
+  const blocks: RunBlock[] = [];
+
+  for (const [index, line] of lines.entries()) {
+    const match = RUN_KEY.exec(line);
+    if (match?.groups === undefined) {
+      continue;
+    }
+    const keyIndent = keyIndentOf(line);
+    const inline = match.groups.inline.trim();
+
+    let script: string;
+    let end = index;
+    // The style indicator is the first character of a block header, whatever
+    // follows it: YAML allows the indentation and chomping indicators in
+    // either order (`>2-` and `>-2` are both folded). Keying on that one
+    // character is why no header spelling can slip past as an inline script.
+    if (inline.startsWith(">")) {
+      // A folded scalar joins ordinary line breaks into spaces, so the script
+      // bash would see is not the text on the page: `if true; then` / `echo
+      // ok` / `fi` folds to one line the runner rejects. Refusing is loud;
+      // checking the unfolded text would quietly pass it. No generator in this
+      // fleet emits one.
+      throw new Error(
+        `folded (\`run: >\`) scripts are not supported: YAML folds their line breaks into spaces, so what bash parses is not what is written. Use a literal block (\`run: |\`).`
+      );
+    }
+    if (inline.trimStart().startsWith('"')) {
+      // Double-quoted YAML has its own escape grammar (\", \\, \n, \x41 ...),
+      // and decoding it half-way is how an unterminated bash quote survives a
+      // parse check. Refusing is loud; guessing is not. No generator in this
+      // fleet emits one.
+      throw new Error(
+        `double-quoted \`run:\` scalars are not supported: their YAML escapes would have to be decoded before bash sees them. Use a literal block (\`run: |\`) or an unquoted scalar.`
+      );
+    }
+    if (inline.startsWith("|")) {
+      const body: string[] = [];
+      for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+        const candidate = lines[cursor];
+        if (candidate.trim().length > 0 && indentOf(candidate) <= keyIndent) {
+          break;
+        }
+        body.push(candidate);
+        end = cursor;
+      }
+      const strip = Math.min(
+        ...body
+          .filter((entry) => entry.trim().length > 0)
+          .map((entry) => indentOf(entry))
+      );
+      script = body.map((entry) => entry.slice(strip)).join("\n");
+    } else if (inline.length > 0) {
+      script = unquote(inline);
+    } else {
+      continue;
+    }
+
+    // The step's own keys: the siblings of this `run:`, scanning back to the
+    // step's `- ` marker and forward to the next one.
+    let shell: string | undefined;
+    let step: string | undefined;
+    const readSibling = (line_: string) => {
+      shell ??= keyValueAt(line_, keyIndent, "shell");
+      step ??= keyValueAt(line_, keyIndent, "name");
+    };
+    for (
+      let cursor = index;
+      cursor >= 0 && keyIndentOf(lines[cursor]) >= keyIndent;
+      cursor -= 1
+    ) {
+      readSibling(lines[cursor]);
+      if (lines[cursor].trimStart().startsWith("- ")) {
+        break;
+      }
+    }
+    for (let cursor = end + 1; cursor < lines.length; cursor += 1) {
+      if (
+        keyIndentOf(lines[cursor]) < keyIndent ||
+        lines[cursor].trimStart().startsWith("- ")
+      ) {
+        break;
+      }
+      readSibling(lines[cursor]);
+    }
+
+    const effectiveShell =
+      shell === undefined ? inheritedShell(scopes, index) : unquote(shell);
+
+    blocks.push({
+      script,
+      ...(effectiveShell === undefined ? {} : { shell: effectiveShell }),
+      ...(step === undefined ? {} : { step: unquote(step) }),
+    });
+  }
+
+  return blocks;
+};
+
+/** `NAME=value` in a shell command template, as `env` takes them. */
+const ASSIGNMENT = /^[A-Za-z_]\w*=/u;
+
+/**
+ * Interpreters GitHub supports that this control deliberately leaves alone.
+ * Named rather than inferred, so an unfamiliar command fails loudly instead of
+ * being skipped as though it had been considered.
+ */
+const NON_SHELL_INTERPRETERS = new Set([
+  "cmd",
+  "powershell",
+  "pwsh",
+  "python",
+  "python3",
+]);
+
+/**
+ * The interpreter that will parse a step's script, or `undefined` for one this
+ * control leaves alone.
+ *
+ * A step declaring no shell gets bash: that is GitHub's default for `run:` on
+ * Linux runners. A step declaring `sh` gets `sh`, because the runner runs it
+ * with `sh` — whose grammar is narrower than bash's, so parsing it with bash
+ * would report a pass for a script the runner cannot run. Anything else
+ * (pwsh, python, cmd) is not this control's business.
+ */
+const parserFor = (shell: string | undefined): string[] | undefined => {
+  if (shell === undefined) {
+    return ["bash"];
+  }
+
+  const argv: string[] = [];
+  let interpreter: string | undefined;
+  for (const token of shell.trim().split(/\s+/u)) {
+    if (token === "{0}") {
+      break;
+    }
+    if (interpreter !== undefined) {
+      // The interpreter's own options change its grammar — `bash -O extglob`
+      // parses scripts plain bash rejects — so they are kept and passed on.
+      argv.push(token);
+      continue;
+    }
+    const executable = token.slice(token.lastIndexOf("/") + 1);
+    if (executable === "bash" || executable === "sh") {
+      interpreter = token;
+    } else if (
+      !(executable === "env" || token.startsWith("-") || ASSIGNMENT.test(token))
+    ) {
+      if (NON_SHELL_INTERPRETERS.has(executable)) {
+        return undefined;
+      }
+      throw new Error(
+        `unrecognized \`shell:\` command: ${shell}. This control parses bash and sh scripts and knowingly skips pwsh, powershell, python, and cmd; it refuses rather than guess at anything else.`
+      );
+    }
+    argv.push(token);
+  }
+
+  if (interpreter === undefined) {
+    throw new Error(
+      `unrecognized \`shell:\` command: ${shell}. No interpreter to parse the script with.`
+    );
+  }
+  return argv;
+};
+
+/** Every `run:` block its interpreter refuses to parse. Empty means sound. */
+export const workflowShellParseFailures = (
+  yaml: string
+): WorkflowShellParseFailure[] => {
+  const failures: WorkflowShellParseFailure[] = [];
+
+  for (const block of workflowRunBlocks(yaml)) {
+    const parser = parserFor(block.shell);
+    if (parser === undefined) {
+      continue;
+    }
+    const [executable, ...parserArgs] = parser;
+    const script = neutralizeExpressions(block.script);
+    try {
+      execFileSync(executable, [...parserArgs, "-n"], {
+        input: script,
+        stdio: ["pipe", "ignore", "pipe"],
+      });
+    } catch (error) {
+      failures.push({
+        script,
+        ...(block.step === undefined ? {} : { step: block.step }),
+        stderr: String(
+          (error as { stderr?: Buffer | string }).stderr ?? error
+        ).trim(),
+      });
+    }
+  }
+
+  return failures;
+};
+
+/**
+ * Fail the generated-workflow lint when any embedded `run:` block is not
+ * parseable bash. Call it on the YAML a generator is about to write, so the
+ * defect is caught at generation rather than by the runner.
+ */
+export const assertWorkflowShellParses = (
+  yaml: string,
+  options: { readonly source: string }
+): void => {
+  const failures = workflowShellParseFailures(yaml);
+  if (failures.length === 0) {
+    return;
+  }
+
+  const detail = failures
+    .map(
+      (failure) =>
+        `  - ${failure.step ?? "unnamed step"}: ${failure.stderr.replaceAll(
+          "\n",
+          "\n    "
+        )}`
+    )
+    .join("\n");
+  throw new Error(
+    `${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`
+  );
+};