entrygraph 0.1.0__py3-none-any.whl

entrygraph/detect/entrypoints/base.py

@@ -0,0 +1,124 @@
+"""Entrypoint rule schema and registry.
+
+Rules are IR-driven: they match against a FileExtraction (symbols, decorators,
+references, framework signals) rather than re-walking the tree, which keeps
+them cheap and language-uniform. A rule gated on a framework only runs when
+that framework was detected above threshold — `app.get("/x")` in random code
+is not an Express route.
+
+Adding a framework = registering one rule (and usually one FrameworkSpec).
+Third parties: entrygraph.detect.entrypoints.register(rule).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Callable
+
+from entrygraph.extract.ir import EntrypointHint, FileExtraction
+from entrygraph.kinds import EntrypointKind
+
+Matcher = Callable[[FileExtraction], list[EntrypointHint]]
+
+
+@dataclass(frozen=True, slots=True)
+class EntrypointRule:
+    id: str  # "python.flask.route"
+    language: str
+    framework: str | None  # None => language-core rule, always runs
+    kind: EntrypointKind
+    match: Matcher
+
+
+_RULES: list[EntrypointRule] = []
+
+
+def register(rule: EntrypointRule) -> None:
+    _RULES.append(rule)
+
+
+# TypeScript/TSX reuse the JavaScript rule set (one extractor drives all three).
+_LANG_ALIASES = {"typescript": "javascript", "tsx": "javascript"}
+
+
+def rules_for(language: str, detected_frameworks: set[str]) -> list[EntrypointRule]:
+    lang = _LANG_ALIASES.get(language, language)
+    return [
+        r
+        for r in _RULES
+        if r.language == lang
+        and (r.framework is None or r.framework in detected_frameworks)
+    ]
+
+
+def all_rules() -> list[EntrypointRule]:
+    return list(_RULES)
+
+
+# ---------------- shared decorator-parsing helpers ----------------
+
+_STRING_ARG = re.compile(r"""\(\s*[rbf]*["']([^"']+)["']""")
+_METHODS_KWARG = re.compile(r"""methods\s*=\s*[\[(]([^\])]*)[\])]""")
+_QUOTED = re.compile(r"""["']([^"']+)["']""")
+_IDENTIFIER = re.compile(r"[A-Za-z_]\w*")
+_PARAMS = re.compile(r"\(([^)]*)\)")
+
+# names conventionally carrying user-controlled input across web frameworks
+_TAINTED_NAMES = frozenset(
+    {"request", "req", "params", "event", "body", "payload", "query", "form", "data"}
+)
+
+
+def first_string_arg(decorator_text: str) -> str | None:
+    match = _STRING_ARG.search(decorator_text)
+    return match.group(1) if match else None
+
+
+def methods_kwarg(decorator_text: str) -> list[str]:
+    match = _METHODS_KWARG.search(decorator_text)
+    if not match:
+        return []
+    return [m.upper() for m in _QUOTED.findall(match.group(1))]
+
+
+def identifier_args(arg_preview: str | None) -> list[str]:
+    """Bare identifiers appearing as call arguments (best-effort over the preview).
+
+    Skips string/number literals and keyword-argument names before '='.
+    """
+    if not arg_preview:
+        return []
+    names: list[str] = []
+    for part in arg_preview.strip("()").split(","):
+        token = part.strip()
+        if "=" in token:  # keyword arg: take the value side only
+            token = token.split("=", 1)[1].strip()
+        if token and _IDENTIFIER.fullmatch(token):
+            names.append(token)
+    return names
+
+
+def tainted_params(signature: str | None, kind: str) -> list[str]:
+    """Parameters of an entrypoint handler that are likely user-controlled.
+
+    HTTP handlers: every parameter except self/cls (path/query params flow in).
+    Lambda handlers: the `event` parameter. Otherwise: parameters whose names
+    match the conventional tainted-name set.
+    """
+    if not signature:
+        return []
+    match = _PARAMS.search(signature)
+    if not match:
+        return []
+    raw = [p.strip() for p in match.group(1).split(",") if p.strip()]
+    params = []
+    for p in raw:
+        name = p.split(":", 1)[0].split("=", 1)[0].strip().lstrip("*")
+        if name and name not in ("self", "cls"):
+            params.append(name)
+    if kind == "http_route":
+        return params
+    if kind == "lambda_handler":
+        return [p for p in params if p == "event"] or params[:1]
+    return [p for p in params if p in _TAINTED_NAMES]

entrygraph/detect/entrypoints/configs.py

@@ -0,0 +1,139 @@
+"""Config-file entrypoints — handlers declared outside source code.
+
+The walker only feeds source files to extractors, so serverless/SAM handler
+fields, Procfile process lines, and Dockerfile CMD/ENTRYPOINT never reach the
+IR-driven rules. This module scans a handful of well-known root files with the
+same stdlib+regex approach as detect/manifests.py (there is no YAML dependency),
+producing ConfigHints that bind to a real symbol where possible.
+
+`Entrypoint.symbol_id` is NOT NULL, so a hint whose handler cannot be bound to
+an indexed symbol is dropped rather than synthesizing a placeholder symbol.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from entrygraph.kinds import EntrypointKind
+
+_SERVERLESS_HANDLER = re.compile(r"^\s*handler:\s*([^\s#]+)", re.MULTILINE)
+_SAM_HANDLER = re.compile(r"^\s*Handler:\s*([^\s#]+)", re.MULTILINE)
+_PROCFILE_LINE = re.compile(r"^(\w+):\s*(.+)$", re.MULTILINE)
+_DOCKER_CMD = re.compile(r"^\s*(?:CMD|ENTRYPOINT)\s+(.+)$", re.MULTILINE | re.IGNORECASE)
+
+# frameworks whose entrypoints are re-derived from config each index run
+CONFIG_FRAMEWORKS = ("serverless", "sam", "procfile", "docker")
+
+
+@dataclass(slots=True)
+class ConfigHint:
+    kind: EntrypointKind
+    framework: str
+    handler_ref: str  # raw handler string as written in the config
+    name: str
+    route: str | None = None
+    metadata: dict = field(default_factory=dict)
+
+
+def scan_config_entrypoints(root: str | Path) -> list[ConfigHint]:
+    root = Path(root)
+    hints: list[ConfigHint] = []
+    for name in ("serverless.yml", "serverless.yaml"):
+        hints += _scan(root / name, _SERVERLESS_HANDLER, EntrypointKind.LAMBDA_HANDLER, "serverless")
+    for name in ("template.yaml", "template.yml"):
+        hints += _scan(root / name, _SAM_HANDLER, EntrypointKind.LAMBDA_HANDLER, "sam")
+    hints += _scan_procfile(root / "Procfile")
+    hints += _scan_dockerfile(root / "Dockerfile")
+    return hints
+
+
+def _read(path: Path) -> str | None:
+    if not path.is_file():
+        return None
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:  # pragma: no cover
+        return None
+
+
+def _scan(path: Path, pattern: re.Pattern, kind: EntrypointKind, framework: str) -> list[ConfigHint]:
+    text = _read(path)
+    if text is None:
+        return []
+    hints = []
+    for match in pattern.finditer(text):
+        ref = match.group(1).strip().strip("'\"")
+        hints.append(ConfigHint(kind=kind, framework=framework, handler_ref=ref, name=ref))
+    return hints
+
+
+def _scan_procfile(path: Path) -> list[ConfigHint]:
+    text = _read(path)
+    if text is None:
+        return []
+    hints = []
+    for proc, command in _PROCFILE_LINE.findall(text):
+        hints.append(ConfigHint(kind=EntrypointKind.MAIN, framework="procfile",
+                                handler_ref=command.strip(), name=proc))
+    return hints
+
+
+def _scan_dockerfile(path: Path) -> list[ConfigHint]:
+    text = _read(path)
+    if text is None:
+        return []
+    hints = []
+    for command in _DOCKER_CMD.findall(text):
+        hints.append(ConfigHint(kind=EntrypointKind.MAIN, framework="docker",
+                                handler_ref=command.strip(), name="cmd"))
+    return hints
+
+
+def bind_handler(handler_ref: str, symbol_id_by_qname: dict[str, int],
+                 module_symbol_ids: dict[str, int]) -> int | None:
+    """Best-effort map a config handler string to an indexed symbol id.
+
+    Handles the common forms:
+      - ``src/app.handler`` / ``app.lambda_handler`` (dotted or path+dot)
+      - ``pkg.mod:app`` (gunicorn/uvicorn colon form)
+      - ``python -m pkg.mod`` / ``node src/server.js`` (process commands)
+    """
+    for qname in _candidate_qnames(handler_ref):
+        if qname in symbol_id_by_qname:
+            return symbol_id_by_qname[qname]
+        if qname in module_symbol_ids:
+            return module_symbol_ids[qname]
+    return None
+
+
+_SRC_PREFIXES = ("src/", "lib/", "app/")
+_CODE_EXTS = (".py", ".js", ".ts", ".mjs", ".cjs", ".rb", ".go")
+
+
+def _candidate_qnames(handler_ref: str) -> list[str]:
+    ref = handler_ref.strip()
+    # process command: take the token that looks like a module/path
+    if " " in ref:
+        tokens = ref.split()
+        if "-m" in tokens:
+            i = tokens.index("-m")
+            if i + 1 < len(tokens):
+                ref = tokens[i + 1]
+        else:
+            ref = next((t for t in tokens[1:] if "/" in t or "." in t), tokens[-1])
+    ref = ref.split(":", 1)[0] if ":" in ref and "/" not in ref.split(":", 1)[1] else ref.replace(":", ".")
+    for prefix in _SRC_PREFIXES:
+        if ref.startswith(prefix):
+            ref = ref[len(prefix):]
+    for ext in _CODE_EXTS:
+        if ref.endswith(ext):
+            ref = ref[: -len(ext)]
+            break
+    dotted = ref.replace("/", ".").strip(".")
+    candidates = [dotted]
+    # a handler like module.function -> also try the bare module
+    if "." in dotted:
+        candidates.append(dotted.rsplit(".", 1)[0])
+    return [c for c in candidates if c]

