pyclichecker 2.4.2__tar.gz → 2.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. pyclichecker-2.5.0/.github/dependabot.yml +28 -0
  2. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/.github/workflows/ci.yml +35 -5
  3. pyclichecker-2.5.0/.github/workflows/publish.yml +167 -0
  4. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/AGENTS.md +21 -0
  5. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/CHANGELOG.md +38 -0
  6. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/CONTRIBUTING.md +14 -2
  7. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/PKG-INFO +109 -15
  8. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/README.md +104 -12
  9. pyclichecker-2.5.0/docs/flow-analysis.md +80 -0
  10. pyclichecker-2.5.0/docs/review-coverage.md +99 -0
  11. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/pyproject.toml +37 -4
  12. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/pyproject.toml.orig +31 -4
  13. pyclichecker-2.5.0/skills/pyclichecker/SKILL.md +97 -0
  14. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/__init__.py +2 -1
  15. pyclichecker-2.5.0/src/pyclichecker/baseline.py +56 -0
  16. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/cli.py +45 -4
  17. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/diagnostics.py +68 -0
  18. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/discovery.py +8 -2
  19. pyclichecker-2.5.0/src/pyclichecker/rules.py +9216 -0
  20. pyclichecker-2.5.0/tests/corpus/README.md +31 -0
  21. pyclichecker-2.5.0/tests/corpus/SLP003/positive.py.fixture +5 -0
  22. pyclichecker-2.5.0/tests/corpus/SLP009/corrected.py.fixture +11 -0
  23. pyclichecker-2.5.0/tests/corpus/SLP015/positive.py.fixture +7 -0
  24. pyclichecker-2.5.0/tests/corpus/SLP018/corrected.py.fixture +7 -0
  25. pyclichecker-2.5.0/tests/corpus/SLP018/false_positive.py.fixture +7 -0
  26. pyclichecker-2.5.0/tests/corpus/SLP018/positive.py.fixture +5 -0
  27. pyclichecker-2.5.0/tests/corpus/SLP019/corrected.py.fixture +8 -0
  28. pyclichecker-2.5.0/tests/corpus/SLP019/false_positive.py.fixture +7 -0
  29. pyclichecker-2.5.0/tests/corpus/SLP019/positive.py.fixture +8 -0
  30. pyclichecker-2.5.0/tests/corpus/comparison/ruff_none_comparison.py.fixture +2 -0
  31. pyclichecker-2.5.0/tests/corpus/comparison/type_error.py.fixture +2 -0
  32. pyclichecker-2.5.0/tests/corpus/manifest.json +156 -0
  33. pyclichecker-2.5.0/tests/corpus_runner.py +175 -0
  34. pyclichecker-2.5.0/tests/test_corpus.py +44 -0
  35. pyclichecker-2.5.0/tests/test_features.py +315 -0
  36. pyclichecker-2.5.0/tests/test_pyclichecker.py +7020 -0
  37. pyclichecker-2.5.0/uv.lock +1061 -0
  38. pyclichecker-2.4.2/.github/workflows/publish.yml +0 -83
  39. pyclichecker-2.4.2/skills/pyclichecker/SKILL.md +0 -68
  40. pyclichecker-2.4.2/src/pyclichecker/rules.py +0 -2286
  41. pyclichecker-2.4.2/tests/test_pyclichecker.py +0 -1266
  42. pyclichecker-2.4.2/uv.lock +0 -43
  43. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/LICENSE +0 -0
  44. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/skills/pyclichecker/agents/openai.yaml +0 -0
  45. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/__main__.py +0 -0
  46. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/_version.py +0 -0
  47. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/config.py +0 -0
  48. {pyclichecker-2.4.2 → pyclichecker-2.5.0}/tests/__init__.py +0 -0
