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

package/hooks/settings.example.json

@@ -0,0 +1,52 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/check-complexity.py"
+          },
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/check-security.py"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/check-commit-signing.py"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/tab-color.sh green"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/tab-color.sh blue"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/smell_checks.py

@@ -0,0 +1,238 @@
+"""Code smell detection -- file-level checks, lizard checks, orchestration.
+
+Delegates Python AST analysis to smell_python, JS/TS analysis to
+smell_javascript, and shared types to smell_types.  This module
+provides the public API: check_file() and format_violations().
+"""
+
+from __future__ import annotations
+
+import os
+
+from config import Config, DEFAULT_CONFIG, is_file_suppressed, load_config
+from suppression import filter_suppressed
+from smell_types import (
+    DUPLICATE_MIN_LINES,
+    DUPLICATE_MIN_OCCURRENCES,
+    FIXES,
+    MAX_PARAMETERS,
+    MAX_COMPLEXITY,
+    MAX_FUNCTION_LINES,
+    Smell,
+    apply_threshold_checks,
+)
+from smell_javascript import check_javascript
+from smell_python import check_python
+from smell_ruff import RUFF_EXTS, check_ruff
+
+# ---------------------------------------------------------------------------
+# File-level: length
+# ---------------------------------------------------------------------------
+
+def check_file_length(
+    file_path: str, lines: list[str], config: Config | None = None,
+) -> list[Smell]:
+    """Flag files exceeding the configured max file lines."""
+    limit = (config or DEFAULT_CONFIG).max_file_lines
+    count = len(lines)
+    if count <= limit:
+        return []
+    return [Smell(
+        "long_file", os.path.basename(file_path), 1,
+        f"file is {count} lines (max {limit})",
+        FIXES["long_file"],
+    )]
+
+
+# ---------------------------------------------------------------------------
+# File-level: duplicate blocks
+# ---------------------------------------------------------------------------
+
+_SKIP_PREFIXES = ("import ", "from ", "export ", "require(", "#", "//", "/*")
+_TRIVIAL_LINES = frozenset((
+    "{", "}", "(", ")", "[", "]",
+    "else:", "else {", "try:", "finally:",
+))
+
+
+def _is_trivial(line: str) -> bool:
+    """Return True for lines to skip in duplicate detection."""
+    stripped = line.strip()
+    if not stripped or stripped in _TRIVIAL_LINES:
+        return True
+    return stripped.startswith(_SKIP_PREFIXES)
+
+
+def _build_fingerprints(lines: list[str]) -> dict[tuple[str, ...], list[int]]:
+    """Map fingerprints of consecutive non-trivial lines to positions."""
+    entries = [
+        (i + 1, line.strip())
+        for i, line in enumerate(lines)
+        if not _is_trivial(line)
+    ]
+    fps: dict[tuple[str, ...], list[int]] = {}
+    for i in range(len(entries) - DUPLICATE_MIN_LINES + 1):
+        window = entries[i : i + DUPLICATE_MIN_LINES]
+        fp = tuple(e[1] for e in window)
+        fps.setdefault(fp, []).append(window[0][0])
+    return fps
+
+
+def _overlaps(locs: list[int], reported: set[int]) -> bool:
+    """Return True if any location overlaps already-reported lines."""
+    return any(
+        loc + i in reported
+        for loc in locs
+        for i in range(DUPLICATE_MIN_LINES)
+    )
+
+
+def _mark_reported(locs: list[int], reported: set[int]) -> None:
+    """Add all lines covered by locs into the reported set."""
+    for loc in locs:
+        reported.update(range(loc, loc + DUPLICATE_MIN_LINES))
+
+
+def _make_dup_smell(locs: list[int]) -> Smell:
+    """Create a Smell for a single duplicate block occurrence."""
+    loc_str = ", ".join(str(loc) for loc in locs[:4])
+    return Smell(
+        "duplicate_block", "<repeated-code>", locs[0],
+        f"{DUPLICATE_MIN_LINES}-line block repeated at lines {loc_str}",
+        FIXES["duplicate_block"],
+    )
+
+
+def check_duplicate_blocks(
+    file_path: str, lines: list[str], config: Config | None = None,
+) -> list[Smell]:
+    """Detect repeated consecutive code blocks within a file."""
+    fps = _build_fingerprints(lines)
+    smells: list[Smell] = []
+    reported: set[int] = set()
+    for _fp, locs in sorted(fps.items(), key=lambda x: x[1][0]):
+        if len(locs) < DUPLICATE_MIN_OCCURRENCES:
+            continue
+        if _overlaps(locs, reported):
+            continue
+        _mark_reported(locs, reported)
+        smells.append(_make_dup_smell(locs))
+        if len(smells) >= 3:
+            break
+    return smells
+
+
+# ---------------------------------------------------------------------------
+# Lizard-based checks (non-JS/TS languages)
+# ---------------------------------------------------------------------------
+
+def _check_lizard_func(func: object) -> list[Smell]:
+    """Check a single lizard function result for smells."""
+    name = getattr(func, "name", "<unknown>")
+    line = getattr(func, "start_line", 0)
+    return apply_threshold_checks(name, line, [
+        ("complexity", getattr(func, "cyclomatic_complexity", 0), MAX_COMPLEXITY),
+        ("long_function", getattr(func, "nloc", 0), MAX_FUNCTION_LINES),
+        ("too_many_params", len(getattr(func, "parameters", [])), MAX_PARAMETERS),
+    ])
+
+
+def check_with_lizard(file_path: str) -> list[Smell]:
+    """Use lizard for CC, function length, and parameter count."""
+    try:
+        import lizard
+    except ImportError:
+        return []
+    try:
+        analysis = lizard.analyze_file(file_path)
+    except Exception:
+        return []
+    smells: list[Smell] = []
+    for func in analysis.function_list:
+        smells.extend(_check_lizard_func(func))
+    return smells
+
+
+# ---------------------------------------------------------------------------
+# Orchestration
+# ---------------------------------------------------------------------------
+
+PYTHON_EXTS = frozenset((".py",))
+JS_EXTS = frozenset((".js", ".jsx", ".ts", ".tsx"))
+LIZARD_EXTS = frozenset((".java", ".go", ".rs", ".c", ".cpp", ".cs"))
+ALL_EXTS = PYTHON_EXTS | JS_EXTS | LIZARD_EXTS
+SKIP_DIRS = frozenset((
+    "node_modules", "__pycache__", ".git", "dist", "build", ".next",
+))
+
+
+def _should_skip(file_path: str) -> bool:
+    """Return True for paths in ignored directories."""
+    parts = set(file_path.replace("\\", "/").split("/"))
+    return bool(SKIP_DIRS & parts)
+
+
+def _read_source(file_path: str) -> str | None:
+    """Read file contents, returning None on failure."""
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return None
+
+
+def _run_lang_checks(ext: str, file_path: str, source: str) -> list[Smell]:
+    """Run language-specific checks based on file extension."""
+    if ext in PYTHON_EXTS:
+        return check_python(file_path, source)
+    if ext in JS_EXTS:
+        return check_javascript(file_path, source)
+    if ext in LIZARD_EXTS:
+        return check_with_lizard(file_path)
+    return []
+
+
+def _ruff_then_reread(
+    ext: str, file_path: str, source: str,
+) -> tuple[list[Smell], str, list[str]]:
+    """Run ruff on Python files and re-read; return smells + fresh source."""
+    if ext not in RUFF_EXTS:
+        return [], source, source.splitlines()
+    smells = check_ruff(file_path)
+    fresh = _read_source(file_path)
+    if fresh is None:
+        return smells, source, source.splitlines()
+    return smells, fresh, fresh.splitlines()
+
+
+def check_file(file_path: str, config: Config | None = None) -> list[Smell]:
+    """Run all applicable smell checks on a single file."""
+    if config is None:
+        config = load_config(file_path)
+    ext = os.path.splitext(file_path)[1]
+    if ext not in ALL_EXTS or _should_skip(file_path):
+        return []
+    if is_file_suppressed(file_path, config):
+        return []
+    source = _read_source(file_path)
+    if source is None:
+        return []
+    smells, source, lines = _ruff_then_reread(ext, file_path, source)
+    smells.extend(check_file_length(file_path, lines, config))
+    smells.extend(check_duplicate_blocks(file_path, lines, config))
+    smells.extend(_run_lang_checks(ext, file_path, source))
+    return filter_suppressed(smells, lines, "smell")
+
+
+def format_violations(file_path: str, smells: list[Smell]) -> str:
+    """Build the feedback message for Claude."""
+    header = f"\nCODE SMELL VIOLATIONS in {file_path}:"
+    details = []
+    for s in smells:
+        tag = s.kind.upper().replace("_", " ")
+        details.append(f"  [{tag}] {s.name}() line {s.line}: {s.detail}")
+    fixes = ["\nFix these code smells before moving on:"]
+    for fix in dict.fromkeys(s.fix for s in smells):
+        fixes.append(f"  - {fix}")
+    fixes.append("Then notify the user what you fixed and why.")
+    return "\n".join([header, *details, *fixes])

