@cmflow/atlas 3.4.0-beta.23 → 3.4.0-beta.24

package/README.md

@@ -42,7 +42,7 @@ atlas init
 atlas --config /path/to/api/atlas.config.ts init
 ```
 
-By default, Atlas loads `atlas.config.ts` from the directory where the command is launched. Use `--config` (or `-c`) to reference another configuration file. Use `--project-root` only to override the API project directory to analyze.
+By default, Atlas loads `atlas.config.ts` from the directory where the command is launched. Use `--config` (or `-c`) to reference another configuration file. Use `--analysis-dir` only to override the API source directory to analyze.
 
 The configuration imports `defineConfig` from Atlas:
 
@@ -50,6 +50,7 @@ The configuration imports `defineConfig` from Atlas:
 import { defineConfig } from "@cmflow/atlas";
 
 export default defineConfig({
+  outputDir: "./tmp/atlas",
   envs: {
     XM_API_URL: "https://xm.example/openapi.json"
   },
@@ -57,12 +58,13 @@ export default defineConfig({
   openapiTimeoutMs: 60_000,
   directusUrl: "https://cms.api.clubmed",
   analysis: {
+    rootDir: "./app",
     backends: ["ICC", "CMS", "CMS_B2C"]
   }
 });
 ```
 
-Atlas reads `compilerOptions.paths` from the `tsconfig.json` in the directory where the command is run (`process.cwd()`) and uses them as module aliases. `repoRoot` only defines the source tree to analyze and may therefore point to a subdirectory. Add `resolver.alias` only to override or complement those aliases.
+Atlas reads `compilerOptions.paths` from the `tsconfig.json` in the directory where the command is run (`process.cwd()`) and uses them as module aliases. `analysis.rootDir` only defines the source tree to analyze and may therefore point to a subdirectory. Add `resolver.alias` only to override or complement those aliases.
 
 ## Backend sources
 
@@ -294,8 +296,8 @@ DIRECTUS_TOKEN=replace-with-a-static-token
 Generate the topology first, then the route catalogue:
 
 ```bash
-atlas --project-root /path/to/api generate:graph
-atlas --project-root /path/to/api generate:catalog --output .tmp/datasource-catalogue
+atlas --analysis-dir /path/to/api generate:graph
+atlas --analysis-dir /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`.
@@ -303,14 +305,14 @@ Each route produces a YAML document and a `.graph.yaml` topology artifact. The c
 Check configured coverage baselines:
 
 ```bash
-atlas --project-root /path/to/api generate:test
+atlas --analysis-dir /path/to/api generate:test
 ```
 
 Review unresolved mappings or run optional AI inference:
 
 ```bash
-atlas --project-root /path/to/api needs-review --sort percentage --limit 25
-atlas --project-root /path/to/api infer .tmp/datasource-catalogue
+atlas --analysis-dir /path/to/api needs-review --sort percentage --limit 25
+atlas --analysis-dir /path/to/api infer .tmp/datasource-catalogue
 ```
 
 The inference pass only reads analysis files referenced by each route graph. Accepted suggestions remain marked `inferred`; suggestions below the configured confidence threshold are retained for manual review.
@@ -318,7 +320,7 @@ The inference pass only reads analysis files referenced by each route graph. Acc
 Push route artifacts to Directus with an explicit write flag:
 
 ```bash
-atlas --project-root /path/to/api push .tmp/datasource-catalogue --write
+atlas --analysis-dir /path/to/api push .tmp/datasource-catalogue --write
 ```
 
 Without `--write`, the command performs a dry run. Use `clean-orphans` to inspect Directus links that no longer reference an API or backend property.

package/dist/{types-D5fngFrb.d.mts → UserConfig-aqAuodcW.d.mts}

@@ -16,12 +16,21 @@ type FieldExtractionRule = {
 };
 declare function defineExpressionRule(rule: FieldExtractionRule): FieldExtractionRule;
 //#endregion
