sarj-python-lint 0.2.0__tar.gz

sarj_python_lint-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+node_modules/
+dist/
+build/
+*.tgz
+.npm/
+*.tsbuildinfo
+.turbo/
+.tsup/
+.vitest-cache/
+.eslintcache
+coverage/
+
+__pycache__/
+*.py[co]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.basedpyright/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.venv/
+venv/
+*.egg-info/
+
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+.zed/
+*.swp

sarj_python_lint-0.2.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: sarj-python-lint
+Version: 0.2.0
+Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
+Project-URL: Homepage, https://github.com/sarj-ai/linting/tree/main/packages/python
+Project-URL: Repository, https://github.com/sarj-ai/linting
+Project-URL: Issues, https://github.com/sarj-ai/linting/issues
+Author: sarj-ai
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# sarj-python-lint
+
+Custom Python lint rules via stdlib `ast`. Designed for pre-commit. For SQL rules see [`sarj-sql-lint`](../sql/).
+
+```bash
+uv tool install sarj-python-lint
+```
+
+## Pre-commit
+
+```yaml
+- repo: https://github.com/sarj-ai/linting
+  rev: python-v0.2.0
+  hooks:
+    - id: sarj-no-sequential-await
+    - id: sarj-inefficient-string-concat-in-loop
+    - id: sarj-prefer-discriminated-union
+    - id: sarj-prefer-str-enum
+```
+
+## CLI
+
+```bash
+sarj-python-lint check --rule no-sequential-await path/to/file.py
+sarj-python-lint list-rules
+```
+
+Diagnostic format is `path:line:col: CODE message` — Ruff-compatible.
+
+## Suppression
+
+Inline `# sarj-noqa: SARJ00X — <reason>` on the offending line.
+
+Each rule's source under `src/sarj_python_lint/rules/` carries its own `description` and diagnostic message.

sarj_python_lint-0.2.0/README.md

@@ -0,0 +1,34 @@
+# sarj-python-lint
+
+Custom Python lint rules via stdlib `ast`. Designed for pre-commit. For SQL rules see [`sarj-sql-lint`](../sql/).
+
+```bash
+uv tool install sarj-python-lint
+```
+
+## Pre-commit
+
+```yaml
+- repo: https://github.com/sarj-ai/linting
+  rev: python-v0.2.0
+  hooks:
+    - id: sarj-no-sequential-await
+    - id: sarj-inefficient-string-concat-in-loop
+    - id: sarj-prefer-discriminated-union
+    - id: sarj-prefer-str-enum
+```
+
+## CLI
+
+```bash
+sarj-python-lint check --rule no-sequential-await path/to/file.py
+sarj-python-lint list-rules
+```
+
+Diagnostic format is `path:line:col: CODE message` — Ruff-compatible.
+
+## Suppression
+
+Inline `# sarj-noqa: SARJ00X — <reason>` on the offending line.
+
+Each rule's source under `src/sarj_python_lint/rules/` carries its own `description` and diagnostic message.

