feat(observability-map): run the report here, score named handlers, and add a force label

Two changes to the observability map report:

**Named handlers are now scored.** A route whose handler is handed to a
builder by name, e.g. `dashboardAction(options, handler)` where
`handler` is a top-level function, was scored from the builder options
alone, blind to the handler body. The scanner now resolves that argument
back to its declaration, so the body's own error handling counts towards
the score. In practice this lifts routes that were being under-scored
(one moved from 0 to 50 on the current route tree, and the global score
did not move). The mutation harness resolves the same shape, so the
corpus stays in step.

**A label to post the report on demand.** The report only comments when
a pull request moves the score, so a pull request that touches no routes
got no report even when you wanted to see one. Add the
`observability-map` label to a pull request and the workflow posts the
current report anyway (it also triggers on the label, so you do not have
to push to get it). Behind this is a `--force` flag on the comment
renderer, which emits the full report even when nothing moved.

Mono-RevId: e6d214424ffdeb5b967ab4781b726b7c2149bcca

Author: 1stvamp

.github/workflows/observability-map.yml

@@ -8,14 +8,18 @@ on:
   # than that empty diff, because a pull request touching a route and other files, whose author
   # reverts the route change and keeps the rest, still has a non-empty diff that no longer matches.
   # The gating moved into the jobs below instead, where it can read whether a comment exists.
+  # `labeled` is here so adding the force label posts a report on demand without waiting for a push;
+  # the other types are the ordinary route-change path.
   pull_request:
-    types: [opened, synchronize, reopened]
+    types: [opened, synchronize, reopened, labeled]
   # The corpus job below is gated to this package's own paths, so a scheduled run is what still
   # scans the tree as it drifts. Nightly rather than per route pull request: a new route can make a
   # known laundering shape start paying, but that is a property of the tree accumulating, not of any
   # one pull request, and it does not need catching within five minutes of the merge.
   schedule:
-    - cron: "0 3 * * *"
+    # Off the top of the hour on purpose: GitHub delays and drops more scheduled runs at :00 under
+    # load, and this nightly is the only tree-drift backstop and has no failure notification.
+    - cron: "17 3 * * *"
   workflow_dispatch:
 
 concurrency:
@@ -46,8 +50,11 @@ jobs:
       # The corpus job's gate. Narrower than the report's on purpose: what the corpus measures is
       # the tool's resistance to laundering, which only an edit to the tool can weaken.
       package: ${{ steps.filter.outputs.package }}
-      # The report job's gate, the union: a route change moves the report as well.
-      report: ${{ steps.filter.outputs.package == 'true' || steps.filter.outputs.routes == 'true' }}
+      # The report job's gate, the union: a route change moves the report as well, and the force label
+      # asks for one when nothing did.
+      report: ${{ steps.filter.outputs.package == 'true' || steps.filter.outputs.routes == 'true' || contains(github.event.pull_request.labels.*.name, 'observability-map') }}
+      # The force label, read once here so the render step posts the full report even at zero delta.
+      forced: ${{ contains(github.event.pull_request.labels.*.name, 'observability-map') }}
       # The id of a marker comment an earlier push left, empty if there is none, and the one source
       # both the render and upsert steps read it from.
       comment: ${{ steps.comment.outputs.id }}
@@ -307,6 +314,7 @@ jobs:
         env:
           SCANNED: ${{ needs.changes.outputs.report }}
           EXISTING_COMMENT: ${{ needs.changes.outputs.comment }}
+          FORCED: ${{ needs.changes.outputs.forced }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           COMPARE_URL: ${{ github.server_url }}/${{ github.repository }}/compare/${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}
         run: |
@@ -356,6 +364,10 @@ jobs:
           if [ -n "$EXISTING_COMMENT" ]; then
             flags=(--existing-comment)
           fi
+          # The force label posts the full report even when nothing moved.
+          if [ "$FORCED" = "true" ]; then
+            flags+=(--force)
+          fi
 
           if ! emit /tmp/head.json "$base" "${flags[@]}"; then
             echo "render failed; falling back to the stale-report comment" >&2

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

@@ -192,6 +192,31 @@ describe.skipIf(!REPORT_PRESENT)(
   }
 );
 
