codeanalyzer-python 1.1.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

codeanalyzer/entrypoints/pipeline.py

@@ -0,0 +1,131 @@
+"""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 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, PyModule
+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.
+
+    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, 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, rules: RuleSet) -> None:
+    """Stages 0-4. Stage 0 (framework detection) and Stage 3 (decorator and
+    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.
+
+    Clears every node's ``entrypoints`` first: on a warm cache,
+    ``_build_symbol_table`` reuses the SAME cached ``PyModule``/``PyCallable``
+    objects when a file is unchanged, so without this clear a second run
+    would ``extend`` onto records already written by the first run and
+    duplicate them. A single full clear up front (rather than clearing each
+    node as it's visited) avoids wiping ``entrypoints_from_bases`` records
+    that ``_walk_module`` writes onto a method before visiting that method
+    directly.
+    """
+    for node in _walk(app):
+        node.entrypoints = []
+
+    app.entrypoint_report.rulesets = list(rules.rulesets)
+    frameworks = detected_frameworks(app, project_dir, rules)
+    app.entrypoint_report.frameworks_detected = sorted(frameworks)
+
+    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_module(mod: PyModule) -> 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 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():
+        yield from _walk_module(mod)

codeanalyzer/entrypoints/rules.py

@@ -0,0 +1,159 @@
+"""Loading and merging of entrypoint rules (#27).
+
+The shipped ``rules.yml`` covers known frameworks; users extend it with
+``--entrypoint-rules``. User rules merge additively and may ``disable:`` a
+shipped rule by id. A malformed user file is a hard error before analysis
+starts -- silently skipping it would let someone ship rules they believe
+are live.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+import yaml
+
+from codeanalyzer.entrypoints.matching import PatternError, validate_pattern
+
+_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):
+    """Raised for a malformed rules file. Never swallowed."""
+
+
+@dataclass
+class DecoratorRule:
+    id: str
+    match: str
+    confidence: str = "certain"
+    route: Optional[Dict[str, Any]] = None
+    methods: Optional[Dict[str, Any]] = None
+    origin: str = "shipped"
+
+
+@dataclass
+class BaseRule:
+    id: str
+    match: str
+    confidence: str = "certain"
+    transitive: bool = False
+    dispatch: List[str] = field(default_factory=list)
+    origin: str = "shipped"
+
+
+@dataclass
+class Framework:
+    name: str
+    detect: List[str] = field(default_factory=list)
+    decorators: List[DecoratorRule] = field(default_factory=list)
+    bases: List[BaseRule] = field(default_factory=list)
+
+
+@dataclass
+class RuleSet:
+    frameworks: Dict[str, Framework] = field(default_factory=dict)
+    rulesets: List[str] = field(default_factory=list)
+
+
+def load_rules(user_paths: Iterable[Path] = ()) -> RuleSet:
+    out = RuleSet()
+    _merge(out, _read(_SHIPPED), "shipped")
+    for p in user_paths:
+        _merge(out, _read(Path(p)), f"user:{p}")
+    return out
+
+
+def _read(path: Path) -> Dict[str, Any]:
+    try:
+        data = yaml.safe_load(path.read_text())
+    except FileNotFoundError as exc:
+        raise RulesError(f"rules file not found: {path}") from exc
+    except yaml.YAMLError as exc:
+        raise RulesError(f"{path}: invalid YAML: {exc}") from exc
+    if not isinstance(data, dict):
+        raise RulesError(f"{path}: top level must be a mapping")
+    return data
+
+
+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 {}
+    if not isinstance(frameworks, dict):
+        raise RulesError(f"{origin}: `frameworks` must be a mapping")
+
+    for name, body in frameworks.items():
+        if not isinstance(body, dict):
+            raise RulesError(f"{origin}: framework `{name}` must be a mapping")
+        fw = out.frameworks.setdefault(name, Framework(name=name))
+        fw.detect = sorted(set(fw.detect) | set(body.get("detect") or []))
+        for raw in body.get("decorators") or []:
+            fw.decorators.append(_decorator_rule(raw, origin))
+        for raw in body.get("bases") or []:
+            fw.bases.append(_base_rule(raw, origin))
+
+    for fw in out.frameworks.values():
+        fw.decorators = [r for r in fw.decorators if r.id not in disabled]
+        fw.bases = [r for r in fw.bases if r.id not in disabled]
+
+
+def _disable_list(data: Dict[str, Any], origin: str) -> List[str]:
+    raw = data.get("disable") or []
+    if not isinstance(raw, list) or not all(isinstance(x, str) for x in raw):
+        raise RulesError(f"{origin}: `disable` must be a list of rule id strings")
+    return raw
+
+
+def _require(raw: Dict[str, Any], key: str, origin: str) -> Any:
+    if key not in raw:
+        raise RulesError(f"{origin}: rule {raw!r} is missing `{key}`")
+    return raw[key]
+
+
+def _confidence(raw: Dict[str, Any], origin: str) -> str:
+    c = raw.get("confidence", "certain")
+    if c not in _CONFIDENCE:
+        raise RulesError(f"{origin}: confidence must be one of {sorted(_CONFIDENCE)}, got {c!r}")
+    return c
+
+
+def _match(raw: Dict[str, Any], origin: str) -> str:
+    match = _require(raw, "match", origin)
+    try:
+        validate_pattern(match)
+    except PatternError as exc:
+        raise RulesError(f"{origin}: rule {raw.get('id', raw)!r}: {exc}") from exc
+    return match
+
+
+def _decorator_rule(raw: Dict[str, Any], origin: str) -> DecoratorRule:
+    return DecoratorRule(
+        id=_require(raw, "id", origin),
+        match=_match(raw, origin),
+        confidence=_confidence(raw, origin),
+        route=raw.get("route"),
+        methods=raw.get("methods"),
+        origin=origin,
+    )
+
+
+def _base_rule(raw: Dict[str, Any], origin: str) -> BaseRule:
+    return BaseRule(
+        id=_require(raw, "id", origin),
+        match=_match(raw, origin),
+        confidence=_confidence(raw, origin),
+        transitive=bool(raw.get("transitive", False)),
+        dispatch=list(raw.get("dispatch") or []),
+        origin=origin,
+    )

codeanalyzer/entrypoints/rules.yml

@@ -0,0 +1,88 @@
+version: 1
+
+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.sansio.scaffold.Scaffold.route"
+        route: {from: positional, index: 0}
+        methods: {from: keyword, name: methods, default: [GET]}
+      - id: flask.bp-verb
+        match: "flask.sansio.scaffold.Scaffold.{get,post,put,delete,patch}"
+        route: {from: positional, index: 0}
+        methods: {from: match_suffix}
+    bases:
+      - id: flask.methodview
+        match: "flask.views.MethodView"
+        transitive: true
+        dispatch: [get, post, put, delete, patch]
+
+  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.applications.FastAPI.{get,post,put,delete,patch,head,options}"
+        route: {from: positional, index: 0}
+        methods: {from: match_suffix}
+      - id: fastapi.router-verb
+        match: "fastapi.routing.APIRouter.{get,post,put,delete,patch}"
+        route: {from: positional, index: 0}
+        methods: {from: match_suffix}
+      - id: fastapi.websocket
+        match: "fastapi.applications.FastAPI.websocket"
+        route: {from: positional, index: 0}
+
+  celery:
+    detect: [celery]
+    decorators:
+      - id: celery.shared-task
+        match: "celery.app.shared_task"
+      - id: celery.task
+        match: "celery.app.base.Celery.task"
+
+  click:
+    detect: [click, typer]
+    decorators:
+      - id: click.command
+        match: "click.decorators.{command,group}"
+      - id: typer.command
+        match: "typer.main.Typer.command"
+
+  drf:
+    detect: [rest_framework]
+    decorators:
+      - id: drf.api-view
+        match: "rest_framework.decorators.api_view"
+      - id: drf.action
+        match: "rest_framework.decorators.action"
+    bases:
+      - id: drf.apiview
+        match: "rest_framework.views.APIView"
+        transitive: true
+        dispatch: [get, post, put, patch, delete, head, options]
+      - id: drf.viewset
+        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]

codeanalyzer/neo4j/bolt.py

@@ -46,7 +46,7 @@ from codeanalyzer.utils import logger
 
 DESCENDANTS = (
     "[:PY_DECLARES|PY_HAS_METHOD|PY_HAS_ATTRIBUTE|PY_DECLARES_VAR"
-    "|PY_HAS_CALLSITE|PY_HAS_CFG_NODE*1..]"
+    "|PY_HAS_CALLSITE|PY_HAS_BODY_NODE*1..]"
 )
 BATCH = 1000