clean-code-tools 1.0.1

package/data/vector-record.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CleanCodePatternVectorRecord",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "title",
+    "topic",
+    "rule_family",
+    "aliases",
+    "problem",
+    "use_when",
+    "avoid_when",
+    "good_examples",
+    "bad_examples",
+    "lint_candidates",
+    "lintability",
+    "embedding_text",
+    "display_text",
+    "source"
+  ],
+  "properties": {
+    "id": { "type": "string", "pattern": "^CC-[0-9]{3}$" },
+    "title": { "type": "string", "minLength": 3 },
+    "topic": { "type": "string", "minLength": 3 },
+    "rule_family": { "type": "string", "minLength": 3 },
+    "aliases": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 2 },
+      "minItems": 3,
+      "uniqueItems": true
+    },
+    "problem": { "type": "string", "minLength": 20 },
+    "use_when": { "type": "string", "minLength": 20 },
+    "avoid_when": { "type": "string", "minLength": 20 },
+    "good_examples": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["typescript", "python"],
+      "properties": {
+        "typescript": { "type": "string", "minLength": 5 },
+        "python": { "type": "string", "minLength": 5 }
+      }
+    },
+    "bad_examples": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["typescript", "python"],
+      "properties": {
+        "typescript": { "type": "string", "minLength": 5 },
+        "python": { "type": "string", "minLength": 5 }
+      }
+    },
+    "lint_candidates": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 10 },
+      "minItems": 1
+    },
+    "lintability": {
+      "type": "string",
+      "enum": ["high", "medium", "low", "review_only"]
+    },
+    "embedding_text": { "type": "string", "minLength": 300 },
+    "display_text": { "type": "string", "minLength": 300 },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "version"],
+      "properties": {
+        "kind": { "type": "string" },
+        "version": { "type": "integer", "minimum": 1 }
+      }
+    }
+  }
+}
+

package/docs/README.md

@@ -0,0 +1,29 @@
+# Documentation Index
+
+Production-facing docs for clean-code lint packages, MCP pattern lookup, and
+release operations.
+
+## Package Usage
+
+- [ESLint recommended config](./eslint-recommended-config.md): install and use
+  the TypeScript ESLint preset from the npm package.
+- [ESLint custom rules](./eslint-custom-rules.md): project-owned TypeScript
+  clean-code rules included in the ESLint plugin.
+- [Python recommended config](./python-lint-recommended-config.md): install and
+  use the Ruff/Pylint config from the Python package.
+- [Python custom Pylint rules](./python-pylint-custom-rules.md): project-owned
+  Python clean-code rules exposed by the Pylint plugin.
+
+## Agent And MCP Workflows
+
+- [FastMCP local server](./fastmcp-local-server.md): run the local MCP server,
+  inspect exposed tools, and query clean-code patterns from an agent.
+- [Semantic Weaviate search](./semantic-weaviate.md): run local Weaviate,
+  ingest the pattern corpus, and test semantic retrieval.
+- [Static trigger to semantic review](./static-trigger-semantic-review.md):
+  convert deterministic lint output into clean-code MCP review candidates.
+
+## Operations
+
+- [Publishing](./publishing.md): package registry setup, branch flow, automated
+  versioning on `develop`, and publishing on `main`.

package/docs/eslint-custom-rules.md

