pydebt 0.1.0__py3-none-any.whl

pydebt/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pydebt/__main__.py

@@ -0,0 +1,4 @@
+from pydebt.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pydebt/baseline.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypedDict
+
+from pydebt.scanner import FileScan
+
+BASELINE_FILE = ".pydebt.json"
+
+
+class FileEntry(TypedDict):
+    lines: int
+    counts: dict[str, int]
+
+
+class Baseline(TypedDict):
+    version: int
+    files: dict[str, FileEntry]
+
+
+@dataclass
+class Delta:
+    added: dict[str, int]
+    removed: dict[str, int]
+    changed_files: list[str]
+
+    @property
+    def net(self) -> int:
+        return sum(self.added.values()) - sum(self.removed.values())
+
+    @property
+    def worse(self) -> bool:
+        return self.net > 0
+
+
+def build_baseline(scans: list[FileScan]) -> Baseline:
+    files: dict[str, FileEntry] = {}
+    for scan in scans:
+        counts: dict[str, int] = {}
+        for f in scan.findings:
+            counts[f.kind] = counts.get(f.kind, 0) + 1
+        files[scan.path] = FileEntry(lines=scan.lines, counts=counts)
+    return Baseline(version=1, files=files)
+
+
+def write_baseline(root: Path, data: Baseline) -> Path:
+    path = root / BASELINE_FILE
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def read_baseline(root: Path) -> Baseline | None:
+    path = root / BASELINE_FILE
+    if not path.exists():
+        return None
+    raw = path.read_text(encoding="utf-8")
+    data: Baseline = json.loads(raw)
+    return data
+
+
+def totals(counts: dict[str, int]) -> int:
+    return sum(counts.values())

