pyclichecker 2.4.1__tar.gz

pyclichecker-2.4.1/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Python 3.14
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv and Python
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.12.5"
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install locked development environment
+        run: uv sync --locked
+
+      - name: Run unit tests
+        run: uv run python -m unittest discover -v
+
+      - name: Run Ruff
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Run pyclichecker on itself
+        run: uv run pyclichecker src tests
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke-test built wheel
+        run: |
+          wheel="$(find dist -name '*.whl' -print -quit)"
+          uvx --from "$wheel" pyclichecker --version
+          uvx --from "$wheel" pyclichecker src tests

pyclichecker-2.4.1/.github/workflows/publish.yml

@@ -0,0 +1,80 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Build and publish
+    if: github.event.release.prerelease == false
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pyclichecker
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv and Python
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.12.5"
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install locked development environment
+        run: uv sync --locked
+
+      - name: Verify release tag
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          project_version="$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "$RELEASE_TAG" = "v$project_version"
+
+      - name: Run quality gates
+        run: |
+          uv run python -m unittest discover -v
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run pyclichecker src tests
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Inspect archives
+        run: |
+          for archive in dist/*.whl; do
+            uv run python -m zipfile -l "$archive"
+          done
+          for archive in dist/*.tar.gz; do
+            tar -tzf "$archive"
+          done
+
+      - name: Smoke-test built wheel
+        run: |
+          repo_root="$PWD"
+          wheel="$repo_root/dist/pyclichecker-${RELEASE_TAG#v}-py3-none-any.whl"
+          scratch="$(mktemp -d)"
+          cd "$scratch"
+          uvx --from "$wheel" pyclichecker --version
+          uvx --from "$wheel" pyclichecker --list-rules
+          uvx --from "$wheel" pyclichecker "$repo_root/src" "$repo_root/tests"
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+
+      - name: Publish distributions
+        run: uv publish --trusted-publishing always

pyclichecker-2.4.1/AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md
+
+## Purpose
+
+This repository builds the `pyclichecker` command, a read-only AST linter for
+Python quality defects associated with rushed or generated code.
+
+## Runtime
+
+- The project requires Python 3.14.
+- Package and environment operations use `uv`.
+- Runtime code has no third-party dependencies.
+- MUST NOT add a runtime dependency when the standard library provides a clear implementation.
+- MUST keep source under `src/pyclichecker/` and tests under `tests/`.
+
+## Rule changes
+
+- MUST give each new rule a permanent `SLP` code, severity, title, and actionable description.
+- MUST NOT reuse or silently change the meaning of an existing code.
+- MUST favor behavioral defects and high-signal maintainability risks over style checks already handled by Ruff.
+- MUST add a positive test, a negative test, and relevant false-positive tests for every rule.
+- MUST keep output deterministic by sorting diagnostics by path, line, column, and code.
+- SHOULD explain the concrete risk and a practical correction in each diagnostic.
+
+## Suppressions
+
+- MUST parse suppression directives from comment tokens, not source substrings.
+- MUST require an explicit `SLP` code for inline suppression.
+- MUST NOT make bare `# noqa` suppress pyclichecker.
+- SHOULD fix a finding before adding a suppression.
+
+## CLI compatibility
+
+- Exit `0` means a complete run with no finding at the configured failure
+  threshold.
+- Exit `1` means findings met the configured failure threshold.
+- Exit `2` means the scan was incomplete or could not operate.
+- MUST preserve text, JSON, and GitHub output modes.
+- MUST treat operational errors as exit `2`, even when findings are also present.
+
+## Testing
+
+Run every check from the repository root.
+
+### Unit tests
+
+```bash
+uv run python -m unittest discover -v
+```
+
+Every changed rule MUST have:
+
+- A source example that reports the rule.
+- A corrected example that does not report it.
+- False-positive coverage for aliases, shadowing, delegation, test fixtures, or suppressions when relevant.
+
+### Static checks
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+```
+
+### Self-lint
+
+```bash
+uv run pyclichecker src tests
+```
+
+### Package build
+
+```bash
+uv build
+```
+
+### Built archive inspection
+
+```bash
+for archive in dist/*.whl; do
+    uv run python -m zipfile -l "$archive"
+done
+for archive in dist/*.tar.gz; do
+    tar -tzf "$archive"
+done
+```
+
+### Installed CLI smoke tests
+
+```bash
+uvx --from . pyclichecker --version
+uvx --from . pyclichecker --list-rules
+uvx --from . pyclichecker src tests
+```
+
+### Fresh-directory package smoke test
+
+Run the built wheel away from the repository so imports cannot accidentally resolve from the checkout:
+
+```bash
+repo_root="$PWD"
+version="$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+wheel="$repo_root/dist/pyclichecker-$version-py3-none-any.whl"
+scratch="$(mktemp -d)"
+(
+    cd "$scratch"
+    uvx --from "$wheel" pyclichecker --version
+    uvx --from "$wheel" pyclichecker --list-rules
+    uvx --from "$wheel" pyclichecker "$repo_root/src" "$repo_root/tests"
+)
+```
+
+## Release changes
+
+- MUST keep the project version and `CHANGELOG.md` aligned.
+- MUST inspect both wheel and source archive contents before release.
+- MUST run the built wheel from a fresh directory using only documented commands.
+- MUST preserve the approved MIT license in package metadata and release
+  archives.
+- MUST scan for credentials, personal paths, and internal references before a
+  public push.

pyclichecker-2.4.1/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## 2.4.1 - 2026-08-21
+
+- Calibrated `SLP015` to report overridable constructor dispatch only while
+  definitely initialized instance state is still pending.
+- Reduced `SLP016` false positives for `hasattr()` guards, test-and-set
+  initialization, and explicit `AttributeError` fallback.
+- Exempted test modules from `SLP017`, where shared mutable containers are
+  commonly intentional recorders and fixtures.
+- Added PyPI Trusted Publishing and documented the short
+  `uvx pyclichecker .` command.
+- Updated the bundled Agent Skill to use the pinned PyPI release.
+
+## 2.4.0 - 2026-08-21
+
+- Added `SLP015` for constructor calls that dispatch to overridable same-class
+  methods before initialization is complete.
+- Added `SLP016` for instance attributes that are initialized on only some
+  successful constructor paths and later read without a local assignment.
+- Added `SLP017` for instance methods that mutate mutable list, dictionary, or
+  set state inherited from the class.
+- Added conservative exemptions for final and private methods, class fallbacks,
+  dynamic attributes, `ClassVar`, per-instance initialization, explicit class
+  mutation, and nested scopes.
+- Added positive, corrected, false-positive, and inline-suppression coverage
+  for all three class-correctness rules.
+
+## 2.3.0 - 2026-08-21
+
+- Added `SLP009` for unchecked `subprocess.run` outcomes.
+- Added `SLP010` for synchronous network calls that omit a timeout or set it to
+  `None`.
+- Added `SLP011` for HTTP responses consumed without a success check.
+- Added `SLP012` for hardcoded paths tied to a user's home directory.
+- Added `SLP014` for tests that can pass without an explicit result or
+  expected-failure oracle.
+- Expanded `SLP006` to inspect environment defaults, mappings, keyword
+  arguments, and function defaults.
+- Added import-alias, shadowing, delegation, suppression, and false-positive
+  coverage for the new checks.
+- Added a version-pinned Agent Skill and portable `AGENTS.md` workflow for
+  running strict changed-file and repository gates through `uvx`.
+- Added MIT licensing, public project metadata, contribution guidance, and
+  pinned GitHub Actions validation.
+
+## 2.2.0 - 2026-08-21
+
+- Converted the standalone script into a Python 3.14 `uv` package with a
+  `pyclichecker` console command.
+- Added locked development tooling, module and console entry points, structured
+  modules, and a 26-test suite.
+- Preserved all ten existing rules, including `SLP013` diagnostics for known
+  blocking calls inside async functions.
+- Made suppressions token-aware so directive-like strings no longer hide
+  findings.
+- Required explicit `SLP` codes for inline `noqa` suppression.
+- Made zero-file scans return operational exit code `2`.
+
+## 2.1.0
+
+- This version number came from the original standalone script. No earlier
+  release notes were available in the source folder.

pyclichecker-2.4.1/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Contributions that improve signal, reduce false positives, or make the command
+easier to use are welcome.
+
+## Development setup
+
+The project requires Python 3.14 and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/ktreharrison/pyclichecker.git
+cd pyclichecker
+uv sync --locked
+```
+
+## Validation
+
+Run every check before opening a pull request:
+
+```bash
+uv run python -m unittest discover -v
+uv run ruff check .
+uv run ruff format --check .
+uv run pyclichecker src tests
+uv build
+```
+
+## Rule changes
+
+Every new rule needs a permanent `SLP` code, an actionable diagnostic, and
+tests for:
+
+- Code that must produce the finding.
+- Corrected code that must not produce the finding.
+- Relevant false-positive cases, including aliases, shadowing, delegation,
+  fixtures, and suppressions.
+
+Prefer behavioral defects and high-signal maintainability risks over formatting
+or style checks already covered by Ruff.
+
+## Reporting a false positive
+
+Open an issue with the rule code, a minimal source example, the actual result,
+and the result you expected. Remove credentials and proprietary code before
+posting.
+
+## Maintainer releases
+
+1. Update the version in `pyproject.toml`, refresh `uv.lock`, and add the
+   matching `CHANGELOG.md` entry.
+2. Run every validation and package inspection command in `AGENTS.md`.
+3. Merge the release commit to `main` and create a GitHub release tagged
+   `v<version>`.
+4. The `publish.yml` workflow verifies the tag, rebuilds and smoke-tests the
+   archives, then publishes them to PyPI through Trusted Publishing.
+
+The publishing job uses GitHub's short-lived OIDC identity. Do not add a PyPI
+API token to repository secrets.

pyclichecker-2.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ken Harrison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyclichecker-2.4.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: pyclichecker
+Version: 2.4.1
+Summary: A high-signal Python linter for defects common in rushed and AI-generated code
+Keywords: ai,ast,code-quality,linter,python
+Author: Ken Harrison
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/ktreharrison/pyclichecker
+Project-URL: Repository, https://github.com/ktreharrison/pyclichecker
+Project-URL: Issues, https://github.com/ktreharrison/pyclichecker/issues
+Project-URL: Changelog, https://github.com/ktreharrison/pyclichecker/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# pyclichecker
+
+[![CI](https://github.com/ktreharrison/pyclichecker/actions/workflows/ci.yml/badge.svg)](https://github.com/ktreharrison/pyclichecker/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pyclichecker.svg)](https://pypi.org/project/pyclichecker/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`pyclichecker` is a read-only Python linter for high-signal defects and
+maintainability smells that often appear in rushed or generated code. It parses
+source with Python's AST and token APIs and has no runtime dependencies.
+
+It is a code-quality tool, not an AI-authorship detector. The same finding can
+occur in human-written code, and every finding should be judged in context.
+
+## Quick start
+
+The project requires Python 3.14. Run it directly without installing:
+
+```bash
+uvx pyclichecker .
+```
+
+For a persistent command, install it with `uv`:
+
+```bash
+uv tool install pyclichecker
+pyclichecker .
+```
+
+It can lint one file, consume standard input, emit JSON for an agent, or emit
+GitHub workflow annotations:
+
+```bash
+pyclichecker app.py
+printf 'def unfinished():\n    pass\n' | pyclichecker -
+pyclichecker . --format json
+pyclichecker . --format github
+```
+
+Pin a release when reproducibility matters:
+
+```bash
+uvx pyclichecker@2.4.1 .
+```
+
+## Reading a result
+
+Text diagnostics use the conventional `path:line:column: code message` shape:
+
+```text
+app.py:8:1: SLP001 `load_config` is a concrete placeholder implementation
+Found 1 issue(s) in 1 file(s).
+```
+
+A practical review loop is:
+
+1. Open the reported file and line.
+2. Decide whether the behavior is intentional.
+3. Fix the implementation, error handling, or structure.
+4. Run the same command again.
+5. Suppress only the specific rule when the code is intentionally exceptional.
+
+## Rules
+
+`pyclichecker --list-rules` reports these rules:
+
+| Code | Severity | Check | Typical correction |
+|---|---|---|---|
+| `SLP000` | error | Invalid Python syntax | Correct the reported syntax before trusting the rest of the scan. |
+| `SLP001` | error | Placeholder implementation | Implement the function, remove it, or make the contract explicitly abstract. |
+| `SLP002` | error | Silently swallowed exception | Handle, record, or re-raise the failure. |
+| `SLP003` | warning | Broad exception converted to fallback behavior | Catch the failures you expect and preserve unexpected ones. |
+| `SLP004` | warning | Async function with no async behavior | Make it synchronous or perform the intended awaited operation. |
+| `SLP005` | warning | Duplicate implementation in the same file | Extract shared behavior so copies cannot drift. |
+| `SLP006` | error | Obvious placeholder in configuration | Require a real configured value instead of shipping a dummy fallback. |
+| `SLP007` | warning | Cluster of narrating comments | Remove narration or replace it with the reason behind non-obvious code. |
+| `SLP008` | warning | Oversized function | Split distinct responsibilities and test them independently. |
+| `SLP009` | warning | Unchecked `subprocess.run` result | Use `check=True`, inspect `returncode`, or deliberately return the result. |
+| `SLP010` | warning | Synchronous network call omits a timeout or sets it to `None` | Pass an explicit timeout appropriate for the operation. |
+| `SLP011` | warning | HTTP response consumed without a success check | Call `raise_for_status()` or validate the status before using the body. |
+| `SLP012` | warning | Path tied to one user's home directory | Use `Path.home()`, a project-relative path, or configuration. |
+| `SLP013` | warning | Known blocking API called inside async code | Use an async API or move the blocking call to a worker thread. |
+| `SLP014` | warning | Test has no explicit result or failure oracle | Assert an observable result or declare the expected exception or failure. |
+| `SLP015` | warning | Overridable method called before constructor state is initialized | Initialize state before dispatch, or make the hook private or final. |
+| `SLP016` | warning | Instance state initialized on only some constructor paths | Initialize the attribute unconditionally before other methods can read it. |
+| `SLP017` | warning | Shared mutable class state changed through an instance in production code | Initialize it per instance or mark intentional shared state as `ClassVar`. |
+
+Rule selection accepts exact codes or prefixes:
+
+```bash
+pyclichecker . --select SLP001,SLP002
+pyclichecker . --ignore SLP004,SLP008
+```
+
+Thresholds for function size, comment clusters, and duplicate bodies are
+exposed as command-line options. Run `pyclichecker --help` for their names and
+defaults.
+
+For a first pass, fix `error` findings before reviewing `warning` findings.
+Warnings are prompts for engineering judgment, not proof that the code is
+wrong.
+
+## Suppressions
+
+Inline suppression requires an explicit pyclichecker rule code:
+
+```python
+def intentional_stub():  # noqa: SLP001
+    pass
+
+
+def another_stub():  # slop: ignore [SLP001]
+    pass
+```
+
+Bare `# noqa` and unrelated codes such as `# noqa: F401` do not suppress
+pyclichecker. Directive-like text inside a string is also ignored.
+
+To suppress an entire file, place this real comment within its first five
+lines:
+
+```python
+# slop: ignore-file
+```
+
+## Exit codes
+
+- `0`: no finding met `--fail-on`, and the run had no operational error.
+- `1`: at least one finding met the configured failure severity.
+- `2`: the scan could not run completely, including missing paths, unreadable
+  files, unsupported inputs, or no discovered Python files.
+
+`--fail-on warning` is the default. `--fail-on error` reports warnings without
+failing, and `--fail-on never` reports all findings without failing.
+
+## Agent use
+
+The repository includes a reusable
+[`pyclichecker` Agent Skill](skills/pyclichecker/SKILL.md). Skill-aware agents
+can load that folder and run the linter through `uvx` without permanently
+installing the package.
+
+Agents should use the pinned release and JSON output for stable results:
+
+```bash
+uvx pyclichecker@2.4.1 changed_file.py --format json
+```
+
+JSON output contains the package version, number of files checked, findings,
+and operational errors. Each finding includes path, line, column, code,
+severity, and message.
+
+Treat exit `1` as work to review and exit `2` as a broken or incomplete scan.
+Fix findings before adding suppressions, and keep every suppression scoped to
+one explicit rule.
+
+An agent should finish only after the same command returns `0`, or after it
+records why each remaining finding is intentional. It should never treat exit
+`2` as a clean result.
+
+For agents that do not load skills, add this portable contract to the
+project's `AGENTS.md`:
+
+```markdown
+## Python quality gate
+
+After creating or changing Python code:
+
+1. Run pyclichecker on every changed Python file:
+   `uvx pyclichecker@2.4.1 changed_file.py --format json`
+2. Treat exit 1 as findings to fix and exit 2 as an incomplete scan.
+3. Fix findings and rerun relevant tests. Do not add broad suppressions.
+4. Run the final repository gate with the same command, replacing
+   `changed_file.py` with `.`, and finish only when it exits 0.
+```
+
+## Development
+
+The locked development environment contains Ruff and uses the standard-library
+`unittest` runner:
+
+```bash
+uv sync --locked
+uv run python -m unittest discover -v
+uv run ruff check .
+uv run ruff format --check .
+uv run pyclichecker src tests
+uv build
+uvx --from . pyclichecker --version
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for rule and pull-request requirements.
+
+The implementation has been exercised on macOS with CPython 3.14. The GitHub
+Actions workflow is configured to run the complete validation suite on Linux.
+
+## License
+
+Released under the [MIT License](LICENSE).