@open-mercato/shared 0.9.1-develop.7476.1.342138d35e → 0.9.1-develop.7496.1.3346415f94

package/src/lib/crud/__tests__/ids.test.ts

@@ -1,4 +1,11 @@
-import { MAX_IDS_PER_REQUEST, mergeIdFilter, parseIdsParam, isIdsParamProvided } from '@open-mercato/shared/lib/crud/ids'
+import {
+  MAX_IDS_PER_REQUEST,
+  mergeIdFilter,
+  parseIdsParam,
+  isIdsParamProvided,
+  isUuidListParam,
+  splitIdListParam,
+} from '@open-mercato/shared/lib/crud/ids'
 
 describe('crud ids helpers', () => {
   const idA = '550e8400-e29b-41d4-a716-446655440001'
@@ -168,4 +175,30 @@ describe('crud ids helpers', () => {
       tenantId: 't1',
     })
   })
+
+  it('splitIdListParam trims entries and drops empty ones', () => {
+    expect(splitIdListParam(` ${idA} ,, ${idB} ,`)).toEqual([idA, idB])
+    expect(splitIdListParam(undefined)).toEqual([])
+    expect(splitIdListParam(['not', 'a', 'string'])).toEqual([])
+  })
+
+  it('isUuidListParam accepts absent, empty, and all-UUID lists', () => {
+    expect(isUuidListParam(undefined)).toBe(true)
+    expect(isUuidListParam('')).toBe(true)
+    expect(isUuidListParam(` ${idA}, ${idB.toUpperCase()} `)).toBe(true)
+    expect(isUuidListParam('00000000-0000-0000-0000-000000000000')).toBe(true)
+  })
+
+  it('isUuidListParam rejects malformed and mixed lists', () => {
+    expect(isUuidListParam('not-a-uuid')).toBe(false)
+    expect(isUuidListParam(`${idA},not-a-uuid`)).toBe(false)
+    expect(isUuidListParam(`${idA}0`)).toBe(false)
+    expect(isUuidListParam(`{${idA}}`)).toBe(false)
+  })
+
+  it('isUuidListParam fails closed on non-string values', () => {
+    expect(isUuidListParam(['not-a-uuid'])).toBe(false)
+    expect(isUuidListParam([idA])).toBe(false)
+    expect(isUuidListParam(null)).toBe(false)
+  })
 })

package/src/lib/crud/ids.ts

@@ -51,6 +51,30 @@ export function parseIdsParam(raw: unknown, maxIds: number = MAX_IDS_PER_REQUEST
   return parsed.slice(0, safeMax)
 }
 
