pi-dev-team 0.2.0

package/skills/static-analysis-integration/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: static-analysis-integration
+description: >-
+  SARIF-first pre-pass stage for /code-review that runs available static
+  analysis tools and normalizes their output to the unified finding envelope
+  defined in security-primitives-contract v1.0.0. Deduplicates findings across
+  tools and passes confirmed issues to AI agents so they can focus on semantic
+  concerns.
+role: worker
+user-invocable: false
+version: 2.0.0
+maintainers:
+  - bdfinst
+  - unassigned   # TODO: name a second maintainer before shipping to production; bus-factor minimum is 2.
+required-primitives-contract: ^1.0.0
+---
+
+# Static Analysis Integration (SARIF-first)
+
+Maintenance policies for adapters and rulesets live in `maintenance.md` — those are out-of-runtime concerns.
+
+## Constraints
+
+1. Collect and report only — read source and tool output; make no code edits.
+2. Graceful degradation: if no tools are installed, return `status: skip`; absence is never a pipeline failure.
+3. Deduplicate across tools: the same issue reported by multiple tools appears once, attributed to the higher-priority source.
+
+## Tool tiers
+
+### Tier 1 — required baseline (SARIF native)
+
+| Tool | SARIF invocation | Capability |
+|---|---|---|
+| semgrep | `semgrep scan --sarif --config auto` | SAST |
+| gitleaks | `gitleaks detect --report-format sarif --report-path - --no-verify` | secrets |
+| trivy | `trivy config --format sarif --skip-update --offline-scan <path>` + `trivy fs --format sarif --skip-update --offline-scan <path>` | IaC + supply-chain |
+| hadolint | `hadolint --format sarif <Dockerfile>` | IaC (Dockerfile) |
+| actionlint | binary emits JSON; thin adapter maps to SARIF `result` (see `references/tool-configs.md`) | CI/CD |
+| pmd | `pmd check -d . -R <resolved-ruleset> -f sarif --no-progress` — language-conditional: dispatched (and hinted when missing) only when `.java` files are in the target set; detection probes the repo-local `.pmd/` bin before PATH; ruleset resolution in `references/tool-configs.md` | Java code quality |
+| ruff | `ruff check --output-format sarif .` (ruff ≥ 0.3.1) | Python lint + autofix (language-conditional — see step 1) |
+
+### Tier 2 — optional SARIF adapters
+
+Shipped in P2 Step 3b. Not part of the baseline.
+
+### Tier 3 — bespoke JSON adapters
+
+Shipped in P2 Step 3b for tools without upstream SARIF. Each adapter ≤ 40 LOC. A thin adapter normalizes `security-review` agent output into the unified envelope (see `adapters/security-review-adapter.py`). Rule_id lookup is driven by `plugins/dev-team/knowledge/security-review-rule-map.yaml`; malformed categories hard-fail, well-formed-but-unmapped categories fall back to `security-review.*` with a WARN.
+
+mypy (≥ 1.11, `mypy --output json`) normalizes via `adapters/mypy-adapter.py` — rule ids `mypy.python.<error-code>`; on older mypy (no `--output json`) the adapter degrades to a skip-with-warning. Language-conditional like ruff (see step 1). Invocation and field mapping in `references/tool-configs.md`.
+
+### Convention, accessibility, and performance probes (#1979)
+
+Two **additional invocations of tools already in the tiers above** — no new binaries, no new adapters, no network. Each exists to hand review agents a deterministic finding where a lens would otherwise re-derive one by inference, and each is separate from its tool's main lane so the main lane keeps reflecting the project's own gating configuration:
+
+| Probe | Invocation | Displaces |
+|---|---|---|
+| ruff convention | `ruff check --select N,PLR2004 --output-format sarif .` | the mechanical half of `naming-review` (PEP 8 naming, magic values in comparisons) |
+| oxlint frontend | `npx oxlint --jsx-a11y-plugin --react-plugin --react-perf-plugin -D perf --format sarif .` | the mechanical half of `a11y-review`; feeds `performance-review` on the JS/TS side (`no-await-in-loop` is the N+1 shape) |
+
+Both are language-conditional, never `[REQUIRED]`, and never gate — they are context, exactly like the rest of the pre-pass. Invocation details, the measured calibration behind them, and the JS/TS magic-number opt-in are in `references/tool-configs.md`.
+
+**Cross-language performance context.** When the Repowise MCP tools are available, the caller injects `get_health`'s static I/O-in-loop / N+1 findings into the pre-pass context alongside these, rather than having `performance-review` fetch them per dispatch. **Semgrep's registry performance rulesets (`p/performance`) are deliberately NOT used**: resolving a registry pack requires an outbound call to `semgrep.dev`, which would break the offline posture § 1b establishes for this pre-pass — and the pack the spike named does not resolve at all (`--config p/performance` returns HTTP 404, verified on semgrep 1.174.0). Shipping our own performance rules is possible but is a separate piece of work: every rule this repo ships needs passing/failing fixtures under the `semgrep rule fixtures` CI gate. The oxlint `perf` lane covers the JS/TS side offline; anything beyond it stays with the agent.
+
+**lizard** (complexity metrics) normalizes via `adapters/lizard-adapter.py` — rule ids `lizard.complexity.<metric>`; **jscpd** (copy-paste duplication) via `adapters/jscpd-adapter.py` — rule id `jscpd.duplication.clone`. Both are Tier 3 by this file's own taxonomy (bespoke adapter, not SARIF-native), but both are *baseline* capabilities rather than optional extras: they are the deterministic source for the two metric families the review panel would otherwise re-derive by inference on every run — function complexity/size/parameter count, and duplicated blocks (#1974). Neither is language-conditional; lizard covers ~15 languages and jscpd ~150, so both are probed on every target set. Invocation, thresholds, and field mapping in `references/tool-configs.md`.
+
+### Tier 4 — legacy (pre-SARIF)
+
+ESLint / tsc remain callable via native JSON for older flows. Not part of the Step 3a baseline; migrate to SARIF when upstream lands. (The legacy Python entry is retired — ruff replaces it outright as the Tier 1 Python source.)
+
+## Execution flow
+
+### 1. Detect available tools
+
+For each Tier 1 tool, run `command -v <tool>`. Record presence in a tool-map. Missing Tier 1 tools surface as a **warning group** via the install-hint format below — never a pipeline failure.
+
+**Language-conditional tools** (ruff, mypy) are probed and dispatched — and their missing-tool hints surfaced — only when `.py` files are in the target set. A non-Python repo never sees a "ruff missing" or "mypy missing" warning, and language-conditional tools never carry the `[REQUIRED]` prefix.
+
+If no Tier 1 tools are present, return:
+
+```json
+{ "status": "skip", "tools": [], "findings": [], "summary": "No static analysis tools detected." }
+```
+
+### 1b. Offline enforcement (gitleaks, trivy)
+
+These tools default to making network calls; in restricted-egress environments those calls hang or fail and take the pre-pass down with them. Both are pinned to local-only operation so the pre-pass never depends on outbound network access.
+
+**gitleaks** runs with `--no-verify`. Verification (confirming a detected secret is a live credential) is the only outbound call gitleaks makes; disabling it keeps detection fully pattern-based and offline. No preflight needed — the flag is always on.
+
+**trivy** runs with `--skip-update --offline-scan` on both `trivy config` and `trivy fs`. Before dispatching trivy, run the **offline DB preflight** against the local cache (`${TRIVY_CACHE_DIR:-$HOME/.cache/trivy}/db/trivy.db`):
+
+| Local DB state | Action | Warning |
+|---|---|---|
+| absent | skip trivy | `trivy local DB missing — run: trivy image --download-db-only` |
+| mtime age ≤ 7 days | run (fresh) | none |
+| mtime age > 7 days | run anyway | `trivy DB is N days old — consider refreshing with: trivy image --download-db-only` |
+
+`N` is the integer day count. The 7-day boundary is inclusive (exactly 7 days = fresh; strictly greater than 7 days = stale). A missing or stale DB is **never a hard pipeline failure** — it degrades to a skip or a warning, consistent with the graceful-degradation constraint.
+
+### 2. Run available tools in parallel
+
+Dispatch each available tool's invocation. Each returns SARIF on stdout (or via its adapter). Collect SARIF documents keyed by tool name.
+
+**Target walk MUST include CI/CD workflow files** even when they live outside the walked tree (monorepo case — walk up to the repo root to find them). Glob list: [`knowledge/ci-cd-file-scope.md`](../../knowledge/ci-cd-file-scope.md).
+
+Invoke every Tier-1 tool that can process them — actionlint for GitHub Actions, trivy-config for any CI YAML, semgrep with `p/github-actions` (or the bundled `crypto-anti-patterns.yaml` rule that catches `printenv` in workflow `run:` blocks).
+
+Record which CI directories were scanned:
+
+```json
+{ "ci_dirs_scanned": [".github/workflows", ".gitlab-ci.yml"], ... }
+```
+
+If none found, record `"ci_dirs_scanned": []`. The caller can then surface "no CI files in scope" when a CI config would be expected.
+
+### 3. Normalize to unified finding envelope
+
+The shared SARIF parser (`references/sarif-parser.md`) walks each SARIF document's `runs[*].results[*]` and emits one unified finding per result:
+
+| SARIF path | Unified finding field | Notes |
+|---|---|---|
+| `results[*].ruleId` | `rule_id` | Prefixed: `<tool>.<lang?>.<rule>` |
+| `results[*].locations[0].physicalLocation.artifactLocation.uri` | `file` | Repo-relative POSIX |
+| `results[*].locations[0].physicalLocation.region.startLine` | `line` | 1-indexed |
+| `results[*].locations[0].physicalLocation.region.startColumn` | `column` | 1-indexed, optional |
+| `results[*].level` | `severity` | `error`→`error`, `warning`→`warning`, `note`→`suggestion`, `none`/absent→`info` |
+| `results[*].message.text` | `message` | Truncated to 500 chars |
+| `runs[*].tool.driver.rules[ruleIndex].properties.cwe` | `cwe[]` | If present: `["CWE-N"]` |
+| `runs[*].tool.driver.name` | `metadata.source` | e.g. `"semgrep"` |
+| result-level `properties.confidence` | `metadata.confidence` | Default `medium` if absent |
+
+The parser MUST validate each emitted finding against unified-finding-v1 before returning; schema violations fail the run with a named tool + rule id.
+
+### 4. Deduplicate
+
+Two findings are duplicates if they share `file`, `line`, and either (a) identical `rule_id`, or (b) `message` cosine similarity > 0.85 on normalized text. When duplicates exist, keep the higher-priority tool:
+
+```
+semgrep > gitleaks > trivy > hadolint > actionlint > ruff > mypy > oxlint > (legacy ESLint > tsc) > lizard > jscpd
+```
+
+lizard and jscpd rank last deliberately. They report *metric* classes no other tool reports (complexity numbers, clone locations), so a genuine collision is rare; when one does occur, a correctness or security finding at that line should always outrank a metric reading of it.
+
+### 5. Consult ACCEPTED-RISKS.md
+
+If present at repo root, apply suppression per `plugins/dev-team/knowledge/accepted-risks-schema.md`. Suppressed findings are removed from the return value but logged to the audit trail.
+
+### 6. Return structured result
+
+```json
+{
+  "status": "pass|warn|fail",
+  "tools_available": ["semgrep", "hadolint"],
+  "tools_missing": [
+    { "tool": "gitleaks", "install_hint": "gitleaks — secrets detection. install: brew install gitleaks" }
+  ],
+  "findings": [ /* unified finding envelope v1.0 objects */ ],
+  "summary": "12 findings from 2 tools: 3 errors, 7 warnings, 2 suggestions"
+}
+```
+
+`status`: `fail` if any finding has `severity: error`; `warn` if warnings only; `pass` if no findings or no tools available.
+
+## Install-hint format
+
+```
+<tool-name> — <capability-tier>. install: <package-manager> install <name>
+```
+
+Examples:
+
+```
+semgrep — SAST. install: pip install semgrep
+gitleaks — secrets detection. install: brew install gitleaks
+trivy — IaC + supply-chain scanning. install: brew install trivy
+hadolint — Dockerfile linting. install: brew install hadolint
+actionlint — GitHub Actions linting. install: brew install actionlint
+ruff — Python lint + autofix. install: python3 -m pip install ruff (project venv / dev requirements)
+mypy — Python type checking. install: python3 -m pip install mypy (project venv / dev requirements)
+lizard — complexity metrics. install: python3 -m pip install lizard (project venv / dev requirements)
+jscpd — copy-paste duplication detection. install: npm install -g jscpd
+```
+
+Print install-hints grouped by capability tier (secrets / IaC / CI-CD / supply-chain / SAST / data-flow). Required tools carry a `[REQUIRED]` prefix; absence of a required tool is a hard failure at install time, absence of an optional tool is a warning. Tier-implementation labels ("SARIF adapter", "bespoke-JSON adapter", "legacy") are internal vocabulary and never surface in user-facing text.
+
+### Missing-tool remediation convention (#838)
+
+When a command hits a **missing REQUIRED tool**, the remediation must name the
+onboarding command first — the consistent, discoverable one-command entry point
+— and give the raw install hint alongside it:
+
+> Run `/project-init` (or `/setup`) to set up this repo's tooling, or install directly: `<raw install hint>`.
+
+Onboarding ownership: `/project-init` installs the static-analysis lane tools
+(ruff, mypy, oxlint, dotnet-format, PMD) **and** the detection-gated capability
+tools other skills depend on — semgrep, hadolint/trivy/grype, `adr`, `gh`, and
+Playwright + Chromium — per its
+`skills/project-init/references/capability-tools.md` registry. The pointer
+names `/project-init` as the one-command entry point and the tool-specific
+install command stays as the direct fallback. Machine output (e.g.
+semgrep-analyze's `--programmatic` JSON) stays prose-free: the onboarding
+pointer lives only in the human-facing branch.
+
+## Agent context injection
+
+When findings are passed to review agents, format them so agents don't re-report confirmed static findings:
+
+```text
+## Static Analysis Pre-Pass Results
+
+The following issues were detected deterministically by static analysis.
+Do not re-report these issues. Focus on semantic and architectural concerns
+that static analysis cannot detect.
+
+| Tool | Severity | File | Line | Rule | Message |
+|------|----------|------|------|------|---------|
+| semgrep | error | src/api/handler.ts | 42 | javascript.express.audit.xss | Potential XSS |
+| gitleaks | error | .env.example | 3  | generic.aws-access-key | AWS key pattern in committed file |
+```
+
+If no findings: "Static analysis pre-pass ran (tools: <list>). No findings — all clear."
+
+This context goes to **all** review agents, not just security-review.
+
+## Related
+
+- `references/tool-configs.md` — per-tool invocation commands, adapter scripts, install hints; hosts the "Build-time lanes" registry for `/build`'s static self-heal pass
+- `references/language-setup.md` — user-facing per-language setup guide for the build-time self-heal pass and this pre-pass
+- `references/sarif-parser.md` — normalized mapping from SARIF `result` to unified finding envelope v1.0
+- `evals/static-analysis-tools/tier1-mocks/` — tier-1 mocked SARIF fixtures
+- `evals/static-analysis-tools/tier2-integration/` — tier-2 real-binary integration tests (nightly CI)
+- `knowledge/security-primitives-contract.md` — unified finding envelope v1.0
+- `knowledge/accepted-risks-schema.md` — per-project suppression policy
+- `maintenance.md` — adapter and ruleset lifecycle policies

package/skills/static-analysis-integration/adapters/_envelope.py

@@ -0,0 +1,26 @@
+"""Shared helpers for the bespoke finding adapters in this directory.
+
+Adapters are invoked as standalone scripts (`python3 adapters/<x>-adapter.py`),
+so `sys.path[0]` is already this directory and a plain `import _envelope`
+resolves with no path manipulation.
+
+Extracted once the second adapter needed the same path normalization: two
+byte-identical copies of it were exactly the kind of finding the duplication
+lane these adapters serve exists to report.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def rel(path: str) -> str:
+    """Repo-relative POSIX path — unified-finding-v1 forbids absolute paths.
+
+    Relativizes against the current working directory, so adapters must be
+    run from the repo root (as the documented lane invocations are).
+    """
+    text = (path or "").replace("\\", "/")
+    if os.path.isabs(text):
+        text = os.path.relpath(text, os.getcwd()).replace("\\", "/")
+    return text.removeprefix("./")

package/skills/static-analysis-integration/adapters/jscpd-adapter.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""jscpd JSON report (stdin) -> unified-finding envelope v1 JSONL (stdout).
+
+Consumes the report ``jscpd --reporters json --output <dir>`` writes to
+``<dir>/jscpd-report.json`` (the JSON reporter writes a file, never stdout —
+verified against jscpd 5.0.16, so the lane pipes the file in) and emits one
+unified finding per detected clone, anchored at the first occurrence with the
+second named in the message (#1974).
+
+The report's ``fragment`` field carries the duplicated source verbatim. It is
+deliberately NOT copied into the finding: these findings are injected into
+every review agent's prompt, and echoing both copies of every clone back into
+that context is exactly the token cost this lane exists to remove.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from _envelope import rel as _rel
+
+
+def main(stdin=sys.stdin, stdout=sys.stdout, stderr=sys.stderr) -> int:
+    try:
+        report = json.load(stdin)
+    except ValueError:
+        print("WARN: jscpd report is not valid JSON — skipping", file=stderr)
+        return 0
+    for dup in (report.get("duplicates") if isinstance(report, dict) else None) or []:
+        # `duplicates` needs no list check of its own: iterating a dict yields
+        # its KEYS, and this per-item guard rejects those the same way it
+        # rejects any other wrong-shape entry. A wrong shape must degrade to
+        # a skip, never crash — the lane runs `jscpd ... && adapter < report`.
+        if not isinstance(dup, dict):
+            continue
+        first, second = dup.get("firstFile") or {}, dup.get("secondFile") or {}
+        try:
+            line = max(int(first["start"]), 1)
+            end_line = max(int(first.get("end", line)), line)
+            # `.strip()` raises on a null/non-string name, which would
+            # otherwise anchor a schema-VALID finding at the empty path — a
+            # fabricated location, worse than emitting nothing.
+            name = first["name"].strip()
+        except (AttributeError, KeyError, TypeError, ValueError):
+            continue
+        if not name:
+            continue
+        other = _rel(second.get("name") or "unknown")
+        stdout.write(json.dumps({
+            "rule_id": "jscpd.duplication.clone",
+            "file": _rel(name),
+            "line": line,
+            "end_line": end_line,
+            "severity": "warning",
+            "message": (f"Duplicated block of {dup.get('lines', '?')} lines "
+                        f"({dup.get('tokens', '?')} tokens) — also at {other}:"
+                        f"{second.get('start', '?')}-{second.get('end', '?')}")[:500],
+            "metadata": {"source": "jscpd", "confidence": "high",
+                         "duplicate_of": other, "format": dup.get("format")},
+        }, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/static-analysis-integration/adapters/lizard-adapter.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""lizard --csv (stdin) -> unified-finding envelope v1 JSONL (stdout).
+
+Consumes the CSV that ``lizard --csv <paths>`` writes — one row per function
+— and emits one unified finding per *threshold breach*, so the complexity
+numbers reach review agents as deterministic findings instead of being
+re-derived by inference on every run (#1974).
+
+Column order is lizard's own, positional and unheadered (verified against
+lizard 1.24.0)::
+
+    0 nloc  1 ccn  2 token  3 param  4 length  5 location
+    6 file  7 name  8 long_name  9 start_line  10 end_line  [11 ns]
+
+Column 11 appears only with the ``-Ens`` extension and is deliberately
+**unused**. It is lizard's *nested-structure complexity*, not max nesting
+depth (a function with three sequential one-level ``if``s scores 5 while a
+two-level nested one scores 2), it is cumulative so it scales with function
+size, and measured over this repo's own ``hooks/`` + ``scripts/`` tree its
+median is 9 — any threshold low enough to mean "deeply nested" fires on the
+majority of functions. Max nesting depth is not a metric lizard exposes; see
+the lane entry in ``../references/tool-configs.md`` for what covers it
+instead. A row carrying the extra column is still parsed normally.
+
+Do not pass ``--warnings_only``: it overrides ``--csv`` and emits clang-style
+text this adapter cannot read. Thresholds live in ``_CHECKS`` below, each
+calibrated against that same tree so a clean file stays quiet.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+
+from _envelope import rel as _rel
+
+#: (column index, threshold, rule suffix, human label). A finding is emitted
+#: when the measured value is STRICTLY greater than the threshold. Each
+#: threshold sits near the 90th percentile of this repo's own functions
+#: (ccn p90=11, length p95=67, param p99=6), so they flag the tail rather
+#: than the middle: 10.3%, 6.1% and 1.4% of functions respectively.
+_CHECKS = (
+    (1, 10, "cyclomatic", "cyclomatic complexity"),
+    (4, 60, "function-length", "function length in lines"),
+    (3, 5, "parameter-count", "parameter count"))
+
+
+
+
+def main(stdin=sys.stdin, stdout=sys.stdout) -> int:
+    for row in csv.reader(stdin):
+        if len(row) < 11:
+            continue
+        for index, limit, rule, label in _CHECKS:
+            # The `len(row) < 11` guard above already proves every index this
+            # loop reads (1, 3, 4, 9, 10) exists, so the only way a row can
+            # fail here is a non-numeric or empty cell in a malformed row.
+            try:
+                value, start, end = int(row[index]), int(row[9]), int(row[10])
+            except ValueError:
+                continue
+            if value <= limit:
+                continue
+            stdout.write(json.dumps({
+                "rule_id": f"lizard.complexity.{rule}",
+                "file": _rel(row[6]),
+                "line": max(start, 1),
+                "end_line": max(end, start, 1),
+                "severity": "warning",
+                # Truncated like every sibling adapter: `row[7]` is
+                # tool-supplied text and the envelope caps `message` at 500.
+                "message": f"{row[7]}: {label} is {value} (threshold {limit})"[:500],
+                "metadata": {"source": "lizard", "confidence": "high",
+                             "metric": rule, "value": value, "threshold": limit},
+            }, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/static-analysis-integration/adapters/mypy-adapter.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""mypy --output json (stdin) -> unified-finding envelope v1 JSONL (stdout).
+
+Consumes the JSONL that ``mypy --output json`` (mypy >= 1.11, the first
+release with the flag) writes — one JSON object per diagnostic — and emits
+one unified-finding envelope per diagnostic. Older mypy rejects the flag
+with a usage error; when that rejection is piped through this adapter it
+degrades to a skip-with-warning (exit 0, zero findings) — never a pipeline
+failure. Field mapping is documented in the Tier 3 mypy entry of
+``../references/tool-configs.md``.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+_SEVERITY = {"error": "error", "warning": "warning", "note": "suggestion"}
+_FLAG_REJECTION_MARKERS = ("--output", "unrecognized")
+
+
+def main(stdin=sys.stdin, stdout=sys.stdout, stderr=sys.stderr) -> int:
+    for raw in stdin:
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            if any(m in line.lower() for m in _FLAG_REJECTION_MARKERS):
+                warn = "WARN: mypy rejected --output json (needs mypy >= 1.11)"
+                print(warn + " — skipping mypy findings", file=stderr)
+                return 0
+            continue
+        finding = {
+            "rule_id": "mypy.python." + (entry.get("code") or "note"),
+            "file": entry["file"],
+            "line": max(int(entry["line"]), 1),
+            "severity": _SEVERITY.get(entry.get("severity"), "info"),
+            "message": entry["message"][:500],
+            "metadata": {"source": "mypy", "confidence": "high"},
+        }
+        if isinstance(entry.get("column"), int) and entry["column"] >= 1:
+            finding["column"] = entry["column"]
+        stdout.write(json.dumps(finding, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/static-analysis-integration/adapters/mypy-src-layout.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Detect a plain src/-layout Python project and emit the mypy flags it needs.
+
+mypy fails outright on a common, unremarkable layout — a ``src/`` directory
+holding modules with no ``__init__.py``, and no project-level mypy
+package-base configuration (``mypy_path`` / ``explicit_package_bases`` / a
+``pyproject.toml`` ``[tool.mypy]`` section). The moment any other checked
+file imports one of those modules via its dotted ``src.`` path (a root-level
+entry point, a test, ...), mypy resolves the same file two different ways
+and refuses to proceed:
+
+    Source file found twice under different module names: "calc" and "src.calc"
+
+mypy >= 0.990 accepts ``--explicit-package-bases`` to resolve this without
+requiring ``__init__.py`` files or hand-written config. This script detects
+the layout and prints the extra flag(s) to pass (empty when not applicable)
+so the caller can splice them into the mypy invocation documented in
+``../references/tool-configs.md``:
+
+    mypy $(python3 adapters/mypy-src-layout.py .) --output json .
+
+Detection deliberately never overrides a project that already owns its mypy
+config — "bind, don't replace" (see static-self-heal.md's provider-binding
+rule): if any recognized mypy config file/section is present, this reports
+no src-layout regardless of what src/ contains.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# name -> marker string that must appear in the file for it to count as a
+# mypy package-base config; None means the file's mere presence counts.
+_CONFIG_MARKERS = {
+    "mypy.ini": None,
+    ".mypy.ini": None,
+    "setup.cfg": "[mypy]",
+    "tox.ini": "[mypy]",
+    "pyproject.toml": "[tool.mypy]",
+}
+
+
+def _has_mypy_config(root: Path) -> bool:
+    for name, marker in _CONFIG_MARKERS.items():
+        path = root / name
+        if not path.is_file():
+            continue
+        if marker is None:
+            return True
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        if marker in text:
+            return True
+    return False
+
+
+def _src_has_modules_without_init(src: Path) -> bool:
+    has_module = False
+    for path in src.rglob("*.py"):
+        if path.name == "__init__.py":
+            return False
+        has_module = True
+    return has_module
+
+
+def is_src_layout(root: Path) -> bool:
+    """True when `root` needs `--explicit-package-bases` to resolve mypy's
+    src/-layout module-naming ambiguity, and nothing in the project already
+    tells mypy how to resolve it."""
+    src = root / "src"
+    if not src.is_dir():
+        return False
+    if not _src_has_modules_without_init(src):
+        return False
+    return not _has_mypy_config(root)
+
+
+def extra_args(root: Path) -> list:
+    return ["--explicit-package-bases"] if is_src_layout(root) else []
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    root = Path(argv[0]) if argv else Path(".")
+    print(" ".join(extra_args(root)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())