entrygraph/detect/entrypoints/csharp.py

@@ -0,0 +1,156 @@
+"""C# entrypoint rules: ASP.NET Core MVC/attribute-routed controllers, minimal
+API route registrations, and the language-core ``static Main`` entrypoint.
+
+Controller rules scan ``FileExtraction.symbols`` and their captured attributes
+(stored on ``RawSymbol.decorators`` as raw source text, e.g.
+``[HttpGet("/x")]``). A controller is a type carrying ``[ApiController]`` /
+``[Controller]`` or whose base type name contains ``Controller``. Minimal-API
+routes are recognised from ``MapGet``/``MapPost``/... call references.
+"""
+
+from __future__ import annotations
+
+import re
+
+from entrygraph.detect.entrypoints.base import (
+    EntrypointRule,
+    first_string_arg,
+    register,
+)
+from entrygraph.extract.ir import EntrypointHint, FileExtraction, RawSymbol
+from entrygraph.kinds import EntrypointKind, SymbolKind
+
+# [HttpGet("/x")] / [HttpPost] / ... -> HTTP verb; [Route("...")] -> generic.
+_HTTP_ATTR = re.compile(r"^\[Http(Get|Post|Put|Delete|Patch|Head|Options)\b")
+_ROUTE_ATTR = re.compile(r"^\[Route\b")
+_CONTROLLER_ATTR = re.compile(r"^\[(ApiController|Controller)\b")
+
+_MINIMAL_MAP = {
+    "MapGet": "GET",
+    "MapPost": "POST",
+    "MapPut": "PUT",
+    "MapDelete": "DELETE",
+    "MapPatch": "PATCH",
+}
+
+
+def _type_symbols(x: FileExtraction) -> list[RawSymbol]:
+    return [s for s in x.symbols if s.kind in (SymbolKind.CLASS, SymbolKind.INTERFACE)]
+
+
+def _methods(x: FileExtraction) -> list[RawSymbol]:
+    return [s for s in x.symbols if s.kind is SymbolKind.METHOD]
+
+
+def _is_controller(t: RawSymbol) -> bool:
+    if any(_CONTROLLER_ATTR.match(d) for d in t.decorators):
+        return True
+    return any("Controller" in b for b in t.bases)
+
+
+def _aspnet_controller_routes(x: FileExtraction) -> list[EntrypointHint]:
+    controllers = {t.qualified_name for t in _type_symbols(x) if _is_controller(t)}
+    if not controllers:
+        return []
+    hints: list[EntrypointHint] = []
+    for method in _methods(x):
+        if method.parent_qualified_name not in controllers:
+            continue
+        for decorator in method.decorators:
+            m = _HTTP_ATTR.match(decorator)
+            if m:
+                hints.append(
+                    EntrypointHint(
+                        rule_id="csharp.aspnet.controller-route",
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        handler_qualified_name=method.qualified_name,
+                        route=first_string_arg(decorator) or "",
+                        http_methods=[m.group(1).upper()],
+                        framework="aspnetcore",
+                    )
+                )
+                break
+        else:
+            # No Http* verb attribute; a bare [Route("...")] still exposes it.
+            route_dec = next(
+                (d for d in method.decorators if _ROUTE_ATTR.match(d)), None
+            )
+            if route_dec is not None:
+                hints.append(
+                    EntrypointHint(
+                        rule_id="csharp.aspnet.controller-route",
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        handler_qualified_name=method.qualified_name,
+                        route=first_string_arg(route_dec) or "",
+                        http_methods=["*"],
+                        framework="aspnetcore",
+                    )
+                )
+    return hints
+
+
+def _aspnet_minimal_api(x: FileExtraction) -> list[EntrypointHint]:
+    hints: list[EntrypointHint] = []
+    for ref in x.references:
+        if ref.kind != "call":
+            continue
+        verb = _MINIMAL_MAP.get(ref.callee_name)
+        if verb is None:
+            continue
+        route = first_string_arg(ref.arg_preview or "")
+        hints.append(
+            EntrypointHint(
+                rule_id="csharp.aspnet.minimal-api",
+                kind=EntrypointKind.HTTP_ROUTE,
+                handler_qualified_name=None,  # inline lambda handler
+                route=route or "",
+                http_methods=[verb],
+                framework="aspnetcore",
+            )
+        )
+    return hints
+
+
+def _csharp_main(x: FileExtraction) -> list[EntrypointHint]:
+    hints: list[EntrypointHint] = []
+    for method in _methods(x):
+        if method.name == "Main" and "static" in method.modifiers:
+            hints.append(
+                EntrypointHint(
+                    rule_id="csharp.core.main",
+                    kind=EntrypointKind.MAIN,
+                    handler_qualified_name=method.qualified_name,
+                    name=method.qualified_name,
+                    framework=None,
+                )
+            )
+    return hints
+
+
+register(
+    EntrypointRule(
+        "csharp.aspnet.controller-route",
+        "csharp",
+        "aspnetcore",
+        EntrypointKind.HTTP_ROUTE,
+        _aspnet_controller_routes,
+    )
+)
+register(
+    EntrypointRule(
+        "csharp.aspnet.minimal-api",
+        "csharp",
+        "aspnetcore",
+        EntrypointKind.HTTP_ROUTE,
+        _aspnet_minimal_api,
+    )
+)
+register(
+    EntrypointRule(
+        "csharp.core.main",
+        "csharp",
+        None,
+        EntrypointKind.MAIN,
+        _csharp_main,
+    )
+)

