pcina 0.1.1__py3-none-any.whl

pcina/__init__.py

@@ -0,0 +1,12 @@
+"""pcina - Python Code-pattern Investigator & Nonsense Analyzer.
+
+Counts code patterns grouped per section (module/class/function) to surface
+AI-generated bloat ("neuroslop"): paranoid raise chains, deep nesting, magic
+values, dead code and speculative abstraction. Pure stdlib, advisory findings,
+pylint-style rating + per-aspect scores. See docs/adr/ for the specs.
+
+Scores guide review; they never prove correctness or quality.
+"""
+
+__version__ = "0.1.0"
+SCHEMA = "pcina/1"

pcina/analyzer.py

@@ -0,0 +1,485 @@
+"""Core AST machinery: parse files, collect per-function records, cross-file references."""
+
+import ast
+import concurrent.futures
+import dataclasses
+from collections import Counter
+
+from pcina import files
+
+# Names that mark trust boundaries: validation here is legitimate (ADR-001 section 3.6).
+BOUNDARY_NAMES = ("main", "cli", "run", "parse_args", "load_config", "setup", "handle", "serve")
+DECORATOR_HINTS = ("app", "router", "command", "cli", "click", "pytest", "fixture", "property")
+
+# Tunable metric thresholds (ADR-002); named to keep the walker free of magic numbers.
+TERNARY_COGNITIVE_COST = 2
+BOOLOP_CHAIN_LIMIT = 3
+FSTRING_FIELD_LIMIT = 3
+DEEP_NESTING_LEVEL = 2
+
+
+def is_boundary(fn_node, filename):
+    """True when a function sits at a trust boundary, so paranoid checks are fine."""
+    is_dunder = fn_node.name.startswith("__") and fn_node.name.endswith("__")
+    if is_dunder or fn_node.name in BOUNDARY_NAMES:
+        return True
+    if fn_node.decorator_list:
+        return True
+    return "__init__.py" in str(filename) or fn_node.name.startswith("_")
+
+
+@dataclasses.dataclass
+class Fn:
+    """Raw stats about one function (excluding nested definitions)."""
+
+    qualname: str
+    start: int
+    end: int
+    params: int
+    docstring: bool
+    is_boundary: bool
+    cc: int = 1
+    cognitive: int = 0
+    max_nesting: int = 0
+    n_stmts: int = 0
+    raises: list = dataclasses.field(default_factory=list)
+    guard_raises: list = dataclasses.field(default_factory=list)
+    try_excepts: int = 0
+    broad_excepts: list = dataclasses.field(default_factory=list)
+    ternary_chains: list = dataclasses.field(default_factory=list)
+    boolop_chains: list = dataclasses.field(default_factory=list)
+    magic_numbers: list = dataclasses.field(default_factory=list)
+    urls: list = dataclasses.field(default_factory=list)
+    else_after_return: list = dataclasses.field(default_factory=list)
+    guard_opportunities: list = dataclasses.field(default_factory=list)
+    shadowed: list = dataclasses.field(default_factory=list)
+    big_fstrings: list = dataclasses.field(default_factory=list)
+
+
+@dataclasses.dataclass
+class Cls:
+    """Raw stats about one class."""
+
+    qualname: str
+    start: int
+    end: int
+    docstring: bool
+    n_methods: int
+
+
+@dataclasses.dataclass
+class FileReport:
+    """Everything collected from one parsed file."""
+
+    path: str
+    lines: list
+    module_docstring: bool
+    fns: list
+    classes: list
+    imports: list  # (name, line) - imported names usable at module level
+    module_defs: list  # (name, line, kind) - module-level functions/classes/constants
+    reference_names: Counter = dataclasses.field(default_factory=Counter)
+    lloc: int = 0
+    has_main_guard: bool = False
+    shadowed: list = dataclasses.field(default_factory=list)  # (line, local, module)
+
+
+class _FnWalker(ast.NodeVisitor):
+    """Collect raw per-function stats, attributing nothing to nested functions."""
+
+    def __init__(self, fn, record):
+        self.fn = fn
+        self.r = record
+        self.nesting = 0
+        self.prenesting = 0
+
+    def visit_FunctionDef(self, node):
+        if node is self.fn:
+            for stmt in node.body:
+                self.visit(stmt)
+        # nested defs belong to their own records, not this one
+
+    visit_AsyncFunctionDef = visit_FunctionDef
+
+    def _walk_all(self, node):
+        for child in ast.iter_child_nodes(node):
+            self.visit(child)
+
+    def visit_If(self, node):
+        self.r.cc += 1
+        self.r.cognitive += 1 + self.nesting
+        self.nesting += 1
+        for stmt in node.body:
+            self.visit(stmt)
+        has_exit = any(isinstance(s, (ast.Return, ast.Raise, ast.Continue, ast.Break))
+                       for s in node.body)
+        if node.orelse and has_exit and len(node.orelse) == 1:
+            self.r.else_after_return.append(node.orelse[0].lineno)
+        if self.nesting >= DEEP_NESTING_LEVEL and any(isinstance(s, ast.If) for s in node.body):
+            self.r.guard_opportunities.append(node.lineno)
+        if any(isinstance(s, ast.Raise) for s in node.body):
+            self.r.guard_raises.append(node.lineno)
+        for stmt in node.orelse:
+            self.visit(stmt)
+        self.nesting -= 1
+        self.r.max_nesting = max(self.r.max_nesting, self.nesting + 1)
+        self.visit(node.test)
+
+    def visit_For(self, node):
+        self.r.cc += 1
+        self.r.cognitive += 1 + self.nesting
+        self.nesting += 1
+        for stmt in node.body:
+            self.visit(stmt)
+        for stmt in node.orelse:
+            self.visit(stmt)
+        self.nesting -= 1
+        self.r.max_nesting = max(self.r.max_nesting, self.nesting + 1)
+
+    visit_AsyncFor = visit_For
+    visit_While = visit_For
+
+    def visit_Try(self, node):
+        # body handled via generic walk below; each handler is a decision
+        for stmt in node.body:
+            self.visit(stmt)
+        for handler in node.handlers:
+            self.r.cc += 1
+            self.r.cognitive += 1
+            self.r.try_excepts += 1
+            name = ""
+            if isinstance(handler.type, ast.Name):
+                name = handler.type.id
+            if isinstance(handler.type, ast.Attribute):
+                name = handler.type.attr
+            if handler.type is None or name in ("Exception", "BaseException"):
+                self.r.broad_excepts.append(handler.lineno)
+            for stmt in handler.body:
+                self.visit(stmt)
+        if node.finalbody:
+            for stmt in node.finalbody:
+                self.visit(stmt)
+
+    def visit_Raise(self, node):
+        self.r.raises.append(node.lineno)
+        self._walk_all(node)
+
+    def visit_Assert(self, node):
+        self.r.cc += 1
+        self._walk_all(node)
+
+    def visit_BoolOp(self, node):
+        if len(node.values) > BOOLOP_CHAIN_LIMIT:
+            self.r.boolop_chains.append((node.lineno, len(node.values)))
+        self.r.cc += 1
+        self._walk_all(node)
+
+    def visit_IfExp(self, node):
+        self.r.cc += 1
+        self.r.cognitive += TERNARY_COGNITIVE_COST
+        if isinstance(node.body, ast.IfExp) or isinstance(node.orelse, ast.IfExp):
+            self.r.ternary_chains.append(node.lineno)
+        self._walk_all(node)
+
+    def visit_JoinedStr(self, node):
+        formed = [v for v in node.values if isinstance(v, ast.FormattedValue)]
+        if len(formed) > FSTRING_FIELD_LIMIT:
+            self.r.big_fstrings.append(node.lineno)
+        self._walk_all(node)
+
+    def visit_Constant(self, node):
+        magic = _magic_literal(node.value)
+        if magic:
+            self.r.magic_numbers.append((node.lineno, node.value))
+        if isinstance(node.value, str) and _looks_like_url(node.value):
+            self.r.urls.append((node.lineno, node.value))
+        ast.NodeVisitor.generic_visit(self, node)
+
+    def generic_visit(self, node):
+        # comprehension generators and with add decisions
+        if isinstance(node, ast.comprehension):
+            self.r.cc += 1
+        if isinstance(node, ast.withitem):
+            self.r.cc += 1
+        ast.NodeVisitor.generic_visit(self, node)
+
+
+def _magic_literal(value, allowed=(0, 1, 2, -1, 0.0, 1.0, 2.0)):
+    """A bare literal that looks like a magic value (ADR-002 metric def)."""
+    if isinstance(value, bool) or isinstance(value, (int, float)):
+        if value in allowed or (isinstance(value, float) and float(value).is_integer() and int(value) in allowed):
+            return False
+        if abs(value) in (10, 100, 1000):  # conventional scales stay anonymous
+            return False
+        return True
+    return False
+
+
+def _looks_like_url(text):
+    return text.startswith(("http://", "https://", "ftp://"))
+
+
+def _n_params(fn):
+    total = len(fn.args.posonlyargs) + len(fn.args.args) + len(fn.args.kwonlyargs)
+    if fn.args.vararg:
+        total += 1
+    if fn.args.kwarg:
+        total += 1
+    return total
+
+
+class _FileWalker(ast.NodeVisitor):
+    """Top-level walk: module defs, imports, main guard, function records."""
+
+    def __init__(self, path, lines):
+        self.report = FileReport(path=path, lines=lines, module_docstring=False,
+                                 fns=[], classes=[], imports=[], module_defs=[])
+        self.prefix = ()
+
+    def visit_Module(self, node):
+        self.report.module_docstring = bool(ast.get_docstring(node))
+        self.report.has_main_guard = any(_is_main_guard(stmt) for stmt in node.body)
+        self.report.lloc = _count_statements(node)
+        for stmt in node.body:
+            if (isinstance(stmt, ast.Assign)
+                    and any(isinstance(t, ast.Name) and t.id == "__all__" for t in stmt.targets)):
+                self._record_exports(stmt.value)
+            self.visit(stmt)
+
+    def _record_exports(self, value):
+        """Count `__all__` entries as references: they are a re-export contract."""
+        if isinstance(value, (ast.Tuple, ast.List)):
+            for item in value.elts:
+                if isinstance(item, ast.Constant) and isinstance(item.value, str):
+                    self.report.reference_names[item.value] += 1
+        elif isinstance(value, ast.Constant) and isinstance(value.value, str):
+            self.report.reference_names[value.value] += 1
+
+    def _register_fn(self, node):
+        qual = ".".join(self.prefix + (node.name,))
+        record = Fn(qualname=qual, start=node.lineno, end=getattr(node, "end_lineno", node.lineno),
+                    params=_n_params(node), docstring=bool(ast.get_docstring(node)),
+                    is_boundary=is_boundary(node, self.report.path))
+        walker = _FnWalker(node, record)
+        for stmt in node.body:
+            walker.visit(stmt)
+        self.report.fns.append(record)
+        self._record_decorators(node.decorator_list)
+        self._record_annotations(node)
+        if not self.prefix:
+            # only TOP-LEVEL defs are module definitions (contract: module_defs)
+            self.report.module_defs.append((node.name, node.lineno, "function"))
+        saved, self.prefix = self.prefix, self.prefix + (node.name,)
+        for stmt in node.body:
+            self.visit(stmt)  # register nested fns/classes too
+        self.prefix = saved
+
+    def _record_decorators(self, decorator_list):
+        """Decorated names are real references (e.g. @dataclass keeps an import alive)."""
+        for name in _decorator_names(decorator_list):
+            self.report.reference_names[name] += 1
+
+    def _record_expr_refs(self, expr):
+        """Every Name in an expression subtree is a use (class bases, metaclass)."""
+        for sub in _expr_name_ids(expr):
+            self.report.reference_names[sub] += 1
+
+    def _record_annotations(self, fn_node):
+        """Annotation-only uses (typing imports) are real references (Vulture #216)."""
+        for name in _annotation_names(fn_node):
+            self.report.reference_names[name] += 1
+
+    def visit_FunctionDef(self, node):
+        self._register_fn(node)
+
+    visit_AsyncFunctionDef = visit_FunctionDef
+
+    def visit_ClassDef(self, node):
+        qual = ".".join(self.prefix + (node.name,))
+        methods = sum(1 for s in node.body
+                      if isinstance(s, (ast.FunctionDef, ast.AsyncFunctionDef)))
+        self.report.classes.append(Cls(qualname=qual, start=node.lineno,
+                                        end=getattr(node, "end_lineno", node.lineno),
+                                        docstring=bool(ast.get_docstring(node)),
+                                        n_methods=methods))
+        self._record_decorators(node.decorator_list)
+        for base in node.bases:
+            self._record_expr_refs(base)
+        for kw in node.keywords:
+            if kw.arg == "metaclass":
+                self._record_expr_refs(kw.value)
+        if not self.prefix:
+            self.report.module_defs.append((node.name, node.lineno, "class"))
+        saved, self.prefix = self.prefix, self.prefix + (node.name,)
+        for stmt in node.body:
+            self.visit(stmt)
+        self.prefix = saved
+
+    def visit_Import(self, node):
+        for alias in node.names:
+            bound = alias.asname or alias.name.split(".")[0]
+            self.report.imports.append((bound, node.lineno))
+            if alias.asname and alias.asname == alias.name.split(".")[0]:
+                # `import x as x` is an explicit re-export marker (Ruff F401 rule).
+                self.report.reference_names[bound] += 1
+
+    def visit_ImportFrom(self, node):
+        for alias in node.names:
+            if alias.name == "*":
+                continue
+            self.report.imports.append((alias.asname or alias.name, node.lineno))
+            if alias.asname == alias.name:
+                # `from x import y as y` is an explicit re-export marker.
+                self.report.reference_names[alias.name] += 1
+
+    def visit_Name(self, node):
+        if isinstance(node.ctx, ast.Load):
+            self.report.reference_names[node.id] += 1
+        ast.NodeVisitor.generic_visit(self, node)
+
+
+def _annotation_names(fn_node):
+    """Name ids appearing in parameter/return annotations (uses are references)."""
+    args = fn_node.args
+    for group in (args.posonlyargs, args.args, args.kwonlyargs):
+        for arg in group:
+            yield from _expr_name_ids(arg.annotation)
+    if args.vararg and args.vararg.annotation:
+        yield from _expr_name_ids(args.vararg.annotation)
+    if args.kwarg and args.kwarg.annotation:
+        yield from _expr_name_ids(args.kwarg.annotation)
+    if fn_node.returns:
+        yield from _expr_name_ids(fn_node.returns)
+
+
+def _expr_name_ids(expr):
+    """All Name ids inside an arbitrary expression subtree (Load context)."""
+    if expr is None:
+        return
+    for sub in ast.walk(expr):
+        if isinstance(sub, ast.Name):
+            yield sub.id
+
+
+def _decorator_names(decorator_list):
+    """Name ids referenced by decorators: @deco, @pkg.deco, @deco(...)."""
+    for deco in decorator_list:
+        target = deco.func if isinstance(deco, ast.Call) else deco
+        while isinstance(target, ast.Attribute):
+            target = target.value
+        if isinstance(target, ast.Name):
+            yield target.id
+
+
+def _is_main_guard(stmt):
+    """True for the `if __name__ == "__main__":` idiom."""
+    if not isinstance(stmt, ast.If) or not isinstance(stmt.test, ast.Compare):
+        return False
+    left = stmt.test.left
+    return isinstance(left, ast.Name) and left.id == "__name__"
+
+
+def _count_statements(tree):
+    """LLOC: count of ast.stmt nodes, excluding def/class signature statements.
+
+    The definition line itself is not executable logic, but the bodies of
+    functions and classes are counted (ADR-002 metric definition).
+    """
+    defs = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+    return sum(1 for node in ast.walk(tree)
+               if isinstance(node, ast.stmt) and not isinstance(node, defs))
+
+
+def _iter_scope(fn):
+    """Yield nodes belonging to fn's own scope, skipping nested def bodies."""
+    stack = list(fn.body)
+    while stack:
+        node = stack.pop()
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            yield node  # its name binds here, but its body is another scope
+            continue
+        yield node
+        stack.extend(ast.iter_child_nodes(node))
+
+
+def _find_shadowed(tree, report):
+    """Local names that silently mask a module import (real defect class, error)."""
+    imported = {name for name, _ in report.imports}
+    if not imported:
+        return
+    records = {fn.start: fn for fn in report.fns}
+
+    def local_names(fn):
+        names = set()
+        for node in _iter_scope(fn):
+            if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+                names.add(node.id)
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                names.add(node.name)
+                names.update(_all_args(node.args))
+            elif isinstance(node, ast.Lambda):
+                names.update(_all_args(node.args))
+            elif isinstance(node, ast.comprehension) and isinstance(node.target, ast.Name):
+                names.add(node.target.id)
+        return names
+
+    for fn in _iter_fndefs(tree):
+        hits = sorted(local_names(fn) & imported)
+        for name in hits:
+            entry = (fn.lineno, name, name)
+            report.shadowed.append(entry)
+            record = records.get(fn.lineno)
+            if record is not None:
+                record.shadowed.append(entry)
+
+
+def _all_args(args):
+    out = []
+    for group in ("posonlyargs", "args", "kwonlyargs"):
+        out.extend(a.arg for a in getattr(args, group, []))
+    return out
+
+
+def _iter_fndefs(tree):
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            yield node
+
+
+def parse_file(path):
+    """Parse one .py file and return its FileReport, or None on syntax error."""
+    lines = files.read_lines(path)
+    try:
+        tree = ast.parse("\n".join(lines), filename=str(path))
+    except SyntaxError:
+        return None
+    walker = _FileWalker(str(path), lines)
+    walker.visit(tree)
+    _find_shadowed(tree, walker.report)
+    return walker.report
+
+
+@dataclasses.dataclass
+class Project:
+    """Aggregated view over all analyzed files."""
+
+    reports: list
+    name_refs: Counter = dataclasses.field(default_factory=Counter)
+    loc: int = 0
+    lloc: int = 0
+
+    def build(self):
+        """Second pass: cross-file reference counts and totals."""
+        for report in self.reports:
+            self.name_refs.update(report.reference_names)
+            self.loc += sum(1 for ln in report.lines if ln.strip())
+            self.lloc += report.lloc
+        return self
+
+
+def analyze(paths, exclude_patterns):
+    """Discover, parse and aggregate every file under paths. Returns Project."""
+    file_paths = list(files.discover(paths, exclude_patterns))
+    with concurrent.futures.ProcessPoolExecutor() as pool:
+        reports = [r for r in pool.map(parse_file, file_paths) if r is not None]
+    return Project(reports=reports).build()

