clean-code-tools 1.0.1

package/sample-apps/README.md

@@ -0,0 +1,40 @@
+# Sample Apps
+
+These apps exercise the clean-code lint presets against realistic small examples.
+
+## Python
+
+```bash
+python -m pip install "ruff>=0.15.0" "pylint>=4.0.0"
+cd sample-apps/python-app
+ruff check src/clean_pricing.py
+pylint --rcfile=pyproject.toml src/clean_pricing.py
+ruff check src/smelly_pricing.py
+pylint --rcfile=pyproject.toml src/smelly_pricing.py
+```
+
+The clean file should pass. The smelly file should report TODO tracking, commented-out code, unused arguments, and too many arguments.
+
+## TypeScript Backend
+
+```bash
+cd sample-apps/ts-backend
+bun install
+bun run lint:clean
+bun run lint:smelly
+```
+
+The clean handler should pass. The smelly handler should report untracked TODOs, commented-out code, boolean flag arguments, policy literals, train-wreck navigation, and null usage.
+
+## TypeScript Frontend
+
+```bash
+cd sample-apps/ts-frontend
+bun install
+bun run lint:clean
+bun run lint:smelly
+```
+
+The clean widget should pass. The smelly widget should report untracked TODOs, commented-out code, train-wreck navigation, policy literals, output argument mutation, null usage, and boolean flag arguments.
+
+The TypeScript samples import the preset through `clean-code-tools/configs/eslint.clean-code.recommended.mjs`, so they exercise the package export path rather than a repository-relative config path.

package/sample-apps/python-app/pyproject.toml

@@ -0,0 +1,113 @@
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+extend-exclude = [
+  ".venv",
+  "__pycache__",
+  "build",
+  "dist",
+]
+
+[tool.ruff.lint]
+select = [
+  "E",
+  "F",
+  "I",
+  "UP",
+  "B",
+  "C4",
+  "SIM",
+  "RET",
+  "ARG",
+  "ERA",
+  "TD",
+  "PLR2004",
+  "RUF",
+]
+ignore = [
+  "E501",
+  "TD001",
+]
+fixable = [
+  "E",
+  "F",
+  "I",
+  "UP",
+  "B",
+  "C4",
+  "SIM",
+  "RET",
+  "ARG",
+  "RUF",
+]
+unfixable = [
+  "ERA",
+  "TD",
+  "PLR2004",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+  "ARG001",
+  "ARG002",
+  "PLR2004",
+  "S101",
+]
+
+[tool.pylint.main]
+py-version = "3.11"
+jobs = 0
+recursive = true
+load-plugins = [
+  "clean_code_tools_pylint",
+]
+
+[tool.pylint."messages control"]
+disable = [
+  "all",
+]
+enable = [
+  "cyclic-import",
+  "clean-code-boolean-flag-argument",
+  "clean-code-business-policy-literal",
+  "clean-code-commented-out-code",
+  "clean-code-noisy-comment",
+  "clean-code-output-argument-mutation",
+  "clean-code-redundant-comment",
+  "clean-code-todo-format",
+  "clean-code-train-wreck",
+  "duplicate-code",
+  "import-error",
+  "too-many-ancestors",
+  "too-many-arguments",
+  "too-many-branches",
+  "too-many-instance-attributes",
+  "too-many-lines",
+  "too-many-locals",
+  "too-many-nested-blocks",
+  "too-many-public-methods",
+  "too-many-return-statements",
+  "too-many-statements",
+  "too-many-boolean-expressions",
+  "too-few-public-methods",
+]
+
+[tool.pylint.design]
+max-args = 5
+max-attributes = 7
+max-bool-expr = 5
+max-branches = 12
+max-locals = 15
+max-nested-blocks = 4
+max-public-methods = 12
+max-returns = 6
+max-statements = 40
+max-parents = 7
+min-public-methods = 1
+
+[tool.pylint.format]
+max-line-length = 100
+max-module-lines = 300
+
+[tool.pylint.reports]
+score = false

package/sample-apps/python-app/src/clean_pricing.py