@@ -0,0 +1,74 @@
+# ESLint Custom Clean-Code Rules
+
+The local plugin lives at [src/js/eslint-plugin-clean-code.mjs](../src/js/eslint-plugin-clean-code.mjs). These rules cover TypeScript clean-code checks that are not well covered by common ESLint rule sets.
+
+## Rules
+
+### `clean-code/todo-format`
+
+Requires TODO/FIXME/XXX comments to include an issue-like owner by default:
+
+```ts
+// TODO(BILL-412): remove fallback after migration.
+```
+
+Default pattern:
+
+```text
+^(TODO|FIXME|XXX)\([A-Z][A-Z0-9]+-\d+\):\s+\S
+```
+
+Corpus: `CC-068`
+
+### `clean-code/no-commented-out-code`
+
+Flags comments that look like disabled JavaScript or TypeScript code.
+
+Corpus: `CC-083`
+
+### `clean-code/no-boolean-flag-arguments`
+
+Flags boolean literals passed at call sites and boolean selector parameters with mode-like names such as `dryRun`, `force`, `skip`, `include`, or `mode`.
+
+Corpus: `CC-043`, `CC-208`, `CC-224`
+
+### `clean-code/no-output-argument-mutation`
+
+Flags assignments, updates, and common mutator calls that mutate function parameters.
+
+Corpus: `CC-050`, `CC-207`
+
+### `clean-code/no-redundant-comment`
+
+Flags comments whose words heavily overlap the following line of code.
+
+Corpus: `CC-071`, `CC-073`
+
+### `clean-code/no-noisy-comments`
+
+Flags separator comments, author/date byline comments, and comments after closing braces.
+
+Corpus: `CC-080`, `CC-081`, `CC-082`
+
+### `clean-code/no-business-policy-literals`
+
+Flags hard-coded policy-looking literals outside named constants and allowlisted calls. The heuristic catches:
+
+- numbers other than `-1`, `0`, and `1`
+- all-caps string values
+- ISO date strings
+- common domain statuses such as `active`, `approved`, `draft`, `failed`, `pending`, and `rejected`
+
+Corpus: `CC-002`, `CC-018`, `CC-234`
+
+### `clean-code/no-train-wrecks`
+
+Flags deep property chains beyond a configurable maximum depth.
+
+Corpus: `CC-106`, `CC-107`, `CC-245`
+
+## Recommended Config
+
+The rules are enabled in [configs/eslint.clean-code.recommended.mjs](../configs/eslint.clean-code.recommended.mjs).
+
+They are intentionally warnings because each rule is heuristic and should be tuned per repository.

package/docs/eslint-recommended-config.md

