@cmflow/atlas 3.4.0-alpha.1

package/README.md

@@ -0,0 +1,132 @@
+<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 `--project-root` only to override the API project directory to analyze.
+
+The configuration imports `defineConfig` from Atlas:
+
+```ts
+import { defineConfig } from "@cmflow/atlas";
+
+export default defineConfig({
+  backendTypesFile: "app/_infra/back/BackendTypes.ts",
+  openapiUrl: "https://api.example.com/openapi.json",
+  openapiTimeoutMs: 60_000,
+  directusUrl: "https://cms.api.clubmed"
+});
+```
+
+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 --project-root /path/to/api generate:graph
+atlas --project-root /path/to/api generate:catalogue --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`.
+
+Check configured coverage baselines:
+
+```bash
+atlas --project-root /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
+```
+
+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 --project-root /path/to/api push .tmp/datasource-catalogue --write
+```
+
+Without `--write`, 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 generate:graph               Trace API routes to backends
+atlas generate:catalogue [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: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.
+
+## 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.