Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

The Go and Node halves of the same problem, and a type check that never ran (#817)

Beenu Arora5d0f96d2ffc0
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 1fd589b60..a91aafeb8 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -9,7 +9,7 @@
# drops first-boot from ~5 minutes to ~30 seconds.
#
# Layers, top to bottom:
-# 1. Base: javascript-node bookworm — Node 20 + pnpm-friendly debian
+# 1. Base: javascript-node bookworm — Node 22 + pnpm-friendly debian
# 2. System packages: docker.io, python3.11 + uv, go, gh
# 3. Workspace bootstrap: corepack-prepare pnpm, prime turbo/eslint caches
#
@@ -20,7 +20,10 @@
# `.github/workflows/devcontainer-coldstart.yml` asserts the boot KPI.
###############################################################################
-FROM mcr.microsoft.com/devcontainers/javascript-node:1-20-bookworm
+# Node 22, matching every workflow and both Node images. On 20 a contributor's
+# container ran a different runtime from the one CI tests and the one the web
+# image ships, and Node 20 left security support in April 2026.
+FROM mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm
ARG TARGETARCH
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index f128e67ba..fc969bca7 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -42,8 +42,8 @@
"label": "Docs site"
}
},
- "//onCreateCommand": "Runs once at image-spawn time. The pnpm store is already warm in the prebuilt image, so `--frozen-lockfile=false` here is fast (≤ 30 s on a green Codespace).",
- "onCreateCommand": "pnpm install --frozen-lockfile=false",
+ "//onCreateCommand": "Runs once at image-spawn time. The pnpm store is already warm in the prebuilt image, so this is fast (<= 30 s on a green Codespace). `--frozen-lockfile` matches CI and the web image: a contributor's first install must produce the dependency set CI tested, or their first green run is a different build from everyone else's. It read `--frozen-lockfile=false`, which a substring test for the flag reads as enabling the very thing it disables.",
+ "onCreateCommand": "pnpm install --frozen-lockfile",
"//postStartCommand": "Starts dockerd. Runs on every container start rather than only at create, so a Codespace stop/resume comes back with a working daemon — `onCreateCommand` would leave the second boot without one.",
"postStartCommand": "bash .devcontainer/start-docker.sh",
"postAttachCommand": "echo '\\n>>> AiSOC dev container is ready.\\n>>> To run the demo, open a terminal and run:\\n>>> pnpm aisoc:demo --no-open\\n>>> Then click the forwarded port 3000 in the Ports panel.\\n>>> Or, no-Docker: pip install -e packages/aisoc-sandbox && aisoc-sandbox demo\\n'",
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 33895f508..5e8d08390 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -234,6 +234,24 @@ jobs:
run: ruff check services/
- name: Ruff format check (all services)
run: ruff format --check services/
+ # This job has been called "Lint & Type-check" since it was written, and
+ # until now it installed mypy and never ran it. Six manifests declare a
+ # `[tool.mypy]` table and three set `strict = true`, so the config asked
+ # for a check that had never once executed.
+ #
+ # The findings are real and there are 690 of them. They are recorded in
+ # `scripts/mypy_baseline.json` exactly as mypy reports them and the gate
+ # fails when any grows — no `ignore_errors`, no widened config, no tree
+ # excluded. Nothing installs the services' dependencies here on purpose:
+ # mypy's answer depends on what is importable, so the baseline is only
+ # reproducible against a fixed environment, and "mypy alone on 3.12" is
+ # that environment. Re-record with
+ # `python scripts/check_mypy_baseline.py --update` under the same
+ # conditions.
+ - name: The type-check this job is named after
+ run: |
+ python scripts/check_mypy_baseline.py --self-test
+ python scripts/check_mypy_baseline.py
# The aisoc-api Docker image is built with `services/api` as its build
# context, so anything under `services/agents` is *not* shipped in the
# container. The natural-language query translator is consumed by both
@@ -893,7 +911,10 @@ jobs:
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version: '1.26'
- cache-dependency-path: services/${{ matrix.service }}/go.sum
+ # `demo-producer` is standard-library only and has no go.sum, so the
+ # glob resolves to the two legs that do have one instead of failing
+ # the third back to an uncached build with only a warning.
+ cache-dependency-path: services/${{ matrix.service }}/go.sum*
- name: Build
run: |
cd services/${{ matrix.service }}
@@ -908,31 +929,42 @@ jobs:
go test ./... -count=1
# ──────────────────────────────────────────────
- # Go SDK (`packages/plugin-sdk-go`)
- # Lives outside `services/` so the matrix above doesn't pick it up.
- # Has `client_test.go`, `loader_test.go`, `registry_test.go` already —
- # they were never gated. Build + vet + test, no soft-fails.
+ # Go SDKs (`packages/plugin-sdk-go`, `packages/sdk-go`)
+ # Live outside `services/` so the matrix above doesn't pick them up.
+ # `plugin-sdk-go` has `client_test.go`, `loader_test.go`,
+ # `registry_test.go`; `sdk-go` had no job at all and so was never
+ # compiled by CI — `scripts/check_toolchain_pins.py` now fails on a Go
+ # module no workflow builds.
+ #
+ # No `cache-dependency-path`: both modules are standard-library only and
+ # have no `go.sum`. Pointing setup-go at a file that does not exist makes
+ # it log `Restore cache failed: Some specified paths were not resolved` as
+ # a *warning* and carry on, so the job kept passing with the cache
+ # permanently off — a green tick over a step that never happened.
# ──────────────────────────────────────────────
sdk-go-test:
- name: SDK — Go (build, vet, test)
+ name: SDK — Go ${{ matrix.module }} (build, vet, test)
runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ module: [plugin-sdk-go, sdk-go]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version: '1.26'
- cache-dependency-path: packages/plugin-sdk-go/go.sum
- name: Build
run: |
- cd packages/plugin-sdk-go
+ cd packages/${{ matrix.module }}
go build ./...
- name: Vet
run: |
- cd packages/plugin-sdk-go
+ cd packages/${{ matrix.module }}
go vet ./...
- name: Test
run: |
- cd packages/plugin-sdk-go
+ cd packages/${{ matrix.module }}
go test ./... -count=1
# ──────────────────────────────────────────────
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 7ce93d5bd..405f40ce5 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -34,11 +34,14 @@ jobs:
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
- node-version: 20
+ node-version: 22
cache: pnpm
- name: Install dependencies
- run: pnpm --filter @aisoc/docs install
+ # `--frozen-lockfile` like every other install of this workspace. A
+ # filtered install is still an install: without the flag the published
+ # docs site could be built from a dependency set no other job resolved.
+ run: pnpm --filter @aisoc/docs install --frozen-lockfile
# Set explicitly rather than leaning on the defaults in
# docusaurus.config.ts. These values decide the canonical <link>, the
diff --git a/.github/workflows/reproducible-builds.yml b/.github/workflows/reproducible-builds.yml
index 73c185171..d0ce27844 100644
--- a/.github/workflows/reproducible-builds.yml
+++ b/.github/workflows/reproducible-builds.yml
@@ -18,19 +18,38 @@ name: Reproducible builds
# Four jobs, each proving a different half of "reproducible":
#
# pin-agreement — no two install paths for one package may disagree.
+# toolchain — the Go, Node, pnpm and Python *toolchains* agree too. A
+# workflow compiling with a different Go or Node version
+# than the Dockerfile ships is the same defect one level
+# up, and it is how the disjoint `cryptography` range
+# stayed invisible.
# lock-freshness — every lock still matches the manifest it was made from,
# so `poetry install` cannot be pushed back into resolving.
# fastapi-range — the service imports on both ends of the range it declares,
# so the bound is a tested claim rather than a guess.
# twice — two `--no-cache` builds of this commit install the same
-# versions. This is the only job that proves the property
-# directly; the other three explain why it holds.
+# versions. This is the job that proves the property
+# directly; the others explain why it holds.
+# twice-all — the same proof for every remaining service, nightly.
+# `twice` covered `api` alone: the other twelve used the
+# same mechanism and nothing asserted it, which is the
+# repository's dominant defect (a property that holds by
+# construction and is checked nowhere) in its mildest
+# costume. Nightly rather than per-PR because it is 24
+# from-scratch image builds; `coverage` below fails if the
+# run did not actually reach every service, so the
+# schedule cannot quietly cover less than it claims.
on:
push:
branches: [main]
pull_request:
branches: [main]
+ schedule:
+ # 03:17 UTC daily. Every service is therefore re-proved within 24 hours
+ # of any merge. Offset off the hour because the runner pool is busiest on
+ # it, and a job that queues past its window is a job that did not run.
+ - cron: '17 3 * * *'
workflow_dispatch:
permissions:
@@ -66,6 +85,27 @@ jobs:
pip install --quiet 'pytest>=7.4,<9'
python -m pytest tests/test_dependency_pin_gate.py -v --tb=short
+ toolchain-agreement:
+ name: Go, Node and pnpm toolchains agree
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.12'
+ # Names its root and every path it scanned, so the log shows which tree
+ # was checked. One gate in this repository resolved its root from its
+ # own file location and would have printed a confident OK about a tree
+ # it never opened.
+ - name: Every path declaring a toolchain agrees, and every install is locked
+ run: python scripts/check_toolchain_pins.py --verbose
+ - name: The gate detects injected drift in every direction
+ run: python scripts/check_toolchain_pins.py --self-test
+ - name: Gate unit tests
+ run: |
+ pip install --quiet 'pytest>=7.4,<9'
+ python -m pytest tests/test_toolchain_pin_gate.py -v --tb=short
+
lock-freshness:
name: Every lock still matches its manifest
runs-on: ubuntu-latest
@@ -189,3 +229,161 @@ jobs:
[ "$(wc -l < first.txt)" -ge 50 ] || { echo "::error::pip freeze returned almost nothing"; exit 1; }
grep -q '^fastapi==' first.txt || { echo "::error::fastapi absent from the image"; exit 1; }
echo "identical: $(wc -l < first.txt) packages, byte-for-byte"
+
+ # ───────────────────────────────────────────────────────────────────────────
+ # The same proof, every remaining service, nightly.
+ # ───────────────────────────────────────────────────────────────────────────
+
+ discover:
+ name: Which services must be proved
+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+ runs-on: ubuntu-latest
+ outputs:
+ images: ${{ steps.find.outputs.images }}
+ lockonly: ${{ steps.find.outputs.lockonly }}
+ total: ${{ steps.find.outputs.total }}
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ # Derived from the tree, never hand-listed. A hand-written matrix is a
+ # second inventory that drifts from the first, and the service added
+ # after it was written is exactly the one nobody proves.
+ - id: find
+ run: |
+ set -euo pipefail
+ images=(); lockonly=(); total=0
+ for manifest in services/*/pyproject.toml; do
+ service="$(basename "$(dirname "$manifest")")"
+ total=$((total + 1))
+ if [ ! -f "services/$service/poetry.lock" ]; then
+ echo "::error::services/$service has no poetry.lock — it resolves afresh on every build"
+ exit 1
+ fi
+ if [ -f "services/$service/Dockerfile" ]; then
+ images+=("$service")
+ else
+ # No image to build twice, so the lock is proved one layer down:
+ # two installs from it must produce the same version set.
+ lockonly+=("$service")
+ fi
+ done
+ printf 'images=%s\n' "$(printf '%s\n' "${images[@]}" | jq -R . | jq -sc .)" >> "$GITHUB_OUTPUT"
+ printf 'lockonly=%s\n' "$(printf '%s\n' "${lockonly[@]}" | jq -R . | jq -sc .)" >> "$GITHUB_OUTPUT"
+ printf 'total=%s\n' "$total" >> "$GITHUB_OUTPUT"
+ echo "$total service(s): ${#images[@]} with an image, ${#lockonly[@]} lock-only"
+
+ twice-all:
+ name: ${{ matrix.service }} builds the same twice
+ needs: discover
+ runs-on: ubuntu-latest
+ timeout-minutes: 40
+ strategy:
+ fail-fast: false
+ matrix:
+ service: ${{ fromJson(needs.discover.outputs.images) }}
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ - name: Build ${{ matrix.service }} twice, from scratch each time
+ run: |
+ set -euo pipefail
+ svc='${{ matrix.service }}'
+ docker build --no-cache -t "aisoc-$svc:first" -f "services/$svc/Dockerfile" "services/$svc"
+ docker build --no-cache -t "aisoc-$svc:second" -f "services/$svc/Dockerfile" "services/$svc"
+ - name: The two images must contain identical versions
+ run: |
+ set -euo pipefail
+ svc='${{ matrix.service }}'
+ docker run --rm --entrypoint pip "aisoc-$svc:first" freeze | sort > first.txt
+ docker run --rm --entrypoint pip "aisoc-$svc:second" freeze | sort > second.txt
+ echo "first: $(wc -l < first.txt) packages, sha256 $(sha256sum first.txt | cut -d' ' -f1)"
+ echo "second: $(wc -l < second.txt) packages, sha256 $(sha256sum second.txt | cut -d' ' -f1)"
+ if ! diff -u first.txt second.txt; then
+ echo "::error::two builds of $svc at the same commit resolved different versions"
+ exit 1
+ fi
+ # Two empty files also diff clean. A service image that installs
+ # nothing is a broken build reported as a reproducible one.
+ [ "$(wc -l < first.txt)" -ge 20 ] || {
+ echo "::error::pip freeze in $svc returned $(wc -l < first.txt) packages — too few to be a real install"
+ exit 1
+ }
+ echo "$svc: identical, $(wc -l < first.txt) packages" >> "$GITHUB_STEP_SUMMARY"
+
+ twice-lockonly:
+ name: ${{ matrix.service }} resolves the same twice
+ needs: discover
+ if: needs.discover.outputs.lockonly != '[]'
+ runs-on: ubuntu-latest
+ timeout-minutes: 25
+ strategy:
+ fail-fast: false
+ matrix:
+ service: ${{ fromJson(needs.discover.outputs.lockonly) }}
+ container: python:3.11-slim
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ # Same resolver the images install with — a different one is a
+ # different answer to what this commit installs.
+ - run: pip install --quiet "poetry==2.4.1"
+ - name: Install from the lock twice, into separate environments
+ # `poetry install`, the same command the twelve images run, rather
+ # than `poetry export | pip install`: export is a plugin in Poetry 2.x
+ # and is not present here, and a second install mechanism would prove
+ # a property about a path nothing uses.
+ run: |
+ set -euo pipefail
+ svc='${{ matrix.service }}'
+ cd "services/$svc"
+ for attempt in first second; do
+ POETRY_VIRTUALENVS_PATH="/tmp/venvs-$attempt" \
+ poetry install --only main --no-root --no-interaction
+ POETRY_VIRTUALENVS_PATH="/tmp/venvs-$attempt" \
+ poetry run pip freeze | sort > "/tmp/$attempt-freeze.txt"
+ done
+ echo "first: $(wc -l < /tmp/first-freeze.txt) packages, sha256 $(sha256sum /tmp/first-freeze.txt | cut -d' ' -f1)"
+ echo "second: $(wc -l < /tmp/second-freeze.txt) packages, sha256 $(sha256sum /tmp/second-freeze.txt | cut -d' ' -f1)"
+ diff -u /tmp/first-freeze.txt /tmp/second-freeze.txt || {
+ echo "::error::two installs of $svc at the same commit resolved different versions"
+ exit 1
+ }
+ [ "$(wc -l < /tmp/first-freeze.txt)" -ge 10 ] || {
+ echo "::error::$svc installed $(wc -l < /tmp/first-freeze.txt) packages — too few to be a real install"
+ exit 1
+ }
+ echo "$svc: identical, $(wc -l < /tmp/first-freeze.txt) packages (no image; proved from the lock)" >> "$GITHUB_STEP_SUMMARY"
+
+ coverage:
+ name: Every service was actually proved
+ needs: [discover, twice-all, twice-lockonly]
+ if: always() && needs.discover.result == 'success'
+ runs-on: ubuntu-latest
+ steps:
+ # The point of this job. A nightly matrix that silently shrinks —
+ # because a leg was skipped, a service lost its lock, or `fail-fast`
+ # cancelled the rest — would keep reporting a green schedule while
+ # covering less than it claims. That is the `wet-eval` failure: eight
+ # consecutive green weekly runs with every real step skipped.
+ - name: Count what ran against what exists
+ run: |
+ set -euo pipefail
+ images='${{ needs.discover.outputs.images }}'
+ lockonly='${{ needs.discover.outputs.lockonly }}'
+ total='${{ needs.discover.outputs.total }}'
+ covered=$(( $(echo "$images" | jq 'length') + $(echo "$lockonly" | jq 'length') ))
+ echo "discovered $total service(s); matrix covered $covered"
+ echo " images: $(echo "$images" | jq -r 'join(", ")')"
+ echo " lock-only: $(echo "$lockonly" | jq -r 'join(", ")')"
+ [ "$covered" -eq "$total" ] || {
+ echo "::error::$covered of $total services were in the matrix"
+ exit 1
+ }
+ # Independent of the discovery that produced the matrix: if a
+ # fourteenth service lands, this floor makes the omission loud
+ # rather than letting the run pass with thirteen.
+ [ "$total" -ge 13 ] || { echo "::error::only $total services found; expected at least 13"; exit 1; }
+ for result in '${{ needs.twice-all.result }}' '${{ needs.twice-lockonly.result }}'; do
+ case "$result" in
+ success) ;;
+ *) echo "::error::a reproducibility matrix finished as '$result', so not every service was proved"; exit 1 ;;
+ esac
+ done
+ echo "all $total service(s) proved reproducible at this commit" >> "$GITHUB_STEP_SUMMARY"
diff --git a/.gitignore b/.gitignore
index 58286763b..722bc68b1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -131,3 +131,11 @@ services/api/marketplace/
# `-current.yaml` file is a runtime artefact that varies by environment.
schemas/graph-schema-current.yaml
+
+# Compiled Go binaries. `services/demo-producer/demo-producer` was committed as
+# a 6.9 MB macOS arm64 executable in a repository whose Dockerfile builds a
+# GOOS=linux one — nothing consumed it, nothing rebuilt it, and running the
+# documented `go build ./...` silently overwrote it and dirtied the tree.
+/services/demo-producer/demo-producer
+/services/enrichment/enrichment
+/services/ingest/ingest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f5fd9df61..e3497b976 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -77,6 +77,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- **`scripts/check_toolchain_pins.py` — the Go, Node and toolchain half of
+ reproducible builds.** `check_dependency_pins.py` made every *package*
+ install path agree and stopped at the Python services. Go has `go.sum` and
+ pnpm has a frozen lockfile, so the raw material was already there — but
+ nothing compared the paths that use it, and nothing audited the *runtime*
+ those paths run on. Measured across 111 install paths, and every
+ disagreement found:
+
+ | What | Before |
+ |---|---|
+ | `apps/web/Dockerfile` | `pnpm install --no-frozen-lockfile` — the production web bundle was the one install path in the repository free to resolve its own dependency set, while all 13 workflows installing the same workspace used `--frozen-lockfile` |
+ | `services/realtime/Dockerfile` | `npm install` twice, and `package-lock.json` never copied into the build context, so the committed lockfile was inert and every image build re-resolved |
+ | `install.sh` | `pnpm install --no-frozen-lockfile`, so a self-hoster's install could differ from everything CI tested |
+ | `.devcontainer/devcontainer.json` | `pnpm install --frozen-lockfile=false` — an opt-out a substring test for the flag reads as *enabling* it |
+ | `deploy-docs.yml` | `pnpm --filter @aisoc/docs install`, unlocked; the published docs site could build from a tree no other job resolved |
+ | `apps/web/Dockerfile` | `npm install -g pnpm@8` against `packageManager: [email protected]` — two resolvers, the `poetry 1.7.1 vs 1.8.2` finding again |
+ | Node | 20 in both images, the devcontainer, `deploy-docs.yml` and both installers; 22 in twelve workflows. Node 20 left security support in April 2026 |
+ | `services/enrichment/Dockerfile` | `COPY go.mod go.sum*` — the glob makes the checksum file optional, so deleting it downgrades the build to an unverified resolve without failing |
+ | `ci.yml` | `cache-dependency-path: packages/plugin-sdk-go/go.sum`, a file that does not exist. `setup-go` reports that as a **warning**, so the cache had been silently off while the job stayed green |
+ | `packages/sdk-go` | compiled by no workflow at all |
+
+ Everything above is now one version and one lockfile discipline, proved
+ rather than asserted: two `--no-cache` builds of each Node image resolve
+ byte-identically (web 1,172 packages, realtime 187, matching sha256 both
+ times).
+
+ Six directions, each with a `--self-test` injection that fails if it goes
+ undetected — 22 cases. Beyond agreement: *ship → test* (a version an image
+ ships that no workflow exercises) and *test → ship* (a version CI uses that
+ no image ships, which is the direction versions actually travel); *module →
+ sum* and *sum → module*; *module → CI* and *CI → module*; unlocked install
+ and its reverse, a lockfile nothing can consume; and both coverage
+ directions — a file declaring a toolchain that the gate never opened, and a
+ file it *did* open whose declaration the parser could not read.
+
+ That last direction earned its place immediately. Hunting for this parser's
+ equivalent of the blind spot `check_dependency_pins` found in itself, five
+ turned up: `cd services/${{ matrix.service }}` resolved to nothing, so five
+ of six Go modules looked ungated; `working-directory:` was not read at all,
+ so `services/osquery-extensions` looked uncompiled while the workflow that
+ compiles it sat two directories away; the npm pattern had no left word
+ boundary and matched inside every `pnpm install`; quoted shell text was read
+ as commands, so `die "pnpm install failed."` counted as an install path; and
+ the `node_modules` skip was a prefix rather than a path segment, so on a
+ checkout with dependencies installed the gate scanned 223 vendored manifests
+ and reported Node floors of `0.10` from other people's packages — an answer
+ that depended on whether someone had run `pnpm install`.
+
+ `EXPECTED_ESBUILD` pins the **resolved** esbuild set (0.25.12 bundled by
+ Next, 0.28.1 from the scoped overrides). The overrides are deliberately
+ per-parent because forcing esbuild workspace-wide broke Turbopack's font
+ import map, and that scoping means a `vite` bump can pull a different
+ esbuild with no esbuild line in the diff.
+
+- **`scripts/check_mypy_baseline.py` — the type check the CI job is named
+ after.** `ci.yml`'s **Python — Lint & Type-check** installed mypy and never
+ invoked it. Six manifests declare `[tool.mypy]` and three set
+ `strict = true`, so three authors had asked for a check that had never once
+ run. It runs now. The 690 findings are recorded in
+ `scripts/mypy_baseline.json` exactly as mypy reports them, keyed on
+ `(tree, file, error-code)` so an error cannot be introduced under cover of
+ fixing an unrelated one — no `ignore_errors`, no widened config, no excluded
+ tree. Both directions: a finding above baseline fails, and a *fixed* finding
+ still in the baseline fails too, so freed headroom must be banked rather
+ than left to absorb the next regression.
+
+ Its first run against a rebased tree earned the gate: 22 findings — 14
+ `union-attr`, 8 `arg-type` — in `services/api/app/services/playbook_step_dispatch.py`,
+ a file merged hours earlier that nothing had ever type-checked. They are
+ recorded rather than fixed because that file belongs to concurrent work;
+ what matters is that they are now visible and cannot grow. Five other
+ findings were real null-safety bugs in `services/fusion` — an
+ `IsolationForest` and an `LGBMRanker` used before training, and the Kafka
+ consumer and producer used before `start()` assigns them — and those are
+ fixed, taking fusion from 7 to 2.
+
+- **`Reproducible builds` now proves the property for all thirteen Python
+ services, not one.** The `twice` job asserted byte-identical resolution for
+ `api` alone; the other twelve used the same mechanism and nothing checked
+ it. A nightly matrix (03:17 UTC) double-builds all twelve services that have
+ a Dockerfile and double-installs the thirteenth, `teams-bot`, which has a
+ lock but no image. The matrix is derived from the tree rather than
+ hand-listed, and a `coverage` job fails when the number of services proved
+ is not the number that exist — a scheduled run that silently covers less
+ than it claims is the `wet-eval` failure, eight green weekly runs with every
+ real step skipped.
+
- **The console's `ConnectorType` union is generated from the connector
registry.** Its members were corrected in the previous release; the
mechanism that let them drift was not. Hand-maintenance is how ten of them
diff --git a/apps/docs/docs/contributing/reproducible-builds.md b/apps/docs/docs/contributing/reproducible-builds.md
index 4c31b8507..30d8e1b25 100644
--- a/apps/docs/docs/contributing/reproducible-builds.md
+++ b/apps/docs/docs/contributing/reproducible-builds.md
@@ -4,14 +4,22 @@ sidebar_position: 3
# Reproducible builds
-Every Python service installs from a committed `poetry.lock`. Two builds of one
-commit install byte-identical versions, and nothing re-resolves at image build
-time.
+Every Python service installs from a committed `poetry.lock`, every Go module
+from a committed `go.sum`, and every Node install from `pnpm-lock.yaml` or
+`package-lock.json`. Two builds of one commit install byte-identical versions,
+and nothing re-resolves at image build time.
If you change a dependency, **re-lock in the same commit**. That is the whole
contributor-facing rule; the rest of this page explains what enforces it and
why it exists.
+Two gates, one property:
+
+| Gate | Asks |
+|---|---|
+| `scripts/check_dependency_pins.py` | do all install paths agree on each **package** version |
+| `scripts/check_toolchain_pins.py` | do all paths agree on each **runtime** version, and is every install **locked** |
+
## Changing a dependency
```bash
@@ -65,6 +73,90 @@ than a preference:
Every other dependency may differ per service. They are separate images and
nothing crosses between them, so forcing agreement there would be noise.
+## Go and Node
+
+Same property, different ecosystems, and one extra failure mode: a Node
+install can simply decline to use the lockfile sitting next to it.
+
+```bash
+python scripts/check_toolchain_pins.py --verbose # every path it scanned and every version it compared
+python scripts/check_toolchain_pins.py --self-test # proves it still detects injected drift
+```
+
+**Every Node install must be locked.** `pnpm install` needs
+`--frozen-lockfile`; `npm install` should be `npm ci`. An image that installs
+Node dependencies must also **copy the lockfile into its build context** — the
+two go together, because `npm ci` without the lockfile in context fails and
+`npm install` without it silently re-resolves. `apps/mobile` is the one
+declared exemption: it sits outside the root workspace with a lockfile of its
+own, so a root refresh must not red it.
+
+**Every Go module must have its checksums.** Copy `go.sum` unconditionally,
+never as `go.sum*` — the glob makes the checksum file optional, so deleting it
+downgrades the build to an unverified resolve without failing anything. Every
+`go.mod` must also be compiled by some workflow; `packages/sdk-go` was not, and
+so was never built by CI at all.
+
+**esbuild overrides stay scoped.** `package.json` pins `vite>esbuild` and
+`tsup>esbuild` per parent rather than workspace-wide, because Next bundles its
+own esbuild and a workspace-wide override replaces it — which breaks
+Turbopack's font import map. That scoping means a `vite` bump can pull a
+different esbuild with no esbuild line in the diff, so the gate also pins the
+**resolved** set in `EXPECTED_ESBUILD`. Moving it is a deliberate edit, not a
+side effect.
+
+## One toolchain version, everywhere
+
+A workflow compiling with a different Go or Node version than the Dockerfile
+ships is the package problem one level up: CI proves something about software
+the image does not contain.
+
+| Runtime | Version | Declared in |
+|---|---|---|
+| Go | 1.26 | every `go.mod` directive, every `setup-go`, every `FROM golang:` |
+| Node | 22 | every `setup-node`, both Node images, the devcontainer, `install.sh` |
+| pnpm | 8.15.1 | `packageManager`, `apps/web/Dockerfile`, `install.sh` |
+| Python | 3.11 in every service image | every `FROM python:`, every manifest floor |
+
+The gate compares these in both directions — a version an image ships that no
+workflow exercises, *and* a version a workflow uses that no image ships —
+because CI versions get bumped and Dockerfiles get forgotten, and a
+one-directional check misses exactly that.
+
+`pnpm/action-setup` is `v6.0.9` everywhere except `e2e.yml` and
+`visual-regression.yml`, which stay on v4 for a measured reason recorded in
+`PNPM_ACTION_EXEMPT`: they run inside the Playwright container, which ships a
+global pnpm 11.x, and under v6 pnpm self-switches down to the `packageManager`
+pin in a way that leaves `@tailwindcss/oxide`'s native binding unlinked.
+
+**Python is the weaker case, and it is recorded rather than closed.** The
+service manifests declare `python = "^3.11"`, which permits 3.12, so the 24
+workflows running 3.12 violate nothing written down — but every image ships
+3.11, so what CI exercises is not what production runs. Closing it means
+moving 24 workflows or re-locking 13 manifests. Until then the set is listed
+in `PYTHON_INTERPRETER_SPLIT` and may not grow: a workflow that joins it
+without being listed fails, and a listed workflow that no longer differs fails
+too.
+
+## Type checking
+
+`scripts/check_mypy_baseline.py` runs mypy over every tree that declares a
+`[tool.mypy]` table and fails when any finding grows. The findings are
+recorded in `scripts/mypy_baseline.json` exactly as mypy reports them — no
+widened config, no excluded tree, and `strict = true` stays strict.
+
+The baseline is only reproducible against a fixed environment: **mypy alone,
+no project dependencies installed, on Python 3.12**, which is what CI does.
+Re-record under the same conditions:
+
+```bash
+docker run --rm -v "$PWD":/w -w /w python:3.12-slim \
+ bash -c "pip install 'mypy>=1.10,<2' && python scripts/check_mypy_baseline.py --update"
+```
+
+Fixing a finding requires re-recording too, so the freed headroom cannot
+silently absorb the next one.
+
## Why this exists
On 2026-09-24 the `One real event through the real pipeline` job failed, then
diff --git a/apps/docs/docs/installation.md b/apps/docs/docs/installation.md
index e33e810a9..5972c8dfb 100644
--- a/apps/docs/docs/installation.md
+++ b/apps/docs/docs/installation.md
@@ -55,7 +55,7 @@ target component is already installed at a sufficient version.
the `docker` service, then adds the invoking user to the `docker`
group with a one-shot `sg docker -c …` so you don't have to log
out and back in for the same install run.
-3. **Node.js 20 LTS** via the official NodeSource APT repo, the Fedora
+3. **Node.js 22 LTS** via the official NodeSource APT repo, the Fedora
NodeJS module, the relevant native package on Arch / openSUSE /
Alpine, or `brew install node@20` on macOS.
4. **pnpm 8+** via `corepack enable && corepack prepare pnpm@latest`.
@@ -85,7 +85,7 @@ target component is already installed at a sufficient version.
4. **Docker Desktop** via `winget install --id Docker.DockerDesktop`.
The script waits for the Docker Engine socket to come up before
proceeding.
-5. **Node.js 20 LTS** via `winget install --id OpenJS.NodeJS.LTS`.
+5. **Node.js 22 LTS** via `winget install --id OpenJS.NodeJS.LTS`.
6. **pnpm 8+** via `corepack enable && corepack prepare pnpm@latest`.
7. **The AiSOC repo** — cloned to `$env:USERPROFILE\aisoc` (override
with `-AisocDir 'C:\path\to\clone'`).
diff --git a/apps/docs/docs/operations/codespaces.md b/apps/docs/docs/operations/codespaces.md
index f7ccb2e5d..6a5769d63 100644
--- a/apps/docs/docs/operations/codespaces.md
+++ b/apps/docs/docs/operations/codespaces.md
@@ -14,7 +14,7 @@ The image is published at
[`ghcr.io/beenuar/aisoc-devcontainer:latest`](https://github.com/beenuar/AiSOC/pkgs/container/aisoc-devcontainer)
on every push to `main`. It carries:
-- Node 20 + `[email protected]` via `corepack`
+- Node 22 + `[email protected]` via `corepack`
- Python 3.11 + [`uv`](https://github.com/astral-sh/uv) + `ruff`
- Go 1.22
- Docker CE 20.x (`docker.io`) + Compose v2 plugin
diff --git a/apps/web/Dockerfile b/apps/web/Dockerfile
index 95937bb11..2767b7111 100644
--- a/apps/web/Dockerfile
+++ b/apps/web/Dockerfile
@@ -1,9 +1,13 @@
# AiSOC Web Frontend Dockerfile
# Multi-stage build for production. Build context = monorepo root.
-FROM node:20-alpine AS base
+FROM node:22-alpine AS base
RUN apk add --no-cache libc6-compat
-RUN npm install -g pnpm@8
+# Pinned to the exact version `package.json`'s `packageManager` field declares
+# and `install.sh` installs. `pnpm@8` floats across the 8.x line, so the image
+# could resolve the lockfile with a different pnpm than CI — two resolvers,
+# two answers to what this commit installs.
+RUN npm install -g [email protected]
# ─── Builder ──────────────────────────────────────────────────────────────────
# Single-stage install + build keeps pnpm's symlinked workspace layout
@@ -13,7 +17,9 @@ FROM base AS builder
WORKDIR /app
COPY package.json pnpm-workspace.yaml ./
-COPY pnpm-lock.yaml* ./
+# Not `pnpm-lock.yaml*`: the glob makes the lockfile optional, so a build with
+# no lockfile in context would succeed and resolve its own dependency tree.
+COPY pnpm-lock.yaml ./
COPY turbo.json ./
COPY tsconfig.base.json ./
COPY VERSION ./
@@ -93,7 +99,14 @@ ENV NEXT_PUBLIC_DEMO_AUTOLOGIN_PASSWORD=${NEXT_PUBLIC_DEMO_AUTOLOGIN_PASSWORD}
# Use pnpm's default symlinked node_modules — same layout as local dev,
# so tsup/tsc bin shims resolve correctly inside each workspace package.
-RUN pnpm install --no-frozen-lockfile
+#
+# `--frozen-lockfile`, matching every workflow that installs this workspace.
+# It was `--no-frozen-lockfile`, which made the production web image the one
+# install path in the repository free to resolve its own answer: the bundle
+# users are served could be built from a dependency set no CI job had ever
+# installed. If this now fails, the lockfile is stale — run `pnpm install` and
+# commit the result rather than relaxing the flag.
+RUN pnpm install --frozen-lockfile
# Build workspace packages then the Next.js app. @aisoc/report-card must be
# built here too — the /tools/coverage page imports it, and without its dist the
diff --git a/docs/QUICK_INSTALL.md b/docs/QUICK_INSTALL.md
index 8bdec594b..94b1e059d 100644
--- a/docs/QUICK_INSTALL.md
+++ b/docs/QUICK_INSTALL.md
@@ -4,7 +4,7 @@ AiSOC ships with two one-click bootstrap installers. They take a freshly-imaged
machine to a running AiSOC dashboard in your browser, with **zero assumed
prerequisites**, in a single command.
-If you already have Docker, Node 20, pnpm 8+, and git installed, you don't need
+If you already have Docker, Node 22, pnpm 8+, and git installed, you don't need
these scripts — just run `pnpm aisoc:demo` from a clone. These installers exist
for the case where you don't (or you're handing the repo to someone who
doesn't).
@@ -38,7 +38,7 @@ needs, and only if they are missing or too old:
| ---------------------- | --------------------------------- | ---------------------- | -------------------------------- |
| `git` | distro package manager | `winget Git.Git` | clone the repo |
| Docker Engine + Compose v2 | distro package manager (Linux), `brew install --cask docker` (macOS) | `winget Docker.DockerDesktop` (+ WSL2) | run the AiSOC stack |
-| Node.js 20 LTS | NodeSource (Linux), `brew` (macOS) | `winget OpenJS.NodeJS.LTS` | drive `pnpm aisoc:demo` |
+| Node.js 22 LTS | NodeSource (Linux), `brew` (macOS) | `winget OpenJS.NodeJS.LTS` | drive `pnpm aisoc:demo` |
| pnpm 8+ | `corepack enable` + `corepack prepare pnpm@latest` | same | install Node deps |
**It does not install:** Python, Go, Rust, Postgres, Redis, Kafka,
diff --git a/docs/architecture/SYSTEM_DESIGN.md b/docs/architecture/SYSTEM_DESIGN.md
index f486ac747..8ec52dfc3 100644
--- a/docs/architecture/SYSTEM_DESIGN.md
+++ b/docs/architecture/SYSTEM_DESIGN.md
@@ -101,8 +101,8 @@ This document describes the end-to-end architecture of the AiSOC platform after
| `services/osquery-tls` | Go 1.25 | TLS server for osquery enrol / config / distributed / log endpoints | Ships normalised host events into `services/ingest` |
| `services/osquery-extensions` | Go 1.25 | Out-of-band osquery extensions (custom virtual tables + decorators) | Loaded by `osquery-tls`-managed agents |
| `services/slack-bot` | Python 3.11 | ChatOps surface: posts approval prompts, `/aisoc` slash command | Verifies inbound interactions with HMAC-signed Slack request signatures |
-| `services/realtime` | Node 20 | WebSocket fan-out + Web Push for the web console + Responder PWA | n/a |
-| `services/mcp` | Node 20 (TypeScript) | Model Context Protocol stdio server, 13 tools for IDE-side agents (Claude / Cursor / Continue / Cody) — discovery, deep-dive, action/replay, and the warm-tier lake query pair (`aisoc_lake_schema`, `aisoc_lake_query`) | n/a |
+| `services/realtime` | Node 22 | WebSocket fan-out + Web Push for the web console + Responder PWA | n/a |
+| `services/mcp` | Node 22 (TypeScript) | Model Context Protocol stdio server, 13 tools for IDE-side agents (Claude / Cursor / Continue / Cody) — discovery, deep-dive, action/replay, and the warm-tier lake query pair (`aisoc_lake_schema`, `aisoc_lake_query`) | n/a |
| `apps/web` | Next.js 14 | Server components + SWR + Responder PWA route group + benchmark scoreboard | n/a |
---
@@ -416,7 +416,7 @@ Two cross-platform bootstrap installers live at the repo root:
* `install.sh` — Linux + macOS bash; supports `apt`, `dnf`, `pacman`, `zypper`, `apk`, and `brew`. Idempotent; safe to re-run.
* `install.ps1` — Windows PowerShell; uses `winget` and handles WSL2 enablement for Docker Desktop.
-Both detect the OS, install missing prerequisites (git, Docker Engine + Compose v2 / Docker Desktop, Node.js 20 LTS, pnpm 8+ via `corepack`), clone the repo into `~/aisoc`, then invoke `pnpm aisoc:demo` to bring up the slim demo stack from the published GHCR images and open the browser at the seeded LockBit case. Companion uninstallers (`uninstall.sh`, `uninstall.ps1`) provide graduated cleanup — stop stack only, drop volumes, remove pulled images, delete `node_modules`, delete the repo clone — gated behind interactive confirmation prompts unless `--all --yes` is supplied.
+Both detect the OS, install missing prerequisites (git, Docker Engine + Compose v2 / Docker Desktop, Node.js 22 LTS, pnpm 8+ via `corepack`), clone the repo into `~/aisoc`, then invoke `pnpm aisoc:demo` to bring up the slim demo stack from the published GHCR images and open the browser at the seeded LockBit case. Companion uninstallers (`uninstall.sh`, `uninstall.ps1`) provide graduated cleanup — stop stack only, drop volumes, remove pulled images, delete `node_modules`, delete the repo clone — gated behind interactive confirmation prompts unless `--all --yes` is supplied.
→ [One-click install (Docusaurus)](../../apps/docs/docs/installation.md)
→ [Quick install reference](../QUICK_INSTALL.md)
diff --git a/docs/operations/live-demo-runbook.md b/docs/operations/live-demo-runbook.md
index 311f40652..cc04ea9e4 100644
--- a/docs/operations/live-demo-runbook.md
+++ b/docs/operations/live-demo-runbook.md
@@ -9,7 +9,7 @@ AiSOC instance running on Fly.io, fronted by a Cloudflare Tunnel. It is
**Always-on fallback:** open the repo in
[GitHub Codespaces](https://codespaces.new/beenuar/AiSOC?quickstart=1).
The devcontainer at [`.devcontainer/devcontainer.json`](.devcontainer/devcontainer.json)
-will bring up Node 20, Python 3.11, Go 1.22, Docker-in-Docker, and the
+will bring up Node 22, Python 3.11, Go 1.26, Docker-in-Docker, and the
GitHub CLI for you. Then:
```bash
diff --git a/install.ps1 b/install.ps1
index d24204a0a..3bc282f0d 100644
--- a/install.ps1
+++ b/install.ps1
@@ -12,7 +12,7 @@
3. Installs (idempotently) the four prerequisites AiSOC needs:
- Git
- Docker Desktop (which bundles Docker Engine + Compose v2)
- - Node.js 20 LTS
+ - Node.js 22 LTS
- pnpm 8+ (via corepack)
All installs go through winget, the official Windows package
manager. We never download random installers from the internet.
@@ -502,7 +502,7 @@ function Test-DockerDaemon {
exit 2
}
-# ─── Step 3: Node.js 20 LTS ───────────────────────────────────────────────
+# ─── Step 3: Node.js 22 LTS ───────────────────────────────────────────────
function Install-Node {
$major = Get-CommandMajorVersion -Name 'node'
@@ -513,7 +513,7 @@ function Install-Node {
Write-Ok "node already installed: $((& node --version))"
return
}
- Install-WingetPackage -Id 'OpenJS.NodeJS.LTS' -DisplayName 'Node.js 20 LTS'
+ Install-WingetPackage -Id 'OpenJS.NodeJS.LTS' -DisplayName 'Node.js 22 LTS'
if (-not (Test-CommandExists node)) {
Stop-WithError "node was installed via winget but isn't on PATH. Open a new PowerShell window and re-run this script."
}
diff --git a/install.sh b/install.sh
index 53227318a..adf7fad83 100755
--- a/install.sh
+++ b/install.sh
@@ -10,7 +10,7 @@
# 2. Installs (idempotently) the four prerequisites AiSOC needs:
# - git
# - Docker Engine + Docker Compose v2 plugin
-# - Node.js 20 LTS
+# - Node.js 22 LTS
# - pnpm 8+ (via corepack)
# 3. Clones the AiSOC repo (if you ran the script as a one-liner) or
# reuses it (if you ran ./install.sh from inside a clone).
@@ -561,39 +561,40 @@ ensure_docker_daemon() {
exit 2
}
-# ─── Step 3: Node.js 20 LTS ──────────────────────────────────────────────────
+# ─── Step 3: Node.js 22 LTS ──────────────────────────────────────────────────
ensure_node() {
- # We need Node >= 20 because tsx 4 + the workspace's "engines" field both
- # require it. Node 18 reaches LTS end-of-life in April 2025 so we don't
- # support it.
- if version_at_least node 20 "node --version"; then
+ # Node 22, the version every workflow tests on and both Node images ship.
+ # Installing 20 here handed a self-hoster a different runtime from the one
+ # the project builds and tests against, and Node 20 left security support
+ # in April 2026.
+ if version_at_least node 22 "node --version"; then
ok "node already installed: $(node --version)"
return 0
fi
- info "Installing Node.js 20 LTS via $PKG_MGR..."
+ info "Installing Node.js 22 LTS via $PKG_MGR..."
case "$PKG_MGR" in
apt)
# NodeSource is the upstream-blessed apt repo for current Node releases.
- curl -fsSL https://deb.nodesource.com/setup_20.x | $SUDO bash -
+ curl -fsSL https://deb.nodesource.com/setup_22.x | $SUDO bash -
$SUDO apt-get install -y nodejs
;;
dnf|yum)
- curl -fsSL https://rpm.nodesource.com/setup_20.x | $SUDO bash -
+ curl -fsSL https://rpm.nodesource.com/setup_22.x | $SUDO bash -
$SUDO "$PKG_MGR" install -y nodejs
;;
pacman) $SUDO pacman -Sy --noconfirm --needed nodejs npm ;;
zypper)
- $SUDO zypper -n install -y nodejs20 npm20 \
+ $SUDO zypper -n install -y nodejs22 npm22 \
|| $SUDO zypper -n install -y nodejs npm
;;
apk) $SUDO apk add --no-cache nodejs npm ;;
- brew) brew install node@20 && brew link --overwrite --force node@20 ;;
+ brew) brew install node@22 && brew link --overwrite --force node@22 ;;
*) die "don't know how to install Node on PKG_MGR=$PKG_MGR" ;;
esac
have node || die "node install reported success but node is still not on PATH."
- if ! version_at_least node 20 "node --version"; then
- warn "Installed Node version ($(node --version)) is older than 20; AiSOC may misbehave."
+ if ! version_at_least node 22 "node --version"; then
+ warn "Installed Node version ($(node --version)) is older than 22; AiSOC may misbehave."
else
ok "node installed: $(node --version)"
fi
@@ -748,8 +749,12 @@ ensure_env_file() {
run_pnpm_install() {
info "Installing JS workspace deps (pnpm install)..."
- ( cd "$REPO_ROOT" && pnpm install --prefer-offline --no-frozen-lockfile ) \
- || die "pnpm install failed."
+ # `--frozen-lockfile`, the same flag CI and the web image use. Without it a
+ # self-hoster's install is free to resolve a dependency set nobody tested,
+ # which is the one thing an installer must not do quietly.
+ ( cd "$REPO_ROOT" && pnpm install --prefer-offline --frozen-lockfile ) \
+ || die "pnpm install failed. If it reported a lockfile mismatch, your checkout's
+package.json and pnpm-lock.yaml disagree — re-clone or 'git checkout pnpm-lock.yaml'."
ok "pnpm dependencies installed."
}
diff --git a/scripts/check_mypy_baseline.py b/scripts/check_mypy_baseline.py
new file mode 100644
index 000000000..085503547
--- /dev/null
+++ b/scripts/check_mypy_baseline.py
@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""Run mypy, and refuse to let the result get worse.
+
+`ci.yml` has a job called **Python — Lint & Type-check**. It installed mypy
+and never invoked it. Six manifests carry a `[tool.mypy]` table and three of
+them set `strict = true`, so three authors explicitly asked for type checking
+that has never once run. A tool in the install list that never executes
+implies a check that is not happening, which is this repository's dominant
+defect wearing yet another costume — a workflow green on eight consecutive
+weekly runs with every real step skipped, a lint job printing "2/2 passed"
+while 32 of 62 packs did not match, three check scripts wired into no
+workflow at all.
+
+Two honest options existed: stop installing mypy, or run it. Running it wins,
+because the configuration says six trees want it.
+
+What this does *not* do is soften the answer to make it pass. There is no new
+`ignore_errors`, no added `ignore_missing_imports`, no `--no-strict-optional`,
+and no tree excluded from the check. `strict = true` stays strict and the
+tests are checked along with the source. The findings — 673 of them at the
+time of writing — are recorded in `scripts/mypy_baseline.json` exactly as
+mypy reports them, and the gate fails when any of them grows. A recorded
+finding is reported; a suppressed one is hidden, and the difference is the
+whole point.
+
+The baseline is keyed on `(tree, file, error-code)`. A bare per-tree total
+would let one error be introduced while an unrelated one is fixed, leaving
+the count flat and the gate silent — the same "compares a tally against
+everything except itself" shape that left a gate off by one while CI stayed
+green.
+
+Environment. mypy's answer depends on what is importable, so the baseline is
+only meaningful against a fixed environment: **mypy alone, no project
+dependencies installed, on the interpreter `ci.yml` uses**. That is what CI
+does and what `--update` must be run under. Anything else produces a
+different set of `import-untyped` findings and a baseline nobody can
+reproduce.
+
+Directions, because a one-directional gate is how drift escapes here:
+
+ findings -> baseline a finding not in the baseline, or more of one than
+ the baseline records, fails
+ baseline -> findings a baseline entry mypy no longer reports fails, so a
+ fixed error must be banked rather than left as
+ headroom for the next one
+ config -> baseline a tree declaring [tool.mypy] and absent from the
+ baseline fails, so adding a config does not quietly
+ add an unchecked tree
+ baseline -> config a baseline entry for a tree with no config fails
+
+Usage:
+ python scripts/check_mypy_baseline.py
+ python scripts/check_mypy_baseline.py --update # re-record, then read the diff
+ python scripts/check_mypy_baseline.py --self-test
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import tomllib
+from collections import defaultdict
+from pathlib import Path
+
+BASELINE = Path("scripts/mypy_baseline.json")
+
+# `file:line: error: message [code]`
+_FINDING = re.compile(r"^(?P<file>[^:]+):\d+:(?:\d+:)?\s*error:\s*(?P<message>.*?)\s*(?:\[(?P<code>[\w-]+)\])?$")
+
+
+def discover(root: Path) -> list[str]:
+ """Every tree whose manifest declares a [tool.mypy] table.
+
+ Structural: it asks the manifests what they configured, rather than
+ matching a directory naming convention that a new service would not
+ follow.
+ """
+ trees: list[str] = []
+ for manifest in sorted(root.glob("services/*/pyproject.toml")) + sorted(root.glob("packages/*/pyproject.toml")):
+ data = tomllib.loads(manifest.read_text(encoding="utf-8"))
+ if "mypy" in data.get("tool", {}):
+ trees.append(manifest.parent.relative_to(root).as_posix())
+ return trees
+
+
+def run_mypy(root: Path, tree: str) -> tuple[dict[str, dict[str, int]], str]:
+ """Findings for one tree, as {relative file: {error code: count}}."""
+ completed = subprocess.run( # noqa: S603 - fixed argv, no shell
+ [sys.executable, "-m", "mypy", "--no-color-output", "--no-error-summary", "."],
+ cwd=root / tree,
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ findings: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+ for line in completed.stdout.splitlines():
+ match = _FINDING.match(line.strip())
+ if not match:
+ continue
+ findings[match.group("file")][match.group("code") or "no-code"] += 1
+ # mypy exits 1 for findings and 2 for a crash or a bad invocation. Treating
+ # those the same would turn "mypy could not run" into "mypy found nothing",
+ # which is the failure this whole file exists to stop.
+ if completed.returncode not in (0, 1):
+ return {}, f"{tree}: mypy exited {completed.returncode} — {completed.stderr.strip()[:400]}"
+ return {f: dict(c) for f, c in findings.items()}, ""
+
+
+def compare(tree: str, found: dict[str, dict[str, int]], recorded: dict[str, dict[str, int]]) -> list[str]:
+ problems: list[str] = []
+ for file in sorted(set(found) | set(recorded)):
+ seen, known = found.get(file, {}), recorded.get(file, {})
+ for code in sorted(set(seen) | set(known)):
+ now, before = seen.get(code, 0), known.get(code, 0)
+ if now > before:
+ problems.append(
+ f"{tree}/{file}: {now} `{code}` finding(s), baseline records {before} "
+ f"(findings -> baseline). Fix it, or if it is genuinely correct add a "
+ f"targeted `# type: ignore[{code}]` with a comment — do not widen the config"
+ )
+ elif now < before:
+ problems.append(
+ f"{tree}/{file}: {now} `{code}` finding(s), baseline still records {before} "
+ f"(baseline -> findings). Run --update to bank the fix, so the headroom "
+ f"does not silently absorb the next one"
+ )
+ return problems
+
+
+def load(root: Path) -> dict:
+ path = root / BASELINE
+ return json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+
+
+def run(root: Path, update: bool = False) -> int:
+ trees = discover(root)
+ if not trees:
+ print(f"check_mypy_baseline: no tree under {root} declares [tool.mypy]")
+ return 1
+
+ recorded = load(root)
+ results: dict[str, dict[str, dict[str, int]]] = {}
+ problems: list[str] = []
+
+ print(f"check_mypy_baseline: root {root}")
+ for tree in trees:
+ found, error = run_mypy(root, tree)
+ if error:
+ problems.append(error)
+ continue
+ results[tree] = found
+ total = sum(sum(c.values()) for c in found.values())
+ print(f" {tree}: {total} finding(s) across {len(found)} file(s)")
+
+ if update:
+ (root / BASELINE).write_text(json.dumps(results, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ total = sum(sum(sum(c.values()) for c in f.values()) for f in results.values())
+ print(f"check_mypy_baseline: recorded {total} finding(s) across {len(results)} tree(s) in {BASELINE}")
+ return 1 if problems else 0
+
+ for tree in sorted(results):
+ if tree not in recorded:
+ problems.append(
+ f"{tree} declares [tool.mypy] but has no baseline entry — a tree added "
+ f"without being recorded is a tree nothing checks (config -> baseline)"
+ )
+ continue
+ problems += compare(tree, results[tree], recorded[tree])
+ for tree in sorted(set(recorded) - set(trees)):
+ problems.append(
+ f"{BASELINE} records `{tree}`, which no longer declares [tool.mypy] — "
+ f"remove it rather than leaving a baseline for a tree nobody checks "
+ f"(baseline -> config)"
+ )
+
+ total = sum(sum(sum(c.values()) for c in f.values()) for f in results.values())
+ print(f" {total} finding(s) total, {len(trees)} tree(s) checked: {', '.join(trees)}")
+
+ if problems:
+ print("check_mypy_baseline: FAIL")
+ for problem in problems:
+ print(f" - {problem}")
+ return 1
+ print("check_mypy_baseline: OK — no tree got worse")
+ return 0
+
+
+def self_test(root: Path) -> int:
+ """Prove the comparison reports drift in each direction.
+
+ `compare` is tested directly rather than through a throwaway repository:
+ a fixture would need a working mypy install per case, and the property
+ under test is the comparison, not mypy.
+ """
+ cases = [
+ ("a new finding", {"a.py": {"arg-type": 1}}, {}, "findings -> baseline"),
+ ("more of a known finding", {"a.py": {"arg-type": 2}}, {"a.py": {"arg-type": 1}}, "findings -> baseline"),
+ ("a fixed finding left banked", {}, {"a.py": {"arg-type": 1}}, "baseline -> findings"),
+ (
+ "one swapped for another, total unchanged",
+ {"a.py": {"union-attr": 1}},
+ {"a.py": {"arg-type": 1}},
+ "findings -> baseline",
+ ),
+ ("unchanged", {"a.py": {"arg-type": 1}}, {"a.py": {"arg-type": 1}}, None),
+ ]
+ failures: list[str] = []
+ for name, found, recorded, expect in cases:
+ problems = compare("t", found, recorded)
+ blob = " ".join(problems)
+ if expect is None:
+ failure = f"{name}: expected no problem, got {problems}" if problems else None
+ elif not problems:
+ failure = f"{name}: injected drift went UNDETECTED"
+ elif expect not in blob:
+ failure = f"{name}: detected something else — {problems}"
+ else:
+ failure = None
+ if failure:
+ failures.append(failure)
+ print(f" self-test [{'FAIL' if failure else 'ok'}] {name}")
+
+ # The baseline must describe this tree, not a remembered one.
+ trees, recorded = discover(root), load(root)
+ if trees and recorded and set(trees) != set(recorded):
+ failures.append(f"baseline covers {sorted(recorded)} but the tree declares {sorted(trees)}")
+ print(f" self-test [{'FAIL' if failures and 'baseline covers' in failures[-1] else 'ok'}] baseline matches the tree")
+
+ if failures:
+ print("\ncheck_mypy_baseline --self-test: FAIL")
+ for failure in failures:
+ print(f" - {failure}")
+ return 1
+ print(f"\ncheck_mypy_baseline --self-test: OK — {len(cases) + 1} cases")
+ return 0
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--repo-root", type=Path, default=None)
+ parser.add_argument("--update", action="store_true", help="re-record the baseline from this run")
+ parser.add_argument("--self-test", action="store_true", help="prove the comparison detects drift")
+ args = parser.parse_args()
+
+ root = (args.repo_root or Path(__file__).resolve().parent.parent).resolve()
+ if not (root / "services").is_dir():
+ print(f"{root} does not look like the AiSOC repository (no services/)")
+ return 1
+ return self_test(root) if args.self_test else run(root, update=args.update)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/check_toolchain_pins.py b/scripts/check_toolchain_pins.py
new file mode 100644
index 000000000..f4b5f2b45
--- /dev/null
+++ b/scripts/check_toolchain_pins.py
@@ -0,0 +1,1429 @@
+#!/usr/bin/env python3
+"""Assert the Go and Node halves of this build are as deterministic as the Python half.
+
+``scripts/check_dependency_pins.py`` made every *package* install path agree.
+It stopped at the Python services, and named what it left behind: the six Go
+modules have ``go.sum`` and the pnpm workspace has ``pnpm-lock.yaml``, so the
+raw material for reproducibility was there, but nothing compared the paths that
+use it and nothing audited the *toolchain* those paths run on.
+
+Both gaps are the same defect one level up. A workflow that compiles with a
+different Go or Node version than the Dockerfile ships is testing different
+software, in exactly the way CI installing ``cryptography>=41,<46`` while the
+service required ``>=46,<51`` meant the version CI tested could never be the
+version the image shipped. A lockfile that CI enforces and the production image
+opts out of is the pip fallback wearing a different hat: the image boots on a
+dependency set nobody tested and the traceback points somewhere innocent.
+
+Measured on this repository before this gate existed:
+
+* ``apps/web/Dockerfile`` ran ``pnpm install --no-frozen-lockfile`` while all
+ thirteen workflows that install the same workspace run ``--frozen-lockfile``.
+ The production web image was the one install path in the repository free to
+ resolve its own answer.
+* ``services/realtime`` committed a ``package-lock.json`` and then never copied
+ it into its image, which runs ``npm install`` twice. The lockfile was inert.
+* ``apps/web/Dockerfile`` installed ``pnpm@8`` — any 8.x — while
+ ``package.json`` pins ``[email protected]`` and ``install.sh`` installs exactly
+ ``8.15.1``. Two resolvers, two answers, the ``poetry 1.7.1 vs 1.8.2`` finding
+ again.
+* Node: two images and the devcontainer shipped 20 while thirteen workflows
+ tested on 22.
+* ``services/enrichment/Dockerfile`` copied ``go.sum*`` — the glob makes the
+ checksum file optional, so deleting it downgrades the build to an unverified
+ resolve without failing.
+* ``ci.yml`` pointed ``cache-dependency-path`` at two ``go.sum`` files that do
+ not exist. ``setup-go`` reports that as a *warning*, so the cache had been
+ silently disabled while the job stayed green.
+
+Directions. The dominant failure shape in this repository is a one-directional
+gate that compares A against B and never B against A, so drift in the direction
+things actually change slips through while the gate prints OK. Every comparison
+below runs both ways, and ``--self-test`` injects drift in each direction
+separately and asserts this file reports it:
+
+ agreement every path declaring a runtime must name the same version
+ ship -> test a version an image ships that no CI path exercises
+ test -> ship a version CI exercises that no image ships
+ floor <= toolchain
+ a `go`/`requires-python` floor above the toolchain installed
+ unlocked install an install path free to resolve outside the lockfile
+ dead lockfile a committed lockfile that no install path consumes
+ module -> sum a Go module with requirements and no checksum file
+ sum -> module a checksum file with no module, or a cache path naming a
+ file that does not exist
+ module -> CI a Go module no workflow builds
+ CI -> module a workflow building a module directory that is not there
+ override scope an `esbuild` override that escapes its parent package
+ coverage a file declaring a runtime or an install path that this
+ gate never opened
+ parser coverage a file this gate *did* open whose declaration the parser
+ could not read — the blind spot `check_dependency_pins`
+ found in itself on its first run
+
+Usage:
+ python scripts/check_toolchain_pins.py [--repo-root PATH] [--verbose]
+ python scripts/check_toolchain_pins.py --self-test
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# ── The runtimes whose version must agree ────────────────────────────────────
+#
+# A runtime earns a row when two versions of it are two different behaviours
+# for code in this tree, not merely two different numbers.
+RUNTIMES: dict[str, str] = {
+ "go": (
+ "the compiler. `go vet` and the escape analysis that decides whether "
+ "the ingest hot path allocates both change between minors, and the "
+ "`go` directive in go.mod selects language semantics"
+ ),
+ "node": (
+ "the runtime `services/realtime` and the Next.js server actually "
+ "execute on. 20 and 22 differ in the fetch/undici stack, the test "
+ "runner and OpenSSL, and Node 20 left security support in April 2026"
+ ),
+ "pnpm": (
+ "the resolver that turns pnpm-lock.yaml into node_modules. Two "
+ "resolvers are two answers to 'what does this commit install' — the "
+ "same defect as two poetry versions, which this repository already hit"
+ ),
+ "python": ("the interpreter the thirteen Python services run on. Their manifests " "declare ^3.11 and every image ships 3.11"),
+}
+
+# ── Declared exemptions ──────────────────────────────────────────────────────
+#
+# An exemption without a reason is a hole. Each of these is a measured
+# decision recorded where the gate can show it, so a future reader can
+# challenge it rather than inherit it.
+
+# The pnpm action version every workflow uses unless exempted below. Declared
+# rather than inferred from a majority vote: with a vote, flipping enough
+# workflows moves the "correct" answer and the gate ratifies the drift it
+# exists to catch.
+PNPM_ACTION_VERSION = "v6.0.9"
+
+# Workflows deliberately not on the repo-wide pnpm action version.
+PNPM_ACTION_EXEMPT: dict[str, str] = {
+ ".github/workflows/e2e.yml": (
+ "runs inside mcr.microsoft.com/playwright, which ships a global "
+ "pnpm 11.x. action-setup@v6 self-switches down to the packageManager "
+ "pin and leaves @tailwindcss/oxide's native binding unlinked in the "
+ "restored store; v4 installs 8.15.1 directly with no switch"
+ ),
+ ".github/workflows/visual-regression.yml": (
+ "same Playwright container and the same pnpm self-switch; pinning " "`version:` under v6 does not avoid it"
+ ),
+}
+
+# Install paths allowed to resolve outside the lockfile, with the reason.
+UNLOCKED_INSTALL_EXEMPT: dict[str, str] = {
+ ".github/workflows/mobile.yml": (
+ "apps/mobile is deliberately outside the root pnpm workspace and "
+ "keeps its own lockfile, so a root lockfile refresh must not red it"
+ ),
+}
+
+# Workflows that run a Python interpreter the service images do not ship.
+#
+# This is a real gap, recorded rather than closed, and it is weaker than the
+# Go and Node checks on purpose — saying so is the point. Every service
+# manifest declares `python = "^3.11"`, which *permits* 3.12, so none of these
+# workflows violates anything written down; but every image ships 3.11, so
+# what CI exercises is not what production runs. That is the same shape as a
+# workflow compiling on a different Go version, one notch milder because the
+# ranges overlap instead of being disjoint.
+#
+# Closing it means moving twenty-four workflows to 3.11 or thirteen images to
+# 3.12 and re-locking all thirteen manifests; neither belongs in the change
+# that discovered it. What is enforced meanwhile is that the set cannot grow
+# silently and cannot rot: a workflow added to the split without being listed
+# fails, and a listed workflow that no longer differs fails too.
+PYTHON_INTERPRETER_SPLIT: set[str] = {
+ ".github/workflows/adoption-snapshot.yml",
+ ".github/workflows/ai-sdk.yml",
+ ".github/workflows/attribution.yml",
+ ".github/workflows/check-openapi.yml",
+ ".github/workflows/ci.yml",
+ ".github/workflows/codeql-alert-gate.yml",
+ ".github/workflows/competitor-names.yml",
+ ".github/workflows/cross-tenant-rbac.yml",
+ ".github/workflows/golden-pipeline.yml",
+ ".github/workflows/governance.yml",
+ ".github/workflows/graph-schema-check.yml",
+ ".github/workflows/hosted-hostname.yml",
+ ".github/workflows/integration.yml",
+ ".github/workflows/isolation-live.yml",
+ ".github/workflows/isolation.yml",
+ ".github/workflows/openapi-breaking.yml",
+ ".github/workflows/papers.yml",
+ ".github/workflows/perf.yml",
+ ".github/workflows/python-detections.yml",
+ ".github/workflows/release.yml",
+ ".github/workflows/reproducible-builds.yml",
+ ".github/workflows/security-audit.yml",
+ ".github/workflows/security.yml",
+ ".github/workflows/wet-eval.yml",
+}
+
+# Every resolved esbuild version pnpm-lock.yaml is expected to contain.
+#
+# The overrides in package.json are scoped per parent (`vite>esbuild`) rather
+# than workspace-wide, because forcing esbuild across the workspace broke
+# Turbopack's font import map — Next bundles its own copy and must keep it.
+# That scoping means a `vite` bump can pull a different esbuild through the
+# override without any esbuild line changing in the diff, so the resolved set
+# is pinned here and a change has to be made deliberately.
+EXPECTED_ESBUILD: dict[str, str] = {
+ "0.25.12": "bundled by Next.js — must not be overridden, see above",
+ "0.28.1": "the version the scoped tsup/vite/bundle-require overrides ask for",
+}
+
+# Prose, vendored history and generated artefacts.
+SKIP_PREFIXES = (
+ "plans/",
+ "apps/docs/",
+ "docs/",
+ "scripts/check_toolchain_pins.py",
+ "tests/test_toolchain_pin_gate.py",
+ "CHANGELOG.md",
+ "RELEASES.md",
+)
+
+# Directories that are downloaded or generated rather than written. Matched as
+# a *path segment*, not a prefix: `node_modules/` as a prefix misses
+# `services/realtime/node_modules/...`, and with dependencies installed this
+# gate scanned 223 vendored manifests and reported Node floors of `0.10` and
+# `6.* || 8.* || >= 10.*` from other people's packages. A gate whose answer
+# depends on whether someone has run `pnpm install` is not structural.
+SKIP_SEGMENTS = frozenset({"node_modules", ".git", ".venv", "venv", "dist", ".next", "vendor", "__pycache__"})
+
+
+def skipped(rel: str) -> bool:
+ return rel.startswith(SKIP_PREFIXES) or bool(SKIP_SEGMENTS & set(rel.split("/")))
+
+
+def walk(root: Path, name: str | None = None) -> list[Path]:
+ """Every non-skipped file under `root`, optionally filtered by filename.
+
+ `Path.rglob` has no way to prune a subtree, so it descends into every
+ `node_modules` before discarding the results — ten seconds on a checkout
+ with dependencies installed. Pruning at the directory level keeps the
+ gate fast enough that nobody is tempted to stop running it locally.
+ """
+ found: list[Path] = []
+ for parent, directories, files in os.walk(root):
+ directories[:] = [d for d in directories if d not in SKIP_SEGMENTS]
+ for filename in files:
+ if name is not None and filename != name:
+ continue
+ path = Path(parent) / filename
+ if not skipped(path.relative_to(root).as_posix()):
+ found.append(path)
+ return sorted(found)
+
+
+def normalise_version(raw: str) -> str:
+ """Reduce a runtime version to the precision that is actually pinned.
+
+ `node:22-alpine`, `'22'` and `22.11.0` are one toolchain written three
+ ways. Go and Node are compared at major.minor because that is the
+ precision every declaration in this tree carries; a patch release is not
+ a decision anyone made here.
+ """
+ digits = re.match(r"(\d+)(?:\.(\d+))?", raw.strip().strip("\"'"))
+ if not digits:
+ return raw.strip()
+ return f"{digits.group(1)}.{digits.group(2)}" if digits.group(2) else digits.group(1)
+
+
+def version_tuple(raw: str) -> tuple[int, ...]:
+ digits = re.match(r"(\d+(?:\.\d+)*)", raw.strip().strip("\"'"))
+ return tuple(int(p) for p in digits.group(1).split(".")) if digits else (0,)
+
+
+def _pad(left: tuple[int, ...], right: tuple[int, ...]) -> tuple[tuple[int, ...], tuple[int, ...]]:
+ width = max(len(left), len(right))
+ return left + (0,) * (width - len(left)), right + (0,) * (width - len(right))
+
+
+def at_most(floor: str, toolchain: str) -> bool:
+ """Whether a declared floor is satisfied by an installed toolchain."""
+ a, b = _pad(version_tuple(floor), version_tuple(toolchain))
+ return a <= b
+
+
+@dataclass
+class Pin:
+ """One runtime version, and the exact place it was written."""
+
+ runtime: str
+ version: str
+ path: str
+ # ship — a version an image or published artefact actually runs on
+ # test — a version CI compiles or tests with
+ # dev — the contributor toolchain (devcontainer, installer)
+ # floor — a minimum a manifest declares, not a toolchain that gets installed
+ role: str
+ raw: str
+
+
+@dataclass
+class Install:
+ """One command that materialises node_modules."""
+
+ tool: str # pnpm | npm
+ path: str
+ locked: bool
+ # The directory whose lockfile this command consumes. pnpm resolves to the
+ # workspace root; npm resolves to the directory the command runs in.
+ owner: str
+ raw: str
+
+
+@dataclass
+class Scan:
+ pins: list[Pin] = field(default_factory=list)
+ installs: list[Install] = field(default_factory=list)
+ files: list[str] = field(default_factory=list)
+ go_modules: dict[str, dict] = field(default_factory=dict)
+ go_cache_paths: list[tuple[str, str]] = field(default_factory=list)
+ pnpm_actions: list[tuple[str, str]] = field(default_factory=list)
+ go_ci_builds: set[str] = field(default_factory=set)
+
+ def by_runtime(self, runtime: str) -> list[Pin]:
+ return [p for p in self.pins if p.runtime == runtime]
+
+
+# ── Parsing ──────────────────────────────────────────────────────────────────
+#
+# Every pattern below is paired with a note about what it would *miss*, because
+# the parser's blind spot is the failure mode this family of gate actually has.
+# `check_parser_coverage` is the backstop: it re-reads each scanned file with a
+# looser pattern and fails if the parser produced nothing for a declaration the
+# file plainly contains.
+
+# `node-version: '22'`, `go-version: "1.26"`, `python-version: 3.12`.
+_SETUP_VERSION = re.compile(
+ r"^\s*(?P<runtime>node|go|python)-version:\s*(?P<version>[\"']?[\d.]+[\"']?)\s*(?:#.*)?$",
+ re.MULTILINE,
+)
+# `node-version-file: .nvmrc` — an indirection the version regex above cannot
+# see. Nothing in this tree uses it today; if that changes the gate must read
+# the file rather than silently extract nothing from the workflow.
+_SETUP_VERSION_FILE = re.compile(r"^\s*(?P<runtime>node|go|python)-version-file:\s*(?P<target>\S+)", re.MULTILINE)
+# `uses: actions/setup-node@sha` with no version input at all: the step then
+# takes whatever the runner image happens to ship, which is the unbounded-pin
+# shape.
+_SETUP_ACTION = re.compile(r"uses:\s*actions/setup-(?P<runtime>node|go|python)@")
+# `image: mcr.microsoft.com/playwright:v1.49.0-jammy` under a job `container:`.
+# A job container supplies its own toolchain, so it is a declaration even
+# though no `*-version:` key appears.
+_JOB_CONTAINER = re.compile(r"^\s*image:\s*(?P<image>[\w./-]+:[\w.-]+)\s*$", re.MULTILINE)
+_PNPM_ACTION = re.compile(r"uses:\s*pnpm/action-setup@\w+\s*#\s*(?P<version>v[\d.]+)")
+
+# `FROM node:20-alpine AS base`, `FROM golang:1.26-alpine`, `FROM python:3.11-slim`.
+_DOCKER_FROM = re.compile(
+ r"^\s*FROM\s+(?:[\w.\-/]+/)?(?P<image>golang|node|python)" r":(?P<version>[\d.]+)(?P<suffix>[\w.-]*)",
+ re.MULTILINE | re.IGNORECASE,
+)
+# The devcontainer base encodes its Node version in the tag, not after a colon
+# and a number: `javascript-node:1-20-bookworm`.
+_DEVCONTAINER_NODE = re.compile(r"devcontainers/javascript-node:\d+-(?P<version>\d+)-")
+# `FROM node:${NODE_VERSION}` — an ARG indirection. Nothing uses it today;
+# extracting nothing from such a line while counting the file scanned is
+# precisely the blind spot, so it is matched and resolved explicitly.
+_DOCKER_FROM_ARG = re.compile(r"^\s*FROM\s+(?P<image>golang|node|python):\$\{?(?P<arg>\w+)\}?", re.MULTILINE | re.IGNORECASE)
+_DOCKER_ARG = re.compile(r"^\s*ARG\s+(?P<name>\w+)=(?P<value>[\w.-]+)", re.MULTILINE)
+
+_PNPM_GLOBAL = re.compile(r"npm\s+install\s+-g\s+pnpm@(?P<version>[\d.]+)")
+_COREPACK_PNPM = re.compile(r"corepack\s+prepare\s+pnpm@(?P<version>[\d.]+)")
+# `install.sh` decides what a self-hoster ends up running, in three spellings:
+# the floor it enforces, the NodeSource channel it adds, and the Homebrew
+# formula it installs. It installed Node 20 while every workflow tested on 22
+# and both images shipped 22, so the one-line installer handed people a
+# different runtime from the one the project is built against.
+_INSTALLER_NODE = re.compile(r"version_at_least\s+node\s+(?P<a>\d+)|setup_(?P<b>\d+)\.x|node@(?P<c>\d+)\b|nodejs(?P<d>\d\d)\b")
+
+_PNPM_INSTALL = re.compile(r"(?P<cmd>pnpm\s+(?:--filter\s+\S+\s+)?(?:install|i)\b[^\n&|;]*)")
+# `(?<![\\w-])` matters: without it this matches the trailing `npm install`
+# inside `pnpm install`, and every pnpm command is reported twice — once
+# correctly and once as an unlocked npm install that does not exist.
+_NPM_INSTALL = re.compile(r"(?<![\w-])(?P<cmd>npm\s+(?:ci|install)\b[^\n&|;]*)")
+# A Dockerfile that installs Node dependencies must copy the lockfile into
+# the build context, or the install resolves afresh however it is spelled.
+_DOCKER_COPY = re.compile(r"^\s*COPY\s+(?P<files>[^\n]+)", re.MULTILINE)
+
+_GO_DIRECTIVE = re.compile(r"^go\s+(?P<version>[\d.]+)\s*$", re.MULTILINE)
+_GO_REQUIRE = re.compile(r"^\s*require\b", re.MULTILINE)
+_GO_CACHE_PATH = re.compile(r"^\s*cache-dependency-path:\s*(?P<path>\S+)\s*$", re.MULTILINE)
+_GO_COPY_SUM = re.compile(r"^\s*COPY\s+(?P<files>[^\n]*go\.sum\S*)", re.MULTILINE)
+# `cd services/ingest`, and `cd services/${{ matrix.service }}`. The matrix
+# form is the parser's blind spot in this family: a line-by-line reader
+# extracts nothing from it, so five of the six Go modules looked ungated when
+# in fact one was. `_matrix_values` below resolves it.
+_GO_CD = re.compile(r"cd\s+(?P<dir>(?:services|packages)/[\w.${}\s-]+?)\s*$", re.MULTILINE)
+# A job can select its module with `defaults: run: working-directory:` instead
+# of a `cd`, and `build-extensions.yml` does. A parser that knew only about
+# `cd` reported `services/osquery-extensions` as compiled by nothing while the
+# workflow that compiles it sat two directories away.
+_GO_WORKDIR = re.compile(r"^\s*working-directory:\s*(?P<dir>\S+)\s*$", re.MULTILINE)
+_GO_VERB = re.compile(r"\bgo\s+(?:build|test|vet|mod)\b")
+_MATRIX_LIST = re.compile(r"^\s*(?P<key>\w+):\s*\[(?P<items>[^\]]+)\]\s*$", re.MULTILINE)
+_EXPANSION = re.compile(r"\$\{\{\s*matrix\.(?P<key>\w+)\s*\}\}")
+
+
+def _matrix_values(text: str) -> dict[str, list[str]]:
+ """Inline `key: [a, b, c]` matrix legs, so `${{ matrix.key }}` can be resolved."""
+ values: dict[str, list[str]] = {}
+ for match in _MATRIX_LIST.finditer(text):
+ items = [i.strip().strip("\"'") for i in match.group("items").split(",")]
+ values.setdefault(match.group("key"), []).extend(i for i in items if i)
+ return values
+
+
+def _expand(template: str, matrix: dict[str, list[str]]) -> list[str]:
+ """Every concrete path a `${{ matrix.* }}` template can become."""
+ found = _EXPANSION.search(template)
+ if not found:
+ return [template.strip()] if "${{" not in template else []
+ key = found.group("key")
+ if key not in matrix:
+ return []
+ out: list[str] = []
+ for value in matrix[key]:
+ out += _expand(template[: found.start()] + value + template[found.end() :], matrix)
+ return out
+
+
+def _strip_quoted(text: str) -> str:
+ """Blank out quoted spans in *shell* sources, which are data not commands.
+
+ `install.sh` says `die "pnpm install failed."` and
+ `info "Installing JS workspace deps (pnpm install)..."`. Read literally
+ those are three more install paths, all of them messages about a fourth.
+
+ Applied only to shell and Dockerfile sources. In JSON the command *is* the
+ quoted value — `devcontainer.json` declares
+ `"onCreateCommand": "pnpm install --frozen-lockfile=false"` — so stripping
+ quotes there would delete the very install path being looked for, which is
+ the blind spot this function exists to avoid creating.
+ """
+ # Shell strings wrap, so the double-quoted form has to cross newlines —
+ # `install.sh` has a two-line `die "…"`. Bounded to 600 characters so a
+ # single unbalanced quote blanks one message rather than the rest of the
+ # file, which would turn this from a false-positive fix into a blind spot.
+ return re.sub(r"\"[^\"]{0,600}\"|'[^'\n]*'", " ", text, flags=re.DOTALL)
+
+
+def _uncommented(text: str) -> str:
+ """Drop comment-only lines.
+
+ Comments in this repository discuss versions and install commands at
+ length — `apps/web/Dockerfile` explains its pnpm choice over eight lines —
+ so reading them as declarations produces confident nonsense. This is the
+ same precaution `_pip_install_tokens` needed in the dependency gate, which
+ once reported packages named `that`, `was` and `a`.
+ """
+ return "\n".join(line for line in text.splitlines() if not line.lstrip().startswith("#"))
+
+
+def _fold_yaml_run_blocks(text: str) -> str:
+ """Join `run: >-` folded scalars into the single command they become.
+
+ A folded block runs as one shell line, so a line-by-line reader sees the
+ `run:` header, finds no command after it, and extracts nothing — while
+ still counting the file as scanned. `integration.yml` hid a whole
+ dependency set from the dependency gate this way.
+ """
+ lines = text.splitlines()
+ out: list[str] = []
+ index = 0
+ while index < len(lines):
+ line = lines[index]
+ header = re.match(r"^(\s*)(-?\s*run:)\s*>-?\s*$", line)
+ if not header:
+ out.append(line)
+ index += 1
+ continue
+ indent = len(header.group(1))
+ body: list[str] = []
+ index += 1
+ while index < len(lines):
+ candidate = lines[index]
+ if candidate.strip() and (len(candidate) - len(candidate.lstrip())) <= indent:
+ break
+ body.append(candidate.strip())
+ index += 1
+ out.append(f"{header.group(1)}{header.group(2)} " + " ".join(b for b in body if b))
+ return "\n".join(out)
+
+
+def _install_commands(text: str, rel: str, owner: str, shell_source: bool = False) -> list[Install]:
+ """Every command in a file that materialises node_modules."""
+ body = _fold_yaml_run_blocks(_uncommented(text))
+ body = re.sub(r"\\\s*\n", " ", body) # fold shell line continuations
+ if shell_source:
+ body = _strip_quoted(body)
+ found: list[Install] = []
+
+ for match in _PNPM_INSTALL.finditer(body):
+ command = match.group("cmd").strip()
+ # `--frozen-lockfile` is the locked form. There are two opt-outs and
+ # both were in the tree: `--no-frozen-lockfile` in the production web
+ # image, and `--frozen-lockfile=false` in the devcontainer — which a
+ # substring test reads as *enabling* the flag it disables.
+ locked = bool(re.search(r"--frozen-lockfile(?!\s*=\s*false)", command)) and ("--no-frozen-lockfile" not in command)
+ found.append(Install("pnpm", rel, locked, owner, command))
+
+ for match in _NPM_INSTALL.finditer(body):
+ command = match.group("cmd").strip()
+ if re.search(r"\s-g\b|--global\b", command):
+ continue # installing a global tool, not this project's tree
+ locked = bool(re.match(r"npm\s+ci\b", command))
+ found.append(Install("npm", rel, locked, owner, command))
+
+ return found
+
+
+def parse_workflow(path: Path, rel: str, scan_result: Scan, root: Path) -> None:
+ text = _uncommented(path.read_text(encoding="utf-8"))
+
+ for match in _SETUP_VERSION.finditer(text):
+ scan_result.pins.append(Pin(match.group("runtime"), normalise_version(match.group("version")), rel, "test", match.group(0).strip()))
+ for match in _SETUP_VERSION_FILE.finditer(text):
+ # Recorded as an unreadable declaration rather than skipped, so it
+ # surfaces as a gate failure instead of a silent gap.
+ scan_result.pins.append(Pin(match.group("runtime"), f"@file:{match.group('target')}", rel, "test", match.group(0).strip()))
+ for match in _JOB_CONTAINER.finditer(text):
+ scan_result.pins.append(Pin("container", match.group("image"), rel, "test", match.group(0).strip()))
+ for match in _PNPM_ACTION.finditer(text):
+ scan_result.pnpm_actions.append((rel, match.group("version")))
+ for match in _GO_CACHE_PATH.finditer(text):
+ target = match.group("path").strip("\"'")
+ if "${{" not in target:
+ scan_result.go_cache_paths.append((rel, target))
+ # A `cd` only counts as compiling a module when a `go` verb follows it.
+ # Matching every `cd services/<x>` reported five Python services as Go
+ # modules the workflow built; matching only literal paths reported five
+ # real Go modules as built by nothing, because `ci.yml` drives them
+ # through `cd services/${{ matrix.service }}`. Both halves are needed.
+ matrix = _matrix_values(text)
+ for match in _GO_CD.finditer(text):
+ if not _GO_VERB.search(text[match.end() : match.end() + 300]):
+ continue
+ for directory in _expand(match.group("dir"), matrix):
+ scan_result.go_ci_builds.add(directory)
+ # `working-directory:` is job- or step-scoped and this reader is not, so a
+ # workflow with a Go job and a Python job would otherwise attribute the
+ # Python job's directory to Go. Accepting only directories that actually
+ # hold a go.mod keeps it precise without parsing the job graph.
+ if _GO_VERB.search(text):
+ for match in _GO_WORKDIR.finditer(text):
+ for directory in _expand(match.group("dir").strip("\"'"), matrix):
+ if (root / directory / "go.mod").exists():
+ scan_result.go_ci_builds.add(directory)
+
+ # A setup step with no version input takes whatever the runner ships.
+ for match in _SETUP_ACTION.finditer(text):
+ runtime = match.group("runtime")
+ window = text[match.end() : match.end() + 400]
+ key = f"{runtime}-version"
+ if key not in window.split("- ")[0]:
+ scan_result.pins.append(Pin(runtime, "", rel, "test", match.group(0).strip()))
+
+ scan_result.installs += _install_commands(path.read_text(encoding="utf-8"), rel, "")
+
+
+def parse_dockerfile(path: Path, rel: str, scan_result: Scan, role: str) -> None:
+ raw = path.read_text(encoding="utf-8")
+ text = _uncommented(raw)
+ args = {m.group("name"): m.group("value") for m in _DOCKER_ARG.finditer(text)}
+
+ for match in _DOCKER_FROM.finditer(text):
+ runtime = {"golang": "go", "node": "node", "python": "python"}[match.group("image").lower()]
+ scan_result.pins.append(Pin(runtime, normalise_version(match.group("version")), rel, role, match.group(0).strip()))
+ for match in _DOCKER_FROM_ARG.finditer(text):
+ runtime = {"golang": "go", "node": "node", "python": "python"}[match.group("image").lower()]
+ resolved = args.get(match.group("arg"), "")
+ scan_result.pins.append(Pin(runtime, normalise_version(resolved) if resolved else "", rel, role, match.group(0).strip()))
+ for match in _DEVCONTAINER_NODE.finditer(text):
+ scan_result.pins.append(Pin("node", normalise_version(match.group("version")), rel, role, match.group(0).strip()))
+ for match in _PNPM_GLOBAL.finditer(text):
+ scan_result.pins.append(Pin("pnpm", match.group("version"), rel, role, match.group(0).strip()))
+
+ scan_result.installs += _install_commands(raw, rel, str(Path(rel).parent), shell_source=True)
+
+ # A Go builder stage must copy the checksum file unconditionally. `go.sum*`
+ # is a glob: if the file is ever absent the COPY still succeeds and
+ # `go mod download` resolves without verification.
+ for match in _GO_COPY_SUM.finditer(text):
+ if "go.sum*" in match.group("files"):
+ scan_result.go_modules.setdefault(str(Path(rel).parent), {})["optional_sum"] = rel
+
+
+def parse_shell(path: Path, rel: str, scan_result: Scan) -> None:
+ raw = path.read_text(encoding="utf-8")
+ text = _uncommented(raw)
+ for match in _PNPM_GLOBAL.finditer(text):
+ scan_result.pins.append(Pin("pnpm", match.group("version"), rel, "dev", match.group(0).strip()))
+ for match in _COREPACK_PNPM.finditer(text):
+ scan_result.pins.append(Pin("pnpm", match.group("version"), rel, "dev", match.group(0).strip()))
+ for match in _INSTALLER_NODE.finditer(text):
+ version = next(g for g in match.groups() if g)
+ scan_result.pins.append(Pin("node", normalise_version(version), rel, "dev", match.group(0).strip()))
+ scan_result.installs += _install_commands(raw, rel, "", shell_source=True)
+
+
+def parse_go_mod(path: Path, rel: str, scan_result: Scan) -> None:
+ text = path.read_text(encoding="utf-8")
+ directory = str(Path(rel).parent)
+ entry = scan_result.go_modules.setdefault(directory, {})
+ entry["mod"] = rel
+ entry["requires"] = bool(_GO_REQUIRE.search(text))
+ entry["sum"] = (path.parent / "go.sum").exists()
+ match = _GO_DIRECTIVE.search(text)
+ if match:
+ scan_result.pins.append(Pin("go", normalise_version(match.group("version")), rel, "floor", match.group(0).strip()))
+
+
+def parse_package_json(path: Path, rel: str, scan_result: Scan) -> None:
+ data = json.loads(path.read_text(encoding="utf-8"))
+ manager = data.get("packageManager", "")
+ if manager.startswith("pnpm@"):
+ # Not a floor: `pnpm/action-setup` with no `version:` input installs
+ # exactly this, so it is the toolchain every CI job runs.
+ scan_result.pins.append(Pin("pnpm", manager.split("@", 1)[1], rel, "test", f"packageManager: {manager}"))
+ engine = (data.get("engines") or {}).get("node")
+ if engine:
+ # A published package's `engines` states what a *consumer* needs, which
+ # is deliberately broader than the toolchain this repository builds
+ # with. It is recorded as a floor, never as a toolchain.
+ scan_result.pins.append(Pin("node", re.sub(r"^[^\d]*", "", engine), rel, "floor", f"engines.node: {engine}"))
+
+
+def scan(root: Path) -> Scan:
+ result = Scan()
+
+ workflows = root / ".github" / "workflows"
+ for workflow in sorted(workflows.glob("*.yml")) if workflows.is_dir() else []:
+ rel = workflow.relative_to(root).as_posix()
+ result.files.append(rel)
+ parse_workflow(workflow, rel, result, root)
+
+ for dockerfile in walk(root, "Dockerfile"):
+ rel = dockerfile.relative_to(root).as_posix()
+ if skipped(rel):
+ continue
+ result.files.append(rel)
+ # The devcontainer is the toolchain a contributor's first build runs
+ # on; a version there that CI does not use is a local green that reds
+ # on push.
+ parse_dockerfile(dockerfile, rel, result, "dev" if rel.startswith(".devcontainer/") else "ship")
+
+ for gomod in walk(root, "go.mod"):
+ rel = gomod.relative_to(root).as_posix()
+ if skipped(rel):
+ continue
+ result.files.append(rel)
+ parse_go_mod(gomod, rel, result)
+
+ for gosum in walk(root, "go.sum"):
+ rel = gosum.relative_to(root).as_posix()
+ if skipped(rel):
+ continue
+ result.files.append(rel)
+ result.go_modules.setdefault(str(Path(rel).parent), {})["sum_file"] = rel
+
+ for manifest in walk(root, "package.json"):
+ rel = manifest.relative_to(root).as_posix()
+ if skipped(rel):
+ continue
+ result.files.append(rel)
+ parse_package_json(manifest, rel, result)
+
+ for pyproject in sorted(root.glob("services/*/pyproject.toml")):
+ rel = pyproject.relative_to(root).as_posix()
+ result.files.append(rel)
+ data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+ declared = data.get("tool", {}).get("poetry", {}).get("dependencies", {}).get("python") or data.get("project", {}).get(
+ "requires-python"
+ )
+ if isinstance(declared, str):
+ result.pins.append(Pin("python", re.sub(r"^[^\d]*", "", declared), rel, "floor", f"python {declared}"))
+
+ installer = root / "install.sh"
+ if installer.exists():
+ rel = installer.relative_to(root).as_posix()
+ result.files.append(rel)
+ parse_shell(installer, rel, result)
+
+ # The devcontainer's lifecycle hooks are install paths: `onCreateCommand`
+ # runs `pnpm install` on every Codespace boot. `check_scan_coverage` is
+ # what surfaced this file — it was declaring an install command from
+ # outside the scanned set.
+ devcontainer = root / ".devcontainer" / "devcontainer.json"
+ if devcontainer.exists():
+ rel = devcontainer.relative_to(root).as_posix()
+ result.files.append(rel)
+ result.installs += _install_commands(devcontainer.read_text(encoding="utf-8"), rel, "")
+
+ return result
+
+
+# ── The checks ───────────────────────────────────────────────────────────────
+
+
+def _toolchains(data: Scan, runtime: str) -> list[Pin]:
+ """Declarations that actually install a toolchain, as opposed to floors."""
+ return [p for p in data.by_runtime(runtime) if p.role in {"ship", "test", "dev"}]
+
+
+def check_runtime_agreement(data: Scan) -> list[str]:
+ """Every path installing a runtime must install the same version.
+
+ Python is excluded from strict equality and handled by
+ `check_python_split` instead: its manifests declare a floor rather than a
+ pin, so CI on 3.12 and an image on 3.11 both satisfy what is written. That
+ is a weaker property than Go and Node have, and saying so is the point.
+ """
+ problems: list[str] = []
+ for runtime, reason in sorted(RUNTIMES.items()):
+ if runtime == "python":
+ continue
+ declarations = _toolchains(data, runtime)
+ if not declarations:
+ continue
+
+ unbounded = [p for p in declarations if not p.version]
+ unreadable = [p for p in declarations if p.version.startswith("@file:")]
+ versions: dict[str, list[Pin]] = {}
+ for pin in declarations:
+ if pin.version and not pin.version.startswith("@file:"):
+ versions.setdefault(pin.version, []).append(pin)
+
+ if unbounded:
+ where = ", ".join(sorted({p.path for p in unbounded}))
+ problems.append(
+ f"`{runtime}` is set up with no version in {where} — the step takes whatever "
+ f"the runner image ships, which changes without any diff. Why it matters: {reason}"
+ )
+ if unreadable:
+ where = ", ".join(sorted({f"{p.path} ({p.version})" for p in unreadable}))
+ problems.append(
+ f"`{runtime}` is declared through a version file in {where}; this gate does not "
+ f"read that indirection, so the version would go uncompared"
+ )
+ if len(versions) > 1:
+ detail = "; ".join(f"[{version}] {', '.join(sorted({p.path for p in pins}))}" for version, pins in sorted(versions.items()))
+ problems.append(f"`{runtime}` is pinned {len(versions)} different ways: {detail}. Why it matters: {reason}")
+ return problems
+
+
+def check_ship_test_parity(data: Scan) -> list[str]:
+ """Both directions between what images ship and what CI exercises.
+
+ Forward (ship -> test) catches an image on a runtime nothing tests: the
+ Node 20 images under thirteen Node 22 workflows. Reverse (test -> ship)
+ catches CI moving ahead of the images, which is the direction versions
+ actually travel — CI bumps are cheap and Dockerfiles get forgotten.
+ """
+ problems: list[str] = []
+ for runtime in sorted(RUNTIMES):
+ if runtime == "python":
+ continue # ratcheted by check_python_split, which explains why
+ shipped = {p.version for p in data.by_runtime(runtime) if p.role == "ship" and p.version}
+ tested = {p.version for p in data.by_runtime(runtime) if p.role == "test" and p.version}
+ if not shipped or not tested:
+ continue
+ for version in sorted(shipped - tested):
+ where = sorted({p.path for p in data.by_runtime(runtime) if p.role == "ship" and p.version == version})
+ problems.append(
+ f"`{runtime}` {version} is shipped by {', '.join(where)} but no workflow " f"builds or tests on it (ship -> test)"
+ )
+ for version in sorted(tested - shipped):
+ where = sorted({p.path for p in data.by_runtime(runtime) if p.role == "test" and p.version == version})
+ problems.append(
+ f"`{runtime}` {version} is used by {', '.join(where)} but no image ships it — "
+ f"CI is testing a runtime nothing runs in production (test -> ship)"
+ )
+ return problems
+
+
+def check_floors(data: Scan) -> list[str]:
+ """A declared minimum must be satisfied by every toolchain installed."""
+ problems: list[str] = []
+ for runtime in sorted(RUNTIMES):
+ toolchains = [p for p in _toolchains(data, runtime) if p.version and not p.version.startswith("@file:")]
+ for floor in [p for p in data.by_runtime(runtime) if p.role == "floor" and p.version]:
+ for pin in toolchains:
+ if not at_most(floor.version, pin.version):
+ problems.append(
+ f"{floor.path} declares `{runtime}` >= {floor.version}, but {pin.path} "
+ f"installs {pin.version} (floor <= toolchain)"
+ )
+ return problems
+
+
+def check_python_split(data: Scan) -> list[str]:
+ """Every service image must ship one interpreter, and CI must satisfy it.
+
+ Deliberately weaker than the Go and Node checks, and the difference is
+ stated rather than hidden. The manifests declare `^3.11`, which permits
+ 3.12, so a workflow on 3.12 is not violating anything written down — but
+ it is still not the interpreter the image runs. What is enforced here is
+ the part that is unambiguous: the images agree with each other, and no
+ workflow drops below the floor the manifests declare. The residual split
+ is printed by `report` so the number is visible rather than implied.
+ """
+ problems: list[str] = []
+ pins = data.by_runtime("python")
+ shipped = {p.version for p in pins if p.role == "ship"}
+ if len(shipped) > 1:
+ detail = "; ".join(
+ f"[{version}] " + ", ".join(sorted({p.path for p in pins if p.role == "ship" and p.version == version}))
+ for version in sorted(shipped)
+ )
+ problems.append(f"service images ship {len(shipped)} different Python interpreters: {detail}")
+ return problems
+
+ if not shipped:
+ return problems # no Python images in this tree; nothing to compare against
+
+ differing = {p.path for p in pins if p.role == "test" and p.version and p.version not in shipped}
+ scanned_workflows = {f for f in data.files if f.startswith(".github/workflows/")}
+ for path in sorted(differing - PYTHON_INTERPRETER_SPLIT):
+ problems.append(
+ f"{path} tests on a Python interpreter no image ships ({', '.join(sorted(shipped))}) "
+ f"and is not in PYTHON_INTERPRETER_SPLIT — the split may not grow silently"
+ )
+ for path in sorted((PYTHON_INTERPRETER_SPLIT & scanned_workflows) - differing):
+ problems.append(
+ f"PYTHON_INTERPRETER_SPLIT names {path}, which now matches the shipped "
+ f"interpreter — remove it so the recorded gap stays the real one"
+ )
+ return problems
+
+
+def check_locked_installs(data: Scan) -> list[str]:
+ """Both directions between install commands and the lockfiles in the tree.
+
+ Forward: an install free to resolve its own answer. Reverse: a lockfile
+ committed and consumed by nothing — which is how `services/realtime`
+ carried a `package-lock.json` for an image that ran `npm install`.
+ """
+ problems: list[str] = []
+ for install in data.installs:
+ if install.locked or install.path in UNLOCKED_INSTALL_EXEMPT:
+ continue
+ problems.append(
+ f"{install.path} runs `{install.raw}` — free to resolve outside the lockfile, so "
+ f"this path can install a version set no other path tested (unlocked install)"
+ )
+ return problems
+
+
+def check_dead_lockfiles(root: Path, data: Scan) -> list[str]:
+ """The reverse direction: a committed lockfile nothing can consume.
+
+ `check_locked_installs` asks whether every install honours a lockfile.
+ This asks the opposite — whether every lockfile is reachable by an
+ install at all. A lockfile with no manifest beside it, or whose package
+ manager is never invoked anywhere in the tree, records a version set that
+ nothing installs while looking like evidence that something does.
+ """
+ problems: list[str] = []
+ tools_used = {install.tool for install in data.installs}
+ for pattern, tool in (("package-lock.json", "npm"), ("pnpm-lock.yaml", "pnpm")):
+ for lockfile in walk(root, pattern):
+ rel = lockfile.relative_to(root).as_posix()
+ if not (lockfile.parent / "package.json").exists():
+ problems.append(f"{rel} has no package.json beside it (dead lockfile)")
+ elif tool not in tools_used:
+ problems.append(
+ f"{rel} is committed but no path in this repository runs `{tool}` — "
+ f"the lockfile records a version set nothing installs (dead lockfile)"
+ )
+ return problems
+
+
+def check_image_copies_lockfile(root: Path, data: Scan) -> list[str]:
+ """An image installing Node dependencies must copy the lockfile it installs from.
+
+ The sharp edge of the reverse direction. `services/realtime` committed a
+ `package-lock.json`, and its Dockerfile copied `package.json` and ran
+ `npm install` — so the lockfile was never in the build context and every
+ image build re-resolved. Spelling the command `npm ci` would not have
+ helped; it would have failed for want of a file nobody copied. The two
+ halves have to be checked together.
+ """
+ problems: list[str] = []
+ wanted = {"pnpm": ("pnpm-lock.yaml",), "npm": ("package-lock.json",)}
+ for install in data.installs:
+ if not install.path.endswith("Dockerfile"):
+ continue
+ path = root / install.path
+ if not path.is_file():
+ continue
+ copied = " ".join(m.group("files") for m in _DOCKER_COPY.finditer(_uncommented(path.read_text("utf-8"))))
+ if not any(name in copied for name in wanted[install.tool]):
+ problems.append(
+ f"{install.path} runs `{install.raw}` but never COPYs "
+ f"{' or '.join(wanted[install.tool])} into the build context, so the image "
+ f"resolves dependencies afresh however the command is spelled (image -> lockfile)"
+ )
+ return problems
+
+
+def check_go_modules(root: Path, data: Scan) -> list[str]:
+ """Go module integrity, in every direction the pieces can disagree."""
+ problems: list[str] = []
+
+ for directory, entry in sorted(data.go_modules.items()):
+ if entry.get("mod") and entry.get("requires") and not entry.get("sum"):
+ problems.append(
+ f"{entry['mod']} declares requirements but {directory}/go.sum does not exist — "
+ f"`go mod download` resolves them unverified (module -> sum)"
+ )
+ if entry.get("sum_file") and not entry.get("mod"):
+ problems.append(f"{entry['sum_file']} has no go.mod beside it (sum -> module)")
+ if entry.get("optional_sum") and entry.get("requires"):
+ problems.append(
+ f"{entry['optional_sum']} copies `go.sum*` — the glob makes the checksum file "
+ f"optional, so deleting it downgrades the build to an unverified resolve "
+ f"without failing (module -> sum)"
+ )
+
+ # A cache path naming a file that is not there. `setup-go` reports this as
+ # a warning and carries on, so the job stays green with the cache silently
+ # off — a green tick for a step that did not happen.
+ for workflow, target in sorted(data.go_cache_paths):
+ if "*" in target:
+ continue
+ if not (root / target).exists():
+ problems.append(
+ f"{workflow} sets cache-dependency-path `{target}`, which does not exist — "
+ f"setup-go warns and continues, so the cache is off and the job still passes "
+ f"(sum -> module)"
+ )
+
+ # A compiled binary committed beside the source it was built from.
+ # `services/demo-producer/demo-producer` was a 6.9 MB macOS arm64
+ # executable in a module whose Dockerfile builds a GOOS=linux one:
+ # nothing consumed it, nothing rebuilt it, and running the documented
+ # `go build ./...` overwrote it and dirtied the working tree. A build
+ # output tracked as source is the opposite of a reproducible build.
+ for directory, entry in sorted(data.go_modules.items()):
+ if not entry.get("mod"):
+ continue
+ for candidate in sorted((root / directory).glob("*")):
+ if not candidate.is_file() or candidate.suffix:
+ continue
+ try:
+ magic = candidate.read_bytes()[:4]
+ except OSError:
+ continue
+ if magic[:4] in (b"\x7fELF", b"\xcf\xfa\xed\xfe", b"\xfe\xed\xfa\xcf", b"\xca\xfe\xba\xbe"):
+ problems.append(
+ f"{directory}/{candidate.name} is a compiled binary committed inside a Go "
+ f"module — `go build` overwrites it, so the tracked bytes are one machine's "
+ f"output and nothing rebuilds or verifies them (build output as source)"
+ )
+
+ modules = {directory for directory, entry in data.go_modules.items() if entry.get("mod")}
+ for directory in sorted(modules - data.go_ci_builds):
+ problems.append(f"{directory}/go.mod is built by no workflow — nothing compiles it (module -> CI)")
+ for directory in sorted(data.go_ci_builds - modules):
+ problems.append(f"a workflow builds `{directory}`, which holds no go.mod (CI -> module)")
+
+ return problems
+
+
+def check_esbuild_overrides(root: Path) -> list[str]:
+ """esbuild must stay overridden per parent, and the resolved set must be pinned.
+
+ Forcing esbuild across the workspace broke Turbopack's font import map,
+ because Next bundles its own copy and the override replaced it. The
+ overrides are therefore scoped (`vite>esbuild`) — but that scoping means a
+ `vite` bump can pull a different esbuild with no esbuild line in the diff,
+ so the resolved versions are compared too.
+ """
+ problems: list[str] = []
+ manifest = root / "package.json"
+ if not manifest.exists():
+ return []
+ overrides = (json.loads(manifest.read_text(encoding="utf-8")).get("pnpm") or {}).get("overrides") or {}
+ for key in sorted(overrides):
+ if key == "esbuild" or key.startswith("esbuild@"):
+ problems.append(
+ f"package.json overrides `{key}` workspace-wide. Next bundles its own esbuild "
+ f"and a workspace-wide override replaces it, which breaks Turbopack's font "
+ f"import map — scope it to its parent as `<parent>>esbuild` (override scope)"
+ )
+
+ lockfile = root / "pnpm-lock.yaml"
+ if not lockfile.exists():
+ return problems
+ resolved = set(re.findall(r"\besbuild@(\d+\.\d+\.\d+)", lockfile.read_text(encoding="utf-8")))
+ if not resolved:
+ return problems
+ for version in sorted(resolved - set(EXPECTED_ESBUILD)):
+ problems.append(
+ f"pnpm-lock.yaml resolves esbuild {version}, which is not in the expected set "
+ f"({', '.join(sorted(EXPECTED_ESBUILD))}). A vite or tsup bump pulls esbuild "
+ f"through the scoped override; confirm Turbopack still builds, then record it "
+ f"in EXPECTED_ESBUILD (override scope)"
+ )
+ for version in sorted(set(EXPECTED_ESBUILD) - resolved):
+ problems.append(
+ f"EXPECTED_ESBUILD names esbuild {version} ({EXPECTED_ESBUILD[version]}) but the "
+ f"lockfile resolves no such version — the expectation is stale (override scope)"
+ )
+ return problems
+
+
+def check_pnpm_actions(data: Scan) -> list[str]:
+ """One pnpm action version, or a recorded reason for the difference."""
+ problems: list[str] = []
+ if not data.pnpm_actions:
+ return []
+ seen = {path for path, _ in data.pnpm_actions}
+ for path, version in sorted(data.pnpm_actions):
+ if version == PNPM_ACTION_VERSION or path in PNPM_ACTION_EXEMPT:
+ continue
+ problems.append(
+ f"{path} uses pnpm/action-setup {version} while the repository declares "
+ f"{PNPM_ACTION_VERSION}. Two action majors resolve pnpm differently; add a "
+ f"measured reason to PNPM_ACTION_EXEMPT or move it"
+ )
+ if PNPM_ACTION_VERSION not in {v for _, v in data.pnpm_actions}:
+ problems.append(f"PNPM_ACTION_VERSION is {PNPM_ACTION_VERSION} but no workflow uses it — " f"the declared version is stale")
+ # An exemption for a workflow that no longer sets up pnpm is a comment
+ # asserting a constraint nothing is under. Only checked against files the
+ # scan actually saw, so an exemption for a workflow outside this tree
+ # (a fixture, a fork) does not fail the run.
+ for path in sorted(PNPM_ACTION_EXEMPT):
+ if path in data.files and path not in seen:
+ problems.append(
+ f"PNPM_ACTION_EXEMPT names {path}, which no longer sets up pnpm — " f"remove the exemption rather than leaving it to rot"
+ )
+ return problems
+
+
+# Loose enough to see a declaration the strict parsers miss, strict enough not
+# to fire on prose. Used only to compare against what the parser extracted.
+_RUNTIME_MENTION = re.compile(
+ r"""(?:^|\s)(?:node|go|python)-version(?:-file)?:\s*\S|""" r"""^\s*FROM\s+(?:golang|node|python):|""" r"""npm\s+install\s+-g\s+pnpm@""",
+ re.MULTILINE | re.IGNORECASE,
+)
+
+
+def check_parser_coverage(root: Path, data: Scan) -> list[str]:
+ """A file this gate opened but did not actually read.
+
+ The other direction of `check_scan_coverage`. That one asks whether every
+ file holding a declaration is in the scanned set; this asks whether the
+ parser extracted anything from the files it did scan. Both are needed,
+ because a file can be globbed, counted, named in the summary — and still
+ have its declaration skipped by a parser that does not understand the
+ syntax it is written in. That is the bug `check_dependency_pins` found in
+ itself: it reported `ruff` agreeing across seven files, none of which had
+ been read for it.
+ """
+ problems: list[str] = []
+ extracted_from = {p.path for p in data.pins} | {i.path for i in data.installs}
+ for rel in sorted(set(data.files)):
+ path = root / rel
+ if not path.is_file() or rel.endswith(("go.sum", "poetry.lock", "pnpm-lock.yaml")):
+ continue
+ try:
+ text = _uncommented(path.read_text(encoding="utf-8"))
+ except (OSError, UnicodeDecodeError):
+ continue
+ if _RUNTIME_MENTION.search(text) and rel not in extracted_from:
+ problems.append(
+ f"{rel} declares a runtime version but the parser extracted nothing from it — "
+ f"the file is counted as scanned while contributing no declaration "
+ f"(parser coverage)"
+ )
+ return problems
+
+
+_STRAY = re.compile(
+ r"""^\s*FROM\s+(?:golang|node|python):|"""
+ r"""(?:node|go|python)-version:\s*["']?\d|"""
+ r"""pnpm\s+install\b|npm\s+ci\b|npm\s+install\s+-g\s+pnpm@""",
+ re.MULTILINE | re.IGNORECASE,
+)
+
+
+def check_scan_coverage(root: Path, data: Scan) -> list[str]:
+ """A file declaring a runtime or an install path that this gate never opened."""
+ scanned = set(data.files)
+ stray: set[str] = set()
+ for path in walk(root):
+ rel = path.relative_to(root).as_posix()
+ if rel in scanned or skipped(rel):
+ continue
+ if path.suffix not in {".yml", ".yaml", ".json", ".sh", ""}:
+ continue
+ if path.suffix == "" and not path.name.startswith("Dockerfile"):
+ continue
+ try:
+ text = _uncommented(path.read_text(encoding="utf-8"))
+ except (OSError, UnicodeDecodeError):
+ continue
+ if _STRAY.search(text):
+ stray.add(rel)
+ return [
+ f"{rel} declares a runtime version or an install command but is not a path this gate "
+ f"scans — add it to `scan()` or to SKIP_PREFIXES with a reason (coverage)"
+ for rel in sorted(stray)
+ ]
+
+
+def report(data: Scan) -> None:
+ for runtime in sorted(RUNTIMES):
+ pins = data.by_runtime(runtime)
+ if not pins:
+ continue
+ toolchains = sorted({p.version for p in pins if p.role in {"ship", "test", "dev"} and p.version})
+ floors = sorted({p.version for p in pins if p.role == "floor" and p.version})
+ print(
+ f" {runtime}: {len(pins)} declarations across {len({p.path for p in pins})} files"
+ f" — toolchain {', '.join(toolchains) or 'none'}" + (f", floors {', '.join(floors)}" if floors else "")
+ )
+ if runtime == "python":
+ shipped = sorted({p.version for p in pins if p.role == "ship"})
+ differing = sorted({p.path for p in pins if p.role == "test" and p.version and p.version not in shipped})
+ if differing:
+ # Not a failure: the manifests declare a floor, and every one
+ # of these satisfies it. Printed because a gap nobody can see
+ # is a gap nobody fixes.
+ print(
+ f" note: {len(differing)} workflow(s) test on an interpreter the images "
+ f"do not ship ({', '.join(shipped)}): {', '.join(Path(p).name for p in differing)}"
+ )
+
+ locked = sum(1 for i in data.installs if i.locked)
+ print(f" node installs: {len(data.installs)} ({locked} locked, {len(data.installs) - locked} unlocked)")
+ modules = sorted(d for d, e in data.go_modules.items() if e.get("mod"))
+ print(f" go modules: {len(modules)} — {', '.join(modules)}")
+
+
+def run(root: Path, verbose: bool = False) -> tuple[int, list[str]]:
+ if not (root / ".github" / "workflows").is_dir() or not (root / "services").is_dir():
+ return 1, [f"{root} does not look like the AiSOC repository (no .github/workflows and services/). " f"Pass --repo-root explicitly."]
+
+ data = scan(root)
+ if not data.pins and not data.installs:
+ return 1, [f"scanned {len(data.files)} file(s) under {root} and found no runtime declaration at all"]
+
+ problems = (
+ check_runtime_agreement(data)
+ + check_ship_test_parity(data)
+ + check_floors(data)
+ + check_python_split(data)
+ + check_locked_installs(data)
+ + check_dead_lockfiles(root, data)
+ + check_image_copies_lockfile(root, data)
+ + check_go_modules(root, data)
+ + check_esbuild_overrides(root)
+ + check_pnpm_actions(data)
+ + check_parser_coverage(root, data)
+ + check_scan_coverage(root, data)
+ )
+
+ print(f"check_toolchain_pins: root {root}")
+ print(
+ f" scanned {len(set(data.files))} paths "
+ f"({sum(1 for f in set(data.files) if f.startswith('.github/'))} workflows, "
+ f"{sum(1 for f in set(data.files) if f.endswith('Dockerfile'))} Dockerfiles, "
+ f"{sum(1 for f in set(data.files) if f.endswith('go.mod'))} go.mod, "
+ f"{sum(1 for f in set(data.files) if f.endswith('package.json'))} package.json)"
+ )
+ report(data)
+ if verbose:
+ for rel in sorted(set(data.files)):
+ print(f" scanned {rel}")
+
+ if problems:
+ print("check_toolchain_pins: FAIL")
+ for problem in problems:
+ print(f" - {problem}")
+ return 1, problems
+ print("check_toolchain_pins: OK")
+ return 0, []
+
+
+# ── Self-test ────────────────────────────────────────────────────────────────
+
+
+def _fixture(root: Path) -> None:
+ """A miniature repository that passes, for the injections to break."""
+ (root / ".github" / "workflows").mkdir(parents=True)
+ (root / "services" / "web-svc").mkdir(parents=True)
+ (root / "services" / "go-svc").mkdir(parents=True)
+
+ (root / "package.json").write_text(
+ json.dumps(
+ {
+ "name": "fixture",
+ "private": True,
+ "packageManager": "[email protected]",
+ "engines": {"node": ">=22.0.0"},
+ "pnpm": {"overrides": {"vite>esbuild": "^0.28.1"}},
+ }
+ ),
+ encoding="utf-8",
+ )
+ (root / "pnpm-lock.yaml").write_text("lockfileVersion: '6.0'\n /[email protected]:\n /[email protected]:\n", encoding="utf-8")
+
+ (root / "services" / "web-svc" / "Dockerfile").write_text(
+ "FROM node:22-alpine AS base\nRUN npm install -g [email protected]\n"
+ "COPY package.json pnpm-lock.yaml ./\nRUN pnpm install --frozen-lockfile\n",
+ encoding="utf-8",
+ )
+ (root / "services" / "go-svc" / "Dockerfile").write_text(
+ "FROM golang:1.26-alpine AS builder\nCOPY go.mod go.sum ./\nRUN go mod download\n", encoding="utf-8"
+ )
+ (root / "services" / "go-svc" / "go.mod").write_text(
+ "module example.com/go-svc\n\ngo 1.26\n\nrequire github.com/x/y v1.0.0\n", encoding="utf-8"
+ )
+ (root / "services" / "go-svc" / "go.sum").write_text("github.com/x/y v1.0.0 h1:abc=\n", encoding="utf-8")
+
+ (root / "install.sh").write_text(
+ "#!/usr/bin/env bash\n"
+ 'if version_at_least node 22 "node --version"; then ok; fi\n'
+ "curl -fsSL https://deb.nodesource.com/setup_22.x | bash -\n"
+ "corepack prepare [email protected] --activate\n"
+ "( cd $REPO_ROOT && pnpm install --frozen-lockfile )\n",
+ encoding="utf-8",
+ )
+ (root / ".github" / "workflows" / "ci.yml").write_text(
+ "name: CI\njobs:\n"
+ " node:\n steps:\n"
+ " - uses: pnpm/action-setup@aaa # v6.0.9\n"
+ " - uses: actions/setup-node@bbb # v6\n"
+ " with:\n node-version: '22'\n"
+ " - run: pnpm install --frozen-lockfile\n"
+ " go:\n steps:\n"
+ " - uses: actions/setup-go@ccc # v7\n"
+ " with:\n go-version: '1.26'\n"
+ " cache-dependency-path: services/go-svc/go.sum\n"
+ " - run: |\n cd services/go-svc\n go build ./...\n",
+ encoding="utf-8",
+ )
+
+
+def self_test() -> int:
+ import shutil
+ import tempfile
+
+ def build(mutate=None) -> tuple[int, list[str]]:
+ temp = Path(tempfile.mkdtemp(prefix="toolchain_selftest_"))
+ try:
+ _fixture(temp)
+ if mutate:
+ mutate(temp)
+ return run(temp)
+ finally:
+ shutil.rmtree(temp, ignore_errors=True)
+
+ def drift_node_image_behind_ci(root: Path) -> None:
+ """The measured bug: images on 20, every workflow on 22."""
+ path = root / "services" / "web-svc" / "Dockerfile"
+ path.write_text(path.read_text().replace("node:22-alpine", "node:20-alpine"), encoding="utf-8")
+
+ def drift_ci_ahead_of_images(root: Path) -> None:
+ """The reverse direction: CI bumps, the Dockerfile is forgotten."""
+ path = root / ".github" / "workflows" / "ci.yml"
+ path.write_text(path.read_text().replace("node-version: '22'", "node-version: '24'"), encoding="utf-8")
+
+ def drift_go_toolchain(root: Path) -> None:
+ path = root / "services" / "go-svc" / "Dockerfile"
+ path.write_text(path.read_text().replace("golang:1.26", "golang:1.25"), encoding="utf-8")
+
+ def drift_floor_above_toolchain(root: Path) -> None:
+ path = root / "services" / "go-svc" / "go.mod"
+ path.write_text(path.read_text().replace("go 1.26", "go 1.28"), encoding="utf-8")
+
+ def drift_pnpm_resolver(root: Path) -> None:
+ """`pnpm@8` instead of `[email protected]` — the poetry 1.7.1/1.8.2 shape."""
+ path = root / "services" / "web-svc" / "Dockerfile"
+ path.write_text(path.read_text().replace("[email protected]", "[email protected]"), encoding="utf-8")
+
+ def drift_unlocked_install(root: Path) -> None:
+ path = root / "services" / "web-svc" / "Dockerfile"
+ path.write_text(path.read_text().replace("--frozen-lockfile", "--no-frozen-lockfile"), encoding="utf-8")
+
+ def drift_dead_lockfile(root: Path) -> None:
+ """A lockfile committed where nothing can consume it."""
+ (root / "services" / "go-svc" / "package-lock.json").write_text('{"lockfileVersion": 3}', encoding="utf-8")
+
+ def drift_image_without_lockfile(root: Path) -> None:
+ """The measured `services/realtime` shape: install, but never copy the lock."""
+ (root / "services" / "web-svc" / "package.json").write_text('{"name": "web-svc"}', encoding="utf-8")
+ (root / "services" / "web-svc" / "package-lock.json").write_text('{"lockfileVersion": 3}', encoding="utf-8")
+ path = root / "services" / "web-svc" / "Dockerfile"
+ path.write_text(path.read_text() + "RUN npm ci --omit=dev\n", encoding="utf-8")
+
+ def drift_missing_go_sum(root: Path) -> None:
+ (root / "services" / "go-svc" / "go.sum").unlink()
+
+ def drift_optional_go_sum(root: Path) -> None:
+ path = root / "services" / "go-svc" / "Dockerfile"
+ path.write_text(path.read_text().replace("go.mod go.sum", "go.mod go.sum*"), encoding="utf-8")
+
+ def drift_stale_cache_path(root: Path) -> None:
+ path = root / ".github" / "workflows" / "ci.yml"
+ path.write_text(path.read_text().replace("services/go-svc/go.sum", "services/absent/go.sum"), encoding="utf-8")
+
+ def drift_ungated_go_module(root: Path) -> None:
+ (root / "packages" / "orphan-go").mkdir(parents=True)
+ (root / "packages" / "orphan-go" / "go.mod").write_text("module example.com/orphan\n\ngo 1.26\n", encoding="utf-8")
+
+ def drift_installer_node(root: Path) -> None:
+ """The one-line installer handing a self-hoster a different runtime."""
+ path = root / "install.sh"
+ path.write_text(path.read_text().replace("setup_22.x", "setup_20.x"), encoding="utf-8")
+
+ def drift_committed_binary(root: Path) -> None:
+ """A compiled binary committed beside the source it was built from."""
+ (root / "services" / "go-svc" / "go-svc").write_bytes(b"\x7fELF\x02\x01\x01\x00" + b"\x00" * 64)
+
+ def drift_ci_builds_absent_module(root: Path) -> None:
+ """The reverse of `module -> CI`: a build step for a module that moved."""
+ path = root / ".github" / "workflows" / "ci.yml"
+ path.write_text(path.read_text().replace("cd services/go-svc", "cd services/renamed-svc"), encoding="utf-8")
+
+ def drift_workspace_wide_esbuild(root: Path) -> None:
+ path = root / "package.json"
+ data = json.loads(path.read_text())
+ data["pnpm"]["overrides"]["esbuild"] = "^0.28.1"
+ path.write_text(json.dumps(data), encoding="utf-8")
+
+ def drift_esbuild_resolution(root: Path) -> None:
+ """A vite bump pulling a different esbuild, with no esbuild line in the diff."""
+ path = root / "pnpm-lock.yaml"
+ path.write_text(path.read_text().replace("[email protected]", "[email protected]"), encoding="utf-8")
+
+ def drift_unversioned_setup(root: Path) -> None:
+ path = root / ".github" / "workflows" / "ci.yml"
+ path.write_text(path.read_text().replace(" with:\n node-version: '22'\n", ""), encoding="utf-8")
+
+ def drift_unscanned_install_path(root: Path) -> None:
+ (root / "extra").mkdir()
+ (root / "extra" / "bootstrap.sh").write_text("#!/bin/sh\npnpm install\n", encoding="utf-8")
+
+ def drift_into_a_syntax_the_parser_skips(root: Path) -> None:
+ """A Node version behind an ARG indirection.
+
+ This is the shape of the bug `check_dependency_pins` found in itself:
+ a declaration that is present, in a scanned file, and invisible to the
+ parser. If `_DOCKER_FROM_ARG` is ever removed, this case fails.
+ """
+ path = root / "services" / "web-svc" / "Dockerfile"
+ path.write_text(
+ "ARG NODE_VERSION=20\nFROM node:${NODE_VERSION}-alpine AS base\n"
+ "RUN npm install -g [email protected]\nRUN pnpm install --frozen-lockfile\n",
+ encoding="utf-8",
+ )
+
+ def drift_inside_a_folded_run_block(root: Path) -> None:
+ """An unlocked install reaching the shell through a folded scalar."""
+ path = root / ".github" / "workflows" / "ci.yml"
+ path.write_text(
+ path.read_text()
+ + " - name: Install via a folded scalar\n"
+ + " run: >-\n"
+ + " pnpm install\n"
+ + " --prefer-offline\n",
+ encoding="utf-8",
+ )
+
+ cases = [
+ ("clean fixture passes", None, None),
+ ("ship -> test (image behind CI)", drift_node_image_behind_ci, "ship -> test"),
+ ("test -> ship (CI ahead of images)", drift_ci_ahead_of_images, "test -> ship"),
+ ("go toolchain disagreement", drift_go_toolchain, "`go` is pinned 2 different ways"),
+ ("floor above toolchain", drift_floor_above_toolchain, "floor <= toolchain"),
+ ("pnpm resolver disagreement", drift_pnpm_resolver, "`pnpm` is pinned 2 different ways"),
+ ("installer installs another Node", drift_installer_node, "`node` is pinned 2 different ways"),
+ ("unlocked install", drift_unlocked_install, "unlocked install"),
+ ("dead lockfile", drift_dead_lockfile, "dead lockfile"),
+ ("image installs without copying the lock", drift_image_without_lockfile, "image -> lockfile"),
+ ("module -> sum (no go.sum)", drift_missing_go_sum, "module -> sum"),
+ ("module -> sum (optional go.sum glob)", drift_optional_go_sum, "module -> sum"),
+ ("sum -> module (cache path absent)", drift_stale_cache_path, "sum -> module"),
+ ("build output committed as source", drift_committed_binary, "build output as source"),
+ ("module -> CI (module nothing builds)", drift_ungated_go_module, "module -> CI"),
+ ("CI -> module (build step for a module that moved)", drift_ci_builds_absent_module, "CI -> module"),
+ ("workspace-wide esbuild override", drift_workspace_wide_esbuild, "override scope"),
+ ("esbuild resolution moved", drift_esbuild_resolution, "override scope"),
+ ("setup step with no version", drift_unversioned_setup, "no version"),
+ ("unscanned install path", drift_unscanned_install_path, "coverage"),
+ ("declaration in a syntax the parser skips", drift_into_a_syntax_the_parser_skips, "ship -> test"),
+ ("drift inside a folded run block", drift_inside_a_folded_run_block, "unlocked install"),
+ ]
+
+ failures: list[str] = []
+ for name, mutate, expect in cases:
+ code, problems = build(mutate)
+ blob = " ".join(problems)
+ if expect is None:
+ failure = f"{name}: expected a clean pass, got {problems}" if code != 0 else None
+ elif code == 0:
+ failure = f"{name}: injected drift went UNDETECTED"
+ elif expect not in blob:
+ failure = f"{name}: detected something else — {problems}"
+ else:
+ failure = None
+ if failure:
+ failures.append(failure)
+ print(f" self-test [{'FAIL' if failure else 'ok'}] {name}")
+
+ # A gate handed a directory that is not the repo must refuse, not print OK.
+ empty = Path(tempfile.mkdtemp(prefix="toolchain_selftest_empty_"))
+ try:
+ code, _ = run(empty)
+ finally:
+ shutil.rmtree(empty, ignore_errors=True)
+ if code == 0:
+ failures.append("non-repo root: printed OK about a tree with no install paths")
+ print(f" self-test [{'ok' if code != 0 else 'FAIL'}] refuses a non-repo root")
+
+ if failures:
+ print("\ncheck_toolchain_pins --self-test: FAIL")
+ for failure in failures:
+ print(f" - {failure}")
+ return 1
+ print(f"\ncheck_toolchain_pins --self-test: OK — {len(cases) + 1} cases, every direction detected")
+ return 0
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--repo-root", type=Path, default=None, help="tree to check")
+ parser.add_argument("--verbose", action="store_true", help="list every file scanned")
+ parser.add_argument("--self-test", action="store_true", help="prove the gate detects drift in each direction")
+ args = parser.parse_args()
+
+ if args.self_test:
+ return self_test()
+
+ root = (args.repo_root or Path(__file__).resolve().parent.parent).resolve()
+ return run(root, verbose=args.verbose)[0]
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/mypy_baseline.json b/scripts/mypy_baseline.json
new file mode 100644
index 000000000..171dd289f
--- /dev/null
+++ b/scripts/mypy_baseline.json
@@ -0,0 +1,311 @@
+{
+ "packages/aisoc-cli": {
+ "src/aisoc_cli/main.py": {
+ "import-not-found": 7,
+ "import-untyped": 2,
+ "untyped-decorator": 48
+ },
+ "tests/test_cli.py": {
+ "import-not-found": 2,
+ "import-untyped": 1,
+ "no-untyped-def": 8
+ },
+ "tests/test_ops_commands.py": {
+ "arg-type": 1,
+ "attr-defined": 15,
+ "import-not-found": 2,
+ "index": 7,
+ "no-untyped-def": 5,
+ "operator": 16,
+ "untyped-decorator": 2
+ },
+ "tests/test_packaging.py": {
+ "import-not-found": 1,
+ "untyped-decorator": 1
+ },
+ "tests/test_submit_command.py": {
+ "attr-defined": 1,
+ "import-not-found": 3,
+ "misc": 1,
+ "no-untyped-call": 1,
+ "no-untyped-def": 3,
+ "untyped-decorator": 1
+ }
+ },
+ "packages/plugin-sdk-py": {
+ "src/aisoc_plugin_sdk/action.py": {
+ "import-not-found": 1,
+ "misc": 2
+ },
+ "src/aisoc_plugin_sdk/client.py": {
+ "import-not-found": 1,
+ "no-any-return": 7
+ },
+ "src/aisoc_plugin_sdk/connector.py": {
+ "import-not-found": 1,
+ "misc": 1
+ },
+ "src/aisoc_plugin_sdk/decorators.py": {
+ "attr-defined": 1,
+ "no-any-return": 2,
+ "type-arg": 5,
+ "unused-ignore": 3
+ },
+ "src/aisoc_plugin_sdk/enricher.py": {
+ "import-not-found": 1,
+ "misc": 2
+ },
+ "src/aisoc_plugin_sdk/loader.py": {
+ "no-any-return": 1,
+ "unused-ignore": 1
+ },
+ "src/aisoc_plugin_sdk/plugin.py": {
+ "import-not-found": 1,
+ "misc": 3
+ },
+ "src/aisoc_plugin_sdk/registry.py": {
+ "import-not-found": 1
+ },
+ "tests/test_client.py": {
+ "import-not-found": 2,
+ "type-arg": 1,
+ "untyped-decorator": 6
+ },
+ "tests/test_hello_plugin_example.py": {
+ "attr-defined": 3,
+ "import-not-found": 1,
+ "untyped-decorator": 1
+ },
+ "tests/test_loader.py": {
+ "import-not-found": 1
+ },
+ "tests/test_sdk.py": {
+ "import-not-found": 1,
+ "untyped-decorator": 6
+ }
+ },
+ "packages/sdk-py": {
+ "src/aisoc_sdk/client.py": {
+ "import-not-found": 2,
+ "no-any-return": 20,
+ "unused-ignore": 1
+ },
+ "src/aisoc_sdk/models.py": {
+ "import-not-found": 1,
+ "misc": 13
+ },
+ "tests/test_client.py": {
+ "func-returns-value": 1,
+ "import-not-found": 2,
+ "no-untyped-def": 10,
+ "untyped-decorator": 8
+ }
+ },
+ "services/api": {
+ "app/api/v1/endpoints/business_context.py": {
+ "import-untyped": 1
+ },
+ "app/api/v1/endpoints/community.py": {
+ "import-untyped": 1
+ },
+ "app/api/v1/endpoints/detection_loop.py": {
+ "call-arg": 1
+ },
+ "app/api/v1/endpoints/hunts.py": {
+ "call-arg": 1
+ },
+ "app/api/v1/endpoints/identity_timeline.py": {
+ "assignment": 1
+ },
+ "app/api/v1/endpoints/knowledge_base.py": {
+ "call-arg": 1
+ },
+ "app/api/v1/endpoints/metrics.py": {
+ "return-value": 2
+ },
+ "app/api/v1/endpoints/phishing.py": {
+ "call-arg": 1
+ },
+ "app/api/v1/endpoints/plugins.py": {
+ "assignment": 8
+ },
+ "app/api/v1/endpoints/translation.py": {
+ "call-arg": 1
+ },
+ "app/auth/saml.py": {
+ "var-annotated": 1
+ },
+ "app/core/scheduler_lock.py": {
+ "func-returns-value": 1
+ },
+ "app/graphql/query.py": {
+ "call-arg": 117
+ },
+ "app/scripts/seed_demo.py": {
+ "no-redef": 1
+ },
+ "app/services/alert_explain.py": {
+ "arg-type": 1
+ },
+ "app/services/business_context/models.py": {
+ "import-untyped": 1
+ },
+ "app/services/detections/sigma_import.py": {
+ "import-untyped": 1
+ },
+ "app/services/effective_permissions/posture_loader.py": {
+ "return-value": 1
+ },
+ "app/services/event_warehouse/registry.py": {
+ "list-item": 2
+ },
+ "app/services/fixture_synth.py": {
+ "import-untyped": 1
+ },
+ "app/services/fleet_health.py": {
+ "arg-type": 22
+ },
+ "app/services/pipeline_transforms.py": {
+ "assignment": 1
+ },
+ "app/services/playbook_step_dispatch.py": {
+ "arg-type": 8,
+ "union-attr": 14
+ },
+ "app/services/plugin_manager.py": {
+ "import-untyped": 1
+ },
+ "app/services/rule_engine.py": {
+ "import-untyped": 1
+ },
+ "app/services/siem_writeback.py": {
+ "arg-type": 1,
+ "union-attr": 6
+ },
+ "app/services/sla.py": {
+ "arg-type": 1,
+ "assignment": 1,
+ "call-overload": 3,
+ "dict-item": 1,
+ "index": 1,
+ "no-redef": 1
+ },
+ "tests/api/v1/endpoints/test_alerts_detail_envelope.py": {
+ "func-returns-value": 1
+ },
+ "tests/api/v1/endpoints/test_detection_proposals_run_eval.py": {
+ "assignment": 1,
+ "attr-defined": 1
+ },
+ "tests/services/test_alert_rail.py": {
+ "arg-type": 28
+ },
+ "tests/services/test_narrative_projection.py": {
+ "arg-type": 29
+ },
+ "tests/test_alert_explain.py": {
+ "arg-type": 43,
+ "list-item": 2
+ },
+ "tests/test_alert_queue.py": {
+ "arg-type": 16
+ },
+ "tests/test_alert_writeback_auth.py": {
+ "arg-type": 2
+ },
+ "tests/test_alerts_tenant_isolation.py": {
+ "misc": 2
+ },
+ "tests/test_audit_export.py": {
+ "arg-type": 9
+ },
+ "tests/test_business_context.py": {
+ "arg-type": 1,
+ "misc": 1,
+ "union-attr": 3
+ },
+ "tests/test_cases_tenant_isolation.py": {
+ "misc": 1
+ },
+ "tests/test_compliance_phishing_kb_tenant_isolation.py": {
+ "assignment": 1,
+ "method-assign": 1,
+ "misc": 2,
+ "var-annotated": 1
+ },
+ "tests/test_credential_vault_envelope.py": {
+ "misc": 1
+ },
+ "tests/test_detection_loop_tenant_isolation.py": {
+ "misc": 1
+ },
+ "tests/test_effective_permissions_aws.py": {
+ "attr-defined": 1
+ },
+ "tests/test_email_approval_endpoint.py": {
+ "arg-type": 2
+ },
+ "tests/test_event_warehouse_providers.py": {
+ "union-attr": 7
+ },
+ "tests/test_event_warehouse_registry.py": {
+ "arg-type": 3
+ },
+ "tests/test_health_probes.py": {
+ "misc": 6,
+ "valid-type": 1
+ },
+ "tests/test_hunts_tenant_isolation.py": {
+ "misc": 1
+ },
+ "tests/test_llm_credentials_endpoint.py": {
+ "arg-type": 5
+ },
+ "tests/test_llm_credentials_tenant_isolation.py": {
+ "misc": 2
+ },
+ "tests/test_oauth_refresh_worker.py": {
+ "arg-type": 12
+ },
+ "tests/test_rule_tuning.py": {
+ "arg-type": 20,
+ "assignment": 1,
+ "union-attr": 4
+ },
+ "tests/test_saved_hunts_endpoint.py": {
+ "arg-type": 3
+ },
+ "tests/test_saved_views_endpoint.py": {
+ "arg-type": 2
+ },
+ "tests/test_seed_demo_confidence_synth.py": {
+ "arg-type": 10
+ },
+ "tests/test_siem_writeback.py": {
+ "union-attr": 5
+ },
+ "tests/test_tenant_deletion.py": {
+ "assignment": 1,
+ "attr-defined": 1
+ },
+ "tests/test_tenant_provision.py": {
+ "operator": 1
+ },
+ "tests/test_threat_intel_tenant_isolation.py": {
+ "misc": 3
+ }
+ },
+ "services/fusion": {
+ "tests/test_consumer_dlq.py": {
+ "arg-type": 1
+ },
+ "tests/test_derived_fields.py": {
+ "arg-type": 1
+ }
+ },
+ "services/osquery-tls": {
+ "app/services/pack_loader.py": {
+ "import-untyped": 1
+ }
+ }
+}
diff --git a/services/demo-producer/demo-producer b/services/demo-producer/demo-producer
deleted file mode 100755
index 16e77999c..000000000
Binary files a/services/demo-producer/demo-producer and /dev/null differ
diff --git a/services/enrichment/Dockerfile b/services/enrichment/Dockerfile
index 572731026..018762bab 100644
--- a/services/enrichment/Dockerfile
+++ b/services/enrichment/Dockerfile
@@ -3,7 +3,10 @@ FROM golang:1.26-alpine AS builder
WORKDIR /app
RUN apk add --no-cache git ca-certificates
-COPY go.mod go.sum* ./
+# Not `go.sum*`: the glob makes the checksum file optional, so if it ever went
+# missing this build would still succeed and `go mod download` would resolve
+# the module graph unverified.
+COPY go.mod go.sum ./
RUN go mod download
COPY . .
diff --git a/services/fusion/app/services/ml_scorer.py b/services/fusion/app/services/ml_scorer.py
index 44b53f1a4..a1dcce5dd 100644
--- a/services/fusion/app/services/ml_scorer.py
+++ b/services/fusion/app/services/ml_scorer.py
@@ -203,12 +203,20 @@ class MLScorer:
def _predict_anomaly(self, features: list[float]) -> float:
"""Run IsolationForest prediction synchronously."""
+ # Bound locally so the "caller already checked `_iso_forest is not
+ # None`" invariant is visible here rather than only at the call site.
+ # Without it the attribute access on None was reachable as far as any
+ # reader or checker could tell, and the only thing turning it into a
+ # score of 0.0 was the blanket `except Exception` below.
+ model = self._iso_forest
+ if model is None:
+ return 0.0
try:
import numpy as np
X = np.array(features).reshape(1, -1)
# decision_function: negative = anomaly, normalize to [0,1]
- raw = self._iso_forest.decision_function(X)[0]
+ raw = model.decision_function(X)[0]
# Map decision score: lower = more anomalous
# Typical range is -0.5 to +0.5; map to 0→1 (inverted)
score = 1.0 / (1.0 + math.exp(5 * raw)) # sigmoid inversion
@@ -219,11 +227,14 @@ class MLScorer:
def _predict_priority(self, features: list[float]) -> float:
"""Run LightGBM ranker prediction synchronously."""
+ model = self._lgbm_ranker # see `_predict_anomaly` for why this is bound
+ if model is None:
+ return 0.0
try:
import numpy as np
X = np.array(features).reshape(1, -1)
- raw = self._lgbm_ranker.predict(X)[0]
+ raw = model.predict(X)[0]
# Normalize to [0,1] via sigmoid
score = 1.0 / (1.0 + math.exp(-raw))
return float(score)
diff --git a/services/fusion/app/workers/consumer.py b/services/fusion/app/workers/consumer.py
index d18925353..9c22423c1 100644
--- a/services/fusion/app/workers/consumer.py
+++ b/services/fusion/app/workers/consumer.py
@@ -147,7 +147,15 @@ class FusionWorker:
logger.info("Fusion worker stopped", metrics=_METRICS)
async def _consume_loop(self) -> None:
- async for msg in self._consumer:
+ # `start()` is the only caller and assigns `_consumer` before getting
+ # here. Bound locally so that invariant is stated where it is relied
+ # on: iterating or committing a None consumer would otherwise be an
+ # AttributeError inside the message loop, reported as a processing
+ # failure rather than as the startup bug it is.
+ consumer = self._consumer
+ if consumer is None: # pragma: no cover — unreachable via start()
+ raise RuntimeError("fusion consume loop started before the Kafka consumer")
+ async for msg in consumer:
if not self._running:
break
try:
@@ -161,7 +169,7 @@ class FusionWorker:
# before this line re-delivers the in-flight message on restart
# instead of losing it. Commit failure => reprocess on restart.
try:
- await self._consumer.commit()
+ await consumer.commit()
except Exception as commit_exc: # noqa: BLE001
logger.warning("fusion.commit_failed", error=str(commit_exc))
# Flush any stale lake batch so archival isn't stranded during a
@@ -315,7 +323,10 @@ class FusionWorker:
envelope = fused.model_dump(mode="json")
envelope["alert_row_id"] = result.alert_id
envelope["persist_outcome"] = result.outcome.value
- await self._producer.send(
+ producer = self._producer
+ if producer is None: # pragma: no cover — assigned by start()
+ raise RuntimeError("fusion produced a fused alert before the Kafka producer started")
+ await producer.send(
settings.kafka_topic_alerts_fused,
value=envelope,
)
diff --git a/services/realtime/Dockerfile b/services/realtime/Dockerfile
index e50380a12..b60f4c36e 100644
--- a/services/realtime/Dockerfile
+++ b/services/realtime/Dockerfile
@@ -1,15 +1,23 @@
-FROM node:20-alpine AS builder
+# AiSOC realtime (WebSocket / SSE) service.
+#
+# `npm ci`, not `npm install`, and the lockfile is copied in both stages.
+# This image used to copy only `package.json` and run `npm install`, so the
+# committed `package-lock.json` was never in the build context and every
+# build re-resolved the whole tree — including a fresh answer for each `^`
+# range. Spelling the command `npm ci` alone would not have helped: it would
+# have failed for want of a file nobody copied. The two halves go together.
+FROM node:22-alpine AS builder
WORKDIR /app
-COPY package.json ./
-RUN npm install
+COPY package.json package-lock.json ./
+RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build
-FROM node:20-alpine
+FROM node:22-alpine
WORKDIR /app
-COPY package.json ./
-RUN npm install --omit=dev
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist
EXPOSE 8086
CMD ["node", "dist/index.js"]
diff --git a/tests/test_toolchain_pin_gate.py b/tests/test_toolchain_pin_gate.py
new file mode 100644
index 000000000..05e0db216
--- /dev/null
+++ b/tests/test_toolchain_pin_gate.py
@@ -0,0 +1,392 @@
+"""Unit tests for `scripts/check_toolchain_pins.py`.
+
+`--self-test` proves the gate detects drift end to end by building throwaway
+repositories. These tests cover the parts a fixture exercises only
+incidentally: the normalisers, and the parser behaviours that were each a
+real bug in this gate or its predecessor before they were a test.
+
+The parser cases matter most. Every one of them is a shape that was present
+in the tree and invisible: a Node version behind an ARG, a Go module selected
+by a matrix expression, an install command inside a shell error message, a
+`--frozen-lockfile=false` that a substring test reads as enabled.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_SPEC = importlib.util.spec_from_file_location(
+ "check_toolchain_pins", Path(__file__).resolve().parent.parent / "scripts" / "check_toolchain_pins.py"
+)
+assert _SPEC and _SPEC.loader
+gate = importlib.util.module_from_spec(_SPEC)
+sys.modules["check_toolchain_pins"] = gate
+_SPEC.loader.exec_module(gate)
+
+
+# ── Version normalisation ────────────────────────────────────────────────────
+
+
+ ("raw", "expected"),
+ [
+ ("22", "22"),
+ ("'22'", "22"),
+ ("22-alpine", "22"),
+ ("1.26", "1.26"),
+ ("1.26-alpine", "1.26"),
+ ("3.11-slim", "3.11"),
+ ("8.15.1", "8.15"),
+ ],
+)
+def test_normalise_version_reduces_to_the_precision_that_is_pinned(raw, expected):
+ assert gate.normalise_version(raw) == expected
+
+
+ ("floor", "toolchain", "ok"),
+ [
+ ("1.26", "1.26", True),
+ ("1.26", "1.27", True),
+ ("1.28", "1.26", False),
+ ("20.0.0", "22", True),
+ ("22.0.0", "20", False),
+ ("3.11", "3.12", True),
+ ],
+)
+def test_at_most_compares_a_floor_against_an_installed_toolchain(floor, toolchain, ok):
+ assert gate.at_most(floor, toolchain) is ok
+
+
+def test_normalise_version_pads_unequal_precision():
+ """`22` and `22.0.0` are one version; a floor must not fail on the shape."""
+ assert gate.at_most("22.0.0", "22")
+ assert gate.at_most("22", "22.0.0")
+
+
+# ── Install-command parsing ──────────────────────────────────────────────────
+
+
+def test_frozen_lockfile_equals_false_is_not_locked():
+ """The devcontainer's real spelling.
+
+ `"--frozen-lockfile" in command` reads `--frozen-lockfile=false` as
+ enabling the flag it disables, so the one install path that opted out
+ counted as locked.
+ """
+ (install,) = gate._install_commands("RUN pnpm install --frozen-lockfile=false", "Dockerfile", "")
+ assert install.locked is False
+
+
+def test_no_frozen_lockfile_is_not_locked():
+ (install,) = gate._install_commands("RUN pnpm install --no-frozen-lockfile", "Dockerfile", "")
+ assert install.locked is False
+
+
+def test_frozen_lockfile_is_locked():
+ (install,) = gate._install_commands("RUN pnpm install --frozen-lockfile", "Dockerfile", "")
+ assert install.locked is True
+
+
+def test_pnpm_install_is_not_read_as_an_npm_install():
+ """`pnpm` ends in `npm`.
+
+ Without a left word boundary the npm pattern matches inside every pnpm
+ command, so each one was reported twice — once correctly and once as an
+ unlocked npm install that does not exist anywhere in the repository.
+ """
+ installs = gate._install_commands("RUN pnpm install --frozen-lockfile", "Dockerfile", "")
+ assert [i.tool for i in installs] == ["pnpm"]
+
+
+def test_npm_ci_is_locked_and_npm_install_is_not():
+ locked = gate._install_commands("RUN npm ci --omit=dev", "Dockerfile", "")
+ unlocked = gate._install_commands("RUN npm install", "Dockerfile", "")
+ assert [(i.tool, i.locked) for i in locked] == [("npm", True)]
+ assert [(i.tool, i.locked) for i in unlocked] == [("npm", False)]
+
+
+def test_global_tool_installs_are_not_project_installs():
+ assert gate._install_commands("RUN npm install -g [email protected]", "Dockerfile", "") == []
+ assert gate._install_commands("RUN npm install --global corepack", "Dockerfile", "") == []
+
+
+def test_install_commands_inside_shell_messages_are_not_install_paths():
+ """`install.sh` says `die "pnpm install failed."`.
+
+ Read literally that is an install path, and so are the two other messages
+ around it. Quoted text in a shell source is an argument.
+ """
+ text = 'info "Installing deps (pnpm install)..."\npnpm install --frozen-lockfile\ndie "pnpm install failed."\n'
+ installs = gate._install_commands(text, "install.sh", "", shell_source=True)
+ assert [i.raw for i in installs] == ["pnpm install --frozen-lockfile"]
+
+
+def test_a_multi_line_shell_message_is_still_a_message():
+ text = 'pnpm install --frozen-lockfile\ndie "pnpm install failed.\nTry again."\n'
+ installs = gate._install_commands(text, "install.sh", "", shell_source=True)
+ assert len(installs) == 1
+
+
+def test_json_command_values_are_not_stripped_as_quotes():
+ """The devcontainer declares its install *as* a quoted JSON value.
+
+ Stripping quotes there would delete the install path being searched for,
+ which is the blind spot the quote-stripping exists to avoid creating.
+ """
+ text = '{"onCreateCommand": "pnpm install --frozen-lockfile"}'
+ assert len(gate._install_commands(text, ".devcontainer/devcontainer.json", "")) == 1
+
+
+def test_a_folded_run_scalar_is_one_command():
+ """The syntax that hid a whole dependency set from the dependency gate."""
+ text = "jobs:\n a:\n steps:\n - run: >-\n pnpm install\n --prefer-offline\n"
+ installs = gate._install_commands(text, ".github/workflows/x.yml", "")
+ assert len(installs) == 1
+ assert installs[0].locked is False
+
+
+def test_comment_lines_are_not_commands():
+ text = "# RUN pnpm install --no-frozen-lockfile is what this used to do\nRUN pnpm install --frozen-lockfile\n"
+ installs = gate._install_commands(text, "Dockerfile", "")
+ assert [i.locked for i in installs] == [True]
+
+
+# ── Matrix expansion ─────────────────────────────────────────────────────────
+
+
+def test_matrix_expression_resolves_to_every_leg():
+ """`cd services/${{ matrix.service }}` is three modules, not zero.
+
+ A reader that skipped the expression reported five of six Go modules as
+ compiled by nothing; one that matched every `cd services/<x>` reported
+ five Python services as Go modules.
+ """
+ text = " strategy:\n matrix:\n service: [enrichment, ingest, demo-producer]\n"
+ matrix = gate._matrix_values(text)
+ assert gate._expand("services/${{ matrix.service }}", matrix) == [
+ "services/enrichment",
+ "services/ingest",
+ "services/demo-producer",
+ ]
+
+
+def test_an_unresolvable_expression_expands_to_nothing_rather_than_a_literal():
+ assert gate._expand("services/${{ matrix.absent }}", {}) == []
+
+
+def test_a_literal_path_needs_no_matrix():
+ assert gate._expand("services/ingest", {}) == ["services/ingest"]
+
+
+# ── Checks ───────────────────────────────────────────────────────────────────
+
+
+def _scan_with(**kwargs) -> gate.Scan:
+ scan = gate.Scan()
+ for key, value in kwargs.items():
+ setattr(scan, key, value)
+ return scan
+
+
+def test_engines_floor_is_not_treated_as_a_toolchain():
+ """A published package's `engines` states what a consumer needs.
+
+ `packages/aisoc-lite` supports Node 20 on purpose. Reading that as "this
+ repository builds on 20" would force every published floor up to the
+ build toolchain for no reason.
+ """
+ scan = _scan_with(
+ pins=[
+ gate.Pin("node", "22", ".github/workflows/ci.yml", "test", ""),
+ gate.Pin("node", "22", "apps/web/Dockerfile", "ship", ""),
+ gate.Pin("node", "18.17", "services/mcp/package.json", "floor", ""),
+ ]
+ )
+ assert gate.check_runtime_agreement(scan) == []
+ assert gate.check_floors(scan) == []
+
+
+def test_a_floor_above_the_toolchain_fails():
+ scan = _scan_with(
+ pins=[
+ gate.Pin("node", "20", "apps/web/Dockerfile", "ship", ""),
+ gate.Pin("node", "22.0.0", "package.json", "floor", ""),
+ ]
+ )
+ assert any("floor <= toolchain" in p for p in gate.check_floors(scan))
+
+
+def test_ship_and_test_parity_runs_in_both_directions():
+ behind = _scan_with(
+ pins=[
+ gate.Pin("node", "20", "apps/web/Dockerfile", "ship", ""),
+ gate.Pin("node", "22", ".github/workflows/ci.yml", "test", ""),
+ ]
+ )
+ problems = gate.check_ship_test_parity(behind)
+ assert any("ship -> test" in p for p in problems)
+ assert any("test -> ship" in p for p in problems)
+
+
+def test_python_is_ratcheted_rather_than_required_to_match():
+ """Python's manifests declare a floor, so 3.12 in CI violates nothing written.
+
+ The gap is recorded instead of enforced, and the recording is what must
+ not drift: a workflow joining the split without being listed fails.
+ """
+ scan = _scan_with(
+ pins=[
+ gate.Pin("python", "3.11", "services/api/Dockerfile", "ship", ""),
+ gate.Pin("python", "3.12", ".github/workflows/brand-new.yml", "test", ""),
+ ],
+ files=[".github/workflows/brand-new.yml"],
+ )
+ assert gate.check_ship_test_parity(scan) == []
+ assert any("may not grow silently" in p for p in gate.check_python_split(scan))
+
+
+def test_a_listed_python_workflow_that_no_longer_differs_must_be_removed():
+ listed = sorted(gate.PYTHON_INTERPRETER_SPLIT)[0]
+ scan = _scan_with(
+ pins=[
+ gate.Pin("python", "3.11", "services/api/Dockerfile", "ship", ""),
+ gate.Pin("python", "3.11", listed, "test", ""),
+ ],
+ files=[listed],
+ )
+ assert any("remove it" in p for p in gate.check_python_split(scan))
+
+
+def test_two_shipped_python_interpreters_fail_outright():
+ scan = _scan_with(
+ pins=[
+ gate.Pin("python", "3.11", "services/api/Dockerfile", "ship", ""),
+ gate.Pin("python", "3.12", "services/fusion/Dockerfile", "ship", ""),
+ ]
+ )
+ assert any("different Python interpreters" in p for p in gate.check_python_split(scan))
+
+
+def test_pnpm_action_version_is_declared_not_voted_on():
+ """A majority vote ratifies the drift it exists to catch.
+
+ Flip enough workflows and the "correct" version becomes the new one.
+ """
+ scan = _scan_with(
+ pnpm_actions=[("a.yml", "v4"), ("b.yml", "v4"), ("c.yml", gate.PNPM_ACTION_VERSION)],
+ files=["a.yml", "b.yml", "c.yml"],
+ )
+ problems = gate.check_pnpm_actions(scan)
+ assert len(problems) == 2
+ assert all("v4" in p for p in problems)
+
+
+def test_a_declared_pnpm_exemption_is_honoured():
+ path = sorted(gate.PNPM_ACTION_EXEMPT)[0]
+ scan = _scan_with(pnpm_actions=[(path, "v4"), ("c.yml", gate.PNPM_ACTION_VERSION)], files=[path, "c.yml"])
+ assert gate.check_pnpm_actions(scan) == []
+
+
+def test_a_pnpm_exemption_for_a_workflow_without_pnpm_has_rotted():
+ path = sorted(gate.PNPM_ACTION_EXEMPT)[0]
+ scan = _scan_with(pnpm_actions=[("c.yml", gate.PNPM_ACTION_VERSION)], files=[path, "c.yml"])
+ assert any("rot" in p for p in gate.check_pnpm_actions(scan))
+
+
+def test_every_declared_exemption_carries_a_reason():
+ """An exemption without a reason is a hole with a comment next to it."""
+ for registry in (gate.PNPM_ACTION_EXEMPT, gate.UNLOCKED_INSTALL_EXEMPT, gate.EXPECTED_ESBUILD):
+ for key, reason in registry.items():
+ assert isinstance(reason, str) and len(reason) > 20, key
+
+
+def test_every_runtime_records_why_it_matters():
+ for runtime, reason in gate.RUNTIMES.items():
+ assert len(reason) > 40, runtime
+
+
+# ── esbuild overrides ────────────────────────────────────────────────────────
+
+
+def _write_workspace(root: Path, overrides: dict, resolved: list[str]) -> None:
+ (root / "package.json").write_text(json.dumps({"pnpm": {"overrides": overrides}}), encoding="utf-8")
+ (root / "pnpm-lock.yaml").write_text("\n".join(f" /esbuild@{v}:" for v in resolved), encoding="utf-8")
+
+
+def test_a_scoped_esbuild_override_is_allowed(tmp_path):
+ _write_workspace(tmp_path, {"vite>esbuild": "^0.28.1"}, list(gate.EXPECTED_ESBUILD))
+ assert gate.check_esbuild_overrides(tmp_path) == []
+
+
+def test_a_workspace_wide_esbuild_override_fails(tmp_path):
+ """Next bundles its own esbuild; replacing it broke Turbopack's font map."""
+ _write_workspace(tmp_path, {"esbuild": "^0.28.1"}, list(gate.EXPECTED_ESBUILD))
+ assert any("override scope" in p for p in gate.check_esbuild_overrides(tmp_path))
+
+
+def test_a_moved_esbuild_resolution_fails(tmp_path):
+ """A vite bump pulls esbuild through the scoped override with no esbuild in the diff."""
+ _write_workspace(tmp_path, {"vite>esbuild": "^0.28.1"}, [*gate.EXPECTED_ESBUILD, "0.30.0"])
+ assert any("0.30.0" in p for p in gate.check_esbuild_overrides(tmp_path))
+
+
+def test_a_stale_expectation_fails(tmp_path):
+ _write_workspace(tmp_path, {"vite>esbuild": "^0.28.1"}, [sorted(gate.EXPECTED_ESBUILD)[0]])
+ assert any("stale" in p for p in gate.check_esbuild_overrides(tmp_path))
+
+
+# ── The gate against this repository ─────────────────────────────────────────
+
+REPO = Path(__file__).resolve().parent.parent
+
+
+def test_the_gate_passes_on_this_repository():
+ code, problems = gate.run(REPO)
+ assert code == 0, problems
+
+
+def test_the_gate_refuses_a_directory_that_is_not_the_repository(tmp_path):
+ """One gate here resolved its root from its own file location and would
+ have printed a confident OK about a tree it never opened."""
+ code, problems = gate.run(tmp_path)
+ assert code == 1
+ assert "does not look like the AiSOC repository" in problems[0]
+
+
+def test_the_scan_names_what_it_read():
+ scanned = set(gate.scan(REPO).files)
+ for expected in (
+ ".github/workflows/ci.yml",
+ "apps/web/Dockerfile",
+ "services/realtime/Dockerfile",
+ "services/ingest/go.mod",
+ "package.json",
+ "install.sh",
+ ".devcontainer/devcontainer.json",
+ ):
+ assert expected in scanned, expected
+
+
+def test_every_go_module_in_the_tree_is_scanned():
+ found = {Path(f).parent.as_posix() for f in gate.scan(REPO).files if f.endswith("go.mod")}
+ on_disk = {p.parent.relative_to(REPO).as_posix() for p in REPO.rglob("go.mod") if "node_modules" not in str(p)}
+ assert found == {d for d in on_disk if not d.startswith("plans/")}
+
+
+def test_self_test_covers_every_check_function():
+ """A direction with no injection is a direction nobody has proved detects.
+
+ Counted structurally rather than listed, so adding a `check_*` without a
+ self-test case fails here instead of silently shipping untested.
+ """
+ checks = [n for n in dir(gate) if n.startswith("check_")]
+ assert len(checks) >= 10
+ source = (REPO / "scripts" / "check_toolchain_pins.py").read_text(encoding="utf-8")
+ for name in checks:
+ assert f"{name}(" in source.split("def run(")[1], f"{name} is never called by run()"