riskratchet 0.1.0__tar.gz

riskratchet-0.1.0/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+coverage.json
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# riskratchet artifacts
+.riskratchet.json
+
+# Local-only operational scripts (not for the package)
+scripts/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

riskratchet-0.1.0/LICENSE

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

riskratchet-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: riskratchet
+Version: 0.1.0
+Summary: A maintainability ratchet for AI-assisted Python.
+Project-URL: Homepage, https://github.com/KayhanB21/riskratchet
+Project-URL: Source, https://github.com/KayhanB21/riskratchet
+Author-email: Kayhan Babaee <me@kayhan.dev>
+License: MIT License
+        
+        Copyright (c) 2026 Kayhan
+        
+        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.
+License-File: LICENSE
+Keywords: code-quality,complexity,coverage,crap,maintainability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: coverage>=7.4
+Requires-Dist: radon>=6.0.1
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# riskratchet
+
+A maintainability ratchet for AI-assisted Python.
+
+riskratchet computes a function-level risk score from coverage gaps,
+cyclomatic complexity, churn, public surface, and sprawl signals, then fails
+when a change pushes risk upward without adding tests. Use it as a CLI, in
+pre-commit, or in CI so AI-assisted commits can land working code without
+ratcheting up untested complexity.
+
+## Quickstart
+
+```bash
+uvx riskratchet scan src --coverage coverage.json
+uvx riskratchet baseline src --coverage coverage.json --output .riskratchet.json
+uvx riskratchet check src --coverage coverage.json --baseline .riskratchet.json
+```
+
+## Local development
+
+```bash
+uv sync
+uv run pytest
+uv run riskratchet scan src --coverage coverage.json
+```
+
+This package is in early development. See PLAN.md for the v1 roadmap.

riskratchet-0.1.0/PLAN.md

