entrygraph 0.1.0__py3-none-any.whl

entrygraph/detect/entrypoints/java.py

@@ -0,0 +1,187 @@
+"""Java entrypoint rules: Spring MVC routes, JAX-RS resources, and the
+language-core ``public static void main`` entrypoint.
+
+Rules scan ``FileExtraction.symbols`` and their captured annotations (stored on
+``RawSymbol.decorators`` as raw source text, e.g. ``@GetMapping("/users")``).
+A Spring route requires the enclosing type to carry ``@RestController`` or
+``@Controller``; a JAX-RS resource requires a class-level ``@Path``.
+"""
+
+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
+
+# @GetMapping / @PostMapping / ... -> HTTP verb; @RequestMapping -> generic.
+_SPRING_MAPPING = re.compile(
+    r"^@(Get|Post|Put|Delete|Patch|Request)Mapping\b"
+)
+_MAPPING_VERB = {
+    "Get": "GET", "Post": "POST", "Put": "PUT", "Delete": "DELETE", "Patch": "PATCH",
+}
+_SPRING_CONTROLLER = re.compile(r"^@(RestController|Controller)\b")
+
+_JAXRS_HTTP = re.compile(r"^@(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b")
+_JAXRS_PATH = re.compile(r"^@Path\b")
+
+
+def _annotation_names(decorators: list[str], pattern: re.Pattern) -> bool:
+    return any(pattern.match(d) for d in decorators)
+
+
+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 _enclosing_type(method: RawSymbol, types: list[RawSymbol]) -> RawSymbol | None:
+    return next((t for t in types if t.qualified_name == method.parent_qualified_name), None)
+
+
+def _spring_routes(x: FileExtraction) -> list[EntrypointHint]:
+    types = _type_symbols(x)
+    controllers = {
+        t.qualified_name for t in types
+        if _annotation_names(t.decorators, _SPRING_CONTROLLER)
+    }
+    if not controllers:
+        return []
+    hints = []
+    for method in _methods(x):
+        if method.parent_qualified_name not in controllers:
+            continue
+        for decorator in method.decorators:
+            match = _SPRING_MAPPING.match(decorator)
+            if not match:
+                continue
+            verb = _MAPPING_VERB.get(match.group(1))
+            methods = [verb] if verb else ["*"]
+            hints.append(
+                EntrypointHint(
+                    rule_id="java.spring.route",
+                    kind=EntrypointKind.HTTP_ROUTE,
+                    handler_qualified_name=method.qualified_name,
+                    route=first_string_arg(decorator) or "",
+                    http_methods=methods,
+                    framework="spring-boot",
+                )
+            )
+    return hints
+
+
+def _jaxrs_routes(x: FileExtraction) -> list[EntrypointHint]:
+    types = _type_symbols(x)
+    resources = {
+        t.qualified_name for t in types if _annotation_names(t.decorators, _JAXRS_PATH)
+    }
+    if not resources:
+        return []
+    hints = []
+    for method in _methods(x):
+        if method.parent_qualified_name not in resources:
+            continue
+        verb = next(
+            (_JAXRS_HTTP.match(d).group(1) for d in method.decorators if _JAXRS_HTTP.match(d)),
+            None,
+        )
+        if verb is None:
+            continue
+        route = next((first_string_arg(d) for d in method.decorators
+                      if _JAXRS_PATH.match(d)), None)
+        hints.append(
+            EntrypointHint(
+                rule_id="java.jaxrs",
+                kind=EntrypointKind.HTTP_ROUTE,
+                handler_qualified_name=method.qualified_name,
+                route=route or "",
+                http_methods=[verb],
+                framework="jax-rs",
+            )
+        )
+    return hints
+
+
+_MICRONAUT_CONTROLLER = re.compile(r"^@Controller\b")
+_MICRONAUT_MAPPING = re.compile(r"^@(Get|Post|Put|Delete|Patch)\b")
+_SERVLET_METHODS = frozenset({"doGet", "doPost", "doPut", "doDelete"})
+
+
+def _micronaut_routes(x: FileExtraction) -> list[EntrypointHint]:
+    types = _type_symbols(x)
+    controllers = {t.qualified_name for t in types
+                   if _annotation_names(t.decorators, _MICRONAUT_CONTROLLER)}
+    if not controllers:
+        return []
+    hints = []
+    for method in _methods(x):
+        if method.parent_qualified_name not in controllers:
+            continue
+        for decorator in method.decorators:
+            m = _MICRONAUT_MAPPING.match(decorator)
+            if m:
+                hints.append(EntrypointHint(
+                    rule_id="java.micronaut.route", kind=EntrypointKind.HTTP_ROUTE,
+                    handler_qualified_name=method.qualified_name,
+                    route=first_string_arg(decorator) or "",
+                    http_methods=[m.group(1).upper()], framework="micronaut"))
+    return hints
+
+
+def _servlet_routes(x: FileExtraction) -> list[EntrypointHint]:
+    """Classes extending HttpServlet expose doGet/doPost/... as HTTP handlers."""
+    servlets = {t.qualified_name for t in _type_symbols(x)
+                if any("HttpServlet" in b for b in t.bases)}
+    if not servlets:
+        return []
+    hints = []
+    for method in _methods(x):
+        if method.parent_qualified_name in servlets and method.name in _SERVLET_METHODS:
+            hints.append(EntrypointHint(
+                rule_id="java.servlet.route", kind=EntrypointKind.HTTP_ROUTE,
+                handler_qualified_name=method.qualified_name, route="",
+                http_methods=[method.name.replace("do", "").upper()], framework="servlet-api"))
+    return hints
+
+
+def _java_main(x: FileExtraction) -> list[EntrypointHint]:
+    hints = []
+    for method in _methods(x):
+        if (
+            method.name == "main"
+            and "static" in method.modifiers
+            and "public" in method.modifiers
+            and method.signature
+            and "String[]" in method.signature
+        ):
+            hints.append(
+                EntrypointHint(
+                    rule_id="java.core.main",
+                    kind=EntrypointKind.MAIN,
+                    handler_qualified_name=method.qualified_name,
+                    name=method.qualified_name,
+                    framework=None,
+                )
+            )
+    return hints
+
+
+register(EntrypointRule("java.spring.route", "java", "spring-boot",
+                        EntrypointKind.HTTP_ROUTE, _spring_routes))
+register(EntrypointRule("java.jaxrs", "java", "jax-rs",
+                        EntrypointKind.HTTP_ROUTE, _jaxrs_routes))
+register(EntrypointRule("java.micronaut.route", "java", "micronaut",
+                        EntrypointKind.HTTP_ROUTE, _micronaut_routes))
+register(EntrypointRule("java.servlet.route", "java", "servlet-api",
+                        EntrypointKind.HTTP_ROUTE, _servlet_routes))
+register(EntrypointRule("java.core.main", "java", None,
+                        EntrypointKind.MAIN, _java_main))

