@cmflow/atlas 3.4.0-beta.6 → 3.4.0-beta.7

package/README.md

@@ -119,7 +119,7 @@ Generate the topology first, then the route catalogue:
 
 ```bash
 atlas --project-root /path/to/api generate:graph
-atlas --project-root /path/to/api generate:catalogue --output .tmp/datasource-catalogue
+atlas --project-root /path/to/api generate:catalog --output .tmp/datasource-catalogue
 ```
 
 Each route produces a YAML document and a `.graph.yaml` topology artifact. The catalogue requires a valid graph and leaves ambiguous fields marked `needs_review`.
@@ -152,7 +152,7 @@ Without `--write`, the command performs a dry run. Use `clean-orphans` to inspec
 ```text
 atlas init                         Create atlas.config.ts
 atlas generate:graph               Trace API routes to backends
-atlas generate:catalogue [route]   Generate route review documents
+atlas generate:catalog [route]     Generate route review documents
 atlas generate:test                Check configured coverage baselines
 atlas needs-review                 Rank unresolved routes
 atlas infer [route|directory]      Optionally enrich unresolved mappings
@@ -163,7 +163,7 @@ atlas report:changed               Report coverage for changed routes
 
 ## CI
 
-The recommended static CI flow is `generate:graph`, `generate:catalogue`, then `push`. Do not run optional inference in CI. Supply `DIRECTUS_URL` and `DIRECTUS_TOKEN` through the CI secret context; skip the push if either value is absent.
+The recommended static CI flow is `generate:graph`, `generate:catalog`, then `push`. Do not run optional inference in CI. Supply `DIRECTUS_URL` and `DIRECTUS_TOKEN` through the CI secret context; skip the push if either value is absent.
 
 ## Development
 

package/dist/bin/atlas.mjs

@@ -1,156 +1,23 @@
 #!/usr/bin/env node
+import { a as isKnownBackendType, c as taskProgressService, d as setUserConfig, i as inferBackendNameFromFile, l as getUserConfig, n as generateBackendTopologyArtifactsInWorkers, o as filterAnalysisFiles, r as resolveModulePath, s as shouldKeepAnalysisFile, u as loadAtlasConfig } from "../routeBackendTopologyService-D_aIIBbX.mjs";
 import { Command, InvalidArgumentError, Option } from "commander";
 import path from "node:path";
-import fs from "node:fs";
-import { pathToFileURL } from "node:url";
 import { Node, Project, SyntaxKind } from "ts-morph";
-import { cancel, intro, log, note, outro, progress, spinner } from "@clack/prompts";
-import fs$1 from "node:fs/promises";
+import { cancel, intro, log, note, outro, progress } from "@clack/prompts";
+import fs from "node:fs/promises";
 import { createDirectus, createItem, deleteItem, readItems, rest, staticToken, updateItem } from "@directus/sdk";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { globby } from "globby";
-import { minimatch } from "minimatch";
 import { createHash } from "node:crypto";
 import { parse, stringify } from "yaml";
-import { Worker } from "node:worker_threads";
 import { NoObjectGeneratedError, Output, generateText } from "ai";
 import { z } from "zod";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
-//#region src/utils/config.ts
-let _config;
-function setUserConfig(config) {
-	_config = config;
-}
-function getUserConfig() {
-	if (!_config) throw new Error("Atlas config not loaded. Run Atlas from a directory containing atlas.config.ts or pass --config.");
-	return _config;
-}
-function getTsconfigAliases(repoRoot) {
-	const tsconfigPath = path.join(repoRoot, "tsconfig.json");
-	if (!fs.existsSync(tsconfigPath)) return {};
-	const paths = new Project({
-		tsConfigFilePath: tsconfigPath,
-		skipAddingFilesFromTsConfig: true
-	}).getCompilerOptions().paths ?? {};
-	return Object.fromEntries(Object.entries(paths).flatMap(([alias, targets]) => {
-		const target = targets?.[0];
-		if (!target) return [];
-		return [[alias.replace(/\/\*$/, ""), target.replace(/^\.\//, "").replace(/\/\*$/, "")]];
-	}));
-}
-async function loadAtlasConfig(configPath, projectRoot) {
-	const filePath = path.resolve(configPath);
-	try {
-		let mod;
-		if (filePath.endsWith(".ts")) {
-			const { tsImport } = await import("tsx/esm/api");
-			mod = await tsImport(filePath, import.meta.url);
-		} else mod = await import(pathToFileURL(filePath).href);
-		const config = mod.default ?? mod;
-		const repoRoot = projectRoot || config.repoRoot || process.cwd();
-		return {
-			...config,
-			repoRoot,
-			cwd: repoRoot,
-			resolver: { alias: {
-				...getTsconfigAliases(repoRoot),
-				...config.resolver?.alias
-			} }
-		};
-	} catch (error) {
-		throw new Error(`Unable to load Atlas configuration at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
-//#endregion
-//#region src/services/taskProgressService.ts
-function formatDuration(durationMs) {
-	if (durationMs < 1e3) return `${durationMs}ms`;
-	return `${(durationMs / 1e3).toFixed(1)}s`;
-}
-var TaskProgressService = class {
-	#storage = new AsyncLocalStorage();
-	attach(sink, task) {
-		return this.#storage.run(sink, task);
-	}
-	log(message) {
-		this.#storage.getStore()?.log(message);
-	}
-	report(message) {
-		const sink = this.#storage.getStore();
-		(sink?.report || sink?.log)?.(message);
-	}
-	createStepProgress(classify = (message) => ({
-		id: message,
-		title: message
-	})) {
-		const progress = spinner();
-		let active;
-		const finishActive = (label) => {
-			if (!active) return;
-			const duration = formatDuration(Date.now() - active.startedAt);
-			progress.stop(`${label || active.completedTitle || `${active.title} completed`} (${duration})`);
-			active = void 0;
-		};
-		const start = (step) => {
-			if (active?.id === step.id) {
-				progress.message(step.detail ? `${step.title}: ${step.detail}` : step.title);
-				return;
-			}
-			finishActive();
-			active = {
-				id: step.id,
-				title: step.title,
-				completedTitle: step.completedTitle,
-				startedAt: Date.now()
-			};
-			progress.start(step.detail ? `${step.title}: ${step.detail}` : step.title);
-		};
-		const execute = (task) => this.attach({
-			log: (message) => progress.message(active ? `${active.title}: ${message}` : message),
-			report: (message) => start(classify(message))
-		}, task);
-		return {
-			report(message) {
-				start(classify(message));
-			},
-			start,
-			execute,
-			run: async (step, task) => {
-				start(step);
-				await new Promise((resolve) => setImmediate(resolve));
-				const result = await execute(task);
-				finishActive();
-				return result;
-			},
-			finish(label) {
-				finishActive(label);
-			},
-			fail(label) {
-				if (!active) return;
-				const duration = formatDuration(Date.now() - active.startedAt);
-				progress.stop(`${label} (${duration})`);
-				active = void 0;
-			}
-		};
-	}
-};
-const taskProgressService = new TaskProgressService();
-//#endregion
 //#region src/utils/catalogueStats.ts
 function calculateNeedsReviewPercentage(inputProperties, outputProperties, needsReview) {
 	const properties = inputProperties + outputProperties;
 	return properties ? Number((needsReview / properties * 100).toFixed(2)) : 0;
 }
 //#endregion
