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

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,22 +58,47 @@ 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.
+`process.cwd()` is always the project root: `outputDir`, `tsconfig.json`, Git paths and serialized source paths are resolved from it. `analysis.rootDir` only defines the source tree to analyze and may therefore point to a subdirectory such as `./app`. Atlas reads `compilerOptions.paths` from the root `tsconfig.json` and uses them as module aliases. Add `resolver.alias` only to override or complement those aliases.
+
+`outputDir` is resolved from the project root, not from `analysis.rootDir`. With the configuration above, artifacts are written to `<project-root>/tmp/atlas`, never to `<project-root>/app/tmp/atlas`.
+
+Use `analysis.excluded` for project-root-relative technical files that must not enter dependency traversal or `analysis_files`:
+
+```ts
+analysis: {
+  rootDir: "./app",
+  excluded: ["tools/build/*-reference.json"],
+  backends: [/* ... */]
+}
+```
 
 ## Backend sources
 
-Atlas extracts a candidate mapping from code, then optionally consolidates it against a strict backend field reference. Configure these references in the same `analysis.backends` list used to declare backends.
+Atlas starts from accesses actually detected in code on a backend reached by the route graph. It then consolidates those code candidates against the canonical properties returned by the matching `BackendSource`. Atlas never creates a confirmed mapping from API field-name similarity alone.
+
+For a backend with no configured source, Atlas preserves code candidates for optional AI inference. A configured source is authoritative: only its resolved properties can validate the code access.
 
 A backend can be either a string or a `BackendSource` created with `defineBackendSource`:
 
 - a string (for example `"ICC"`) has no field reference; Atlas keeps the current code-analysis and optional inference flow;
 - a `BackendSource` provides a `resolve` function that returns the backend's known properties. Atlas assigns its `name` as `backend` on every resolved property.
 
+Any backend source can persist its resolved properties in a YAML cache. When the cache exists, Atlas uses it and does not call the remote source. Refresh it explicitly with `atlas backend-source --refresh` (or the compatible `atlas backend-sources --refresh`). Use `atlas backend-sources --refresh --all` to refresh every configured source without an interactive prompt.
+
+```ts
+export const xm = defineBackendSource({
+  name: "XM",
+  cache: `${__dirname}/cache.yaml`,
+  resolve: () => openapiSource({ url: "https://xm.example/openapi.json" })
+});
+```
+
 When a string and a source share the same name, the last declaration wins. This lets a source enrich a list of backend names, for example `[..., Object.values(BackendTypes), quableBackendSource]`.
 
 The resolver returns one of the following shapes. Document-oriented backends have no route; REST backends have no document.
@@ -94,6 +120,16 @@ type BackendProperty =
 
 The generated mapping preserves this shape. In particular, `document` is a separate property: Atlas does not turn a Quable field into an artificial path such as `products.product_geographical_area`.
 
+## Resolved backend metadata artifacts
+
+At the start of `generate:graph` and `generate:catalog`, Atlas resolves every configured backend source and writes its metadata for inspection:
+
+```text
+<outputDir>/backends/<backend>.yaml
+```
+
+For example, `<outputDir>/backends/quable_rest.yaml` contains the source name, generation date and canonical properties returned by Quable. Backends declared as strings still receive an artifact with `resolved: false`; this makes missing metadata sources visible during analysis.
+
 ### Quable
 
 Attach rules that are specific to Quable directly to its source. They inherit the source backend automatically and their candidates are validated by the Quable property list.
@@ -171,6 +207,7 @@ import { constant, defineBackendSource, openapiSource } from "@cmflow/atlas";
 
 export const xm = defineBackendSource({
   name: "XM",
+  cache: `${__dirname}/xm-openapi.yaml`,
   resolve: () =>
     openapiSource({
       url: constant<string>("XM_API_URL", "https://xm.example/openapi.json")
@@ -294,23 +331,30 @@ 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`.
 
+When changing `analysis.rootDir`, backend sources or exclusions, regenerate the graph before the catalogue so the route graph and metadata artifacts use the same configuration:
+
+```bash
+atlas generate:graph "GET /v2/products"
+atlas generate:catalog "GET /v2/products"
+```
+
 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 +362,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.
@@ -327,7 +371,8 @@ Without `--write`, the command performs a dry run. Use `clean-orphans` to inspec
 
 ```text
 atlas init                         Create atlas.config.ts
-atlas backend-sources              Execute backend sources and display resolved metadata
+atlas backend-source [--refresh]         Display backend metadata; refresh configured source caches when requested
+atlas backend-sources [--refresh] [--all] Compatible plural alias; --all skips the source picker
 atlas generate:graph               Trace API routes to backends
 atlas generate:catalog [route]     Generate route review documents
 atlas generate:test                Check configured coverage baselines

package/dist/{types-D5fngFrb.d.mts → UserConfig-BlRknCRh.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,27 @@ type BackendProperty = {
   method: string;
   field: string;
   description?: string;
-};
+});
+//#endregion
+//#region src/interfaces/BackendSource.d.ts
 interface BackendSource {
   name: string;
+  /** YAML file containing resolved properties. Existing caches are read before calling `resolve`. */
+  cache?: 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 +96,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 +138,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-BlRknCRh.d.mts.map