entrygraph/detect/entrypoints/javascript.py

@@ -0,0 +1,211 @@
+"""JavaScript/TypeScript entrypoint rules: express/fastify routes, NestJS
+decorators, and Next.js file-convention handlers."""
+
+from __future__ import annotations
+
+import re
+
+from entrygraph.detect.entrypoints.base import EntrypointRule, first_string_arg, register
+from entrygraph.extract.ir import EntrypointHint, FileExtraction
+from entrygraph.kinds import EntrypointKind, SymbolKind
+
+_HTTP_METHODS = frozenset({"get", "post", "put", "delete", "patch", "all", "options", "head"})
+_NEST_DECORATOR = re.compile(r"^@(Get|Post|Put|Delete|Patch|All)\b")
+
+
+_TRAILING_IDENT = re.compile(r",\s*([A-Za-z_$][\w$]*)\s*\)?\s*$")
+
+
+def _router_routes(framework: str):
+    """Factory for app.get('/x', handler) / router.post(...) style matchers.
+
+    express, koa, and hono all register routes this way; the framework label is
+    bound per rule so detection stays accurate.
+    """
+
+    def matcher(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 _HTTP_METHODS
+                and ref.arg_preview
+            ):
+                route = first_string_arg("(" + ref.arg_preview.lstrip("("))
+                if route is None or not route.startswith("/"):
+                    continue
+                # link a named handler argument (app.post('/x', createReport)); an
+                # inline function falls back to the enclosing scope / module.
+                handler = ref.caller_qualified_name
+                named = _TRAILING_IDENT.search(ref.arg_preview)
+                if named:
+                    handler = f"{x.module_path}.{named.group(1)}"
+                hints.append(
+                    EntrypointHint(
+                        rule_id=f"javascript.{framework}.route",
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        handler_qualified_name=handler,
+                        route=route,
+                        http_methods=[ref.callee_name.upper()],
+                        framework=framework,
+                    )
+                )
+        return hints
+
+    return matcher
+
+
+_express_routes = _router_routes("express")
+
+
+def _event_handlers(x: FileExtraction, receivers: frozenset[str], framework: str) -> list[EntrypointHint]:
+    """socket.io / electron style `emitter.on('event', handler)` registrations."""
+    hints = []
+    for ref in x.references:
+        if (
+            ref.kind == "call"
+            and ref.callee_name in ("on", "handle")
+            and ref.receiver_text in receivers
+            and ref.arg_preview
+        ):
+            hints.append(
+                EntrypointHint(
+                    rule_id=f"javascript.{framework}.event",
+                    kind=EntrypointKind.EVENT_HANDLER,
+                    handler_qualified_name=ref.caller_qualified_name,
+                    name=first_string_arg("(" + ref.arg_preview.lstrip("(")),
+                    framework=framework,
+                )
+            )
+    return hints
+
+
+def _socketio_events(x: FileExtraction) -> list[EntrypointHint]:
+    return _event_handlers(x, frozenset({"io", "socket"}), "socket.io")
+
+
+def _electron_ipc(x: FileExtraction) -> list[EntrypointHint]:
+    return _event_handlers(x, frozenset({"ipcMain"}), "electron")
+
+
+def _lambda_js_handlers(x: FileExtraction) -> list[EntrypointHint]:
+    """An exported `handler` function is the AWS Lambda entrypoint convention."""
+    hints = []
+    for symbol in x.symbols:
+        if (
+            symbol.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD)
+            and symbol.name == "handler"
+            and symbol.is_exported
+        ):
+            hints.append(
+                EntrypointHint(
+                    rule_id="javascript.aws-lambda.handler",
+                    kind=EntrypointKind.LAMBDA_HANDLER,
+                    handler_qualified_name=symbol.qualified_name,
+                    name=symbol.name,
+                    framework="aws-lambda-js",
+                )
+            )
+    return hints
+
+
+def _express_middleware(x: FileExtraction) -> list[EntrypointHint]:
+    """app.use(mw) / router.use('/path', mw) -> middleware registration."""
+    hints = []
+    for ref in x.references:
+        if (
+            ref.kind == "call"
+            and ref.callee_name == "use"
+            and ref.receiver_text in ("app", "router")
+        ):
+            hints.append(
+                EntrypointHint(
+                    rule_id="javascript.express.middleware",
+                    kind=EntrypointKind.MIDDLEWARE,
+                    handler_qualified_name=ref.caller_qualified_name,
+                    name="use",
+                    framework="express",
+                    metadata={"registration": ref.arg_preview} if ref.arg_preview else {},
+                )
+            )
+    return hints
+
+
+_NEST_CONTROLLER = re.compile(r"^@Controller\b")
+
+
+def _nest_routes(x: FileExtraction) -> list[EntrypointHint]:
+    # controller class qname -> its @Controller('prefix') path prefix
+    prefixes: dict[str, str] = {}
+    for symbol in x.symbols:
+        if symbol.kind is SymbolKind.CLASS:
+            for decorator in symbol.decorators:
+                if _NEST_CONTROLLER.match(decorator):
+                    prefixes[symbol.qualified_name] = (first_string_arg(decorator) or "").strip("/")
+    hints = []
+    for symbol in x.symbols:
+        if symbol.kind is not SymbolKind.METHOD:
+            continue
+        for decorator in symbol.decorators:
+            m = _NEST_DECORATOR.match(decorator)
+            if m:
+                prefix = prefixes.get(symbol.parent_qualified_name or "", "")
+                path = (first_string_arg(decorator) or "").strip("/")
+                route = "/" + "/".join(p for p in (prefix, path) if p)
+                hints.append(
+                    EntrypointHint(
+                        rule_id="javascript.nestjs.route",
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        handler_qualified_name=symbol.qualified_name,
+                        route=route,
+                        http_methods=[m.group(1).upper()],
+                        framework="nestjs",
+                    )
+                )
+    return hints
+
+
+def _next_handlers(x: FileExtraction) -> list[EntrypointHint]:
+    """Next.js app-router route handlers: exported GET/POST in app/**/route.{ts,js}."""
+    if not (x.path.endswith(("route.ts", "route.js")) and "/app/" in f"/{x.path}"):
+        return []
+    hints = []
+    for symbol in x.symbols:
+        if symbol.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD) and symbol.name in _HTTP_METHODS_UPPER:
+            hints.append(
+                EntrypointHint(
+                    rule_id="javascript.next.route",
+                    kind=EntrypointKind.HTTP_ROUTE,
+                    handler_qualified_name=symbol.qualified_name,
+                    route="/" + x.path.split("/app/", 1)[1].rsplit("/", 1)[0],
+                    http_methods=[symbol.name],
+                    framework="next",
+                )
+            )
+    return hints
+
+
+_HTTP_METHODS_UPPER = frozenset(m.upper() for m in _HTTP_METHODS)
+
+
+register(EntrypointRule("javascript.express.route", "javascript", "express",
+                        EntrypointKind.HTTP_ROUTE, _express_routes))
+register(EntrypointRule("javascript.express.middleware", "javascript", "express",
+                        EntrypointKind.MIDDLEWARE, _express_middleware))
+register(EntrypointRule("javascript.fastify.route", "javascript", "fastify",
+                        EntrypointKind.HTTP_ROUTE, _router_routes("fastify")))
+register(EntrypointRule("javascript.koa.route", "javascript", "koa",
+                        EntrypointKind.HTTP_ROUTE, _router_routes("koa")))
+register(EntrypointRule("javascript.hono.route", "javascript", "hono",
+                        EntrypointKind.HTTP_ROUTE, _router_routes("hono")))
+register(EntrypointRule("javascript.socketio.event", "javascript", "socket.io",
+                        EntrypointKind.EVENT_HANDLER, _socketio_events))
+register(EntrypointRule("javascript.electron.ipc", "javascript", "electron",
+                        EntrypointKind.EVENT_HANDLER, _electron_ipc))
+register(EntrypointRule("javascript.aws-lambda.handler", "javascript", "aws-lambda-js",
+                        EntrypointKind.LAMBDA_HANDLER, _lambda_js_handlers))
+register(EntrypointRule("javascript.nestjs.route", "javascript", "nestjs",
+                        EntrypointKind.HTTP_ROUTE, _nest_routes))
+register(EntrypointRule("javascript.next.route", "javascript", "next",
+                        EntrypointKind.HTTP_ROUTE, _next_handlers))