pydebt/cli.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import cast
+
+from pydebt import __version__
+from pydebt.baseline import (
+    Baseline,
+    Delta,
+    FileEntry,
+    build_baseline,
+    read_baseline,
+    totals,
+    write_baseline,
+)
+from pydebt.report import render_text, summary
+from pydebt.scanner import scan_tree
+
+DEFAULT_EXCLUDE = ["tests", "test", ".venv", "venv", "build", "dist", "node_modules"]
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    scans = scan_tree(root, exclude=args.exclude)
+    data = summary(scans)
+    if args.json:
+        print(json.dumps(data, indent=2))
+    else:
+        print(render_text(data, top=args.top))
+    return 0
+
+
+def cmd_baseline(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    scans = scan_tree(root, exclude=args.exclude)
+    data = build_baseline(scans)
+    path = write_baseline(root, data)
+    total = sum(totals(f["counts"]) for f in data["files"].values())
+    print(f"baseline: {total} findings across {len(data['files'])} files -> {path.name}")
+    return 0
+
+
+def _compute_delta(current: Baseline, baseline: Baseline) -> Delta:
+    cur_files = current["files"]
+    base_files = baseline["files"]
+    added: dict[str, int] = {}
+    removed: dict[str, int] = {}
+    changed: list[str] = []
+    empty = FileEntry(lines=0, counts={})
+
+    for path in sorted(set(cur_files) | set(base_files)):
+        cur_counts = cur_files.get(path, empty)["counts"]
+        base_counts = base_files.get(path, empty)["counts"]
+        for kind in set(cur_counts) | set(base_counts):
+            diff = cur_counts.get(kind, 0) - base_counts.get(kind, 0)
+            if diff > 0:
+                added[kind] = added.get(kind, 0) + diff
+            elif diff < 0:
+                removed[kind] = removed.get(kind, 0) - diff
+        if cur_counts != base_counts:
+            changed.append(path)
+
+    return Delta(added=added, removed=removed, changed_files=changed)
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    baseline = read_baseline(root)
+    if baseline is None:
+        print("pydebt: no baseline found. run `pydebt baseline` first.", file=sys.stderr)
+        return 1
+
+    scans = scan_tree(root, exclude=args.exclude)
+    current = build_baseline(scans)
+    delta = _compute_delta(current, baseline)
+
+    if not delta.changed_files:
+        print("pydebt: no changes vs baseline.")
+        return 0
+
+    print(f"changed files: {len(delta.changed_files)}")
+    for kind, n in sorted(delta.added.items()):
+        print(f"  +{n}  {kind}")
+    for kind, n in sorted(delta.removed.items()):
+        print(f"  -{n}  {kind}")
+    print(f"net: {delta.net:+d}")
+
+    if delta.worse and not args.allow_growth:
+        print("pydebt: debt increased. failing.")
+        return 1
+    return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    scans = scan_tree(root, exclude=args.exclude)
+    data = summary(scans)
+    if args.json:
+        print(json.dumps(data, indent=2))
+    else:
+        print(render_text(data, top=args.top))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pydebt",
+        description="Measurable technical debt for Python projects.",
+    )
+    parser.add_argument("--version", action="version", version=f"pydebt {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add_common(p: argparse.ArgumentParser) -> None:
+        p.add_argument("root", nargs="?", default=".", help="project root (default: .)")
+        p.add_argument(
+            "--exclude",
+            nargs="*",
+            default=DEFAULT_EXCLUDE,
+            help="directory names to skip",
+        )
+
+    p_scan = sub.add_parser("scan", help="scan and summarize")
+    add_common(p_scan)
+    p_scan.add_argument("--json", action="store_true", help="emit JSON")
+    p_scan.add_argument("--top", type=int, default=10, help="top N files/dirs")
+    p_scan.set_defaults(func=cmd_scan)
+
+    p_base = sub.add_parser("baseline", help="write .pydebt.json from current state")
+    add_common(p_base)
+    p_base.set_defaults(func=cmd_baseline)
+
+    p_check = sub.add_parser("check", help="compare current state to baseline")
+    add_common(p_check)
+    p_check.add_argument(
+        "--allow-growth", action="store_true", help="exit 0 even if debt increased"
+    )
+    p_check.set_defaults(func=cmd_check)
+
+    p_report = sub.add_parser("report", help="summary report")
+    add_common(p_report)
+    p_report.add_argument("--json", action="store_true", help="emit JSON")
+    p_report.add_argument("--top", type=int, default=10, help="top N files/dirs")
+    p_report.set_defaults(func=cmd_report)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return cast(int, args.func(args))

pydebt/report.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import TypedDict
+
+from pydebt.scanner import FileScan
+
+
+class Summary(TypedDict):
+    total: int
+    by_kind: dict[str, int]
+    by_dir: dict[str, int]
+    by_file: list[tuple[str, int]]
+
+
+def summary(scans: list[FileScan]) -> Summary:
+    by_kind: Counter[str] = Counter()
+    by_dir: Counter[str] = Counter()
+    by_file: list[tuple[str, int]] = []
+    total = 0
+
+    for scan in scans:
+        if scan.findings:
+            by_file.append((scan.path, len(scan.findings)))
+            total += len(scan.findings)
+        dirname = scan.path.rsplit("/", 1)[0] if "/" in scan.path else "."
+        for f in scan.findings:
+            by_kind[f.kind] += 1
+            by_dir[dirname] += 1
+
+    by_file.sort(key=lambda x: (-x[1], x[0]))
+    return Summary(
+        total=total,
+        by_kind=dict(by_kind.most_common()),
+        by_dir=dict(by_dir.most_common()),
+        by_file=by_file,
+    )
+
+
+def render_text(data: Summary, top: int = 10) -> str:
+    lines = [f"total findings: {data['total']}", ""]
+
+    if data["by_kind"]:
+        lines.append("by kind:")
+        kind_width = max(len(k) for k in data["by_kind"])
+        for kind, n in data["by_kind"].items():
+            lines.append(f"  {kind:<{kind_width}}  {n}")
+        lines.append("")
+
+    if data["by_dir"]:
+        lines.append("by directory:")
+        dir_width = max(len(d) for d in data["by_dir"])
+        for d, n in list(data["by_dir"].items())[:top]:
+            lines.append(f"  {d:<{dir_width}}  {n}")
+        lines.append("")
+
+    if data["by_file"]:
+        lines.append(f"top {top} files:")
+        for path, n in data["by_file"][:top]:
+            lines.append(f"  {n:>4}  {path}")
+
+    return "\n".join(lines)

pydebt/scanner.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import ast
+import io
+import re
+import tokenize
+from dataclasses import dataclass, field
+from pathlib import Path
+
+FUNCTION_LINE_THRESHOLD = 50
+FILE_LINE_THRESHOLD = 500
+
+WORD_MARKERS = ("TODO", "FIXME", "HACK", "XXX")
+PRAGMA_MARKERS = {
+    "TYPE_IGNORE": "type: ignore",
+    "NOQA": "noqa",
+    "NO_COVER": "pragma: no cover",
+}
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str
+    path: str
+    line: int
+    detail: str = ""
+
+
+@dataclass
+class FileScan:
+    path: str
+    lines: int
+    findings: list[Finding] = field(default_factory=list)
+
+
+def _scan_comments(source: str) -> list[tuple[int, str]]:
+    comments: list[tuple[int, str]] = []
+    try:
+        for tok in tokenize.generate_tokens(io.StringIO(source).readline):
+            if tok.type == tokenize.COMMENT:
+                comments.append((tok.start[0], tok.string))
+    except (tokenize.TokenError, IndentationError):
+        return comments
+    return comments
+
+
+def _match_kind(comment: str) -> str | None:
+    for kind in WORD_MARKERS:
+        if re.search(rf"\b{kind}\b", comment):
+            return kind
+    lower = comment.lower()
+    for kind, needle in PRAGMA_MARKERS.items():
+        if needle in lower:
+            return kind
+    return None
+
+
+def _scan_ast(source: str, path: str) -> list[Finding]:
+    findings: list[Finding] = []
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return findings
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            end = node.end_lineno if node.end_lineno is not None else node.lineno
+            length = end - node.lineno + 1
+            if length > FUNCTION_LINE_THRESHOLD:
+                findings.append(
+                    Finding(
+                        kind="LONG_FUNCTION",
+                        path=path,
+                        line=node.lineno,
+                        detail=f"{node.name} ({length} lines)",
+                    )
+                )
+        if (
+            isinstance(node, ast.ExceptHandler)
+            and len(node.body) == 1
+            and isinstance(node.body[0], ast.Pass)
+        ):
+            findings.append(
+                Finding(
+                    kind="EXCEPT_PASS",
+                    path=path,
+                    line=node.lineno,
+                    detail="silent except",
+                )
+            )
+    return findings
+
+
+def scan_file(path: Path, root: Path) -> FileScan | None:
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError):
+        return None
+
+    rel = str(path.relative_to(root)).replace("\\", "/")
+    lines = source.count("\n") + (1 if source and not source.endswith("\n") else 0)
+    result = FileScan(path=rel, lines=lines)
+
+    if lines > FILE_LINE_THRESHOLD:
+        result.findings.append(Finding(kind="LONG_FILE", path=rel, line=1, detail=f"{lines} lines"))
+
+    for lineno, text in _scan_comments(source):
+        kind = _match_kind(text)
+        if kind:
+            result.findings.append(Finding(kind=kind, path=rel, line=lineno))
+
+    result.findings.extend(_scan_ast(source, rel))
+    return result
+
+
+def scan_tree(root: Path, exclude: list[str] | None = None) -> list[FileScan]:
+    exclude_set = set(exclude or [])
+    results: list[FileScan] = []
+    for path in sorted(root.rglob("*.py")):
+        if "__pycache__" in path.parts:
+            continue
+        if set(path.relative_to(root).parts) & exclude_set:
+            continue
+        scanned = scan_file(path, root)
+        if scanned is not None:
+            results.append(scanned)
+    return results

