Skip to content

fix(express): resolve mount prefixes for routers in other files - #22

Merged
danieloceno merged 4 commits into
mainfrom
fix/8-express-cross-file-mounts
Nov 15, 2026
Merged

danieloceno merged 4 commits into
mainfrom
fix/8-express-cross-file-mounts

Conversation

@danieloceno

Copy link
Copy Markdown
Contributor

Closes #8

What changed

  • New lib/parsers/express-modules.mjs (pure, no AST): resolves relative specifiers (./x.js, ./x, ./dir to dir/index.*), composes mount chains across files (nesting, cycles, at most 64 prefixes, all or nothing) and rewrites the endpoints. joinPath moved here from express.mjs.
  • lib/parsers/express.mjs: per file it also records exports (ESM export, CommonJS module.exports and exports.x), imports, and X.use([prefix, ...middleware,] importedRouter) mounts, where the last argument is the router. It reuses the router recognition from Express: any router name, route() chains, router-level auth #7 (analyzeBindings, isStableRouterBinding, isPathlessUse, collectUseMarkers) and the shared candidate file list: no new directory walk, no new dependency. After the file loop, routes get their full prefix, and the mount middleware becomes their auth markers.
  • How "never emit a bare path as resolved" is applied: a route stays resolved only when every mount from a root express() app down to it is known and static. Otherwise it gets resolved: false, path: null and unresolvedReason: "mount-prefix-cross-file". That covers an exported Router() that no resolved mount reaches (alias or package imports, mounts in .ts files, a scan of a sub-directory, factory exports, cycles), a router mounted both in its own file and from another file, a router nested on another local router inside a chain, and a router on an app that is itself mounted. An express() app that nothing mounts is a root. A dynamic prefix keeps the existing reason mount-prefix-not-static.
  • lib/utils.mjs sortEndpoints sorts null paths last. The old comparator was not a total order once null and string paths mixed, so reversed input gave different output.
  • lib/capabilities.mjs: crossFileMountPrefix: true, a new crossFileMounts description and the reason mount-prefix-cross-file. README (Express row, capabilities example, limits) and CHANGELOG.md [Unreleased].
  • Tests: fixture test/fixtures/express-multifile/ (the issue's reproduction plus admin, nested, cycle, alias, factory, dynamic, sub-directory and same-file cases), new cases in test/parser-express.mjs, a reversed-order case in test/determinism.mjs, and test/capabilities.mjs.
  • test/fixtures/express-router-negatives/conditional-use.js and unless.js (from Express: any router name, route() chains, router-level auth #7) exported their routers only as a leftover. Under the new rule those unmounted exported routers became unresolved, and the tests stopped checking what they exist for: the auth markers of a path-less use(). The two export lines are removed, and the marker results are unchanged.
  • main is merged into the branch twice (after docs: remove links to private Stelnyx repositories #19 and chore(deps): clear audit advisories, bump ESLint 10, drop Node 18 #20, then after feat(nest): detect global guards and setGlobalPrefix #21). Only the [Unreleased] section of CHANGELOG.md overlapped.

Proof per acceptance criterion

  • Fixture express-multifile: routes/users.js yields GET /api/users and POST /api/users, both resolved. On main, the same files give bare GET / and POST /, marked resolved.
  • app.use("/admin", requireAuth, adminRouter) across files: routes/admin.js yields DELETE /admin/wipe GUARDED (marker requireAuth).
  • Imports that cannot be resolved: the alias import @/routes/ghost, the factory export in routes/legacy.js and the cycle in cycle/a.js and cycle/b.js all yield path: null, resolved: false and unresolvedReason: "mount-prefix-cross-file". The dynamic prefix in routes/dyn.js yields mount-prefix-not-static.
  • Determinism: test/determinism.mjs passes, and a new case that feeds the candidate files in reversed order gets identical output.
  • npm test passes. No golden number moved: test/golden-apigate.mjs passes unchanged, because the sample app has no exported router that the new rule touches.
  • Regression proof: every review round added a fixture that fails without its fix. For example, samefile6 and samefile7 give GET /r/x/z resolved without the last guard, and GET null mount-prefix-cross-file with it.

Gate

npm ci && npm run lint && npm test at 29c2cc9, after merging main (so with ESLint 10):

  • Node v22.23.4: exit 0. eslint reports nothing; all 20 suites end N passed, 0 failed.
  • Node v24.22.1: exit 0, same result.

Not done (documented in README and parserCapabilities)

  • Only Program-level routers are linked. A router that is a function parameter or this.app is treated as a root.
  • Re-export barrels, TypeScript path aliases, dynamic require and router factories are not followed (the last three are out of scope in the issue). TypeScript files go through the regex extractor and are outside the cross-file rule.
  • A router mounted on two express() apps in the same file reports only the last app's prefix. This same-file rule predates this change, and the reported path is one that Express really serves.
  • When an app's own cross-file mount has a dynamic prefix, its routes report mount-prefix-cross-file instead of mount-prefix-not-static. They are unresolved either way.
  • Path-less mount middleware imported from another file (app.use(requireAuth, router)) makes the prefix dynamic: mount-prefix-not-static.

Suggested labels: bug

@danieloceno

Copy link
Copy Markdown
Contributor Author

Second-model review

  1. non-blocking (confirmed, predates this change), lib/parsers/express.mjs (routerMounts): a router mounted on two express() apps in one file (a1.use("/a", r); a2.use("/b", r)) reports only the last app's prefix (GET /b/x/z), while Express also serves /a/x/z. The same-file "last mount wins" rule is older than this PR, and the reported path is real, so it does not break the rule that no partial or stacked prefix is marked resolved. Fix: a follow-up issue, or list it as a README limit.
  2. non-blocking (confirmed), lib/parsers/express-modules.mjs:108: when an app's own cross-file mount has a dynamic prefix, the routes on its routers report mount-prefix-cross-file instead of mount-prefix-not-static. The route is unresolved either way, so the posture is right. Fix: pass the upstream fail reason through when it is set.
  3. Verified: the last blocking finding is fixed. A router whose same-file owner is an express() app that is itself mounted (a sub-app in the same file, or an exported app mounted from another file) got a partial resolved prefix, /r/x/z where Express serves /v/r/x/z. chainsFor (express-modules.mjs:104-109) now accepts that app as a root only if it has no same-file mount, no unresolved same-file mount and no cross-file chain, and rootMounted maps each router to its owning app (express.mjs:352). Fixtures samefile6/ and samefile7/ fail with the guard removed (GET /r/x/z resolved) and pass with it. Seventeen probes (a to q) cover nesting, dual mounts, cycles, aliases, factories, sub-apps and sub-directory scans; each one either resolves to the full path Express serves or is unresolved. The issue's fixture gives GET /api/users and POST /api/users, the admin mount gives DELETE /admin/wipe GUARDED, and unresolvable imports give mount-prefix-cross-file. Reversed file order gives identical output. Specifiers resolve only into the candidate file set, no other file is read and no dependency is added. npm ci && npm run lint && npm test on Node 22 exits 0 with every suite at 0 failed (parser-express 37 passed). No golden number moves, CHANGELOG [0.3.4] is untouched and the version is not bumped.
  4. Earlier rounds: seven review passes found six blocking cases where a partial or stacked prefix was still marked resolved: an unmounted exported router at the top of a chain, same-file nesting under it, a router mounted in its own file and from another file, a dual-mounted middle router, a router nested on a local router, and a router on a mounted app. Each fix came with a fixture that fails without it.
  5. After the review: the branch merged main (feat(nest): detect global guards and setGlobalPrefix #21). The only conflict was in CHANGELOG.md [Unreleased], where the two lists were combined without changing any text. After that merge the gate passes on Node 22 and 24; Node 20 and 26 run in this PR's CI.

Verdict: approve.

In plain English

In most Express projects, routes are written in one file and attached under a path such as /api/users in another file. ApiGate used to report those routes under a shorter, wrong path and still call it correct, so its security checks and API spec comparisons worked on paths that do not exist. It now follows the link between the files and reports the real path, together with any login check applied where the routes are attached. When it cannot be sure of the full path, it now says "unknown" instead of guessing, and two small leftovers are documented.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Express: resolve mount prefixes for routers in other files

1 participant