pycodegate 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

pycodegate/__init__.py

@@ -1,3 +1,3 @@
 """Python Doctor - Diagnose your Python project's health."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"

pycodegate/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import sys
+from dataclasses import dataclass
 
 import click
 
@@ -16,6 +17,94 @@ from pycodegate.utils.fixer import run_ruff_fix
 from pycodegate.utils.precommit import install_precommit_hook
 
 
+@dataclass
+class CliOptions:
+    """Bundle of all CLI flags passed to main()."""
+
+    directory: str
+    lint: bool
+    dead_code: bool
+    verbose: bool
+    score_only: bool
+    json_output: bool
+    diff_base: str | None
+    fail_on: str
+    fix: bool
+    profile_override: str | None
+    badge: bool
+    ci_workflow: bool
+    precommit: bool
+    min_score: int | None
+
+
+def _handle_early_exits(opts: CliOptions) -> bool:
+    """Handle flags that exit before scanning. Returns True if handled."""
+    if opts.ci_workflow:
+        click.echo(generate_ci_workflow(), nl=False)
+        return True
+
+    if opts.precommit:
+        effective_min = opts.min_score if opts.min_score is not None else 50
+        msg = install_precommit_hook(opts.directory, min_score=effective_min)
+        click.echo(msg)
+        return True
+
+    return False
+
+
+def _maybe_run_fix(opts: CliOptions) -> None:
+    """Apply ruff auto-fix if --fix was passed."""
+    if not opts.fix:
+        return
+    fixes = run_ruff_fix(opts.directory)
+    if fixes == -1:
+        click.echo("ruff not found, skipping auto-fix")
+    else:
+        click.echo(f"Fixed {fixes} issues via ruff")
+
+
+def _build_config(opts: CliOptions):
+    """Load config and apply CLI overrides."""
+    config = load_config(opts.directory)
+    config.lint = opts.lint
+    config.dead_code = opts.dead_code
+    config.verbose = opts.verbose
+    config.fail_on = opts.fail_on
+    if opts.profile_override is not None:
+        config.profile = opts.profile_override
+    return config
+
+
+def _output_result(opts: CliOptions, result) -> None:
+    """Write scan result to stdout in the requested format."""
+    if opts.badge:
+        click.echo(generate_badge(result.score.value, result.score.label))
+        return
+
+    if opts.json_output:
+        output_json(result)
+    elif opts.score_only:
+        click.echo(str(result.score.value))
+    else:
+        print_scan_result(result, verbose=opts.verbose)
+
+
+def _apply_exit_codes(opts: CliOptions, result) -> None:
+    """Exit with non-zero code based on --fail-on and --min-score."""
+    has_errors = any(d.severity == Severity.ERROR for d in result.diagnostics)
+    if (opts.fail_on == "error" and has_errors) or (
+        opts.fail_on == "warning" and result.diagnostics
+    ):
+        sys.exit(1)
+
+    if opts.min_score is not None and result.score.value < opts.min_score:
+        click.echo(
+            f"pycodegate: score {result.score.value} is below minimum {opts.min_score}",
+            err=True,
+        )
+        sys.exit(1)
+
+
 @click.command(context_settings={"help_option_names": ["-h", "--help"]})
 @click.version_option(__version__, "-v", "--version", prog_name="PyCodeGate")
 @click.argument("directory", default=".", type=click.Path(exists=True))
@@ -80,52 +169,30 @@ def main(
     min_score: int | None,
 ) -> None:
     """PyCodeGate — Diagnose your Python project's health."""
-    if ci_workflow:
-        click.echo(generate_ci_workflow(), nl=False)
-        return
+    opts = CliOptions(
+        directory=directory,
+        lint=lint,
+        dead_code=dead_code,
+        verbose=verbose,
+        score_only=score_only,
+        json_output=json_output,
+        diff_base=diff_base,
+        fail_on=fail_on,
+        fix=fix,
+        profile_override=profile_override,
+        badge=badge,
+        ci_workflow=ci_workflow,
+        precommit=precommit,
+        min_score=min_score,
+    )
 
-    if precommit:
-        effective_min = min_score if min_score is not None else 50
-        msg = install_precommit_hook(directory, min_score=effective_min)
-        click.echo(msg)
+    if _handle_early_exits(opts):
         return
 
-    if fix:
-        fixes = run_ruff_fix(directory)
-        if fixes == -1:
-            click.echo("ruff not found, skipping auto-fix")
-        else:
-            click.echo(f"Fixed {fixes} issues via ruff")
-
-    config = load_config(directory)
-    config.lint = lint
-    config.dead_code = dead_code
-    config.verbose = verbose
-    config.fail_on = fail_on
-    if profile_override is not None:
-        config.profile = profile_override
+    _maybe_run_fix(opts)
 
