clean-code-tools 1.0.1

package/src/python/clean_code_tools_pylint/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from pylint.lint import PyLinter
+
+from .ast_checker import CleanCodeAstChecker
+from .comments import CleanCodeCommentChecker
+
+
+def register(linter: PyLinter) -> None:
+    if getattr(linter, "_clean_code_tools_registered", False):  # pylint: disable=clean-code-boolean-flag-argument
+        return
+    linter._clean_code_tools_registered = True
+    linter.register_checker(CleanCodeCommentChecker(linter))
+    linter.register_checker(CleanCodeAstChecker(linter))

package/src/python/clean_code_tools_pylint/ast_checker.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from astroid import nodes
+from pylint.checkers import BaseChecker
+from pylint.lint import PyLinter
+
+from .helpers import (
+    MAX_ATTRIBUTE_CHAIN_DEPTH,
+    MUTATOR_METHODS,
+    annotation_is_bool,
+    attribute_depth,
+    is_allowed_literal_context,
+    is_policy_literal_context,
+    literal_looks_like_policy,
+    name_looks_like_selector,
+    root_name,
+)
+
+
+class CleanCodeAstChecker(BaseChecker):
+    name = "clean-code-ast"
+    msgs: ClassVar = {
+        "C9003": (
+            "Boolean selector argument changes behavior by mode; prefer named operations or an explicit options object.",
+            "clean-code-boolean-flag-argument",
+            "Discourage boolean selector arguments and boolean mode parameters.",
+        ),
+        "C9004": (
+            "Avoid mutating parameter '%s' as an output argument; return a value or create a local copy instead.",
+            "clean-code-output-argument-mutation",
+            "Flag parameter mutation that treats arguments as output containers.",
+        ),
+        "C9007": (
+            "Policy literal '%s' should usually be a named constant so the rule is searchable.",
+            "clean-code-business-policy-literal",
+            "Flag hard-coded policy literals in branch, return, and call expressions.",
+        ),
+        "C9008": (
+            "Deep attribute chain exposes object internals; prefer a named query on the owning object.",
+            "clean-code-train-wreck",
+            "Flag deep attribute chains that expose transitive object structure.",
+        ),
+    }
+
+    def __init__(self, linter: PyLinter) -> None:
+        super().__init__(linter)
+        self._function_params: list[set[str]] = []
+        self._function_locals: list[set[str]] = []
+
+    def visit_functiondef(self, node: nodes.FunctionDef) -> None:
+        params = {argument.name for argument in node.args.args + node.args.kwonlyargs}
+        self._function_params.append(params)
+        self._function_locals.append(set())
+        self.check_boolean_params(node)
+
+    visit_asyncfunctiondef = visit_functiondef
+
+    def leave_functiondef(self, _node: nodes.FunctionDef) -> None:
+        self._function_params.pop()
+        self._function_locals.pop()
+
+    leave_asyncfunctiondef = leave_functiondef
+
+    def visit_assignname(self, node: nodes.AssignName) -> None:
+        if isinstance(node.parent, nodes.Arguments):
+            return
+        if self._function_locals:
+            self._function_locals[-1].add(node.name)
+
+    def visit_call(self, node: nodes.Call) -> None:
+        for argument in node.args:
+            if isinstance(argument, nodes.Const) and isinstance(argument.value, bool):
+                self.add_message("clean-code-boolean-flag-argument", node=argument)
+        if isinstance(node.func, nodes.Attribute) and node.func.attrname in MUTATOR_METHODS:
+            self.report_if_param_mutation(node.func.expr, node.func.expr)
+
+    def visit_assignattr(self, node: nodes.AssignAttr) -> None:
+        self.report_if_param_mutation(node, node)
+
+    def visit_assign(self, node: nodes.Assign) -> None:
+        for target in node.targets:
+            self.report_if_param_mutation(target, target)
+
+    def visit_augassign(self, node: nodes.AugAssign) -> None:
+        self.report_if_param_mutation(node.target, node.target)
+
+    def visit_const(self, node: nodes.Const) -> None:
+        if (
+            literal_looks_like_policy(node.value)
+            and is_policy_literal_context(node)
+            and not is_allowed_literal_context(node)
+        ):
+            self.add_message("clean-code-business-policy-literal", node=node, args=(str(node.value),))
+
+    def visit_attribute(self, node: nodes.Attribute) -> None:
+        if isinstance(node.parent, nodes.Attribute):
+            return
+        if attribute_depth(node) > MAX_ATTRIBUTE_CHAIN_DEPTH:
+            self.add_message("clean-code-train-wreck", node=node)
+
+    def check_boolean_params(self, node: nodes.FunctionDef) -> None:
+        arguments = node.args.args + node.args.kwonlyargs
+        annotations = node.args.annotations + node.args.kwonlyargs_annotations
+        for argument, annotation in zip(arguments, annotations, strict=False):
+            if argument.name in {"self", "cls"}:
+                continue
+            if annotation_is_bool(annotation) and name_looks_like_selector(argument.name):
+                self.add_message("clean-code-boolean-flag-argument", node=argument)
+
+    def report_if_param_mutation(self, node: nodes.NodeNG, expression: nodes.NodeNG) -> None:
+        name = root_name(expression)
+        if not name or name in {"self", "cls"}:
+            return
+        scopes = zip(reversed(self._function_params), reversed(self._function_locals), strict=False)
+        for params, locals_ in scopes:
+            if name in locals_:
+                return
+            if name in params:
+                self.add_message("clean-code-output-argument-mutation", node=node, args=(name,))
+                return