@@ -0,0 +1,87 @@
+# ESLint Recommended Clean-Code Config
+
+This config combines mature existing ESLint rule sets with a small local clean-code plugin for the TypeScript gaps that are not well covered elsewhere.
+
+## Target
+
+Use [configs/eslint.clean-code.recommended.mjs](../configs/eslint.clean-code.recommended.mjs) in TypeScript projects that already run ESLint flat config.
+
+This preset currently targets Node `^22.13.0 || >=24`, matching the tested ESLint 10/plugin stack.
+
+Install the npm package with its peer dependencies:
+
+```bash
+npm install --save-dev clean-code-tools eslint @eslint/js typescript-eslint eslint-plugin-sonarjs eslint-plugin-unicorn
+```
+
+Then import the preset from the consuming project's `eslint.config.mjs`:
+
+```js
+import cleanCode from "clean-code-tools/configs/eslint.clean-code.recommended.mjs";
+
+export default cleanCode;
+```
+
+If a project already has a config, spread this preset before project-specific overrides:
+
+```js
+import cleanCode from "clean-code-tools/configs/eslint.clean-code.recommended.mjs";
+
+export default [
+  ...cleanCode,
+  {
+    rules: {
+      "max-lines": ["warn", { max: 300, skipBlankLines: true, skipComments: true }],
+      "max-lines-per-function": ["warn", { max: 50, skipBlankLines: true, skipComments: true }],
+    },
+  },
+];
+```
+
+## TypeScript Project Setup
+
+The config uses type-aware `typescript-eslint` rules with `projectService: true` for TypeScript files. Linted `*.ts`, `*.tsx`, `*.mts`, and `*.cts` files must be included by the consuming project's `tsconfig.json`.
+
+If a project intentionally lints generated files, config files, or one-off scripts outside `tsconfig.json`, add a project-specific override rather than broadening this preset globally.
+
+The package declares these peer dependencies:
+
+- `eslint@^10.4.0`
+- `@eslint/js@^10.0.0`
+- `typescript-eslint@^8.0.0`
+- `eslint-plugin-sonarjs@^4.0.0`
+- `eslint-plugin-unicorn@^69.0.0`
+
+## Existing Rule Coverage
+
+| Corpus area | Existing ESLint coverage |
+| --- | --- |
+| Small files, functions, and complexity, `CC-033..CC-059`, `CC-137..CC-142`, `CC-206` | `complexity`, `max-depth`, `max-lines`, `max-lines-per-function`, `max-params`, `sonarjs/cognitive-complexity` |
+| Magic numbers and repeated literals, `CC-018`, `CC-234` | `@typescript-eslint/no-magic-numbers`, `sonarjs/no-duplicate-string` |
+| TODO/FIXME visibility, `CC-068` | `clean-code/todo-format` |
+| Duplicate conditions and branches, `CC-160`, `CC-214` | `sonarjs/no-duplicated-branches`, `sonarjs/no-identical-conditions`, `sonarjs/no-identical-functions` |
+| Complex and negative conditionals, `CC-237`, `CC-238` | `no-nested-ternary`, `no-negated-condition`, `sonarjs/no-inverted-boolean-check`, `unicorn/no-negated-condition` |
+| Null avoidance, `CC-118`, `CC-119` | `unicorn/no-null`, `@typescript-eslint/no-unnecessary-condition`, `@typescript-eslint/prefer-nullish-coalescing` |
+| Dead and redundant code, `CC-209`, `CC-218`, `CC-221` | `@typescript-eslint/no-unused-vars`, `no-empty`, `no-useless-return`, `sonarjs/no-dead-store` |
+| Long import lists, `CC-246` | `no-restricted-syntax` custom selector over `ImportDeclaration[specifiers.length>10]` |
+| Naming consistency, `CC-011`, `CC-025`, `CC-249..CC-255` | `@typescript-eslint/naming-convention` |
+| Async precision and type clarity, `CC-235` | `@typescript-eslint/no-floating-promises`, `@typescript-eslint/no-misused-promises`, `@typescript-eslint/switch-exhaustiveness-check`, `eqeqeq` |
+
+## Custom Gap Coverage
+
+These corpus candidates are implemented by the local clean-code plugin:
+
+- commented-out TypeScript code detection: `clean-code/no-commented-out-code`, `CC-083`
+- TODO format such as `TODO(PROJ-123): ...`: `clean-code/todo-format`, `CC-068`
+- boolean literal arguments at call sites and boolean selector parameters: `clean-code/no-boolean-flag-arguments`, `CC-043`, `CC-208`
+- output argument mutation: `clean-code/no-output-argument-mutation`, `CC-207`
+- comments that restate the following line: `clean-code/no-redundant-comment`, `CC-071`, `CC-073`
+- byline/date comments, separator comments, and closing-brace comments: `clean-code/no-noisy-comments`, `CC-080..CC-082`
+- business-policy string/date/status literals: `clean-code/no-business-policy-literals`, `CC-002`, `CC-234`
+- Law of Demeter / train-wreck chains: `clean-code/no-train-wrecks`, `CC-106`, `CC-107`, `CC-245`
+
+See [eslint-custom-rules.md](./eslint-custom-rules.md) for rule details.
+
+## Python Config
+
+Python projects should use the Ruff + Pylint config in [python-lint-recommended-config.md](./python-lint-recommended-config.md).

package/docs/fastmcp-local-server.md

