[P0][phase:b] Detect package root / entry points before analysis (kills ~36% of out-of-box FPs) #114

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). Per ADR 0008 § Triage trigger, new observations open issues that compete with existing Phase B/C tickets on equal footing.

Problem

When fallow-py is run with no [tool.fallow_py] config (the first-run experience), it walks the entire repo tree — including docs/, docs_src/, .github/, sandbox/, examples/, setup.py, and requirements/ — and reports findings in all of them.

This is the single largest source of out-of-the-box false positives: 57 of 157 sampled FPs (36%).

Evidence (real repos, no config)

pydantic: findings in .github/actions/people/people.py (a GitHub Action helper — flagged requests as a missing dependency and its functions as unused-symbol)
fastapi: dozens of unused-module / unused-symbol on docs_src/** tutorial files
requests / flask: setup.py flagged as an unused module and setuptools as a missing dependency
django-oscar: sandbox/** demo deployment flagged throughout

Proposed fix

Detect the actual package root before analysis instead of walking the whole tree:

Honor [tool.fallow_py] roots/entry when present (already supported) — but also
Infer a sensible default package root when config is absent: prefer src/<pkg>/ (src-layout), else the top-level dir(s) containing __init__.py, and exclude well-known non-package trees (docs, examples, .github, scripts, benchmarks, tests for non-test rules, setup.py, requirements/) by default.
Make the exclusion list configurable.

Acceptance criteria

Running fallow-py analyze with no config on requests / flask / pydantic no longer reports findings in docs/, .github/, setup.py, examples/.
A benchmarks/fp-cases/non-package-tree/ fixture is added and passes.
The 2026-06-15 audit's non-package-tree FP cluster (57 findings) is re-run and shows a large reduction.

Priority

P0. Highest-leverage single fix — eliminates ~36% of out-of-box FPs. Without it, every library/app user's first run is dominated by noise from trees that are not the shipped package.

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`). Per ADR 0008 § Triage trigger, new observations open issues that compete with existing Phase B/C tickets on equal footing. ## Problem When `fallow-py` is run with **no `[tool.fallow_py]` config** (the first-run experience), it walks the entire repo tree — including `docs/`, `docs_src/`, `.github/`, `sandbox/`, `examples/`, `setup.py`, and `requirements/` — and reports findings in all of them. This is the **single largest source of out-of-the-box false positives: 57 of 157 sampled FPs (36%)**. ### Evidence (real repos, no config) - `pydantic`: findings in `.github/actions/people/people.py` (a GitHub Action helper — flagged `requests` as a missing dependency and its functions as unused-symbol) - `fastapi`: dozens of `unused-module` / `unused-symbol` on `docs_src/**` tutorial files - `requests` / `flask`: `setup.py` flagged as an unused module and `setuptools` as a missing dependency - `django-oscar`: `sandbox/**` demo deployment flagged throughout ## Proposed fix Detect the actual package root before analysis instead of walking the whole tree: 1. Honor `[tool.fallow_py]` `roots`/`entry` when present (already supported) — but also 2. **Infer a sensible default package root when config is absent**: prefer `src/<pkg>/` (src-layout), else the top-level dir(s) containing `__init__.py`, and exclude well-known non-package trees (`docs`, `examples`, `.github`, `scripts`, `benchmarks`, `tests` for non-test rules, `setup.py`, `requirements/`) by default. 3. Make the exclusion list configurable. ## Acceptance criteria - Running `fallow-py analyze` with no config on `requests` / `flask` / `pydantic` no longer reports findings in `docs/`, `.github/`, `setup.py`, `examples/`. - A `benchmarks/fp-cases/non-package-tree/` fixture is added and passes. - The 2026-06-15 audit's non-package-tree FP cluster (57 findings) is re-run and shows a large reduction. ## Priority **P0.** Highest-leverage single fix — eliminates ~36% of out-of-box FPs. Without it, every library/app user's first run is dominated by noise from trees that are not the shipped package. --- *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 no-config discovery inside package trees