+    config = _build_config(opts)
     result = scan_project(directory, config, diff_base=diff_base)
 
-    if badge:
-        click.echo(generate_badge(result.score.value, result.score.label))
-        return
-
-    if json_output:
-        output_json(result)
-    elif score_only:
-        click.echo(str(result.score.value))
-    else:
-        print_scan_result(result, verbose=verbose)
-
-    # Exit code based on --fail-on
-    has_errors = any(d.severity == Severity.ERROR for d in result.diagnostics)
-    if (fail_on == "error" and has_errors) or (fail_on == "warning" and result.diagnostics):
-        sys.exit(1)
-
-    if min_score is not None and result.score.value < min_score:
-        click.echo(
-            f"pycodegate: score {result.score.value} is below minimum {min_score}",
-            err=True,
-        )
-        sys.exit(1)
+    _output_result(opts, result)
+    _apply_exit_codes(opts, result)

pycodegate/output.py

@@ -138,8 +138,6 @@ def print_scan_result(result: ScanResult, verbose: bool = False) -> None:
     # Project info header
     p = result.project
     console.print()
-    from pycodegate import __version__
-
     console.print(f"  [bold]PyCodeGate[/bold] — v{__version__}")
     console.print()
     console.print(f"  [dim]Path:[/dim]            {p.path}")
@@ -215,6 +213,47 @@ def output_json(result: ScanResult) -> None:
     sys.stdout.write(json.dumps(payload, indent=2) + "\n")
 
 