@@ -0,0 +1,104 @@
+# FastMCP Local Server
+
+This server exposes clean-code pattern lookup tools through FastMCP. Coding
+agents should use the pattern-first tools for review/refactor decisions and keep
+the lower-level chunk search for diagnostics.
+
+## Install
+
+```bash
+uv sync
+```
+
+## Prepare Weaviate
+
+```bash
+bun run weaviate:dev:start
+bun run weaviate:dev:smoke
+bun run semantic:ingest -- --reset
+```
+
+If the default port is busy, use the same alternate port for all commands:
+
+```bash
+WEAVIATE_HTTP_PORT=38080 WEAVIATE_GRPC_PORT=35051 bun run weaviate:dev:start
+WEAVIATE_HTTP_PORT=38080 bun run weaviate:dev:smoke
+bun run semantic:ingest -- --url http://127.0.0.1:38080 --reset
+```
+
+## Run MCP
+
+Stdio:
+
+```bash
+bun run mcp:stdio
+```
+
+HTTP:
+
+```bash
+bun run mcp:http
+```
+
+The HTTP server defaults to `http://127.0.0.1:8765`.
+
+## Exposed Tools
+
+- `clean_code_corpus_summary`: returns corpus chunk counts.
+- `clean_code_weaviate_schema`: returns the `CleanCodeChunks` schema payload.
+- `search_clean_code`: low-level compatibility search over populated Weaviate chunks.
+- `search_clean_code_patterns`: pattern-first search for concrete code smells.
+- `get_clean_code_pattern`: full canonical lookup by `CC-###` ID.
+- `recommend_clean_code_lint_rules`: lint-rule candidate guidance for repeated smells.
+- `list_clean_code_facets`: available filter values and counts.
+
+Pattern-first search arguments:
+
+```json
+{
+  "query": "typescript boolean parameter controls behavior",
+  "language": "typescript",
+  "lintability": ["high", "medium"],
+  "limit": 5,
+  "weaviate_url": "http://127.0.0.1:8080"
+}
+```
+
+Full pattern lookup:
+
+```json
+{
+  "pattern_id": "CC-043"
+}
+```
+
+Lint-rule recommendation:
+
+```json
+{
+  "query": "TODO comments without issue IDs",
+  "language": "typescript",
+  "targets": ["eslint", "semgrep"]
+}
+```
+
+## Agent Workflow
+
+Use the MCP after inspecting code and forming a concrete smell hypothesis. Send
+short queries such as `python function mutates output argument and returns
+status`, not whole files or full diffs.
+
+Recommended review loop:
+
+1. Read the changed code and nearby tests.
+2. Identify one maintainability concern.
+3. Query `search_clean_code_patterns` with language and narrow filters.
+4. Fetch detail with `get_clean_code_pattern` only for a relevant result.
+5. Use the pattern as support for a local code finding, not as the finding
+   itself.
+6. Suppress weak results or framework-idiomatic near-misses.
+
+`search_clean_code_patterns` returns `confidence`, `score`, `match_reasons`,
+and top-level `no_strong_match`. Treat `no_strong_match` as a signal to avoid
+surfacing a clean-code recommendation unless the local code evidence is already
+strong.

package/docs/publishing.md

