fix(entrypoints): per-rule ruleset origin and import-resolved base matching (#27)

Attribute each PyEntrypoint's ruleset to the rule's own load origin instead
of the last-loaded ruleset, and resolve written base-class names against the
owning module's import table so bases: rules match real, idiomatically
imported code instead of only fully-qualified spellings.

Author: rahlk

codeanalyzer/entrypoints/matching.py

@@ -113,7 +113,7 @@ def _methods_of(dec, spec: Optional[Dict[str, Any]]) -> List[str]:
 
 
 def entrypoints_from_decorators(
-    node, framework: str, rules: Iterable["DecoratorRule"], ruleset: str
+    node, framework: str, rules: Iterable["DecoratorRule"]
 ) -> List[PyEntrypoint]:
     out: List[PyEntrypoint] = []
     for dec in getattr(node, "decorators", []) or []:
@@ -125,7 +125,7 @@ def entrypoints_from_decorators(
                     framework=framework,
                     confidence=rule.confidence,
                     rule=rule.id,
-                    ruleset=ruleset,
+                    ruleset=rule.origin,
                     evidence=dec.qualified_name,
                     route=_route_of(dec, rule.route),
                     http_methods=_methods_of(dec, rule.methods),
@@ -138,7 +138,6 @@ def entrypoints_from_bases(
     cls,
     framework: str,
     rules: Iterable["BaseRule"],
-    ruleset: str,
     resolve: Callable[[str], Optional[str]],
 ) -> Tuple[List[PyEntrypoint], Dict[str, List[PyEntrypoint]]]:
     """Records for a routed class and for the methods the framework dispatches.
@@ -161,7 +160,7 @@ def entrypoints_from_bases(
                 framework=framework,
                 confidence=rule.confidence,
                 rule=rule.id,
-                ruleset=ruleset,
+                ruleset=rule.origin,
                 evidence=cls.signature,
             )
         )
@@ -174,7 +173,7 @@ def entrypoints_from_bases(
                     framework=framework,
                     confidence=rule.confidence,
                     rule=f"{rule.id}.dispatch",
-                    ruleset=ruleset,
+                    ruleset=rule.origin,
                     evidence=cls.signature,
                     http_methods=[name.upper()] if name in _HTTP_VERBS else [],
                     via=cls.id or None,

codeanalyzer/entrypoints/pipeline.py

@@ -7,12 +7,12 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Iterable, Iterator
+from typing import Dict, Iterable, Iterator
 
 from codeanalyzer.entrypoints.detect import detected_frameworks
 from codeanalyzer.entrypoints.matching import entrypoints_from_bases, entrypoints_from_decorators
 from codeanalyzer.entrypoints.rules import RuleSet, load_rules
-from codeanalyzer.schema.py_schema import PyApplication, PyCallable, PyClass
+from codeanalyzer.schema.py_schema import PyApplication, PyCallable, PyClass, PyModule
 from codeanalyzer.utils import logger
 
 
@@ -38,35 +38,62 @@ def detect_entrypoints(
 
 def _run_stages(app: PyApplication, project_dir: Path, rules: RuleSet) -> None:
     """Stages 0-4. Stage 0 (framework detection) and Stage 3 (decorator and
-    base-class matching) exist so far."""
+    base-class matching) exist so far.
+
+    Base-class resolution needs the OWNING MODULE's import table (a written
+    base like ``APIView`` only resolves via that module's own
+    ``from rest_framework.views import APIView``), so this walks module by
+    module rather than the whole app flat, building one resolver per module.
+    """
     app.entrypoint_report.rulesets = list(rules.rulesets)
     frameworks = detected_frameworks(app, project_dir, rules)
     app.entrypoint_report.frameworks_detected = sorted(frameworks)
 
-    ruleset_name = rules.rulesets[-1] if len(rules.rulesets) > 1 else "shipped"
-    for name in sorted(frameworks):
-        fw = rules.frameworks[name]
-        for node in _walk(app):
-            node.entrypoints.extend(
-                entrypoints_from_decorators(node, name, fw.decorators, ruleset_name)
-            )
-            if isinstance(node, PyClass) and fw.bases:
-                class_eps, method_eps = entrypoints_from_bases(
-                    node, name, fw.bases, ruleset_name, lambda b: b
-                )
-                node.entrypoints.extend(class_eps)
-                for method_name, eps in method_eps.items():
-                    target = (node.callables or {}).get(method_name)
-                    if target is not None:
-                        target.entrypoints.extend(eps)
+    names = sorted(frameworks)
+    for mod in app.symbol_table.values():
+        resolve = _base_resolver(mod)
+        for node in _walk_module(mod):
+            for name in names:
+                fw = rules.frameworks[name]
+                node.entrypoints.extend(entrypoints_from_decorators(node, name, fw.decorators))
+                if isinstance(node, PyClass) and fw.bases:
+                    class_eps, method_eps = entrypoints_from_bases(
+                        node, name, fw.bases, resolve
+                    )
+                    node.entrypoints.extend(class_eps)
+                    for method_name, eps in method_eps.items():
+                        target = (node.callables or {}).get(method_name)
+                        if target is not None:
+                            target.entrypoints.extend(eps)
+
+
+def _base_resolver(mod: PyModule):
+    """A per-module ``resolve`` callable for ``entrypoints_from_bases``, built
+    from the module's own import table -- exact data already on the node,
+    never a Jedi guess. Covers ``from x.y import Z[ as W]`` and
+    ``import x.y[ as z]``, plus a dotted base (``views.APIView``) whose head
+    is the imported name. A base the import table has no mapping for is
+    returned unchanged -- under-approximate rather than guess.
+    """
+    aliases: Dict[str, str] = {}
+    for imp in mod.imports or []:
+        original = imp.alias or imp.name
+        aliases[imp.name] = imp.module if imp.module == original else f"{imp.module}.{original}"
+
+    def resolve(written: str) -> str:
+        head, _, rest = written.partition(".")
+        target = aliases.get(head)
+        return f"{target}.{rest}" if target and rest else (target or written)
+
+    return resolve
 
 
 def _derive_flags(app: PyApplication) -> None:
     for node in _walk(app):
         node.is_entrypoint = bool(node.entrypoints)
 
 
-def _walk(app: PyApplication) -> Iterator[object]:
+def _walk_module(mod: PyModule) -> Iterator[object]:
     def walk_callable(c: PyCallable) -> Iterator[object]:
         yield c
         for inner in (c.callables or {}).values():
@@ -81,8 +108,12 @@ def walk_class(k: PyClass) -> Iterator[object]:
         for inner in (k.types or {}).values():
             yield from walk_class(inner)
 
+    for fn in (mod.functions or {}).values():
+        yield from walk_callable(fn)
+    for cls in (mod.types or {}).values():
+        yield from walk_class(cls)
+
+
+def _walk(app: PyApplication) -> Iterator[object]:
     for mod in app.symbol_table.values():
-        for fn in (mod.functions or {}).values():
-            yield from walk_callable(fn)
-        for cls in (mod.types or {}).values():
-            yield from walk_class(cls)
+        yield from _walk_module(mod)

codeanalyzer/entrypoints/rules.py

@@ -31,6 +31,7 @@ class DecoratorRule:
     confidence: str = "certain"
     route: Optional[Dict[str, Any]] = None
     methods: Optional[Dict[str, Any]] = None
+    origin: str = "shipped"
 
 
 @dataclass
@@ -40,6 +41,7 @@ class BaseRule:
     confidence: str = "certain"
     transitive: bool = False
     dispatch: List[str] = field(default_factory=list)
+    origin: str = "shipped"
 
 
 @dataclass
@@ -134,6 +136,7 @@ def _decorator_rule(raw: Dict[str, Any], origin: str) -> DecoratorRule:
         confidence=_confidence(raw, origin),
         route=raw.get("route"),
         methods=raw.get("methods"),
+        origin=origin,
     )
 
 
@@ -144,4 +147,5 @@ def _base_rule(raw: Dict[str, Any], origin: str) -> BaseRule:
         confidence=_confidence(raw, origin),
         transitive=bool(raw.get("transitive", False)),
         dispatch=list(raw.get("dispatch") or []),
+        origin=origin,
     )