sarj_python_lint-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "sarj-python-lint"
+version = "0.2.0"
+description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
+readme = "README.md"
+authors = [{ name = "sarj-ai" }]
+license = { text = "MIT" }
+requires-python = ">=3.13"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.scripts]
+sarj-python-lint = "sarj_python_lint.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/sarj-ai/linting/tree/main/packages/python"
+Repository = "https://github.com/sarj-ai/linting"
+Issues = "https://github.com/sarj-ai/linting/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+  "pytest-benchmark>=4.0",
+  "ruff>=0.6",
+  "basedpyright>=1.20",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sarj_python_lint"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src",
+  "README.md",
+  "pyproject.toml",
+]
+exclude = [
+  "tests/",
+  "**/__pycache__/",
+  "**/*.pyc",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sarj_python_lint-0.2.0/src/sarj_python_lint/__init__.py

@@ -0,0 +1,3 @@
+"""sarj-python-lint — custom Python + SQL lint rules."""
+
+__version__ = "0.1.4"

sarj_python_lint-0.2.0/src/sarj_python_lint/__main__.py

@@ -0,0 +1,99 @@
+"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] <files>"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from sarj_python_lint import __version__
+from sarj_python_lint.rule_base import Diagnostic, is_suppressed
+from sarj_python_lint.rules import REGISTRY
+
+
+SKIP_DIR_NAMES = {
+    "node_modules", ".venv", "venv", ".git", "dist", "build", ".next",
+    "coverage", "__pycache__", ".pytest_cache", ".ruff_cache", ".mypy_cache",
+    ".turbo", ".yarn", ".pnpm-store",
+}
+
+
+def _expand_paths(paths: list[Path]) -> list[Path]:
+    out: list[Path] = []
+    for p in paths:
+        if not p.exists():
+            continue
+        if p.is_file():
+            out.append(p)
+            continue
+        for child in p.rglob("*.py"):
+            if not child.is_file():
+                continue
+            if any(part in SKIP_DIR_NAMES for part in child.parts):
+                continue
+            try:
+                if child.stat().st_size > 500_000:
+                    continue
+            except OSError:
+                continue
+            out.append(child)
+    return out
+
+
+def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
+    unknown = [rid for rid in rule_ids if rid not in REGISTRY]
+    if unknown:
+        sys.stderr.write(f"unknown rule(s): {', '.join(unknown)}\n")
+        sys.stderr.write(f"available: {', '.join(sorted(REGISTRY))}\n")
+        raise SystemExit(2)
+    rules = [REGISTRY[rid]() for rid in rule_ids]
+    expanded = _expand_paths(paths)
+    diags: list[Diagnostic] = []
+    for p in expanded:
+        try:
+            source = p.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        source_lines = source.splitlines()
+        for rule in rules:
+            for d in rule.check(p, source):
+                if is_suppressed(source_lines, d.line, d.code):
+                    continue
+                diags.append(d)
+    return diags
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="sarj-python-lint",
+        description="Custom Python + SQL lint rules.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    check_p = sub.add_parser("check", help="Run rules over files.")
+    check_p.add_argument(
+        "--rule",
+        action="append",
+        required=True,
+        help="Rule ID (repeat for multiple).",
+    )
+    check_p.add_argument("files", nargs="+", type=Path)
+
+    sub.add_parser("list-rules", help="List available rule IDs.")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "list-rules":
+        for rid, cls in sorted(REGISTRY.items()):
+            inst = cls()
+            sys.stdout.write(f"{inst.code:8}  {rid:40}  {inst.description}\n")
+        return 0
+
+    diags = _check(args.rule, args.files)
+    for d in diags:
+        sys.stdout.write(d.format() + "\n")
+    return 1 if diags else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sarj_python_lint-0.2.0/src/sarj_python_lint/rule_base.py

@@ -0,0 +1,70 @@
+"""Base types for sarj-python-lint rules."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+# Suppression syntax. Two forms supported:
+#   # sarj-noqa: SARJ001 — reason
+#   # sarj-noqa: SARJ001, SARJ002 — reason
+# We deliberately do NOT use `# noqa` because ruff aggressively cleans
+# unrecognized noqa codes (RUF100/RUF102) even with `external` set, which
+# silently breaks suppressions across runs. Distinct prefix = no conflict.
+_SARJ_NOQA_RE = re.compile(
+    r"#\s*sarj-noqa(?::\s*([A-Za-z0-9_, ]+))?",
+    re.IGNORECASE,
+)
+
+
+def is_suppressed(source_lines: list[str], line: int, code: str) -> bool:
+    """Return True if the diagnostic's line carries a `# sarj-noqa[: CODE]` comment.
+
+    `line` is 1-based to match Diagnostic.line.
+    """
+    if line < 1 or line > len(source_lines):
+        return False
+    text = source_lines[line - 1]
+    m = _SARJ_NOQA_RE.search(text)
+    if not m:
+        return False
+    codes_str = m.group(1)
+    if not codes_str:
+        # Bare `# sarj-noqa` suppresses every SARJ code on the line
+        return True
+    codes = {c.strip().upper() for c in codes_str.split(",") if c.strip()}
+    return code.upper() in codes
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """A single lint finding."""
+
+    path: Path
+    line: int
+    col: int
+    code: str
+    message: str
+
+    def format(self) -> str:
+        """Ruff-compatible: `path:line:col: CODE message`."""
+        return f"{self.path}:{self.line}:{self.col}: {self.code} {self.message}"
+
+
+class Rule(ABC):
+    """Base class for a single lint rule.
+
+    Subclasses set `id` (kebab-case) and `code` (e.g. SARJ001) as class
+    attributes and implement `check(path, source) -> list[Diagnostic]`.
+    """
+
+    id: str
+    code: str
+    description: str
+
+    @abstractmethod
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        """Inspect the given source. Return zero or more diagnostics."""
+        raise NotImplementedError

sarj_python_lint-0.2.0/src/sarj_python_lint/rules/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from sarj_python_lint.rule_base import Rule
+from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
+    InefficientStringConcatInLoop,
+)
+from sarj_python_lint.rules.no_sequential_await import NoSequentialAwait
+from sarj_python_lint.rules.prefer_discriminated_union import PreferDiscriminatedUnion
+from sarj_python_lint.rules.prefer_str_enum import PreferStrEnum
+
+
+REGISTRY: dict[str, type[Rule]] = {
+    NoSequentialAwait.id: NoSequentialAwait,
+    InefficientStringConcatInLoop.id: InefficientStringConcatInLoop,
+    PreferDiscriminatedUnion.id: PreferDiscriminatedUnion,
+    PreferStrEnum.id: PreferStrEnum,
+}
+
+__all__ = ["REGISTRY"]

sarj_python_lint-0.2.0/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -0,0 +1,74 @@
+"""SARJ002: detect `s += "..."` inside loops.
+
+String concatenation with `+=` inside a loop is O(n²) in CPython because
+strings are immutable — each `+=` allocates a new string and copies the
+previous one. Append to a list and `"".join(parts)` at the end for O(n).
+
+References:
+- https://docs.python.org/3/library/stdtypes.html#str.join
+- https://wiki.python.org/moin/PythonSpeed/PerformanceTips
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+
+class InefficientStringConcatInLoop(Rule):
+    """O(n²) string concatenation in a loop."""
+
+    id = "inefficient-string-concat-in-loop"
+    code = "SARJ002"
+    description = "`s += '...'` in a loop is O(n²); append to a list and join."
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for loop in ast.walk(tree):
+            if not isinstance(loop, (ast.For, ast.While)):
+                continue
+            for node in ast.walk(loop):
+                if not isinstance(node, ast.AugAssign):
+                    continue
+                if not isinstance(node.op, ast.Add):
+                    continue
+                # Heuristic: the RHS is a string-like value
+                if not _looks_like_string(node.value):
+                    continue
+                diags.append(
+                    Diagnostic(
+                        path=path,
+                        line=node.lineno,
+                        col=node.col_offset + 1,
+                        code=self.code,
+                        message=(
+                            "`+=` string concat in a loop is O(n²). "
+                            "Append to a list and `''.join(...)`."
+                        ),
+                    )
+                )
+        return diags
+
+
+def _looks_like_string(node: ast.AST) -> bool:
+    """Heuristic for 'this RHS is probably a string at runtime'."""
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return True
+    if isinstance(node, ast.JoinedStr):  # f-string
+        return True
+    if isinstance(node, ast.Call):
+        # str(...) / repr(...) / format / strftime — usually string
+        if isinstance(node.func, ast.Name) and node.func.id in {"str", "repr", "format"}:
+            return True
+        if isinstance(node.func, ast.Attribute):
+            return node.func.attr in {"format", "strftime", "join"}
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+        # `+` propagates string-ness if either side is a string
+        return _looks_like_string(node.left) or _looks_like_string(node.right)
+    return False

sarj_python_lint-0.2.0/src/sarj_python_lint/rules/no_sequential_await.py

@@ -0,0 +1,71 @@
+"""SARJ001: detect `for x in xs: await f(x)` patterns.
+
+Sequential `await` in a for-loop serializes I/O that could be parallelized
+with `asyncio.gather([f(x) for x in xs])`. The performance gap is often 10-100x
+for network-bound work (HTTP, DB queries, LLM calls).
+
+References:
+- https://docs.python.org/3/library/asyncio-task.html#running-tasks-concurrently
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+
+class NoSequentialAwait(Rule):
+    """Sequential await calls in a loop that could be parallelized."""
+
+    id = "no-sequential-await"
+    code = "SARJ001"
+    description = "Sequential `await` in a for-loop — prefer asyncio.gather."
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.For):
+                continue
+            # `async for` is fine — that's the parallel-iteration construct
+            for child in ast.walk(node):
+                # Skip nested For loops to avoid double-reporting the outer one
+                if isinstance(child, ast.Await) and _enclosing_loop(child, tree) is node:
+                    diags.append(
+                        Diagnostic(
+                            path=path,
+                            line=child.lineno,
+                            col=child.col_offset + 1,
+                            code=self.code,
+                            message=(
+                                "Sequential `await` inside `for` — prefer "
+                                "`asyncio.gather([f(x) for x in xs])`."
+                            ),
+                        )
+                    )
+                    break  # one diag per for-loop
+        return diags
+
+
+def _enclosing_loop(node: ast.AST, root: ast.AST) -> ast.AST | None:
+    """Walk parents until we find the nearest enclosing `ast.For`."""
+    # Build a child→parent map lazily on the first call. ast doesn't track
+    # parents, so we walk the whole tree once per check.
+    parent: dict[int, ast.AST] = {}
+    for child in ast.walk(root):
+        for grandchild in ast.iter_child_nodes(child):
+            parent[id(grandchild)] = child
+    cur: ast.AST | None = node
+    while cur is not None:
+        cur = parent.get(id(cur))
+        if isinstance(cur, ast.For):
+            return cur
+        if isinstance(cur, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            # Don't escape function boundaries
+            return None
+    return None

sarj_python_lint-0.2.0/src/sarj_python_lint/rules/prefer_discriminated_union.py

@@ -0,0 +1,148 @@
+"""SARJ005: flag BaseModel with `success: bool` + Optional fields.
+
+The anti-pattern:
+
+    class Result(BaseModel):
+        success: bool
+        data: Optional[Data] = None
+        error: Optional[str] = None
+
+allows illegal states (success=True with data=None, or success=False with
+data set). Use a discriminated union:
+
+    class Success(BaseModel): data: Data
+    class Failure(BaseModel): error: str
+    Result = Union[Success, Failure]
+
+References:
+- https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions
+- https://en.wikipedia.org/wiki/Tagged_union
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+STATUS_FIELDS = {"success", "ok", "is_success", "succeeded", "successful", "failed", "failure"}
+IGNORED_OPTIONAL_FIELDS = {
+    "metadata",
+    "meta",
+    "debug",
+    "debug_logs",
+    "extra",
+    "log",
+    "logs",
+    "traceback",
+    "request_id",
+    "trace_id",
+}
+
+
+class PreferDiscriminatedUnion(Rule):
+    """Pydantic BaseModel with success:bool — prefer a discriminated union."""
+
+    id = "prefer-discriminated-union"
+    code = "SARJ005"
+    description = "BaseModel with `success: bool` + Optional siblings — use a discriminated union."
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            if not _inherits_basemodel(node):
+                continue
+            has_status_bool = False
+            optional_fields: list[str] = []
+            for stmt in node.body:
+                if not isinstance(stmt, ast.AnnAssign):
+                    continue
+                if not isinstance(stmt.target, ast.Name):
+                    continue
+                name = stmt.target.id
+                ann_text = ast.unparse(stmt.annotation) if stmt.annotation else ""
+                if name in STATUS_FIELDS and "bool" in ann_text:
+                    has_status_bool = True
+                if _is_optional(stmt.annotation):
+                    if name not in IGNORED_OPTIONAL_FIELDS:
+                        optional_fields.append(name)
+            if has_status_bool and len(optional_fields) >= 2:
+                diags.append( 
+                    Diagnostic(
+                        path=path,
+                        line=node.lineno,
+                        col=node.col_offset + 1,
+                        code=self.code,
+                        message=(
+                            f"`{node.name}` has a bool status field plus "
+                            f"Optional fields ({', '.join(optional_fields)}). "
+                            "Model as `Union[Success, Failure]` to make illegal "
+                            "states unrepresentable."
+                        ),
+                    )
+                )
+        return diags
+
+
+def _inherits_basemodel(node: ast.ClassDef) -> bool:
+    for base in node.bases:
+        if isinstance(base, ast.Name) and base.id == "BaseModel":
+            return True
+        if isinstance(base, ast.Attribute) and base.attr == "BaseModel":
+            return True
+    return False
+
+
+def _get_name_flat(node: ast.AST) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        val = _get_name_flat(node.value)
+        if val:
+            return f"{val}.{node.attr}"
+    return ""
+
+
+def _is_optional(node: ast.AST | None) -> bool:
+    """Detect if an annotation represents an Optional type or Union with None."""
+    if node is None:
+        return False
+
+    # If it's a string literal (forward ref), parse it and check the inner AST
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        try:
+            parsed = ast.parse(node.value, mode="eval")
+            return _is_optional(parsed.body)
+        except SyntaxError:
+            pass
+
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+        return _is_optional(node.left) or _is_optional(node.right)
+
+    if isinstance(node, ast.Subscript):
+        name = _get_name_flat(node.value)
+        if name == "Optional" or name.endswith(".Optional"):
+            return True
+        if name == "Union" or name.endswith(".Union"):
+            slice_node = node.slice
+            # Handle Python < 3.9 Index wrapper safely
+            if type(slice_node).__name__ == "Index":
+                slice_node = getattr(slice_node, "value", slice_node)
+            if isinstance(slice_node, ast.Tuple):
+                return any(_is_optional(elt) for elt in slice_node.elts)
+            return _is_optional(slice_node)
+
+    if isinstance(node, ast.Constant) and node.value is None:
+        return True
+
+    if isinstance(node, ast.Name) and node.id == "None":
+        return True
+
+    return False

sarj_python_lint-0.2.0/src/sarj_python_lint/rules/prefer_str_enum.py

@@ -0,0 +1,107 @@
+"""SARJ006: Pydantic field with raw `str` annotation that looks like a choice/enum field.
+
+`Literal["a", "b", "c"]` is acceptable — that's a proper closed set. This rule
+only flags **raw `str`** annotations on fields whose name (`*_status`, `*_state`,
+`*_type`, `*_kind`) or sibling class attribute (`choices`, `states`, `STATUSES`,
+`values`, `allowed`) strongly suggests a closed enumeration is intended.
+
+Replace with:
+    class Status(StrEnum):
+        ACTIVE = "active"
+        INACTIVE = "inactive"
+
+References:
+- https://docs.python.org/3/library/enum.html#enum.StrEnum
+- https://docs.pydantic.dev/latest/concepts/types/#enums
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+
+class PreferStrEnum(Rule):
+    """Choice-shaped str field — prefer StrEnum or Literal."""
+
+    id = "prefer-str-enum"
+    code = "SARJ006"
+    description = "Pydantic str field with choice-like default — prefer StrEnum."
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for cls in ast.walk(tree):
+            if not isinstance(cls, ast.ClassDef):
+                continue
+            # Skip enum classes themselves
+            if any(_base_name(b) in {"Enum", "StrEnum", "IntEnum"} for b in cls.bases):
+                continue
+            # Find string-list class attrs that look like a choices set.
+            choices_attrs: set[str] = set()
+            for stmt in cls.body:
+                if isinstance(stmt, (ast.Assign, ast.AnnAssign)):
+                    target = (
+                        stmt.targets[0]
+                        if isinstance(stmt, ast.Assign) and stmt.targets
+                        else getattr(stmt, "target", None)
+                    )
+                    if not isinstance(target, ast.Name):
+                        continue
+                    val = getattr(stmt, "value", None)
+                    if _is_string_collection(val) and target.id.lower() in {
+                        "choices",
+                        "states",
+                        "statuses",
+                        "values",
+                        "allowed",
+                    }:
+                        choices_attrs.add(target.id)
+            # Flag bare-str AnnAssigns
+            for stmt in cls.body:
+                if not isinstance(stmt, ast.AnnAssign):
+                    continue
+                if not isinstance(stmt.target, ast.Name):
+                    continue
+                ann_text = ast.unparse(stmt.annotation) if stmt.annotation else ""
+                if ann_text.strip() != "str":
+                    continue  # Literal[...] etc. is fine per user L234
+                # Heuristic: there's a nearby choices list OR the field name
+                # ends with `_status` / `_state` / `_type`.
+                name = stmt.target.id
+                if choices_attrs or name.endswith(("_status", "_state", "_type", "_kind")):
+                    diags.append(
+                        Diagnostic(
+                            path=path,
+                            line=stmt.lineno,
+                            col=stmt.col_offset + 1,
+                            code=self.code,
+                            message=(
+                                f"`{name}: str` looks like a choice field — "
+                                "prefer `StrEnum`. (`Literal[...]` is also acceptable.)"
+                            ),
+                        )
+                    )
+        return diags
+
+
+def _base_name(base: ast.AST) -> str | None:
+    if isinstance(base, ast.Name):
+        return base.id
+    if isinstance(base, ast.Attribute):
+        return base.attr
+    return None
+
+
+def _is_string_collection(node: ast.AST | None) -> bool:
+    if not isinstance(node, (ast.List, ast.Tuple, ast.Set)):
+        return False
+    return all(
+        isinstance(elt, ast.Constant) and isinstance(elt.value, str)
+        for elt in node.elts
+    )