@open-mercato/shared 0.7.1-develop.7123.1.25365e718d → 0.7.1-develop.7130.1.fef2396fd8

package/src/lib/db/__tests__/duplicateEntityClassNames.test.ts

@@ -0,0 +1,172 @@
+import {
+  DUPLICATE_ENTITY_CLASS_NAMES_REASON,
+  DUPLICATE_ENTITY_CLASS_NAMES_REMEDIATION,
+  findDuplicateEntityClassNames,
+  formatDuplicateEntityClassNamesWarning,
+  toDuplicateEntityClassNameFields,
+} from '../duplicateEntityClassNames'
+
+describe('findDuplicateEntityClassNames', () => {
+  it('reports nothing for an empty or single-entry list', () => {
+    expect(findDuplicateEntityClassNames([])).toEqual([])
+    expect(findDuplicateEntityClassNames([{ className: 'Invoice', moduleId: 'billing' }])).toEqual([])
+  })
+
+  it('reports nothing when class names differ', () => {
+    const groups = findDuplicateEntityClassNames([
+      { className: 'Invoice', moduleId: 'billing' },
+      { className: 'Ledger', moduleId: 'subscriptions' },
+    ])
+
+    expect(groups).toEqual([])
+  })
+
+  it('reports a name declared by two modules', () => {
+    const groups = findDuplicateEntityClassNames([
+      { className: 'Invoice', moduleId: 'billing', sourcePath: 'modules/billing/data/entities.ts' },
+      { className: 'Invoice', moduleId: 'subscriptions', sourcePath: 'modules/subscriptions/data/entities.ts' },
+    ])
+
+    expect(groups).toEqual([
+      {
+        className: 'Invoice',
+        sources: [
+          { moduleId: 'billing', sourcePath: 'modules/billing/data/entities.ts' },
+          { moduleId: 'subscriptions', sourcePath: 'modules/subscriptions/data/entities.ts' },
+        ],
+      },
+    ])
+  })
+
+  it('treats identical module and path as the same class, not a collision', () => {
+    const groups = findDuplicateEntityClassNames([
+      { className: 'Invoice', moduleId: 'billing', sourcePath: 'modules/billing/data/entities.ts' },
+      { className: 'Invoice', moduleId: 'billing', sourcePath: 'modules/billing/data/entities.ts' },
+    ])
+
+    expect(groups).toEqual([])
+  })
+
+  it('treats a shared target as the same class reached twice', () => {
+    const target = class Invoice {}
+    const groups = findDuplicateEntityClassNames([
+      { className: 'Invoice', moduleId: 'billing', target },
+      { className: 'Invoice', moduleId: 'subscriptions', target },
+    ])
+
+    expect(groups).toEqual([])
+  })
+
+  it('collects three-way collisions and multiple names in one pass', () => {
+    const groups = findDuplicateEntityClassNames([
+      { className: 'Invoice', moduleId: 'billing' },
+      { className: 'Ledger', moduleId: 'billing' },
+      { className: 'Invoice', moduleId: 'subscriptions' },
+      { className: 'Ledger', moduleId: 'subscriptions' },
+      { className: 'Ledger', moduleId: 'reporting' },
+    ])
+
+    expect(groups.map((group) => group.className)).toEqual(['Invoice', 'Ledger'])
+    expect(groups[1].sources.map((source) => source.moduleId)).toEqual(['billing', 'subscriptions', 'reporting'])
+  })
+
+  it('keeps unidentifiable entries distinct so a collision fails open', () => {
+    // Neither entry names a module, a file, or a class, so nothing distinguishes them.
+    // Collapsing them into one bucket would hide a genuine collision.
+    const groups = findDuplicateEntityClassNames([{ className: 'Invoice' }, { className: 'Invoice' }])
+
+    expect(groups).toHaveLength(1)
+    expect(groups[0].sources).toHaveLength(2)
+  })
+
+  it('skips entries without a class name', () => {
+    expect(findDuplicateEntityClassNames([{ className: '' }, { className: '' }])).toEqual([])
+  })
+})
+
+describe('formatDuplicateEntityClassNamesWarning', () => {
+  it('names the class, the modules and the source files', () => {
+    const message = formatDuplicateEntityClassNamesWarning([
+      {
+        className: 'Invoice',
+        sources: [
+          { moduleId: 'billing', sourcePath: '/repo/modules/billing/data/entities.ts' },
+          { moduleId: 'subscriptions', sourcePath: '/repo/modules/subscriptions/data/entities.ts' },
+        ],
+      },
+    ])
+
+    expect(message).toContain('Duplicate entity class name(s) defined by more than one enabled module: "Invoice".')
+    expect(message).toContain('  Invoice')
+    expect(message).toContain('    - billing (/repo/modules/billing/data/entities.ts)')
+    expect(message).toContain('    - subscriptions (/repo/modules/subscriptions/data/entities.ts)')
+    expect(message).toContain('Rename all but one of the colliding classes')
+  })
+
+  it('lists every colliding name in one message', () => {
+    const message = formatDuplicateEntityClassNamesWarning([
+      { className: 'Invoice', sources: [{ moduleId: 'a' }, { moduleId: 'b' }] },
+      { className: 'Ledger', sources: [{ moduleId: 'a' }, { moduleId: 'b' }] },
+    ])
+
+    expect(message).toContain('"Invoice", "Ledger"')
+    expect(message).toContain('  Invoice')
+    expect(message).toContain('  Ledger')
+  })
+
+  it('degrades gracefully when the module id or path is unavailable', () => {
+    const message = formatDuplicateEntityClassNamesWarning([
+      {
+        className: 'Invoice',
+        sources: [
+          { moduleId: undefined, sourcePath: '/repo/a/entities.ts' },
+          { moduleId: undefined, sourcePath: undefined },
+        ],
+      },
+    ])
+
+    expect(message).toContain('    - /repo/a/entities.ts')
+    expect(message).toContain('    - unknown module')
+  })
+
+  it('omits a source path that degraded to a bare class name', () => {
+    // MikroORM derives the decorator path by parsing a stack trace and falls back to
+    // the class name when that parse fails.
+    const message = formatDuplicateEntityClassNamesWarning([
+      { className: 'Invoice', sources: [{ moduleId: 'billing', sourcePath: 'Invoice' }] },
+    ])
+
+    const sourceLine = message.split('\n').find((line) => line.startsWith('    - '))
+    expect(sourceLine).toBe('    - billing')
+  })
+})
+
+describe('toDuplicateEntityClassNameFields', () => {
+  // The runtime surface logs through the structured facade, where the message must stay
+  // constant and every dynamic value has to be a queryable field.
+  it('carries the collisions as fields beside the constant explanation', () => {
+    const groups = findDuplicateEntityClassNames([
+      { className: 'Invoice', moduleId: 'billing', sourcePath: '/repo/modules/billing/data/entities.ts' },
+      { className: 'Invoice', moduleId: 'subscriptions', sourcePath: '/repo/modules/subscriptions/data/entities.ts' },
+    ])
+
+    expect(toDuplicateEntityClassNameFields(groups)).toEqual({
+      classNames: ['Invoice'],
+      duplicates: [
+        {
+          className: 'Invoice',
+          sources: [
+            { moduleId: 'billing', sourcePath: '/repo/modules/billing/data/entities.ts' },
+            { moduleId: 'subscriptions', sourcePath: '/repo/modules/subscriptions/data/entities.ts' },
+          ],
+        },
+      ],
+      reason: DUPLICATE_ENTITY_CLASS_NAMES_REASON,
+      remediation: DUPLICATE_ENTITY_CLASS_NAMES_REMEDIATION,
+    })
+  })
+
+  it('stays empty for no collisions', () => {
+    expect(toDuplicateEntityClassNameFields([]).classNames).toEqual([])
+  })
+})