+/**
+ * The force label posts a report on demand, for a pull request that moved nothing and so would
+ * otherwise get no comment. Text checks over the workflow, the same as the reconcile wiring above.
+ */
+describe.skipIf(!REPORT_PRESENT)("the report workflow honours the force label", () => {
+  it("also starts on a labeled pull request, not only on a push", () => {
+    const trigger = withoutComments(read(REPORT).split("\non:\n")[1]!.split("\nconcurrency:")[0]!);
+    expect(trigger).toContain("labeled");
+  });
+
+  it("reads the observability-map label into a forced output and the report gate", () => {
+    const changes = withoutComments(gate("changes"));
+    expect(changes).toContain("forced:");
+    const label = "contains(github.event.pull_request.labels.*.name, 'observability-map')";
+    expect(changes).toContain(label);
+    expect(gate("report")).toContain("needs.changes.outputs.report == 'true'");
+  });
+
+  it("passes --force to the renderer only when the label forced the run", () => {
+    const render = steps(job("report")).find((step) => step.startsWith("📝 Render comment"))!;
+    expect(render).toContain("FORCED: ${{ needs.changes.outputs.forced }}");
+    expect(render).toMatch(/FORCED" = "true" \]; then\s+flags\+=\(--force\)/);
+  });
+});
+
 /**
  * Asserts the shape that cannot have the stdout-capture bug rather than the pnpm version that happens
  * not to. Why: INTERNALS.md, "Tests, timeouts and CI".

internal-packages/observability-map/src/mutations.ts

@@ -145,8 +145,9 @@ function rootCall(call: ts.CallExpression): ts.CallExpression {
 }
 
 /**
- * The handler functions an export's initializer resolves to. `locals` is consulted for the two indirect
- * spellings, `export const action = route.action` and `export const action = handleThing`; `seen` stops
+ * The handler functions an export's initializer resolves to. `locals` is consulted for the indirect
+ * spellings: `export const action = route.action`, the alias `export const action = handleThing`, and a
+ * handler passed to a builder by name (`dashboardAction(options, handleThing)`); `seen` stops
  * `const a = b; const b = a`.
  */
 function fromInitializer(
@@ -165,6 +166,8 @@ function fromInitializer(
       const unwrapped = unwrap(arg);
       if (isEntryFunction(unwrapped)) out.push(unwrapped);
       else if (ts.isObjectLiteralExpression(unwrapped)) collectNamedHandlers(unwrapped, out);
+      // A handler given to the builder by name, resolved through `locals` like the alias case below.
+      else if (ts.isIdentifier(unwrapped)) fromInitializer(unwrapped, out, locals, seen);
     }
     return;
   }

internal-packages/observability-map/src/report/prCommentCli.test.ts

@@ -80,6 +80,26 @@ describe("prCommentCli", () => {
     }
   });
 
+  // The force label's path: a report on demand even when nothing moved, where the delta path posts
+  // nothing, and a report rather than a resolved state even when a comment already exists.
+  it("posts the full report with --force even when nothing moved", () => {
+    expect(run(unchangedPath, unchangedPath).out).toBe("");
+    const r = run(unchangedPath, unchangedPath, "--force");
+    expect(r.code).toBe(0);
+    expect(r.out.split("\n")[0]).toBe("<!-- observability-map-report -->");
+    expect(r.out).not.toContain("moves the report any more");
+  });
+
+  it("renders a report, not a resolved state, when --force meets an existing comment", () => {
+    expect(run(unchangedPath, unchangedPath, "--existing-comment").out).toContain(
+      "moves the report any more"
+    );
+    const r = run(unchangedPath, unchangedPath, "--existing-comment", "--force");
+    expect(r.code).toBe(0);
+    expect(r.out.split("\n")[0]).toBe("<!-- observability-map-report -->");
+    expect(r.out).not.toContain("moves the report any more");
+  });
+
   it("prints the stale-report comment for --scan-failed without reading any file", () => {
     const r = run("--scan-failed");
     expect(r.code).toBe(0);

internal-packages/observability-map/src/report/prCommentCli.ts

@@ -61,13 +61,15 @@ function commitFrom(args: string[]): CommitContext | undefined {
  * Empty output means "post nothing". `--existing-comment` is how the workflow says a comment from an
  * earlier push is already there, so with the delta gone that comment is replaced with a resolved state
  * rather than left standing. `--scan-failed` and `--resolved` take no report at all, for a head scan
- * that produced nothing to read and for a run where the watched paths did not move.
+ * that produced nothing to read and for a run where the watched paths did not move. `--force` posts the
+ * full report even with no delta, which is how the workflow honours a label asking for one on demand.
  */
 export function main(argv: string[], io: Io = processIo): number {
   const args = argv.slice(2);
   const scanFailed = args.includes("--scan-failed");
   const resolved = args.includes("--resolved");
   const existingComment = args.includes("--existing-comment");
+  const force = args.includes("--force");
   const positional = args.filter((a) => !a.startsWith("--"));
   const headPath = positional[0];
   const basePath = positional[1];
@@ -120,7 +122,7 @@ export function main(argv: string[], io: Io = processIo): number {
     return 1;
   }
 
-  if (hasDelta(head, base)) {
+  if (force || hasDelta(head, base)) {
     write(`${renderPrComment(head, base, commit)}\n`);
     return 0;
   }

internal-packages/observability-map/src/scan.ts

@@ -977,11 +977,21 @@ function rootCall(call: ts.CallExpression): ts.CallExpression {
  * The handler functions passed to a builder call. Only the root call of a chain is read: a
  * callback given to a decorator further along the chain (`.withCors(cb)`) is not the route body.
  */
-function collectHandlerFunctions(call: ts.CallExpression, out: EntryFunction[]): void {
+function collectHandlerFunctions(
+  call: ts.CallExpression,
+  out: EntryFunction[],
+  locals: LocalDeclarations,
+  seen: Set<string>
+): void {
   for (const arg of rootCall(call).arguments) {
     const unwrapped = unwrap(arg);
     if (isEntryFunction(unwrapped)) out.push(unwrapped);
     else if (ts.isObjectLiteralExpression(unwrapped)) collectNamedHandlers(unwrapped, out);
+    // A handler handed to the builder by name (`dashboardAction(options, handler)`), resolved back
+    // through `locals` like the alias export below.
+    else if (ts.isIdentifier(unwrapped)) {
+      for (const fn of resolveLocal(unwrapped.text, locals, seen).functions) out.push(fn);
+    }
   }
 }
 
@@ -1031,7 +1041,7 @@ function analyzeInitializer(
 
   if (ts.isCallExpression(target)) {
     const functions: EntryFunction[] = [];
-    collectHandlerFunctions(target, functions);
+    collectHandlerFunctions(target, functions, locals, seen);
     return {
       callee: rootCalleeName(target),
       functions,