[jeroenrinzema]

Stacked on #21 (feat/detect-env). Everything is opt-in: --with-env reads manifest/config/deployment files only; the source-file search needs --with-source as well (--with-source without --with-env is a clap error).

Summary

brainpod detect --with-env now also reports:

• Platform deployment manifests: Heroku/Dokku app.json, Scalingo scalingo.json, heroku.yml, Render render.yaml, Fly.io fly.toml, DigitalOcean .do/app.yaml/.do/deploy.template.yaml, Vercel vercel.json/vercel.toml (legacy env/build.env), Netlify netlify.toml (build, context and template environments), Google App Engine app.yaml (only when runtime is present), and AWS Copilot copilot/*/manifest.yml. Railway and Koyeb are excluded: Railway's config files hold no variables and its replacement is executable code, and Koyeb has no repository file.
• New optional record fields: required, secret, generated, hasDefault and scope. Each is set only where the manifest states it. Database, service and secret wiring uses feat: detect environment declarations with --with-env #21's reference shape: Render fromDatabase/fromService/fromGroup, DigitalOcean ${db.VAR}/${APP_URL} bindings, Vercel @secret, and Copilot SSM, Secrets Manager and CloudFormation references.
• Dockerfile ARG: reported like ENV, with scope: "build" and a hasDefault boolean. This updates feat: detect environment declarations with --with-env #21's statement that ARG is not inferred.
• Code references (--with-env --with-source only): a literal, catalog-driven search of source files for platform-injected names and framework env prefixes:
  • Platforms: Vercel, Netlify, Render, Railway, Heroku, Fly.io, Cloudflare Pages, App Engine, Cloud Run and Koyeb.
  • Frameworks: NEXT_PUBLIC_, VITE_, REACT_APP_, NUXT_PUBLIC_/NUXT_, PUBLIC_ (only in projects detected as SvelteKit or Astro), EXPO_PUBLIC_, GATSBY_, VUE_APP_ and others.
  • Patterns live as data in rules.toml catalog.code_references, each with its primary documentation link.
  • Each (project, name) becomes one format: "code-reference" record with origin, provider, scope, up to 20 file/line occurrences and occurrenceCount.
  • Generic names (URL, CONTEXT, PORT, …) are never cataloged. Moderately generic documented names are reported only when the platform's manifest exists in the repository.

Platform adapters live in src/detect/environment/platforms.rs and the code-reference matcher in src/detect/environment/references.rs. There are no new dependencies: TOML uses the existing toml crate, and platform JSON uses serde_json. JSON keeps the last value of a duplicate key, as these platforms do; Chatwoot's app.json has one.

Read impact

Measured on the 56 pinned repositories. Times are the median of per-repository five-run warm medians on a loaded host, including CLI startup and serialization.

Mode	Files read	Bytes read	Median ms
No flags	5,239	7.3 MB	15.66
--with-env on #21	6,756	14.4 MB	17.49
--with-env	6,822	15.1 MB	18.04
--with-env --with-source	277,283	1.77 GB	78.29

--with-env reads no application source; the 66 extra files compared with #21 are the platform manifests. Only --with-source reads source files. Without flags, reads and output are unchanged.

Privacy

Names and provenance only. No values are returned in JSON, text, diagnostics or retained facts, including defaults, generated values, secret values, DigitalOcean EV[...] values and Netlify template labels. Nothing is evaluated, expanded, fetched or executed. Source files are only split into identifier tokens; no code text is kept. SSM paths, ARNs and other non-simple targets are dropped. Malformed input produces fixed, redacted diagnostics. Synthetic tests assert that DO_NOT_DISCLOSE markers never appear in output.

Validation

• cargo test --locked: 231 passed, 3 ignored benchmarks not run. The offline cache lacks serde-saphyr, so this ran online. New tests check that --with-env alone reads no source files and emits no code-reference records, and that clap rejects --with-source without --with-env.
• cargo fmt --all -- --check: passed.
• cargo clippy --all-targets -- -D warnings: with clippy 0.1.98 there are 4 errors in unchanged code (deno.rs question_mark, generated tunnel protobuf result_large_err); the base branch reports the same 4. With only those two lints allowed, clippy is clean.
• Python audit-runner tests: 13/13. The runner gains --with-source. Code-reference corpus checks are stored as sourceChecks and run only in that mode; declaration checks run in both opt-in modes.
• Corpus audit, 56/56 repositories with 5 deterministic runs (51 existing plus 5 pinned supplements for Render, DigitalOcean, Copilot, App Engine and app.json):
  • No flags: 300/300.
  • --with-env: 348/348, including 48/48 declaration checks (22 new).
  • --with-env --with-source: 353/353, adding 5/5 sourceChecks.
  • All 56 no-flag JSON reports are byte-identical to the feat: detect environment declarations with --with-env #21 base binary, and the projects arrays in both opt-in modes equal the no-flag ones.
• One existing feat: detect environment declarations with --with-env #21 assertion, hyperswitch EXTRA_FEATURES absent, encoded "ARG is not inferred". It now asserts that no non-build record exists, plus a positive build-scoped ARG check.
• Not run: native OS CI and the Brainpod starter branches.

See tests/detect-env.md for the platform research (included and excluded, with doc links), the field mapping per format, the code-reference rules and pattern table with sources, and full results.

[dmeijboom]

Approved but as discussed with a new flag

[Copilot]

🟡 Changes recommended

Environment overrides omit sidecar declarations from detection, and reference scanning retains and clones every match before truncation, risking substantial memory amplification despite the output cap.

2 open issues

• Include sidecar declarations when scanning environment overrides · New
• Bound match storage before aggregating and truncating results · New

What changed in this PR

Extends the opt-in environment detection introduced in #21 with platform deployment manifests and catalog-driven source references, while preserving default scan behavior.

Changes:

• Adds platform adapters and optional semantic fields for declarations and resource references.
• Detects build-scoped Dockerfile ARG declarations and cataloged environment names in source files.
• Expands synthetic tests, pinned corpus checks, and documentation covering privacy and increased opt-in reads.

File	Description
tests/​detect-env.md	Documents platform coverage, reference matching, privacy, and validation results.
tests/​detect-corpus.md	Describes the five-repository platform supplement.
tests/​detect-corpus.json	Adds platform, build-argument, and code-reference assertions.
src/​detect/​rules.toml	Defines platform routing and documented code-reference patterns.
src/​detect/​mod.rs	Integrates source scanning, project ownership, and output fields.
src/​detect/​environment/​references.rs	Matches cataloged identifiers and groups reference records.
src/​detect/​environment/​platforms.rs	Parses platform declarations and resource references.
src/​detect/​environment.rs	Adds formats, semantic fields, and Dockerfile ARG parsing.
src/​detect/​environment_tests.rs	Updates existing tests for source reads and build arguments.
src/​detect/​environment_reference_tests.rs	Tests matching, gating, occurrence limits, and determinism.
src/​detect/​environment_platform_tests.rs	Tests platform semantics, routing, and redaction.
src/​detect/​catalog.rs	Compiles and extends the code-reference catalog.
README.md	Explains expanded opt-in coverage and source-read impact.

_{Review effort: Balanced}