zopia 0.3.0

package/docs/09-configuration.md

@@ -0,0 +1,167 @@
+# ⚙️ Configuration
+
+The complete option reference. Every option is **explicit, typed, and
+validated** — invalid combinations fail fast with `ZOPIA_CONFIG_INVALID`
+(they are never silently coerced).
+
+> 📌 **Rule R-901** — options may come from three sources with one fixed
+> precedence: **explicit CLI flags win over config-file values, and
+> config-file values win over built-in defaults.** A project config file
+> (`zopia.config.ts`, D-19) is discovered next to the working directory; the
+> option names below are exactly its shape.
+
+## 🧾 `zopia.config.ts` — project defaults (v0.2.x, D-19)
+
+```ts
+import { defineConfig } from 'zopia';
+
+export default defineConfig({
+  generate: {
+    mode: 'directory',
+    insertComponents: true,
+    useComponentAsReference: true,
+    custom: true,
+    outDir: 'api_docs',
+  },
+  reverse: { version: '3.1', out: 'openapi.json' },
+});
+```
+
+| # | Rule |
+| --- | --- |
+| R-940 | The CLI discovers `zopia.config.ts`, then `zopia.config.mts`, next to the **working directory** (`process.cwd()`); `--config <path>` selects an explicit file instead (bare paths resolve from the working directory) and a missing explicit file fails with `ZOPIA_CONFIG_INVALID`. Library users call `loadZopiaConfig({ cwd?, file? })` for the same discovery. |
+| R-941 | The config module accepts a `default` export or a named `config` export (default wins). Its shape is exactly `{ generate?: …, reverse?: … }` with the option keys below; unknown keys, non-`Options` nesting, and mistyped values fail with `ZOPIA_CONFIG_INVALID` located at the offending key (`generate.mode`, `reverse.version`, …). |
+| R-942 | Precedence is stable: **CLI flag > config value > built-in default.** `--no-manifest` overrides `generate.manifest: true`; omitted generate flags adopt `generate.*` booleans; `generate.outDir`/`reverse.out`/`reverse.version` apply only when the positional/flag is absent. Without `generate.outDir` the `<output-dir>` positional stays required for `zopia generate`. |
+| R-943 | The config file is **executed JavaScript** under the same trust model as reverse conversion — only trusted projects should carry one; evaluation failures surface as `ZOPIA_CONFIG_INVALID` with the module's error chained. |
+
+## 📄 `ZopiaGenerateOptions` — engine ③ (`openApiToApiDocs`)
+
+```ts
+interface ZopiaGenerateOptions {
+  /** 📂 Where the tree is written. @default 'api_docs' */
+  outDir?: string;
+
+  /** 📂 Layout mode. @default 'directory' */
+  mode?: 'directory' | 'flat';
+
+  /** 🧱 Write components/** with one file per component. @default false (T-8) */
+  insertComponents?: boolean;
+
+  /** 🔗 Endpoints import components instead of inlining.
+   *  Requires insertComponents: true. @default false (T-9) */
+  useComponentAsReference?: boolean;
+
+  /** 📦 Write .zopia-manifest.json (needed by engine ④ — keep it on). @default true */
+  manifest?: boolean;
+
+  /** 🧩 Write merge-safe custom.ts companions per endpoint. @default false (D-24) */
+  custom?: boolean;
+
+  /** 🧰 Split generation into per-bucket sub-trees: `multi-tag` (per primary tag)
+   *  or `multi-server` (per effective first server). @default undefined (S-92) */
+  preset?: 'multi-tag' | 'multi-server';
+}
+
+interface ZopiaGenerateResult {
+  files: GeneratedFile[];
+  warnings: ZopiaWarning[];
+  manifestPath?: string; // absent when manifest: false or a preset split ran
+  trees?: ZopiaPresetTree[]; // {name, directory, manifestPath?} per routed bucket (S-92)
+}
+```
+
+| ⚙️ Option | 📏 Type | 🆔 Default | 📝 Notes |
+| --- | --- | --- | --- |
+| `outDir` | `string` | `'api_docs'` | relative or absolute; created if missing; **never deleted recursively without this exact dir** (safety R-406) |
+| `mode` | `'directory' \| 'flat'` | `'directory'` | the two layouts of [API docs format](07-api-docs.md) |
+| `insertComponents` | `boolean` | `false` | T-8 — emits `components/**` (schemas plus reusable `components/parameters/**` / `components/responses/**` modules, v0.2.x — D-18) |
+| `useComponentAsReference` | `boolean` | `false` | T-9 — imports exact structural component schema references in endpoints and recursively renders nested references through the complete Engine ② schema surface; literal `$ref`-looking data is untouched, aliases/cycles use lazy schemas, and valid `$ref` siblings keep their constraints; **requires** `insertComponents: true` |
+| `manifest` | `boolean` | `true` | disabling it makes engine ④ impossible for that tree — a deliberate escape hatch only; regeneration removes a previous manifest and warns that the tree configuration changed |
+| `custom` | `boolean` | `false` | D-24 — every endpoint/webhook module exports `export * as custom from './custom';` and a sibling `custom.ts` is scaffolded once and never overwritten; CLI flag `--custom`, config key `generate.custom` |
+| `preset` | `'multi-tag' \| 'multi-server'` | `undefined` | S-92 — splits generation into one api-docs sub-tree per routed bucket: `multi-tag` routes each operation by its primary tag (`tags[0]`, warning `ZOPIA_WARN_PRESET_PRIMARY_TAG` when several), `multi-server` by the effective first server (operation → path item → document). Untagged/default-server operations land in `untagged` / `https-default-server`-style buckets; the result gains `trees[]` and every bucket is an independently reverse-convertible tree with its own manifest. Collision-safe lowercase slugs; **nothing to split → the normal single tree** and no `trees[]` |
+
+### ✅ Validation rules
+
+| # | Invalid input | 🛑 Result |
+| --- | --- | --- |
+| R-911 | `useComponentAsReference: true` + `insertComponents: false` (or omitted) | `ZOPIA_CONFIG_INVALID` — hint: *"enable `insertComponents` first"* |
+| R-912 | `mode` outside `'directory' \| 'flat'` | `ZOPIA_CONFIG_INVALID` |
+| R-913 | `outDir` empty string | `ZOPIA_CONFIG_INVALID` |
+| R-914 | unknown option keys or non-boolean boolean flags | `ZOPIA_CONFIG_INVALID` |
+| R-915 | `preset` outside `'multi-tag' \| 'multi-server'` (options or `generate.preset`) | `ZOPIA_CONFIG_INVALID` |
+
+## 📄 `ZopiaReverseOptions` — engine ④ (`apiDocsToOpenApi`)
+
+```ts
+interface ZopiaReverseOptions {
+  /** 🏷️ Spec version to emit. @default '3.1' (D-09, D-20) */
+  version?: '2.0' | '3.0' | '3.1';
+  /** ⚠️ Receive every normalized reverse-conversion warning. */
+  onWarning?: (warning: ZopiaWarning) => void;
+}
+```
+
+| # | Invalid input | 🛑 Result |
+| --- | --- | --- |
+| R-921 | `version` outside `'3.0' \| '3.1'` | `ZOPIA_CONFIG_INVALID` |
+
+## 📄 `ZodToJsonSchemaOptions` — engine ①
+
+See [Conversions → Engine ①](06-conversions.md)
+(`target`, `$schema`, `io`).
+
+## 📄 `JsonSchemaToZodOptions` — engine ②
+
+| ⚙️ Option | 📏 Type | 🆔 Default | 📝 Notes |
+| --- | --- | --- | --- |
+| `rootName` | `string` | `'schema'` | name of the root const (component files always keep their spec name — `<ComponentName>Schema`) |
+
+## 🧮 Defaults at a glance
+
+```ts
+// 🆔 The implicit default configuration of engine ③:
+{
+  outDir: 'api_docs',
+  mode: 'directory',
+  insertComponents: false,          // 🎯 T-8 default
+  useComponentAsReference: false,   // 🎯 T-9 default
+  manifest: true,
+}
+```
+
+> 💡 The defaults produce the **simplest possible tree**: self-contained
+> `index.ts` files, no component files, plus the manifest that keeps the
+> reverse conversion alive. Developers opt *into* complexity only when they
+> want it.
+
+## ⌨️ CLI ↔ options mapping
+
+```text
+zopia generate <spec.json> <output-dir> [--mode <directory|flat>]
+    [--insert-components] [--use-component-as-reference] [--custom] [--no-manifest] [--watch]
+zopia reverse  <docs-dir>  [--out <file.json>] [--version <2.0|3.0|3.1>]
+zopia validate <spec|docs-dir>             (no options yet; `--config path` accepted for parity)
+zopia diff <old-spec> <new-spec>          (no options yet; `--config path` accepted for parity)
+```
+
+| 🚩 Flag | ⚙️ Option |
+| --- | --- |
+| positional `<output-dir>` (generate) | `outDir` |
+| `--mode <directory\|flat>` | `mode` |
+| `--insert-components` | `insertComponents: true` |
+| `--use-component-as-reference` | `useComponentAsReference: true` |
+| `--custom` | `custom: true` |
+| `--preset <multi-tag\|multi-server>` | `preset` |
+| `--no-manifest` | `manifest: false` |
+| `--watch` | no config equivalent — CLI-only; watches the spec file's parent directory (survives atomic editor saves) and regenerates on change |
+| `--out <file.json>` (reverse) | output file path |
+| `--version <3.0\|3.1>` | `version` |
+
+> 📌 **Rule R-931** — positive boolean flags are additive: absence = `false`.
+> `--no-manifest` is the one explicit inverse because manifests default on.
+> Long flags only; no camelCase/kebab ambiguity.
+
+## 🔗 Next
+
+- 🚀 How options are used end-to-end → [Usage](10-usage.md)
+- 📂 What each option changes in the tree → [API docs format](07-api-docs.md) · [Components](08-components.md)

