codetruth 0.2.0__py3-none-any.whl

codetruth/languages/python/extractor.py

@@ -0,0 +1,271 @@
+"""Layer 1 — symbol extraction for Python via the ast module.
+
+Walks every .py file in the repo and produces a flat symbol table:
+modules, classes, functions, methods, and module-level variables, plus the
+raw import statements and __all__ needed by the edge builder (Layer 2).
+"""
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from ...core.models import Symbol, SymbolType
+
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", "__pycache__", ".venv", "venv", "env", ".env",
+    "node_modules", ".tox", ".nox", ".mypy_cache", ".pytest_cache",
+    ".ruff_cache", "build", "dist", ".eggs", "site-packages", ".idea", ".vscode",
+    ".codetruth",  # CodeTruth's own cache — must never be scanned or fingerprinted
+}
+
+CONFIG_EXTS = {".json", ".yaml", ".yml", ".toml", ".ini", ".cfg"}
+
+
+@dataclass
+class ImportRec:
+    kind: str          # "import" | "from"
+    module: str        # dotted module ('' for `from . import x`)
+    name: str          # imported name ('' for plain `import x`, '*' for star)
+    asname: Optional[str]
+    level: int         # relative-import level
+    lineno: int
+
+
+@dataclass
+class ModuleInfo:
+    name: str                       # dotted module name
+    rel_path: str                   # repo-relative path, forward slashes
+    abs_path: str
+    is_test: bool
+    is_package: bool                # file is an __init__.py
+    tree: Optional[ast.Module] = None
+    symbols: list[Symbol] = field(default_factory=list)
+    imports: list[ImportRec] = field(default_factory=list)
+    all_names: Optional[list[str]] = None   # contents of __all__ if present
+    has_main_guard: bool = False
+
+
+def is_test_path(rel_path: str) -> bool:
+    parts = rel_path.replace("\\", "/").split("/")
+    base = parts[-1]
+    if base == "conftest.py" or base.startswith("test_") or base.endswith("_test.py"):
+        return True
+    return any(p in ("tests", "test", "testing") for p in parts[:-1])
+
+
+def _ignored(rel_posix: str, ignores: tuple[str, ...]) -> bool:
+    if not ignores:
+        return False
+    from ...core.config import RepoConfig
+    return RepoConfig(ignore_paths=list(ignores)).is_ignored(rel_posix)
+
+
+def iter_py_files(root: Path, ignores: tuple[str, ...] = ()):
+    for path in sorted(root.rglob("*.py")):
+        rel = path.relative_to(root)
+        if any(part in SKIP_DIRS for part in rel.parts):
+            continue
+        if _ignored(rel.as_posix(), ignores):
+            continue
+        yield path
+
+
+def iter_config_files(root: Path, ignores: tuple[str, ...] = ()):
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or path.suffix.lower() not in CONFIG_EXTS:
+            continue
+        rel = path.relative_to(root)
+        if any(part in SKIP_DIRS for part in rel.parts):
+            continue
+        if _ignored(rel.as_posix(), ignores):
+            continue
+        yield path
+
+
+def module_name_for(path: Path, root: Path) -> tuple[str, bool]:
+    """Dotted module name from the file path; returns (name, is_package)."""
+    rel = path.relative_to(root)
+    parts = list(rel.parts)
+    is_package = parts[-1] == "__init__.py"
+    if is_package:
+        parts = parts[:-1]
+    else:
+        parts[-1] = parts[-1][:-3]  # strip .py
+    if not parts:  # __init__.py at repo root
+        parts = [root.name]
+    return ".".join(parts), is_package
+
+
+def dotted_name(node: ast.AST) -> Optional[str]:
+    """Best-effort dotted name for decorators / base classes / call targets."""
+    if isinstance(node, ast.Call):
+        return dotted_name(node.func)
+    if isinstance(node, ast.Attribute):
+        base = dotted_name(node.value)
+        return f"{base}.{node.attr}" if base else node.attr
+    if isinstance(node, ast.Name):
+        return node.id
+    return None
+
+
+def _is_main_guard(node: ast.If) -> bool:
+    t = node.test
+    if isinstance(t, ast.Compare) and len(t.comparators) == 1:
+        left, right = t.left, t.comparators[0]
+        for a, b in ((left, right), (right, left)):
+            if (isinstance(a, ast.Name) and a.id == "__name__"
+                    and isinstance(b, ast.Constant) and b.value == "__main__"):
+                return True
+    return False
+
+
+class _Extractor:
+    def __init__(self, mi: ModuleInfo):
+        self.mi = mi
+
+    def run(self) -> None:
+        mi = self.mi
+        mod_sym = Symbol(
+            id=mi.name, name=mi.name.rsplit(".", 1)[-1], qualname=mi.name,
+            type=SymbolType.MODULE, file=mi.rel_path, line=1,
+            end_line=getattr(mi.tree, "end_lineno", 1) or 1,
+            module=mi.name, parent=None, exported=True, is_public=True,
+            is_test=mi.is_test,
+        )
+        mi.symbols.append(mod_sym)
+        self._walk_body(mi.tree.body, prefix="", parent=mi.name, in_class=False, depth=0)
+        # Resolve exported flags now that __all__ is known.
+        for s in mi.symbols:
+            if s.type is SymbolType.MODULE or s.parent != mi.name:
+                continue
+            if mi.all_names is not None:
+                s.exported = s.name in mi.all_names
+            else:
+                s.exported = not s.name.startswith("_")
+
+    def _walk_body(self, body, prefix: str, parent: str, in_class: bool, depth: int):
+        for node in body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                self._add_def(node, prefix, parent, in_class, depth, is_class=False)
+            elif isinstance(node, ast.ClassDef):
+                self._add_def(node, prefix, parent, in_class, depth, is_class=True)
+            elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+                if depth == 0 or in_class:
+                    self._add_variables(node, prefix, parent, depth)
+            elif isinstance(node, (ast.Import, ast.ImportFrom)):
+                self._add_import(node)
+            elif isinstance(node, ast.If):
+                if depth == 0 and _is_main_guard(node):
+                    self.mi.has_main_guard = True
+                # Descend into conditional blocks at the same scope (covers
+                # TYPE_CHECKING imports, platform-conditional defs, etc.).
+                self._walk_body(node.body, prefix, parent, in_class, depth)
+                self._walk_body(node.orelse, prefix, parent, in_class, depth)
+            elif isinstance(node, ast.Try):
+                for blk in (node.body, node.orelse, node.finalbody):
+                    self._walk_body(blk, prefix, parent, in_class, depth)
+                for handler in node.handlers:
+                    self._walk_body(handler.body, prefix, parent, in_class, depth)
+            elif isinstance(node, ast.With):
+                self._walk_body(node.body, prefix, parent, in_class, depth)
+            else:
+                # Function-level imports still create aliases; catch them.
+                for sub in ast.walk(node):
+                    if isinstance(sub, (ast.Import, ast.ImportFrom)):
+                        self._add_import(sub)
+
+    def _add_def(self, node, prefix, parent, in_class, depth, is_class: bool):
+        mi = self.mi
+        qual = f"{prefix}{node.name}"
+        sym_id = f"{mi.name}:{qual}"
+        if is_class:
+            stype = SymbolType.CLASS
+        else:
+            stype = SymbolType.METHOD if in_class else SymbolType.FUNCTION
+        decorators = [d for d in (dotted_name(x) for x in node.decorator_list) if d]
+        bases = []
+        if is_class:
+            bases = [b for b in (dotted_name(x) for x in node.bases) if b]
+        sym = Symbol(
+            id=sym_id, name=node.name, qualname=qual, type=stype,
+            file=mi.rel_path, line=node.lineno,
+            end_line=node.end_lineno or node.lineno, module=mi.name,
+            parent=parent, exported=False,
+            is_public=(depth == 0 or in_class) and not node.name.startswith("_"),
+            is_test=mi.is_test, decorators=decorators, bases=bases,
+        )
+        mi.symbols.append(sym)
+        # Function-level imports inside the def still matter for edges.
+        self._walk_body(node.body, prefix=f"{qual}.", parent=sym_id,
+                        in_class=is_class, depth=depth + 1)
+
+    def _add_variables(self, node, prefix, parent, depth):
+        mi = self.mi
+        targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+        for t in targets:
+            names = []
+            if isinstance(t, ast.Name):
+                names = [t.id]
+            elif isinstance(t, (ast.Tuple, ast.List)):
+                names = [e.id for e in t.elts if isinstance(e, ast.Name)]
+            for name in names:
+                if name == "__all__" and depth == 0:
+                    mi.all_names = self._literal_str_list(node.value)
+                    continue
+                if name.startswith("__") and name.endswith("__"):
+                    continue  # dunder module metadata (__version__, etc.)
+                qual = f"{prefix}{name}"
+                sym_id = f"{mi.name}:{qual}"
+                if any(s.id == sym_id for s in mi.symbols):
+                    continue  # reassignment — keep first definition site
+                mi.symbols.append(Symbol(
+                    id=sym_id, name=name, qualname=qual, type=SymbolType.VARIABLE,
+                    file=mi.rel_path, line=node.lineno,
+                    end_line=node.end_lineno or node.lineno, module=mi.name,
+                    parent=parent, exported=False,
+                    is_public=not name.startswith("_"), is_test=mi.is_test,
+                ))
+
+    @staticmethod
+    def _literal_str_list(value) -> list[str]:
+        out = []
+        if isinstance(value, (ast.List, ast.Tuple)):
+            for e in value.elts:
+                if isinstance(e, ast.Constant) and isinstance(e.value, str):
+                    out.append(e.value)
+        return out
+
+    def _add_import(self, node) -> None:
+        mi = self.mi
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                mi.imports.append(ImportRec("import", alias.name, "",
+                                            alias.asname, 0, node.lineno))
+        else:
+            for alias in node.names:
+                mi.imports.append(ImportRec("from", node.module or "", alias.name,
+                                            alias.asname, node.level, node.lineno))
+
+
+def extract_repo(repo_path: Path,
+                 ignores: tuple[str, ...] = ()) -> tuple[list[ModuleInfo], list[str]]:
+    """Parse every Python file under repo_path. Returns (modules, warnings)."""
+    modules: list[ModuleInfo] = []
+    warnings: list[str] = []
+    for path in iter_py_files(repo_path, ignores):
+        rel = path.relative_to(repo_path).as_posix()
+        name, is_package = module_name_for(path, repo_path)
+        mi = ModuleInfo(name=name, rel_path=rel, abs_path=str(path),
+                        is_test=is_test_path(rel), is_package=is_package)
+        try:
+            source = path.read_text(encoding="utf-8", errors="replace")
+            mi.tree = ast.parse(source, filename=rel)
+        except (SyntaxError, ValueError) as exc:
+            warnings.append(f"parse error in {rel}: {exc}")
+            modules.append(mi)
+            continue
+        _Extractor(mi).run()
+        modules.append(mi)
+    return modules, warnings

