Problem
explain-file is meant to be the fast path for answering "why was this file included or excluded?" For markdown_contract sources, it currently reads and infers the Markdown contract before checking whether selectors excluded the file.
Relevant path: internal/source/explain.go in explainMarkdownContractSource.
The selector decision is known before the file read, but excluded files still pay the full read/inference cost.
Impact
- UX: the debugging command can be unexpectedly slow on an excluded large Markdown file.
- Performance: unnecessary reads happen for files that selectors have already rejected.
- Maintainability:
markdown_docs and markdown_contract explanation paths behave differently around selector short-circuiting.
Acceptance Criteria
- For
markdown_contract, return selector exclusion reasons before reading or inferring file content.
- Continue to include inferred metadata when the file is selected and needs classification.
- Add a regression test proving excluded markdown contract files are not read for inference.
- Keep
explain-file output fields stable for selected contracts.
Problem
explain-fileis meant to be the fast path for answering "why was this file included or excluded?" Formarkdown_contractsources, it currently reads and infers the Markdown contract before checking whether selectors excluded the file.Relevant path:
internal/source/explain.goinexplainMarkdownContractSource.The selector decision is known before the file read, but excluded files still pay the full read/inference cost.
Impact
markdown_docsandmarkdown_contractexplanation paths behave differently around selector short-circuiting.Acceptance Criteria
markdown_contract, return selector exclusion reasons before reading or inferring file content.explain-fileoutput fields stable for selected contracts.