package/docs/10-usage.md

@@ -0,0 +1,208 @@
+# 🚀 Usage
+
+How to use zopia — installation, the programmatic API (the primary interface),
+and the CLI. The API below is the implemented **Phase 1 contract**, pinned by
+tests.
+
+## 📦 Installation
+
+```bash
+bun add zopia        # 📦 the toolkit (no bundled runtime dependencies)
+bun add zod km-api   # ⚛️🧱 peer dependencies for conversion/generated code
+```
+
+| 📦 Package | 🏷️ Kind | 📝 Why |
+| --- | --- | --- |
+| `zopia` | dependency | the engines |
+| `zod` `^4` | peer | engines ①/② convert runtime schemas; generated schemas validate at runtime |
+| `km-api` `^0.4.1` (0.4.x) | peer | generated files call `makeApiConfig()` and engine ④ imports their results |
+
+## ⚡ Quick start — all four engines
+
+```ts
+import {
+  zodToJsonSchema,
+  jsonSchemaToZod,
+  openApiToApiDocs,
+  apiDocsToOpenApi,
+} from 'zopia';
+import { z } from 'zod';
+
+// ── ① Zod → JSON Schema ────────────────────────────────────
+const schema = z.object({ name: z.string().min(1), email: z.email() });
+const jsonSchema = zodToJsonSchema(schema, { target: 'openapi-3.1' });
+// → { type: 'object', properties: { … }, required: ['name', 'email'], … }
+
+// ── ② JSON Schema → Zod ────────────────────────────────────
+const { code, schema: back, warnings, overlays } = jsonSchemaToZod(jsonSchema);
+// → code: executable Zod v4 TypeScript (lossy nodes include @zopia:warn markers)
+// → schema: <runtime Zod schema equivalent to `code`>
+// → warnings: structured diagnostics; overlays: exact reverse-conversion restorations
+
+// ── ③ OpenAPI → api docs ───────────────────────────────────
+// input: object · JSON/YAML text · .json/.yaml/.yml path (v0.2.x, D-16)
+const result = await openApiToApiDocs('swagger.yaml', {
+  mode: 'directory',            // 📂 or 'flat'
+  insertComponents: false,      // 🧱 default
+  useComponentAsReference: false, // 🔗 default
+});
+// → one api_docs/<path>/<method>/index.ts per operation + .zopia-manifest.json
+console.log(result.files, result.warnings);
+
+// ── ④ api docs → OpenAPI ───────────────────────────────────
+const { openapi, warnings: w2 } = await apiDocsToOpenApi('api_docs', {
+  version: '3.1',
+});
+// → a complete OpenAPI document, ready for JSON.stringify
+```
+
+## 📄 End-to-end — what a developer actually gets
+
+```bash
+$ bunx zopia generate openapi.json api_docs --mode directory --insert-components --use-component-as-reference
+```
+
+With the canonical Admin API fixture saved as `openapi.json`, that produces:
+
+```text
+api_docs/
+├── .zopia-manifest.json
+├── components/
+│   ├── index.ts
+│   ├── CreateUser/index.ts
+│   └── User/index.ts
+├── health/get/index.ts
+└── users/{userId}/
+    ├── get/index.ts
+    └── patch/index.ts
+```
+
+…and `api_docs/users/{userId}/get/index.ts` is real, runnable, type-safe code —
+see its exact checked-in output in
+[API docs format → The `index.ts` contract](07-api-docs.md#-the-indexts-contract).
+Drop the tree into your project, import what you need:
+
+```ts
+import getUser from './api_docs/users/{userId}/get/index';
+
+const url = getUser.makeFullPath({ userId: '550e8400-e29b-41d4-a716-446655440000' });
+const user = getUser.makeBody(undefined); // type-safe: no body on GET
+```
+
+## ⚠️ Handling warnings
+
+Warnings are structured, deterministic, and non-fatal. `code` is a stable
+`ZopiaWarningCode`; `at` is an escaped JSON Pointer when a location is known.
+Use codes for automation and treat `message` as human-readable context.
+
+```ts
+import { apiDocsToOpenApi, zodToJsonSchema, type ZopiaWarning } from 'zopia';
+
+const observed: ZopiaWarning[] = [];
+zodToJsonSchema(schema, { onWarning: (warning) => observed.push(warning) });
+
+const result = await apiDocsToOpenApi('api_docs', {
+  version: '3.1',
+  onWarning: (warning) => observed.push(warning),
+});
+
+for (const warning of result.warnings) {
+  console.error(warning.code, warning.at, warning.message);
+}
+```
+
+Exact duplicates are removed and results/callbacks are sorted by location,
+code, then message. Engine ② also writes canonical `// @zopia:warn …` comments
+into emitted code. A manifest preserves restorable schema facts; a warning
+still remains visible because the generated Zod expression itself is an
+approximation.
+
+## ⌨️ CLI
+
+> The CLI delegates generation to the same validated Engine ③ public API; its
+> flags map to [Configuration](09-configuration.md#-cli--options-mapping).
+
+```text
+zopia generate <spec.json|spec.yaml> [output-dir] [--mode directory|flat] [--preset multi-tag|multi-server]
+    [--insert-components] [--use-component-as-reference] [--custom] [--no-manifest]
+    [--watch] [--config path]
+zopia reverse <docs-dir|manifest.json> [--out openapi.json]
+    [--version 2.0|3.0|3.1] [--config path]
+zopia validate <spec.json|spec.yaml|docs-dir> [--config path]
+zopia diff <old.json|old.yaml> <new.json|new.yaml> [--config path]
+zopia navigate <docs-dir> (--to-code <spec-pointer> | --to-spec <tree-file>) [--config path]
+```
+
+| 🚩 Command | 📝 What it does | 💡 Example |
+| --- | --- | --- |
+| `zopia generate` | generates the endpoint tree and manifest; `--watch` keeps it running and regenerates whenever the spec file changes (survives atomic editor saves; Ctrl+C stops) | `zopia generate swagger.json api_docs`, `zopia generate swagger.yaml api_docs --watch` |
+| `zopia reverse` | imports the manifest's endpoint and emitted component modules, then writes the reconstructed OpenAPI document to stdout or `--out` | `zopia reverse api_docs/.zopia-manifest.json --out openapi.json` |
+| `zopia validate` | lints a spec (broken refs, name collisions, cross-namespace duplicate operationIds, unreachable components) or checks a generated tree (manifest validity, reverse dry-run, km-api peer drift); prints sorted diagnostics and a summary line to stdout | `zopia validate openapi.yaml`, `zopia validate api_docs` |
+| `zopia diff` | compares two specs semantically (dialect, info, endpoints with parameter/request-body/response details, webhooks, schema components and named registries (security schemes, reusable parameters/responses, request bodies…), path-item and webhook-item metadata, document fields, `x-` extensions) — key order is ignored and JSON/YAML inputs mix freely; prints `+`/`-`/`~` lines plus a summary to stdout; differences are data, so a changed pair still exits `0` | `zopia diff v1.json v2.yaml` |
+| `zopia navigate` | manifest-driven jump table between a generated tree and its source spec (S-93): `--to-code '#/paths/~1pets/get'` prints the generated file(s) implementing the pointer (endpoints, webhooks, components, plus custom companions when enabled); `--to-spec pets/get/index.ts` prints the owning pointer — both directions print one stable line per location and exit non-zero with `ZOPIA_CONFIG_INVALID` for unmatched pointers/files or `ZOPIA_DOCS_MISSING_MANIFEST` for generation-less roots | `zopia navigate api_docs --to-spec pets/get/index.ts` |
+
+### 📏 CLI contract
+
+| # | Contract |
+| --- | --- |
+| R-931 | Boolean flags are additive and default to `false` when absent; `--custom` enables the merge-safe companion layer ([07 → R-744](07-api-docs.md#-regeneration--manual-edits-phase-1-policy)); `--no-manifest` is the explicit inverse of the default-on manifest option; `--watch` (S-88) is generate-only and requires a spec **file path** — it watches the spec's parent directory so atomic editor saves (`write-temp` + rename) still trigger a regeneration, coalesces change bursts, prints per-run errors to stderr while continuing, and never writes a partial tree beyond the failing run's first output. With a [project config file](09-configuration.md#-zopiaconfigts--project-defaults-v02x-d-19), config values fill every option the flags leave unset, and every explicit flag still wins (D-19); the `<output-dir>` positional is required unless the config supplies `generate.outDir`. |
+| R-932 | Parsing is strict and completes before either engine runs: options may surround positional arguments, but unknown, command-incompatible, repeated, or valueless options and missing/extra positionals fail with `ZOPIA_CONFIG_INVALID` at the offending argument. |
+| R-933 | Data uses stdout (or the selected `--out` file); warnings and errors use stderr. Exit status is `0` success, `1` typed user/configuration failure, and `2` unexpected internal failure. |
+| R-934 | `-h`/`--help` lists the complete grammar and warns that reverse conversion executes generated TypeScript from trusted trees. `--config <path>` selects an explicit config file on every command; loading, discovery, and validation rules live in [09-configuration](09-configuration.md#-zopiaconfigts--project-defaults-v02x-d-19). `zopia validate`, `zopia diff`, and `zopia navigate` have no configurable knobs yet — a named config file only needs to load. |
+
+Both commands print warnings only to stderr as
+`Warning: ZOPIA_WARN_* <pointer>: <message>`. In particular, `zopia reverse`
+keeps stdout as valid OpenAPI JSON even when warnings are present; `--out`
+writes only JSON to the selected file. `zopia validate` instead prints every
+diagnostic to **stdout** (`Error|Warning: <CODE> <pointer>: <message>`) followed
+by one summary line, keeping stderr for the typed failure tail; exit status is
+`1` exactly when an error-severity diagnostic exists (S-89). The same coverage
+is available programmatically as `validateZopia(input)` returning
+`{ ok, kind, target, diagnostics }`.
+
+> ⚠️ `zopia reverse` executes the TypeScript modules referenced by `apis[].file`
+> and non-null `components[].file` entries. Reverse only trusted generated trees,
+> and only commit config files you trust — `zopia.config.ts` is executed
+> JavaScript under the same model. File paths are restricted to the manifest
+> directory (including after symlink resolution), while edited runtime km-api
+> metadata and endpoint/component Zod schemas take precedence over their
+> manifest snapshots.
+
+Exit codes: `0` success · `1` user error (bad input/options — message on
+stderr, hint included) · `2` internal error (should never happen — report it).
+
+## 🧩 Working with the generated tree
+
+| # | Practice | Rule |
+| --- | --- | --- |
+| R-101 | 📂 **Import, don't re-type** — your app imports the generated `index.ts` files; their Zod schemas *are* the validation | — |
+| R-102 | 🔄 **Spec or generation options changed?** re-run `zopia generate` — output is idempotent (P-1); manifest staleness warns on source/config/incomplete-tree drift and safely prunes only obsolete manifest-owned files (`ZOPIA_WARN_STALE_TREE`) | [07 → Regeneration](07-api-docs.md#-regeneration--manual-edits-phase-1-policy) |
+| R-103 | ✍️ **Hand edits** — Phase 1 overwrites them on regeneration (see the file banner); the merge-safe custom layer arrives in Phase 3 | [07 → Regeneration](07-api-docs.md#-regeneration--manual-edits-phase-1-policy) |
+| R-104 | 🧪 **km-api helpers** — `makeFullPath`, `makeParams`, `convertResponseType`, … are available on every generated config for free | [Concepts → km-api](05-concepts.md#-km-api) |
+| R-105 | 🚫 **No zopia import in app code** — generated files depend only on `zod` + `km-api` (R-502) | — |
+
+## 🧯 Error handling
+
+```ts
+import { openApiToApiDocs, isZopiaError } from 'zopia';
+
+try {
+  // Exact component references import through components/index.ts
+  await openApiToApiDocs('swagger.json', { insertComponents: true, useComponentAsReference: true });
+} catch (e) {
+  if (isZopiaError(e)) {
+    console.error(e.code);  // 🆔 'ZOPIA_CONFIG_INVALID'
+    console.error(e.hint);  // 💡 'enable `insertComponents` first'
+    console.error(e.at);    // 📍 JSON Pointer, option, or file, when discoverable
+    console.error(e.cause); // 🔗 original parser/import/filesystem failure, when wrapped
+  }
+}
+```
+
+The full error-code table lives in
+[Architecture → Error model](04-architecture.md#-error-model).
+
+## 🔗 Next
+
+- ⚙️ Every option → [Configuration](09-configuration.md)
+- 🧪 How all of this is tested → [Testing](11-testing.md)