pycodegate 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

pycodegate/__init__.py

@@ -1,3 +1,10 @@
-"""Python Doctor - Diagnose your Python project's health."""
+"""PyCodeGate — the quality gate for AI-generated Python code."""
 
-__version__ = "0.2.0"
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pycodegate")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"

pycodegate/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m pycodegate``."""
+
+from pycodegate.cli import main
+
+if __name__ == "__main__":
+    main()

pycodegate/api.py

@@ -1,4 +1,4 @@
-"""Programmatic API for python-doctor."""
+"""Programmatic API for pycodegate."""
 
 from __future__ import annotations
 
@@ -18,7 +18,7 @@ def diagnose(
     dead_code: bool = True,
     diff_base: str | None = None,
 ) -> ScanResult:
-    """Run python-doctor analysis programmatically."""
+    """Run pycodegate analysis programmatically."""
     config = load_config(project_path)
     config.lint = lint
     config.dead_code = dead_code

pycodegate/cli.py

@@ -1,4 +1,4 @@
-"""CLI entry point for py-doctor."""
+"""CLI entry point for pycodegate."""
 
 from __future__ import annotations
 
@@ -58,15 +58,19 @@ def _maybe_run_fix(opts: CliOptions) -> None:
     if not opts.fix:
         return
     fixes = run_ruff_fix(opts.directory)
+    # Progress goes to stderr so it never pollutes --json/--score/--sarif stdout.
     if fixes == -1:
-        click.echo("ruff not found, skipping auto-fix")
+        click.echo("ruff not found, skipping auto-fix", err=True)
     else:
-        click.echo(f"Fixed {fixes} issues via ruff")
+        click.echo(f"Fixed {fixes} issues via ruff", err=True)
 
 
 def _build_config(opts: CliOptions):
     """Load config and apply CLI overrides."""
-    config = load_config(opts.directory)
+    try:
+        config = load_config(opts.directory)
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
     config.lint = opts.lint
     config.dead_code = opts.dead_code
     config.verbose = opts.verbose

pycodegate/config.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 from pycodegate._compat import tomllib
+from pycodegate.types import ImportBoundary
 
 
 @dataclass
@@ -19,6 +20,7 @@ class Config:
     profile: str | None = None
     per_file_suppress: dict[str, list[str]] = field(default_factory=dict)
     max_deduction: dict[str, int] = field(default_factory=dict)
+    import_boundaries: list[ImportBoundary] = field(default_factory=list)
 
 
 def load_config(project_path: str) -> Config:
@@ -53,8 +55,9 @@ def _parse_doctor_toml(path: Path) -> Config:
         ignore_rules=ignore.get("rules", []),
         ignore_files=ignore.get("files", []),
         profile=options.get("profile", None),
-        per_file_suppress=data.get("per-file-suppress", {}),
-        max_deduction=data.get("max-deduction", {}),
+        per_file_suppress=_read_per_file_suppress(data),
+        max_deduction=_read_max_deduction(data),
+        import_boundaries=_read_import_boundaries(data),
     )
 
 
@@ -76,6 +79,52 @@ def _parse_pyproject_toml(path: Path) -> Config:
         ignore_rules=ignore.get("rules", []),
         ignore_files=ignore.get("files", []),
         profile=section.get("profile", None),
-        per_file_suppress=section.get("per-file-suppress", {}),
-        max_deduction=section.get("max-deduction", {}),
+        per_file_suppress=_read_per_file_suppress(section),
+        max_deduction=_read_max_deduction(section),
+        import_boundaries=_read_import_boundaries(section),
     )
+
+
+def _read_per_file_suppress(table: dict) -> dict:
+    """Read per-file rule suppression, accepting the documented ``per-file-ignores`` alias."""
+    return table.get("per-file-suppress") or table.get("per-file-ignores") or {}
+
+
+def _read_import_boundaries(table: dict) -> list[ImportBoundary]:
+    boundaries = table.get("import-boundaries", [])
+    if not isinstance(boundaries, list):
+        raise ValueError("import-boundaries must be an array of tables")
+    result = []
+    for boundary in boundaries:
+        if not isinstance(boundary, dict):
+            raise ValueError("Each import boundary must be a table")
+        for key in ("files", "forbidden"):
+            values = boundary.get(key)
+            if not isinstance(values, list) or not values:
+                raise ValueError(f"Import boundary {key} must be a nonempty array of strings")
+            if any(not isinstance(value, str) or not value.strip() for value in values):
+                raise ValueError(f"Import boundary {key} must contain nonempty strings")
+        message = boundary.get("message", "Move shared code behind the allowed layer's API")
+        if any(
+            not all(part.isidentifier() for part in module.split("."))
+            for module in boundary["forbidden"]
+        ):
+            raise ValueError("Import boundary forbidden entries must be dotted module names")
+        if not isinstance(message, str) or not message.strip():
+            raise ValueError("Import boundary message must be a nonempty string")
+        result.append(
+            ImportBoundary(tuple(boundary["files"]), tuple(boundary["forbidden"]), message)
+        )
+    return result
+
+
+def _read_max_deduction(table: dict) -> dict:
+    """Read scoring max-deduction overrides.
+
+    Documented location is the ``[scoring]`` table (``max-deduction.Security = 20``);
+    the historical top-level ``[max-deduction]`` table is still accepted.
+    """
+    scoring = table.get("scoring", {})
+    if isinstance(scoring, dict) and "max-deduction" in scoring:
+        return scoring["max-deduction"]
+    return table.get("max-deduction", {})

pycodegate/constants.py

@@ -1,4 +1,4 @@
-"""Constants and thresholds for python-doctor."""
+"""Constants and thresholds for pycodegate."""
 
 from pycodegate.types import Category
 
@@ -21,9 +21,30 @@ CATEGORY_WEIGHTS: dict = {
     Category.PERFORMANCE: 2,
     Category.STRUCTURE: 2,
     Category.IMPORTS: 1,
+    Category.DEPENDENCIES: 1,
     Category.DEAD_CODE: 1,
 }
 
+# Rules suppressed in test files: idiomatic in tests, noise as findings.
+# Asserts are the pytest idiom; tests are long, deeply nested, take many fixtures,
+# and legitimately contain fixture "secrets", weak hashes, and pickle round-trips.
+RULES_SUPPRESSED_IN_TESTS: frozenset[str] = frozenset(
+    {
+        "no-assert-in-production",
+        "no-god-function",
+        "no-giant-module",
+        "no-deep-nesting",
+        "too-many-arguments",
+        "high-complexity",
+        "critical-complexity",
+        "structure/large-file",
+        "no-hardcoded-secret",
+        "no-weak-hash",
+        "no-pickle-load",
+        "no-string-concat-in-loop",
+    }
+)
+
 # Framework categories map to their parent category for scoring
 FRAMEWORK_CATEGORY_MAP: dict = {
     Category.DJANGO: Category.SECURITY,

pycodegate/output.py

@@ -12,6 +12,7 @@ from rich.text import Text
 
 from pycodegate import __version__
 from pycodegate.constants import CATEGORY_WEIGHTS, FRAMEWORK_CATEGORY_MAP
+from pycodegate.score import category_breakdown
 from pycodegate.types import Category, Diagnostic, ScanResult, Severity
 
 BAR_WIDTH = 50
@@ -78,42 +79,6 @@ def _score_color(score: int) -> str:
     return "red"
 
 
-def _compute_category_sub_scores(
-    diagnostics: list[Diagnostic],
-) -> dict[Category, tuple[int, int]]:
-    """Return {resolved_category: (earned, max)} for each category in CATEGORY_WEIGHTS."""
-    total_weight = sum(CATEGORY_WEIGHTS.values())
-    max_deductions = {cat: round(w / total_weight * 100) for cat, w in CATEGORY_WEIGHTS.items()}
-    # Fix rounding to ensure sum == 100
-    diff = 100 - sum(max_deductions.values())
-    if diff != 0:
-        highest = max(CATEGORY_WEIGHTS, key=lambda k: CATEGORY_WEIGHTS[k])
-        max_deductions[highest] += diff
-
-    # Group diagnostics by resolved category
-    by_category: dict[Category, list[Diagnostic]] = defaultdict(list)
-    for d in diagnostics:
-        resolved = FRAMEWORK_CATEGORY_MAP.get(d.category, d.category)
-        by_category[resolved].append(d)
-
-    # Compute actual deduction per category (same logic as score.py)
-    actual_deductions: dict[Category, float] = {}
-    for cat, diags in by_category.items():
-        costs = sorted([d.cost for d in diags], reverse=True)
-        cat_total = sum(c if i < 3 else c * 0.1 for i, c in enumerate(costs))
-        cap = max_deductions.get(cat, 10)
-        actual_deductions[cat] = min(cat_total, cap)
-
-    # Build (earned, max) per category
-    result: dict[Category, tuple[int, int]] = {}
-    for cat, max_ded in max_deductions.items():
-        deducted = round(actual_deductions.get(cat, 0.0))
-        earned = max_ded - deducted
-        result[cat] = (earned, max_ded)
-
-    return result
-
-
 def format_summary(result: ScanResult) -> str:
     """Format the full scan summary as a string (for testing)."""
     lines: list[str] = []
@@ -152,8 +117,9 @@ def print_scan_result(result: ScanResult, verbose: bool = False) -> None:
     console.print(f"  [dim]Source files:[/dim]    {p.source_file_count}")
     console.print()
 
-    # Category-grouped diagnostics with sub-scores
-    _print_category_groups(console, result.diagnostics, verbose)
+    # Category-grouped diagnostics with sub-scores (single source of truth from scoring)
+    breakdown = result.category_scores or category_breakdown(result.diagnostics)
+    _print_category_groups(console, result.diagnostics, breakdown, verbose)
 
     # Summary panel
     color = _score_color(result.score.value)
@@ -187,6 +153,7 @@ def output_json(result: ScanResult) -> None:
         "path": p.path,
         "score": result.score.value,
         "label": result.score.label,
+        "profile": result.profile,
         "errors": errors,
         "warnings": warnings,
         "elapsed_ms": result.elapsed_ms,
@@ -231,6 +198,18 @@ def _sarif_rules(diagnostics: list[Diagnostic]) -> list[dict]:
     ]
 
 
+def _sarif_location(diag: Diagnostic) -> dict:
+    """Build a SARIF physicalLocation, omitting the region for project-level findings.
+
+    SARIF 2.1.0 requires region.startLine >= 1, so a line of 0 (project-level
+    diagnostics) points at the artifact only rather than an invalid line 0.
+    """
+    physical: dict = {"artifactLocation": {"uri": diag.file_path}}
+    if diag.line and diag.line >= 1:
+        physical["region"] = {"startLine": diag.line, "startColumn": (diag.column or 0) + 1}
+    return {"physicalLocation": physical}
+
+
 def _sarif_results(diagnostics: list[Diagnostic]) -> list[dict]:
     """Build SARIF results array from diagnostics."""
     return [
@@ -238,17 +217,7 @@ def _sarif_results(diagnostics: list[Diagnostic]) -> list[dict]:
             "ruleId": d.rule,
             "level": "error" if d.severity == Severity.ERROR else "warning",
             "message": {"text": d.message},
-            "locations": [
-                {
-                    "physicalLocation": {
-                        "artifactLocation": {"uri": d.file_path},
-                        "region": {
-                            "startLine": d.line,
-                            "startColumn": (d.column or 0) + 1,
-                        },
-                    }
-                }
-            ],
+            "locations": [_sarif_location(d)],
         }
         for d in diagnostics
     ]
@@ -319,11 +288,10 @@ def _print_category_with_issues(
 def _print_category_groups(
     console: Console,
     diagnostics: list[Diagnostic],
+    sub_scores: dict[Category, tuple[int, int]],
     verbose: bool,
 ) -> None:
     """Print diagnostics grouped by category with sub-scores."""
-    sub_scores = _compute_category_sub_scores(diagnostics)
-
     # Build rule-grouped diagnostics per resolved category
     by_category: dict[Category, list[Diagnostic]] = defaultdict(list)
     for d in diagnostics:
@@ -338,7 +306,7 @@ def _print_category_groups(
         earned, maximum = sub_scores.get(cat, (CATEGORY_WEIGHTS[cat], CATEGORY_WEIGHTS[cat]))
         cat_diags = by_category.get(cat, [])
 
-        if earned == maximum:
+        if not cat_diags:
             console.print(
                 f"  [bold]{emoji} {name}[/bold] "
                 f"[green]({earned}/{maximum})[/green] [green]✓[/green]"

pycodegate/profile.py

@@ -20,7 +20,7 @@ PROFILES = {
     "web": Profile(name="web"),
     "cli": Profile(
         name="cli",
-        suppressed_rules=frozenset({"no-subprocess", "no-shell-exec"}),
+        suppressed_rules=frozenset({"no-os-system", "no-subprocess-shell"}),
         max_deduction_overrides={"Security": 15},
     ),
     "library": Profile(name="library"),

pycodegate/rules/__init__.py

@@ -11,6 +11,7 @@ from pycodegate.rules.dependencies import DependencyRules as DependencyRules
 from pycodegate.rules.django import DjangoRules
 from pycodegate.rules.fastapi import FastAPIRules
 from pycodegate.rules.flask import FlaskRules
+from pycodegate.rules.import_boundaries import ImportBoundaryRules as ImportBoundaryRules
 from pycodegate.rules.imports import ImportsRules as ImportsRules
 from pycodegate.rules.logging_rules import LoggingRules
 from pycodegate.rules.numpy_rules import NumpyRules
@@ -25,7 +26,7 @@ from pycodegate.rules.structure import StructureRules as StructureRules
 
 
 def get_all_rule_sets() -> list[BaseRules]:
-    """Return all available rule sets."""
+    """Return the core rule sets that run on every Python file."""
     return [
         SecurityRules(),
         PerformanceRules(),
@@ -35,21 +36,23 @@ def get_all_rule_sets() -> list[BaseRules]:
     ]
 
 
-_FRAMEWORK_MAP: dict[str, type[BaseRules]] = {
-    "django": DjangoRules,
-    "fastapi": FastAPIRules,
-    "flask": FlaskRules,
-    "pydantic": PydanticRules,
-    "sqlalchemy": SQLAlchemyRules,
-    "celery": CeleryRules,
-    "requests": RequestsRules,
-    "logging": LoggingRules,
-    "pandas": PandasRules,
-    "pytest": PytestRules,
-    "numpy": NumpyRules,
-}
+def get_import_gated_rules() -> list[tuple[BaseRules, str]]:
+    """Return (rule_set, trigger_module) pairs.
 
