@cmflow/atlas 3.4.0-beta.3 → 3.4.0-beta.30

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,13 +50,275 @@ The configuration imports `defineConfig` from Atlas:
 import { defineConfig } from "@cmflow/atlas";
 
 export default defineConfig({
-  backendTypesFile: "app/_infra/back/BackendTypes.ts",
+  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"
+  directusUrl: "https://cms.api.clubmed",
+  analysis: {
+    rootDir: "./app",
+    backends: ["ICC", "CMS", "CMS_B2C"]
+  }
 });
 ```
 
+`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 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.
+
+```ts
+type BackendProperty =
+  | {
+      document: string;
+      field: string;
+      description?: string;
+    }
+  | {
+      route: string;
+      method: string;
+      field: string;
+      description?: string;
+    };
+```
+
+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 } from "@cmflow/atlas";
+import { quableI18nFieldRule } from "./atlas-rules";
+
+export const quable = defineBackendSource({
+  name: "QUABLE",
+  rules: [quableI18nFieldRule],
+  resolve: async () => {
+    const documentTypes = await httpClient.get<QuableDocumentType[]>("https://quable.example/document-types");
+
+    return documentTypes.flatMap((document) =>
+      document.properties.map((property) => ({
+        document: document.code,
+        field: property.code,
+        description: "récupéré via le backend resolver"
+      }))
+    );
+  }
+});
+```
+
+For example, the resolver above may return:
+
+```ts
+{
+  backend: "QUABLE",
+  document: "products",
+  field: "product_geographical_area",
+  description: "récupéré via le backend resolver"
+}
+```
+
+### CMS Directus
+
+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 } from "@cmflow/atlas";
+import { cmsI18nFieldRule } from "./atlas-rules";
+
+export const cmsDirectus = defineBackendSource({
+  name: "CMS",
+  rules: [cmsI18nFieldRule],
+  resolve: async () => directusResolver.listProperties()
+});
+```
+
+`directusResolver.listProperties()` returns items such as `{ document: "offers", field: "title", description: "…" }`.
+
+### CMS Legacy
+
+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 } from "@cmflow/atlas";
+import { cmsI18nFieldRule } from "./atlas-rules";
+
+export const cmsLegacy = defineBackendSource({
+  name: "CMS_LEGACY",
+  rules: [cmsI18nFieldRule],
+  resolve: async () => cmsLegacyResolver.listProperties()
+});
+```
+
+### Custom REST backend with OpenAPI
+
+`openapiSource` reuses Atlas's OpenAPI parsing utilities: downloading the document, resolving references, traversing operations, and extracting field descriptions. A project therefore only supplies the URL.
+
+```ts
+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")
+    })
+});
+```
+
+`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. Declare injected values at the root of `atlas.config.ts`; the value is resolved when the source runs:
+
+1. Atlas uses `envs[name]` when it is set.
+2. Otherwise, it returns the supplied default value.
+
+```ts
+import { constant, defineBackendSource, openapiSource } from "@cmflow/atlas";
+
+export const xmBackendSource = defineBackendSource({
+  name: "XM",
+  resolve: () =>
+    openapiSource({
+      url: constant<string>("XM_API_URL", "https://xm.example/openapi.json")
+    })
+});
+```
+
+For example, configure the endpoint used by the source:
+
+```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
+{
+  backend: "XM",
+  route: "/path/to",
+  method: "GET",
+  field: "path.to.field",
+  description: "Description extraite du Swagger"
+}
+```
+
+Register strings and sources together:
+
+```ts
+import { defineConfig } from "@cmflow/atlas";
+import { cmsDirectus, cmsLegacy, quable, xm } from "./backend-sources";
+
+export default defineConfig({
+  // …other Atlas options
+  analysis: {
+    backends: ["ICC", quable, cmsDirectus, cmsLegacy, xm]
+  }
+});
+```
+
+## Custom expression rules
+
+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.
+
+```ts
+import { defineConfig, defineExpressionRule } from "@cmflow/atlas";
+import { Node } from "ts-morph";
+
+const localizedFieldRule = defineExpressionRule({
+  name: "localized-field",
+  match: (expression) => Node.isCallExpression(expression) && expression.getExpression().getText() === "localizedField",
+  parse: (expression) => {
+    if (!Node.isCallExpression(expression)) return undefined;
+
+    const [source, field] = expression.getArguments();
+    if (!source || !Node.isExpression(source) || !Node.isStringLiteral(field)) return undefined;
+
+    return { backendField: `${source.getText()}.${field.getLiteralValue()}` };
+  }
+});
+
+export default defineConfig({
+  // …other Atlas options
+  analysis: {
+    // …other analysis options
+    rules: [localizedFieldRule]
+  }
+});
+```
+
+For a wrapper that does not change the field path, return `transparent: true`:
+
+```ts
+const unwrapRule = defineExpressionRule({
+  name: "unwrap-api-value",
+  match: (expression) => Node.isCallExpression(expression) && expression.getExpression().getText() === "unwrap",
+  parse: () => ({ transparent: true })
+});
+```
+
+`parse` may also set `mapperType` to annotate the generated mapping, or `apiMapping: true` when the helper maps an API value rather than a backend value.
+
 Create a `.env.local` in the target API project when pushing to Directus:
 
 ```dotenv
@@ -69,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:catalogue --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.
@@ -93,17 +362,19 @@ 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-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:catalogue [route]   Generate route review documents
+atlas generate:catalog [route]     Generate route review documents
 atlas generate:test                Check configured coverage baselines
 atlas needs-review                 Rank unresolved routes
 atlas infer [route|directory]      Optionally enrich unresolved mappings
@@ -114,7 +385,7 @@ atlas report:changed               Report coverage for changed routes
 
 ## CI
 
-The recommended static CI flow is `generate:graph`, `generate:catalogue`, then `push`. Do not run optional inference in CI. Supply `DIRECTUS_URL` and `DIRECTUS_TOKEN` through the CI secret context; skip the push if either value is absent.
+The recommended static CI flow is `generate:graph`, `generate:catalog`, then `push`. Do not run optional inference in CI. Supply `DIRECTUS_URL` and `DIRECTUS_TOKEN` through the CI secret context; skip the push if either value is absent.
 
 ## Development
 

package/dist/UserConfig-BlRknCRh.d.mts

@@ -0,0 +1,142 @@
+
+import { Expression } from "ts-morph";
+//#region src/fn/defineExpressionRule.d.ts
+type FieldExtractionRuleResult = {
+  backendField?: string;
+  transparent?: boolean;
+  mapperType?: string;
+  apiMapping?: boolean;
+};
+type FieldExtractionRule = {
+  name: string;
+  /** Higher-priority rules are evaluated first. Defaults to 0. */
+  priority?: number;
+  match: (expression: Expression, config: UserConfig) => boolean;
+  parse: (expression: Expression, config: UserConfig) => FieldExtractionRuleResult | undefined;
+};
+declare function defineExpressionRule(rule: FieldExtractionRule): FieldExtractionRule;
+//#endregion
+//#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;
+}
+//#endregion
+//#region src/interfaces/BackendProperty.d.ts
+type BackendProperty = PropertyMetadata & ({
+  document: string;
+  field: string;
+  description?: string;
+} | {
+  route: string;
+  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>;
+  /** 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`.
+   */
+  openapiUrl: string;
+  /** Maximum duration allowed to connect to and download the OpenAPI document. */
+  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.
+   */
+  resolver?: {
+    /** Explicit aliases override aliases read from tsconfig. */
+    alias?: Record<string, string>;
+  };
+  /** Defaults used by the optional AI pass that reviews unresolved static mappings. */
+  inference: {
+    /** ai/sdk model used for structured mapping suggestions. */
+    model: string;
+    /** ai/sdk HTTP API base URL. */
+    baseUrl: string;
+    /** Minimum model confidence required to replace a `needs_review` mapping. */
+    minimumConfidence: number;
+    /** Maximum duration of one route-level AI request before aborting it. */
+    timeoutMs: number;
+    /** Maximum number of route-level AI requests run concurrently. */
+    workers: number;
+  };
+  /**
+   * 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, 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[];
+    /**
+     * Input root fields considered transverse to the API, such as access headers or generic list filters.
+     * These fields are kept in the extracted contract but are not flagged as `needs_review`
+     * when they do not map to a backend property. A detected backend mapping always takes precedence.
+     */
+    transversalInputs: string[];
+    /** Output field paths omitted from catalogues and coverage checks, including nested fields. */
+    ignoredOutputs: string[];
+    /** Technical property-access prefixes that must not be treated as backend fields. */
+    backendFieldAccess: {
+      excludedPrefixes: string[];
+    };
+    /** Mapper naming conventions used to infer mapping direction and domain roots. */
+    mapperNaming: {
+      inputPatterns: RegExp[];
+      outputPatterns: RegExp[];
+      domainToBackendPattern: RegExp;
+      domainNameFromToDomainPattern: RegExp;
+      constructedTypeToDomainPattern: (constructorName: string) => RegExp;
+    };
+    /** Expressions that are transparent while tracing a field through a mapping. */
+    neutralExpressionMatchers: NeutralExpressionMatcher[];
+    rules: FieldExtractionRule[];
+  };
+  /** Route-level minimum resolved-field coverage accepted by the static-analysis regression check. */
+  test: {
+    coverage: Array<{
+      route: string;
+      minimum_coverage: number | string;
+    }>;
+  };
+}
+//#endregion
+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 {}