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

package/README.md

@@ -64,17 +64,41 @@ export default defineConfig({
 });
 ```
 
-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.
+`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.
@@ -96,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.
@@ -173,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")
@@ -302,6 +337,13 @@ atlas --analysis-dir /path/to/api generate:catalog --output .tmp/datasource-cata
 
 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
@@ -329,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/{UserConfig-aqAuodcW.d.mts → UserConfig-BlRknCRh.d.mts}

@@ -44,6 +44,8 @@ type BackendProperty = PropertyMetadata & ({
 //#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[];
 }
@@ -137,4 +139,4 @@ interface UserConfig {
 }
 //#endregion
 export { defineExpressionRule as a, FieldExtractionRule as i, BackendSource as n, BackendProperty as r, UserConfig as t };
-//# sourceMappingURL=UserConfig-aqAuodcW.d.mts.map
+//# sourceMappingURL=UserConfig-BlRknCRh.d.mts.map