pycodegate 0.1.2__tar.gz → 0.1.3__tar.gz

{pycodegate-0.1.2 → pycodegate-0.1.3}/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-pycodegate is a Python code quality gate that produces a 0–100 health score. It detects your framework, runs parallel lint and dead-code analysis across 40+ rules, and reports findings by severity so you always know what to fix first.
+PyCodeGate is the quality gate for AI-generated Python code. It produces a 0–100 health score by detecting your framework, running parallel lint and dead-code analysis across 40+ rules, and reporting findings by severity — so you can trust what your AI agent just wrote.
 
 ## Quick Start
 

{pycodegate-0.1.2 → pycodegate-0.1.3}/PKG-INFO

@@ -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 → pycodegate-0.1.3}/README.md

@@ -1,6 +1,6 @@
 <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>
@@ -11,9 +11,13 @@
 
 ---
 
+## 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 → pycodegate-0.1.3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "pycodegate"
-version = "0.1.2"
-description = "One command. One score. Your Python quality gate."
+version = "0.1.3"
+description = "Trust, but verify. The quality gate for AI-generated Python code."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
@@ -72,4 +72,8 @@ ignore = ["SIM102"]  # nested ifs in AST walking are clearer than combined condi
 
 [tool.pycodegate]
 [tool.pycodegate.ignore]
-files = ["tests/fixtures/**"]
+files = ["tests/fixtures/**", "tests/**"]
+
+[tool.pycodegate.per-file-suppress]
+# Click CLI entry-points must declare all options as individual parameters
+"src/pycodegate/cli.py" = ["too-many-arguments"]

{pycodegate-0.1.2 → pycodegate-0.1.3}/src/pycodegate/__init__.py

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

{pycodegate-0.1.2 → pycodegate-0.1.3}/src/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-0.1.2 → pycodegate-0.1.3}/src/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-0.1.2 → pycodegate-0.1.3}/src/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-0.1.2 → pycodegate-0.1.3}/src/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-0.1.3/src/pycodegate/rules/imports.py

@@ -0,0 +1,109 @@
+"""Import rules: circular dependency detection."""
+
+from __future__ import annotations
+
+import ast
+import os
+from collections import defaultdict
+from pathlib import Path
+
+from pycodegate.types import Category, Diagnostic, Severity
+
+
+class ImportsRules:
+    """Project-level import analysis."""
+
+    def check_project(self, project_path: str, source_files: list[str]) -> list[Diagnostic]:
+        """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]:
+        # Build import graph: module_name -> set of imported module_names
+        graph: dict[str, set[str]] = defaultdict(set)
+        file_map: dict[str, str] = {}  # module_name -> file_path
+
+        root = str(Path(project_path).resolve())
+
+        for filepath in source_files:
+            self._collect_imports_for_module(filepath, root, graph, file_map)
+
+        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."""
+        try:
+            rel = os.path.relpath(filepath, root)
+        except ValueError:
+            return None
+
+        # Remove .py extension
+        if rel.endswith(".py"):
+            rel = rel[:-3]
+        else:
+            return None
+
+        # Remove __init__ suffix
+        if rel.endswith("__init__"):
+            rel = rel[:-9].rstrip(os.sep)
+
+        if not rel:
+            return None
+
+        # Convert path separators to dots
+        return rel.replace(os.sep, ".").replace("/", ".")

{pycodegate-0.1.2 → pycodegate-0.1.3}/src/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-0.1.2 → pycodegate-0.1.3}/src/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-0.1.2 → pycodegate-0.1.3}/src/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 → pycodegate-0.1.3}/tests/test_output.py

@@ -1,7 +1,9 @@
+import re
 from io import StringIO
 
 from rich.console import Console
 
