fix(entrypoints): repoint decorator rules at Jedi's real resolution paths

Every shipped decorator rule matched the framework's public re-export
path (flask.Flask.route, fastapi.FastAPI.get, celery.Celery.task,
click.command, ...) but PyDecorator.qualified_name is Jedi's DEFINITION
path (flask.sansio.scaffold.Scaffold.route,
fastapi.applications.FastAPI.get, celery.app.base.Celery.task,
click.decorators.command, ...), so none of them ever matched a real
app. Verified each pattern against the installed package via
jedi.Script.infer(...).full_name.

Also:
- add a django: block (bases: django.views.generic.* dispatch) so a
  Django project reports frameworks_detected: ["django"] instead of
  [] -- base-class matching resolves against the module's own import
  table, not Jedi's definition path, so the public spelling is
  correct there.
- normalize detect.py's case handling: imported package names are now
  lowercased alongside the already-lowercased manifest names, and
  detect: values are lowercased before the membership check, so
  detect: [Flask] matches a real `import flask`.
- reject unknown top-level rules.yml keys (e.g. the not-yet-implemented
  declared: block) instead of silently ignoring them.

Author: rahlk

codeanalyzer/entrypoints/detect.py

@@ -21,11 +21,15 @@
 
 
 def detected_frameworks(app: PyApplication, project_dir: Path, rules: RuleSet) -> Set[str]:
+    # `present` (imports, manifest names) and `detect:` values are both
+    # lowercased before comparison -- manifest names were already lowercased
+    # (PyPI/pip is case-insensitive) but imports and `detect:` were not, so
+    # a `detect: [Flask]` user rule silently never matched a `flask` import.
     present = _imported_packages(app) | _manifest_packages(project_dir)
     return {
         name
         for name, fw in rules.frameworks.items()
-        if any(pkg in present for pkg in (fw.detect or [name]))
+        if any(pkg.lower() in present for pkg in (fw.detect or [name]))
     }
 
 
@@ -38,7 +42,7 @@ def _imported_packages(app: PyApplication) -> Set[str]:
             spelling = (getattr(imp, "module", "") or getattr(imp, "name", "") or "")
             spelling = spelling.lstrip(".")
             if spelling:
-                out.add(spelling.split(".", 1)[0])
+                out.add(spelling.split(".", 1)[0].lower())
     return out
 
 

codeanalyzer/entrypoints/rules.py

@@ -18,6 +18,11 @@
 
 _SHIPPED = Path(__file__).with_name("rules.yml")
 _CONFIDENCE = {"declared", "certain", "heuristic"}
+# `declared:` (readers) and per-framework routing engines are real spec
+# blocks (Units 4-5) not implemented yet; they are deliberately absent here
+# rather than accepted-and-ignored, so a user file using them fails loudly
+# instead of loading clean and doing nothing.
+_TOP_LEVEL_KEYS = {"version", "frameworks", "disable"}
 
 
 class RulesError(Exception):
@@ -79,6 +84,9 @@ def _read(path: Path) -> Dict[str, Any]:
 
 
 def _merge(out: RuleSet, data: Dict[str, Any], origin: str) -> None:
+    unknown = sorted(set(data) - _TOP_LEVEL_KEYS)
+    if unknown:
+        raise RulesError(f"{origin}: unknown top-level key(s): {', '.join(unknown)}")
     out.rulesets.append(origin)
     disabled = set(_disable_list(data, origin))
     frameworks = data.get("frameworks") or {}

codeanalyzer/entrypoints/rules.yml

@@ -4,12 +4,16 @@ frameworks:
   flask:
     detect: [flask]
     decorators:
+      # Flask 3's Flask/Blueprint decorators are all inherited from one base
+      # (flask.sansio.scaffold.Scaffold); matching is on Jedi's resolved
+      # DEFINITION path, not the public `flask.Flask`/`flask.Blueprint`
+      # spelling, so one rule now covers both call sites.
       - id: flask.route
-        match: "flask.Flask.route"
+        match: "flask.sansio.scaffold.Scaffold.route"
         route: {from: positional, index: 0}
         methods: {from: keyword, name: methods, default: [GET]}
       - id: flask.bp-verb
-        match: "flask.Blueprint.{get,post,put,delete,patch}"
+        match: "flask.sansio.scaffold.Scaffold.{get,post,put,delete,patch}"
         route: {from: positional, index: 0}
         methods: {from: match_suffix}
     bases:
@@ -21,33 +25,37 @@ frameworks:
   fastapi:
     detect: [fastapi]
     decorators:
+      # FastAPI's own get/post/... are defined directly on the FastAPI class
+      # (fastapi/applications.py); APIRouter's are a distinct class
+      # (fastapi/routing.py) -- Jedi resolves each to its own module, so
+      # these stay two rules.
       - id: fastapi.verb
-        match: "fastapi.FastAPI.{get,post,put,delete,patch,head,options}"
+        match: "fastapi.applications.FastAPI.{get,post,put,delete,patch,head,options}"
         route: {from: positional, index: 0}
         methods: {from: match_suffix}
       - id: fastapi.router-verb
-        match: "fastapi.APIRouter.{get,post,put,delete,patch}"
+        match: "fastapi.routing.APIRouter.{get,post,put,delete,patch}"
         route: {from: positional, index: 0}
         methods: {from: match_suffix}
       - id: fastapi.websocket
-        match: "fastapi.FastAPI.websocket"
+        match: "fastapi.applications.FastAPI.websocket"
         route: {from: positional, index: 0}
 
   celery:
     detect: [celery]
     decorators:
       - id: celery.shared-task
