scilintr (Python)

AST-based linter for hidden scientific commitments in Python data-analysis code. Sibling of r/scilintr/ (R code) and tex/scitexlintr/ (LaTeX reports); same waiver mechanism (# ANALYSIS_OK[category]: explanation, % ANALYSIS_OK[...]: for the TeX linter), same agent-first design philosophy (high recall over precision).

Rules

Each rule has a kebab-case code that names the failure mode. Rules currently implemented:

Opt-in rules

Higher-false-positive rules run only when named in --enable (added on top of the default rules) or --rules / rules= (exactly the listed rules):

scilintr --enable return-none-on-empty-input src/

See ../../analysis_lint_strategy.md for the design rationale and ../../docs/failure-modes.md for the bugs each rule catches.

Install / use

pip install scilintr        # from PyPI

# lint a file or directory
scilintr path/to/analysis/
scilintr --rules broad-exception,unchecked-merge path/to/file.py
scilintr --no-waivers path/to/file.py     # audit mode: ignore ANALYSIS_OK
scilintr --summary path/to/dir/           # per-rule counts only

Exit code is 1 if any findings are produced, 0 otherwise.

API

from scilintr import lint_code, lint_paths, Finding

findings = lint_code(source_string, filename="foo.py")
findings = lint_paths(["path/to/dir/", "path/to/file.py"])

# Restrict to a subset of rules
findings = lint_code(src, rules=["broad-exception", "unchecked-merge"])

# Audit mode — surface waivered findings too
findings = lint_code(src, respect_waivers=False)

Finding is a frozen dataclass: rule, line, col, message, severity ("hard-fail" | "structured-comment" | "warning"), filename.

Waivers

A finding can be suppressed by a structured comment on (or up to four lines before) the offending line:

# ANALYSIS_OK[api-retry]: external API requires bare Exception
try:
    response = client.fetch()
except Exception:
    retry()

The square-bracket category is required and free-form ([\w-]+). The colon-and-explanation is required and must be non-empty — the structure exists to force a reviewable statement, not to wave off arbitrary code.

Development

cd py/scilintr
pip install -e ".[dev]"
pytest                              # full suite
pytest tests/test_broad_exception.py    # iterate on one rule

Each rule has three tests:

• test_<rule>_flags_bad_code — bad code produces ≥1 finding for the rule
• test_<rule>_passes_good_code — equivalent good code produces zero findings
• test_<rule>_respects_waiver — # ANALYSIS_OK[<category>]: suppresses

The waiver test only becomes meaningful once the rule detects the pattern; before then it passes vacuously. That's the natural TDD inflection inside each rule: implement detection → bad-code test passes → add waiver suppression → all three pass.