clean-code-tools 1.0.1

package/docs/semantic-weaviate.md

@@ -0,0 +1,80 @@
+# Semantic Weaviate Search
+
+This repo uses local Weaviate with self-provided vectors. Weaviate stores chunks and performs vector search; Python generates CPU embeddings with FastEmbed.
+
+## Local Setup
+
+```bash
+uv sync
+bun run weaviate:dev:start
+bun run weaviate:dev:smoke
+```
+
+If port `8080` is busy:
+
+```bash
+WEAVIATE_HTTP_PORT=18080 WEAVIATE_GRPC_PORT=15051 bun run weaviate:dev:start
+WEAVIATE_HTTP_PORT=18080 bun run weaviate:dev:smoke
+```
+
+## Ingest
+
+```bash
+bun run semantic:chunks
+bun run semantic:ingest -- --reset
+```
+
+The default collection is `CleanCodeChunks`. The default embedding model is `BAAI/bge-small-en-v1.5`, running through `fastembed/cpu`.
+
+## Search
+
+```bash
+bun run semantic:search -- "boolean flag argument"
+bun run semantic:search -- "comments that explain bad code"
+bun run semantic:search -- "train wreck deep property chain"
+bun run semantic:search -- "too many function arguments"
+```
+
+Expected useful matches include:
+
+- `boolean flag argument`: `CC-043`, `CC-208`, `CC-224`
+- `comments that explain bad code`: `CC-060`, `CC-071`, `CC-073`
+- `train wreck deep property chain`: `CC-107`, `CC-245`
+- `too many function arguments`: `CC-041`, `CC-045`, `CC-206`
+
+The MCP pattern search builds on this chunk search but adds a pattern-first
+retrieval layer:
+
+- overfetch semantic matches from Weaviate
+- add local exact matches over pattern IDs, titles, aliases, and lint candidates
+- filter by source kind, language, rule family, topic, and lintability
+- rerank with transparent semantic, lexical, metadata, and context scores
+- deduplicate by `record_id`
+- return `no_strong_match` for weak or conservative contexts
+
+Run the offline retrieval evals with:
+
+```bash
+bun run check:retrieval-evals
+```
+
+## Chunking
+
+The ingestion builds two chunk families:
+
+- `pattern_record`: one chunk per canonical `data/clean-code-patterns.jsonl` record
+- `markdown_section`: one chunk per heading section in markdown docs
+
+Markdown parsing is code-fence aware and preserves code blocks with the nearest semantic section. Oversized sections are split by paragraph/code-block groups instead of arbitrary character windows.
+
+## Schema
+
+The collection uses a named self-provided vector:
+
+```text
+collection: CleanCodeChunks
+vector: content
+vectorizer: none
+```
+
+Stored properties include source identity, section path, clean-code rule metadata, lintability, language hints, `contentText`, `embeddingText`, `textHash`, `chunkerVersion`, `embeddingModel`, and `embeddingProvider`.

package/docs/static-trigger-semantic-review.md

