@open-mercato/shared 0.9.1-develop.7477.1.64ba865101 → 0.9.1-develop.7497.1.543ea44c40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.9.1-develop.7477.1.64ba865101",
+  "version": "0.9.1-develop.7497.1.543ea44c40",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -121,7 +121,7 @@
     "@mikro-orm/core": "^7.1.14",
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/cache": "0.9.1-develop.7477.1.64ba865101",
+    "@open-mercato/cache": "0.9.1-develop.7497.1.543ea44c40",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

package/src/lib/bootstrap/__tests__/dynamicLoader.appDi.test.ts

@@ -91,9 +91,9 @@ function writeCompiledPair(
   fs.writeFileSync(compiledPath, source.compiled)
   const sourceRelativePath = path.relative(appRoot, sourcePath).split(path.sep).join('/')
   fs.writeFileSync(`${compiledPath}.cache.json`, JSON.stringify({
-    version: 4,
+    version: 5,
     inputHash: hash(JSON.stringify({
-      version: 4,
+      version: 5,
       sourceHash: hash(source.ts),
       tsconfigHashes: {
         'tsconfig.json': hash(APP_TSCONFIG),

package/src/lib/bootstrap/__tests__/dynamicLoader.appModuleOverrides.test.ts

@@ -132,9 +132,9 @@ function writeCompiledPair(
   fs.writeFileSync(compiledPath, source.compiled)
   const sourceRelativePath = path.relative(appRoot, sourcePath).split(path.sep).join('/')
   fs.writeFileSync(`${compiledPath}.cache.json`, JSON.stringify({
-    version: 4,
+    version: 5,
     inputHash: hash(JSON.stringify({
-      version: 4,
+      version: 5,
       sourceHash: hash(source.ts),
       tsconfigHashes: {
         'tsconfig.json': hash(APP_TSCONFIG),

package/src/lib/bootstrap/__tests__/dynamicLoader.cacheRecovery.test.ts

@@ -77,7 +77,7 @@ function writeGeneratedModule(generatedDir: string, baseName: string, source: {
 function writeCompiledSibling(generatedDir: string, baseName: string, compiled: string) {
   const source = fs.readFileSync(path.join(generatedDir, `${baseName}.ts`), 'utf8')
   const inputHash = hash(JSON.stringify({
-    version: 4,
+    version: 5,
     sourceHash: hash(source),
     tsconfigHashes: {
       'tsconfig.json': hash(APP_TSCONFIG),
@@ -90,7 +90,7 @@ function writeCompiledSibling(generatedDir: string, baseName: string, compiled:
   const compiledPath = path.join(generatedDir, `${baseName}.mjs`)
   fs.writeFileSync(compiledPath, compiled)
   fs.writeFileSync(`${compiledPath}.cache.json`, JSON.stringify({
-    version: 4,
+    version: 5,
     inputHash,
     outputHash: hash(compiled),
     dependencies: {

package/src/lib/bootstrap/__tests__/dynamicLoader.commandInterceptors.test.ts

@@ -77,9 +77,9 @@ function writeGeneratedModule(generatedDir: string, baseName: string, source: {
   fs.writeFileSync(sourcePath, source.ts)
   fs.writeFileSync(compiledPath, source.compiled)
   fs.writeFileSync(`${compiledPath}.cache.json`, JSON.stringify({
-    version: 4,
+    version: 5,
     inputHash: hash(JSON.stringify({
-      version: 4,
+      version: 5,
       sourceHash: hash(source.ts),
       tsconfigHashes: {
         'tsconfig.json': hash(APP_TSCONFIG),

package/src/lib/bootstrap/__tests__/dynamicLoader.externalSubpath.test.ts

@@ -0,0 +1,141 @@
+/**
+ * @jest-environment node
+ *
+ * The CLI bundle externalizes every bare package import. Node's ESM resolver only maps an
+ * extensionless subpath such as `next/link` when the package publishes an `exports` map; for a
+ * legacy package (no `exports`, like `next`) it requires the file extension and the bundle
+ * fails with ERR_MODULE_NOT_FOUND (#6993). The external plugin therefore rewrites such
+ * subpaths to the file `require.resolve` finds, and leaves everything else untouched.
+ */
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { compileAppSourceFile, createCliBundlePlugins } from '../dynamicLoader'
+
+function writePackage(appRoot: string, name: string, manifest: Record<string, unknown>, files: Record<string, string>) {
+  const packageDir = path.join(appRoot, 'node_modules', ...name.split('/'))
+  fs.mkdirSync(packageDir, { recursive: true })
+  fs.writeFileSync(path.join(packageDir, 'package.json'), JSON.stringify({ name, version: '1.0.0', ...manifest }))
+  for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path.join(packageDir, relativePath)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, content)
+  }
+}
+
+async function bundleWithCliPlugins(appRoot: string, source: string): Promise<{ outfile: string; output: string }> {
+  const esbuild = await import('esbuild')
+  const generatedDir = path.join(appRoot, '.mercato', 'generated')
+  fs.mkdirSync(generatedDir, { recursive: true })
+  const entry = path.join(generatedDir, 'entry.ts')
+  fs.writeFileSync(entry, source)
+  const outfile = path.join(generatedDir, 'entry.mjs')
+  await esbuild.build({
+    entryPoints: [entry],
+    outfile,
+    absWorkingDir: appRoot,
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node18',
+    plugins: createCliBundlePlugins(appRoot),
+  })
+  return { outfile, output: fs.readFileSync(outfile, 'utf8') }
+}
+
+describe('createCliBundlePlugins — externalized package subpaths', () => {
+  let appRoot: string
+
+  beforeEach(() => {
+    appRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'om-external-subpath-')))
+    fs.writeFileSync(path.join(appRoot, 'package.json'), JSON.stringify({ name: 'app', type: 'module' }))
+    writePackage(appRoot, 'legacy-pkg', { main: 'index.js' }, {
+      'index.js': "module.exports = 'legacy-root'\n",
+      'link.js': "module.exports = 'legacy-link'\n",
+      'dist/nested/index.js': "module.exports = 'legacy-nested'\n",
+    })
+    writePackage(appRoot, '@scope/legacy-scoped', {}, {
+      'tools.js': "module.exports = 'scoped-tools'\n",
+    })
+    writePackage(appRoot, 'exports-pkg', { exports: { './feature': './lib/feature.js' } }, {
+      'lib/feature.js': "module.exports = 'exports-feature'\n",
+    })
+  })
+
+  afterEach(() => {
+    fs.rmSync(appRoot, { recursive: true, force: true })
+  })
+
+  it('appends the resolved file to extensionless subpaths of packages without an exports map', async () => {
+    const { output } = await bundleWithCliPlugins(appRoot, [
+      "import link from 'legacy-pkg/link'",
+      "import nested from 'legacy-pkg/dist/nested'",
+      "import tools from '@scope/legacy-scoped/tools'",
+      'export const values = [link, nested, tools]',
+      '',
+    ].join('\n'))
+
+    expect(output).toContain('"legacy-pkg/link.js"')
+    expect(output).toContain('"legacy-pkg/dist/nested/index.js"')
+    expect(output).toContain('"@scope/legacy-scoped/tools.js"')
+  })
+
+  it('keeps package roots, exports-mapped subpaths, builtins and unresolvable specifiers unchanged', async () => {
+    const { output } = await bundleWithCliPlugins(appRoot, [
+      "import root from 'legacy-pkg'",
+      "import feature from 'exports-pkg/feature'",
+      "import explicit from 'legacy-pkg/link.js'",
+      "import { readFile } from 'fs/promises'",
+      "import missing from 'missing-pkg/sub'",
+      'export const values = [root, feature, explicit, readFile, missing]',
+      '',
+    ].join('\n'))
+
+    expect(output).toContain('"legacy-pkg"')
+    expect(output).toContain('"exports-pkg/feature"')
+    expect(output).toContain('"legacy-pkg/link.js"')
+    expect(output).toContain('"fs/promises"')
+    expect(output).toContain('"missing-pkg/sub"')
+  })
+
+  it('produces a bundle Node ESM can load', async () => {
+    const { outfile } = await bundleWithCliPlugins(appRoot, [
+      "import link from 'legacy-pkg/link'",
+      "import feature from 'exports-pkg/feature'",
+      'console.log(JSON.stringify([link, feature]))',
+      '',
+    ].join('\n'))
+
+    const result = spawnSync(process.execPath, [outfile], { encoding: 'utf8' })
+
+    expect(result.stderr).not.toContain('ERR_MODULE_NOT_FOUND')
+    expect(result.status).toBe(0)
+    expect(JSON.parse(result.stdout.trim())).toEqual(['legacy-link', 'exports-feature'])
+  })
+
+  it('records the rewritten package manifest so a package upgrade invalidates the cached bundle', async () => {
+    fs.writeFileSync(path.join(appRoot, 'tsconfig.json'), JSON.stringify({ compilerOptions: { target: 'ES2022' } }))
+    const generatedDir = path.join(appRoot, '.mercato', 'generated')
+    fs.mkdirSync(generatedDir, { recursive: true })
+    const entry = path.join(generatedDir, 'registry.generated.ts')
+    fs.writeFileSync(entry, "import link from 'legacy-pkg/link'\nexport const value = link\n")
+    const outFile = path.join(generatedDir, 'registry.generated.mjs')
+
+    await compileAppSourceFile(entry, { appRoot, outFile })
+    const metadata = JSON.parse(fs.readFileSync(`${outFile}.cache.json`, 'utf8')) as {
+      dependencies: Record<string, string>
+    }
+    expect(Object.keys(metadata.dependencies)).toContain('node_modules/legacy-pkg/package.json')
+
+    const firstOutputMtime = fs.statSync(outFile).mtimeMs
+    await compileAppSourceFile(entry, { appRoot, outFile })
+    expect(fs.statSync(outFile).mtimeMs).toBe(firstOutputMtime)
+
+    writePackage(appRoot, 'legacy-pkg', { exports: { './link': './link.js' } }, {})
+    await compileAppSourceFile(entry, { appRoot, outFile })
+    expect(fs.readFileSync(outFile, 'utf8')).toContain('"legacy-pkg/link"')
+    expect(fs.readFileSync(outFile, 'utf8')).not.toContain('"legacy-pkg/link.js"')
+  })
+})

package/src/lib/bootstrap/__tests__/dynamicLoader.tsconfig.test.ts

@@ -133,7 +133,7 @@ describe('dynamic loader app tsconfig and content-addressed cache', () => {
     loadBootstrapDataInNode(appRoot)
     const after = readCacheMetadata(appRoot, 'entities')
 
-    expect(after.version).toBe(4)
+    expect(after.version).toBe(5)
     expect(after.inputHash).not.toBe(before.inputHash)
   })
 
@@ -287,6 +287,6 @@ describe('dynamic loader app tsconfig and content-addressed cache', () => {
 
     loadBootstrapDataInNode(appRoot)
 
-    expect(readCacheMetadata(appRoot, 'entities').version).toBe(4)
+    expect(readCacheMetadata(appRoot, 'entities').version).toBe(5)
   })
 })

package/src/lib/bootstrap/dynamicLoader.ts

@@ -16,7 +16,7 @@ import { CLIENT_ONLY_STUB_NAMESPACE, createClientOnlyStubPlugin } from './client
 import path from 'node:path'
 import fs from 'node:fs'
 import crypto from 'node:crypto'
-import { createRequire } from 'node:module'
+import { createRequire, isBuiltin } from 'node:module'
 import { pathToFileURL } from 'node:url'
 
 let activeBootstrapLoads = 0
@@ -77,6 +77,44 @@ class GeneratedFileNotFoundError extends Error {
   }
 }
 
+function splitBareSpecifier(specifier: string): { packageName: string; subpath: string } | null {
+  const segments = specifier.split('/')
+  const nameLength = specifier.startsWith('@') ? 2 : 1
+  if (segments.length <= nameLength || segments.slice(0, nameLength).some((segment) => !segment)) return null
+  return {
+    packageName: segments.slice(0, nameLength).join('/'),
+    subpath: segments.slice(nameLength).join('/'),
+  }
+}
+
+/**
+ * Rewrites an externalized `pkg/subpath` specifier to the file Node's ESM resolver can load
+ * when `pkg` publishes no `exports` map (#6993). Builtins, packages with `exports`, subpaths
+ * that already carry an extension and anything that fails to resolve keep the original
+ * specifier, so the bundle never gets worse than before.
+ */
+function rewriteLegacySubpathSpecifier(
+  specifier: string,
+  appRequire: NodeRequire,
+  onRewrite: (manifestPath: string) => void,
+): string {
+  if (isBuiltin(specifier)) return specifier
+  const parts = splitBareSpecifier(specifier)
+  if (!parts || path.posix.extname(parts.subpath)) return specifier
+  try {
+    const manifestPath = appRequire.resolve(`${parts.packageName}/package.json`)
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as { exports?: unknown }
+    if (manifest.exports != null) return specifier
+    const resolvedFile = appRequire.resolve(specifier)
+    const relativeFile = path.relative(path.dirname(manifestPath), resolvedFile)
+    if (!relativeFile || relativeFile.startsWith('..') || path.isAbsolute(relativeFile)) return specifier
+    onRewrite(manifestPath)
+    return `${parts.packageName}/${relativeFile.split(path.sep).join('/')}`
+  } catch {
+    return specifier
+  }
+}
+
 /**
  * esbuild plugins for the CLI bundle, in resolution order. The client-only stub must come
  * first so it wins over the alias and external plugins for `*.client` dynamic imports.
@@ -85,7 +123,10 @@ class GeneratedFileNotFoundError extends Error {
  * `createClientOnlyStubPlugin` in isolation stays green if the plugin is dropped from this
  * list, which would silently reintroduce #4623.
  */
-export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugin[] {
+export function createCliBundlePlugins(
+  appRoot: string,
+  options: { onLegacySubpathRewrite?: (manifestPath: string) => void } = {},
+): import('esbuild').Plugin[] {
   // Plugin to resolve the @/ alias the way the app tsconfig maps it:
   // `@/.mercato/*` to the app root, every other `@/*` to the app's src/ directory.
   const aliasPlugin: import('esbuild').Plugin = {
@@ -113,6 +154,19 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
     },
   }
 
+  // Node's ESM resolver only maps an extensionless package subpath (`next/link`) when the
+  // package publishes an `exports` map; legacy packages need the real file path instead.
+  const appRequire = createRequire(path.join(appRoot, 'package.json'))
+  const externalSpecifierCache = new Map<string, string>()
+  const onLegacySubpathRewrite = options.onLegacySubpathRewrite ?? (() => undefined)
+  const resolveExternalSpecifier = (specifier: string): string => {
+    const cached = externalSpecifierCache.get(specifier)
+    if (cached !== undefined) return cached
+    const resolved = rewriteLegacySubpathSpecifier(specifier, appRequire, onLegacySubpathRewrite)
+    externalSpecifierCache.set(specifier, resolved)
+    return resolved
+  }
+
   // Plugin to mark non-JSON package imports as external
   const externalNonJsonPlugin: import('esbuild').Plugin = {
     name: 'external-non-json',
@@ -129,7 +183,7 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
           return null // Let esbuild handle it
         }
         // Otherwise mark as external
-        return { path: args.path, external: true }
+        return { path: resolveExternalSpecifier(args.path), external: true }
       })
     },
   }
@@ -137,7 +191,7 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
   return [createClientOnlyStubPlugin(), aliasPlugin, externalNonJsonPlugin]
 }
 
-const DYNAMIC_LOADER_CACHE_VERSION = 4
+const DYNAMIC_LOADER_CACHE_VERSION = 5
 
 type DynamicLoaderCacheMetadata = {
   version: number
@@ -433,6 +487,7 @@ async function compileAppSourceFileWithActiveEsbuild(
   // Dynamically import esbuild only when needed
   const esbuild = await getEsbuildRuntime()
 
+  const rewrittenPackageManifests = new Set<string>()
   // Use esbuild.build with bundling to handle JSON imports
   const result = await esbuild.build({
     entryPoints: [tsPath],
@@ -444,7 +499,9 @@ async function compileAppSourceFileWithActiveEsbuild(
     platform: 'node',
     target: 'node18',
     tsconfig: appTsconfig,
-    plugins: createCliBundlePlugins(appRoot),
+    plugins: createCliBundlePlugins(appRoot, {
+      onLegacySubpathRewrite: (manifestPath) => rewrittenPackageManifests.add(manifestPath),
+    }),
     // Allow JSON imports
     loader: { '.json': 'json' },
   })
@@ -455,6 +512,7 @@ async function compileAppSourceFileWithActiveEsbuild(
     dependencies: {
       ...collectDependencyHashes(appRoot, result.metafile.inputs),
       ...hashFilesRelativeTo(appRoot, tsconfigPaths),
+      ...hashFilesRelativeTo(appRoot, [...rewrittenPackageManifests]),
     },
   }
   fs.writeFileSync(metadataPath, JSON.stringify(metadata))

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([])
+  })
+})