+def _print_rule_details(
+    console: Console,
+    rule_diags: list[Diagnostic],
+    verbose: bool,
+) -> None:
+    """Print a single rule line and, in verbose mode, the file locations."""
+    rule = rule_diags[0].rule
+    count = len(rule_diags)
+    sev = rule_diags[0].severity
+    icon = "[red]✗[/red]" if sev == Severity.ERROR else "[yellow]⚠[/yellow]"
+    console.print(f"    {icon} {rule} × {count}")
+    if not verbose:
+        return
+    for d in rule_diags[:10]:
+        console.print(f"      [dim]{d.file_path}:{d.line}[/dim]")
+    if count > 10:
+        console.print(f"      [dim]... and {count - 10} more[/dim]")
+
+
+def _print_category_with_issues(
+    console: Console,
+    emoji: str,
+    name: str,
+    earned: int,
+    maximum: int,
+    cat_diags: list[Diagnostic],
+    verbose: bool,
+) -> None:
+    """Print a category header and its grouped rule findings."""
+    console.print(f"  [bold]{emoji} {name}[/bold] [yellow]({earned}/{maximum})[/yellow]")
+    by_rule: dict[str, list[Diagnostic]] = defaultdict(list)
+    for d in cat_diags:
+        by_rule[d.rule].append(d)
+    sorted_rules = sorted(
+        by_rule.keys(),
+        key=lambda r: (0 if by_rule[r][0].severity == Severity.ERROR else 1, r),
+    )
+    for rule in sorted_rules:
+        _print_rule_details(console, by_rule[rule], verbose)
+
+
 def _print_category_groups(
     console: Console,
     diagnostics: list[Diagnostic],
@@ -235,38 +274,15 @@ def _print_category_groups(
             continue
         emoji, name = CATEGORY_DISPLAY[cat]
         earned, maximum = sub_scores.get(cat, (CATEGORY_WEIGHTS[cat], CATEGORY_WEIGHTS[cat]))
-        # Recompute max from sub_scores (already normalised to 100-point scale)
         cat_diags = by_category.get(cat, [])
 
         if earned == maximum:
-            # Perfect score for this category
             console.print(
                 f"  [bold]{emoji} {name}[/bold] "
                 f"[green]({earned}/{maximum})[/green] [green]✓[/green]"
             )
             console.print("    [green]✓ All clear.[/green]")
         else:
-            console.print(f"  [bold]{emoji} {name}[/bold] [yellow]({earned}/{maximum})[/yellow]")
-            # Group by rule within this category
-            by_rule: dict[str, list[Diagnostic]] = defaultdict(list)
-            for d in cat_diags:
-                by_rule[d.rule].append(d)
-
-            # Sort: errors first, then by rule name
-            sorted_rules = sorted(
-                by_rule.keys(),
-                key=lambda r: (0 if by_rule[r][0].severity == Severity.ERROR else 1, r),
-            )
-            for rule in sorted_rules:
-                rule_diags = by_rule[rule]
-                count = len(rule_diags)
-                sev = rule_diags[0].severity
-                icon = "[red]✗[/red]" if sev == Severity.ERROR else "[yellow]⚠[/yellow]"
-                console.print(f"    {icon} {rule} × {count}")
-                if verbose:
-                    for d in rule_diags[:10]:
-                        console.print(f"      [dim]{d.file_path}:{d.line}[/dim]")
-                    if count > 10:
-                        console.print(f"      [dim]... and {count - 10} more[/dim]")
+            _print_category_with_issues(console, emoji, name, earned, maximum, cat_diags, verbose)
 
         console.print()

pycodegate/profile.py

@@ -32,6 +32,56 @@ PROFILES = {
 }
 
 
+def _normalise_dep(dep: str) -> str:
+    """Strip version specifiers and extras from a dependency string."""
+    return dep.split("[")[0].split(">")[0].split("<")[0].split("=")[0].split("!")[0].strip().lower()
+
+
+def _deps_from_pyproject(pyproject: Path) -> tuple[set[str], bool, bool]:
+    """Parse pyproject.toml and return (deps, has_build_system, has_scripts)."""
+    deps: set[str] = set()
+    has_build_system = False
+    has_scripts = False
+    try:
+        with open(pyproject, "rb") as f:
+            data = tomllib.load(f)
+        for dep in data.get("project", {}).get("dependencies", []):
+            deps.add(_normalise_dep(dep))
+        has_build_system = "build-system" in data
+        has_scripts = bool(data.get("project", {}).get("scripts"))
+    except (OSError, ValueError, KeyError):
+        pass
+    return deps, has_build_system, has_scripts
+
+
+def _deps_from_requirements(path: Path) -> set[str]:
+    """Parse requirements files and return the set of normalised dep names."""
+    deps: set[str] = set()
+    for req_file in ["requirements.txt", "requirements-dev.txt"]:
+        req_path = path / req_file
+        if not req_path.exists():
+            continue
+        try:
+            for line in req_path.read_text().splitlines():
+                line = line.strip()
+                if line and not line.startswith("#") and not line.startswith("-"):
+                    deps.add(_normalise_dep(line))
+        except (OSError, ValueError):
+            pass
+    return deps
+
+
+def _classify_by_deps(deps: set[str], has_scripts: bool) -> str | None:
+    """Return a profile name based on dependencies, or None if undetermined."""
+    web_deps = {"flask", "django", "fastapi", "starlette", "tornado", "aiohttp", "sanic", "bottle"}
+    if deps & web_deps:
+        return "web"
+    cli_deps = {"click", "typer", "fire", "cement", "cliff", "argparse"}
+    if (deps & cli_deps) or has_scripts:
+        return "cli"
+    return None
+
+
 def detect_profile(project_path: str) -> Profile:
     """Auto-detect project profile from project structure and dependencies."""
     path = Path(project_path)
@@ -42,56 +92,15 @@ def detect_profile(project_path: str) -> Profile:
     has_scripts = False
 
     if pyproject.exists():
-        try:
-            with open(pyproject, "rb") as f:
-                data = tomllib.load(f)
-            # Collect dependency names
-            for dep in data.get("project", {}).get("dependencies", []):
-                deps.add(
-                    dep.split("[")[0]
-                    .split(">")[0]
-                    .split("<")[0]
-                    .split("=")[0]
-                    .split("!")[0]
-                    .strip()
-                    .lower()
-                )
-            has_build_system = "build-system" in data
-            has_scripts = bool(data.get("project", {}).get("scripts"))
-        except Exception:
-            pass
+        pyproject_deps, has_build_system, has_scripts = _deps_from_pyproject(pyproject)
+        deps |= pyproject_deps
 
-    # Also check requirements.txt
-    for req_file in ["requirements.txt", "requirements-dev.txt"]:
-        req_path = path / req_file
-        if req_path.exists():
-            try:
-                for line in req_path.read_text().splitlines():
-                    line = line.strip()
-                    if line and not line.startswith("#") and not line.startswith("-"):
-                        deps.add(
-                            line.split("[")[0]
-                            .split(">")[0]
-                            .split("<")[0]
-                            .split("=")[0]
-                            .split("!")[0]
-                            .strip()
-                            .lower()
-                        )
-            except Exception:
-                pass
-
-    # Web frameworks
-    web_deps = {"flask", "django", "fastapi", "starlette", "tornado", "aiohttp", "sanic", "bottle"}
-    if deps & web_deps:
-        return PROFILES["web"]
+    deps |= _deps_from_requirements(path)
 
-    # CLI tools
-    cli_deps = {"click", "typer", "fire", "cement", "cliff", "argparse"}
-    if (deps & cli_deps) or has_scripts:
-        return PROFILES["cli"]
+    profile_name = _classify_by_deps(deps, has_scripts)
+    if profile_name is not None:
+        return PROFILES[profile_name]
 
-    # Library
     if has_build_system and not has_scripts:
         return PROFILES["library"]
 
@@ -103,5 +112,4 @@ def detect_profile(project_path: str) -> Profile:
     if not has_init and len(py_files) <= 5:
         return PROFILES["script"]
 
-    # Default to library
     return PROFILES["library"]

pycodegate/rules/dependencies.py

@@ -14,15 +14,8 @@ from pycodegate.types import Category, Diagnostic, Severity
 class DependencyRules:
     """Dependency vulnerability checks using pip-audit (optional)."""
 
-    def check_project(self, project_path: str) -> list[Diagnostic]:
-        if not shutil.which("pip-audit"):
-            return []
-
-        path = Path(project_path)
-        req_file = self._find_or_export_requirements(path)
-        if not req_file:
-            return []
-
+    def _run_pip_audit(self, req_file: Path) -> dict | None:
+        """Run pip-audit against *req_file* and return parsed JSON, or None on failure."""
         try:
             result = subprocess.run(
                 [
@@ -38,17 +31,14 @@ class DependencyRules:
                 text=True,
                 timeout=60,
             )
-            # pip-audit exits non-zero when vulnerabilities found
             if not result.stdout.strip():
-                return []
-            data = json.loads(result.stdout)
+                return None
+            return json.loads(result.stdout)
         except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError):
-            return []
-        finally:
-            # Clean up temp file if we created one
-            if req_file and str(req_file).startswith(tempfile.gettempdir()):
-                req_file.unlink(missing_ok=True)
+            return None
 
+    def _build_vuln_diagnostics(self, data: dict) -> list[Diagnostic]:
+        """Convert pip-audit JSON output into Diagnostic objects."""
         diags: list[Diagnostic] = []
         for vuln in data.get("dependencies", []):
             pkg_name = vuln.get("name", "unknown")
@@ -71,6 +61,26 @@ class DependencyRules:
                 )
         return diags
 
+    def check_project(self, project_path: str) -> list[Diagnostic]:
+        if not shutil.which("pip-audit"):
+            return []
+
+        path = Path(project_path)
+        req_file = self._find_or_export_requirements(path)
+        if not req_file:
+            return []
+
+        try:
+            data = self._run_pip_audit(req_file)
+        finally:
+            # Clean up temp file if we created one
+            if req_file and str(req_file).startswith(tempfile.gettempdir()):
+                req_file.unlink(missing_ok=True)
+
+        if data is None:
+            return []
+        return self._build_vuln_diagnostics(data)
+
     def _find_or_export_requirements(self, path: Path) -> Path | None:
         # Try existing requirements.txt
         for name in ["requirements.txt", "requirements.lock"]:

pycodegate/rules/imports.py

@@ -17,6 +17,60 @@ class ImportsRules:
         """Detect circular imports across the project."""
         return self._check_circular_imports(project_path, source_files)
 
+    def _collect_imports_for_module(
+        self, filepath: str, root: str, graph: dict[str, set[str]], file_map: dict[str, str]
+    ) -> None:
+        """Parse *filepath* and populate *graph* and *file_map* in-place."""
+        try:
+            source = Path(filepath).read_text()
+            tree = ast.parse(source)
+        except (SyntaxError, OSError, UnicodeDecodeError):
+            return
+
+        module_name = self._file_to_module(filepath, root)
+        if not module_name:
+            return
+        file_map[module_name] = filepath
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    graph[module_name].add(alias.name)
+            elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+                graph[module_name].add(node.module)
+
+    def _detect_cycles(
+        self,
+        graph: dict[str, set[str]],
+        file_map: dict[str, str],
+    ) -> list[Diagnostic]:
+        """Return diagnostics for every direct A↔B cycle in *graph*."""
+        diags: list[Diagnostic] = []
+        seen_pairs: set[tuple[str, str]] = set()
+
+        for mod_a, imports in graph.items():
+            for mod_b in imports:
+                if mod_b not in graph or mod_a not in graph[mod_b]:
+                    continue
+                pair = tuple(sorted([mod_a, mod_b]))
+                if pair in seen_pairs:
+                    continue
+                seen_pairs.add(pair)
+                diags.append(
+                    Diagnostic(
+                        file_path=file_map.get(mod_a, mod_a),
+                        rule="imports/circular",
+                        severity=Severity.ERROR,
+                        category=Category.IMPORTS,
+                        message=f"Circular import between '{mod_a}' and '{mod_b}'",
+                        help="Break the cycle by moving shared code to a third module",
+                        line=1,
+                        cost=3.0,
+                    )
+                )
+
+        return diags
+
     def _check_circular_imports(
         self, project_path: str, source_files: list[str]
     ) -> list[Diagnostic]:
@@ -24,53 +78,12 @@ class ImportsRules:
         graph: dict[str, set[str]] = defaultdict(set)
         file_map: dict[str, str] = {}  # module_name -> file_path
 
-        root = Path(project_path).resolve()
+        root = str(Path(project_path).resolve())
 
         for filepath in source_files:
-            try:
-                source = Path(filepath).read_text()
-                tree = ast.parse(source)
-            except (SyntaxError, OSError, UnicodeDecodeError):
-                continue
-
-            module_name = self._file_to_module(filepath, str(root))
-            if not module_name:
-                continue
-            file_map[module_name] = filepath
-
-            for node in ast.walk(tree):
-                if isinstance(node, ast.Import):
-                    for alias in node.names:
-                        graph[module_name].add(alias.name)
-                elif isinstance(node, ast.ImportFrom):
-                    if node.module and node.level == 0:
-                        graph[module_name].add(node.module)
-
-        # Detect direct A↔B cycles
-        diags: list[Diagnostic] = []
-        seen_pairs: set[tuple[str, str]] = set()
+            self._collect_imports_for_module(filepath, root, graph, file_map)
 
-        for mod_a, imports in graph.items():
-            for mod_b in imports:
-                if mod_b in graph and mod_a in graph[mod_b]:
-                    pair = tuple(sorted([mod_a, mod_b]))
-                    if pair not in seen_pairs:
-                        seen_pairs.add(pair)
-                        file_a = file_map.get(mod_a, mod_a)
-                        diags.append(
-                            Diagnostic(
-                                file_path=file_a,
-                                rule="imports/circular",
-                                severity=Severity.ERROR,
-                                category=Category.IMPORTS,
-                                message=f"Circular import between '{mod_a}' and '{mod_b}'",
-                                help="Break the cycle by moving shared code to a third module",
-                                line=1,
-                                cost=3.0,
-                            )
-                        )
-
-        return diags
+        return self._detect_cycles(graph, file_map)
 
     def _file_to_module(self, filepath: str, root: str) -> str | None:
         """Convert a file path to a dotted module name."""

pycodegate/rules/structure.py

@@ -49,6 +49,39 @@ class StructureRules:
                 pass
         return diags
 
+    @staticmethod
+    def _count_lines(files: list[str]) -> int:
+        """Return total line count across *files*, ignoring unreadable files."""
+        return sum(len(Path(f).read_text().splitlines()) for f in files if Path(f).exists())
+
+    def _check_test_ratio(
+        self, path: Path, test_files: list[str], src_files: list[str]
+    ) -> list[Diagnostic]:
+        """Return a diagnostic if the test-to-source line ratio is too low."""
+        test_lines = self._count_lines(test_files)
+        src_lines = self._count_lines(src_files)
+        if src_lines == 0:
+            return []
+        ratio = test_lines / src_lines
+        if ratio < 0.1:
+            cost = 2.0
+        elif ratio < 0.3:
+            cost = 1.0
+        else:
+            return []
+        return [
+            Diagnostic(
+                file_path=str(path),
+                rule="structure/low-test-ratio",
+                severity=Severity.WARNING,
+                category=Category.STRUCTURE,
+                message=f"Test:source ratio is {ratio:.1f} (< 0.3)",
+                help="Add more tests to improve coverage",
+                line=0,
+                cost=cost,
+            )
+        ]
+
     def _check_tests(self, path: Path, source_files: list[str]) -> list[Diagnostic]:
         test_files = [
             f
@@ -71,43 +104,7 @@ class StructureRules:
                 )
             ]
 
