clean-code-tools 1.0.1

package/scripts/clean_code_python_triggers.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+from clean_code_review_models import TriggerRule
+
+PYLINT_TRIGGERS = {
+    "clean-code-boolean-flag-argument": TriggerRule(
+        questions=(
+            "Does the boolean select behavior rather than represent plain data?",
+            "Would intention-revealing functions or an explicit options object make call sites clearer?",
+        ),
+        mcp_query="python boolean flag argument intention revealing functions options object",
+    ),
+    "clean-code-business-policy-literal": TriggerRule(
+        questions=(
+            "Does this literal encode business policy or domain state?",
+            "Would a named constant or typed domain value make changes safer?",
+        ),
+        mcp_query="python business policy literal named constant domain state",
+    ),
+    "clean-code-commented-out-code": TriggerRule(
+        questions=(
+            "Is this commented code obsolete implementation detail?",
+            "Can it be removed in favor of version control history or a tracked task?",
+        ),
+        mcp_query="python commented out code remove obsolete implementation",
+    ),
+    "clean-code-noisy-comment": TriggerRule(
+        questions=(
+            "Is the comment adding constraint/context or just visual noise?",
+            "Would deleting or replacing it with a precise explanation improve scanability?",
+        ),
+        mcp_query="python noisy comments remove visual separators byline comments",
+    ),
+    "clean-code-output-argument-mutation": TriggerRule(
+        questions=(
+            "Is mutation hidden behind an output parameter?",
+            "Would returning a value or copying data make the contract clearer?",
+        ),
+        mcp_query="python output argument mutation return value contract",
+    ),
+    "clean-code-redundant-comment": TriggerRule(
+        questions=(
+            "Does the comment repeat the next line instead of explaining why?",
+            "Can clearer naming or deletion remove the need for the comment?",
+        ),
+        mcp_query="python redundant comment intention revealing code",
+    ),
+    "clean-code-todo-format": TriggerRule(
+        questions=(
+            "Is this TODO actionable and traceable?",
+            "Should the comment include a tracked issue or be converted into code/tests?",
+        ),
+        mcp_query="python todo comment issue id actionable technical debt",
+    ),
+    "clean-code-train-wreck": TriggerRule(
+        questions=(
+            "Is this chain exposing too much object structure to the caller?",
+            "Would a named query/helper or domain method reduce coupling?",
+        ),
+        mcp_query="python train wreck law of demeter object navigation",
+    ),
+    "cyclic-import": TriggerRule(
+        questions=(
+            "Is the cycle exposing a module boundary problem?",
+            "Can dependencies be inverted or shared types/constants moved lower?",
+        ),
+        mcp_query="python cyclic import module boundary dependency inversion",
+    ),
+    "duplicate-code": TriggerRule(
+        questions=(
+            "Is this real domain duplication or a benign framework shape?",
+            "Can a shared helper remove policy drift without obscuring the caller?",
+        ),
+        mcp_query="python duplicate code shared helper policy drift",
+    ),
+    "too-few-public-methods": TriggerRule(
+        questions=(
+            "Is this class just a passive data container or unnecessary wrapper?",
+            "Would a dataclass, TypedDict, or plain function fit the local style better?",
+        ),
+        mcp_query="python too few public methods unnecessary class dataclass function",
+    ),
+    "too-many-ancestors": TriggerRule(
+        questions=(
+            "Is inheritance making behavior harder to trace?",
+            "Would composition or a flatter design reduce coupling?",
+        ),
+        mcp_query="python too many ancestors inheritance composition coupling",
+    ),
+    "too-many-arguments": TriggerRule(
+        questions=(
+            "Do these arguments form a stable concept?",
+            "Would a dataclass, TypedDict, or keyword-only boundary clarify the call site?",
+        ),
+        mcp_query="python too many arguments dataclass typed dict call site clarity",
+    ),
+    "too-many-boolean-expressions": TriggerRule(
+        questions=(
+            "Is this condition encoding several decisions at once?",
+            "Would named predicates or explicit decision steps make the policy clearer?",
+        ),
+        mcp_query="python too many boolean expressions named predicates policy clarity",
+    ),
+    "too-many-branches": TriggerRule(
+        questions=(
+            "Is branching mixing policy decisions with execution?",
+            "Can guard clauses, named predicates, or extracted decisions simplify the flow?",
+        ),
+        mcp_query="python too many branches guard clauses named predicates",
+    ),
+    "too-many-instance-attributes": TriggerRule(
+        questions=(
+            "Is this object accumulating multiple responsibilities or state groups?",
+            "Can cohesive state move into smaller value objects or collaborators?",
+        ),
+        mcp_query="python too many instance attributes class responsibility state groups",
+    ),
+    "too-many-lines": TriggerRule(
+        questions=(
+            "Does this module have more than one reason to change?",
+            "Are there cohesive extraction boundaries that preserve imports and public APIs?",
+        ),
+        mcp_query="python large module single responsibility extraction boundaries",
+    ),
+    "too-many-locals": TriggerRule(
+        questions=(
+            "Is the function carrying too much intermediate state?",
+            "Can parsing, calculation, and side effects be separated?",
+        ),
+        mcp_query="python too many locals split parsing calculation side effects",
+    ),
+    "too-many-nested-blocks": TriggerRule(
+        questions=(
+            "Is nesting hiding the main path through the function?",
+            "Can early returns or named predicates flatten the code?",
+        ),
+        mcp_query="python nested blocks guard clauses main path readability",
+    ),
+    "too-many-public-methods": TriggerRule(
+        questions=(
+            "Does this class represent more than one responsibility?",
+            "Can cohesive behavior move into smaller collaborators or plain functions?",
+        ),
+        mcp_query="python class too many public methods single responsibility",
+    ),
+    "too-many-return-statements": TriggerRule(
+        questions=(
+            "Are return paths representing distinct outcomes that should be named?",
+            "Can guard clauses or result objects make the contract clearer?",
+        ),
+        mcp_query="python too many return statements guard clauses result contract",
+    ),
+    "too-many-statements": TriggerRule(
+        questions=(
+            "Does this function combine validation, transformation, and side effects?",
+            "Can smaller named steps preserve behavior while improving scanability?",
+        ),
+        mcp_query="python too many statements split validation transformation side effects",
+    ),
+}
+
+
+RUFF_TRIGGERS = {
+    "ARG001": TriggerRule(
+        questions=(
+            "Is this unused argument required by a framework or callback contract?",
+            "If not, can the function boundary be narrowed?",
+        ),
+        mcp_query="python unused function argument narrow function boundary",
+    ),
+    "ARG002": TriggerRule(
+        questions=(
+            "Is this unused method argument required by inheritance or framework convention?",
+            "If not, can the method contract be simplified?",
+        ),
+        mcp_query="python unused method argument simplify contract",
+    ),
+    "ERA001": TriggerRule(
+        questions=(
+            "Is this commented code obsolete implementation detail?",
+            "Can it be removed in favor of version control history or a tracked task?",
+        ),
+        mcp_query="python commented out code remove obsolete implementation",
+    ),
+    "F401": TriggerRule(
+        questions=(
+            "Is this unused import dead code or a leftover dependency?",
+            "Can removing it clarify the module boundary?",
+        ),
+        mcp_query="python unused import dead code module boundary",
+    ),
+    "F841": TriggerRule(
+        questions=(
+            "Is this unused variable dead code or an incomplete refactor?",
+            "Can the unused state or surrounding responsibility be removed?",
+        ),
+        mcp_query="python unused variable dead code incomplete refactor",
+    ),
+    "PLR0911": TriggerRule(
+        questions=(
+            "Are return paths representing distinct outcomes that should be named?",
+            "Can guard clauses or result objects make the contract clearer?",
+        ),
+        mcp_query="python too many return statements guard clauses result contract",
+    ),
+    "PLR0912": TriggerRule(
+        questions=(
+            "Is branching mixing policy decisions with execution?",
+            "Can guard clauses, named predicates, or extracted decisions simplify the flow?",
+        ),
+        mcp_query="python too many branches guard clauses named predicates",
+    ),
+    "PLR0913": TriggerRule(
+        questions=(
+            "Do these arguments form a stable concept?",
+            "Would a dataclass, TypedDict, or keyword-only boundary clarify the call site?",
+        ),
+        mcp_query="python too many arguments dataclass typed dict call site clarity",
+    ),
+    "PLR0914": TriggerRule(
+        questions=(
+            "Is the function carrying too much intermediate state?",
+            "Can parsing, calculation, and side effects be separated?",
+        ),
+        mcp_query="python too many locals split parsing calculation side effects",
+    ),
+    "PLR0915": TriggerRule(
+        questions=(
+            "Does this function combine validation, transformation, and side effects?",
+            "Can smaller named steps preserve behavior while improving scanability?",
+        ),
+        mcp_query="python too many statements split validation transformation side effects",
+    ),
+    "PLR0916": TriggerRule(
+        questions=(
+            "Is this condition encoding several decisions at once?",
+            "Would named predicates or explicit decision steps make the policy clearer?",
+        ),
+        mcp_query="python too many boolean expressions named predicates policy clarity",
+    ),
+    "PLR1702": TriggerRule(
+        questions=(
+            "Is nesting hiding the main path through the function?",
+            "Can early returns or named predicates flatten the code?",
+        ),
+        mcp_query="python nested blocks guard clauses main path readability",
+    ),
+    "PLR2004": TriggerRule(
+        questions=(
+            "Does this value encode business policy or a domain threshold?",
+            "Would a named constant make the rule searchable and easier to change?",
+        ),
+        mcp_query="python magic value comparison named constant business policy",
+    ),
+    "RET505": TriggerRule(
+        questions=(
+            "Is the else branch unnecessary after a return?",
+            "Would flattening the control flow make the main path clearer?",
+        ),
+        mcp_query="python unnecessary else after return flatten control flow",
+    ),
+    "RET506": TriggerRule(
+        questions=(
+            "Is the else branch unnecessary after an exception?",
+            "Would flattening the control flow make failure handling clearer?",
+        ),
+        mcp_query="python unnecessary else after raise flatten error handling",
+    ),
+    "RET507": TriggerRule(
+        questions=(
+            "Is the else branch unnecessary after continue?",
+            "Would flattening the loop body improve scanability?",
+        ),
+        mcp_query="python unnecessary else after continue flatten loop",
+    ),
+    "RET508": TriggerRule(
+        questions=(
+            "Is the else branch unnecessary after break?",
+            "Would flattening the loop body improve scanability?",
+        ),
+        mcp_query="python unnecessary else after break flatten loop",
+    ),
+    "SIM102": TriggerRule(
+        questions=(
+            "Is nested branching hiding a single combined condition?",
+            "Would a named predicate or combined guard clarify the decision?",
+        ),
+        mcp_query="python nested if combined condition named predicate",
+    ),
+    "SIM103": TriggerRule(
+        questions=(
+            "Is a boolean branch returning literal booleans instead of the condition?",
+            "Would returning a named predicate make intent clearer?",
+        ),
+        mcp_query="python needless boolean return named predicate",
+    ),
+    "SIM108": TriggerRule(
+        questions=(
+            "Is assignment spread across branches obscuring one decision?",
+            "Would a named expression or helper make the choice clearer?",
+        ),
+        mcp_query="python if else assignment decision helper readability",
+    ),
+    "TD002": TriggerRule(
+        questions=(
+            "Is this TODO owned by a person or team?",
+            "Should the debt be tracked or removed?",
+        ),
+        mcp_query="python todo owner tracked technical debt",
+    ),
+    "TD003": TriggerRule(
+        questions=(
+            "Is this TODO tied to a tracked issue?",
+            "Should the comment become an actionable task or be removed?",
+        ),
+        mcp_query="python todo issue link actionable technical debt",
+    ),
+}