package/src/python/clean_code_tools_pylint/comments.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import tokenize
+from io import BytesIO
+from typing import ClassVar
+
+from astroid import nodes
+from pylint.checkers import BaseRawFileChecker
+
+from .helpers import (
+    MIN_SHARED_COMMENT_WORDS,
+    REDUNDANT_COMMENT_OVERLAP_RATIO,
+    TODO_PATTERN,
+    TODO_SEGMENT,
+    clean_comment,
+    is_byline_or_date,
+    is_likely_code_comment,
+    is_separator_comment,
+    normalized_words,
+)
+
+
+class CleanCodeCommentChecker(BaseRawFileChecker):
+    name = "clean-code-comments"
+    msgs: ClassVar = {
+        "C9001": (
+            "TODO/FIXME comments should include an owner or issue ID, for example TODO(PROJ-123): remove fallback.",
+            "clean-code-todo-format",
+            "Require TODO, FIXME, and XXX comments to include an owner or issue identifier.",
+        ),
+        "C9002": (
+            "Remove commented-out code; version history should preserve old implementations.",
+            "clean-code-commented-out-code",
+            "Flag comments that look like disabled Python code.",
+        ),
+        "C9005": (
+            "Comment mostly repeats the next line; prefer making the code name carry the intent.",
+            "clean-code-redundant-comment",
+            "Flag comments that mostly repeat the following line of code.",
+        ),
+        "C9006": (
+            "Avoid noisy separator, byline, or date comments; use structure and version control instead.",
+            "clean-code-noisy-comment",
+            "Flag separator, byline, and date comments.",
+        ),
+    }
+
+    def process_module(self, node: nodes.Module) -> None:
+        raw_bytes = node.stream().read()
+        lines = raw_bytes.decode("utf-8", errors="replace").splitlines()
+        for token in tokenize.tokenize(BytesIO(raw_bytes).readline):
+            if token.type != tokenize.COMMENT:
+                continue
+            text = clean_comment(token.string)
+            line_number = token.start[0]
+            self.check_todo(text, line_number)
+            self.check_comment_shape(text, line_number)
+            self.check_redundant_comment(text, line_number, lines)
+
+    def check_todo(self, text: str, line_number: int) -> None:
+        todo_segments = TODO_SEGMENT.findall(text)
+        if any(not TODO_PATTERN.match(segment.strip()) for segment in todo_segments):
+            self.add_message("clean-code-todo-format", line=line_number)
+
+    def check_comment_shape(self, text: str, line_number: int) -> None:
+        if TODO_SEGMENT.search(text):
+            return
+        if is_likely_code_comment(text):
+            self.add_message("clean-code-commented-out-code", line=line_number)
+        if is_separator_comment(text) or is_byline_or_date(text):
+            self.add_message("clean-code-noisy-comment", line=line_number)
+
+    def check_redundant_comment(self, text: str, line_number: int, lines: list[str]) -> None:
+        comment_words = normalized_words(text)
+        if len(comment_words) < MIN_SHARED_COMMENT_WORDS or line_number >= len(lines):
+            return
+        next_line_words = set(normalized_words(lines[line_number]))
+        shared_words = [word for word in comment_words if word in next_line_words]
+        if (
+            len(shared_words) >= MIN_SHARED_COMMENT_WORDS
+            and len(shared_words) / len(comment_words) >= REDUNDANT_COMMENT_OVERLAP_RATIO
+        ):
+            self.add_message("clean-code-redundant-comment", line=line_number)

