clean-code-tools 1.0.1

package/scripts/check_sample_apps.py

@@ -0,0 +1,169 @@
+#!/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"
+
+
+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 check_python_app() -> None:
+    with tempfile.TemporaryDirectory(prefix="clean-code-python-sample-"):
+        app = ROOT / "sample-apps" / "python-app"
+
+        run(
+            [
+                "uv",
+                "run",
+                "--project",
+                str(ROOT),
+                "--group",
+                "lint",
+                "ruff",
+                "check",
+                "src/clean_pricing.py",
+            ],
+            cwd=app,
+        )
+        run(
+            [
+                "uv",
+                "run",
+                "--project",
+                str(ROOT),
+                "--group",
+                "lint",
+                "pylint",
+                "--rcfile=pyproject.toml",
+                "src/clean_pricing.py",
+            ],
+            cwd=app,
+        )
+
+        ruff_smelly = run(
+            [
+                "uv",
+                "run",
+                "--project",
+                str(ROOT),
+                "--group",
+                "lint",
+                "ruff",
+                "check",
+                "src/smelly_pricing.py",
+            ],
+            cwd=app,
+            check=False,
+        )
+        pylint_smelly = run(
+            [
+                "uv",
+                "run",
+                "--project",
+                str(ROOT),
+                "--group",
+                "lint",
+                "pylint",
+                "--rcfile=pyproject.toml",
+                "src/smelly_pricing.py",
+            ],
+            cwd=app,
+            check=False,
+        )
+        if ruff_smelly.returncode == 0 or pylint_smelly.returncode == 0:
+            print(ruff_smelly.stdout)
+            print(pylint_smelly.stdout)
+            raise SystemExit("Expected Python smelly sample to fail linting")
+
+        for code in ["TD002", "TD003", "ERA001", "ARG001"]:
+            if code not in ruff_smelly.stdout:
+                print(ruff_smelly.stdout)
+                raise SystemExit(f"Expected Python smelly Ruff output to include {code}")
+        for code in ["R0913", "C9001", "C9002", "C9007"]:
+            if code not in pylint_smelly.stdout:
+                print(pylint_smelly.stdout)
+                raise SystemExit(f"Expected Python smelly Pylint output to include {code}")
+        if "bad-plugin-value" in pylint_smelly.stdout or "unknown-option-value" in pylint_smelly.stdout:
+            print(pylint_smelly.stdout)
+            raise SystemExit("Expected Python smelly Pylint plugin to load cleanly")
+
+
+def check_ts_app(app_name: str, clean_script: str, smelly_script: str, expected_rule_ids: list[str]) -> None:
+    with tempfile.TemporaryDirectory(prefix=f"clean-code-{app_name}-") as raw_tmp:
+        tmp = Path(raw_tmp)
+        package_json = ROOT / "sample-apps" / app_name / "package.json"
+        package_text = package_json.read_text()
+        packed = run(["npm", "pack", "--silent"], cwd=ROOT).stdout.strip().splitlines()[-1]
+        tarball = ROOT / packed
+        try:
+            shutil.copytree(ROOT / "sample-apps" / app_name, tmp / app_name)
+            isolated_app = tmp / app_name
+            isolated_package = package_text.replace('"clean-code-tools": "file:../.."', f'"clean-code-tools": "{tarball}"')
+            (isolated_app / "package.json").write_text(isolated_package)
+            run(["bun", "install"], cwd=isolated_app)
+            run(["bun", "run", clean_script], cwd=isolated_app)
+            smelly = run(["bun", "run", smelly_script], cwd=isolated_app, check=False)
+            if smelly.returncode == 0:
+                print(smelly.stdout)
+                raise SystemExit(f"Expected isolated {app_name} smelly script to fail linting")
+            for rule_id in expected_rule_ids:
+                if rule_id not in smelly.stdout:
+                    print(smelly.stdout)
+                    raise SystemExit(f"Expected isolated {app_name} output to include {rule_id}")
+        finally:
+            tarball.unlink(missing_ok=True)
+
+
+def main() -> None:
+    check_python_app()
+    check_ts_app(
+        "ts-backend",
+        "lint:clean",
+        "lint:smelly",
+        [
+            "clean-code/todo-format",
+            "clean-code/no-commented-out-code",
+            "clean-code/no-boolean-flag-arguments",
+            "clean-code/no-business-policy-literals",
+            "clean-code/no-train-wrecks",
+        ],
+    )
+    check_ts_app(
+        "ts-frontend",
+        "lint:clean",
+        "lint:smelly",
+        [
+            "clean-code/todo-format",
+            "clean-code/no-commented-out-code",
+            "clean-code/no-output-argument-mutation",
+            "clean-code/no-business-policy-literals",
+            "clean-code/no-train-wrecks",
+        ],
+    )
+    print("sample_apps_check=ok")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/check_semantic_search_tooling.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import tempfile
+import uuid
+from pathlib import Path
+
+from _mcp_app import load_semantic_module
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main() -> None:
+    semantic = load_semantic_module()
+
+    chunks = semantic.build_chunks()
+
+    by_kind = {}
+    for chunk in chunks:
+        by_kind[chunk.chunk_kind] = by_kind.get(chunk.chunk_kind, 0) + 1
+    assert by_kind["pattern_record"] == 264
+    assert by_kind["markdown_section"] >= 40
+    assert len({chunk.chunk_id for chunk in chunks}) == len(chunks)
+    assert len({chunk.object_id for chunk in chunks}) == len(chunks)
+    for chunk in chunks:
+        uuid.UUID(chunk.object_id)
+        assert chunk.embedding_text
+        assert chunk.text_hash == semantic.sha256_text(chunk.embedding_text)
+
+    by_chunk_id = {chunk.chunk_id: chunk for chunk in chunks}
+    assert "pattern:CC-043" in by_chunk_id
+    assert "pattern:CC-068" in by_chunk_id
+    assert "pattern:CC-107" in by_chunk_id
+    assert by_chunk_id["pattern:CC-043"].languages == ("typescript", "python")
+    assert "flag argument" in " ".join(by_chunk_id["pattern:CC-043"].aliases)
+
+    schema = semantic.create_schema_payload()
+    assert schema["class"] == semantic.COLLECTION_NAME
+    assert schema["vectorConfig"][semantic.VECTOR_NAME]["vectorizer"] == {"none": {}}
+    property_names = {property_config["name"] for property_config in schema["properties"]}
+    for required in (
+        "chunkId",
+        "recordId",
+        "sourceFile",
+        "sourceKind",
+        "sectionPath",
+        "ruleFamily",
+        "lintability",
+        "embeddingText",
+        "textHash",
+        "embeddingModel",
+    ):
+        assert required in property_names
+
+    query = semantic.build_search_graphql_query(
+        collection_name=semantic.COLLECTION_NAME,
+        vector=[0.1, 0.2, 0.3],
+        limit=5,
+    )
+    assert "nearVector" in query
+    assert 'targetVectors: ["content"]' in query
+    assert "chunkId recordId sourceFile" in query
+
+    payload = {"data": {"Get": {semantic.COLLECTION_NAME: [{"chunkId": "pattern:CC-043"}]}}}
+    assert semantic.search_rows_from_payload(
+        payload,
+        collection_name=semantic.COLLECTION_NAME,
+    ) == [{"chunkId": "pattern:CC-043"}]
+    assert semantic.search_rows_from_payload({}, collection_name=semantic.COLLECTION_NAME) == []
+    try:
+        semantic.search_rows_from_payload(
+            {"errors": [{"message": "bad query"}]},
+            collection_name=semantic.COLLECTION_NAME,
+        )
+    except RuntimeError as exc:
+        assert "bad query" in str(exc)
+    else:
+        raise AssertionError("expected Weaviate GraphQL errors to raise")
+
+    with tempfile.TemporaryDirectory() as raw_tmp:
+        tmp = Path(raw_tmp)
+        doc = tmp / "sample.md"
+        doc.write_text(
+            "# Root\n\n"
+            "Intro.\n\n"
+            "## Section\n\n"
+            "Before.\n\n"
+            "```ts\n"
+            "const heading = '## not a heading';\n"
+            "```\n\n"
+            "After.\n"
+        )
+        sections = semantic.markdown_sections(doc, root=tmp)
+        assert len(sections) == 2
+        assert sections[1].heading == "Section"
+        assert "## not a heading" in sections[1].body
+
+    print("semantic_search_tooling_check=ok")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/clean_code_eslint_triggers.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from clean_code_review_models import TriggerRule
+
+ESLINT_TRIGGERS = {
+    "@typescript-eslint/naming-convention": TriggerRule(
+        questions=(
+            "Is the name hiding domain meaning or using inconsistent terminology?",
+            "Would renaming improve call-site readability without changing behavior?",
+        ),
+        mcp_query="typescript naming consistency intention revealing names",
+    ),
+    "@typescript-eslint/consistent-type-imports": TriggerRule(
+        questions=(
+            "Are runtime imports being used only for types?",
+            "Would type-only imports clarify the module's runtime dependency boundary?",
+        ),
+        mcp_query="typescript type only imports runtime dependency boundary",
+    ),
+    "@typescript-eslint/no-confusing-void-expression": TriggerRule(
+        questions=(
+            "Is this expression mixing side effects with value flow?",
+            "Would separating the side effect from the return value clarify intent?",
+        ),
+        mcp_query="typescript confusing void expression separate side effects values",
+    ),
+    "@typescript-eslint/no-magic-numbers": TriggerRule(
+        questions=(
+            "Does this number encode business policy or a domain threshold?",
+            "Would a named constant make the rule searchable and easier to change?",
+        ),
+        mcp_query="typescript magic number named constant business policy",
+    ),
+    "@typescript-eslint/no-unnecessary-condition": TriggerRule(
+        questions=(
+            "Is this branch dead or protecting against an impossible state?",
+            "Would removing it clarify the real contract?",
+        ),
+        mcp_query="typescript unnecessary condition dead branch explicit contract",
+    ),
+    "@typescript-eslint/no-unnecessary-type-assertion": TriggerRule(
+        questions=(
+            "Is the assertion hiding a type contract that is already known?",
+            "Would removing it make the trusted shape clearer?",
+        ),
+        mcp_query="typescript unnecessary type assertion trusted shape contract",
+    ),
+    "@typescript-eslint/no-unused-vars": TriggerRule(
+        questions=(
+            "Is this dead code or a half-removed responsibility?",
+            "Can it be deleted safely without changing behavior?",
+        ),
+        mcp_query="typescript unused variable dead code remove safely",
+    ),
+    "@typescript-eslint/prefer-nullish-coalescing": TriggerRule(
+        questions=(
+            "Is falsy handling being confused with absence handling?",
+            "Would explicit nullish logic make the data contract clearer?",
+        ),
+        mcp_query="typescript nullish coalescing absence contract",
+    ),
+    "@typescript-eslint/strict-boolean-expressions": TriggerRule(
+        questions=(
+            "Is truthiness hiding the distinction between absence, empty values, and false?",
+            "Would an explicit predicate or comparison make the condition safer to read?",
+        ),
+        mcp_query="typescript strict boolean expressions explicit predicate truthiness",
+    ),
+    "@typescript-eslint/switch-exhaustiveness-check": TriggerRule(
+        questions=(
+            "Is variant handling incomplete or scattered?",
+            "Would an exhaustive branch make the domain states explicit?",
+        ),
+        mcp_query="typescript exhaustive switch discriminated union explicit states",
+    ),
+    "clean-code/no-boolean-flag-arguments": TriggerRule(
+        questions=(
+            "Does the boolean select behavior rather than represent plain data?",
+            "Would intention-revealing functions make call sites clearer?",
+        ),
+        mcp_query="typescript boolean flag argument intention revealing functions",
+    ),
+    "clean-code/no-business-policy-literals": TriggerRule(
+        questions=(
+            "Does this literal encode business policy or domain state?",
+            "Would a named constant or typed domain value make changes safer?",
+        ),
+        mcp_query="typescript business policy literal named constant domain state",
+    ),
+    "clean-code/no-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="typescript commented out code remove obsolete implementation",
+    ),
+    "clean-code/no-noisy-comments": 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="typescript noisy comments remove visual separators byline comments",
+    ),
+    "clean-code/no-output-argument-mutation": TriggerRule(
+        questions=(
+            "Is mutation hidden behind an output parameter?",
+            "Would returning a value make the contract clearer?",
+        ),
+        mcp_query="typescript output argument mutation return value contract",
+    ),
+    "clean-code/no-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="typescript redundant comment intention revealing code",
+    ),
+    "clean-code/no-train-wrecks": 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="typescript train wreck law of demeter object navigation",
+    ),
+    "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="typescript todo comment issue id actionable technical debt",
+    ),
+    "complexity": TriggerRule(
+        questions=(
+            "Is this function mixing validation, transformation, branching, and side effects?",
+            "Can guard clauses or cohesive helper extraction reduce branching?",
+        ),
+        mcp_query="typescript high complexity function mixed responsibilities guard clauses",
+    ),
+    "max-depth": TriggerRule(
+        questions=(
+            "Is rightward drift hiding the normal path?",
+            "Can early returns, named predicates, or smaller functions flatten the flow?",
+        ),
+        mcp_query="typescript deeply nested conditionals guard clauses readability",
+    ),
+    "max-lines": TriggerRule(
+        questions=(
+            "Does this file contain multiple reasons to change?",
+            "Are there cohesive module boundaries that preserve the public API?",
+        ),
+        mcp_query="typescript large file single responsibility extraction boundaries",
+    ),
+    "max-lines-per-function": TriggerRule(
+        questions=(
+            "Does this function do more than one job?",
+            "Can stable parsing, validation, transformation, or side-effect steps be separated?",
+        ),
+        mcp_query="typescript long function split validation transformation side effects",
+    ),
+    "max-params": TriggerRule(
+        questions=(
+            "Do these parameters travel together as a named concept?",
+            "Would a typed object parameter improve call-site clarity?",
+        ),
+        mcp_query="typescript long parameter list object parameter call site clarity",
+    ),
+    "no-empty": TriggerRule(
+        questions=(
+            "Is this empty block hiding ignored behavior or an incomplete branch?",
+            "Should the code handle, document, or remove the branch explicitly?",
+        ),
+        mcp_query="typescript empty block ignored behavior explicit handling",
+    ),
+    "no-negated-condition": TriggerRule(
+        questions=(
+            "Is the negative branch making the normal path harder to follow?",
+            "Would a positive predicate or guard clause clarify the condition?",
+        ),
+        mcp_query="typescript negated condition positive predicate guard clause",
+    ),
+    "no-nested-ternary": TriggerRule(
+        questions=(
+            "Is dense expression logic hiding a decision table or branching policy?",
+            "Would named intermediate values or ordinary branches improve readability?",
+        ),
+        mcp_query="typescript nested ternary decision logic readability",
+    ),
+    "no-restricted-syntax": TriggerRule(
+        questions=(
+            "Is this import list signaling an overly broad module boundary?",
+            "Would a narrower module, namespace import, or split dependency improve scanability?",
+        ),
+        mcp_query="typescript long import list module boundary readability",
+    ),
+    "no-useless-return": TriggerRule(
+        questions=(
+            "Is redundant control flow adding noise to the function ending?",
+            "Can the return path be simplified without changing behavior?",
+        ),
+        mcp_query="typescript useless return redundant control flow",
+    ),
+    "sonarjs/cognitive-complexity": TriggerRule(
+        questions=(
+            "Which branches force a reader to retain too much context?",
+            "Can conditions be named or decision logic isolated?",
+        ),
+        mcp_query="typescript cognitive complexity named predicates decision logic",
+    ),
+    "sonarjs/no-dead-store": TriggerRule(
+        questions=(
+            "Is this assignment dead code or evidence of an incomplete refactor?",
+            "Can the unused state or surrounding responsibility be removed?",
+        ),
+        mcp_query="typescript dead store incomplete refactor unused state",
+    ),
+    "sonarjs/no-duplicate-string": TriggerRule(
+        questions=(
+            "Is this repeated string a domain value, message, or policy token?",
+            "Would naming it avoid drift between copies?",
+        ),
+        mcp_query="typescript duplicate string named constant policy drift",
+    ),
+    "sonarjs/no-duplicated-branches": TriggerRule(
+        questions=(
+            "Is duplicated branching hiding a missing abstraction or a bug?",
+            "Can the condition or branch body be simplified safely?",
+        ),
+        mcp_query="typescript duplicated branches conditional simplification",
+    ),
+    "sonarjs/no-identical-conditions": TriggerRule(
+        questions=(
+            "Is repeated conditional logic hiding a copy/paste mistake or missing predicate?",
+            "Can the branching model be simplified safely?",
+        ),
+        mcp_query="typescript identical conditions duplicated predicate branch bug",
+    ),
+    "sonarjs/no-identical-functions": TriggerRule(
+        questions=(
+            "Is this real duplication or a coincidental framework shape?",
+            "Can a shared helper remove policy drift without hiding intent?",
+        ),
+        mcp_query="typescript duplicated functions shared helper policy drift",
+    ),
+    "sonarjs/no-inverted-boolean-check": TriggerRule(
+        questions=(
+            "Is inverted boolean logic making the condition harder to read?",
+            "Would a positive predicate or renamed boolean clarify intent?",
+        ),
+        mcp_query="typescript inverted boolean check positive predicate naming",
+    ),
+    "unicorn/explicit-length-check": TriggerRule(
+        questions=(
+            "Is collection emptiness being expressed indirectly?",
+            "Would an explicit length comparison clarify the condition?",
+        ),
+        mcp_query="typescript explicit length check collection emptiness",
+    ),
+    "unicorn/no-negated-condition": TriggerRule(
+        questions=(
+            "Is the negative branch making the normal path harder to follow?",
+            "Would a positive predicate or guard clause clarify the condition?",
+        ),
+        mcp_query="typescript negated condition positive predicate guard clause",
+    ),
+    "unicorn/no-null": TriggerRule(
+        questions=(
+            "Is null being used as an ambiguous absence value?",
+            "Does the surrounding code prefer undefined, option-like objects, or explicit states?",
+        ),
+        mcp_query="typescript null absence value explicit state contract",
+    ),
+}

package/scripts/clean_code_mcp_server.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+from _mcp_app import load_server_module
+
+if __name__ == "__main__":
+    load_server_module().main()