@@ -0,0 +1,97 @@
+# Static Trigger to Semantic Review
+
+This repo uses deterministic lint rules as tripwires for deeper clean-code
+review. The static layer stays fast and reproducible; the semantic layer decides
+whether a finding is a real maintainability issue and what refactor would be
+safe.
+
+## Flow
+
+```text
+ESLint / Pylint / Ruff
+  -> clean-code review candidates
+  -> clean-code-mcp-reviewer skill
+  -> clean-code MCP pattern lookup
+  -> advisory finding or refactor plan
+  -> normal tests and lint verification
+```
+
+The scanner output uses schema `clean-code-review-candidates/v1`. Each
+candidate contains:
+
+- `language`
+- `file`
+- `symbol`
+- `anchor`
+- `skill`
+- deterministic `triggers`
+- `semantic_questions`
+- suggested `mcp_queries`
+
+## Run
+
+From lint JSON files:
+
+```bash
+bun run clean-code:candidates -- \
+  --eslint-json eslint-report.json \
+  --pylint-json pylint-report.json \
+  --ruff-json ruff-report.json
+```
+
+From lint commands:
+
+```bash
+bun run clean-code:candidates -- \
+  --pylint-command "uv run --group lint pylint src/python/mcp_server --output-format=json" \
+  --ruff-command "uv run --group lint ruff check src/python/mcp_server --output-format=json"
+```
+
+Markdown is useful for agent prompts:
+
+```bash
+bun run clean-code:candidates -- \
+  --pylint-command "uv run --group lint pylint src/python/mcp_server --output-format=json" \
+  --ruff-command "uv run --group lint ruff check src/python/mcp_server --output-format=json" \
+  --format markdown
+```
+
+## Trigger Policy
+
+Only rules with a strong relationship to maintainability are promoted into
+semantic candidates. Formatting and ordinary style rules are intentionally
+ignored.
+
+Good triggers include:
+
+- large files, functions, or classes
+- high complexity or nesting
+- too many arguments, locals, statements, branches, or public methods
+- duplicated branches or functions
+- boolean flag arguments
+- output argument mutation
+- TODO/comment hygiene, commented-out code, and traceable technical debt
+- policy literals, magic values, duplicate strings, and repeated domain values
+- train-wreck object navigation, broad imports, and dependency cycles
+- dead stores, unused symbols, and incomplete cleanup
+
+The trigger is not the recommendation. For example, `max-lines` means "inspect
+this file for mixed responsibilities"; it does not mean "split the file."
+
+## Agent Contract
+
+`skill` is always `clean-code-mcp-reviewer`. The candidate does not name
+language-specific skills because consuming systems may only install this repo's
+MCP reviewer skill.
+
+Agents should:
+
+1. Read the candidate's file plus its `symbol` or `anchor` first.
+2. Confirm or reject the semantic questions using local code evidence.
+3. Query the MCP narrowly with the suggested query or a refined one.
+4. Suppress weak matches.
+5. Produce a scoped refactor plan only when it preserves behavior and follows
+   local conventions.
+
+This keeps the deterministic check useful without turning clean-code guidance
+into noisy doctrine.

package/evals/clean-code-retrieval.jsonl

@@ -0,0 +1,13 @@
+{"id":"flag-argument-ts","query":"typescript boolean parameter controls behavior selector argument calculatePrice true false","language":"typescript","expected_top_ids":["CC-043","CC-208"],"vector_ids":["CC-047","CC-043","CC-208","CC-195"],"should_strong_match":true}
+{"id":"todo-without-issue","query":"TODO fix this later comment without issue id","language":"typescript","expected_top_ids":["CC-068"],"vector_ids":["CC-064","CC-068","CC-071","CC-012"],"should_strong_match":true}
+{"id":"train-wreck","query":"deep property chain account owner address city train wreck transitive navigation","language":"typescript","expected_top_ids":["CC-107"],"vector_ids":["CC-106","CC-107","CC-245","CC-001"],"should_strong_match":true}
+{"id":"output-argument-python","query":"python function mutates output argument errors list and returns status","language":"python","expected_top_ids":["CC-050","CC-207"],"vector_ids":["CC-047","CC-050","CC-207","CC-052"],"should_strong_match":true}
+{"id":"tracked-todo-nearmiss","query":"TODO(PROJ-123) remove legacy fallback after migration tracked issue marker","language":"typescript","expected_top_ids":["CC-068"],"vector_ids":["CC-068","CC-064","CC-071"],"should_strong_match":false}
+{"id":"generated-fixture-nearmiss","query":"generated api client fixture deep dto property chain hard coded fixture literal","language":"typescript","expected_top_ids":["CC-107"],"vector_ids":["CC-107","CC-002","CC-245"],"should_strong_match":false}
+{"id":"vague-nonsense","query":"do this thing with code","language":"typescript","expected_top_ids":[],"vector_ids":["CC-001","CC-012","CC-191"],"should_strong_match":false}
+{"id":"broad-comment-category","query":"python comment","language":"python","expected_top_ids":[],"vector_ids":["CC-199","CC-200","CC-201"],"should_strong_match":false}
+{"id":"broad-error-category","query":"error handling","language":"typescript","expected_top_ids":[],"vector_ids":["CC-054","CC-112","CC-113"],"should_strong_match":false}
+{"id":"generic-clean-code","query":"clean code","language":"typescript","expected_top_ids":[],"vector_ids":["CC-001","CC-012","CC-191"],"should_strong_match":false}
+{"id":"generic-code-smell","query":"code smell","language":"python","expected_top_ids":[],"vector_ids":["CC-199","CC-200","CC-201"],"should_strong_match":false}
+{"id":"generic-planning-guidance","query":"planning guidance","language":"typescript","expected_top_ids":[],"vector_ids":["CC-001","CC-012","CC-191"],"should_strong_match":false}
+{"id":"generic-refactoring-rule","query":"refactoring rule","language":"python","expected_top_ids":[],"vector_ids":["CC-050","CC-107","CC-207"],"should_strong_match":false}