@@ -0,0 +1,28 @@
1
+ version: 2
2
+
3
+ updates:
4
+ - package-ecosystem: "uv"
5
+ directory: "/"
6
+ schedule:
7
+ interval: "weekly"
8
+ day: "monday"
9
+ time: "08:00"
10
+ timezone: "Europe/Luxembourg"
11
+ open-pull-requests-limit: 3
12
+ groups:
13
+ python-dependencies:
14
+ patterns:
15
+ - "*"
16
+
17
+ - package-ecosystem: "github-actions"
18
+ directory: "/"
19
+ schedule:
20
+ interval: "weekly"
21
+ day: "monday"
22
+ time: "08:00"
23
+ timezone: "Europe/Luxembourg"
24
+ open-pull-requests-limit: 3
25
+ groups:
26
+ workflow-actions:
27
+ patterns:
28
+ - "*"
@@ -24,9 +24,11 @@ jobs:
24
24
  steps:
25
25
  - name: Check out repository
26
26
  uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
27
+ with:
28
+ persist-credentials: false
27
29
 
28
30
  - name: Set up uv and Python
29
- uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
31
+ uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
30
32
  with:
31
33
  version: "0.12.5"
32
34
  python-version: "3.14"
@@ -35,14 +37,29 @@ jobs:
35
37
  - name: Install locked development environment
36
38
  run: uv sync --locked
37
39
 
38
- - name: Run unit tests
39
- run: uv run python -m unittest discover -v
40
+ - name: Run unit tests with branch coverage
41
+ run: |
42
+ uv run coverage erase
43
+ uv run coverage run -m unittest discover -v
44
+ uv run coverage report
45
+
46
+ - name: Run differential corpus
47
+ run: uv run python -m tests.corpus_runner
40
48
 
41
49
  - name: Run Ruff
42
50
  run: |
43
51
  uv run ruff check .
44
52
  uv run ruff format --check .
45
53
 
54
+ - name: Run strict type checking
55
+ run: uv run mypy
56
+
57
+ - name: Run security checks
58
+ run: |
59
+ uv run bandit -q -r src
60
+ uv export --quiet --locked --all-groups --no-emit-project --format requirements.txt --output-file .audit-requirements.txt
61
+ uv run pip-audit --strict --requirement .audit-requirements.txt
62
+
46
63
  - name: Run pyclichecker on itself
47
64
  run: uv run pyclichecker src tests
48
65
 
@@ -63,6 +80,19 @@ jobs:
63
80
  print(f"path={wheels[0].as_posix()}", file=output)
64
81
 
65
82
  - name: Smoke-test built wheel
83
+ shell: python
84
+ env:
85
+ WHEEL_PATH: ${{ steps.wheel.outputs.path }}
66
86
  run: |
