feat(entrypoints): stage 0 framework detection gate (#27)

Loads entrypoint rules outside the detection pass's broad exception
handler so a malformed --entrypoint-rules file is a hard configuration
error (RulesError) rather than a swallowed detection failure.

Author: rahlk

codeanalyzer/entrypoints/detect.py

@@ -0,0 +1,59 @@
+"""Stage 0: which frameworks is this project actually using? (#27)
+
+Gates every later stage, so a project without Celery never pays for Celery
+rules and cannot false-positive on a locally-defined ``shared_task``. A
+package counts as present if first-party source imports it OR the dependency
+manifest names it -- either is sufficient, since an import may be dynamic.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Set
+
+from codeanalyzer.entrypoints.rules import RuleSet
+from codeanalyzer.schema.py_schema import PyApplication
+
+_REQ = re.compile(r"^\s*['\"]?([A-Za-z0-9_.\-]+)")
+_DEPS_ARRAY = re.compile(r"dependencies\s*=\s*\[(.*?)\]", re.DOTALL)
+_PKG = re.compile(r"['\"]([A-Za-z0-9][A-Za-z0-9_.\-]*)")
+
+
+def detected_frameworks(app: PyApplication, project_dir: Path, rules: RuleSet) -> Set[str]:
+    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]))
+    }
+
+
+def _imported_packages(app: PyApplication) -> Set[str]:
+    out: Set[str] = set()
+    for mod in app.symbol_table.values():
+        for imp in mod.imports or []:
+            # `from flask import Flask` puts the package in `module`, not `name`.
+            # Prefer `module`; fall back to `name` for a bare `import flask`.
+            spelling = (getattr(imp, "module", "") or getattr(imp, "name", "") or "")
+            spelling = spelling.lstrip(".")
+            if spelling:
+                out.add(spelling.split(".", 1)[0])
+    return out
+
+
+def _manifest_packages(project_dir: Path) -> Set[str]:
+    out: Set[str] = set()
+    pyproject = project_dir / "pyproject.toml"
+    if pyproject.exists():
+        # PEP 621 `[project] dependencies = [...]` -- single- or multi-line.
+        m = _DEPS_ARRAY.search(pyproject.read_text())
+        if m:
+            for pm in _PKG.finditer(m.group(1)):
+                out.add(pm.group(1).split("[", 1)[0].lower())
+    requirements = project_dir / "requirements.txt"
+    if requirements.exists():
+        for line in requirements.read_text().splitlines():
+            m = _REQ.match(line)
+            if m:
+                out.add(m.group(1).split("[", 1)[0].lower())
+    return out

codeanalyzer/entrypoints/pipeline.py

@@ -9,25 +9,37 @@
 from pathlib import Path
 from typing import Iterable, Iterator
 
+from codeanalyzer.entrypoints.detect import detected_frameworks
+from codeanalyzer.entrypoints.rules import RuleSet, load_rules
 from codeanalyzer.schema.py_schema import PyApplication, PyCallable, PyClass
 from codeanalyzer.utils import logger
 
 
 def detect_entrypoints(
     app: PyApplication, project_dir: Path, rule_paths: Iterable[Path] = ()
 ) -> None:
-    """Populate ``entrypoints`` on every callable and class, in place."""
+    """Populate ``entrypoints`` on every callable and class, in place.
+
+    Loading the rules is a CONFIGURATION step, not a detection step: a
+    malformed user rules file is a hard error that must stop the run before
+    analysis starts, so ``load_rules`` runs outside (and before) the
+    try/except below. Everything after that -- the actual framework
+    detection -- is best-effort and must never abort the analysis.
+    """
+    rules = load_rules(rule_paths)
     try:
-        _run_stages(app, project_dir, tuple(rule_paths))
+        _run_stages(app, project_dir, rules)
     except Exception as exc:  # noqa: BLE001 - additive pass must never abort analysis
         logger.warning("entrypoint detection failed: %s", exc)
         app.entrypoint_report.errors.append(str(exc))
     _derive_flags(app)
 
 
-def _run_stages(app: PyApplication, project_dir: Path, rule_paths: tuple) -> None:
-    """Stages 0-4. Empty until Task 5; the skeleton exists so the contract does."""
-    return None
+def _run_stages(app: PyApplication, project_dir: Path, rules: RuleSet) -> None:
+    """Stages 0-4. Only stage 0 (framework detection) exists so far."""
+    app.entrypoint_report.rulesets = list(rules.rulesets)
+    frameworks = detected_frameworks(app, project_dir, rules)
+    app.entrypoint_report.frameworks_detected = sorted(frameworks)
 
 
 def _derive_flags(app: PyApplication) -> None:

test/test_entrypoint_detect.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+
+from codeanalyzer.entrypoints.detect import detected_frameworks
+from codeanalyzer.entrypoints.rules import load_rules
+from codeanalyzer.schema.py_schema import PyApplication, PyImport, PyModule
+
+
+def _app(*modules: str) -> PyApplication:
+    return PyApplication(
+        symbol_table={
+            "a.py": PyModule(
+                file_path="a.py",
+                module_name="a",
+                imports=[PyImport(module=m, name=m.split(".")[-1]) for m in modules],
+            )
+        }
+    )
+
+
+def test_framework_detected_from_an_import(tmp_path: Path):
+    got = detected_frameworks(_app("flask"), tmp_path, load_rules())
+    assert "flask" in got
+
+
+def test_absent_framework_is_not_detected(tmp_path: Path):
+    got = detected_frameworks(_app("os"), tmp_path, load_rules())
+    assert "celery" not 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'
+    )
+    got = detected_frameworks(_app("os"), tmp_path, load_rules())
+    assert "celery" in got

test/test_entrypoint_pipeline.py

@@ -1,6 +1,9 @@
 from pathlib import Path
 
+import pytest
+
 from codeanalyzer.entrypoints.pipeline import detect_entrypoints
+from codeanalyzer.entrypoints.rules import RulesError
 from codeanalyzer.schema.py_schema import PyApplication
 
 
@@ -37,3 +40,17 @@ def test_derives_is_entrypoint_from_the_list(tmp_path: Path):
     )
     detect_entrypoints(app, tmp_path)
     assert fn.is_entrypoint is True
+
+
+def test_malformed_user_rules_file_raises_instead_of_being_swallowed(tmp_path: Path):
+    """A bad --entrypoint-rules file is a CONFIGURATION error, not a detection
+    failure: it must stop the run via RulesError, not land quietly in
+    entrypoint_report.errors like a finder crash would."""
+    bad_rules = tmp_path / "bad_rules.yml"
+    bad_rules.write_text("frameworks: not-a-mapping\n")
+    app = PyApplication(symbol_table={})
+
+    with pytest.raises(RulesError):
+        detect_entrypoints(app, tmp_path, rule_paths=(bad_rules,))
+
+    assert app.entrypoint_report.errors == []