package/src/lib/db/__tests__/duplicateEntityClassNamesExport.test.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const PACKAGE_ROOT = join(__dirname, '..', '..', '..', '..')
+const SUBPATH = './lib/db/duplicateEntityClassNames'
+
+type ExportTarget = { types?: string | string[]; default?: string }
+
+function readExports(): Record<string, ExportTarget | string> {
+  const packageJson = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')) as {
+    exports?: Record<string, ExportTarget | string>
+  }
+  return packageJson.exports ?? {}
+}
+
+/**
+ * Node's subpath resolution: an exact key wins outright, and only when none matches do
+ * the `*` patterns compete on the longest static prefix. `@open-mercato/cli` imports this
+ * subpath across a workspace boundary, and resolvers do not agree on wildcard handling,
+ * so it must not depend on one.
+ */
+function resolveSubpath(exports: Record<string, ExportTarget | string>, subpath: string): string | null {
+  if (Object.prototype.hasOwnProperty.call(exports, subpath)) return subpath
+  let best: string | null = null
+  for (const key of Object.keys(exports)) {
+    const star = key.indexOf('*')
+    if (star < 0) continue
+    const prefix = key.slice(0, star)
+    const suffix = key.slice(star + 1)
+    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue
+    if (subpath.length < prefix.length + suffix.length) continue
+    if (!best || prefix.length > best.slice(0, best.indexOf('*')).length) best = key
+  }
+  return best
+}
+
+describe('@open-mercato/shared duplicateEntityClassNames export map', () => {
+  const exports = readExports()
+
+  it('resolves through an explicit entry rather than a wildcard pattern', () => {
+    expect(resolveSubpath(exports, SUBPATH)).toBe(SUBPATH)
+  })
+
+  it('maps types to the source module and default to the built module', () => {
+    expect(exports[SUBPATH]).toEqual({
+      types: './src/lib/db/duplicateEntityClassNames.ts',
+      default: './dist/lib/db/duplicateEntityClassNames.js',
+    })
+  })
+
+  // Both halves of the mapping must exist in a packed package. `default` is produced by
+  // `yarn build:packages`, which the validation gate runs before `yarn test`.
+  it('ships both mapped files', () => {
+    const target = exports[SUBPATH] as ExportTarget
+    expect(existsSync(join(PACKAGE_ROOT, target.types as string))).toBe(true)
+    expect(existsSync(join(PACKAGE_ROOT, target.default as string))).toBe(true)
+  })
+
+  it('keeps the module importable under the mapped default condition', async () => {
+    const target = exports[SUBPATH] as ExportTarget
+    await expect(import(join(PACKAGE_ROOT, target.default as string))).resolves.toBeDefined()
+  })
+})

