Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/*
* Herkunft: portiert am 2026-08-28 aus CodeAtlasIDE,
* /Users/bernhard/Desktop/CodeAtlasIDE/theia-extensions/codeatlas-intelligence/src/node/provider/route-reader.ts
* Gleicher Urheber (Bernhard Jackiewicz). Semantisch unveraendert uebernommen.
* Die Datei ist rein: Text rein, Funde raus, kein Dateisystem und keine Engine.
* Genau deshalb laeuft sie im Browser unveraendert; wer den Quelltext liefert,
* entscheidet der Provider. Aenderungen gegenueber dem Original: keine.
*/
/**
* Recovering HTTP routes from source text, for the languages the index does not.
*
* This file exists because of a gap, and the gap is worth stating plainly. The
* 0.9.0 analysis writes route nodes for annotation-driven Java and reports them
* under the `routes` aspect. For TypeScript, JavaScript and Python it writes
* none at all: a file that registers three routes produces three call edges and
* nothing that names a method or a path. A workspace map that showed only what
* the index reports would therefore tell a Node or a Flask reader that their
* application has no entry points, which is the confident-empty-list failure
* this product exists to avoid.
*
* So the routes are read off the text instead, and every route recovered this
* way is marked `source` rather than `index` all the way to the screen. Three
* rules keep that reading honest rather than clever:
*
* 1. **A literal or nothing.** Only a registration whose path is a string
* literal is reported. `router.get(basePath + '/users', ...)` is invisible
* here, and inventing `basePath` would be a guess about a value.
* 2. **A path, not a key.** A candidate is only a route when the literal
* starts with `/`. Without that rule `cache.get('user')` and
* `map.delete(id)` become routes, and a map full of imaginary endpoints is
* worse than a map with none.
* 3. **No handler is named here.** The registration's line is reported and
* nothing else. Which symbol encloses that line is a question for the
* index, asked when a reader clicks the row, because that answer is a
* reading and this file only has text.
*
* Everything below is pure: text in, findings out. No file system, no engine.
*/
/** One route registration found in one file. */
export interface SourceRoute {
/** HTTP method in upper case, absent when the registration does not name one. */
method?: string;
/** The path exactly as written, parameters and all. */
path: string;
/** 1-based line of the registration. */
line: number;
}
/** Verbs a router object exposes as methods, in JavaScript, TypeScript and FastAPI. */
const VERB_CALLS = 'get|post|put|patch|delete|head|options|all';
/** Registration through a router method: `app.get('/users', handler)`. */
const VERB_CALL_PATTERN = new RegExp(
`\\.(${VERB_CALLS})\\s*\\(\\s*(['"\`])(/[^'"\`\\n]*)\\2`,
'g'
);
/** Flask and Django style decorator: `@bp.route('/users', methods=['POST'])`. */
const DECORATOR_ROUTE_PATTERN = /@\s*[\w.]*\.?route\s*\(\s*(['"])(\/[^'"\n]*)\1([^)\n]*)/g;
/** The `methods=[...]` argument of a decorator route, which may name several verbs. */
const DECORATOR_METHODS_PATTERN = /methods\s*=\s*\[([^\]]*)\]/;
/** Spring style annotation: `@GetMapping("/articles")`, `@RequestMapping(value = "/x")`. */
const ANNOTATION_PATTERN = /@(Get|Post|Put|Patch|Delete|Request)Mapping\s*\(([^)]*)\)/g;
/** The first string literal inside an annotation's arguments, which is its path. */
const ANNOTATION_PATH_PATTERN = /"([^"\n]*)"/;
/** The verb a `@RequestMapping` names, when it names one. */
const ANNOTATION_METHOD_PATTERN = /RequestMethod\.([A-Z]+)/;
/** Extensions whose route registrations look like method calls or decorators. */
const SCRIPT_EXTENSIONS = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts', '.py'];
/** Extensions whose route registrations look like annotations. */
const ANNOTATION_EXTENSIONS = ['.java', '.kt'];
/** Every extension this reader knows how to look at. Anything else is skipped whole. */
export const ROUTE_SOURCE_EXTENSIONS = [...SCRIPT_EXTENSIONS, ...ANNOTATION_EXTENSIONS];
/** How many routes one file may contribute. A file past this is a generated table. */
export const MAX_ROUTES_PER_FILE = 40;
/** True when this reader has a pattern family for the file. */
export function isRouteSource(filePath: string): boolean {
const lower = filePath.toLowerCase();
return ROUTE_SOURCE_EXTENSIONS.some(extension => lower.endsWith(extension));
}
/** 1-based line the character at `index` sits on. */
function lineAt(source: string, index: number): number {
let line = 1;
for (let at = 0; at < index && at < source.length; at++) {
if (source[at] === '\n') {
line += 1;
}
}
return line;
}
/**
* Routes registered in one file.
*
* Returns an empty list for a file whose extension this reader does not know,
* which is the same answer as a file it read and found nothing in. The
* difference matters to the caller and not to the reader: the provider reports
* both as "no route recovered here", and the capability is what says whether
* that means anything.
*/
export function readRoutes(source: string, filePath: string): SourceRoute[] {
if (!isRouteSource(filePath)) {
return [];
}
const lower = filePath.toLowerCase();
const found = ANNOTATION_EXTENSIONS.some(extension => lower.endsWith(extension))
? readAnnotationRoutes(source)
: readScriptRoutes(source);
return dedupe(found).slice(0, MAX_ROUTES_PER_FILE);
}
/** Method calls and decorators, which is how JavaScript, TypeScript and Python register. */
function readScriptRoutes(source: string): SourceRoute[] {
const routes: SourceRoute[] = [];
for (const match of source.matchAll(VERB_CALL_PATTERN)) {
routes.push({
method: match[1].toUpperCase(),
path: match[3],
line: lineAt(source, match.index ?? 0)
});
}
for (const match of source.matchAll(DECORATOR_ROUTE_PATTERN)) {
const line = lineAt(source, match.index ?? 0);
const methods = DECORATOR_METHODS_PATTERN.exec(match[3] ?? '');
if (!methods) {
// A decorator with no `methods=` accepts GET in every framework that
// spells it this way, but this reader is not the place to encode
// that: the honest answer is that the registration names no verb.
routes.push({ path: match[2], line });
continue;
}
for (const verb of methods[1].split(',')) {
const cleaned = verb.replace(/['"\s]/g, '').toUpperCase();
if (cleaned.length > 0) {
routes.push({ method: cleaned, path: match[2], line });
}
}
}
return routes;
}
/**
* Annotations, which is how Spring and its relatives register.
*
* Two annotations are declined, and both for the same reason: what they carry
* is not a route.
*
* A mapping that names no verb is a class-level prefix. `@RequestMapping(path =
* "/articles")` above a controller is the first half of every route in the file
* and an endpoint of nothing on its own, so putting `/articles` on the map as a
* way in would be describing an address that does not answer.
*
* A mapping whose path does not start with `/` is the second half. `@GetMapping
* (path = "feed")` is `/articles/feed` once the prefix above it is applied, and
* this reader has only text: joining the two would mean deciding which of the
* annotations in the file is the class-level one, which is a parse and not a
* scan. Reporting `feed` on its own would be worse than reporting nothing.
*
* What both cases have in common is that the index reports these routes whole
* for exactly the languages where they appear, so declining them loses nothing.
*/
function readAnnotationRoutes(source: string): SourceRoute[] {
const routes: SourceRoute[] = [];
for (const match of source.matchAll(ANNOTATION_PATTERN)) {
const args = match[2] ?? '';
const path = ANNOTATION_PATH_PATTERN.exec(args)?.[1];
const verb = match[1] === 'Request'
? ANNOTATION_METHOD_PATTERN.exec(args)?.[1]
: match[1].toUpperCase();
if (path === undefined || !path.startsWith('/') || verb === undefined) {
continue;
}
routes.push({ method: verb, path, line: lineAt(source, match.index ?? 0) });
}
return routes;
}
/** One registration reported once, even when two patterns both matched it. */
function dedupe(routes: SourceRoute[]): SourceRoute[] {
const seen = new Set<string>();
const out: SourceRoute[] = [];
for (const route of routes) {
const key = `${route.method ?? ''} ${route.path} ${route.line}`;
if (seen.has(key)) {
continue;
}
seen.add(key);
out.push(route);
}
return out;
}