feat(observability-map): static observability scorer for webapp route entry points

.github/workflows/pr_checks.yml

@@ -22,6 +22,7 @@ jobs:
  webapp: ${{ steps.filter.outputs.webapp }}
  packages: ${{ steps.filter.outputs.packages }}
  internal: ${{ steps.filter.outputs.internal }}
+ obsmap: ${{ steps.filter.outputs.obsmap }}
  cli: ${{ steps.filter.outputs.cli }}
  sdk: ${{ steps.filter.outputs.sdk }}
  steps:
@@ -81,6 +82,36 @@ jobs:
  - 'pnpm-lock.yaml'
  - 'pnpm-workspace.yaml'
  - 'turbo.json'
+ # The whole webapp app tree, not just its routes, and that is the whole reason this
+ # filter exists. Two tests in @internal/observability-map read it: integration.test.ts
+ # scans the live route tree, and webappSymbols.test.ts walks all of apps/webapp/app and
+ # fails when a guard, sensitive or audit symbol stops resolving. Routes-only was this
+ # filter's own bug: renaming e.g. requireUserId in app/services/session.server.ts
+ # matched `webapp` and nothing else, so no job ran the suite and the break landed on
+ # main, or on the next unrelated internal-packages PR.
+ #
+ # The cost of the wider set, measured over the last 400 commits on main: 31% touch
+ # routes, 52% touch apps/webapp/app, so the job goes from firing on roughly a third of
+ # PRs to roughly a half. It is the cheap one -- a single 4x runner, no containers, no
+ # database, no prisma generate -- which is what makes that affordable.
+ #
+ # observability-map.yml is here because integration.test.ts asserts on its text and no
+ # other filter watches it, so editing the report workflow alone ran nothing at all.
+ #
+ # Deliberately NOT here: this package's own paths, and packages/plugins/src and
+ # internal-packages/rbac/src, the other two trees webappSymbols.test.ts reads.
+ # `internal` above already matches `internal-packages/**` and `packages/**`, and
+ # `unit-tests-internal.yml` runs `turbo run test --filter "@internal/*"`, which picks up
+ # @internal/observability-map and runs the same vitest suite. Listing them here as well
+ # ran the suite twice on every PR touching them, which was this filter's own doing.
+ obsmap:
+ - 'apps/webapp/app/**'
+ - '.github/workflows/pr_checks.yml'
+ - '.github/workflows/unit-tests-observability-map.yml'
+ - '.github/workflows/observability-map.yml'
+ - 'package.json'
+ - 'pnpm-lock.yaml'
+ - 'pnpm-workspace.yaml'
  cli:
  - 'packages/cli-v3/**'
  - 'packages/build/**'
@@ -149,6 +180,11 @@ jobs:
  DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
  DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
 
+ obsmap:
+ needs: changes
+ if: needs.changes.outputs.obsmap == 'true'
+ uses: ./.github/workflows/unit-tests-observability-map.yml
+
  e2e:
  needs: changes
  if: needs.changes.outputs.cli == 'true'
@@ -172,6 +208,7 @@ jobs:
  - e2e-webapp
  - packages
  - internal
+ - obsmap
  - e2e
  - sdk-compat
  if: always()

.github/workflows/unit-tests-observability-map.yml

@@ -0,0 +1,43 @@
+name: "🧪 Unit Tests: Observability Map"
+
+permissions:
+ contents: read
+
+# Its own workflow rather than a job inside observability-map.yml, because that workflow is not
+# reachable from pr_checks.yml's all-checks aggregate and so gates nothing. Called from there
+# instead, behind a paths filter, which is how every other test suite in this repo is gated.
+on:
+ workflow_call:
+
+jobs:
+ unitTests:
+ name: "🧪 Unit Tests: Observability Map"
+ # No containers and no database: the package is a static analyser over source text, so the
+ # suite is CPU bound on parsing the route tree and needs nothing the runner does not have.
+ runs-on: warp-ubuntu-latest-x64-4x
+ steps:
+ - name: ⬇️ Checkout repo
+ uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+ with:
+ fetch-depth: 1
+ persist-credentials: false
+
+ - name: ⎔ Setup pnpm
+ uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+ with:
+ version: 10.33.2
+
+ - name: ⎔ Setup node
+ uses: WarpBuilds/setup-node@bc639b444d583175926b588962199c247d23e8d3 # v6
+ with:
+ node-version: 24.18.0
+ cache: "pnpm"
+
+ - name: 📥 Download deps
+ run: pnpm install --frozen-lockfile
+
+ # This suite reads apps/webapp/app (the route tree for the scan, the whole app tree for the
+ # symbol check) and the report workflow's text, which is why the filter that gates this
+ # workflow watches all of those and not only the routes folder.
+ - name: 🧪 Run tests
+ run: pnpm --filter @internal/observability-map run test

.gitignore

@@ -82,3 +82,6 @@ ailogger-output.log
 
 # local planning/design docs, not committed
 **/docs/superpowers/
+
+# observability-map CLI output artifact, not committed
+observability-map.json