package/ops/dev/weaviate/README.md

@@ -0,0 +1,34 @@
+# Local Weaviate
+
+This stack runs a local Weaviate instance for clean-code semantic search.
+
+It uses the same shape as the BusyBots local stack:
+
+- no Weaviate vectorizer module
+- anonymous local access
+- self-provided vectors inserted by Python tooling
+- HTTP on `http://127.0.0.1:8080`
+- gRPC on `127.0.0.1:50051`
+- persistent Docker volume `clean-code-tools-weaviate_weaviate_data`
+
+## Commands
+
+From the repo root:
+
+```bash
+uv sync
+bun run weaviate:dev:start
+bun run weaviate:dev:smoke
+bun run weaviate:dev:status
+bun run weaviate:dev:logs
+bun run weaviate:dev:stop
+```
+
+If port `8080` is already taken:
+
+```bash
+WEAVIATE_HTTP_PORT=18080 WEAVIATE_GRPC_PORT=15051 bun run weaviate:dev:start
+WEAVIATE_HTTP_PORT=18080 bun run weaviate:dev:smoke
+```
+
+The semantic ingestion scripts default to `WEAVIATE_URL=http://127.0.0.1:8080`.

package/ops/dev/weaviate/compose.yaml

@@ -0,0 +1,34 @@
+name: clean-code-tools-weaviate
+
+services:
+  weaviate:
+    image: cr.weaviate.io/semitechnologies/weaviate:1.38.1
+    mem_limit: "${WEAVIATE_MEMORY_LIMIT:-4g}"
+    command:
+      - --host
+      - 0.0.0.0
+      - --port
+      - "8080"
+      - --scheme
+      - http
+    ports:
+      - "${WEAVIATE_HTTP_PORT:-8080}:8080"
+      - "${WEAVIATE_GRPC_PORT:-50051}:50051"
+    restart: on-failure:0
+    environment:
+      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: "true"
+      CLUSTER_HOSTNAME: node1
+      DEFAULT_VECTORIZER_MODULE: none
+      DISABLE_TELEMETRY: "${WEAVIATE_DISABLE_TELEMETRY:-true}"
+      ENABLE_MODULES: ""
+      ASYNC_INDEXING: "${WEAVIATE_ASYNC_INDEXING:-true}"
+      GOMEMLIMIT: "${WEAVIATE_GOMEMLIMIT:-3072MiB}"
+      GOMAXPROCS: "${WEAVIATE_GOMAXPROCS:-4}"
+      PERSISTENCE_DATA_PATH: /var/lib/weaviate
+      QUERY_DEFAULTS_LIMIT: "${WEAVIATE_QUERY_DEFAULTS_LIMIT:-100}"
+    volumes:
+      - weaviate_data:/var/lib/weaviate
+
+volumes:
+  weaviate_data:
+

