zopia 0.3.0 → 0.5.0

package/src/conversions/api-docs-tree-types.ts

@@ -0,0 +1,113 @@
+/**
+ * 🧠 Generated exact tree types (S-95).
+ *
+ * Renders the `.zopia-tree.d.ts` declaration emitted beside every retained
+ * manifest: a types-only artifact describing the **exact** nested shape the
+ * runtime resolver (`createApiDocs`) builds and the **exact** flat record
+ * `flattenApiDocs` returns, so consumers get precise IntelliSense — literal
+ * path-segment keys, method leaves typed as the generated module's own
+ * `makeApiConfig()` export, and typo-proof access (unknown keys are compile
+ * errors). Nothing runtime is emitted; the file is pure declaration.
+ *
+ * Ordering and naming are shared with the runtime: entries sort through
+ * `compareApiDocsEntries` and flat keys derive through `endpointExportName` /
+ * `uniqueEndpointName` — the same rules as the generator's `export const`
+ * names — so the declared types match the runtime objects by construction.
+ */
+
+import { apiDocsPathSegments, compareApiDocsEntries } from './api-docs-layout';
+import { endpointExportName, uniqueEndpointName } from './api-docs-names';
+
+/** File name of the generated exact-tree declaration, written beside the manifest. */
+export const ZOPIA_TREE_TYPES_FILE = '.zopia-tree.d.ts';
+
+/** One endpoint record the declaration is rendered from. */
+export interface ApiDocsTreeTypePlan {
+  /** Portable endpoint-module path relative to the tree root (POSIX, with `.ts`). */
+  file: string;
+  /** OpenAPI path template — the authority for the nested key chain. */
+  path: string;
+  /** Lowercase HTTP method — the leaf key. */
+  method: string;
+  /** Declared or deterministically derived operation identifier. */
+  operationId: string;
+}
+
+/** Internal tree node while assembling the declaration: a branch, a method leaf, or both. */
+interface TypeTreeNode {
+  /** Child branches/leaves by key; insertion follows the deterministic entry order. */
+  children?: Map<string, TypeTreeNode>;
+  /** Module type reference when this node is (also) a method leaf. */
+  leaf?: { module: string; exportName: string };
+}
+
+/** Import-free module type reference: `typeof import('<module>').<exportName>`. */
+const typeReference = (module: string, exportName: string): string => `typeof import('${module}').${exportName}`;
+
+/** Module specifier of one endpoint plan: the portable file path without the `.ts` extension. */
+const moduleSpecifier = (file: string): string => `./${file.replace(/\.ts$/, '')}`;
+
+/**
+ * Render the `.zopia-tree.d.ts` declaration for one tree root.
+ *
+ * @param apis Endpoint records (path operations only — webhooks are not URL-path endpoints).
+ * @returns The complete declaration file text: an `ApiDocsTree` type keyed by exact URL path segments with lowercase-method leaves, and an `ApiDocsFlat` type keyed by the derived endpoint names.
+ */
+export function renderApiDocsTreeTypes(apis: readonly ApiDocsTreeTypePlan[]): string {
+  const sorted = [...apis].sort(compareApiDocsEntries);
+  const root: TypeTreeNode = {};
+  for (const api of sorted) {
+    let node: TypeTreeNode = root;
+    for (const segment of apiDocsPathSegments(api.path)) {
+      let child = node.children?.get(segment);
+      if (!child) {
+        child = {};
+        (node.children ??= new Map<string, TypeTreeNode>()).set(segment, child);
+      }
+      node = child;
+    }
+    (node.children ??= new Map<string, TypeTreeNode>()).set(api.method, { leaf: { module: moduleSpecifier(api.file), exportName: endpointExportName(api.operationId) } });
+  }
+
+  const renderNode = (node: TypeTreeNode, depth: number): string => {
+    if (!node.children || node.children.size === 0) return 'Record<string, never>';
+    const indent = '  '.repeat(depth);
+    const lines: string[] = [];
+    for (const [key, child] of node.children) {
+      const childType = child.leaf
+        ? child.children && child.children.size > 0
+          // A path continuing below another path's method leaf: the key is both the
+          // endpoint config and a deeper branch — the permissive intersection shape.
+          ? `(${typeReference(child.leaf.module, child.leaf.exportName)} & ${renderNode(child, 1)})`
+          : typeReference(child.leaf.module, child.leaf.exportName)
+        : renderNode(child, depth + 1);
+      lines.push(`${indent}  readonly ${JSON.stringify(key)}: ${childType};`);
+    }
+    return `{\n${lines.join('\n')}\n${indent}}`;
+  };
+
+  const flatLines: string[] = [];
+  const used = new Set<string>();
+  for (const api of sorted) {
+    const key = uniqueEndpointName(endpointExportName(api.operationId), used);
+    used.add(key);
+    flatLines.push(`  readonly ${JSON.stringify(key)}: ${typeReference(moduleSpecifier(api.file), endpointExportName(api.operationId))};`);
+  }
+
+  return [
+    '/**',
+    ' * Generated by zopia — do not edit by hand.',
+    ' *',
+    ' * Exact types of this api-docs tree as loaded at runtime by the',
+    ' * `createApiDocs()` / `flattenApiDocs()` helpers of the zopia `zopia/runtime`',
+    ' * subpath (types-only: this file imports nothing beyond the tree itself):',
+    ' *',
+    " *   const apiDocs = await createApiDocs<ApiDocsTree>('./<this-tree>');   // nested: exact segments → method",
+    ' *   const endpoints = flattenApiDocs<ApiDocsFlat>(apiDocs);             // flat: exact endpoint names',
+    ' */',
+    `export type ApiDocsTree = ${renderNode(root, 0)};`,
+    '',
+    `export type ApiDocsFlat = ${flatLines.length ? `{\n${flatLines.join('\n')}\n}` : 'Record<string, never>'};`,
+    '',
+  ].join('\n').replace(/[ \t]+$/gm, '');
+}

