codedoctor 0.1.0__tar.gz

codedoctor-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+  
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

codedoctor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Black
+        run: black . --check
+
+      - name: MyPy
+        run: mypy src
+
+      - name: Pytest
+        run: pytest -q

codedoctor-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build
+        run: |
+          python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  pypi:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release + upload artifacts
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*

codedoctor-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.codedoctor
+src/codedoctor/__pycache__/
+tests/__pycache__/

codedoctor-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/psf/black
+    rev: 26.1.0
+    hooks:
+      - id: black

codedoctor-0.1.0/LICENSE

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

codedoctor-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: codedoctor
+Version: 0.1.0
+Summary: Beginner-friendly codebase doctor: lint, format, type-check, security and tests.
+Author-email: Patrick Faint <pattymayo3@icloud.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.0; extra == 'dev'
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CodeDoctor - v0.1.0
+
+**CodeDoctor** is a beginner-friendly Python CLI that scans a repository and
+summarizes common quality checks (linting, formatting, typing, security, and
+tests) in one readable report.
+
+It can also generate a **TL;DR summary** at the top of the report and save
+results to a `.txt` report file so you can compare runs over time.
+
+---
+
+## What it checks
+
+Depending on what you have installed, CodeDoctor can run:
+
+- **ruff** — linting (and optional auto-fixes)
+- **black** — formatting (and optional formatting changes)
+- **mypy** — static type checking
+- **bandit** — basic security checks
+- **pytest** — test runner
+
+If a tool is missing, CodeDoctor will report it clearly.
+
+---
+
+## Installation
+
+### Option A: Install from PyPI (recommended once published)
+
+```bash
+pip install codedoctor
+```
+
+### Option B: Install from source (for development)
+
+```bash
+git clone https://github.com/BigPattyOG/CodeDoctor.git
+cd CodeDoctor
+python -m venv .venv
+# Windows:
+.venv\Scripts\activate
+# macOS/Linux:
+source .venv/bin/activate
+
+python -m pip install -U pip
+python -m pip install -e .
+```
+
+To include developer tools (recommended for contributors):
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+From inside any repo you want to scan:
+
+```bash
+codedoctor scan .
+```
+
+CodeDoctor prints a report to the terminal and also writes a report file under:
+
+- `.codedoctor/report-latest.txt`
+- `.codedoctor/report-prev.txt` (previous run)
+- `.codedoctor/report-YYYYMMDD-HHMMSS.txt` (timestamped history)
+
+---
+
+## Example output (TL;DR)
+
+```text
+CodeDoctor Report TL;DR
+----------------------
+Overall: WARN
+Checks:  6 passed / 1 warned / 0 failed / 7 total
+
+Warnings:
+ - pytest (tests)
+```
+
+---
+
+## Commands
+
+### Scan a repo
+
+```bash
+codedoctor scan .
+```
+
+### Apply safe auto-fixes (where supported)
+
+```bash
+codedoctor scan . --fix
+```
+
+This may run tools like:
+
+- `ruff check . --fix`
+- `black .`
+
+### Skip running tests
+
+```bash
+codedoctor scan . --skip-tests
+```
+
+---
+
+## Exit codes (for CI)
+
+CodeDoctor uses simple exit codes so it can be used in CI:
+
+- **0** — all checks PASS
+- **1** — at least one WARN, and no FAIL
+- **2** — one or more FAIL
+
+---
+
+## Notes (Windows + pytest warnings)
+
+On Windows, `pytest` may sometimes print messages like:
+
+- `Exception ignored in atexit callback`
+- `PermissionError: [WinError 5] Access is denied`
+
+Even if tests pass, CodeDoctor may classify the result as **WARN** so the run is
+not marked as perfectly clean.
+
+---
+
+## Contributing
+
+PRs welcome. A typical workflow:
+
+```bash
+python -m pip install -e ".[dev]"
+pre-commit run --all-files
+pytest -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

codedoctor-0.1.0/README.md

@@ -0,0 +1,150 @@
+# CodeDoctor - v0.1.0
+
+**CodeDoctor** is a beginner-friendly Python CLI that scans a repository and
+summarizes common quality checks (linting, formatting, typing, security, and
+tests) in one readable report.
+
+It can also generate a **TL;DR summary** at the top of the report and save
+results to a `.txt` report file so you can compare runs over time.
+
+---
+
+## What it checks
+
+Depending on what you have installed, CodeDoctor can run:
+
+- **ruff** — linting (and optional auto-fixes)
+- **black** — formatting (and optional formatting changes)
+- **mypy** — static type checking
+- **bandit** — basic security checks
+- **pytest** — test runner
+
+If a tool is missing, CodeDoctor will report it clearly.
+
+---
+
+## Installation
+
+### Option A: Install from PyPI (recommended once published)
+
+```bash
+pip install codedoctor
+```
+
+### Option B: Install from source (for development)
+
+```bash
+git clone https://github.com/BigPattyOG/CodeDoctor.git
+cd CodeDoctor
+python -m venv .venv
+# Windows:
+.venv\Scripts\activate
+# macOS/Linux:
+source .venv/bin/activate
+
+python -m pip install -U pip
+python -m pip install -e .
+```
+
+To include developer tools (recommended for contributors):
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+From inside any repo you want to scan:
+
+```bash
+codedoctor scan .
+```
+
+CodeDoctor prints a report to the terminal and also writes a report file under:
+
+- `.codedoctor/report-latest.txt`
+- `.codedoctor/report-prev.txt` (previous run)
+- `.codedoctor/report-YYYYMMDD-HHMMSS.txt` (timestamped history)
+
+---
+
+## Example output (TL;DR)
+
+```text
+CodeDoctor Report TL;DR
+----------------------
+Overall: WARN
+Checks:  6 passed / 1 warned / 0 failed / 7 total
+
+Warnings:
+ - pytest (tests)
+```
+
+---
+
+## Commands
+
+### Scan a repo
+
+```bash
+codedoctor scan .
+```
+
+### Apply safe auto-fixes (where supported)
+
+```bash
+codedoctor scan . --fix
+```
+
+This may run tools like:
+
+- `ruff check . --fix`
+- `black .`
+
+### Skip running tests
+
+```bash
+codedoctor scan . --skip-tests
+```
+
+---
+
+## Exit codes (for CI)
+
+CodeDoctor uses simple exit codes so it can be used in CI:
+
+- **0** — all checks PASS
+- **1** — at least one WARN, and no FAIL
+- **2** — one or more FAIL
+
+---
+
+## Notes (Windows + pytest warnings)
+
+On Windows, `pytest` may sometimes print messages like:
+
+- `Exception ignored in atexit callback`
+- `PermissionError: [WinError 5] Access is denied`
+
+Even if tests pass, CodeDoctor may classify the result as **WARN** so the run is
+not marked as perfectly clean.
+
+---
+
+## Contributing
+
+PRs welcome. A typical workflow:
+
+```bash
+python -m pip install -e ".[dev]"
+pre-commit run --all-files
+pytest -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

