ballpython 2.0.2__py3-none-any.whl → 2.0.4__py3-none-any.whl

ballpython-2.0.4.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: ballpython
+Version: 2.0.4
+Summary: The Ultimate Static Python Intelligence, Healing, Type Verification, and Security Suite
+Author: Developer
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ruff>=0.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: isort>=5.13.0; extra == "dev"
+Provides-Extra: security
+Requires-Dist: cryptography>=41.0.0; extra == "security"
+Requires-Dist: defusedxml>=0.7.1; extra == "security"
+
+# ballpython
+
+[![PyPI version](https://img.shields.io/pypi/v/ballpython.svg)](https://pypi.org/project/ballpython/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/ballpython.svg)](https://pypi.org/project/ballpython/)
+[![CI](https://github.com/moonrox420/ball-python/actions/workflows/ci.yml/badge.svg)](https://github.com/moonrox420/ball-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**The zero-config Python code cleaner, syntax healer, and quality suite.**
+
+`ballpython` automatically repairs broken syntax, resolves missing imports, prunes dead code, scans for security vulnerabilities, and formats your code in a single command. Zero LLM dependencies, 100% offline, and fast.
+
+Both `ballpython` and `pycleaner` CLI commands are identical.
+
+---
+
+## Installation
+
+```bash
+pip install ballpython
+```
+
+---
+
+## Quickstart
+
+### 1. Fix and format your code
+Run `ballpython` on any file or directory. It automatically heals syntax errors, resolves missing imports, removes unused variables, and applies canonical formatting:
+
+```bash
+ballpython .
+```
+
+### 2. Check code in CI (Dry Run)
+Check for syntax errors, security vulnerabilities, dead code, and linting violations without modifying any files on disk:
+
+```bash
+ballpython check .
+```
+
+---
+
+## What It Does Automatically
+
+When you run `ballpython`, all engines run under the hood in one pass:
+
+* **Syntax Healing:** Repairs missing statement colons (`def`, `class`, `if`), accidental `=` assignments in conditionals, unclosed parentheses/brackets, tab/space mixups, and legacy Python 2 except/print statements.
+* **Smart Import Resolution:** Resolves undefined symbols to standard library modules and common aliases, inserts `TYPE_CHECKING` guards, and prunes unused imports.
+* **Formatting & Modernization:** Formats code to PEP 8 standards (powered by `ruff`), modernizes legacy type annotations (PEP 585/604), and removes redundant `object` inheritance.
+* **Dead Code Pruning:** Discovers and eliminates unreachable code, empty pass blocks, and unused private definitions.
+* **Security & Taint Audit:** Detects hardcoded API secrets, SQL/command injection patterns, and unsafe `eval`/`exec`/`pickle` calls.
+* **Type Verification:** Verifies function call signatures against bundled Typeshed stubs.
+
+---
+
+## Pre-Commit Hook
+
+Add `ballpython` to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/moonrox420/ball-python
+    rev: v2.0.4
+    hooks:
+      - id: pycleaner
+        args: ["check"]
+```
+
+---
+
+## Configuration
+
+Optional configuration can be placed in `pyproject.toml` under `[tool.pycleaner]`:
+
+```toml
+[tool.pycleaner]
+exclude = ["migrations/", "generated/"]
+line-length = 88
+```
+
+---
+
+## License
+
+MIT License.

{ballpython-2.0.2.dist-info → ballpython-2.0.4.dist-info}/RECORD

@@ -2,11 +2,11 @@ ballpython/__init__.py,sha256=d8ONxgaz9jml_fHPVvg867Vt5jGRhGTqzWPtux3WJOc,206
 ballpython/__main__.py,sha256=aCRr0vnZfKYHDrPHBsYSjX5xTxtFJpTTSPVUSZTBK-I,136
 ballpython/cli.py,sha256=LllCLRAQQ-fRR_lIXwmd2e3Q7DLCIvf-5jHBXsAhJWs,125
 ballpython/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pycleaner/__init__.py,sha256=GMc3bYj3wg2AM_SZn_MRDq4i0f0PTaVq_ITR5spiOgI,2894
+pycleaner/__init__.py,sha256=AbIZyqCYVTi-fjqPCgWZmTeSth_8ma-8sYbl9SghNnQ,2894
 pycleaner/__main__.py,sha256=8QBFrPyxId563F6cipPMNVEBTG8TIZUgxQfp8gk1VSI,135
 pycleaner/baseline.py,sha256=DS32C8_G8khYYNJo42FVv6Cc58lJj7NUmPOzWNfQwlU,3856
 pycleaner/cache.py,sha256=WhCiMkuL6ryWVr3l3XrYLLoI7A3bRF8jNxpOyedNW8M,10761
-pycleaner/cli.py,sha256=NhMMmLcf7RMuKjc0rjCmSGYn5ns_yib2rUbXRJDVaYY,73034
+pycleaner/cli.py,sha256=MMK0U57pam-FuvB1UL7jwVk7m9Z_Cosuwuu5FIfrPp0,73029
 pycleaner/complexity_analyzer.py,sha256=uGC40cHCcr1tshzfIUw56sodEDySMFR3kGmjo7nq_1c,14977
 pycleaner/config.py,sha256=XhloyaY_9pdwbQuc3QaAPCerLeXz-i1da4xT50h-pjY,8514
 pycleaner/dead_code_detector.py,sha256=1DwtBSZL1ug1OI9-6jcJyxkhqHmJ0F8ZR19POI2zO3c,26549
@@ -18,17 +18,17 @@ pycleaner/linter_formatter.py,sha256=LB5j66OCASU8WG8QgRFpSX7C2c7_UNMBgkJh2hSWxAY
 pycleaner/modernizer.py,sha256=L9hxXXfdyTwf8itDO58y6bW5LobGo6dg8q537QdiYbM,12946
 pycleaner/pipeline.py,sha256=ZG7_9PNz0jBadFrZoiI7juLtUJXglGQhLgQhrLJqEac,20612
 pycleaner/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pycleaner/security_scanner.py,sha256=9mAWc8JxcWavwpJP9aYeiDSfzYrH1eZLmeZ54xRouOY,21841
+pycleaner/security_scanner.py,sha256=h7WSPYf40X-PBlJVOsJL-KaknDaOcWCMhcPwXkUvlbA,21986
 pycleaner/syntax_healer.py,sha256=TlIMKIJhaX9GED3e2JNzNMJ5aXmL9eLJMCu7xKSjdv8,26711
 pycleaner/taint_engine.py,sha256=96cZdDpSPbo5b13zIZY18f_4GJm_tw0clqCZMBtjXMQ,26481
 pycleaner/test_generator.py,sha256=TJsNJSojc6eIsaKZkwMlpnb-MKHuDpNLZCPnMlO-a8M,19663
 pycleaner/type_checker.py,sha256=h09QI_8MRHv83s23myjSYFdMTsWoQ900ffBJHtRuhmE,34087
 pycleaner/typeshed_resolver.py,sha256=N-kWU_CI5DG59lQMkt7wMW9sHYjNCBdfFS42b4y2Kr4,12742
 pycleaner/verifier.py,sha256=pOfSLRNHe4qDUYJG8mxDxjY6Ph8QKBdJZmqBtoJX87w,17937
-pycleaner/frameworks/__init__.py,sha256=7MLgg469hCNtQR6dsE5gZcAZkCywJHz9zOPrbH8NmrE,3415
-pycleaner/frameworks/plugins.py,sha256=K3J4mVJw2MR_pa6Mhmo5oZOX8pUesL8lx9LUo4RLrNo,9390
-ballpython-2.0.2.dist-info/METADATA,sha256=tpostFTk54cwmBz56dghrw0fOAZVcsJPKA1N9NMUtZ4,12459
-ballpython-2.0.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-ballpython-2.0.2.dist-info/entry_points.txt,sha256=6ux-5UxoVSmlK5p9M-GDVt24sCdwTQq9wgRDkpMIYU8,81
-ballpython-2.0.2.dist-info/top_level.txt,sha256=u6lmy8RWZ_saxCZAQTL7EijB4sunegOiVyk5fHjpwLk,21
-ballpython-2.0.2.dist-info/RECORD,,
+pycleaner/frameworks/__init__.py,sha256=-W24zqvug8eUkkwqla5oh7rFOqQR-WI4TohQhbXGYoo,3472
+pycleaner/frameworks/plugins.py,sha256=sMhP9mZ82sx10OI3opgXIEPXNAWFZRe2I__6yh2Uq_E,11453
+ballpython-2.0.4.dist-info/METADATA,sha256=vIeFxyxog9s1kF_UlbDp4yJg-UCiSho2HQe3qhC4odE,3466
+ballpython-2.0.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ballpython-2.0.4.dist-info/entry_points.txt,sha256=6ux-5UxoVSmlK5p9M-GDVt24sCdwTQq9wgRDkpMIYU8,81
+ballpython-2.0.4.dist-info/top_level.txt,sha256=u6lmy8RWZ_saxCZAQTL7EijB4sunegOiVyk5fHjpwLk,21
+ballpython-2.0.4.dist-info/RECORD,,

pycleaner/__init__.py

@@ -18,7 +18,7 @@ from pycleaner.discovery import (
     is_protected_file,
 )
 
-__version__ = "2.0.2"
+__version__ = "2.0.4"
 __all__ = [
     "BaselineFingerprint",
     "BaselineManager",

pycleaner/cli.py

@@ -567,7 +567,7 @@ def _resolve_cli_command(args: argparse.Namespace) -> str:
         return "all"
     if getattr(args, "check", False):
         return "check"
-    return "ultimate"
+    return "fix"
 
 
 def _run_all_command(

pycleaner/frameworks/__init__.py

@@ -103,6 +103,7 @@ def get_default_registry() -> FrameworkRegistry:
         FastAPIPlugin,
         PydanticPlugin,
         PytestPlugin,
+        PyTorchPlugin,
         SQLAlchemyPlugin,
     )
 
@@ -112,4 +113,5 @@ def get_default_registry() -> FrameworkRegistry:
     reg.register(FastAPIPlugin())
     reg.register(SQLAlchemyPlugin())
     reg.register(DataclassPlugin())
+    reg.register(PyTorchPlugin())
     return reg

pycleaner/frameworks/plugins.py

@@ -2,7 +2,7 @@
 pycleaner.frameworks.plugins
 ============================
 
-Concrete Framework Plugins for Pydantic, Pytest, FastAPI, SQLAlchemy, and Dataclasses.
+Concrete Framework Plugins for Pydantic, Pytest, FastAPI, SQLAlchemy, Dataclasses, and PyTorch.
 """
 
 from __future__ import annotations
@@ -50,15 +50,18 @@ class PydanticPlugin:
         for node in ast.walk(tree):
             if isinstance(node, ast.Import):
                 for alias in node.names:
-                    if alias.name.split(".")[0] == "pydantic":
+                    if alias.name.split(".")[0] in ("pydantic", "pydantic_settings"):
                         return True
             elif isinstance(node, ast.ImportFrom):
-                if node.module and node.module.split(".")[0] == "pydantic":
+                if node.module and node.module.split(".")[0] in (
+                    "pydantic",
+                    "pydantic_settings",
+                ):
                     return True
         return False
 
     def get_protected_names(self, tree: ast.AST) -> set[str]:
-        return {"model_config", "Config", "ConfigDict"}
+        return {"model_config", "Config", "ConfigDict", "model_post_init"}
 
     def get_protected_decorators(self) -> set[str]:
         return self._VALIDATOR_DECORATORS
@@ -288,3 +291,74 @@ class DataclassPlugin:
         tree: ast.AST,
     ) -> bool:
         return name in self.get_protected_names(tree)
+
+
+class PyTorchPlugin:
+    """Understands PyTorch nn.Module, LightningModule, HuggingFace models, and datasets."""
+
+    name = "pytorch"
+    _MODULE_BASES = {
+        "Module",
+        "LightningModule",
+        "PreTrainedModel",
+        "Dataset",
+        "IterableDataset",
+        "Sampler",
+    }
+    _PROTECTED_METHODS = {
+        "forward",
+        "backward",
+        "training_step",
+        "validation_step",
+        "test_step",
+        "predict_step",
+        "configure_optimizers",
+        "optimizer_step",
+        "compute_loss",
+        "reset_parameters",
+        "extra_repr",
+        "state_dict",
+        "load_state_dict",
+        "collate_fn",
+    }
+
+    def is_applicable(self, tree: ast.AST, filepath: Path | str) -> bool:
+        torch_pkgs = {
+            "torch",
+            "torchvision",
+            "torchaudio",
+            "pytorch_lightning",
+            "lightning",
+            "transformers",
+            "accelerate",
+            "timm",
+        }
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name.split(".")[0] in torch_pkgs:
+                        return True
+            elif isinstance(node, ast.ImportFrom):
+                if node.module and node.module.split(".")[0] in torch_pkgs:
+                    return True
+        return False
+
+    def get_protected_names(self, tree: ast.AST) -> set[str]:
+        return self._PROTECTED_METHODS
+
+    def get_protected_decorators(self) -> set[str]:
+        return set()
+
+    def is_protected_field(self, node: ast.AST, class_node: ast.ClassDef) -> bool:
+        return _has_base_named(class_node, self._MODULE_BASES)
+
+    def should_ignore_definition(
+        self,
+        name: str,
+        kind: str,
+        node: ast.AST,
+        context: str,
+        tree: ast.AST,
+    ) -> bool:
+        return name in self._PROTECTED_METHODS
+

pycleaner/security_scanner.py

@@ -196,9 +196,14 @@ class _DangerousCallDetector(ast.NodeVisitor):
             return self.source_lines[lineno - 1].strip()
         return ""
 
-    def _is_suppressed(self, lineno: int, category: str) -> bool:
-        if 1 <= lineno <= len(self.source_lines):
-            line = self.source_lines[lineno - 1]
+    def _is_suppressed(
+        self, lineno: int, category: str, end_lineno: int | None = None
+    ) -> bool:
+        start = max(1, lineno)
+        end = max(start, end_lineno or lineno)
+        max_line = len(self.source_lines)
+        for ln in range(start, min(end + 1, max_line + 1)):
+            line = self.source_lines[ln - 1]
             if "#" in line:
                 comment = line.split("#", 1)[1].strip().lower()
                 if (
@@ -208,21 +213,21 @@ class _DangerousCallDetector(ast.NodeVisitor):
                     or f"ignore[{category.lower()}]" in comment
                 ):
                     return True
-            if lineno > 1:
-                prev_line = self.source_lines[lineno - 2]
-                if prev_line.strip().startswith("#"):
-                    prev_comment = prev_line.strip().lstrip("#").strip().lower()
-                    if (
-                        "nosec" in prev_comment
-                        or "noqa" in prev_comment
-                        or "pycleaner: ignore" in prev_comment
-                        or f"ignore[{category.lower()}]" in prev_comment
-                    ):
-                        return True
+        if start > 1:
+            prev_line = self.source_lines[start - 2]
+            if prev_line.strip().startswith("#"):
+                prev_comment = prev_line.strip().lstrip("#").strip().lower()
+                if (
+                    "nosec" in prev_comment
+                    or "noqa" in prev_comment
+                    or "pycleaner: ignore" in prev_comment
+                    or f"ignore[{category.lower()}]" in prev_comment
+                ):
+                    return True
         return False
 
     def _add_finding(self, finding: SecurityFinding) -> None:
-        if not self._is_suppressed(finding.lineno, finding.category):
+        if not self._is_suppressed(finding.lineno, finding.category, finding.end_lineno):
             self.findings.append(finding)
 
     def visit_Call(self, node: ast.Call) -> None:

ballpython-2.0.2.dist-info/METADATA

@@ -1,328 +0,0 @@
-Metadata-Version: 2.4
-Name: ballpython
-Version: 2.0.2
-Summary: The Ultimate Static Python Intelligence, Healing, Type Verification, and Security Suite
-Author: Developer
-License-Expression: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: ruff>=0.1.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: tomli>=1.1.0; python_version < "3.11"
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0.0; extra == "dev"
-Requires-Dist: black>=24.0.0; extra == "dev"
-Requires-Dist: isort>=5.13.0; extra == "dev"
-Provides-Extra: security
-Requires-Dist: cryptography>=41.0.0; extra == "security"
-Requires-Dist: defusedxml>=0.7.1; extra == "security"
-
-# pycleaner — Ultimate Static Python Code Quality Suite
-
-A production-grade, offline Python static analysis, syntax healing, linting, formatting, security scanning, complexity evaluation, dead code detection, and dependency auditing suite.
-
-Zero external LLM dependencies, zero mock modes, and built for deterministic developer workflows and CI/CD pipelines.
-
----
-
-## Key Capabilities
-
-1. **Syntax Healer (`SyntaxHealer`)**:
-   - Statically repairs missing colons on compound statement headers (`def`, `class`, `if`, `elif`, `else`, `for`, `while`, `try`, `except`, `finally`, `with`, `async def`, `match`, `case`).
-   - Corrects accidental single `=` assignments in conditionals (`if x = 1:` $\to$ `if x == 1:`) without corrupting keyword arguments (`func(x=1)`), augmented assignments, or walrus expressions (`x := 1`).
-   - Modernizes legacy Python 2 statements (`print "..."` $\to$ `print(...)`, `except Error, e:` $\to$ `except Error as e:`, and multi-exception tuples `except (E1, E2), e:` on Python 3.12+).
-   - Automatically closes unclosed parentheses, brackets, and braces.
-   - Normalizes mixed tab characters into 4 spaces.
-
-2. **Missing Import Resolver (`ImportResolver`)**:
-   - Walks Python AST to extract undefined loaded symbols across local, function, class, and comprehension scopes.
-   - Resolves undefined identifiers to standard library modules (`os`, `sys`, `json`, `re`, `subprocess`, `pathlib`, etc.), collections, typing constructs, dataclasses, concurrent primitives (`ThreadPoolExecutor`, `ProcessPoolExecutor`, `Lock`, `Queue`), and popular aliases (`np`, `pd`, `plt`, `sns`, `tf`, `nn`).
-   - **`TYPE_CHECKING` Awareness**: Injects typing-only imports into `if TYPE_CHECKING:` guards and adds `from __future__ import annotations` when symbols are used strictly in type annotations.
-   - **Custom Import Mapping**: Configurable mapping from symbol names to exact import statements.
-
-3. **Linter & Formatter (`LinterFormatter`)**:
-   - Integrates Rust-based `ruff` via in-memory stream processing (`--stdin-filename`).
-   - Automatically removes unused imports (`F401`) and unused variables (`F841`).
-   - Sorts and groups imports via `isort` / `ruff` or an internal pure-Python 3-tier sorter (stdlib $\to$ third-party $\to$ local).
-   - Modernizes deprecated syntax via `pyupgrade` (`UP`).
-   - Applies deterministic PEP 8 formatting (`ruff format` / `black` / pure-Python formatter).
-   - Wraps long `from ... import (...)` statements exceeding configured `line-length`.
-   - Modernizes legacy typing to PEP 585/604 syntax (`List[T]` -> `list[T]`, `Optional[T]` -> `T | None`), singleton comparisons, and `class X(object)` inheritance via `Modernizer` (disable with `--no-modernize`).
-
-4. **Dead Code Detector (`DeadCodeDetector`)**:
-   - Builds a cross-file symbol definition and reference graph across a project.
-   - Identifies unused functions, methods, classes, module-level constants, and class attributes.
-   - Respects public exports in `__all__` and framework decorators (`@app.route`, `@pytest.fixture`, `@abstractmethod`, etc.).
-   - Detects unreachable code following unconditional `return`, `raise`, `break`, `continue`, or `sys.exit()`.
-   - Identifies empty pass blocks with no comments.
-   - Auto-prunes unreachable code, redundant `pass` statements, and `if False:` branches via `DeadCodeFixer` (enable with `dead-code --fix`, disable in the pipeline with `--no-dead-code`).
-
-5. **Static Security Scanner (`SecurityScanner`)**:
-   - Detects dangerous function calls: `eval()`, `exec()`, `compile()`, `pickle.loads()`, `os.system()`, and unsafe `yaml.load()` lacking `SafeLoader`.
-   - Flags SQL injection patterns (string concatenation, f-strings, `%`-formatting, or `.format()` inside `cursor.execute()`).
-   - Flags subprocess command injection (`shell=True`).
-   - Flags insecure transport (`verify=False` in `requests` or `httpx`).
-   - Scans for hardcoded secrets: AWS access/secret keys, GitHub tokens, Slack tokens, JWT tokens, private key headers, and generic passwords/API keys.
-   - Flags production `assert` statements used for input validation (which get stripped under `python -O`).
-
-6. **Complexity Analyzer (`ComplexityAnalyzer`)**:
-   - McCabe Cyclomatic Complexity per function ($E - N + 2$).
-   - Sonar-style Cognitive Complexity scoring (penalizing nested control flow, compound boolean conditions, and break in linear flow).
-   - Metrics tracked: line count, argument count, return statement count, and maximum nesting depth.
-   - Configurable thresholds with tabular and JSON reporting.
-
-7. **Dependency Auditor (`DependencyAuditor`)**:
-   - Statically scans all `.py` files across a repository to discover external third-party imports.
-   - Maps module import names to PyPI distribution package names (e.g., `yaml` $\to$ `PyYAML`, `PIL` $\to$ `pillow`, `cv2` $\to$ `opencv-python`).
-   - Compares imported dependencies against `requirements.txt` and `pyproject.toml`.
-   - Synchronizes `requirements.txt` with `--fix-deps` and prunes unused packages with `--prune-deps`.
-
-8. **Safety & Concurrency**:
-   - Backup creation (`.pycleaner.bak`) before overwriting files (enabled by default).
-   - Parallel multi-core file processing via `ProcessPoolExecutor`.
-   - Continuous file watching (`watch` mode) with automatic re-healing on save.
-   - Pre-commit configuration generator (`hook` subcommand).
-
----
-
-## Installation
-
-```bash
-# Editable install
-pip install -e .
-
-# Core dependencies
-pip install ruff rich
-
-# Optional security and development packages
-pip install -e ".[dev,security]"
-```
-
----
-
-## CLI Usage
-
-### Subcommands
-
-#### `fix` (Default Action)
-Heals syntax, modernizes legacy typing (PEP 585/604), prunes dead code, resolves imports, fixes lint violations, and formats code:
-```bash
-py -m pycleaner fix src/
-py -m pycleaner fix --diff path/to/script.py
-py -m pycleaner fix --no-backup src/
-py -m pycleaner fix --parallel --workers 4 src/
-py -m pycleaner fix --no-modernize --no-dead-code src/
-```
-
-#### `check` (Dry-Run CI Verification)
-Inspects files without writing modifications to disk. Exits with code `1` if changes or errors are detected:
-```bash
-py -m pycleaner check src/
-py -m pycleaner check --diff src/
-```
-
-#### `scan` (Security Vulnerability Audit)
-Scans Python files for hardcoded secrets, dangerous calls, and injection vulnerabilities:
-```bash
-py -m pycleaner scan .
-py -m pycleaner scan --severity HIGH .
-py -m pycleaner scan --json .
-```
-
-#### `complexity` (Function Complexity Metrics)
-Calculates Cyclomatic Complexity, Cognitive Complexity, and architectural metrics:
-```bash
-py -m pycleaner complexity .
-py -m pycleaner complexity --max-cyclomatic 10 --max-cognitive 15 .
-py -m pycleaner complexity --json .
-```
-
-#### `dead-code` (Unused Symbols & Unreachable Branches)
-Finds unused functions, unused classes, empty pass branches, and dead code:
-```bash
-py -m pycleaner dead-code .
-py -m pycleaner dead-code --json .
-py -m pycleaner dead-code --fix .
-```
-
-#### `audit` (Project Dependency Verification)
-Audits imported third-party libraries against `requirements.txt`:
-```bash
-# Audit only
-py -m pycleaner audit .
-
-# Automatically append missing dependencies
-py -m pycleaner audit --fix-deps .
-
-# Append missing and remove unimported dependencies
-py -m pycleaner audit --fix-deps --prune-deps .
-```
-
-#### `all` (Complete Quality Sweep)
-Executes all engines in one command (fix + dependency audit + security scan + complexity + dead code):
-```bash
-py -m pycleaner all .
-```
-
-#### `watch` (Continuous File Watcher)
-Watches files for filesystem modifications and auto-cleans on save:
-```bash
-py -m pycleaner watch src/ --interval 1.0
-```
-
-#### `hook` (Pre-Commit Integration)
-Outputs a ready-to-use `.pre-commit-hooks.yaml` configuration block:
-```bash
-py -m pycleaner hook
-```
-
----
-
-### Backward-Compatible Flat Invocations
-
-Legacy invocations continue to work seamlessly:
-```bash
-pycleaner -a .                     # Equivalent to: pycleaner all .
-pycleaner --check --diff src/      # Equivalent to: pycleaner check --diff src/
-pycleaner --deps-only .            # Equivalent to: pycleaner audit .
-pycleaner path/to/file.py          # Equivalent to: pycleaner fix path/to/file.py
-```
-
----
-
-## Configuration
-
-`pycleaner` automatically reads configuration from `pyproject.toml` under `[tool.pycleaner]` or from `.pycleaner.toml`. An explicit file can be forced with `pycleaner --config path/to/pyproject.toml <command> ...`, which overrides target-path auto-discovery.
-
-### `pyproject.toml` Example
-
-```toml
-[tool.pycleaner]
-# File targeting
-exclude = ["migrations/", "generated/", "*_pb2.py", "*_pb2_grpc.py"]
-include = ["src/", "tests/"]
-
-# Syntax healing
-fix-py2-syntax = true
-fix-conditional-assignments = true
-
-# Import resolution
-custom-import-map = { "logger" = "from myapp.core.logging import logger" }
-auto-add-future-annotations = false
-
-# Linting & formatting
-line-length = 88
-select-rules = "F401,F841,I,UP,E,W,B,SIM,RUF"
-
-# Dead code
-ignore-decorators = ["@app.route", "@pytest.fixture", "@override"]
-ignore-names = ["_*", "test_*"]
-
-# Security
-security-severity-threshold = "LOW"
-ignore-security-rules = []
-
-# Complexity thresholds
-max-cyclomatic-complexity = 10
-max-cognitive-complexity = 15
-max-function-length = 50
-max-arguments = 5
-
-# Behavior
-backup = true
-parallel = false
-max-workers = 4
-```
-
----
-
-## Programmatic API
-
-### 1. Cleaning Source Code or Files
-```python
-from pathlib import Path
-from pycleaner import CleanPipeline, load_config
-
-# Load config with project overrides
-config = load_config(project_root=".")
-pipeline = CleanPipeline(config=config)
-
-# In-memory code processing
-dirty_code = """
-import math
-
-def calculate(x)
-    if x = 0
-        return Path('.')
-    return Path(str(x))
-"""
-result = pipeline.process_source(dirty_code, filename="example.py")
-print("Cleaned code:\n", result.cleaned_code)
-print("Repairs applied:", result.syntax_repairs)
-print("Imports added:", result.resolved_imports)
-
-# File processing with automatic backup
-file_result = pipeline.process_file("example.py", apply_changes=True, backup=True)
-```
-
-### 2. Security Vulnerability Scanning
-```python
-from pycleaner import SecurityScanner
-
-scanner = SecurityScanner(severity_threshold="MEDIUM")
-report = scanner.scan_project("src/")
-
-for finding in report.findings:
-    print(f"[{finding.severity}] {finding.category} at {finding.filepath}:{finding.lineno}")
-    print(f"  Message: {finding.message}")
-    print(f"  Fix: {finding.suggestion}")
-```
-
-### 3. Complexity Analysis
-```python
-from pycleaner import ComplexityAnalyzer
-
-analyzer = ComplexityAnalyzer()
-report = analyzer.analyze_project("src/")
-
-print(f"Scanned {report.files_scanned} files, {report.count} functions.")
-print(f"Average Cyclomatic: {report.average_cyclomatic:.2f}")
-
-violations = report.above_threshold(max_cyclomatic=10, max_cognitive=15)
-for func in violations:
-    print(f"{func.qualified_name} (CC={func.cyclomatic}, Cog={func.cognitive})")
-```
-
-### 4. Dead Code Detection
-```python
-from pycleaner import DeadCodeDetector
-
-detector = DeadCodeDetector()
-report = detector.scan_project("src/")
-
-print(f"{report.count} dead code item(s) across {report.files_scanned} file(s).")
-
-for item in report.items:
-    print(f"Dead {item.kind} '{item.name}' at {item.filepath}:{item.lineno}")
-
-for item in report.by_kind("unreachable"):
-    print(f"Unreachable code at {item.filepath}:{item.lineno} ({item.reason})")
-```
-
----
-
-## Exit Codes
-
-| Exit Code | Meaning |
-|:---:|:---|
-| `0` | Clean run: all files valid, no errors, or changes cleanly written |
-| `1` | Issues found: check mode detected modifications, errors occurred, or critical security findings flagged |
-| `2` | Configuration error: invalid TOML syntax, invalid configuration keys, or mismatched types |
-
----
-
-## License
-
-MIT License.
-# ball-python
-# ball-python