@paulduvall/claude-dev-toolkit 0.0.1-alpha.19 → 0.0.1-alpha.21

package/hooks/smell_python.py

@@ -0,0 +1,110 @@
+"""Python AST-based code smell checks.
+
+Detects: cyclomatic complexity, long functions, deep nesting,
+and too-many-parameters in Python source files.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from smell_types import (
+    MAX_COMPLEXITY,
+    MAX_FUNCTION_LINES,
+    MAX_NESTING_DEPTH,
+    MAX_PARAMETERS,
+    Smell,
+    apply_threshold_checks,
+)
+
+_NESTING_TYPES: tuple[type, ...] = (
+    ast.If, ast.For, ast.AsyncFor, ast.While,
+    ast.Try, ast.With, ast.AsyncWith,
+)
+if hasattr(ast, "Match"):
+    _NESTING_TYPES = (*_NESTING_TYPES, ast.Match)
+if hasattr(ast, "TryStar"):
+    _NESTING_TYPES = (*_NESTING_TYPES, ast.TryStar)
+
+_CC_DECISION_TYPES: dict[type, str] = {
+    ast.If: "single", ast.IfExp: "single",
+    ast.For: "single", ast.AsyncFor: "single", ast.While: "single",
+    ast.ExceptHandler: "single",
+    ast.With: "single", ast.AsyncWith: "single",
+    ast.Assert: "single",
+    ast.BoolOp: "boolop",
+}
+
+
+def _py_nesting_depth(node: ast.AST) -> int:
+    """Return the maximum nesting depth within *node*."""
+    max_depth = 0
+
+    def _visit(current: ast.AST, depth: int) -> None:
+        nonlocal max_depth
+        max_depth = max(max_depth, depth)
+        for child in ast.iter_child_nodes(current):
+            inc = 1 if isinstance(child, _NESTING_TYPES) else 0
+            _visit(child, depth + inc)
+
+    _visit(node, 0)
+    return max_depth
+
+
+def _py_func_lines(node: ast.AST) -> int:
+    """Return line span of a function node."""
+    start = getattr(node, "lineno", None)
+    end = getattr(node, "end_lineno", None)
+    if isinstance(start, int) and isinstance(end, int):
+        return end - start + 1
+    return 0
+
+
+def _py_param_count(node: ast.FunctionDef) -> int:
+    """Count user-facing parameters (excludes self/cls)."""
+    args = node.args
+    count = len(args.args) + len(args.posonlyargs) + len(args.kwonlyargs)
+    if args.vararg:
+        count += 1
+    if args.kwarg:
+        count += 1
+    if args.args and args.args[0].arg in ("self", "cls"):
+        count -= 1
+    return count
+
+
+def _py_complexity(node: ast.AST) -> int:
+    """Calculate cyclomatic complexity for a Python function."""
+    cc = 1
+    for child in ast.walk(node):
+        kind = _CC_DECISION_TYPES.get(type(child))
+        if kind == "single":
+            cc += 1
+        elif kind == "boolop":
+            cc += len(child.values) - 1
+    return cc
+
+
+def _check_py_func(node: ast.AST) -> list[Smell]:
+    """Check a single Python function for all smells."""
+    name: str = getattr(node, "name", "<unknown>")
+    line: int = getattr(node, "lineno", 0)
+    return apply_threshold_checks(name, line, [
+        ("complexity", _py_complexity(node), MAX_COMPLEXITY),
+        ("long_function", _py_func_lines(node), MAX_FUNCTION_LINES),
+        ("deep_nesting", _py_nesting_depth(node), MAX_NESTING_DEPTH),
+        ("too_many_params", _py_param_count(node), MAX_PARAMETERS),
+    ])
+
+
+def check_python(file_path: str, source: str) -> list[Smell]:
+    """Run all AST-based smell checks on a Python file."""
+    try:
+        tree = ast.parse(source, filename=file_path)
+    except SyntaxError:
+        return []
+    smells: list[Smell] = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            smells.extend(_check_py_func(node))
+    return smells

package/hooks/smell_ruff.py

@@ -0,0 +1,70 @@
+"""Ruff lint + format integration for code smell hooks.
+
+Auto-fixes fixable issues (unused imports, formatting), then reports
+any remaining unfixable violations as blocking smells.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+from smell_types import Smell
+
+RUFF_EXTS = frozenset((".py",))
+
+
+def _ruff_cmd(project_root: str | None = None) -> list[str] | None:
+    """Return command prefix for ruff, or None if unavailable."""
+    if shutil.which("ruff"):
+        return ["ruff"]
+    if project_root:
+        venv_ruff = os.path.join(project_root, ".venv", "bin", "ruff")
+        if os.path.isfile(venv_ruff):
+            return [venv_ruff]
+    return None
+
+
+def _run_ruff_cmd(cmd: list[str], cwd: str | None = None) -> tuple[int, str]:
+    """Run a ruff command in the given directory."""
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=30, cwd=cwd,
+        )
+        return result.returncode, (result.stdout + result.stderr).strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return 0, ""
+
+
+def _parse_ruff_output(output: str) -> list[Smell]:
+    """Convert remaining ruff output lines into Smell objects."""
+    return [
+        Smell("ruff_lint", "<ruff>", 0, line.strip(),
+              "Fix the ruff lint violation manually.")
+        for line in output.splitlines()
+        if line.strip() and not line.strip().startswith("Found ")
+    ]
+
+
+def _find_project_root(file_path: str) -> str | None:
+    """Walk up from file_path to find a pyproject.toml directory."""
+    directory = os.path.dirname(os.path.abspath(file_path))
+    while directory != os.path.dirname(directory):
+        if os.path.isfile(os.path.join(directory, "pyproject.toml")):
+            return directory
+        directory = os.path.dirname(directory)
+    return None
+
+
+def check_ruff(file_path: str) -> list[Smell]:
+    """Auto-fix with ruff, then report any remaining unfixable issues."""
+    cwd = _find_project_root(file_path)
+    prefix = _ruff_cmd(cwd)
+    if not prefix:
+        return []
+    _run_ruff_cmd(prefix + ["check", "--fix", "--quiet", file_path], cwd)
+    _run_ruff_cmd(prefix + ["format", "--quiet", file_path], cwd)
+    check_cmd = prefix + ["check", "--output-format", "concise", file_path]
+    code, out = _run_ruff_cmd(check_cmd, cwd)
+    return _parse_ruff_output(out) if code != 0 else []