package/scripts/clean_code_review_candidates.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from clean_code_eslint_triggers import ESLINT_TRIGGERS
+from clean_code_python_triggers import PYLINT_TRIGGERS, RUFF_TRIGGERS
+from clean_code_review_io import load_json_file, run_json_command
+from clean_code_review_models import LintTrigger, ReviewCandidate, TriggerInput, TriggerRule
+
+ROOT = Path(__file__).resolve().parents[1]
+JsonDict = dict[str, Any]
+
+
+def eslint_candidates(results: list[JsonDict]) -> list[ReviewCandidate]:
+    candidates: list[ReviewCandidate] = []
+    for result in results:
+        file_path = result.get("filePath")
+        if not isinstance(file_path, str):
+            continue
+        for message in result.get("messages", []):
+            if not isinstance(message, dict):
+                continue
+            rule_id = message.get("ruleId")
+            if not isinstance(rule_id, str) or rule_id not in ESLINT_TRIGGERS:
+                continue
+            candidates.append(
+                review_candidate(
+                    TriggerInput(
+                        language="typescript",
+                        file=file_path,
+                        symbol=None,
+                        anchor=line_anchor(optional_int(message.get("line"))),
+                        tool="eslint",
+                        rule=rule_id,
+                        message=str(message.get("message", "")),
+                        line=optional_int(message.get("line")),
+                        column=optional_int(message.get("column")),
+                    ),
+                    trigger_rule=ESLINT_TRIGGERS[rule_id],
+                )
+            )
+    return candidates
+
+
+def ruff_candidates(messages: list[JsonDict]) -> list[ReviewCandidate]:
+    candidates: list[ReviewCandidate] = []
+    for message in messages:
+        code = message.get("code")
+        if not isinstance(code, str) or code not in RUFF_TRIGGERS:
+            continue
+        location = message.get("location", {})
+        if not isinstance(location, dict):
+            location = {}
+        row = optional_int(location.get("row"))
+        candidates.append(
+            review_candidate(
+                TriggerInput(
+                    language="python",
+                    file=str(message.get("filename", "")),
+                    symbol=None,
+                    anchor=line_anchor(row),
+                    tool="ruff",
+                    rule=code,
+                    message=str(message.get("message", "")),
+                    line=row,
+                    column=optional_int(location.get("column")),
+                ),
+                trigger_rule=RUFF_TRIGGERS[code],
+            )
+        )
+    return candidates
+
+
+def pylint_candidates(messages: list[JsonDict]) -> list[ReviewCandidate]:
+    candidates: list[ReviewCandidate] = []
+    for message in messages:
+        symbol = message.get("symbol")
+        if not isinstance(symbol, str) or symbol not in PYLINT_TRIGGERS:
+            continue
+        candidates.append(
+            review_candidate(
+                TriggerInput(
+                    language="python",
+                    file=str(message.get("path", "")),
+                    symbol=optional_str(message.get("obj")),
+                    anchor=line_anchor(optional_int(message.get("line"))),
+                    tool="pylint",
+                    rule=symbol,
+                    message=str(message.get("message", "")),
+                    line=optional_int(message.get("line")),
+                    column=optional_int(message.get("column")),
+                ),
+                trigger_rule=PYLINT_TRIGGERS[symbol],
+            )
+        )
+    return candidates
+
+
+def optional_int(value: object) -> int | None:
+    return value if isinstance(value, int) else None
+
+
+def optional_str(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def line_anchor(line: int | None) -> str | None:
+    if line is None:
+        return None
+    return f"line {line}"
+
+
+def review_candidate(
+    trigger_input: TriggerInput,
+    *,
+    trigger_rule: TriggerRule,
+) -> ReviewCandidate:
+    return ReviewCandidate(
+        language=trigger_input.language,
+        file=normalize_file(trigger_input.file),
+        symbol=trigger_input.symbol,
+        anchor=trigger_input.anchor,
+        skill="clean-code-mcp-reviewer",
+        triggers=(
+            LintTrigger(
+                tool=trigger_input.tool,
+                rule=trigger_input.rule,
+                message=trigger_input.message,
+                line=trigger_input.line,
+                column=trigger_input.column,
+            ),
+        ),
+        semantic_questions=trigger_rule.questions,
+        mcp_queries=(trigger_rule.mcp_query,),
+    )
+
+
+def normalize_file(path: str) -> str:
+    if not path:
+        return path
+    raw_path = Path(path)
+    try:
+        return str(raw_path.resolve().relative_to(ROOT))
+    except ValueError:
+        return path
+
+
+def merge_candidates(candidates: list[ReviewCandidate]) -> list[ReviewCandidate]:
+    grouped: dict[tuple[str, str, str | None, str | None, str], list[ReviewCandidate]] = {}
+    for candidate in candidates:
+        key = (
+            candidate.language,
+            candidate.file,
+            candidate.symbol,
+            candidate.anchor,
+            candidate.skill,
+        )
+        grouped.setdefault(key, []).append(candidate)
+
+    merged: list[ReviewCandidate] = []
+    for (language, file, symbol, anchor, skill), group in grouped.items():
+        triggers = tuple(trigger for candidate in group for trigger in candidate.triggers)
+        questions = unique_items(
+            question for candidate in group for question in candidate.semantic_questions
+        )
+        queries = unique_items(query for candidate in group for query in candidate.mcp_queries)
+        merged.append(
+            ReviewCandidate(
+                language=language,
+                file=file,
+                symbol=symbol,
+                anchor=anchor,
+                skill=skill,
+                triggers=triggers,
+                semantic_questions=questions,
+                mcp_queries=queries,
+            )
+        )
+    return sorted(merged, key=candidate_sort_key)
+
+
+def candidate_sort_key(candidate: ReviewCandidate) -> tuple[str, str, int]:
+    first_line = min(
+        (trigger.line for trigger in candidate.triggers if trigger.line is not None),
+        default=0,
+    )
+    return (candidate.file, candidate.symbol or candidate.anchor or "", first_line)
+
+
+def unique_items(items: Any) -> tuple[str, ...]:
+    seen: set[str] = set()
+    unique: list[str] = []
+    for item in items:
+        if item not in seen:
+            seen.add(item)
+            unique.append(item)
+    return tuple(unique)
+
+
+def candidates_from_sources(args: argparse.Namespace) -> list[ReviewCandidate]:
+    candidates: list[ReviewCandidate] = []
+    if args.eslint_json:
+        candidates.extend(eslint_candidates(load_json_file(args.eslint_json)))
+    if args.eslint_command:
+        candidates.extend(eslint_candidates(run_json_command(args.eslint_command)))
+    if args.pylint_json:
+        candidates.extend(pylint_candidates(load_json_file(args.pylint_json)))
+    if args.pylint_command:
+        candidates.extend(pylint_candidates(run_json_command(args.pylint_command)))
+    if args.ruff_json:
+        candidates.extend(ruff_candidates(load_json_file(args.ruff_json)))
+    if args.ruff_command:
+        candidates.extend(ruff_candidates(run_json_command(args.ruff_command)))
+    return merge_candidates(candidates)
+
+
+def candidate_payload(candidates: list[ReviewCandidate]) -> JsonDict:
+    return {
+        "schema": "clean-code-review-candidates/v1",
+        "candidate_count": len(candidates),
+        "candidates": [asdict(candidate) for candidate in candidates],
+    }
+
+
+def markdown_payload(candidates: list[ReviewCandidate]) -> str:
+    if not candidates:
+        return "No clean-code semantic review candidates found.\n"
+
+    lines = ["# Clean-Code Semantic Review Candidates", ""]
+    for candidate in candidates:
+        location = candidate.file
+        if candidate.symbol:
+            location = f"{location}::{candidate.symbol}"
+        elif candidate.anchor:
+            location = f"{location}::{candidate.anchor}"
+        lines.extend(
+            [
+                f"## {location}",
+                "",
+                f"- language: `{candidate.language}`",
+                f"- skill: `{candidate.skill}`",
+                "- triggers:",
+            ]
+        )
+        for trigger in candidate.triggers:
+            line = f"  - `{trigger.tool}/{trigger.rule}`"
+            if trigger.line is not None:
+                line = f"{line} at line {trigger.line}"
+            if trigger.message:
+                line = f"{line}: {trigger.message}"
+            lines.append(line)
+        lines.append("- semantic questions:")
+        for question in candidate.semantic_questions:
+            lines.extend([f"  - {question}"])
+        lines.append("- MCP queries:")
+        for query in candidate.mcp_queries:
+            lines.extend([f"  - `{query}`"])
+        lines.append("")
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Convert deterministic lint findings into clean-code semantic review candidates."
+    )
+    parser.add_argument("--eslint-json", type=Path)
+    parser.add_argument("--eslint-command")
+    parser.add_argument("--pylint-json", type=Path)
+    parser.add_argument("--pylint-command")
+    parser.add_argument("--ruff-json", type=Path)
+    parser.add_argument("--ruff-command")
+    parser.add_argument("--format", choices=("json", "markdown"), default="json")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    candidates = candidates_from_sources(args)
+    if args.format == "markdown":
+        print(markdown_payload(candidates))
+    else:
+        print(json.dumps(candidate_payload(candidates), indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/clean_code_review_io.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def parse_json(raw_json: str, *, source: str) -> Any:
+    try:
+        return json.loads(raw_json)
+    except json.JSONDecodeError as exc:
+        error = f"Could not parse {source} as JSON: {exc}"
+        raise SystemExit(error) from exc
+
+
+def load_json_file(path: Path) -> Any:
+    return parse_json(path.read_text(), source=str(path))
+
+
+def run_json_command(command: str) -> Any:
+    completed = subprocess.run(  # noqa: S603 - runs caller-provided local lint commands.
+        shlex.split(command),
+        cwd=ROOT,
+        check=False,
+        text=True,
+        capture_output=True,
+    )
+    if not completed.stdout.strip():
+        print(completed.stderr, file=sys.stderr)
+        raise SystemExit(completed.returncode or 1)
+    return parse_json(completed.stdout, source=command)

package/scripts/clean_code_review_models.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TriggerRule:
+    questions: tuple[str, ...]
+    mcp_query: str
+
+
+@dataclass(frozen=True)
+class LintTrigger:
+    tool: str
+    rule: str
+    message: str
+    line: int | None
+    column: int | None
+
+
+@dataclass(frozen=True)
+class TriggerInput:
+    language: str
+    file: str
+    symbol: str | None
+    anchor: str | None
+    tool: str
+    rule: str
+    message: str
+    line: int | None
+    column: int | None
+
+
+@dataclass(frozen=True)
+class ReviewCandidate:
+    language: str
+    file: str
+    symbol: str | None
+    anchor: str | None
+    skill: str
+    triggers: tuple[LintTrigger, ...]
+    semantic_questions: tuple[str, ...]
+    mcp_queries: tuple[str, ...]