codedoctor-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codedoctor"
+version = "0.1.0"
+description = "Beginner-friendly codebase doctor: lint, format, type-check, security and tests."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Patrick Faint", email = "pattymayo3@icloud.com" }]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.8.0",
+    "black>=24.0.0",
+    "mypy>=1.10.0",
+    "bandit>=1.7.0",
+    "pre-commit>=3.7.0",
+]
+
+[project.scripts]
+codedoctor = "codedoctor.cli:main"
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.black]
+line-length = 88
+target-version = ["py312"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true

codedoctor-0.1.0/src/codedoctor/cli.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from codedoctor.runner import scan_repo
+from codedoctor.storage import get_report_paths, rotate_latest_to_previous
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codedoctor",
+        description="Beginner-friendly checks for Python repositories.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan = subparsers.add_parser("scan", help="Scan a repository.")
+    scan.add_argument("path", nargs="?", default=".", help="Repo path (default: .)")
+    scan.add_argument(
+        "--fix", action="store_true", help="Apple safe auto_fixes (ruff --fix, black)."
+    )
+    scan.add_argument("--skip-tests", action="store_true", help="Skip running pytest.")
+    scan.add_argument(
+        "--report-dir",
+        default=".codedoctor",
+        help="Directory (relative to repo) to store reports.",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    repo_path = Path(args.path).resolve()
+
+    if args.command == "scan":
+        report = scan_repo(
+            repo_path=repo_path,
+            apply_fixes=bool(args.fix),
+            skip_tests=bool(args.skip_tests),
+        )
+
+        report_root = repo_path / args.report_dir
+        paths = get_report_paths(repo_path=repo_path)
+
+        paths = paths.__class__(
+            directory=report_root,
+            latest=report_root / "report-latest.txt",
+            previous=report_root / "report-prev.txt",
+            timestamped=report_root / paths.timestamped.name,
+        )
+
+        report_root.mkdir(parents=True, exist_ok=True)
+        rotate_latest_to_previous(latest=paths.latest, previous=paths.previous)
+
+        text = report.to_full_text()
+        paths.latest.write_text(text, encoding="utf-8")
+        paths.timestamped.write_text(text, encoding="utf-8")
+
+        print(text)
+        print(f"\nWrote: {paths.latest}")
+        print(f"Wrote: {paths.timestamped}")
+        if paths.previous.exists():
+            print(f"Previous: {paths.previous}")
+
+        return report.exit_code
+
+    return 1

codedoctor-0.1.0/src/codedoctor/report.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class CheckStatus(str, Enum):
+    PASS = "PASS"  # nosec B105
+    WARN = "WARN"
+    FAIL = "FAIL"
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    command: list[str]
+    returncode: int
+    output: str
+    status: CheckStatus
+
+    @property
+    def ok(self) -> bool:
+        return self.status in {CheckStatus.PASS, CheckStatus.WARN}
+
+
+@dataclass(frozen=True)
+class ScanReport:
+    repo: str
+    results: list[CheckResult]
+
+    @property
+    def ok(self) -> bool:
+        return all(r.ok for r in self.results)
+
+    @property
+    def has_failures(self) -> bool:
+        return any(r.status == CheckStatus.FAIL for r in self.results)
+
+    @property
+    def has_warnings(self) -> bool:
+        return any(r.status == CheckStatus.WARN for r in self.results)
+
+    @property
+    def overall_status(self) -> CheckStatus:
+        if self.has_failures:
+            return CheckStatus.FAIL
+        if self.has_warnings:
+            return CheckStatus.WARN
+        return CheckStatus.PASS
+
+    @property
+    def exit_code(self) -> int:
+        if self.has_failures:
+            return 2
+        if self.has_warnings:
+            return 1
+        return 0
+
+    def to_tldr(self) -> str:
+        total = len(self.results)
+        passed = sum(1 for r in self.results if r.status == CheckStatus.PASS)
+        warned = sum(1 for r in self.results if r.status == CheckStatus.WARN)
+        failed = sum(1 for r in self.results if r.status == CheckStatus.FAIL)
+
+        lines: list[str] = []
+        lines.append("CodeDoctor Report TL;DR")
+        lines.append("----------------------")
+        lines.append(f"Overall: {self.overall_status.value}")
+        lines.append(
+            f"Checks:  {passed} passed / {warned} warned / {failed} failed / "
+            f"{total} total"
+        )
+        lines.append("")
+
+        if failed:
+            lines.append("Failures:")
+            for r in self.results:
+                if r.status == CheckStatus.FAIL:
+                    lines.append(f" - {r.name}")
+            lines.append("")
+
+        if warned:
+            lines.append("Warnings:")
+            for r in self.results:
+                if r.status == CheckStatus.WARN:
+                    lines.append(f" - {r.name}")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def to_full_text(self) -> str:
+        lines: list[str] = []
+        lines.append(self.to_tldr())
+        lines.append(f"Repository: {self.repo}")
+        lines.append("")
+        lines.append("Details")
+        lines.append("-------")
+        lines.append("")
+
+        for r in self.results:
+            lines.append(f"== {r.name} : {r.status.value} ==")
+            if r.command:
+                lines.append(f"$ {' '.join(r.command)}")
+            lines.append(r.output if r.output else "(no output)")
+            lines.append("")
+
+        lines.append("Next steps:")
+        lines.append(" - Re-run with safe auto-fixes: codedoctor scan . --fix")
+        lines.append("")
+        return "\n".join(lines)
+
+    def to_human_text(self) -> str:
+        return self.to_full_text()

codedoctor-0.1.0/src/codedoctor/runner.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import shutil
+import subprocess  # nosec B404
+from pathlib import Path
+
+from codedoctor.report import CheckResult, CheckStatus, ScanReport
+
+
+def tool_exists(tool: str) -> bool:
+    return shutil.which(tool) is not None
+
+
+def classify_status(name: str, returncode: int, output: str) -> CheckStatus:
+    if returncode != 0:
+        return CheckStatus.FAIL
+
+    # Pytest can return 0 but still print nasty shutdown exceptions on Windows.
+    warning_signatures = [
+        "Exception ignored in atexit callback",
+        "PermissionError: [WinError 5]",
+        "Traceback (most recent call last):",
+    ]
+    if name.startswith("pytest") and any(s in output for s in warning_signatures):
+        return CheckStatus.WARN
+
+    return CheckStatus.PASS
+
+
+def run_command(display_name: str, cmd: list[str], cwd: Path) -> CheckResult:
+    proc = subprocess.run(  # nosec B603
+        cmd,
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+    )
+    output = ((proc.stdout or "") + (proc.stderr or "")).strip()
+    status = classify_status(
+        name=display_name, returncode=proc.returncode, output=output
+    )
+
+    return CheckResult(
+        name=display_name,
+        command=cmd,
+        returncode=proc.returncode,
+        output=output,
+        status=status,
+    )
+
+
+def build_checks(apply_fixes: bool, skip_tests: bool) -> list[tuple[str, list[str]]]:
+    checks: list[tuple[str, list[str]]] = []
+
+    # Ruff
+    if tool_exists("ruff"):
+        if apply_fixes:
+            checks.append(("ruff (auto-fix)", ["ruff", "check", ".", "--fix"]))
+        checks.append(("ruff (lint)", ["ruff", "check", "."]))
+    else:
+        checks.append(("ruff (missing)", []))
+
+    # Black
+    if tool_exists("black"):
+        if apply_fixes:
+            checks.append(("black (format)", ["black", "."]))
+        checks.append(("black (check)", ["black", ".", "--check"]))
+    else:
+        checks.append(("black (missing)", []))
+
+    # MyPy
+    if tool_exists("mypy"):
+        checks.append(("mypy (types)", ["mypy", "src"]))
+
+    # Bandit
+    if tool_exists("bandit"):
+        checks.append(("bandit (security)", ["bandit", "-r", "src"]))
+
+    # Pytest
+    if not skip_tests and tool_exists("pytest"):
+        checks.append(("pytest (tests)", ["pytest", "-q"]))
+
+    return checks
+
+
+def scan_repo(repo_path: Path, apply_fixes: bool, skip_tests: bool) -> ScanReport:
+    results: list[CheckResult] = []
+
+    for name, cmd in build_checks(apply_fixes=apply_fixes, skip_tests=skip_tests):
+        if not cmd:
+            tool = name.split(" ", 1)[0]
+            results.append(
+                CheckResult(
+                    name=name,
+                    command=[],
+                    returncode=127,
+                    output=(
+                        f"{tool} is not installed or not on PATH.\n"
+                        f"Install it with: python -m pip install {tool}"
+                    ),
+                    status=CheckStatus.FAIL,
+                )
+            )
+            continue
+
+        results.append(run_command(display_name=name, cmd=cmd, cwd=repo_path))
+
+    return ScanReport(repo=str(repo_path), results=results)

codedoctor-0.1.0/src/codedoctor/storage.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ReportPaths:
+    directory: Path
+    latest: Path
+    previous: Path
+    timestamped: Path
+
+
+def get_report_paths(repo_path: Path) -> ReportPaths:
+    report_dir = repo_path / ".codedoctor"
+    latest = report_dir / "report-latest.txt"
+    previous = report_dir / "report-prev.txt"
+
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    timestamped = report_dir / f"report-{ts}.txt"
+
+    return ReportPaths(
+        directory=report_dir,
+        latest=latest,
+        previous=previous,
+        timestamped=timestamped,
+    )
+
+
+def rotate_latest_to_previous(latest: Path, previous: Path) -> None:
+    if latest.exists():
+        previous.parent.mkdir(parents=True, exist_ok=True)
+        if previous.exists():
+            previous.unlink()
+        latest.replace(previous)

codedoctor-0.1.0/tests/test_smoke.py

@@ -0,0 +1,7 @@
+from codedoctor.runner import scan_repo
+
+
+def test_scan_repo_smoke(tmp_path) -> None:
+    repo = tmp_path
+    report = scan_repo(repo_path=repo, apply_fixes=False, skip_tests=True)
+    assert report.results