Skip to main content

code_system_graph_core/
router_mounts.rs

1//! Repository-level composition of router prefixes declared across source files.
2//!
3//! Extractors record the router each provider route is registered on and every mount of one
4//! router under a prefix on another. Composition resolves those references per repository, through
5//! file-local names, relative and package imports, and function paths, then rewrites each route
6//! path with every prefix chain that reaches it.
7
8use std::collections::{BTreeMap, BTreeSet};
9
10use crate::repository_symbols::{
11    RepositorySourceFile, RepositorySymbols, SymbolFile, SymbolKey, files_by_repository
12};
13use crate::{
14    SourceEpistemicStatus, SourceLanguage, SourceObservation, SourceRole, SymbolRef, normalize_source_http_path
15};
16
17/// Longest mount chain followed from a route to the application root.
18const MAX_MOUNT_DEPTH: usize = 8;
19/// Most composed paths retained for one router.
20const MAX_COMPOSED_PREFIXES: usize = 16;
21
22/// Rewrites provider paths with the router prefixes mounted above them.
23///
24/// The result has one observation list per input file, in input order. Mount observations are
25/// consumed, a route on a router mounted at several places is repeated once per composed path,
26/// and routes whose router is not mounted anywhere keep their path.
27#[must_use]
28pub fn compose_router_mounts(files: &[RepositorySourceFile<'_>]) -> Vec<Vec<SourceObservation>> {
29    let by_repository = files_by_repository(files);
30    let mut output = files
31        .iter()
32        .map(|file| file.observations.to_vec())
33        .collect::<Vec<_>>();
34    for members in by_repository.into_values() {
35        let repository = RepositoryRouters::new(files, &members);
36        if repository.mounts.is_empty() {
37            for &index in &members {
38                output[index].retain(|observation| observation.role != SourceRole::Mount);
39            }
40            continue;
41        }
42        let mut cache = BTreeMap::new();
43        for (local, &index) in members.iter().enumerate() {
44            output[index] = repository.rewrite(local, &mut cache);
45        }
46    }
47    output
48}
49
50struct RepositoryRouters<'a> {
51    symbols: RepositorySymbols<'a>,
52    mounts: BTreeMap<SymbolKey, Vec<(Option<SymbolKey>, String)>>,
53}
54
55impl<'a> RepositoryRouters<'a> {
56    fn new(files: &'a [RepositorySourceFile<'a>], members: &[usize]) -> Self {
57        let mut symbols = RepositorySymbols::new(
58            members
59                .iter()
60                .map(|&index| SymbolFile {
61                    path: files[index].path,
62                    observations: files[index].observations,
63                })
64                .collect(),
65        );
66        for local in 0..members.len() {
67            for observation in symbols.files()[local].observations {
68                for reference in [&observation.router, &observation.mount_parent]
69                    .into_iter()
70                    .flatten()
71                {
72                    if let SymbolRef::Function(name) = reference {
73                        symbols.declare_function(local, name);
74                    }
75                }
76            }
77        }
78        let mut mounts = BTreeMap::<SymbolKey, Vec<(Option<SymbolKey>, String)>>::new();
79        for local in 0..members.len() {
80            for observation in symbols.files()[local]
81                .observations
82                .iter()
83                .filter(|observation| observation.role == SourceRole::Mount)
84            {
85                let Some(child) = observation
86                    .router
87                    .as_ref()
88                    .and_then(|reference| symbols.resolve(local, reference))
89                else {
90                    continue;
91                };
92                let parent = observation
93                    .mount_parent
94                    .as_ref()
95                    .and_then(|reference| symbols.resolve(local, reference));
96                if parent.as_ref() == Some(&child) {
97                    continue;
98                }
99                let prefix = observation
100                    .path
101                    .as_deref()
102                    .map(prefix_text)
103                    .unwrap_or_default();
104                mounts.entry(child).or_default().push((parent, prefix));
105            }
106        }
107        for edges in mounts.values_mut() {
108            edges.sort();
109            edges.dedup();
110        }
111        Self { symbols, mounts }
112    }
113
114    fn rewrite(
115        &self,
116        local: usize,
117        cache: &mut BTreeMap<SymbolKey, Vec<String>>,
118    ) -> Vec<SourceObservation> {
119        let observations = self.symbols.files()[local].observations;
120        let mut output = Vec::with_capacity(observations.len());
121        for observation in observations {
122            match observation.role {
123                SourceRole::Mount => {}
124                SourceRole::Provider => {
125                    let prefixes = observation
126                        .router
127                        .as_ref()
128                        .and_then(|reference| self.symbols.resolve(local, reference))
129                        .map(|key| self.prefixes(&key, cache))
130                        .unwrap_or_default();
131                    match (&observation.path, prefixes.as_slice()) {
132                        (Some(path), [_, ..]) if prefixes != [""] => {
133                            output.extend(prefixes.iter().map(|prefix| {
134                                let mut composed = observation.clone();
135                                composed.path =
136                                    Some(normalize_source_http_path(&format!("{prefix}{path}")));
137                                composed
138                            }));
139                        }
140                        _ => output.push(observation.clone()),
141                    }
142                }
143                SourceRole::Consumer
144                | SourceRole::Test
145                | SourceRole::Factory
146                | SourceRole::Call
147                | SourceRole::Client => {
148                    output.push(observation.clone());
149                }
150            }
151        }
152        output
153    }
154
155    /// Returns every prefix chain from `key` to a root, outermost prefix first.
156    fn prefixes(
157        &self,
158        key: &SymbolKey,
159        cache: &mut BTreeMap<SymbolKey, Vec<String>>,
160    ) -> Vec<String> {
161        if let Some(cached) = cache.get(key) {
162            return cached.clone();
163        }
164        let mut visiting = Vec::new();
165        let mut prefixes = self.walk(key, &mut visiting);
166        if prefixes.is_empty() {
167            prefixes.push(String::new());
168        }
169        cache.insert(key.clone(), prefixes.clone());
170        prefixes
171    }
172
173    /// Chains through a cycle or deeper than [`MAX_MOUNT_DEPTH`] are dropped.
174    fn walk(&self, key: &SymbolKey, visiting: &mut Vec<SymbolKey>) -> Vec<String> {
175        let Some(edges) = self.mounts.get(key) else {
176            return vec![String::new()];
177        };
178        if visiting.len() >= MAX_MOUNT_DEPTH || visiting.contains(key) {
179            return Vec::new();
180        }
181        visiting.push(key.clone());
182        let mut prefixes = BTreeSet::new();
183        for (parent, prefix) in edges {
184            let outer = parent
185                .as_ref()
186                .map_or_else(|| vec![String::new()], |parent| self.walk(parent, visiting));
187            prefixes.extend(outer.into_iter().map(|outer| format!("{outer}{prefix}")));
188        }
189        visiting.pop();
190        prefixes.into_iter().take(MAX_COMPOSED_PREFIXES).collect()
191    }
192}
193
194/// Normalized prefix text without a trailing slash; the root prefix is empty.
195fn prefix_text(path: &str) -> String {
196    let normalized = normalize_source_http_path(path);
197    if normalized == "/" {
198        String::new()
199    } else {
200        normalized
201    }
202}
203
204/// Builds a mount observation recorded by a source extractor.
205#[must_use]
206pub(crate) fn mount_observation(
207    language: SourceLanguage,
208    framework: crate::SourceFramework,
209    child: SymbolRef,
210    parent: Option<SymbolRef>,
211    prefix: Option<&str>,
212    lines: crate::SourceLineRange,
213) -> SourceObservation {
214    SourceObservation {
215        language,
216        framework,
217        role: SourceRole::Mount,
218        method: None,
219        path: Some(normalize_source_http_path(prefix.unwrap_or("/"))),
220        symbol_name: None,
221        symbol_start_line: None,
222        related_symbol: None,
223        related_path: None,
224        authority: None,
225        router: Some(child),
226        mount_parent: parent,
227        url: None,
228        call: None,
229        lines,
230        status: SourceEpistemicStatus::Confirmed,
231        confidence: 1.0,
232        warnings: Vec::new(),
233    }
234}
235
236#[cfg(test)]
237mod tests {
238    use code_system_graph_model::RepoId;
239
240    use super::{compose_router_mounts, mount_observation};
241    use crate::{
242        RepositorySourceFile, SourceEpistemicStatus, SourceFramework, SourceLanguage, SourceLineRange, SourceObservation, SourceRole, SymbolRef
243    };
244
245    const LINES: SourceLineRange = SourceLineRange { start: 1, end: 1 };
246
247    fn route(language: SourceLanguage, path: &str, router: SymbolRef) -> SourceObservation {
248        SourceObservation {
249            language,
250            framework: SourceFramework::Express,
251            role: SourceRole::Provider,
252            method: Some("GET".to_owned()),
253            path: Some(path.to_owned()),
254            symbol_name: Some("handler".to_owned()),
255            symbol_start_line: None,
256            related_symbol: None,
257            related_path: None,
258            authority: None,
259            router: Some(router),
260            mount_parent: None,
261            url: None,
262            call: None,
263            lines: LINES,
264            status: SourceEpistemicStatus::Confirmed,
265            confidence: 1.0,
266            warnings: Vec::new(),
267        }
268    }
269
270    fn mount(
271        language: SourceLanguage,
272        child: SymbolRef,
273        parent: Option<SymbolRef>,
274        prefix: &str,
275    ) -> SourceObservation {
276        mount_observation(
277            language,
278            SourceFramework::Express,
279            child,
280            parent,
281            Some(prefix),
282            LINES,
283        )
284    }
285
286    fn composed_paths(files: &[(&str, Vec<SourceObservation>)]) -> Vec<String> {
287        let repo = RepoId::new("repo:api");
288        let inputs = files
289            .iter()
290            .map(|(path, observations)| RepositorySourceFile {
291                repo_id: &repo,
292                path,
293                observations,
294            })
295            .collect::<Vec<_>>();
296        let mut paths = compose_router_mounts(&inputs)
297            .into_iter()
298            .flatten()
299            .filter_map(|observation| observation.path)
300            .collect::<Vec<_>>();
301        paths.sort();
302        paths
303    }
304
305    fn local(name: &str) -> SymbolRef {
306        SymbolRef::Local(name.to_owned())
307    }
308
309    #[test]
310    fn script_imports_and_default_exports_should_compose_nested_prefixes() {
311        let js = SourceLanguage::TypeScript;
312        let files = [
313            (
314                "src/routes/orders.ts",
315                vec![
316                    route(js, "/:id", local("router")),
317                    mount(js, local("router"), Some(local("default")), "/"),
318                ],
319            ),
320            (
321                "src/routes/index.ts",
322                vec![mount(
323                    js,
324                    SymbolRef::Import {
325                        module: "./orders.js".to_owned(),
326                        name: "default".to_owned(),
327                    },
328                    Some(local("api")),
329                    "/orders",
330                )],
331            ),
332            (
333                "src/app.ts",
334                vec![
335                    mount(
336                        js,
337                        SymbolRef::Import {
338                            module: "./routes".to_owned(),
339                            name: "api".to_owned(),
340                        },
341                        Some(local("app")),
342                        "/v1",
343                    ),
344                    mount(
345                        js,
346                        SymbolRef::Import {
347                            module: "./routes/index".to_owned(),
348                            name: "api".to_owned(),
349                        },
350                        Some(local("app")),
351                        "/v2/",
352                    ),
353                ],
354            ),
355        ];
356
357        assert_eq!(
358            composed_paths(&files),
359            ["/v1/orders/:id".to_owned(), "/v2/orders/:id".to_owned()]
360        );
361    }
362
363    #[test]
364    fn python_modules_should_resolve_absolute_and_relative_imports() {
365        let py = SourceLanguage::Python;
366        let files = [
367            (
368                "src/app/api/users.py",
369                vec![route(py, "/users/{id}", local("router"))],
370            ),
371            (
372                "src/app/api/__init__.py",
373                vec![mount(
374                    py,
375                    SymbolRef::Import {
376                        module: ".users".to_owned(),
377                        name: "router".to_owned(),
378                    },
379                    Some(local("api")),
380                    "/internal",
381                )],
382            ),
383            (
384                "src/app/main.py",
385                vec![mount(
386                    py,
387                    SymbolRef::Import {
388                        module: "app".to_owned(),
389                        name: "api.api".to_owned(),
390                    },
391                    Some(local("app")),
392                    "/v1",
393                )],
394            ),
395        ];
396
397        assert_eq!(
398            composed_paths(&files),
399            ["/v1/internal/users/{id}".to_owned()]
400        );
401    }
402
403    #[test]
404    fn function_routers_should_resolve_by_module_path() {
405        let rust = SourceLanguage::Rust;
406        let files = [
407            (
408                "crates/api/src/orders/mod.rs",
409                vec![route(
410                    rust,
411                    "/{id}",
412                    SymbolRef::Function("routes".to_owned()),
413                )],
414            ),
415            (
416                "crates/api/src/users.rs",
417                vec![route(
418                    rust,
419                    "/{id}",
420                    SymbolRef::Function("routes".to_owned()),
421                )],
422            ),
423            (
424                "crates/api/src/main.rs",
425                vec![
426                    mount(
427                        rust,
428                        SymbolRef::Call("crate::orders::routes".to_owned()),
429                        Some(SymbolRef::Function("app".to_owned())),
430                        "/orders",
431                    ),
432                    mount(
433                        rust,
434                        SymbolRef::Call("routes".to_owned()),
435                        Some(SymbolRef::Function("app".to_owned())),
436                        "/ambiguous",
437                    ),
438                ],
439            ),
440        ];
441
442        assert_eq!(
443            composed_paths(&files),
444            ["/orders/{id}".to_owned(), "/{id}".to_owned()]
445        );
446    }
447
448    fn extracted_routes(files: &[(&str, &str)]) -> Vec<String> {
449        let repo = RepoId::new("repo:api");
450        let observations = files
451            .iter()
452            .map(|(path, source)| {
453                let extension = path.rsplit_once('.').map(|(_, extension)| extension);
454                match extension {
455                    Some("py") => crate::parse_python_source(source),
456                    Some("rs") => crate::parse_rust_source(source),
457                    Some("go") => crate::parse_go_source(source),
458                    Some("java") => crate::parse_java_source(source),
459                    Some("js") => crate::parse_javascript_source_at_path(path, source),
460                    _ => crate::parse_typescript_source_at_path(path, source),
461                }
462            })
463            .collect::<Vec<_>>();
464        let inputs = files
465            .iter()
466            .zip(&observations)
467            .map(|((path, _), observations)| RepositorySourceFile {
468                repo_id: &repo,
469                path,
470                observations,
471            })
472            .collect::<Vec<_>>();
473        let mut routes = compose_router_mounts(&inputs)
474            .into_iter()
475            .flatten()
476            .filter(|observation| {
477                observation.role == SourceRole::Provider
478                    && observation.status == SourceEpistemicStatus::Confirmed
479            })
480            .filter_map(|observation| {
481                Some(format!(
482                    "{} {} {}",
483                    observation.method?, observation.path?, observation.symbol_name?
484                ))
485            })
486            .collect::<Vec<_>>();
487        routes.sort();
488        routes
489    }
490
491    #[test]
492    fn fastapi_and_flask_mounts_should_compose_across_modules() {
493        let routes = extracted_routes(&[
494            (
495                "app/api/users.py",
496                "from fastapi import APIRouter\nrouter = APIRouter(prefix=\"/users\")\n\n@router.get(\"/{user_id}\")\ndef read_user(user_id: int):\n    return {}\n",
497            ),
498            (
499                "app/main.py",
500                "from fastapi import FastAPI\nfrom app.api import users\nfrom app.api.users import router as users_router\napp = FastAPI()\napp.include_router(users.router, prefix=\"/v1\")\napp.include_router(users_router, prefix=\"/v2\")\n",
501            ),
502            (
503                "shop/views.py",
504                "from flask import Blueprint\nbp = Blueprint(\"orders\", __name__, url_prefix=\"/orders\")\n\n@bp.route(\"/<int:order_id>\", methods=[\"GET\"])\ndef show(order_id):\n    return ''\n",
505            ),
506            (
507                "shop/__init__.py",
508                "from flask import Flask\nfrom .views import bp\napp = Flask(__name__)\napp.register_blueprint(bp, url_prefix=\"/shop\")\n",
509            ),
510        ]);
511
512        assert_eq!(
513            routes,
514            [
515                "GET /shop/orders/<int:order_id> show",
516                "GET /v1/users/{user_id} read_user",
517                "GET /v2/users/{user_id} read_user",
518            ]
519        );
520    }
521
522    #[test]
523    fn express_and_nest_mounts_should_compose_across_modules() {
524        let routes = extracted_routes(&[
525            (
526                "src/routes/orders.ts",
527                "import { Router } from 'express';\nconst router = Router();\nrouter.get('/:id', getOrder);\nexport default router;\n",
528            ),
529            (
530                "src/routes/users.js",
531                "const express = require('express');\nfunction buildUsers() {\n  const users = express.Router();\n  users.get('/:id', getUser);\n  return users;\n}\nmodule.exports = { buildUsers };\n",
532            ),
533            (
534                "src/app.ts",
535                "import express from 'express';\nimport orders from './routes/orders';\nconst { buildUsers } = require('./routes/users');\nconst app = express();\nconst api = express.Router();\napi.use('/orders', orders);\napi.use('/users', authenticate, buildUsers());\napp.use('/api', api);\n",
536            ),
537            (
538                "src/catalog/catalog.controller.ts",
539                "import { Controller, Get } from '@nestjs/common';\n@Controller('catalog')\nexport class CatalogController {\n  @Get(':sku')\n  findOne() {}\n  @Get()\n  findAll() {}\n}\n",
540            ),
541            (
542                "src/main.ts",
543                "import { NestFactory } from '@nestjs/core';\nasync function bootstrap() {\n  const app = await NestFactory.create(AppModule);\n  app.setGlobalPrefix('v2');\n}\n",
544            ),
545        ]);
546
547        assert_eq!(
548            routes,
549            [
550                "GET /api/orders/:id getOrder",
551                "GET /api/users/:id getUser",
552                "GET /v2/catalog findAll",
553                "GET /v2/catalog/:sku findOne",
554            ]
555        );
556    }
557
558    #[test]
559    fn spring_class_mappings_should_prefix_method_mappings() {
560        let routes = extracted_routes(&[(
561            "src/main/java/shop/OrderController.java",
562            "import org.springframework.web.bind.annotation.*;\n@RestController\n@RequestMapping(\"/api/orders\")\npublic class OrderController {\n  @GetMapping(\"/{id}\")\n  public Order get(@PathVariable long id) { return null; }\n  @PostMapping\n  public Order create() { return null; }\n}\n",
563        )]);
564
565        assert_eq!(
566            routes,
567            ["GET /api/orders/{id} get", "POST /api/orders create"]
568        );
569    }
570
571    #[test]
572    fn gin_chi_and_net_http_mounts_should_compose_across_packages() {
573        let routes = extracted_routes(&[
574            (
575                "internal/routes/orders.go",
576                "package routes\n\nimport \"github.com/gin-gonic/gin\"\n\nfunc RegisterOrders(rg *gin.RouterGroup) {\n\trg.GET(\"/:id\", getOrder)\n}\n",
577            ),
578            (
579                "cmd/api/main.go",
580                "package main\n\nimport (\n\t\"github.com/gin-gonic/gin\"\n\t\"example.com/internal/routes\"\n)\n\nfunc main() {\n\tr := gin.Default()\n\tv1 := r.Group(\"/v1\")\n\t{\n\t\tv1.GET(\"/health\", health)\n\t}\n\troutes.RegisterOrders(v1.Group(\"/orders\"))\n}\n",
581            ),
582            (
583                "billing/server.go",
584                "package billing\n\nimport (\n\t\"net/http\"\n\t\"github.com/go-chi/chi/v5\"\n)\n\nfunc invoices() http.Handler {\n\tr := chi.NewRouter()\n\tr.Get(\"/{id}\", getInvoice)\n\treturn r\n}\n\nfunc Router() http.Handler {\n\tr := chi.NewRouter()\n\tr.Route(\"/billing\", func(r chi.Router) {\n\t\tr.Get(\"/status\", status)\n\t\tr.Mount(\"/invoices\", invoices())\n\t})\n\tmux := http.NewServeMux()\n\tmux.HandleFunc(\"GET /payments/{id}\", getPayment)\n\treturn r\n}\n",
585            ),
586        ]);
587
588        assert_eq!(
589            routes,
590            [
591                "GET /billing/invoices/{id} getInvoice",
592                "GET /billing/status status",
593                "GET /payments/{id} getPayment",
594                "GET /v1/health health",
595                "GET /v1/orders/:id getOrder",
596            ]
597        );
598    }
599
600    #[test]
601    fn axum_and_actix_mounts_should_compose_across_modules() {
602        let routes = extracted_routes(&[
603            (
604                "orders/src/orders.rs",
605                "use axum::{routing::get, Router};\npub fn routes() -> Router {\n    Router::new().route(\"/{id}\", get(get_order))\n}\n",
606            ),
607            (
608                "orders/src/main.rs",
609                "use axum::{routing::get, Router};\nfn app() -> Router {\n    let api = Router::new().route(\"/health\", get(health));\n    Router::new()\n        .nest(\"/orders\", crate::orders::routes())\n        .nest(\"/api\", api)\n}\n",
610            ),
611            (
612                "billing/src/handlers.rs",
613                "use actix_web::{get, web, HttpResponse};\n#[get(\"/invoices/{id}\")]\nasync fn get_invoice() -> HttpResponse { HttpResponse::Ok().finish() }\npub fn config(cfg: &mut web::ServiceConfig) {\n    cfg.service(web::scope(\"/admin\").route(\"/audit\", web::get().to(audit)));\n}\n",
614            ),
615            (
616                "billing/src/main.rs",
617                "use actix_web::{web, App, HttpServer};\nasync fn main() {\n    HttpServer::new(|| {\n        App::new()\n            .service(web::scope(\"/api\").service(handlers::get_invoice))\n            .configure(handlers::config)\n    });\n}\n",
618            ),
619        ]);
620
621        assert_eq!(
622            routes,
623            [
624                "GET /admin/audit audit",
625                "GET /api/health health",
626                "GET /api/invoices/{id} get_invoice",
627                "GET /orders/{id} get_order",
628            ]
629        );
630    }
631
632    #[test]
633    fn mount_cycles_and_unresolved_routers_should_keep_route_paths() {
634        let go = SourceLanguage::Go;
635        let files = [(
636            "internal/http/routes.go",
637            vec![
638                route(go, "/orders", local("a")),
639                route(go, "/users", local("lonely")),
640                mount(go, local("a"), Some(local("b")), "/a"),
641                mount(go, local("b"), Some(local("a")), "/b"),
642                mount(
643                    go,
644                    SymbolRef::Call("missing.Register".to_owned()),
645                    None,
646                    "/x",
647                ),
648            ],
649        )];
650
651        assert_eq!(
652            composed_paths(&files),
653            ["/orders".to_owned(), "/users".to_owned()]
654        );
655    }
656}