test/test_entrypoint_bases.py

@@ -21,26 +21,26 @@ def _cls(*methods: str, bases=("rest_framework.views.APIView",)) -> PyClass:
 
 def test_class_is_flagged_and_only_defined_methods_dispatch():
     cls = _cls("get")                       # defines get, not post
-    class_eps, method_eps = entrypoints_from_bases(cls, "drf", [RULE], "shipped", lambda b: b)
+    class_eps, method_eps = entrypoints_from_bases(cls, "drf", [RULE], lambda b: b)
     assert len(class_eps) == 1
     assert list(method_eps) == ["get"], "no phantom post entrypoint"
 
 
 def test_methods_point_back_at_the_routed_class_via():
     cls = _cls("get")
     cls.id = "can://python/app/a.py/V"
-    _, method_eps = entrypoints_from_bases(cls, "drf", [RULE], "shipped", lambda b: b)
+    _, method_eps = entrypoints_from_bases(cls, "drf", [RULE], lambda b: b)
     assert method_eps["get"][0].via == "can://python/app/a.py/V"
 
 
 def test_transitive_base_resolves_one_hop():
     cls = _cls("get", bases=("app.BaseView",))
     resolve = {"app.BaseView": "rest_framework.views.APIView"}.get
-    class_eps, _ = entrypoints_from_bases(cls, "drf", [RULE], "shipped", resolve)
+    class_eps, _ = entrypoints_from_bases(cls, "drf", [RULE], resolve)
     assert len(class_eps) == 1
 
 
 def test_unrelated_class_is_not_flagged():
     cls = _cls("get", bases=("object",))
