Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(workspace): read Fastify, hapi and Koa router prefixes and Next.js pages/api routes as HTTP providers (#4558)

Raghav Chamadiya7ae1629455aa
diff --git a/docs/reference/WORKSPACE_CONTRACTS.md b/docs/reference/WORKSPACE_CONTRACTS.md
index 8b3a2b438..3c74983b8 100644
--- a/docs/reference/WORKSPACE_CONTRACTS.md
+++ b/docs/reference/WORKSPACE_CONTRACTS.md
@@ -95,8 +95,11 @@ Data/DB contracts use the id scheme `data::<table>` and render as a `db` edge in
HTTP routes are matched on their **full** path: a router mount prefix
(`APIRouter(prefix=...)`, `include_router(prefix=...)`, Express `app.use('/x', router)`,
-Go route groups, Laravel `Route::prefix(...)->group(...)` and `Route::group(['prefix' => ...])`)
-is stitched onto each handler path before matching. Laravel's `routes/api.php` is
+Go route groups, Laravel `Route::prefix(...)->group(...)` and `Route::group(['prefix' => ...])`,
+Fastify `register(plugin, {prefix})`, Koa `new Router({prefix})` and nested `router.use()`,
+hapi `register({plugin, routes: {prefix}})`) is stitched onto each handler path before matching.
+A Fastify, Koa or hapi prefix that does not resolve to a string, or a plugin mounted at two
+different prefixes, leaves those routes out rather than at a guessed path. Laravel's `routes/api.php` is
served under `/api` unless `bootstrap/app.php` (`apiPrefix`) or a route provider says
otherwise, and `Route::resource` / `apiResource` expand into the routes they register. A NestJS
route is served at the app's `setGlobalPrefix` (unless its `exclude` list names the route), then
diff --git a/docs/scale/WORKSPACES.md b/docs/scale/WORKSPACES.md
index 1bbcc0f37..2fe70fd71 100644
--- a/docs/scale/WORKSPACES.md
+++ b/docs/scale/WORKSPACES.md
@@ -138,7 +138,7 @@ Scans source files for HTTP routes, gRPC services, database tables, message topi
| Language | Providers (routes served) | Consumers (calls made) |
|----------|---------------------------|------------------------|
-| JS / TS | Express, Hono, Fastify, Koa, Elysia; NestJS controllers; Next.js App Router; Remix | `fetch`; axios, ky, got, ofetch and their instances; Angular `HttpClient`; AngularJS `$http`; request, superagent, needle; HTTP-named wrappers |
+| JS / TS | Express, Hono, Fastify, Koa, hapi, Elysia; NestJS controllers; Next.js App Router and `pages/api`; Remix | `fetch`; axios, ky, got, ofetch and their instances; Angular `HttpClient`; AngularJS `$http`; request, superagent, needle; HTTP-named wrappers |
| Python | FastAPI, Flask, Django | requests, httpx (aiohttp through wrappers the index confirms); Locust user `client` calls |
| PHP | Laravel | Guzzle, Laravel `Http` |
| Java / Kotlin | Spring, JAX-RS, Micronaut | Feign (`@RequestLine`, and `@FeignClient` with Spring MVC annotations, its `name` read as the host), Spring `@HttpExchange` interfaces, Spring `WebClient` and `RestClient`, `RestTemplate` (also through a getter or a `RequestEntity`), `java.net.http`, Apache HttpClient (`new HttpPost(url)`, with a base URL passed to a helper's constructor in another file), MicroProfile `@RegisterRestClient` interfaces, Ktor (Kotlin) |
diff --git a/packages/core/src/repowise/core/ingestion/framework_routes.py b/packages/core/src/repowise/core/ingestion/framework_routes.py
index d9d072d24..e7821b862 100644
--- a/packages/core/src/repowise/core/ingestion/framework_routes.py
+++ b/packages/core/src/repowise/core/ingestion/framework_routes.py
@@ -127,16 +127,20 @@ def aspnet_groups(content: str) -> Iterator[GroupMatch]:
# ---------------------------------------------------------------------------
# `use` and `all` are here because the graph consumer scans them for handler
-# functions; the contract consumer drops them via HTTP_METHODS.
-_EXPRESS_VERBS = "get|post|put|delete|patch|options|head|all|use"
+# functions; the contract consumer drops them via HTTP_METHODS. `del` is
+# koa-router's (and Express 3's) DELETE.
+_EXPRESS_VERBS = "get|post|put|delete|del|patch|options|head|all|use"
# router.get('/path', handler). The path literal is optional — `app.use(router)`
# carries none. The lookbehind excludes a word character as well as `@`, which
# neither copy did: `\b` alone admits `@app.get` (a FastAPI/NestJS decorator, not
# an Express route), and `(?<!@)` alone lets the engine restart inside the name
# and match `pp.get` there instead.
+# A TypeScript type argument may sit between the verb and its call
+# (Fastify's `app.get<{Params: P}>('/x', h)`); it holds no parenthesis.
_EXPRESS_ROUTE_RE = re.compile(
- rf"(?<![\w@])(?P<receiver>\w+)\s*\.\s*(?P<verb>{_EXPRESS_VERBS})\s*(?P<paren>\()"
+ rf"(?<![\w@])(?P<receiver>\w+)\s*\.\s*(?P<verb>{_EXPRESS_VERBS})\s*"
+ r"(?:<[^()<>]*(?:<[^()<>]*>[^()<>]*)*>\s*)?(?P<paren>\()"
r"""\s*(?:(?P<q>['"])(?P<path>[^'"]*)(?P=q))?""",
re.IGNORECASE,
)
@@ -155,7 +159,7 @@ _JS_ROUTER_CTORS: tuple[tuple[str, str], ...] = (
# (`services.http.Router()`) still binds, as it did before this table.
("express", r"(?:[\w$.]*\s*\.\s*)?Router\s*\(|express\s*\("),
("hono", r"new\s+Hono\s*[(<]"),
- ("fastify", r"[Ff]astify\s*\("),
+ ("fastify", r"[Ff]astify\s*\(|require\s*\(\s*['\"]fastify['\"]\s*\)\s*\("),
("koa", r"new\s+[Kk]oa\s*\("),
("elysia", r"new\s+Elysia\s*[(<]"),
)
diff --git a/packages/core/src/repowise/core/ingestion/framework_routes_fastify.py b/packages/core/src/repowise/core/ingestion/framework_routes_fastify.py
new file mode 100644
index 000000000..fd948d66b
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/framework_routes_fastify.py
@@ -0,0 +1,230 @@
+"""Fastify routes: ``route({method, url})`` objects and plugin prefixes.
+
+Fastify's shorthand ``app.get('/x', h)`` is the Express call shape and is read
+by ``framework_routes.express_routes``. What Fastify adds is encapsulation: a
+plugin is a function ``(instance, opts) => {...}``, and
+``app.register(plugin, {prefix: '/api'})`` serves every route the plugin
+declares on ``instance`` under ``/api``. Plugins nest, inline or across files.
+
+:func:`fastify_plugins` finds the plugin functions of a file and
+:func:`fastify_registers` the ``register`` calls; the contract consumer joins
+them through the repo-wide mount map. A plugin wrapped in ``fastify-plugin``
+(``fp(...)``) is not encapsulated, so a prefix given to it does not apply.
+Not read: a plugin reached through a bare or aliased import (``@/routes``), a
+spread route table, and ``@fastify/autoload`` directory prefixes.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+from .framework_routes import RouteMatch, match_paren
+from .framework_routes_js import (
+ call_arg_spans,
+ chain_receiver,
+ js_imports,
+ js_object_at,
+ js_object_named,
+ plugin_ref,
+)
+
+# An import or require of Fastify, its types, or a call on a `fastify` instance.
+_FASTIFY_FILE_RE = re.compile(
+ r"""(?:\bfrom\s*|\brequire\s*\(\s*)['"](?:fastify|fastify-plugin|@fastify/[\w.-]+)['"]"""
+ r"""|\bFastify[A-Z]\w*|\bfastify\s*\.\s*(?:get|post|put|delete|patch|route|register)\s*[(<]"""
+)
+
+#: Receivers that hold a Fastify instance where no binding is in scope.
+FASTIFY_DEFAULT_NAMES = frozenset({"app", "router", "fastify", "server"})
+
+# `instance.route({` and `instance.register(`, with an optional TS type argument.
+_TYPE_ARG = r"(?:<[^()<>]*(?:<[^()<>]*>[^()<>]*)*>\s*)?"
+_ROUTE_CALL_RE = re.compile(
+ rf"(?<![\w$@.])(?P<receiver>[\w$]+)\s*\.\s*route\s*{_TYPE_ARG}(?P<paren>\()\s*\{{"
+)
+# `.register(`, its receiver read back along the chain (`app.register(a).register(b)`).
+_REGISTER_RE = re.compile(r"(?P<dot>\.)\s*register\s*(?P<paren>\()")
+
+# A function's head: `function name(p`, `async (p: T, opts) =>`, `p =>`.
+_FUNCTION_RE = re.compile(r"\bfunction\b\s*\*?\s*(?P<name>[\w$]*)\s*\(\s*(?P<param>[\w$]+)")
+# An arrow with a block body, found from its `=>`; the parameters are read
+# back from a bounded window before it, so a long line costs nothing.
+_ARROW_BODY_RE = re.compile(r"=>\s*\{")
+_ARROW_PARAMS_RE = re.compile(
+ r"(?:\(\s*(?P<p1>[\w$]+)\s*(?::[^,()]{0,120})?(?:,[^()]{0,200})?\)|(?<![\w$.])(?P<p2>[\w$]+))"
+ r"\s*(?::\s*[^=;{()\n]{0,120})?$"
+)
+_ARROW_WINDOW = 300
+# What names a function from just before its head.
+_NAMED_BY_RE = re.compile(
+ r"(?:(?:\b(?:const|let|var)\s+(?P<var>[\w$]+)\s*(?::[^=;\n]+)?=)"
+ r"|(?P<default>\bexport\s+default|\bmodule\.exports\s*=)"
+ r"|(?:\b(?:module\.)?exports\.(?P<cjs>[\w$]+)\s*=))"
+ r"\s*(?P<fp>[\w$]+\s*\(\s*)?(?:async\s*)?$"
+)
+_ALIAS_RE = re.compile(
+ r"(?:\bexport\s+default|\bmodule\.exports\s*=)\s*(?:(?P<fp>[\w$]+)\s*\(\s*)?(?P<name>[\w$]+)\s*\)?\s*;?\s*$",
+ re.MULTILINE,
+)
+_FP_WRAPPERS = frozenset({"fp", "fastifyPlugin", "plugin"})
+
+
+def fastify_file(content: str) -> bool:
+ """Whether *content* is Fastify code: imports it, names its types, or calls
+ a ``fastify`` instance."""
+ return _FASTIFY_FILE_RE.search(content) is not None
+
+
+@dataclass(frozen=True)
+class Plugin:
+ """A function a route or ``register`` call may run in."""
+
+ body: int # the `{` opening the body
+ end: int # its `}`
+ param: str # the instance it is handed
+ names: tuple[str, ...] # what the module exports it as (`default` included)
+ fp: bool # wrapped in fastify-plugin: shares its parent's context
+ head: int # where the function expression starts
+
+
+@dataclass(frozen=True)
+class Register:
+ """One ``instance.register(plugin, opts)`` call."""
+
+ receiver: str
+ offset: int
+ #: ``(spec, exported name)``; spec None for the same file. None when the
+ #: plugin argument is an inline function, in :attr:`inline`.
+ target: tuple[str | None, str] | None
+ inline: Plugin | None
+ #: The ``prefix`` option's source text, "" when none is given, None when the
+ #: options are not an object literal this can read.
+ prefix: str | None
+
+
+def _named(content: str, head: int, own: str) -> tuple[list[str], bool]:
+ before = content[max(0, head - 160) : head]
+ m = _NAMED_BY_RE.search(before)
+ names = [own] if own else []
+ fp = False
+ if m is not None:
+ fp = bool(m.group("fp")) and m.group("fp").split("(")[0].strip() in _FP_WRAPPERS
+ if m.group("var"):
+ names.append(m.group("var"))
+ elif m.group("cjs"):
+ names.append(m.group("cjs"))
+ elif m.group("default"):
+ names.append("default")
+ return names, fp
+
+
+def _function_heads(content: str, params: set[str]) -> list[tuple[int, str, str, int]]:
+ """``(head, param, own name, body brace)`` per function taking a param in *params*."""
+ heads: list[tuple[int, str, str, int]] = []
+ for m in _FUNCTION_RE.finditer(content):
+ if m.group("param") not in params:
+ continue
+ paren = content.index("(", m.end("name"))
+ close = match_paren(content, paren)
+ brace = content.find("{", close) if close > 0 else -1
+ if brace > 0:
+ heads.append((m.start(), m.group("param"), m.group("name"), brace))
+ for m in _ARROW_BODY_RE.finditer(content):
+ window_start = max(0, m.start() - _ARROW_WINDOW)
+ p = _ARROW_PARAMS_RE.search(content[window_start : m.start()])
+ param = (p.group("p1") or p.group("p2")) if p else None
+ if p is not None and param in params:
+ heads.append((window_start + p.start(), param, "", m.end() - 1))
+ return heads
+
+
+def fastify_plugins(content: str, params: set[str]) -> list[Plugin]:
+ """The functions of *content* whose instance parameter is in *params*."""
+ aliases: dict[str, bool] = {} # name -> wrapped in fp, for `export default name`
+ for m in _ALIAS_RE.finditer(content):
+ aliases[m.group("name")] = bool(m.group("fp")) and m.group("fp") in _FP_WRAPPERS
+
+ out: list[Plugin] = []
+ for head, param, own, brace in _function_heads(content, params):
+ end = match_paren(content, brace)
+ if end < 0:
+ continue
+ names, fp = _named(content, head, own)
+ for name in list(names):
+ if name in aliases:
+ names.append("default")
+ fp = fp or aliases[name]
+ out.append(Plugin(brace, end, param, tuple(dict.fromkeys(names)), fp, head))
+ return out
+
+
+def register_receivers(content: str) -> set[str]:
+ """The names ``register`` is called on in *content*."""
+ found = (chain_receiver(content, m.start("dot")) for m in _REGISTER_RE.finditer(content))
+ return {name for name in found if name}
+
+
+def fastify_registers(content: str, plugins: list[Plugin]) -> list[Register]:
+ """Every ``register`` call in *content*, its plugin and its prefix."""
+ imports = js_imports(content) if "import" in content or "require" in content else {}
+ out: list[Register] = []
+ for m in _REGISTER_RE.finditer(content):
+ receiver = chain_receiver(content, m.start("dot"))
+ spans = call_arg_spans(content, m.start("paren"))
+ if not receiver or not spans:
+ continue
+ first, first_end = spans[0]
+ # The outermost function in the argument is the plugin itself.
+ inline = min(
+ (p for p in plugins if first <= p.head < first_end), key=lambda p: p.head, default=None
+ )
+ target = None if inline else plugin_ref(content, first, imports)
+ if inline is None and target is None:
+ continue
+ prefix = _prefix_expr(content, spans[1]) if len(spans) > 1 else ""
+ out.append(Register(receiver, m.start(), target, inline, prefix))
+ return out
+
+
+def _prefix_expr(content: str, span: tuple[int, int]) -> str | None:
+ """The ``prefix`` of the options argument at *span* ("" for none)."""
+ text = content[span[0] : span[1]]
+ lead = span[0] + len(text) - len(text.lstrip())
+ if text.strip().startswith("{"):
+ obj = js_object_at(content, lead)
+ else:
+ name = text.strip()
+ obj = js_object_named(content, name) if name.isidentifier() else None
+ if obj is None:
+ return None
+ return obj.expr(content, "prefix") or ""
+
+
+def fastify_route_objects(content: str) -> Iterator[tuple[RouteMatch, str | None]]:
+ """``instance.route({method, url})`` declarations, one row per verb.
+
+ The route's ``path`` is set for a plain literal; otherwise the url's source
+ text comes second, for the caller to resolve against the file's constants.
+ """
+ for m in _ROUTE_CALL_RE.finditer(content):
+ obj = js_object_at(content, m.end() - 1)
+ if obj is None:
+ continue
+ methods = obj.strings(content, "method")
+ key = "url" if "url" in obj.keys else "path"
+ expr = obj.expr(content, key)
+ if not methods or not expr:
+ continue
+ path = obj.string(content, key)
+ for verb in methods:
+ route = RouteMatch(
+ verb=verb.upper(),
+ path=path,
+ receiver=m.group("receiver"),
+ handler=None,
+ offset=m.start(),
+ paren_offset=m.start("paren"),
+ )
+ yield route, None if path is not None else expr
diff --git a/packages/core/src/repowise/core/ingestion/framework_routes_hapi.py b/packages/core/src/repowise/core/ingestion/framework_routes_hapi.py
new file mode 100644
index 000000000..3f9f967f0
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/framework_routes_hapi.py
@@ -0,0 +1,143 @@
+"""hapi routes: ``server.route({method, path, handler})`` and plugin prefixes.
+
+A hapi route is an object literal, passed to ``server.route`` alone or in an
+array, or exported from a module the server file passes in
+(``server.route(require('./routes'))``). An object counts only with a
+``method``, a ``path`` and a handler (``handler``, or one under ``options`` or
+``config``): a Node ``http.request({method, path})`` options object has the
+first two and no handler.
+
+``server.register({plugin: require('./api'), routes: {prefix: '/api'}})``
+serves every route of the plugin's module under ``/api``. :func:`hapi_mounts`
+reads those calls, and the module ``server.route`` pulls routes from, so the
+contract consumer can stitch prefixes across files. A prefix applies per
+module: a module declaring two plugins registered at different prefixes is
+read as one.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+from .framework_routes import RouteMatch
+from .framework_routes_js import (
+ JsObject,
+ call_arg_spans,
+ js_imports,
+ js_object_at,
+ js_objects,
+ plugin_ref,
+)
+
+_HAPI_FILE_RE = re.compile(
+ r"""['"](?:@hapi/hapi|hapi)['"]|\bHapi\s*\.\s*[Ss]erver\s*\(|(?<![\w$.])server\s*\.\s*route\s*\("""
+)
+_HANDLER_HOLDERS = ("options", "config")
+
+_CALL_RE = re.compile(r"(?<![\w$@.])(?P<receiver>[\w$]+)\s*\.\s*(?P<call>register|route)\s*(?P<paren>\()")
+
+
+def hapi_file(content: str) -> bool:
+ """Whether *content* imports hapi, builds a server, or calls ``server.route``."""
+ return _HAPI_FILE_RE.search(content) is not None
+
+
+def _has_handler(content: str, obj: JsObject) -> bool:
+ if "handler" in obj.keys:
+ return True
+ held = any(k in obj.keys for k in _HANDLER_HOLDERS)
+ return held and "handler" in content[obj.open : obj.close]
+
+
+def hapi_routes(content: str) -> Iterator[tuple[RouteMatch, str | None]]:
+ """Every route object in *content*, one row per verb (``*`` kept as is).
+
+ The route's ``path`` is set for a plain literal; otherwise its source text
+ comes second, for the caller to resolve against the file's constants.
+ """
+ for obj in sorted(js_objects(content), key=lambda o: o.open):
+ if "method" not in obj.keys or "path" not in obj.keys:
+ continue
+ methods = obj.strings(content, "method")
+ expr = obj.expr(content, "path")
+ if not methods or not expr or not _has_handler(content, obj):
+ continue
+ path = obj.string(content, "path")
+ for verb in methods:
+ route = RouteMatch(
+ verb=verb.upper(),
+ path=path,
+ receiver=None,
+ handler=None,
+ offset=obj.open,
+ paren_offset=obj.open,
+ )
+ yield route, None if path is not None else expr
+
+
+@dataclass(frozen=True)
+class HapiMount:
+ """A module another file serves routes from, and the prefix it gives them."""
+
+ offset: int
+ #: ``(spec, exported name)``; spec None for a name declared in the file.
+ target: tuple[str | None, str]
+ #: The ``prefix`` option's source text, "" when none is given, None when
+ #: the plugin object and the call's options both give one.
+ prefix: str | None
+
+
+def _routes_prefix(content: str, obj: JsObject | None) -> str:
+ """``routes: {prefix}`` of a register options object."""
+ if obj is None or "routes" not in obj.keys:
+ return ""
+ inner = js_object_at(content, obj.keys["routes"][0] + _lead(content, obj.keys["routes"]))
+ return (inner.expr(content, "prefix") or "") if inner is not None else ""
+
+
+def _lead(content: str, span: tuple[int, int]) -> int:
+ text = content[span[0] : span[1]]
+ return len(text) - len(text.lstrip())
+
+
+def _plugin_objects(
+ content: str, span: tuple[int, int], imports: dict[str, tuple[str, str]], call_prefix: str
+) -> Iterator[HapiMount]:
+ """``{plugin, routes: {prefix}}`` objects in *span*, alone or in a list."""
+ for obj in js_objects(content, span[0], span[1]):
+ target = plugin_ref(content, obj.keys["plugin"][0], imports) if "plugin" in obj.keys else None
+ if target is None:
+ continue
+ own = _routes_prefix(content, obj)
+ # A prefix on the plugin object and another on the call: unreadable.
+ prefix = None if own and call_prefix else own or call_prefix
+ yield HapiMount(obj.open, target, prefix)
+
+
+def hapi_mounts(content: str) -> Iterator[HapiMount]:
+ """``register`` plugins and ``route`` modules named in *content*."""
+ imports = js_imports(content)
+ for m in _CALL_RE.finditer(content):
+ spans = call_arg_spans(content, m.start("paren"))
+ if not spans:
+ continue
+ first, first_end = spans[0]
+ options = None
+ if len(spans) > 1:
+ options = js_object_at(content, spans[1][0] + _lead(content, spans[1]))
+ call_prefix = _routes_prefix(content, options)
+ if m.group("call") == "route":
+ # `server.route(require('./routes'))`, or a route-table factory
+ # `server.route(Routes(server))`.
+ target = plugin_ref(content, first, imports, calls=True)
+ if target is not None:
+ yield HapiMount(m.start(), target, "")
+ continue
+ if content[first:first_end].lstrip()[:1] in "{[":
+ yield from _plugin_objects(content, (first, first_end), imports, call_prefix)
+ continue
+ target = plugin_ref(content, first, imports)
+ if target is not None:
+ yield HapiMount(m.start(), target, call_prefix)
diff --git a/packages/core/src/repowise/core/ingestion/framework_routes_js.py b/packages/core/src/repowise/core/ingestion/framework_routes_js.py
new file mode 100644
index 000000000..44e2f9952
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/framework_routes_js.py
@@ -0,0 +1,285 @@
+"""Pieces the Node route frameworks outside the Express call shape share.
+
+Fastify's ``route({method, url})`` and hapi's ``server.route({method, path})``
+declare a route as an object literal, and both mount a plugin from another
+module with a prefix (``register(plugin, {prefix})``). This module reads those
+object literals, the relative module a plugin reference names, and the
+module keys a file answers to; each framework's own rules stay in its module.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from .framework_routes import match_paren, scan_code
+
+#: Extensions a relative import may omit, longest first so `.d.ts` style
+#: suffixes never shadow a shorter one.
+_JS_EXTS = (".tsx", ".jsx", ".mjs", ".cjs", ".ts", ".js")
+
+# A key opening an object entry: `method:`, `'method':`, `"url":`.
+_KEY_RE = re.compile(r"""\s*(?:(?P<q>['"])(?P<qkey>[\w$]+)(?P=q)|(?P<key>[\w$]+))\s*:(?!:)""")
+_STR_RE = re.compile(r"""\s*(?P<q>['"`])(?P<text>[^'"`]*)(?P=q)""")
+_STR_LIST_RE = re.compile(r"""\s*\[(?P<items>(?:\s*['"`]\w+['"`]\s*,?)+)\s*\]""")
+_LIST_ITEM_RE = re.compile(r"""['"`](\w+)['"`]""")
+
+# `require('./x')`, `require('./x').routes`, `import('./x')`, or a name.
+_REF_RE = re.compile(
+ r"""\s*(?:(?:await\s+)?(?:require|import)\s*\(\s*['"](?P<spec>[^'"]+)['"]\s*\)"""
+ r"""(?:\s*\.\s*(?P<member>[\w$]+))?|(?P<name>[\w$]+)(?![\w$]*\s*[(.]))"""
+)
+
+_CALL_REF_RE = re.compile(r"\s*(?P<name>[\w$]+)\s*\(")
+
+_IMPORT_RE = re.compile(
+ r"""\bimport\s+(?:type\s+)?(?P<clause>[\w$\s,{}]+?)\s+from\s+['"](?P<spec>[^'"]+)['"]"""
+)
+_REQUIRE_RE = re.compile(
+ r"""\b(?:const|let|var)\s+(?P<lhs>[\w$]+|\{[^}]*\})\s*=\s*require\s*\(\s*['"](?P<spec>[^'"]+)['"]\s*\)"""
+ r"""(?:\s*\.\s*(?P<member>[\w$]+))?"""
+)
+_AS_RE = re.compile(r"^(?P<name>[\w$]+)(?:\s+as\s+(?P<alias>[\w$]+)|\s*:\s*(?P<rename>[\w$]+))?$")
+
+
+@dataclass
+class JsObject:
+ """One object literal: where it opens and closes, and its top-level keys."""
+
+ open: int
+ close: int
+ #: key -> ``(start, end)`` of its value
+ keys: dict[str, tuple[int, int]] = field(default_factory=dict)
+
+ def expr(self, content: str, key: str) -> str | None:
+ """The source text of *key*'s value, None when absent."""
+ span = self.keys.get(key)
+ return content[span[0] : span[1]].strip() if span is not None else None
+
+ def string(self, content: str, key: str) -> str | None:
+ """The string literal *key* holds, None when absent or not a plain literal."""
+ span = self.keys.get(key)
+ m = _STR_RE.match(content, span[0]) if span is not None else None
+ if m is None or "${" in m.group("text"):
+ return None
+ return m.group("text")
+
+ def strings(self, content: str, key: str) -> tuple[str, ...] | None:
+ """A string or a list of strings *key* holds, None when unreadable."""
+ one = self.string(content, key)
+ if one is not None:
+ return (one,)
+ span = self.keys.get(key)
+ m = _STR_LIST_RE.match(content, span[0]) if span is not None else None
+ return tuple(_LIST_ITEM_RE.findall(m.group("items"))) if m else None
+
+
+@dataclass
+class _Open:
+ obj: JsObject | None # None for `(` and `[`
+ key: str | None = None # the key whose value is being read
+ value: int = 0
+
+
+def js_objects(content: str, start: int = 0, end: int | None = None) -> Iterator[JsObject]:
+ """Every object literal opened in ``content[start:end]``, innermost first.
+
+ One pass over the code (strings and comments skipped), with a stack of the
+ open brackets, so the cost is linear in the span however deep it nests.
+ """
+ end = len(content) if end is None else end
+ stack: list[_Open] = []
+ for i, c, _depth in scan_code(content, start):
+ if i >= end:
+ break
+ top = stack[-1] if stack else None
+ if c in ",}" and top is not None and top.obj is not None and top.key is not None:
+ top.obj.keys[top.key] = (top.value, i)
+ top.key = None
+ if c in "([":
+ stack.append(_Open(None))
+ elif c == "{":
+ stack.append(_Open(JsObject(open=i, close=-1)))
+ elif c in ")]}":
+ if stack:
+ closed = stack.pop().obj
+ if closed is not None:
+ closed.close = i
+ yield closed
+ continue
+ top = stack[-1] if stack else None
+ if c in "{," and top is not None and top.obj is not None:
+ m = _KEY_RE.match(content, i + 1)
+ if m is not None:
+ top.key, top.value = m.group("key") or m.group("qkey"), m.end()
+
+
+def js_object_at(content: str, brace: int) -> JsObject | None:
+ """The object literal opened by the ``{`` at *brace*, None for another character."""
+ if content[brace : brace + 1] != "{":
+ return None
+ close = match_paren(content, brace)
+ if close < 0:
+ return None
+ last = None
+ for obj in js_objects(content, brace, close + 1):
+ last = obj
+ return last if last is not None and last.open == brace else None
+
+
+def js_object_named(content: str, name: str) -> JsObject | None:
+ """The object literal ``const <name> = {...}`` binds in *content*."""
+ m = re.search(rf"\b(?:const|let|var)\s+{re.escape(name)}\s*(?::[^=;\n]+)?=\s*\{{", content)
+ return js_object_at(content, m.end() - 1) if m else None
+
+
+def call_arg_spans(content: str, paren: int) -> list[tuple[int, int]] | None:
+ """``(start, end)`` of each top-level argument of the call opened at *paren*."""
+ close = match_paren(content, paren)
+ if close < 0:
+ return None
+ spans: list[tuple[int, int]] = []
+ nest, at = 0, paren + 1
+ for i, c, _depth in scan_code(content, paren + 1):
+ if i >= close:
+ break
+ if c in "([{":
+ nest += 1
+ elif c in ")]}":
+ nest -= 1
+ elif c == "," and nest == 0:
+ spans.append((at, i))
+ at = i + 1
+ if content[at:close].strip():
+ spans.append((at, close))
+ return spans
+
+
+def chain_receiver(content: str, dot: int) -> str | None:
+ """The name a call chain ending at the ``.`` at *dot* starts from.
+
+ In ``app.register(a).register(b)`` it gives ``app`` for the second call.
+ Parentheses are matched backwards without reading strings, which is enough
+ for the argument lists of a registration chain.
+ """
+ i = _back_over_space(content, dot - 1)
+ for _ in range(64):
+ if i < 0:
+ return None
+ if content[i] == ")":
+ i = _back_over_space(content, _open_paren_before(content, i) - 1)
+ continue
+ m = _NAME_AT_END_RE.search(content, max(0, i - 128), i + 1)
+ if m is None:
+ return None
+ before = _back_over_space(content, m.start() - 1)
+ if before < 0 or content[before] != ".":
+ return m.group()
+ i = _back_over_space(content, before - 1)
+ return None
+
+
+_NAME_AT_END_RE = re.compile(r"[\w$]+$")
+
+
+def _back_over_space(content: str, i: int) -> int:
+ while i >= 0 and content[i].isspace():
+ i -= 1
+ return i
+
+
+def _open_paren_before(content: str, close: int) -> int:
+ """Index of the ``(`` the ``)`` at *close* closes, or -1."""
+ depth = 0
+ for i in range(close, -1, -1):
+ depth += {")": 1, "(": -1}.get(content[i], 0)
+ if depth == 0:
+ return i
+ return -1
+
+
+def module_key(rel_path: str) -> str:
+ """The module name *rel_path* is imported by: its path without the
+ extension, and an ``index`` file's directory (``./routes`` imports
+ ``routes/index.ts``)."""
+ return _module_name(_strip_ext(rel_path))
+
+
+def resolve_module(rel_path: str, spec: str) -> str | None:
+ """The repo-relative module a relative *spec* in *rel_path* names, else None.
+
+ A bare or aliased spec (``fastify``, ``@/routes``) is not resolved: its
+ target depends on the bundler or tsconfig, which this does not read.
+ """
+ if not spec.startswith("."):
+ return None
+ joined = posixpath.normpath(posixpath.join(posixpath.dirname(rel_path), spec))
+ if joined.startswith(".."):
+ return None
+ return _module_name(_strip_ext(joined))
+
+
+def _module_name(stem: str) -> str:
+ if posixpath.basename(stem) == "index" and "/" in stem:
+ return posixpath.dirname(stem)
+ return stem
+
+
+def _strip_ext(path: str) -> str:
+ for ext in _JS_EXTS:
+ if path.endswith(ext):
+ return path[: -len(ext)]
+ return path
+
+
+def js_imports(content: str) -> dict[str, tuple[str, str]]:
+ """``local name -> (spec, exported name)`` for ES imports and ``require``.
+
+ The exported name is ``default`` for a default import or a whole-module
+ ``require``.
+ """
+ out: dict[str, tuple[str, str]] = {}
+ for m in _IMPORT_RE.finditer(content):
+ clause, spec = m.group("clause").strip(), m.group("spec")
+ head, _, rest = clause.partition("{")
+ head = head.strip().rstrip(",").strip()
+ if head and _AS_RE.match(head) and "*" not in head:
+ out[head] = (spec, "default")
+ for part in rest.rstrip("}").split(","):
+ named = _AS_RE.match(part.strip().removeprefix("type ").strip())
+ if named:
+ out[named.group("alias") or named.group("name")] = (spec, named.group("name"))
+ for m in _REQUIRE_RE.finditer(content):
+ lhs, spec = m.group("lhs"), m.group("spec")
+ if not lhs.startswith("{"):
+ out[lhs] = (spec, m.group("member") or "default")
+ continue
+ for part in lhs.strip("{}").split(","):
+ named = _AS_RE.match(part.strip())
+ if named:
+ out[named.group("rename") or named.group("name")] = (spec, named.group("name"))
+ return out
+
+
+def plugin_ref(
+ content: str, start: int, imports: dict[str, tuple[str, str]], *, calls: bool = False
+) -> tuple[str | None, str] | None:
+ """``(spec, exported name)`` of the plugin reference at *start*.
+
+ *spec* is None for a name declared in the same file. None when the
+ expression is not a module reference this can follow (a member, or a call
+ unless *calls* admits a factory the module exports, ``Routes(server)``).
+ """
+ m = _REF_RE.match(content, start)
+ if m is None and calls:
+ m = _CALL_REF_RE.match(content, start)
+ if m is None:
+ return None
+ if m.groupdict().get("spec") is not None:
+ return m.group("spec"), m.group("member") or "default"
+ name = m.group("name")
+ if name in {"async", "function", "await", "new"}:
+ return None
+ return imports.get(name, (None, name))
diff --git a/packages/core/src/repowise/core/ingestion/framework_routes_koa.py b/packages/core/src/repowise/core/ingestion/framework_routes_koa.py
new file mode 100644
index 000000000..d5187a5bc
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/framework_routes_koa.py
@@ -0,0 +1,117 @@
+"""Koa router prefixes: ``new Router({prefix: '/api'})``, ``router.prefix()`` and
+``parent.use('/x', child.routes())``.
+
+``@koa/router`` (formerly ``koa-router``) routes use the Express call shape,
+read by ``framework_routes.express_routes``; what Koa adds is where a router is
+served. A router carries its own prefix, and a parent router nests another,
+in the same file or from a module that exports it
+(``api.use(require('./users'))``). :func:`koa_routers` reads the first and
+:func:`koa_uses` the second; the contract consumer stitches them across files.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+from .framework_routes_js import JsObject, call_arg_spans, chain_receiver, js_object_at
+
+_KOA_ROUTER_SPECS = ("@koa/router", "koa-router")
+_KOA_ROUTER_IMPORT_RE = re.compile(
+ r"""(?:\bfrom\s*|\brequire\s*\(\s*)['"](?:@koa/router|koa-router)['"]"""
+)
+
+# What the module is bound to: `import Router from '@koa/router'`,
+# `const Router = require('koa-router')`.
+_IMPORT_RE = re.compile(
+ r"""(?:\bimport\s+(?P<imp>[\w$]+)\s+from|\b(?:const|let|var)\s+(?P<req>[\w$]+)\s*=\s*require\s*\()"""
+ r"""\s*['"](?:@koa/router|koa-router)['"]"""
+)
+# `require('koa-router')(...)`: the module called as a factory in place.
+_INLINE_FACTORY = r"""require\s*\(\s*['"](?:@koa/router|koa-router)['"]\s*\)"""
+_PREFIX_CALL_RE = re.compile(r"(?<![\w$.])(?P<var>[\w$]+)\s*\.\s*prefix\s*(?P<paren>\()")
+_USE_RE = re.compile(r"(?P<dot>\.)\s*use\s*(?P<paren>\()")
+# `child.routes()` / `child.middleware()` mounts the router `child`.
+_INNER_ROUTES_RE = re.compile(r"(?<![\w$.])([\w$]+)\s*\.\s*(?:routes|middleware)\s*\(")
+_ROUTES_CALL_RE = re.compile(r"^(?P<expr>.+?)\s*\.\s*(?:routes|middleware)\s*\(\s*\)$", re.DOTALL)
+
+
+def koa_router_file(content: str) -> bool:
+ """Whether *content* imports ``@koa/router`` or ``koa-router``."""
+ return any(spec in content for spec in _KOA_ROUTER_SPECS) and bool(
+ _KOA_ROUTER_IMPORT_RE.search(content)
+ )
+
+
+def koa_routers(content: str) -> dict[str, str | None]:
+ """``router variable -> prefix expression`` for each Koa router in *content*.
+
+ The expression is the ``prefix`` option's (or ``prefix()`` argument's)
+ source text, "" for a router with none, None when the options are not an
+ object literal.
+ """
+ if not koa_router_file(content):
+ return {}
+ ctors = {m.group("imp") or m.group("req") for m in _IMPORT_RE.finditer(content)}
+ alts = [re.escape(c) for c in sorted(ctors)] + [_INLINE_FACTORY]
+ bind_re = re.compile(
+ r"(?<![\w$.])(?P<var>[\w$]+)\s*(?::[^=;\n]+)?=\s*(?:new\s+)?(?:"
+ + "|".join(alts)
+ + r")\s*(?P<paren>\()"
+ )
+ out: dict[str, str | None] = {}
+ for m in bind_re.finditer(content):
+ spans = call_arg_spans(content, m.start("paren"))
+ if not spans:
+ out[m.group("var")] = ""
+ continue
+ options = _object(content, spans[0])
+ out[m.group("var")] = None if options is None else options.expr(content, "prefix") or ""
+ for m in _PREFIX_CALL_RE.finditer(content):
+ spans = call_arg_spans(content, m.start("paren"))
+ if m.group("var") in out and spans:
+ out[m.group("var")] = content[spans[0][0] : spans[0][1]].strip()
+ return out
+
+
+def _object(content: str, span: tuple[int, int]) -> JsObject | None:
+ text = content[span[0] : span[1]]
+ return js_object_at(content, span[0] + len(text) - len(text.lstrip()))
+
+
+@dataclass(frozen=True)
+class KoaUse:
+ """One ``parent.use([path,] router...)`` call."""
+
+ offset: int
+ receiver: str
+ #: The path argument's source text, "" when the call has none.
+ path: str
+ #: Each router argument, unwrapped from ``.routes()`` / ``.middleware()``.
+ routers: tuple[str, ...]
+ #: Routers whose ``.routes()`` is passed inside another call
+ #: (``mount('/api', r.routes())``), so where they are served is not read.
+ wrapped: tuple[str, ...] = ()
+
+
+def koa_uses(content: str) -> Iterator[KoaUse]:
+ """Every ``.use(...)`` call in *content* that may mount a router."""
+ for m in _USE_RE.finditer(content):
+ receiver = chain_receiver(content, m.start("dot"))
+ spans = call_arg_spans(content, m.start("paren"))
+ if not receiver or not spans:
+ continue
+ args = [content[s:e].strip() for s, e in spans]
+ path = args[0] if args[0][:1] in "'\"`" else ""
+ routers: list[str] = []
+ wrapped: list[str] = []
+ for arg in args[1:] if path else args:
+ unwrapped = _ROUTES_CALL_RE.match(arg)
+ expr = unwrapped.group("expr").strip() if unwrapped else arg
+ inner = _INNER_ROUTES_RE.findall(expr)
+ if inner and not expr.startswith("require"):
+ wrapped.extend(inner)
+ else:
+ routers.append(expr)
+ yield KoaUse(m.start(), receiver, path, tuple(routers), tuple(wrapped))
diff --git a/packages/core/src/repowise/core/ingestion/framework_routes_next_pages.py b/packages/core/src/repowise/core/ingestion/framework_routes_next_pages.py
new file mode 100644
index 000000000..cc4fd84bc
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/framework_routes_next_pages.py
@@ -0,0 +1,82 @@
+"""Next.js Pages Router API routes: ``pages/api/**``.
+
+The path comes from the file's location under ``pages/api/``, as in the App
+Router, but one default-exported handler serves every verb. The verbs a handler
+compares ``req.method`` against are the ones it serves; a handler that compares
+none is recorded as ``*``.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .framework_routes import NEXT_APP_ROUTER_EXTS
+
+# `[id]`, `[...slug]`, `[[...slug]]` -> `{id}` / `{slug}`.
+_DYNAMIC_SEG_RE = re.compile(r"^\[+\.{0,3}(?P<name>[^\]]+)\]+$")
+# A test, mock or type declaration beside a handler is not a route a
+# deployment serves.
+_TEST_NAME_RE = re.compile(r"\.(?:test|spec|d)$")
+_NON_ROUTE_DIRS = frozenset({"__tests__", "__mocks__", "__fixtures__"})
+# What says a default export is a handler: it touches a request or response,
+# names Next's types, takes `(req, res)`, or is built by a handler factory
+# (`export default startServerAndCreateNextHandler(server)`).
+_HANDLER_RE = re.compile(
+ r"\b(?:req|res|request|response)\s*\.|\bNext(?:Api)?(?:Request|Response)\b"
+ r"|^[^\S\n]*(?:export\s+default|module\.exports\s*=)\s*(?:async\s+)?"
+ r"(?:[\w$.]+\s*\(|function\b[^(]*\(\s*[\w$]+[^,)]*,|\(\s*[\w$]+[^,)]*,)",
+ re.MULTILINE,
+)
+
+_VERBS = "GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS"
+# `req.method === 'POST'` and `req.method !== 'POST'` (an early 405) both name
+# a verb the handler serves; so does a `case 'POST':` under `switch (req.method)`.
+_METHOD_COMPARE_RE = re.compile(rf"""\.method\s*[!=]==?\s*['"`](?P<verb>{_VERBS})['"`]""")
+_METHOD_SWITCH_RE = re.compile(r"switch\s*\(\s*[\w$.]*\.method\s*\)")
+_METHOD_CASE_RE = re.compile(rf"""\bcase\s+['"`](?P<verb>{_VERBS})['"`]\s*:""")
+_DEFAULT_EXPORT_RE = re.compile(r"^[^\S\n]*(?:export\s+default\b|module\.exports\s*=)", re.MULTILINE)
+
+
+def next_pages_api_path(rel_path: str) -> str | None:
+ """The URL a ``pages/api/**`` handler serves, else None."""
+ parts = rel_path.split("/")
+ name = parts[-1]
+ ext = next((e for e in NEXT_APP_ROUTER_EXTS if name.endswith(e)), None)
+ if ext is None:
+ return None
+ stem = name[: -len(ext)]
+ if stem == "_middleware" or _TEST_NAME_RE.search(stem):
+ return None
+ # The nearest `pages/api/` pair, so a nested app's own pages win.
+ at = next(
+ (i for i in range(len(parts) - 3, -1, -1) if parts[i] == "pages" and parts[i + 1] == "api"),
+ None,
+ )
+ if at is None:
+ return None
+ if _NON_ROUTE_DIRS.intersection(parts[at + 2 : -1]):
+ return None
+ segments = parts[at + 1 : -1] + ([] if stem == "index" else [stem])
+ out = []
+ for seg in segments:
+ dyn = _DYNAMIC_SEG_RE.match(seg)
+ out.append("{" + dyn.group("name") + "}" if dyn else seg)
+ return "/" + "/".join(out)
+
+
+def next_pages_api_verbs(content: str) -> list[tuple[str, int]] | None:
+ """``(verb, offset)`` per verb the handler serves, ``[("*", offset)]`` when it
+ compares none, or None when the file default-exports no handler (a helper
+ module kept under ``pages/api`` touches no request or response)."""
+ export = _DEFAULT_EXPORT_RE.search(content)
+ if export is None or _HANDLER_RE.search(content) is None:
+ return None
+ found = [(m.group("verb"), m.start()) for m in _METHOD_COMPARE_RE.finditer(content)]
+ if _METHOD_SWITCH_RE.search(content):
+ found += [(m.group("verb"), m.start()) for m in _METHOD_CASE_RE.finditer(content)]
+ if not found:
+ return [("*", export.start())]
+ first: dict[str, int] = {}
+ for verb, at in sorted(found, key=lambda f: f[1]):
+ first.setdefault(verb, at)
+ return list(first.items())
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/__init__.py b/packages/core/src/repowise/core/workspace/extractors/http/__init__.py
index 798470209..61c6258bc 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/__init__.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/__init__.py
@@ -27,12 +27,15 @@ from .csharp_http import CSharpHttpDialect
from .django import DjangoDialect
from .express import ExpressDialect
from .fastapi import FastApiDialect
+from .fastify import FastifyDialect
from .flask import FlaskDialect
from .go import GoDialect
from .go_clients import GoClientsDialect
+from .hapi import HapiDialect
from .java_clients import JavaClientsDialect, MicroProfileClientsDialect, SpringClientsDialect
from .jaxrs import JaxRsDialect
from .js_clients import JsClientsDialect
+from .koa import KoaDialect
from .kotlin_clients import KotlinClientsDialect
from .laravel import LaravelDialect
from .micronaut import MicronautDialect
@@ -76,6 +79,9 @@ PROVIDER_DIALECTS: tuple[ContractDialect, ...] = (
RemixDialect(),
ApexRestDialect(),
AzureFunctionsDialect(),
+ FastifyDialect(),
+ HapiDialect(),
+ KoaDialect(),
)
# HTTP-client call recognisers (one client/language each).
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/express.py b/packages/core/src/repowise/core/workspace/extractors/http/express.py
index 8e43da0f0..810bb8d5a 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/express.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/express.py
@@ -2,7 +2,10 @@
Express, Hono, Fastify, Koa and Elysia all serve routes through this one call
shape, and only the variable's binding says which is which. The contract is
-labelled from that binding rather than assumed to be Express.
+labelled from that binding rather than assumed to be Express. A Fastify file
+(or a module a Fastify file registers) and a ``koa-router`` file are left to
+their own dialects, because there a route's path depends on the plugin or
+router it runs in.
Routers carry no in-file prefix; the mount lives in a separate
``app.use('/prefix', router)`` call, so the real path is recovered by stitching
@@ -23,11 +26,13 @@ from repowise.core.ingestion.framework_routes import (
express_routes,
js_router_bindings,
)
+from repowise.core.ingestion.framework_routes_koa import koa_router_file
from ..base import line_at
from ..calls import code_matches, outside_comments
from ..langs import JS_TS
from .dialect import build_provider_contract
+from .fastify import fastify_module
from .mounts import compose_prefix
if TYPE_CHECKING:
@@ -58,6 +63,8 @@ class ExpressDialect:
return out
def extract(self, ctx: ScanContext) -> list[Contract]:
+ if fastify_module(ctx) or koa_router_file(ctx.content):
+ return []
bindings = js_router_bindings(ctx.content)
# `app`/`router` are routers whose constructor is in another file, so
# they take the file's framework when it binds exactly one, and Express
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/fastify.py b/packages/core/src/repowise/core/workspace/extractors/http/fastify.py
new file mode 100644
index 000000000..55b90fa02
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/extractors/http/fastify.py
@@ -0,0 +1,234 @@
+"""Fastify HTTP provider dialect: shorthand routes, ``route({...})`` objects and
+``register(plugin, {prefix})`` prefixes.
+
+A Fastify file is read here and not by the Express dialect, because its paths
+depend on the plugin each route runs in. Recognition is in
+``ingestion.framework_routes_fastify``; this dialect joins it across files:
+
+* ``collect_mounts`` records, for every ``register`` of a plugin in another
+ module (or a named one in the same file), the prefix it is given and the
+ plugin the call itself runs in, keyed ``fastify:<module>#<export>``.
+* ``extract`` composes a route's prefix by walking up from the plugin the route
+ runs in: inline plugins in the file, then the registrations recorded above.
+
+A prefix this cannot read (a variable), or a plugin registered at two different
+prefixes or under two parents, makes its routes unreadable, so they are not
+emitted rather than emitted at a guessed path.
+"""
+
+from __future__ import annotations
+
+from itertools import chain
+from typing import TYPE_CHECKING
+
+from repowise.core.ingestion.framework_routes import (
+ HTTP_METHODS,
+ express_routes,
+ js_router_bindings,
+)
+from repowise.core.ingestion.framework_routes_fastify import (
+ FASTIFY_DEFAULT_NAMES,
+ Plugin,
+ Register,
+ fastify_file,
+ fastify_plugins,
+ fastify_registers,
+ fastify_route_objects,
+ register_receivers,
+)
+from repowise.core.ingestion.framework_routes_js import module_key, resolve_module
+
+from ..base import line_at
+from ..calls import file_strings, outside_comments
+from ..langs import JS_TS
+from .dialect import build_provider_contract
+from .mounts import (
+ add_mounts,
+ alias_mounted,
+ compose_prefix,
+ declare_alias_mount,
+ declare_mount,
+ declared_mount,
+ prefix_text,
+)
+
+if TYPE_CHECKING:
+ from collections.abc import Mapping
+
+ from repowise.core.ingestion.framework_routes import RouteMatch
+ from repowise.core.workspace.contracts import Contract
+
+ from ..base import ScanContext
+
+# `fastify:<module>#<export>` -> the prefix a register call gives the plugin;
+# `fastify-in:<module>#<export>` -> the plugin that call runs in, as
+# `<module>#<name>,<name>` ("" at the top level).
+_PREFIX = "fastify:"
+_PARENT = "fastify-in:"
+# `fastify-module:<module>`: a module some Fastify file registers, so it is a
+# Fastify plugin even when it never imports Fastify.
+_MODULE = "fastify-module:"
+_NAMESPACE = "fastify"
+# Plugins nest a few levels deep; a longer chain is a cycle.
+_MAX_DEPTH = 16
+
+# (the exported plugin a call runs in, or None; the prefix within it, or None
+# when unreadable)
+_Site = tuple[Plugin | None, str | None]
+
+
+class _File:
+ """One Fastify file's routes, plugins and registrations."""
+
+ def __init__(self, ctx: ScanContext) -> None:
+ content = ctx.content
+ self.module = module_key(ctx.rel_path)
+ strings = file_strings(ctx)
+ objects = (
+ (r, prefix_text(strings, expr) if expr else r.path)
+ for r, expr in fastify_route_objects(content)
+ )
+ shorthand = ((r, r.path) for r in express_routes(content))
+ self.routes: list[tuple[RouteMatch, str]] = [
+ (r, path)
+ for r, path in chain(shorthand, objects)
+ if path and r.verb in HTTP_METHODS and not ctx.in_comment(r.offset)
+ ]
+ receivers = {r.receiver for r, _path in self.routes if r.receiver}
+ self.plugins = fastify_plugins(content, receivers | register_receivers(content))
+ self.registers: list[tuple[Register, str | None]] = [
+ (reg, None if reg.prefix is None else prefix_text(strings, reg.prefix))
+ for reg in outside_comments(ctx, fastify_registers(content, self.plugins))
+ ]
+ self.bound = {v for v, fw in js_router_bindings(content).items() if fw == "fastify"}
+ self._inline = {r.inline.head: (r, p) for r, p in self.registers if r.inline is not None}
+
+ def _plugin_at(self, offset: int, receiver: str | None) -> Plugin | None:
+ """The innermost plugin around *offset* whose instance is *receiver*."""
+ best: Plugin | None = None
+ for p in self.plugins:
+ inside = p.body < offset < p.end
+ if p.param == receiver and inside and (best is None or p.body > best.body):
+ best = p
+ return best
+
+ def site(self, offset: int, receiver: str | None, depth: int = 0) -> _Site | None:
+ """Where a call on *receiver* at *offset* runs; None when *receiver*
+ holds no Fastify instance there."""
+ plugin = self._plugin_at(offset, receiver)
+ if plugin is None:
+ if receiver in self.bound or receiver in FASTIFY_DEFAULT_NAMES:
+ return None, ""
+ return None
+ found = self._inline.get(plugin.head)
+ if found is None:
+ return plugin, "" # a named or exported plugin: the mount map has its prefix
+ reg, prefix = found
+ outer = self.site(reg.offset, reg.receiver, depth + 1) if depth < _MAX_DEPTH else None
+ exported, within = outer if outer is not None else (None, "")
+ if plugin.fp:
+ return exported, within
+ if within is None or prefix is None:
+ return exported, None
+ return exported, compose_prefix(within, prefix)
+
+ def keys(self, plugin: Plugin) -> list[str]:
+ return [f"{self.module}#{name}" for name in plugin.names]
+
+
+def _parent_keys(value: str) -> list[str]:
+ module, _, names = value.partition("#")
+ return [f"{module}#{name}" for name in names.split(",") if name]
+
+
+def _resolve(mounts: Mapping[str, str], keys: list[str], fp: bool, depth: int = 0) -> str | None:
+ """The prefix the plugin known by *keys* is served at; None when unreadable.
+
+ A plugin no ``register`` call names is served where it is declared ("").
+ """
+ if depth > _MAX_DEPTH:
+ return None
+ for key in keys:
+ declared, value = declared_mount(mounts, _PREFIX + key)
+ if not declared:
+ continue
+ has_parent, parent = declared_mount(mounts, _PARENT + key)
+ if value is None or (has_parent and parent is None):
+ return None
+ outer = _resolve(mounts, _parent_keys(parent or ""), False, depth + 1)
+ if outer is None:
+ return None
+ return outer if fp else compose_prefix(outer, value)
+ return ""
+
+
+def fastify_module(ctx: ScanContext) -> bool:
+ """Whether *ctx*'s file is Fastify code, or a module a Fastify file registers."""
+ if fastify_file(ctx.content):
+ return True
+ return declared_mount(ctx.mounts, _MODULE + module_key(ctx.rel_path))[0]
+
+
+class FastifyDialect:
+ name = "fastify"
+ extensions = JS_TS
+ # A plugin module need not name Fastify at all
+ # (`module.exports = async function (app) {...}`); the export admits it and
+ # the mount map then has to name it before anything is read.
+ requires = ("fastify", "Fastify", "export", "exports")
+
+ def collect_mounts(self, ctx: ScanContext) -> dict[str, str]:
+ """Each plugin registered from this file: its prefix and its parent."""
+ if not fastify_file(ctx.content):
+ return {}
+ f = _File(ctx)
+ out: dict[str, str] = {}
+ for reg, reg_prefix in f.registers:
+ if reg.target is None:
+ continue
+ spec, export = reg.target
+ module = f.module if spec is None else resolve_module(ctx.rel_path, spec)
+ exported, within = f.site(reg.offset, reg.receiver) or (None, "")
+ prefix = (
+ None
+ if within is None or reg_prefix is None
+ else compose_prefix(within, reg_prefix)
+ )
+ if module is None:
+ if spec and prefix != "":
+ add_mounts(out, declare_alias_mount(_NAMESPACE, spec))
+ continue
+ parent = f"{f.module}#{','.join(exported.names)}" if exported and exported.names else ""
+ key = f"{module}#{export}"
+ add_mounts(out, declare_mount(_PREFIX + key, prefix))
+ add_mounts(out, declare_mount(_PARENT + key, parent))
+ add_mounts(out, declare_mount(_MODULE + module, ""))
+ return out
+
+ def extract(self, ctx: ScanContext) -> list[Contract]:
+ if not fastify_module(ctx):
+ return []
+ f = _File(ctx)
+ aliased = alias_mounted(ctx.mounts, _NAMESPACE, f.module)
+ out: list[Contract] = []
+ for route, path in f.routes:
+ site = f.site(route.offset, route.receiver)
+ if site is None or site[1] is None:
+ continue
+ exported, within = site
+ keys = f.keys(exported) if exported else []
+ if aliased and not any(declared_mount(ctx.mounts, _PREFIX + k)[0] for k in keys):
+ continue # registered through an alias this cannot follow
+ outer = _resolve(ctx.mounts, keys, exported.fp) if exported else ""
+ if outer is None:
+ continue
+ c = build_provider_contract(
+ ctx,
+ method=route.verb,
+ path_raw=compose_prefix(compose_prefix(outer, within), path),
+ framework="fastify",
+ line=line_at(ctx.content, route.offset),
+ )
+ if c is not None:
+ out.append(c)
+ return out
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/hapi.py b/packages/core/src/repowise/core/workspace/extractors/http/hapi.py
new file mode 100644
index 000000000..4a9392e91
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/extractors/http/hapi.py
@@ -0,0 +1,92 @@
+"""hapi HTTP provider dialect: route objects and ``register`` prefixes.
+
+Recognition is in ``ingestion.framework_routes_hapi``. ``collect_mounts``
+records each module a file registers as a plugin or passes to ``server.route``,
+with its prefix and the registering module, keyed ``hapi:<module>``; a module
+recorded there is read even when it does not import hapi itself (a route table
+exported as a plain array). A prefix that is not a literal, or a module mounted
+at two different prefixes, leaves its routes unread rather than guessed.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from repowise.core.ingestion.framework_routes_fastify import fastify_file
+from repowise.core.ingestion.framework_routes_hapi import hapi_file, hapi_mounts, hapi_routes
+from repowise.core.ingestion.framework_routes_js import module_key, resolve_module
+
+from ..base import line_at
+from ..calls import file_strings, outside_comments
+from ..langs import JS_TS
+from .dialect import build_provider_contract
+from .mounts import (
+ add_mounts,
+ alias_mounted,
+ compose_prefix,
+ declare_alias_mount,
+ declare_module_mount,
+ module_prefix,
+ prefix_text,
+)
+
+if TYPE_CHECKING:
+ from repowise.core.workspace.contracts import Contract
+
+ from ..base import ScanContext
+
+_NAMESPACE = "hapi"
+_VERBS = frozenset({"GET", "POST", "PUT", "DELETE", "PATCH", "*"})
+
+
+class HapiDialect:
+ name = "hapi"
+ extensions = JS_TS
+ # `handler` admits a route table module with no hapi import, which the
+ # mount map then has to name before anything is read from it.
+ requires = ("hapi", "Hapi", ".route(", ".route (", "handler")
+
+ def collect_mounts(self, ctx: ScanContext) -> dict[str, str]:
+ """The modules this file mounts, with their prefixes."""
+ if not hapi_file(ctx.content) or fastify_file(ctx.content):
+ return {}
+ here = module_key(ctx.rel_path)
+ strings = file_strings(ctx)
+ out: dict[str, str] = {}
+ for mount in outside_comments(ctx, hapi_mounts(ctx.content)):
+ spec, _name = mount.target
+ # A name declared in this file is read with the file itself.
+ module = resolve_module(ctx.rel_path, spec) if spec else None
+ prefix = prefix_text(strings, mount.prefix)
+ if spec and module is None and prefix != "":
+ add_mounts(out, declare_alias_mount(_NAMESPACE, spec))
+ if module is None or module == here:
+ continue
+ add_mounts(out, declare_module_mount(_NAMESPACE, module, prefix, here))
+ return out
+
+ def extract(self, ctx: ScanContext) -> list[Contract]:
+ if fastify_file(ctx.content):
+ return []
+ module = module_key(ctx.rel_path)
+ mounted, prefix = module_prefix(ctx.mounts, _NAMESPACE, module)
+ if prefix is None or not (mounted or hapi_file(ctx.content)):
+ return []
+ if not mounted and alias_mounted(ctx.mounts, _NAMESPACE, module):
+ return [] # registered through an alias this cannot follow
+ strings = file_strings(ctx)
+ out: list[Contract] = []
+ for route, expr in hapi_routes(ctx.content):
+ path = prefix_text(strings, expr) if expr else route.path
+ if not path or route.verb not in _VERBS or ctx.in_comment(route.offset):
+ continue
+ c = build_provider_contract(
+ ctx,
+ method=route.verb,
+ path_raw=compose_prefix(prefix, path),
+ framework="hapi",
+ line=line_at(ctx.content, route.offset),
+ )
+ if c is not None:
+ out.append(c)
+ return out
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/koa.py b/packages/core/src/repowise/core/workspace/extractors/http/koa.py
new file mode 100644
index 000000000..36860fcb5
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/extractors/http/koa.py
@@ -0,0 +1,151 @@
+"""Koa router HTTP provider dialect: ``@koa/router`` / ``koa-router`` routes with
+their prefixes.
+
+A file that imports the router package is read here and not by the Express
+dialect, because a Koa route's path depends on its router: the router's own
+``prefix``, the router that nests it in the same file
+(``api.use('/v1', child.routes())``), and the module that nests the whole file
+(``api.use(require('./users'))``). Recognition is in
+``ingestion.framework_routes_koa``; ``collect_mounts`` records module mounts,
+keyed ``koa:<module>``, and ``extract`` composes the three.
+
+A prefix that is not a string this can resolve leaves the router's routes
+unread rather than placed at a guessed path.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from repowise.core.ingestion.framework_routes import (
+ HTTP_METHODS,
+ JS_DEFAULT_ROUTER_NAMES,
+ express_routes,
+)
+from repowise.core.ingestion.framework_routes_js import js_imports, module_key, resolve_module
+from repowise.core.ingestion.framework_routes_koa import koa_router_file, koa_routers, koa_uses
+
+from ..base import line_at
+from ..calls import file_strings, outside_comments
+from ..langs import JS_TS
+from .dialect import build_provider_contract
+from .mounts import (
+ add_mounts,
+ compose_prefix,
+ declare_module_mount,
+ module_prefix,
+ prefix_text,
+)
+
+if TYPE_CHECKING:
+ from repowise.core.ingestion.framework_routes_koa import KoaUse
+ from repowise.core.workspace.contracts import Contract
+
+ from ..base import ScanContext
+
+_NAMESPACE = "koa"
+# Routers nest a few levels deep in one file; a longer chain is a cycle.
+_MAX_DEPTH = 16
+# koa-router's `del` is its name for DELETE.
+_VERB_ALIASES = {"DEL": "DELETE"}
+
+
+class _File:
+ """One Koa file's routers and where each is served within the file."""
+
+ def __init__(self, ctx: ScanContext) -> None:
+ strings = file_strings(ctx)
+ self.own = {
+ var: None if expr is None else prefix_text(strings, expr)
+ for var, expr in koa_routers(ctx.content).items()
+ }
+ self.uses: list[KoaUse] = list(outside_comments(ctx, koa_uses(ctx.content)))
+ self._paths = {id(use): prefix_text(strings, use.path) for use in self.uses}
+
+ def use_path(self, use: KoaUse) -> str | None:
+ return self._paths[id(use)]
+
+ def prefix_of(self, router: str, depth: int = 0) -> str | None:
+ """Where *router* is served within this file; None when unreadable.
+
+ A router mounted through a wrapper (``mount('/api', r.routes())``) or
+ under parents that place it differently is unreadable.
+ """
+ own = self.own.get(router, "")
+ if depth > _MAX_DEPTH or own is None or any(router in u.wrapped for u in self.uses):
+ return None
+ placed: set[str | None] = set()
+ for use in self.uses:
+ if router not in use.routers or use.receiver == router:
+ continue
+ outer, path = self.prefix_of(use.receiver, depth + 1), self.use_path(use)
+ placed.add(None if outer is None or path is None else compose_prefix(outer, path))
+ if not placed:
+ return own
+ if len(placed) > 1 or None in placed:
+ return None
+ return compose_prefix(placed.pop() or "", own)
+
+
+class KoaDialect:
+ name = "koa"
+ extensions = JS_TS
+ requires = ("koa-router", "@koa/router")
+
+ def collect_mounts(self, ctx: ScanContext) -> dict[str, str]:
+ """Each module this file nests under one of its routers."""
+ if not koa_router_file(ctx.content):
+ return {}
+ f = _File(ctx)
+ imports = js_imports(ctx.content)
+ here = module_key(ctx.rel_path)
+ out: dict[str, str] = {}
+ for use in f.uses:
+ for router in use.routers:
+ spec = _module_spec(router, imports)
+ module = resolve_module(ctx.rel_path, spec) if spec else None
+ if module is None or module == here:
+ continue
+ outer, path = f.prefix_of(use.receiver), f.use_path(use)
+ prefix = None if outer is None or path is None else compose_prefix(outer, path)
+ add_mounts(out, declare_module_mount(_NAMESPACE, module, prefix, here))
+ return out
+
+ def extract(self, ctx: ScanContext) -> list[Contract]:
+ if not koa_router_file(ctx.content):
+ return []
+ _mounted, module = module_prefix(ctx.mounts, _NAMESPACE, module_key(ctx.rel_path))
+ if module is None:
+ return []
+ f = _File(ctx)
+ out: list[Contract] = []
+ for route in outside_comments(ctx, express_routes(ctx.content)):
+ verb = _VERB_ALIASES.get(route.verb, route.verb)
+ receiver = route.receiver or ""
+ if verb not in HTTP_METHODS or not route.path:
+ continue
+ if receiver not in f.own and receiver not in JS_DEFAULT_ROUTER_NAMES:
+ continue
+ within = f.prefix_of(receiver)
+ if within is None:
+ continue
+ c = build_provider_contract(
+ ctx,
+ method=verb,
+ path_raw=compose_prefix(compose_prefix(module, within), route.path),
+ framework="koa",
+ line=line_at(ctx.content, route.offset),
+ )
+ if c is not None:
+ out.append(c)
+ return out
+
+
+def _module_spec(expr: str, imports: dict[str, tuple[str, str]]) -> str | None:
+ """The module spec a router argument names: ``require('./x')`` or an import."""
+ if expr.startswith("require"):
+ start, end = expr.find("("), expr.rfind(")")
+ inner = expr[start + 1 : end].strip()
+ return inner[1:-1] if inner[:1] in "'\"" and inner[-1:] == inner[:1] else None
+ found = imports.get(expr)
+ return found[0] if found else None
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/mounts.py b/packages/core/src/repowise/core/workspace/extractors/http/mounts.py
index 703c3ff1d..973e35b42 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/mounts.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/mounts.py
@@ -21,9 +21,13 @@ from __future__ import annotations
import re
from collections.abc import Iterable, Mapping
+from typing import TYPE_CHECKING
from repowise.core.ingestion.framework_routes import GroupMatch
+if TYPE_CHECKING:
+ from ..calls import FileStrings
+
# A ``prefix="..."`` / ``prefix='...'`` keyword argument inside a constructor call.
_PREFIX_KW_RE = re.compile(r"""prefix\s*=\s*['"]([^'"]+)['"]""")
@@ -145,3 +149,74 @@ def group_prefixes(groups: Iterable[GroupMatch]) -> dict[str, str]:
for var in edges:
resolve(var, frozenset())
return resolved
+
+
+# Module mounts nest a few levels deep; a longer chain is a cycle.
+_MAX_MODULE_DEPTH = 16
+
+
+def add_mounts(out: dict[str, str], entries: Mapping[str, str]) -> None:
+ """Add *entries* to one file's mount map; a key the file already gave a
+ different value becomes unreadable, as two files disagreeing does in
+ :func:`merge_mount_maps`."""
+ for key, value in entries.items():
+ out[key] = _UNREADABLE if key in out and out[key] != value else value
+
+
+def declare_alias_mount(namespace: str, spec: str) -> dict[str, str]:
+ """Record that a module was mounted through a spec this cannot resolve
+ (``@/routes``, a bundler or tsconfig alias), by its last path segment."""
+ return declare_mount(f"{namespace}-alias:{spec.rstrip('/').rsplit('/', 1)[-1]}", "")
+
+
+def alias_mounted(mounts: Mapping[str, str], namespace: str, module: str) -> bool:
+ """Whether a module named like *module* was mounted through an unresolved
+ alias, so where it is served cannot be told from here."""
+ name = module.rsplit("/", 1)[-1]
+ return declared_mount(mounts, f"{namespace}-alias:{name}")[0]
+
+
+def declare_module_mount(
+ namespace: str, module: str, prefix: str | None, parent: str
+) -> dict[str, str]:
+ """The mount entries saying *module* is served at *prefix* under *parent*.
+
+ For frameworks that mount a whole module from another (a hapi plugin, a
+ Koa router module): *parent* is the mounting module, itself perhaps
+ mounted. A module mounted at two prefixes or under two parents reads as
+ unreadable, so its routes are left out rather than placed at one guess.
+ """
+ return {
+ **declare_mount(f"{namespace}:{module}", prefix),
+ **declare_mount(f"{namespace}-in:{module}", parent),
+ }
+
+
+def module_prefix(
+ mounts: Mapping[str, str], namespace: str, module: str, depth: int = 0
+) -> tuple[bool, str | None]:
+ """``(mounted, full prefix)`` of *module*; the prefix is None when unreadable."""
+ declared, value = declared_mount(mounts, f"{namespace}:{module}")
+ if not declared:
+ return False, ""
+ has_parent, parent = declared_mount(mounts, f"{namespace}-in:{module}")
+ if value is None or (has_parent and parent is None) or depth > _MAX_MODULE_DEPTH:
+ return True, None
+ if not parent:
+ return True, value
+ _mounted, outer = module_prefix(mounts, namespace, parent, depth + 1)
+ return True, None if outer is None else compose_prefix(outer, value)
+
+
+def prefix_text(strings: FileStrings | None, expr: str | None) -> str | None:
+ """A prefix or path expression read through the file's constants.
+
+ "" for no expression; None for an unreadable one (None) or one that does
+ not resolve to a whole string.
+ """
+ if expr is None:
+ return None
+ if not expr:
+ return ""
+ text = strings.text(expr) if strings is not None else None
+ return None if text is None or "${" in text else text
diff --git a/packages/core/src/repowise/core/workspace/extractors/http/next_app.py b/packages/core/src/repowise/core/workspace/extractors/http/next_app.py
index ea4d4d39f..553e3cf80 100644
--- a/packages/core/src/repowise/core/workspace/extractors/http/next_app.py
+++ b/packages/core/src/repowise/core/workspace/extractors/http/next_app.py
@@ -1,10 +1,13 @@
-"""Next.js App Router HTTP provider dialect — ``app/**/route.ts``.
+"""Next.js HTTP provider dialect: App Router ``app/**/route.ts`` and Pages Router
+``pages/api/**``.
-Unique among the dialects here in reading no route call at all: the App Router
-takes the path from the file's own location and the verb from the name of each
-exported handler, so both halves come from outside the source text. Both are
-derived by ``ingestion.framework_routes``, shared with the graph-edge builder
-that uses the same convention test to find files loaded without an import.
+Unique among the dialects here in reading no route call at all: Next.js takes
+the path from the file's own location. The App Router takes the verb from the
+name of each exported handler; a Pages Router handler serves the verbs it
+compares ``req.method`` against, or every verb (``*``) when it compares none.
+Both conventions are derived in ``ingestion``, shared with the graph-edge
+builder that uses the same convention test to find files loaded without an
+import.
"""
from __future__ import annotations
@@ -16,6 +19,10 @@ from repowise.core.ingestion.framework_routes import (
next_route_path,
next_route_verbs,
)
+from repowise.core.ingestion.framework_routes_next_pages import (
+ next_pages_api_path,
+ next_pages_api_verbs,
+)
from ..base import line_at
from ..langs import JS_TS
@@ -26,19 +33,27 @@ if TYPE_CHECKING:
from ..base import ScanContext
+_ANY_VERB = HTTP_METHODS | {"*"}
+
class NextAppDialect:
name = "next-app"
extensions = JS_TS
- requires = ("export",)
+ # `module.exports =` serves a Pages Router handler from plain JS.
+ requires = ("export", "module.exports")
def extract(self, ctx: ScanContext) -> list[Contract]:
path = next_route_path(ctx.rel_path)
- if path is None:
- return []
+ framework = "next-app"
+ if path is not None:
+ verbs = next_route_verbs(ctx.content)
+ else:
+ path = next_pages_api_path(ctx.rel_path)
+ framework = "next-pages"
+ verbs = (next_pages_api_verbs(ctx.content) or []) if path is not None else []
out: list[Contract] = []
- for verb, offset in next_route_verbs(ctx.content):
- if verb not in HTTP_METHODS:
+ for verb, offset in verbs:
+ if verb not in _ANY_VERB:
continue
# Bound by line, not by `handler=verb`: every route handler in the
# repo exports the same few names, so a repo-wide lookup by name
@@ -47,7 +62,7 @@ class NextAppDialect:
ctx,
method=verb,
path_raw=path,
- framework="next-app",
+ framework=framework,
line=line_at(ctx.content, offset),
)
if c is not None:
diff --git a/tests/unit/workspace/test_node_route_frameworks.py b/tests/unit/workspace/test_node_route_frameworks.py
new file mode 100644
index 000000000..f575904ea
--- /dev/null
+++ b/tests/unit/workspace/test_node_route_frameworks.py
@@ -0,0 +1,570 @@
+"""Fastify, hapi, Koa router prefixes and Next.js ``pages/api`` as HTTP providers.
+
+Fastify and Koa routes use the Express call shape, so they were read, but at the
+wrong path: Fastify serves a plugin's routes under the prefix its ``register``
+call gives it, and a Koa router carries its own ``prefix``. hapi declares a route
+as an object literal and Next.js Pages Router takes it from the file's location,
+so neither produced a contract at all.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.core.ingestion.framework_routes import express_routes
+from repowise.core.ingestion.framework_routes_next_pages import (
+ next_pages_api_path,
+ next_pages_api_verbs,
+)
+from repowise.core.workspace.extractors.http import HttpExtractor
+from repowise.core.workspace.origins import ContractOrigin
+
+
+def _write(root: Path, files: dict[str, str]) -> Path:
+ for rel, text in files.items():
+ path = root / rel
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8")
+ return root
+
+
+def _providers(root: Path) -> dict[str, dict]:
+ return {
+ c.contract_id: {"framework": c.meta["framework"], "file": c.file_path, "origin": c.origin}
+ for c in HttpExtractor().extract(root, "api")
+ if c.role == "provider"
+ }
+
+
+# ---------------------------------------------------------------------------
+# Fastify
+# ---------------------------------------------------------------------------
+
+# The shape of a real gateway server: typed plugins in their own modules, each
+# registered with a prefix, one of them registering a sub-plugin of its own.
+FASTIFY_SERVER_TS = """\
+import Fastify from 'fastify';
+import {opsRoutes} from './ops';
+import {folderRoutes} from './folders';
+import {browserRoutes} from './browser';
+
+export async function buildServer() {
+\tconst app = Fastify({logger: false});
+\tawait app.register(opsRoutes);
+\tawait app.register(folderRoutes, {prefix: '/api/folders'});
+\t// await app.register(legacyRoutes, {prefix: '/old'});
+\tawait app.register(browserRoutes, {prefix: '/api/browser'});
+\treturn app;
+}
+"""
+
+FASTIFY_OPS_TS = """\
+import type {FastifyPluginAsync} from 'fastify';
+
+export const opsRoutes: FastifyPluginAsync = async (app) => {
+\tapp.get('/healthz', async () => ({ok: true}));
+};
+"""
+
+FASTIFY_FOLDERS_TS = """\
+import type {FastifyPluginAsync} from 'fastify';
+
+export const folderRoutes: FastifyPluginAsync = async (app) => {
+\tapp.get('/', async () => ({folders: []}));
+\tapp.post<{
+\t\tBody: {path: string};
+\t}>(
+\t\t'/local',
+\t\tasync (req, reply) => reply.send({}),
+\t);
+\tapp.delete<{Params: {idOrName: string}}>('/:idOrName', async () => ({}));
+};
+"""
+
+FASTIFY_BROWSER_INDEX_TS = """\
+import type {FastifyPluginAsync} from 'fastify';
+import {browserLaunchRoute} from './launch';
+
+export const browserRoutes: FastifyPluginAsync = async (app) => {
+\tawait app.register(browserLaunchRoute);
+};
+"""
+
+FASTIFY_BROWSER_LAUNCH_TS = """\
+import type {FastifyPluginAsync} from 'fastify';
+
+export const browserLaunchRoute: FastifyPluginAsync = async (app) => {
+\tapp.post('/launch', async () => ({}));
+};
+"""
+
+
+class TestFastify:
+ def test_plugin_routes_take_the_register_prefix(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "src/server.ts": FASTIFY_SERVER_TS,
+ "src/ops.ts": FASTIFY_OPS_TS,
+ "src/folders/index.ts": FASTIFY_FOLDERS_TS,
+ "src/browser/index.ts": FASTIFY_BROWSER_INDEX_TS,
+ "src/browser/launch.ts": FASTIFY_BROWSER_LAUNCH_TS,
+ },
+ )
+ found = _providers(root)
+ assert set(found) == {
+ "http::GET::/healthz",
+ "http::GET::/api/folders",
+ "http::POST::/api/folders/local",
+ "http::DELETE::/api/folders/{param}",
+ # A sub-plugin registered with no prefix inherits its parent's.
+ "http::POST::/api/browser/launch",
+ }
+ assert {c["framework"] for c in found.values()} == {"fastify"}
+ assert {c["origin"] for c in found.values()} == {ContractOrigin.ROUTE_REGISTRATION.value}
+
+ def test_route_objects_and_require_plugins(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "app.js": (
+ "const fastify = require('fastify')({ logger: true });\n"
+ "fastify.register(require('./routes/users'), { prefix: '/v1' });\n"
+ "fastify.route({ method: ['GET', 'HEAD'], url: '/status', handler: s });\n"
+ ),
+ "routes/users.js": (
+ "module.exports = async function (fastify, opts) {\n"
+ " fastify.route({ method: 'POST', url: '/users', handler: create });\n"
+ " fastify.get('/users/:id', { schema }, show);\n"
+ "};\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {
+ "http::GET::/status",
+ "http::POST::/v1/users",
+ "http::GET::/v1/users/{param}",
+ }
+
+ def test_chained_registers_options_variable_and_constant_urls(self, tmp_path: Path) -> None:
+ # A RealWorld Fastify shape: one options object for a chain of
+ # registers, a prefix and urls built from constants.
+ root = _write(
+ tmp_path,
+ {
+ "src/utils/server.ts": (
+ "import Fastify from 'fastify';\n"
+ "import userRoutes from '../modules/user';\n"
+ "const API_PREFIX = 'api';\n"
+ "export async function build() {\n"
+ " const fastify = Fastify();\n"
+ " const _options = { prefix: API_PREFIX };\n"
+ " fastify\n"
+ " .register(cors, { origin: true })\n"
+ " .register(userRoutes, _options);\n"
+ " return fastify;\n"
+ "}\n"
+ ),
+ "src/modules/user/index.ts": (
+ "import { FastifyInstance } from 'fastify';\n"
+ "export default async function (fastify: FastifyInstance) {\n"
+ " const apiModuleUsers = '/users';\n"
+ " fastify.route({ method: 'POST', url: `${apiModuleUsers}/login`, handler: h });\n"
+ " fastify.route({ method: 'GET', url: `${unknown}/x`, handler: h });\n"
+ "}\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {"http::POST::/api/users/login"}
+
+ def test_inline_plugins_nest_their_prefixes(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "server.js": (
+ "const app = require('fastify')();\n"
+ "app.register(async (api) => {\n"
+ " api.get('/items', list);\n"
+ " api.register(async function (v2) {\n"
+ " v2.get('/items', list2);\n"
+ " }, { prefix: '/v2' });\n"
+ "}, { prefix: '/api' });\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {"http::GET::/api/items", "http::GET::/api/v2/items"}
+
+ def test_fastify_plugin_wrapper_ignores_the_prefix(self, tmp_path: Path) -> None:
+ # fastify-plugin breaks encapsulation, and with it the prefix option.
+ root = _write(
+ tmp_path,
+ {
+ "app.js": (
+ "const app = require('fastify')();\n"
+ "app.register(require('./shared'), { prefix: '/ignored' });\n"
+ ),
+ "shared.js": (
+ "const fp = require('fastify-plugin');\n"
+ "module.exports = fp(async function (fastify) {\n"
+ " fastify.get('/ping', ping);\n"
+ "});\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {"http::GET::/ping"}
+
+ def test_a_prefix_it_cannot_read_drops_the_routes(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "app.js": (
+ "const app = require('fastify')();\n"
+ "app.register(require('./users'), { prefix: API_BASE });\n"
+ ),
+ "users.js": (
+ "module.exports = async function (fastify) { fastify.get('/users', h); };\n"
+ ),
+ },
+ )
+ assert _providers(root) == {}
+
+ def test_two_prefixes_in_one_file_drop_the_routes(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "app.js": (
+ "const app = require('fastify')();\n"
+ "const p = require('./p');\n"
+ "app.register(p, { prefix: '/a' });\n"
+ "app.register(p, { prefix: '/b' });\n"
+ ),
+ "p.js": "module.exports = async function (fastify) { fastify.get('/x', h); };\n",
+ },
+ )
+ assert _providers(root) == {}
+
+ def test_a_plugin_registered_through_an_alias_is_not_guessed(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "src/app.ts": (
+ "import Fastify from 'fastify';\nimport routes from '@/routes';\n"
+ "const app = Fastify();\napp.register(routes, { prefix: '/api' });\n"
+ ),
+ "src/routes.ts": (
+ "import type { FastifyInstance } from 'fastify';\n"
+ "export default async function (app: FastifyInstance) { app.get('/u', h); }\n"
+ ),
+ },
+ )
+ assert _providers(root) == {}
+
+ def test_a_plugin_module_without_a_fastify_import(self, tmp_path: Path) -> None:
+ # Registered from a Fastify file, so it is Fastify's, not Express's.
+ root = _write(
+ tmp_path,
+ {
+ "app.js": (
+ "const app = require('fastify')();\n"
+ "app.register(require('./users'), { prefix: '/v1' });\n"
+ ),
+ "users.js": "module.exports = async function (app) { app.get('/users', h); };\n",
+ },
+ )
+ assert _providers(root) == {"http::GET::/v1/users": {
+ "framework": "fastify", "file": "users.js",
+ "origin": ContractOrigin.ROUTE_REGISTRATION.value,
+ }}
+
+ def test_express_files_stay_with_the_express_dialect(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "server.js": (
+ "// not 'fastify' or koa-router\n"
+ "const supported = ['fastify', 'koa'];\n"
+ "const app = express();\napp.get('/users', h);\n"
+ ),
+ },
+ )
+ assert _providers(root)["http::GET::/users"]["framework"] == "express"
+
+ def test_plugin_scan_is_linear_on_a_large_flat_table(self) -> None:
+ # A data table in a Fastify file once cost seconds in the arrow scan.
+ import time
+
+ from repowise.core.ingestion.framework_routes_fastify import fastify_plugins
+
+ content = "import Fastify from 'fastify';\n" + " key: 'value',\n" * 20000
+ start = time.perf_counter()
+ fastify_plugins(content, {"key", "app"})
+ assert time.perf_counter() - start < 2.0
+
+ def test_type_argument_between_verb_and_call(self) -> None:
+ (route,) = list(express_routes("app.get<{Params: {id: string}}>('/x/:id', h)"))
+ assert route.path == "/x/:id"
+
+
+# ---------------------------------------------------------------------------
+# hapi
+# ---------------------------------------------------------------------------
+
+
+class TestHapi:
+ def test_server_route_objects(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "server.js": (
+ "const Hapi = require('@hapi/hapi');\n"
+ "const server = Hapi.server({ port: 3000 });\n"
+ "server.route({ method: 'GET', path: '/accounts/{id}', handler: get });\n"
+ "server.route([\n"
+ " { method: ['PUT', 'PATCH'], path: '/accounts/{id}', options: { handler: put } },\n"
+ " { method: '*', path: '/fallback', handler: any },\n"
+ "]);\n"
+ ),
+ },
+ )
+ found = _providers(root)
+ assert set(found) == {
+ "http::GET::/accounts/{param}",
+ "http::PUT::/accounts/{param}",
+ "http::PATCH::/accounts/{param}",
+ "http::*::/fallback",
+ }
+ assert {c["framework"] for c in found.values()} == {"hapi"}
+
+ def test_plugin_prefix_and_route_table_modules(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "server.js": (
+ "const Hapi = require('@hapi/hapi');\n"
+ "const server = Hapi.server();\n"
+ "await server.register({ plugin: require('./api'), routes: { prefix: '/api' } });\n"
+ ),
+ "api/index.js": (
+ "exports.plugin = {\n"
+ " name: 'api',\n"
+ " register: async (server) => { server.route(require('./orders')); },\n"
+ "};\n"
+ ),
+ # A plain route table: no hapi import, read because it is mounted.
+ "api/orders.js": (
+ "module.exports = [\n"
+ " { method: 'GET', path: '/orders', handler: list },\n"
+ " { method: 'POST', path: '/orders', handler: create },\n"
+ "];\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {"http::GET::/api/orders", "http::POST::/api/orders"}
+
+ def test_optional_param(self, tmp_path: Path) -> None:
+ root = _write(tmp_path, {"server.js": (
+ "const server = require('@hapi/hapi').server();\n"
+ "server.route({ method: 'GET', path: '/users/{id?}', handler: h });\n"
+ )})
+ assert set(_providers(root)) == {"http::GET::/users/{param}"}
+
+ def test_prefix_in_the_register_options(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "server.js": (
+ "const Hapi = require('@hapi/hapi');\nconst server = Hapi.server();\n"
+ "server.register({ plugin: require('./api') }, { routes: { prefix: '/v1' } });\n"
+ ),
+ "api.js": (
+ "exports.plugin = { register: async (server) => {\n"
+ " server.route({ method: 'GET', path: '/u', handler: h });\n} };\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {"http::GET::/v1/u"}
+
+ def test_route_table_factory_module(self, tmp_path: Path) -> None:
+ # hapi 16 style: a plugin passes `Routes(server)` to `server.route`.
+ root = _write(
+ tmp_path,
+ {
+ "lib/users/index.js": (
+ "const Routes = require('./routes');\n"
+ "const register = (server, options, next) => {\n"
+ " server.route(Routes(server));\n next();\n};\n"
+ "module.exports = register;\n"
+ ),
+ "lib/users/routes.js": (
+ "module.exports = (server) => {\n"
+ " const handlers = require('./handlers')(server);\n"
+ " return [\n"
+ " { method: 'GET', path: '/user', config: { auth: 'jwt' }, handler: handlers.get },\n"
+ " ];\n};\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {"http::GET::/user"}
+
+ def test_request_options_are_not_routes(self, tmp_path: Path) -> None:
+ # Node's http.request options carry method and path but no handler.
+ root = _write(
+ tmp_path,
+ {
+ "client.js": (
+ "const server = require('@hapi/hapi').server();\n"
+ "http.request({ method: 'GET', path: '/remote', host: 'x' });\n"
+ "// server.route({ method: 'GET', path: '/commented', handler: h });\n"
+ ),
+ "table.js": "module.exports = [{ method: 'GET', path: '/unmounted', handler: h }];\n",
+ },
+ )
+ assert _providers(root) == {}
+
+
+# ---------------------------------------------------------------------------
+# Koa
+# ---------------------------------------------------------------------------
+
+
+class TestKoa:
+ def test_router_prefix_is_served(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "server.js": (
+ "const Router = require('@koa/router');\n"
+ "const router = new Router({ prefix: '/api' });\n"
+ "const carts = new Router();\n"
+ "carts.prefix('/carts');\n"
+ "router.get('/health', h);\n"
+ "carts.get('/:id', show);\n"
+ "carts.post('/', create);\n"
+ ),
+ },
+ )
+ found = _providers(root)
+ assert set(found) == {
+ "http::GET::/api/health",
+ "http::GET::/carts/{param}",
+ "http::POST::/carts",
+ }
+ assert {c["framework"] for c in found.values()} == {"koa"}
+
+ def test_router_modules_nested_under_a_prefixed_router(self, tmp_path: Path) -> None:
+ # The RealWorld Koa layout: route modules export `router.routes()`, an
+ # index nests them in `api`, and `api` is served under `/api`.
+ root = _write(
+ tmp_path,
+ {
+ "src/routes/index.js": (
+ "const Router = require('koa-router');\n"
+ "const router = new Router();\n"
+ "const api = new Router();\n"
+ "const users = require('./users-router');\n"
+ "api.use(users);\n"
+ "api.use('/v2', require('./tags-router'));\n"
+ "router.use('/api', api.routes());\n"
+ "module.exports = router;\n"
+ ),
+ "src/routes/users-router.js": (
+ "const Router = require('koa-router');\n"
+ "const router = new Router();\n"
+ "router.get('/user', h);\n"
+ "router.del('/users/:id', auth, remove);\n"
+ "module.exports = router.routes();\n"
+ ),
+ "src/routes/tags-router.js": (
+ "import Router from '@koa/router';\n"
+ "const router = new Router({ prefix: '/tags' });\n"
+ "router.get('/', list);\n"
+ "export default router.routes();\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {
+ "http::GET::/api/user",
+ "http::DELETE::/api/users/{param}",
+ "http::GET::/api/v2/tags",
+ }
+
+ def test_wrapped_or_twice_placed_routers_are_not_guessed(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "server.js": (
+ "const Router = require('@koa/router');\n"
+ "const r = new Router();\nconst c = new Router();\n"
+ "const a = new Router({ prefix: '/a' });\nconst b = new Router({ prefix: '/b' });\n"
+ "app.use(mount('/api', r.routes()));\n"
+ "a.use(c.routes());\nb.use(c.routes());\n"
+ "r.get('/x', h);\nc.get('/y', h);\na.get('/z', h);\n"
+ ),
+ },
+ )
+ assert set(_providers(root)) == {"http::GET::/a/z"}
+
+ def test_a_prefix_it_cannot_read_drops_the_routes(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "server.js": (
+ "const Router = require('@koa/router');\n"
+ "const router = new Router({ prefix: config.base });\n"
+ "router.get('/x', h);\n"
+ ),
+ },
+ )
+ assert _providers(root) == {}
+
+
+# ---------------------------------------------------------------------------
+# Next.js pages/api
+# ---------------------------------------------------------------------------
+
+
+class TestNextPagesApi:
+ def test_path_from_location(self) -> None:
+ assert next_pages_api_path("pages/api/users/[id].ts") == "/api/users/{id}"
+ assert next_pages_api_path("src/pages/api/posts/index.js") == "/api/posts"
+ assert next_pages_api_path("pages/api/docs/[[...slug]].tsx") == "/api/docs/{slug}"
+ assert next_pages_api_path("pages/users/[id].tsx") is None # a page, not an API route
+ assert next_pages_api_path("pages/api/users.test.ts") is None
+ assert next_pages_api_path("pages/api/readme.md") is None
+ assert next_pages_api_path("pages/api/types.d.ts") is None
+ assert next_pages_api_path("pages/api/__tests__/users.ts") is None
+
+ def test_verbs_from_method_checks(self) -> None:
+ assert [v for v, _ in next_pages_api_verbs(
+ "export default function h(req, res) {\n"
+ " if (req.method !== 'POST') return res.status(405).end();\n}\n"
+ )] == ["POST"]
+ assert [v for v, _ in next_pages_api_verbs(
+ "export default async (req, res) => {\n"
+ " switch (req.method) {\n case 'GET': break;\n case 'PUT': break;\n }\n};\n"
+ )] == ["GET", "PUT"]
+ assert [v for v, _ in next_pages_api_verbs("module.exports = (req, res) => res.end();\n")] == ["*"]
+ assert next_pages_api_verbs("export const config = {};\n") is None
+ # A helper module kept under pages/api touches no request or response.
+ assert next_pages_api_verbs("export default function slugify(s) { return s; }\n") is None
+
+ def test_contracts(self, tmp_path: Path) -> None:
+ root = _write(
+ tmp_path,
+ {
+ "pages/api/users/[id].ts": (
+ "export default function handler(req, res) {\n"
+ " if (req.method === 'GET') return res.json({});\n"
+ " if (req.method === 'DELETE') return res.end();\n}\n"
+ ),
+ "pages/api/health.js": "export default (req, res) => res.end('ok');\n",
+ "pages/index.tsx": "export default function Home() { return null; }\n",
+ },
+ )
+ found = _providers(root)
+ assert set(found) == {
+ "http::GET::/api/users/{param}",
+ "http::DELETE::/api/users/{param}",
+ "http::*::/api/health",
+ }
+ assert {c["framework"] for c in found.values()} == {"next-pages"}