ci(observability-map): write scan reports with --out instead of capturing stdout

Both scan steps redirected pnpm --filter ... exec stdout into files the renderer
JSON.parses. pnpm takes its recursive path under --filter and some versions
announce 'Scope: N of M workspace projects' on it; one such line in head.json
fails the parse and degrades every run to the stale-report comment, which is a
permanent quiet failure rather than a loud one.

It does not reproduce on the 10.33.2 the workflow pins, which was checked, so
this closes the class rather than a reproduction: the scanner writes its own
file and stdout is left to be log output. The -s guard keeps the partial dance
honest now the redirect no longer creates the file, so a scanner that exits 0
without writing takes the stale-report branch instead of failing the mv and
turning the job red.

The render step still captures stdout, since prCommentCli has no --out and a
banner there puts a stray line in a markdown comment rather than breaking a
parse.

Reported by Devin on #4455.

Author: 1stvamp

.github/workflows/observability-map.yml

@@ -149,10 +149,24 @@ jobs:
       # Guarded rather than allowed to fail: this job must never block a pull request. The failure
       # is not swallowed either, the render step below turns a missing head report into a comment
       # saying so, because a swallowed failure with no comment is the outcome nobody wants.
+      #
+      # `--out` rather than a stdout redirect, so nothing a tool decides to print can end up inside
+      # the document `prCommentCli` parses. `pnpm --filter` takes its recursive path and some
+      # versions announce `Scope: N of M workspace projects` on the way; that line landing in
+      # head.json would fail the parse and degrade every run to the stale-report comment, which is
+      # a permanent quiet failure rather than a loud one. It does not reproduce on the 10.33.2
+      # pinned above, so this closes the class rather than a reproduction: the file is written by
+      # the process that owns it and stdout is left to be log output. Held by
+      # `it("let the scanner write its own report rather than capturing stdout")` in
+      # `internal-packages/observability-map/src/integration.test.ts`.
+      #
+      # `-s` keeps the partial dance honest now the redirect no longer creates the file: a scanner
+      # that exits 0 without writing takes the else branch and the stale-report comment, instead of
+      # failing the `mv` and turning the job red.
       - name: 🔎 Scan head
         run: |
-          if pnpm --filter @internal/observability-map exec tsx src/cli.ts --json --no-write \
-            > /tmp/head.json.partial; then
+          if pnpm --filter @internal/observability-map exec tsx src/cli.ts \
+            --out=/tmp/head.json.partial && [ -s /tmp/head.json.partial ]; then
             mv /tmp/head.json.partial /tmp/head.json
           else
             rm -f /tmp/head.json /tmp/head.json.partial
@@ -168,8 +182,9 @@ jobs:
       - name: 🔎 Scan base with the head's scanner
         run: |
           if git worktree add /tmp/base-tree ${{ github.event.pull_request.base.sha }} \
-            && pnpm --filter @internal/observability-map exec tsx src/cli.ts --json --no-write \
-              --routes=/tmp/base-tree/apps/webapp/app/routes > /tmp/base.json; then
+            && pnpm --filter @internal/observability-map exec tsx src/cli.ts \
+              --routes=/tmp/base-tree/apps/webapp/app/routes --out=/tmp/base.json \
+            && [ -s /tmp/base.json ]; then
             :
           else
             echo "-" > /tmp/base.json || true

internal-packages/observability-map/src/integration.test.ts

@@ -117,6 +117,40 @@ describe("the report workflow's two readers of the comment lookup", () => {
   });
 });
 
+/**
+ * Both scan steps used to capture the scanner's stdout with a shell redirect, into files the
+ * renderer then `JSON.parse`s. Anything else reaching stdout therefore corrupted the report:
+ * `pnpm --filter` takes its recursive path, and some versions of pnpm announce
+ * `Scope: N of M workspace projects` on it. A single line of that in head.json fails the parse,
+ * and the workflow degrades to the stale-report comment on every run, quietly and permanently.
+ *
+ * It does not reproduce on the 10.33.2 the workflow pins, which was checked. What is asserted here
+ * is the shape that cannot have the bug at all rather than the version that happens not to: the
+ * scanner writes its own file through `--out`, so stdout carries log output and nothing else.
+ * The same is not yet true of the render step, which has no `--out` to reach for; a banner there
+ * puts a stray line in a markdown comment instead of breaking a parse, so it is left alone.
+ */
+describe("the report workflow's two scan steps", () => {
+  const WORKFLOW = resolve(__dirname, "../../../.github/workflows/observability-map.yml");
+
+  it("let the scanner write its own report rather than capturing stdout", () => {
+    const scans = readFileSync(WORKFLOW, "utf8")
+      .split(/^ {6}- name: /m)
+      .slice(1)
+      .filter((step) => step.startsWith("🔎 Scan"));
+    expect(scans).toHaveLength(2);
+
+    for (const step of scans) {
+      // The `if ...; then` condition only, which is where the scanner runs. The else branch writes
+      // `echo "-" > /tmp/base.json`, a redirect of the workflow's own making that has nothing to
+      // do with capturing the scanner, and an earlier version of this test failed on it.
+      const command = step.split("; then")[0]!;
+      expect(command).toMatch(/--out=\S+\.json/);
+      expect(command).not.toMatch(/>\s*\S*\.json/);
+    }
+  });
+});
+
 /**
  * The gating half of the same problem. A test job that nothing waits for is decoration, and the
  * first attempt at this was exactly that: a job inside `observability-map.yml`, which reads well