smellcheck 0.2.1__tar.gz

smellcheck-0.2.1/.claude-plugin/marketplace.json

@@ -0,0 +1,32 @@
+{
+  "name": "smellcheck",
+  "owner": {
+    "name": "Cheick Berthe",
+    "email": "cheick@example.com"
+  },
+  "metadata": {
+    "description": "Python code smell detector with 82+ patterns mapped to a refactoring catalog. AST-based, zero dependencies, stdlib only.",
+    "version": "0.2.1"
+  },
+  "plugins": [
+    {
+      "name": "python-refactoring",
+      "source": "./plugins/python-refactoring",
+      "description": "Python refactoring catalog with 82+ patterns covering immutability, class design, control flow, architecture, OO metrics, and Python idioms. Analyze code for smells and apply numbered refactoring patterns.",
+      "version": "0.2.1",
+      "author": {
+        "name": "Cheick Berthe"
+      },
+      "license": "MIT",
+      "keywords": [
+        "python",
+        "refactoring",
+        "code-smells",
+        "ast",
+        "static-analysis",
+        "code-quality"
+      ],
+      "category": "development"
+    }
+  ]
+}

smellcheck-0.2.1/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Default owner for everything in the repo
+* @cheickmec
+
+# Core detector -- changes here need careful review
+src/smellcheck/detector.py @cheickmec

smellcheck-0.2.1/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: cheickmec

