@cmflow/atlas 3.4.0-beta.6 → 3.4.0-beta.8

package/README.md

@@ -59,11 +59,143 @@ export default defineConfig({
 });
 ```
 
-Atlas reads `compilerOptions.paths` from the project's `tsconfig.json` and uses them as module aliases. 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. `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.
+
+## 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.
+
+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.
+
+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`.
+
+### 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";
+
+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, cmsI18nFieldRule } from "@cmflow/atlas";
+
+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, cmsI18nFieldRule } from "@cmflow/atlas";
+
+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 { defineBackendSource, openapiSource } from "@cmflow/atlas";
+
+export const xm = defineBackendSource({
+  name: "XM",
+  resolve: () => openapiSource({ url: "https://xm.example/openapi.json" })
+});
+```
+
+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. Add the rule to `analysis.rules` in `atlas.config.ts`.
+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.
 
 `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.
 
@@ -73,8 +205,7 @@ import { Node } from "ts-morph";
 
 const localizedFieldRule = defineExpressionRule({
   name: "localized-field",
-  match: (expression) =>
-    Node.isCallExpression(expression) && expression.getExpression().getText() === "localizedField",
+  match: (expression) => Node.isCallExpression(expression) && expression.getExpression().getText() === "localizedField",
   parse: (expression) => {
     if (!Node.isCallExpression(expression)) return undefined;
 
@@ -119,7 +250,7 @@ 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 --project-root /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`.
@@ -151,8 +282,9 @@ 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 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
@@ -163,7 +295,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