clean-code-tools 1.0.1

package/scripts/clean_code_semantic.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+
+from _mcp_app import load_semantic_module
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Inspect clean-code semantic chunks.")
+    parser.add_argument("--json", action="store_true", help="Print chunks as JSONL.")
+    args = parser.parse_args()
+    semantic = load_semantic_module()
+    chunks = semantic.build_chunks()
+    if args.json:
+        for chunk in chunks:
+            print(json.dumps(chunk.properties, sort_keys=True))
+        return
+    by_kind: dict[str, int] = {}
+    for chunk in chunks:
+        by_kind[chunk.chunk_kind] = by_kind.get(chunk.chunk_kind, 0) + 1
+    print(json.dumps({"chunks": len(chunks), "by_kind": by_kind}, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/set_package_versions.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGE_JSON = ROOT / "package.json"
+PYPROJECT = ROOT / "pyproject.toml"
+RELEASE_VERSION_RE = re.compile(r"^\d+\.\d+\.\d+(?:[a-zA-Z0-9.-]+)?$")
+CORE_VERSION_RE = re.compile(r"^(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$")
+PYPROJECT_VERSION_RE = re.compile(r'(?m)^version = "([^"]+)"$')
+
+
+def package_version() -> str:
+    return str(json.loads(PACKAGE_JSON.read_text())["version"])
+
+
+def set_json_version(path: Path, version: str) -> None:
+    payload = json.loads(path.read_text())
+    payload["version"] = version
+    path.write_text(json.dumps(payload, indent=2) + "\n")
+
+
+def set_pyproject_version(version: str) -> None:
+    text = PYPROJECT.read_text()
+    updated, count = PYPROJECT_VERSION_RE.subn(f'version = "{version}"', text, count=1)
+    if count != 1:
+        raise SystemExit("Expected exactly one [project] version in pyproject.toml")
+    PYPROJECT.write_text(updated)
+
+
+def set_versions(*, npm_version: str, python_version: str) -> None:
+    set_json_version(PACKAGE_JSON, npm_version)
+    set_pyproject_version(python_version)
+    print(f"npm_version={npm_version}")
+    print(f"python_version={python_version}")
+
+
+def bumped_version(base: str, part: str) -> str:
+    match = CORE_VERSION_RE.match(base)
+    if match is None:
+        raise SystemExit(f"Version bumps require a plain major.minor.patch base, got: {base}")
+    major = int(match.group("major"))
+    minor = int(match.group("minor"))
+    patch = int(match.group("patch"))
+    if part == "major":
+        return f"{major + 1}.0.0"
+    if part == "minor":
+        return f"{major}.{minor + 1}.0"
+    return f"{major}.{minor}.{patch + 1}"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Set coordinated npm and Python package versions.")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--release", help="Release version to write to both manifests, for example 1.2.3.")
+    group.add_argument("--bump", choices=("patch", "minor", "major"), help="Bump the base release version.")
+    parser.add_argument(
+        "--base",
+        default=None,
+        help="Base SemVer version for --bump. Defaults to package.json.",
+    )
+    args = parser.parse_args()
+
+    if args.release:
+        if not RELEASE_VERSION_RE.match(args.release):
+            raise SystemExit(f"Invalid release version: {args.release}")
+        set_versions(npm_version=args.release, python_version=args.release)
+        return
+
+    base = args.base or package_version()
+    if not RELEASE_VERSION_RE.match(base):
+        raise SystemExit(f"Invalid base version: {base}")
+    version = bumped_version(base, args.bump)
+    set_versions(npm_version=version, python_version=version)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/weaviate_ingest_clean_code.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+
+from _mcp_app import load_semantic_module
+
+semantic = load_semantic_module()
+DEFAULT_BATCH_SIZE = semantic.DEFAULT_BATCH_SIZE
+build_chunks = semantic.build_chunks
+ingest_chunks = semantic.ingest_chunks
+reset_collection = semantic.reset_collection
+
+
+def add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--url", default=semantic.DEFAULT_WEAVIATE_URL)
+    parser.add_argument("--collection", default=semantic.COLLECTION_NAME)
+    parser.add_argument("--model", default=semantic.DEFAULT_EMBEDDING_MODEL)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Ingest clean-code semantic chunks into Weaviate.")
+    add_common_args(parser)
+    parser.add_argument("--reset", action="store_true", help="Drop and recreate the collection first.")
+    parser.add_argument("--batch-size", type=int, default=DEFAULT_BATCH_SIZE)
+    args = parser.parse_args()
+
+    if args.batch_size < 1:
+        raise SystemExit("--batch-size must be at least 1")
+    if args.reset:
+        reset_collection(url=args.url, collection_name=args.collection)
+    chunks = build_chunks()
+    inserted = ingest_chunks(
+        chunks=chunks,
+        url=args.url,
+        collection_name=args.collection,
+        model_name=args.model,
+        batch_size=args.batch_size,
+    )
+    print(f"ingested={inserted} collection={args.collection}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/weaviate_search_clean_code.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+
+from _mcp_app import load_semantic_module
+
+semantic = load_semantic_module()
+search_chunks = semantic.search_chunks
+
+
+def add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--url", default=semantic.DEFAULT_WEAVIATE_URL)
+    parser.add_argument("--collection", default=semantic.COLLECTION_NAME)
+    parser.add_argument("--model", default=semantic.DEFAULT_EMBEDDING_MODEL)
+
+
+def print_search_results(results: list[dict[str, object]]) -> None:
+    for index, row in enumerate(results, start=1):
+        additional = row.get("_additional") or {}
+        distance = additional.get("distance", "?") if isinstance(additional, dict) else "?"
+        print(
+            f"{index}. {row.get('recordId') or row.get('chunkId')} "
+            f"{row.get('title')} distance={distance}"
+        )
+        print(f"   source={row.get('sourceFile')} kind={row.get('chunkKind', row.get('sourceKind'))}")
+        text = " ".join(str(row.get("contentText", "")).split())
+        print(f"   {text[:280]}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Search clean-code semantic chunks in Weaviate.")
+    add_common_args(parser)
+    parser.add_argument("query")
+    parser.add_argument("--limit", type=int, default=8)
+    args = parser.parse_args()
+
+    if args.limit < 1:
+        raise SystemExit("--limit must be at least 1")
+    results = search_chunks(
+        query=args.query,
+        url=args.url,
+        collection_name=args.collection,
+        model_name=args.model,
+        limit=args.limit,
+    )
+    print_search_results(results)
+
+
+if __name__ == "__main__":
+    main()

package/skills/clean-code-mcp-reviewer/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: clean-code-mcp-reviewer
+description: Use this skill whenever reviewing, refactoring, or designing lint checks for TypeScript, JavaScript, Python, or React code where clean-code patterns may help. This skill teaches agents how to use the clean-code MCP interactively: read code first, form concrete smell hypotheses, query the MCP narrowly, suppress weak matches, and apply only guidance anchored to local code evidence. Use it for maintainability reviews, readability concerns, refactor planning, and clean-code lint-rule design, even when the user does not explicitly mention MCP.
+---
+
+# Clean-Code MCP Reviewer
+
+Use the clean-code MCP as decision support, not as a generic style rulebook. The
+tool is valuable when a concrete code shape creates a maintainability decision:
+function boundaries, arguments, naming, side effects, comments, duplication,
+tests, error handling, literals, or object navigation.
+
+## Operating Principle
+
+Read the code before querying. A good MCP query starts from observed local
+evidence, not from the task title or a generic desire to "make it cleaner." The
+agent remains responsible for judging whether retrieved guidance fits the local
+framework, public API, tests, performance constraints, and project conventions.
+
+This skill is self-contained. Do not assume separate language-specific
+clean-code skills are installed. Use the language heuristics below when judging
+Python, JavaScript, TypeScript, or React code.
+
+## Refactor Discipline
+
+- Read formatter, linter, type-checker, framework, tests, and nearby files
+  before applying generic advice.
+- Name the concrete smell before proposing a cleanup.
+- Keep the refactor local unless the user asks for a broader redesign.
+- Preserve public APIs, return shapes, exception behavior, async boundaries,
+  mutability expectations, and framework contracts.
+- Prefer the smallest useful change: rename, flatten control flow, extract one
+  cohesive helper, introduce a stable data shape, or clarify an error boundary.
+- Avoid class hierarchies, speculative abstractions, trivial wrappers, and
+  extraction that hides the main logic.
+- Optimize for the call site: the best boundary makes the caller obviously
+  correct.
+- Verify that tests, lint, types, and the relevant runtime contract still hold.
+
+## When To Use The MCP
+
+Use the MCP when you have a specific clean-code concern:
+
+- following up deterministic lint triggers emitted as clean-code review
+  candidates
+- reviewing a possible maintainability finding
+- planning a behavior-preserving refactor
+- deciding whether a pattern is lintable
+- comparing alternative extraction, naming, or argument-shape choices
+- checking whether a repeated smell should become an ESLint, Ruff, Pylint, or
+  Semgrep rule
+
+Do not query for:
+
+- formatting-only edits
+- dependency bumps
+- obvious build/type errors
+- purely mechanical renames
+- generated files or migrations unless the user explicitly asks
+- code where local conventions or framework idioms already settle the decision
+
+## Query Workflow
+
+1. Inspect the changed code, nearby tests, and local conventions.
+2. Identify one concrete concern at a time.
+3. Summarize the concern as a smell hypothesis.
+4. Query `search_clean_code_patterns` with language and relevant filters.
+5. If a result looks useful, call `get_clean_code_pattern` for full detail.
+6. Use the pattern only when it matches a concrete code anchor.
+7. Say there is no strong clean-code match when results are generic or weak.
+
+When a repo provides `clean-code-review-candidates/v1` input, treat each
+candidate as a deterministic tripwire, not as a finding. Read the file plus the
+symbol or anchor named by the candidate, check whether the listed semantic
+questions are actually supported by the code, then run only the relevant MCP
+queries. A candidate may produce `no strong clean-code match`, an advisory note,
+or a targeted refactor plan.
+
+Prefer concise queries over whole-file or whole-diff input.
+
+If the pattern-first tools are not available yet, use the lower-level
+`search_clean_code` tool as a fallback and be more conservative: treat mixed
+markdown/chunk results as supporting context only, and do not claim full pattern
+applicability without a canonical pattern record.
+
+Good query examples:
+
+```text
+typescript function boolean parameter controls behavior in calculatePrice
+python function mutates output argument and also returns status
+react component mixes data normalization conditional rendering and side effects
+typescript review lint candidate TODO comment without tracked issue id
+python long parameter list configuration values passed positionally
+```
+
+Poor query examples:
+
+```text
+make this cleaner
+review this entire diff
+clean code suggestions for app.tsx
+```
+
+## Result Handling
+
+Treat MCP results as candidates. Before using a result, check:
+
+- Does the result match the language or framework?
+- Does the result describe the observed code shape?
+- Does `avoid_when` apply?
+- Is the pattern lintable, review-only, or context-dependent?
+- Would applying it preserve the public API and behavior?
+- Is the match specific enough to mention in a review or plan?
+
+Use at most 1-3 selected matches in visible output. Do not decorate every
+review finding with pattern IDs. Cite a pattern ID only when it materially
+changed the recommendation.
+
+## Review Output
+
+When writing code-review findings, lead with local evidence. Use MCP guidance as
+supporting context.
+
+Preferred shape:
+
+```text
+Finding: `calculatePrice(user, includeDiscounts)` uses a boolean selector that
+changes behavior, so callers must understand two execution modes from one
+signature.
+
+Clean-code support: CC-043 applies because the boolean argument selects behavior
+rather than representing plain data. A safer remediation is to introduce
+intention-revealing functions while keeping a compatibility wrapper if the API
+is public.
+```
+
+Avoid findings that say only "Clean code says..." or "Pattern CC-043 says...".
+The issue must stand on the code.
+
+## Language Heuristics
+
+For Python:
+
+- Prefer Pythonic clarity over abstract purity.
+- Use plain functions when data flow is simple.
+- Use `TypedDict` for stable mapping-shaped data, `dataclass` for value-like
+  data, and richer models only when validation, serialization, or invariants
+  justify them.
+- Use keyword-only parameters when they improve call-site clarity.
+- Preserve the local failure style: exceptions, `None`, result objects, or
+  framework responses.
+- Separate parsing, validation, transformation, and side effects when they are
+  tangled.
+- Do not add docstrings to every private helper; comments should explain why,
+  constraints, or surprising behavior.
+
+For JavaScript and TypeScript:
+
+- Prefer domain names over implementation names; drop vague suffixes like
+  `Data`, `Info`, `Manager`, or `Helper` unless they distinguish real concepts.
+- Use boolean names that read like questions: `isReady`, `hasAccess`,
+  `shouldRetry`.
+- Prefer stronger TypeScript types over explanatory comments.
+- Narrow external data early and keep internal code on trusted shapes.
+- Use discriminated unions when the code already branches on variants.
+- Prefer object parameters when several values travel together, but do not
+  introduce options objects only to satisfy an arbitrary parameter count.
+- Follow the existing error boundary style: throw, result object, or
+  framework-specific response.
+
+## Refactor Output
+
+When planning a refactor, translate selected patterns into constraints:
+
+- what behavior must stay unchanged
+- what code shape should change
+- what compatibility wrapper is needed, if any
+- what tests or checks should verify the change
+
+Keep the refactor small unless the user asks for a broader rewrite.
+
+## Lint-Rule Design
+
+For lint-rule work, filter toward high and medium lintability. If the MCP accepts
+a list, pass `["high", "medium"]`; if it accepts only one value, run separate
+queries or use the lint-rule recommendation tool. Keep
+`review_only` patterns out of automated lint checks unless there is a narrow,
+low-false-positive signal.
+
+A lint recommendation should include:
+
+- target tool: ESLint, Ruff, Pylint, Semgrep, or review-only
+- static signal
+- likely false positives
+- safe contexts to ignore
+- suppression strategy
+- autofix feasibility
+
+## Weak-Match Policy
+
+Suppress weak or generic MCP results. Say `no strong clean-code match` when:
+
+- the top results are broad clean-code advice without a local code anchor
+- the result depends on context the agent has not verified
+- the code is idiomatic for the framework
+- the evidence comes from generated, fixture, migration, or test-helper code
+- applying the pattern would conflict with stable public API constraints
+
+Missing a weak suggestion is better than producing a noisy style finding.

package/skills/clean-code-mcp-reviewer/evals/evals.json

@@ -0,0 +1,30 @@
+{
+  "skill_name": "clean-code-mcp-reviewer",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Review this TypeScript helper. Use the clean-code MCP only if it helps.\n\n```ts\nexport function calculatePrice(customer: Customer, includeDiscounts: boolean): Money {\n  let total = customer.cart.subtotal;\n  if (includeDiscounts) {\n    total = total.minus(customer.discountAmount);\n  }\n  return total;\n}\n\nconst invoicePrice = calculatePrice(customer, false);\nconst checkoutPrice = calculatePrice(customer, true);\n```",
+      "expected_output": "The agent reads the code first, queries for a boolean selector or flag argument pattern, uses a high-fit match, and anchors the finding to the local function/callers."
+    },
+    {
+      "id": 2,
+      "prompt": "Review this React component and decide whether clean-code MCP guidance should block it.\n\n```tsx\nexport function SaveDialog({ isSaving }: { isSaving: boolean }) {\n  return (\n    <Modal open>\n      <Button disabled={isSaving}>Save</Button>\n    </Modal>\n  );\n}\n```",
+      "expected_output": "The agent treats declarative React boolean props as a near-miss and avoids a flag-argument finding unless there is behavior-selection evidence."
+    },
+    {
+      "id": 3,
+      "prompt": "Plan a Python refactor for this function. Use the clean-code MCP only after identifying the concern.\n\n```python\ndef normalize_order(order: Order, errors: list[str]) -> str:\n    if order.total <= 0:\n        errors.append(\"total must be positive\")\n        return \"invalid\"\n    order.customer_email = order.customer_email.strip().lower()\n    return \"valid\"\n```",
+      "expected_output": "The agent queries for output argument mutation or side-effect concerns, fetches details only for a relevant match, and proposes a behavior-preserving refactor with verification."
+    },
+    {
+      "id": 4,
+      "prompt": "Design a clean-code lint check for repeated TODO comments in TypeScript and Python.\n\nExamples that should pass:\n```ts\n// TODO(PROJ-123): remove legacy tax fallback after migration.\n```\n\nExamples that should fail:\n```python\n# TODO fix this later\nresult = legacy_process(data)\n```",
+      "expected_output": "The agent uses lintability filters, distinguishes valid tracked TODOs from weak comments, and recommends appropriate target tooling and false-positive controls."
+    },
+    {
+      "id": 5,
+      "prompt": "Review this generated API client fixture change and decide whether clean-code patterns should block it.\n\n```ts\n// generated from billing-openapi.yaml\nexport const fixture = {\n  account: { owner: { address: { city: \"London\" } } },\n  status: \"active\"\n};\n\nexport const city = fixture.account.owner.address.city;\n```\n\nThe file path is `src/generated/billingClient.fixture.ts`.",
+      "expected_output": "The agent recognizes generated/fixture code as a weak-match context and reports no strong clean-code finding unless local project rules say otherwise."
+    }
+  ]
+}