smellcheck-0.2.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report a false positive, false negative, crash, or incorrect output
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear description of what went wrong.
+
+**Python code that triggers the issue**
+```python
+# Paste the minimal code that reproduces the problem
+```
+
+**Expected behavior**
+What should smellcheck report (or not report)?
+
+**Actual behavior**
+What does smellcheck actually output? Paste the relevant output:
+```
+# smellcheck output here
+```
+
+**Environment**
+- smellcheck version: (`smellcheck --version`)
+- Python version: (`python --version`)
+- OS:
+- Install method: pip / GitHub Action / pre-commit / Agent Skills
+
+**Additional context**
+- Is this a false positive (reported something that isn't a smell)?
+- Is this a false negative (missed a smell that should be detected)?
+- Is this a crash or unexpected error?

smellcheck-0.2.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,40 @@
+---
+name: Feature request
+about: Suggest a new smell check, CLI feature, or improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**What kind of feature?**
+- [ ] New smell check
+- [ ] New CLI option
+- [ ] New output format
+- [ ] Improvement to existing check
+- [ ] Other
+
+**For new smell checks: describe the code pattern**
+
+What code should be detected?
+
+```python
+# Before (smelly code)
+```
+
+What does the refactored version look like?
+
+```python
+# After (clean code)
+```
+
+**Why is this a smell?**
+Explain why this pattern is problematic. References to Fowler, Contieri, or other
+refactoring literature are a plus.
+
+**Suggested severity**
+- [ ] error (always wrong, like mutable default args)
+- [ ] warning (usually wrong, should be reviewed)
+- [ ] info (style suggestion, may be intentional)
+
+**Additional context**
+Any other context, related patterns, or edge cases to consider.

smellcheck-0.2.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,41 @@
+## What does this PR do?
+
+Brief description of the change.
+
+## Type of change
+
+- [ ] New smell check (add pattern number, e.g. `#071`)
+- [ ] Bug fix (false positive, false negative, crash)
+- [ ] CLI / output improvement
+- [ ] Documentation
+- [ ] CI / tooling
+- [ ] Other
+
+## Checklist
+
+- [ ] `pytest tests/ -v` passes (all tests, including version parity)
+- [ ] New check has a test in `tests/test_detector.py`
+- [ ] `smellcheck src/smellcheck/` self-check runs clean (or new findings are intentional)
+- [ ] No dependencies added (stdlib only)
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
+
+## For new smell checks
+
+- **Pattern number**: `#___`
+- **Severity**: error / warning / info
+- **Category**: functions / classes / complexity / imports / ...
+- **Before** (smelly code):
+
+```python
+# paste example
+```
+
+- **After** (clean code):
+
+```python
+# paste example
+```
+
+## Additional context
+
+Any other context, edge cases, or related issues.

smellcheck-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and test deps
+        run: pip install -e . && pip install pytest
+      - name: Run tests
+        run: pytest tests/ -v
+      - name: Self-check
+        run: smellcheck src/smellcheck/ --min-severity warning
+
+  version-parity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install package and test deps
+        run: pip install -e . && pip install pytest
+      - name: Verify version parity
+        run: pytest tests/test_version_parity.py -v

smellcheck-0.2.1/.github/workflows/lint-commits.yml

@@ -0,0 +1,14 @@
+name: Lint Commits
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint-commits:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: webiny/action-conventional-commits@v1.3.0
+        with:
+          allowed-commit-types: "feat,fix,refactor,test,docs,chore,ci,style,perf,build,revert"

smellcheck-0.2.1/.github/workflows/release-please.yml

@@ -0,0 +1,80 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-pypi:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/smellcheck
+    env:
+      TAG_NAME: ${{ needs.release-please.outputs.tag_name }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # Guard 1: tag must match pyproject.toml version
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${TAG_NAME#v}"
+          PKG_VERSION=$(python3 -c "
+          import re, pathlib
+          text = pathlib.Path('pyproject.toml').read_text()
+          m = re.search(r'^version\s*=\s*\"([^\"]+)\"', text, re.MULTILINE)
+          print(m.group(1))
+          ")
+          echo "Tag version:    $TAG_VERSION"
+          echo "Package version: $PKG_VERSION"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Version mismatch: tag=$TAG_VERSION != pyproject.toml=$PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Install build tools
+        run: pip install build
+      - name: Build package
+        run: python -m build
+
+      # Guard 2: smoke-test the built wheel before publishing
+      - name: Smoke-test wheel
+        run: |
+          TAG_VERSION="${TAG_NAME#v}"
+          pip install dist/smellcheck-*.whl
+          INSTALLED=$(smellcheck --version | awk '{print $2}')
+          echo "Installed version: $INSTALLED"
+          echo "Expected version:  $TAG_VERSION"
+          if [ "$INSTALLED" != "$TAG_VERSION" ]; then
+            echo "::error::Installed version $INSTALLED does not match tag $TAG_VERSION"
+            exit 1
+          fi
+          echo "Smoke test: smellcheck --version OK"
+          smellcheck --help > /dev/null
+          echo "Smoke test: smellcheck --help OK"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

smellcheck-0.2.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.tox/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.so
+.DS_Store

smellcheck-0.2.1/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: local
+    hooks:
+      - id: no-commit-to-main
+        name: no-commit-to-main
+        entry: bash -c 'branch=$(git rev-parse --abbrev-ref HEAD); if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then echo "Direct commits to $branch are not allowed. Use a feature branch." >&2; exit 1; fi'
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]
+
+      - id: version-parity
+        name: version-parity
+        entry: python -m pytest tests/test_version_parity.py -q --no-header --tb=short
+        language: system
+        pass_filenames: false
+        files: '(pyproject\.toml|\.release-please-manifest\.json|marketplace\.json)$'

smellcheck-0.2.1/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: smellcheck
+  name: smellcheck
+  description: 'Python code smell detector (55 AST checks, 82 refactoring patterns)'
+  entry: smellcheck
+  language: python
+  types: [python]
+  require_serial: false

smellcheck-0.2.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.1"
+}

smellcheck-0.2.1/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1](https://github.com/cheickmec/smellcheck/compare/v0.2.0...v0.2.1) (2026-02-11)
+
+
+### Features
+
+* initial release -- 82-pattern Python refactoring skill with AST detector ([e96f750](https://github.com/cheickmec/smellcheck/commit/e96f7507e6739bb3463dca93e38ed04bc6cf1597))
+* restructure for PyPI, GitHub Action, pre-commit, and Agent Skills distribution ([e1bf50b](https://github.com/cheickmec/smellcheck/commit/e1bf50b2f4f1b8191903a84c7d262a0c312f163d))
+
+
+### Bug Fixes
+
+* address 9 code review findings (P1-P3) ([39a62c0](https://github.com/cheickmec/smellcheck/commit/39a62c0b2ce9fb0ce00f54e8dc4e4a97fddfc792))
+
+
+### Documentation
+
+* add community files for OSS maturity ([8b7fc5f](https://github.com/cheickmec/smellcheck/commit/8b7fc5fcc81f27c58469f220fd33483a116ab07c))
+* update README for cross-platform compatibility and SEO ([aecccba](https://github.com/cheickmec/smellcheck/commit/aecccba107b831b7206c543e1a1b34641a0c6903))
+
+
+### Miscellaneous
+
+* add CHANGELOG.md, fix version to 0.1.1 ([82aae13](https://github.com/cheickmec/smellcheck/commit/82aae130e0830ce38e4f0f1d46c26c095619ee33))
+* add pre-commit hook to prevent direct commits to main ([b23e812](https://github.com/cheickmec/smellcheck/commit/b23e812f123f551ad181d1262959e47ff503d1c0))
+* rename project from pysmells to smellcheck ([71589cc](https://github.com/cheickmec/smellcheck/commit/71589cc6efa36085d7c2bcc0e4d39c11edad1155))
+
+## [0.1.1] - 2026-02-11
+
+### Fixed
+- Import analysis now captures full dotted paths, fixing under-reporting of #CYC, #UDE, #FIO on package-based repos
+- RFC metric counts distinct external method calls (not class names), correctly measuring response set size
+- elif chains no longer produce duplicate #014 and #068 findings
+- #058 no longer false-positives on `ExitStack.enter_context(open(...))`
+- Single-file scans now run per-class OO metrics (LCOM, CBO, RFC, MID)
+- CLI docs updated with correct script path from repo root
+- Corrected detection counts: 40 per-file + 10 cross-file + 5 OO metrics = 55
+- Added missing #007 (extract class) to per-file detection table
+- Fixed SKILL.md smell-to-file mappings (003, 005, 006, 008, MID pointed to wrong reference files)
+- `--min-severity` now validates input and rejects invalid values with clear error message
+
+## [0.1.0] - 2026-02-10
+
+### Added
+- AST-based smell detector with 55 automated checks (stdlib-only, zero dependencies)
+  - 40 per-file patterns (#001-#070, #CC)
+  - 10 cross-file patterns (#013, #CYC, #GOD, #FE, #SHO, #DIT, #WHI, #INT, #SPG, #UDE)
+  - 5 OO metrics (#LCOM, #CBO, #FIO, #RFC, #MID)
+- 82 refactoring patterns with before/after examples across 8 reference files
+- Agent Skills plugin structure for Claude Code, Codex CLI, Cursor, Copilot, Gemini CLI, Roo Code
+- JSON output mode for CI/CD integration
+- Severity filtering (`--min-severity info|warning|error`)
+
+[0.1.1]: https://github.com/cheickmec/smellcheck/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/cheickmec/smellcheck/releases/tag/v0.1.0

smellcheck-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,50 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in our
+project and our community a harassment-free experience for everyone, regardless of
+age, body size, disability, ethnicity, sex characteristics, gender identity and
+expression, level of experience, education, socio-economic status, nationality,
+personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in response
+to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, including issues, pull
+requests, discussions, and any other communication channel associated with the project.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported
+to the project maintainer at **cheick@example.com**. All complaints will be reviewed
+and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

smellcheck-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing to smellcheck
+
+Thanks for your interest in contributing. smellcheck is a focused tool -- a zero-dependency Python code smell detector built entirely on stdlib. Contributions that preserve that simplicity are welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/cheickmec/smellcheck.git
+cd smellcheck
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+pip install pytest pre-commit
+pre-commit install
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+Self-check (smellcheck analyzing itself):
+
+```bash
+smellcheck src/smellcheck/ --min-severity warning
+```
+
+## Project structure
+
+```
+src/smellcheck/
+  detector.py    # The entire detector: AST visitor, cross-file analysis, CLI
+  __init__.py    # Public API + version
+  __main__.py    # python -m smellcheck
+```
+
+The detector is intentionally a single file. The code is tightly coupled (AST visitor + cross-file passes + output formatting) and works well as one unit. Don't split it into modules without a strong reason.
+
+## Adding a new smell check
+
+### Per-file check (AST-based)
+
+1. Add a `_check_<name>` method to the `SmellDetector` class
+2. Call it from the appropriate `visit_*` method (e.g., `visit_FunctionDef`, `visit_If`)
+3. Use `self._add(line, pattern, name, severity, message, category)` to report findings
+4. Pattern format: `#NNN` for numbered patterns (e.g., `#071`), `#ABC` for named patterns
+5. Add a test in `tests/test_detector.py`
+
+Example:
+
+```python
+def _check_too_many_returns(self, node: ast.FunctionDef | ast.AsyncFunctionDef):
+    """#071 -- Function with too many return statements."""
+    returns = [n for n in ast.walk(node) if isinstance(n, ast.Return)]
+    if len(returns) > 5:
+        self._add(node.lineno, "#071", "Too Many Returns", "info",
+                  f"`{node.name}` has {len(returns)} return statements",
+                  "functions")
+```
+
+### Cross-file check
+
+1. Add a `_detect_<name>(all_data: list[FileData]) -> list[Finding]` function
+2. Call it from `cross_file_analysis()`
+3. If you need new per-file metadata, add fields to `FileData` and populate them in `SmellDetector`
+
+### Thresholds
+
+Configurable thresholds live at the top of `detector.py` as `Final` constants. If your check has a numeric threshold, add it there.
+
+## Code style
+
+- **Zero dependencies.** Do not add imports beyond Python stdlib. This is a hard rule.
+- **Python 3.10+.** Use `|` unions, pattern matching, modern features.
+- **Type hints** on all public functions.
+- No linter is configured in the repo yet, but keep style consistent with the existing code.
+
+## Commit messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add #071 too-many-returns check
+fix: false positive in #058 with ExitStack
+test: add regression test for elif duplicate findings
+docs: update README with new check
+```
+
+Scopes are optional but helpful: `feat(detector):`, `fix(cli):`, `test(regression):`.
+
+## Pull requests
+
+1. Create a feature branch from `main`
+2. Make your changes with tests
+3. Ensure `pytest tests/ -v` passes (all tests, including version parity)
+4. Open a PR against `main`
+
+The PR template will guide you through the checklist.
+
+## Reporting bugs
+
+Use the [bug report template](https://github.com/cheickmec/smellcheck/issues/new?template=bug_report.md). Include:
+
+- The Python code that triggered the issue
+- Expected vs. actual output
+- Your Python version
+
+## Suggesting new checks
+
+Open a [feature request](https://github.com/cheickmec/smellcheck/issues/new?template=feature_request.md). Describe:
+
+- What code pattern the check would detect
+- Why it's a smell (reference to Fowler, Contieri, or other literature is a plus)
+- Before/after examples

smellcheck-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cheick Berthe
+
+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.