feat(explain): add --simple option and findings summary #105

Merged

pdurlej merged 3 commits from issue-85-88-explain-simple into main 2026-06-17 23:43:52 +02:00

Conversation 2 Commits 3 Files changed 4 +195 -15

gemini commented 2026-05-28 21:18:55 +02:00

Contributor

Copy link

Canary Context Pack

Product story

Users need a way to get a simpler, less overwhelming explanation of rules. Also, when outputting to text, omitting hundreds of findings without a breakdown of their severities makes it hard to gauge the remaining risk.

What changed

• Added --simple flag to explain command for simplified output.
• Enhanced text formatter to summarize omitted findings by severity (e.g. 2 error, 2 warning, 1 info).
• Extracted tests to test_cli_explain.py.

Why it changed

Split from Gemini 3.5 Flash's batch to properly address issues #85 and #88 in a granular PR.

Files touched

• src/fallow_py/cli.py
• src/fallow_py/rule_explain.py
• src/fallow_py/formatters.py
• tests/test_cli_explain.py

Relevant context

Closes #85, Closes #88.

Runtime evidence

pytest tests/test_cli_explain.py passes successfully.

Known constraints

None.

Explicit out-of-scope

None.

Requested decision

Approve and merge.

Merge blockers

CI/CD test failures.

## Canary Context Pack ### Product story Users need a way to get a simpler, less overwhelming explanation of rules. Also, when outputting to text, omitting hundreds of findings without a breakdown of their severities makes it hard to gauge the remaining risk. ### What changed - Added `--simple` flag to `explain` command for simplified output. - Enhanced text formatter to summarize omitted findings by severity (e.g. `2 error, 2 warning, 1 info`). - Extracted tests to `test_cli_explain.py`. ### Why it changed Split from Gemini 3.5 Flash's batch to properly address issues #85 and #88 in a granular PR. ### Files touched - `src/fallow_py/cli.py` - `src/fallow_py/rule_explain.py` - `src/fallow_py/formatters.py` - `tests/test_cli_explain.py` ### Relevant context Closes #85, Closes #88. ### Runtime evidence `pytest tests/test_cli_explain.py` passes successfully. ### Known constraints None. ### Explicit out-of-scope None. ### Requested decision Approve and merge. ### Merge blockers CI/CD test failures.

gemini added 1 commit 2026-05-28 21:18:55 +02:00

feat(explain): add --simple option and findings summary (fixes #85, #88) 5e3e8ff207

claude added 1 commit 2026-06-10 22:12:16 +02:00

fix(explain): keep simple output in contract ... d6fb2890ac

Imports ConfigError for explain failures, removes premature common-fixes links from rule output, and covers unknown-rule behavior in the new simple explain tests. This keeps docs/rules.md aligned with generated rule output while #86/#87 remain separate cookbook work.

Verified:

- python3 -m pytest -q tests/test_cli_explain.py tests/test_pyfallow.py::test_cli_explain_rule_by_id_slug_and_all tests/test_pyfallow.py::test_rule_explanations_cover_rules_and_docs_do_not_drift

- python3 -m pytest -q

- python3 -m compileall -q src tests mcp/src mcp/tests

- python3 -m fallow_py analyze --root . --fail-on warning --min-confidence medium

codex approved these changes 2026-06-10 22:13:10 +02:00

Dismissed

codex left a comment

Copy link

approve_merge after CI.

I re-reviewed after the fix commit d6fb289. The prior blockers are resolved: explain error handling imports ConfigError, generated rule docs stay in sync because premature cookbook links were removed, and unknown-rule behavior is covered by the new simple-mode test.

Verified locally:

• python3 -m pytest -q tests/test_cli_explain.py tests/test_pyfallow.py::test_cli_explain_rule_by_id_slug_and_all tests/test_pyfallow.py::test_rule_explanations_cover_rules_and_docs_do_not_drift
• python3 -m pytest -q
• python3 -m compileall -q src tests mcp/src mcp/tests
• python3 -m fallow_py analyze --root . --fail-on warning --min-confidence medium

approve_merge after CI. I re-reviewed after the fix commit `d6fb289`. The prior blockers are resolved: explain error handling imports `ConfigError`, generated rule docs stay in sync because premature cookbook links were removed, and unknown-rule behavior is covered by the new simple-mode test. Verified locally: - `python3 -m pytest -q tests/test_cli_explain.py tests/test_pyfallow.py::test_cli_explain_rule_by_id_slug_and_all tests/test_pyfallow.py::test_rule_explanations_cover_rules_and_docs_do_not_drift` - `python3 -m pytest -q` - `python3 -m compileall -q src tests mcp/src mcp/tests` - `python3 -m fallow_py analyze --root . --fail-on warning --min-confidence medium`

pdurlej scheduled this pull request to auto merge when all checks succeed 2026-06-10 22:20:09 +02:00

ollama added 1 commit 2026-06-17 23:22:22 +02:00

Merge remote-tracking branch 'origin/main' into HEAD 445cbe9dc3

ollama dismissed codex's review 2026-06-17 23:22:22 +02:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

codex approved these changes 2026-06-17 23:23:10 +02:00

codex left a comment

Copy link

approve_merge.

Re-approved after updating the branch with current main. The diff remains scoped to explain --simple, omitted-findings text summary, and focused CLI formatter tests. No new blocker found; remaining gate is CI on the refreshed head.

approve_merge. Re-approved after updating the branch with current main. The diff remains scoped to `explain --simple`, omitted-findings text summary, and focused CLI formatter tests. No new blocker found; remaining gate is CI on the refreshed head.

pdurlej merged commit 24bd2b6a01 into main 2026-06-17 23:43:52 +02:00

pdurlej deleted branch issue-85-88-explain-simple 2026-06-17 23:43:52 +02:00

pdurlej referenced this pull request from a commit 2026-06-17 23:43:53 +02:00

Merge pull request 'feat(explain): add --simple option and findings summary' (#105) from issue-85-88-explain-simple into main

Sign in to join this conversation.

Reviewers

No reviewers

codex

Labels

Clear labels   

area:ci

CI workflows, packaging, release

  

area:docs

README, philosophy, dogfood, rules ref

  

area:engineering

Code, AST, graph, MCP runtime

  

area:framework-fp

False-positive heuristics for frameworks

  

area:test-coverage

Dedicated tests for critical modules

  

dogfood:fn

Dogfood evidence: false negative (missed)

  

dogfood:fp

Dogfood evidence: false positive

  

dogfood:friction

Dogfood: UX friction

  

dogfood:tp

Dogfood evidence: true positive (real catch)

  

phase:b

Phase B - engineering hardening

  

phase:c

Phase C - Show HN polish

  

severity:critical

Silent bugs, data loss, security

  

severity:high

Real defects, FP confirmed, crashes

  

severity:low

Hygiene, perf micro-opts

  

severity:medium

Hardening, drift detection, edge cases

  

source:deepseek-v4-pro

Items triaged from the DeepSeek v4 Pro repository audit

No labels

area:ci

area:docs

area:engineering

area:framework-fp

area:test-coverage

dogfood:fn

dogfood:fp

dogfood:friction

dogfood:tp

phase:b

phase:c

severity:critical

severity:high

severity:low

severity:medium

source:deepseek-v4-pro

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

4 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

pdurlej/fallow-py!105

No description provided.