package/src/lib/db/__tests__/fixtures/invoiceBilling.ts

@@ -0,0 +1,7 @@
+import { Entity, PrimaryKey } from '@mikro-orm/decorators/legacy'
+
+@Entity({ tableName: 'duplicate_entity_fixture_billing' })
+export class Invoice {
+  @PrimaryKey({ type: 'string' })
+  id!: string
+}

package/src/lib/db/__tests__/fixtures/invoiceReporting.ts

@@ -0,0 +1,7 @@
+import { Entity, PrimaryKey } from '@mikro-orm/decorators/legacy'
+
+@Entity({ tableName: 'duplicate_entity_fixture_reporting' })
+export class Invoice {
+  @PrimaryKey({ type: 'string' })
+  id!: string
+}

package/src/lib/db/__tests__/fixtures/invoiceSubscriptions.ts

@@ -0,0 +1,7 @@
+import { Entity, PrimaryKey } from '@mikro-orm/decorators/legacy'
+
+@Entity({ tableName: 'duplicate_entity_fixture_subscriptions' })
+export class Invoice {
+  @PrimaryKey({ type: 'string' })
+  id!: string
+}

package/src/lib/db/__tests__/fixtures/ledgerBilling.ts

@@ -0,0 +1,7 @@
+import { Entity, PrimaryKey } from '@mikro-orm/decorators/legacy'
+
+@Entity({ tableName: 'duplicate_entity_fixture_ledger_billing' })
+export class Ledger {
+  @PrimaryKey({ type: 'string' })
+  id!: string
+}