-    class_eps, method_eps = entrypoints_from_bases(cls, "drf", [RULE], "shipped", lambda b: b)
+    class_eps, method_eps = entrypoints_from_bases(cls, "drf", [RULE], lambda b: b)
     assert class_eps == [] and method_eps == {}

test/test_entrypoint_decorators.py

@@ -33,7 +33,7 @@ def test_route_and_methods_are_extracted():
         route={"from": "positional", "index": 0},
         methods={"from": "keyword", "name": "methods", "default": ["GET"]},
     )
-    (ep,) = entrypoints_from_decorators(fn, "flask", [rule], "shipped")
+    (ep,) = entrypoints_from_decorators(fn, "flask", [rule])
     assert ep.route == "/products"
     assert ep.http_methods == ["POST"]
     assert ep.rule == "flask.route" and ep.ruleset == "shipped"
@@ -51,7 +51,7 @@ def test_verb_comes_from_the_matched_suffix():
         route={"from": "positional", "index": 0},
         methods={"from": "match_suffix"},
     )
-    (ep,) = entrypoints_from_decorators(fn, "fastapi", [rule], "shipped")
+    (ep,) = entrypoints_from_decorators(fn, "fastapi", [rule])
     assert ep.http_methods == ["POST"]
 
 
@@ -60,4 +60,4 @@ def test_unresolved_decorator_never_matches():
     fn = PyCallable(name="h", path="a.py", signature="a.h")
     fn.decorators.append(PyDecorator(name="app.route", qualified_name=None))
     rule = DecoratorRule(id="flask.route", match="flask.Flask.route")
-    assert entrypoints_from_decorators(fn, "flask", [rule], "shipped") == []
+    assert entrypoints_from_decorators(fn, "flask", [rule]) == []

test/test_entrypoint_pipeline.py

