clean-code-tools 1.0.1

package/README.md

@@ -0,0 +1,66 @@
+# Clean Code Tools
+
+This repository contains clean-code lint packages, a local MCP server for
+pattern lookup, and the production clean-code pattern corpus.
+
+Start with [docs/README.md](docs/README.md) for the documentation index.
+
+For vector database ingestion, use `data/clean-code-patterns.jsonl`. It contains
+264 records with aliases, problem statements, use/avoid guidance, good and bad
+examples, lintability, and embedding/display text. The expected record shape is
+documented in `data/vector-record.schema.json`.
+
+Suggested vector metadata fields:
+
+- `id`
+- `topic`
+- `language`
+- `title`
+- `description`
+- `lint_candidates`
+
+## Local MCP
+
+This repo includes a uv-backed FastMCP server in `src/python/mcp_server` for local
+clean-code pattern search.
+
+```bash
+uv sync
+bun run weaviate:dev:start
+bun run semantic:ingest -- --reset
+bun run mcp:http
+```
+
+Useful checks:
+
+```bash
+bun run check:fastmcp
+bun run check:retrieval-evals
+bun run check
+```
+
+The agent-facing tools are documented in `docs/fastmcp-local-server.md`.
+
+## Static Triggers to Semantic Review
+
+Use deterministic lint output as the first pass, then hand selected
+maintainability tripwires to an agent or MCP-backed review:
+
+```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"
+```
+
+The workflow and `clean-code-review-candidates/v1` schema are documented in
+`docs/static-trigger-semantic-review.md`.
+
+## Packages
+
+The ESLint plugin/config is distributed through npm, and the Python Pylint
+plugin/config is distributed through PyPI. Packaging checks are documented in
+`docs/publishing.md` and run through:
+
+```bash
+bun run check:packages
+```

package/configs/eslint.clean-code.recommended.mjs

@@ -0,0 +1,211 @@
+import js from "@eslint/js";
+import sonarjs from "eslint-plugin-sonarjs";
+import unicorn from "eslint-plugin-unicorn";
+import tseslint from "typescript-eslint";
+import cleanCode from "../src/js/eslint-plugin-clean-code.mjs";
+
+const TEST_FILE_PATTERNS = [
+  "**/*.test.{js,jsx,ts,tsx}",
+  "**/*.spec.{js,jsx,ts,tsx}",
+  "**/__tests__/**/*.{js,jsx,ts,tsx}",
+];
+const TYPE_SCRIPT_FILE_PATTERNS = ["**/*.{ts,tsx,mts,cts}"];
+
+function scopeToTypeScriptFiles(configs) {
+  return configs.map((config) => ({
+    ...config,
+    files: TYPE_SCRIPT_FILE_PATTERNS,
+  }));
+}
+
+export default tseslint.config(
+  {
+    ignores: [
+      "**/dist/**",
+      "**/build/**",
+      "**/coverage/**",
+      "**/.next/**",
+      "**/node_modules/**",
+      "**/*.d.ts",
+    ],
+  },
+  js.configs.recommended,
+  ...scopeToTypeScriptFiles(tseslint.configs.strictTypeChecked),
+  ...scopeToTypeScriptFiles(tseslint.configs.stylisticTypeChecked),
+  {
+    files: TYPE_SCRIPT_FILE_PATTERNS,
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+      },
+    },
+    plugins: {
+      "clean-code": cleanCode,
+      sonarjs,
+      unicorn,
+    },
+    rules: {
+      // CC-033..CC-059, CC-137..CC-142, CC-206: keep units small enough to scan.
+      complexity: ["warn", { max: 10 }],
+      "max-depth": ["warn", 4],
+      "max-lines": [
+        "warn",
+        {
+          max: 300,
+          skipBlankLines: true,
+          skipComments: true,
+        },
+      ],
+      "max-lines-per-function": [
+        "warn",
+        {
+          max: 50,
+          skipBlankLines: true,
+          skipComments: true,
+        },
+      ],
+      "max-params": ["warn", 4],
+      "sonarjs/cognitive-complexity": ["warn", 15],
+
+      // CC-043, CC-208, CC-224: discourage selector-style boolean modes.
+      "@typescript-eslint/strict-boolean-expressions": [
+        "warn",
+        {
+          allowString: false,
+          allowNumber: false,
+          allowNullableObject: false,
+          allowNullableBoolean: false,
+          allowNullableString: false,
+          allowNullableNumber: false,
+          allowAny: false,
+        },
+      ],
+
+      // CC-018, CC-234: make policy values searchable.
+      "@typescript-eslint/no-magic-numbers": [
+        "warn",
+        {
+          ignore: [-1, 0, 1],
+          ignoreArrayIndexes: true,
+          ignoreDefaultValues: true,
+          ignoreEnums: true,
+          ignoreNumericLiteralTypes: true,
+          ignoreReadonlyClassProperties: true,
+        },
+      ],
+      "sonarjs/no-duplicate-string": ["warn", { threshold: 5 }],
+
+      // CC-068, CC-083: use issue-tracked TODOs and do not park code in comments.
+      "no-warning-comments": "off",
+
+      // CC-071..CC-089: reduce noisy or misleading comment patterns.
+      "capitalized-comments": "off",
+      "lines-around-comment": "off",
+      "spaced-comment": [
+        "warn",
+        "always",
+        {
+          markers: ["/"],
+          exceptions: ["-", "+"],
+        },
+      ],
+      "clean-code/no-commented-out-code": "warn",
+      "clean-code/no-noisy-comments": "warn",
+      "clean-code/no-redundant-comment": "warn",
+      "clean-code/todo-format": "warn",
+
+      // CC-160, CC-214: catch copy/paste branching before it becomes policy drift.
+      "sonarjs/no-duplicated-branches": "warn",
+      "sonarjs/no-identical-conditions": "warn",
+      "sonarjs/no-identical-functions": "warn",
+
+      // CC-237, CC-238: prefer readable predicates and positive branches.
+      "no-nested-ternary": "warn",
+      "no-negated-condition": "warn",
+      "sonarjs/no-inverted-boolean-check": "warn",
+      "unicorn/no-negated-condition": "warn",
+      "clean-code/no-business-policy-literals": "warn",
+
+      // CC-118, CC-119: avoid surprise nulls in codebases that prefer explicit absence.
+      "unicorn/no-null": "warn",
+      "@typescript-eslint/no-unnecessary-condition": "warn",
+      "@typescript-eslint/prefer-nullish-coalescing": "warn",
+
+      // CC-209, CC-218, CC-221: remove dead and redundant code.
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+      "no-empty": ["warn", { allowEmptyCatch: false }],
+      "no-useless-return": "warn",
+      "sonarjs/no-dead-store": "warn",
+      "clean-code/no-boolean-flag-arguments": "warn",
+      "clean-code/no-output-argument-mutation": "warn",
+
+      // CC-246: keep imports readable and dependency lists explicit.
+      "no-restricted-syntax": [
+        "warn",
+        {
+          selector: "ImportDeclaration[specifiers.length>10]",
+          message:
+            "Import lists with more than 10 specifiers are hard to scan; prefer a narrower module or namespace import when it matches local conventions.",
+        },
+      ],
+      "clean-code/no-train-wrecks": "warn",
+
+      // CC-011, CC-025, CC-249..CC-255: enforce baseline naming consistency.
+      "@typescript-eslint/naming-convention": [
+        "warn",
+        {
+          selector: "variableLike",
+          format: ["camelCase", "PascalCase", "UPPER_CASE"],
+          leadingUnderscore: "allow",
+        },
+        {
+          selector: "typeLike",
+          format: ["PascalCase"],
+        },
+        {
+          selector: "function",
+          format: ["camelCase", "PascalCase"],
+        },
+        {
+          selector: "variable",
+          types: ["boolean"],
+          format: ["PascalCase", "UPPER_CASE"],
+          prefix: ["is", "has", "can", "should", "will", "did"],
+        },
+      ],
+
+      // General precision rules that support CC-235 and reduce avoidable ambiguity.
+      "@typescript-eslint/consistent-type-imports": [
+        "warn",
+        {
+          prefer: "type-imports",
+          fixStyle: "separate-type-imports",
+        },
+      ],
+      "@typescript-eslint/no-confusing-void-expression": "warn",
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/no-misused-promises": "error",
+      "@typescript-eslint/no-unnecessary-type-assertion": "warn",
+      "@typescript-eslint/switch-exhaustiveness-check": "warn",
+      "eqeqeq": ["error", "always", { null: "ignore" }],
+      "unicorn/explicit-length-check": "warn",
+    },
+  },
+  {
+    files: TEST_FILE_PATTERNS,
+    rules: {
+      "@typescript-eslint/no-magic-numbers": "off",
+      "max-lines": "off",
+      "max-lines-per-function": "off",
+      "max-params": "off",
+      "sonarjs/no-identical-functions": "off",
+    },
+  },
+);