package/hooks/smell_types.py

@@ -0,0 +1,72 @@
+"""Shared types, thresholds, and helpers for code smell detection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# ---------------------------------------------------------------------------
+# Thresholds
+# ---------------------------------------------------------------------------
+MAX_COMPLEXITY = 10
+MAX_FUNCTION_LINES = 20
+MAX_NESTING_DEPTH = 3
+MAX_PARAMETERS = 4
+MAX_FILE_LINES = 300
+DUPLICATE_MIN_LINES = 4
+DUPLICATE_MIN_OCCURRENCES = 2
+
+FIXES = {
+    "complexity": "Use extract-method, early returns, guard clauses, or lookup tables.",
+    "long_function": "Extract helper functions for distinct logical steps.",
+    "deep_nesting": "Use guard clauses and early returns to flatten control flow.",
+    "too_many_params": "Group related parameters into a dataclass or options object.",
+    "duplicate_block": "Extract repeated code into a shared helper function.",
+    "long_file": "Split into smaller modules with clear single responsibilities.",
+    "secrets": "Move secrets to environment variables or a secrets manager.",
+    "B101": "Remove assert from non-test code; use proper validation instead.",
+    "B102": "Replace exec/eval with safer alternatives.",
+    "B105": "Move hardcoded passwords to environment variables.",
+    "B106": "Move hardcoded passwords to environment variables.",
+    "B110": "Handle exceptions explicitly instead of using bare except-pass.",
+    "B301": "Avoid pickle for untrusted data; use json or safer serialization.",
+    "B602": "Avoid shell=True; pass command as a list to subprocess.",
+    "trojan_bidi": "Remove Unicode bidi override characters that can disguise code.",
+    "trojan_zero_width": "Remove zero-width Unicode characters that hide content.",
+    "ruff_lint": "Fix the ruff lint violation manually.",
+}
+
+
+@dataclass(frozen=True)
+class Smell:
+    """A single code-smell violation."""
+
+    kind: str
+    name: str
+    line: int
+    detail: str
+    fix: str
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+_DETAIL_TEMPLATES = {
+    "complexity": ("complexity={value} (max {max})", MAX_COMPLEXITY),
+    "long_function": ("{value} lines (max {max})", MAX_FUNCTION_LINES),
+    "deep_nesting": ("nesting depth {value} (max {max})", MAX_NESTING_DEPTH),
+    "too_many_params": ("{value} params (max {max})", MAX_PARAMETERS),
+}
+
+
+def make_smell(kind: str, name: str, line: int, value: int) -> Smell:
+    """Create a Smell with a formatted detail string."""
+    tpl, mx = _DETAIL_TEMPLATES[kind]
+    return Smell(kind, name, line, tpl.format(value=value, max=mx), FIXES[kind])
+
+
+def apply_threshold_checks(
+    name: str, line: int, checks: list[tuple[str, int, int]],
+) -> list[Smell]:
+    """Return Smell for each (kind, value, threshold) where value > threshold."""
+    return [make_smell(k, name, line, v) for k, v, t in checks if v > t]

package/hooks/suppression.py

@@ -0,0 +1,82 @@
+"""Inline suppression parser for code smell and security hooks.
+
+Supports per-line suppression comments:
+  # smell: ignore[complexity,long_function]
+  # security: ignore[secrets,B101]
+
+Applies to the same line or the line immediately following the comment.
+No wildcards supported -- explicit check names required.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+from smell_types import Smell
+
+_SUPPRESS_RE = re.compile(
+    r"#\s*(?P<ns>smell|security):\s*ignore\[(?P<names>[^\]]+)\]"
+)
+_MAX_SUPPRESSIONS_PER_FILE = 5
+
+
+def _parse_suppression(line: str) -> dict[str, set[str]]:
+    """Parse suppression directives from a single line.
+
+    Returns:
+        Dict mapping namespace to set of suppressed check names.
+    """
+    result: dict[str, set[str]] = {}
+    for match in _SUPPRESS_RE.finditer(line):
+        ns = match.group("ns")
+        names = {n.strip() for n in match.group("names").split(",")}
+        result.setdefault(ns, set()).update(names)
+    return result
+
+
+def _build_suppression_map(lines: list[str]) -> dict[int, dict[str, set[str]]]:
+    """Build a map of line numbers to their active suppressions.
+
+    A suppression on line N applies to line N and line N+1.
+    """
+    suppression_map: dict[int, dict[str, set[str]]] = {}
+    for lineno, line in enumerate(lines, start=1):
+        parsed = _parse_suppression(line)
+        if not parsed:
+            continue
+        for target_line in (lineno, lineno + 1):
+            existing = suppression_map.setdefault(target_line, {})
+            for ns, names in parsed.items():
+                existing.setdefault(ns, set()).update(names)
+    return suppression_map
+
+
+def _is_suppressed(smell: Smell, namespace: str, active: dict[str, set[str]]) -> bool:
+    """Check if a smell is suppressed by the active suppressions."""
+    names = active.get(namespace, set())
+    return smell.kind in names or smell.name in names
+
+
+def _warn_excessive(count: int, total_lines: int) -> None:
+    """Warn to stderr if too many suppressions are used."""
+    if count > _MAX_SUPPRESSIONS_PER_FILE:
+        print(
+            f"Warning: {count} suppression comments in file "
+            f"({_MAX_SUPPRESSIONS_PER_FILE} max recommended)",
+            file=sys.stderr,
+        )
+
+
+def filter_suppressed(
+    smells: list[Smell], lines: list[str], namespace: str,
+) -> list[Smell]:
+    """Remove smells covered by inline suppression comments."""
+    suppression_map = _build_suppression_map(lines)
+    _warn_excessive(len(suppression_map), len(lines))
+    result: list[Smell] = []
+    for smell in smells:
+        active = suppression_map.get(smell.line, {})
+        if not _is_suppressed(smell, namespace, active):
+            result.append(smell)
+    return result