-        # Test ratio check
-        test_lines = sum(
-            len(Path(f).read_text().splitlines()) for f in test_files if Path(f).exists()
-        )
-        src_lines = sum(
-            len(Path(f).read_text().splitlines()) for f in src_files if Path(f).exists()
-        )
-
-        if src_lines > 0:
-            ratio = test_lines / src_lines
-            if ratio < 0.1:
-                return [
-                    Diagnostic(
-                        file_path=str(path),
-                        rule="structure/low-test-ratio",
-                        severity=Severity.WARNING,
-                        category=Category.STRUCTURE,
-                        message=f"Test:source ratio is {ratio:.1f} (< 0.3)",
-                        help="Add more tests to improve coverage",
-                        line=0,
-                        cost=2.0,
-                    )
-                ]
-            elif ratio < 0.3:
-                return [
-                    Diagnostic(
-                        file_path=str(path),
-                        rule="structure/low-test-ratio",
-                        severity=Severity.WARNING,
-                        category=Category.STRUCTURE,
-                        message=f"Test:source ratio is {ratio:.1f} (< 0.3)",
-                        help="Add more tests to improve coverage",
-                        line=0,
-                        cost=1.0,
-                    )
-                ]
-        return []
+        return self._check_test_ratio(path, test_files, src_files)
 
     def _check_readme(self, path: Path) -> list[Diagnostic]:
         for name in ["README.md", "README.rst", "README", "readme.md"]:

pycodegate/score.py

@@ -15,16 +15,10 @@ from pycodegate.constants import (
 from pycodegate.types import Diagnostic, Score
 
 
-def calculate_score(
-    diagnostics: list[Diagnostic], max_deduction_overrides: dict | None = None
-) -> Score:
-    """Calculate a 0-100 health score from diagnostics using category budgets.
-
-    Each category has a weight that determines its maximum deduction budget.
-    Within a category, the top 3 findings are counted at full cost; additional
-    findings apply diminishing returns (10% each) to reward fixing top issues.
-    """
-    # 1. Compute max_deduction per category from weights
+def _build_budget(
+    max_deduction_overrides: dict | None,
+) -> dict:
+    """Return per-category maximum deduction budget normalised to sum to 100."""
     total_weight = sum(CATEGORY_WEIGHTS.values())
     max_deductions = {cat: round(w / total_weight * 100) for cat, w in CATEGORY_WEIGHTS.items()}
 
@@ -34,19 +28,43 @@ def calculate_score(
         highest = max(CATEGORY_WEIGHTS, key=CATEGORY_WEIGHTS.get)
         max_deductions[highest] += diff
 
-    # Apply overrides
     if max_deduction_overrides:
         for cat, val in max_deduction_overrides.items():
             if cat in max_deductions:
                 max_deductions[cat] = val
 
-    # 2. Group diagnostics by resolved category
+    return max_deductions
+
+
+def _score_label(value: int) -> str:
+    """Return a human-readable label for a numeric score."""
+    if value >= 90:
+        return LABEL_EXCELLENT
+    if value >= 75:
+        return LABEL_GREAT
+    if value >= 50:
+        return LABEL_NEEDS_WORK
+    return LABEL_CRITICAL
+
+
+def calculate_score(
+    diagnostics: list[Diagnostic], max_deduction_overrides: dict | None = None
+) -> Score:
+    """Calculate a 0-100 health score from diagnostics using category budgets.
+
+    Each category has a weight that determines its maximum deduction budget.
+    Within a category, the top 3 findings are counted at full cost; additional
+    findings apply diminishing returns (10% each) to reward fixing top issues.
+    """
+    max_deductions = _build_budget(max_deduction_overrides)
+
+    # Group diagnostics by resolved category
     by_category: dict = defaultdict(list)
     for d in diagnostics:
         resolved = FRAMEWORK_CATEGORY_MAP.get(d.category, d.category)
         by_category[resolved].append(d)
 
-    # 3. Calculate deduction per category with diminishing returns
+    # Calculate deduction per category with diminishing returns
     total_deduction = 0.0
     for cat, diags in by_category.items():
         costs = sorted([d.cost for d in diags], reverse=True)
@@ -56,14 +74,4 @@ def calculate_score(
         total_deduction += min(cat_total, cap)
 
     value = max(0, round(100 - total_deduction))
-
-    if value >= 90:
-        label = LABEL_EXCELLENT
-    elif value >= 75:
-        label = LABEL_GREAT
-    elif value >= 50:
-        label = LABEL_NEEDS_WORK
-    else:
-        label = LABEL_CRITICAL
-
-    return Score(value=value, label=label)
+    return Score(value=value, label=_score_label(value))

pycodegate/utils/fixer.py

@@ -21,7 +21,7 @@ def run_ruff_fix(project_path: str) -> int:
     except FileNotFoundError:
         # ruff is not installed
         return -1
-    except Exception:
+    except (OSError, subprocess.SubprocessError):
         return 0
 
     # ruff prints something like "Fixed 3 errors." to stdout or stderr

{pycodegate-0.1.2.dist-info → pycodegate-0.1.3.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pycodegate
-Version: 0.1.2
-Summary: One command. One score. Your Python quality gate.
+Version: 0.1.3
+Summary: Trust, but verify. The quality gate for AI-generated Python code.
 Project-URL: Homepage, https://github.com/themohitkhare/pycodegate
 Project-URL: Repository, https://github.com/themohitkhare/pycodegate
 Project-URL: Issues, https://github.com/themohitkhare/pycodegate/issues
@@ -34,7 +34,7 @@ Description-Content-Type: text/markdown
 
 <h1 align="center">PyCodeGate</h1>
 <p align="center">
-  <strong>One command. One score. Your Python quality gate.</strong>
+  <strong>Trust, but verify. The quality gate for AI-generated Python code.</strong>
 </p>
 <p align="center">
   <a href="https://github.com/themohitkhare/pycodegate/actions/workflows/ci.yml"><img src="https://github.com/themohitkhare/pycodegate/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -45,9 +45,13 @@ Description-Content-Type: text/markdown
 
 ---
 
+## Why PyCodeGate?
+
+AI coding agents ship code fast — but fast doesn't mean safe. Every `eval()` an LLM drops in, every mutable default it forgets, every circular import it creates is a landmine waiting to go off. PyCodeGate is the trust layer between AI-generated code and your production codebase: one command, one score, zero ambiguity.
+
 ## How it works
 
-PyCodeGate starts by detecting your project's context: framework (Django, FastAPI, Flask), Python version, package manager (uv, poetry, pip), and test framework. That context drives which rules are active — Django projects get SQL injection checks, FastAPI projects get async-correctness checks, and so on.
+PyCodeGate detects your project's context: framework (Django, FastAPI, Flask), Python version, package manager (uv, poetry, pip), and test framework. That context drives which rules are active — Django projects get SQL injection checks, FastAPI projects get async-correctness checks, and so on.
 
 It then runs two analysis passes **in parallel**: a lint pass that evaluates 40+ rules across 8 categories (Security, Correctness, Complexity, Architecture, Performance, Structure, Imports, Dead Code), and a dead-code pass powered by [Vulture](https://github.com/jendrikseipp/vulture) that finds unused functions, classes, imports, and variables.
 

{pycodegate-0.1.2.dist-info → pycodegate-0.1.3.dist-info}/RECORD

@@ -1,14 +1,14 @@
-pycodegate/__init__.py,sha256=joZnN6S8V6dL3973Q7VQbG-JZvnKhwxcei9XLDbhGFo,84
+pycodegate/__init__.py,sha256=C30sIG3GQ43ZgC_imlRU7Ym6StPA5Soq3tnxztdN24Q,84
 pycodegate/_compat.py,sha256=tnXZge9z8NFCDz-zi_vAScbJkDNJo2_vpEW_UgSqbd8,293
 pycodegate/api.py,sha256=W93EWmBlzrE2Uwrs4opr4F0QO-1v6GzRp1jN05b9rBo,631
-pycodegate/cli.py,sha256=PD8bblh80hRvj1A-CuYYdiXoRfXdd9ekayl8fUIoL8k,4135
+pycodegate/cli.py,sha256=O0B7e6JP42dI5a5zeYuT6VbBbKXi4vtBiF1eWWJ3zxQ,5838
 pycodegate/config.py,sha256=56wBpGecabUYYs3UN_olDyzG49My7SumorMTDvlxRuY,2462
 pycodegate/constants.py,sha256=HJnPIZR1OcpDGmqIsNCFan7fHzezJZtt105GT7-WTfI,788
 pycodegate/discover.py,sha256=ywIPIJD-fM5PHt6ACRhehuVoJVyhm36Wf28HFGn0E3I,3694
-pycodegate/output.py,sha256=MVcn5qcfxjFNIIFP6vieN7BRi9VX8v9iJsqGf81nAlM,9775
-pycodegate/profile.py,sha256=XCmFHuyQlYfr1jru0RWXoxouQ3IVh-vgc46AjTEp3xc,3438
+pycodegate/output.py,sha256=mUWLoHg9FtZ73wd0KNnC1QErO2kCic_9ITi0hUmMep8,9918
+pycodegate/profile.py,sha256=okmh8_o_P5YpJxUnrOPGVxzDWZhBOb5WCJSkVVoO23c,3862
 pycodegate/scan.py,sha256=WEw_-a-uiDYiz3i8c3gHl8QXBRb_pVgeJciYB_E68Ws,7282
-pycodegate/score.py,sha256=Dy01pkWyi0p9ypa64aekVSlfZxXKSbdhKP54EgqYu34,2366
+pycodegate/score.py,sha256=1ANbWGABy4raiVn_32NCQG-Pu4eNCqBIx90AvXoQL_Q,2613
 pycodegate/types.py,sha256=_5eDkdNmxTkfxDNE-g_FLKpcUF6l0ArKZfwXafhYn2I,1285
 pycodegate/rules/__init__.py,sha256=Do4SzAF41GAnEUS1tn2lPZK99wSYJ67OaLKZD62B2fY,1353
 pycodegate/rules/architecture.py,sha256=e1dh_bSNyno8SaWV2UK4YoSCVMhhDphUpFrK3TSa6Xc,5151
@@ -16,23 +16,23 @@ pycodegate/rules/base.py,sha256=u7qejC4rDfXMh5RYy_3r-htxxSVTRB5zHETEnQt6X_M,593
 pycodegate/rules/complexity.py,sha256=roYTPx3i8PCltqVpHWPt_U0jMZ2MZumJXeZ6mK6RNcU,3388
 pycodegate/rules/correctness.py,sha256=go6n1fcv4NDu89zL8j4LLX-kOBgBRvuOx78C11bxhLg,6049
 pycodegate/rules/dead_code.py,sha256=ZzawHLHbYKaNoK9zcnQQA99clUkOAdA4y64VtUDUouQ,1795
-pycodegate/rules/dependencies.py,sha256=q8w0VAJeGV9FMNCOVqs0CYpc5Zmqoc-qZ-x4FxMn7sA,3732
+pycodegate/rules/dependencies.py,sha256=NOg9rRhzEP92s6_IkYEN0o3dHDKpgERzspoQGgahRbk,4123
 pycodegate/rules/django.py,sha256=IddI4eVnSZ2hDJW5EZu3xnPyrmjVwHq0DOnrpV7XncM,6385
 pycodegate/rules/fastapi.py,sha256=16LOX97gXvVsWf0cvdqp5Ji-byzlKQP51iAy_yGX14Q,2769
 pycodegate/rules/flask.py,sha256=htKFDjV2VZtAyE4ELlxYqDQUSYM4ROJZnS7UI_PK-xA,4574
-pycodegate/rules/imports.py,sha256=yp5aSIrcw7AdqgljkJEywEJ_HQ2GcqZVIcDdVSK_R30,3404
+pycodegate/rules/imports.py,sha256=L5o_JtG1DNvV5LdoG1PgEwjf6CrWgPsUSMzK7v1Q5g0,3751
 pycodegate/rules/performance.py,sha256=qZ9Tw0CNwjeIsqDwPulZXZu0VWWJQuU-r0TvG9odaQU,4512
 pycodegate/rules/security.py,sha256=fdISx3yLVtQ2OjVtnaDBUOPXK6Tpq4ykntRlKr_1bAs,7515
-pycodegate/rules/structure.py,sha256=VC19nrGyiATurP4tvnK7scBI1dZ9bDKyPYKiowzIVLI,9138
+pycodegate/rules/structure.py,sha256=rURxlkMjQp6O-0xhe72fscTuUYZVyU-YxGWhbxXeSwA,8938
 pycodegate/utils/__init__.py,sha256=MTVfXf-fKi2bjxXedkveORadRqo5qSUK4pMl08WJWdA,41
 pycodegate/utils/ast_helpers.py,sha256=bRQwOsUvNASjq0wjZ_Yc0cDmVnXPGhujzxZV2Qff0Z8,538
 pycodegate/utils/badge.py,sha256=dh49h3LaOY402WxestPb0m38wQWhLZjNMn5NyuOT_ag,1432
 pycodegate/utils/diff.py,sha256=o8YuqBqOwiHmPDsjFKXAlPphd0m8y20EwXRrcSvaoIg,824
 pycodegate/utils/file_discovery.py,sha256=2tqW1LPoNjH2Y57UDo9sLyCioXvKBv8vFTmtmh2knpw,1472
-pycodegate/utils/fixer.py,sha256=EDw4dMqLqnzGaQwaGyehrnHBirFajYxRDONnzp9I6HM,890
+pycodegate/utils/fixer.py,sha256=SlKH1mt9YaMxfZk-T_rFOc3FeDKNTnqTzbFdiD9eTXI,918
 pycodegate/utils/precommit.py,sha256=nzcmXc0NPAaxL-ZqDkDyHuuua4SiRXK2HrJZq3HLkMc,1737
-pycodegate-0.1.2.dist-info/METADATA,sha256=worPWZbmaQz_PNIsueyzvqXmy5chnpHcZa2KalzKoU8,11516
-pycodegate-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-pycodegate-0.1.2.dist-info/entry_points.txt,sha256=oSjjP_VAA3O74Y5a-IqIHYsT7-Ljuv97wXiMQ5RdOg0,51
-pycodegate-0.1.2.dist-info/licenses/LICENSE,sha256=YQAkET2EceAFEwM7LLUco13527CKFujpBapIIRPshTQ,1068
-pycodegate-0.1.2.dist-info/RECORD,,
+pycodegate-0.1.3.dist-info/METADATA,sha256=oexR4oMM3sHfX4vMPeoYGyCvMxtJvA-qIaKWzddxtik,11879
+pycodegate-0.1.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pycodegate-0.1.3.dist-info/entry_points.txt,sha256=oSjjP_VAA3O74Y5a-IqIHYsT7-Ljuv97wXiMQ5RdOg0,51
+pycodegate-0.1.3.dist-info/licenses/LICENSE,sha256=YQAkET2EceAFEwM7LLUco13527CKFujpBapIIRPshTQ,1068
+pycodegate-0.1.3.dist-info/RECORD,,