-
-def get_framework_rules(frameworks: list[str]) -> list[BaseRules]:
-    """Return framework/library-specific rule sets for all detected frameworks."""
-    return [_FRAMEWORK_MAP[f]() for f in frameworks if f in _FRAMEWORK_MAP]
+    Each library rule set runs only on files that actually import its module, so a
+    pandas rule never fires on a file that does not touch pandas — activation is
+    per-file and import-based rather than project-wide from the dependency manifest.
+    """
+    return [
+        (DjangoRules(), "django"),
+        (FastAPIRules(), "fastapi"),
+        (FlaskRules(), "flask"),
+        (PydanticRules(), "pydantic"),
+        (SQLAlchemyRules(), "sqlalchemy"),
+        (CeleryRules(), "celery"),
+        (RequestsRules(), "requests"),
+        (LoggingRules(), "logging"),
+        (PandasRules(), "pandas"),
+        (NumpyRules(), "numpy"),
+        (PytestRules(), "pytest"),
+    ]

pycodegate/rules/architecture.py

@@ -51,10 +51,25 @@ class ArchitectureRules(BaseRules):
         return diags
 
     def _walk_nesting(
-        self, node: ast.AST, depth: int, filename: str, diags: list[Diagnostic]
+        self,
+        node: ast.AST,
+        depth: int,
+        filename: str,
+        diags: list[Diagnostic],
+        is_elif: bool = False,
     ) -> None:
-        nesting_nodes = (ast.If, ast.For, ast.While, ast.With, ast.Try)
-        if isinstance(node, nesting_nodes):
+        nesting_nodes = (
+            ast.If,
+            ast.For,
+            ast.AsyncFor,
+            ast.While,
+            ast.With,
+            ast.AsyncWith,
+            ast.Try,
+        )
+        # An `elif` continues its parent `if` at the same nesting level, so it must
+        # not deepen the count — only a true block does.
+        if isinstance(node, nesting_nodes) and not is_elif:
             depth += 1
             if depth >= MAX_NESTING_DEPTH:
                 diags.append(
@@ -70,6 +85,18 @@ class ArchitectureRules(BaseRules):
                         cost=1.0,
                     )
                 )
+
+        if isinstance(node, ast.If):
+            for child in node.body:
+                self._walk_nesting(child, depth, filename, diags)
+            if len(node.orelse) == 1 and isinstance(node.orelse[0], ast.If):
+                # `elif`: same level, continue the chain without deepening.
+                self._walk_nesting(node.orelse[0], depth, filename, diags, is_elif=True)
+            else:
+                for child in node.orelse:
+                    self._walk_nesting(child, depth, filename, diags)
+            return
+
         for child in ast.iter_child_nodes(node):
             self._walk_nesting(child, depth, filename, diags)
 

pycodegate/rules/celery.py

@@ -72,9 +72,6 @@ class CeleryRules(BaseRules):
                 diags.extend(self._check_broad_autoretry(node, call, filename))
         return diags
 
-    # ------------------------------------------------------------------
-    # Rule: celery-missing-bind
-    # ------------------------------------------------------------------
     def _check_missing_bind(self, func_node, decorator, filename) -> list[Diagnostic]:
         args = func_node.args
         first_arg = args.args[0].arg if args.args else None
@@ -102,9 +99,6 @@ class CeleryRules(BaseRules):
             )
         ]
 
-    # ------------------------------------------------------------------
-    # Rule: celery-retry-no-exc
-    # ------------------------------------------------------------------
     def _check_retry_no_exc(self, handler: ast.ExceptHandler, filename: str) -> list[Diagnostic]:
         diags: list[Diagnostic] = []
         for node in ast.walk(handler):
@@ -129,9 +123,6 @@ class CeleryRules(BaseRules):
                         )
         return diags
 
-    # ------------------------------------------------------------------
-    # Rule: celery-broad-autoretry
-    # ------------------------------------------------------------------
     def _check_broad_autoretry(self, func_node, call: ast.Call, filename: str) -> list[Diagnostic]:
         for kw in call.keywords:
             if kw.arg != "autoretry_for":
@@ -154,9 +145,6 @@ class CeleryRules(BaseRules):
                         ]
         return []
 
-    # ------------------------------------------------------------------
-    # Rule: celery-direct-call
-    # ------------------------------------------------------------------
     def _check_direct_call(
         self, node: ast.Call, task_names: set[str], filename: str
     ) -> list[Diagnostic]:

pycodegate/rules/complexity.py

@@ -21,6 +21,7 @@ def _cyclomatic_complexity(func_node: ast.FunctionDef | ast.AsyncFunctionDef) ->
       - and / or boolean operators
       - assert statements
       - ternary expressions (IfExp)
+      - match/case arms
     """
     complexity = 1
     for node in ast.walk(func_node):
