@voyant-travel/hono 0.119.0 → 0.120.0

package/dist/openapi.d.ts

@@ -124,30 +124,60 @@ export declare function mergeLazyOpenApiPaths(base: OpenApiDocument, mounts: rea
  * (`@asteasolutions/zod-to-openapi` must stay out of the Worker bundle).
  */
 export declare function generateModuleOpenApiDocuments(mounts: readonly ModuleMount[], options: GenerateOpenApiOptions): Promise<Map<string, OpenApiDocument>>;
+/**
+ * Build the authoritative path → module ownership map from the mount manifest.
+ *
+ * Generates each module's isolated doc (see `generateModuleOpenApiDocuments`)
+ * only to learn which real absolute paths it owns — so `publicPath` overrides
+ * (whose prefix isn't the module name, e.g. `/v1/public/booking-engine`) map to
+ * the right module. Routes the manifest doesn't record (`additionalRoutes`,
+ * directly-mounted routes) are absent here and fall back to their path segment.
+ *
+ * Build-time only.
+ */
+export declare function buildModulePathOwnership(mounts: readonly ModuleMount[], options: GenerateOpenApiOptions): Promise<Map<string, string>>;
 /**
  * Partition a composed document into one document per module, covering EVERY
  * admin/storefront path (voyant#2733).
  *
- * `generateModuleOpenApiDocuments` alone only sees routes recorded in the module
- * mount manifest — it misses `additionalRoutes` and any route mounted directly
- * on the composed app (e.g. the operator's workflow-runs admin surface, the
- * `_meta/capabilities` route). Those were present in the old committed aggregate
- * and must not silently vanish from the committed per-module specs.
- *
- * This uses the manifest as the *authoritative* owner for the routes it knows
- * about — which is what makes `publicPath` overrides (whose prefix isn't the
- * module name, e.g. `/v1/public/booking-engine`) land under the right module —
- * and falls back to the path's own second segment for anything the manifest
- * doesn't claim. The result therefore partitions the full surface exactly: every
- * `/v1/admin/*` and `/v1/public/*` path lands in exactly one module document.
- * Non-surface routes (`/v1/<name>` webhooks, legacy `/v1/*`) live only in the
- * aggregate, as before.
+ * Uses the ownership map as the authoritative module owner, falling back to the
+ * path's own segment for anything the manifest doesn't claim (e.g.
+ * `additionalRoutes` mounts like the operator's workflow-runs admin surface).
+ * The full surface is therefore partitioned exactly: every `/v1/admin/*` and
+ * `/v1/public/*` path lands in exactly one module document. Non-surface routes
+ * (`/v1/<name>` webhooks, legacy `/v1/*`) live only in the aggregate, as before.
  *
  * Each per-module document carries the aggregate's shared `components` verbatim
  * (there is ~one), so it stays a valid, self-contained OpenAPI document.
+ */
+export declare function partitionByModule(full: OpenApiDocument, owner: ReadonlyMap<string, string>): Map<string, OpenApiDocument>;
+/**
+ * Convenience: build the ownership map and partition in one call. Prefer the
+ * two-step `buildModulePathOwnership` + `partitionByModule` when you also want
+ * to `stampModuleMetadata` the aggregate from the same map (so it's built once).
  *
  * Build-time only.
  */
 export declare function splitDocumentByModule(full: OpenApiDocument, mounts: readonly ModuleMount[], options: GenerateOpenApiOptions): Promise<Map<string, OpenApiDocument>>;
+/**
+ * Stamp every operation with the metadata standard OpenAPI tooling expects
+ * (voyant#2733 / voyant#2729). All fields are non-destructive — a value a route
+ * already declares is never overwritten:
+ *   - `operationId` — stable camelCase id from method + path, for readable
+ *     generated client method names.
+ *   - `summary` — the method + path signature, so viewers/linters have a title
+ *     for every operation.
+ *   - `tags: [module]` — so Swagger/Scalar group the sidebar by module (they
+ *     key grouping off `tags` and ignore `x-*`).
+ *   - `x-voyant-module` / `x-voyant-surface` — machine-readable owner + surface
+ *     for custom tooling that shouldn't re-derive them from path prefixes.
+ *
+ * The module is the authoritative owner from the manifest, so `publicPath`
+ * overrides are labelled with their real owning module rather than their mount
+ * prefix. Applied to the aggregate before it's split, so the per-module and
+ * surface documents (all derived from it) inherit the stamps. Keys are appended,
+ * keeping order deterministic for the drift gate.
+ */
+export declare function stampModuleMetadata(doc: OpenApiDocument, owner: ReadonlyMap<string, string>): OpenApiDocument;
 export {};
 //# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8EAA8E;IAC9E,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;CAC1B;AAGD,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAEjC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAE7E;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CASjB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,YAAY,CAAA;AAO/C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,GAAG,eAAe,CAMxF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACrC;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CA8D1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAsCvC;AAOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CA4BvC"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"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"}

package/dist/openapi.js

@@ -173,46 +173,68 @@ export async function generateModuleOpenApiDocuments(mounts, options) {
     }
     return result;
 }
