feat(entrypoints): decorator rule matching with route extraction (#27)

Author: rahlk

codeanalyzer/entrypoints/matching.py

@@ -0,0 +1,103 @@
+"""Stage 3: match rules against decorators and base classes (#27).
+
+Matching is on ``PyDecorator.qualified_name`` -- never the written spelling --
+so ``@route`` under ``from flask import route`` hits the same rule as
+``@app.route``. An unresolved decorator (``qualified_name is None``) never
+matches: under-approximate rather than guess.
+"""
+from __future__ import annotations
+
+import ast
+import re
+from typing import Any, Dict, Iterable, List, Optional
+
+from codeanalyzer.entrypoints.rules import DecoratorRule
+from codeanalyzer.schema.py_schema import PyEntrypoint
+
+# Dispatch names that are HTTP verbs. DRF's ViewSet dispatch names
+# (list, retrieve, create, ...) are NOT verbs and must not be emitted as such.
+_HTTP_VERBS = {"get", "post", "put", "patch", "delete", "head", "options"}
+
+
+def match_pattern(pattern: str, qualified_name: Optional[str]) -> bool:
+    """``{a,b}`` alternation and trailing ``*``; everything else is literal."""
+    if not qualified_name:
+        return False
+    return re.fullmatch(_compile(pattern), qualified_name) is not None
+
+
+def _compile(pattern: str) -> str:
+    out, i = [], 0
+    while i < len(pattern):
+        ch = pattern[i]
+        if ch == "{":
+            j = pattern.index("}", i)
+            alts = pattern[i + 1 : j].split(",")
+            out.append("(?:" + "|".join(re.escape(a.strip()) for a in alts) + ")")
+            i = j + 1
+        elif ch == "*":
+            out.append(r"[^\s]*")
+            i += 1
+        else:
+            out.append(re.escape(ch))
+            i += 1
+    return "".join(out)
+
+
+def _literal(text: Optional[str]) -> Any:
+    """Best-effort: decorator arguments are unparsed source fragments."""
+    if text is None:
+        return None
+    try:
+        return ast.literal_eval(text)
+    except (ValueError, SyntaxError):
+        return None
+
+
+def _route_of(dec, spec: Optional[Dict[str, Any]]) -> Optional[str]:
+    if not spec or spec.get("from") != "positional":
+        return None
+    args = dec.positional_arguments or []
+    idx = int(spec.get("index", 0))
+    if idx >= len(args):
+        return None
+    value = _literal(args[idx])
+    return value if isinstance(value, str) else None
+
+
+def _methods_of(dec, rule: DecoratorRule, spec: Optional[Dict[str, Any]]) -> List[str]:
+    if not spec:
+        return []
+    source = spec.get("from")
+    if source == "match_suffix":
+        verb = (dec.qualified_name or "").rsplit(".", 1)[-1]
+        return [verb.upper()]
+    if source == "keyword":
+        raw = (dec.keyword_arguments or {}).get(spec.get("name", ""))
+        value = _literal(raw)
+        if isinstance(value, (list, tuple)):
+            return [str(v).upper() for v in value]
+        return [str(v).upper() for v in (spec.get("default") or [])]
+    return []
+
+
+def entrypoints_from_decorators(
+    node, framework: str, rules: Iterable[DecoratorRule], ruleset: str
+) -> List[PyEntrypoint]:
+    out: List[PyEntrypoint] = []
+    for dec in getattr(node, "decorators", []) or []:
+        for rule in rules:
+            if not match_pattern(rule.match, dec.qualified_name):
+                continue
+            out.append(
+                PyEntrypoint(
+                    framework=framework,
+                    confidence=rule.confidence,
+                    rule=rule.id,
+                    ruleset=ruleset,
+                    evidence=dec.qualified_name,
+                    route=_route_of(dec, rule.route),
+                    http_methods=_methods_of(dec, rule, rule.methods),
+                )
+            )
+    return out

test/test_entrypoint_decorators.py

@@ -0,0 +1,56 @@
+from codeanalyzer.entrypoints.matching import entrypoints_from_decorators, match_pattern
+from codeanalyzer.entrypoints.rules import DecoratorRule
+from codeanalyzer.schema.py_schema import PyCallable, PyDecorator
+
+
+def test_brace_alternation_and_wildcard():
+    assert match_pattern("flask.Blueprint.{get,post}", "flask.Blueprint.get")
+    assert not match_pattern("flask.Blueprint.{get,post}", "flask.Blueprint.delete")
+    assert match_pattern("rest_framework.viewsets.*", "rest_framework.viewsets.ModelViewSet")
+    assert not match_pattern("flask.Flask.route", "flask.Flask.routes")
+
+
+def test_route_and_methods_are_extracted():
+    fn = PyCallable(name="h", path="a.py", signature="a.h")
+    fn.decorators.append(
+        PyDecorator(
+            name="app.route",
+            qualified_name="flask.Flask.route",
+            positional_arguments=["'/products'"],
+            keyword_arguments={"methods": "['POST']"},
+        )
+    )
+    rule = DecoratorRule(
+        id="flask.route",
+        match="flask.Flask.route",
+        route={"from": "positional", "index": 0},
+        methods={"from": "keyword", "name": "methods", "default": ["GET"]},
+    )
+    (ep,) = entrypoints_from_decorators(fn, "flask", [rule], "shipped")
+    assert ep.route == "/products"
+    assert ep.http_methods == ["POST"]
+    assert ep.rule == "flask.route" and ep.ruleset == "shipped"
+
+
+def test_verb_comes_from_the_matched_suffix():
+    fn = PyCallable(name="h", path="a.py", signature="a.h")
+    fn.decorators.append(
+        PyDecorator(name="router.post", qualified_name="fastapi.APIRouter.post",
+                    positional_arguments=["'/x'"])
+    )
+    rule = DecoratorRule(
+        id="fastapi.router-verb",
+        match="fastapi.APIRouter.{get,post}",
+        route={"from": "positional", "index": 0},
+        methods={"from": "match_suffix"},
+    )
+    (ep,) = entrypoints_from_decorators(fn, "fastapi", [rule], "shipped")
+    assert ep.http_methods == ["POST"]
+
+
+def test_unresolved_decorator_never_matches():
+    """qualified_name is None when Jedi could not resolve; must not guess."""
+    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") == []