+import pycodegate.output as output_mod
 from pycodegate.output import (
     format_doctor_face,
     format_score_bar,
@@ -51,8 +53,6 @@ def _capture_output(result: ScanResult, verbose: bool = False) -> str:
     buf = StringIO()
     console = Console(file=buf, highlight=False, markup=True, no_color=True)
     # Patch console into print_scan_result by monkey-patching module
-    import pycodegate.output as output_mod
-
     original_console_cls = output_mod.Console
 
     class _FakeConsole(Console):
@@ -156,8 +156,6 @@ def test_sub_scores_appear():
     output = _capture_output(result)
     # With no diagnostics every category earns its max, so earned==max
     # Check at least one pattern like "(24/24)" or similar parenthesised numbers
-    import re
-
     matches = re.findall(r"\(\d+/\d+\)", output)
     assert len(matches) >= len(
         [

{pycodegate-0.1.2 → pycodegate-0.1.3}/uv.lock

@@ -203,7 +203,7 @@ wheels = [
 
 [[package]]
 name = "pycodegate"
-version = "0.1.1"
+version = "0.1.3"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

pycodegate-0.1.3/whitelist.py

@@ -0,0 +1,14 @@
+"""Vulture whitelist — these symbols are used but vulture can't detect it."""
+
+# Public API — called by external users of the pycodegate package
+import pycodegate.api
+import pycodegate.constants
+import pycodegate.types
+import pycodegate.utils.ast_helpers
+
+pycodegate.api.diagnose  # public API function
+pycodegate.constants.SCORE_GREAT  # exported threshold constant
+pycodegate.constants.SCORE_NEEDS_WORK  # exported threshold constant
+pycodegate.types.Diagnostic.column  # used by rules that track column offsets
+pycodegate.types.ProjectInfo.has_type_hints  # accessed in output/templates
+pycodegate.utils.ast_helpers.parse_file  # utility used by rule checkers

pycodegate-0.1.2/src/pycodegate/rules/imports.py

@@ -1,96 +0,0 @@
-"""Import rules: circular dependency detection."""
-
-from __future__ import annotations
-
-import ast
-import os
-from collections import defaultdict
-from pathlib import Path
-
-from pycodegate.types import Category, Diagnostic, Severity
-
-
-class ImportsRules:
-    """Project-level import analysis."""
-
-    def check_project(self, project_path: str, source_files: list[str]) -> list[Diagnostic]:
-        """Detect circular imports across the project."""
-        return self._check_circular_imports(project_path, source_files)
-
-    def _check_circular_imports(
-        self, project_path: str, source_files: list[str]
-    ) -> list[Diagnostic]:
-        # Build import graph: module_name -> set of imported module_names
-        graph: dict[str, set[str]] = defaultdict(set)
-        file_map: dict[str, str] = {}  # module_name -> file_path
-
-        root = 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()
-
-        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
-
-    def _file_to_module(self, filepath: str, root: str) -> str | None:
-        """Convert a file path to a dotted module name."""
-        try:
-            rel = os.path.relpath(filepath, root)
-        except ValueError:
-            return None
-
-        # Remove .py extension
-        if rel.endswith(".py"):
-            rel = rel[:-3]
-        else:
-            return None
-
-        # Remove __init__ suffix
-        if rel.endswith("__init__"):
-            rel = rel[:-9].rstrip(os.sep)
-
-        if not rel:
-            return None
-
-        # Convert path separators to dots
-        return rel.replace(os.sep, ".").replace("/", ".")

pycodegate-0.1.2/whitelist.py

@@ -1,14 +0,0 @@
-"""Vulture whitelist — these symbols are used but vulture can't detect it."""
-
-# Public API
-from python_doctor.api import diagnose  # noqa: F401
-
-# Dataclass fields accessed dynamically or in templates
-from python_doctor.types import ProjectInfo, Score  # noqa: F401
-
-ProjectInfo.has_type_hints  # type: ignore[truthy-function]
-ProjectInfo.source_file_count  # type: ignore[truthy-function]
-Score.label  # type: ignore[truthy-function]
-
-# AST helper used by rules
-from python_doctor.utils.ast_helpers import parse_file  # noqa: F401