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

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-DkNyCtKt.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, isCancel, log, note, outro, progress, select } 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();
@@ -181,16 +48,16 @@ function getAggregationTarget(call) {
 	let current = call;
 	while (current) {
 		const parent = current.getParent();
-		if (!parent) return void 0;
+		if (!parent) return;
 		if (Node.isVariableDeclaration(parent)) return normalizeCodeText(parent.getName());
 		if (Node.isReturnStatement(parent)) return "return";
-		if (Node.isStatement(parent)) return void 0;
+		if (Node.isStatement(parent)) return;
 		current = parent;
 	}
 }
 function getAggregationCondition(call) {
 	const callback = call.getArguments().find((argument) => Node.isArrowFunction(argument) || Node.isFunctionExpression(argument));
-	if (!callback || !Node.isArrowFunction(callback) && !Node.isFunctionExpression(callback)) return void 0;
+	if (!callback || !Node.isArrowFunction(callback) && !Node.isFunctionExpression(callback)) return;
 	const body = callback.getBody();
 	if (!Node.isBlock(body)) return normalizeCodeText(body.getText());
 	const condition = body.getDescendantsOfKind(SyntaxKind.IfStatement)[0]?.getExpression();
@@ -268,29 +135,80 @@ var AnalysisCacheService = class {
 };
 const analysisCacheService = new AnalysisCacheService();
 //#endregion
-//#region src/services/openapi/downloadService.ts
-async function downloadOpenApiDocument(url, timeoutMs = getUserConfig().openapiTimeoutMs) {
-	const response = await fetch(url, {
-		headers: { accept: "application/json" },
-		signal: AbortSignal.timeout(timeoutMs)
+//#region src/services/backendPropertyService.ts
+const propertiesBySource = /* @__PURE__ */ new WeakMap();
+async function resolveBackendProperties(sources) {
+	const resolved = await Promise.all(sources.map(async (source) => {
+		if (!source.resolve) return [source.name, void 0];
+		let properties = propertiesBySource.get(source);
+		if (!properties) {
+			properties = source.resolve().then((result) => result.map((property) => ({
+				...property,
+				backend: source.name
+			})));
+			propertiesBySource.set(source, properties);
+		}
+		return [source.name, await properties];
+	}));
+	return new Map(resolved.filter((entry) => entry[1] !== void 0).map(([backend, properties]) => [backend, properties]));
+}
+function matchBackendProperty(field, properties) {
+	if (!properties) return;
+	const normalized = normalizeField(field);
+	return properties.find((property) => {
+		const reference = normalizeField(property.field);
+		return normalized === reference || normalized.endsWith(reference) || reference.endsWith(normalized);
 	});
-	if (!response.ok) throw new Error(`Unable to fetch OpenAPI document from ${url}: ${response.status} ${response.statusText}`);
-	const reader = response.body?.getReader();
-	if (!reader) return response.json();
-	const decoder = new TextDecoder();
-	let content = "";
-	while (true) {
-		const { done, value } = await reader.read();
-		if (done) break;
-		content += decoder.decode(value, { stream: true });
-		taskProgressService.log(`Downloading (${(content.length / 1048576).toFixed(1)} MB)`);
-	}
-	taskProgressService.log("Parsing document");
-	return JSON.parse(content + decoder.decode());
 }
+function normalizeField(value) {
+	return value.replace(/\[locale\]/g, "").replace(/\[\]/g, "").replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+}
+//#endregion
+//#region src/services/http/httpClient.ts
+var HttpClient = class {
+	async fetch(url, init) {
+		const headers = {
+			accept: "application/json",
+			...init?.headers
+		};
+		const response = await fetch(url, {
+			...init,
+			headers
+		});
+		if (!response.ok) throw new Error(`Unable to fetch ${url}: ${response.status} ${response.statusText}`);
+		if (init?.onProgress) {
+			const reader = response.body?.getReader();
+			if (!reader) return response.json();
+			const decoder = new TextDecoder();
+			let content = "";
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				content += decoder.decode(value, { stream: true });
+				init.onProgress(content);
+			}
+			return content + decoder.decode();
+		}
+		return response;
+	}
+	async get(url, init) {
+		return (await this.fetch(url, init)).json();
+	}
+};
+const httpClient = new HttpClient();
+//#endregion
+//#region src/services/openapi/loadOpenApiDocument.ts
 async function loadOpenApiDocument(url, timeoutMs) {
 	try {
-		return await downloadOpenApiDocument(url, timeoutMs);
+		const content = await httpClient.fetch(url, {
+			signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : void 0,
+			onProgress(content) {
+				taskProgressService.log(`Downloading (${(content.length / 1048576).toFixed(1)} MB)`);
+			}
+		});
+		if (!content || typeof content === "object") return content;
+		taskProgressService.log("Parsing document");
+		return JSON.parse(content);
 	} catch (error) {
 		if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) throw new Error(`OpenAPI download timed out after ${timeoutMs}ms: ${url}`);
 		throw new Error(`Unable to fetch OpenAPI document from ${url}: ${error instanceof Error ? error.message : String(error)}`);
@@ -391,22 +309,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 +359,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();
@@ -1382,6 +1239,7 @@ async function collectDependencyFiles(project, entryFilePath, routeLabel, resolv
 }
 async function analyzeCodebaseRouteContracts(params) {
 	const { cwd, openApiDocument: swagger, selectedRouteKeys, routeContracts, onDocument, routeAnalysisScope } = params;
+	const backendProperties = await resolveBackendProperties(userConfig.analysis.backends);
 	taskProgressService.log("Discovering route files");
 	const routeFiles = await globby(["app/_api/**/routes.@(js|ts)", "app/legacy/**/routes.@(js|ts)"], {
 		cwd,
@@ -1443,11 +1301,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) => {
@@ -1470,7 +1329,15 @@ async function analyzeCodebaseRouteContracts(params) {
 		}), (item) => `${item.backend}:${item.method}:${item.route}:${item.sourceFile}`);
 		const backendGraphKey = `${backendSourceFiles.map((file) => file.getFilePath()).sort().join("|")}::${[...reachableBackendFunctionNames].sort().join("|")}`;
 		const backendFieldCandidates = backendFieldsByGraph.get(backendGraphKey) || (() => {
-			const candidates = extractRouteBackendFieldCandidates(backendSourceFiles, reachableBackendFunctionNames, [...apiSourceFiles, ...useCaseSourceFiles]);
+			const candidates = extractRouteBackendFieldCandidates(backendSourceFiles, reachableBackendFunctionNames, [...apiSourceFiles, ...useCaseSourceFiles]).flatMap((candidate) => {
+				const properties = backendProperties.get(candidate.backend);
+				if (!properties) return [candidate];
+				const resolvedProperty = matchBackendProperty(candidate.backendField, properties);
+				return resolvedProperty ? [{
+					...candidate,
+					resolvedProperty
+				}] : [];
+			});
 			backendFieldsByGraph.set(backendGraphKey, candidates);
 			return candidates;
 		})();
@@ -1619,6 +1486,31 @@ function resolveBackendRouteCandidate(document, match) {
 	const sameBackendCandidates = document.backendRouteCandidates.filter((candidate) => candidate.backend === match.backend);
 	return sameBackendCandidates.find((candidate) => candidate.sourceFile === match.sourceFile) || sameBackendCandidates[0];
 }
+function toBackendMapping(document, match) {
+	const resolved = match.resolvedProperty;
+	if (resolved && "document" in resolved) return {
+		backend: match.backend,
+		document: resolved.document,
+		field: resolved.field,
+		description: resolved.description,
+		source_file: backendFieldSource(match),
+		confidence: match.confidence,
+		mapper_type: match.mapperType,
+		reason: match.reviewReason
+	};
+	const backendRouteCandidate = resolved && "route" in resolved ? resolved : resolveBackendRouteCandidate(document, match);
+	return {
+		backend: match.backend,
+		method: backendRouteCandidate?.method || null,
+		route: backendRouteCandidate?.route || "unknown",
+		field: resolved?.field || match.backendField,
+		description: resolved?.description,
+		source_file: backendFieldSource(match),
+		confidence: match.confidence,
+		mapper_type: match.mapperType,
+		reason: match.reviewReason
+	};
+}
 async function buildCatalogue(documents) {
 	const routes = documents.map((document) => ({
 		key: document.key,
@@ -1660,19 +1552,7 @@ async function buildCatalogue(documents) {
 			const backendNames = dedupeByKey(matches.map((candidate) => candidate.backend), (value) => value);
 			const isTransverseWithoutMapping = isTransversalInput(property) && !matches.length;
 			const evidenceStatus = isTransverseWithoutMapping ? "confirmed" : evidenceStatusFromCandidates(matches);
-			const backendMappings = dedupeByKey(matches.map((match) => {
-				const backendRouteCandidate = resolveBackendRouteCandidate(document, match);
-				return {
-					backend: match.backend,
-					method: backendRouteCandidate?.method || null,
-					route: backendRouteCandidate?.route || "unknown",
-					field: match.backendField,
-					source_file: backendFieldSource(match),
-					confidence: match.confidence,
-					mapper_type: match.mapperType,
-					reason: match.reviewReason
-				};
-			}), (mapping) => `${mapping.backend}:${mapping.method || "CALL"}:${mapping.route}:${mapping.field}:${mapping.source_file}`);
+			const backendMappings = dedupeByKey(matches.map((match) => toBackendMapping(document, match)), (mapping) => `${mapping.backend}:${mapping.document || ""}:${mapping.method || "CALL"}:${mapping.route || ""}:${mapping.field}:${mapping.source_file}`);
 			routeInputProperties.push({
 				key: apiPropertyKey,
 				route_key: document.key,
@@ -1703,12 +1583,14 @@ async function buildCatalogue(documents) {
 					route: "unknown",
 					sourceFile: match.sourceFile
 				}).key;
-				const backendPropertyKey = stableKey$2(backendRouteKey, "input", match.backendField);
+				const backendPropertyKey = stableKey$2(backendRouteKey, "input", match.resolvedProperty?.field || match.backendField);
 				backendPropertiesByKey.set(backendPropertyKey, {
 					key: backendPropertyKey,
 					backend_route_key: backendRouteKey,
 					backend: match.backend,
-					field: match.backendField,
+					field: match.resolvedProperty?.field || match.backendField,
+					document: match.resolvedProperty && "document" in match.resolvedProperty ? match.resolvedProperty.document : void 0,
+					description: match.resolvedProperty?.description,
 					direction: "input",
 					source_file: backendFieldSource(match),
 					provenance: "code_analysis"
@@ -1732,19 +1614,7 @@ async function buildCatalogue(documents) {
 			const apiPropertyKey = stableKey$2(document.key, "output", property.path);
 			const backendNames = dedupeByKey(matches.map((candidate) => candidate.backend), (value) => value);
 			const evidenceStatus = evidenceStatusFromCandidates(matches);
-			const backendMappings = dedupeByKey(matches.map((match) => {
-				const backendRouteCandidate = resolveBackendRouteCandidate(document, match);
-				return {
-					backend: match.backend,
-					method: backendRouteCandidate?.method || null,
-					route: backendRouteCandidate?.route || "unknown",
-					field: match.backendField,
-					source_file: backendFieldSource(match),
-					confidence: match.confidence,
-					mapper_type: match.mapperType,
-					reason: match.reviewReason
-				};
-			}), (mapping) => `${mapping.backend}:${mapping.method || "CALL"}:${mapping.route}:${mapping.field}:${mapping.source_file}`);
+			const backendMappings = dedupeByKey(matches.map((match) => toBackendMapping(document, match)), (mapping) => `${mapping.backend}:${mapping.document || ""}:${mapping.method || "CALL"}:${mapping.route || ""}:${mapping.field}:${mapping.source_file}`);
 			routeOutputProperties.push({
 				key: apiPropertyKey,
 				route_key: document.key,
@@ -1775,12 +1645,14 @@ async function buildCatalogue(documents) {
 					route: "unknown",
 					sourceFile: match.sourceFile
 				}).key;
-				const backendPropertyKey = stableKey$2(backendRouteKey, "output", match.backendField);
+				const backendPropertyKey = stableKey$2(backendRouteKey, "output", match.resolvedProperty?.field || match.backendField);
 				backendPropertiesByKey.set(backendPropertyKey, {
 					key: backendPropertyKey,
 					backend_route_key: backendRouteKey,
 					backend: match.backend,
-					field: match.backendField,
+					field: match.resolvedProperty?.field || match.backendField,
+					document: match.resolvedProperty && "document" in match.resolvedProperty ? match.resolvedProperty.document : void 0,
+					description: match.resolvedProperty?.description,
 					direction: "output",
 					source_file: backendFieldSource(match),
 					provenance: "code_analysis"
@@ -1824,7 +1696,7 @@ async function buildCatalogue(documents) {
 	};
 }
 //#endregion
-//#region src/services/directusSyncService.ts
+//#region src/services/directus/directusSyncService.ts
 const ROUTE_STATUSES = { published: "published" };
 const LOCAL_SOURCE_FILE = "digital-api:tools/datasource-catalogue";
 const DIRECTUS_RETRY_MAX_ATTEMPTS = 6;
@@ -2356,14 +2228,14 @@ 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) {
-		console.warn("========================================");
-		console.warn("BIG WARNING: missing predefined values or unresolved Directus links");
-		for (const warning of warnings) console.warn(`- ${warning}`);
-		console.warn("========================================");
+		taskProgressService.log("========================================");
+		taskProgressService.log("BIG WARNING: missing predefined values or unresolved Directus links");
+		for (const warning of warnings) taskProgressService.log(`- ${warning}`);
+		taskProgressService.log("========================================");
 	}
 	return {
 		pushedCollections,
@@ -2403,9 +2275,11 @@ function buildReviewProperty(property) {
 	const backends = property.backend_mappings.map((mapping) => ({
 		type: mapping.backend,
 		field: mapping.field,
+		document: mapping.document,
+		description: mapping.description,
 		source: mapping.source_file,
-		...mapping.route !== "unknown" || mapping.method ? { operation: {
-			method: mapping.method,
+		...mapping.route && (mapping.route !== "unknown" || mapping.method) ? { operation: {
+			method: mapping.method || null,
 			route: mapping.route
 		} } : {},
 		confidence: mapping.confidence,
@@ -2552,12 +2426,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 +2439,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);
@@ -2577,16 +2451,17 @@ async function writeCatalogueArtifacts(catalogue, outputDir, repoRoot = process.
 	};
 }
 function addBackendMapping(routeKey, direction, apiPropertyKey, mapping, backendRoutesByKey, backendPropertiesByKey, mappingEvidence) {
-	const backendRouteKey = stableKey$1(routeKey, mapping.backend, mapping.route);
-	const backendRoute = backendRoutesByKey.get(backendRouteKey) || {
+	const backendRoute = mapping.route || (mapping.document ? `DOCUMENT ${mapping.document}` : "unknown");
+	const backendRouteKey = stableKey$1(routeKey, mapping.backend, backendRoute);
+	const backendRouteRecord = backendRoutesByKey.get(backendRouteKey) || {
 		key: backendRouteKey,
 		backend: mapping.backend,
 		route_key: routeKey,
-		route: `${mapping.method || "CALL"} ${mapping.route}`,
+		route: `${mapping.method || "CALL"} ${backendRoute}`,
 		source_file: mapping.source_file,
 		provenance: "code_analysis"
 	};
-	backendRoutesByKey.set(backendRouteKey, backendRoute);
+	backendRoutesByKey.set(backendRouteKey, backendRouteRecord);
 	const backendPropertyKey = stableKey$1(backendRouteKey, direction, mapping.field);
 	backendPropertiesByKey.set(backendPropertyKey, {
 		key: backendPropertyKey,
@@ -2612,8 +2487,10 @@ function toCatalogueBackendMapping(mapping) {
 	return {
 		backend: mapping.type,
 		method: mapping.operation?.method || null,
-		route: mapping.operation?.route || "unknown",
+		...mapping.operation?.route ? { route: mapping.operation.route } : {},
 		field: mapping.field,
+		document: mapping.document,
+		description: mapping.description,
 		source_file: mapping.source,
 		confidence: mapping.confidence,
 		mapper_type: mapping.mapper_type,
@@ -2744,7 +2621,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;
 		}))),
@@ -2752,7 +2629,7 @@ async function readCatalogueFromDirectory(inputDir) {
 	};
 }
 //#endregion
-//#region src/services/directusPushService.ts
+//#region src/services/directus/directusPushService.ts
 async function pushCatalogueDirectoryToDirectus(params) {
 	const inputPath = path.resolve(params.cwd, params.catalogueDirectory);
 	taskProgressService.report("Loading and reconstructing route YAML documents");
@@ -2921,6 +2798,42 @@ var cleanOrphans_default = (program) => void program.command("clean-orphans").op
 	}
 });
 //#endregion
+//#region src/commands/backendSources.ts
+async function listBackendSourceMetadata(sources, backend) {
+	const selectedSources = backend ? sources.filter((source) => source.name === backend) : sources;
+	if (backend && !selectedSources.length) throw new Error(`Unknown backend source: ${backend}`);
+	const propertiesByBackend = await resolveBackendProperties(selectedSources);
+	return selectedSources.map((source) => ({
+		backend: source.name,
+		properties: propertiesByBackend.get(source.name) || []
+	}));
+}
+var backendSources_default = (program) => void program.command("backend-sources").option("--backend <name>", "Only execute one backend source").description("Execute configured backend sources and display their resolved property metadata").action(async (options) => {
+	intro("Atlas backend source metadata");
+	try {
+		const sources = getUserConfig().analysis.backends;
+		const selectedBackend = options.backend || await select({
+			message: "Which backend source do you want to execute?",
+			options: sources.map((source) => ({
+				value: source.name,
+				label: source.name,
+				hint: source.resolve ? "resolver configured" : "no resolver configured"
+			}))
+		});
+		if (isCancel(selectedBackend)) {
+			cancel("Backend source execution cancelled");
+			process.exitCode = 1;
+			return;
+		}
+		const metadata = await listBackendSourceMetadata(sources, selectedBackend);
+		log.message(JSON.stringify(metadata, null, 2));
+		outro("Backend source metadata generated");
+	} catch (error) {
+		cancel(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	}
+});
+//#endregion
 //#region src/services/analysisProfileService.ts
 function createAnalysisProfile(enabled) {
 	const durations = /* @__PURE__ */ new Map();
@@ -2938,8 +2851,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 +2871,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 +2892,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 +2992,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 +3000,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);
@@ -3333,7 +3148,7 @@ var generateTest_default = (program) => void program.command("generate:test").de
 	}
 });
 //#endregion
-//#region src/services/aiSdkClient.ts
+//#region src/services/ai/aiSdkClient.ts
 var AISdkClient = class {
 	#config;
 	constructor(config) {
@@ -3364,7 +3179,7 @@ var AISdkClient = class {
 	}
 };
 //#endregion
-//#region src/services/inferenceService.ts
+//#region src/services/ai/inferenceService.ts
 const MAPPING_OUTPUT_SCHEMA = z.object({ mappings: z.array(z.object({
 	property_index: z.number().int(),
 	candidate_index: z.number().int(),
@@ -3439,7 +3254,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 +4020,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 +4164,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 +4172,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 +4290,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,9 +4311,11 @@ 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);
+backendSources_default(program);
 generate_default(program);
 generateGraph_default(program);
 generateTest_default(program);