@cmflow/agents 3.4.0-alpha.1

package/README.md

@@ -0,0 +1,403 @@
+<div style="text-align: center" align="center">
+ <img src="https://ns.clubmed.com/fbs/RWD/branding2023/Logo/MicrosoftTeams-image%20(9).png" width="200" alt="Club Med"/>
+</div>
+
+<div align="center">
+   <h1>@cmflow/atlas</h1>
+   <hr />
+
+[![npm version](https://badge.fury.io/js/%40cmflow%2Fatlas.svg)](https://badge.fury.io/js/%40cmflow%2Fatlas)
+[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+[![code style: oxfmt](https://img.shields.io/badge/code_style-oxfmt-ef4444.svg?style=flat-square)](https://oxc.rs/docs/guide/usage/formatter)
+
+</div>
+
+Atlas builds an API-to-backend mapping catalogue from an OpenAPI contract and static TypeScript analysis. It generates a reviewable YAML document per route, can optionally infer unresolved mappings, and synchronizes confirmed mappings with Directus.
+
+## What Atlas produces
+
+For each API route, Atlas writes a route-centric YAML document and a companion `.graph.yaml` file. The graph records the resolved path from the API handler to its backends; the YAML records inputs, outputs, mapping evidence and fields that require review.
+
+## Install
+
+```bash
+npm install --save-dev @cmflow/atlas
+```
+
+```bash
+yarn add -D @cmflow/atlas
+```
+
+```bash
+pnpm add -D @cmflow/atlas
+```
+
+## Initialize a target API project
+
+Create `atlas.config.ts` at the root of the API project; it does not belong in the Atlas package.
+
+```bash
+atlas init
+# or create it at an explicit location
+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 `--analysis-dir` only to override the API source directory to analyze.
+
+The configuration imports `defineConfig` from Atlas:
+
+```ts
+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"]
+  }
+});
+```
+
+`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
+DIRECTUS_URL=https://****
+DIRECTUS_TOKEN=replace-with-a-static-token
+```
+
+## Workflow
+
+Generate the topology first, then the route catalogue:
+
+```bash
+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 --analysis-dir /path/to/api generate:test
+```
+
+Review unresolved mappings or run optional AI inference:
+
+```bash
+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.
+
+Push route artifacts to Directus with an explicit write flag:
+
+```bash
+atlas --analysis-dir /path/to/api push .tmp/datasource-catalogue --update
+```
+
+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: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
+atlas push [directory|route]       Preview or push mappings to Directus
+atlas clean-orphans                Inspect or delete orphaned Directus links
+atlas report:changed               Report coverage for changed routes
+```
+
+## CI
+
+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
+
+From the monorepo root:
+
+```bash
+yarn workspace @cmflow/atlas build
+yarn workspace @cmflow/atlas test
+```
+
+## License
+
+LicenseThe 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/bin/cm-agents.d.mts

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