@@ -0,0 +1,399 @@
+# riskratchet Package Plan
+
+## Summary
+
+Build `riskratchet` as a Python maintainability ratchet for AI-assisted development: agents can change code, but CI/pre-commit/pytest should fail when a change increases untested complexity or maintainability risk.
+
+V1 will be a standalone CLI with pre-commit and pytest integrations. The core will compute a full function-level risk score using complexity, coverage gaps, churn, public surface area, and sprawl signals. It will also expose the classic CRAP score for familiarity, but the product framing is broader: "do not let AI-assisted changes ratchet risk upward."
+
+Use **uv as the package manager and developer workflow**. The repo should commit `uv.lock` for reproducible development and CI.
+
+## Key Design
+
+- Package name: `riskratchet`
+- Tagline: `A maintainability ratchet for AI-assisted Python.`
+- Python support: `>=3.10`
+- Packaging: `pyproject.toml` with `hatchling`
+- Package/dependency workflow: `uv`
+- Commit:
+  - `pyproject.toml`
+  - `uv.lock`
+  - `.python-version` only if the project wants to pin local dev Python
+- Runtime dependencies:
+  - `radon` for cyclomatic complexity
+  - `coverage` JSON input compatibility, parsed directly
+  - `typer` for CLI
+  - `rich` for terminal output
+- Dev dependencies:
+  - `pytest`
+  - `pytest-cov`
+  - `ruff`
+  - `mypy`
+  - `pre-commit`
+  - `hypothesis`
+
+Developer commands:
+
+```bash
+uv sync
+uv run riskratchet --help
+uv run pytest
+uv run ruff check .
+uv run mypy src tests
+uv build
+```
+
+Public commands:
+
+```bash
+riskratchet scan src --coverage coverage.json
+riskratchet baseline src --coverage coverage.json --output .riskratchet.json
+riskratchet check src --coverage coverage.json --baseline .riskratchet.json
+riskratchet explain src/pkg/file.py::function_name --coverage coverage.json
+```
+
+V1 outputs:
+
+```bash
+--format table
+--format json
+--format markdown
+```
+
+V1 integrations:
+
+```bash
+pytest --riskratchet --riskratchet-baseline .riskratchet.json
+```
+
+```yaml
+repos:
+  - repo: https://github.com/KayhanB21/riskratchet
+    rev: v0.1.0
+    hooks:
+      - id: riskratchet
+        args: ["check", "src", "--coverage", "coverage.json", "--baseline", ".riskratchet.json"]
+```
+
+## Scoring Model
+
+Analyze at function/method level. Each finding includes file, qualified function name, line span, risk score, CRAP score, component scores, and concrete remediation hints.
+
+Core inputs:
+
+- Function spans from Python AST
+- Cyclomatic complexity from `radon`
+- Coverage from `coverage json`
+- Branch coverage mapped to function line spans
+- Git churn from local git history when available
+- Public surface detection from exported/importable names and underscore naming
+- File sprawl from file length and function length
+
+For each function, compute:
+
+```text
+risk_score =
+  0.30 * coverage_gap_score +
+  0.25 * structural_complexity_score +
+  0.15 * branch_gap_score +
+  0.10 * churn_score +
+  0.10 * public_surface_score +
+  0.10 * sprawl_score
+```
+
+Also compute classic CRAP:
+
+```text
+CRAP = CC^2 * (1 - line_coverage)^3 + CC
+```
+
+Default severity:
+
+```text
+0-24    low
+25-49   medium
+50-74   high
+75-100  critical
+```
+
+Default check behavior:
+
+- `scan`: never fails; reports current risk.
+- `baseline`: writes full baseline JSON.
+- `check`: fails if any function's risk increases beyond tolerance, or if a new function appears above the configured high-risk threshold.
+- Default tolerance: `+5` risk points to avoid noise.
+- Default new-function threshold: `50`.
+- Existing high-risk code is allowed if it does not get worse.
+
+Measured thermo-nuclear signals in v1:
+
+- File over 1000 lines
+- Function over 80 logical lines
+- High nesting depth
+- High boolean-condition density
+- Many exception handlers or returns
+- Churn-heavy functions
+- Public functions with weak coverage
+- Complex functions with missing branch coverage
+
+Keep subjective "strict review" prose out of the numeric score in v1. Use direct remediation text like:
+
+```text
+High risk because complexity=14, branch coverage=38%, churn=7 commits.
+Add tests for missing branches or split this function before changing it further.
+```
+
+## Implementation Breakdown
+
+### Phase 1: uv Scaffold And Core Contracts
+
+Create a typed Python package using uv:
+
+```bash
+uv init --package --name riskratchet
+uv add radon coverage typer rich
+uv add --dev pytest pytest-cov ruff mypy pre-commit hypothesis
+uv lock
+```
+
+Use this project layout:
+
+```text
+src/riskratchet/
+  __init__.py
+  cli.py
+  analysis.py
+  coverage.py
+  complexity.py
+  git.py
+  scoring.py
+  baseline.py
+  reporting.py
+  pytest_plugin.py
+tests/
+  fixtures/
+```
+
+Core boundaries:
+
+- `analysis`: AST function discovery, file metrics, public surface detection
+- `coverage`: parse `coverage.json` and map line/branch data to function spans
+- `complexity`: wrap `radon` and normalize complexity signals
+- `git`: optional churn provider with a no-git fallback
+- `scoring`: pure risk and CRAP calculations
+- `baseline`: read/write/compare baseline JSON
+- `reporting`: table, JSON, and markdown renderers
+- `cli`: Typer commands only; no business logic
+- `pytest_plugin`: pytest entrypoint that delegates to the same core check path
+
+Core dataclasses:
+
+- `FunctionId`
+- `FunctionSpan`
+- `CoverageStats`
+- `ComplexityStats`
+- `RiskComponents`
+- `FunctionRisk`
+- `RiskReport`
+- `Baseline`
+- `Regression`
+
+All scoring functions must be pure and deterministic.
+
+### Phase 2: CLI
+
+Implement:
+
+```bash
+riskratchet scan PATH...
+riskratchet baseline PATH...
+riskratchet check PATH...
+riskratchet explain TARGET
+```
+
+Required options:
+
+```bash
+--coverage coverage.json
+--config pyproject.toml
+--format table|json|markdown
+--output path
+--fail-new-above 50
+--fail-regression-above 5
+--include PATTERN
+--exclude PATTERN
+--no-git
+```
+
+Config under `pyproject.toml`:
+
+```toml
+[tool.riskratchet]
+paths = ["src"]
+coverage = "coverage.json"
+baseline = ".riskratchet.json"
+fail_new_above = 50
+fail_regression_above = 5
+exclude = ["tests/**", "migrations/**", "*/generated/**"]
+```
+
+### Phase 3: Integrations
+
+Pre-commit:
+
+- Add `.pre-commit-hooks.yaml`
+- Hook runs `riskratchet check`
+- Document that users should generate coverage before the hook in CI, or use pre-commit mainly for local ratchet checks against an existing coverage artifact.
+
+Pytest:
+
+- Add a thin pytest plugin.
+- It should not duplicate the CLI logic.
+- It should read pytest/coverage output after tests finish, run the same core check, and fail pytest on regressions.
+- Keep plugin options minimal:
+  - `--riskratchet`
+  - `--riskratchet-baseline`
+  - `--riskratchet-fail-new-above`
+  - `--riskratchet-fail-regression-above`
+
+### Phase 4: Docs And Post Support
+
+README must include:
+
+- Why CRAP alone is useful but incomplete
+- Why AI-agent workflows need a maintainability ratchet
+- Quickstart using uv:
+
+```bash
+uvx riskratchet scan src --coverage coverage.json
+uvx riskratchet baseline src --coverage coverage.json --output .riskratchet.json
+uvx riskratchet check src --coverage coverage.json --baseline .riskratchet.json
+```
+
+- Local development using uv:
+
+```bash
+uv sync
+uv run pytest
+uv run riskratchet scan src --coverage coverage.json
+```
+
+- pre-commit example
+- pytest example
+- JSON and markdown output examples
+- Comparison table versus `pytest-crap`, `radon`, `coverage.py`, and `xenon`
+
+Post angle:
+
+```text
+Let Agents Write Code. Don't Let Them Ratchet Up Risk.
+```
+
+The post should show:
+
+- An AI agent adds working code.
+- Tests pass.
+- Coverage percentage looks acceptable.
+- `riskratchet` fails because branch/path risk or maintainability risk increased.
+- The fix is either adding meaningful tests or simplifying the function.
+
+## Test Plan
+
+Testability is a first-class design constraint. The implementation should be built around pure functions and fixture projects.
+
+Unit tests:
+
+- CRAP formula matches known examples.
+- Risk score component weighting is deterministic.
+- Severity thresholds classify correctly.
+- Function span discovery handles:
+  - nested functions
+  - methods
+  - async functions
+  - decorators
+  - class methods/static methods
+  - multiline signatures
+- Coverage mapping handles:
+  - fully covered functions
+  - uncovered functions
+  - partial line coverage
+  - missing branch coverage
+  - files absent from coverage JSON
+- Complexity mapping handles:
+  - radon blocks matched to AST spans
+  - syntax errors reported cleanly
+  - unsupported files skipped with warnings
+- Churn provider handles:
+  - normal git repo
+  - shallow/no-history repo
+  - no-git directory
+  - renamed/deleted files gracefully
+- Baseline comparison handles:
+  - new risky function
+  - improved risky function
+  - worsened existing function
+  - deleted function
+  - changed line numbers with same qualified function name
+  - tolerance boundary exactly
+
+CLI tests:
+
+- `scan` exits 0.
+- `baseline` writes stable JSON.
+- `check` exits 0 with no regression.
+- `check` exits non-zero with risk regression.
+- `--format json` validates against snapshot/schema.
+- `--format markdown` is stable enough for PR comments.
+- Invalid coverage path gives actionable error.
+- Invalid baseline gives actionable error.
+
+Integration tests:
+
+- Fixture package with pytest + coverage JSON.
+- pre-commit hook smoke test using a small fixture repo.
+- pytest plugin smoke test proving pytest exits non-zero on risk regression.
+
+Property-style tests:
+
+- Risk score is bounded 0-100.
+- Increasing coverage cannot increase coverage-gap score.
+- Increasing branch coverage cannot increase branch-gap score.
+- Increasing complexity cannot decrease structural-complexity score.
+- Baseline comparison is deterministic regardless of input ordering.
+
+Golden fixtures:
+
+- `simple_clean`
+- `complex_uncovered`
+- `covered_but_branchy`
+- `large_file_sprawl`
+- `public_api_regression`
+- `agent_generated_spaghetti`
+
+CI checks, all through uv:
+
+```bash
+uv sync --locked
+uv run ruff check .
+uv run mypy src tests
+uv run pytest
+uv run pytest --cov=riskratchet --cov-report=term-missing --cov-report=json
+uv run riskratchet scan src --coverage coverage.json --format json
+uv build
+```
+
+Target internal coverage for `riskratchet`: at least 90%, with focused branch coverage around scoring and baseline comparison.
+
+## Assumptions And Defaults
+
+- V1 is named `riskratchet`.
+- uv is the package manager and local dev workflow.
+- `uv.lock` is committed.
+- V1 is a standalone CLI first, but includes pre-commit and pytest integrations.
+- V1 implements the full risk score, not pure CRAP.
+- V1 keeps CRAP as a reported compatibility metric.
+- V1 supports table, JSON, and markdown output. SARIF is deferred.
+- V1 uses measured maintainability signals from the thermo-nuclear review idea, but does not ship subjective review prose as scoring logic.
+- V1 uses local git churn when available and falls back cleanly when git is unavailable.
+- V1 is strict about regressions, not existing legacy risk.
+- V1 should be small, typed, and heavily tested before optimizing for broad framework support.