entrygraph/detect/entrypoints/php.py

@@ -0,0 +1,133 @@
+"""PHP entrypoint rules: Laravel routes, Symfony route attributes, WordPress
+hooks, and the language-core namespace-less script entrypoint.
+
+Laravel route DSLs are ``Route::get('/x', ...)`` scoped calls — extracted as
+call references with ``receiver_text == "Route"`` — so those rules match against
+references rather than symbol decorators (like the Ruby route rules). Symfony
+uses PHP 8 ``#[Route('/x')]`` attributes, which the extractor emits as symbol
+decorators (like Java annotations), so that rule matches decorators.
+"""
+
+from __future__ import annotations
+
+import re
+
+from entrygraph.detect.entrypoints.base import (
+    EntrypointRule,
+    first_string_arg,
+    register,
+)
+from entrygraph.extract.ir import EntrypointHint, FileExtraction
+from entrygraph.kinds import EntrypointKind, SymbolKind
+
+_LARAVEL_VERBS = frozenset(
+    {"get", "post", "put", "delete", "patch", "any", "match"}
+)
+_SYMFONY_ROUTE = re.compile(r"#\[\s*Route\s*\(")
+_WORDPRESS_HOOKS = frozenset({"add_action", "add_filter"})
+
+
+def _laravel_routes(x: FileExtraction) -> list[EntrypointHint]:
+    if not re.search(r"(^|/)routes/[^/]+\.php$", x.path):
+        return []
+    hints = []
+    for ref in x.references:
+        if (
+            ref.kind == "call"
+            and ref.receiver_text == "Route"
+            and ref.callee_name in _LARAVEL_VERBS
+            and ref.arg_preview
+        ):
+            route = first_string_arg("(" + ref.arg_preview.lstrip("("))
+            hints.append(
+                EntrypointHint(
+                    rule_id="php.laravel.route",
+                    kind=EntrypointKind.HTTP_ROUTE,
+                    handler_qualified_name=None,  # handler resolved as a call edge
+                    route=route if route is not None else "",
+                    http_methods=["*"] if ref.callee_name in ("any", "match")
+                    else [ref.callee_name.upper()],
+                    framework="laravel",
+                    metadata={"registration": ref.arg_preview},
+                )
+            )
+    return hints
+
+
+def _symfony_routes(x: FileExtraction) -> list[EntrypointHint]:
+    hints = []
+    for symbol in x.symbols:
+        if symbol.kind not in (SymbolKind.METHOD, SymbolKind.FUNCTION):
+            continue
+        for decorator in symbol.decorators:
+            if _SYMFONY_ROUTE.search(decorator):
+                hints.append(
+                    EntrypointHint(
+                        rule_id="php.symfony.route",
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        handler_qualified_name=symbol.qualified_name,
+                        route=first_string_arg(decorator) or "",
+                        http_methods=["*"],
+                        framework="symfony",
+                    )
+                )
+    return hints
+
+
+def _wordpress_hooks(x: FileExtraction) -> list[EntrypointHint]:
+    hints = []
+    for ref in x.references:
+        if (
+            ref.kind == "call"
+            and ref.receiver_text is None
+            and ref.callee_name in _WORDPRESS_HOOKS
+            and ref.arg_preview
+        ):
+            hints.append(
+                EntrypointHint(
+                    rule_id="php.wordpress.hook",
+                    kind=EntrypointKind.EVENT_HANDLER,
+                    handler_qualified_name=None,  # callback resolved as call edge
+                    name=first_string_arg("(" + ref.arg_preview.lstrip("(")),
+                    framework="wordpress",
+                    metadata={"registration": ref.arg_preview},
+                )
+            )
+    return hints
+
+
+def _script(x: FileExtraction) -> list[EntrypointHint]:
+    """A namespace-less top-level ``index.php`` with module-level references.
+
+    The extractor sets ``module_path`` to the file's PHP namespace when one is
+    present, otherwise to the directory-derived path (which for ``index.php``
+    ends in ``.index`` or equals ``index``). A namespaced ``index.php`` is a
+    library file, not a script entrypoint, so we require the directory-derived
+    (namespace-less) form. We also require at least one module-level reference
+    (a ``caller_qualified_name is None`` call) so an empty file is not flagged.
+    """
+    if not x.path.endswith("index.php"):
+        return []
+    if not (x.module_path == "index" or x.module_path.endswith(".index")):
+        return []  # namespaced -> not a bare script
+    if not any(ref.caller_qualified_name is None for ref in x.references):
+        return []
+    return [
+        EntrypointHint(
+            rule_id="php.core.script",
+            kind=EntrypointKind.MAIN,
+            handler_qualified_name=None,  # the module itself
+            name=x.module_path,
+            framework=None,
+        )
+    ]
+
+
+register(EntrypointRule("php.laravel.route", "php", "laravel",
+                        EntrypointKind.HTTP_ROUTE, _laravel_routes))
+register(EntrypointRule("php.symfony.route", "php", "symfony",
+                        EntrypointKind.HTTP_ROUTE, _symfony_routes))
+register(EntrypointRule("php.wordpress.hook", "php", "wordpress",
+                        EntrypointKind.EVENT_HANDLER, _wordpress_hooks))
+register(EntrypointRule("php.core.script", "php", None,
+                        EntrypointKind.MAIN, _script))