codedoctor 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+codedoctor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codedoctor/cli.py,sha256=zeB9i7Rrz9Nzn2Hf7CzEFNca0UvjGni7duKyDpb2VPw,2190
+codedoctor/report.py,sha256=dmiBrC3GsqbsS1BgWoW8Wyuihpvs70pMDxdnNpQ58aY,3163
+codedoctor/runner.py,sha256=6aizE98Uey-4l_zcU8tv5WGnVRAa-_sh8VETGpiAeqI,3181
+codedoctor/storage.py,sha256=slHvv0AtW6H70LVSyW0DM2PV_JNk79NpfvQ9DTQBNp0,953
+codedoctor-0.1.0.dist-info/METADATA,sha256=BpgWLND7MEUBMG5wnUcfZXkrkbAkja5CkIVWzdZ2qzo,3290
+codedoctor-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+codedoctor-0.1.0.dist-info/entry_points.txt,sha256=uSBQkck94mA7M3g9Ae9VYaUVlYpB15Vl4fLZ1G0SeAE,51
+codedoctor-0.1.0.dist-info/licenses/LICENSE,sha256=ZzI8Mmsq793d2u4MNeZ17v5hPzfk4qT7nlH-Po_7c1s,1069
+codedoctor-0.1.0.dist-info/RECORD,,

codedoctor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codedoctor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codedoctor = codedoctor.cli:main

codedoctor-0.1.0.dist-info/licenses/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.