phy-code-smell#

Static code smell detector — finds the 10 most damaging code quality anti-patterns across 5 languages with zero dependencies and zero configuration required.

Unlike linters (which check syntax rules), this tool detects structural problems: code that is syntactically valid but architecturally unsound, hard to test, and expensive to maintain.

What It Detects#

IDSmellSeverityWhy It HurtsCS001Long Function (>40 lines)HIGHImpossible to test in isolation; hides bugsCS002God Class (>20 methods or >400 lines)HIGHSingle Responsibility violated; breaks teams' mental modelsCS003Too Many Parameters (>5)MEDIUMForces callers to remember argument order; usually means missing objectCS004Deep Nesting (>4 levels)MEDIUMExponential cognitive load; extract early returnsCS005Magic Number/StringMEDIUMUnreadable and unmaintainable; replace with named constantCS006Duplicate Code Block (≥6 lines, ≥2 occurrences)HIGHChange in one copy never reaches the otherCS007TODO/FIXME/HACK Debt MarkerLOWDocuments intent to fix; tracks technical debtCS008Boolean Trap (≥2 bool params)MEDIUMrender(true, false, true) — no caller knows what these meanCS009Long Method Chain (>5 dots)LOWSingle-step debugging is impossible; violates Law of DemeterCS010Unreachable Code (after return/break)HIGHDead logic that misleads readers; suggests a refactoring gone wrong

Trigger Phrases#

text

/phy-code-smell
Review my codebase for code smells

text

/phy-code-smell
Find long functions and god classes in src/

text

/phy-code-smell
Code quality audit before the refactoring sprint

text

/phy-code-smell
Show me the worst-smelling files in this project

---

Implementation#

When invoked, run the following Python analysis. Accept --root (default .) and optional --min-severity flag.

python

#!/usr/bin/env python3
"""
phy-code-smell — Static code quality smell detector
Detects CS001–CS010 in Python, JS/TS, Java, Go, Ruby
Zero external dependencies.
"""
import os
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path
from typing import Optional
from collections import defaultdict

# ─────────────────────────────────────────────────────
# Configuration
# ─────────────────────────────────────────────────────

MAX_FUNCTION_LINES = int(os.environ.get('MAX_FN_LINES', '40'))
MAX_CLASS_METHODS = int(os.environ.get('MAX_CLASS_METHODS', '20'))
MAX_CLASS_LINES = int(os.environ.get('MAX_CLASS_LINES', '400'))
MAX_PARAMS = int(os.environ.get('MAX_PARAMS', '5'))
MAX_NESTING = int(os.environ.get('MAX_NESTING', '4'))
MIN_DUP_LINES = int(os.environ.get('MIN_DUP_LINES', '6'))
MAX_CHAIN_DOTS = int(os.environ.get('MAX_CHAIN_DOTS', '5'))

SKIP_DIRS = {
    '__pycache__', '.git', 'node_modules', 'vendor', '.venv', 'venv',
    'dist', 'build', '.next', 'coverage', 'migrations', 'generated',
    '__tests__', 'e2e', 'fixtures', 'mocks',
}

SEVERITY_ORDER = {'HIGH': 0, 'MEDIUM': 1, 'LOW': 2}
SEVERITY_EMOJI = {'HIGH': '🔴', 'MEDIUM': '🟡', 'LOW': '🔵'}

CI_MODE = '--ci' in sys.argv
MIN_SEVERITY = next(
    (sys.argv[sys.argv.index('--min-severity') + 1]
     for _ in ['x'] if '--min-severity' in sys.argv),
    'LOW'
)

# ─────────────────────────────────────────────────────
# Data model
# ─────────────────────────────────────────────────────

@dataclass
class SmellFinding:
    check_id: str
    file: str
    line: int
    severity: str
    element: str      # function/class/block name
    description: str
    suggestion: str
    metric: str = ''  # e.g. "47 lines", "8 params"

# ─────────────────────────────────────────────────────
# File walker
# ─────────────────────────────────────────────────────

LANG_EXTENSIONS = {
    'python': {'.py'},
    'javascript': {'.js', '.mjs', '.cjs', '.jsx'},
    'typescript': {'.ts', '.tsx'},
    'java': {'.java', '.kt'},
    'go': {'.go'},
    'ruby': {'.rb'},
}

ALL_EXTENSIONS = set().union(*LANG_EXTENSIONS.values())

def get_lang(path: Path) -> Optional[str]:
    ext = path.suffix.lower()
    for lang, exts in LANG_EXTENSIONS.items():
        if ext in exts:
            return lang
    return None