@@ -33,7 +34,7 @@ def _cyclomatic_complexity(func_node: ast.FunctionDef | ast.AsyncFunctionDef) ->
             complexity += 1
         elif isinstance(node, ast.BoolOp):
             complexity += len(node.values) - 1
-        elif isinstance(node, (ast.Assert, ast.IfExp)):
+        elif isinstance(node, (ast.Assert, ast.IfExp, ast.match_case)):
             complexity += 1
     return complexity
 

pycodegate/rules/correctness.py

@@ -1,4 +1,4 @@
-"""Correctness rules: mutable defaults, bare except, broad exception, assert in prod, return in __init__."""
+"""Correctness rules: mutable defaults, bare except, assert in prod, return in __init__."""
 
 from __future__ import annotations
 
@@ -19,7 +19,6 @@ class CorrectnessRules(BaseRules):
         diags: list[Diagnostic] = []
         diags.extend(self._check_mutable_defaults(tree, filename))
         diags.extend(self._check_bare_except(tree, filename))
-        diags.extend(self._check_broad_exception(tree, filename))
         diags.extend(self._check_assert_in_production(tree, filename))
         diags.extend(self._check_return_in_init(tree, filename))
         return diags
@@ -28,21 +27,23 @@ class CorrectnessRules(BaseRules):
         diags: list[Diagnostic] = []
         for node in ast.walk(tree):
             if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-                for default in node.args.defaults + node.args.kw_defaults:
-                    if default is not None and isinstance(default, (ast.List, ast.Dict, ast.Set)):
-                        diags.append(
-                            Diagnostic(
-                                file_path=filename,
-                                rule="no-mutable-default",
-                                severity=Severity.ERROR,
-                                category=Category.CORRECTNESS,
-                                message="Mutable default argument — shared across all calls",
-                                help="Use None as default and create the mutable inside the function body",
-                                line=node.lineno,
-                                column=node.col_offset,
-                                cost=2.0,
-                            )
+                defaults = node.args.defaults + node.args.kw_defaults
+                if any(
+                    d is not None and isinstance(d, (ast.List, ast.Dict, ast.Set)) for d in defaults
+                ):
+                    diags.append(
+                        Diagnostic(
+                            file_path=filename,
+                            rule="no-mutable-default",
+                            severity=Severity.ERROR,
+                            category=Category.CORRECTNESS,
+                            message="Mutable default argument — shared across all calls",
+                            help="Use None as default and create the mutable inside the function body",
+                            line=node.lineno,
+                            column=node.col_offset,
+                            cost=2.0,
                         )
+                    )
         return diags
 
     def _check_bare_except(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
@@ -64,33 +65,7 @@ class CorrectnessRules(BaseRules):
                 )
         return diags
 
-    def _check_broad_exception(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
-        diags: list[Diagnostic] = []
-        for node in ast.walk(tree):
-            if isinstance(node, ast.ExceptHandler) and node.type is not None:
-                if isinstance(node.type, ast.Name) and node.type.id in (
-                    "Exception",
-                    "BaseException",
-                ):
-                    diags.append(
-                        Diagnostic(
-                            file_path=filename,
-                            rule="no-broad-exception",
-                            severity=Severity.WARNING,
-                            category=Category.CORRECTNESS,
-                            message=f"Catching '{node.type.id}' is too broad — masks real errors",
-                            help="Catch specific exception types (ValueError, TypeError, etc.)",
-                            line=node.lineno,
-                            column=node.col_offset,
-                            cost=1.0,
-                        )
-                    )
-        return diags
-
     def _check_assert_in_production(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
-        if filename.startswith("test_") or "/test_" in filename or filename.endswith("_test.py"):
-            return []
-
         diags: list[Diagnostic] = []
         for node in ast.walk(tree):
             if isinstance(node, ast.Assert):
@@ -113,8 +88,8 @@ class CorrectnessRules(BaseRules):
         diags: list[Diagnostic] = []
         for node in ast.walk(tree):
             if isinstance(node, ast.FunctionDef) and node.name == "__init__":
-                for child in ast.walk(node):
-                    if isinstance(child, ast.Return) and child.value is not None:
+                for child in self._returns_in_scope(node):
+                    if child.value is not None:
                         diags.append(
                             Diagnostic(
                                 file_path=filename,
@@ -129,3 +104,20 @@ class CorrectnessRules(BaseRules):
                             )
                         )
         return diags
+
+    @staticmethod
+    def _returns_in_scope(func: ast.FunctionDef) -> list[ast.Return]:
+        """Return statements belonging to *func* directly, not to nested scopes."""
+        returns: list[ast.Return] = []
+        nested_scopes = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)
+
+        def visit(node: ast.AST) -> None:
+            for child in ast.iter_child_nodes(node):
+                if isinstance(child, nested_scopes):
+                    continue  # a nested scope owns its own return statements
+                if isinstance(child, ast.Return):
+                    returns.append(child)
+                visit(child)
+
+        visit(func)
+        return returns

pycodegate/rules/django.py

@@ -3,10 +3,26 @@
 from __future__ import annotations
 
 import ast
+import re
 
 from pycodegate.rules.base import BaseRules
 from pycodegate.types import Category, Diagnostic, Severity
 
+_SQL_PATTERN = re.compile(
+    r"(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE|ALTER)\s",
+    re.IGNORECASE,
+)
+
+
+def _binop_has_sql_literal(node: ast.AST) -> bool:
+    """True if any string literal inside a BinOp tree looks like SQL."""
+    return any(
+        isinstance(child, ast.Constant)
+        and isinstance(child.value, str)
+        and _SQL_PATTERN.search(child.value)
+        for child in ast.walk(node)
+    )
+
 
 class DjangoRules(BaseRules):
     """Django framework-specific checks."""
@@ -29,7 +45,11 @@ class DjangoRules(BaseRules):
             if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
                 if node.func.attr == "execute" and node.args:
                     arg = node.args[0]
-                    if isinstance(arg, ast.BinOp) and isinstance(arg.op, ast.Add):
+                    if (
+                        isinstance(arg, ast.BinOp)
+                        and isinstance(arg.op, ast.Add)
+                        and _binop_has_sql_literal(arg)
+                    ):
                         diags.append(
                             Diagnostic(
                                 file_path=filename,
@@ -78,6 +98,8 @@ class DjangoRules(BaseRules):
         for node in ast.walk(tree):
             if not isinstance(node, ast.For) or not self._is_queryset_iter(node.iter):
                 continue
+            if self._uses_eager_loading(node.iter):
+                continue  # select_related/prefetch_related already prevents the N+1
             if not isinstance(node.target, ast.Name):
                 continue
             var_name = node.target.id
@@ -97,6 +119,16 @@ class DjangoRules(BaseRules):
                 )
         return diags
 
+    @staticmethod
+    def _uses_eager_loading(node: ast.expr) -> bool:
+        """True if any call in the queryset chain is select_related/prefetch_related."""
+        current = node
+        while isinstance(current, ast.Call) and isinstance(current.func, ast.Attribute):
+            if current.func.attr in ("select_related", "prefetch_related"):
+                return True
+            current = current.func.value
+        return False
+
     @staticmethod
     def _has_related_access(loop_node: ast.For, var_name: str) -> bool:
         for child in ast.walk(loop_node):