-        match: "celery.shared_task"
+        match: "celery.app.shared_task"
       - id: celery.task
-        match: "celery.Celery.task"
+        match: "celery.app.base.Celery.task"
 
   click:
     detect: [click, typer]
     decorators:
       - id: click.command
-        match: "click.{command,group}"
+        match: "click.decorators.{command,group}"
       - id: typer.command
-        match: "typer.Typer.command"
+        match: "typer.main.Typer.command"
 
   drf:
     detect: [rest_framework]
@@ -65,3 +73,16 @@ frameworks:
         match: "rest_framework.viewsets.*"
         transitive: true
         dispatch: [list, retrieve, create, update, partial_update, destroy]
+
+  django:
+    detect: [django]
+    bases:
+      # Base-class matching resolves against the module's own import table
+      # (the WRITTEN spelling, e.g. `from django.views.generic import
+      # ListView`), never Jedi's definition path -- so the public
+      # `django.views.generic.*` path is correct here, unlike the decorator
+      # rules above.
+      - id: django.cbv
+        match: "django.views.generic.*"
+        transitive: true
+        dispatch: [get, post, put, patch, delete, head, options]

docs/design/specs/call-site-body-convergence.md

@@ -27,6 +27,16 @@ def test_absent_framework_is_not_detected(tmp_path: Path):
     assert "celery" not in got
 
 
+def test_detect_value_case_is_normalized_against_a_lowercase_import(tmp_path: Path):
+    """A ``detect: [Flask]`` user rule must fire against a real ``import
+    flask`` -- imports are recorded lowercase, so `detect:` values need the
+    same normalization or they silently never match (#122 review, MINOR)."""
+    user = tmp_path / "user.yml"
+    user.write_text("version: 1\nframeworks:\n  myflask:\n    detect: [Flask]\n")
+    got = detected_frameworks(_app("flask"), tmp_path, load_rules([user]))
+    assert "myflask" in got
+
+
 def test_manifest_entry_alone_is_sufficient(tmp_path: Path):
     (tmp_path / "pyproject.toml").write_text(
         '[project]\nname = "x"\ndependencies = ["celery>=5"]\n'

test/test_entrypoint_detect.py

@@ -34,7 +34,7 @@ def test_derives_is_entrypoint_from_the_list(tmp_path: Path):
     from codeanalyzer.schema.py_schema import PyCallable, PyDecorator, PyImport, PyModule
 
     fn = PyCallable(name="f", path="a.py", signature="a.f")
-    fn.decorators.append(PyDecorator(name="route", qualified_name="flask.Flask.route"))
+    fn.decorators.append(PyDecorator(name="route", qualified_name="flask.sansio.scaffold.Scaffold.route"))
     app = PyApplication(
         symbol_table={
             "a.py": PyModule(
@@ -80,7 +80,7 @@ def test_ruleset_provenance_distinguishes_shipped_from_user_rules(tmp_path: Path
     )
 
     shipped_fn = PyCallable(name="f", path="a.py", signature="a.f")
-    shipped_fn.decorators.append(PyDecorator(name="app.route", qualified_name="flask.Flask.route"))
+    shipped_fn.decorators.append(PyDecorator(name="app.route", qualified_name="flask.sansio.scaffold.Scaffold.route"))
     user_fn = PyCallable(name="g", path="a.py", signature="a.g")
     user_fn.decorators.append(PyDecorator(name="handler", qualified_name="inhouse.app.handler"))
 
@@ -173,7 +173,7 @@ def test_running_the_pass_twice_does_not_duplicate_entrypoints(tmp_path: Path):
     from codeanalyzer.schema.py_schema import PyCallable, PyDecorator, PyImport, PyModule
 
     fn = PyCallable(name="f", path="a.py", signature="a.f")
-    fn.decorators.append(PyDecorator(name="route", qualified_name="flask.Flask.route"))
+    fn.decorators.append(PyDecorator(name="route", qualified_name="flask.sansio.scaffold.Scaffold.route"))
     app = PyApplication(
         symbol_table={
             "a.py": PyModule(

test/test_entrypoint_pipeline.py

@@ -11,6 +11,27 @@ def test_shipped_rules_load_and_include_flask():
     assert any(r.id == "flask.route" for r in flask.decorators)
 
 
+def test_shipped_rules_include_django_cbv_dispatch():
+    """A Django project must report ``frameworks_detected: ["django"]``
+    distinct from an unsupported project, even with the routing engine
+    (Unit 5) still absent -- the `bases:` rule works today via the
+    import-table resolver (#122 review, IMPORTANT 2)."""
+    rs = load_rules()
+    assert "django" in rs.frameworks
+    django = rs.frameworks["django"]
+    assert "django" in django.detect
+    cbv = next(r for r in django.bases if r.id == "django.cbv")
+    assert cbv.match == "django.views.generic.*"
+    assert set(cbv.dispatch) == {"get", "post", "put", "patch", "delete", "head", "options"}
+
+
+def test_unknown_top_level_key_is_rejected(tmp_path):
+    bad = tmp_path / "bad.yml"
+    bad.write_text("declared:\n  - id: pyproject.scripts\n")
+    with pytest.raises(RulesError, match="declared"):
+        load_rules([bad])
+
+
 def test_every_shipped_rule_has_a_stable_id_and_valid_confidence():
     rs = load_rules()
     for fw in rs.frameworks.values():