forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/review/analyzers/architecture.py

@@ -0,0 +1,258 @@
+"""Architecture analyzer.
+
+Two heuristics:
+
+* **Layering**: enforce a "lower layers cannot import higher layers"
+  rule. By default we use the top-level ``forgecli`` package layout
+  (core -> utils -> providers -> graph -> optimizer -> builder ->
+  review) and forbid e.g. ``core`` from importing ``graph``. Users can
+  override the layer ordering via the ``layers`` attribute.
+* **Forbidden imports**: flag any import from a configurable
+  blacklist (default empty). The analyzer is conservative: it never
+  blocks legitimate patterns.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import ClassVar
+
+from forgecli.review.analyzer import AnalysisContext, Analyzer
+from forgecli.review.finding import Finding, Severity
+
+_DEFAULT_LAYERS: tuple[str, ...] = (
+    "core",
+    "config",
+    "utils",
+    "providers",
+    "graph",
+    "optimizer",
+    "builder",
+    "review",
+    "planner",
+    "git",
+    "memory",
+    "prompts",
+    "templates",
+    "cli",
+    "commit",
+    "build",
+)
+
+
+@dataclass
+class ArchitectureAnalyzer(Analyzer):
+    """Enforce a layer ordering and detect circular imports."""
+
+    name: ClassVar[str] = "architecture"
+    category: ClassVar[str] = "architecture"
+    layers: tuple[str, ...] = _DEFAULT_LAYERS
+    forbidden_imports: tuple[str, ...] = ()
+
+    def run(self, context: AnalysisContext) -> list[Finding]:
+        findings: list[Finding] = []
+        findings.extend(self._scan_layering(context))
+        findings.extend(self._scan_circular_imports(context))
+        findings.extend(self._scan_forbidden_imports(context))
+        return findings
+
+    # ------------------------------------------------------------------
+    # Layering
+    # ------------------------------------------------------------------
+
+    def _scan_layering(self, context: AnalysisContext) -> list[Finding]:
+        out: list[Finding] = []
+        layer_index = {layer: index for index, layer in enumerate(self.layers)}
+        for file in context.files:
+            try:
+                tree = ast.parse(file.text)
+            except SyntaxError:
+                continue
+            file_layer = _top_level_layer(file.path)
+            if file_layer is None or file_layer not in layer_index:
+                continue
+            for node in ast.walk(tree):
+                imported = _imported_module(node)
+                if imported is None:
+                    continue
+                target_layer = _layer_of(imported, layer_index)
+                if target_layer is None:
+                    continue
+                if layer_index[target_layer] <= layer_index[file_layer]:
+                    continue
+                out.append(
+                    Finding(
+                        rule_id="ARCH001",
+                        category="architecture",
+                        severity=Severity.MEDIUM,
+                        message=(
+                            f"Layer '{file_layer}' imports from higher layer "
+                            f"'{target_layer}' ({imported})."
+                        ),
+                        path=str(file.path),
+                        line=getattr(node, "lineno", 1),
+                        suggestion=(
+                            "Move the dependency, or invert the call so the "
+                            "lower layer exposes a callback."
+                        ),
+                    )
+                )
+        return out
+
+    def _scan_circular_imports(self, context: AnalysisContext) -> list[Finding]:
+        """Detect cycles in the package-level import graph.
+
+        For each ``forgecli/<layer>/...`` file we record the set of
+        other layers it imports. A cycle is reported as a single
+        finding describing the cycle.
+        """
+        graph: dict[str, set[str]] = defaultdict(set)
+        for file in context.files:
+            layer = _top_level_layer(file.path)
+            if layer is None or layer not in self.layers:
+                continue
+            try:
+                tree = ast.parse(file.text)
+            except SyntaxError:
+                continue
+            for node in ast.walk(tree):
+                imported = _imported_module(node)
+                if imported is None:
+                    continue
+                target = _layer_of(imported, {layer: idx for idx, layer in enumerate(self.layers)})
+                if target is None or target == layer:
+                    continue
+                graph[layer].add(target)
+        out: list[Finding] = []
+        for cycle in _find_cycles(graph):
+            message = " -> ".join([*cycle, cycle[0]])
+            out.append(
+                Finding(
+                    rule_id="ARCH002",
+                    category="architecture",
+                    severity=Severity.MEDIUM,
+                    message=f"Circular import between layers: {message}",
+                    path=None,
+                    line=None,
+                    suggestion=(
+                        "Break the cycle by extracting a shared interface "
+                        "or by deferring the import inside the function."
+                    ),
+                    extra={"cycle": cycle},
+                )
+            )
+        return out
+
+    def _scan_forbidden_imports(self, context: AnalysisContext) -> list[Finding]:
+        if not self.forbidden_imports:
+            return []
+        out: list[Finding] = []
+        for file in context.files:
+            try:
+                tree = ast.parse(file.text)
+            except SyntaxError:
+                continue
+            for node in ast.walk(tree):
+                imported = _imported_module(node)
+                if imported is None:
+                    continue
+                for forbidden in self.forbidden_imports:
+                    if imported == forbidden or imported.startswith(forbidden + "."):
+                        out.append(
+                            Finding(
+                                rule_id="ARCH003",
+                                category="architecture",
+                                severity=Severity.HIGH,
+                                message=(
+                                    f"Forbidden import: '{imported}' is not "
+                                    f"allowed in this project."
+                                ),
+                                path=str(file.path),
+                                line=getattr(node, "lineno", 1),
+                                suggestion=(
+                                    "Use the public API exposed by the "
+                                    "intended module."
+                                ),
+                            )
+                        )
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _top_level_layer(path) -> str | None:
+    """Return the layer name for a path under the project source root."""
+    parts = path.parts
+    # Look for "forgecli" in the path; the next part is the layer.
+    try:
+        idx = parts.index("forgecli")
+    except ValueError:
+        return None
+    if idx + 1 >= len(parts):
+        return None
+    return parts[idx + 1]
+
+
+def _imported_module(node: ast.AST) -> str | None:
+    """Return the dotted module name for an import node, or None."""
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            return alias.name
+    if isinstance(node, ast.ImportFrom):
+        if node.module is None:
+            return None
+        return node.module
+    return None
+
+
+def _layer_of(module: str, layer_index: dict[str, int]) -> str | None:
+    """Return the layer name for a dotted module, or None."""
+    if not module:
+        return None
+    parts = module.split(".")
+    if "forgecli" in parts:
+        idx = parts.index("forgecli")
+        if idx + 1 < len(parts):
+            candidate = parts[idx + 1]
+            if candidate in layer_index:
+                return candidate
+    # External modules: not a layer.
+    return None
+
+
+def _find_cycles(graph: dict[str, set[str]]) -> list[list[str]]:
+    """Return a list of cycles in ``graph`` (each cycle as a list of nodes)."""
+    cycles: list[list[str]] = []
+    seen_cycles: set[tuple[str, ...]] = set()
+    for start in graph:
+        visited: set[str] = set()
+
+        def dfs(node: str, stack: list[str], visited: set[str]) -> None:
+            if node in visited:
+                if node in stack:
+                    cycle_start = stack.index(node)
+                    cycle = stack[cycle_start:]
+                    key = tuple(sorted(cycle))
+                    if key not in seen_cycles:
+                        seen_cycles.add(key)
+                        cycles.append(cycle)
+                return
+            visited.add(node)
+            stack.append(node)
+            for neighbor in graph.get(node, ()):
+                dfs(neighbor, stack, visited)
+            stack.pop()
+
+        dfs(start, [], visited)
+    return cycles
+
+
+__all__ = ["ArchitectureAnalyzer"]
+
+
+# Silence unused-import warnings.

forgecli/review/analyzers/complexity.py

@@ -0,0 +1,167 @@
+"""Complexity analyzer.
+
+Reports per-function:
+
+* **line count** — anything over a threshold (default 80) is flagged;
+* **parameter count** — anything over 5 is flagged;
+* **cyclomatic complexity** — branches + boolean operators + 1.
+
+The numbers are intentionally conservative; this is a smoke-detector
+for "this function has gotten too big" rather than a precise metric.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import ClassVar
+
+from forgecli.review.analyzer import AnalysisContext, Analyzer
+from forgecli.review.finding import Finding, Severity
+
+_BRANCH_NODES: tuple[type[ast.AST], ...] = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.ExceptHandler,
+    ast.With,
+    ast.AsyncWith,
+    ast.BoolOp,
+    ast.IfExp,
+    ast.Match,
+)
+
+
+@dataclass
+class ComplexityAnalyzer(Analyzer):
+    """Cyclomatic-ish complexity and size metrics per function."""
+
+    name: ClassVar[str] = "complexity"
+    category: ClassVar[str] = "complexity"
+    max_function_lines: int = 80
+    max_parameters: int = 5
+    max_cyclomatic: int = 12
+
+    def run(self, context: AnalysisContext) -> list[Finding]:
+        findings: list[Finding] = []
+        parents: dict[ast.AST, ast.AST] = {}
+        for file in context.files:
+            try:
+                tree = ast.parse(file.text)
+            except SyntaxError:
+                continue
+            _link_parents(tree, parents)
+            for function in _walk_functions(tree):
+                findings.extend(self._check_function(file, function, parents))
+        return findings
+
+    def _check_function(self, file, function, parents) -> list[Finding]:
+        out: list[Finding] = []
+        line_count = _function_length(function)
+        params = len(function.args.args) + len(function.args.kwonlyargs)
+        cyclomatic = _cyclomatic_complexity(function)
+        name = _qualified_function_name(function, parents)
+
+        if line_count > self.max_function_lines:
+            out.append(
+                Finding(
+                    rule_id="CPLX001",
+                    category="complexity",
+                    severity=Severity.LOW,
+                    message=(
+                        f"Function {name} is {line_count} lines long "
+                        f"(>{self.max_function_lines})."
+                    ),
+                    path=str(file.path),
+                    line=function.lineno,
+                    suggestion="Split into smaller helpers; extract branches.",
+                    extra={"lines": line_count},
+                )
+            )
+        if params > self.max_parameters:
+            out.append(
+                Finding(
+                    rule_id="CPLX002",
+                    category="complexity",
+                    severity=Severity.LOW,
+                    message=(
+                        f"Function {name} takes {params} parameters "
+                        f"(>{self.max_parameters}); consider a parameter object."
+                    ),
+                    path=str(file.path),
+                    line=function.lineno,
+                    suggestion="Bundle related parameters into a dataclass.",
+                    extra={"params": params},
+                )
+            )
+        if cyclomatic > self.max_cyclomatic:
+            out.append(
+                Finding(
+                    rule_id="CPLX003",
+                    category="complexity",
+                    severity=Severity.MEDIUM,
+                    message=(
+                        f"Function {name} has cyclomatic complexity "
+                        f"{cyclomatic} (>{self.max_cyclomatic})."
+                    ),
+                    path=str(file.path),
+                    line=function.lineno,
+                    suggestion=(
+                        "Decompose the function along its decision points."
+                    ),
+                    extra={"cyclomatic": cyclomatic},
+                )
+            )
+        return out
+
+
+def _walk_functions(tree: ast.AST) -> list[ast.FunctionDef | ast.AsyncFunctionDef]:
+    return [
+        node
+        for node in ast.walk(tree)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+    ]
+
+
+def _link_parents(root: ast.AST, parents: dict[ast.AST, ast.AST]) -> None:
+    """Populate ``parents[child] = parent`` for every AST node in ``root``."""
+    for parent in ast.walk(root):
+        for child in ast.iter_child_nodes(parent):
+            parents[child] = parent
+
+
+def _function_length(function) -> int:
+    if function.end_lineno is None or function.lineno is None:
+        return 0
+    return function.end_lineno - function.lineno + 1
+
+
+def _cyclomatic_complexity(function) -> int:
+    """Approximate cyclomatic complexity: 1 + number of decision points."""
+    complexity = 1
+    for node in ast.walk(function):
+        if isinstance(node, _BRANCH_NODES):
+            complexity += 1
+        if isinstance(node, ast.BoolOp):
+            # Each `and`/`or` operator adds an extra edge.
+            complexity += len(node.values) - 1
+        if isinstance(node, ast.comprehension):
+            # Comprehensions have implicit branches.
+            complexity += sum(1 for _ in node.ifs)
+        if isinstance(node, ast.ExceptHandler):
+            complexity += 1
+    return complexity
+
+
+def _qualified_function_name(function, parents) -> str:
+    """Best-effort qualified name for a function definition."""
+    parts: list[str] = [function.name]
+    parent = parents.get(function)
+    while isinstance(parent, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        parts.append(parent.name)
+        parent = parents.get(parent)
+    return ".".join(reversed(parts))
+
+
+__all__ = ["ComplexityAnalyzer"]

forgecli/review/analyzers/dead_code.py

@@ -0,0 +1,262 @@
+"""Dead-code analyzer.
+
+Detects:
+
+* private (``_foo``) functions/classes defined at module level but
+  never referenced anywhere in the project (other than their
+  definition);
+* ``__all__``-listed symbols that are not actually defined in the
+  module.
+
+The analyzer is conservative: ``__init__``, dunder methods,
+``__all__`` re-exports, and pytest-style ``test_*`` functions are
+ignored. The analyzer also ignores private symbols whose name is
+listed in a module-level ``__all__`` tuple (re-exported).
+"""
+
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar
+
+from forgecli.review.analyzer import AnalysisContext, Analyzer
+from forgecli.review.finding import Finding, Severity
+
+_DUNDER_NAMES: frozenset[str] = frozenset(
+    {
+        "__init__",
+        "__del__",
+        "__repr__",
+        "__str__",
+        "__bytes__",
+        "__format__",
+        "__lt__",
+        "__le__",
+        "__eq__",
+        "__ne__",
+        "__gt__",
+        "__ge__",
+        "__hash__",
+        "__bool__",
+        "__call__",
+        "__len__",
+        "__length_hint__",
+        "__getitem__",
+        "__setitem__",
+        "__delitem__",
+        "__iter__",
+        "__next__",
+        "__reversed__",
+        "__contains__",
+        "__add__",
+        "__sub__",
+        "__mul__",
+        "__matmul__",
+        "__truediv__",
+        "__floordiv__",
+        "__mod__",
+        "__divmod__",
+        "__pow__",
+        "__lshift__",
+        "__rshift__",
+        "__and__",
+        "__or__",
+        "__xor__",
+        "__radd__",
+        "__rsub__",
+        "__rmul__",
+        "__rmatmul__",
+        "__rtruediv__",
+        "__rfloordiv__",
+        "__rmod__",
+        "__rdivmod__",
+        "__rpow__",
+        "__rlshift__",
+        "__rrshift__",
+        "__rand__",
+        "__ror__",
+        "__rxor__",
+        "__iadd__",
+        "__isub__",
+        "__imul__",
+        "__imatmul__",
+        "__itruediv__",
+        "__ifloordiv__",
+        "__imod__",
+        "__ipow__",
+        "__ilshift__",
+        "__irshift__",
+        "__iand__",
+        "__ior__",
+        "__ixor__",
+        "__neg__",
+        "__pos__",
+        "__abs__",
+        "__invert__",
+        "__complex__",
+        "__int__",
+        "__float__",
+        "__index__",
+        "__round__",
+        "__trunc__",
+        "__floor__",
+        "__ceil__",
+        "__enter__",
+        "__exit__",
+        "__await__",
+        "__aiter__",
+        "__anext__",
+        "__aenter__",
+        "__aexit__",
+        "__set_name__",
+        "__class_getitem__",
+        "__init_subclass__",
+        "__class__",
+        "__dict__",
+        "__doc__",
+        "__module__",
+        "__qualname__",
+        "__annotations__",
+        "__slots__",
+        "__weakref__",
+    }
+)
+
+
+@dataclass
+class DeadCodeAnalyzer(Analyzer):
+    """Detect private symbols that are never referenced."""
+
+    name: ClassVar[str] = "dead-code"
+    category: ClassVar[str] = "dead-code"
+
+    def run(self, context: AnalysisContext) -> list[Finding]:
+        # Collect definitions and references.
+        definitions: dict[tuple[str, str], tuple[Path, int, str]] = {}
+        references: dict[tuple[str, str], int] = defaultdict(int)
+        # Maps module name -> set of private names in __all__
+        all_overrides: dict[str, set[str]] = {}
+
+        for file in context.files:
+            module = _module_of(file.path)
+            if module is None:
+                continue
+            try:
+                tree = ast.parse(file.text)
+            except SyntaxError:
+                continue
+            self._collect_definitions(tree, module, file, definitions, all_overrides)
+            self._collect_references(tree, module, references)
+
+        findings: list[Finding] = []
+        for key, (path, line, kind) in definitions.items():
+            module, name = key
+            if not name.startswith("_"):
+                continue
+            if name.startswith("__") and name.endswith("__"):
+                continue
+            if name in _DUNDER_NAMES:
+                continue
+            if name in all_overrides.get(module, set()):
+                continue
+            if references.get(key, 0) > 0:
+                continue
+            findings.append(
+                Finding(
+                    rule_id="DEAD001",
+                    category="dead-code",
+                    severity=Severity.LOW,
+                    message=(
+                        f"{kind} {name!r} is defined in {module} but never "
+                        "referenced."
+                    ),
+                    path=str(path),
+                    line=line,
+                    suggestion=(
+                        "Delete the symbol, or expose it in __all__ if it "
+                        "is part of the public API."
+                    ),
+                )
+            )
+        return findings
+
+    def _collect_definitions(
+        self,
+        tree: ast.AST,
+        module: str,
+        file,
+        definitions: dict,
+        all_overrides: dict,
+    ) -> None:
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, ast.Assign):
+                # Capture module-level __all__ assignments.
+                for target in node.targets:
+                    if (
+                        isinstance(target, ast.Name)
+                        and target.id == "__all__"
+                        and isinstance(node.value, (ast.List, ast.Tuple))
+                    ):
+                        names: set[str] = set()
+                        for element in node.value.elts:
+                            if isinstance(element, ast.Constant) and isinstance(
+                                element.value, str
+                            ):
+                                names.add(element.value)
+                        all_overrides[module] = names
+                continue
+            if isinstance(node, ast.FunctionDef):
+                definitions[(module, node.name)] = (file.path, node.lineno, "Function")
+            elif isinstance(node, ast.AsyncFunctionDef):
+                definitions[(module, node.name)] = (
+                    file.path,
+                    node.lineno,
+                    "Async function",
+                )
+            elif isinstance(node, ast.ClassDef):
+                definitions[(module, node.name)] = (file.path, node.lineno, "Class")
+            elif (
+                isinstance(node, ast.AnnAssign)
+                and isinstance(node.target, ast.Name)
+                and isinstance(node.value, ast.AST)
+            ):
+                definitions[(module, node.target.id)] = (
+                    file.path,
+                    node.lineno,
+                    "Variable",
+                )
+
+    def _collect_references(
+        self, tree: ast.AST, module: str, references: dict
+    ) -> None:
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Name):
+                references[(module, node.id)] += 1
+            elif isinstance(node, ast.Attribute):
+                base: ast.expr = node
+                while isinstance(base, ast.Attribute):
+                    base = base.value
+                if isinstance(base, ast.Name):
+                    # `self.foo` and `module.foo` both reference `foo` on
+                    # the same module; we count it once.
+                    references[(module, node.attr)] += 1
+
+
+def _module_of(path) -> str | None:
+    parts = path.parts
+    try:
+        idx = parts.index("forgecli")
+    except ValueError:
+        return None
+    relevant = parts[idx:]
+    if relevant[-1] == "__init__.py":
+        relevant = relevant[:-1]
+    elif relevant[-1].endswith(".py"):
+        relevant = (*relevant[:-1], relevant[-1][:-3])
+    return ".".join(relevant)
+
+
+__all__ = ["DeadCodeAnalyzer"]