build-verify

Build Verify

Purpose — "clean" must mean it actually WORKS

The other skills check quality, security, style and licensing — but none of them runs the compiler. SonarQube and the linters do static analysis: they parse the code and apply rules. They do not run tsc, go build, cargo check or the project's real build, and they do not fail when the build would. So a refactoring that introduces a type/compile error — or a config change that breaks the build — can pass SonarQube with a green Quality Gate (0 bugs, 0 smells) while the actual build fails. That is exactly the "looks nice but doesn't work" code this suite exists to prevent.

This skill closes that gap. It runs the project's canonical compile/typecheck in the matching official Docker image and gates on a build failure (exit 1 = real finding). "Clean" is only clean if it compiles and builds.

There is no single cross-language "build-quality" tool — the compiler of each ecosystem IS the tool. So this skill detects the language(s) like the other scanners and runs the right compiler, staying Dockerized and host-toolchain-free.

What it runs (auto-detected; a repo may match several)

All detection is recursive (monorepo-aware), so projects in sub-directories are found and built — a repo may match several:

Language	Detected by	Check
TypeScript	every tsconfig.json (per file)	tsc --noEmit (project's own tsc, else npx typescript)
Python	any *.py	python -m compileall (syntax) · mypy opt-in
Go	every go.mod (each is an independent module)	go build ./...
Rust	Cargo.toml workspace roots / standalone crates	cargo check
PHP	any *.php	php -l (syntax)
Ruby	any *.rb	ruby -c (syntax)
Java/Kotlin	topmost pom.xml / build.gradle[.kts] (aggregators build their modules)	mvn compile / gradle classes
.NET	*.sln / *.csproj	dotnet build
ANY (default)	each Dockerfile	docker build — the real prod/release build

Nothing detected → it exits 0 with "nothing to verify" (logged, never a silent pass).

No tree pollution. Compiled languages that would otherwise write into the source (Go binaries + go.sum, Rust Cargo.lock, JVM target//build/, .NET obj//bin/) build from a writable copy in /tmp; TypeScript redirects its .tsbuildinfo to /dev/null (so a composite/incremental project doesn't EROFS on the read-only mount). Python .pyc goes to /tmp. The project tree is always mounted read-only and left untouched.

Core Workflow (drive to a building project)

1. Verify:

   ~/.claude/skills/build-verify/scripts/scan.sh [TARGET_DIR]
   

2. Fix every compile/type error at the root (correct the type, the import, the signature, the config) — never silence it. Re-run.
3. Stop when it exits 0 (everything detected compiles/typechecks).

Two tiers — and an honesty note

• Tier 1: typecheck/compile. Fast, side-effect-free. Catches the broad class of refactoring breakages (type errors, bad imports, syntax) per language.
• Tier 2 (DEFAULT): the real Docker build. Builds every Dockerfile found — the faithful prod/release build, the same artifact CI/ACR builds. This is the language-agnostic guarantee that the release build goes through. For the fast refactoring loop, skip it:

  BUILD_VERIFY_NO_DOCKER=1 ~/.claude/skills/build-verify/scripts/scan.sh [DIR]
  

Why Tier 2 is the real guarantee: a Tier-1 typecheck runs with the project's dependencies present, so it will not reproduce a prod-only dependency split — e.g. a test file that imports a devDependency the production build omits (a classic Cannot find module at build time). Only a build that mirrors prod catches that, and the Dockerfile build does exactly that. Tests, lint and SonarQube do not catch build-time issues like this — the build does.

What it still cannot catch: deploy-time failures a compiler never sees — a pinned external image tag that does not exist, registry auth, runtime env, integration tests needing live services. "Release goes through" minus those is what this delivers; those remain deploy-pipeline concerns.

The Docker build context defaults to each Dockerfile's own directory (the per-service CI pattern); if a build fails on a missing COPY source it is retried once with the repo root as context (the other common pattern). Override the context for the whole run with BUILD_VERIFY_DOCKER_CONTEXT. A failed build step (RUN/COPY/compile, incl. a missing COPY source) is a finding; only a base-image pull / registry / DNS failure is classified operational, not a finding.

Finding vs. operational (no green-washing, no false alarms)

A non-zero exit is reported as a real finding (exit 1) only when the output carries the compiler's own diagnostic signature (error TS####, file.go:line:, error[E####] / a rustc --> pointer, a compileall syntax error). A toolchain that simply could not run (image pull failure, missing local tsc, network/module-download failure, Docker error) is an operational ERROR (exit 125) — never mislabeled as a finding, never silently passed. Same discipline as the rest of the suite.

Notes & tuning

• Mounts the project read-only; caches/.pyc/target/build/obj/bin are redirected to (or built in) /tmp inside the container so the tree is never polluted.
• BUILD_VERIFY_NO_DOCKER=1 skips the Dockerfile build (fast loop). BUILD_VERIFY_MYPY=1 adds Python type-checking via mypy. BUILD_VERIFY_DOCKER_CONTEXT sets the build context.
• Image overrides: BUILD_VERIFY_NODE_IMAGE, _PY_IMAGE, _GO_IMAGE, _RUST_IMAGE, _PHP_IMAGE, _RUBY_IMAGE, _MAVEN_IMAGE, _GRADLE_IMAGE, _DOTNET_IMAGE.
• First runs pull the per-language base images (JVM/.NET/Maven SDK images and Tier-2 Docker builds are heavy); subsequent runs reuse the Docker layer cache.
• Within the suite, build-verify runs by default; set BUILD_VERIFY_NO_DOCKER=1 for a fast pass or SUITE_SKIP=buildverify to skip it entirely.

Resources

• scripts/scan.sh — detects TS/Python/Go/Rust/PHP/Ruby/JVM/.NET, runs each compiler/typechecker in Docker, builds Dockerfiles by default, and gates: exit 0 = builds clean (or nothing to build), 1 = compile/build error, 125 = operational error. Env: BUILD_VERIFY_NO_DOCKER, BUILD_VERIFY_DOCKER_CONTEXT, BUILD_VERIFY_MYPY, BUILD_VERIFY_*_IMAGE.
• scripts/lib.sh — shared classification signatures + classify* functions, sourced by BOTH scan.sh and selftest.sh so the per-language finding/operational regexes can never drift between production and the test. Change a signature here once.
• scripts/selftest.sh — regression guard: builds mini-fixtures and runs the REAL scan.sh against them, plus classifier unit tests against lib.sh. Run it before committing any change to scan.sh/lib.sh (./scripts/selftest.sh).