package/src/python/clean_code_tools_pylint/helpers.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from astroid import nodes
+
+TODO_PATTERN = re.compile(r"^(TODO|FIXME|XXX)\([A-Z][A-Z0-9]+-\d+\):\s+\S", re.IGNORECASE)
+TODO_SEGMENT = re.compile(r"\b(?:TODO|FIXME|XXX)\b[^\n;]*", re.IGNORECASE)
+SELECTOR_PARAM_NAMES = (
+    "flag",
+    "mode",
+    "option",
+    "type",
+    "kind",
+    "variant",
+    "selector",
+    "enabled",
+    "disabled",
+    "dry_run",
+    "verbose",
+    "silent",
+    "force",
+    "skip",
+    "include",
+    "exclude",
+)
+MUTATOR_METHODS = {
+    "add",
+    "append",
+    "clear",
+    "discard",
+    "extend",
+    "insert",
+    "pop",
+    "popitem",
+    "remove",
+    "reverse",
+    "setdefault",
+    "sort",
+    "update",
+}
+ALLOWED_LITERAL_CALLS = {
+    "bool",
+    "bytes",
+    "dict",
+    "float",
+    "int",
+    "len",
+    "list",
+    "print",
+    "range",
+    "repr",
+    "set",
+    "str",
+    "tuple",
+}
+STATUS_WORD = re.compile(
+    r"(?:^|[_\s-])(active|approved|cancelled|canceled|draft|failed|paid|pending|rejected|retry|suspended)(?:$|[_\s-])",
+    re.IGNORECASE,
+)
+MIN_CODE_COMMENT_LENGTH = 4
+MIN_SEPARATOR_LENGTH = 8
+MIN_POLICY_STRING_LENGTH = 2
+MIN_SHARED_COMMENT_WORDS = 2
+REDUNDANT_COMMENT_OVERLAP_RATIO = 0.65
+MAX_ATTRIBUTE_CHAIN_DEPTH = 3
+
+
+def clean_comment(comment: str) -> str:
+    return comment.lstrip("#").strip()
+
+
+def normalized_words(value: str) -> list[str]:
+    return re.findall(r"[a-z][a-z0-9]+", re.sub(r"[_$]+", " ", value).lower())
+
+
+def is_likely_code_comment(text: str) -> bool:
+    if len(text.strip()) < MIN_CODE_COMMENT_LENGTH:
+        return False
+    code_patterns = (
+        r"\b(await|def|class|return|raise|if|for|while|match|import|from|with|try|except)\b",
+        r"(?:^|\s)[\w.]+\([^)]*\)\s*$",
+        r"^\s*[\w.]+\s*=\s*.+$",
+        r"[{}\[\]]",
+        r"->",
+    )
+    return any(re.search(pattern, text) for pattern in code_patterns)
+
+
+def is_separator_comment(text: str) -> bool:
+    compact = re.sub(r"\s+", "", text)
+    return len(compact) >= MIN_SEPARATOR_LENGTH and bool(re.fullmatch(r"[-=*_/#]+", compact))
+
+
+def is_byline_or_date(text: str) -> bool:
+    byline = r"\b(author|created by|written by|modified by|last modified|since)\b"
+    date = r"\b(?:\d{4}[-/]\d{1,2}[-/]\d{1,2}|\d{1,2}[-/]\d{1,2}[-/]\d{2,4})\b"
+    return bool(re.search(byline, text, re.IGNORECASE) or re.search(date, text))
+
+
+def annotation_is_bool(annotation: nodes.NodeNG | None) -> bool:
+    return isinstance(annotation, nodes.Name) and annotation.name == "bool"
+
+
+def name_looks_like_selector(name: str) -> bool:
+    lower_name = name.lower()
+    return any(selector in lower_name for selector in SELECTOR_PARAM_NAMES)
+
+
+def call_name(node: nodes.Call) -> str | None:
+    func = node.func
+    if isinstance(func, nodes.Name):
+        return func.name
+    if isinstance(func, nodes.Attribute):
+        return func.attrname
+    return None
+
+
+def root_name(node: nodes.NodeNG) -> str | None:
+    current = node
+    while isinstance(current, (nodes.Attribute, nodes.Subscript)):
+        current = current.expr if isinstance(current, nodes.Attribute) else current.value
+    if isinstance(current, nodes.Name):
+        return current.name
+    return None
+
+
+def is_uppercase_assignment(node: nodes.Const) -> bool:
+    parent = node.parent
+    if not isinstance(parent, (nodes.Assign, nodes.AnnAssign)):
+        return False
+    targets = parent.targets if isinstance(parent, nodes.Assign) else [parent.target]
+    return any(isinstance(target, nodes.AssignName) and target.name.isupper() for target in targets)
+
+
+def literal_looks_like_policy(value: Any) -> bool:
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, int | float):
+        return value not in {-1, 0, 1}
+    if not isinstance(value, str) or len(value) < MIN_POLICY_STRING_LENGTH:
+        return False
+    return bool(
+        re.fullmatch(r"[A-Z][A-Z0-9_]+", value)
+        or re.fullmatch(r"\d{4}-\d{2}-\d{2}", value)
+        or STATUS_WORD.search(value)
+    )
+
+
+def is_allowed_literal_context(node: nodes.Const) -> bool:
+    if is_uppercase_assignment(node):
+        return True
+    current = node.parent
+    while current is not None:
+        if isinstance(current, nodes.Call) and call_name(current) in ALLOWED_LITERAL_CALLS:
+            return True
+        current = current.parent
+    return False
+
+
+def is_policy_literal_context(node: nodes.Const) -> bool:
+    if isinstance(node.value, int | float) and not literal_looks_like_named_threshold(node):
+        return False
+    current = node.parent
+    while current is not None and not isinstance(
+        current,
+        (nodes.ClassDef, nodes.FunctionDef, nodes.AsyncFunctionDef, nodes.Module),
+    ):
+        if isinstance(current, (nodes.Compare, nodes.If, nodes.Return, nodes.Call)):
+            return True
+        if isinstance(current, nodes.Assign):
+            return any(isinstance(target, (nodes.AssignAttr, nodes.Subscript)) for target in current.targets)
+        current = current.parent
+    return False
+
+
+def literal_looks_like_named_threshold(node: nodes.Const) -> bool:
+    current = node.parent
+    while current is not None and not isinstance(
+        current,
+        (nodes.ClassDef, nodes.FunctionDef, nodes.AsyncFunctionDef, nodes.Module),
+    ):
+        if isinstance(current, nodes.Compare):
+            return True
+        current = current.parent
+    return False
+
+
+def attribute_depth(node: nodes.Attribute) -> int:
+    depth = 0
+    current: nodes.NodeNG = node
+    while isinstance(current, nodes.Attribute):
+        depth += 1
+        current = current.expr
+    return depth