codetruth/languages/python/plugin.py

@@ -0,0 +1,49 @@
+"""The v1 language plugin: full Python support."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ...core.graph import CodeGraph
+from ...core.models import Marker, Symbol
+from ...core.plugin import LanguagePlugin, Rule
+from . import edges as edges_mod
+from . import rules as rules_mod
+from .extractor import (ModuleInfo, extract_repo, iter_config_files,
+                        iter_py_files)
+
+
+class PythonPlugin(LanguagePlugin):
+    name = "python"
+
+    def extract(self, repo_path: Path,
+                ignores: tuple[str, ...] = ()) -> tuple[list[ModuleInfo], list[str]]:
+        return extract_repo(repo_path, ignores)
+
+    def build_index(self, modules: list[ModuleInfo]) -> edges_mod.SymbolIndex:
+        return edges_mod.SymbolIndex(modules)
+
+    def build_edges(self, repo_path: Path, modules: list[ModuleInfo],
+                    index: edges_mod.SymbolIndex, graph: CodeGraph,
+                    markers: list[Marker]) -> None:
+        edges_mod.build_edges(modules, index, graph, markers)
+
+    def rules(self) -> list[Rule]:
+        return rules_mod.default_rules()
+
+    def symbols(self, modules: list[ModuleInfo]) -> list[Symbol]:
+        return [s for m in modules for s in m.symbols]
+
+    def config_files(self, repo_path: Path,
+                     ignores: tuple[str, ...] = ()) -> list[Path]:
+        return list(iter_config_files(repo_path, ignores))
+
+    def source_files(self, repo_path: Path,
+                     ignores: tuple[str, ...] = ()) -> list[Path]:
+        """Every file whose bytes affect a scan — used for cache fingerprints.
+        Includes .codetruth.toml so config changes invalidate the cache."""
+        files = list(iter_py_files(repo_path, ignores)) \
+            + list(iter_config_files(repo_path, ignores))
+        toml = repo_path / ".codetruth.toml"
+        if toml.is_file():
+            files.append(toml)
+        return files

codetruth/languages/python/rules.py

@@ -0,0 +1,332 @@
+"""Layer 3 — semantic safety rules for Python.
+
+Each rule scans ASTs / the symbol table for one dynamic-usage pattern and
+emits weak edges or markers. Framework knowledge (FastAPI, Django, Celery,
+pytest, ...) lives in YAML files under codetruth/rules/python/ so coverage
+can grow without code changes.
+"""
+from __future__ import annotations
+
+import ast
+import fnmatch
+import re
+from pathlib import Path
+
+import yaml
+
+from ...core.models import (Edge, EdgeKind, EdgeStrength, Marker, MarkerKind,
+                            SymbolType)
+from ...core.plugin import Rule, RuleContext
+from .extractor import dotted_name
+
+RULES_DIR = Path(__file__).resolve().parents[2] / "rules" / "python"
+
+IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+DOTTED_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)+")
+
+# Bare identifiers too common to count as a string reference to a symbol.
+COMMON_WORDS = {
+    "main", "test", "data", "name", "type", "value", "true", "false", "none",
+    "null", "user", "file", "path", "list", "dict", "info", "debug", "error",
+    "warning", "default", "config", "utf-8", "ascii", "json", "yaml", "text",
+    "html", "http", "https", "get", "post", "put", "delete", "read", "write",
+    "id", "key", "app", "api", "run", "start", "stop", "date", "time",
+}
+
+
+class DeclaredEntrypointRule(Rule):
+    """Symbols the user declared externally reached in .codetruth.toml
+    (cron jobs, service runners, cross-repo handlers)."""
+    id = "declared-entrypoints"
+
+    def apply(self, ctx: RuleContext) -> None:
+        from ...core.config import load_config
+        cfg = load_config(ctx.repo_path)
+        if not cfg.entrypoints:
+            return
+        for sym in ctx.index.all_symbols():
+            if cfg.is_declared_entrypoint(sym.id):
+                ctx.add_marker(Marker(
+                    sym.id, MarkerKind.ENTRYPOINT,
+                    "declared as an entry point in .codetruth.toml",
+                    rule=self.id, file=sym.file, line=sym.line))
+
+
+class KeepCommentRule(Rule):
+    """`# codetruth: keep` on (or directly above) a definition marks it as
+    an entry point — the user asserts it is reached in a way the scanner
+    cannot see."""
+    id = "keep-comment"
+    TAG = "codetruth: keep"
+
+    def apply(self, ctx: RuleContext) -> None:
+        for mi in ctx.modules:
+            if mi.tree is None or not mi.symbols:
+                continue
+            try:
+                lines = Path(mi.abs_path).read_text(
+                    encoding="utf-8", errors="replace").splitlines()
+            except OSError:
+                continue
+            if not any(self.TAG in ln for ln in lines):
+                continue
+            for sym in mi.symbols:
+                for lineno in (sym.line, sym.line - 1):
+                    if 1 <= lineno <= len(lines) and self.TAG in lines[lineno - 1]:
+                        ctx.add_marker(Marker(
+                            sym.id, MarkerKind.ENTRYPOINT,
+                            "marked '# codetruth: keep' in source",
+                            rule=self.id, file=sym.file, line=sym.line))
+                        break
+
+
+class DunderRule(Rule):
+    """Dunder methods are invoked implicitly by the interpreter."""
+    id = "python-dunder-methods"
+
+    def apply(self, ctx: RuleContext) -> None:
+        for sym in ctx.index.all_symbols():
+            if sym.type is SymbolType.METHOD and sym.name.startswith("__") \
+                    and sym.name.endswith("__"):
+                ctx.add_marker(Marker(sym.id, MarkerKind.ENTRYPOINT,
+                                      "dunder method — invoked implicitly by Python",
+                                      rule=self.id, file=sym.file, line=sym.line))
+
+
+class TestEntryRule(Rule):
+    """Test functions/classes are collected by the test runner, not called."""
+    id = "python-test-entrypoints"
+
+    def apply(self, ctx: RuleContext) -> None:
+        for sym in ctx.index.all_symbols():
+            if not sym.is_test:
+                continue
+            if (sym.type in (SymbolType.FUNCTION, SymbolType.METHOD)
+                    and sym.name.startswith("test")) or \
+               (sym.type is SymbolType.CLASS and sym.name.startswith("Test")):
+                ctx.add_marker(Marker(sym.id, MarkerKind.ENTRYPOINT,
+                                      "test entry point — collected by the test runner",
+                                      rule=self.id, file=sym.file, line=sym.line))
+
+
+class MainGuardRule(Rule):
+    """Modules with a __main__ guard are executable scripts."""
+    id = "python-main-guard"
+
+    def apply(self, ctx: RuleContext) -> None:
+        for mi in ctx.modules:
+            if mi.has_main_guard:
+                ctx.add_marker(Marker(mi.name, MarkerKind.ENTRYPOINT,
+                                      "has `if __name__ == '__main__'` guard — "
+                                      "executable script", rule=self.id,
+                                      file=mi.rel_path, line=1))
+
+
+class ReflectionRule(Rule):
+    """getattr/setattr/hasattr, importlib, __import__, eval/exec, globals()[...].
+
+    Literal targets become weak DYNAMIC edges. Non-literal reflection poisons
+    the whole module: nothing defined there can be *proved* dead, so every
+    symbol in it is capped below `safe_to_delete`.
+    """
+    id = "python-reflection"
+
+    REFLECT_FUNCS = {"getattr", "setattr", "hasattr", "delattr"}
+    DYNAMIC_FUNCS = {"eval", "exec", "__import__", "globals", "locals", "vars"}
+
+    def apply(self, ctx: RuleContext) -> None:
+        for mi in ctx.modules:
+            if mi.tree is None:
+                continue
+            for node in ast.walk(mi.tree):
+                if not isinstance(node, ast.Call):
+                    continue
+                fname = dotted_name(node.func) or ""
+                short = fname.split(".")[-1]
+                if short in self.REFLECT_FUNCS and len(node.args) >= 2:
+                    self._reflect(ctx, mi, node, fname)
+                elif fname in ("importlib.import_module", "import_module") \
+                        and node.args:
+                    self._import_module(ctx, mi, node)
+                elif short in self.DYNAMIC_FUNCS and fname == short:
+                    ctx.add_marker(Marker(
+                        mi.name, MarkerKind.DYNAMIC_MODULE,
+                        f"non-literal dynamic access `{short}(...)` at "
+                        f"{mi.rel_path}:{node.lineno}", rule=self.id,
+                        file=mi.rel_path, line=node.lineno))
+
+    def _reflect(self, ctx, mi, node, fname):
+        arg = node.args[1]
+        if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+            for sid in ctx.index.by_name.get(arg.value, []):
+                ctx.add_edge(Edge(mi.name, sid, EdgeKind.DYNAMIC,
+                                  EdgeStrength.WEAK, mi.rel_path, node.lineno,
+                                  f"{fname}(..., '{arg.value}')"))
+        else:
+            ctx.add_marker(Marker(
+                mi.name, MarkerKind.DYNAMIC_MODULE,
+                f"non-literal `{fname}()` at {mi.rel_path}:{node.lineno} — "
+                "symbols in this module cannot be proved unreachable",
+                rule=self.id, file=mi.rel_path, line=node.lineno))
+
+    def _import_module(self, ctx, mi, node):
+        arg = node.args[0]
+        if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+            target = arg.value
+            if target in ctx.index.modules:
+                ctx.add_edge(Edge(mi.name, target, EdgeKind.DYNAMIC,
+                                  EdgeStrength.WEAK, mi.rel_path, node.lineno,
+                                  f"importlib.import_module('{target}')"))
+        else:
+            ctx.add_marker(Marker(
+                mi.name, MarkerKind.DYNAMIC_MODULE,
+                f"non-literal import_module() at {mi.rel_path}:{node.lineno}",
+                rule=self.id, file=mi.rel_path, line=node.lineno))
+
+
+class StringReferenceRule(Rule):
+    """String literals naming a symbol (dotted path or exact identifier) in
+    Python source or config files create weak string_ref edges — the
+    config-driven / dispatch-table usage pattern."""
+    id = "python-string-references"
+
+    def apply(self, ctx: RuleContext) -> None:
+        # Python source strings
+        for mi in ctx.modules:
+            if mi.tree is None:
+                continue
+            for node in ast.walk(mi.tree):
+                if isinstance(node, ast.Constant) and isinstance(node.value, str):
+                    self._match(ctx, node.value, mi.name, mi.rel_path,
+                                node.lineno)
+        # Config files
+        for path in ctx.config_files:
+            rel = path.relative_to(ctx.repo_path).as_posix()
+            try:
+                text = path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            for lineno, line in enumerate(text.splitlines(), 1):
+                self._match(ctx, line, f"file:{rel}", rel, lineno,
+                            whole_line=True)
+
+    def _match(self, ctx, text: str, src: str, file: str, lineno: int,
+               whole_line: bool = False) -> None:
+        stripped = text.strip().strip("\"'")
+        # Exact identifier match (dispatch keys, registry names).
+        if not whole_line and IDENT_RE.match(stripped):
+            if len(stripped) >= 4 and stripped.lower() not in COMMON_WORDS:
+                for sid in ctx.index.by_name.get(stripped, []):
+                    ctx.add_edge(Edge(src, sid, EdgeKind.STRING_REF,
+                                      EdgeStrength.WEAK, file, lineno,
+                                      f"string literal '{stripped}'"))
+            return
+        # Dotted-path matches anywhere in the text ("app.views.login").
+        for m in DOTTED_RE.finditer(text):
+            dotted = m.group(0)
+            self._match_dotted(ctx, dotted, src, file, lineno)
+
+    def _match_dotted(self, ctx, dotted: str, src, file, lineno) -> None:
+        if dotted in ctx.index.modules:
+            ctx.add_edge(Edge(src, dotted, EdgeKind.STRING_REF,
+                              EdgeStrength.WEAK, file, lineno,
+                              f"dotted string reference '{dotted}'"))
+            return
+        parts = dotted.split(".")
+        for split in range(len(parts) - 1, 0, -1):
+            mod = ".".join(parts[:split])
+            if mod in ctx.index.modules:
+                qual = ".".join(parts[split:])
+                sid = f"{mod}:{qual}"
+                if sid in ctx.index.by_id:
+                    ctx.add_edge(Edge(src, sid, EdgeKind.STRING_REF,
+                                      EdgeStrength.WEAK, file, lineno,
+                                      f"dotted string reference '{dotted}'"))
+                return
+
+
+class DecoratorPatternRule(Rule):
+    """YAML-defined: decorators that register a symbol with a framework."""
+
+    def __init__(self, rule_id: str, patterns: list[str], reason: str,
+                 effect: str = "entrypoint"):
+        self.id = rule_id
+        self.patterns = patterns
+        self.reason = reason
+        self.effect = effect
+
+    def _matches(self, dec: str) -> bool:
+        for pat in self.patterns:
+            if fnmatch.fnmatch(dec, pat):
+                return True
+            if "." not in pat and dec.split(".")[-1] == pat:
+                return True
+        return False
+
+    def apply(self, ctx: RuleContext) -> None:
+        for sym in ctx.index.all_symbols():
+            for dec in sym.decorators:
+                if self._matches(dec):
+                    kind = MarkerKind.ENTRYPOINT if self.effect == "entrypoint" \
+                        else MarkerKind.CAUTION
+                    ctx.add_marker(Marker(sym.id, kind,
+                                          f"@{dec}: {self.reason}", rule=self.id,
+                                          file=sym.file, line=sym.line))
+                    break
+
+
+class NamePatternRule(Rule):
+    """YAML-defined: symbols whose name+path+type mark them framework-owned
+    (Django settings constants, management commands, migrations, wsgi app)."""
+
+    def __init__(self, rule_id: str, reason: str, name_regex: str = "",
+                 path_glob: str = "", symbol_type: str = ""):
+        self.id = rule_id
+        self.reason = reason
+        self.name_re = re.compile(name_regex) if name_regex else None
+        self.path_glob = path_glob
+        self.symbol_type = symbol_type
+
+    def apply(self, ctx: RuleContext) -> None:
+        for sym in ctx.index.all_symbols():
+            if self.symbol_type and sym.type.value != self.symbol_type:
+                continue
+            if self.name_re and not self.name_re.match(sym.name):
+                continue
+            if self.path_glob and not fnmatch.fnmatch(sym.file, self.path_glob):
+                continue
+            ctx.add_marker(Marker(sym.id, MarkerKind.ENTRYPOINT, self.reason,
+                                  rule=self.id, file=sym.file, line=sym.line))
+
+
+def load_yaml_rules(rules_dir: Path = RULES_DIR) -> list[Rule]:
+    rules: list[Rule] = []
+    if not rules_dir.is_dir():
+        return rules
+    for path in sorted(rules_dir.glob("*.yaml")):
+        doc = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        for spec in doc.get("rules", []):
+            rtype = spec.get("type")
+            if rtype == "decorator":
+                rules.append(DecoratorPatternRule(
+                    spec["id"], spec["patterns"], spec.get("reason", ""),
+                    spec.get("effect", "entrypoint")))
+            elif rtype == "name":
+                rules.append(NamePatternRule(
+                    spec["id"], spec.get("reason", ""),
+                    spec.get("name_regex", ""), spec.get("path_glob", ""),
+                    spec.get("symbol_type", "")))
+    return rules
+
+
+def default_rules() -> list[Rule]:
+    return [
+        DeclaredEntrypointRule(),
+        KeepCommentRule(),
+        DunderRule(),
+        TestEntryRule(),
+        MainGuardRule(),
+        ReflectionRule(),
+        StringReferenceRule(),
+        *load_yaml_rules(),
+    ]