zopia 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,7 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-29
+
+### 🔄 Changed
+- 📦 **Slimmer npm package — practical docs only.** The published archive now
+  ships just the user-facing guides (`docs/07-api-docs.md`,
+  `docs/09-configuration.md`, `docs/10-usage.md`) next to `README.md` /
+  `CHANGELOG.md`; the development documentation (overview, targets, roadmap,
+  architecture, concepts, conversions, components, testing, standards, the
+  docs map, and the publish-workflow example) stays in the GitHub repository
+  and is linked from the README — npm users installing the package get
+  usage/installation docs, not project management artifacts. The tarball
+  shrinks **239 KB → 182 KB packed (915 KB → 750 KB unpacked, 50 → 39
+  files)**; `npm` force-includes `README*` from any directory, so the docs map
+  is explicitly negated (`!docs/README.md`) in `files`. `package:check` and
+  the release contract now enforce the slim archive: a missing practical doc
+  fails, and any development doc leaking into the pack fails. The release
+  standard (R-192) and the docs map describe the split.
+
 ### ✨ Added
+- 🌳 **Runtime tree consumption — `zopia/runtime` (S-94).** New opt-in subpath
+  export (`import { createApiDocs, flattenApiDocs } from 'zopia/runtime'`) that
+  turns a generated api-docs directory into the objects an application
+  consumes, with **zero changes to generation output**. `createApiDocs(dir)` —
+  the entire consumer DX — discovers the root `.zopia-manifest.json` plus every
+  one-level-deep preset bucket manifest (`multi-tag`/`multi-server`), merges
+  them (deduplicating by `${path}#${method}`, root manifest first), sorts
+  deterministically (path segments, then the canonical method order), and
+  returns one nested object keyed by the exact URL path segments with the
+  lowercase method as leaf key holding the endpoint module's `export default`
+  (loaded via `pathToFileURL`, Windows-safe). `flattenApiDocs(tree)` is the
+  flat freebie: a `Record<string, config>` keyed by `operationId`, deriving
+  missing names and collision suffixes through the **same shared rules the
+  generator uses for its export identifiers** (extracted to
+  `src/conversions/api-docs-names.ts`: camelize, reserved-word guard,
+  leading-numeric guard, `2`/`3`… suffixing — `await` → `awaitEndpoint`).
+  Missing/garbled manifests, unsafe manifest paths, import failures, and
+  modules without default exports fail typed (`ZOPIA_DOCS_MISSING_MANIFEST`,
+  `ZOPIA_MANIFEST_INVALID`, `ZOPIA_DOCS_IMPORT_FAILED`); paths that cannot
+  share one nested tree (below a method leaf, trailing-slash twins) fail typed
+  `ZOPIA_SPEC_INVALID`. Documented in
+  [docs/07-api-docs.md → Runtime tree consumption](docs/07-api-docs.md).
 - 📦 **npm publish pipeline** — `.github/workflows/publish.yml` publishes on GitHub Release creation (or manually) with the pinned Bun toolchain, verifies the release tag matches `package.json`'s version, and runs `npm publish --provenance --access public`. Its only credential is the repository-secret `NODE_AUTH_TOKEN` (npm `NPM_TOKEN`) — never handled in chat or commits; npm trusted-publishing (OIDC) is supported by the declared `id-token` permission.
 
 ### 🐛 Fixed

package/README.md