@@ -54,3 +54,105 @@ def test_malformed_user_rules_file_raises_instead_of_being_swallowed(tmp_path: P
         detect_entrypoints(app, tmp_path, rule_paths=(bad_rules,))
 
     assert app.entrypoint_report.errors == []
+
+
+def test_ruleset_provenance_distinguishes_shipped_from_user_rules(tmp_path: Path):
+    """A shipped rule's record must say "shipped" even when a user rules
+    file is also loaded -- the ruleset field exists so someone debugging a
+    surprising flag can find which file produced it."""
+    from codeanalyzer.schema.py_schema import PyCallable, PyDecorator, PyImport, PyModule
+
+    user_rules = tmp_path / "user.yml"
+    user_rules.write_text(
+        "frameworks:\n"
+        "  inhouse:\n"
+        "    detect: [inhouse]\n"
+        "    decorators:\n"
+        "      - id: inhouse.handler\n"
+        "        match: 'inhouse.app.handler'\n"
+    )
+
+    shipped_fn = PyCallable(name="f", path="a.py", signature="a.f")
+    shipped_fn.decorators.append(PyDecorator(name="app.route", qualified_name="flask.Flask.route"))
+    user_fn = PyCallable(name="g", path="a.py", signature="a.g")
+    user_fn.decorators.append(PyDecorator(name="handler", qualified_name="inhouse.app.handler"))
+
+    app = PyApplication(
+        symbol_table={
+            "a.py": PyModule(
+                file_path="a.py",
+                module_name="a",
+                functions={"f": shipped_fn, "g": user_fn},
+                imports=[
+                    PyImport(module="flask", name="Flask"),
+                    PyImport(module="inhouse", name="app"),
+                ],
+            )
+        }
+    )
+    detect_entrypoints(app, tmp_path, rule_paths=(user_rules,))
+
+    assert shipped_fn.entrypoints[0].ruleset == "shipped"
+    assert user_fn.entrypoints[0].ruleset == f"user:{user_rules}"
+
+
+def test_direct_base_class_is_flagged_when_the_import_resolves_it(tmp_path: Path):
+    """``class V(APIView)`` under ``from rest_framework.views import APIView``
+    is the idiomatic spelling -- base_classes stores the written name
+    ``"APIView"``, and it must resolve via the module's own import table."""
+    from codeanalyzer.schema.py_schema import PyClass, PyImport, PyModule
+
+    cls = PyClass(name="V", signature="a.V", base_classes=["APIView"])
+    app = PyApplication(
+        symbol_table={
+            "a.py": PyModule(
+                file_path="a.py",
+                module_name="a",
+                types={"a.V": cls},
+                imports=[PyImport(module="rest_framework.views", name="APIView")],
+            )
+        }
+    )
+    detect_entrypoints(app, tmp_path)
+    assert cls.is_entrypoint is True
+
+
+def test_direct_base_class_is_not_flagged_without_the_import(tmp_path: Path):
+    """``rest_framework`` is imported (so the drf framework gate passes) but
+    ``APIView`` itself is never imported into this module -- the written
+    "APIView" base has nothing to resolve against and must not be flagged."""
+    from codeanalyzer.schema.py_schema import PyClass, PyImport, PyModule
+
+    cls = PyClass(name="V", signature="a.V", base_classes=["APIView"])
+    app = PyApplication(
+        symbol_table={
+            "a.py": PyModule(
+                file_path="a.py",
+                module_name="a",
+                types={"a.V": cls},
+                imports=[PyImport(module="rest_framework", name="serializers")],
+            )
+        }
+    )
+    detect_entrypoints(app, tmp_path)
+    assert cls.is_entrypoint is False
+
+
+def test_dotted_base_class_resolves_through_a_module_import(tmp_path: Path):
+    """``class V(views.APIView)`` under ``from rest_framework import views``
+    -- the dotted base's head ("views") is the imported name."""
+    from codeanalyzer.schema.py_schema import PyClass, PyImport, PyModule
+
+    cls = PyClass(name="V", signature="a.V", base_classes=["views.APIView"])
+    app = PyApplication(
+        symbol_table={
+            "a.py": PyModule(
+                file_path="a.py",
+                module_name="a",
+                types={"a.V": cls},
+                imports=[PyImport(module="rest_framework", name="views")],
+            )
+        }
+    )
+    detect_entrypoints(app, tmp_path)
+    assert cls.is_entrypoint is True