-//#region src/models/types.d.ts
-interface NeutralExpressionMatcher {
-  prefix: string;
-  apiMapping?: boolean;
+//#region src/interfaces/Direction.d.ts
+type Direction = "input" | "output";
+//#endregion
+//#region src/interfaces/PropertyLocation.d.ts
+type PropertyLocation = "query" | "path" | "header" | "body";
+//#endregion
+//#region src/interfaces/PropertyMetadata.d.ts
+interface PropertyMetadata {
+  direction?: Direction;
+  location?: PropertyLocation;
+  type?: string;
 }
-type BackendProperty = {
+//#endregion
+//#region src/interfaces/BackendProperty.d.ts
+type BackendProperty = PropertyMetadata & ({
   document: string;
   field: string;
   description?: string;
@@ -30,20 +39,25 @@ type BackendProperty = {
   method: string;
   field: string;
   description?: string;
-};
+});
+//#endregion
+//#region src/interfaces/BackendSource.d.ts
 interface BackendSource {
   name: string;
   resolve?: () => Promise<BackendProperty[]>;
   rules?: FieldExtractionRule[];
 }
+//#endregion
+//#region src/config/interfaces/UserConfig.d.ts
+interface NeutralExpressionMatcher {
+  prefix: string;
+  apiMapping?: boolean;
+}
 interface UserConfig {
   /** Values injectable into backend source resolvers through `constant`. */
   envs?: Record<string, unknown>;
-  /**
-   * Absolute path to the root of the repository to analyze (e.g. the digital-api repo).
-   * Can be set via the ATLAS_CWD environment variable.
-   */
-  repoRoot?: string;
+  /** Directory where Atlas writes generated graph and catalogue artifacts, resolved from `process.cwd()`. */
+  outputDir: string;
   /**
    * Default OpenAPI document URL used to extract the public contract exposed by the API.
    * The CLI can still override this value with `--openapi-url`.
@@ -80,10 +94,12 @@ interface UserConfig {
    * Static analysis options used to keep generated artifacts focused on business-relevant files and fields.
    */
   analysis: {
+    /** Directory containing the application source tree to analyze, resolved from `process.cwd()`. */
+    rootDir: string;
     /** Backend identifiers used by the API project. */
     backends: Array<string | BackendSource>;
     /**
-     * Glob patterns excluded from `analysis_files`.
+     * Glob patterns, relative to the project working directory, excluded from `analysis_files`.
      * Use this to hide technical plumbing files that add noise to route review documents.
      */
     excluded: string[];
@@ -120,5 +136,5 @@ interface UserConfig {
   };
 }
 //#endregion
-export { defineExpressionRule as a, FieldExtractionRule as i, BackendSource as n, UserConfig as r, BackendProperty as t };
-//# sourceMappingURL=types-D5fngFrb.d.mts.map
+export { defineExpressionRule as a, FieldExtractionRule as i, BackendSource as n, BackendProperty as r, UserConfig as t };
+//# sourceMappingURL=UserConfig-aqAuodcW.d.mts.map

package/dist/bin/atlas.mjs

@@ -2,9 +2,9 @@
 import { fileURLToPath as __atlasFileURLToPath } from "node:url";
 const __filename = __atlasFileURLToPath(import.meta.url);
 import { n as __require, r as __toESM, t as __commonJSMin } from "../rolldown-runtime-CGR6nZuH.mjs";
-import { a as note, c as select, d as setUserConfig, f as userConfig$1, i as log, l as isCancel, n as cancel, o as outro, r as intro, s as progress, t as taskProgressService, u as getUserConfig } from "../taskProgressService-CAC_RIoa.mjs";
-import { a as inferBackendNameFromFile, c as shouldKeepAnalysisFile, i as resolveModulePath, l as normalizeFilePath, n as generateBackendTopologyArtifactsInWorkers, o as isKnownBackendType, r as matchesRouteSelector, s as filterAnalysisFiles, u as globby } from "../routeBackendTopologyService-CQyRyoSN.mjs";
-import { i as loadOpenApiDocument, n as extractOpenApiInputProperties, r as extractOpenApiOutputProperties } from "../propertyExtractionService-BLat-Hsf.mjs";
+import { a as note, c as select, d as setUserConfig, f as userConfig$1, i as log, l as isCancel, n as cancel, o as outro, r as intro, s as progress, t as taskProgressService, u as getUserConfig } from "../taskProgressService-BRoIJQbK.mjs";
+import { a as resolveModulePath, c as filterAnalysisFiles, d as globby, i as matchesRouteSelector, l as shouldKeepAnalysisFile, n as generateBackendTopologyArtifactsInWorkers, o as inferBackendNameFromFile, s as isKnownBackendType, u as normalizeFilePath } from "../routeBackendTopologyService-NPO-ZHyY.mjs";
+import { i as loadOpenApiDocument, n as extractOpenApiInputProperties, r as extractOpenApiOutputProperties } from "../propertyExtractionService-CTQFyLdy.mjs";
 import { n as require_auth_errors, r as require_token_error, t as require_token_util } from "../token-util-Dnzm6rU4.mjs";
 import path from "node:path";
 import { Node, Project, SyntaxKind } from "ts-morph";
@@ -4154,7 +4154,7 @@ function collectReachableBackendFunctionNames(entrySourceFiles, backendSourceFil
 	}
 	return reachable;
 }
-function resolveHandlerFile(routeSourceFile, handlerRef, resolvePath = (sourceFilePath, moduleSpecifier) => resolveModulePath(sourceFilePath, moduleSpecifier, userConfig.resolver.alias, userConfig.repoRoot)) {
+function resolveHandlerFile(routeSourceFile, handlerRef, resolvePath = (sourceFilePath, moduleSpecifier) => resolveModulePath(sourceFilePath, moduleSpecifier, userConfig.resolver.alias, userConfig.analysis.rootDir)) {
 	if (!handlerRef) return {};
 	if (!handlerRef.includes(".")) {
 		if (routeSourceFile.getFunction(handlerRef) || routeSourceFile.getVariableDeclaration(handlerRef)) return {
@@ -4184,7 +4184,7 @@ function resolveHandlerFile(routeSourceFile, handlerRef, resolvePath = (sourceFi
 async function yieldToEventLoop() {
 	await new Promise((resolve) => setImmediate(resolve));
 }
-async function collectDependencyFiles(project, entryFilePath, routeLabel, resolvePath = (sourceFilePath, moduleSpecifier) => resolveModulePath(sourceFilePath, moduleSpecifier, userConfig.resolver.alias, userConfig.repoRoot)) {
+async function collectDependencyFiles(project, entryFilePath, routeLabel, resolvePath = (sourceFilePath, moduleSpecifier) => resolveModulePath(sourceFilePath, moduleSpecifier, userConfig.resolver.alias, userConfig.analysis.rootDir)) {
 	const queue = [entryFilePath];
 	const visited = /* @__PURE__ */ new Set();
 	while (queue.length) {
@@ -4214,7 +4214,7 @@ 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)"], {
+	const routeFiles = await globby(["_api/**/routes.@(js|ts)", "legacy/**/routes.@(js|ts)"], {
 		cwd,
 		absolute: true
 	});
@@ -4250,7 +4250,7 @@ async function analyzeCodebaseRouteContracts(params) {
 	const resolveCachedModulePath = (sourceFilePath, moduleSpecifier) => {
 		const key = `${sourceFilePath}${moduleSpecifier}`;
 		if (resolvedModulePaths.has(key)) return resolvedModulePaths.get(key);
-		const resolved = resolveModulePath(sourceFilePath, moduleSpecifier, userConfig.resolver.alias, userConfig.repoRoot);
+		const resolved = resolveModulePath(sourceFilePath, moduleSpecifier, userConfig.resolver.alias, process.cwd());
 		resolvedModulePaths.set(key, resolved);
 		return resolved;
 	};
@@ -12153,7 +12153,7 @@ async function readCatalogueFromDirectory(inputDir) {
 //#endregion
 //#region src/services/directus/pushCatalogueDirectoryToDirectus.ts
 async function pushCatalogueDirectoryToDirectus(params) {
-	const inputPath = path.resolve(params.cwd, params.catalogueDirectory);
+	const inputPath = path.resolve(params.cwd, params.catalogueDirectory ?? getUserConfig().outputDir);
 	taskProgressService.report("Loading and reconstructing route YAML documents");
 	const { catalogue, files } = await readCatalogueFromDirectory(inputPath);
 	taskProgressService.report(`${files.length} route documents loaded, ${catalogue.backend_routes.length} backend routes reconstructed`);
@@ -12187,7 +12187,6 @@ function parseRouteSelector(value) {
 
 //#endregion
 //#region src/commands/push.ts
-const DEFAULT_CATALOGUE_DIRECTORY = ".tmp/datasource-catalogue";
 function formatPushError(error) {
 	if (error instanceof Error) return error.message;
 	if (!isRecord$1(error)) return String(error);
@@ -12255,15 +12254,15 @@ function createPushStepClassifier() {
 		};
 	};
 }
-var push_default = (program) => void program.command("push").argument("[catalogue-directory-or-route]", "Directory or route such as \"GET /v1/offers\"", DEFAULT_CATALOGUE_DIRECTORY).option("--route <route>", "Push one route only, for example \"POST /v0/accommodations_arrangement/check\"").option("--write", "Persist changes to Directus", false).description("Push generated per-route YAML documents to Directus").action(async (catalogueDirectoryOrRoute, options) => {
+var push_default = (program) => void program.command("push").argument("[catalogue-directory-or-route]", "Directory or route such as \"GET /v1/offers\"").option("--route <route>", "Push one route only, for example \"POST /v0/accommodations_arrangement/check\"").option("--write", "Persist changes to Directus", false).description("Push generated per-route YAML documents to Directus").action(async (catalogueDirectoryOrRoute, options) => {
 	intro("Datasource catalogue push");
 	const { cwd } = getUserConfig();
 	const progress = taskProgressService.createStepProgress(createPushStepClassifier());
 	try {
-		const positionalRouteSelector = isRouteSelector(catalogueDirectoryOrRoute) ? parseRouteSelector(catalogueDirectoryOrRoute) : void 0;
+		const positionalRouteSelector = catalogueDirectoryOrRoute && isRouteSelector(catalogueDirectoryOrRoute) ? parseRouteSelector(catalogueDirectoryOrRoute) : void 0;
 		if (options.route && positionalRouteSelector) throw new Error("Specify the route either as the positional argument or with --route, not both");
 		const routeSelector = options.route ? parseRouteSelector(options.route) : positionalRouteSelector;
-		const catalogueDirectory = positionalRouteSelector ? DEFAULT_CATALOGUE_DIRECTORY : catalogueDirectoryOrRoute;
+		const catalogueDirectory = positionalRouteSelector ? void 0 : catalogueDirectoryOrRoute;
 		const pushResult = await progress.execute(() => pushCatalogueDirectoryToDirectus({
 			cwd,
 			catalogueDirectory,
@@ -12435,6 +12434,28 @@ async function loadBackendTopologyAnalysisScope(outputDir, cwd, method, routePat
 	};
 }
 
+//#endregion
+//#region src/services/backendMetadataArtifactService.ts
+function backendMetadataFileName(backend) {
+	return `${backend.toLowerCase()}.yaml`;
+}
+async function writeBackendMetadataArtifacts(params) {
+	const directory = path.join(params.outputDir, "backends");
+	await fsPromises.mkdir(directory, { recursive: true });
+	return Promise.all(params.sources.map(async (source) => {
+		const filePath = path.join(directory, backendMetadataFileName(source.name));
+		const properties = params.propertiesByBackend.get(source.name) || [];
+		await fsPromises.writeFile(filePath, `${(0, import_dist$1.stringify)({
+			schema_version: 1,
+			generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+			backend: source.name,
+			resolved: Boolean(source.resolve),
+			properties
+		})}\n`);
+		return filePath;
+	}));
+}
+
 //#endregion
 //#region src/commands/generate.ts
 async function generateHandler(cwd, routeArgument, options) {
@@ -12443,7 +12464,7 @@ async function generateHandler(cwd, routeArgument, options) {
 	const routeSelector = parseRouteSelector(routeArgument);
 	const profile = createAnalysisProfile(Boolean(options.profile));
 	try {
-		const outputDir = path.resolve(cwd, options.output);
+		const outputDir = path.resolve(cwd, options.output ?? getUserConfig().outputDir);
 		await progress$3.run({
 			id: "artifacts",
 			title: "Preparing route documents",
@@ -12457,6 +12478,20 @@ async function generateHandler(cwd, routeArgument, options) {
 			completedTitle: "OpenAPI contract loaded"
 		}, () => loadOpenApiDocument(options.openapiUrl));
 		profile.add("OpenAPI", performance.now() - openApiStartedAt);
+		const backendMetadataStartedAt = performance.now();
+		await progress$3.run({
+			id: "backend-metadata",
+			title: "Loading backend metadata",
+			completedTitle: "Backend metadata loaded"
+		}, async () => {
+			const config = getUserConfig();
+			await writeBackendMetadataArtifacts({
+				outputDir,
+				sources: config.analysis.backends,
+				propertiesByBackend: await resolveBackendProperties(config.analysis.backends)
+			});
+		});
+		profile.add("Backend metadata", performance.now() - backendMetadataStartedAt);
 		const selectedRouteKeys = routeSelector ? /* @__PURE__ */ new Set([stableKey(routeSelector.method, routeSelector.path)]) : void 0;
 		const totalRoutes = routeSelector ? 1 : Object.values(openApiDocument.paths || {}).reduce((total, pathItem) => total + Object.keys(pathItem || {}).filter((method) => /^(get|post|put|patch|delete|head|options)$/i.test(method)).length, 0);
 		const analysisStartedAt = performance.now();
@@ -12474,7 +12509,7 @@ async function generateHandler(cwd, routeArgument, options) {
 			selectedRouteKeys,
 			routeAnalysisScope: async ({ method, path: routePath }) => {
 				try {
-					return await loadBackendTopologyAnalysisScope(outputDir, cwd, method, routePath);
+					return await loadBackendTopologyAnalysisScope(outputDir, process.cwd(), method, routePath);
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);
 					taskProgressService.log(`Warning: ${message} Route skipped.`);
@@ -12486,7 +12521,7 @@ async function generateHandler(cwd, routeArgument, options) {
 				analyzedRoutes += 1;
 				analysisProgress.advance(1, `Analyzing · [${analyzedRoutes}/${totalRoutes}] routes · ${document.method} ${document.path} ...`);
 				const routeCatalogue = await buildCatalogue([document]);
-				await writeRouteReviewDocument(routeCatalogue, outputDir, cwd, document.key);
+				await writeRouteReviewDocument(routeCatalogue, outputDir, process.cwd(), document.key);
 				profile.add("Artifacts", performance.now() - artifactStartedAt);
 			}
 		});
@@ -12514,7 +12549,7 @@ async function generateHandler(cwd, routeArgument, options) {
 		process.exit(1);
 	}
 }
-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) => {
+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, overriding outputDir").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,
@@ -12559,7 +12594,19 @@ async function generateGraphHandler(cwd, routeArgument, options) {
 	});
 	try {
 		const routeSelector = parseRouteSelector(routeArgument);
-		const outputDir = path.resolve(cwd, options.output);
+		const outputDir = path.resolve(cwd, options.output ?? getUserConfig().outputDir);
+		const config = getUserConfig();
+		await progress$2.run({
+			id: "backend-metadata",
+			title: "Loading backend metadata",
+			completedTitle: "Backend metadata loaded"
+		}, async () => {
+			await writeBackendMetadataArtifacts({
+				outputDir,
+				sources: config.analysis.backends,
+				propertiesByBackend: await resolveBackendProperties(config.analysis.backends)
+			});
+		});
 		const workerCount = options.workers ?? 2;
 		const files = [];
 		let routeProgress;
@@ -12603,7 +12650,7 @@ async function generateGraphHandler(cwd, routeArgument, options) {
 		process.exitCode = 1;
 	}
 }
-var generateGraph_default = (program) => void program.command("generate:graph").argument("[route]", "Optional route selector in the format \"GET /v1/products\"").option("-o, --output <directory>", "Directory where backend graph artifacts are generated", ".tmp/datasource-catalogue").option("-w, --workers <count>", "Maximum number of topology workers", parseWorkerCount$1, 2).description("Generate weighted call graphs from API routes to backend types").action((routeArgument, options) => {
+var generateGraph_default = (program) => void program.command("generate:graph").argument("[route]", "Optional route selector in the format \"GET /v1/products\"").option("-o, --output <directory>", "Directory where backend graph artifacts are generated, overriding outputDir").option("-w, --workers <count>", "Maximum number of topology workers", parseWorkerCount$1, 2).description("Generate weighted call graphs from API routes to backend types").action((routeArgument, options) => {
 	const { cwd } = getUserConfig();
 	return generateGraphHandler(cwd, routeArgument, options);
 });
@@ -29859,6 +29906,7 @@ function formatInferenceFailure(error) {
 	return (error instanceof Error ? error.message : String(error)).split(" Raw response:")[0];
 }
 async function inferCatalogueDirectory(params) {
+	const workspaceRoot = params.workspaceRoot || params.cwd;
 	const inputPath = path.resolve(params.cwd, params.catalogueDirectory);
 	const outputPath = path.resolve(params.cwd, params.outputDirectory || params.catalogueDirectory);
 	taskProgressService.report("Loading route YAML documents");
@@ -29882,7 +29930,7 @@ async function inferCatalogueDirectory(params) {
 	const unresolvedProperties = [...catalogue.route_input_properties, ...catalogue.route_output_properties].filter((property) => property.evidence_status === "needs_review").filter((property) => !selectedRoute || property.route_key === selectedRoute.key);
 	if (outputPath !== inputPath) {
 		taskProgressService.report("Copying source YAML documents to the output directory");
-		await writeCatalogueArtifacts(catalogue, outputPath, params.cwd);
+		await writeCatalogueArtifacts(catalogue, outputPath, workspaceRoot);
 	}
 	if (!unresolvedProperties.length) return {
 		inputPath,
@@ -29953,12 +30001,12 @@ async function inferCatalogueDirectory(params) {
 			input: catalogue.route_input_properties.filter((property) => property.route_key === routeKey).map((property) => ({
 				path: property.field,
 				description: property.description,
-				type: "BODY"
+				location: "body"
 			})),
 			output: catalogue.route_output_properties.filter((property) => property.route_key === routeKey).map((property) => ({
 				path: property.field,
 				description: property.description,
-				type: "RESPONSE_BODY"
+				location: "body"
 			}))
 		}]]);
 		reportRoute("Static analysis refresh");
@@ -29968,7 +30016,7 @@ async function inferCatalogueDirectory(params) {
 			routeContracts,
 			routeAnalysisScope: async ({ method, path: routePath }) => {
 				try {
-					return await loadBackendTopologyAnalysisScope(inputPath, params.cwd, method, routePath);
+					return await loadBackendTopologyAnalysisScope(inputPath, workspaceRoot, method, routePath);
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);
 					graphErrors.set(`${method} ${routePath}`, message);
@@ -29995,7 +30043,7 @@ async function inferCatalogueDirectory(params) {
 		if (!remainingRouteProperties.length) {
 			refreshStats(catalogue);
 			reportRoute("Update artifacts");
-			await writeRouteReviewDocument(catalogue, outputPath, params.cwd, routeKey);
+			await writeRouteReviewDocument(catalogue, outputPath, workspaceRoot, routeKey);
 			params.onWorkerProgress?.({
 				workerId,
 				total: routeKeys.length,
@@ -30020,7 +30068,7 @@ async function inferCatalogueDirectory(params) {
 			taskProgressService.log(`Warning: AI inference failed for ${route.method} ${route.path}: ${formatInferenceFailure(error)}. Route kept for review.`);
 			refreshStats(catalogue);
 			reportRoute("Update artifacts");
-			await writeRouteReviewDocument(catalogue, outputPath, params.cwd, routeKey);
+			await writeRouteReviewDocument(catalogue, outputPath, workspaceRoot, routeKey);
 			params.onWorkerProgress?.({
 				workerId,
 				total: routeKeys.length,
@@ -30048,7 +30096,7 @@ async function inferCatalogueDirectory(params) {
 		}
 		refreshStats(catalogue);
 		reportRoute("Update artifacts");
-		await writeRouteReviewDocument(catalogue, outputPath, params.cwd, routeKey);
+		await writeRouteReviewDocument(catalogue, outputPath, workspaceRoot, routeKey);
 		params.onWorkerProgress?.({
 			workerId,
 			total: routeKeys.length,
@@ -30152,6 +30200,7 @@ var infer_default = (program) => void program.command("infer").argument("[route-
 		let completedRoutes = 0;
 		const result = await progress$1.execute(() => inferCatalogueDirectory({
 			cwd: config.cwd,
+			workspaceRoot: process.cwd(),
 			catalogueDirectory,
 			routeSelector,
 			outputDirectory: options.output,
@@ -30214,7 +30263,7 @@ const configTemplate = `import { defineConfig } from "@cmflow/atlas";
 
 export default defineConfig({
   envs: {},
-  repoRoot: process.cwd(),
+  outputDir: "./.tmp/atlas",
   openapiUrl: "https://api.example.com/openapi.json",
   openapiTimeoutMs: 60_000,
   directusUrl: "https://cms.api.clubmed",
@@ -30226,6 +30275,7 @@ export default defineConfig({
     workers: 2
   },
   analysis: {
+    rootDir: "./app",
     backends: [],
     excluded: [],
     transversalInputs: [],
@@ -30476,8 +30526,8 @@ async function readChangedFiles(filePath) {
 //#region src/commands/reportChanged.ts
 async function reportChangedHandler(cwd, options) {
 	const config = getUserConfig();
-	const outputDirectory = path.resolve(cwd, options.output);
-	const changedFiles = await readChangedFiles(path.resolve(cwd, options.changedFiles));
+	const outputDirectory = path.resolve(cwd, options.output ?? config.outputDir);
+	const changedFiles = await readChangedFiles(path.resolve(process.cwd(), options.changedFiles));
 	const impactedRoutes = collectImpactedRoutes({
 		changedFiles,
 		graphs: await readRouteGraphs(outputDirectory)
@@ -30490,7 +30540,7 @@ async function reportChangedHandler(cwd, options) {
 				cwd,
 				openApiDocument,
 				selectedRouteKeys: /* @__PURE__ */ new Set([stableKey(route.method, route.path)]),
-				routeAnalysisScope: ({ method, path: routePath }) => loadBackendTopologyAnalysisScope(outputDirectory, cwd, method, routePath)
+				routeAnalysisScope: ({ method, path: routePath }) => loadBackendTopologyAnalysisScope(outputDirectory, process.cwd(), method, routePath)
 			});
 			if (documents.length !== 1) throw new Error("Route was not found in the OpenAPI contract");
 			const catalogue = await buildCatalogue(documents);
@@ -30522,12 +30572,12 @@ async function reportChangedHandler(cwd, options) {
 		changedFiles,
 		routes: coverages
 	});
-	const reportPath = path.resolve(cwd, options.report);
+	const reportPath = path.resolve(cwd, options.report ?? path.join(config.outputDir, "changed-routes-report.md"));
 	await fsPromises.mkdir(path.dirname(reportPath), { recursive: true });
 	await fsPromises.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) => {
+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, overriding outputDir").option("--report <file>", "Markdown report output path; defaults to outputDir/changed-routes-report.md").description("Report deterministic mapping coverage for routes impacted by changed files").action(async (options) => {
 	intro("Datasource changed-route report");
 	const { cwd } = getUserConfig();
 	try {
@@ -30543,9 +30593,9 @@ var reportChanged_default = (program) => void program.command("report:changed").
 //#region src/bin/atlas.ts
 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) => {
+program.name("atlas").description("Manage the API-to-backend mapping catalogue").option("--analysis-dir <path>", "Directory containing the API source tree 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;
-	const config = await userConfig$1(program.opts().config, program.opts().projectRoot);
+	const config = await userConfig$1(program.opts().config, program.opts().analysisDir);
 	setUserConfig(config);
 });
 init_default(program, program);