clean-code-tools 1.0.1

package/scripts/check_fastmcp_server.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import asyncio
+from typing import Any, cast
+
+from _mcp_app import load_server_module
+
+
+async def main() -> None:
+    try:
+        from fastmcp import Client
+    except ImportError as exc:
+        raise SystemExit(
+            "Install FastMCP to run this check: python3 -m pip install 'fastmcp>=2.0.0'"
+        ) from exc
+
+    mcp_server = cast(Any, load_server_module())
+
+    def fake_search_pattern_records(**_: object) -> dict[str, object]:
+        return {
+            "query": "stub",
+            "filters_applied": {},
+            "no_strong_match": False,
+            "results": [
+                {
+                    "pattern_id": "CC-043",
+                    "chunk_id": "pattern:CC-043",
+                    "title": "Flag Arguments",
+                    "topic": "Chapter 3: Functions",
+                    "rule_family": "functions",
+                    "lintability": "high",
+                    "languages": ["typescript", "python"],
+                    "aliases": ["flag argument", "boolean parameter"],
+                    "lint_candidates": ["Replace boolean modes with named functions."],
+                    "source_kind": "clean_code_pattern",
+                    "chunk_kind": "pattern_record",
+                    "score": 0.91,
+                    "confidence": "high",
+                    "distance": 0.09,
+                    "match_reasons": ["matched exact terms: flag argument"],
+                }
+            ],
+        }
+
+    mcp_server.search_pattern_records = fake_search_pattern_records
+
+    async with Client(mcp_server.mcp) as client:
+        tools = await client.list_tools()
+        tool_names = {tool.name for tool in tools}
+        assert {
+            "clean_code_corpus_summary",
+            "clean_code_weaviate_schema",
+            "search_clean_code",
+            "search_clean_code_patterns",
+            "get_clean_code_pattern",
+            "recommend_clean_code_lint_rules",
+            "list_clean_code_facets",
+        } <= tool_names
+
+        resources = await client.list_resources()
+        resource_uris = {str(resource.uri) for resource in resources}
+        assert "clean-code://corpus/summary" in resource_uris
+        assert "clean-code://weaviate/schema" in resource_uris
+
+        summary = await client.call_tool("clean_code_corpus_summary", {})
+        summary_data = summary.data
+        assert summary_data["chunks"] >= 560
+        assert summary_data["by_kind"]["pattern_record"] == 264
+
+        schema = await client.call_tool("clean_code_weaviate_schema", {})
+        schema_data = schema.data
+        assert schema_data["class"] == "CleanCodeChunks"
+        assert schema_data["vectorConfig"]["content"]["vectorizer"] == {"none": {}}
+
+        pattern = await client.call_tool("get_clean_code_pattern", {"pattern_id": "CC-043"})
+        pattern_data = pattern.data
+        assert pattern_data["id"] == "CC-043"
+        assert "flag argument" in " ".join(pattern_data["aliases"])
+
+        facets = await client.call_tool("list_clean_code_facets", {})
+        facet_data = facets.data
+        assert facet_data["rule_families"]["functions"] >= 1
+        assert facet_data["languages"]["typescript"] >= 1
+
+        search = await client.call_tool(
+            "search_clean_code_patterns",
+            {"query": "typescript boolean flag argument", "language": "typescript"},
+        )
+        search_data = search.data
+        assert search_data["results"][0]["pattern_id"] == "CC-043"
+        assert search_data["no_strong_match"] is False
+
+        recommendations = await client.call_tool(
+            "recommend_clean_code_lint_rules",
+            {"query": "typescript boolean flag argument", "language": "typescript"},
+        )
+        recommendation_data = recommendations.data
+        assert recommendation_data["results"][0]["pattern_id"] == "CC-043"
+        assert recommendation_data["results"][0]["targets"] == ["eslint", "semgrep"]
+
+    print("fastmcp_server_check=ok")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/scripts/check_packages.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run(command: list[str], *, cwd: Path = ROOT, check: bool = True) -> subprocess.CompletedProcess[str]:
+    completed = subprocess.run(
+        command,
+        cwd=cwd,
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    if check and completed.returncode != 0:
+        print(completed.stdout)
+        raise SystemExit(completed.returncode)
+    return completed
+
+
+def check_npm_package() -> None:
+    packed = run(["npm", "pack", "--dry-run", "--json"]).stdout
+    package_files = {item["path"] for item in json.loads(packed)[0]["files"]}
+    required_files = {
+        "src/js/eslint-plugin-clean-code.mjs",
+        "configs/eslint.clean-code.recommended.mjs",
+        "configs/python.clean-code.pyproject.toml",
+        "data/clean-code-patterns.jsonl",
+        "data/vector-record.schema.json",
+        "src/python/clean_code_tools_pylint/__init__.py",
+        "src/python/clean_code_tools_pylint/ast_checker.py",
+        "src/python/clean_code_tools_pylint/comments.py",
+        "src/python/clean_code_tools_pylint/helpers.py",
+    }
+    missing_files = sorted(required_files - package_files)
+    if missing_files:
+        raise SystemExit(f"npm package missing files: {', '.join(missing_files)}")
+
+
+def check_version_parity() -> None:
+    package_json = json.loads((ROOT / "package.json").read_text())
+    try:
+        import tomllib
+    except ImportError as exc:  # pragma: no cover - Python 3.12 project
+        raise SystemExit("Python 3.11+ is required for tomllib") from exc
+    pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
+    npm_version = package_json["version"]
+    python_version = pyproject["project"]["version"]
+    if npm_version == python_version:
+        return
+    raise SystemExit(
+        f"Package versions must match for dual publishing: npm={npm_version}, python={python_version}"
+    )
+
+
+def venv_executable(venv: Path, executable: str) -> Path:
+    return venv / "bin" / executable
+
+
+def installed_python_config(venv: Path) -> str:
+    script = (
+        "from importlib.resources import files\n"
+        "print(files('clean_code_tools_pylint').joinpath("
+        "'configs/python.clean-code.pyproject.toml').read_text())\n"
+    )
+    return run([str(venv_executable(venv, "python")), "-c", script], cwd=venv).stdout
+
+
+def check_python_package() -> None:
+    with tempfile.TemporaryDirectory(prefix="clean-code-package-") as raw_tmp:
+        tmp = Path(raw_tmp)
+        dist = tmp / "dist"
+        run(["uv", "build", "--wheel", "--out-dir", str(dist)])
+        wheels = sorted(dist.glob("clean_code_tools_python-*.whl"))
+        if not wheels:
+            raise SystemExit("Expected uv build to create a clean-code-tools-python wheel")
+
+        venv = tmp / ".venv"
+        run([sys.executable, "-m", "venv", str(venv)])
+        run([str(venv_executable(venv, "python")), "-m", "pip", "install", "--quiet", str(wheels[-1])])
+
+        fixture = tmp / "fixture"
+        fixture.mkdir()
+        (fixture / "pyproject.toml").write_text(installed_python_config(venv))
+        (fixture / "smelly.py").write_text(
+            """
+# TODO clean this up
+# old_result = calculate_total(order)
+
+def calculate_total(order, include_tax, dry_run, retry, verbose, mode):
+    if order.status == "pending":
+        order["status"] = "retry"
+        calculate_total(order, True, False, False, False, "mode")
+        return 5
+    return 0
+""".lstrip(),
+        )
+
+        ruff = run([str(venv_executable(venv, "ruff")), "check", "smelly.py"], cwd=fixture, check=False)
+        pylint = run(
+            [
+                str(venv_executable(venv, "pylint")),
+                "--rcfile=pyproject.toml",
+                "smelly.py",
+            ],
+            cwd=fixture,
+            check=False,
+        )
+        if ruff.returncode == 0 or pylint.returncode == 0:
+            print(ruff.stdout)
+            print(pylint.stdout)
+            raise SystemExit("Expected installed package lint commands to report findings")
+        for code in ["TD002", "TD003", "ERA001"]:
+            if code not in ruff.stdout:
+                print(ruff.stdout)
+                raise SystemExit(f"Expected installed Ruff output to include {code}")
+        for code in ["C9001", "C9002", "C9003", "C9004", "C9007"]:
+            if code not in pylint.stdout:
+                print(pylint.stdout)
+                raise SystemExit(f"Expected installed Pylint output to include {code}")
+
+def main() -> None:
+    check_version_parity()
+    check_npm_package()
+    check_python_package()
+    print("package_checks=ok")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/check_python_config.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+PYTHON_SRC = ROOT / "src" / "python"
+CONFIG = ROOT / "configs" / "python.clean-code.pyproject.toml"
+
+
+def run(command: list[str], cwd: Path, check: bool = True) -> subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    env["PYTHONPATH"] = f"{PYTHON_SRC}:{env.get('PYTHONPATH', '')}".rstrip(":")
+    completed = subprocess.run(
+        command,
+        cwd=cwd,
+        env=env,
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    if check and completed.returncode != 0:
+        print(completed.stdout)
+        raise SystemExit(completed.returncode)
+    return completed
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory(prefix="clean-code-python-config-") as raw_tmp:
+        tmp = Path(raw_tmp)
+        shutil.copyfile(CONFIG, tmp / "pyproject.toml")
+
+        (tmp / "sample.py").write_text(
+            """
+MAX_ATTEMPTS = 5
+
+
+def can_retry(failed_attempts: int) -> bool:
+    return failed_attempts < MAX_ATTEMPTS
+""".lstrip(),
+        )
+        (tmp / "smelly.py").write_text(
+            """
+# TODO clean this up
+# old_result = calculate_total(order)
+
+def calculate_total(order, include_tax, dry_run, retry, verbose, mode):
+    if order.status == "pending":
+        return 5
+    return 0
+""".lstrip(),
+        )
+
+        run(["uv", "run", "--project", str(ROOT), "--group", "lint", "ruff", "check", "sample.py"], cwd=tmp)
+        run(
+            [
+                "uv",
+                "run",
+                "--project",
+                str(ROOT),
+                "--group",
+                "lint",
+                "pylint",
+                "--rcfile=pyproject.toml",
+                "sample.py",
+            ],
+            cwd=tmp,
+        )
+
+        ruff_smelly = run(
+            ["uv", "run", "--project", str(ROOT), "--group", "lint", "ruff", "check", "smelly.py"],
+            cwd=tmp,
+            check=False,
+        )
+        pylint_smelly = run(
+            [
+                "uv",
+                "run",
+                "--project",
+                str(ROOT),
+                "--group",
+                "lint",
+                "pylint",
+                "--rcfile=pyproject.toml",
+                "smelly.py",
+            ],
+            cwd=tmp,
+            check=False,
+        )
+
+        if ruff_smelly.returncode == 0:
+            print("Expected Ruff to report clean-code findings for smelly.py")
+            raise SystemExit(1)
+        if pylint_smelly.returncode == 0:
+            print("Expected Pylint to report design findings for smelly.py")
+            raise SystemExit(1)
+
+        ruff_output = ruff_smelly.stdout
+        pylint_output = pylint_smelly.stdout
+        required_ruff_codes = ["TD002", "TD003", "ERA001", "ARG001"]
+        required_pylint_codes = ["R0913", "C9001", "C9002", "C9007"]
+        forbidden_codes = ["FIX002", "R0917"]
+
+        for code in required_ruff_codes:
+            if code not in ruff_output:
+                print(ruff_output)
+                raise SystemExit(f"Expected Ruff output to include {code}")
+        for code in required_pylint_codes:
+            if code not in pylint_output:
+                print(pylint_output)
+                raise SystemExit(f"Expected Pylint output to include {code}")
+        for code in forbidden_codes:
+            combined = f"{ruff_output}\n{pylint_output}"
+            if code in combined:
+                print(combined)
+                raise SystemExit(f"Did not expect duplicate/noisy code {code}")
+        if "bad-plugin-value" in combined or "unknown-option-value" in combined:
+            print(combined)
+            raise SystemExit("Expected custom Pylint plugin to load cleanly")
+
+        print("python_config_check=ok")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/check_repo_python_lint.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+PYTHON_SRC = ROOT / "src" / "python"
+PYTHON_TARGETS = [
+    "src/python/clean_code_tools_pylint",
+    "src/python/mcp_server",
+    "scripts",
+]
+PYLINT_TARGETS = [
+    "src/python/clean_code_tools_pylint",
+    "src/python/mcp_server",
+]
+
+
+def run(command: list[str], *, cwd: Path = ROOT) -> subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    env["PYTHONPATH"] = f"{PYTHON_SRC}:{env.get('PYTHONPATH', '')}".rstrip(":")
+    completed = subprocess.run(
+        command,
+        cwd=cwd,
+        env=env,
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    if completed.returncode != 0:
+        print(completed.stdout)
+        raise SystemExit(completed.returncode)
+    return completed
+
+
+def main() -> None:
+    run(["uv", "run", "--group", "lint", "ruff", "check", *PYTHON_TARGETS])
+    run(["uv", "run", "--group", "lint", "pylint", *PYLINT_TARGETS])
+    print("repo_python_lint_check=ok")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/check_retrieval_evals.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from _mcp_app import load_semantic_module
+
+ROOT = Path(__file__).resolve().parents[1]
+EVALS = ROOT / "evals" / "clean-code-retrieval.jsonl"
+
+
+def main() -> None:
+    semantic = load_semantic_module()
+    cases = [json.loads(line) for line in EVALS.read_text().splitlines() if line.strip()]
+    failures: list[str] = []
+    metrics = empty_metrics()
+    for case in cases:
+        payload = local_search_payload(semantic, case)
+        failures.extend(evaluate_case(case, payload, metrics))
+    failures.extend(production_ranking_checks(semantic))
+
+    if failures:
+        raise SystemExit("\n".join(failures))
+    print(
+        "retrieval_eval_check=ok "
+        f"cases={len(cases)} "
+        f"top1={metrics['top1_correct']} "
+        f"top5={metrics['top5_recall']} "
+        f"strong_calibration={metrics['strong_calibration']} "
+        f"duplicate_failures={metrics['duplicate_failures']} "
+        f"markdown_pollution={metrics['markdown_pollution']}"
+    )
+
+
+def local_search_payload(semantic: Any, case: dict[str, Any]) -> dict[str, Any]:
+    return semantic.rank_pattern_rows(
+        query=str(case["query"]),
+        vector_rows=mock_vector_rows(semantic, case),
+        limit=8,
+        language=str(case.get("language", "any")),
+        source_kinds=("clean_code_pattern",),
+    )
+
+
+def mock_vector_rows(semantic: Any, case: dict[str, Any]) -> list[dict[str, Any]]:
+    chunks = {
+        chunk.record_id: chunk
+        for chunk in semantic.build_chunks()
+        if chunk.chunk_kind == "pattern_record"
+    }
+    rows: list[dict[str, Any]] = []
+    for index, pattern_id in enumerate(case.get("vector_ids", [])):
+        chunk = chunks.get(pattern_id)
+        if chunk is not None:
+            rows.append(chunk.properties | {"_additional": {"id": chunk.object_id, "distance": 0.20 + index * 0.05}})
+    return rows
+
+
+def empty_metrics() -> dict[str, int]:
+    return {
+        "top1_correct": 0,
+        "top5_recall": 0,
+        "strong_calibration": 0,
+        "duplicate_failures": 0,
+        "markdown_pollution": 0,
+    }
+
+
+def evaluate_case(
+    case: dict[str, Any],
+    payload: dict[str, Any],
+    metrics: dict[str, int],
+) -> list[str]:
+    results = payload["results"][:5]
+    ids = [str(result["pattern_id"]) for result in results]
+    expected = set(case["expected_top_ids"])
+    failures: list[str] = []
+
+    if expected and ids[:1] and ids[0] in expected:
+        metrics["top1_correct"] += 1
+    if not expected or expected & set(ids):
+        metrics["top5_recall"] += 1
+    if bool(case["should_strong_match"]) != bool(payload["no_strong_match"]):
+        metrics["strong_calibration"] += 1
+    if len(ids) != len(set(ids)):
+        metrics["duplicate_failures"] += 1
+        failures.append(f"{case['id']}: duplicate pattern IDs in top 5: {ids}")
+    if any(result.get("source_kind") != "clean_code_pattern" for result in results):
+        metrics["markdown_pollution"] += 1
+
+    if case["should_strong_match"]:
+        if not expected & set(ids[:3]):
+            failures.append(f"{case['id']}: expected one of {sorted(expected)} in top 3, got {ids[:3]}")
+        if payload["no_strong_match"]:
+            failures.append(f"{case['id']}: expected strong match")
+    elif not payload["no_strong_match"]:
+        failures.append(f"{case['id']}: expected no_strong_match")
+    if expected and not case["should_strong_match"] and not expected & set(ids):
+        failures.append(f"{case['id']}: expected relevant pattern {sorted(expected)} in top 5, got {ids}")
+    return failures
+
+
+def production_ranking_checks(semantic: Any) -> list[str]:
+    chunks = {chunk.chunk_id: chunk for chunk in semantic.build_chunks()}
+    pattern = chunks["pattern:CC-043"]
+    markdown = next(chunk for chunk in chunks.values() if chunk.source_kind == "markdown_doc")
+    payload = semantic.rank_pattern_rows(
+        query="typescript boolean flag argument",
+        vector_rows=[
+            markdown.properties | {"_additional": {"id": markdown.object_id, "distance": 0.01}},
+            pattern.properties | {"_additional": {"id": pattern.object_id, "distance": 0.40}},
+            pattern.properties | {"_additional": {"id": pattern.object_id, "distance": 0.10}},
+        ],
+        limit=5,
+        language="typescript",
+        source_kinds=("clean_code_pattern",),
+    )
+    ids = [result["pattern_id"] for result in payload["results"]]
+    failures: list[str] = []
+    if ids.count("CC-043") != 1:
+        failures.append(f"production-ranking: expected deduped CC-043 once, got {ids}")
+    if payload["results"][0]["source_kind"] != "clean_code_pattern":
+        failures.append("production-ranking: markdown vector row was not filtered out")
+    if payload["results"][0]["distance"] != 0.1:
+        failures.append(f"production-ranking: expected best vector distance 0.1, got {payload['results'][0]['distance']}")
+    return failures
+
+
+if __name__ == "__main__":
+    main()