@@ -13,7 +13,7 @@
 [![Runtime](https://img.shields.io/badge/Runtime-Bun%201.x-black.svg)](https://bun.sh/)
 [![Tests](https://img.shields.io/badge/Tests-vitest-10b981.svg)](https://vitest.dev/)
 
-✅ **Status — Phase 3 complete · v0.3.0 released**
+✅ **Status — Phase 3 complete · v0.4.0 released**
 
 </div>
 
@@ -91,25 +91,57 @@ await openApiToApiDocs('swagger.json', {
 const { openapi } = await apiDocsToOpenApi('api_docs', { version: '3.1' });
 ```
 
+### 🌳 Consuming the tree at runtime
+
+When wiring endpoints dynamically beats importing generated files one by one,
+import the opt-in runtime subpath and point it at any directory zopia ever
+generated into (`directory`, `flat`, and `multi-tag` / `multi-server` splits
+all resolve through their manifests):
+
+```ts
+import { createApiDocs, flattenApiDocs } from 'zopia/runtime';
+
+// Nested: URL path segments → lowercase method → the makeApiConfig object
+const apiDocs = await createApiDocs('api_docs');
+const getUser = apiDocs.users['{userId}'].get;   // default export of that index.ts
+
+// Flat freebie: keyed by operationId, same leaf objects, deterministic order
+const endpoints = flattenApiDocs(apiDocs);
+endpoints.getUser === getUser;                    // → true
+```
+
+Generation output is untouched — the resolver only reads manifests and imports
+modules. See [docs/07-api-docs.md → Runtime tree consumption](docs/07-api-docs.md#-runtime-tree-consumption--createapidocs).
+
 ## 📚 Documentation
 
-Everything about the project — targets, architecture, conversion rules,
-output format, configuration, testing, standards — lives in [`docs/`](docs/).
+The **practical guides ship inside the npm package** — usage, configuration,
+and the generated output format. The development documentation (project
+targets, roadmap, architecture, testing strategy, engineering standards)
+stays in the
+[GitHub repository](https://github.com/komeilm76/zopia/tree/main/docs).
+
+**📦 Packed with the npm package** (relative links, in `docs/`):
 
 | 📄 Document | Contents |
 | --- | --- |
-| 🧭 [Overview](docs/01-overview.md) | What zopia is, the problem it solves, principles, non-goals |
-| 🎯 [Targets](docs/02-targets.md) | The explicit, testable targets of this project |
-| 🗺️ [Roadmap](docs/03-roadmap.md) | Phases, milestones, definition of done |
-| 🏗️ [Architecture](docs/04-architecture.md) | Modules, pipeline, internal model, error model, safety |
-| 🧩 [Concepts](docs/05-concepts.md) | Glossary — Swagger 2.0, OpenAPI 3.x, JSON Schema, `$ref`, Zod v4, km-api |
-| 🔄 [Conversions](docs/06-conversions.md) | The four engines: algorithms, mapping tables, edge cases |
-| 📄 [API docs format](docs/07-api-docs.md) | `directory` & `flat` layouts, `index.ts` contract, manifest |
-| 🧱 [Components](docs/08-components.md) | `insertComponents` / `useComponentAsReference`, `$ref` graphs |
-| ⚙️ [Configuration](docs/09-configuration.md) | Full option reference, defaults, validation rules |
 | 🚀 [Usage](docs/10-usage.md) | Installation, programmatic API, CLI, end-to-end example |
-| 🧪 [Testing](docs/11-testing.md) | Vitest strategy, scenario matrix, fixtures, coverage gates |
-| 📏 [Standards](docs/12-standards.md) | Code, JSDoc, commits, changelog, releases, key decisions |
+| ⚙️ [Configuration](docs/09-configuration.md) | Full option reference, defaults, validation rules |
+| 📄 [API docs format](docs/07-api-docs.md) | `directory` & `flat` layouts, `index.ts` contract, manifest, runtime consumption |
+
+**🐙 GitHub-only** (development docs, not packed):
+
+| 📄 Document | Contents |
+| --- | --- |
+| 🧭 [Overview](https://github.com/komeilm76/zopia/blob/main/docs/01-overview.md) | What zopia is, the problem it solves, principles, non-goals |
+| 🎯 [Targets](https://github.com/komeilm76/zopia/blob/main/docs/02-targets.md) | The explicit, testable targets of this project |
+| 🗺️ [Roadmap](https://github.com/komeilm76/zopia/blob/main/docs/03-roadmap.md) | Phases, milestones, definition of done |
+| 🏗️ [Architecture](https://github.com/komeilm76/zopia/blob/main/docs/04-architecture.md) | Modules, pipeline, internal model, error model, safety |
+| 🧩 [Concepts](https://github.com/komeilm76/zopia/blob/main/docs/05-concepts.md) | Glossary — Swagger 2.0, OpenAPI 3.x, JSON Schema, `$ref`, Zod v4, km-api |
+| 🔄 [Conversions](https://github.com/komeilm76/zopia/blob/main/docs/06-conversions.md) | The four engines: algorithms, mapping tables, edge cases |
+| 🧱 [Components](https://github.com/komeilm76/zopia/blob/main/docs/08-components.md) | `insertComponents` / `useComponentAsReference`, `$ref` graphs |
+| 🧪 [Testing](https://github.com/komeilm76/zopia/blob/main/docs/11-testing.md) | Vitest strategy, scenario matrix, fixtures, coverage gates |
+| 📏 [Standards](https://github.com/komeilm76/zopia/blob/main/docs/12-standards.md) | Code, JSDoc, commits, changelog, releases, key decisions |
 
 ## 🏗️ Project structure
 
@@ -139,7 +171,7 @@ zopia/
 
 ## 🧪 Development
 
-zopia is a **Bun-first** project (see [docs/12-standards.md](docs/12-standards.md)):
+zopia is a **Bun-first** project (see [docs/12-standards.md](https://github.com/komeilm76/zopia/blob/main/docs/12-standards.md)):
 
 ```bash
 bun install --frozen-lockfile # 📦 reproducible install from bun.lock
@@ -157,7 +189,7 @@ bun run release:check         # 🚢 complete pinned-Bun prepublish gate
 
 ## 🤝 Contributing
 
-Read [docs/12-standards.md](docs/12-standards.md) first — it defines code style,
+Read [docs/12-standards.md](https://github.com/komeilm76/zopia/blob/main/docs/12-standards.md) first — it defines code style,
 JSDoc rules, the commit convention, and the changelog rule. Every feature ships
 **with** its documentation in the same commit.
 

package/docs/07-api-docs.md

@@ -106,6 +106,81 @@ templates, duplicate parameters, unsupported methods, and unsafe roots. Engine
 does not emit a facade module in v0.1.0: direct imports are the generated
 file-level API, and the manifest remains authoritative (D-06).
 
+## 🌳 Runtime tree consumption — `createApiDocs`
+
+> 🎯 **S-94** — *an opt-in runtime API, shipped in the `zopia` package itself,
+> converts a generated tree directory into the nested / flat objects an
+> application consumes. No generation output changes: the feature only reads
+> and imports.*
+
+```ts
+import { createApiDocs, flattenApiDocs } from 'zopia/runtime';
+
+const apiDocs = await createApiDocs('api_docs');   // ← the entire consumer DX
+const endpoint = apiDocs.applicant['{applicantId}'].exame['{examId}'].get;
+// → the endpoint module's makeApiConfig object (its default export)
+
+const endpoints = flattenApiDocs(apiDocs);        // the flat freebie
+endpoints.getExam;                                 // same leaf object
+```
+
+**Manifest discovery & merge (B-conditions).** The resolver reads the root
+`.zopia-manifest.json` **plus** every one-level-deep preset bucket manifest
+(`multi-tag` / `multi-server` splits write one manifest per bucket directory),
+merging all of them and deduplicating by `${path}#${method}` — the root
+manifest wins duplicates, buckets follow in sorted directory order. Any
+directory that was ever a zopia output root is accepted, including a single
+preset bucket root. Entries are then sorted deterministically: URL path
+segments first, then the canonical method order
+(`get, post, put, delete, head, options, patch, trace`).
+
+**Nesting.** Branch keys are the URL path segments **exactly and in order**
+(including literal `{param}` segments), the leaf key is the lowercase method,
+and the leaf value is the endpoint module's **default export**, loaded with
+dynamic `import()` through `pathToFileURL` (Windows-safe). Because which keys
+exist depends on the source spec, the `ApiDocsTree` type types every node
+permissively (branch ∪ config). A tree `/` path nests its methods at the root
+(`apiDocs.get`). Paths that cannot coexist in one nested tree — a path
+continuing below another path's method leaf, or two paths differing only by a
+trailing slash — fail with a typed `ZOPIA_SPEC_INVALID` instead of silently
+dropping an endpoint. Key insertion follows the deterministic sort, so the
+same tree always enumerates keys in the same order (P-1).
+
+**Errors** reuse the manifest conventions: a missing manifest →
+`ZOPIA_DOCS_MISSING_MANIFEST`; garbled JSON or unusable `apis[]` records →
+`ZOPIA_MANIFEST_INVALID`; a module that cannot be imported or has no default
+export → `ZOPIA_DOCS_IMPORT_FAILED` naming the file. Reading is pure — nothing
+on disk is written.
+
+**The flatten freebie.** `flattenApiDocs(apiDocs)` deep-walks the tree in its
+deterministic leaf order and returns a flat `Record<string, config>` keyed by
+each config's `operationId`. When a leaf has no usable `operationId`, or two
+keys collide, the name is derived by the **same rules the generator uses for
+its `export const` identifiers** (R-732: camelize, reserved-word guard,
+leading-numeric guard, `2`/`3`… uniqueness suffix — `await` → `awaitEndpoint`,
+`get-a` + `getA` → `getA` + `getA2`), so the flat keys always match the
+modules' named exports. The shared rules live in
+`src/conversions/api-docs-names.ts` and both call-sites (generation and
+runtime) use them.
+
+**A small km-api hand-off** — every leaf *is* a `makeApiConfig()` object, so
+the km-api surface is available directly:
+
+```ts
+import { createApiDocs } from 'zopia/runtime';
+
+const apiDocs = await createApiDocs('api_docs');
+const getUser = apiDocs.users['{userId}'].get;
+
+getUser.method;                          // "GET"
+getUser.pathShape;                       // "/users/{userId}"
+getUser.request.params.parse({ userId: '22ccbc6a-…' }); // ✅ Zod-validated path params
+getUser.response[200].parse({ id: 'u1', email: 'a@b.c' }); // ✅ Zod-validated response
+```
+
+> 💡 Generated webhook modules are not URL-path endpoints and stay outside the
+> nested tree — import them directly or reverse-convert the tree (engine ④).
+
 ## 🧬 Operation contract extraction
 
 Before rendering an endpoint, zopia normalizes each operation into an
@@ -177,7 +252,7 @@ With the default options (`insertComponents: false`), every `index.ts` imports
 **only** `zod` and `km-api` (R-502): each component use is inlined into its
 request/parameter/response expression (R-403). Cross-file imports appear
 **only** when `useComponentAsReference` is `true` — see
-[Components](08-components.md).
+[Components](https://github.com/komeilm76/zopia/blob/main/docs/08-components.md).
 
 ## 📦 The manifest — `.zopia-manifest.json`
 
@@ -333,5 +408,5 @@ Security requirements remain manifest-owned because km-api stores only `auth: 'Y
 
 ## 🔗 Next
 
-- 🧱 What changes when components are emitted → [Components](08-components.md)
+- 🧱 What changes when components are emitted → [Components](https://github.com/komeilm76/zopia/blob/main/docs/08-components.md)
 - ⚙️ Every option that shapes this output → [Configuration](09-configuration.md)

package/docs/09-configuration.md

@@ -107,7 +107,7 @@ interface ZopiaReverseOptions {
 
 ## 📄 `ZodToJsonSchemaOptions` — engine ①
 
-See [Conversions → Engine ①](06-conversions.md)
+See [Conversions → Engine ①](https://github.com/komeilm76/zopia/blob/main/docs/06-conversions.md)
 (`target`, `$schema`, `io`).
 
 ## 📄 `JsonSchemaToZodOptions` — engine ②
@@ -164,4 +164,4 @@ zopia diff <old-spec> <new-spec>          (no options yet; `--config path` accep
 ## 🔗 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)
+- 📂 What each option changes in the tree → [API docs format](07-api-docs.md) · [Components](https://github.com/komeilm76/zopia/blob/main/docs/08-components.md)

package/docs/10-usage.md

@@ -178,8 +178,31 @@ stderr, hint included) · `2` internal error (should never happen — report it)
 | 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-104 | 🧪 **km-api helpers** — `makeFullPath`, `makeParams`, `convertResponseType`, … are available on every generated config for free | [Concepts → km-api](https://github.com/komeilm76/zopia/blob/main/docs/05-concepts.md#-km-api) |
 | R-105 | 🚫 **No zopia import in app code** — generated files depend only on `zod` + `km-api` (R-502) | — |
+| R-106 | 🌳 **Runtime tree loading** — when wiring endpoints dynamically beats importing files one by one, `createApiDocs()` from the opt-in `zopia/runtime` subpath turns the whole directory into one nested object (plus the `flattenApiDocs` flat record); generation output is untouched | [07 → Runtime tree consumption](07-api-docs.md#-runtime-tree-consumption--createapidocs) |
+
+### 🌳 Consuming the tree at runtime
+
+Import the dedicated subpath (the package root stays free of
+filesystem-importing APIs) and point it at any directory zopia ever generated
+into — `directory`, `flat`, and split `multi-tag` / `multi-server` trees all
+resolve through their manifests:
+
+```ts
+import { createApiDocs, flattenApiDocs } from 'zopia/runtime';
+
+// Nested: exact URL path segments, lowercase method leaf, default-export config
+const apiDocs = await createApiDocs('api_docs');
+const getUser = apiDocs.users['{userId}'].get;   // the makeApiConfig object
+
+// Flat: keyed by operationId (derived with the generator's own naming rules)
+const endpoints = flattenApiDocs(apiDocs);
+endpoints.getUser === getUser;                    // → true
+```
+
+Failures are typed `ZopiaError`s with `at`/`hint` — see
+[API docs → Runtime tree consumption](07-api-docs.md#-runtime-tree-consumption--createapidocs).
 
 ## 🧯 Error handling
 
@@ -200,9 +223,9 @@ try {
 ```
 
 The full error-code table lives in
-[Architecture → Error model](04-architecture.md#-error-model).
+[Architecture → Error model](https://github.com/komeilm76/zopia/blob/main/docs/04-architecture.md#-error-model).
 
 ## 🔗 Next
 
 - ⚙️ Every option → [Configuration](09-configuration.md)
-- 🧪 How all of this is tested → [Testing](11-testing.md)
+- 🧪 How all of this is tested → [Testing](https://github.com/komeilm76/zopia/blob/main/docs/11-testing.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zopia",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Type-safe OpenAPI, JSON Schema, and Zod conversion toolkit.",
   "keywords": [
     "api-docs",
@@ -27,7 +27,10 @@
   "files": [
     "bin",
     "src",
-    "docs",
+    "docs/07-api-docs.md",
+    "docs/09-configuration.md",
+    "docs/10-usage.md",
+    "!docs/README.md",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
@@ -72,6 +75,11 @@
       "types": "./src/index.ts",
       "import": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./runtime": {
+      "types": "./src/runtime.ts",
+      "import": "./src/runtime.ts",
+      "default": "./src/runtime.ts"
     }
   }
 }

package/src/conversions/api-docs-generate.ts

@@ -1,6 +1,7 @@
 import { lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { asZopiaError, ZopiaError } from '../errors';
+import { endpointExportName } from './api-docs-names';
 import { buildOpenApiOperationIR } from './openapi-ir';
 import { deriveReusableParameterSchema, deriveReusableResponseSchema, extractOperationContracts, reusableDeclarations } from './openapi-contracts';
 import { jsonSchemaToZod } from './json-schema-to-zod';
@@ -61,7 +62,7 @@ function collectComponentRefs(value: unknown, names = new Set<string>(), mapEntr
   return names;
 }
 function schemaCode(schema: unknown, name: string): string {
-  const safeName = exportName(name);
+  const safeName = endpointExportName(name);
   const converted = jsonSchemaToZod(schema === undefined ? true : schema as any, { rootName: safeName });
   const source = converted.code.trimEnd();
   const direct = source.match(new RegExp(`^const ${safeName.replace(/[$]/g, '\\$&')} = ([\\s\\S]*);$`));
@@ -222,23 +223,16 @@ function resolveObject(value: unknown, source: OpenApiDocument): any {
   }
   return current;
 }
-function exportName(operationId: string): string {
-  const parts = operationId.split(/[^A-Za-z0-9_$]+/).filter(Boolean);
-  let name = parts.map((part, index) => index === 0 ? part : part[0].toUpperCase() + part.slice(1)).join('') || 'endpoint';
-  if (!/^[A-Za-z_$]/.test(name)) name = `endpoint${name}`;
-  if (['arguments', 'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'eval', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'implements', 'import', 'in', 'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private', 'protected', 'public', 'return', 'static', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield'].includes(name)) name = `${name}Endpoint`;
-  return name;
-}
 function componentExportName(componentName: string): string {
-  const name = exportName(componentName);
+  const name = endpointExportName(componentName);
   return name.endsWith('Schema') ? name : `${name}Schema`;
 }
 function componentParameterExportName(componentName: string): string {
-  const name = exportName(componentName);
+  const name = endpointExportName(componentName);
   return name.endsWith('Parameter') ? name : `${name}Parameter`;
 }
 function componentResponseExportName(componentName: string): string {
-  const name = exportName(componentName);
+  const name = endpointExportName(componentName);
   return name.endsWith('Response') ? name : `${name}Response`;
 }
 function componentReaches(source: OpenApiDocument, from: string, target: string, seen = new Set<string>()): boolean {
@@ -352,7 +346,7 @@ function renderEndpoint(operation: any, source: OpenApiDocument, mode: ApiDocsMo
   const examplesValue = { ...(Object.keys(requestExamples).length ? { request: requestExamples } : {}), ...(Object.keys(responseExamples).length ? { response: responseExamples } : {}) };
   const examples = Object.keys(examplesValue).length ? `examples: JSON.parse(${JSON.stringify(stableDataJson(examplesValue))}),` : '';
   const opId = operation.operationId;
-  const exportId = exportName(opId);
+  const exportId = endpointExportName(opId);
   const tags = ir.tags;
   const auth = ir.security !== undefined && ir.security.length > 0 && ir.security.every((requirement) => Object.keys(requirement as Record<string, unknown>).length > 0) ? 'YES' : 'NO';
   const sourceName = JSON.stringify(`${source.info.title} v${source.info.version}`).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');

package/src/conversions/api-docs-names.ts

@@ -0,0 +1,54 @@
+/**
+ * 📛 Shared endpoint identifier rules (R-732).
+ *
+ * The single source of truth for deriving safe export identifiers from
+ * operation IDs — and for the numeric uniqueness suffix applied when two
+ * derived identifiers collide. Generation (Engine ③'s `export const` names
+ * and the collectors' deterministic operation IDs) and the runtime tree
+ * resolver (`flattenApiDocs` record keys) call these helpers so both surfaces
+ * keep producing identical names by construction.
+ */
+
+/** ECMAScript keywords and literals never emitted as generated identifiers. */
+const RESERVED_IDENTIFIER_NAMES: ReadonlySet<string> = new Set([
+  'arguments', 'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'eval', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'implements', 'import', 'in', 'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private', 'protected', 'public', 'return', 'static', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield',
+]);
+
+/**
+ * Derive the endpoint export identifier from one operation ID.
+ *
+ * Applies the fixed naming contract of R-732: split on non-identifier
+ * characters, camel-case the parts (camelize), fall back to `endpoint` when
+ * nothing remains, prefix `endpoint` when the result starts with a digit or
+ * other non-identifier character, and append `Endpoint` when the result is a
+ * reserved ECMAScript keyword or literal (e.g. `await` → `awaitEndpoint`).
+ *
+ * @param operationId Explicit or deterministically derived operation identifier.
+ * @returns Safe camel-case TypeScript identifier for the module export.
+ */
+export function endpointExportName(operationId: string): string {
+  const parts = operationId.split(/[^A-Za-z0-9_$]+/).filter(Boolean);
+  let name = parts.map((part, index) => index === 0 ? part : part[0].toUpperCase() + part.slice(1)).join('') || 'endpoint';
+  if (!/^[A-Za-z_$]/.test(name)) name = `endpoint${name}`;
+  if (RESERVED_IDENTIFIER_NAMES.has(name)) name = `${name}Endpoint`;
+  return name;
+}
+
+/**
+ * Return the first free variant of a derived identifier, suffixing `2`, `3`, …
+ *
+ * This is the exact uniqueness rule the operation collectors apply when a
+ * derived operation ID collides (`getA` → `getA2` → `getA3`): the first
+ * candidate is the base itself, and every subsequent candidate appends the
+ * next integer directly to the base.
+ *
+ * @param base Identifier before any uniqueness suffix.
+ * @param used Already-claimed identifiers this derivation must not clobber.
+ * @returns `base` itself when free, otherwise the first suffixed variant.
+ */
+export function uniqueEndpointName(base: string, used: ReadonlySet<string>): string {
+  let name = base;
+  let suffix = 1;
+  while (used.has(name)) name = `${base}${++suffix}`;
+  return name;
+}

package/src/conversions/manifest-writer.ts

@@ -16,7 +16,7 @@ export const ZOPIA_MANIFEST_SCHEMA = 'zopia:manifest@1' as const;
 export const ZOPIA_MANIFEST_FILE = '.zopia-manifest.json' as const;
 
 /** Package version recorded by the current manifest writer. */
-export const ZOPIA_VERSION = '0.3.0' as const;
+export const ZOPIA_VERSION = '0.4.0' as const;
 
 /** Supported source dialect labels stored in a manifest. */
 export type ZopiaManifestSourceKind = 'swagger-2.0' | 'openapi-3.0' | 'openapi-3.1';

package/src/conversions/openapi-to-api-docs.ts

@@ -1,5 +1,6 @@
 import { ZopiaError } from '../errors';
 import { normalizeOpenApiDocument, type OpenApiDocument } from './openapi';
+import { uniqueEndpointName } from './api-docs-names';
 import { resolveOpenApiLocalRef } from './openapi-ref';
 
 /** Canonical km-api/OpenAPI operation method order. */
@@ -107,15 +108,12 @@ export function collectOpenApiOperations(input: OpenApiDocument | string): OpenA
         const previous = owners.get(operationId);
         if (previous) {
           if (previous.operation.operationId !== undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Duplicate operationId: ${operationId}`);
-          let replacement = previous.operationId; let suffix = 1;
-          while (ids.has(replacement)) replacement = `${operationId}${++suffix}`;
+          const replacement = uniqueEndpointName(operationId, ids);
           ids.delete(previous.operationId); owners.delete(previous.operationId);
           previous.operationId = replacement; ids.add(replacement); owners.set(replacement, previous);
         }
       } else {
-        const base = deriveOperationId(path, method);
-        operationId = base; let suffix = 1;
-        while (ids.has(operationId)) operationId = `${base}${++suffix}`;
+        operationId = uniqueEndpointName(deriveOperationId(path, method), ids);
       }
       const collected = { path, method, operation, operationId, parameters: mergedParameters };
       ids.add(operationId); owners.set(operationId, collected); operations.push(collected);
@@ -185,15 +183,12 @@ export function collectOpenApiWebhookOperations(document: OpenApiDocument): Open
         const previous = owners.get(operationId);
         if (previous) {
           if (previous.operation.operationId !== undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Duplicate operationId: ${operationId}`);
-          let replacement = previous.operationId; let suffix = 1;
-          while (ids.has(replacement)) replacement = `${operationId}${++suffix}`;
+          const replacement = uniqueEndpointName(operationId, ids);
           ids.delete(previous.operationId); owners.delete(previous.operationId);
           previous.operationId = replacement; ids.add(replacement); owners.set(replacement, previous);
         }
       } else {
-        const base = `${method}${pascalPath(name)}`;
-        operationId = base; let suffix = 1;
-        while (ids.has(operationId)) operationId = `${base}${++suffix}`;
+        operationId = uniqueEndpointName(`${method}${pascalPath(name)}`, ids);
       }
       const collected = { path: name, method, operation, operationId, parameters: mergedParameters };
       ids.add(operationId); owners.set(operationId, collected); operations.push(collected);