package/hooks/tab-color.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# tab-color.sh - Sets iTerm2 tab color for Claude Code hook events
+# Usage: tab-color.sh [gray|blue|green|red|reset]
+#
+# gray  = session idle (no prompt running)
+# blue  = prompt in progress (working)
+# green = prompt complete (done) -- decays to gray after 3 minutes
+# red   = error
+# reset = restore default tab color
+#
+# Tab TITLE (directory name) is set by claude-wrapper.sh at launch.
+# This script only manages COLOR -- Claude Code overrides mid-session title changes.
+
+DECAY_SECONDS=180
+
+# Consume stdin (hook protocol sends JSON on stdin)
+cat > /dev/null
+
+# Per-session state file to prevent decay timer from overwriting blue
+get_state_file() {
+    local tty_id
+    tty_id=$(tty < /dev/tty 2>/dev/null | tr '/' '_' || echo "unknown")
+    echo "/tmp/claude-tab-state${tty_id}"
+}
+
+set_tab_color() {
+    printf "\033]6;1;bg;red;brightness;%s\a" "$1" > /dev/tty 2>/dev/null
+    printf "\033]6;1;bg;green;brightness;%s\a" "$2" > /dev/tty 2>/dev/null
+    printf "\033]6;1;bg;blue;brightness;%s\a" "$3" > /dev/tty 2>/dev/null
+}
+
+STATE_FILE=$(get_state_file)
+
+case "${1:-blue}" in
+    gray)
+        echo "gray" > "$STATE_FILE" 2>/dev/null
+        set_tab_color 130 130 130
+        ;;
+    blue)
+        echo "blue" > "$STATE_FILE" 2>/dev/null
+        set_tab_color 20 80 255
+        ;;
+    green)
+        echo "green" > "$STATE_FILE" 2>/dev/null
+        set_tab_color 0 255 0
+        # Ring terminal bell -- triggers iTerm2 notification for background tabs
+        printf "\a" > /dev/tty 2>/dev/null
+        # Auto-decay to gray after 3 minutes (only if still green)
+        # Fully detach: redirect all fds so Claude Code doesn't wait for child
+        nohup bash -c "
+            sleep $DECAY_SECONDS
+            state_file='$STATE_FILE'
+            if [[ -f \"\$state_file\" && \"\$(cat \"\$state_file\" 2>/dev/null)\" == 'green' ]]; then
+                echo 'gray' > \"\$state_file\"
+                printf '\033]6;1;bg;red;brightness;130\a' > /dev/tty 2>/dev/null
+                printf '\033]6;1;bg;green;brightness;130\a' > /dev/tty 2>/dev/null
+                printf '\033]6;1;bg;blue;brightness;130\a' > /dev/tty 2>/dev/null
+            fi
+        " </dev/null >/dev/null 2>&1 &
+        ;;
+    red)
+        echo "red" > "$STATE_FILE" 2>/dev/null
+        set_tab_color 220 0 0
+        printf "\a" > /dev/tty 2>/dev/null
+        ;;
+    reset)
+        rm -f "$STATE_FILE" 2>/dev/null
+        printf "\033]6;1;bg;*;default\a" > /dev/tty 2>/dev/null
+        ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paulduvall/claude-dev-toolkit",
-  "version": "0.0.1-alpha.19",
+  "version": "0.0.1-alpha.21",
   "description": "Custom commands toolkit for Claude Code - streamline your development workflow",
   "author": "Paul Duvall",
   "license": "MIT",