@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/core/shared/skills/do-code-review/scripts/code_quality_checker.py

@@ -0,0 +1,1696 @@
+#!/usr/bin/env python3
+"""
+Code Quality Checker
+
+Analyzes source code for quality issues, code smells, complexity metrics,
+and SOLID principle violations.
+
+Usage:
+    python code_quality_checker.py /path/to/file.py
+    python code_quality_checker.py /path/to/directory --recursive
+    python code_quality_checker.py . --language typescript --json
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+# Language-specific file extensions.
+# `c` is declared before `cpp` so plain `.h` resolves to C, matching the
+# dispatch table in SKILL.md. C++ headers use `.hpp` / `.hh` / `.hxx`.
+LANGUAGE_EXTENSIONS = {
+    "python": [".py"],
+    "typescript": [".ts", ".tsx"],
+    "javascript": [".js", ".jsx", ".mjs"],
+    "go": [".go"],
+    "swift": [".swift"],
+    "kotlin": [".kt", ".kts"],
+    "csharp": [".cs", ".csx", ".razor", ".cshtml"],
+    "java": [".java"],
+    "c": [".c", ".h"],
+    "cpp": [".cpp", ".cc", ".cxx", ".hpp", ".hh", ".hxx"],
+    "rust": [".rs"],
+    "ruby": [".rb", ".rake", ".gemspec", ".ru"],
+    "php": [".php", ".phtml"],
+    "dart": [".dart"],
+    "shell": [".sh", ".bash", ".zsh"],
+    "yaml": [".yaml", ".yml"],
+    "json": [".json"],
+}
+
+# Languages analysed as declarative structure rather than as code. Functions, classes, cyclomatic
+# complexity and SOLID have no meaning here, and reporting them anyway is how a fabricated score
+# gets attached to a file nobody analysed — the defect this coverage work exists to remove.
+DECLARATIVE_LANGUAGES = {"yaml", "json"}
+
+# Code smell thresholds
+THRESHOLDS = {
+    "long_function_lines": 50,
+    "too_many_parameters": 5,
+    "high_complexity": 10,
+    "god_class_methods": 20,
+    "max_imports": 15,
+    "max_declarative_depth": 8,
+}
+
+# Feature 030 — the review policy resolves from three tiers instead of living in prose.
+#
+# THRESHOLDS above stays the literal source for the built-in tier (IC-001): it is copied, never
+# duplicated, so the lowest tier cannot drift from the code that reads it. The shipped default
+# (review-policy.json beside this scripts/ directory) and an optional per-repo file overlay it, and
+# load_policy() writes the merged result back into THRESHOLDS before any analysis runs — which is why
+# the eight existing THRESHOLDS[...] reads need no edit and cannot be missed.
+#
+# Why a file at all: SKILL.md used to transcribe these numbers and drifted, listing five of six and
+# denying a nesting-depth check the analyzer performs for declarative files. A document that copies a
+# value is a copy that goes stale; a document that names a file is not.
+
+# The label each threshold is known by in documentation. Lives here rather than in the guard that
+# reads it, so adding a threshold does not mean editing the guard too.
+THRESHOLD_LABELS = {
+    "long_function_lines": "Long function",
+    "too_many_parameters": "Too many params",
+    "high_complexity": "High complexity",
+    "god_class_methods": "God class",
+    "max_imports": "Too many imports",
+    "max_declarative_depth": "Nesting depth",
+}
+
+DEFAULT_SEVERITIES = ["low", "medium", "high"]
+
+# Bands a reviewer reads a score against. Declared, never applied: the verdict stays a reading of the
+# code, and automating it would make a score authoritative over that reading.
+DEFAULT_VERDICT_BANDS = [
+    {"verdict": "Approve", "minScore": 90, "maxHighFindings": 0},
+    {"verdict": "Approve with suggestions", "minScore": 75, "maxHighFindings": 2},
+    {"verdict": "Request changes", "minScore": 50, "maxHighFindings": None},
+    {"verdict": "Block", "minScore": 0, "maxHighFindings": None},
+]
+
+# Empty because the analyzer excludes nothing today. Inventing a default exclusion here would change
+# behaviour under cover of a refactor.
+DEFAULT_EXCLUSIONS = []
+
+POLICY_GROUPS = ("thresholds", "thresholdLabels", "severities", "verdictBands", "exclusions")
+SHIPPED_POLICY_FILENAME = "review-policy.json"
+REPO_POLICY_RELPATH = Path("agent-docs") / "review-policy.json"
+
+
+def _policy_error(message: str) -> None:
+    """Stop rather than fall back. A policy that silently reverts to defaults applies one policy
+    while its author believes another is in force, which is worse than having no file."""
+    print(f"Error: {message}", file=sys.stderr)
+    sys.exit(2)
+
+
+def _check_thresholds(value, source: str) -> None:
+    if not isinstance(value, dict):
+        _policy_error(f"{source}: 'thresholds' must be an object")
+    for key, number in value.items():
+        if key not in THRESHOLDS:
+            _policy_error(f"{source}: unknown threshold '{key}' — the analyzer implements "
+                          f"{', '.join(sorted(THRESHOLDS))}")
+        # bool is an int in Python, and `true` is not a threshold.
+        if not isinstance(number, int) or isinstance(number, bool) or number <= 0:
+            _policy_error(f"{source}: threshold '{key}' must be a positive integer, got {number!r}")
+
+
+def _check_threshold_labels(value, source: str) -> None:
+    if not isinstance(value, dict) or any(
+            not isinstance(k, str) or not isinstance(v, str) for k, v in value.items()):
+        _policy_error(f"{source}: 'thresholdLabels' must be an object of strings")
+    for key in value:
+        if key not in THRESHOLDS:
+            _policy_error(f"{source}: label declared for unknown threshold '{key}'")
+
+
+def _check_string_list(group: str):
+    def check(value, source: str) -> None:
+        if not isinstance(value, list) or any(not isinstance(v, str) for v in value):
+            _policy_error(f"{source}: '{group}' must be a list of strings")
+    return check
+
+
+def _check_verdict_bands(value, source: str) -> None:
+    if not isinstance(value, list) or any(not isinstance(v, dict) for v in value):
+        _policy_error(f"{source}: 'verdictBands' must be a list of objects")
+
+
+# One validator per group, looked up rather than branched through. The first version of this was a
+# single nested ladder at complexity 27, which this skill's own analyzer flagged at high severity —
+# a validator whose shape is hard to read is the wrong place to economise.
+GROUP_VALIDATORS = {
+    "thresholds": _check_thresholds,
+    "thresholdLabels": _check_threshold_labels,
+    "severities": _check_string_list("severities"),
+    "exclusions": _check_string_list("exclusions"),
+    "verdictBands": _check_verdict_bands,
+}
+
+
+def _validate_policy_fragment(fragment: Dict, source: str) -> None:
+    if not isinstance(fragment, dict):
+        _policy_error(f"{source}: top level must be an object")
+    for group, value in fragment.items():
+        if group == "description":
+            continue
+        validator = GROUP_VALIDATORS.get(group)
+        if validator is None:
+            _policy_error(f"{source}: unknown policy group '{group}' "
+                          f"(known: {', '.join(POLICY_GROUPS)})")
+        validator(value, source)
+
+
+def _read_policy_file(path: Path) -> Dict:
+    try:
+        fragment = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as err:
+        _policy_error(f"{path}: does not parse as JSON — {err}")
+    _validate_policy_fragment(fragment, str(path))
+    return fragment
+
+
+def _trace_path(path: Path) -> str:
+    """Relative to the working directory where possible. The fixtures compare emitted JSON across
+    machines, and an absolute path would make every recorded output machine-specific — the same
+    reason finding locations are already emitted relative."""
+    try:
+        return str(path.relative_to(Path.cwd()))
+    except ValueError:
+        return str(path)
+
+
+def _walk_up_for_policy(start: Path) -> Optional[Path]:
+    current = start if start.is_dir() else start.parent
+    for directory in [current, *current.parents]:
+        candidate = directory / REPO_POLICY_RELPATH
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def find_repo_policy(start: Path) -> Optional[Path]:
+    """First agent-docs/review-policy.json found walking upward, mirroring the runtime seam's own
+    upward search for .doflow/. First hit wins, and the trace names which file won.
+
+    The analysed path is searched first, because when it sits in a repository that repository's own
+    policy is the one under review. Only when that search finds nothing does the working directory
+    get a turn — which is what makes `cd my-repo && ... /tmp/patch.py` apply my-repo's policy instead
+    of silently applying none. A target inside a policy-bearing repo is therefore never overridden by
+    wherever the reviewer happened to be standing."""
+    found = _walk_up_for_policy(start)
+    if found is not None:
+        return found
+    return _walk_up_for_policy(Path.cwd())
+
+
+def load_policy(start: Path):
+    """Resolve the policy from three tiers, lowest precedence first. Returns (policy, tiers)."""
+    policy = {
+        "thresholds": dict(THRESHOLDS),
+        "severities": list(DEFAULT_SEVERITIES),
+        "verdictBands": [dict(b) for b in DEFAULT_VERDICT_BANDS],
+        "exclusions": list(DEFAULT_EXCLUSIONS),
+        "thresholdLabels": dict(THRESHOLD_LABELS),
+    }
+    tiers = ["built-in"]
+
+    shipped = Path(__file__).resolve().parent.parent / SHIPPED_POLICY_FILENAME
+    for source in (shipped, find_repo_policy(start)):
+        if source is None or not source.is_file():
+            continue
+        fragment = _read_policy_file(source)
+        # Per key within a group, never deeper: groups hold scalars and flat lists, so there is no
+        # nested case, and validation above refuses a shape that would need one.
+        for group in POLICY_GROUPS:
+            if group not in fragment:
+                continue
+            if group in ("thresholds", "thresholdLabels"):
+                policy[group].update(fragment[group])
+            else:
+                policy[group] = fragment[group]
+        tiers.append(_trace_path(source))
+
+    return policy, tiers
+
+
+def get_file_extension(filepath: Path) -> str:
+    """Get file extension."""
+    return filepath.suffix.lower()
+
+
+def detect_language(filepath: Path) -> Optional[str]:
+    """Detect programming language from file extension."""
+    ext = get_file_extension(filepath)
+    for lang, extensions in LANGUAGE_EXTENSIONS.items():
+        if ext in extensions:
+            return lang
+    return None
+
+
+def read_file_content(filepath: Path) -> str:
+    """Read file content safely."""
+    try:
+        with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+            return f.read()
+    except Exception:
+        return ""
+
+
+# Only these languages have heredocs. Everything else spells `<<` as an operator — a stream insert
+# in C++, a bit shift in Java, an array append in Ruby's non-heredoc use — and must never be scanned
+# for one. See `_blank_heredocs` for what happens when it is.
+_HEREDOC_LANGUAGES = frozenset({"shell", "ruby", "php"})
+
+# A bare terminator must follow the delimiter immediately: `cat <<EOF`, never `cat << EOF`. That one
+# character of strictness is what separates a heredoc from `cout << total`, which always has the
+# space. The quoted forms may keep it, since `<< 'EOF'` is not a shift in any language.
+_HEREDOC_OPENER = re.compile(
+    r"""<<<?[-~]?(?:\s*(['"])([A-Za-z_][A-Za-z0-9_]*)\1|([A-Za-z_][A-Za-z0-9_]*))"""
+)
+
+
+def _heredoc_end(lines: List[str], start: int, word: str) -> Optional[int]:
+    """
+    Index of the line terminating a heredoc opened at `start`, or None if it never terminates.
+
+    Whitespace around the terminator is ignored, which is more lenient than any single language
+    allows. Leniency here can only end a body early, and ending early under-blanks — the safe
+    direction. Returning None is what makes an opener that is really an operator harmless.
+    """
+    for j in range(start + 1, len(lines)):
+        if lines[j].strip() == word:
+            return j
+    return None
+
+
+def _blank_heredocs(content: str) -> str:
+    """
+    Blank the body of every heredoc that actually terminates, preserving newlines.
+
+    A heredoc body is prose, SQL or JSON far more often than it is code, and the keyword scan
+    charges every `and`, `or`, `if` and `case` in it as a branch. A shell function whose entire
+    body is `cat <<'EOF' ... EOF` printing a usage message scored complexity 17 against a
+    threshold of 10 — a false `high_complexity` smell on a function with no branch at all.
+
+    Heredocs were previously parked as needing a tokenizer, alongside regex literals and PHP's
+    `<?php` boundary. That grouping was wrong for this one form: a heredoc *declares its own
+    terminator at the opener*, so finding the end needs no grammar, only the word the opener
+    already named. Recognising the opener is the bounded part, not recognising the end.
+
+    Bounded exactly like `_blank_spanning`, and in the same direction: an opener whose terminator
+    never appears in the remaining lines is treated as not an opener, leaving the text untouched.
+    Every bound below fails toward under-blanking, because over-blanking is what manufactures a
+    false pass.
+
+    Recognised: `<<WORD`, `<<-WORD`, `<<~WORD` (Ruby) and `<<<WORD` (PHP), quoted or bare. The
+    terminator is matched on its own line ignoring surrounding whitespace — more lenient than any
+    single language, which can only end a body early and so under-blank. Lines beginning with `#`
+    are skipped as openers, so a comment mentioning a heredoc cannot start one.
+
+    **Only called for `_HEREDOC_LANGUAGES`, and that gate is load-bearing rather than tidy.** An
+    earlier version ran for every language on the reasoning that a `<<` operator would find no
+    terminator and be left alone. That reasoning was wrong: it checked only that an opener with no
+    closer cannot blank to end-of-file, never that a *spurious* opener could meet a *spurious*
+    closer part-way down. `std::cout << total` followed anywhere below by a line reading `total`
+    blanked every branch between them, taking a C++ function from complexity 7 to 1 — a false pass,
+    the one failure this module treats as unacceptable. The gate removes the case; requiring a bare
+    terminator to touch the delimiter (`<<EOF`, never `<< EOF`) removes it a second time.
+
+    The opener's own line is code and is kept; only the body and the terminator line are blanked.
+    """
+    lines = content.split("\n")
+    out = list(lines)
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if line.lstrip().startswith("#"):
+            i += 1
+            continue
+        # A single command may open several bodies: `cmd <<A <<B`. They fill in the order opened.
+        words = [m.group(2) or m.group(3) for m in _HEREDOC_OPENER.finditer(line)]
+        cursor = i
+        for word in words:
+            end = _heredoc_end(lines, cursor, word)
+            if end is None:
+                # No terminator anywhere below: not a heredoc. Leave this line and stop here.
+                break
+            for j in range(cursor + 1, end + 1):
+                out[j] = " " * len(lines[j])
+            cursor = end
+        i = cursor + 1 if cursor > i else i + 1
+    return "\n".join(out)
+
+
+def strip_comments(content: str, language: Optional[str] = None) -> str:
+    """
+    Remove comment text so prose is not measured as code.
+
+    The keyword scan below matches \\band\\b and \\bor\\b — Python operators — against raw text,
+    case-insensitively. A documented function was therefore charged for every "and" and "or" in its
+    own prose, so the better a function was commented the worse it scored. Blank lines replace the
+    removed text rather than deleting it, so any line number derived from this string still lines up
+    with the original file.
+
+    Deliberately not handled: an "and"/"or" inside a string literal still counts. That is a separate
+    defect from the reported one, and stripping strings correctly needs a real tokenizer.
+    """
+    # Heredocs first of all: their bodies are arbitrary text, so a stray backtick or quote inside
+    # one would otherwise pair with real code below and let `_blank_spanning` erase across it.
+    # Gated on the language, and defaulting to *not* blanking: a caller that passes nothing gets the
+    # under-blanking behaviour, so a future call site that forgets the argument cannot reintroduce
+    # the false pass that gating exists to prevent.
+    if language in _HEREDOC_LANGUAGES:
+        content = _blank_heredocs(content)
+    # Block comments next, preserving newline count so line numbers survive.
+    content = re.sub(r"/\*.*?\*/", lambda m: "\n" * m.group(0).count("\n"), content, flags=re.DOTALL)
+    # Multi-line forms first, since a line-scoped pass cannot see them. Each is blanked in place with
+    # newlines preserved, so the line-scoped pass below then sees ordinary blank content.
+    for opener in ('\"\"\"', "'''", '`'):
+        content = _blank_spanning(content, opener)
+
+    out = []
+    for line in content.split("\n"):
+        stripped = line.lstrip()
+        if stripped.startswith("//") or stripped.startswith("*") or stripped.startswith("#"):
+            out.append("")
+        else:
+            out.append(re.sub(r"\s//.*$", "", line))
+    return "\n".join(out)
+
+
+def _blank_spanning(content: str, delim: str) -> str:
+    """
+    Blank the interior of every `delim`-fenced block that actually closes, preserving newlines.
+
+    Bounded the same way as the line-scoped pass: an opener with no matching closer in the rest of
+    the text is left exactly as it is. Over-blanking is the failure that matters — one unterminated
+    delimiter silently erasing the remainder of a file would turn a branch-heavy function into a
+    clean one, which is the false pass this whole analyser thread exists to remove.
+    """
+    out, i, n = [], 0, len(content)
+    while i < n:
+        start = content.find(delim, i)
+        if start == -1:
+            out.append(content[i:])
+            break
+        end = content.find(delim, start + len(delim))
+        if end == -1:
+            # No closer anywhere: not a fenced block. Leave the rest untouched.
+            out.append(content[i:])
+            break
+        inner = content[start + len(delim):end]
+        out.append(content[i:start] + delim + re.sub(r"[^\n]", " ", inner) + delim)
+        i = end + len(delim)
+    return "".join(out)
+
+
+def strip_string_literals(content: str) -> str:
+    """
+    Blank the contents of string literals so text inside them is not measured as code.
+
+    `strip_comments` fixed prose in comments being counted as control flow. The same defect exists
+    for strings: `const msg = "error or warning";` contributes a branch for the word `or`.
+
+    **This cannot be made fully correct without a tokenizer**, and none is available — the repository
+    has zero runtime dependencies and Python's `tokenize` only understands Python. Regex literals in
+    JS and PHP's `<?php` boundary need parse context this does not have. Triple-quotes and heredocs
+    do not, and are handled — see `_blank_spanning` and `_blank_heredocs`.
+
+    So the rule is bounded rather than complete: scanning is **line-scoped**, and a quote that does
+    not close on its own line is retroactively treated as not a string, leaving the rest of that line
+    untouched. That direction is deliberate. The failure that matters is not under-counting a branch;
+    it is a phantom unterminated string blanking the remainder of a file and turning a forty-branch
+    function into a clean one. Under-blanking loses a little accuracy. Over-blanking manufactures a
+    false pass, which is the whole defect class this analyser work exists to remove.
+
+    Length and newlines are preserved, so any line number derived from the result still lines up
+    with the original file.
+
+    Three multi-line forms are handled by carrying state across lines, in `strip_comments`, which
+    runs first: Python/JS triple-quoted blocks, JS backtick templates (`_blank_spanning`) and
+    heredocs (`_blank_heredocs`). All three are bounded the same way — an opener with no closer
+    anywhere in the remaining text is treated as not an opener, so an odd quote can never blank the
+    tail of a file. A heredoc's terminator is caller-chosen but the opener declares it, so it needs
+    no parsing; what is still unhandled is JS regex literals and PHP's `<?php` boundary, where
+    finding the end genuinely does require the grammar.
+    """
+    out = []
+    for line in content.split("\n"):
+        i, n, buf = 0, len(line), []
+        while i < n:
+            ch = line[i]
+            if ch in "\"'`":
+                # Look for the matching close on this line, honouring backslash escapes.
+                j, closed = i + 1, False
+                while j < n:
+                    if line[j] == "\\":
+                        j += 2
+                        continue
+                    if line[j] == ch:
+                        closed = True
+                        break
+                    j += 1
+                if closed:
+                    buf.append(ch + " " * (j - i - 1) + ch)
+                    i = j + 1
+                    continue
+                # Unclosed on this line: bounded failure. Treat it as not a string and stop
+                # scanning this line rather than blanking to end-of-file.
+                buf.append(line[i:])
+                i = n
+                continue
+            buf.append(ch)
+            i += 1
+        out.append("".join(buf))
+    return "\n".join(out)
+
+
+def trim_trailing_comment_block(body: str) -> str:
+    """
+    Drop a documentation comment sitting at the end of a sliced function body.
+
+    `find_functions` slices a body from one function match to the *next* one, so whatever documents
+    the next function landed inside this one — inflating its line count and its complexity. The
+    comment belongs to what follows, not to what precedes it.
+    """
+    lines = body.split("\n")
+    end = len(lines)
+    while end > 0 and lines[end - 1].strip() == "":
+        end -= 1
+    # Walk back over a contiguous run of comment lines at the tail.
+    start = end
+    while start > 0:
+        candidate = lines[start - 1].strip()
+        if candidate.startswith(("//", "/*", "*", "#")) or candidate == "":
+            start -= 1
+        else:
+            break
+    return "\n".join(lines[:start]) if start < end else "\n".join(lines[:end])
+
+
+def calculate_cyclomatic_complexity(content: str, language: Optional[str] = None) -> int:
+    """
+    Estimate cyclomatic complexity based on control flow keywords.
+
+    Comments and string literals are stripped first: counting keywords in either made prose a
+    penalty. String stripping is bounded, not complete — see `strip_string_literals`.
+    """
+    content = strip_string_literals(strip_comments(content, language))
+    complexity = 1  # Base complexity
+
+    # Control flow patterns that increase complexity
+    patterns = [
+        r"\bif\b",
+        r"\belif\b",
+        r"\belse\b",
+        r"\bfor\b",
+        r"\bwhile\b",
+        r"\bcase\b",
+        r"\bcatch\b",
+        r"\bexcept\b",
+        r"\band\b",
+        r"\bor\b",
+        r"\|\|",
+        r"&&"
+    ]
+
+    for pattern in patterns:
+        matches = re.findall(pattern, content, re.IGNORECASE)
+        complexity += len(matches)
+
+    return complexity
+
+
+def count_lines(content: str) -> Dict[str, int]:
+    """Count different types of lines in code."""
+    lines = content.split("\n")
+    total = len(lines)
+    blank = sum(1 for line in lines if not line.strip())
+    comment = 0
+
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("#") or stripped.startswith("//"):
+            comment += 1
+        elif stripped.startswith("/*") or stripped.startswith("'''") or stripped.startswith('"""'):
+            comment += 1
+
+    code = total - blank - comment
+
+    return {
+        "total": total,
+        "code": code,
+        "blank": blank,
+        "comment": comment
+    }
+
+
+def find_functions(content: str, language: str) -> List[Dict]:
+    """Find function definitions and their metrics."""
+    functions = []
+
+    # Language-specific function patterns
+    patterns = {
+        "python": r"def\s+(\w+)\s*\(([^)]*)\)",
+        # Both shell spellings: `name() {` and `function name {`.
+        "shell": r"(?:function\s+(\w+)\s*(?:\(\s*\))?|(\w+)\s*\(\s*\))\s*\{",
+        "typescript": r"(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^)]*\)\s*=>)",
+        "javascript": r"(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^)]*\)\s*=>)",
+        "go": r"func\s+(?:\([^)]+\)\s+)?(\w+)\s*\(([^)]*)\)",
+        "swift": r"func\s+(\w+)\s*\(([^)]*)\)",
+        "kotlin": r"fun\s+(\w+)\s*\(([^)]*)\)",
+        # C#: require at least one method modifier (public/private/etc. or static/async/...)
+        # to distinguish declarations from invocations.
+        "csharp": (
+            r"(?:(?:public|private|protected|internal|static|async|virtual|"
+            r"override|sealed|abstract|partial|new|readonly|extern)\s+)+"
+            r"(?:[\w<>?,\s\[\]\.]+?\s+)?(\w+)\s*\(([^)]*)\)"
+        ),
+        # Java: require at least one method modifier to distinguish
+        # declarations from invocations (mirrors the C# approach).
+        "java": (
+            r"(?:(?:public|private|protected|static|final|abstract|"
+            r"synchronized|native|default|strictfp)\s+)+"
+            r"(?:[\w<>?,\s\[\]\.]+?\s+)?(\w+)\s*\(([^)]*)\)"
+        ),
+        # C: require an opening brace after the parens so prototypes and
+        # call sites don't get matched. Return type / qualifiers come first.
+        # Skip C control-flow keywords that look like function calls.
+        "c": (
+            r"^(?:static\s+|inline\s+|extern\s+|const\s+|unsigned\s+|"
+            r"signed\s+|volatile\s+|register\s+)*"
+            r"(?:[\w\*]+\s+\**)+"
+            r"(?!(?:if|while|for|switch|return|sizeof)\b)"
+            r"(\w+)\s*\(([^)]*)\)\s*\{"
+        ),
+        # C++: like C but also catches `ClassName::method(...)` definitions
+        # and template return types like `std::vector<int>`.
+        "cpp": (
+            r"^(?:static\s+|inline\s+|extern\s+|const\s+|virtual\s+|"
+            r"explicit\s+|constexpr\s+|noexcept\s+)*"
+            r"(?:[\w:\*<>&,\s]+\s+\**)+"
+            r"(?!(?:if|while|for|switch|return|sizeof)\b)"
+            r"(\w+)(?:::\w+)?\s*\(([^)]*)\)\s*(?:const\s*)?"
+            r"(?:noexcept\s*)?(?:override\s*)?(?:final\s*)?\{"
+        ),
+        # Rust: `fn` keyword is always present and unambiguous.
+        "rust": (
+            r"(?:pub(?:\([^)]+\))?\s+)?(?:async\s+)?(?:unsafe\s+)?"
+            r"(?:extern\s+\"[^\"]+\"\s+)?fn\s+(\w+)\s*"
+            r"(?:<[^>]+>)?\s*\(([^)]*)\)"
+        ),
+        # Ruby: `def` keyword; params may be parenthesised or bare.
+        "ruby": (
+            r"def\s+(?:self\.)?(\w+[?!=]?)(?:\s*\(([^)]*)\)|\s*$|\s+\w)"
+        ),
+        # PHP: `function` keyword is always present.
+        "php": (
+            r"(?:(?:public|private|protected|static|abstract|final)\s+)*"
+            r"function\s+(\w+)\s*\(([^)]*)\)"
+        ),
+        # Dart: typed return followed by name and parens. Constructors
+        # (where name matches enclosing class) are not specially handled.
+        "dart": (
+            r"^\s*(?:static\s+|external\s+)*"
+            r"(?:Future<[^>]*>|Stream<[^>]*>|void|[\w<>?,\s]+?)\s+"
+            r"(\w+)\s*\(([^)]*)\)\s*(?:async\*?\s*|sync\*?\s*)?\{"
+        ),
+    }
+
+    pattern = patterns.get(language, patterns["python"])
+    matches = re.finditer(pattern, content, re.MULTILINE)
+
+    for match in matches:
+        name = next((g for g in match.groups() if g), "anonymous")
+        params_str = match.group(2) if len(match.groups()) > 1 and match.group(2) else ""
+
+        # Count parameters
+        params = [p.strip() for p in params_str.split(",") if p.strip()]
+        param_count = len(params)
+
+        # Estimate function length
+        start_pos = match.end()
+        remaining = content[start_pos:]
+
+        next_func = re.search(pattern, remaining)
+        if next_func:
+            func_body = remaining[:next_func.start()]
+        else:
+            func_body = remaining[:min(2000, len(remaining))]
+
+        # The slice runs to the next function's *declaration*, so it swallows that function's
+        # documentation comment. Give it back before measuring anything.
+        func_body = trim_trailing_comment_block(func_body)
+
+        line_count = len(func_body.split("\n"))
+        complexity = calculate_cyclomatic_complexity(func_body, language)
+
+        functions.append({
+            "name": name,
+            "parameters": param_count,
+            "lines": line_count,
+            "complexity": complexity
+        })
+
+    return functions
+
+
+def find_classes(content: str, language: str) -> List[Dict]:
+    """Find class definitions and their metrics."""
+    classes = []
+
+    patterns = {
+        "python": r"class\s+(\w+)",
+        "typescript": r"class\s+(\w+)",
+        "javascript": r"class\s+(\w+)",
+        "go": r"type\s+(\w+)\s+struct",
+        "swift": r"class\s+(\w+)",
+        "kotlin": r"class\s+(\w+)",
+        "csharp": r"(?:class|struct|record|interface)\s+(\w+)",
+        "java": r"(?:class|interface|enum|record)\s+(\w+)",
+        # C has no classes; `struct` and `typedef struct` are the closest.
+        "c": r"(?:typedef\s+)?struct\s+(\w+)",
+        "cpp": r"(?:class|struct)\s+(\w+)",
+        # Rust uses `struct`, `enum`, `trait`, `union` for type definitions.
+        # `impl` blocks attach methods but are not type defs themselves.
+        "rust": r"(?:pub(?:\([^)]+\))?\s+)?(?:struct|enum|trait|union)\s+(\w+)",
+        "ruby": r"(?:class|module)\s+(\w+)",
+        "php": (
+            r"(?:abstract\s+|final\s+)?"
+            r"(?:class|interface|trait|enum)\s+(\w+)"
+        ),
+        # Dart 3 class modifiers: final / interface / base / sealed / mixin.
+        "dart": (
+            r"(?:abstract\s+|sealed\s+|final\s+|base\s+|interface\s+)?"
+            r"(?:class|mixin|enum|extension)\s+(\w+)"
+        ),
+    }
+
+    pattern = patterns.get(language, patterns["python"])
+    matches = re.finditer(pattern, content)
+
+    for match in matches:
+        name = match.group(1)
+
+        start_pos = match.end()
+        remaining = content[start_pos:]
+
+        next_class = re.search(pattern, remaining)
+        if next_class:
+            class_body = remaining[:next_class.start()]
+        else:
+            class_body = remaining
+
+        # Count methods
+        method_patterns = {
+            "python": r"def\s+\w+\s*\(",
+            "typescript": r"(?:public|private|protected)?\s*\w+\s*\([^)]*\)\s*[:{]",
+            "javascript": r"\w+\s*\([^)]*\)\s*\{",
+            "go": r"func\s+\(",
+            "swift": r"func\s+\w+",
+            "kotlin": r"fun\s+\w+",
+            "csharp": (
+                r"(?:(?:public|private|protected|internal|static|async|virtual|"
+                r"override|sealed|abstract|partial)\s+)+"
+                r"(?:[\w<>?,\s\[\]\.]+?\s+)?\w+\s*\("
+            ),
+            "java": (
+                r"(?:(?:public|private|protected|static|final|abstract|"
+                r"synchronized|native|default|strictfp)\s+)+"
+                r"(?:[\w<>?,\s\[\]\.]+?\s+)?\w+\s*\("
+            ),
+            # C has no classes; struct members are typically function pointers
+            # rather than methods. Use the function definition pattern.
+            "c": (
+                r"^(?:static\s+|inline\s+)*(?:[\w\*]+\s+\**)+"
+                r"(?!(?:if|while|for|switch|return|sizeof)\b)"
+                r"\w+\s*\([^)]*\)\s*\{"
+            ),
+            "cpp": (
+                r"^(?:static\s+|inline\s+|virtual\s+|explicit\s+|"
+                r"constexpr\s+)*(?:[\w:\*<>&,\s]+\s+\**)+"
+                r"(?!(?:if|while|for|switch|return|sizeof)\b)"
+                r"\w+(?:::\w+)?\s*\([^)]*\)"
+            ),
+            "rust": (
+                r"(?:pub(?:\([^)]+\))?\s+)?(?:async\s+)?(?:unsafe\s+)?"
+                r"fn\s+\w+"
+            ),
+            "ruby": r"def\s+(?:self\.)?\w+[?!=]?",
+            "php": (
+                r"(?:(?:public|private|protected|static|abstract|final)\s+)*"
+                r"function\s+\w+\s*\("
+            ),
+            "dart": (
+                r"^\s*(?:static\s+|external\s+)*"
+                r"(?:Future<[^>]*>|Stream<[^>]*>|void|[\w<>?,\s]+?)\s+"
+                r"\w+\s*\([^)]*\)\s*(?:async\*?\s*|sync\*?\s*)?\{"
+            ),
+        }
+        method_pattern = method_patterns.get(language, method_patterns["python"])
+        methods = len(re.findall(method_pattern, class_body))
+
+        classes.append({
+            "name": name,
+            "methods": methods,
+            "lines": len(class_body.split("\n"))
+        })
+
+    return classes
+
+
+def check_code_smells(content: str, functions: List[Dict], classes: List[Dict]) -> List[Dict]:
+    """Check for code smells in the content."""
+    smells = []
+
+    # Long functions
+    for func in functions:
+        if func["lines"] > THRESHOLDS["long_function_lines"]:
+            smells.append({
+                "type": "long_function",
+                "severity": "medium",
+                "message": f"Function '{func['name']}' has {func['lines']} lines (max: {THRESHOLDS['long_function_lines']})",
+                "location": func["name"]
+            })
+
+    # Too many parameters
+    for func in functions:
+        if func["parameters"] > THRESHOLDS["too_many_parameters"]:
+            smells.append({
+                "type": "too_many_parameters",
+                "severity": "low",
+                "message": f"Function '{func['name']}' has {func['parameters']} parameters (max: {THRESHOLDS['too_many_parameters']})",
+                "location": func["name"]
+            })
+
+    # High complexity
+    for func in functions:
+        if func["complexity"] > THRESHOLDS["high_complexity"]:
+            severity = "high" if func["complexity"] > 20 else "medium"
+            smells.append({
+                "type": "high_complexity",
+                "severity": severity,
+                "message": f"Function '{func['name']}' has complexity {func['complexity']} (max: {THRESHOLDS['high_complexity']})",
+                "location": func["name"]
+            })
+
+    # God classes
+    for cls in classes:
+        if cls["methods"] > THRESHOLDS["god_class_methods"]:
+            smells.append({
+                "type": "god_class",
+                "severity": "high",
+                "message": f"Class '{cls['name']}' has {cls['methods']} methods (max: {THRESHOLDS['god_class_methods']})",
+                "location": cls["name"]
+            })
+
+    # Magic numbers
+    magic_pattern = r"\b(?<![.\"\'])\d{3,}\b(?!\.\d)"
+    for i, line in enumerate(content.split("\n"), 1):
+        if line.strip().startswith(("#", "//", "import", "from")):
+            continue
+        matches = re.findall(magic_pattern, line)
+        for match in matches[:1]:  # One per line
+            smells.append({
+                "type": "magic_number",
+                "severity": "low",
+                "message": f"Magic number {match} should be a named constant",
+                "location": f"line {i}"
+            })
+
+    # Commented code patterns
+    commented_code_pattern = r"^\s*[#//]+\s*(if|for|while|def|function|class|const|let|var)\s"
+    for i, line in enumerate(content.split("\n"), 1):
+        if re.match(commented_code_pattern, line, re.IGNORECASE):
+            smells.append({
+                "type": "commented_code",
+                "severity": "low",
+                "message": "Commented-out code should be removed",
+                "location": f"line {i}"
+            })
+
+    return smells
+
+
+def _strip_csharp_comments(content: str) -> str:
+    """Remove // line comments and /* */ block comments so regex detectors
+    don't match keywords inside prose."""
+    no_block = re.sub(r"/\*.*?\*/", "", content, flags=re.DOTALL)
+    no_line = re.sub(r"//[^\n]*", "", no_block)
+    return no_line
+
+
+def check_csharp_specific_smells(content: str) -> List[Dict]:
+    """C# / .NET-specific code smells documented in SKILL.md."""
+    smells: List[Dict] = []
+    content = _strip_csharp_comments(content)
+
+    # async void (event handler exception only — caller must justify)
+    for match in re.finditer(r"\basync\s+void\s+(\w+)\s*\(", content):
+        smells.append({
+            "type": "csharp_async_void",
+            "severity": "high",
+            "message": (
+                f"'async void {match.group(1)}' — only safe for event handlers; "
+                "prefer 'async Task'"
+            ),
+            "location": match.group(1),
+        })
+
+    # Blocking on async: .Result, .Wait(), .GetAwaiter().GetResult()
+    for match in re.finditer(
+        r"\.(?:Result\b|Wait\(\)|GetAwaiter\(\)\.GetResult\(\))", content
+    ):
+        smells.append({
+            "type": "csharp_blocking_async",
+            "severity": "high",
+            "message": (
+                "Blocking call on async operation ('.Result' / '.Wait()' / "
+                "'.GetAwaiter().GetResult()') — can deadlock in ASP.NET contexts"
+            ),
+            "location": f"offset {match.start()}",
+        })
+
+    # Bare catch / catch (Exception) that swallows
+    swallow_pattern = re.compile(
+        r"catch\s*(?:\(\s*(?:System\.)?Exception(?:\s+\w+)?\s*\))?\s*\{\s*\}"
+    )
+    for match in swallow_pattern.finditer(content):
+        smells.append({
+            "type": "csharp_swallowed_exception",
+            "severity": "high",
+            "message": "Empty catch block swallows exceptions silently",
+            "location": f"offset {match.start()}",
+        })
+
+    # IDisposable instantiated but not in `using` — heuristic: `new SomethingClient(`
+    # / `new SomethingStream(` / `new SqlConnection(` outside a `using` line.
+    disposable_hint = re.compile(
+        r"^(?!\s*using\b)\s*(?:var|[\w<>]+)\s+\w+\s*=\s*new\s+"
+        r"(\w*(?:Stream|Connection|Reader|Writer|Client|Context|Command))\s*\(",
+        re.MULTILINE,
+    )
+    for match in disposable_hint.finditer(content):
+        smells.append({
+            "type": "csharp_undisposed_idisposable",
+            "severity": "medium",
+            "message": (
+                f"'{match.group(1)}' looks like IDisposable but is not wrapped in "
+                "'using' / 'using var'"
+            ),
+            "location": f"offset {match.start()}",
+        })
+
+    # HttpClient instantiated with `new` inside a method body (socket exhaustion)
+    httpclient_inline = re.compile(r"new\s+HttpClient\s*\(\s*\)")
+    for match in httpclient_inline.finditer(content):
+        smells.append({
+            "type": "csharp_new_httpclient",
+            "severity": "medium",
+            "message": (
+                "'new HttpClient()' — prefer IHttpClientFactory or a long-lived "
+                "static instance to avoid socket exhaustion"
+            ),
+            "location": f"offset {match.start()}",
+        })
+
+    # Missing await: `Task.Run(` / async method call assigned but never awaited.
+    # Heuristic: a statement ending in `Async()` or `Async(...)` followed by `;`
+    # with no `await` keyword on the same line.
+    for line_no, line in enumerate(content.split("\n"), 1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith(("//", "/*", "*")):
+            continue
+        if re.search(r"\b\w+Async\s*\([^)]*\)\s*;\s*$", stripped) and "await " not in stripped:
+            # Skip `return ...Async();` (forwarding the Task is legitimate)
+            if stripped.startswith("return "):
+                continue
+            smells.append({
+                "type": "csharp_missing_await",
+                "severity": "medium",
+                "message": "Async method called without 'await' — Task is discarded",
+                "location": f"line {line_no}",
+            })
+
+    # Unnecessary `using` directives — heuristic: `using` directive whose
+    # namespace tail isn't referenced anywhere else in the file.
+    using_directives = re.findall(
+        r"^using\s+(?:static\s+)?([A-Z]\w*(?:\.\w+)*)\s*;", content, re.MULTILINE
+    )
+    body = re.sub(r"^using\s+[^;]+;\s*$", "", content, flags=re.MULTILINE)
+    for ns in using_directives:
+        tail = ns.split(".")[-1]
+        if not re.search(rf"\b{re.escape(tail)}\b", body):
+            smells.append({
+                "type": "csharp_unused_using",
+                "severity": "low",
+                "message": f"'using {ns};' appears unused",
+                "location": ns,
+            })
+
+    return smells
+
+
+def check_java_specific_smells(content: str) -> List[Dict]:
+    """Java-specific code smells documented in languages/java.md."""
+    smells: List[Dict] = []
+    # Java comment syntax matches C#, so the same stripper applies.
+    content = _strip_csharp_comments(content)
+
+    # Empty catch block — swallows the exception silently.
+    for match in re.finditer(r"catch\s*\([^)]*\)\s*\{\s*\}", content):
+        smells.append({
+            "type": "java_empty_catch",
+            "severity": "high",
+            "message": "Empty catch block swallows exceptions silently",
+            "location": f"offset {match.start()}",
+        })
+
+    # printStackTrace() as error handling — use a logger instead.
+    for match in re.finditer(r"\.printStackTrace\s*\(\s*\)", content):
+        smells.append({
+            "type": "java_print_stack_trace",
+            "severity": "medium",
+            "message": (
+                "'printStackTrace()' is not real error handling — log via a "
+                "proper logger or rethrow with context"
+            ),
+            "location": f"offset {match.start()}",
+        })
+
+    # InterruptedException caught without restoring the interrupt flag.
+    for match in re.finditer(
+        r"catch\s*\(\s*InterruptedException\s+(\w+)\s*\)\s*\{(.*?)\}",
+        content,
+        re.DOTALL,
+    ):
+        if "interrupt()" not in match.group(2):
+            smells.append({
+                "type": "java_swallowed_interrupt",
+                "severity": "high",
+                "message": (
+                    "InterruptedException caught without "
+                    "'Thread.currentThread().interrupt()' — breaks cooperative "
+                    "cancellation"
+                ),
+                "location": f"offset {match.start()}",
+            })
+
+    # Closeable resource instantiated outside try-with-resources (leak heuristic).
+    resource_hint = re.compile(
+        r"^(?!\s*try\b)\s*(?:final\s+)?[\w<>\[\]]+\s+\w+\s*=\s*new\s+"
+        r"(\w*(?:InputStream|OutputStream|Reader|Writer|Stream|Connection))\s*\(",
+        re.MULTILINE,
+    )
+    for match in resource_hint.finditer(content):
+        smells.append({
+            "type": "java_unclosed_resource",
+            "severity": "medium",
+            "message": (
+                f"'{match.group(1)}' looks like an AutoCloseable but is not in a "
+                "try-with-resources statement"
+            ),
+            "location": f"offset {match.start()}",
+        })
+
+    # Heavy object built per use instead of shared as a singleton.
+    # A `static` field assignment is the recommended singleton form — skip it.
+    heavy_object = re.compile(
+        r"^(?!.*\bstatic\b).*\bnew\s+(ObjectMapper|Gson)\s*\(\s*\)",
+        re.MULTILINE,
+    )
+    for match in heavy_object.finditer(content):
+        smells.append({
+            "type": "java_per_use_heavy_object",
+            "severity": "medium",
+            "message": (
+                f"'new {match.group(1)}()' is expensive — share a singleton "
+                "instance instead of constructing per call"
+            ),
+            "location": f"offset {match.start()}",
+        })
+
+    return smells
+
+
+def check_c_specific_smells(content: str) -> List[Dict]:
+    """C-specific code smells documented in languages/c.md.
+
+    Focuses on memory-safety and command/format-string patterns that the
+    CERT C Coding Standard and the CWE catalogue rank as the
+    highest-impact footguns. C uses the same line/block comment syntax as
+    C# and Java, so the existing comment stripper applies.
+    """
+    smells: List[Dict] = []
+    content = _strip_csharp_comments(content)
+
+    # 1. Banned functions — no bounds check on any of them.
+    banned = {
+        "gets": "no bounds check, removed from C11 (CWE-242)",
+        "strcpy": "no bounds check — prefer strncpy or strlcpy",
+        "strcat": "no bounds check — prefer strncat or strlcat",
+        "sprintf": "no bounds check — prefer snprintf",
+        "vsprintf": "no bounds check — prefer vsnprintf",
+    }
+    for fn, reason in banned.items():
+        for m in re.finditer(rf"\b{fn}\s*\(", content):
+            smells.append({
+                "type": f"c_banned_{fn}",
+                "severity": "high",
+                "message": f"'{fn}()' is unsafe: {reason}",
+                "location": f"offset {m.start()}",
+            })
+
+    # 2. Format-string vulnerability — printf/syslog called with a bare
+    # identifier as the format argument (CWE-134). Skip when the first
+    # arg is a string literal.
+    for fn in ("printf", "syslog"):
+        pattern = rf"\b{fn}\s*\(\s*(?!\")(\w+)\s*[,\)]"
+        for m in re.finditer(pattern, content):
+            smells.append({
+                "type": "c_format_string",
+                "severity": "high",
+                "message": (
+                    f"'{fn}({m.group(1)})' uses a non-literal format string "
+                    "— CWE-134 format string vulnerability"
+                ),
+                "location": f"offset {m.start()}",
+            })
+
+    # 3. Unbounded scanf — `%s` without a width specifier invites overflow.
+    scanf_call = re.compile(
+        r"\b(?:scanf|fscanf|sscanf)\s*\(\s*[^)]*?\"([^\"]*)\""
+    )
+    for m in scanf_call.finditer(content):
+        fmt = m.group(1)
+        if "%s" in fmt and not re.search(r"%\d+s", fmt):
+            smells.append({
+                "type": "c_unbounded_scanf",
+                "severity": "high",
+                "message": (
+                    "scanf '%s' without a width specifier — unbounded read "
+                    "can overflow the destination buffer"
+                ),
+                "location": f"offset {m.start()}",
+            })
+
+    # 4. malloc / calloc / realloc result dereferenced without a NULL check
+    # within 5 lines. CWE-690.
+    lines = content.split("\n")
+    malloc_assign = re.compile(
+        r"^\s*(?:[\w\*]+\s+)?\*?(\w+)\s*=\s*\(?[\w\s\*]*\)?\s*"
+        r"(?:m|c|re)alloc\s*\("
+    )
+    for i, line in enumerate(lines):
+        m = malloc_assign.match(line)
+        if not m:
+            continue
+        var = m.group(1)
+        window = "\n".join(lines[i + 1 : i + 6])
+        null_check = re.compile(
+            rf"\bif\s*\([^)]*(?:{re.escape(var)}\s*==\s*NULL"
+            rf"|NULL\s*==\s*{re.escape(var)}"
+            rf"|!\s*{re.escape(var)}\b"
+            rf"|{re.escape(var)}\s*!=\s*NULL)"
+        )
+        if not null_check.search(window):
+            smells.append({
+                "type": "c_malloc_unchecked",
+                "severity": "medium",
+                "message": (
+                    f"'{var}' from malloc/calloc/realloc is not NULL-checked "
+                    "within 5 lines — dereferencing NULL is UB (CWE-690)"
+                ),
+                "location": f"line {i + 1}",
+            })
+
+    # 5. free(p) without setting p to NULL on the next real line.
+    # CWE-416 use-after-free guardrail.
+    free_call = re.compile(r"^\s*free\s*\(\s*(\w+)\s*\)\s*;")
+    for i, line in enumerate(lines):
+        m = free_call.match(line)
+        if not m:
+            continue
+        var = m.group(1)
+        for j in range(i + 1, min(i + 3, len(lines))):
+            nxt = lines[j].strip()
+            if not nxt:
+                continue
+            if re.match(rf"^{re.escape(var)}\s*=\s*NULL\s*;", nxt):
+                break
+            smells.append({
+                "type": "c_free_without_null",
+                "severity": "low",
+                "message": (
+                    f"'free({var})' not followed by '{var} = NULL;' — "
+                    "dangling pointer can be reused (CWE-416)"
+                ),
+                "location": f"line {i + 1}",
+            })
+            break
+
+    # 6. system() with a non-string-literal argument — command injection.
+    system_pattern = re.compile(r"\bsystem\s*\(\s*(?!\"|NULL\b)(\w+)\s*\)")
+    for m in system_pattern.finditer(content):
+        smells.append({
+            "type": "c_system_non_literal",
+            "severity": "high",
+            "message": (
+                f"'system({m.group(1)})' with a non-literal argument — "
+                "command injection (CWE-78); use execve with validated args"
+            ),
+            "location": f"offset {m.start()}",
+        })
+
+    return smells
+
+
+def check_solid_violations(content: str) -> List[Dict]:
+    """Check for potential SOLID principle violations."""
+    violations = []
+
+    # OCP: Type checking instead of polymorphism
+    type_checks = len(re.findall(r"isinstance\(|type\(.*\)\s*==|typeof\s+\w+\s*===", content))
+    if type_checks > 2:
+        violations.append({
+            "principle": "OCP",
+            "name": "Open/Closed Principle",
+            "severity": "medium",
+            "message": f"Found {type_checks} type checks - consider using polymorphism"
+        })
+
+    # LSP/ISP: NotImplementedError
+    not_impl = len(re.findall(r"raise\s+NotImplementedError|not\s+implemented", content, re.IGNORECASE))
+    if not_impl:
+        violations.append({
+            "principle": "LSP/ISP",
+            "name": "Liskov/Interface Segregation",
+            "severity": "low",
+            "message": f"Found {not_impl} unimplemented methods - may indicate oversized interface"
+        })
+
+    # DIP: Too many direct imports
+    imports = len(re.findall(r"^(?:import|from)\s+", content, re.MULTILINE))
+    if imports > THRESHOLDS["max_imports"]:
+        violations.append({
+            "principle": "DIP",
+            "name": "Dependency Inversion Principle",
+            "severity": "low",
+            "message": f"File has {imports} imports - consider dependency injection"
+        })
+
+    return violations
+
+
+def calculate_quality_score(
+    line_metrics: Dict,
+    functions: List[Dict],
+    classes: List[Dict],
+    smells: List[Dict],
+    violations: List[Dict]
+) -> int:
+    """Calculate overall quality score (0-100)."""
+    score = 100
+
+    # Deduct for code smells
+    for smell in smells:
+        if smell["severity"] == "high":
+            score -= 10
+        elif smell["severity"] == "medium":
+            score -= 5
+        elif smell["severity"] == "low":
+            score -= 2
+
+    # Deduct for SOLID violations
+    for violation in violations:
+        if violation["severity"] == "high":
+            score -= 8
+        elif violation["severity"] == "medium":
+            score -= 4
+        elif violation["severity"] == "low":
+            score -= 2
+
+    # Bonus for good comment ratio (10-30%)
+    if line_metrics["total"] > 0:
+        comment_ratio = line_metrics["comment"] / line_metrics["total"]
+        if 0.1 <= comment_ratio <= 0.3:
+            score += 5
+
+    # Bonus for reasonable function sizes
+    if functions:
+        avg_lines = sum(f["lines"] for f in functions) / len(functions)
+        if avg_lines < 30:
+            score += 5
+
+    return max(0, min(100, score))
+
+
+def get_grade(score: int) -> str:
+    """Convert score to letter grade."""
+    if score >= 90:
+        return "A"
+    elif score >= 80:
+        return "B"
+    elif score >= 70:
+        return "C"
+    elif score >= 60:
+        return "D"
+    else:
+        return "F"
+
+
+def display_path(path: Path) -> str:
+    """The form a path takes in emitted output: relative to the working directory.
+
+    Input is resolved to an absolute path so filesystem checks are unambiguous, but an
+    absolute path in the *output* is machine-specific. That has two costs: committed
+    fixtures under expected_outputs/ can only ever match the machine that produced them,
+    and findings here cannot be matched against pr_analyzer.py's git-relative paths when
+    review_report_generator.py merges both into one report.
+
+    os.path.relpath rather than Path.relative_to: the latter raises ValueError for a
+    target outside the working directory, which is a supported input here.
+    """
+    return os.path.relpath(str(path), os.getcwd())
+
+
+def check_shell_specific_smells(content: str) -> List[Dict]:
+    """Shell has real control flow, so it is analysed as code — but its failure modes are its own."""
+    smells = []
+    lines = content.split("\n")
+
+    if lines and lines[0].startswith("#!") and "set -" not in content:
+        smells.append({
+            "type": "no_error_handling",
+            "severity": "high",
+            "message": "Script has no 'set -e'/'set -u'/'set -o pipefail' — a failing command is "
+                       "silently ignored and the script continues with bad state",
+            "location": "line 1",
+        })
+
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            continue
+        # Unquoted expansion of a variable that may hold spaces or globs.
+        if re.search(r"(?<![\"'\w])\$\{?[A-Za-z_][A-Za-z0-9_]*\}?(?![\"'\w])", stripped) and re.search(
+            r"^\s*(?:rm|cp|mv|cat|source|\.|cd|mkdir|test|\[)\s", stripped
+        ):
+            if '"' not in stripped:
+                smells.append({
+                    "type": "unquoted_expansion",
+                    "severity": "high",
+                    "message": "Unquoted variable expansion in a command that acts on paths — a "
+                               "value containing spaces or globs will not do what it looks like",
+                    "location": f"line {i}",
+                })
+        if re.search(r"\bcd\s+[^&|;]+$", stripped) and "||" not in stripped and "set -e" not in content:
+            smells.append({
+                "type": "unchecked_cd",
+                "severity": "medium",
+                "message": "'cd' without '|| exit' or 'set -e' — the rest of the script runs in the "
+                           "wrong directory if it fails",
+                "location": f"line {i}",
+            })
+
+    return smells
+
+
+def analyze_declarative(content: str, language: str) -> Dict:
+    """
+    Structural analysis for YAML and JSON.
+
+    Reports parse validity, nesting depth, duplicate keys and plain-text secrets. Deliberately
+    reports no cyclomatic complexity, no SOLID verdict and no function count: those readings do not
+    exist for declarative data, and inventing them is exactly the false-confidence defect this
+    coverage work removes.
+    """
+    smells = []
+    lines = content.split("\n")
+
+    parse_error = None
+    if language == "json":
+        try:
+            json.loads(content)
+        except ValueError as exc:
+            parse_error = str(exc)
+    else:
+        seen_at_indent = {}
+        for i, line in enumerate(lines, 1):
+            match = re.match(r"^(\s*)([A-Za-z_][\w.-]*):", line)
+            if not match:
+                continue
+            indent, key = len(match.group(1)), match.group(2)
+            bucket = seen_at_indent.setdefault(indent, {})
+            if key in bucket:
+                smells.append({
+                    "type": "duplicate_key",
+                    "severity": "high",
+                    "message": f"Key '{key}' is defined twice at the same level — the later value "
+                               f"silently wins (first seen at line {bucket[key]})",
+                    "location": f"line {i}",
+                })
+            else:
+                bucket[key] = i
+
+    if parse_error:
+        smells.append({
+            "type": "parse_error",
+            "severity": "high",
+            "message": f"File does not parse as {language}: {parse_error}",
+            "location": "line 1",
+        })
+
+    max_depth = 0
+    for line in lines:
+        if not line.strip() or line.strip().startswith("#"):
+            continue
+        indent = len(line) - len(line.lstrip())
+        max_depth = max(max_depth, indent // 2)
+    if max_depth > THRESHOLDS["max_declarative_depth"]:
+        smells.append({
+            "type": "deep_nesting",
+            "severity": "medium",
+            "message": f"Nesting reaches depth {max_depth} (threshold "
+                       f"{THRESHOLDS['max_declarative_depth']}) — deeply nested config is hard to "
+                       f"review and easy to mis-indent",
+            "location": "file",
+        })
+
+    for i, line in enumerate(lines, 1):
+        if re.search(r"(?i)\b(password|secret|token|api[_-]?key|private[_-]?key)\b\s*[:=]\s*['\"]?[^\s'\"{}$]{8,}", line):
+            smells.append({
+                "type": "plaintext_secret",
+                "severity": "high",
+                "message": "A credential-shaped key carries a literal value — secrets belong in a "
+                           "secret store, not in a committed config file",
+                "location": f"line {i}",
+            })
+
+    return {"smells": smells, "max_depth": max_depth, "parses": parse_error is None}
+
+
+def analyze_file(filepath: Path) -> Dict:
+    """Analyze a single file for code quality."""
+    language = detect_language(filepath)
+    if not language:
+        return {"error": f"Unsupported file type: {filepath.suffix}"}
+
+    content = read_file_content(filepath)
+    if not content:
+        return {"error": f"Could not read file: {filepath}"}
+
+    if language in DECLARATIVE_LANGUAGES:
+        line_metrics = count_lines(content)
+        declarative = analyze_declarative(content, language)
+        smells = declarative["smells"]
+        # Scored on the same 100-point scale so a mixed change compares, but from structural
+        # findings only — there is no complexity or SOLID term to include here.
+        score = max(0, 100 - sum(
+            15 if sm["severity"] == "high" else 8 if sm["severity"] == "medium" else 3
+            for sm in smells
+        ))
+        return {
+            "file": display_path(filepath),
+            "language": language,
+            "analysis_kind": "declarative",
+            "metrics": {
+                "lines": line_metrics,
+                "max_depth": declarative["max_depth"],
+                "parses": declarative["parses"],
+            },
+            "smells": smells,
+            "solid_violations": [],
+            "quality_score": score,
+            "grade": get_grade(score),
+        }
+
+    line_metrics = count_lines(content)
+    functions = find_functions(content, language)
+    classes = find_classes(content, language)
+    smells = check_code_smells(content, functions, classes)
+    if language == "csharp":
+        smells.extend(check_csharp_specific_smells(content))
+    if language == "java":
+        smells.extend(check_java_specific_smells(content))
+    if language == "c":
+        smells.extend(check_c_specific_smells(content))
+    if language == "shell":
+        smells.extend(check_shell_specific_smells(content))
+    violations = check_solid_violations(content)
+    score = calculate_quality_score(line_metrics, functions, classes, smells, violations)
+
+    return {
+        "file": display_path(filepath),
+        "language": language,
+        "metrics": {
+            "lines": line_metrics,
+            "functions": len(functions),
+            "classes": len(classes),
+            "avg_complexity": round(sum(f["complexity"] for f in functions) / max(1, len(functions)), 1)
+        },
+        "quality_score": score,
+        "grade": get_grade(score),
+        "smells": smells,
+        "solid_violations": violations,
+        "function_details": functions[:10],
+        "class_details": classes[:10]
+    }
+
+
+def analyze_directory(
+    dir_path: Path,
+    recursive: bool = True,
+    language: Optional[str] = None
+) -> Dict:
+    """
+    Analyze all files in a directory, reporting what was NOT analysed as prominently as what was.
+
+    This function used to enumerate only the extensions it recognised and then drop any per-file
+    error before averaging (`if "error" not in result`). A change of nineteen OpenAPI files and two
+    TypeScript files therefore reported "Files Analyzed: 2" with a score computed from the two, and
+    the nineteen appeared nowhere. The skill's own Review Contract already forbids that — "a file
+    the derivation includes but the review never opened is reported as not reviewed; it is never
+    dropped from the list" — so this is the deterministic tool being made to obey a policy the
+    bundle already publishes, not a new policy.
+
+    Every file the walk sees ends up in exactly one of `files` or `skipped`. `coverage` is
+    "complete" only when nothing was skipped.
+    """
+    results = []
+    skipped = []
+
+    pattern = "**/*" if recursive else "*"
+    selected_extensions = set(LANGUAGE_EXTENSIONS.get(language, [])) if language else None
+
+    for filepath in sorted(dir_path.glob(pattern)):
+        if not filepath.is_file():
+            continue
+        parts = filepath.parts
+        if "node_modules" in parts or ".git" in parts:
+            continue
+
+        detected = detect_language(filepath)
+        if selected_extensions is not None and get_file_extension(filepath) not in selected_extensions:
+            # An explicit --language narrowed the scope. Still reported: the caller chose it, but a
+            # reader of the report did not, and a narrowed run that looks like a full one is the
+            # same false confidence in a different costume.
+            skipped.append({"file": display_path(filepath), "reason": f"excluded by --language {language}"})
+            continue
+        if not detected:
+            skipped.append({
+                "file": display_path(filepath),
+                "reason": f"no analyser for '{filepath.suffix or filepath.name}'",
+            })
+            continue
+
+        result = analyze_file(filepath)
+        if "error" in result:
+            skipped.append({"file": display_path(filepath), "reason": result["error"]})
+            continue
+        results.append(result)
+
+    skipped_by_reason: Dict[str, int] = {}
+    for item in skipped:
+        skipped_by_reason[item["reason"]] = skipped_by_reason.get(item["reason"], 0) + 1
+
+    base = {
+        "directory": display_path(dir_path),
+        "files_analyzed": len(results),
+        "files_skipped": len(skipped),
+        "coverage": "complete" if not skipped else "partial",
+        "skipped": skipped,
+        "skipped_by_reason": skipped_by_reason,
+    }
+
+    if not results:
+        # Previously an error string, which discarded the skipped list with it — the caller was told
+        # "No supported files found" and could not see WHICH files those were.
+        return {
+            **base,
+            "average_score": None,
+            "overall_grade": None,
+            "total_code_smells": 0,
+            "total_solid_violations": 0,
+            "files": [],
+        }
+
+    total_score = sum(r["quality_score"] for r in results)
+    avg_score = total_score / len(results)
+
+    return {
+        **base,
+        "average_score": round(avg_score, 1),
+        "overall_grade": get_grade(int(avg_score)),
+        "total_code_smells": sum(len(r["smells"]) for r in results),
+        "total_solid_violations": sum(len(r["solid_violations"]) for r in results),
+        "files": sorted(results, key=lambda x: x["quality_score"]),
+    }
+
+
+def print_report(analysis: Dict) -> None:
+    """Print human-readable analysis report."""
+    if "error" in analysis:
+        print(f"Error: {analysis['error']}")
+        return
+
+    print("=" * 60)
+    print("CODE QUALITY REPORT")
+    print("=" * 60)
+
+    if "file" in analysis:
+        print(f"\nFile: {analysis['file']}")
+        print(f"Language: {analysis['language']}")
+        print(f"Quality Score: {analysis['quality_score']}/100 ({analysis['grade']})")
+
+        metrics = analysis["metrics"]
+        print(f"\nLines: {metrics['lines']['total']} ({metrics['lines']['code']} code, {metrics['lines']['comment']} comments)")
+        if analysis.get("analysis_kind") == "declarative":
+            # No function, class or complexity line here on purpose: those readings do not exist for
+            # declarative data, and printing a zero would read as "analysed and found none".
+            print(f"Max nesting depth: {metrics['max_depth']}")
+            print(f"Parses: {'yes' if metrics['parses'] else 'no'}")
+            print("Analysed as declarative structure — complexity and SOLID do not apply.")
+        else:
+            print(f"Functions: {metrics['functions']}")
+            print(f"Classes: {metrics['classes']}")
+            print(f"Avg Complexity: {metrics['avg_complexity']}")
+
+        if analysis["smells"]:
+            print("\n--- CODE SMELLS ---")
+            for smell in analysis["smells"][:10]:
+                print(f"  [{smell['severity'].upper()}] {smell['message']} ({smell['location']})")
+
+        if analysis["solid_violations"]:
+            print("\n--- SOLID VIOLATIONS ---")
+            for v in analysis["solid_violations"]:
+                print(f"  [{v['principle']}] {v['message']}")
+    else:
+        print(f"\nDirectory: {analysis['directory']}")
+        print(f"Files Analyzed: {analysis['files_analyzed']}")
+        print(f"Files Skipped:  {analysis['files_skipped']}")
+        if analysis["average_score"] is None:
+            print("Average Score: n/a — nothing in this directory was analysed")
+        else:
+            print(f"Average Score: {analysis['average_score']}/100 ({analysis['overall_grade']})"
+                  f" — over the {analysis['files_analyzed']} analysed file(s) only")
+        print(f"Total Code Smells: {analysis['total_code_smells']}")
+        print(f"Total SOLID Violations: {analysis['total_solid_violations']}")
+
+        # The coverage line comes before the findings, not after: a reader who stops at the score
+        # must already have been told what the score does not cover.
+        if analysis["coverage"] == "partial":
+            print(f"\n*** COVERAGE: PARTIAL — {analysis['files_skipped']} file(s) were not analysed. ***")
+            print("*** This verdict describes the analysed files only, not the whole change.   ***")
+        else:
+            print("\nCoverage: complete — every file in scope was analysed.")
+
+        if analysis["files"]:
+            print("\n--- FILES BY QUALITY ---")
+            for f in analysis["files"][:10]:
+                print(f"  {f['quality_score']:3d}/100 [{f['grade']}] {f['file']}")
+
+        if analysis["skipped"]:
+            print("\n--- SKIPPED (not analysed) ---")
+            for reason, count in sorted(analysis["skipped_by_reason"].items(), key=lambda kv: -kv[1]):
+                print(f"  {count:3d} x {reason}")
+            for item in analysis["skipped"][:20]:
+                print(f"      {item['file']} — {item['reason']}")
+            if len(analysis["skipped"]) > 20:
+                print(f"      ... and {len(analysis['skipped']) - 20} more (use --json for the full list)")
+
+    print("\n" + "=" * 60)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Analyze code quality, smells, and SOLID violations"
+    )
+    parser.add_argument(
+        "path",
+        help="File or directory to analyze"
+    )
+    parser.add_argument(
+        "--recursive", "-r",
+        action="store_true",
+        default=True,
+        help="Recursively analyze directories (default: true)"
+    )
+    parser.add_argument(
+        "--language", "-l",
+        choices=list(LANGUAGE_EXTENSIONS.keys()),
+        help="Filter by programming language"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format"
+    )
+    parser.add_argument(
+        "--output", "-o",
+        help="Write output to file"
+    )
+
+    args = parser.parse_args()
+
+    target = Path(args.path).resolve()
+
+    if not target.exists():
+        print(f"Error: Path does not exist: {target}", file=sys.stderr)
+        sys.exit(1)
+
+    # Resolve the policy before any analysis runs, and write the merged thresholds back into
+    # THRESHOLDS so every check reads the resolved values where it already read the dict (IC-004).
+    policy, policy_tiers = load_policy(target)
+    THRESHOLDS.update(policy["thresholds"])
+
+    if target.is_file():
+        analysis = analyze_file(target)
+    else:
+        analysis = analyze_directory(target, args.recursive, args.language)
+
+    # IC-005: every report states the policy it applied, so a surprising finding is traceable to the
+    # tier that produced it rather than guessed at.
+    analysis["policy"] = {"tiers": policy_tiers, "thresholds": dict(policy["thresholds"])}
+
+    if args.json:
+        output = json.dumps(analysis, indent=2, default=str)
+        if args.output:
+            with open(args.output, "w") as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+    else:
+        print(f"Policy tiers applied: {' -> '.join(policy_tiers)}")
+        print_report(analysis)
+
+
+if __name__ == "__main__":
+    main()