def walk_files(root: Path):
    """Yield (path, content, lang) for all source files."""
    for dirpath, dirnames, filenames in os.walk(root):
        dirnames[:] = [d for d in dirnames
                       if d not in SKIP_DIRS and not d.startswith('.')]
        for fname in filenames:
            fpath = Path(dirpath) / fname
            lang = get_lang(fpath)
            if not lang:
                continue
            # Skip test files
            name_lower = fpath.name.lower()
            if any(x in name_lower for x in ('test', 'spec', '_test', '.test.',
                                              '.spec.', 'mock', 'fixture')):
                continue
            try:
                content = fpath.read_text(errors='ignore')
                yield fpath, content, lang
            except Exception:
                continue

# ─────────────────────────────────────────────────────
# CS001 — Long Function
# ─────────────────────────────────────────────────────

# Each entry: (lang_pattern, regex_for_function_start)
FUNCTION_START_PATTERNS = {
    'python': re.compile(
        r'^(?P<indent> {0,16})def\s+(?P<name>\w+)\s*\(', re.MULTILINE
    ),
    'javascript': re.compile(
        r'^(?P<indent> {0,16})(?:async\s+)?function\s*\*?\s*(?P<name>\w+)\s*\(|'
        r'^(?P<indent2> {0,16})(?:const|let|var)\s+(?P<name2>\w+)\s*=\s*(?:async\s+)?\(',
        re.MULTILINE
    ),
    'typescript': re.compile(
        r'^(?P<indent> {0,16})(?:async\s+)?function\s*\*?\s*(?P<name>\w+)\s*\(|'
        r'^(?P<indent2> {0,16})(?:const|let|var)\s+(?P<name2>\w+)\s*=\s*(?:async\s+)?\(',
        re.MULTILINE
    ),
    'java': re.compile(
        r'^(?P<indent> {0,16})(?:public|protected|private|static|final|synchronized|\s)+'
        r'[\w<>\[\]]+\s+(?P<name>\w+)\s*\(',
        re.MULTILINE
    ),
    'go': re.compile(
        r'^func\s+(?:\(\w+\s+\*?\w+\)\s+)?(?P<name>\w+)\s*\(',
        re.MULTILINE
    ),
    'ruby': re.compile(
        r'^(?P<indent> {0,16})def\s+(?P<name>\w[\w?!]*)',
        re.MULTILINE
    ),
}

# End markers per language (indent-based for Python/Ruby, brace for others)
BRACE_LANGS = {'javascript', 'typescript', 'java', 'go'}

def find_function_end_brace(content: str, start_pos: int) -> int:
    """Find the closing brace of a function, returns line number of closing brace."""
    depth = 0
    i = start_pos
    found_open = False
    while i < len(content):
        c = content[i]
        if c == '{':
            depth += 1
            found_open = True
        elif c == '}':
            depth -= 1
            if found_open and depth == 0:
                return content[:i].count('\n') + 1
        i += 1
    return content.count('\n') + 1

def find_function_end_indent(lines: list[str], start_line: int, base_indent: int) -> int:
    """For Python/Ruby: find the last line of the function body by indentation."""
    end = start_line
    for i in range(start_line + 1, len(lines)):
        line = lines[i]
        stripped = line.lstrip()
        if not stripped or stripped.startswith('#'):
            continue
        indent = len(line) - len(stripped)
        if indent <= base_indent:
            return i - 1
        end = i
    return end