pydebt-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pydebt
+Version: 0.1.0
+Summary: Measurable technical debt for Python projects
+Author-email: your name <you@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/eduardowebdev/pydebt
+Project-URL: Repository, https://github.com/eduardowebdev/pydebt
+Project-URL: Issues, https://github.com/eduardowebdev/pydebt/issues
+Project-URL: Changelog, https://github.com/eduardowebdev/pydebt/blob/main/CHANGELOG.md
+Keywords: technical-debt,linter,static-analysis,quality
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# pydebt
+
+[![ci](https://github.com/eduardowebdev/pydebt/actions/workflows/ci.yml/badge.svg)](https://github.com/eduardowebdev/pydebt/actions/workflows/ci.yml)
+[![pypi](https://img.shields.io/pypi/v/pydebt.svg)](https://pypi.org/project/pydebt/)
+[![python](https://img.shields.io/pypi/pyversions/pydebt.svg)](https://pypi.org/project/pydebt/)
+[![license](https://img.shields.io/pypi/l/pydebt.svg)](https://pypi.org/project/pydebt/)
+
+Measurable technical debt for Python. Counts markers, complexity signals, and
+compares against a committed baseline so CI fails when debt grows.
+
+## Install
+
+~~~
+pip install pydebt
+~~~
+
+## Usage
+
+~~~
+# snapshot current state
+pydebt baseline
+
+# summarize
+pydebt scan
+pydebt scan --json --top 20
+
+# compare to baseline (exit 1 if worse)
+pydebt check
+
+# allow growth, just report
+pydebt check --allow-growth
+
+# full report
+pydebt report
+~~~
+
+## What it counts
+
+| Kind | Source |
+|---|---|
+| `TODO` `FIXME` `HACK` `XXX` | comments (uppercase convention) |
+| `TYPE_IGNORE` | `# type: ignore` in comments |
+| `NOQA` | `# noqa` in comments |
+| `NO_COVER` | `# pragma: no cover` in comments |
+| `EXCEPT_PASS` | `except:` with only `pass` |
+| `LONG_FUNCTION` | function > 50 lines |
+| `LONG_FILE` | file > 500 lines |
+
+## CI
+
+~~~
+- run: pip install pydebt
+- run: pydebt check
+~~~
+
+## Baseline
+
+`.pydebt.json` is committed. It stores per-file line count and per-kind marker
+counts. `check` diffs current against it and fails on net growth.
+
+## Development
+
+~~~
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+mypy src
+~~~
+
+## License
+
+MIT

pydebt-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pydebt/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+pydebt/__main__.py,sha256=j3U-DOMfz0uVXLX8fQ1mhwsjeRp0L2XTS7MFWqZ6Pm8,85
+pydebt/baseline.py,sha256=Gy9q_uc2BYUgDfyQZPHsf8WMh_bNHbwk03aTBJDyla8,1498
+pydebt/cli.py,sha256=riPzYYjz7x74s_EOkMxMgJxPZg0dyNfv1AVppjQQgZY,4992
+pydebt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydebt/report.py,sha256=OorjV2AFfOVwhCgvK1xcGoVNd1BYjthfNuT9TMd6NMI,1770
+pydebt/scanner.py,sha256=MXbI7n0TIeObns4YfQfjAtKpUqDImAFiaqk4OsPqc7k,3645
+pydebt-0.1.0.dist-info/licenses/LICENSE,sha256=unCqpibCvd_QzWR4zmO6pkNvTghXSnbh-nVKQawYpfQ,1076
+pydebt-0.1.0.dist-info/METADATA,sha256=iMPv8MNVU4i6h1zeq38JUmGp08-73pxxyEtJ4inWauI,2802
+pydebt-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pydebt-0.1.0.dist-info/entry_points.txt,sha256=6zoJkbzDJCeyJFkwumF_UjRluh9c2sF-2qAxT1Ji2EU,43
+pydebt-0.1.0.dist-info/top_level.txt,sha256=tiKslpP9YVhXfXuZ4LePDYFkHVU2CtXeecLwWIsMCpI,7
+pydebt-0.1.0.dist-info/RECORD,,

pydebt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pydebt-0.1.0.dist-info/entry_points.txt

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

pydebt-0.1.0.dist-info/licenses/LICENSE

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

pydebt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pydebt