[P0][phase:b] Guarded imports (TYPE_CHECKING / try-except) must not be blocking missing-runtime-dependency #115

New issue

Open

opened 2026-06-15 22:56:48 +02:00 by claude · 0 comments

claude commented

2026-06-15 22:56:48 +02:00

Collaborator

Source: evidence-derived from the 2026-06-15 real-world precision audit (docs/dogfood/real-world-precision-2026-06-15.md).

Problem

fallow-py flags imports that are guarded by if TYPE_CHECKING: or try/except ImportError: as missing-runtime-dependency — the only blocking/error-severity rule. This means a first-time CI integration fails the build on type-only and optional imports.

This is the most damaging defect found, because it is blocking. missing-runtime-dependency measured 3% precision (29 of 30 sampled findings were false positives).

Evidence (real repos, no config)

celery/app/base.py: if typing.TYPE_CHECKING: from pydantic import BaseModel → flagged as a blocking missing dependency (the import never runs)
flask/config.py: if t.TYPE_CHECKING: import typing_extensions as te → blocking error
click/_winconsole.py: if t.TYPE_CHECKING: ... from typing_extensions import Buffer → blocking error
celery/backends/arangodb.py: try: from pyArango import ... except ImportError: (handled optional driver) → flagged missing
requests/__init__.py, httpx/_transports/asgi.py: try/except ImportError optional imports → flagged missing
celery: _patch_eventlet() / _patch_gevent() function-local optional-backend imports → flagged missing

The analyzer already records evidence.guarded: true for several of these, yet still emits them at error severity.

Proposed fix

TYPE_CHECKING-guarded imports are never runtime dependencies — exclude them from missing-runtime-dependency entirely (at most an info note).
try/except ImportError-guarded imports are optional — do not emit blocking; at most decision_needed.
Respect the existing evidence.guarded signal: a guarded import must never be blocking.

Acceptance criteria

No TYPE_CHECKING-guarded or try/except ImportError-guarded import is ever reported at blocking/error severity.
benchmarks/fp-cases/type-checking-guarded-import/ fixture added and passes.
Re-running the audit shows missing-runtime-dependency precision rising substantially from the 3% baseline.

Priority

P0. This is the adoption-breaker — it is the difference between "noisy" and "actively fails first-time CI." Fix first regardless of volume rank.

Opened by claude (Opus 4.8) from the 2026-06-15 precision audit. Audit PR: #113.

**Source:** evidence-derived from the 2026-06-15 real-world precision audit (`docs/dogfood/real-world-precision-2026-06-15.md`). ## Problem `fallow-py` flags imports that are guarded by `if TYPE_CHECKING:` or `try/except ImportError:` as **`missing-runtime-dependency`** — the only `blocking`/error-severity rule. This means a first-time CI integration **fails the build on type-only and optional imports**. This is the **most damaging defect found**, because it is `blocking`. `missing-runtime-dependency` measured **3% precision** (29 of 30 sampled findings were false positives). ### Evidence (real repos, no config) - `celery/app/base.py`: `if typing.TYPE_CHECKING: from pydantic import BaseModel` → flagged as a blocking missing dependency (the import never runs) - `flask/config.py`: `if t.TYPE_CHECKING: import typing_extensions as te` → blocking error - `click/_winconsole.py`: `if t.TYPE_CHECKING: ... from typing_extensions import Buffer` → blocking error - `celery/backends/arangodb.py`: `try: from pyArango import ... except ImportError:` (handled optional driver) → flagged missing - `requests/__init__.py`, `httpx/_transports/asgi.py`: `try/except ImportError` optional imports → flagged missing - `celery`: `_patch_eventlet()` / `_patch_gevent()` function-local optional-backend imports → flagged missing The analyzer already records `evidence.guarded: true` for several of these, yet still emits them at `error` severity. ## Proposed fix 1. **`TYPE_CHECKING`-guarded imports are never runtime dependencies** — exclude them from `missing-runtime-dependency` entirely (at most an `info` note). 2. **`try/except ImportError`-guarded imports are optional** — do not emit `blocking`; at most `decision_needed`. 3. Respect the existing `evidence.guarded` signal: a guarded import must never be `blocking`. ## Acceptance criteria - No `TYPE_CHECKING`-guarded or `try/except ImportError`-guarded import is ever reported at `blocking`/error severity. - `benchmarks/fp-cases/type-checking-guarded-import/` fixture added and passes. - Re-running the audit shows `missing-runtime-dependency` precision rising substantially from the 3% baseline. ## Priority **P0.** This is the adoption-breaker — it is the difference between "noisy" and "actively fails first-time CI." Fix first regardless of volume rank. --- *Opened by `claude` (Opus 4.8) from the 2026-06-15 precision audit. Audit PR: #113.*

claude added the

phase:b

label

2026-06-15 22:56:48 +02:00

claude referenced this issue from a commit

2026-06-17 23:09:21 +02:00

fix: keep guarded imports out of runtime blockers