package/src/conversions/manifest-staleness.ts

@@ -1,6 +1,7 @@
 import { lstat, readFile, realpath, rmdir, rm, stat } from 'node:fs/promises';
 import { asZopiaError } from '../errors';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { ZOPIA_TREE_TYPES_FILE } from './api-docs-tree-types';
 import type { ApiDocsMode } from './api-docs-layout';
 import {
   validateZopiaManifest,
@@ -55,7 +56,8 @@ function compareText(left: string, right: string): number {
 const isManifestComponent = (value: unknown): value is { kind?: string; file?: unknown } => typeof value === 'object' && value !== null;
 
 function collectOwnedFiles(manifest: GeneratedZopiaManifest): string[] {
-  const files = new Set<string>([ZOPIA_MANIFEST_FILE]);
+  // The exact-tree declaration is written and pruned together with the manifest.
+  const files = new Set<string>([ZOPIA_MANIFEST_FILE, ZOPIA_TREE_TYPES_FILE]);
   for (const api of manifest.apis) files.add(api.file);
   for (const webhook of manifest.webhooks ?? []) files.add(webhook.file);
   for (const component of manifest.components) if (component.file !== null) files.add(component.file);
@@ -110,7 +112,7 @@ export async function inspectZopiaManifestStaleness(outputDir: string, identity:
     return {
       status: 'stale',
       reasons: ['invalid-manifest', ...(!identity.manifest ? ['manifest-disabled' as const] : [])],
-      ownedFiles: [ZOPIA_MANIFEST_FILE],
+      ownedFiles: [ZOPIA_MANIFEST_FILE, ZOPIA_TREE_TYPES_FILE],
     };
   }
 

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.5.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-public.ts

@@ -12,6 +12,7 @@ import { normalizeOpenApiDocument, type OpenApiDocument } from './openapi';
 import { parseYaml } from './yaml';
 import { jsonSchemaToZod, type JsonSchema } from './json-schema-to-zod';
 import { hashOpenApiDocument, ZOPIA_MANIFEST_FILE } from './manifest-writer';
+import { ZOPIA_TREE_TYPES_FILE } from './api-docs-tree-types';
 import { formatManifestStaleness, inspectZopiaManifestStaleness } from './manifest-staleness';
 import { join } from 'node:path';
 import { planPresetBuckets, ZOPIA_GENERATE_PRESETS, type ZopiaGeneratePreset, type ZopiaPresetTree } from './api-docs-presets';
@@ -39,7 +40,7 @@ export interface ZopiaGeneratedFile {
   /** Portable path relative to `outDir`. */
   path: string;
   /** Generated artifact category. */
-  kind: 'endpoint' | 'component' | 'manifest';
+  kind: 'endpoint' | 'component' | 'manifest' | 'types';
 }
 
 /** Result returned by the Engine ③ public API. */
@@ -459,7 +460,7 @@ export async function openApiToApiDocs(input: string | Record<string, unknown>,
     : []);
   const files: ZopiaGeneratedFile[] = generated.map(({ file }): ZopiaGeneratedFile => ({
     path: file,
-    kind: file === ZOPIA_MANIFEST_FILE ? 'manifest' : componentFiles.has(file) ? 'component' : 'endpoint',
+    kind: file === ZOPIA_MANIFEST_FILE ? 'manifest' : file === ZOPIA_TREE_TYPES_FILE ? 'types' : componentFiles.has(file) ? 'component' : 'endpoint',
   })).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
   const warningCollector = new ZopiaWarningCollector(); warningCollector.addAll(warnings);
   return { files, warnings: warningCollector.toArray(), ...(config.manifest ? { manifestPath: ZOPIA_MANIFEST_FILE } : {}) };

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);

package/src/runtime/create-api-docs.ts

@@ -0,0 +1,329 @@
+/**
+ * 🌳 Runtime consumption of a generated api-docs tree (S-94).
+ *
+ * Opt-in helpers, shipped behind the `zopia/runtime` subpath export, that turn
+ * a generated tree directory into the objects an application consumes:
+ * {@link createApiDocs} loads every endpoint module named by the tree's
+ * manifest(s) into one nested object keyed by the exact URL path segments with
+ * the lowercase method as the leaf key, and {@link flattenApiDocs} deep-walks
+ * that tree into a flat record keyed by each config's `operationId` (derived
+ * with the generator's own naming rules). Generation output is untouched —
+ * these helpers only read and import.
+ */
+
+import type { IMakeApiConfigEntry } from 'km-api';
+import { readFile, readdir } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { asZopiaError, ZopiaError } from '../errors';
+import { endpointExportName, uniqueEndpointName } from '../conversions/api-docs-names';
+import { apiDocsPathSegments, compareApiDocsEntries } from '../conversions/api-docs-layout';
+import { deriveOperationId, OPENAPI_METHODS, type OpenApiMethod } from '../conversions/openapi-to-api-docs';
+import { ZOPIA_MANIFEST_FILE } from '../conversions/manifest-writer';
+
+/** One generated km-api endpoint configuration — the `export default` value every endpoint module ships (R-732). */
+export type ApiDocsEndpointConfig = IMakeApiConfigEntry;
+
+/**
+ * Nested runtime view of one generated api-docs tree.
+ *
+ * Branch keys are the URL path segments **verbatim and in order** (including
+ * literal `{param}` segments), the leaf key is the lowercase HTTP method, and
+ * the leaf value is the endpoint module's default export. Because which keys
+ * exist depends on the source spec, every node is typed permissively as both a
+ * deeper branch and an {@link ApiDocsEndpointConfig}, so chained access such as
+ * `apiDocs.users['{userId}'].get.method` typechecks and reads the runtime
+ * values the tree actually holds.
+ */
+export interface ApiDocsTree {
+  /** Deeper path-segment branch or the method-leaf endpoint config; presence is decided by the source spec at runtime. */
+  [segment: string]: ApiDocsTree & ApiDocsEndpointConfig;
+}
+
+/** Internal mutable branch node; null-prototype objects keep `{param}` and `__proto__` segments plain own keys. */
+type ApiDocsBranch = Record<string, unknown>;
+
+/** One merged, deduplicated manifest endpoint record ready for tree insertion. */
+interface MergedApiEntry {
+  /** Absolute directory of the manifest this entry came from (its file paths resolve against it). */
+  root: string;
+  /** Portable endpoint-module path relative to `root`. */
+  file: string;
+  /** Original OpenAPI path template — the authority for the nested key chain. */
+  path: string;
+  /** Lowercase HTTP method — the leaf key. */
+  method: string;
+}
+
+/** One discovered manifest with the directory its relative file paths resolve against. */
+interface DiscoveredManifest {
+  /** Absolute directory containing this manifest (the tree root or a preset bucket root). */
+  root: string;
+  /** Validated `apis[]` endpoint records of this manifest, in manifest order. */
+  apis: Array<{ file: string; path: string; method: string }>;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);
+const compareText = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
+const isMissingFileError = (error: unknown): boolean => isRecord(error) && (error.code === 'ENOENT' || error.code === 'ENOTDIR');
+const isSupportedApiDocsMethod = (method: string): boolean => (OPENAPI_METHODS as readonly string[]).includes(method);
+
+/** Guard one manifest file reference: relative, POSIX-separated, and unable to escape the tree root. */
+function isSafeTreeFile(file: string): boolean {
+  if (!file || isAbsolute(file) || file.includes('\\') || /^[A-Za-z]:/.test(file)) return false;
+  return file.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+/** Validate one parsed manifest and return its `apis[]` records (reader-tolerant shape, hard on unsafe paths). */
+function manifestApiEntries(manifest: unknown, manifestPath: string): Array<{ file: string; path: string; method: string }> {
+  if (!isRecord(manifest) || !Array.isArray(manifest.apis)) {
+    throw new ZopiaError('ZOPIA_MANIFEST_INVALID', `invalid zopia manifest (expected an object with an apis array): ${manifestPath}`, { at: manifestPath, hint: 'regenerate the tree to rebuild a valid manifest' });
+  }
+  const entries: Array<{ file: string; path: string; method: string }> = [];
+  for (const [index, api] of manifest.apis.entries()) {
+    if (!isRecord(api)
+      || typeof api.file !== 'string' || !isSafeTreeFile(api.file)
+      || typeof api.path !== 'string' || !api.path.startsWith('/')
+      || typeof api.method !== 'string' || !isSupportedApiDocsMethod(api.method)) {
+      throw new ZopiaError('ZOPIA_MANIFEST_INVALID', `invalid zopia manifest API entry ${index}: ${manifestPath}`, { at: `${manifestPath}#apis/${index}`, hint: 'regenerate the tree to rebuild a valid manifest' });
+    }
+    entries.push({ file: api.file, path: api.path, method: api.method });
+  }
+  return entries;
+}
+
+/** Read and parse one manifest file; a missing file resolves to `undefined`, garbled JSON fails typed. */
+async function readManifestFile(file: string): Promise<unknown> {
+  let text: string;
+  try { text = await readFile(file, 'utf8'); }
+  catch (error) {
+    if (isMissingFileError(error)) return undefined;
+    throw asZopiaError(error, 'ZOPIA_MANIFEST_INVALID', 'unable to read zopia manifest', { at: file, hint: 'check that the manifest is readable JSON' });
+  }
+  try { return JSON.parse(text) as unknown; }
+  catch (error) { throw new ZopiaError('ZOPIA_MANIFEST_INVALID', `invalid zopia manifest JSON: ${file}`, { at: file, hint: 'regenerate the tree to rebuild a valid manifest', cause: error }); }
+}
+
+/**
+ * Discover every manifest of one output root: the root `.zopia-manifest.json`
+ * plus the one-level-deep preset bucket roots (`multi-tag` / `multi-server`
+ * splits write one manifest per bucket directory). Real directories only —
+ * symlinked children never masquerade as bucket roots.
+ */
+async function discoverApiDocsManifests(root: string): Promise<DiscoveredManifest[]> {
+  const discovered: DiscoveredManifest[] = [];
+  const rootManifestPath = join(root, ZOPIA_MANIFEST_FILE);
+  const rootManifest = await readManifestFile(rootManifestPath);
+  if (rootManifest !== undefined) discovered.push({ root, apis: manifestApiEntries(rootManifest, rootManifestPath) });
+  let directories: string[] = [];
+  try {
+    directories = (await readdir(root, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort(compareText);
+  } catch (error) {
+    // A missing root simply has no buckets; anything else is an unreadable tree.
+    if (!isMissingFileError(error)) throw asZopiaError(error, 'ZOPIA_MANIFEST_INVALID', 'unable to scan the api-docs directory', { at: root, hint: 'check that the directory is readable' });
+  }
+  for (const directory of directories) {
+    const bucketRoot = join(root, directory);
+    const bucketManifestPath = join(bucketRoot, ZOPIA_MANIFEST_FILE);
+    const bucketManifest = await readManifestFile(bucketManifestPath);
+    if (bucketManifest !== undefined) discovered.push({ root: bucketRoot, apis: manifestApiEntries(bucketManifest, bucketManifestPath) });
+  }
+  return discovered;
+}
+
+/**
+ * Merge discovered manifests into one deterministically sorted entry list.
+ * Duplicates are dropped by `${path}#${method}` identity (the root manifest
+ * wins over bucket manifests, buckets in sorted directory order); the sort is
+ * path segments first, then the canonical method order
+ * (`get, post, put, delete, head, options, patch, trace`).
+ */
+function mergeApiEntries(manifests: readonly DiscoveredManifest[]): MergedApiEntry[] {
+  const seen = new Set<string>();
+  const merged: MergedApiEntry[] = [];
+  for (const { root, apis } of manifests) {
+    for (const api of apis) {
+      const identity = `${api.path}#${api.method}`;
+      if (seen.has(identity)) continue;
+      seen.add(identity);
+      merged.push({ root, file: api.file, path: api.path, method: api.method });
+    }
+  }
+  return merged.sort((left, right) => compareApiDocsEntries(left, right));
+}
+
+/** Import one generated endpoint module through its file URL — `pathToFileURL` keeps absolute (Windows-style) paths safe. */
+async function importEndpointModule(root: string, file: string): Promise<Record<string, unknown>> {
+  try {
+    return await import(pathToFileURL(join(root, file)).href) as Record<string, unknown>;
+  } catch (error) {
+    throw new ZopiaError('ZOPIA_DOCS_IMPORT_FAILED', `unable to import generated endpoint module: ${file}`, { at: file, hint: 'fix or regenerate the affected generated module', cause: error });
+  }
+}
+
+/** Create one null-prototype branch node so every path segment becomes a plain own enumerable key. */
+function createBranch(): ApiDocsBranch {
+  return Object.create(null) as ApiDocsBranch;
+}
+
+/** Whether one tree node is a branch this resolver created (null prototype) rather than an endpoint config leaf. */
+function isBranch(value: unknown): value is ApiDocsBranch {
+  return isRecord(value) && Object.getPrototypeOf(value) === null;
+}
+
+/** Typed failure for paths whose nested key chains cannot coexist in one tree (below a method leaf, or trailing-slash twins). */
+function treeConflictError(file: string, detail: string): ZopiaError {
+  return new ZopiaError('ZOPIA_SPEC_INVALID', `the nested api-docs tree cannot represent this path: ${detail}`, { at: file, hint: 'rename the colliding path, or consume its endpoint module through a direct import / flattenApiDocs' });
+}
+
+/** Insert one endpoint config at its segment chain, failing typed when another path already owns a conflicting key. */
+function insertEndpoint(root: ApiDocsBranch, segments: readonly string[], method: string, config: unknown, file: string): void {
+  let node = root;
+  for (const segment of segments) {
+    const existing = node[segment];
+    if (existing === undefined) {
+      const branch = createBranch();
+      node[segment] = branch;
+      node = branch;
+    } else if (isBranch(existing)) {
+      node = existing;
+    } else {
+      throw treeConflictError(file, `segment '${segment}' is already the method leaf of another path`);
+    }
+  }
+  if (node[method] !== undefined) {
+    throw treeConflictError(file, `method leaf '${method}' is already occupied at this tree node by another path with the same segments (paths differing only by a trailing slash collapse to one another)`);
+  }
+  node[method] = config;
+}
+
+/** Whether one tree value is a km-api endpoint config leaf (string `method` + `pathShape`, object `request` + `response`). */
+function isEndpointConfig(value: unknown): value is ApiDocsEndpointConfig & Record<string, unknown> {
+  return isRecord(value) && typeof value.method === 'string' && typeof value.pathShape === 'string' && isRecord(value.request) && isRecord(value.response);
+}
+
+/**
+ * Load a generated api-docs tree into one nested endpoint object.
+ *
+ * The resolver is layout- and path-preserving: it discovers the root
+ * `.zopia-manifest.json` plus every one-level-deep preset bucket manifest
+ * (`multi-tag` / `multi-server`), merges them (deduplicating by
+ * `${path}#${method}`), and accepts any directory that was ever a zopia output
+ * root — tree roots and preset bucket roots alike. Endpoint modules are loaded
+ * with dynamic `import()` through `pathToFileURL`, and every leaf is the
+ * module's **default export** (its named export stays available on the module
+ * itself). Keys are inserted in the deterministic manifest order, so the same
+ * tree always enumerates its keys in the same order. The tree is only read and
+ * imported — nothing on disk is written.
+ *
+ * **Exact IntelliSense (S-95):** every tree generated with a manifest also
+ * carries a `.zopia-tree.d.ts` declaration. Pass its `ApiDocsTree` type as the
+ * type argument to type the result exactly — literal path-segment keys,
+ * method-leaf configs typed as the generated module's own `makeApiConfig()`
+ * export, and unknown keys become compile errors:
+ *
+ * ```ts
+ * import type { ApiDocsTree } from './api_docs/.zopia-tree';
+ * const apiDocs = await createApiDocs<ApiDocsTree>('./api_docs');
+ * ```
+ *
+ * @param docsDir Generated api-docs output directory (tree root or preset bucket root; absolute or relative).
+ * @returns Nested tree keyed by exact URL path segments with lowercase-method leaves holding the endpoint configs.
+ * @throws {ZopiaError} `ZOPIA_CONFIG_INVALID` when `docsDir` is not a usable path.
+ * @throws {ZopiaError} `ZOPIA_DOCS_MISSING_MANIFEST` when no root or bucket manifest exists under `docsDir`.
+ * @throws {ZopiaError} `ZOPIA_MANIFEST_INVALID` when a discovered manifest is garbled JSON or has unusable `apis[]` records.
+ * @throws {ZopiaError} `ZOPIA_DOCS_IMPORT_FAILED` when an endpoint module cannot be imported or has no default export.
+ * @throws {ZopiaError} `ZOPIA_SPEC_INVALID` when two paths cannot coexist in one nested tree (a path continuing below another path's method leaf, or trailing-slash twins).
+ * @example
+ * ```ts
+ * import { createApiDocs } from './src/runtime';
+ *
+ * // Exact typing: pass the generated `.zopia-tree.d.ts` tree type.
+ * type MyTree = { readonly users: { readonly get: { readonly pathShape: string } } };
+ * const apiDocs = await createApiDocs<MyTree>('api_docs');
+ * console.log(apiDocs.users.get.pathShape);
+ * ```
+ * @see [docs/07-api-docs.md → Runtime tree consumption](../../docs/07-api-docs.md)
+ */
+export async function createApiDocs<TTree extends object = ApiDocsTree>(docsDir: string): Promise<TTree> {
+  if (typeof docsDir !== 'string' || docsDir.trim() === '' || docsDir.includes('\0')) {
+    throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'docsDir must be a non-empty directory path', { at: 'docsDir', hint: 'provide the generated api-docs output directory (tree root or preset bucket root)' });
+  }
+  const root = resolve(docsDir);
+  const manifests = await discoverApiDocsManifests(root);
+  if (manifests.length === 0) {
+    throw new ZopiaError('ZOPIA_DOCS_MISSING_MANIFEST', `no zopia manifest found under ${docsDir}`, { at: join(docsDir, ZOPIA_MANIFEST_FILE), hint: 'generate api docs first (manifests stay enabled by default), or pass a tree or preset-bucket root' });
+  }
+  const entries = mergeApiEntries(manifests);
+  const tree = createBranch();
+  for (const entry of entries) {
+    const endpointModule = await importEndpointModule(entry.root, entry.file);
+    const config = endpointModule.default;
+    if (!isRecord(config)) {
+      throw new ZopiaError('ZOPIA_DOCS_IMPORT_FAILED', `generated endpoint module has no default export: ${entry.file}`, { at: entry.file, hint: "regenerate the tree, or restore the module's default endpoint-config export" });
+    }
+    insertEndpoint(tree, apiDocsPathSegments(entry.path), entry.method, config, entry.file);
+  }
+  return tree as unknown as TTree;
+}
+
+/**
+ * Flatten one runtime api-docs tree into a record keyed by endpoint name.
+ *
+ * Deep-walks the tree produced by {@link createApiDocs} in its deterministic
+ * leaf order and registers every endpoint config under its `operationId`. When
+ * a leaf has no usable `operationId`, the key is derived by the **same rules
+ * the generator uses for its export identifiers** (method + PascalCase path
+ * segments, camelize, reserved-word guard, leading-numeric guard), and
+ * collisions receive the generator's `2`, `3`, … uniqueness suffix — a later
+ * duplicate never clobbers an already-registered name. The returned record has
+ * a null prototype, so even an `operationId` spelled `__proto__` stays a plain
+ * own key.
+ *
+ * **Exact IntelliSense (S-95):** pass the generated `.zopia-tree.d.ts`
+ * `ApiDocsFlat` type as the type argument to key the record exactly —
+ * `endpoints.getUser` autocompletes and unknown names become compile errors:
+ *
+ * ```ts
+ * import type { ApiDocsFlat } from './api_docs/.zopia-tree';
+ * const endpoints = flattenApiDocs<ApiDocsFlat>(apiDocs);
+ * ```
+ *
+ * @param apiDocs Nested tree returned by {@link createApiDocs} (exact generated tree types are accepted).
+ * @returns Flat record of every endpoint config keyed by its derived endpoint name, in tree leaf order.
+ * @throws {ZopiaError} `ZOPIA_CONFIG_INVALID` when `apiDocs` is not the nested tree object (a non-object input or a non-tree value inside it).
+ * @throws {ZopiaError} `ZOPIA_SPEC_INVALID` when a leaf without a usable `operationId` cannot be named (its `pathShape` is not an OpenAPI `/`-rooted template or its `method` is not one of the eight standard methods).
+ * @example
+ * ```ts
+ * import { createApiDocs, flattenApiDocs, type ApiDocsEndpointConfig } from './src/runtime';
+ *
+ * // Exact typing: pass the generated `.zopia-tree.d.ts` flat type.
+ * type MyFlat = { readonly getUser: ApiDocsEndpointConfig };
+ * const endpoints = flattenApiDocs<MyFlat>(await createApiDocs('api_docs'));
+ * console.log(endpoints.getUser.pathShape);
+ * ```
+ * @see [docs/07-api-docs.md → Runtime tree consumption](../../docs/07-api-docs.md)
+ */
+export function flattenApiDocs<TFlat extends Record<string, ApiDocsEndpointConfig> = Record<string, ApiDocsEndpointConfig>>(apiDocs: object): TFlat {
+  if (!isRecord(apiDocs)) {
+    throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'flattenApiDocs expects the tree object returned by createApiDocs', { at: 'apiDocs', hint: 'pass the createApiDocs result (a nested object of endpoint configs)' });
+  }
+  const flat: Record<string, ApiDocsEndpointConfig> = createBranch() as Record<string, ApiDocsEndpointConfig>;
+  const used = new Set<string>();
+  const register = (config: ApiDocsEndpointConfig & Record<string, unknown>): void => {
+    const operationId = typeof config.operationId === 'string' && config.operationId.trim() !== '' ? config.operationId : undefined;
+    const base = endpointExportName(operationId ?? deriveOperationId(config.pathShape, config.method.toLowerCase() as OpenApiMethod));
+    const key = uniqueEndpointName(base, used);
+    used.add(key);
+    flat[key] = config;
+  };
+  const walk = (node: Record<string, unknown>): void => {
+    for (const [key, value] of Object.entries(node)) {
+      if (isEndpointConfig(value)) register(value);
+      else if (isRecord(value)) walk(value);
+      else throw new ZopiaError('ZOPIA_CONFIG_INVALID', `unexpected value in the api-docs tree at key '${key}': ${typeof value}`, { at: key, hint: 'pass the createApiDocs result (every value is a branch or an endpoint config)' });
+    }
+  };
+  walk(apiDocs);
+  return flat as unknown as TFlat;
+}

package/src/runtime.ts

@@ -0,0 +1,10 @@
+/**
+ * 🌳 Opt-in runtime tree consumption (S-94).
+ *
+ * Thin subpath entry (`zopia/runtime`) re-exporting the helpers that turn a
+ * generated api-docs directory into the objects an application consumes. The
+ * package root stays free of filesystem-importing APIs — importing this
+ * subpath is the explicit opt-in.
+ */
+
+export { createApiDocs, flattenApiDocs, type ApiDocsEndpointConfig, type ApiDocsTree } from './runtime/create-api-docs';

package/docs/01-overview.md

@@ -1,94 +0,0 @@
-# 🧭 Overview
-
-zopia is a **type-safe OpenAPI ↔ Zod toolkit** for generating, validating, and
-transforming API schemas. It converts between the four formats an API team
-lives in — **Swagger 2.0**, **OpenAPI 3.x**, **JSON Schema**, and **Zod v4** —
-and turns any of them into a tree of **type-safe `km-api` endpoint files** that
-drop straight into a TypeScript codebase.
-
-## 🌩️ The problem
-
-API teams keep the same knowledge in many places, and every copy drifts:
-
-| 😖 Pain | 🔍 Consequence |
-| --- | --- |
-| The spec (`swagger.json`) describes the API | …but the validation code is written by hand |
-| Zod schemas validate at runtime | …but they are re-typed from the spec, field by field |
-| Components (`$ref`) keep the DRY spec | …but the generated code duplicates the same shapes |
-| Swagger 2.0 and OpenAPI 3.x differ subtly | …and both must be supported to read legacy specs |
-
-**Every copy is a source of bugs. Every re-typing is a waste of time.**
-
-## 🛠️ The solution
-
-zopia makes the spec and the code **two views of one fact**:
-
-```mermaid
-flowchart LR
-  A["📄 swagger.json<br/>(v2 / v3)"] -->|"③ openapi → api docs"| B["📂 api_docs/**<br/>(.ts · km-api · zod v4)"]
-  B -->|"④ api docs → openapi"| A
-  C["⚛️ Zod v4 schemas"] -->|"① zod → JSON Schema"| D["📐 JSON Schema"]
-  D -->|"② JSON Schema → zod"| C
-```
-
-- **③** reads a spec, resolves every `$ref`, and renders one **`index.ts` per
-  endpoint** — each built with `makeApiConfig()` from **km-api** (0.4.x), with
-  request/response/params/query/headers/cookies validated by **Zod v4** schemas.
-- **④** reads that tree back and regenerates a complete OpenAPI document — so
-  developer edits to the generated code become the new spec.
-- **① / ②** are the two primitive schema converters the other engines are built on.
-
-## 🎯 The promise
-
-> **Fast and valid developing.** A developer gets **valid, documented,
-> type-safe** endpoint code **in seconds**, from a spec they already trust —
-> and can always get the spec back.
-
-## 🧰 The stack (fixed, by standard)
-
-| 🧩 Piece | Version | Role in zopia |
-| --- | --- | --- |
-| ⚛️ [Zod](https://zod.dev/) | **v4** (`^4`) | Runtime validation + static types; built-in `z.toJSONSchema()` |
-| 🧱 [km-api](https://www.npmjs.com/package/km-api) | **0.4.x** (`^0.4` from npm) | The "make function" — `makeApiConfig()` builds every generated endpoint |
-| 🟣 [Bun](https://bun.sh/) | `≥ 1.1` | Primary runtime & toolchain (runs the package, tests, and generated code) |
-| 🧪 [Vitest](https://vitest.dev/) | latest stable | Test runner for the full scenario matrix |
-| 🔷 TypeScript | `5.9+`, `strict` | Language of the package and of every generated file |
-
-## 👥 Who is this for?
-
-- 🧑‍💻 **TypeScript backend teams** that maintain a Swagger/OpenAPI spec and
-  want the validation layer generated, not hand-written
-- 🔄 **Legacy teams** still on Swagger 2.0 who need a path to OpenAPI 3.x
-- 🤝 **Full-stack teams** that want one artifact (`api_docs/**`) shared between
-  server validation and client code
-
-## 🚫 Non-goals (Phase 1)
-
-Being explicit about what zopia **does not do** keeps the scope honest:
-
-- 🌐 It is **not a runtime** — no HTTP server, no client, no hosting of specs.
-  (km-api already provides client adapters; zopia generates the definitions.)
-- ✍️ It is **not a spec editor** — it never edits your original spec file.
-- 🧮 It does **not execute user code** except through the documented,
-  trusted-input contract of engine ④ (see [Standards → Safety](12-standards.md#-safety)).
-- 📝 **YAML input** — v0.1.0 accepted JSON only; v0.2.x lifts that limit
-  (D-16): JSON/YAML objects, JSON/YAML text, and `spec.json` / `spec.yaml` /
-  `spec.yml` all enter the same normalized model through zopia's owned
-  deterministic YAML parser.
-
-## 💎 Core principles
-
-| # | Principle | Meaning |
-| --- | --- | --- |
-| P-1 | 🎯 **Deterministic** | Same input + same options ⇒ **byte-identical** output. No timestamps, no random order, no environment leakage. |
-| P-2 | 🔒 **Lossless by design** | Every conversion is reversible; what cannot be represented in the target format is recorded (manifest + warnings), never silently dropped. |
-| P-3 | 🧼 **Pure core** | In-memory transforms stay pure; documented file reads, generated-tree writes/imports, and CLI process access live at explicit adapter boundaries. |
-| P-4 | 🛡️ **Safe** | Fail loudly with typed, actionable errors; never write outside the configured output directory; never hide lossy conversions. |
-| P-5 | 📖 **Documented** | Every public symbol has JSDoc; every rule is numbered; every decision is recorded. |
-| P-6 | 📦 **Dependency-light** | Zero bundled runtime dependencies; `zod` and `km-api` remain explicit peers (`zod` powers engines ①/② and generated schemas; km-api powers generated endpoints and their reverse imports). |
-
-## 🔗 Next
-
-- 🎯 The completed public targets → [Targets](02-targets.md)
-- 🗺️ Release phases and deferred breadth → [Roadmap](03-roadmap.md)
-- 🧩 Words you will keep seeing → [Concepts](05-concepts.md)