package/ops/dev/weaviate/smoke.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+http_port="${WEAVIATE_HTTP_PORT:-8080}"
+base_url="http://127.0.0.1:${http_port}"
+
+ready_url="${base_url}/v1/.well-known/ready"
+meta_url="${base_url}/v1/meta"
+ready=false
+
+for _attempt in $(seq 1 60); do
+  if curl -fsS "${ready_url}" >/dev/null 2>&1; then
+    ready=true
+    break
+  fi
+  sleep 1
+done
+
+if [[ "${ready}" != "true" ]]; then
+  echo "Weaviate did not become ready at ${base_url}" >&2
+  curl -sS "${ready_url}" || true
+  exit 1
+fi
+
+curl -fsS "${meta_url}" | python3 -m json.tool >/dev/null
+
+echo "Weaviate ready at ${base_url}"
+

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "clean-code-tools",
+  "version": "1.0.1",
+  "description": "Clean-code pattern corpus and lint tooling.",
+  "type": "module",
+  "packageManager": "bun@1.3.13",
+  "homepage": "https://github.com/wnz99/clean-code-tools#readme",
+  "bugs": {
+    "url": "https://github.com/wnz99/clean-code-tools/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wnz99/clean-code-tools.git"
+  },
+  "main": "src/js/eslint-plugin-clean-code.mjs",
+  "exports": {
+    ".": "./src/js/eslint-plugin-clean-code.mjs",
+    "./eslint-plugin": "./src/js/eslint-plugin-clean-code.mjs",
+    "./configs/eslint.clean-code.recommended.mjs": "./configs/eslint.clean-code.recommended.mjs",
+    "./configs/python.clean-code.pyproject.toml": "./configs/python.clean-code.pyproject.toml"
+  },
+  "files": [
+    "configs/",
+    "docs/",
+    "evals/",
+    "data/",
+    "pyproject.toml",
+    "uv.lock",
+    "sample-apps/",
+    "scripts/*.py",
+    "skills/",
+    "ops/",
+    "src/python/clean_code_tools_pylint/*.py",
+    "src/js/eslint-plugin-clean-code.mjs",
+    "src/python/mcp_server/*.py",
+    "src/python/mcp_server/utils/*.py",
+    "README.md",
+    "package.json"
+  ],
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "test": "bun test tests/*.test.mjs",
+    "test:eslint-plugin": "bun test tests/eslint-plugin-clean-code.test.mjs",
+    "check:python-config": "uv run --group lint python scripts/check_python_config.py",
+    "check:sample-apps": "uv run --group lint python scripts/check_sample_apps.py",
+    "check:semantic-search": "uv run python scripts/check_semantic_search_tooling.py",
+    "check:review-candidates": "uv run python scripts/check_clean_code_review_candidates.py",
+    "check:retrieval-evals": "uv run python scripts/check_retrieval_evals.py",
+    "check:python-repo-lint": "uv run --group lint python scripts/check_repo_python_lint.py",
+    "check:packages": "uv run python scripts/check_packages.py",
+    "check:fastmcp": "uv run python scripts/check_fastmcp_server.py",
+    "weaviate:dev:start": "docker compose -f ops/dev/weaviate/compose.yaml up -d",
+    "weaviate:dev:stop": "docker compose -f ops/dev/weaviate/compose.yaml down",
+    "weaviate:dev:status": "docker compose -f ops/dev/weaviate/compose.yaml ps",
+    "weaviate:dev:logs": "docker compose -f ops/dev/weaviate/compose.yaml logs -f weaviate",
+    "weaviate:dev:smoke": "bash ops/dev/weaviate/smoke.sh",
+    "semantic:chunks": "uv run python scripts/clean_code_semantic.py",
+    "clean-code:candidates": "uv run python scripts/clean_code_review_candidates.py",
+    "semantic:ingest": "uv run python scripts/weaviate_ingest_clean_code.py",
+    "semantic:search": "uv run python scripts/weaviate_search_clean_code.py",
+    "mcp:stdio": "uv run python scripts/clean_code_mcp_server.py",
+    "mcp:http": "uv run python scripts/clean_code_mcp_server.py --transport http --host 127.0.0.1 --port 8765",
+    "check": "bun --check src/js/eslint-plugin-clean-code.mjs && bun --check configs/eslint.clean-code.recommended.mjs && bun test && bun run check:python-config && bun run check:sample-apps && bun run check:semantic-search && bun run check:review-candidates && bun run check:retrieval-evals && bun run check:python-repo-lint && bun run check:packages"
+  },
+  "keywords": [
+    "clean-code",
+    "eslint",
+    "pylint",
+    "ruff",
+    "mcp",
+    "static-analysis"
+  ],
+  "author": "",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": "^22.13.0 || >=24"
+  },
+  "peerDependencies": {
+    "@eslint/js": "^10.0.0",
+    "eslint": "^10.4.0",
+    "eslint-plugin-sonarjs": "^4.0.0",
+    "eslint-plugin-unicorn": "^69.0.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^10.6.0",
+    "eslint-plugin-sonarjs": "^4.1.0",
+    "eslint-plugin-unicorn": "^69.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,303 @@
+#:schema https://json.schemastore.org/pyproject.json
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clean-code-tools-python"
+version = "1.0.1"
+description = "Python clean-code lint plugin and recommended Ruff/Pylint config."
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = [
+  "clean-code",
+  "pylint",
+  "ruff",
+  "static-analysis",
+]
+dependencies = [
+  "pylint>=4.0.0",
+  "ruff>=0.15.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/wnz99/clean-code-tools"
+Repository = "https://github.com/wnz99/clean-code-tools"
+Issues = "https://github.com/wnz99/clean-code-tools/issues"
+Documentation = "https://github.com/wnz99/clean-code-tools/tree/main/docs"
+
+[dependency-groups]
+lint = [
+  "ruff>=0.15.0",
+  "pylint>=4.0.0",
+]
+mcp = [
+  "fastembed>=0.8.0",
+  "fastmcp>=2.0.0",
+  "httpx>=0.27.0",
+]
+typecheck = [
+  "pyright>=1.1.403",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/python/clean_code_tools_pylint"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"configs/python.clean-code.pyproject.toml" = "clean_code_tools_pylint/configs/python.clean-code.pyproject.toml"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+fix = true
+show-fixes = true
+output-format = "grouped"
+extend-exclude = [
+  ".git",
+  ".mypy_cache",
+  ".nox",
+  ".ruff_cache",
+  ".tox",
+  ".venv",
+  "__pycache__",
+  "build",
+  "dist",
+  "node_modules",
+  "sample-apps",
+]
+
+[tool.ruff.lint]
+select = [
+  "E",
+  "W",
+  "F",
+  "I",
+  "UP",
+  "B",
+  "C4",
+  "SIM",
+  "RET",
+  "PTH",
+  "TID",
+  "RUF",
+  "S",
+  "BLE",
+  "A",
+  "G",
+  "TRY",
+  "FA",
+  "ISC",
+  "ICN",
+  "PIE",
+  "T20",
+  "Q",
+  "RSE",
+  "PERF",
+  "FURB",
+  "LOG",
+  "FBT",
+  "COM",
+  "INP",
+  "ARG",
+  "ERA",
+  "TD",
+  "PGH",
+  "PL",
+  "PYI",
+]
+ignore = [
+  "E501",
+  "COM812",
+  "ISC001",
+  "TD001",
+]
+fixable = [
+  "E",
+  "W",
+  "F",
+  "I",
+  "UP",
+  "B",
+  "C4",
+  "SIM",
+  "RET",
+  "PTH",
+  "TID",
+  "RUF",
+  "S",
+  "BLE",
+  "A",
+  "G",
+  "TRY",
+  "FA",
+  "ISC",
+  "ICN",
+  "PIE",
+  "T20",
+  "Q",
+  "RSE",
+  "PERF",
+  "FURB",
+  "LOG",
+  "FBT",
+  "COM",
+  "INP",
+  "ARG",
+  "PGH",
+  "PL",
+  "PYI",
+]
+unfixable = [
+  "ERA",
+  "TD",
+  "PLR2004",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = []
+combine-as-imports = true
+split-on-trailing-comma = true
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/**/*.py" = [
+  "T201",
+]
+"scripts/check_*.py" = [
+  "S101",
+  "PLC0415",
+  "S603",
+  "TRY003",
+  "FBT001",
+  "FBT002",
+  "PLR2004",
+]
+"scripts/clean_code_eslint_triggers.py" = [
+  "INP001",
+]
+"scripts/clean_code_python_triggers.py" = [
+  "INP001",
+]
+"scripts/clean_code_review_io.py" = [
+  "INP001",
+]
+"scripts/clean_code_review_models.py" = [
+  "INP001",
+]
+"scripts/set_package_versions.py" = [
+  "TRY003",
+]
+"scripts/_mcp_app.py" = [
+  "TRY003",
+]
+"scripts/weaviate_ingest_clean_code.py" = [
+  "TRY003",
+]
+"scripts/weaviate_search_clean_code.py" = [
+  "TRY003",
+]
+"src/python/mcp_server/server.py" = [
+  "PLC0415",
+  "PLR0913",
+  "TRY003",
+]
+"src/python/mcp_server/semantic.py" = [
+  "PLC0415",
+  "TRY003",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.pylint.main]
+py-version = "3.12"
+jobs = 0
+recursive = true
+load-plugins = [
+  "clean_code_tools_pylint",
+]
+ignore-paths = [
+  "^\\.venv/.*$",
+  "^build/.*$",
+  "^dist/.*$",
+  "^node_modules/.*$",
+  "^sample-apps/.*$",
+]
+
+[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.imports]
+allow-any-import-level = []
+
+[tool.pylint.reports]
+score = false
+
+[tool.pyright]
+include = ["src/python/clean_code_tools_pylint", "src/python/mcp_server", "scripts"]
+extraPaths = ["src/python"]
+exclude = [
+  "**/__pycache__",
+  "**/.venv",
+  "**/.pytest_cache",
+  "**/.ruff_cache",
+  "node_modules",
+  "sample-apps",
+]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportMissingImports = "error"
+reportMissingTypeStubs = "warning"
+reportUnusedImport = "error"
+reportUnusedVariable = "warning"
+reportPrivateUsage = "warning"
+reportUnknownArgumentType = "warning"
+reportUnknownMemberType = "warning"
+reportUnknownVariableType = "warning"
+reportUnusedFunction = "warning"