67
- uvx --from "${{ steps.wheel.outputs.path }}" pyclichecker --version
68
- uvx --from "${{ steps.wheel.outputs.path }}" pyclichecker src tests
87
+ import os
88
+ import subprocess
89
+
90
+ wheel = os.environ["WHEEL_PATH"]
91
+ subprocess.run(
92
+ ["uvx", "--from", wheel, "pyclichecker", "--version"],
93
+ check=True,
94
+ )
95
+ subprocess.run(
96
+ ["uvx", "--from", wheel, "pyclichecker", "src", "tests"],
97
+ check=True,
98
+ )
@@ -0,0 +1,167 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ concurrency:
11
+ group: publish-${{ github.event.release.tag_name }}
12
+ cancel-in-progress: false
13
+
14
+ jobs:
15
+ build:
16
+ name: Build and verify
17
+ if: github.event.release.prerelease == false
18
+ runs-on: ubuntu-latest
19
+ timeout-minutes: 10
20
+
21
+ steps:
22
+ - name: Check out repository
23
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
24
+ with:
25
+ persist-credentials: false
26
+
27
+ - name: Set up uv and Python
28
+ uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
29
+ with:
30
+ version: "0.12.5"
31
+ python-version: "3.14"
32
+ enable-cache: false
33
+
34
+ - name: Install locked development environment
35
+ run: uv sync --locked
36
+
37
+ - name: Verify release tag
38
+ env:
39
+ RELEASE_TAG: ${{ github.event.release.tag_name }}
40
+ run: |
41
+ project_version="$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
42
+ test "$RELEASE_TAG" = "v$project_version"
43
+
44
+ - name: Run quality gates
45
+ run: |
46
+ uv run coverage erase
47
+ uv run coverage run -m unittest discover -v
48
+ uv run coverage report
49
+ uv run python -m tests.corpus_runner
50
+ uv run ruff check .
51
+ uv run ruff format --check .
52
+ uv run mypy
53
+ uv run bandit -q -r src
54
+ uv export --quiet --locked --all-groups --no-emit-project --format requirements.txt --output-file .audit-requirements.txt
55
+ uv run pip-audit --strict --requirement .audit-requirements.txt
56
+ uv run pyclichecker src tests
57
+
58
+ - name: Build distributions
59
+ run: uv build
60
+
61
+ - name: Inspect archives
62
+ run: |
63
+ for archive in dist/*.whl; do
64
+ uv run python -m zipfile -l "$archive"
65
+ done
66
+ for archive in dist/*.tar.gz; do
67
+ tar -tzf "$archive"
68
+ done
69
+
70
+ - name: Smoke-test built wheel
71
+ run: |
72
+ repo_root="$PWD"
73
+ wheel="$repo_root/dist/pyclichecker-${RELEASE_TAG#v}-py3-none-any.whl"
74
+ scratch="$(mktemp -d)"
75
+ cd "$scratch"
76
+ uvx --from "$wheel" pyclichecker --version
77
+ uvx --from "$wheel" pyclichecker --list-rules
78
+ uvx --from "$wheel" pyclichecker "$repo_root/src" "$repo_root/tests"
79
+ env:
80
+ RELEASE_TAG: ${{ github.event.release.tag_name }}
81
+
82
+ - name: Upload distributions
83
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
84
+ with:
85
+ name: distributions
86
+ path: dist/
87
+ if-no-files-found: error
88
+ retention-days: 1
89
+
90
+ publish:
91
+ name: Publish
92
+ if: github.event.release.prerelease == false
93
+ needs: build
94
+ runs-on: ubuntu-latest
95
+ timeout-minutes: 5
96
+ environment:
97
+ name: pypi
98
+ url: https://pypi.org/p/pyclichecker
99
+ permissions:
100
+ id-token: write
101
+
102
+ steps:
103
+ - name: Download distributions
104
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
105
+ with:
106
+ name: distributions
107
+ path: dist/
108
+
109
+ - name: Set up uv
110
+ uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
111
+ with:
112
+ version: "0.12.5"
113
+ enable-cache: false
114
+
115
+ - name: Publish distributions
116
+ run: >-
117
+ uv publish
118
+ --trusted-publishing always
119
+ --check-url https://pypi.org/simple
120
+
121
+ verify-index:
122
+ name: Verify public installation
123
+ if: github.event.release.prerelease == false
124
+ needs: publish
125
+ runs-on: ubuntu-latest
126
+ timeout-minutes: 5
127
+
128
+ steps:
129
+ - name: Set up uv and Python
130
+ uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
131
+ with:
132
+ version: "0.12.5"
133
+ python-version: "3.14"
134
+ enable-cache: false
135
+
136
+ - name: Verify no-cache installation from PyPI
137
+ env:
138
+ RELEASE_TAG: ${{ github.event.release.tag_name }}
139
+ run: |
140
+ version="${RELEASE_TAG#v}"
141
+ expected="pyclichecker $version"
142
+ for attempt in 1 2 3 4 5; do
143
+ if output="$(
144
+ uvx \
145
+ --no-cache \
146
+ --python 3.14 \
147
+ --default-index https://pypi.org/simple \
148
+ --from "pyclichecker==$version" \
149
+ pyclichecker --version 2>&1
150
+ )"; then
151
+ printf '%s\n' "$output"
152
+ if printf '%s\n' "$output" | grep -Fx "$expected"; then
153
+ uvx \
154
+ --no-cache \
155
+ --python 3.14 \
156
+ --default-index https://pypi.org/simple \
157
+ --from "pyclichecker==$version" \
158
+ pyclichecker --list-rules
159
+ exit 0
160
+ fi
161
+ else
162
+ printf '%s\n' "$output"
163
+ fi
164
+ sleep 10
165
+ done
166
+ echo "PyPI did not serve $expected after 5 attempts" >&2
167
+ exit 1
@@ -54,11 +54,32 @@ Every changed rule MUST have:
54
54
  - A corrected example that does not report it.
55
55
  - False-positive coverage for aliases, shadowing, delegation, test fixtures, or suppressions when relevant.
56
56
 
57
+ ### Differential corpus
58
+
59
+ ```bash
60
+ uv run python -m tests.corpus_runner
61
+ ```
62
+
63
+ This gate MUST match the checked-in expectations for pyclichecker, Ruff,
64
+ Pyright, and ty.
65
+
57
66
  ### Static checks
58
67
 
59
68
  ```bash
60
69
  uv run ruff check .
61
70
  uv run ruff format --check .
71
+ uv run mypy
72
+ ```
73
+
74
+ ### Coverage and security
75
+
76
+ ```bash
77
+ uv run coverage erase
78
+ uv run coverage run -m unittest discover -v
79
+ uv run coverage report
80
+ uv run bandit -q -r src
81
+ uv export --quiet --locked --all-groups --no-emit-project --format requirements.txt --output-file .audit-requirements.txt
82
+ uv run pip-audit --strict --requirement .audit-requirements.txt
62
83
  ```
63
84
 
64
85
  ### Self-lint
@@ -1,5 +1,43 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.5.0 - 2026-10-11
4
+
5
+ - Expanded Python runtime and syntax compatibility to Python >=3.12, including
6
+ Python 3.12 and 3.13 classifiers and configuration.
7
+ - Added evidence-rich JSON findings with confidence, related locations, and
8
+ line-independent content fingerprints.
9
+ - Added `--baseline` support so established repositories can report and fail
10
+ only on findings absent from a prior JSON result.
11
+ - Added `SLP018` for discarded return statuses from `os.system` and
12
+ `subprocess.call`.
13
+ - Added `SLP019` for insecure temporary file creation via `tempfile.mktemp`.
14
+ - Added an executable differential corpus for Ruff, Pyright, ty, and
15
+ pyclichecker, plus explicit source-encoding regression coverage.
16
+ - Documented pyclichecker's place beside formatters, general linters, type
17
+ checkers, tests, and the internal flow-analysis model.
18
+ - Added a post-publish, no-cache public PyPI installation verification.
19
+
20
+ ## 2.4.3 - 2026-09-19
21
+
22
+ - Tightened suppression parsing so prose cannot masquerade as a directive,
23
+ while preserving code-specific suppressions with trailing reasons, adjacent
24
+ type-ignore directives, and multiline-call closing lines.
25
+ - Improved alias and shadowing handling for protocols, abstract methods,
26
+ overloads, and test oracles, including contract imports inside module and
27
+ class control flow and stricter recognition of attribute-style assertions.
28
+ - Made broad-exception, subprocess, HTTP-response, constructor-loop, and
29
+ standard-input analysis follow the relevant control flow more accurately.
30
+ - Corrected nested re-raise classification, exceptional result abandonment,
31
+ guaranteed loop checks, status-constant aliases, derived HTTP predicates, and
32
+ inverted predicate polarity in subprocess and HTTP flow analysis.
33
+ - Indexed operational-result uses so stricter subprocess and HTTP validation
34
+ remains fast on functions with many calls.
35
+ - Added strict mypy, branch coverage, Ruff
36
+ security/datetime/complexity/performance rules, Bandit, and pip-audit to the
37
+ locked development and CI gates.
38
+ - Documented review coverage, agentic handoff expectations, and the explicit
39
+ limit that pyclichecker does not infer formal time complexity.
40
+
3
41
  ## 2.4.2 - 2026-08-21
4
42
 
5
43
  - Added Ubuntu, macOS, and Windows CI coverage for tests, static checks,
@@ -15,16 +15,27 @@ uv sync --locked
15
15
 
16
16
  ## Validation
17
17
 
18
- Run every check before opening a pull request:
18
+ Run the core quality checks before opening a pull request:
19
19
 
20
20
  ```bash
21
21
  uv run python -m unittest discover -v
22
+ uv run python -m tests.corpus_runner
23
+ uv run coverage erase
24
+ uv run coverage run -m unittest discover -v
25
+ uv run coverage report
22
26
  uv run ruff check .
23
27
  uv run ruff format --check .
28
+ uv run mypy
29
+ uv run bandit -q -r src
30
+ uv export --quiet --locked --all-groups --no-emit-project --format requirements.txt --output-file .audit-requirements.txt
31
+ uv run pip-audit --strict --requirement .audit-requirements.txt
24
32
  uv run pyclichecker src tests
25
33
  uv build
26
34
  ```
27
35
 
36
+ Then run the built-archive inspection, installed-CLI smoke tests, and
37
+ fresh-directory wheel test documented in [AGENTS.md](AGENTS.md).
38
+
28
39
  ## Rule changes
29
40
 
30
41
  Every new rule needs a permanent `SLP` code, an actionable diagnostic, and
@@ -53,7 +64,8 @@ posting.
53
64
  `v<version>`.
54
65
  4. The `publish.yml` workflow verifies the tag, rebuilds and smoke-tests the
55
66
  archives, checks PyPI for matching immutable files, then publishes any new
56
- files through Trusted Publishing.
67
+ files through Trusted Publishing and verifies a no-cache installation from
68
+ the public index.
57
69
 
58
70
  The publishing job uses GitHub's short-lived OIDC identity. Do not add a PyPI
59
71
  API token to repository secrets.
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pyclichecker
3
- Version: 2.4.2
4
- Summary: A high-signal Python linter for defects common in rushed and AI-generated code
3
+ Version: 2.5.0
4
+ Summary: A high-signal Python linter for behavioral defects and maintainability risks
5
5
  Keywords: ai,ast,code-quality,linter,python
6
6
  Author: Ken Harrison
7
7
  License-Expression: MIT
@@ -10,9 +10,11 @@ Classifier: Development Status :: 4 - Beta
10
10
  Classifier: Environment :: Console
11
11
  Classifier: Intended Audience :: Developers
12
12
  Classifier: Programming Language :: Python :: 3 :: Only
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
13
15
  Classifier: Programming Language :: Python :: 3.14
14
16
  Classifier: Topic :: Software Development :: Quality Assurance
15
- Requires-Python: >=3.14
17
+ Requires-Python: >=3.12
16
18
  Project-URL: Homepage, https://github.com/ktreharrison/pyclichecker
17
19
  Project-URL: Repository, https://github.com/ktreharrison/pyclichecker
18
20
  Project-URL: Issues, https://github.com/ktreharrison/pyclichecker/issues
@@ -25,6 +27,8 @@ Description-Content-Type: text/markdown
25
27
  [![PyPI](https://img.shields.io/pypi/v/pyclichecker.svg)](https://pypi.org/project/pyclichecker/)
26
28
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
27
29
 
30
+ **High-signal behavioral linting for Python.**
31
+
28
32
  `pyclichecker` is a read-only Python linter for high-signal defects and
29
33
  maintainability smells that often appear in rushed or generated code. It parses
30
34
  source with Python's AST and token APIs and has no runtime dependencies.
@@ -32,6 +36,24 @@ source with Python's AST and token APIs and has no runtime dependencies.
32
36
  It is a code-quality tool, not an AI-authorship detector. The same finding can
33
37
  occur in human-written code, and every finding should be judged in context.
34
38
 
39
+ ## Where it fits
40
+
41
+ `pyclichecker` belongs alongside general-purpose formatters, linters, type
42
+ checkers, and tests. It does not replace them.
43
+
44
+ | Tool | Primary role | Relationship to `pyclichecker` |
45
+ |---|---|---|
46
+ | [Ruff](https://docs.astral.sh/ruff/) | Broad Python linting and formatting | Use Ruff for style, imports, modernization, common bug patterns, and formatting. `pyclichecker` concentrates on a smaller set of behavioral and path-sensitive risks. |
47
+ | [Pyright](https://github.com/microsoft/pyright) | Static type checking | Use Pyright to validate type compatibility and typed interfaces. `pyclichecker` can report selected runtime-quality risks even when a project has few annotations. |
48
+ | [ty](https://docs.astral.sh/ty/) | Static type checking and language services | Use ty for type analysis. Its role overlaps with Pyright rather than with most `pyclichecker` rules. |
49
+ | [Black](https://black.readthedocs.io/) | Deterministic Python formatting | Use Black when it is the project's formatter. `pyclichecker` never rewrites formatting. |
50
+ | `pyclichecker` | Focused AST and control-flow checks | Use it for swallowed failures, unchecked external operations, missing postconditions, fragile constructor state, assertion-free tests, and related generated or rushed-code risks. |
51
+
52
+ A practical stack is one formatter, Ruff, one type checker, meaningful tests,
53
+ and `pyclichecker`. The
54
+ [differential corpus](tests/corpus/README.md) records examples that distinguish
55
+ the tools and examples where their findings overlap.
56
+
35
57
  ## Quick start
36
58
 
37
59
  The project requires Python 3.14. Run it directly without installing:
@@ -60,7 +82,7 @@ pyclichecker . --format github
60
82
  Pin a release when reproducibility matters:
61
83
 
62
84
  ```bash
63
- uvx pyclichecker@2.4.2 .
85
+ uvx pyclichecker@2.5.0 .
64
86
  ```
65
87
 
66
88
  ## Reading a result
@@ -80,6 +102,25 @@ A practical review loop is:
80
102
  4. Run the same command again.
81
103
  5. Suppress only the specific rule when the code is intentionally exceptional.
82
104
 
105
+ JSON findings include a confidence level, evidence statements, related source
106
+ locations, and a stable fingerprint:
107
+
108
+ ```json
109
+ {
110
+ "code": "SLP009",
111
+ "confidence": "high",
112
+ "evidence": [
113
+ "resolved call is `subprocess.run`",
114
+ "no return-code check or deliberate result delegation covers every continuation"
115
+ ],
116
+ "related_locations": [],
117
+ "fingerprint": "v1:..."
118
+ }
119
+ ```
120
+
121
+ Confidence describes how strongly the analyzer established the reported code
122
+ pattern. It does not prove that the behavior is unintended.
123
+
83
124
  ## Rules
84
125
 
85
126
  `pyclichecker --list-rules` reports these rules:
@@ -95,15 +136,17 @@ A practical review loop is:
95
136
  | `SLP006` | error | Obvious placeholder in configuration | Require a real configured value instead of shipping a dummy fallback. |
96
137
  | `SLP007` | warning | Cluster of narrating comments | Remove narration or replace it with the reason behind non-obvious code. |
97
138
  | `SLP008` | warning | Oversized function | Split distinct responsibilities and test them independently. |
98
- | `SLP009` | warning | Unchecked `subprocess.run` result | Use `check=True`, inspect `returncode`, or deliberately return the result. |
139
+ | `SLP009` | warning | Unchecked `subprocess.run` result | Use `check=True`, validate `returncode` before reading output, or deliberately return the complete result. |
99
140
  | `SLP010` | warning | Synchronous network call omits a timeout or sets it to `None` | Pass an explicit timeout appropriate for the operation. |
100
- | `SLP011` | warning | HTTP response consumed without a success check | Call `raise_for_status()` or validate the status before using the body. |
141
+ | `SLP011` | warning | HTTP response consumed without a success check | Call `raise_for_status()` or validate the status on every path before using the body. |
101
142
  | `SLP012` | warning | Path tied to one user's home directory | Use `Path.home()`, a project-relative path, or configuration. |
102
143
  | `SLP013` | warning | Known blocking API called inside async code | Use an async API or move the blocking call to a worker thread. |
103
- | `SLP014` | warning | Test has no explicit result or failure oracle | Assert an observable result or declare the expected exception or failure. |
144
+ | `SLP014` | warning | Test has no explicit result or failure oracle | Use an assertion, a recognized test-framework oracle, or an expected-failure declaration. Arbitrary `assert_*` helper names are not trusted automatically. |
104
145
  | `SLP015` | warning | Overridable method called before constructor state is initialized | Initialize state before dispatch, or make the hook private or final. |
105
146
  | `SLP016` | warning | Instance state initialized on only some constructor paths | Initialize the attribute unconditionally before other methods can read it. |
106
147
  | `SLP017` | warning | Shared mutable class state changed through an instance in production code | Initialize it per instance or mark intentional shared state as `ClassVar`. |
148
+ | `SLP018` | warning | Return status from `os.system` or `subprocess.call` is discarded | Inspect or return the status, or use a raising subprocess API. |
149
+ | `SLP019` | warning | Insecure temporary file creation via `tempfile.mktemp` | Use `NamedTemporaryFile` or `TemporaryDirectory` instead of deprecated `mktemp`. |
107
150
 
108
151
  Rule selection accepts exact codes or prefixes:
109
152
 
@@ -120,6 +163,42 @@ For a first pass, fix `error` findings before reviewing `warning` findings.
120
163
  Warnings are prompts for engineering judgment, not proof that the code is
121
164
  wrong.
122
165
 
166
+ ## Baselines for established repositories
167
+
168
+ Create a baseline from a complete JSON run:
169
+
170
+ ```bash
171
+ pyclichecker . --format json --fail-on never > .pyclichecker-baseline.json
172
+ ```
173
+
174
+ Confirm that command exits `0`, then fail only on findings that are not present
175
+ in the baseline:
176
+
177
+ ```bash
178
+ pyclichecker . --baseline .pyclichecker-baseline.json
179
+ ```
180
+
181
+ AST-backed fingerprints use the rule, normalized path, enclosing scope, and
182
+ normalized AST content rather than line numbers. Syntax-error fingerprints use
183
+ the parser message and offending source line. Moving unchanged code within a
184
+ file therefore does not make an existing finding new. Duplicate fingerprints
185
+ are counted, so adding another copy of an existing defect is still reported.
186
+
187
+ ## Review coverage and performance
188
+
189
+ `pyclichecker` complements, rather than replaces, general-purpose quality
190
+ tools. This repository also gates changes with Ruff, strict mypy, Bandit,
191
+ pip-audit, unit tests, and branch coverage. See
192
+ [Review coverage and limits](https://github.com/ktreharrison/pyclichecker/blob/main/docs/review-coverage.md)
193
+ for the mapping to the Real Python review and agentic-engineering workflows.
194
+ See [Flow analysis](docs/flow-analysis.md) for the implementation model behind
195
+ the path-sensitive rules.
196
+
197
+ Performance coverage is deliberately narrow. `SLP013` catches selected
198
+ blocking calls in async code, and Ruff's `PERF` rules catch known local
199
+ performance anti-patterns. `pyclichecker` does not infer Big-O complexity,
200
+ detect general N+1 behavior, or replace benchmarks and profiling.
201
+
123
202
  ## Suppressions
124
203
 
125
204
  Inline suppression requires an explicit pyclichecker rule code:
@@ -134,7 +213,9 @@ def another_stub(): # slop: ignore [SLP001]
134
213
  ```
135
214
 
136
215
  Bare `# noqa` and unrelated codes such as `# noqa: F401` do not suppress
137
- pyclichecker. Directive-like text inside a string is also ignored.
216
+ pyclichecker. A code-specific directive may include a trailing reason and may
217
+ follow a `# type: ignore[...]` directive on the same line. Directive-like prose
218
+ and text inside a string are ignored.
138
219
 
139
220
  To suppress an entire file, place this real comment within its first five
140
221
  lines:
@@ -163,17 +244,21 @@ installing the package.
163
244
  Agents should use the pinned release and JSON output for stable results:
164
245
 
165
246
  ```bash
166
- uvx pyclichecker@2.4.2 changed_file.py --format json
247
+ uvx pyclichecker@2.5.0 changed_file.py --format json
167
248
  ```
168
249
 
169
250
  JSON output contains the package version, number of files checked, findings,
170
- and operational errors. Each finding includes path, line, column, code,
171
- severity, and message.
251
+ baseline metadata, and operational errors. Each finding includes path, line,
252
+ column, code, severity, confidence, message, evidence, related locations, and
253
+ a stable fingerprint.
172
254
 
173
255
  Treat exit `1` as work to review and exit `2` as a broken or incomplete scan.
174
256
  Fix findings before adding suppressions, and keep every suppression scoped to
175
257
  one explicit rule.
176
258
 
259
+ Treat findings or review claims from another agent as hypotheses until source
260
+ inspection, reproduction, tests, or another independent check verifies them.
261
+
177
262
  An agent should finish only after the same command returns `0`, or after it
178
263
  records why each remaining finding is intentional. It should never treat exit
179
264
  `2` as a clean result.
@@ -187,7 +272,7 @@ project's `AGENTS.md`:
187
272
  After creating or changing Python code:
188
273
 
189
274
  1. Run pyclichecker on every changed Python file:
190
- `uvx pyclichecker@2.4.2 changed_file.py --format json`
275
+ `uvx pyclichecker@2.5.0 changed_file.py --format json`
191
276
  2. Treat exit 1 as findings to fix and exit 2 as an incomplete scan.
192
277
  3. Fix findings and rerun relevant tests. Do not add broad suppressions.
193
278
  4. Run the final repository gate with the same command, replacing
@@ -197,13 +282,22 @@ After creating or changing Python code:
197
282
  ## Development
198
283
 
199
284
  The locked development environment contains Ruff and uses the standard-library
200
- `unittest` runner:
285
+ `unittest` runner. It also includes strict typing, branch coverage, security,
286
+ and dependency-audit gates:
201
287
 
202
288
  ```bash
203
289
  uv sync --locked
204
290
  uv run python -m unittest discover -v
291
+ uv run python -m tests.corpus_runner
292
+ uv run coverage erase
293
+ uv run coverage run -m unittest discover -v
294
+ uv run coverage report
205
295
  uv run ruff check .
206
296
  uv run ruff format --check .
297
+ uv run mypy
298
+ uv run bandit -q -r src
299
+ uv export --quiet --locked --all-groups --no-emit-project --format requirements.txt --output-file .audit-requirements.txt
300
+ uv run pip-audit --strict --requirement .audit-requirements.txt
207
301
  uv run pyclichecker src tests
208
302
  uv build
209
303
  uvx --from . pyclichecker --version
@@ -211,8 +305,8 @@ uvx --from . pyclichecker --version
211
305
 
212
306
  See [CONTRIBUTING.md](CONTRIBUTING.md) for rule and pull-request requirements.
213
307
 
214
- The implementation has been exercised on macOS with CPython 3.14. The GitHub
215
- Actions workflow is configured to run the complete validation suite on Linux.
308
+ The GitHub Actions workflow runs the complete validation suite with CPython
309
+ 3.14 on Linux, macOS, and Windows.
216
310
 
217
311
  ## License
218
312