@@ -0,0 +1,10 @@
+MAX_RETRY_ATTEMPTS = 5
+PENDING_STATUS = "pending"
+
+
+def can_retry_payment(status: str, failed_attempts: int) -> bool:
+    return status == PENDING_STATUS and failed_attempts < MAX_RETRY_ATTEMPTS
+
+
+def calculate_total(subtotal_cents: int, tax_cents: int) -> int:
+    return subtotal_cents + tax_cents

package/sample-apps/python-app/src/smelly_pricing.py

@@ -0,0 +1,8 @@
+# TODO clean this up
+# old_total = calculate_total(order)
+
+
+def calculate_total(order, include_tax, dry_run, retry, verbose, mode):
+    if order.status == "pending":
+        return 5
+    return 0

package/sample-apps/ts-backend/eslint.config.mjs

@@ -0,0 +1,3 @@
+import cleanCode from "clean-code-tools/configs/eslint.clean-code.recommended.mjs";
+
+export default cleanCode;

package/sample-apps/ts-backend/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "sample-ts-backend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "lint:clean": "eslint src/clean-handler.ts --max-warnings 0",
+    "lint:smelly": "eslint src/smelly-handler.ts"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "clean-code-tools": "file:../..",
+    "eslint": "^10.4.0",
+    "eslint-plugin-sonarjs": "^4.0.0",
+    "eslint-plugin-unicorn": "^69.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0"
+  }
+}

package/sample-apps/ts-backend/src/clean-handler.ts

@@ -0,0 +1,19 @@
+const MAX_LOGIN_ATTEMPTS = 5;
+const PAYMENT_FAILED_STATUS = "payment_failed";
+
+interface Payment {
+  readonly failedAttempts: number;
+  readonly status: string;
+}
+
+function canRetryPayment(payment: Payment): boolean {
+  return payment.status === PAYMENT_FAILED_STATUS && payment.failedAttempts < MAX_LOGIN_ATTEMPTS;
+}
+
+export function planPaymentRetry(payment: Payment): string {
+  if (canRetryPayment(payment)) {
+    return "retry";
+  }
+
+  return "skip";
+}

package/sample-apps/ts-backend/src/smelly-handler.ts

@@ -0,0 +1,29 @@
+// TODO clean this up
+// await publishReceipt(receipt);
+
+type Payment = {
+  status: string;
+  customer: {
+    account: {
+      billing: {
+        email: string;
+      };
+    };
+  };
+};
+
+function sendPaymentEmail(payment: Payment, dryRun: boolean): null {
+  if (payment.status === "payment_failed") {
+    sendEmail(payment.customer.account.billing.email, true);
+  }
+
+  return null;
+}
+
+function sendEmail(email: string, urgent: boolean): void {
+  if (urgent) {
+    console.log(email);
+  }
+}
+
+sendPaymentEmail({ status: "payment_failed", customer: { account: { billing: { email: "a@b.test" } } } }, false);

package/sample-apps/ts-backend/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "target": "ES2022"
+  },
+  "include": ["src/**/*.ts"]
+}

package/sample-apps/ts-frontend/eslint.config.mjs

@@ -0,0 +1,3 @@
+import cleanCode from "clean-code-tools/configs/eslint.clean-code.recommended.mjs";
+
+export default cleanCode;

package/sample-apps/ts-frontend/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "sample-ts-frontend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "lint:clean": "eslint src/CleanWidget.tsx --max-warnings 0",
+    "lint:smelly": "eslint src/SmellyWidget.tsx"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "clean-code-tools": "file:../..",
+    "eslint": "^10.4.0",
+    "eslint-plugin-sonarjs": "^4.0.0",
+    "eslint-plugin-unicorn": "^69.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0"
+  }
+}

package/sample-apps/ts-frontend/src/CleanWidget.tsx

@@ -0,0 +1,18 @@
+const MAX_VISIBLE_ITEMS = 5;
+
+interface DashboardWidgetProps {
+  readonly items: readonly string[];
+  readonly shouldShowEmptyState: boolean;
+}
+
+function visibleItems(items: readonly string[]): readonly string[] {
+  return items.slice(0, MAX_VISIBLE_ITEMS);
+}
+
+export function DashboardWidget({ items, shouldShowEmptyState }: DashboardWidgetProps): string {
+  if (items.length === 0 && shouldShowEmptyState) {
+    return "No items";
+  }
+
+  return visibleItems(items).join(", ");
+}

