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.
- pyclichecker-2.5.0/.github/dependabot.yml +28 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/.github/workflows/ci.yml +35 -5
- pyclichecker-2.5.0/.github/workflows/publish.yml +167 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/AGENTS.md +21 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/CHANGELOG.md +38 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/CONTRIBUTING.md +14 -2
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/PKG-INFO +109 -15
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/README.md +104 -12
- pyclichecker-2.5.0/docs/flow-analysis.md +80 -0
- pyclichecker-2.5.0/docs/review-coverage.md +99 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/pyproject.toml +37 -4
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/pyproject.toml.orig +31 -4
- pyclichecker-2.5.0/skills/pyclichecker/SKILL.md +97 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/__init__.py +2 -1
- pyclichecker-2.5.0/src/pyclichecker/baseline.py +56 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/cli.py +45 -4
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/diagnostics.py +68 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/discovery.py +8 -2
- pyclichecker-2.5.0/src/pyclichecker/rules.py +9216 -0
- pyclichecker-2.5.0/tests/corpus/README.md +31 -0
- pyclichecker-2.5.0/tests/corpus/SLP003/positive.py.fixture +5 -0
- pyclichecker-2.5.0/tests/corpus/SLP009/corrected.py.fixture +11 -0
- pyclichecker-2.5.0/tests/corpus/SLP015/positive.py.fixture +7 -0
- pyclichecker-2.5.0/tests/corpus/SLP018/corrected.py.fixture +7 -0
- pyclichecker-2.5.0/tests/corpus/SLP018/false_positive.py.fixture +7 -0
- pyclichecker-2.5.0/tests/corpus/SLP018/positive.py.fixture +5 -0
- pyclichecker-2.5.0/tests/corpus/SLP019/corrected.py.fixture +8 -0
- pyclichecker-2.5.0/tests/corpus/SLP019/false_positive.py.fixture +7 -0
- pyclichecker-2.5.0/tests/corpus/SLP019/positive.py.fixture +8 -0
- pyclichecker-2.5.0/tests/corpus/comparison/ruff_none_comparison.py.fixture +2 -0
- pyclichecker-2.5.0/tests/corpus/comparison/type_error.py.fixture +2 -0
- pyclichecker-2.5.0/tests/corpus/manifest.json +156 -0
- pyclichecker-2.5.0/tests/corpus_runner.py +175 -0
- pyclichecker-2.5.0/tests/test_corpus.py +44 -0
- pyclichecker-2.5.0/tests/test_features.py +315 -0
- pyclichecker-2.5.0/tests/test_pyclichecker.py +7020 -0
- pyclichecker-2.5.0/uv.lock +1061 -0
- pyclichecker-2.4.2/.github/workflows/publish.yml +0 -83
- pyclichecker-2.4.2/skills/pyclichecker/SKILL.md +0 -68
- pyclichecker-2.4.2/src/pyclichecker/rules.py +0 -2286
- pyclichecker-2.4.2/tests/test_pyclichecker.py +0 -1266
- pyclichecker-2.4.2/uv.lock +0 -43
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/LICENSE +0 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/skills/pyclichecker/agents/openai.yaml +0 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/__main__.py +0 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/_version.py +0 -0
- {pyclichecker-2.4.2 → pyclichecker-2.5.0}/src/pyclichecker/config.py +0 -0
- {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@
|
|
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:
|
|
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
|
-
|
|
68
|
-
|
|
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
|
|
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
|
-
Summary: A high-signal Python linter for defects
|
|
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.
|
|
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
|
[](https://pypi.org/project/pyclichecker/)
|
|
26
28
|
[](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.
|
|
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`,
|
|
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 |
|
|
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.
|
|
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.
|
|
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,
|
|
171
|
-
severity,
|
|
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.
|
|
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
|
|
215
|
-
|
|
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
|
|