synergyspec-selfevolving 1.1.10 → 1.1.12

package/scripts/code-health.py

@@ -0,0 +1,1154 @@
+#!/usr/bin/env python3
+"""Self-contained local code-health analyzer for multi-language source trees.
+
+This is the fallback MetricSource for the self-evolution fitness loop: it
+needs no SonarQube server, no network, and no third-party packages -- only the
+Python 3 standard library (``ast`` + ``tokenize`` for Python, plus a
+dependency-free brace/keyword heuristic for the C-family and Rust).
+
+Usage::
+
+    python code-health.py <dir>
+
+It recursively analyzes every source file under ``<dir>`` -- Python (``.py``)
+via ``ast``, and C (``.c``/``.h``), C++ (``.cc``/``.cpp``/``.cxx``/``.c++``/
+``.hpp``/``.hh``/``.hxx``/``.h++``) and Rust (``.rs``) via a heuristic -- and
+prints a single JSON object to stdout with EXACTLY these keys::
+
+    cyclomatic_p95
+    max_nesting_depth
+    cognitive_complexity
+    duplicated_lines_density
+    import_count
+    attr_method_usage_ratio
+    bare_except_count
+
+The metrics are aggregated across ALL analyzed files of ALL languages
+combined, with the same aggregation rules used for the Python-only path
+(p95 over the combined cyclomatic list, mean over the combined cognitive
+list, max depth across files, summed counts, dup density over the combined
+corpus, mean cohesion ratio over all class/impl methods).
+
+The precise backend for the heuristic languages is SonarQube; this local
+source is a deliberate good-enough proxy -- no real C/C++/Rust parser exists
+in the standard library, so a brace/keyword heuristic is expected.
+
+Robustness contract: files that fail to parse are skipped (their text may
+still feed duplication density if readable); the program always emits valid
+JSON (zeros / neutral values when the tree is empty), and never raises out to
+the shell on bad input.
+"""
+
+from __future__ import annotations
+
+import ast
+import io
+import json
+import math
+import os
+import re
+import sys
+import tokenize
+from typing import Iterable, List, Tuple
+
+
+# --------------------------------------------------------------------------- #
+# Per-function cyclomatic complexity (McCabe)                                 #
+# --------------------------------------------------------------------------- #
+
+# Boolean operators (and / or) add a decision point per *extra* operand: a
+# chain `a and b and c` has 2 ``and`` edges, i.e. (len(values) - 1).
+_BOOLOP_NODE = ast.BoolOp
+
+
+def _is_function(node: ast.AST) -> bool:
+    return isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+
+
+def _cyclomatic_complexity(func: ast.AST) -> int:
+    """1 + number of decision points inside ``func`` (not descending into
+    nested function/class bodies, which are counted as their own units)."""
+    complexity = 1
+    stack: List[ast.AST] = list(ast.iter_child_nodes(func))
+    while stack:
+        node = stack.pop()
+        # Do not descend into nested defs/classes: each function is its own
+        # complexity unit, mirroring per-function McCabe.
+        if _is_function(node) or isinstance(node, ast.ClassDef):
+            continue
+
+        if isinstance(node, (ast.If, ast.For, ast.AsyncFor, ast.While, ast.ExceptHandler)):
+            complexity += 1
+        elif isinstance(node, _BOOLOP_NODE):
+            # +1 per logical edge: N operands => N-1 edges (And/Or).
+            complexity += max(0, len(node.values) - 1)
+        elif isinstance(node, ast.IfExp):  # ternary  a if cond else b
+            complexity += 1
+        elif isinstance(node, ast.comprehension):
+            # each `if` clause in a comprehension is a branch
+            complexity += len(node.ifs)
+
+        stack.extend(ast.iter_child_nodes(node))
+    return complexity
+
+
+def _percentile(values: List[float], pct: float) -> float:
+    """Linear-interpolation percentile (same method as numpy's default).
+
+    ``pct`` in [0, 100]. Returns 0.0 for an empty input.
+    """
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    if len(ordered) == 1:
+        return float(ordered[0])
+    rank = (pct / 100.0) * (len(ordered) - 1)
+    low = math.floor(rank)
+    high = math.ceil(rank)
+    if low == high:
+        return float(ordered[int(rank)])
+    frac = rank - low
+    return float(ordered[low] * (1 - frac) + ordered[high] * frac)
+
+
+# --------------------------------------------------------------------------- #
+# Max nesting depth of control structures                                     #
+# --------------------------------------------------------------------------- #
+
+_NESTING_NODES = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.With,
+    ast.AsyncWith,
+    ast.Try,
+    ast.FunctionDef,
+    ast.AsyncFunctionDef,
+)
+
+
+def _max_nesting_depth(tree: ast.AST) -> int:
+    """Deepest nesting of control structures in a module tree."""
+
+    def walk(node: ast.AST, depth: int) -> int:
+        deepest = depth
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, _NESTING_NODES):
+                deepest = max(deepest, walk(child, depth + 1))
+            else:
+                deepest = max(deepest, walk(child, depth))
+        return deepest
+
+    return walk(tree, 0)
+
+
+# --------------------------------------------------------------------------- #
+# Cognitive complexity (Sonar-style approximation)                            #
+# --------------------------------------------------------------------------- #
+
+# Structures that both (a) increment by 1 and (b) raise the nesting level for
+# anything nested beneath them, adding the current nesting level on top of the
+# base increment.
+_COGNITIVE_NESTING_NODES = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.ExceptHandler,
+)
+
+
+def _cognitive_complexity(func: ast.AST) -> int:
+    """Sonar-style cognitive complexity for a single function.
+
+    Rules approximated:
+      * +1 (plus current nesting level) for each control-flow structure that
+        breaks linear flow: if / for / while / except.
+      * nesting increases for code inside those structures.
+      * boolean operators add +1 per sequence of like operators (a flat penalty
+        for mixing logic), independent of nesting.
+      * else/elif and ternary add a flat +1 (no nesting bonus), matching
+        Sonar's "else does not add nesting" treatment closely enough for a
+        proxy.
+    """
+    score = 0
+
+    def walk(node: ast.AST, nesting: int) -> None:
+        nonlocal score
+        for child in ast.iter_child_nodes(node):
+            # Each nested function is its own unit; don't recurse into it here.
+            if _is_function(child) or isinstance(child, ast.ClassDef):
+                continue
+
+            if isinstance(child, _COGNITIVE_NESTING_NODES):
+                score += 1 + nesting
+                walk(child, nesting + 1)
+                # `orelse` of an If is the elif/else chain: flat +1 each, no
+                # extra nesting bonus, but its body still nests one level.
+                if isinstance(child, ast.If) and child.orelse:
+                    score += 1
+            elif isinstance(child, _BOOLOP_NODE):
+                score += 1
+                walk(child, nesting)
+            elif isinstance(child, ast.IfExp):  # ternary
+                score += 1
+                walk(child, nesting)
+            else:
+                walk(child, nesting)
+
+    walk(func, 0)
+    return score
+
+
+# --------------------------------------------------------------------------- #
+# Bare / overly-broad except handlers                                          #
+# --------------------------------------------------------------------------- #
+
+_BROAD_EXC_NAMES = {"Exception", "BaseException"}
+
+
+def _is_broad_handler(handler: ast.ExceptHandler) -> bool:
+    """True for ``except:`` and ``except (Exception|BaseException):``."""
+    if handler.type is None:
+        return True  # bare except:
+    names: Iterable[ast.AST]
+    if isinstance(handler.type, ast.Tuple):
+        names = handler.type.elts
+    else:
+        names = [handler.type]
+    for n in names:
+        if isinstance(n, ast.Name) and n.id in _BROAD_EXC_NAMES:
+            return True
+        # Handle attribute forms defensively (e.g. builtins.Exception).
+        if isinstance(n, ast.Attribute) and n.attr in _BROAD_EXC_NAMES:
+            return True
+    return False
+
+
+# --------------------------------------------------------------------------- #
+# Per-class attr / method usage ratio                                         #
+# --------------------------------------------------------------------------- #
+
+
+def _self_attr_names(method: ast.AST) -> "tuple[set, set]":
+    """Return (assigned_attrs, referenced_attrs) of ``self.<attr>`` inside a
+    single method body (does not descend into nested functions/classes)."""
+    assigned: set = set()
+    referenced: set = set()
+
+    def is_self_attr(node: ast.AST):
+        if (
+            isinstance(node, ast.Attribute)
+            and isinstance(node.value, ast.Name)
+            and node.value.id == "self"
+        ):
+            return node.attr
+        return None
+
+    def walk(node: ast.AST) -> None:
+        for child in ast.iter_child_nodes(node):
+            if _is_function(child) or isinstance(child, ast.ClassDef):
+                continue
+            attr = is_self_attr(child)
+            if attr is not None:
+                # Determine assignment vs reference by context.
+                referenced.add(attr)
+            walk(child)
+
+    # Assignments: scan all assignment targets explicitly.
+    def walk_assign(node: ast.AST) -> None:
+        for child in ast.iter_child_nodes(node):
+            if _is_function(child) or isinstance(child, ast.ClassDef):
+                continue
+            if isinstance(child, ast.Assign):
+                for tgt in child.targets:
+                    a = is_self_attr(tgt)
+                    if a is not None:
+                        assigned.add(a)
+            elif isinstance(child, (ast.AnnAssign, ast.AugAssign)):
+                a = is_self_attr(child.target)
+                if a is not None:
+                    assigned.add(a)
+            walk_assign(child)
+
+    walk(method)
+    walk_assign(method)
+    return assigned, referenced
+
+
+def _attr_method_usage_ratio(classes: List[ast.ClassDef]) -> float:
+    """Mean over all (class, method) pairs of the fraction of the class's full
+    ``self.<attr>`` set that the method references.
+
+    Returns 1.0 when there are no classes / methods / attributes (a neutral
+    "no signal" value, matching the spec's "1.0 (or omit) when no classes").
+    """
+    ratios: List[float] = []
+    for cls in classes:
+        methods = [m for m in cls.body if _is_function(m)]
+        if not methods:
+            continue
+        # Class-wide attribute universe = union of every method's assigned +
+        # referenced self.<attr>.
+        class_attrs: set = set()
+        per_method_refs = []
+        for m in methods:
+            assigned, referenced = _self_attr_names(m)
+            class_attrs |= assigned | referenced
+            per_method_refs.append(referenced | assigned)
+        if not class_attrs:
+            continue
+        denom = len(class_attrs)
+        for refs in per_method_refs:
+            used = len(refs & class_attrs)
+            ratios.append(used / denom)
+
+    if not ratios:
+        return 1.0
+    return sum(ratios) / len(ratios)
+
+
+# --------------------------------------------------------------------------- #
+# Duplicated lines density                                                     #
+# --------------------------------------------------------------------------- #
+
+_DUP_WINDOW = 4  # >= 4 consecutive identical stripped lines
+
+
+def _non_trivial_lines(source: str) -> List[str]:
+    """Stripped lines worth considering for duplication: drop blank lines and
+    pure-comment lines (they inflate duplication noise)."""
+    out: List[str] = []
+    for raw in source.splitlines():
+        s = raw.strip()
+        if not s:
+            continue
+        if s.startswith("#"):
+            continue
+        out.append(s)
+    return out
+
+
+def _duplicated_lines_density(all_files_lines: List[List[str]]) -> float:
+    """Fraction of non-trivial lines that fall inside a duplicated block.
+
+    A block of >= ``_DUP_WINDOW`` consecutive identical stripped lines that
+    appears (as a window hash) more than once anywhere in the corpus marks all
+    of its member lines as duplicated. Result clamped to [0, 1].
+    """
+    # Flatten the corpus, remembering file boundaries so windows never straddle
+    # two files.
+    windows = {}  # hash -> count
+    indexed: List["tuple[int, int]"] = []  # (file_idx, line_idx) per global line
+    file_line_lists = all_files_lines
+
+    total_lines = sum(len(f) for f in file_line_lists)
+    if total_lines == 0:
+        return 0.0
+
+    # First pass: count window occurrences per file.
+    for fi, lines in enumerate(file_line_lists):
+        for li in range(len(lines) - _DUP_WINDOW + 1):
+            window = tuple(lines[li : li + _DUP_WINDOW])
+            h = hash(window)
+            windows[h] = windows.get(h, 0) + 1
+
+    # Second pass: any line covered by a window whose hash count > 1 is dup.
+    duplicated = set()  # (file_idx, line_idx)
+    for fi, lines in enumerate(file_line_lists):
+        for li in range(len(lines) - _DUP_WINDOW + 1):
+            window = tuple(lines[li : li + _DUP_WINDOW])
+            if windows.get(hash(window), 0) > 1:
+                for k in range(li, li + _DUP_WINDOW):
+                    duplicated.add((fi, k))
+
+    density = len(duplicated) / total_lines
+    if density < 0:
+        return 0.0
+    if density > 1:
+        return 1.0
+    return density
+
+
+# --------------------------------------------------------------------------- #
+# Heuristic analyzer for C-family + Rust (brace/keyword proxy)                #
+# --------------------------------------------------------------------------- #
+#
+# No real parser for C/C++/Rust exists in the standard library, so these
+# languages are handled with a brace-depth + keyword heuristic. The precise
+# backend is SonarQube; this is a deliberate good-enough proxy. Everything
+# below runs on a *stripped* copy of the source (comments and string/char
+# literals replaced with spaces) so keywords inside them are never counted.
+
+# Language tags for the heuristic dispatch.
+_LANG_C = "c"
+_LANG_CPP = "cpp"
+_LANG_RUST = "rust"
+
+# Extension -> language. Python is dispatched separately.
+_C_EXTS = {".c", ".h"}
+_CPP_EXTS = {".cc", ".cpp", ".cxx", ".c++", ".hpp", ".hh", ".hxx", ".h++"}
+_RUST_EXTS = {".rs"}
+
+
+def _strip_c_family(source: str) -> str:
+    """Remove ``//`` line comments, ``/* ... */`` block comments (multi-line),
+    double-quoted strings, and char literals from C/C++/Rust source, replacing
+    each removed span with spaces while preserving newlines.
+
+    Also makes a best-effort attempt at Rust raw strings (``r"..."`` and
+    ``r#"..."#`` with any number of ``#``). Preserving line breaks keeps both
+    line-based metrics (dup density) and brace-depth metrics aligned with the
+    original source.
+    """
+    out: List[str] = []
+    i = 0
+    n = len(source)
+
+    def emit_blanking(span: str) -> None:
+        # Replace every non-newline char with a space; keep newlines.
+        out.append("".join("\n" if ch == "\n" else " " for ch in span))
+
+    while i < n:
+        ch = source[i]
+        nxt = source[i + 1] if i + 1 < n else ""
+
+        # Line comment //...
+        if ch == "/" and nxt == "/":
+            j = source.find("\n", i)
+            if j == -1:
+                j = n
+            emit_blanking(source[i:j])
+            i = j
+            continue
+
+        # Block comment /* ... */ (multi-line)
+        if ch == "/" and nxt == "*":
+            j = source.find("*/", i + 2)
+            if j == -1:
+                j = n
+            else:
+                j += 2
+            emit_blanking(source[i:j])
+            i = j
+            continue
+
+        # Rust raw string: r"..."  or  r#"..."#  (with k>=1 hashes), and the
+        # br"..." byte-string variant. Only treat as raw string when 'r' is at
+        # a token boundary (not part of a longer identifier).
+        if (ch in ("r", "R")) and not (i > 0 and (source[i - 1].isalnum() or source[i - 1] == "_")):
+            k = i + 1
+            hashes = 0
+            while k < n and source[k] == "#":
+                hashes += 1
+                k += 1
+            if k < n and source[k] == '"':
+                # Opening quote at k; closing delimiter is `"` + hashes*`#`.
+                closer = '"' + ("#" * hashes)
+                end = source.find(closer, k + 1)
+                if end == -1:
+                    end = n
+                else:
+                    end += len(closer)
+                emit_blanking(source[i:end])
+                i = end
+                continue
+        # Rust byte raw string br"..." / br#"..."#
+        if ch == "b" and i + 1 < n and source[i + 1] in ("r", "R") and not (
+            i > 0 and (source[i - 1].isalnum() or source[i - 1] == "_")
+        ):
+            k = i + 2
+            hashes = 0
+            while k < n and source[k] == "#":
+                hashes += 1
+                k += 1
+            if k < n and source[k] == '"':
+                closer = '"' + ("#" * hashes)
+                end = source.find(closer, k + 1)
+                if end == -1:
+                    end = n
+                else:
+                    end += len(closer)
+                emit_blanking(source[i:end])
+                i = end
+                continue
+
+        # Double-quoted string "..." with backslash escapes.
+        if ch == '"':
+            j = i + 1
+            while j < n:
+                if source[j] == "\\":
+                    j += 2
+                    continue
+                if source[j] == '"':
+                    j += 1
+                    break
+                j += 1
+            emit_blanking(source[i:j])
+            i = j
+            continue
+
+        # Char literal 'x' / '\n' / '\\'. Rust lifetimes (e.g. &'a) also start
+        # with a quote but are not terminated by a quote; guard by only
+        # consuming when a closing quote is found within a short window.
+        if ch == "'":
+            j = i + 1
+            consumed = -1
+            if j < n and source[j] == "\\":
+                # Escaped char: '\n', '\xFF', '\u{1F600}' ... scan to quote.
+                k = j + 1
+                while k < n and source[k] != "'" and source[k] != "\n":
+                    k += 1
+                if k < n and source[k] == "'":
+                    consumed = k + 1
+            else:
+                # Single char then a quote: 'a'
+                if j + 1 < n and source[j + 1] == "'":
+                    consumed = j + 2
+            if consumed != -1:
+                emit_blanking(source[i:consumed])
+                i = consumed
+                continue
+            # Otherwise: a Rust lifetime / label -> leave the quote as-is.
+            out.append(ch)
+            i += 1
+            continue
+
+        out.append(ch)
+        i += 1
+
+    return "".join(out)
+
+
+# Identifier-boundary keyword matchers (operate on stripped text).
+_RE_IF = re.compile(r"\bif\b")
+_RE_FOR = re.compile(r"\bfor\b")
+_RE_WHILE = re.compile(r"\bwhile\b")
+_RE_CASE = re.compile(r"\bcase\b")
+_RE_CATCH = re.compile(r"\bcatch\b")
+_RE_SWITCH = re.compile(r"\bswitch\b")
+_RE_ELSE = re.compile(r"\belse\b")
+_RE_AND = re.compile(r"&&")
+_RE_OR = re.compile(r"\|\|")
+_RE_TERNARY_Q = re.compile(r"\?")
+_RE_MATCH = re.compile(r"\bmatch\b")
+_RE_LOOP = re.compile(r"\bloop\b")
+_RE_IF_LET = re.compile(r"\bif\s+let\b")
+_RE_WHILE_LET = re.compile(r"\bwhile\s+let\b")
+_RE_FAT_ARROW = re.compile(r"=>")
+
+# Function-header detection. Operate on the stripped text.
+# Rust: `fn name(...)` (possibly `pub`, `async`, `const`, `unsafe`, generics).
+_RE_RUST_FN = re.compile(r"\bfn\s+[A-Za-z_]\w*\s*(?:<[^{};]*?>)?\s*\(")
+# C-family: an identifier (the function name) immediately followed by `(`.
+# We additionally require the matched `(` to begin a parameter list that, when
+# the matching brace block opens, denotes a function. We locate candidate
+# headers as `<ident>(` not preceded by a keyword that would make it a call or
+# control structure.
+_RE_C_HEADER_IDENT = re.compile(r"(?<![\w])([A-Za-z_]\w*)\s*\(")
+
+# Keywords that, when they are the identifier before `(`, mean it is NOT a
+# function definition (control flow / common macros / operators).
+_C_NON_FUNC_IDENTS = {
+    "if", "for", "while", "switch", "catch", "return", "sizeof", "do",
+    "case", "else", "defined", "static_assert", "assert", "decltype",
+    "alignof", "alignas", "noexcept", "throw", "new", "delete", "and", "or",
+    "not", "typeid", "static_cast", "dynamic_cast", "reinterpret_cast",
+    "const_cast",
+}
+
+
+def _ternary_count(text: str) -> int:
+    """Count ``?`` ternary operators, excluding Rust's ``?`` error-propagation
+    postfix and ``?`` inside obvious non-ternary spots. Heuristic: count `?`
+    that is NOT immediately followed by `;`, `)`, `,`, `.`, whitespace+`;`, or
+    end -- i.e. looks like the middle of ``cond ? a : b``. This is approximate;
+    monotonic sanity is what matters."""
+    count = 0
+    for m in _RE_TERNARY_Q.finditer(text):
+        j = m.end()
+        # skip following whitespace
+        k = j
+        while k < len(text) and text[k] in " \t":
+            k += 1
+        nxt = text[k] if k < len(text) else ""
+        # Rust postfix `?` is typically followed by ; ) . , } or whitespace+those
+        if nxt in (";", ")", ",", ".", "}", "?", ""):
+            continue
+        count += 1
+    return count
+
+
+def _find_blocks(stripped: str) -> List[Tuple[int, int, int]]:
+    """Return a list of ``(open_index, close_index, header_start)`` for every
+    top-level-or-nested brace block, where ``header_start`` is the index just
+    after the previous block boundary / statement terminator (used to inspect
+    the block's header text). ``open_index`` is the position of ``{`` and
+    ``close_index`` is the position of the matching ``}`` (exclusive of the
+    brace itself is not implied -- close_index points AT the ``}``)."""
+    blocks: List[Tuple[int, int, int]] = []
+    stack: List[Tuple[int, int]] = []  # (open_index, header_start)
+    # header_start tracking: position after the most recent ; { } at the same
+    # textual scan, so we can recover the header preceding a `{`.
+    last_boundary = 0
+    n = len(stripped)
+    for i, ch in enumerate(stripped):
+        if ch == "{":
+            stack.append((i, last_boundary))
+            last_boundary = i + 1
+        elif ch == "}":
+            if stack:
+                open_i, hdr = stack.pop()
+                blocks.append((open_i, i, hdr))
+            last_boundary = i + 1
+        elif ch == ";":
+            last_boundary = i + 1
+    return blocks
+
+
+def _is_rust_fn_header(header: str) -> bool:
+    return _RE_RUST_FN.search(header) is not None
+
+
+def _is_c_fn_header(header: str) -> bool:
+    """True if ``header`` (text between the previous boundary and this ``{``)
+    looks like a C-family function signature: contains ``<ident>(`` where the
+    ident is not a control keyword, and a closing ``)`` appears before the
+    block. Excludes struct/enum/namespace/class/union bodies (no call paren)
+    and control structures.
+    """
+    # Reject obvious aggregate / namespace headers.
+    # (These can still contain `(` in rare cases, but the keyword presence is a
+    # strong signal it is not a free/member function definition.)
+    if re.search(r"\b(struct|enum|union|namespace|class)\b", header):
+        # A class with a base-clause has no `(`; method defs inside the class
+        # are separate blocks, so excluding the class block itself is correct.
+        return False
+    last = None
+    for m in _RE_C_HEADER_IDENT.finditer(header):
+        ident = m.group(1)
+        if ident in _C_NON_FUNC_IDENTS:
+            last = None
+            continue
+        last = m
+    if last is None:
+        return False
+    # Require a closing paren somewhere after the ident's `(`.
+    return ")" in header[last.end() - 1:]
+
+
+def _depth_at(stripped: str, idx: int) -> int:
+    """Brace depth at character index ``idx`` (number of unmatched ``{`` before
+    it)."""
+    depth = 0
+    for ch in stripped[:idx]:
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+    return depth
+
+
+def _analyze_heuristic(stripped: str, lang: str) -> dict:
+    """Analyze one stripped C/C++/Rust file. Returns a dict with:
+
+        cyclomatic   : list[int]  (per detected function)
+        cognitive    : list[int]  (per detected function)
+        max_depth    : int        (deepest brace nesting inside fn bodies)
+        import_count : int
+        bare_except  : int        (broad/abrupt error-handling analogue)
+        cohesion     : list[float] (per (class/impl, method) ratio)
+    """
+    blocks = _find_blocks(stripped)
+
+    # Identify function blocks (header looks like a signature).
+    fn_blocks: List[Tuple[int, int]] = []  # (open_index, close_index)
+    for open_i, close_i, hdr_start in blocks:
+        header = stripped[hdr_start:open_i]
+        if lang == _LANG_RUST:
+            if _is_rust_fn_header(header):
+                fn_blocks.append((open_i, close_i))
+        else:  # C / C++
+            if _is_c_fn_header(header):
+                fn_blocks.append((open_i, close_i))
+
+    cyclomatic: List[int] = []
+    cognitive: List[int] = []
+    max_depth = 0
+
+    for open_i, close_i in fn_blocks:
+        body = stripped[open_i + 1:close_i]
+        cyclomatic.append(_heuristic_cyclomatic(body, lang))
+        cognitive.append(_heuristic_cognitive(body, lang))
+        d = _max_brace_depth(body)
+        if d > max_depth:
+            max_depth = d
+
+    import_count = _heuristic_imports(stripped, lang)
+    bare_except = _heuristic_broad_handling(stripped, lang)
+    cohesion = _heuristic_cohesion(stripped, blocks, lang)
+
+    return {
+        "cyclomatic": cyclomatic,
+        "cognitive": cognitive,
+        "max_depth": max_depth,
+        "import_count": import_count,
+        "bare_except": bare_except,
+        "cohesion": cohesion,
+    }
+
+
+def _max_brace_depth(body: str) -> int:
+    """Deepest brace nesting reached inside ``body`` (control structures in
+    these languages are brace-delimited). The function body itself is depth 1
+    relative to the function header; we report depth counting the outermost
+    brace as 1."""
+    depth = 0
+    deepest = 0
+    for ch in body:
+        if ch == "{":
+            depth += 1
+            if depth > deepest:
+                deepest = depth
+        elif ch == "}":
+            if depth > 0:
+                depth -= 1
+    # The body text excludes the function's own outer braces, so a top-level
+    # statement (no nested block) yields deepest == 0. Add 1 so a flat function
+    # counts as depth 1 (its own body) and one nested control block counts as 2,
+    # matching the "deepest brace nesting reached inside function bodies"
+    # framing where the function body is the first level.
+    return deepest + 1
+
+
+def _heuristic_cyclomatic(body: str, lang: str) -> int:
+    """1 + decision points in a function body (stripped text)."""
+    c = 1
+    c += len(_RE_IF.findall(body))
+    c += len(_RE_FOR.findall(body))
+    c += len(_RE_WHILE.findall(body))
+    c += len(_RE_CASE.findall(body))
+    c += len(_RE_CATCH.findall(body))
+    c += len(_RE_AND.findall(body))
+    c += len(_RE_OR.findall(body))
+    c += _ternary_count(body)
+    if lang == _LANG_RUST:
+        # match arms: count `=>` occurrences inside match blocks (approximate
+        # by counting all `=>`, which in stripped Rust appear in match arms and
+        # closures; closures are uncommon enough to keep this a fair proxy).
+        c += len(_RE_FAT_ARROW.findall(body))
+        c += len(_RE_LOOP.findall(body))
+        # if let / while let are already counted via the bare if/while above;
+        # no extra increment to avoid double-counting.
+    return c
+
+
+def _heuristic_cognitive(body: str, lang: str) -> int:
+    """Sonar-style nesting-weighted cognitive complexity, approximated by brace
+    depth. For each control structure add ``1 + nestingLevel``; add a flat +1
+    per ``&&``/``||`` and per ternary ``?``; add a flat +1 per ``else``.
+
+    Nesting level is the brace depth (relative to the function body) at the
+    position of the control keyword.
+    """
+    score = 0
+
+    # Control structures that take a nesting bonus.
+    control_res = [_RE_IF, _RE_FOR, _RE_WHILE, _RE_SWITCH, _RE_CATCH]
+    if lang == _LANG_RUST:
+        control_res = [_RE_IF, _RE_FOR, _RE_WHILE, _RE_MATCH, _RE_LOOP]
+
+    for rex in control_res:
+        for m in rex.finditer(body):
+            nesting = _depth_at(body, m.start())
+            score += 1 + nesting
+
+    # Flat penalties (no nesting bonus).
+    score += len(_RE_AND.findall(body))
+    score += len(_RE_OR.findall(body))
+    score += _ternary_count(body)
+    score += len(_RE_ELSE.findall(body))
+
+    return score
+
+
+def _heuristic_imports(stripped: str, lang: str) -> int:
+    if lang == _LANG_RUST:
+        # `use ...;` items + `extern crate ...;`
+        uses = len(re.findall(r"\buse\b[^;{}]*;", stripped))
+        crates = len(re.findall(r"\bextern\s+crate\b[^;{}]*;", stripped))
+        return uses + crates
+    # C / C++: `#include` directives.
+    return len(re.findall(r"(?m)^[ \t]*#[ \t]*include\b", stripped))
+
+
+def _heuristic_broad_handling(stripped: str, lang: str) -> int:
+    """bare_except analogue (abrupt / broad error handling, lower is better)."""
+    if lang == _LANG_RUST:
+        # .unwrap( , .expect( , panic!(
+        n = 0
+        n += len(re.findall(r"\.unwrap\s*\(", stripped))
+        n += len(re.findall(r"\.expect\s*\(", stripped))
+        n += len(re.findall(r"\bpanic!\s*\(", stripped))
+        return n
+    if lang == _LANG_CPP:
+        # catch (...) / catch(...) catch-all handlers.
+        return len(re.findall(r"\bcatch\s*\(\s*\.\.\.\s*\)", stripped))
+    # C: 0
+    return 0
+
+
+def _heuristic_cohesion(
+    stripped: str, blocks: List[Tuple[int, int, int]], lang: str
+) -> List[float]:
+    """Per (class/impl, method) cohesion ratios.
+
+    Rust: for each ``impl [Trait for] Type { ... }`` block, methods are ``fn``
+    items taking ``self``/``&self``/``&mut self``; attribute universe is the
+    union of ``self.<field>`` accesses across the impl's methods. Ratio for a
+    method = |fields it references| / |universe|. Skip impls with no self fields.
+
+    C++: for each ``class``/``struct`` body containing methods, approximate the
+    member universe via ``this-><member>`` accesses across methods; ratio = mean
+    over methods. Skip when no ``this->`` usage.
+
+    C: nothing.
+    """
+    if lang == _LANG_C:
+        return []
+    ratios: List[float] = []
+
+    # Sort blocks by open index so we can find children of a container block.
+    blocks_sorted = sorted(blocks, key=lambda b: b[0])
+
+    if lang == _LANG_RUST:
+        for open_i, close_i, hdr_start in blocks_sorted:
+            header = stripped[hdr_start:open_i]
+            if not re.search(r"\bimpl\b", header):
+                continue
+            # Find method (fn) blocks directly inside this impl.
+            method_bodies = _direct_method_bodies(stripped, open_i, close_i, blocks_sorted, _LANG_RUST)
+            if not method_bodies:
+                continue
+            per_method_fields: List[set] = []
+            universe: set = set()
+            for mbody in method_bodies:
+                fields = set(re.findall(r"\bself\s*\.\s*([A-Za-z_]\w*)", mbody))
+                per_method_fields.append(fields)
+                universe |= fields
+            if not universe:
+                continue
+            denom = len(universe)
+            for fields in per_method_fields:
+                ratios.append(len(fields & universe) / denom)
+        return ratios
+
+    # C++: class / struct bodies.
+    for open_i, close_i, hdr_start in blocks_sorted:
+        header = stripped[hdr_start:open_i]
+        if not re.search(r"\b(class|struct)\b", header):
+            continue
+        # The class body is everything between its braces.
+        method_bodies = _direct_method_bodies(stripped, open_i, close_i, blocks_sorted, _LANG_CPP)
+        # Also consider out-of-line member functions? Approximate via this->
+        # within method blocks nested in the class body only (good-enough).
+        if not method_bodies:
+            continue
+        per_method_fields = []
+        universe = set()
+        for mbody in method_bodies:
+            fields = set(re.findall(r"\bthis\s*->\s*([A-Za-z_]\w*)", mbody))
+            per_method_fields.append(fields)
+            universe |= fields
+        if not universe:
+            continue
+        denom = len(universe)
+        for fields in per_method_fields:
+            ratios.append(len(fields & universe) / denom)
+    return ratios
+
+
+def _direct_method_bodies(
+    stripped: str,
+    container_open: int,
+    container_close: int,
+    blocks_sorted: List[Tuple[int, int, int]],
+    lang: str,
+) -> List[str]:
+    """Return the body texts of method blocks that are nested (at any depth)
+    inside the container span and whose header looks like a method.
+
+    For Rust we require ``fn`` taking ``self``; for C++ we require a function
+    header (``<ident>(`` not a control keyword). We collect any matching fn
+    block strictly inside the container; nested blocks inside those (control
+    structures) are naturally excluded because their headers don't match.
+    """
+    bodies: List[str] = []
+    for open_i, close_i, hdr_start in blocks_sorted:
+        if not (container_open < open_i and close_i < container_close):
+            continue
+        header = stripped[hdr_start:open_i]
+        if lang == _LANG_RUST:
+            if _RE_RUST_FN.search(header) and re.search(r"\bself\b", header):
+                bodies.append(stripped[open_i + 1:close_i])
+        else:  # C++
+            if _is_c_fn_header(header):
+                bodies.append(stripped[open_i + 1:close_i])
+    return bodies
+
+
+# --------------------------------------------------------------------------- #
+# File walking + aggregation                                                  #
+# --------------------------------------------------------------------------- #
+
+_SKIP_DIRS = {
+    ".git",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "node_modules",
+    ".mypy_cache",
+    "target",
+    "build",
+    "dist",
+    ".pytest_cache",
+    "vendor",
+    "third_party",
+    "synergyspec-selfevolving",
+    ".synergyspec-selfevolving",
+}
+
+_PY_EXT = ".py"
+_HEURISTIC_EXTS = _C_EXTS | _CPP_EXTS | _RUST_EXTS
+_ALL_EXTS = {_PY_EXT} | _HEURISTIC_EXTS
+
+
+def _ext_lang(path: str) -> "str | None":
+    """Return the heuristic language tag for a path, or None if not C/C++/Rust."""
+    lower = path.lower()
+    # Longest-suffix match first for multi-dot exts like .c++ / .h++.
+    for ext in sorted(_HEURISTIC_EXTS, key=len, reverse=True):
+        if lower.endswith(ext):
+            if ext in _C_EXTS:
+                return _LANG_C
+            if ext in _CPP_EXTS:
+                return _LANG_CPP
+            if ext in _RUST_EXTS:
+                return _LANG_RUST
+    return None
+
+
+def _iter_source_files(root: str) -> "Iterable[tuple[str, str]]":
+    """Yield ``(path, kind)`` where kind is 'py' or a heuristic language tag."""
+    def classify(p: str) -> "str | None":
+        if p.lower().endswith(_PY_EXT):
+            return "py"
+        return _ext_lang(p)
+
+    if os.path.isfile(root):
+        kind = classify(root)
+        if kind is not None:
+            yield root, kind
+        return
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        for fn in filenames:
+            full = os.path.join(dirpath, fn)
+            kind = classify(full)
+            if kind is not None:
+                yield full, kind
+
+
+def _iter_python_files(root: str) -> Iterable[str]:
+    """Backwards-compatible Python-only iterator (retained for any callers /
+    tests that import it). Honors the extended skip-dir set."""
+    if os.path.isfile(root) and root.endswith(".py"):
+        yield root
+        return
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        for fn in filenames:
+            if fn.endswith(".py"):
+                yield os.path.join(dirpath, fn)
+
+
+def _read_source(path: str) -> "str | None":
+    try:
+        with tokenize.open(path) as f:  # respects PEP 263 encoding cookies
+            return f.read()
+    except (OSError, SyntaxError, ValueError, UnicodeDecodeError):
+        # tokenize.open can raise SyntaxError on a bad encoding declaration.
+        try:
+            with open(path, "r", encoding="utf-8", errors="replace") as f:
+                return f.read()
+        except OSError:
+            return None
+
+
+def _non_trivial_lines_heuristic(stripped: str) -> List[str]:
+    """Stripped lines worth considering for duplication in C/C++/Rust.
+
+    ``stripped`` has already had comments and string/char literals replaced
+    with spaces (preserving newlines), so we only need to drop blank lines.
+    Returns the trimmed text of each remaining line.
+    """
+    out: List[str] = []
+    for raw in stripped.splitlines():
+        s = raw.strip()
+        if not s:
+            continue
+        out.append(s)
+    return out
+
+
+def analyze(root: str) -> dict:
+    cyclomatic_values: List[float] = []
+    cognitive_values: List[float] = []
+    cohesion_ratios: List[float] = []  # heuristic class/impl cohesion ratios
+    max_depth = 0
+    import_count = 0
+    bare_except_count = 0
+    all_classes: List[ast.ClassDef] = []
+    corpus_lines: List[List[str]] = []
+
+    for path, kind in _iter_source_files(root):
+        source = _read_source(path)
+        if source is None:
+            continue
+
+        if kind == "py":
+            # ---- Python path: byte-for-byte identical to the original. ----
+            # Duplication works on raw text even if the file fails to parse.
+            corpus_lines.append(_non_trivial_lines(source))
+
+            try:
+                tree = ast.parse(source, filename=path)
+            except (SyntaxError, ValueError):
+                continue  # skip un-parseable files but keep their lines for dup
+
+            max_depth = max(max_depth, _max_nesting_depth(tree))
+
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    import_count += len(node.names)
+                elif isinstance(node, ast.ImportFrom):
+                    import_count += len(node.names)
+                elif isinstance(node, ast.ExceptHandler):
+                    if _is_broad_handler(node):
+                        bare_except_count += 1
+                elif _is_function(node):
+                    cyclomatic_values.append(_cyclomatic_complexity(node))
+                    cognitive_values.append(_cognitive_complexity(node))
+                elif isinstance(node, ast.ClassDef):
+                    all_classes.append(node)
+            continue
+
+        # ---- C / C++ / Rust heuristic path. ----
+        try:
+            stripped = _strip_c_family(source)
+        except Exception:  # noqa: BLE001 -- never let one file kill the run
+            # Fall back to raw text for dup density only.
+            corpus_lines.append(_non_trivial_lines_heuristic(source))
+            continue
+
+        # Dup density uses the comment/string-stripped, blank-dropped lines.
+        corpus_lines.append(_non_trivial_lines_heuristic(stripped))
+
+        try:
+            res = _analyze_heuristic(stripped, kind)
+        except Exception:  # noqa: BLE001 -- robustness: skip metrics for this file
+            continue
+
+        cyclomatic_values.extend(res["cyclomatic"])
+        cognitive_values.extend(res["cognitive"])
+        cohesion_ratios.extend(res["cohesion"])
+        if res["max_depth"] > max_depth:
+            max_depth = res["max_depth"]
+        import_count += res["import_count"]
+        bare_except_count += res["bare_except"]
+
+    cyclomatic_p95 = _percentile(cyclomatic_values, 95.0)
+    cognitive_mean = (
+        sum(cognitive_values) / len(cognitive_values) if cognitive_values else 0.0
+    )
+    dup_density = _duplicated_lines_density(corpus_lines)
+    attr_ratio = _attr_method_usage_ratio_combined(all_classes, cohesion_ratios)
+
+    return {
+        "cyclomatic_p95": round(cyclomatic_p95, 4),
+        "max_nesting_depth": int(max_depth),
+        "cognitive_complexity": round(cognitive_mean, 4),
+        "duplicated_lines_density": round(dup_density, 4),
+        "import_count": int(import_count),
+        "attr_method_usage_ratio": round(attr_ratio, 4),
+        "bare_except_count": int(bare_except_count),
+    }
+
+
+def _attr_method_usage_ratio_combined(
+    classes: List[ast.ClassDef], heuristic_ratios: List[float]
+) -> float:
+    """Mean over the combined set of per-(class/impl, method) cohesion ratios
+    from all languages: Python AST classes plus the precomputed heuristic
+    (Rust impl / C++ class/struct) ratios. Returns 1.0 (neutral) when there is
+    no signal at all, matching the Python-only behavior.
+
+    When there are NO heuristic ratios, this reduces exactly to the original
+    ``_attr_method_usage_ratio`` (so Python-only results are unchanged).
+    """
+    py_ratios: List[float] = []
+    for cls in classes:
+        methods = [m for m in cls.body if _is_function(m)]
+        if not methods:
+            continue
+        class_attrs: set = set()
+        per_method_refs = []
+        for m in methods:
+            assigned, referenced = _self_attr_names(m)
+            class_attrs |= assigned | referenced
+            per_method_refs.append(referenced | assigned)
+        if not class_attrs:
+            continue
+        denom = len(class_attrs)
+        for refs in per_method_refs:
+            used = len(refs & class_attrs)
+            py_ratios.append(used / denom)
+
+    combined = py_ratios + list(heuristic_ratios)
+    if not combined:
+        return 1.0
+    return sum(combined) / len(combined)
+
+
+def _empty_result() -> dict:
+    return {
+        "cyclomatic_p95": 0.0,
+        "max_nesting_depth": 0,
+        "cognitive_complexity": 0.0,
+        "duplicated_lines_density": 0.0,
+        "import_count": 0,
+        "attr_method_usage_ratio": 1.0,
+        "bare_except_count": 0,
+    }
+
+
+def main(argv: List[str]) -> int:
+    if len(argv) < 2:
+        # No directory given: emit a valid empty result rather than crash.
+        print(json.dumps(_empty_result()))
+        return 0
+    root = argv[1]
+    try:
+        if not os.path.exists(root):
+            print(json.dumps(_empty_result()))
+            return 0
+        result = analyze(root)
+    except Exception:  # noqa: BLE001 -- last-resort guard; always emit JSON
+        result = _empty_result()
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))