-//#region src/services/analysisFileService.ts
-function shouldKeepAnalysisFile(filePath) {
-	const normalizedProjectPath = filePath.replaceAll(path.sep, "/").replace(/^.*?(app\/)/, "app/");
-	return !getUserConfig().analysis.excluded.some((pattern) => minimatch(normalizedProjectPath, pattern, { dot: true }));
-}
-function filterAnalysisFiles(filePaths) {
-	return filePaths.filter(shouldKeepAnalysisFile);
-}
-//#endregion
 //#region src/services/useCaseAnalysisService.ts
 function normalizeCodeText(value) {
 	return value.replace(/\s+/g, " ").replace(/;$/, "").trim();
@@ -391,22 +258,6 @@ function extractOpenApiOutputProperties(operation, swagger) {
 	return [...map.values()];
 }
 //#endregion
-//#region src/utils/isKnowBackendType.ts
-function isKnownBackendType(value) {
-	return getUserConfig().analysis.backends.includes(value);
-}
-//#endregion
-//#region src/services/backendSourceService.ts
-function inferBackendNameFromFile(sourceFile) {
-	const declaredType = sourceFile.getFullText().match(/BackendTypes\.([A-Z0-9_]+)/)?.[1];
-	if (declaredType) return isKnownBackendType(declaredType) ? declaredType : null;
-	const parts = sourceFile.getFilePath().split(path.sep);
-	const backIndex = parts.lastIndexOf("back");
-	const infrastructureIndex = parts.lastIndexOf("_infra");
-	const candidate = backIndex >= 0 ? parts[backIndex + 1] : infrastructureIndex >= 0 ? parts[infrastructureIndex + 2] : void 0;
-	return candidate && isKnownBackendType(candidate.toUpperCase()) ? candidate.toUpperCase() : null;
-}
-//#endregion
 //#region src/services/backendRouteExtractionService.ts
 function looksLikeBackendRoute(value) {
 	return value.startsWith("/") || /^https?:\/\//.test(value) || /^graphql$/i.test(value);
@@ -457,51 +308,6 @@ function normalizeDescription(description) {
 	return description?.trim() || "";
 }
 //#endregion
-//#region src/utils/resolveAliasPath.ts
-function resolveAliasPath(moduleSpecifier, aliases, rootPath) {
-	for (const [alias, target] of Object.entries(aliases)) {
-		if (moduleSpecifier !== alias && !moduleSpecifier.startsWith(`${alias}/`)) continue;
-		const modulePath = moduleSpecifier.slice(alias.length).replace(/^\//, "");
-		return path.join(rootPath, target, modulePath);
-	}
-	return null;
-}
-//#endregion
-//#region src/utils/tryResolveWithExtensions.ts
-function tryResolveWithExtensions(basePath) {
-	const ext = path.extname(basePath);
-	const withoutExt = ext ? basePath.slice(0, -ext.length) : basePath;
-	const candidates = [
-		basePath,
-		ext === ".js" ? `${withoutExt}.ts` : null,
-		ext === ".ts" ? `${withoutExt}.js` : null,
-		ext === ".mjs" ? `${withoutExt}.mts` : null,
-		ext === ".mts" ? `${withoutExt}.mjs` : null,
-		`${basePath}.ts`,
-		`${basePath}.js`,
-		`${basePath}.mts`,
-		`${basePath}.mjs`,
-		path.join(withoutExt, "index.ts"),
-		path.join(withoutExt, "index.js"),
-		path.join(basePath, "index.ts"),
-		path.join(basePath, "index.js")
-	].filter((candidate) => Boolean(candidate));
-	for (const candidate of candidates) try {
-		const normalized = path.normalize(candidate);
-		if (fs.existsSync(normalized)) return normalized;
-	} catch {
-		continue;
-	}
-	return null;
-}
-//#endregion
-//#region src/utils/resolveModulePath.ts
-function resolveModulePath(sourceFilePath, moduleSpecifier, aliases, rootPath) {
-	if (moduleSpecifier.startsWith(".")) return tryResolveWithExtensions(path.resolve(path.dirname(sourceFilePath), moduleSpecifier));
-	const aliased = resolveAliasPath(moduleSpecifier, aliases, rootPath);
-	return aliased ? tryResolveWithExtensions(aliased) : null;
-}
-//#endregion
 //#region src/utils/dedupeByKey.ts
 function dedupeByKey(items, keyFn) {
 	const map = /* @__PURE__ */ new Map();
@@ -1443,11 +1249,12 @@ async function analyzeCodebaseRouteContracts(params) {
 		}) : void 0;
 		if (routeAnalysisScope && !topologyScope) continue;
 		taskProgressService.log(topologyScope ? `${routeLabel} ... Loading dependencies from backend graph` : `${routeLabel} ... Collecting dependencies`);
-		const analysisFiles = filterAnalysisFiles(dedupeByKey(await (topologyScope ? topologyScope.analysisFiles : handler.handlerFile ? dependencyFilesByHandler.get(handler.handlerFile) || (() => {
+		const dependencyFiles = topologyScope ? topologyScope.analysisFiles : handler.handlerFile ? dependencyFilesByHandler.get(handler.handlerFile) || (() => {
 			const files = collectDependencyFiles(project, handler.handlerFile, routeLabel, resolveCachedModulePath);
 			dependencyFilesByHandler.set(handler.handlerFile, files);
 			return files;
-		})() : [routeDeclaration.file]), (value) => value));
+		})() : [routeDeclaration.file];
+		const analysisFiles = filterAnalysisFiles(dedupeByKey(await dependencyFiles, (value) => value));
 		taskProgressService.log(`${routeLabel} ... Extracting mappings from ${analysisFiles.length} relevant files`);
 		await yieldToEventLoop();
 		const backendSourceFiles = analysisFiles.filter((file) => file.includes(`${path.sep}app${path.sep}_infra${path.sep}back${path.sep}`)).map((file) => project.getSourceFile(file) || project.addSourceFileAtPath(file)).filter((sourceFile) => {
@@ -2356,7 +2163,7 @@ async function pushCatalogueToDirectus(catalogue, options) {
 			}
 		}
 	}
-	if (options.outputPath) await fs$1.appendFile(options.outputPath, "", "utf8");
+	if (options.outputPath) await fs.appendFile(options.outputPath, "", "utf8");
 	const removedOrphanedLinks = await cleanupOrphanedPropertyLinks(client);
 	taskProgressService.report("Finalizing Directus synchronization");
 	if (warnings.size) {
@@ -2552,12 +2359,12 @@ async function writeRouteReviewDocument(catalogue, outputDir, repoRoot, routeKey
 	if (!route) throw new Error(`Unable to write review document for unknown route key ${routeKey}`);
 	const document = relativizeRouteReviewDocument(buildRouteReviewDocument(catalogue, route.key), repoRoot);
 	const filePath = path.join(outputDir, buildRouteReviewRelativePath(route.method, route.path));
-	await fs$1.mkdir(path.dirname(filePath), { recursive: true });
-	await fs$1.writeFile(filePath, `${stringify(document)}\n`, "utf8");
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, `${stringify(document)}\n`, "utf8");
 	return filePath;
 }
 async function writeRouteReviewDocuments(catalogue, outputDir, repoRoot) {
-	await fs$1.mkdir(outputDir, { recursive: true });
+	await fs.mkdir(outputDir, { recursive: true });
 	for (const [index, route] of catalogue.routes.entries()) {
 		taskProgressService.log(`[${index + 1}/${catalogue.routes.length}] - ${route.method} ${route.path} ...`);
 		await writeRouteReviewDocument(catalogue, outputDir, repoRoot, route.key);
@@ -2565,8 +2372,8 @@ async function writeRouteReviewDocuments(catalogue, outputDir, repoRoot) {
 	return outputDir;
 }
 async function prepareCatalogueOutputDirectory(outputDir) {
-	await fs$1.mkdir(outputDir, { recursive: true });
-	await Promise.all(["catalogue.yaml", "catalogue.yml"].map((fileName) => fs$1.rm(path.join(outputDir, fileName), { force: true })));
+	await fs.mkdir(outputDir, { recursive: true });
+	await Promise.all(["catalogue.yaml", "catalogue.yml"].map((fileName) => fs.rm(path.join(outputDir, fileName), { force: true })));
 }
 async function writeCatalogueArtifacts(catalogue, outputDir, repoRoot = process.cwd()) {
 	await prepareCatalogueOutputDirectory(outputDir);
@@ -2744,7 +2551,7 @@ async function readCatalogueFromDirectory(inputDir) {
 	if (!files.length) throw new Error(`No route YAML documents found in ${inputDir}`);
 	return {
 		catalogue: mergeRouteReviewDocuments(await Promise.all(files.sort().map(async (file) => {
-			const parsed = parse(await fs$1.readFile(file, "utf8"));
+			const parsed = parse(await fs.readFile(file, "utf8"));
 			if (parsed?.schema_version !== 1 || !parsed?.route?.method || !parsed?.route?.path) throw new Error(`Invalid route YAML document: ${file}`);
 			return parsed;
 		}))),
@@ -2938,8 +2745,8 @@ function buildBackendTopologyRelativePath(method, routePath) {
 }
 async function writeBackendTopologyArtifact(artifact, outputDir) {
 	const filePath = path.join(outputDir, buildBackendTopologyRelativePath(artifact.route.method, artifact.route.path));
-	await fs$1.mkdir(path.dirname(filePath), { recursive: true });
-	await fs$1.writeFile(filePath, `${stringify(artifact, { aliasDuplicateObjects: false })}\n`, "utf8");
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, `${stringify(artifact, { aliasDuplicateObjects: false })}\n`, "utf8");
 	return filePath;
 }
 function isRecord(value) {
@@ -2958,7 +2765,7 @@ async function loadBackendTopologyAnalysisScope(outputDir, cwd, method, routePat
 	const filePath = path.join(outputDir, buildBackendTopologyRelativePath(method, routePath));
 	let content;
 	try {
-		content = await fs$1.readFile(filePath, "utf8");
+		content = await fs.readFile(filePath, "utf8");
 	} catch (error) {
 		if (isRecord(error) && error.code === "ENOENT") throw new Error(`Backend graph artifact not found for ${method} ${routePath}: ${filePath}. Run generate:graph first.`);
 		throw error;
@@ -2979,7 +2786,7 @@ async function loadBackendTopologyAnalysisScope(outputDir, cwd, method, routePat
 	const missingFiles = [];
 	await Promise.all(analysisFiles.map(async (analysisFile) => {
 		try {
-			await fs$1.access(analysisFile);
+			await fs.access(analysisFile);
 		} catch {
 			missingFiles.push(path.relative(cwd, analysisFile));
 		}
@@ -3079,7 +2886,7 @@ async function generateHandler(cwd, routeArgument, options) {
 		process.exit(1);
 	}
 }
-var generate_default = (program) => void program.command("generate:catalogue").argument("[route]", "Route selector in the format \"GET /v1/products\"").option("-o, --output <directory>", "Directory where catalogue artifacts are generated", ".tmp/datasource-catalogue").option("--openapi-url <url>", "OpenAPI document URL").option("--profile", "Display elapsed time by generation stage").description("Analyze the codebase and generate one YAML review document per route").action((routeArgument, options) => {
+var generate_default = (program) => void program.command("generate:catalog").argument("[route]", "Route selector in the format \"GET /v1/products\"").option("-o, --output <directory>", "Directory where catalogue artifacts are generated", ".tmp/datasource-catalogue").option("--openapi-url <url>", "OpenAPI document URL").option("--profile", "Display elapsed time by generation stage").description("Analyze the codebase and generate one YAML review document per route").action((routeArgument, options) => {
 	const config = getUserConfig();
 	return generateHandler(config.cwd, routeArgument, {
 		...options,
@@ -3087,104 +2894,6 @@ var generate_default = (program) => void program.command("generate:catalogue").a
 	});
 });
 //#endregion
-//#region src/services/routeBackendTopologyService.ts
-function stringProperty(object, name) {
-	const property = object.getProperty(name);
-	if (!property || !Node.isPropertyAssignment(property)) return void 0;
-	const initializer = property.getInitializer();
-	return initializer && (Node.isStringLiteral(initializer) || Node.isNoSubstitutionTemplateLiteral(initializer)) ? initializer.getLiteralValue() : void 0;
-}
-function handlerProperty(object) {
-	const property = object.getProperty("handler");
-	if (!property || !Node.isPropertyAssignment(property)) return void 0;
-	const initializer = property.getInitializer();
-	return initializer && (Node.isIdentifier(initializer) || Node.isPropertyAccessExpression(initializer)) ? initializer.getText() : void 0;
-}
-function extractRouteDeclarations(sourceFile) {
-	const initializer = sourceFile.getVariableDeclaration("routes")?.getInitializer();
-	let expression = initializer;
-	if (initializer && (Node.isAsExpression(initializer) || Node.isSatisfiesExpression(initializer))) expression = initializer.getExpression();
-	if (!expression || !Node.isArrayLiteralExpression(expression)) return [];
-	return expression.getElements().flatMap((element) => {
-		if (!Node.isObjectLiteralExpression(element)) return [];
-		const method = stringProperty(element, "method");
-		const routePath = stringProperty(element, "path");
-		const handlerRef = handlerProperty(element);
-		return method && routePath && handlerRef ? [{
-			method: method.toUpperCase(),
-			path: routePath,
-			sourceFile,
-			handlerRef
-		}] : [];
-	});
-}
-async function discoverBackendTopologyRouteSelectors(cwd) {
-	const project = new Project({
-		skipAddingFilesFromTsConfig: true,
-		compilerOptions: {
-			allowJs: true,
-			checkJs: false
-		}
-	});
-	return (await globby(["app/_api/**/routes.@(js|ts)", "app/legacy/**/routes.@(js|ts)"], {
-		cwd,
-		absolute: true
-	})).flatMap((routeFile) => extractRouteDeclarations(project.addSourceFileAtPath(routeFile))).map((route) => ({
-		method: route.method,
-		path: route.path
-	}));
-}
-async function generateBackendTopologyArtifactsInWorkers(params) {
-	const selectors = params.routeSelector ? [params.routeSelector] : await discoverBackendTopologyRouteSelectors(params.cwd);
-	params.onRoutesDiscovered?.(selectors.length);
-	const workerCount = Math.min(params.workers || 2, selectors.length);
-	const chunks = Array.from({ length: workerCount }, () => []);
-	selectors.forEach((selector, index) => chunks[index % workerCount].push(selector));
-	const artifacts = [];
-	let completed = 0;
-	let writeQueue = Promise.resolve();
-	const workers = [];
-	try {
-		await Promise.all(chunks.map((routeSelectors) => new Promise((resolve, reject) => {
-			const worker = new Worker(new URL("./routeBackendTopologyWorker.ts", import.meta.url), {
-				workerData: {
-					cwd: params.cwd,
-					routeSelectors
-				},
-				execArgv: process.execArgv
-			});
-			workers.push(worker);
-			worker.on("message", (message) => {
-				if (message.type === "error") {
-					reject(new Error(message.message));
-					return;
-				}
-				writeQueue = writeQueue.then(async () => {
-					if (message.type === "artifact") {
-						await params.onArtifact(message.artifact);
-						artifacts.push(message.artifact);
-						return;
-					}
-					completed += 1;
-					params.onRouteProgress?.({
-						current: completed,
-						total: selectors.length,
-						route: message.route,
-						stage: "completed"
-					});
-				}).catch(reject);
-			});
-			worker.once("error", reject);
-			worker.once("exit", (code) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`Topology worker exited with code ${code}`)));
-		})));
-		await writeQueue;
-		return artifacts;
-	} catch (error) {
-		await Promise.all(workers.map((worker) => worker.terminate().catch(() => void 0)));
-		throw error;
-	}
-}
-//#endregion
 //#region src/commands/generateGraph.ts
 function parseWorkerCount$1(value) {
 	const workers = Number(value);
@@ -3439,7 +3148,7 @@ async function readSourceExcerpts(document) {
 	const excerpts = [];
 	let totalCharacters = 0;
 	for (const location of uniqueLocations) try {
-		const lines = (await fs$1.readFile(location.sourceFile, "utf8")).split("\n");
+		const lines = (await fs.readFile(location.sourceFile, "utf8")).split("\n");
 		const startLine = Math.max(1, location.line - EXCERPT_RADIUS);
 		const endLine = Math.min(lines.length, location.line + EXCERPT_RADIUS);
 		const code = lines.slice(startLine - 1, endLine).map((line, index) => `${String(startLine + index).padStart(5)} | ${line}`).join("\n");
@@ -4205,18 +3914,18 @@ var init_default = (program, datasourceCommand) => void program.command("init").
 	const configDirectory = path.dirname(configPath);
 	intro("Initialize datasource configuration");
 	try {
-		await fs$1.mkdir(configDirectory, { recursive: true });
+		await fs.mkdir(configDirectory, { recursive: true });
 		if (!options.force) {
 			let exists = false;
 			try {
-				await fs$1.access(configPath);
+				await fs.access(configPath);
 				exists = true;
 			} catch (error) {
 				if (error.code !== "ENOENT") throw error;
 			}
 			if (exists) throw new Error(`${configPath} already exists. Use --force to overwrite it.`);
 		}
-		await fs$1.writeFile(configPath, configTemplate, "utf8");
+		await fs.writeFile(configPath, configTemplate, "utf8");
 		outro(`Created ${configPath}`);
 	} catch (error) {
 		cancel(error instanceof Error ? error.message : String(error));
@@ -4349,7 +4058,7 @@ function collectImpactedRoutes(params) {
 	return params.graphs.filter((graph) => graph.analysisFiles.some((analysisFile) => changedFiles.has(normalizeFilePath(analysisFile)))).sort((left, right) => `${left.method} ${left.path}`.localeCompare(`${right.method} ${right.path}`));
 }
 async function readChangedFiles(filePath) {
-	return (await fs$1.readFile(filePath, "utf8")).split(/\r?\n/).map((line) => normalizeFilePath(line.trim())).filter(Boolean);
+	return (await fs.readFile(filePath, "utf8")).split(/\r?\n/).map((line) => normalizeFilePath(line.trim())).filter(Boolean);
 }
 async function readRouteGraphs(outputDirectory) {
 	const graphFiles = await globby("**/*.graph.yaml", {
@@ -4357,7 +4066,7 @@ async function readRouteGraphs(outputDirectory) {
 		absolute: true
 	});
 	const graphs = await Promise.all(graphFiles.map(async (graphFile) => {
-		const document = parse(await fs$1.readFile(graphFile, "utf8"));
+		const document = parse(await fs.readFile(graphFile, "utf8"));
 		if (!isGraphDocument(document)) throw new Error(`Invalid graph document: ${graphFile}`);
 		return {
 			method: document.route.method,
@@ -4475,8 +4184,8 @@ async function reportChangedHandler(cwd, options) {
 		routes: coverages
 	});
 	const reportPath = path.resolve(cwd, options.report);
-	await fs$1.mkdir(path.dirname(reportPath), { recursive: true });
-	await fs$1.writeFile(reportPath, `${report}\n`, "utf8");
+	await fs.mkdir(path.dirname(reportPath), { recursive: true });
+	await fs.writeFile(reportPath, `${report}\n`, "utf8");
 	note(report, "Datasource mapping report");
 }
 var reportChanged_default = (program) => void program.command("report:changed").requiredOption("--changed-files <file>", "Newline-delimited list of changed repository files").option("-o, --output <directory>", "Directory containing generated graph artifacts", ".tmp/datasource-catalogue").option("--report <file>", "Markdown report output path", ".tmp/datasource-catalogue/changed-routes-report.md").description("Report deterministic mapping coverage for routes impacted by changed files").action(async (options) => {
@@ -4496,7 +4205,8 @@ const program = new Command();
 program.version("3.4.0-alpha.1");
 program.name("atlas").description("Manage the API-to-backend mapping catalogue").option("--project-root <path>", "Root directory of the API project to analyze").option("-c, --config <path>", "Path to atlas.config.ts", path.resolve(process.cwd(), "atlas.config.ts")).hook("preAction", async (_thisCommand, actionCommand) => {
 	if (actionCommand.name() === "init") return;
-	setUserConfig(await loadAtlasConfig(program.opts().config, program.opts().projectRoot));
+	const config = await loadAtlasConfig(program.opts().config, program.opts().projectRoot);
+	setUserConfig(config);
 });
 init_default(program, program);
 generate_default(program);

package/dist/routeBackendTopologyService-D_aIIBbX.mjs

@@ -0,0 +1,792 @@
+import path from "node:path";
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+import { Node, Project, SyntaxKind } from "ts-morph";
+import { spinner } from "@clack/prompts";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { globby } from "globby";
+import { minimatch } from "minimatch";
+import { Worker } from "node:worker_threads";
+//#region src/utils/config.ts
+let _config;
+function setUserConfig(config) {
+	_config = config;
+}
+function getUserConfig() {
+	if (!_config) throw new Error("Atlas config not loaded. Run Atlas from a directory containing atlas.config.ts or pass --config.");
+	return _config;
+}
+function getTsconfigAliases(repoRoot) {
+	const tsconfigPath = path.join(repoRoot, "tsconfig.json");
+	if (!fs.existsSync(tsconfigPath)) return {};
+	const paths = new Project({
+		tsConfigFilePath: tsconfigPath,
+		skipAddingFilesFromTsConfig: true
+	}).getCompilerOptions().paths ?? {};
+	return Object.fromEntries(Object.entries(paths).flatMap(([alias, targets]) => {
+		const target = targets?.[0];
+		if (!target) return [];
+		return [[alias.replace(/\/\*$/, ""), target.replace(/^\.\//, "").replace(/\/\*$/, "")]];
+	}));
+}
+async function loadAtlasConfig(configPath, projectRoot) {
+	const filePath = path.resolve(configPath);
+	try {
+		let mod;
+		if (filePath.endsWith(".ts")) {
+			const { tsImport } = await import("tsx/esm/api");
+			mod = await tsImport(filePath, import.meta.url);
+		} else mod = await import(pathToFileURL(filePath).href);
+		const config = mod.default ?? mod;
+		const repoRoot = projectRoot || config.repoRoot || process.cwd();
+		return {
+			...config,
+			repoRoot,
+			cwd: repoRoot,
+			resolver: { alias: {
+				...getTsconfigAliases(repoRoot),
+				...config.resolver?.alias
+			} }
+		};
+	} catch (error) {
+		throw new Error(`Unable to load Atlas configuration at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+//#endregion
+//#region src/services/taskProgressService.ts
+function formatDuration(durationMs) {
+	if (durationMs < 1e3) return `${durationMs}ms`;
+	return `${(durationMs / 1e3).toFixed(1)}s`;
+}
+var TaskProgressService = class {
+	#storage = new AsyncLocalStorage();
+	attach(sink, task) {
+		return this.#storage.run(sink, task);
+	}
+	log(message) {
+		this.#storage.getStore()?.log(message);
+	}
+	report(message) {
+		const sink = this.#storage.getStore();
+		(sink?.report || sink?.log)?.(message);
+	}
+	createStepProgress(classify = (message) => ({
+		id: message,
+		title: message
+	})) {
+		const progress = spinner();
+		let active;
+		const finishActive = (label) => {
+			if (!active) return;
+			const duration = formatDuration(Date.now() - active.startedAt);
+			progress.stop(`${label || active.completedTitle || `${active.title} completed`} (${duration})`);
+			active = void 0;
+		};
+		const start = (step) => {
+			if (active?.id === step.id) {
+				progress.message(step.detail ? `${step.title}: ${step.detail}` : step.title);
+				return;
+			}
+			finishActive();
+			active = {
+				id: step.id,
+				title: step.title,
+				completedTitle: step.completedTitle,
+				startedAt: Date.now()
+			};
+			progress.start(step.detail ? `${step.title}: ${step.detail}` : step.title);
+		};
+		const execute = (task) => this.attach({
+			log: (message) => progress.message(active ? `${active.title}: ${message}` : message),
+			report: (message) => start(classify(message))
+		}, task);
+		return {
+			report(message) {
+				start(classify(message));
+			},
+			start,
+			execute,
+			run: async (step, task) => {
+				start(step);
+				await new Promise((resolve) => setImmediate(resolve));
+				const result = await execute(task);
+				finishActive();
+				return result;
+			},
+			finish(label) {
+				finishActive(label);
+			},
+			fail(label) {
+				if (!active) return;
+				const duration = formatDuration(Date.now() - active.startedAt);
+				progress.stop(`${label} (${duration})`);
+				active = void 0;
+			}
+		};
+	}
+};
+const taskProgressService = new TaskProgressService();
+//#endregion
+//#region src/services/analysisFileService.ts
+function shouldKeepAnalysisFile(filePath) {
+	const normalizedProjectPath = filePath.replaceAll(path.sep, "/").replace(/^.*?(app\/)/, "app/");
+	return !getUserConfig().analysis.excluded.some((pattern) => minimatch(normalizedProjectPath, pattern, { dot: true }));
+}
+function filterAnalysisFiles(filePaths) {
+	return filePaths.filter(shouldKeepAnalysisFile);
+}
+//#endregion
+//#region src/utils/isKnowBackendType.ts
+function isKnownBackendType(value) {
+	return getUserConfig().analysis.backends.includes(value);
+}
+//#endregion
+//#region src/services/backendSourceService.ts
+function inferBackendNameFromFile(sourceFile) {
+	const declaredType = sourceFile.getFullText().match(/BackendTypes\.([A-Z0-9_]+)/)?.[1];
+	if (declaredType) return isKnownBackendType(declaredType) ? declaredType : null;
+	const parts = sourceFile.getFilePath().split(path.sep);
+	const backIndex = parts.lastIndexOf("back");
+	const infrastructureIndex = parts.lastIndexOf("_infra");
+	const candidate = backIndex >= 0 ? parts[backIndex + 1] : infrastructureIndex >= 0 ? parts[infrastructureIndex + 2] : void 0;
+	return candidate && isKnownBackendType(candidate.toUpperCase()) ? candidate.toUpperCase() : null;
+}
+//#endregion
+//#region src/utils/resolveAliasPath.ts
+function resolveAliasPath(moduleSpecifier, aliases, rootPath) {
+	for (const [alias, target] of Object.entries(aliases)) {
+		if (moduleSpecifier !== alias && !moduleSpecifier.startsWith(`${alias}/`)) continue;
+		const modulePath = moduleSpecifier.slice(alias.length).replace(/^\//, "");
+		return path.join(rootPath, target, modulePath);
+	}
+	return null;
+}
+//#endregion
+//#region src/utils/tryResolveWithExtensions.ts
+function tryResolveWithExtensions(basePath) {
+	const ext = path.extname(basePath);
+	const withoutExt = ext ? basePath.slice(0, -ext.length) : basePath;
+	const candidates = [
+		basePath,
+		ext === ".js" ? `${withoutExt}.ts` : null,
+		ext === ".ts" ? `${withoutExt}.js` : null,
+		ext === ".mjs" ? `${withoutExt}.mts` : null,
+		ext === ".mts" ? `${withoutExt}.mjs` : null,
+		`${basePath}.ts`,
+		`${basePath}.js`,
+		`${basePath}.mts`,
+		`${basePath}.mjs`,
+		path.join(withoutExt, "index.ts"),
+		path.join(withoutExt, "index.js"),
+		path.join(basePath, "index.ts"),
+		path.join(basePath, "index.js")
+	].filter((candidate) => Boolean(candidate));
+	for (const candidate of candidates) try {
+		const normalized = path.normalize(candidate);
+		if (fs.existsSync(normalized)) return normalized;
+	} catch {
+		continue;
+	}
+	return null;
+}
+//#endregion
+//#region src/utils/resolveModulePath.ts
+function resolveModulePath(sourceFilePath, moduleSpecifier, aliases, rootPath) {
+	if (moduleSpecifier.startsWith(".")) return tryResolveWithExtensions(path.resolve(path.dirname(sourceFilePath), moduleSpecifier));
+	const aliased = resolveAliasPath(moduleSpecifier, aliases, rootPath);
+	return aliased ? tryResolveWithExtensions(aliased) : null;
+}
+//#endregion
+//#region src/services/routeBackendTopologyService.ts
+const backendTopologyWeights = {
+	local_call: 1,
+	imported_call: 2,
+	local_callback: 2,
+	imported_callback: 3
+};
+function normalizeSourcePath(cwd, filePath) {
+	const relative = path.relative(cwd, filePath);
+	return relative.startsWith("..") ? filePath : relative.replaceAll(path.sep, "/");
+}
+function isFilePath(filePath) {
+	try {
+		return fs.statSync(filePath).isFile();
+	} catch {
+		return false;
+	}
+}
+function callableLine(callable) {
+	return callable.declaration?.getStartLineNumber() || 1;
+}
+function callableKey(callable) {
+	return `${callable.sourceFile.getFilePath()}:${callable.symbol}:${callableLine(callable)}`;
+}
+function isCallableVariable(declaration) {
+	const initializer = declaration.getInitializer();
+	return Boolean(initializer && (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer) || Node.isCallExpression(initializer) || Node.isNewExpression(initializer)));
+}
+function findLocalCallable(sourceFile, symbol) {
+	const functionDeclaration = sourceFile.getFunctions().find((item) => item.getName() === symbol);
+	if (functionDeclaration) return functionDeclaration;
+	const variableDeclaration = sourceFile.getVariableDeclarations().find((item) => item.getName() === symbol && isCallableVariable(item));
+	if (variableDeclaration) return variableDeclaration;
+	return sourceFile.getDescendantsOfKind(SyntaxKind.MethodDeclaration).find((item) => item.getName() === symbol);
+}
+function resolveSourceFile(project, owner, moduleSpecifier, resolvePath) {
+	const resolvedPath = resolvePath(owner.getFilePath(), moduleSpecifier);
+	if (!resolvedPath) return void 0;
+	const existing = project.getSourceFile(resolvedPath);
+	if (existing) return existing;
+	return isFilePath(resolvedPath) ? project.addSourceFileAtPathIfExists(resolvedPath) : void 0;
+}
+function resolveExportedCallable(project, sourceFile, symbol, resolvePath, seen = /* @__PURE__ */ new Set()) {
+	const key = `${sourceFile.getFilePath()}:${symbol}`;
+	if (seen.has(key)) return void 0;
+	seen.add(key);
+	const local = findLocalCallable(sourceFile, symbol);
+	if (local) return {
+		declaration: local,
+		sourceFile,
+		symbol,
+		imported: true
+	};
+	for (const exportDeclaration of sourceFile.getExportDeclarations()) {
+		const moduleSpecifier = exportDeclaration.getModuleSpecifierValue();
+		if (!moduleSpecifier) continue;
+		const namedExport = exportDeclaration.getNamedExports().find((item) => (item.getAliasNode()?.getText() || item.getName()) === symbol);
+		if (exportDeclaration.getNamedExports().length && !namedExport) continue;
+		const targetFile = resolveSourceFile(project, sourceFile, moduleSpecifier, resolvePath);
+		if (!targetFile) continue;
+		const resolved = resolveExportedCallable(project, targetFile, namedExport?.getName() || symbol, resolvePath, seen);
+		if (resolved) return resolved;
+	}
+}
+function resolveConstructedMember(project, sourceFile, variableName, memberName, resolvePath) {
+	const initializer = sourceFile.getVariableDeclaration(variableName)?.getInitializer();
+	if (!initializer || !Node.isNewExpression(initializer)) return void 0;
+	const constructorName = initializer.getExpression().getText();
+	const localMethod = sourceFile.getClass(constructorName)?.getInstanceMethod(memberName);
+	if (localMethod) return {
+		declaration: localMethod,
+		sourceFile,
+		symbol: memberName,
+		imported: true
+	};
+	for (const importDeclaration of sourceFile.getImportDeclarations()) {
+		const namedImport = importDeclaration.getNamedImports().find((item) => (item.getAliasNode()?.getText() || item.getName()) === constructorName);
+		if (!namedImport) continue;
+		const targetFile = resolveSourceFile(project, sourceFile, importDeclaration.getModuleSpecifierValue(), resolvePath);
+		const method = targetFile?.getClass(namedImport.getName())?.getInstanceMethod(memberName);
+		if (targetFile && method) return {
+			declaration: method,
+			sourceFile: targetFile,
+			symbol: memberName,
+			imported: true
+		};
+	}
+}
+function resolveImportedReference(project, sourceFile, expressionText, resolvePath) {
+	const [root, member] = expressionText.split(".");
+	for (const importDeclaration of sourceFile.getImportDeclarations()) {
+		const targetFile = resolveSourceFile(project, sourceFile, importDeclaration.getModuleSpecifierValue(), resolvePath);
+		if (!targetFile) continue;
+		if (importDeclaration.getNamespaceImport()?.getText() === root && member) return resolveExportedCallable(project, targetFile, member, resolvePath) || {
+			sourceFile: targetFile,
+			symbol: expressionText,
+			imported: true
+		};
+		const namedImport = importDeclaration.getNamedImports().find((item) => (item.getAliasNode()?.getText() || item.getName()) === root);
+		if (namedImport) {
+			const importedSymbol = namedImport.getName();
+			if (member) {
+				if (inferBackendNameFromFile(targetFile)) return {
+					sourceFile: targetFile,
+					symbol: expressionText,
+					imported: true
+				};
+				const constructedMember = resolveConstructedMember(project, targetFile, importedSymbol, member, resolvePath);
+				if (constructedMember) return constructedMember;
+			}
+			return resolveExportedCallable(project, targetFile, member || importedSymbol, resolvePath) || {
+				sourceFile: targetFile,
+				symbol: expressionText,
+				imported: true
+			};
+		}
+		if (importDeclaration.getDefaultImport()?.getText() === root) return resolveExportedCallable(project, targetFile, member || "default", resolvePath) || {
+			sourceFile: targetFile,
+			symbol: expressionText,
+			imported: true
+		};
+	}
+}
+function resolveTypedPropertyMethod(project, sourceFile, expression, resolvePath) {
+	const receiver = expression.getExpression();
+	if (!Node.isPropertyAccessExpression(receiver) || receiver.getExpression().getText() !== "this") return;
+	const propertyType = expression.getFirstAncestorByKind(SyntaxKind.ClassDeclaration)?.getProperty(receiver.getName())?.getTypeNode()?.getText().match(/[A-Za-z_$][A-Za-z0-9_$]*/)?.[0];
+	if (!propertyType) return void 0;
+	for (const importDeclaration of sourceFile.getImportDeclarations()) {
+		const namedImport = importDeclaration.getNamedImports().find((item) => (item.getAliasNode()?.getText() || item.getName()) === propertyType);
+		if (!namedImport) continue;
+		const targetFile = resolveSourceFile(project, sourceFile, importDeclaration.getModuleSpecifierValue(), resolvePath);
+		if (!targetFile) continue;
+		const importedType = namedImport.getName();
+		const method = targetFile.getClasses().find((declaration) => declaration.getName() === importedType)?.getInstanceMethod(expression.getName());
+		if (method) return {
+			declaration: method,
+			sourceFile: targetFile,
+			symbol: expression.getText(),
+			imported: true
+		};
+	}
+}
+function resolveReference(project, sourceFile, expression, resolvePath) {
+	const expressionText = expression.getText();
+	const localSymbol = Node.isPropertyAccessExpression(expression) ? expression.getName() : Node.isIdentifier(expression) ? expression.getText() : void 0;
+	if (Node.isPropertyAccessExpression(expression)) {
+		const imported = resolveImportedReference(project, sourceFile, expressionText, resolvePath);
+		if (imported) return imported;
+		const typedPropertyMethod = resolveTypedPropertyMethod(project, sourceFile, expression, resolvePath);
+		if (typedPropertyMethod) return typedPropertyMethod;
+	}
+	if (localSymbol) {
+		const local = findLocalCallable(sourceFile, localSymbol);
+		if (local) return {
+			declaration: local,
+			sourceFile,
+			symbol: localSymbol,
+			imported: false
+		};
+	}
+	const imported = resolveImportedReference(project, sourceFile, expressionText, resolvePath);
+	if (imported) return imported;
+	const declaration = expression.getSymbol()?.getAliasedSymbol()?.getDeclarations()[0] || expression.getSymbol()?.getDeclarations()[0];
+	if (!declaration) return void 0;
+	const callable = Node.isFunctionDeclaration(declaration) || Node.isMethodDeclaration(declaration) || Node.isVariableDeclaration(declaration) ? declaration : void 0;
+	if (!callable) return void 0;
+	if (Node.isVariableDeclaration(callable) && !isCallableVariable(callable)) return void 0;
+	const targetFile = callable.getSourceFile();
+	return {
+		declaration: callable,
+		sourceFile: targetFile,
+		symbol: localSymbol || expressionText,
+		imported: targetFile.getFilePath() !== sourceFile.getFilePath()
+	};
+}
+function referenceExpressions(call) {
+	const references = [{
+		expression: call.getExpression(),
+		type: "call"
+	}];
+	for (const argument of call.getArguments()) if (Node.isIdentifier(argument) || Node.isPropertyAccessExpression(argument)) references.push({
+		expression: argument,
+		type: "callback"
+	});
+	return references;
+}
+function edgeWeight(type, imported) {
+	if (type === "callback") return imported ? backendTopologyWeights.imported_callback : backendTopologyWeights.local_callback;
+	return imported ? backendTopologyWeights.imported_call : backendTopologyWeights.local_call;
+}
+function callableCalls(callable) {
+	return callable.declaration?.getDescendantsOfKind(SyntaxKind.CallExpression) || [];
+}
+function mappingDirection(symbol, layer) {
+	const mapperNaming = getUserConfig().analysis.mapperNaming;
+	if (layer === "api") {
+		if (mapperNaming.inputPatterns.some((pattern) => pattern.test(symbol))) return "input";
+		if (mapperNaming.outputPatterns.some((pattern) => pattern.test(symbol))) return "output";
+		return;
+	}
+	if (mapperNaming.domainToBackendPattern.test(symbol)) return "input";
+	if (mapperNaming.domainNameFromToDomainPattern.test(symbol) || /(?:From(?:Back|Backend)ToDomain|ToDomain)$/i.test(symbol)) return "output";
+}
+function callableFromTopologyNode(cwd, project, node) {
+	const filePath = path.resolve(cwd, node.source);
+	const sourceFile = project.getSourceFile(filePath) || project.addSourceFileAtPathIfExists(filePath);
+	if (!sourceFile) return void 0;
+	const declaration = [
+		...sourceFile.getFunctions(),
+		...sourceFile.getDescendantsOfKind(SyntaxKind.MethodDeclaration),
+		...sourceFile.getVariableDeclarations().filter(isCallableVariable)
+	].find((item) => item.getStartLineNumber() === node.line);
+	return declaration ? {
+		declaration,
+		sourceFile,
+		symbol: node.symbol,
+		imported: true
+	} : void 0;
+}
+function collectBackendTopologyMappingContext(params) {
+	const handlerDeclaration = findLocalCallable(params.handlerFile, params.handlerName);
+	if (!handlerDeclaration) return [];
+	const handler = {
+		declaration: handlerDeclaration,
+		sourceFile: params.handlerFile,
+		symbol: params.handlerName,
+		imported: false
+	};
+	const contexts = [];
+	const visitedMapperCalls = /* @__PURE__ */ new Set();
+	const appendMapper = (callable, layer, direction, backendPath, backendType) => {
+		const key = [
+			callableKey(callable),
+			layer,
+			direction,
+			backendPath,
+			backendType
+		].join(":");
+		if (visitedMapperCalls.has(key)) return;
+		visitedMapperCalls.add(key);
+		contexts.push({
+			layer,
+			direction,
+			symbol: callable.declaration?.getSymbol()?.getName() || callable.symbol.split(".").at(-1),
+			source: normalizeSourcePath(params.cwd, callable.sourceFile.getFilePath()),
+			line: callableLine(callable),
+			backend_path: backendPath,
+			backend_type: backendType
+		});
+		const expectedLayerPath = layer === "api" ? "app/_api/" : "app/_infra/back/";
+		for (const call of callableCalls(callable)) {
+			const dependency = resolveReference(params.project, callable.sourceFile, call.getExpression(), params.resolvePath);
+			if (!dependency?.declaration || !normalizeSourcePath(params.cwd, dependency.sourceFile.getFilePath()).includes(expectedLayerPath)) continue;
+			appendMapper(dependency, layer, direction, backendPath, backendType);
+		}
+	};
+	const appendMapperCalls = (callable, layer, backendPath, backendType) => {
+		for (const call of callableCalls(callable)) {
+			const resolved = resolveReference(params.project, callable.sourceFile, call.getExpression(), params.resolvePath);
+			if (!resolved?.declaration) continue;
+			const direction = mappingDirection(resolved.declaration.getSymbol()?.getName() || resolved.symbol.split(".").at(-1), layer);
+			if (!direction) continue;
+			appendMapper(resolved, layer, direction, backendPath, backendType);
+		}
+	};
+	for (const [backendPath, topologyPath] of params.backendPaths.entries()) {
+		appendMapperCalls(handler, "api", backendPath, topologyPath.backend_type);
+		for (const node of topologyPath.nodes) {
+			if (!node.source.includes("app/_infra/back/")) continue;
+			const callable = callableFromTopologyNode(params.cwd, params.project, node);
+			if (callable) appendMapperCalls(callable, "backend", backendPath, topologyPath.backend_type);
+		}
+	}
+	return [...new Map(contexts.map((context) => [[
+		context.layer,
+		context.direction,
+		context.symbol,
+		context.source,
+		context.line,
+		context.backend_path,
+		context.backend_type
+	].join(":"), context])).values()];
+}
+function traceBackendPaths(params) {
+	const handlerDeclaration = findLocalCallable(params.handlerFile, params.handlerName);
+	if (!handlerDeclaration) throw new Error(`Handler declaration not found: ${params.handlerName} in ${params.handlerFile.getFilePath()}`);
+	const handler = {
+		declaration: handlerDeclaration,
+		sourceFile: params.handlerFile,
+		symbol: params.handlerName,
+		imported: false
+	};
+	const queue = [{
+		callable: handler,
+		weight: 0,
+		nodes: [{
+			symbol: handler.symbol,
+			source: normalizeSourcePath(params.cwd, handler.sourceFile.getFilePath()),
+			line: callableLine(handler),
+			depth: 0
+		}],
+		edges: [],
+		visited: /* @__PURE__ */ new Set([callableKey(handler)])
+	}];
+	const paths = [];
+	const shortestWeightByCallable = /* @__PURE__ */ new Map([[callableKey(handler), 0]]);
+	const shortestWeightByBackendBoundary = /* @__PURE__ */ new Map();
+	while (queue.length) {
+		queue.sort((left, right) => left.weight - right.weight);
+		const current = queue.shift();
+		for (const call of callableCalls(current.callable)) for (const reference of referenceExpressions(call)) {
+			const resolved = resolveReference(params.project, current.callable.sourceFile, reference.expression, params.resolvePath);
+			if (!resolved) continue;
+			const key = callableKey(resolved);
+			if (current.visited.has(key)) continue;
+			const weight = edgeWeight(reference.type, resolved.imported);
+			const totalWeight = current.weight + weight;
+			const backendType = inferBackendNameFromFile(resolved.sourceFile) || void 0;
+			const node = {
+				symbol: resolved.symbol,
+				source: normalizeSourcePath(params.cwd, resolved.sourceFile.getFilePath()),
+				line: callableLine(resolved),
+				depth: totalWeight,
+				backend_type: backendType
+			};
+			const edge = {
+				type: reference.type,
+				from: current.callable.symbol,
+				to: resolved.symbol,
+				source: normalizeSourcePath(params.cwd, current.callable.sourceFile.getFilePath()),
+				line: call.getStartLineNumber(),
+				weight
+			};
+			const nodes = [...current.nodes, node];
+			const edges = [...current.edges, edge];
+			if (backendType) {
+				const boundaryKey = `${backendType}:${node.source}:${node.symbol}:${node.line}`;
+				const shortestWeight = shortestWeightByBackendBoundary.get(boundaryKey);
+				if (shortestWeight !== void 0 && totalWeight > shortestWeight) continue;
+				shortestWeightByBackendBoundary.set(boundaryKey, totalWeight);
+				paths.push({
+					backend_type: backendType,
+					total_weight: totalWeight,
+					status: "resolved",
+					nodes,
+					edges
+				});
+				continue;
+			}
+			if (!resolved.declaration) continue;
+			const shortestWeight = shortestWeightByCallable.get(key);
+			if (shortestWeight !== void 0 && totalWeight >= shortestWeight) continue;
+			shortestWeightByCallable.set(key, totalWeight);
+			queue.push({
+				callable: resolved,
+				weight: totalWeight,
+				nodes,
+				edges,
+				visited: /* @__PURE__ */ new Set([...current.visited, key])
+			});
+		}
+	}
+	const unique = /* @__PURE__ */ new Map();
+	for (const topologyPath of paths.filter((item) => {
+		const terminalNode = item.nodes.at(-1);
+		const boundaryKey = `${item.backend_type}:${terminalNode.source}:${terminalNode.symbol}:${terminalNode.line}`;
+		return item.total_weight === shortestWeightByBackendBoundary.get(boundaryKey);
+	})) {
+		const key = `${topologyPath.backend_type}:${topologyPath.nodes.map((node) => `${node.source}:${node.symbol}:${node.line}`).join("->")}`;
+		const existing = unique.get(key);
+		if (!existing || topologyPath.total_weight < existing.total_weight) unique.set(key, topologyPath);
+	}
+	return [...unique.values()].sort((left, right) => left.total_weight - right.total_weight || left.backend_type.localeCompare(right.backend_type));
+}
+function stringProperty(object, name) {
+	const property = object.getProperty(name);
+	if (!property || !Node.isPropertyAssignment(property)) return void 0;
+	const initializer = property.getInitializer();
+	return initializer && (Node.isStringLiteral(initializer) || Node.isNoSubstitutionTemplateLiteral(initializer)) ? initializer.getLiteralValue() : void 0;
+}
+function handlerProperty(object) {
+	const property = object.getProperty("handler");
+	if (!property || !Node.isPropertyAssignment(property)) return void 0;
+	const initializer = property.getInitializer();
+	return initializer && (Node.isIdentifier(initializer) || Node.isPropertyAccessExpression(initializer)) ? initializer.getText() : void 0;
+}
+function extractRouteDeclarations(sourceFile) {
+	const initializer = sourceFile.getVariableDeclaration("routes")?.getInitializer();
+	let expression = initializer;
+	if (initializer && (Node.isAsExpression(initializer) || Node.isSatisfiesExpression(initializer))) expression = initializer.getExpression();
+	if (!expression || !Node.isArrayLiteralExpression(expression)) return [];
+	return expression.getElements().flatMap((element) => {
+		if (!Node.isObjectLiteralExpression(element)) return [];
+		const method = stringProperty(element, "method");
+		const routePath = stringProperty(element, "path");
+		const handlerRef = handlerProperty(element);
+		return method && routePath && handlerRef ? [{
+			method: method.toUpperCase(),
+			path: routePath,
+			sourceFile,
+			handlerRef
+		}] : [];
+	});
+}
+function resolveHandler(project, route, resolvePath) {
+	const resolved = resolveImportedReference(project, route.sourceFile, route.handlerRef, resolvePath);
+	if (resolved) return resolved;
+	const local = findLocalCallable(route.sourceFile, route.handlerRef);
+	return local ? {
+		declaration: local,
+		sourceFile: route.sourceFile,
+		symbol: route.handlerRef,
+		imported: false
+	} : void 0;
+}
+async function collectBackendTopologyDependencyFiles(project, entryFilePath, resolvePath) {
+	const queue = [entryFilePath];
+	const visited = /* @__PURE__ */ new Set();
+	while (queue.length) {
+		const current = queue.shift();
+		if (visited.has(current)) continue;
+		visited.add(current);
+		const sourceFile = project.getSourceFile(current) || (isFilePath(current) ? project.addSourceFileAtPathIfExists(current) : void 0);
+		if (!sourceFile) continue;
+		const moduleSpecifiers = [...sourceFile.getImportDeclarations().map((item) => item.getModuleSpecifierValue()), ...sourceFile.getExportDeclarations().map((item) => item.getModuleSpecifierValue()).filter((value) => Boolean(value))];
+		for (const moduleSpecifier of moduleSpecifiers) {
+			const resolved = resolvePath(sourceFile.getFilePath(), moduleSpecifier);
+			if (resolved && !visited.has(resolved) && shouldKeepAnalysisFile(resolved)) queue.push(resolved);
+		}
+	}
+	return [...visited];
+}
+async function generateBackendTopologyArtifacts(params) {
+	const resolvePath = (sourceFilePath, moduleSpecifier) => resolveModulePath(sourceFilePath, moduleSpecifier, getUserConfig().resolver.alias, params.cwd);
+	const project = new Project({
+		skipAddingFilesFromTsConfig: true,
+		compilerOptions: {
+			allowJs: true,
+			checkJs: false,
+			target: 99,
+			module: 99
+		}
+	});
+	taskProgressService.report("Discovering route files");
+	const routeFiles = await globby(["app/_api/**/routes.@(js|ts)", "app/legacy/**/routes.@(js|ts)"], {
+		cwd: params.cwd,
+		absolute: true
+	});
+	taskProgressService.log(`${routeFiles.length} route file${routeFiles.length === 1 ? "" : "s"} discovered`);
+	taskProgressService.report("Extracting route declarations");
+	const routes = routeFiles.flatMap((routeFile) => extractRouteDeclarations(project.addSourceFileAtPath(routeFile))).filter((route) => {
+		if (params.routeSelector) return route.method === params.routeSelector.method && route.path === params.routeSelector.path;
+		return !params.routeSelectors || params.routeSelectors.some((selector) => route.method === selector.method && route.path === selector.path);
+	});
+	if (params.routeSelector && !routes.length) throw new Error(`Route not found: ${params.routeSelector.method} ${params.routeSelector.path}`);
+	params.onRoutesDiscovered?.(routes.length);
+	if (!params.onRoutesDiscovered) taskProgressService.log(`${routes.length} API route${routes.length === 1 ? "" : "s"} selected`);
+	const artifacts = [];
+	for (const [index, route] of routes.entries()) {
+		const routeProgress = (stage) => params.onRouteProgress?.({
+			current: index + 1,
+			total: routes.length,
+			route: {
+				method: route.method,
+				path: route.path
+			},
+			stage
+		});
+		if (!params.onRouteProgress) {
+			taskProgressService.report(`Tracing route ${index + 1}/${routes.length}: ${route.method} ${route.path}`);
+			await new Promise((resolve) => setImmediate(resolve));
+		}
+		const handler = resolveHandler(project, route, resolvePath);
+		if (!handler?.declaration) {
+			taskProgressService.log(`Warning: handler not resolved for ${route.method} ${route.path} (${route.handlerRef}); route skipped`);
+			routeProgress("completed");
+			continue;
+		}
+		routeProgress("collecting_dependencies");
+		if (!params.onRouteProgress) taskProgressService.log(`${route.method} ${route.path} ... Collecting dependencies`);
+		const dependencyFiles = await collectBackendTopologyDependencyFiles(project, handler.sourceFile.getFilePath(), resolvePath);
+		routeProgress("tracing_paths");
+		if (!params.onRouteProgress) taskProgressService.log(`${route.method} ${route.path} ... Tracing callable paths`);
+		const backendPaths = traceBackendPaths({
+			cwd: params.cwd,
+			project,
+			handlerFile: handler.sourceFile,
+			handlerName: handler.symbol,
+			resolvePath
+		});
+		const mappingContext = collectBackendTopologyMappingContext({
+			cwd: params.cwd,
+			project,
+			handlerFile: handler.sourceFile,
+			handlerName: handler.symbol,
+			backendPaths,
+			resolvePath
+		});
+		if (!params.onRouteProgress) taskProgressService.log(`${route.method} ${route.path} ... ${backendPaths.length} backend path${backendPaths.length === 1 ? "" : "s"}`);
+		const artifact = {
+			schema_version: 3,
+			generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+			route: {
+				method: route.method,
+				path: route.path,
+				source: normalizeSourcePath(params.cwd, route.sourceFile.getFilePath()),
+				handler: {
+					symbol: handler.symbol,
+					source: normalizeSourcePath(params.cwd, handler.sourceFile.getFilePath()),
+					line: callableLine(handler)
+				}
+			},
+			analysis_files: [.../* @__PURE__ */ new Set([...dependencyFiles.map((filePath) => normalizeSourcePath(params.cwd, filePath)), ...backendPaths.flatMap((backendPath) => backendPath.nodes.map((node) => node.source))])].sort(),
+			mapping_context: mappingContext,
+			weights: backendTopologyWeights,
+			backend_paths: backendPaths
+		};
+		artifacts.push(artifact);
+		await params.onArtifact?.(artifact);
+		routeProgress("completed");
+	}
+	return artifacts;
+}
+async function discoverBackendTopologyRouteSelectors(cwd) {
+	const project = new Project({
+		skipAddingFilesFromTsConfig: true,
+		compilerOptions: {
+			allowJs: true,
+			checkJs: false
+		}
+	});
+	return (await globby(["app/_api/**/routes.@(js|ts)", "app/legacy/**/routes.@(js|ts)"], {
+		cwd,
+		absolute: true
+	})).flatMap((routeFile) => extractRouteDeclarations(project.addSourceFileAtPath(routeFile))).map((route) => ({
+		method: route.method,
+		path: route.path
+	}));
+}
+async function generateBackendTopologyArtifactsInWorkers(params) {
+	const selectors = params.routeSelector ? [params.routeSelector] : await discoverBackendTopologyRouteSelectors(params.cwd);
+	params.onRoutesDiscovered?.(selectors.length);
+	const workerCount = Math.min(params.workers || 2, selectors.length);
+	const chunks = Array.from({ length: workerCount }, () => []);
+	selectors.forEach((selector, index) => chunks[index % workerCount].push(selector));
+	const artifacts = [];
+	let completed = 0;
+	let writeQueue = Promise.resolve();
+	const workers = [];
+	try {
+		await Promise.all(chunks.map((routeSelectors) => new Promise((resolve, reject) => {
+			const workerFile = import.meta.url.endsWith(".ts") ? "../workers/routeBackendTopologyWorker.ts" : "./workers/routeBackendTopologyWorker.mjs";
+			const worker = new Worker(new URL(workerFile, import.meta.url), {
+				workerData: {
+					cwd: params.cwd,
+					routeSelectors
+				},
+				execArgv: process.execArgv
+			});
+			workers.push(worker);
+			worker.on("message", (message) => {
+				if (message.type === "error") {
+					reject(new Error(message.message));
+					return;
+				}
+				writeQueue = writeQueue.then(async () => {
+					if (message.type === "artifact") {
+						await params.onArtifact(message.artifact);
+						artifacts.push(message.artifact);
+						return;
+					}
+					completed += 1;
+					params.onRouteProgress?.({
+						current: completed,
+						total: selectors.length,
+						route: message.route,
+						stage: "completed"
+					});
+				}).catch(reject);
+			});
+			worker.once("error", reject);
+			worker.once("exit", (code) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`Topology worker exited with code ${code}`)));
+		})));
+		await writeQueue;
+		return artifacts;
+	} catch (error) {
+		await Promise.all(workers.map((worker) => worker.terminate().catch(() => void 0)));
+		throw error;
+	}
+}
+//#endregion
+export { isKnownBackendType as a, taskProgressService as c, setUserConfig as d, inferBackendNameFromFile as i, getUserConfig as l, generateBackendTopologyArtifactsInWorkers as n, filterAnalysisFiles as o, resolveModulePath as r, shouldKeepAnalysisFile as s, generateBackendTopologyArtifacts as t, loadAtlasConfig as u };

package/dist/workers/routeBackendTopologyWorker.mjs

@@ -0,0 +1,29 @@
+import { t as generateBackendTopologyArtifacts } from "../routeBackendTopologyService-D_aIIBbX.mjs";
+import { parentPort, workerData } from "node:worker_threads";
+//#region src/workers/routeBackendTopologyWorker.ts
+const data = workerData;
+generateBackendTopologyArtifacts({
+	cwd: data.cwd,
+	routeSelectors: data.routeSelectors,
+	onRouteProgress: ({ route, stage }) => {
+		if (stage !== "completed") return;
+		parentPort?.postMessage({
+			type: "progress",
+			route
+		});
+	},
+	onArtifact: async (artifact) => {
+		parentPort?.postMessage({
+			type: "artifact",
+			artifact
+		});
+	}
+}).catch((error) => {
+	parentPort?.postMessage({
+		type: "error",
+		message: error instanceof Error ? error.message : String(error)
+	});
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmflow/atlas",
-  "version": "3.4.0-beta.6",
+  "version": "3.4.0-beta.7",
   "description": "API-to-backend mapping catalogue for Club Med Flow",
   "license": "MIT",
   "author": "romakita",