@@ -0,0 +1,125 @@
+# Publishing
+
+This repo publishes two native package shapes from the same source tree.
+
+## Registries
+
+- npm registry: `clean-code-tools`
+- PyPI: `clean-code-tools-python`
+
+These are production registry names. If either name is already taken, rename the
+package in `package.json` or `pyproject.toml` before the first publish.
+
+## TypeScript / ESLint
+
+The npm package exposes:
+
+- `clean-code-tools`
+- `clean-code-tools/eslint-plugin`
+- `clean-code-tools/configs/eslint.clean-code.recommended.mjs`
+- `clean-code-tools/configs/python.clean-code.pyproject.toml`
+
+Before publishing:
+
+```bash
+bun run check:packages
+npm publish --dry-run --provenance
+```
+
+The package must not set `private: true`; otherwise npm refuses publication. The
+GitHub Actions workflows use npm trusted publishing with provenance, so configure
+the npm package's trusted publisher to allow this repository and these workflow
+files:
+
+- `.github/workflows/publish-main.yml`
+
+The workflows use Node 24 so the bundled npm supports trusted publishing.
+
+## Python / Pylint
+
+The PyPI package is `clean-code-tools-python`. It installs:
+
+- the `clean_code_tools_pylint` plugin package
+- Ruff and Pylint runtime dependencies
+- the reusable config as package data at
+  `clean_code_tools_pylint/configs/python.clean-code.pyproject.toml`
+
+Before publishing:
+
+```bash
+bun run check:packages
+uv build
+uv publish --dry-run
+```
+
+Configure PyPI trusted publishers for this repository and these workflow files:
+
+- `.github/workflows/publish-main.yml`
+
+The workflows use `uv publish --trusted-publishing always`, so no PyPI token is
+stored in GitHub secrets.
+
+The package smoke check builds a wheel, installs it into an isolated virtualenv,
+loads the packaged config through `importlib.resources`, then runs Ruff and
+Pylint against a fixture that must trigger the custom `clean-code-*` messages.
+
+## Versioning
+
+The source manifests keep a stable release base:
+
+- `package.json`
+- `pyproject.toml`
+
+Use `scripts/set_package_versions.py` to update them together:
+
+```bash
+uv run python scripts/set_package_versions.py --release 1.2.3
+uv run python scripts/set_package_versions.py --bump patch --base 1.2.3
+```
+
+`bun run check:packages` requires exact version parity between npm and Python.
+Packages are never given a development suffix.
+
+Every push or merge to `develop` runs `.github/workflows/version-develop.yml`.
+It reads the latest `vX.Y.Z` tag, bumps the patch version, writes that version to
+`package.json` and `pyproject.toml`, runs the full check, then commits the
+version update back to `develop` and creates a matching `vX.Y.Z` tag on that
+develop commit.
+
+Publishing happens only from `main`. Merge `develop` into `main` after the
+versioning workflow has created the version commit and tag. A push to `main`
+runs `.github/workflows/publish-main.yml`, verifies that the manifest version has
+a matching `vX.Y.Z` tag reachable from `main`, runs the full check, then
+publishes npm `latest` plus the PyPI final release.
+
+If a change needs a minor or major bump, run the version script manually on
+`develop` before merging, or adjust the workflow bump type for that release.
+
+## SemVer Policy
+
+Publish the Python package and npm package with matching versions when rule
+semantics change. Patch-only documentation or packaging fixes can ship
+independently if the lint behavior is unchanged.
+
+The package check enforces version parity between `package.json` and
+`pyproject.toml`, so bump both manifests in the same release change.
+
+Use SemVer for both registries:
+
+- patch: documentation, packaging, or false-positive tuning that reduces noise
+- minor: new rules, new recommended warnings, or new MCP candidate mappings
+- major: removed rules, renamed public exports, or stricter defaults that create
+  a large new failure surface
+
+## References
+
+- npm publishing and provenance:
+  <https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages>
+- npm package versions are immutable after publish:
+  <https://docs.npmjs.com/cli/v11/commands/npm-publish/>
+- PyPI trusted publishing:
+  <https://docs.pypi.org/trusted-publishers/adding-a-publisher/>
+- GitHub OIDC setup for PyPI:
+  <https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-pypi>
+- uv publishing with trusted publishers:
+  <https://docs.astral.sh/uv/guides/package/>

package/docs/python-lint-recommended-config.md

@@ -0,0 +1,57 @@
+# Python Recommended Clean-Code Config
+
+Use [configs/python.clean-code.pyproject.toml](../configs/python.clean-code.pyproject.toml) as a reusable `pyproject.toml` fragment for Python projects that want clean-code-oriented linting.
+
+The config intentionally mixes Ruff and Pylint:
+
+- Ruff owns fast local checks: syntax/correctness, imports, bug-prone patterns, simple refactors, commented-out code, TODO shape, unused arguments, return-flow cleanup, magic-value comparisons, and Ruff-specific quality checks.
+- Pylint owns broader design pressure: too many module lines, arguments, locals, branches, returns, statements, nested blocks, public methods, instance attributes, duplicate code, cyclic imports, and the custom Python clean-code plugin.
+
+## Install
+
+```bash
+python -m pip install clean-code-tools-python
+```
+
+Copy the config into a project root as `pyproject.toml`, or merge its `[tool.ruff]`, `[tool.ruff.lint]`, and `[tool.pylint.*]` sections into an existing `pyproject.toml`.
+
+The Python package installs Ruff, Pylint, and the custom Pylint plugin module
+`clean_code_tools_pylint`. The canonical reusable config is packaged as
+`clean_code_tools_pylint/configs/python.clean-code.pyproject.toml`; this repo
+also keeps a copy at [configs/python.clean-code.pyproject.toml](../configs/python.clean-code.pyproject.toml)
+for local and JavaScript-package consumers.
+
+Run:
+
+```bash
+ruff check .
+pylint .
+```
+
+## Clean-Code Coverage
+
+| Corpus area | Tool coverage |
+| --- | --- |
+| Commented-out code, `CC-083` | Ruff `ERA` |
+| TODO/FIXME visibility and tracking, `CC-068` | Ruff `TD` |
+| Magic numbers / named constants, `CC-018`, `CC-234` | Ruff `PLR2004` |
+| Dead and unused code, `CC-209`, `CC-218`, `CC-221` | Ruff `F`, `ARG`, `B` |
+| Import readability and ordering, `CC-246` | Ruff `I`, `F401` |
+| Return-flow cleanup, `CC-237`, `CC-238` adjacent | Ruff `RET`, `SIM` |
+| File, function, and class size pressure, `CC-033..CC-059`, `CC-137..CC-142`, `CC-206` | Pylint `too-many-lines` plus design messages |
+| Duplication and coupling signals, `CC-004`, `CC-160`, `CC-214` | Pylint `duplicate-code`, `cyclic-import` |
+| Custom clean-code gaps matching the TypeScript plugin, `CC-043`, `CC-050`, `CC-068`, `CC-071`, `CC-073`, `CC-080`, `CC-083`, `CC-106`, `CC-107`, `CC-207`, `CC-208`, `CC-224`, `CC-245` | Pylint plugin `clean-code-*` messages |
+
+## Notes
+
+Ruff does not currently support project-local custom rule plugins, so the config only uses built-in Ruff rule families. Pylint is included because its design checker still provides useful clean-code pressure that Ruff either does not cover or would duplicate less flexibly.
+
+The thresholds are intentionally strict enough to act as early architecture-smell signals: modules warn above 300 lines, functions warn through statement count, and classes warn when public methods or attributes accumulate. Relax them for framework entrypoints, generated code, migrations, tests, and compatibility layers through project-local overrides.
+
+## Remaining Custom Candidates
+
+The remaining custom candidates are mostly domain-specific allowlists and
+project-specific suppression policies around the `clean-code-*` messages.
+
+See [python-pylint-custom-rules.md](./python-pylint-custom-rules.md) for the
+custom rule details.

