ragcode-context-engine 0.1.0

package/dist/src/topology/export-index.js

@@ -0,0 +1,14 @@
+export function createExportIndex(symbols) {
+    const fileSymbols = new Map();
+    const exportedSymbols = new Map();
+    for (const symbol of symbols) {
+        if (symbol.kind === "file")
+            fileSymbols.set(symbol.filePath, symbol);
+        if (symbol.exported)
+            exportedSymbols.set(exportKey(symbol.filePath, symbol.name), symbol);
+    }
+    return { fileSymbols, exportedSymbols };
+}
+export function exportKey(filePath, name) {
+    return `${filePath}::${name}`;
+}

package/dist/src/topology/framework-topology.d.ts

@@ -0,0 +1,3 @@
+import type { CodeFile, GraphEdge, SymbolNode } from "../core/types.js";
+import type { TypeScriptSourceFile } from "../lsp/typescript-language-service.js";
+export declare function buildFrameworkTopologyEdges(files: CodeFile[], sources: TypeScriptSourceFile[], symbols: SymbolNode[], edges: GraphEdge[], priorEdges?: GraphEdge[]): GraphEdge[];

package/dist/src/topology/framework-topology.js

@@ -0,0 +1,460 @@
+import path from "node:path";
+import ts from "typescript";
+export function buildFrameworkTopologyEdges(files, sources, symbols, edges, priorEdges = []) {
+    const context = { files, sources, symbols, edges };
+    const routes = dedupeRoutes([
+        ...routesFromEdges(priorEdges),
+        ...frameworkResolvers.flatMap((resolver) => resolver.routes(context))
+    ]);
+    const frameworkEdges = [];
+    frameworkEdges.push(...clientApiEdges(sources, symbols, routes));
+    frameworkEdges.push(...routeServiceEdges(edges, symbols, routes));
+    frameworkEdges.push(...webhookEdges(routes));
+    return dedupeEdges(frameworkEdges);
+}
+function routesFromEdges(edges) {
+    const routes = [];
+    for (const edge of edges) {
+        if (edge.kind !== "calls_api" && edge.kind !== "routes_to" && edge.kind !== "handles_webhook")
+            continue;
+        const routePath = stringMetadata(edge, "route") ?? stringMetadata(edge, "requestPath");
+        const routeFile = stringMetadata(edge, "routeFile") ?? stringMetadata(edge, "targetFile") ?? stringMetadata(edge, "sourceFile");
+        const filePath = stringMetadata(edge, "targetFile") ?? stringMetadata(edge, "sourceFile");
+        const targetName = stringMetadata(edge, "targetName") ?? edge.targetId;
+        if (!routePath || !routeFile || !filePath)
+            continue;
+        routes.push({
+            framework: stringMetadata(edge, "framework") ?? "unknown",
+            routePath,
+            routeFile,
+            filePath,
+            symbol: {
+                id: edge.targetId,
+                projectId: edge.projectId,
+                filePath,
+                name: targetName,
+                kind: "unknown",
+                language: "unknown",
+                startLine: 0,
+                endLine: 0,
+                exported: false
+            },
+            isWebhook: /webhook/i.test(routePath) || /webhook/i.test(path.posix.basename(routeFile))
+        });
+    }
+    return routes;
+}
+function dedupeRoutes(routes) {
+    const seen = new Set();
+    const deduped = [];
+    for (const route of routes) {
+        const key = [route.framework, route.routePath, route.routeFile, route.filePath, route.symbol.id].join("::");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(route);
+    }
+    return deduped;
+}
+function stringMetadata(edge, key) {
+    const value = edge.metadata?.[key];
+    return typeof value === "string" ? value : undefined;
+}
+const nextJsResolver = {
+    name: "nextjs",
+    routes: ({ files, symbols }) => {
+        const routes = [];
+        for (const file of files) {
+            const routePath = nextRoutePath(file.path);
+            if (!routePath)
+                continue;
+            const routeSymbol = routeHandlerSymbol(symbols, file.path) ?? fileSymbol(symbols, file.path);
+            if (!routeSymbol)
+                continue;
+            routes.push({
+                framework: "nextjs",
+                routePath,
+                routeFile: file.path,
+                filePath: file.path,
+                symbol: routeSymbol,
+                isWebhook: isWebhookRoute(routePath, file.path)
+            });
+        }
+        return routes;
+    }
+};
+const expressResolver = {
+    name: "express",
+    routes: ({ sources, symbols }) => sources
+        .filter((source) => importsPackage(source.content, "express"))
+        .flatMap((source) => routeDefinitions(source, symbols, "express"))
+};
+const fastifyResolver = {
+    name: "fastify",
+    routes: ({ sources, symbols }) => sources
+        .filter((source) => importsPackage(source.content, "fastify"))
+        .flatMap((source) => routeDefinitions(source, symbols, "fastify"))
+};
+const frameworkResolvers = [
+    nextJsResolver,
+    expressResolver,
+    fastifyResolver
+];
+function clientApiEdges(sources, symbols, routes) {
+    const edges = [];
+    for (const source of sources) {
+        if (!isClientSource(source))
+            continue;
+        for (const call of apiCalls(source)) {
+            if (call.resolution === "framework_template")
+                continue;
+            const route = findRoute(routes, call.url);
+            if (!route)
+                continue;
+            const sourceSymbol = containingSymbol(symbols, source.filePath, call.line) ?? fileSymbol(symbols, source.filePath);
+            if (!sourceSymbol)
+                continue;
+            edges.push({
+                projectId: sourceSymbol.projectId,
+                sourceId: sourceSymbol.id,
+                targetId: route.symbol.id,
+                kind: "calls_api",
+                metadata: {
+                    framework: route.framework,
+                    sourceFile: source.filePath,
+                    targetFile: route.filePath,
+                    routeFile: route.routeFile,
+                    route: route.routePath,
+                    requestPath: call.url,
+                    targetName: route.symbol.name,
+                    line: call.line,
+                    resolution: call.resolution
+                }
+            });
+        }
+    }
+    return edges;
+}
+function routeServiceEdges(edges, symbols, routes) {
+    const routeFiles = new Map(routes.map((route) => [route.routeFile, route]));
+    return edges.flatMap((edge) => {
+        const sourceFile = typeof edge.metadata?.sourceFile === "string" ? edge.metadata.sourceFile : undefined;
+        if (edge.kind !== "calls" || !isResolvedCall(edge) || !sourceFile || !routeFiles.has(sourceFile))
+            return [];
+        const source = symbols.find((symbol) => symbol.id === edge.sourceId);
+        const target = symbols.find((symbol) => symbol.id === edge.targetId);
+        const route = routeFiles.get(sourceFile);
+        return [{
+                projectId: edge.projectId,
+                sourceId: edge.sourceId,
+                targetId: edge.targetId,
+                kind: "routes_to",
+                metadata: {
+                    framework: route?.framework,
+                    sourceFile: source?.filePath ?? edge.metadata?.sourceFile,
+                    targetFile: target?.filePath ?? edge.metadata?.targetFile,
+                    routeFile: route?.routeFile,
+                    route: route?.routePath,
+                    targetName: target?.name ?? edge.metadata?.targetName,
+                    line: edge.metadata?.line,
+                    resolution: "framework_call_graph"
+                }
+            }];
+    });
+}
+function webhookEdges(routes) {
+    return routes
+        .filter((route) => route.isWebhook)
+        .map((route) => ({
+        projectId: route.symbol.projectId,
+        sourceId: route.symbol.id,
+        targetId: route.symbol.id,
+        kind: "handles_webhook",
+        metadata: {
+            framework: route.framework,
+            sourceFile: route.filePath,
+            targetFile: route.filePath,
+            routeFile: route.routeFile,
+            route: route.routePath,
+            targetName: route.symbol.name,
+            resolution: "framework_static"
+        }
+    }));
+}
+function routeDefinitions(source, symbols, framework) {
+    const sourceFile = parseSourceFile(source);
+    const routes = [];
+    function visit(node) {
+        if (ts.isCallExpression(node)) {
+            const definition = routeDefinitionFromCall(node, sourceFile, source, symbols, framework);
+            if (definition)
+                routes.push(definition);
+        }
+        ts.forEachChild(node, visit);
+    }
+    ts.forEachChild(sourceFile, visit);
+    return routes;
+}
+function routeDefinitionFromCall(node, sourceFile, source, symbols, framework) {
+    if (!ts.isPropertyAccessExpression(node.expression))
+        return undefined;
+    const method = node.expression.name.text;
+    if (!httpMethodNames.has(method))
+        return undefined;
+    const routePath = stringLiteralValue(node.arguments[0]);
+    const handler = node.arguments[1];
+    if (!routePath?.startsWith("/") || !handler || !looksLikeRouteHandler(handler))
+        return undefined;
+    const line = lineRange(sourceFile, node).startLine;
+    const symbol = routeHandlerFromArgument(handler, symbols, source.filePath, line) ?? containingSymbol(symbols, source.filePath, line) ?? fileSymbol(symbols, source.filePath);
+    if (!symbol)
+        return undefined;
+    return {
+        framework,
+        routePath,
+        routeFile: source.filePath,
+        filePath: symbol.filePath,
+        symbol,
+        isWebhook: isWebhookRoute(routePath, symbol.filePath)
+    };
+}
+function routeHandlerFromArgument(node, symbols, filePath, line) {
+    if (ts.isIdentifier(node)) {
+        return symbols.find((symbol) => symbol.name === node.text && symbol.kind !== "file" && symbol.exported)
+            ?? symbols.find((symbol) => symbol.name === node.text && symbol.kind !== "file" && symbol.filePath === filePath)
+            ?? containingSymbol(symbols, filePath, line);
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+        return symbols.find((symbol) => symbol.name === node.name.text && symbol.kind !== "file" && symbol.exported)
+            ?? symbols.find((symbol) => symbol.name === node.name.text && symbol.kind !== "file" && symbol.filePath === filePath)
+            ?? containingSymbol(symbols, filePath, line);
+    }
+    return containingSymbol(symbols, filePath, line);
+}
+function looksLikeRouteHandler(node) {
+    return ts.isIdentifier(node)
+        || ts.isPropertyAccessExpression(node)
+        || ts.isFunctionExpression(node)
+        || ts.isArrowFunction(node);
+}
+function importsPackage(content, packageName) {
+    const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`from ['\"]${escaped}['\"]|require\\(['\"]${escaped}['\"]\\)`).test(content);
+}
+function isResolvedCall(edge) {
+    return edge.metadata?.resolution === "resolved" || edge.metadata?.resolution === "resolved_lsp";
+}
+function nextRoutePath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/");
+    const match = /(?:^|\/)(?:app|pages)\/api\/(.+)\/route\.[jt]sx?$/.exec(normalized);
+    if (match?.[1])
+        return `/api/${trimRouteSegments(match[1])}`;
+    const pagesMatch = /(?:^|\/)pages\/api\/(.+)\.[jt]sx?$/.exec(normalized);
+    if (pagesMatch?.[1])
+        return `/api/${trimRouteSegments(pagesMatch[1])}`;
+    return undefined;
+}
+function trimRouteSegments(route) {
+    return route
+        .split("/")
+        .filter((segment) => segment && !segment.startsWith("("))
+        .map((segment) => segment.replace(/^\[(.+)\]$/, ":$1"))
+        .join("/");
+}
+function routeHandlerSymbol(symbols, filePath) {
+    return symbols.find((symbol) => symbol.filePath === filePath && ["GET", "POST", "PUT", "PATCH", "DELETE"].includes(symbol.name))
+        ?? symbols.find((symbol) => symbol.filePath === filePath && symbol.exported && symbol.kind !== "file");
+}
+function fileSymbol(symbols, filePath) {
+    return symbols.find((symbol) => symbol.filePath === filePath && symbol.kind === "file");
+}
+function containingSymbol(symbols, filePath, line) {
+    return symbols
+        .filter((symbol) => symbol.filePath === filePath && symbol.kind !== "file" && symbol.startLine <= line && symbol.endLine >= line)
+        .sort((a, b) => (a.endLine - a.startLine) - (b.endLine - b.startLine))[0];
+}
+function isClientSource(source) {
+    return /\.(tsx|jsx)$/.test(source.filePath) || /^["']use client["'];?/.test(source.content.trimStart()) || /from ['"]react['"]/.test(source.content);
+}
+function apiCalls(source) {
+    const sourceFile = parseSourceFile(source);
+    const stringConstants = collectStringConstants(sourceFile);
+    const calls = [];
+    function visit(node) {
+        if (ts.isCallExpression(node)) {
+            const url = apiUrlForCall(node, stringConstants);
+            if (url?.url.startsWith("/api/")) {
+                calls.push({
+                    ...url,
+                    line: lineRange(sourceFile, node).startLine
+                });
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    ts.forEachChild(sourceFile, visit);
+    return calls;
+}
+function apiUrlForCall(node, stringConstants) {
+    const directUrl = node.arguments[0] ? urlFromExpression(node.arguments[0], stringConstants) : undefined;
+    const expression = node.expression;
+    if (ts.isIdentifier(expression) && expression.text === "fetch" && directUrl)
+        return directUrl;
+    const chain = propertyChain(expression);
+    if (chain.length >= 2 && chain[0] === "axios" && httpMethodNames.has(chain[chain.length - 1] ?? "") && directUrl) {
+        // Preserve the URL's own resolution (a literal stays framework_static, a const stays
+        // framework_dataflow). Flattening static literals to framework_wrapper understated their
+        // certainty and dropped them to heuristic confidence downstream.
+        return directUrl;
+    }
+    const clientUrl = urlFromClientCall(chain);
+    if (clientUrl)
+        return clientUrl;
+    return undefined;
+}
+function urlFromExpression(expression, stringConstants) {
+    if (ts.isStringLiteralLike(expression))
+        return { url: expression.text, resolution: "framework_static" };
+    if (ts.isIdentifier(expression)) {
+        const value = stringConstants.get(expression.text);
+        return value ? { url: value, resolution: "framework_dataflow" } : undefined;
+    }
+    if (ts.isTemplateExpression(expression)) {
+        const result = templateStringValue(expression, stringConstants);
+        return {
+            url: result.value,
+            resolution: result.resolved ? "framework_dataflow" : "framework_template"
+        };
+    }
+    return undefined;
+}
+function collectStringConstants(sourceFile) {
+    const constants = new Map();
+    const conflicting = new Set();
+    function visit(node) {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+            const name = node.name.text;
+            const value = stringValueFromExpression(node.initializer, constants);
+            if (value !== undefined && !conflicting.has(name)) {
+                const existing = constants.get(name);
+                if (existing !== undefined && existing !== value) {
+                    // Same identifier bound to different string values across scopes in one file.
+                    // Bounded dataflow cannot tell which binding a reference resolves to, so drop it
+                    // and let callers degrade to framework_template / unresolved instead of emitting
+                    // a confident-but-wrong route link.
+                    conflicting.add(name);
+                    constants.delete(name);
+                }
+                else {
+                    constants.set(name, value);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    ts.forEachChild(sourceFile, visit);
+    return constants;
+}
+function stringValueFromExpression(expression, constants) {
+    if (ts.isStringLiteralLike(expression))
+        return expression.text;
+    if (ts.isIdentifier(expression))
+        return constants.get(expression.text);
+    if (ts.isTemplateExpression(expression)) {
+        const result = templateStringValue(expression, constants);
+        return result.resolved ? result.value : undefined;
+    }
+    if (ts.isNoSubstitutionTemplateLiteral(expression))
+        return expression.text;
+    return undefined;
+}
+function templateStringValue(expression, constants) {
+    let resolved = true;
+    let value = expression.head.text;
+    for (const span of expression.templateSpans) {
+        const part = stringValueFromExpression(span.expression, constants);
+        if (part === undefined) {
+            resolved = false;
+            value += "*";
+        }
+        else {
+            value += part;
+        }
+        value += span.literal.text;
+    }
+    return { value, resolved };
+}
+function urlFromClientCall(chain) {
+    if (chain.length >= 3 && ["api", "apiClient"].includes(chain[0] ?? "")) {
+        const resource = chain[1];
+        if (resource)
+            return { url: `/api/${resource}`, resolution: "framework_wrapper" };
+    }
+    const root = chain[0];
+    if (chain.length >= 2 && root?.endsWith("Api")) {
+        const resource = root.slice(0, -"Api".length);
+        if (resource)
+            return { url: `/api/${resource}`, resolution: "framework_wrapper" };
+    }
+    return undefined;
+}
+function propertyChain(expression) {
+    if (ts.isIdentifier(expression))
+        return [expression.text];
+    if (ts.isPropertyAccessExpression(expression))
+        return [...propertyChain(expression.expression), expression.name.text];
+    return [];
+}
+function findRoute(routes, requestPath) {
+    const exact = routes.find((route) => route.routePath === requestPath);
+    if (exact)
+        return exact;
+    return routes.find((route) => routePathMatches(route.routePath, requestPath));
+}
+function routePathMatches(routePath, requestPath) {
+    const routeSegments = routePath.split("/");
+    const requestSegments = requestPath.split("/");
+    if (routeSegments.length !== requestSegments.length)
+        return false;
+    return routeSegments.every((segment, index) => segment === requestSegments[index] || segment.startsWith(":"));
+}
+function isWebhookRoute(routePath, filePath) {
+    return /webhook/i.test(routePath) || /webhook/i.test(path.posix.basename(filePath));
+}
+function stringLiteralValue(node) {
+    if (!node)
+        return undefined;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    return undefined;
+}
+function parseSourceFile(source) {
+    return ts.createSourceFile(source.filePath, source.content, ts.ScriptTarget.Latest, true, scriptKindForPath(source.filePath));
+}
+function lineRange(sourceFile, node) {
+    const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
+    return { startLine: start.line + 1, endLine: end.line + 1 };
+}
+function scriptKindForPath(filePath) {
+    if (filePath.endsWith(".tsx"))
+        return ts.ScriptKind.TSX;
+    if (filePath.endsWith(".jsx"))
+        return ts.ScriptKind.JSX;
+    if (filePath.endsWith(".js") || filePath.endsWith(".mjs") || filePath.endsWith(".cjs"))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+const httpMethodNames = new Set(["get", "post", "put", "patch", "delete"]);
+function dedupeEdges(edges) {
+    const seen = new Set();
+    const deduped = [];
+    for (const edge of edges) {
+        const key = [edge.kind, edge.sourceId, edge.targetId, edge.metadata?.framework, edge.metadata?.route, edge.metadata?.requestPath, edge.metadata?.sourceFile, edge.metadata?.line].join("::");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(edge);
+    }
+    return deduped;
+}

package/dist/src/topology/import-resolver.d.ts

@@ -0,0 +1,2 @@
+import type { CodeFile } from "../core/types.js";
+export declare function resolveImportPath(sourceFilePath: string, importSource: string, files: CodeFile[]): string | undefined;

package/dist/src/topology/import-resolver.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"];
+export function resolveImportPath(sourceFilePath, importSource, files) {
+    if (!importSource.startsWith(".") && !importSource.startsWith("/"))
+        return undefined;
+    const filePaths = new Set(files.map((file) => file.path));
+    const sourceDir = path.posix.dirname(sourceFilePath);
+    const base = normalizeImportCandidate(importSource.startsWith("/")
+        ? importSource.slice(1)
+        : path.posix.normalize(path.posix.join(sourceDir, importSource)));
+    for (const candidate of candidatePaths(base)) {
+        if (filePaths.has(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function candidatePaths(base) {
+    const candidates = [base];
+    if (!RESOLVABLE_EXTENSIONS.some((extension) => base.endsWith(extension))) {
+        for (const extension of RESOLVABLE_EXTENSIONS)
+            candidates.push(`${base}${extension}`);
+    }
+    for (const extension of RESOLVABLE_EXTENSIONS)
+        candidates.push(path.posix.join(base, `index${extension}`));
+    return [...new Set(candidates.map(normalizeImportCandidate))];
+}
+function normalizeImportCandidate(candidate) {
+    return candidate.replaceAll("\\", "/").replace(/^\/+/, "");
+}

package/dist/src/topology/orm-topology.d.ts

@@ -0,0 +1,3 @@
+import type { CodeFile, GraphEdge, SymbolNode } from "../core/types.js";
+import type { TypeScriptSourceFile } from "../lsp/typescript-language-service.js";
+export declare function buildOrmTopologyEdges(repoRoot: string, _files: CodeFile[], sources: TypeScriptSourceFile[], symbols: SymbolNode[]): GraphEdge[];