def check_long_functions(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []
    pattern = FUNCTION_START_PATTERNS.get(lang)
    if not pattern:
        return []

    lines = content.split('\n')

    for m in pattern.finditer(content):
        name = (m.group('name') or m.groupdict().get('name2') or
                m.groupdict().get('name') or '<anonymous>')
        if name in {'<anonymous>', 'if', 'for', 'while', 'switch'}:
            continue
        start_line = content[:m.start()].count('\n') + 1

        if lang in BRACE_LANGS:
            end_line = find_function_end_brace(content, m.start())
        else:
            indent_group = m.groupdict().get('indent', '')
            base_indent = len(indent_group) if indent_group else 0
            end_line = find_function_end_indent(lines, start_line - 1, base_indent)

        fn_lines = end_line - start_line + 1
        if fn_lines > MAX_FUNCTION_LINES:
            findings.append(SmellFinding(
                check_id='CS001',
                file=str(fpath),
                line=start_line,
                severity='HIGH',
                element=name,
                description=f'Function `{name}` is {fn_lines} lines long (max: {MAX_FUNCTION_LINES}).',
                suggestion=(
                    f'Extract sub-operations into helper functions. '
                    f'Aim for each function to do ONE thing: describe it in a single sentence. '
                    f'Look for "and" in the function name — it usually signals two functions.'
                ),
                metric=f'{fn_lines} lines',
            ))
    return findings

# ─────────────────────────────────────────────────────
# CS002 — God Class
# ─────────────────────────────────────────────────────

CLASS_START_PATTERNS = {
    'python': re.compile(r'^class\s+(?P<name>\w+)', re.MULTILINE),
    'javascript': re.compile(r'^class\s+(?P<name>\w+)', re.MULTILINE),
    'typescript': re.compile(r'^(?:export\s+)?(?:abstract\s+)?class\s+(?P<name>\w+)', re.MULTILINE),
    'java': re.compile(
        r'^(?:public\s+|protected\s+|private\s+|abstract\s+|final\s+)*class\s+(?P<name>\w+)',
        re.MULTILINE
    ),
    'ruby': re.compile(r'^class\s+(?P<name>\w+)', re.MULTILINE),
}

METHOD_COUNT_PATTERNS = {
    'python': re.compile(r'^\s+def\s+\w+', re.MULTILINE),
    'javascript': re.compile(r'^\s+(?:async\s+)?\w+\s*\(', re.MULTILINE),
    'typescript': re.compile(r'^\s+(?:(?:public|private|protected|static|async)\s+)*\w+\s*\(', re.MULTILINE),
    'java': re.compile(
        r'^\s+(?:public|protected|private|static|final|synchronized|\s)+'
        r'[\w<>\[\]]+\s+\w+\s*\(', re.MULTILINE
    ),
    'ruby': re.compile(r'^\s+def\s+\w+', re.MULTILINE),
}

def check_god_classes(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []
    pattern = CLASS_START_PATTERNS.get(lang)
    method_pattern = METHOD_COUNT_PATTERNS.get(lang)
    if not pattern or not method_pattern:
        return []

    lines = content.split('\n')

    for m in pattern.finditer(content):
        name = m.group('name')
        start_line = content[:m.start()].count('\n') + 1

        if lang in BRACE_LANGS:
            end_line = find_function_end_brace(content, m.start())
        else:
            end_line = find_function_end_indent(lines, start_line - 1, 0)

        class_body = '\n'.join(lines[start_line - 1:end_line])
        class_lines = end_line - start_line + 1
        method_count = len(method_pattern.findall(class_body))

        issues = []
        if method_count > MAX_CLASS_METHODS:
            issues.append(f'{method_count} methods (max: {MAX_CLASS_METHODS})')
        if class_lines > MAX_CLASS_LINES:
            issues.append(f'{class_lines} lines (max: {MAX_CLASS_LINES})')

        if issues:
            findings.append(SmellFinding(
                check_id='CS002',
                file=str(fpath),
                line=start_line,
                severity='HIGH',
                element=name,
                description=f'God class `{name}`: {", ".join(issues)}.',
                suggestion=(
                    f'Apply Single Responsibility Principle. '
                    f'Group methods by responsibility and extract into separate classes. '
                    f'Common splits: data (model), behavior (service), presentation (formatter).'
                ),
                metric=', '.join(issues),
            ))
    return findings

# ─────────────────────────────────────────────────────
# CS003 — Too Many Parameters
# ─────────────────────────────────────────────────────

def count_params(param_str: str) -> int:
    """Count parameters in a parameter string, handling nested generics/types."""
    if not param_str.strip():
        return 0
    depth = 0
    count = 1
    for c in param_str:
        if c in '(<{[':
            depth += 1
        elif c in ')>}]':
            depth -= 1
        elif c == ',' and depth == 0:
            count += 1
    return count

PARAM_LIST_PATTERNS = {
    'python': re.compile(
        r'^\s*def\s+(?P<name>\w+)\s*\((?P<params>[^)]*)\)',
        re.MULTILINE
    ),
    'javascript': re.compile(
        r'(?:function\s+(?P<name>\w+)|(?P<name2>\w+)\s*=\s*(?:async\s+)?function)\s*\((?P<params>[^)]*)\)',
    ),
    'typescript': re.compile(
        r'(?:function\s+(?P<name>\w+)|(?P<name2>\w+)\s*=\s*(?:async\s+)?function)\s*\((?P<params>[^)]*)\)',
    ),
    'java': re.compile(
        r'(?:public|protected|private|static)\s+\S+\s+(?P<name>\w+)\s*\((?P<params>[^)]*)\)',
    ),
    'go': re.compile(
        r'func\s+(?:\(\w+\s+\*?\w+\)\s+)?(?P<name>\w+)\s*\((?P<params>[^)]*)\)',
    ),
    'ruby': re.compile(
        r'^\s*def\s+(?P<name>\w[\w?!]*)\s*\((?P<params>[^)]*)\)',
        re.MULTILINE
    ),
}

# Skip these Python special params
SKIP_PYTHON_PARAMS = {'self', 'cls', '*args', '**kwargs', '*', '/'}

def check_too_many_params(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []
    pattern = PARAM_LIST_PATTERNS.get(lang)
    if not pattern:
        return []

    for m in pattern.finditer(content):
        name = (m.groupdict().get('name') or m.groupdict().get('name2') or
                m.groupdict().get('name3') or '<func>')
        params_raw = m.groupdict().get('params', '') or ''
        if not params_raw.strip():
            continue

        # Normalize params
        if lang == 'python':
            params = [p.strip().split(':')[0].split('=')[0].strip()
                      for p in params_raw.split(',')]
            params = [p for p in params if p and p not in SKIP_PYTHON_PARAMS]
        else:
            params = [p.strip() for p in params_raw.split(',') if p.strip()]

        n = len(params)
        if n > MAX_PARAMS:
            line_no = content[:m.start()].count('\n') + 1
            findings.append(SmellFinding(
                check_id='CS003',
                file=str(fpath),
                line=line_no,
                severity='MEDIUM',
                element=name,
                description=f'Function `{name}` has {n} parameters (max: {MAX_PARAMS}).',
                suggestion=(
                    f'Group related parameters into a config object/dataclass. '
                    f'Example: replace (host, port, timeout, retries, ssl) with ConnectionConfig. '
                    f'Parameters that always travel together are a data clump.'
                ),
                metric=f'{n} params',
            ))
    return findings

# ─────────────────────────────────────────────────────
# CS004 — Deep Nesting
# ─────────────────────────────────────────────────────

# Indent-based for Python/Ruby; brace-count for others
NESTING_TRIGGERS = {
    'python': re.compile(r'^\s*(?:if|elif|else|for|while|with|try|except|finally)\b'),
    'javascript': re.compile(r'(?:if|else\s+if|for|while|switch|try|catch)\s*[\({]'),
    'typescript': re.compile(r'(?:if|else\s+if|for|while|switch|try|catch)\s*[\({]'),
    'java': re.compile(r'(?:if|else\s+if|for|while|switch|try|catch)\s*[\({]'),
    'go': re.compile(r'(?:if|else\s+if|for|switch|select)\s+'),
    'ruby': re.compile(r'^\s*(?:if|elsif|else|unless|while|until|for|begin|rescue|case)\b'),
}

def check_deep_nesting(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []
    lines = content.split('\n')

    if lang in ('python', 'ruby'):
        # Count nesting by indentation level (4 spaces = 1 level)
        for i, line in enumerate(lines):
            stripped = line.lstrip()
            if not stripped or stripped.startswith('#'):
                continue
            indent = len(line) - len(stripped)
            nesting = indent // 4
            if nesting > MAX_NESTING:
                findings.append(SmellFinding(
                    check_id='CS004',
                    file=str(fpath),
                    line=i + 1,
                    severity='MEDIUM',
                    element=stripped[:60],
                    description=f'Code nested {nesting} levels deep (max: {MAX_NESTING}).',
                    suggestion=(
                        'Invert conditions to return early. '
                        'Replace nested ifs with guard clauses: '
                        'if not condition: return. '
                        'Extract nested blocks into helper functions.'
                    ),
                    metric=f'{nesting} levels',
                ))
    else:
        # Brace-based nesting depth
        trigger = NESTING_TRIGGERS.get(lang)
        depth = 0
        for i, line in enumerate(lines):
            depth += line.count('{') - line.count('}')
            if depth > MAX_NESTING and trigger and trigger.search(line):
                stripped = line.strip()
                findings.append(SmellFinding(
                    check_id='CS004',
                    file=str(fpath),
                    line=i + 1,
                    severity='MEDIUM',
                    element=stripped[:60],
                    description=f'Control flow nested {depth} levels deep (max: {MAX_NESTING}).',
                    suggestion=(
                        'Extract inner blocks into named functions. '
                        'Use early returns to reduce nesting. '
                        'Consider guard clauses: validate inputs first, then process.'
                    ),
                    metric=f'{depth} levels',
                ))

    # Deduplicate consecutive lines — keep only highest nesting line per 5-line window
    deduped = []
    last_line = -10
    for f in sorted(findings, key=lambda x: x.line):
        if f.line - last_line >= 5:
            deduped.append(f)
            last_line = f.line
    return deduped

# ─────────────────────────────────────────────────────
# CS005 — Magic Numbers and Strings
# ─────────────────────────────────────────────────────

# Numbers that are almost always intentional and not "magic"
SAFE_NUMBERS = {
    '0', '1', '2', '-1', '0.0', '1.0', '0.5', '100', '1000',
    '1024', '65536', '3.14', '3.14159', '2.718', '60', '24', '7',
    '12', '365', '3600', '86400',
}

MAGIC_NUMBER_RE = re.compile(
    r'(?<![.\w])(-?\d+\.?\d*(?:[eE][+-]?\d+)?)(?![.\w])'
)

# Magic string: non-empty string literal of length ≥ 5 that isn't in common patterns
MAGIC_STRING_RE = re.compile(
    r"""(?<!\\)(?:["'])([^"'\\]{8,})(?:["'])"""
)

SAFE_STRING_PATTERNS = re.compile(
    r"""(?:https?://|//|#|SELECT|INSERT|UPDATE|DELETE|FROM|WHERE|
    Content-Type|application/|charset=|text/|multipart/|
    %s|%d|{|}|\{\w+\}|\\n|\\t|
    __.*__|->|=>|error:|warning:|info:|debug:)""",
    re.IGNORECASE | re.VERBOSE
)

def check_magic_literals(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []
    lines = content.split('\n')

    for i, line in enumerate(lines):
        stripped = line.strip()
        # Skip comments, imports, constant definitions, test assertions
        if stripped.startswith(('//','#','*','import','from','require','const '
                                 'MAX','MIN','DEFAULT','CONFIG','TIMEOUT')):
            continue
        if any(x in stripped for x in ('assert', 'expect(', 'toBe(', 'assertEqual',
                                         '== True', '== False', 'const ', 'final ')):
            continue
        # Skip line if it looks like a constant definition
        if re.match(r'\s*(?:const|let|final|val|var)\s+[A-Z_]+\s*[=:]', line):
            continue

        # Magic numbers
        for m in MAGIC_NUMBER_RE.finditer(stripped):
            num = m.group(1)
            if num in SAFE_NUMBERS:
                continue
            # Skip array indices, loop counters, simple math in assignments
            ctx = stripped[max(0, m.start()-10):m.end()+10]
            if re.search(r'\[\s*' + re.escape(num) + r'\s*\]', ctx):
                continue

            findings.append(SmellFinding(
                check_id='CS005',
                file=str(fpath),
                line=i + 1,
                severity='MEDIUM',
                element=f'literal {num}',
                description=f'Magic number `{num}` — meaning unclear without context.',
                suggestion=f'Extract to a named constant: MAX_RETRIES = {num} or TIMEOUT_SECONDS = {num}',
                metric=f'literal {num}',
            ))
            break  # One finding per line for magic numbers

        # Magic strings (only flag once per line)
        for m in MAGIC_STRING_RE.finditer(stripped):
            s = m.group(1)
            if SAFE_STRING_PATTERNS.search(s):
                continue
            if len(s) < 8:
                continue
            # Skip paths, log messages, format strings
            if '/' in s or '%' in s or '{' in s:
                continue

            findings.append(SmellFinding(
                check_id='CS005',
                file=str(fpath),
                line=i + 1,
                severity='MEDIUM',
                element=f'"{s[:30]}"',
                description=f'Magic string `"{s[:30]}"` — should be a named constant.',
                suggestion='Move to a constants file or configuration. Makes typos catchable at compile time.',
                metric=f'string len={len(s)}',
            ))
            break  # One per line

    return findings

# ─────────────────────────────────────────────────────
# CS006 — Duplicate Code Blocks
# ─────────────────────────────────────────────────────

def _normalize_line(line: str) -> str:
    """Normalize a line for duplication comparison (strip whitespace, remove literals)."""
    line = line.strip()
    line = re.sub(r'"[^"]*"', '"STR"', line)
    line = re.sub(r"'[^']*'", '"STR"', line)
    line = re.sub(r'\b\d+\b', 'NUM', line)
    return line

def check_duplicate_blocks(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []
    lines = content.split('\n')
    normalized = [_normalize_line(l) for l in lines]

    # Build n-gram fingerprints
    n = MIN_DUP_LINES
    seen_blocks: dict[tuple, int] = {}  # fingerprint → first line number

    for i in range(len(normalized) - n + 1):
        block = tuple(normalized[i:i + n])
        # Skip blocks that are mostly blank/comments
        non_empty = sum(1 for l in block if l.strip() and not l.strip().startswith(('//','#','*')))
        if non_empty < n // 2:
            continue

        if block in seen_blocks:
            first_line = seen_blocks[block]
            findings.append(SmellFinding(
                check_id='CS006',
                file=str(fpath),
                line=i + 1,
                severity='HIGH',
                element=f'block at line {first_line}',
                description=(
                    f'Duplicate code block ({n} lines) — '
                    f'identical structure first seen at line {first_line}.'
                ),
                suggestion=(
                    f'Extract duplicated logic into a shared function. '
                    f'Even 3 occurrences of the same logic costs 3× the maintenance. '
                    f'Rule of Three: once = ok, twice = watch, thrice = extract.'
                ),
                metric=f'{n} duplicate lines',
            ))
        else:
            seen_blocks[block] = i + 1

    # Deduplicate findings for closely adjacent lines
    deduped = []
    last_line = -100
    for f in sorted(findings, key=lambda x: x.line):
        if f.line - last_line >= n:
            deduped.append(f)
            last_line = f.line
    return deduped

# ─────────────────────────────────────────────────────
# CS007 — TODO/FIXME/HACK Debt Markers
# ─────────────────────────────────────────────────────

DEBT_MARKER_RE = re.compile(
    r'(?://|#|<!--)\s*(?P<marker>TODO|FIXME|HACK|XXX|BUG|TEMP|KLUDGE)\b(?P<rest>[^\n]*)',
    re.IGNORECASE
)

def check_debt_markers(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []
    for m in DEBT_MARKER_RE.finditer(content):
        marker = m.group('marker').upper()
        rest = m.group('rest').strip()[:80]
        line_no = content[:m.start()].count('\n') + 1

        severity = 'HIGH' if marker in ('FIXME', 'BUG', 'HACK') else 'LOW'
        findings.append(SmellFinding(
            check_id='CS007',
            file=str(fpath),
            line=line_no,
            severity=severity,
            element=f'{marker}',
            description=f'{marker}: {rest}' if rest else f'{marker} marker with no description.',
            suggestion=(
                f'File a GitHub issue and link it: {marker}(#123). '
                f'Track debt in your issue tracker — not in code comments. '
                f'Use git-blame to see how old this is.'
            ),
            metric=marker,
        ))
    return findings

# ─────────────────────────────────────────────────────
# CS008 — Boolean Trap
# ─────────────────────────────────────────────────────

BOOL_PARAM_RE = re.compile(
    r'def\s+(?P<name>\w+)\s*\((?P<params>[^)]+)\)',
    re.IGNORECASE
)

BOOL_TYPE_RE = re.compile(r'\bbool(?:ean)?\b', re.IGNORECASE)
BOOL_DEFAULT_RE = re.compile(r'=\s*(?:True|False|true|false)\b')

def check_boolean_trap(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []

    # Pattern for function definitions with typed bool params
    for m in re.finditer(
        r'(?:def|function|func)\s+(?P<name>\w+)\s*\((?P<params>[^)]{1,300})\)',
        content, re.IGNORECASE
    ):
        name = m.group('name')
        params_raw = m.group('params')

        bool_params = []
        for param in params_raw.split(','):
            param = param.strip()
            if (BOOL_TYPE_RE.search(param) or
                    BOOL_DEFAULT_RE.search(param) or
                    re.search(r'\b(?:is_|has_|can_|should_|enable|disable|verbose|debug|force|dry_run)\w*\s*:', param)):
                bool_params.append(param.split(':')[0].split('=')[0].strip())

        if len(bool_params) >= 2:
            line_no = content[:m.start()].count('\n') + 1
            findings.append(SmellFinding(
                check_id='CS008',
                file=str(fpath),
                line=line_no,
                severity='MEDIUM',
                element=name,
                description=(
                    f'Function `{name}` has {len(bool_params)} boolean parameters '
                    f'({", ".join(bool_params[:3])}). '
                    f'Callers write `{name}(user, true, false)` — impossible to understand without the signature.'
                ),
                suggestion=(
                    f'Replace multiple bool params with an options object/enum: '
                    f'`{name}(user, mode=Mode.VERBOSE)` instead of `{name}(user, verbose=True, debug=False)`. '
                    f'Or split into separate functions: `{name}_verbose()`, `{name}_quiet()`.'
                ),
                metric=f'{len(bool_params)} bool params',
            ))
    return findings

# ─────────────────────────────────────────────────────
# CS009 — Long Method Chain
# ─────────────────────────────────────────────────────

METHOD_CHAIN_RE = re.compile(
    r'(\w+(?:\([^()]*\))?\s*(?:\.\s*\w+(?:\([^()]*\))?){' +
    str(MAX_CHAIN_DOTS) + r',})'
)

def check_long_chains(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    if lang not in ('javascript', 'typescript', 'java', 'ruby'):
        return []

    findings = []
    lines = content.split('\n')

    for i, line in enumerate(lines):
        stripped = line.strip()
        if stripped.startswith(('//','#','*')):
            continue
        dot_count = stripped.count('.')
        if dot_count < MAX_CHAIN_DOTS:
            continue

        m = METHOD_CHAIN_RE.search(stripped)
        if m:
            chain = m.group(1)
            chain_dots = chain.count('.')
            findings.append(SmellFinding(
                check_id='CS009',
                file=str(fpath),
                line=i + 1,
                severity='LOW',
                element=chain[:60],
                description=f'Method chain {chain_dots} calls deep — impossible to debug one step at a time.',
                suggestion=(
                    'Break the chain into named intermediate variables: '
                    'const filtered = users.filter(active); '
                    'const sorted = filtered.sort(byDate); '
                    'const names = sorted.map(getName);'
                ),
                metric=f'{chain_dots} chained calls',
            ))
    return findings

# ─────────────────────────────────────────────────────
# CS010 — Unreachable Code
# ─────────────────────────────────────────────────────

RETURN_BREAK_RE = {
    'python': re.compile(r'^\s+(return|raise|break|continue)\b'),
    'javascript': re.compile(r'^\s+(return|throw|break|continue)\b'),
    'typescript': re.compile(r'^\s+(return|throw|break|continue)\b'),
    'java': re.compile(r'^\s+(return|throw|break|continue)\b'),
    'go': re.compile(r'^\s+(return|panic\()\b'),
    'ruby': re.compile(r'^\s+(return|raise|next|break)\b'),
}

def check_unreachable_code(fpath: Path, content: str, lang: str) -> list[SmellFinding]:
    findings = []
    pattern = RETURN_BREAK_RE.get(lang)
    if not pattern:
        return []

    lines = content.split('\n')

    for i, line in enumerate(lines[:-1]):
        if not pattern.match(line):
            continue
        # Get indentation of the return/break line
        return_indent = len(line) - len(line.lstrip())
        # Look at the next non-blank line
        for j in range(i + 1, min(i + 4, len(lines))):
            next_line = lines[j]
            if not next_line.strip() or next_line.strip().startswith(('//','#','}')):
                continue
            next_indent = len(next_line) - len(next_line.lstrip())
            if next_indent == return_indent:
                # Same indentation — code after a terminal statement
                findings.append(SmellFinding(
                    check_id='CS010',
                    file=str(fpath),
                    line=j + 1,
                    severity='HIGH',
                    element=next_line.strip()[:60],
                    description=f'Unreachable code after `{line.strip()[:40]}`.',
                    suggestion=(
                        'Delete the unreachable code or move the terminal statement. '
                        'This often indicates a refactoring that was partially completed. '
                        'Use git blame to understand the intent.'
                    ),
                    metric='unreachable',
                ))
            break

    return findings

# ─────────────────────────────────────────────────────
# File-level summary
# ─────────────────────────────────────────────────────

@dataclass
class FileReport:
    path: str
    findings: list[SmellFinding] = field(default_factory=list)

    @property
    def smell_score(self) -> int:
        score = 0
        for f in self.findings:
            score += {'HIGH': 3, 'MEDIUM': 2, 'LOW': 1}.get(f.severity, 0)
        return score

# ─────────────────────────────────────────────────────
# Main runner
# ─────────────────────────────────────────────────────

CHECKS = [
    check_long_functions,
    check_god_classes,
    check_too_many_params,
    check_deep_nesting,
    check_magic_literals,
    check_duplicate_blocks,
    check_debt_markers,
    check_boolean_trap,
    check_long_chains,
    check_unreachable_code,
]

def run_audit(root: Path) -> int:
    print(f"\n🔍  phy-code-smell — scanning {root}\n{'─'*60}")

    all_findings: list[SmellFinding] = []
    file_reports: dict[str, FileReport] = {}

    severity_threshold = SEVERITY_ORDER.get(MIN_SEVERITY, 2)

    for fpath, content, lang in walk_files(root):
        file_findings: list[SmellFinding] = []
        for check in CHECKS:
            try:
                results = check(fpath, content, lang)
                file_findings.extend(results)
            except Exception:
                pass

        # Filter by severity
        file_findings = [f for f in file_findings
                         if SEVERITY_ORDER.get(f.severity, 2) <= severity_threshold]

        if file_findings:
            rel = str(fpath.relative_to(root) if root != Path('.') else fpath)
            file_reports[rel] = FileReport(path=rel, findings=file_findings)
            all_findings.extend(file_findings)

    if not all_findings:
        print("✅  No code smells found.")
        return 0

    # Sort findings by severity
    all_findings.sort(key=lambda f: (SEVERITY_ORDER.get(f.severity, 2), f.file, f.line))

    high = sum(1 for f in all_findings if f.severity == 'HIGH')
    med = sum(1 for f in all_findings if f.severity == 'MEDIUM')
    low = sum(1 for f in all_findings if f.severity == 'LOW')

    print(f"Found {len(all_findings)} smell(s) in {len(file_reports)} file(s): "
          f"🔴 HIGH={high}  🟡 MEDIUM={med}  🔵 LOW={low}")

    # Top 5 smelliest files
    sorted_files = sorted(file_reports.values(), key=lambda r: r.smell_score, reverse=True)
    print(f"\n📊 Smelliest files (by score):")
    for fr in sorted_files[:5]:
        print(f"  {fr.smell_score:3d} pts  {fr.path}  ({len(fr.findings)} findings)")

    # Findings grouped by severity
    current_severity = None
    for f in all_findings:
        if f.severity != current_severity:
            current_severity = f.severity
            emoji = SEVERITY_EMOJI.get(f.severity, '⚪')
            print(f"\n{emoji} {f.severity} — {f.check_id}\n{'─'*50}")

        print(f"\n[{f.check_id}] {f.file}:{f.line}  {f.metric}")
        print(f"  {f.description}")
        print(f"  → {f.suggestion}")

    # Summary by smell type
    print(f"\n{'═'*60}")
    smell_counts: dict[str, int] = defaultdict(int)
    for f in all_findings:
        smell_counts[f.check_id] += 1
    print("Smell breakdown:")
    for check_id, count in sorted(smell_counts.items(), key=lambda x: -x[1]):
        print(f"  {check_id}: {count}")

    print(f"\nCI fail-gate (fails on HIGH findings):")
    print(f"  python code_smell.py --root . --ci --min-severity HIGH")

    if CI_MODE and high > 0:
        print(f"\n[CI] Exit 1 — {high} HIGH severity smells found.")
        return 1
    return 0

if __name__ == '__main__':
    import argparse

    parser = argparse.ArgumentParser(description='Static code smell detector')
    parser.add_argument('--root', default='.', help='Root directory to scan')
    parser.add_argument('--ci', action='store_true', help='Exit 1 on HIGH severity smells')
    parser.add_argument('--min-severity', choices=['HIGH', 'MEDIUM', 'LOW'],
                        default='LOW', help='Minimum severity to report')
    parser.add_argument('--max-fn-lines', type=int, default=40)
    parser.add_argument('--max-params', type=int, default=5)
    parser.add_argument('--max-nesting', type=int, default=4)
    args = parser.parse_args()

    MAX_FUNCTION_LINES = args.max_fn_lines
    MAX_PARAMS = args.max_params
    MAX_NESTING = args.max_nesting
    CI_MODE = args.ci
    MIN_SEVERITY = args.min_severity

    sys.exit(run_audit(Path(args.root)))

---

Example Output#

text

🔍  phy-code-smell — scanning /home/user/myproject
────────────────────────────────────────────────────────────
Found 12 smell(s) in 4 file(s): 🔴 HIGH=5  🟡 MEDIUM=5  🔵 LOW=2

📊 Smelliest files (by score):
  18 pts  src/services/UserService.py  (6 findings)
   9 pts  src/api/handlers.py  (3 findings)
   5 pts  src/utils/formatters.ts  (2 findings)
   3 pts  src/models/order.rb  (1 finding)

🔴 HIGH — CS001
──────────────────────────────────────────────────────

[CS001] src/services/UserService.py:47  72 lines
  Function `create_user_with_notifications` is 72 lines long (max: 40).
  → Extract sub-operations into helper functions. Aim for each function to
    do ONE thing: describe it in a single sentence. Look for "and" in the
    function name — it usually signals two functions.

[CS002] src/services/UserService.py:12  24 methods, 487 lines
  God class `UserService`: 24 methods (max: 20), 487 lines (max: 400).
  → Apply Single Responsibility Principle. Common splits: data (model),
    behavior (service), presentation (formatter).

🟡 MEDIUM — CS003
──────────────────────────────────────────────────────

[CS003] src/api/handlers.py:89  8 params
  Function `handle_payment` has 8 parameters (max: 5).
  → Group related parameters into a config object: replace
    (host, port, timeout, retries, ssl) with ConnectionConfig.

[CS005] src/api/handlers.py:134  literal 86400
  Magic number `86400` — meaning unclear without context.
  → Extract to a named constant: SECONDS_PER_DAY = 86400

════════════════════════════════════════════════════════════
Smell breakdown:
  CS001: 3
  CS003: 3
  CS007: 2
  CS005: 2
  CS002: 1
  CS010: 1

CI fail-gate (fails on HIGH findings):
  python code_smell.py --root . --ci --min-severity HIGH

---

Configuration via Environment Variables#

bash

# All thresholds are configurable
export MAX_FN_LINES=50      # default: 40
export MAX_CLASS_METHODS=25  # default: 20
export MAX_CLASS_LINES=500   # default: 400
export MAX_PARAMS=4          # default: 5
export MAX_NESTING=3         # default: 4
export MIN_DUP_LINES=8       # default: 6

python code_smell.py --root src/

Or via CLI flags:

bash

python code_smell.py --root . --max-fn-lines 60 --max-params 6 --min-severity HIGH

---

Relationship to Other phy- Skills#

SkillWhat It Checksphy-code-smell (this)Structural quality — functions, classes, complexityphy-ts-any-auditorTypeScript any type sprawlphy-regex-auditReDoS vulnerabilities in regex patternsphy-flag-janitorDead feature flagsphy-concurrency-auditRace conditions and TOCTOU bugsphy-dead-codeUnused CSS selectors

phy-code-smell is the language-agnostic structural audit layer. The others are targeted deep-dives into specific problem domains.

---

Supported Languages#

LanguageCS001CS002CS003CS004CS005CS006CS007CS008CS009CS010Python✓✓✓✓✓✓✓✓—✓JavaScript✓✓✓✓✓✓✓✓✓✓TypeScript✓✓✓✓✓✓✓✓✓✓Java / Kotlin✓✓✓✓✓✓✓✓✓✓Go✓—✓✓✓✓✓✓—✓Ruby✓✓✓✓✓✓✓—✓✓

---

Author#

Canlah AI — Run performance marketing without breaking your brand.

• GitHub: github.com/PHY041
• All Skills: clawhub.ai/PHY041