feat(entrypoints): wrapped post-pass skeleton wired into the analyzer (#27)

Author: rahlk

codeanalyzer/core.py

@@ -636,6 +636,12 @@ def analyze(self) -> Analysis:
             backfill_callees(app, sig_to_id)
         reidentify_call_graph(app, sig_to_id)
 
+        # Entrypoints: a post-pass over the built L1 tree (#27). Runs at every
+        # level -- entrypoints are L1 data and must not vary with -a.
+        from codeanalyzer.entrypoints import detect_entrypoints
+
+        detect_entrypoints(app, self.project_dir, self.options.entrypoint_rules)
+
         # L3: intraprocedural dataflow (CFG/CDG/DDG) emitted onto the v2 tree.
         if self.analysis_level >= 3:
             from codeanalyzer.dataflow.builder import (

codeanalyzer/entrypoints/__init__.py

@@ -0,0 +1,3 @@
+from codeanalyzer.entrypoints.pipeline import detect_entrypoints
+
+__all__ = ["detect_entrypoints"]

codeanalyzer/entrypoints/pipeline.py

@@ -0,0 +1,57 @@
+"""Entrypoint detection: a post-pass over the built L1 symbol table (#27).
+
+Runs AFTER the symbol table exists so every view reference resolves as a
+lookup against ids that already exist. Additive metadata: a failure here
+loses flags, never the analysis.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, Iterator
+
+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."""
+    try:
+        _run_stages(app, project_dir, tuple(rule_paths))
+    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 _derive_flags(app: PyApplication) -> None:
+    for node in _walk(app):
+        node.is_entrypoint = bool(node.entrypoints)
+
+
+def _walk(app: PyApplication) -> Iterator[object]:
+    def walk_callable(c: PyCallable) -> Iterator[object]:
+        yield c
+        for inner in (c.callables or {}).values():
+            yield from walk_callable(inner)
+        for cls in (c.types or {}).values():
+            yield from walk_class(cls)
+
+    def walk_class(k: PyClass) -> Iterator[object]:
+        yield k
+        for m in (k.callables or {}).values():
+            yield from walk_callable(m)
+        for inner in (k.types or {}).values():
+            yield from walk_class(inner)
+
+    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)

codeanalyzer/options/options.py

@@ -1,6 +1,6 @@
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Tuple
 from enum import Enum
 
 
@@ -65,3 +65,4 @@ class AnalysisOptions:
     pycg_shard_timeout: int = 120
     pycg_shard_strategy: ShardStrategy = ShardStrategy.JEDI
     pycg_max_iter: int = 50
+    entrypoint_rules: Tuple[Path, ...] = ()

test/test_entrypoint_pipeline.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from codeanalyzer.entrypoints.pipeline import detect_entrypoints
+from codeanalyzer.schema.py_schema import PyApplication
+
+
+def test_pass_is_a_noop_on_an_empty_application(tmp_path: Path):
+    app = PyApplication(symbol_table={})
+    detect_entrypoints(app, tmp_path)
+    assert app.entrypoint_report.errors == []
+
+
+def test_pass_never_raises_and_records_the_failure(tmp_path: Path, monkeypatch):
+    """A finder crash must lose flags, not the analysis."""
+    import codeanalyzer.entrypoints.pipeline as p
+
+    def boom(*a, **k):
+        raise RuntimeError("finder exploded")
+
+    monkeypatch.setattr(p, "_run_stages", boom)
+    app = PyApplication(symbol_table={})
+    detect_entrypoints(app, tmp_path)          # must not raise
+    assert any("finder exploded" in e for e in app.entrypoint_report.errors)
+
+
+def test_derives_is_entrypoint_from_the_list(tmp_path: Path):
+    from codeanalyzer.schema.py_schema import PyCallable, PyEntrypoint, PyModule
+
+    fn = PyCallable(name="f", path="a.py", signature="a.f")
+    fn.entrypoints.append(
+        PyEntrypoint(framework="flask", confidence="certain", rule="flask.route", ruleset="shipped")
+    )
+    app = PyApplication(
+        symbol_table={
+            "a.py": PyModule(file_path="a.py", module_name="a", functions={"f": fn})
+        }
+    )
+    detect_entrypoints(app, tmp_path)
+    assert fn.is_entrypoint is True