entrygraph/detect/entrypoints/golang.py

@@ -0,0 +1,158 @@
+"""Go entrypoint rules: the package-main entrypoint, net/http handler
+registration, gin router routes, and cobra CLI commands."""
+
+from __future__ import annotations
+
+from entrygraph.detect.entrypoints.base import (
+    EntrypointRule,
+    first_string_arg,
+    register,
+)
+from entrygraph.extract.ir import EntrypointHint, FileExtraction
+from entrygraph.kinds import EntrypointKind, SymbolKind
+
+_GIN_METHODS = frozenset(
+    {"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "Any", "Handle"}
+)
+_NETHTTP_REGISTER = frozenset({"HandleFunc", "Handle"})
+
+
+def _go_main(x: FileExtraction) -> list[EntrypointHint]:
+    hints = []
+    for symbol in x.symbols:
+        if (
+            symbol.kind is SymbolKind.FUNCTION
+            and symbol.name == "main"
+            and symbol.parent_qualified_name is None
+        ):
+            hints.append(
+                EntrypointHint(
+                    rule_id="go.core.main",
+                    kind=EntrypointKind.MAIN,
+                    handler_qualified_name=symbol.qualified_name,
+                    name=symbol.qualified_name,
+                    span=symbol.span,
+                )
+            )
+    return hints
+
+
+def _nethttp_routes(x: FileExtraction) -> list[EntrypointHint]:
+    hints = []
+    for ref in x.references:
+        if (
+            ref.kind == "call"
+            and ref.receiver_text == "http"
+            and ref.callee_name in _NETHTTP_REGISTER
+            and ref.arg_preview
+        ):
+            route = first_string_arg("(" + ref.arg_preview.lstrip("("))
+            if route is not None:
+                hints.append(
+                    EntrypointHint(
+                        rule_id="go.nethttp.route",
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        handler_qualified_name=ref.caller_qualified_name,
+                        route=route,
+                        http_methods=["*"],
+                        framework="net/http",
+                        metadata={"registration": ref.arg_preview},
+                    )
+                )
+    return hints
+
+
+def _gin_routes(x: FileExtraction) -> list[EntrypointHint]:
+    hints = []
+    for ref in x.references:
+        if (
+            ref.kind == "call"
+            and ref.receiver_text is not None
+            and ref.callee_name in _GIN_METHODS
+            and ref.arg_preview
+        ):
+            route = first_string_arg("(" + ref.arg_preview.lstrip("("))
+            if route is not None and route.startswith("/"):
+                method = ref.callee_name.upper() if ref.callee_name in {
+                    "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"
+                } else "*"
+                hints.append(
+                    EntrypointHint(
+                        rule_id="go.gin.route",
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        handler_qualified_name=ref.caller_qualified_name,
+                        route=route,
+                        http_methods=[method],
+                        framework="gin",
+                        metadata={"registration": ref.arg_preview},
+                    )
+                )
+    return hints
+
+
+def _gin_style(framework: str):
+    """chi and fiber share gin's r.Get('/x', handler) registration shape."""
+
+    def matcher(x: FileExtraction) -> list[EntrypointHint]:
+        hints = []
+        for hint in _gin_routes(x):
+            hints.append(EntrypointHint(
+                rule_id=f"go.{framework}.route", kind=hint.kind,
+                handler_qualified_name=hint.handler_qualified_name, route=hint.route,
+                http_methods=hint.http_methods, framework=framework, metadata=hint.metadata))
+        return hints
+
+    return matcher
+
+
+def _gorilla_routes(x: FileExtraction) -> list[EntrypointHint]:
+    """gorilla/mux: r.HandleFunc('/x', handler)."""
+    hints = []
+    for ref in x.references:
+        if (
+            ref.kind == "call"
+            and ref.callee_name in ("HandleFunc", "Handle")
+            and ref.receiver_text not in (None, "http")
+            and ref.arg_preview
+        ):
+            route = first_string_arg("(" + ref.arg_preview.lstrip("("))
+            if route is not None and route.startswith("/"):
+                hints.append(EntrypointHint(
+                    rule_id="go.gorilla-mux.route", kind=EntrypointKind.HTTP_ROUTE,
+                    handler_qualified_name=ref.caller_qualified_name, route=route,
+                    http_methods=["*"], framework="gorilla-mux",
+                    metadata={"registration": ref.arg_preview}))
+    return hints
+
+
+def _cobra_commands(x: FileExtraction) -> list[EntrypointHint]:
+    hints = []
+    for ref in x.references:
+        if ref.kind == "composite" and ref.callee_text == "cobra.Command":
+            hints.append(
+                EntrypointHint(
+                    rule_id="go.cobra.command",
+                    kind=EntrypointKind.CLI_COMMAND,
+                    handler_qualified_name=ref.caller_qualified_name,
+                    name=first_string_arg("(" + (ref.arg_preview or "") + ")") or None,
+                    framework="cobra",
+                    span=ref.span,
+                )
+            )
+    return hints
+
+
+register(EntrypointRule("go.core.main", "go", None,
+                        EntrypointKind.MAIN, _go_main))
+register(EntrypointRule("go.nethttp.route", "go", "net/http",
+                        EntrypointKind.HTTP_ROUTE, _nethttp_routes))
+register(EntrypointRule("go.gin.route", "go", "gin",
+                        EntrypointKind.HTTP_ROUTE, _gin_routes))
+register(EntrypointRule("go.chi.route", "go", "chi",
+                        EntrypointKind.HTTP_ROUTE, _gin_style("chi")))
+register(EntrypointRule("go.fiber.route", "go", "fiber",
+                        EntrypointKind.HTTP_ROUTE, _gin_style("fiber")))
+register(EntrypointRule("go.gorilla-mux.route", "go", "gorilla-mux",
+                        EntrypointKind.HTTP_ROUTE, _gorilla_routes))
+register(EntrypointRule("go.cobra.command", "go", "cobra",
+                        EntrypointKind.CLI_COMMAND, _cobra_commands))