package/sample-apps/ts-frontend/src/SmellyWidget.tsx

@@ -0,0 +1,27 @@
+// TODO fix widget
+// return <OldWidget />;
+
+type DashboardWidgetProps = {
+  items: string[];
+  user: {
+    account: {
+      plan: {
+        status: string;
+      };
+    };
+  };
+};
+
+function DashboardWidget(props: DashboardWidgetProps, compact: boolean): null {
+  if (props.user.account.plan.status === "active") {
+    props.items.push("bonus");
+  }
+
+  if (compact) {
+    return null;
+  }
+
+  return null;
+}
+
+DashboardWidget({ items: [], user: { account: { plan: { status: "active" } } } }, true);

package/sample-apps/ts-frontend/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "target": "ES2022"
+  },
+  "include": ["src/**/*.tsx"]
+}

package/scripts/_mcp_app.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from types import ModuleType
+
+ROOT = Path(__file__).resolve().parents[1]
+PYTHON_SRC = ROOT / "src" / "python"
+
+if str(PYTHON_SRC) not in sys.path:
+    sys.path.insert(0, str(PYTHON_SRC))
+
+
+def load_semantic_module() -> ModuleType:
+    return importlib.import_module("mcp_server.semantic")
+
+
+def load_server_module() -> ModuleType:
+    return importlib.import_module("mcp_server.server")

