@open-mercato/cli 0.6.7 → 0.6.8-canary.319.1.5b4be4bc52

package/src/lib/generators/__tests__/module-facts.bc-guard.test.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { extractAllModuleFacts } from '../module-facts'
+import { extractAllModuleFacts, isExactSourceFilePath, renderModuleFactsJson } from '../module-facts'
 import { discoverPackageModuleSources } from '../module-facts-discovery'
 import { createResolver } from '../../resolver'
 
@@ -17,10 +17,131 @@ function isUnique(values: string[]): boolean {
   return values.length === new Set(values).size
 }
 
+const MARKDOWN_LINK_TARGET = /\]\(\.\.\/\.\.\/\.\.\/([^)#]+)(?:#L\d+)?\)/g
+
+function collectLinkTargets(markdown: string): string[] {
+  return [...markdown.matchAll(MARKDOWN_LINK_TARGET)].map((match) => match[1])
+}
+
 describe('module-facts BC resolve guard (T2)', () => {
   const repoRoot = findRepoRoot()
   const sources = discoverPackageModuleSources(createResolver(repoRoot))
-  const { factsByModule } = extractAllModuleFacts({ sources })
+  const extractionStartedAt = process.cpuUsage()
+  const { factsByModule, markdownByModule, frameworkMarkdown } = extractAllModuleFacts({ sources })
+  const extractionCpuUsage = process.cpuUsage(extractionStartedAt)
+  const extractionCpuDurationMs = (extractionCpuUsage.user + extractionCpuUsage.system) / 1_000
+
+  it('emits complete, deterministic extension catalogs for every resolved module', () => {
+    const repeated = extractAllModuleFacts({ sources })
+    expect(renderModuleFactsJson(repeated.factsByModule)).toBe(renderModuleFactsJson(factsByModule))
+    expect(repeated.markdownByModule).toEqual(markdownByModule)
+    expect(repeated.frameworkMarkdown).toBe(frameworkMarkdown)
+    for (const facts of Object.values(factsByModule)) {
+      expect(facts.extensionSurfaces).toBeDefined()
+      expect(facts.extensionSurfaces?.unresolved).toEqual([])
+    }
+  })
+
+  it('keeps generated extension facts within bounded build-time and context budgets', () => {
+    const completeJson = renderModuleFactsJson(factsByModule)
+    const legacyJson = renderModuleFactsJson(Object.fromEntries(
+      Object.entries(factsByModule).map(([moduleId, facts]) => [moduleId, { ...facts, extensionSurfaces: undefined }]),
+    ))
+    const markdownBytes = Object.values(markdownByModule)
+      .reduce((total, markdown) => total + Buffer.byteLength(markdown), Buffer.byteLength(frameworkMarkdown))
+
+    // Budget raised by the bidirectional-topology spec
+    // (2026-08-02-module-facts-extension-activation-and-incoming-index): the
+    // additive `activations`, cross-module `incoming`, and per-contribution
+    // `contributionResolutions` layers add ~210KB of compact references (no
+    // contribution payloads are duplicated). Incoming rows are cross-module only;
+    // resolution rows are required one-per-contribution by the spec's acceptance
+    // criteria and are the dominant term.
+    //
+    // JSON cap raised again by the exact-override-targets spec
+    // (2026-08-02-module-facts-exact-override-targets): the additive per-module
+    // `overrideTargets` project one exact key per real override entry (acl
+    // features, di tokens, subscribers, pages, workers, encryption, widgets,
+    // notifications, cli, setup, ai, interceptors/enrichers, page guards). These
+    // are required exhaustively by the spec's acceptance criteria; targets carry
+    // only compact structured path/key/factRef/source refs (no runtime values or
+    // contribution payloads). The delta cap is unchanged because `overrideTargets`
+    // live in both the complete and legacy renders (only `extensionSurfaces` is
+    // stripped for the legacy comparison).
+    //
+    // JSON cap raised a third time by the uniform provenance index
+    // (2026-08-02-module-facts-source-provenance-and-contract-inventory): every
+    // proven `(kind, id)` now reaches `factSources` (~630KB across the repo), so a
+    // consumer resolves any fact's origin through one lookup. Entries whose
+    // declaration site is already serialized inline (routes, pages, CLI commands,
+    // AI tools/agents, owned contracts, hosts, contributions) emit a typed
+    // `factRef` pointer instead of a duplicated source ref, and `factKey` is
+    // omitted when it equals the entry `id` — so the index costs references, never
+    // copied provenance payloads. The cap also covers the newly reachable
+    // framework-host activations (dashboard/menu/notification contributions now
+    // resolve as bound instead of silently falling back to capability-only).
+    // This is a blow-up detector, not a performance target. It measures CPU time
+    // for a whole-repo extraction, and CPU time for fixed work varies with the
+    // machine: the same extraction measures ~7.3s on a developer workstation and
+    // ~30.0s on a CI runner. At the previous 30s cap CI sat exactly on the line
+    // (an observed failure at 30,052.8ms), so the guard could not tell a genuine
+    // pathological regression from ordinary hardware variance and failed
+    // unrelated PRs at random. 90s keeps it meaningful — a real blow-up here is
+    // multiplicative, not a few percent — while leaving CI roughly 3x headroom.
+    expect(extractionCpuDurationMs).toBeLessThan(90_000)
+    // JSON cap raised a fourth time by the injection-table slot normalization:
+    // `extractInjectionTable` previously did `if (!Array.isArray(entries)) continue`,
+    // silently dropping every string and single-object slot form that
+    // `ModuleInjectionTable` allows. Twelve real contributions across catalog, sales,
+    // wms, staff, integrations and checkout were therefore invisible to every fact
+    // consumer — `integrations` published no contributions at all. Reading them costs
+    // ~28KB, which is the fix working, not drift.
+    expect(Buffer.byteLength(completeJson)).toBeLessThan(3_560_000)
+    expect(Buffer.byteLength(completeJson) - Buffer.byteLength(legacyJson)).toBeLessThan(1_800_000)
+    // Markdown cap raised with the source-link contract: entities, events, ACL
+    // features, DI tokens, search entities, notifications, UMES hosts and UMES
+    // contributions all render a resolved Source cell, and contribution
+    // resolutions render as their own source-linked section.
+    expect(markdownBytes).toBeLessThan(1_550_000)
+  })
+
+  it('links every generated fact to an exact resolvable file, never a directory', () => {
+    const packageLinkRoot = path.join(repoRoot, 'node_modules', '@open-mercato')
+    const canCheckDisk = fs.existsSync(packageLinkRoot)
+    const nonExactTargets = new Set<string>()
+    const unresolvedTargets = new Set<string>()
+    let checkedTargets = 0
+
+    for (const markdown of Object.values(markdownByModule)) {
+      for (const target of collectLinkTargets(markdown)) {
+        checkedTargets += 1
+        if (!isExactSourceFilePath(target)) {
+          nonExactTargets.add(target)
+          continue
+        }
+        if (!canCheckDisk) continue
+        const absolute = path.join(repoRoot, target)
+        if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) unresolvedTargets.add(target)
+      }
+    }
+
+    expect(checkedTargets).toBeGreaterThan(1_000)
+    expect([...nonExactTargets]).toEqual([])
+    expect([...unresolvedTargets]).toEqual([])
+  })
+
+  it('keeps directory-valued provenance readable as plain text', () => {
+    const frameworkHostMarkdowns = Object.values(markdownByModule)
+      .filter((markdown) => markdown.includes('packages/ui/src'))
+    expect(frameworkHostMarkdowns.length).toBeGreaterThan(0)
+    for (const markdown of frameworkHostMarkdowns) {
+      expect(markdown).not.toContain('(../../../packages/ui/src)')
+    }
+    for (const [moduleId, facts] of Object.entries(factsByModule)) {
+      expect(markdownByModule[moduleId]).toContain(`Source root: ${facts.sourceRoot}\n`)
+      expect(markdownByModule[moduleId]).not.toContain(`(../../../${facts.sourceRoot})`)
+    }
+  })
 
   it('discovers a superset of the historical core modules', () => {
     const discovered = new Set(Object.keys(factsByModule))
@@ -30,11 +151,27 @@ describe('module-facts BC resolve guard (T2)', () => {
     expect(discovered.size).toBeGreaterThan(9)
   })
 
+  it('keeps factory-built and generated-registry enricher contributions visible', () => {
+    expect(factsByModule.sales.extensionSurfaces?.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: 'sales.catalog-image:sales:sales_quote_line', kind: 'response-enricher' }),
+      expect.objectContaining({ id: 'sales.catalog-image:sales:sales_order_line', kind: 'response-enricher' }),
+    ]))
+    expect(factsByModule.wms.extensionSurfaces?.contributions).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: 'wms.sales-order-inventory', kind: 'response-enricher' }),
+    ]))
+  })
+
   for (const source of sources) {
     const moduleId = source.moduleId
     describe(`${moduleId}`, () => {
       const facts = factsByModule[moduleId]
 
+      it('stamps the exact providing package and version without removing coreVersion', () => {
+        expect(facts.sourcePackage).toBe(source.from ?? null)
+        expect(facts.sourceVersion).toBe(source.packageVersion ?? null)
+        expect(facts).toHaveProperty('coreVersion')
+      })
+
       // Entity / search / host ids are colon-namespaced under the module by construction
       // and convention; drift here means the builder or a module's data model broke.
       it('colon-namespaces entity / search / host ids under the module and keeps ids unique', () => {

package/src/lib/generators/__tests__/module-facts.computed-di-token.test.ts

@@ -0,0 +1,88 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { extractModuleFacts } from '../module-facts'
+
+/**
+ * A DI token registered through a computed key must still reach module facts.
+ *
+ * `container.register({ [SERVICE_TOKEN]: asFunction(...) })` — reading the token from an
+ * exported const — is the idiomatic, type-safe registration. `getPropertyName` returned
+ * undefined for a `ts.ComputedPropertyName`, so the whole registration vanished with NO
+ * diagnostic: the unresolved-token path is only reached for a NAMED token whose Awilix kind
+ * is unrecognised, so a computed key failed silently rather than being reported.
+ *
+ * That produced a capability the inventory claimed and the extractor scored zero for. Found
+ * by an agent that ran the real extractor instead of trusting the row.
+ */
+
+function write(filePath: string, source: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, source)
+}
+
+function factsFor(diSource: string): Array<{ id: string; metadata?: Record<string, unknown> }> {
+  const moduleRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'om-computed-di-'))
+  try {
+    write(path.join(moduleRoot, 'di.ts'), diSource)
+    const facts = extractModuleFacts({
+      moduleId: 'probe',
+      moduleRoot,
+      sourceRoot: 'src/modules/probe',
+    }) as { ownedContracts?: Record<string, Array<{ id: string; metadata?: Record<string, unknown> }>> }
+    return facts.ownedContracts?.['di-registration'] ?? []
+  } finally {
+    fs.rmSync(moduleRoot, { recursive: true, force: true })
+  }
+}
+
+describe('module-facts DI registration with a computed token', () => {
+  it('resolves a token declared as a same-file const', () => {
+    const facts = factsFor(`
+      import { asFunction } from 'awilix'
+      export const PROBE_SERVICE = 'probeService' as const
+      export function register(container: any) {
+        container.register({ [PROBE_SERVICE]: asFunction(createProbeService).scoped() })
+      }
+    `)
+
+    expect(facts).toHaveLength(1)
+    expect(facts[0].id).toBe('probeService')
+    expect(facts[0].metadata).toMatchObject({ registrationKind: 'function', lifetime: 'scoped' })
+  })
+
+  it('resolves a token written as a computed string literal', () => {
+    const facts = factsFor(`
+      import { asValue } from 'awilix'
+      export function register(container: any) {
+        container.register({ ['literalToken']: asValue(42) })
+      }
+    `)
+
+    expect(facts.map((fact) => fact.id)).toEqual(['literalToken'])
+  })
+
+  it('still resolves plain identifier and string keys', () => {
+    const facts = factsFor(`
+      import { asValue } from 'awilix'
+      export function register(container: any) {
+        container.register({ plainKey: asValue(1), 'quotedKey': asValue(2) })
+      }
+    `)
+
+    expect(facts.map((fact) => fact.id).sort()).toEqual(['plainKey', 'quotedKey'])
+  })
+
+  it('leaves a genuinely dynamic token unresolved rather than inventing one', () => {
+    // A key the reader cannot know statically must NOT be guessed. Emitting a wrong token
+    // would be worse than emitting none.
+    const facts = factsFor(`
+      import { asValue } from 'awilix'
+      export function register(container: any, name: string) {
+        container.register({ [name]: asValue(1) })
+      }
+    `)
+
+    expect(facts).toEqual([])
+  })
+})

package/src/lib/generators/__tests__/module-facts.customers.fixture.test.ts

@@ -52,6 +52,7 @@ describe('module-facts customers fixture (T1 anti-drift guard)', () => {
       'customers.companies.list',
       'customers.deals.list',
       'customers.people.list',
+      'customers.todos.list',
     ])
     expect(facts.hostTokens.entityIds).toEqual(['customers:customer_entity'])
     expect(facts.diTokens).toEqual([])

package/src/lib/generators/__tests__/module-facts.discovery.test.ts

@@ -4,11 +4,13 @@ import path from 'node:path'
 import type { PackageResolver } from '../../resolver'
 import { discoverPackageModuleSources, hasReadableModuleSource } from '../module-facts-discovery'
 
-type FakePackage = { name: string; path: string; modulesPath: string }
+type FakePackage = { name: string; version?: string | null; path: string; modulesPath: string }
+type FakeModuleEntry = { id: string; from?: string }
 
-function makeResolver(packages: FakePackage[]): PackageResolver {
+function makeResolver(packages: FakePackage[], enabledModules: FakeModuleEntry[] = []): PackageResolver {
   return {
     discoverPackages: () => packages,
+    loadEnabledModules: () => enabledModules,
   } as unknown as PackageResolver
 }
 
@@ -62,27 +64,69 @@ describe('module-facts discovery (T1)', () => {
     writeModule(path.join(pkgSrc, 'src', 'modules'), 'gamma', 'events.ts')
 
     const resolver = makeResolver([
-      { name: '@open-mercato/tagged', path: pkgSrc, modulesPath: path.join(pkgSrc, 'src', 'modules') },
+      { name: '@open-mercato/tagged', version: '0.6.6', path: pkgSrc, modulesPath: path.join(pkgSrc, 'src', 'modules') },
     ])
 
     const [source] = discoverPackageModuleSources(resolver)
-    expect(source).toMatchObject({ moduleId: 'gamma', from: '@open-mercato/tagged' })
+    expect(source).toMatchObject({
+      moduleId: 'gamma',
+      from: '@open-mercato/tagged',
+      packageVersion: '0.6.6',
+    })
     expect(source.moduleRoot).toBe(path.join(pkgSrc, 'src', 'modules', 'gamma'))
   })
 
-  it('dedupes duplicate module ids first-wins', () => {
+  it('fails closed on duplicate module ids and reports every provider independent of discovery order', () => {
     const pkgA = path.join(tmp, 'dup-a')
     writeModule(path.join(pkgA, 'src', 'modules'), 'shared', 'index.ts')
     const pkgB = path.join(tmp, 'dup-b')
     writeModule(path.join(pkgB, 'src', 'modules'), 'shared', 'index.ts')
 
-    const resolver = makeResolver([
+    const packages = [
       { name: '@open-mercato/dup-a', path: pkgA, modulesPath: path.join(pkgA, 'src', 'modules') },
       { name: '@open-mercato/dup-b', path: pkgB, modulesPath: path.join(pkgB, 'src', 'modules') },
-    ])
+    ]
+    const expected = '[module-facts] duplicate module id "shared" is provided by '
+      + '@open-mercato/dup-a, @open-mercato/dup-b; src/modules.ts does not select a provider. '
+      + 'Select exactly one matching provider in src/modules.ts.'
+
+    expect(() => discoverPackageModuleSources(makeResolver(packages))).toThrow(expected)
+    expect(() => discoverPackageModuleSources(makeResolver([...packages].reverse()))).toThrow(expected)
+  })
+
+  it('uses the exact src/modules.ts provider even when package discovery order is reversed', () => {
+    const pkgA = path.join(tmp, 'selected-a')
+    writeModule(path.join(pkgA, 'src', 'modules'), 'shared', 'index.ts')
+    const pkgB = path.join(tmp, 'selected-b')
+    writeModule(path.join(pkgB, 'src', 'modules'), 'shared', 'index.ts')
+
+    const packages = [
+      { name: '@open-mercato/selected-a', path: pkgA, modulesPath: path.join(pkgA, 'src', 'modules') },
+      { name: '@open-mercato/selected-b', path: pkgB, modulesPath: path.join(pkgB, 'src', 'modules') },
+    ]
+    const enabled = [{ id: 'shared', from: '@open-mercato/selected-b' }]
+
+    for (const discoveredPackages of [packages, [...packages].reverse()]) {
+      const sources = discoverPackageModuleSources(makeResolver(discoveredPackages, enabled))
+      expect(sources).toHaveLength(1)
+      expect(sources[0]).toMatchObject({ moduleId: 'shared', from: '@open-mercato/selected-b' })
+      expect(sources[0].moduleRoot).toBe(path.join(pkgB, 'src', 'modules', 'shared'))
+    }
+  })
+
+  it('explains that an omitted provider implicitly selects core', () => {
+    const pkgA = path.join(tmp, 'implicit-a')
+    writeModule(path.join(pkgA, 'src', 'modules'), 'shared', 'index.ts')
+    const pkgB = path.join(tmp, 'implicit-b')
+    writeModule(path.join(pkgB, 'src', 'modules'), 'shared', 'index.ts')
+
+    const packages = [
+      { name: '@open-mercato/dup-a', path: pkgA, modulesPath: path.join(pkgA, 'src', 'modules') },
+      { name: '@open-mercato/dup-b', path: pkgB, modulesPath: path.join(pkgB, 'src', 'modules') },
+    ]
 
-    const sources = discoverPackageModuleSources(resolver)
-    expect(sources).toHaveLength(1)
-    expect(sources[0].moduleRoot).toBe(path.join(pkgA, 'src', 'modules', 'shared'))
+    expect(() => discoverPackageModuleSources(makeResolver(packages, [{ id: 'shared' }]))).toThrow(
+      'src/modules.ts omits "from", which defaults to @open-mercato/core',
+    )
   })
 })

package/src/lib/generators/__tests__/module-facts.extension-hosts.test.ts

@@ -0,0 +1,108 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { extractModuleFacts } from '../module-facts'
+
+function findCoreSrcRoot(): string {
+  let dir = __dirname
+  for (let depth = 0; depth < 10; depth += 1) {
+    const candidate = path.join(dir, 'packages', 'core', 'src', 'modules')
+    if (fs.existsSync(candidate)) return candidate
+    dir = path.dirname(dir)
+  }
+  throw new Error('[internal] could not locate packages/core/src/modules from the test directory')
+}
+
+function write(filePath: string, source: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, source)
+}
+
+describe('module-facts extension host extraction', () => {
+  const coreSrcRoot = findCoreSrcRoot()
+
+  it('resolves generated E.<module>.<entity> custom-field declarations from shipped modules', () => {
+    const expectedByModule: Record<string, string[]> = {
+      attachments: ['attachments:attachment'],
+      catalog: [
+        'catalog:catalog_product',
+        'catalog:catalog_product_variant',
+        'catalog:catalog_product_price',
+      ],
+      sales: [
+        'sales:sales_order',
+        'sales:sales_order_line',
+        'sales:sales_order_adjustment',
+        'sales:sales_quote',
+        'sales:sales_quote_line',
+        'sales:sales_quote_adjustment',
+        'sales:sales_invoice',
+        'sales:sales_invoice_line',
+        'sales:sales_payment',
+        'sales:sales_payment_allocation',
+        'sales:sales_credit_memo',
+        'sales:sales_credit_memo_line',
+        'sales:sales_shipment',
+        'sales:sales_shipment_item',
+        'sales:sales_note',
+      ],
+      staff: ['staff:staff_team_member'],
+    }
+
+    for (const [moduleId, expected] of Object.entries(expectedByModule)) {
+      const facts = extractModuleFacts({ moduleId, coreSrcRoot })
+      expect(facts.entities.filter((entity) => entity.customFields).map((entity) => entity.id).sort()).toEqual(
+        [...expected].sort(),
+      )
+    }
+  })
+
+  it('discovers literal and conditional DataTable IDs outside backend while excluding test sources', () => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'module-facts-extension-hosts-'))
+    const moduleRoot = path.join(tmpRoot, 'alpha')
+    try {
+      write(
+        path.join(moduleRoot, 'data', 'entities.ts'),
+        `@Entity({ tableName: 'alpha_records' })\nexport class AlphaRecord { updatedAt?: Date }\n`,
+      )
+      write(
+        path.join(moduleRoot, 'ce.ts'),
+        `export const entities = [{ id: E.alpha.alpha_record, fields: [] }]\n`,
+      )
+      write(
+        path.join(moduleRoot, 'components', 'AlphaTable.tsx'),
+        `export const props = {
+  perspective: { tableId: kind === 'one' ? 'alpha.one' : 'alpha.two' },
+  extensionTableId: 'alpha.extension',
+}\n`,
+      )
+      write(
+        path.join(moduleRoot, 'components', 'Noise.test.tsx'),
+        `export const noise = { tableId: 'alpha.test-noise' }\n`,
+      )
+      write(
+        path.join(moduleRoot, 'backend', '__tests__', 'noise.tsx'),
+        `export const noise = { extensionTableId: 'alpha.test-directory-noise' }\n`,
+      )
+
+      const facts = extractModuleFacts({ moduleId: 'alpha', moduleRoot })
+      expect(facts.entities).toEqual([
+        expect.objectContaining({ id: 'alpha:alpha_record', customFields: true }),
+      ])
+      expect(facts.hostTokens.tableIds).toEqual(['alpha.extension', 'alpha.one', 'alpha.two'])
+    } finally {
+      fs.rmSync(tmpRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('captures shipped component-level table hosts used by catalog and sales', () => {
+    const catalog = extractModuleFacts({ moduleId: 'catalog', coreSrcRoot })
+    expect(catalog.hostTokens.tableIds).toEqual([
+      'catalog.categories.list',
+      'catalog.products.list',
+    ])
+
+    const sales = extractModuleFacts({ moduleId: 'sales', coreSrcRoot })
+    expect(sales.hostTokens.tableIds).toEqual(['sales.orders', 'sales.quotes'])
+  })
+})