package/configs/python.clean-code.pyproject.toml

@@ -0,0 +1,143 @@
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+extend-exclude = [
+  ".git",
+  ".mypy_cache",
+  ".nox",
+  ".ruff_cache",
+  ".tox",
+  ".venv",
+  "__pycache__",
+  "build",
+  "dist",
+]
+
+[tool.ruff.lint]
+# Ruff owns fast, mostly local checks: correctness, imports, upgrade safety,
+# argument hygiene, commented code, TODO shape, return flow, and simple
+# readability smells. Pylint owns broader design thresholds below.
+select = [
+  "E",
+  "F",
+  "I",
+  "UP",
+  "B",
+  "C4",
+  "SIM",
+  "RET",
+  "ARG",
+  "ERA",
+  "TD",
+  "PLR2004",
+  "RUF",
+]
+ignore = [
+  # Formatter-compatible defaults.
+  "E501",
+
+  # Keep TODO enforcement useful but not hostile to teams that track work in
+  # project-specific systems. TD002/TD003 still require author/issue context.
+  "TD001",
+]
+fixable = [
+  "E",
+  "F",
+  "I",
+  "UP",
+  "B",
+  "C4",
+  "SIM",
+  "RET",
+  "ARG",
+  "RUF",
+]
+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]
+"tests/**/*.py" = [
+  "ARG001",
+  "ARG002",
+  "PLR2004",
+  "S101",
+]
+"**/__init__.py" = [
+  "F401",
+]
+
+[tool.pylint.main]
+py-version = "3.11"
+jobs = 0
+recursive = true
+load-plugins = [
+  "clean_code_tools_pylint",
+]
+ignore-paths = [
+  "^\\.venv/.*$",
+  "^build/.*$",
+  "^dist/.*$",
+]
+
+[tool.pylint."messages control"]
+# Let Ruff own these categories to avoid duplicate reports. Pylint remains
+# focused on design pressure, dependency shape, and semantic review signals.
+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