package/hooks/smell_javascript.py

@@ -0,0 +1,231 @@
+"""Native JS/TS token-based code smell checks.
+
+Detects: cyclomatic complexity, long functions, deep nesting,
+and too-many-parameters in JavaScript and TypeScript source files.
+
+Uses a token-based parser (strip comments/strings, regex function
+detection, brace matching) -- zero external dependencies.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+
+from smell_types import (
+    MAX_COMPLEXITY,
+    MAX_FUNCTION_LINES,
+    MAX_NESTING_DEPTH,
+    MAX_PARAMETERS,
+    Smell,
+    apply_threshold_checks,
+)
+
+# ---------------------------------------------------------------------------
+# Layer 1 -- Tokenizer: strip comments and strings
+# ---------------------------------------------------------------------------
+
+_COMMENT_OR_STRING = re.compile(
+    r"//[^\n]*"              # single-line comment
+    r"|/\*[\s\S]*?\*/"       # multi-line comment
+    r"|`(?:[^`\\]|\\.)*`"    # template literal
+    r'|"(?:[^"\\]|\\.)*"'    # double-quoted string
+    r"|'(?:[^'\\]|\\.)*'"    # single-quoted string
+    r"|/(?![*/])(?:[^/\\\n]|\\.)+/[gimsuy]*"  # regex literal
+)
+
+
+def _strip_comments_and_strings(source: str) -> str:
+    """Replace comment/string contents with spaces, preserving lines."""
+    def _replacer(match: re.Match[str]) -> str:
+        return re.sub(r"[^\n]", " ", match.group(0))
+    return _COMMENT_OR_STRING.sub(_replacer, source)
+
+
+# ---------------------------------------------------------------------------
+# Layer 2 -- Function Finder
+# ---------------------------------------------------------------------------
+
+class _JsFunc(NamedTuple):
+    """A detected JS/TS function."""
+
+    name: str
+    start_line: int
+    end_line: int
+    params_str: str
+    body_source: str
+
+
+_MAYBE_ASYNC = r"(?:async\s+)?"
+_MAYBE_EXPORT = r"(?:export\s+)?"
+_MAYBE_GENERICS = r"(?:<[^>]*>)?"
+_MAYBE_RETURN_TYPE = r"(?::\s*[^{]+?)?"
+_IDENT = r"(?P<name>[a-zA-Z_$][a-zA-Z0-9_$]*)"
+_PARAMS = r"\((?P<params>[^)]*)\)"
+_DECL_VAR = r"(?:const|let|var)"
+_MAYBE_TYPE_ANN = r"(?::\s*[^=]+?)?"
+_MAYBE_STAR = r"\*?\s*"
+
+# Shared tail: <generics?> (params) <return-type?> {
+_PARAMS_OPEN = r"\s*" + _MAYBE_GENERICS + r"\s*" + _PARAMS + r"\s*" + _MAYBE_RETURN_TYPE
+_VAR_PREFIX = _MAYBE_EXPORT + _DECL_VAR + r"\s+" + _IDENT + r"\s*" + _MAYBE_TYPE_ANN + r"\s*=\s*"
+
+# Patterns that detect function declarations in stripped source.
+_FUNC_PATTERNS = [
+    # function declaration / async function declaration
+    re.compile(
+        _MAYBE_EXPORT + _MAYBE_ASYNC + r"function\s*" + _MAYBE_STAR
+        + _IDENT + _PARAMS_OPEN + r"\s*\{"
+    ),
+    # const/let/var name = function(params) {
+    re.compile(
+        _VAR_PREFIX + _MAYBE_ASYNC + r"function\s*" + _MAYBE_STAR
+        + r"(?:[a-zA-Z_$][a-zA-Z0-9_$]*)?" + _PARAMS_OPEN + r"\s*\{"
+    ),
+    # const/let/var name = (params) => {
+    re.compile(
+        _VAR_PREFIX + _MAYBE_ASYNC + _MAYBE_GENERICS
+        + r"\s*" + _PARAMS + r"\s*" + _MAYBE_RETURN_TYPE + r"\s*=>\s*\{"
+    ),
+    # class method: name(params) {
+    re.compile(
+        r"(?:(?:async|static|get|set|public|private|protected"
+        r"|readonly|override|abstract)\s+)*"
+        + _IDENT + _PARAMS_OPEN + r"\s*\{"
+    ),
+]
+
+
+def _match_brace(source: str, open_pos: int) -> int:
+    """Return index of the closing } that matches the { at open_pos."""
+    depth = 1
+    for i in range(open_pos + 1, len(source)):
+        if source[i] == "{":
+            depth += 1
+            continue
+        if source[i] != "}":
+            continue
+        depth -= 1
+        if depth == 0:
+            return i
+    return len(source) - 1
+
+
+def _line_of(source: str, char_index: int) -> int:
+    """Return 1-based line number for char_index in source."""
+    return source[:char_index].count("\n") + 1
+
+
+def _overlaps_existing(start: int, ranges: list[tuple[int, int]]) -> bool:
+    """Return True if start falls inside an already-claimed range."""
+    return any(r_start <= start < r_end for r_start, r_end in ranges)
+
+
+def _collect_raw_matches(stripped: str) -> list[tuple[int, int, str, str]]:
+    """Scan stripped source for all function matches, deduped by range."""
+    found: list[tuple[int, int, str, str]] = []
+    used: list[tuple[int, int]] = []
+    for pattern in _FUNC_PATTERNS:
+        for match in pattern.finditer(stripped):
+            start = match.start()
+            if _overlaps_existing(start, used):
+                continue
+            brace_pos = stripped.index("{", match.end() - 1)
+            close_pos = _match_brace(stripped, brace_pos)
+            found.append((start, close_pos, match.group("name"), match.group("params")))
+            used.append((start, close_pos))
+    found.sort(key=lambda x: x[0])
+    return found
+
+
+def _find_functions(stripped: str) -> list[_JsFunc]:
+    """Find all functions in the stripped source."""
+    results: list[_JsFunc] = []
+    for start, close, name, params in _collect_raw_matches(stripped):
+        start_line = _line_of(stripped, start)
+        end_line = _line_of(stripped, close)
+        body = stripped[start:close + 1]
+        results.append(_JsFunc(name, start_line, end_line, params, body))
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Layer 3 -- Metric functions
+# ---------------------------------------------------------------------------
+
+_CC_KEYWORDS = re.compile(
+    r"\b(?:if|else\s+if|case|catch|for|while|do)\b"
+)
+_CC_OPERATORS = re.compile(r"&&|\|\||\?\?|\?\.")
+_CC_TERNARY_REAL = re.compile(r"\?(?![.:])")
+
+
+def _js_complexity(body: str) -> int:
+    """Calculate cyclomatic complexity for a JS/TS function body."""
+    cc = 1
+    cc += len(_CC_KEYWORDS.findall(body))
+    cc += len(_CC_OPERATORS.findall(body))
+    cc += len(_CC_TERNARY_REAL.findall(body))
+    return cc
+
+
+def _js_func_lines(start: int, end: int) -> int:
+    """Return line count for a function."""
+    return end - start + 1
+
+
+def _js_nesting_depth(body: str) -> int:
+    """Calculate max nesting depth within a function body."""
+    max_depth = 0
+    depth = 0
+    for ch in body:
+        if ch == "{":
+            depth += 1
+            max_depth = max(max_depth, depth)
+        elif ch == "}":
+            depth = max(depth - 1, 0)
+    # Subtract 1 for the function's own braces
+    return max(max_depth - 1, 0)
+
+
+_TS_TYPE_ANNOTATION = re.compile(r"\s*[?!]?\s*:\s*[^,)]+")
+
+
+def _js_param_count(params_str: str) -> int:
+    """Count parameters, stripping TS type annotations."""
+    params = params_str.strip()
+    if not params:
+        return 0
+    cleaned = _TS_TYPE_ANNOTATION.sub("", params)
+    parts = [p.strip() for p in cleaned.split(",") if p.strip()]
+    return len(parts)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def _check_js_func(func: _JsFunc) -> list[Smell]:
+    """Check a single JS/TS function for all smells."""
+    return apply_threshold_checks(func.name, func.start_line, [
+        ("complexity", _js_complexity(func.body_source), MAX_COMPLEXITY),
+        ("long_function", _js_func_lines(func.start_line, func.end_line),
+         MAX_FUNCTION_LINES),
+        ("deep_nesting", _js_nesting_depth(func.body_source),
+         MAX_NESTING_DEPTH),
+        ("too_many_params", _js_param_count(func.params_str),
+         MAX_PARAMETERS),
+    ])
+
+
+def check_javascript(file_path: str, source: str) -> list[Smell]:
+    """Run all token-based smell checks on a JS/TS file."""
+    try:
+        stripped = _strip_comments_and_strings(source)
+        funcs = _find_functions(stripped)
+    except Exception:
+        return []
+    smells: list[Smell] = []
+    for func in funcs:
+        smells.extend(_check_js_func(func))
+    return smells

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 []