package/docs/python-pylint-custom-rules.md

@@ -0,0 +1,77 @@
+# Python Custom Clean-Code Rules
+
+The local Pylint plugin lives at
+[src/python/clean_code_tools_pylint/](../src/python/clean_code_tools_pylint/). These rules
+mirror the project-owned ESLint clean-code rules where Python syntax gives us a
+reasonably precise static signal.
+
+## Rules
+
+### `clean-code-todo-format`
+
+Requires TODO/FIXME/XXX comments to include an issue-like owner by default:
+
+```python
+# TODO(BILL-412): remove fallback after migration.
+```
+
+Corpus: `CC-068`
+
+### `clean-code-commented-out-code`
+
+Flags comments that look like disabled Python code.
+
+Corpus: `CC-083`
+
+### `clean-code-boolean-flag-argument`
+
+Flags boolean literals passed at call sites and boolean selector parameters with
+mode-like names such as `dry_run`, `force`, `skip`, `include`, or `mode`.
+
+Corpus: `CC-043`, `CC-208`, `CC-224`
+
+### `clean-code-output-argument-mutation`
+
+Flags assignments, updates, and common mutator calls that mutate function
+parameters.
+
+Corpus: `CC-050`, `CC-207`
+
+### `clean-code-redundant-comment`
+
+Flags comments whose words heavily overlap the following line of code.
+
+Corpus: `CC-071`, `CC-073`
+
+### `clean-code-noisy-comment`
+
+Flags separator comments and author/date byline comments.
+
+Corpus: `CC-080`, `CC-081`
+
+### `clean-code-business-policy-literal`
+
+Flags hard-coded policy-looking literals outside named constants and allowlisted
+calls. The heuristic catches:
+
+- numbers other than `-1`, `0`, and `1`
+- all-caps string values
+- ISO date strings
+- common domain statuses such as `active`, `approved`, `draft`, `failed`,
+  `pending`, and `rejected`
+
+Corpus: `CC-002`, `CC-018`, `CC-234`
+
+### `clean-code-train-wreck`
+
+Flags deep attribute chains beyond the default maximum depth.
+
+Corpus: `CC-106`, `CC-107`, `CC-245`
+
+## Recommended Config
+
+The plugin is loaded and these messages are enabled in
+[configs/python.clean-code.pyproject.toml](../configs/python.clean-code.pyproject.toml).
+
+They are intentionally warnings/design signals because each rule is heuristic
+and should be tuned per repository.