package/src/lib/db/__tests__/fixtures/ledgerReporting.ts

@@ -0,0 +1,7 @@
+import { Entity, PrimaryKey } from '@mikro-orm/decorators/legacy'
+
+@Entity({ tableName: 'duplicate_entity_fixture_ledger_reporting' })
+export class Ledger {
+  @PrimaryKey({ type: 'string' })
+  id!: string
+}

package/src/lib/db/__tests__/fixtures/ledgerSubscriptions.ts

@@ -0,0 +1,7 @@
+import { Entity, PrimaryKey } from '@mikro-orm/decorators/legacy'
+
+@Entity({ tableName: 'duplicate_entity_fixture_ledger_subscriptions' })
+export class Ledger {
+  @PrimaryKey({ type: 'string' })
+  id!: string
+}

package/src/lib/db/__tests__/registerOrmEntities.duplicates.test.ts

@@ -0,0 +1,164 @@
+import 'reflect-metadata'
+import { MetadataStorage } from '@mikro-orm/core'
+import { Invoice as InvoiceBilling } from './fixtures/invoiceBilling'
+import { Invoice as InvoiceSubscriptions } from './fixtures/invoiceSubscriptions'
+import { Invoice as InvoiceReporting } from './fixtures/invoiceReporting'
+import { Ledger as LedgerBilling } from './fixtures/ledgerBilling'
+import { Ledger as LedgerSubscriptions } from './fixtures/ledgerSubscriptions'
+
+const warn = jest.fn()
+
+jest.mock('../../logger', () => ({
+  createLogger: () => ({
+    child: () => ({ debug: jest.fn(), info: jest.fn(), warn, error: jest.fn() }),
+  }),
+}))
+
+const GLOBAL_ENTITIES_KEY = '__openMercatoOrmEntities__'
+const GLOBAL_REPORTED_KEY = '__openMercatoReportedDuplicateEntityClassNames__'
+
+function readSourcePath(entity: unknown): string {
+  return (entity as Record<symbol, string>)[MetadataStorage.PATH_SYMBOL]
+}
+
+function stampModuleId(entity: unknown, stamp: string): void {
+  Object.defineProperty(entity, 'entityName', {
+    value: stamp,
+    configurable: true,
+    enumerable: false,
+    writable: false,
+  })
+}
+
+describe('registerOrmEntities duplicate class name reporting', () => {
+  const originalEntities = (globalThis as Record<string, unknown>)[GLOBAL_ENTITIES_KEY]
+
+  beforeEach(() => {
+    warn.mockClear()
+    // Collisions are reported once per process; start each case from a clean slate.
+    delete (globalThis as Record<string, unknown>)[GLOBAL_REPORTED_KEY]
+  })
+
+  afterEach(() => {
+    for (const entity of [InvoiceBilling, InvoiceSubscriptions]) {
+      delete (entity as Record<string, unknown>).entityName
+    }
+    if (typeof originalEntities === 'undefined') {
+      delete (globalThis as Record<string, unknown>)[GLOBAL_ENTITIES_KEY]
+      return
+    }
+    ;(globalThis as Record<string, unknown>)[GLOBAL_ENTITIES_KEY] = originalEntities
+  })
+
+  it('warns and still registers when two modules contribute the same class name', async () => {
+    stampModuleId(InvoiceBilling, 'billing.Invoice')
+    stampModuleId(InvoiceSubscriptions, 'subscriptions.Invoice')
+    const entities = [InvoiceBilling, InvoiceSubscriptions]
+    const { registerOrmEntities, getOrmEntities } = await import('../mikro')
+
+    registerOrmEntities(entities)
+
+    expect(warn).toHaveBeenCalledTimes(1)
+    // The structured-logging contract keeps the message constant and the dynamic values
+    // in queryable fields.
+    const [message, fields] = warn.mock.calls[0] as [string, Record<string, unknown>]
+    expect(message).toBe('Duplicate entity class names across enabled modules')
+    expect(fields.classNames).toEqual(['Invoice'])
+    expect(fields.duplicates).toEqual([
+      {
+        className: 'Invoice',
+        sources: [
+          { moduleId: 'billing', sourcePath: readSourcePath(InvoiceBilling) },
+          { moduleId: 'subscriptions', sourcePath: readSourcePath(InvoiceSubscriptions) },
+        ],
+      },
+    ])
+    expect(typeof fields.remediation).toBe('string')
+    // Warning-only by design: registration must still complete.
+    expect(getOrmEntities()).toBe(entities)
+  })
+
+  it('stays silent for a registration with unique class names', async () => {
+    const { registerOrmEntities } = await import('../mikro')
+
+    registerOrmEntities([InvoiceBilling])
+
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('stays silent when the same class is registered twice', async () => {
+    const { registerOrmEntities } = await import('../mikro')
+
+    registerOrmEntities([InvoiceBilling, InvoiceBilling])
+
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('stays silent for non-entity exports that share a name', async () => {
+    const { registerOrmEntities } = await import('../mikro')
+
+    registerOrmEntities([
+      function helper(): void {},
+      function helper(): void {},
+      { name: 'TestEntity' },
+      { name: 'TestEntity' },
+    ])
+
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('reports a standing collision once, not on every HMR re-registration', async () => {
+    stampModuleId(InvoiceBilling, 'billing.Invoice')
+    stampModuleId(InvoiceSubscriptions, 'subscriptions.Invoice')
+    const entities = [InvoiceBilling, InvoiceSubscriptions]
+    const { registerOrmEntities } = await import('../mikro')
+
+    registerOrmEntities(entities)
+    registerOrmEntities(entities)
+    registerOrmEntities(entities)
+
+    expect(warn).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports a newly introduced collision even after an earlier one was reported', async () => {
+    const { registerOrmEntities } = await import('../mikro')
+
+    registerOrmEntities([InvoiceBilling, InvoiceSubscriptions])
+    expect(warn).toHaveBeenCalledTimes(1)
+
+    registerOrmEntities([InvoiceBilling, InvoiceSubscriptions, LedgerBilling, LedgerSubscriptions])
+
+    expect(warn).toHaveBeenCalledTimes(2)
+    // The already-reported name is not repeated.
+    expect(warn.mock.calls[1][1].classNames).toEqual(['Ledger'])
+  })
+
+  it('reports a collision again after it was fixed and reintroduced', async () => {
+    const { registerOrmEntities } = await import('../mikro')
+
+    registerOrmEntities([InvoiceBilling, InvoiceSubscriptions])
+    expect(warn).toHaveBeenCalledTimes(1)
+
+    // The developer renames one of them; the next reload is clean.
+    registerOrmEntities([InvoiceBilling])
+    expect(warn).toHaveBeenCalledTimes(1)
+
+    // Reverting the rename must warn again rather than stay silent forever.
+    registerOrmEntities([InvoiceBilling, InvoiceSubscriptions])
+
+    expect(warn).toHaveBeenCalledTimes(2)
+    expect(warn.mock.calls[1][1].classNames).toEqual(['Invoice'])
+  })
+
+  it('reports again when the same class name starts colliding with a different module', async () => {
+    const { registerOrmEntities } = await import('../mikro')
+
+    registerOrmEntities([InvoiceBilling, InvoiceSubscriptions])
+    expect(warn).toHaveBeenCalledTimes(1)
+
+    registerOrmEntities([InvoiceBilling, InvoiceReporting])
+
+    expect(warn).toHaveBeenCalledTimes(2)
+    expect(warn.mock.calls[1][1].classNames).toEqual(['Invoice'])
+  })
+})

package/src/lib/db/duplicateEntities.ts

@@ -0,0 +1,89 @@
+import { EntitySchema, MetadataStorage } from '@mikro-orm/core'
+import {
+  findDuplicateEntityClassNames,
+  type DuplicateEntityClassNameGroup,
+  type EntityClassNameEntry,
+} from './duplicateEntityClassNames'
+
+/**
+ * Adapts a registered ORM entity array to the dependency-free collision detector in
+ * `./duplicateEntityClassNames`, which explains the underlying MikroORM behaviour.
+ */
+
+type DecoratedEntityClass = {
+  readonly name?: unknown
+  readonly entityName?: unknown
+  readonly [MetadataStorage.PATH_SYMBOL]?: unknown
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/**
+ * `enhanceEntities()` in the generated entity registry stamps `<moduleId>.<ExportName>`
+ * onto every entity export. MikroORM ignores that stamp, but it is the only place the
+ * contributing module id survives to runtime. Module ids may contain dots; the export
+ * name never does, so split on the last one. A class that declares its own `entityName`
+ * keeps it — `enhanceEntities()` never overwrites one — so a declared value containing a
+ * dot yields a bogus module id here; cosmetic in the warning text, and a dot-free value
+ * degrades to `undefined`.
+ */
+function readModuleIdFromStamp(stamp: unknown): string | undefined {
+  const value = readString(stamp)
+  if (!value) return undefined
+  const separator = value.lastIndexOf('.')
+  return separator > 0 ? value.slice(0, separator) : undefined
+}
+
+/**
+ * The registered array holds every function export of each module's entity file, so
+ * plain helper functions travel alongside real entities. Only classes touched by a
+ * MikroORM decorator carry `MetadataStorage.PATH_SYMBOL` as an own property; everything
+ * else is skipped so helpers that happen to share a name are never reported.
+ */
+function toEntityClassNameEntry(value: unknown): EntityClassNameEntry | null {
+  // `enhanceEntities()` in the generated registry keeps only `typeof value === 'function'`
+  // exports, so an EntitySchema a module exports never arrives through it. This branch is
+  // live only for direct callers such as the testing bootstrap — and since the module id
+  // stamp is applied to those same function exports, an EntitySchema carries no module id
+  // and reports by path alone.
+  if (EntitySchema.is(value)) {
+    const className = readString(value.meta?.className)
+    if (!className) return null
+    return { className, sourcePath: readString(value.meta?.path), target: value }
+  }
+  if (typeof value !== 'function') return null
+  if (!Object.prototype.hasOwnProperty.call(value, MetadataStorage.PATH_SYMBOL)) return null
+  const entity = value as DecoratedEntityClass
+  const className = readString(entity.name)
+  if (!className) return null
+  return {
+    className,
+    moduleId: readModuleIdFromStamp(entity.entityName),
+    sourcePath: readString(entity[MetadataStorage.PATH_SYMBOL]),
+    target: value,
+  }
+}
+
+export function collectEntityClassNameEntries(entities: readonly unknown[]): EntityClassNameEntry[] {
+  const entries: EntityClassNameEntry[] = []
+  for (const value of entities) {
+    let entry: EntityClassNameEntry | null = null
+    try {
+      entry = toEntityClassNameEntry(value)
+    } catch {
+      // Reading a name off an exotic export (a throwing getter, a proxy) must not turn
+      // a diagnostic into a boot failure. Skip the value and keep checking the rest.
+      continue
+    }
+    if (entry) entries.push(entry)
+  }
+  return entries
+}
+
+export function findDuplicateRegisteredEntityClassNames(
+  entities: readonly unknown[],
+): DuplicateEntityClassNameGroup[] {
+  return findDuplicateEntityClassNames(collectEntityClassNameEntries(entities))
+}