-/** Second path segment after the surface prefix — `/v1/admin/<seg>/...`. */
-function moduleSegment(path) {
-    return path.split("/")[3] ?? "misc";
+/**
+ * The module a path belongs to, given the authoritative owner map: the manifest
+ * owner if known (which is what keeps `publicPath` overrides correct), else the
+ * path's own module segment — `<seg>` in `/v1/admin/<seg>/...`,
+ * `/v1/public/<seg>/...`, or `/v1/<seg>/...` (webhooks/legacy).
+ */
+function moduleNameForPath(path, owner) {
+    const known = owner.get(path);
+    if (known)
+        return known;
+    const parts = path.split("/").filter(Boolean); // ["v1","admin","bookings",...]
+    const seg = parts[1] === "admin" || parts[1] === "public" ? parts[2] : parts[1];
+    return seg ?? "misc";
+}
+/** The API surface a path is served on, or `null` for non-surface routes. */
+function surfaceForPath(path) {
+    if (path.startsWith("/v1/admin/"))
+        return "admin";
+    if (path.startsWith("/v1/public/"))
+        return "storefront";
+    return null;
 }
 /**
- * Partition a composed document into one document per module, covering EVERY
- * admin/storefront path (voyant#2733).
- *
- * `generateModuleOpenApiDocuments` alone only sees routes recorded in the module
- * mount manifest — it misses `additionalRoutes` and any route mounted directly
- * on the composed app (e.g. the operator's workflow-runs admin surface, the
- * `_meta/capabilities` route). Those were present in the old committed aggregate
- * and must not silently vanish from the committed per-module specs.
+ * Build the authoritative path → module ownership map from the mount manifest.
  *
- * This uses the manifest as the *authoritative* owner for the routes it knows
- * about — which is what makes `publicPath` overrides (whose prefix isn't the
- * module name, e.g. `/v1/public/booking-engine`) land under the right module —
- * and falls back to the path's own second segment for anything the manifest
- * doesn't claim. The result therefore partitions the full surface exactly: every
- * `/v1/admin/*` and `/v1/public/*` path lands in exactly one module document.
- * Non-surface routes (`/v1/<name>` webhooks, legacy `/v1/*`) live only in the
- * aggregate, as before.
- *
- * Each per-module document carries the aggregate's shared `components` verbatim
- * (there is ~one), so it stays a valid, self-contained OpenAPI document.
+ * Generates each module's isolated doc (see `generateModuleOpenApiDocuments`)
+ * only to learn which real absolute paths it owns — so `publicPath` overrides
+ * (whose prefix isn't the module name, e.g. `/v1/public/booking-engine`) map to
+ * the right module. Routes the manifest doesn't record (`additionalRoutes`,
+ * directly-mounted routes) are absent here and fall back to their path segment.
  *
  * Build-time only.
  */
-export async function splitDocumentByModule(full, mounts, options) {
+export async function buildModulePathOwnership(mounts, options) {
     const moduleDocs = await generateModuleOpenApiDocuments(mounts, options);
     const owner = new Map();
     for (const [moduleName, doc] of moduleDocs) {
         for (const path of Object.keys(doc.paths ?? {}))
             owner.set(path, moduleName);
     }
+    return owner;
+}
+/**
+ * Partition a composed document into one document per module, covering EVERY
+ * admin/storefront path (voyant#2733).
+ *
+ * Uses the ownership map as the authoritative module owner, falling back to the
+ * path's own segment for anything the manifest doesn't claim (e.g.
+ * `additionalRoutes` mounts like the operator's workflow-runs admin surface).
+ * The full surface is therefore partitioned exactly: every `/v1/admin/*` and
+ * `/v1/public/*` path lands in exactly one module document. Non-surface routes
+ * (`/v1/<name>` webhooks, legacy `/v1/*`) live only in the aggregate, as before.
+ *
+ * Each per-module document carries the aggregate's shared `components` verbatim
+ * (there is ~one), so it stays a valid, self-contained OpenAPI document.
+ */
+export function partitionByModule(full, owner) {
     const buckets = new Map();
     for (const [path, item] of Object.entries(full.paths ?? {})) {
         if (!path.startsWith("/v1/admin/") && !path.startsWith("/v1/public/"))
             continue;
-        const moduleName = owner.get(path) ?? moduleSegment(path);
+        const moduleName = moduleNameForPath(path, owner);
         let bucket = buckets.get(moduleName);
         if (!bucket) {
             bucket = {};
@@ -230,3 +252,113 @@ export async function splitDocumentByModule(full, mounts, options) {
     }
     return result;
 }
+/**
+ * Convenience: build the ownership map and partition in one call. Prefer the
+ * two-step `buildModulePathOwnership` + `partitionByModule` when you also want
+ * to `stampModuleMetadata` the aggregate from the same map (so it's built once).
+ *
+ * Build-time only.
+ */
+export async function splitDocumentByModule(full, mounts, options) {
+    return partitionByModule(full, await buildModulePathOwnership(mounts, options));
+}
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/** PascalCase a path segment, splitting on non-alphanumerics (kebab, etc.). */
+function pascalCase(segment) {
+    return segment
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join("");
+}
+/**
+ * Stable camelCase operationId derived from method + path (voyant#2729) — gives
+ * client generators readable, deterministic method names instead of guessing.
+ * Path params render as `ByX`, the `v1` prefix is dropped:
+ * `GET /v1/admin/bookings/{id}` → `getAdminBookingsById`. Method + path is unique
+ * per OpenAPI, so the derived id is too (a numeric suffix guards edge cases).
+ */
+function deriveOperationId(method, path) {
+    const parts = path
+        .split("/")
+        .filter(Boolean)
+        .filter((segment) => segment !== "v1")
+        .map((segment) => {
+        const param = /^\{(.+)\}$/.exec(segment);
+        return param?.[1] ? `By${pascalCase(param[1])}` : pascalCase(segment);
+    });
+    return `${method}${parts.join("")}`;
+}
+/**
+ * A readable, always-correct operation summary (voyant#2729): the method + path
+ * signature. Deliberately mechanical rather than guessed prose — a hand-authored
+ * per-route `summary` overrides it (forward-only).
+ */
+function deriveSummary(method, path) {
+    return `${method.toUpperCase()} ${path}`;
+}
+/**
+ * Stamp every operation with the metadata standard OpenAPI tooling expects
+ * (voyant#2733 / voyant#2729). All fields are non-destructive — a value a route
+ * already declares is never overwritten:
+ *   - `operationId` — stable camelCase id from method + path, for readable
+ *     generated client method names.
+ *   - `summary` — the method + path signature, so viewers/linters have a title
+ *     for every operation.
+ *   - `tags: [module]` — so Swagger/Scalar group the sidebar by module (they
+ *     key grouping off `tags` and ignore `x-*`).
+ *   - `x-voyant-module` / `x-voyant-surface` — machine-readable owner + surface
+ *     for custom tooling that shouldn't re-derive them from path prefixes.
+ *
+ * The module is the authoritative owner from the manifest, so `publicPath`
+ * overrides are labelled with their real owning module rather than their mount
+ * prefix. Applied to the aggregate before it's split, so the per-module and
+ * surface documents (all derived from it) inherit the stamps. Keys are appended,
+ * keeping order deterministic for the drift gate.
+ */
+export function stampModuleMetadata(doc, owner) {
+    const paths = {};
+    // operationId must be unique across the document; track what we've assigned
+    // (including route-declared ids) so a derived id never collides.
+    const usedOperationIds = new Set();
+    for (const [path, item] of Object.entries(doc.paths ?? {})) {
+        if (!item || typeof item !== "object") {
+            paths[path] = item;
+            continue;
+        }
+        const moduleName = moduleNameForPath(path, owner);
+        const surface = surfaceForPath(path);
+        const nextItem = { ...item };
+        for (const method of HTTP_METHODS) {
+            const op = nextItem[method];
+            if (!op || typeof op !== "object")
+                continue;
+            const operation = op;
+            const declaredId = typeof operation.operationId === "string" && operation.operationId.length > 0
+                ? operation.operationId
+                : null;
+            let operationId = declaredId ?? deriveOperationId(method, path);
+            if (!declaredId) {
+                let suffix = 2;
+                while (usedOperationIds.has(operationId)) {
+                    operationId = `${deriveOperationId(method, path)}_${suffix++}`;
+                }
+            }
+            usedOperationIds.add(operationId);
+            const hasSummary = typeof operation.summary === "string" && operation.summary.length > 0;
+            // Swagger/Scalar group by `tags` (and ignore `x-*`) — without one a
+            // whole-surface document collapses under a single "default" group (#2733).
+            const hasTags = Array.isArray(operation.tags) && operation.tags.length > 0;
+            nextItem[method] = {
+                ...operation,
+                operationId,
+                ...(hasSummary ? {} : { summary: deriveSummary(method, path) }),
+                ...(hasTags ? {} : { tags: [moduleName] }),
+                "x-voyant-module": moduleName,
+                ...(surface ? { "x-voyant-surface": surface } : {}),
+            };
+        }
+        paths[path] = nextItem;
+    }
+    return { ...doc, paths };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/hono",
-  "version": "0.119.0",
+  "version": "0.120.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -140,14 +140,14 @@
     "@voyant-travel/storage": "^0.106.0",
     "@voyant-travel/types": "^0.106.1",
     "@voyant-travel/utils": "^0.105.5",
-    "@voyant-travel/workflows": "^0.111.13"
+    "@voyant-travel/workflows": "^0.111.14"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260628.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
     "@voyant-travel/voyant-typescript-config": "^0.1.0",
-    "@voyant-travel/workflows-orchestrator": "^0.111.13"
+    "@voyant-travel/workflows-orchestrator": "^0.111.14"
   },
   "files": [
     "dist"