package/scripts/check_clean_code_review_candidates.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import re
+import tomllib
+from pathlib import Path
+
+from clean_code_eslint_triggers import ESLINT_TRIGGERS
+from clean_code_python_triggers import PYLINT_TRIGGERS, RUFF_TRIGGERS
+from clean_code_review_candidates import (
+    candidate_payload,
+    eslint_candidates,
+    markdown_payload,
+    merge_candidates,
+    pylint_candidates,
+    ruff_candidates,
+)
+
+ROOT = Path(__file__).resolve().parents[1]
+ESLINT_CONFIG = ROOT / "configs/eslint.clean-code.recommended.mjs"
+PYTHON_CONFIG = ROOT / "configs/python.clean-code.pyproject.toml"
+REPO_PYTHON_CONFIG = ROOT / "pyproject.toml"
+
+EXPECTED_ESLINT_TRIGGERS = {
+    "@typescript-eslint/consistent-type-imports",
+    "@typescript-eslint/naming-convention",
+    "@typescript-eslint/no-confusing-void-expression",
+    "@typescript-eslint/no-magic-numbers",
+    "@typescript-eslint/no-unnecessary-condition",
+    "@typescript-eslint/no-unnecessary-type-assertion",
+    "@typescript-eslint/no-unused-vars",
+    "@typescript-eslint/prefer-nullish-coalescing",
+    "@typescript-eslint/strict-boolean-expressions",
+    "@typescript-eslint/switch-exhaustiveness-check",
+    "clean-code/no-boolean-flag-arguments",
+    "clean-code/no-business-policy-literals",
+    "clean-code/no-commented-out-code",
+    "clean-code/no-noisy-comments",
+    "clean-code/no-output-argument-mutation",
+    "clean-code/no-redundant-comment",
+    "clean-code/no-train-wrecks",
+    "clean-code/todo-format",
+    "complexity",
+    "max-depth",
+    "max-lines",
+    "max-lines-per-function",
+    "max-params",
+    "no-empty",
+    "no-negated-condition",
+    "no-nested-ternary",
+    "no-restricted-syntax",
+    "no-useless-return",
+    "sonarjs/cognitive-complexity",
+    "sonarjs/no-dead-store",
+    "sonarjs/no-duplicate-string",
+    "sonarjs/no-duplicated-branches",
+    "sonarjs/no-identical-conditions",
+    "sonarjs/no-identical-functions",
+    "sonarjs/no-inverted-boolean-check",
+    "unicorn/explicit-length-check",
+    "unicorn/no-negated-condition",
+    "unicorn/no-null",
+}
+
+ESLINT_SEMANTIC_EXCLUSIONS = {
+    "@typescript-eslint/no-floating-promises",
+    "@typescript-eslint/no-misused-promises",
+    "eqeqeq",
+    "spaced-comment",
+}
+
+EXPECTED_PYLINT_TRIGGERS = {
+    "clean-code-boolean-flag-argument",
+    "clean-code-business-policy-literal",
+    "clean-code-commented-out-code",
+    "clean-code-noisy-comment",
+    "clean-code-output-argument-mutation",
+    "clean-code-redundant-comment",
+    "clean-code-todo-format",
+    "clean-code-train-wreck",
+    "cyclic-import",
+    "duplicate-code",
+    "too-few-public-methods",
+    "too-many-ancestors",
+    "too-many-arguments",
+    "too-many-boolean-expressions",
+    "too-many-branches",
+    "too-many-instance-attributes",
+    "too-many-lines",
+    "too-many-locals",
+    "too-many-nested-blocks",
+    "too-many-public-methods",
+    "too-many-return-statements",
+    "too-many-statements",
+}
+
+PYLINT_SEMANTIC_EXCLUSIONS = {
+    "import-error",
+}
+
+EXPECTED_RUFF_TRIGGERS = {
+    "ARG001",
+    "ARG002",
+    "ERA001",
+    "F401",
+    "F841",
+    "PLR0911",
+    "PLR0912",
+    "PLR0913",
+    "PLR0914",
+    "PLR0915",
+    "PLR0916",
+    "PLR1702",
+    "PLR2004",
+    "RET505",
+    "RET506",
+    "RET507",
+    "RET508",
+    "SIM102",
+    "SIM103",
+    "SIM108",
+    "TD002",
+    "TD003",
+}
+
+RUFF_CURATED_SELECT_PREFIXES = {
+    "ARG",
+    "ERA",
+    "F",
+    "PLR2004",
+    "RET",
+    "SIM",
+    "TD",
+}
+
+
+def enabled_eslint_rules() -> set[str]:
+    source = ESLINT_CONFIG.read_text()
+    rule_pattern = re.compile(
+        r'^\s*(?:"(?P<quoted>[^"]+)"|(?P<bare>[A-Za-z][\w/-]*)):\s*'
+        r'(?:(?P<string>"(?:warn|error)")|\[\s*"(?P<array>warn|error)")',
+        re.MULTILINE,
+    )
+    return {
+        match.group("quoted") or match.group("bare")
+        for match in rule_pattern.finditer(source)
+    }
+
+
+def python_lint_config(path: Path = PYTHON_CONFIG) -> dict:
+    return tomllib.loads(path.read_text())
+
+
+def enabled_pylint_rules() -> set[str]:
+    return set(python_lint_config()["tool"]["pylint"]["messages control"]["enable"])
+
+
+def selected_ruff_prefixes() -> set[str]:
+    return set(python_lint_config()["tool"]["ruff"]["lint"]["select"])
+
+
+def repo_selected_ruff_prefixes() -> set[str]:
+    return set(python_lint_config(REPO_PYTHON_CONFIG)["tool"]["ruff"]["lint"]["select"])
+
+
+def all_selected_ruff_prefixes() -> set[str]:
+    return selected_ruff_prefixes() | repo_selected_ruff_prefixes()
+
+
+def ruff_code_is_selected(code: str, selected_prefixes: set[str]) -> bool:
+    return any(code.startswith(prefix) for prefix in selected_prefixes)
+
+
+def main() -> None:
+    assert set(ESLINT_TRIGGERS) == EXPECTED_ESLINT_TRIGGERS
+    assert set(PYLINT_TRIGGERS) == EXPECTED_PYLINT_TRIGGERS
+    assert set(RUFF_TRIGGERS) == EXPECTED_RUFF_TRIGGERS
+    assert enabled_eslint_rules() <= set(ESLINT_TRIGGERS) | ESLINT_SEMANTIC_EXCLUSIONS
+    assert enabled_pylint_rules() <= set(PYLINT_TRIGGERS) | PYLINT_SEMANTIC_EXCLUSIONS
+    assert selected_ruff_prefixes() >= RUFF_CURATED_SELECT_PREFIXES
+    assert all(ruff_code_is_selected(code, all_selected_ruff_prefixes()) for code in RUFF_TRIGGERS)
+
+    eslint_results = [
+        {
+            "filePath": "/repo/src/pricing.ts",
+            "messages": [
+                {
+                    "ruleId": "max-lines-per-function",
+                    "message": "Function has too many lines.",
+                    "line": 12,
+                    "column": 1,
+                },
+                {
+                    "ruleId": "clean-code/no-boolean-flag-arguments",
+                    "message": "Boolean literal selects behavior.",
+                    "line": 44,
+                    "column": 22,
+                },
+                {
+                    "ruleId": "semi",
+                    "message": "Formatting-only rules are not semantic triggers.",
+                    "line": 45,
+                    "column": 1,
+                },
+            ],
+        }
+    ]
+    pylint_results = [
+        {
+            "path": "sample-apps/python-app/src/smelly_pricing.py",
+            "obj": "calculate_total",
+            "line": 5,
+            "column": 0,
+            "symbol": "too-many-arguments",
+            "message": "Too many arguments (6/5)",
+        },
+        {
+            "path": "sample-apps/python-app/src/smelly_pricing.py",
+            "obj": "calculate_total",
+            "line": 7,
+            "column": 4,
+            "symbol": "clean-code-output-argument-mutation",
+            "message": "Avoid mutating parameter 'order' as an output argument.",
+        },
+        {
+            "path": "sample-apps/python-app/src/smelly_pricing.py",
+            "obj": "calculate_total",
+            "line": 5,
+            "column": 0,
+            "symbol": "missing-function-docstring",
+            "message": "Not part of semantic trigger handoff.",
+        },
+    ]
+    ruff_results = [
+        {
+            "filename": "sample-apps/python-app/src/smelly_pricing.py",
+            "location": {"row": 12, "column": 8},
+            "code": "PLR2004",
+            "message": "Magic value used in comparison.",
+        },
+        {
+            "filename": "sample-apps/python-app/src/smelly_pricing.py",
+            "location": {"row": 18, "column": 5},
+            "code": "TD003",
+            "message": "Missing issue link for this TODO.",
+        },
+        {
+            "filename": "sample-apps/python-app/src/smelly_pricing.py",
+            "location": {"row": 20, "column": 1},
+            "code": "E501",
+            "message": "Formatting-only rules are not semantic triggers.",
+        },
+    ]
+
+    candidates = merge_candidates(
+        [
+            *eslint_candidates(eslint_results),
+            *pylint_candidates(pylint_results),
+            *ruff_candidates(ruff_results),
+        ]
+    )
+    payload = candidate_payload(candidates)
+
+    assert payload["schema"] == "clean-code-review-candidates/v1"
+    assert payload["candidate_count"] == 6
+
+    assert {candidate["skill"] for candidate in payload["candidates"]} == {
+        "clean-code-mcp-reviewer"
+    }
+
+    typescript_candidates = [
+        candidate for candidate in payload["candidates"] if candidate["language"] == "typescript"
+    ]
+    python_candidates = [
+        candidate for candidate in payload["candidates"] if candidate["language"] == "python"
+    ]
+    assert len(typescript_candidates) == 2
+    assert {candidate["anchor"] for candidate in typescript_candidates} == {"line 12", "line 44"}
+    assert any(candidate["symbol"] == "calculate_total" for candidate in python_candidates)
+    assert any("too many arguments" in candidate["mcp_queries"][0] for candidate in python_candidates)
+    assert any(
+        trigger["tool"] == "pylint" and trigger["rule"] == "clean-code-output-argument-mutation"
+        for candidate in python_candidates
+        for trigger in candidate["triggers"]
+    )
+    assert any(
+        trigger["tool"] == "ruff" and trigger["rule"] == "TD003"
+        for candidate in python_candidates
+        for trigger in candidate["triggers"]
+    )
+
+    markdown = markdown_payload(candidates)
+    assert "Clean-Code Semantic Review Candidates" in markdown
+    assert "clean-code/no-boolean-flag-arguments" in markdown
+    assert "calculate_total" in markdown
+    assert "ruff/PLR2004" in markdown
+
+    print("clean_code_review_candidates_check=ok")
+
+
+if __name__ == "__main__":
+    main()