@cmflow/atlas 3.4.0-beta.2 → 3.4.0-beta.20

package/README.md

@@ -50,13 +50,238 @@ The configuration imports `defineConfig` from Atlas:
 import { defineConfig } from "@cmflow/atlas";
 
 export default defineConfig({
-  backendTypesFile: "app/_infra/back/BackendTypes.ts",
+  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: {
+    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.
+
+## 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.
+
+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`.
+
+### 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",
+  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
@@ -70,7 +295,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`.
@@ -102,8 +327,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
@@ -114,7 +340,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/bin/atlas.d.mts

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