pcina/budget.py

@@ -0,0 +1,66 @@
+"""Budget gate checks: `pcina check` fails only on these, never on the score (ADR-001)."""
+
+from pcina.config import DEFAULT_BUDGETS
+from pcina.finding import BudgetViolation
+
+# Scaling for the project-wide raise-rate budget: raises per 100 LLOC.
+PER_100 = 100
+
+
+def _limit(budgets, key):
+    """Budget value with a fallback to the documented default."""
+    return budgets.get(key, DEFAULT_BUDGETS[key])
+
+
+def _fn_violations(report, fn, budgets):
+    """Per-function budget breaches, each anchored at the offending fn."""
+    out = []
+    max_cc = _limit(budgets, "max_cc")
+    if fn.cc > max_cc:
+        out.append(BudgetViolation("max_cc", f"cc={fn.cc} (limit {max_cc})",
+                                   report.path, fn.start))
+    max_nesting = _limit(budgets, "max_nesting")
+    if fn.max_nesting > max_nesting:
+        out.append(BudgetViolation("max_nesting",
+                                   f"nesting={fn.max_nesting} (limit {max_nesting})",
+                                   report.path, fn.start))
+    max_fn_loc = _limit(budgets, "max_fn_loc")
+    span = fn.end - fn.start
+    if span > max_fn_loc:
+        out.append(BudgetViolation("max_fn_loc",
+                                   f"span={span} lines (limit {max_fn_loc})",
+                                   report.path, fn.start))
+    max_params = _limit(budgets, "max_params")
+    if fn.params > max_params:
+        out.append(BudgetViolation("max_params",
+                                   f"params={fn.params} (limit {max_params})",
+                                   report.path, fn.start))
+    return out
+
+
+def _project_violations(project, budgets):
+    """Project-wide gates: raise density and the bare-except policy."""
+    out = []
+    raises = sum(len(fn.raises) for report in project.reports for fn in report.fns)
+    max_raises = _limit(budgets, "max_raises_per_100")
+    rate = raises * PER_100 / max(project.lloc, 1)
+    if rate > max_raises:
+        out.append(BudgetViolation(
+            "max_raises_per_100",
+            f"{rate:.1f} raises per 100 LLOC (limit {max_raises})"))
+    if _limit(budgets, "bare_except") == "error":
+        bare = sum(len(fn.broad_excepts)
+                   for report in project.reports for fn in report.fns)
+        if bare:
+            out.append(BudgetViolation("bare_except", f"{bare} broad/bare except(s)"))
+    return out
+
+
+def violations(project, findings, budgets):
+    """All budget violations for the project against the given budgets dict."""
+    out = []
+    for report in project.reports:
+        for fn in report.fns:
+            out.extend(_fn_violations(report, fn, budgets))
+    out.extend(_project_violations(project, budgets))
+    return out