+const UUID_SHAPE_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * Splits a comma-separated id list query param into its trimmed, non-empty entries.
+ */
+export function splitIdListParam(raw: unknown): string[] {
+  if (typeof raw !== 'string') return []
+  return raw
+    .split(',')
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0)
+}
+
+/**
+ * Whether every entry of a comma-separated id list query param is UUID-shaped, so it can be
+ * bound to a uuid column without a database error. Use it to reject a malformed or mixed list
+ * with a 400 instead of dropping the bad entries and widening the result set (#7265).
+ */
+export function isUuidListParam(raw: unknown): boolean {
+  if (raw === undefined) return true
+  if (typeof raw !== 'string') return false
+  return splitIdListParam(raw).every((value) => UUID_SHAPE_REGEX.test(value))
+}
+
 /**
  * Whether an `?ids=` param was supplied at all (a non-empty string, or repeated
  * `?ids=` occurrences), regardless of whether any value survived UUID

package/src/lib/openapi/__tests__/optional-path-params.test.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod'
+import { buildOpenApiDocument } from '../generator'
+import type { Module } from '../../../modules/registry'
+
+type ParameterNode = { name?: string; in?: string; required?: boolean }
+type OperationNode = { operationId?: string; parameters?: ParameterNode[] }
+
+const noopHandler = async () => new Response(null)
+
+function imageModule(extraApis: unknown[] = [], operationId?: string): Module {
+  return {
+    id: 'attachments',
+    apis: [
+      {
+        path: '/attachments/image/[id]/[[...slug]]',
+        handlers: { GET: noopHandler },
+        docs: {
+          methods: {
+            GET: {
+              summary: 'Serve image',
+              ...(operationId ? { operationId } : {}),
+              pathParams: z.object({ id: z.string().uuid() }),
+              responses: [{ status: 200, description: 'Image' }],
+            },
+          },
+        },
+      },
+      ...extraApis,
+    ],
+  } as unknown as Module
+}
+
+function operation(doc: ReturnType<typeof buildOpenApiDocument>, path: string): OperationNode | undefined {
+  return (doc.paths[path] as Record<string, OperationNode> | undefined)?.get
+}
+
+function collectPathParameterViolations(doc: ReturnType<typeof buildOpenApiDocument>): string[] {
+  const violations: string[] = []
+  const operationIds = new Set<string>()
+  for (const [path, item] of Object.entries(doc.paths)) {
+    const templateNames = Array.from(path.matchAll(/\{([^}]+)\}/g), (match) => match[1])
+    for (const [method, op] of Object.entries(item as Record<string, OperationNode>)) {
+      const pathParams = (op.parameters ?? []).filter((param) => param.in === 'path')
+      for (const param of pathParams) {
+        if (param.required !== true) violations.push(`${method} ${path}: path parameter ${param.name} is not required`)
+        if (!templateNames.includes(param.name ?? '')) violations.push(`${method} ${path}: path parameter ${param.name} is not in the template`)
+      }
+      for (const name of templateNames) {
+        if (!pathParams.some((param) => param.name === name)) violations.push(`${method} ${path}: template variable ${name} is not declared`)
+      }
+      if (op.operationId) {
+        if (operationIds.has(op.operationId)) violations.push(`${method} ${path}: duplicate operationId ${op.operationId}`)
+        operationIds.add(op.operationId)
+      }
+    }
+  }
+  return violations
+}
+
+describe('buildOpenApiDocument optional catch-all path parameters', () => {
+  it('emits id-only and id-plus-slug paths with only required path parameters', () => {
+    const doc = buildOpenApiDocument([imageModule()])
+
+    expect(collectPathParameterViolations(doc)).toEqual([])
+
+    const withSlug = operation(doc, '/attachments/image/{id}/{slug}')
+    const withoutSlug = operation(doc, '/attachments/image/{id}')
+    expect(withSlug?.parameters?.filter((param) => param.in === 'path').map((param) => param.name)).toEqual(['id', 'slug'])
+    expect(withoutSlug?.parameters?.filter((param) => param.in === 'path').map((param) => param.name)).toEqual(['id'])
+  })
+
+  it('keeps the published operationId on the slug path and gives the id-only path a distinct one', () => {
+    const doc = buildOpenApiDocument([imageModule()])
+
+    expect(operation(doc, '/attachments/image/{id}/{slug}')?.operationId).toBe('attachments_get_attachments_image_id_slug')
+    expect(operation(doc, '/attachments/image/{id}')?.operationId).toBe('attachments_get_attachments_image_id')
+  })
+
+  it('derives a distinct id-only operationId from an explicit operationId', () => {
+    const doc = buildOpenApiDocument([imageModule([], 'serveImage')])
+
+    expect(operation(doc, '/attachments/image/{id}/{slug}')?.operationId).toBe('serveImage')
+    expect(operation(doc, '/attachments/image/{id}')?.operationId).toBe('serveImage_without_slug')
+  })
+
+  it('never replaces a concrete route that owns the id-only path, whichever is registered first', () => {
+    const concreteRoute = {
+      path: '/attachments/image/[id]',
+      handlers: { GET: noopHandler },
+      docs: { methods: { GET: { summary: 'Concrete', operationId: 'concreteImage', responses: [{ status: 200, description: 'OK' }] } } },
+    }
+    const after = buildOpenApiDocument([imageModule([concreteRoute])])
+    const before = buildOpenApiDocument([
+      { id: 'other', apis: [concreteRoute] } as unknown as Module,
+      imageModule(),
+    ])
+
+    expect(operation(after, '/attachments/image/{id}')?.operationId).toBe('concreteImage')
+    expect(operation(before, '/attachments/image/{id}')?.operationId).toBe('concreteImage')
+    expect(collectPathParameterViolations(after)).toEqual([])
+  })
+})

package/src/lib/openapi/generator.ts

@@ -15,6 +15,12 @@ type PathParamInfo = {
   optional?: boolean
 }
 
+type PathVariant = {
+  path: string
+  params: PathParamInfo[]
+  omittedParam?: string
+}
+
 type ParameterLocation = 'query' | 'path' | 'header'
 
 export type JsonSchema = Record<string, unknown>
@@ -119,6 +125,20 @@ function normalizePath(path: string): { path: string; params: PathParamInfo[] }
   return { path: '/' + normalized, params }
 }
 
+function expandOptionalPathParams(normalized: { path: string; params: PathParamInfo[] }): PathVariant[] {
+  const required = normalized.params.filter((param) => !param.optional)
+  const optionalParam = normalized.params.find((param) => param.optional)
+  const fullVariant: PathVariant = {
+    path: normalized.path,
+    params: normalized.params.map((param) => ({ ...param, optional: false })),
+  }
+  if (!optionalParam) return [fullVariant]
+  const placeholder = `/{${optionalParam.name}}`
+  if (!normalized.path.endsWith(placeholder)) return [fullVariant]
+  const basePath = normalized.path.slice(0, -placeholder.length) || '/'
+  return [fullVariant, { path: basePath, params: required, omittedParam: optionalParam.name }]
+}
+
 function unwrap(schema?: ZodTypeAny): {
   schema: ZodTypeAny | undefined
   optional: boolean
@@ -681,14 +701,14 @@ function buildParameters(
 
   if (location === 'path' && pathParamNames && pathParamNames.length) {
     const merged = mergePathParamSchemas(schema, pathParamNames)
-    for (const { name, schema: paramSchema, optional } of merged) {
+    for (const { name, schema: paramSchema } of merged) {
       const jsonSchema = zodToJsonSchema(paramSchema)
       const example = generateExample(paramSchema)
       const description = extractZodDescription(paramSchema)
       params.push({
         name,
         in: 'path',
-        required: !optional,
+        required: true,
         schema: jsonSchema ?? { type: 'string' },
         example,
         ...(description ? { description } : {}),
@@ -738,7 +758,7 @@ function buildParameters(
 }
 
 function mergePathParamSchemas(schema: ZodTypeAny | undefined, params: PathParamInfo[]) {
-  const merged: Array<{ name: string; schema: ZodTypeAny | undefined; optional: boolean }> = []
+  const merged: Array<{ name: string; schema: ZodTypeAny | undefined }> = []
   const map: Record<string, ZodTypeAny> = {}
   if (schema) {
     const { schema: unwrapped } = unwrap(schema)
@@ -753,7 +773,6 @@ function mergePathParamSchemas(schema: ZodTypeAny | undefined, params: PathParam
     merged.push({
       name: param.name,
       schema: map[param.name],
-      optional: !!param.optional,
     })
   }
   return merged
@@ -1051,6 +1070,7 @@ export function buildOpenApiDocument(modules: Module[], options: OpenApiDocument
 
   const includeAccessControlMetadata = options.includeAccessControlMetadata !== false
   const tags = new Map<string, string | undefined>()
+  const derivedOperations = new Set<string>()
 
   for (const moduleEntry of modules) {
     const defaultTag = moduleEntry.info?.title ?? toTitle(moduleEntry.id)
@@ -1060,85 +1080,94 @@ export function buildOpenApiDocument(modules: Module[], options: OpenApiDocument
     for (const api of apis) {
       const routeDoc = collectRouteDoc(api, moduleEntry.id)
       const moduleTag = routeDoc?.tag ?? defaultTag
-      const normalized = normalizePath((api as any).path ?? (api as any).path ?? '')
-      const pathKey = normalized.path
-      if (!doc.paths[pathKey]) doc.paths[pathKey] = {}
       const availableMethods: HttpMethod[] =
         'handlers' in api
           ? HTTP_METHODS.filter((method) => typeof (api as ModuleApiRouteFile).handlers?.[method] === 'function')
           : [api.method as HttpMethod]
 
-      for (const method of availableMethods) {
-        const methodLower = method.toLowerCase() as Lowercase<HttpMethod>
-        const existing = doc.paths[pathKey][methodLower]
-        if (existing) continue
-
-        const metadata = 'handlers' in api ? (api as ModuleApiRouteFile).metadata?.[method] : undefined
-        const methodDoc = routeDoc?.methods?.[method]
-        const summary = methodDoc?.summary ?? routeDoc?.summary ?? `${method} ${pathKey}`
-        const baseDescription = methodDoc?.description ?? routeDoc?.description
-        const meta = metadata && typeof metadata === 'object' ? (metadata as Record<string, unknown>) : undefined
-        const requireFeatures = Array.isArray(meta?.['requireFeatures'])
-          ? (meta!['requireFeatures'] as string[])
-          : undefined
-        const requireRoles = Array.isArray(meta?.['requireRoles'])
-          ? (meta!['requireRoles'] as string[])
-          : undefined
-        const requireAuth = meta?.['requireAuth'] === true
-        const descriptionParts: string[] = []
-        if (baseDescription) descriptionParts.push(baseDescription)
-        if (includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length) {
-          descriptionParts.push(`Requires features: ${requireFeatures.join(', ')}`)
-        }
-        if (includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length) {
-          descriptionParts.push(`Requires roles: ${requireRoles.join(', ')}`)
-        }
+      for (const normalized of expandOptionalPathParams(normalizePath((api as any).path ?? ''))) {
+        const pathKey = normalized.path
+        if (!doc.paths[pathKey]) doc.paths[pathKey] = {}
+
+        for (const method of availableMethods) {
+          const methodLower = method.toLowerCase() as Lowercase<HttpMethod>
+          const operationKey = `${methodLower} ${pathKey}`
+          const existing = doc.paths[pathKey][methodLower]
+          if (existing && (normalized.omittedParam || !derivedOperations.has(operationKey))) continue
+          if (normalized.omittedParam) derivedOperations.add(operationKey)
+          else derivedOperations.delete(operationKey)
+
+          const metadata = 'handlers' in api ? (api as ModuleApiRouteFile).metadata?.[method] : undefined
+          const methodDoc = routeDoc?.methods?.[method]
+          const summary = methodDoc?.summary ?? routeDoc?.summary ?? `${method} ${pathKey}`
+          const baseDescription = methodDoc?.description ?? routeDoc?.description
+          const meta = metadata && typeof metadata === 'object' ? (metadata as Record<string, unknown>) : undefined
+          const requireFeatures = Array.isArray(meta?.['requireFeatures'])
+            ? (meta!['requireFeatures'] as string[])
+            : undefined
+          const requireRoles = Array.isArray(meta?.['requireRoles'])
+            ? (meta!['requireRoles'] as string[])
+            : undefined
+          const requireAuth = meta?.['requireAuth'] === true
+          const descriptionParts: string[] = []
+          if (baseDescription) descriptionParts.push(baseDescription)
+          if (includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length) {
+            descriptionParts.push(`Requires features: ${requireFeatures.join(', ')}`)
+          }
+          if (includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length) {
+            descriptionParts.push(`Requires roles: ${requireRoles.join(', ')}`)
+          }
 
-        const querySchema = methodDoc?.query
-        const pathSchema = methodDoc?.pathParams ?? routeDoc?.pathParams
-        const headerSchema = methodDoc?.headers
-        const requestBody = methodDoc?.requestBody
-        const examples = collectExamples(querySchema, requestBody?.schema, pathSchema, headerSchema, metadata)
-        const curlSample = buildCurlSample(
-          method,
-          pathKey,
-          normalized.params,
-          examples,
-          options.baseUrlForExamples ?? 'https://api.open-mercato.local',
-          metadata,
-          requestBody
-        )
-
-        doc.paths[pathKey][methodLower] = {
-          operationId: methodDoc?.operationId ?? resolveOperationId(moduleEntry.id, pathKey, method),
-          summary,
-          description: descriptionParts.length ? descriptionParts.join('\n\n') : undefined,
-          tags: methodDoc?.tags ?? (moduleTag ? [moduleTag] : undefined),
-          deprecated: methodDoc?.deprecated,
-          externalDocs: methodDoc?.externalDocs,
-          parameters: [
-            ...buildParameters(pathSchema, 'path', normalized.params),
-            ...buildParameters(querySchema, 'query'),
-            ...buildParameters(headerSchema, 'header'),
-          ].filter(Boolean),
-          requestBody: buildRequestBody(requestBody),
-          responses: buildResponses(method, methodDoc?.responses, methodDoc?.errors, metadata),
-          security: buildSecurity(metadata, methodDoc, options.defaultSecurity),
-          'x-codeSamples': methodDoc?.codeSamples ?? [
-            {
-              lang: 'curl',
-              label: 'cURL',
-              source: curlSample,
-            },
-          ],
-          ...(includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length
-            ? { 'x-require-features': requireFeatures }
-            : {}),
-          ...(includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length
-            ? { 'x-require-roles': requireRoles }
-            : {}),
-          ...(requireAuth ? { 'x-require-auth': true } : {}),
-          ...(methodDoc?.extensions ?? {}),
+          const querySchema = methodDoc?.query
+          const pathSchema = methodDoc?.pathParams ?? routeDoc?.pathParams
+          const headerSchema = methodDoc?.headers
+          const requestBody = methodDoc?.requestBody
+          const examples = collectExamples(querySchema, requestBody?.schema, pathSchema, headerSchema, metadata)
+          const curlSample = buildCurlSample(
+            method,
+            pathKey,
+            normalized.params,
+            examples,
+            options.baseUrlForExamples ?? 'https://api.open-mercato.local',
+            metadata,
+            requestBody
+          )
+
+          doc.paths[pathKey][methodLower] = {
+            operationId: methodDoc?.operationId
+              ? normalized.omittedParam
+                ? `${methodDoc.operationId}_without_${normalizeOperationIdSegment(normalized.omittedParam)}`
+                : methodDoc.operationId
+              : resolveOperationId(moduleEntry.id, pathKey, method),
+            summary,
+            description: descriptionParts.length ? descriptionParts.join('\n\n') : undefined,
+            tags: methodDoc?.tags ?? (moduleTag ? [moduleTag] : undefined),
+            deprecated: methodDoc?.deprecated,
+            externalDocs: methodDoc?.externalDocs,
+            parameters: [
+              ...buildParameters(pathSchema, 'path', normalized.params),
+              ...buildParameters(querySchema, 'query'),
+              ...buildParameters(headerSchema, 'header'),
+            ].filter(Boolean),
+            requestBody: buildRequestBody(requestBody),
+            responses: buildResponses(method, methodDoc?.responses, methodDoc?.errors, metadata),
+            security: buildSecurity(metadata, methodDoc, options.defaultSecurity),
+            'x-codeSamples': methodDoc?.codeSamples ?? [
+              {
+                lang: 'curl',
+                label: 'cURL',
+                source: curlSample,
+              },
+            ],
+            ...(includeAccessControlMetadata && Array.isArray(requireFeatures) && requireFeatures.length
+              ? { 'x-require-features': requireFeatures }
+              : {}),
+            ...(includeAccessControlMetadata && Array.isArray(requireRoles) && requireRoles.length
+              ? { 'x-require-roles': requireRoles }
+              : {}),
+            ...(requireAuth ? { 'x-require-auth': true } : {}),
+            ...(methodDoc?.extensions ?? {}),
+          }
         }
       }
     }

package/src/modules/registry.ts

@@ -178,6 +178,11 @@ export type ApiRouteManifestEntry = {
 export type ModuleCli = {
   command: string
   run: (argv: string[]) => Promise<void> | void
+  // Usage text printed by the `mercato` dispatcher when the command is invoked with --help/-h.
+  help?: string
+  // Set when the command parses --help/-h itself; the dispatcher then forwards the flag
+  // instead of intercepting it, so the command can print its own richer usage text.
+  handlesHelp?: boolean
 }
 
 export type ModuleSubscriber = {