@cmflow/atlas 3.4.0-beta.9 → 3.5.0

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,26 +50,55 @@ 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"
+  },
   openapiUrl: "https://api.example.com/openapi.json",
   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.
@@ -91,12 +120,23 @@ 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.
 
 ```ts
-import { defineBackendSource, httpClient, quableI18nFieldRule } from "@cmflow/atlas";
+import { defineBackendSource, httpClient } from "@cmflow/atlas";
+import { quableI18nFieldRule } from "./atlas-rules";
 
 export const quable = defineBackendSource({
   name: "QUABLE",
@@ -131,7 +171,8 @@ For example, the resolver above may return:
 CMS Directus follows the same document-oriented contract. Its `cmsI18nFieldRule` is owned by the CMS source rather than registered as a global expression rule.
 
 ```ts
-import { defineBackendSource, cmsI18nFieldRule } from "@cmflow/atlas";
+import { defineBackendSource } from "@cmflow/atlas";
+import { cmsI18nFieldRule } from "./atlas-rules";
 
 export const cmsDirectus = defineBackendSource({
   name: "CMS",
@@ -147,7 +188,8 @@ export const cmsDirectus = defineBackendSource({
 CMS Legacy is configured identically, with its own resolver and backend identifier. It may reuse `cmsI18nFieldRule` when the backend uses `CmsI18n` helpers.
 
 ```ts
-import { defineBackendSource, cmsI18nFieldRule } from "@cmflow/atlas";
+import { defineBackendSource } from "@cmflow/atlas";
+import { cmsI18nFieldRule } from "./atlas-rules";
 
 export const cmsLegacy = defineBackendSource({
   name: "CMS_LEGACY",
@@ -165,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")
@@ -172,13 +215,13 @@ export const xm = defineBackendSource({
 });
 ```
 
-`constant` resolves an environment variable directly from `process.env`, falling back to its second argument. No resolver context is required.
+`constant` resolves a value declared in `envs`, falling back to its second argument. No resolver context is required.
 
 ### Environment constants
 
-Use `constant` when a backend source needs a configurable value such as a URL or an access token. The value is resolved when the source runs:
+Use `constant` when a backend source needs a configurable value such as a URL or an access token. Declare injected values at the root of `atlas.config.ts`; the value is resolved when the source runs:
 
-1. Atlas uses `process.env[name]` when it is set.
+1. Atlas uses `envs[name]` when it is set.
 2. Otherwise, it returns the supplied default value.
 
 ```ts
@@ -193,12 +236,19 @@ export const xmBackendSource = defineBackendSource({
 });
 ```
 
-For example, override the default in CI or locally:
+For example, configure the endpoint used by the source:
 
-```bash
-XM_API_URL=https://xm.internal/openapi.json atlas backend-sources --backend XM
+```ts
+export default defineConfig({
+  envs: {
+    XM_API_URL: "https://xm.internal/openapi.json"
+  }
+  // …other Atlas options
+});
 ```
 
+`envs` can itself be populated from `process.env` when appropriate for the project.
+
 This returns entries such as:
 
 ```ts
@@ -227,7 +277,7 @@ export default defineConfig({
 
 ## Custom expression rules
 
-Use `defineExpressionRule` when a project-specific helper hides a backend field or wraps an expression that Atlas should follow. Add a cross-backend rule to `analysis.rules` in `atlas.config.ts`. Attach a backend-specific rule, such as `quableI18nFieldRule` or `cmsI18nFieldRule`, to `defineBackendSource({ rules: [...] })` instead.
+Use `defineExpressionRule` when a project-specific helper hides a backend field or wraps an expression that Atlas should follow. Define those rules in the analyzed project, add a cross-backend rule to `analysis.rules` in `atlas.config.ts`, and attach backend-specific rules to `defineBackendSource({ rules: [...] })` instead.
 
 `match` is a cheap predicate that selects the `ts-morph` expression. `parse` returns the information Atlas should use: a backend field, a transparent wrapper, or both.
 
@@ -281,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.
@@ -305,16 +362,17 @@ 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 --update
 ```
 
-Without `--write`, the command performs a dry run. Use `clean-orphans` to inspect Directus links that no longer reference an API or backend property.
+Without `--update`, the command performs a dry run. Use `clean-orphans` to inspect Directus links that no longer reference an API or backend property.
 
 ## Command reference
 
 ```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
@@ -340,6 +398,8 @@ yarn workspace @cmflow/atlas test
 
 ## License
 
-LicenseThe MIT License (MIT)Copyright (c) 2016 - Today ClubMed
+The MIT License (MIT)
+
+Copyright (c) 2016 - Today ClubMed
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/{types-cYprdLUO.d.mts → UserConfig-BlRknCRh.d.mts}

@@ -1,5 +1,6 @@
+
 import { Expression } from "ts-morph";
-//#region src/utils/defineExpressionRule.d.ts
+//#region src/fn/defineExpressionRule.d.ts
 type FieldExtractionRuleResult = {
   backendField?: string;
   transparent?: boolean;
@@ -15,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;
@@ -29,18 +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 {
-  /**
-   * 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;
+  /** Values injectable into backend source resolvers through `constant`. */
+  envs?: Record<string, unknown>;
+  /** 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`.
@@ -50,6 +69,8 @@ interface UserConfig {
   openapiTimeoutMs: number;
   /** Default Directus base URL used by `push` when no CLI option or environment variable overrides it. */
   directusUrl: string;
+  /** Default Directus token used by `push` when no CLI option or environment variable overrides it. */
+  directusToken: string;
   /**
    * Module aliases resolved while traversing static-analysis dependencies.
    * Defaults are read from `compilerOptions.paths` in the repository tsconfig.
@@ -75,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[];
@@ -115,5 +138,5 @@ interface UserConfig {
   };
 }
 //#endregion
-export { defineExpressionRule as a, FieldExtractionRule as i, BackendSource as n, UserConfig as r, BackendProperty as t };
-//# sourceMappingURL=types-cYprdLUO.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

package/dist/bin/atlas.d.mts

@@ -0,0 +1,2 @@
+
+export {}