package/src/python/mcp_server/__init__.py

@@ -0,0 +1 @@
+

package/src/python/mcp_server/corpus.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import uuid
+from pathlib import Path
+
+from mcp_server.markdown import (
+    infer_markdown_rule_family,
+    markdown_aliases,
+    markdown_sections,
+    split_section_body,
+)
+from mcp_server.models import CleanCodeChunk, JsonDict
+from mcp_server.text import (
+    clean_alias,
+    clean_topic,
+    clean_topic_text,
+    detected_record_id,
+    languages_in_text,
+    lint_candidates_in_text,
+    slug,
+)
+from mcp_server.utils.sha256_text import sha256_text
+
+ROOT = Path(__file__).resolve().parents[3]
+PATTERN_RECORDS = ROOT / "data" / "clean-code-patterns.jsonl"
+MARKDOWN_SOURCES = (
+    ROOT / "README.md",
+    ROOT / "docs" / "eslint-custom-rules.md",
+    ROOT / "docs" / "eslint-recommended-config.md",
+    ROOT / "docs" / "python-lint-recommended-config.md",
+    ROOT / "docs" / "python-pylint-custom-rules.md",
+    ROOT / "docs" / "static-trigger-semantic-review.md",
+)
+CHUNK_ID_NAMESPACE = uuid.UUID("fd1b279f-073e-5aa4-bf70-9f70446a3d8f")
+
+
+def build_chunks(root: Path = ROOT) -> list[CleanCodeChunk]:
+    chunks = [*pattern_record_chunks(root / PATTERN_RECORDS.relative_to(ROOT))]
+    for source in MARKDOWN_SOURCES:
+        path = root / source.relative_to(ROOT)
+        if path.exists():
+            chunks.extend(markdown_chunks(path, root=root))
+    return chunks
+
+
+def pattern_record_chunks(path: Path) -> list[CleanCodeChunk]:
+    chunks: list[CleanCodeChunk] = []
+    with path.open() as handle:
+        for index, line in enumerate(handle):
+            if not line.strip():
+                continue
+            record = json.loads(line)
+            chunk_id = f"pattern:{record['id']}"
+            topic = clean_topic(str(record["topic"]))
+            aliases = tuple(
+                alias
+                for alias in (clean_alias(str(item)) for item in record["aliases"])
+                if alias
+            )
+            embedding_text = clean_topic_text(str(record["embedding_text"]).strip())
+            display_text = clean_topic_text(str(record["display_text"]).strip())
+            languages = tuple(
+                language
+                for language in ("typescript", "python")
+                if record.get("good_examples", {}).get(language)
+                or record.get("bad_examples", {}).get(language)
+            )
+            chunks.append(
+                CleanCodeChunk(
+                    chunk_id=chunk_id,
+                    object_id=object_id_for(chunk_id),
+                    source_file=path.name,
+                    source_kind="clean_code_pattern",
+                    record_id=str(record["id"]),
+                    title=str(record["title"]),
+                    topic=topic,
+                    section_path=(topic, str(record["title"])),
+                    chunk_kind="pattern_record",
+                    chunk_index=index,
+                    rule_family=str(record["rule_family"]),
+                    lintability=str(record["lintability"]),
+                    aliases=aliases,
+                    languages=languages,
+                    lint_candidates=tuple(str(item) for item in record["lint_candidates"]),
+                    content_text=display_text,
+                    embedding_text=embedding_text,
+                    display_text=display_text,
+                    text_hash=sha256_text(embedding_text),
+                )
+            )
+    return chunks
+
+
+def load_pattern_records(path: Path = PATTERN_RECORDS) -> list[JsonDict]:
+    records: list[JsonDict] = []
+    with path.open() as handle:
+        for line in handle:
+            if line.strip():
+                record = json.loads(line)
+                if isinstance(record, dict):
+                    records.append(record)
+    return records
+
+
+def get_pattern_record(pattern_id: str, *, root: Path = ROOT) -> JsonDict | None:
+    normalized_id = pattern_id.strip().upper()
+    for record in load_pattern_records(root / PATTERN_RECORDS.relative_to(ROOT)):
+        if str(record.get("id", "")).upper() == normalized_id:
+            return record
+    return None
+
+
+def markdown_chunks(path: Path, *, root: Path = ROOT) -> list[CleanCodeChunk]:
+    chunks: list[CleanCodeChunk] = []
+    relative_path = path.relative_to(root).as_posix()
+    for section_index, section in enumerate(markdown_sections(path, root=root)):
+        for split_index, body in enumerate(split_section_body(section.body)):
+            heading_text = " > ".join(section.section_path)
+            record_id = detected_record_id(section.heading)
+            chunk_id = (
+                f"md:{relative_path}:{slug(heading_text)}"
+                if split_index == 0
+                else f"md:{relative_path}:{slug(heading_text)}:{split_index + 1}"
+            )
+            content_text = clean_topic_text(body.strip())
+            embedding_text = (
+                f"Markdown section: {heading_text}\n"
+                f"Source: {relative_path}:{section.start_line}-{section.end_line}\n\n"
+                f"{content_text}"
+            )
+            chunks.append(
+                CleanCodeChunk(
+                    chunk_id=chunk_id,
+                    object_id=object_id_for(chunk_id),
+                    source_file=relative_path,
+                    source_kind="markdown_doc",
+                    record_id=record_id,
+                    title=section.heading,
+                    topic=clean_topic(section.section_path[0]) if section.section_path else clean_topic(section.heading),
+                    section_path=tuple(clean_topic(item) for item in section.section_path),
+                    chunk_kind="markdown_section" if split_index == 0 else "markdown_section_part",
+                    chunk_index=section_index * 100 + split_index,
+                    rule_family=infer_markdown_rule_family(section),
+                    lintability="",
+                    aliases=tuple(clean_alias(alias) for alias in markdown_aliases(section) if clean_alias(alias)),
+                    languages=languages_in_text(content_text),
+                    lint_candidates=lint_candidates_in_text(content_text),
+                    content_text=content_text,
+                    embedding_text=embedding_text,
+                    display_text=embedding_text,
+                    text_hash=sha256_text(embedding_text),
+                )
+            )
+    return chunks
+
+
+def object_id_for(chunk_id: str) -> str:
+    return str(uuid.uuid5(CHUNK_ID_NAMESPACE, chunk_id))