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

package/src/lib/generators/__tests__/module-facts.search-entity-id.test.ts

@@ -0,0 +1,151 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { extractModuleFacts } from '../module-facts'
+
+/**
+ * A search entity declared with a non-literal `entityId` must still reach module facts.
+ *
+ * `extractSearchEntities` accepted only a bare string literal, but modules reference the
+ * entity through `E.<module>.<entity>` (the generated entity-id registry, where
+ * `E[module][entity] === '<module>:<entity>'`) or through a same-file `const ENTITY_ID`.
+ * Every such entry was dropped with NO diagnostic, so a module shipping `search.ts` scored
+ * zero search facts while looking healthy — the same class of defect as the computed DI
+ * token. Repo-wide this moved the search family from 47 ids across 9 modules to 52 across 11.
+ *
+ * The second half of this file pins the other direction: an `entityId` the reader genuinely
+ * cannot know statically (an imported constant object) must NOT be guessed, and must produce
+ * a warning rather than a silent zero.
+ */
+
+type Probe = {
+  searchEntities: string[]
+  warnings: string[]
+  searchRegistryIds: string[]
+}
+
+function probe(searchSource: string): Probe {
+  const moduleRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'om-search-entity-id-'))
+  try {
+    fs.writeFileSync(path.join(moduleRoot, 'search.ts'), searchSource)
+    const facts = extractModuleFacts({
+      moduleId: 'probe',
+      moduleRoot,
+      sourceRoot: 'src/modules/probe',
+    }) as unknown as {
+      searchEntities: string[]
+      warnings: string[]
+      extensionSurfaces?: {
+        contributions?: Array<{ kind: string; details?: { registry?: string; registryId?: string } }>
+      }
+    }
+    return {
+      searchEntities: facts.searchEntities,
+      warnings: facts.warnings.filter((warning) => warning.includes('searchConfig')),
+      searchRegistryIds: (facts.extensionSurfaces?.contributions ?? [])
+        .filter((contribution) => contribution.details?.registry === 'search')
+        .map((contribution) => contribution.details?.registryId ?? ''),
+    }
+  } finally {
+    fs.rmSync(moduleRoot, { recursive: true, force: true })
+  }
+}
+
+describe('module-facts search entityId resolution', () => {
+  it('resolves an entityId declared as a same-file const', () => {
+    const result = probe(`
+      const ENTITY_ID = 'probe:todo' as const
+      export const searchConfig = {
+        entities: [{ entityId: ENTITY_ID, enabled: true }],
+      }
+    `)
+
+    expect(result.searchEntities).toEqual(['probe:todo'])
+    expect(result.warnings).toEqual([])
+    // The whole chain matters: `searchEntities` feeds the specialized-registry contribution
+    // that downstream consumers actually read.
+    expect(result.searchRegistryIds).toEqual(['probe:todo'])
+  })
+
+  it('resolves an entityId read from the generated entity-id registry', () => {
+    const result = probe(`
+      import { E } from '#generated/entities.ids.generated'
+      export const searchConfig = {
+        entities: [
+          { entityId: E.probe.todo, enabled: true },
+          { entityId: E['probe']['note'], enabled: true },
+        ],
+      }
+    `)
+
+    expect(result.searchEntities).toEqual(['probe:todo', 'probe:note'])
+    expect(result.warnings).toEqual([])
+  })
+
+  it('still resolves a plain string literal and de-duplicates repeats', () => {
+    const result = probe(`
+      export const searchConfig = {
+        entities: [
+          { entityId: 'probe:todo' },
+          { entityId: 'probe:todo' },
+          { entityId: 'probe:note' },
+        ],
+      }
+    `)
+
+    expect(result.searchEntities).toEqual(['probe:todo', 'probe:note'])
+    expect(result.warnings).toEqual([])
+  })
+
+  it('reports rather than invents an entityId it cannot resolve statically', () => {
+    // `CHECKOUT_ENTITY_IDS` lives in another file, so a single-file reader cannot know the
+    // value. Emitting a guessed id would be worse than emitting none — but staying silent is
+    // what let this family read zero for years, so the entry must surface as a warning.
+    const result = probe(`
+      import { CHECKOUT_ENTITY_IDS } from './lib/constants'
+      import { CONSTANTS } from './lib/other'
+      export const searchConfig = {
+        entities: [
+          { entityId: CHECKOUT_ENTITY_IDS.link, enabled: true },
+          { entityId: CONSTANTS.entities.todo, enabled: true },
+          { entityId: 'probe:known' },
+        ],
+      }
+    `)
+
+    // Neither the two-segment access nor the three-segment access rooted at something other
+    // than the generated `E` registry may be folded into an id.
+    expect(result.searchEntities).toEqual(['probe:known'])
+    expect(result.searchRegistryIds).toEqual(['probe:known'])
+    expect(result.warnings).toHaveLength(2)
+    for (const warning of result.warnings) {
+      expect(warning).toContain('searchConfig entityId is not statically resolvable')
+    }
+  })
+
+  it('reports an entity that declares no entityId at all', () => {
+    const result = probe(`
+      export const searchConfig = {
+        entities: [{ enabled: true, priority: 5 }],
+      }
+    `)
+
+    expect(result.searchEntities).toEqual([])
+    expect(result.warnings).toHaveLength(1)
+    expect(result.warnings[0]).toContain('searchConfig entity declares no entityId')
+  })
+
+  it('does not follow a self-referential const into an infinite loop', () => {
+    const result = probe(`
+      const A = B
+      const B = A
+      export const searchConfig = {
+        entities: [{ entityId: A }],
+      }
+    `)
+
+    expect(result.searchEntities).toEqual([])
+    expect(result.warnings).toHaveLength(1)
+    expect(result.warnings[0]).toContain('searchConfig entityId is not statically resolvable')
+  })
+})

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

@@ -0,0 +1,160 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { extractModuleFacts, isExactSourceFilePath, renderModuleFactsMarkdown } from '../module-facts'
+
+const MARKDOWN_LINK_TARGET = /\]\(\.\.\/\.\.\/\.\.\/([^)#]+)(?:#L\d+)?\)/g
+
+function collectLinkTargets(markdown: string): string[] {
+  return [...markdown.matchAll(MARKDOWN_LINK_TARGET)].map((match) => match[1])
+}
+
+function writeFixture(root: string, relativePath: string, source: string): void {
+  const filePath = path.join(root, relativePath)
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, source)
+}
+
+describe('module-facts source-linked extension surfaces', () => {
+  let temporaryRoot: string
+  let moduleRoot: string
+
+  beforeAll(() => {
+    temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'module-facts-source-links-'))
+    moduleRoot = path.join(temporaryRoot, 'facts')
+    writeFixture(moduleRoot, 'index.ts', "export const metadata = { title: 'Facts' }\n")
+    writeFixture(
+      moduleRoot,
+      'api/records/route.ts',
+      "export const metadata = { path: '/facts/records-custom' }\nexport async function GET() {}\n",
+    )
+    writeFixture(moduleRoot, 'backend/page.tsx', 'export default function FactsPage() { return null }\n')
+    writeFixture(
+      moduleRoot,
+      'backend/facts/items/[id]/page.tsx',
+      'export default function FactItemPage() { return null }\n',
+    )
+    writeFixture(
+      moduleRoot,
+      'frontend/facts/portal/[id]/page.tsx',
+      'export default function FactPortalPage() { return null }\n',
+    )
+    writeFixture(
+      moduleRoot,
+      'cli.ts',
+      "const commands = [{ command: 'facts:sync' }, { command: 'facts:check' }]\nexport default commands\n",
+    )
+    writeFixture(
+      moduleRoot,
+      'ai-tools/tools-pack.ts',
+      "type FactsAiToolDefinition = { name: string; description: string }\nconst inspectTool: FactsAiToolDefinition = { name: 'facts.inspect', description: 'Inspect facts' }\nexport default [inspectTool]\n",
+    )
+    writeFixture(
+      moduleRoot,
+      'ai-tools.ts',
+      "type FactsAiToolDefinition = { name: string; description: string }\nconst listTool: FactsAiToolDefinition = { name: 'facts.list', description: 'List facts' }\nexport const aiTools = [listTool]\nexport default aiTools\n",
+    )
+    writeFixture(
+      moduleRoot,
+      'ai-agents.ts',
+      "type AiAgentDefinition = { id: string; label: string }\nconst AGENT_ID = 'facts.assistant'\nconst agent: AiAgentDefinition = { id: AGENT_ID, label: 'Facts assistant' }\nexport const aiAgents = [agent]\nexport default aiAgents\n",
+    )
+  })
+
+  afterAll(() => {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true })
+  })
+
+  it('emits portable source links for routes, pages, commands, tools, and agents', () => {
+    const registrySource = `export const modules = [{
+      id: 'facts',
+      apis: [{
+        path: '/facts/records-custom',
+        handlers: { GET: async () => undefined },
+        metadata: { GET: { requireFeatures: ['facts.view'] } },
+      }],
+    }]`
+    const facts = extractModuleFacts({
+      moduleId: 'facts',
+      moduleRoot,
+      sourcePackage: '@open-mercato/example',
+      sourceVersion: '1.2.3',
+      registrySource,
+    })
+
+    expect(facts.sourceRoot).toBe('node_modules/@open-mercato/example/src/modules/facts')
+    expect(facts.apiRoutes).toEqual([
+      {
+        path: '/facts/records-custom',
+        methods: ['GET'],
+        auth: { GET: { requireFeatures: ['facts.view'] } },
+        sourcePath: 'node_modules/@open-mercato/example/src/modules/facts/api/records/route.ts',
+      },
+    ])
+    expect(facts.backendPages).toEqual([
+      {
+        path: '/backend/facts',
+        sourcePath: 'node_modules/@open-mercato/example/src/modules/facts/backend/page.tsx',
+      },
+      {
+        path: '/backend/facts/items/[id]',
+        sourcePath: 'node_modules/@open-mercato/example/src/modules/facts/backend/facts/items/[id]/page.tsx',
+      },
+    ])
+    expect(facts.frontendPages).toEqual([
+      {
+        path: '/facts/portal/[id]',
+        sourcePath: 'node_modules/@open-mercato/example/src/modules/facts/frontend/facts/portal/[id]/page.tsx',
+      },
+    ])
+    expect(facts.cli).toEqual(['facts:sync', 'facts:check'])
+    expect(facts.cliCommands.map((command) => command.command)).toEqual(['facts:sync', 'facts:check'])
+    expect(facts.aiTools.map((tool) => tool.name)).toEqual(['facts.inspect', 'facts.list'])
+    expect(facts.aiAgents.map((agentFact) => agentFact.id)).toEqual(['facts.assistant'])
+
+    const markdown = renderModuleFactsMarkdown(facts)
+    expect(markdown).toContain('## Backend pages')
+    expect(markdown).toContain('## Frontend pages')
+    expect(markdown).toContain('## CLI commands')
+    expect(markdown).toContain('## AI tools / MCP capabilities')
+    expect(markdown).toContain('## AI agents')
+    expect(markdown).toContain(
+      '(../../../node_modules/@open-mercato/example/src/modules/facts/api/records/route.ts)',
+    )
+  })
+
+  it('links only exact module code files and never a directory', () => {
+    const facts = extractModuleFacts({
+      moduleId: 'facts',
+      moduleRoot,
+      sourcePackage: '@open-mercato/example',
+      sourceVersion: '1.2.3',
+    })
+    const markdown = renderModuleFactsMarkdown(facts)
+    const targets = collectLinkTargets(markdown)
+
+    expect(targets.length).toBeGreaterThan(0)
+    expect(targets.filter((target) => !isExactSourceFilePath(target))).toEqual([])
+  })
+
+  it('renders the directory-valued source root as plain text instead of a folder link', () => {
+    const facts = extractModuleFacts({
+      moduleId: 'facts',
+      moduleRoot,
+      sourcePackage: '@open-mercato/example',
+      sourceVersion: '1.2.3',
+    })
+    const markdown = renderModuleFactsMarkdown(facts)
+
+    expect(markdown).toContain('Source root: node_modules/@open-mercato/example/src/modules/facts\n')
+    expect(markdown).not.toContain('(../../../node_modules/@open-mercato/example/src/modules/facts)')
+  })
+
+  it('classifies exact files and directories consistently', () => {
+    expect(isExactSourceFilePath('packages/core/src/modules/customers/index.ts')).toBe(true)
+    expect(isExactSourceFilePath('packages/ui/src/backend/DataTable.tsx')).toBe(true)
+    expect(isExactSourceFilePath('node_modules/@open-mercato/core/dist/modules/customers/acl.js')).toBe(true)
+    expect(isExactSourceFilePath('packages/ui/src')).toBe(false)
+    expect(isExactSourceFilePath('node_modules/@open-mercato/core/src/modules/customers')).toBe(false)
+  })
+})

package/src/lib/generators/__tests__/module-override-targets.roundtrip.test.ts

@@ -0,0 +1,149 @@
+import {
+  applyApiOverridesToManifests,
+  applyDiOverrides,
+  applyDiOverridesToContainer,
+  applyInjectionWidgetOverridesToEntries,
+  applyPageGuardOverridesToEntries,
+  applyPageOverridesToManifests,
+  applyWorkerOverridesToDescriptors,
+  resetModuleContractOverridesForTests,
+} from '@open-mercato/shared/modules/overrides'
+import type { ModuleFactsJsonEntry } from '../module-facts'
+import { collectModuleOverrideTargets, type ModuleOverrideTarget } from '../module-override-targets'
+
+const SOURCE_ROOT = 'node_modules/@open-mercato/core/src/modules/demo'
+
+function facts(): ModuleFactsJsonEntry {
+  return {
+    title: null, description: null, coreVersion: null, sourcePackage: '@open-mercato/core',
+    sourceVersion: null, sourceRoot: SOURCE_ROOT,
+    entities: [], events: [], aclFeatures: ['demo.view'],
+    apiRoutes: [{ path: '/demo/items', methods: ['GET', 'POST'], auth: {}, sourcePath: `${SOURCE_ROOT}/api/items/route.ts` }],
+    diTokens: ['demoService'], searchEntities: [], hostTokens: { entityIds: [], tableIds: [] },
+    notifications: [], cli: [], backendPages: [{ path: '/backend/demo/list', sourcePath: `${SOURCE_ROOT}/backend/demo/list/page.tsx` }],
+    frontendPages: [{ path: '/demo-portal', sourcePath: `${SOURCE_ROOT}/frontend/demo-portal/page.tsx` }],
+    cliCommands: [], aiTools: [], aiAgents: [],
+    factSources: [{ kind: 'acl-feature', id: 'demo.view', source: { sourcePath: `${SOURCE_ROOT}/acl.ts` } }],
+    ownedContracts: {
+      worker: [{ kind: 'worker', id: 'demo.worker', source: { sourcePath: `${SOURCE_ROOT}/workers/demo.ts`, line: 3 }, metadata: { queue: 'demo', concurrency: 1 } }],
+      'page-middleware': [{ kind: 'page-middleware', id: 'demo.guard', source: { sourcePath: `${SOURCE_ROOT}/backend/middleware.ts`, line: 2 }, metadata: { surface: 'backend' } }],
+      'di-registration': [{ kind: 'di-registration', id: 'demoService', source: { sourcePath: `${SOURCE_ROOT}/di.ts`, line: 5 }, metadata: { registrationKind: 'class' } }],
+    },
+    extensionSurfaces: {
+      hosts: [], unresolved: [],
+      contributions: [
+        { id: 'demo.widget@profile:demo:slot', kind: 'widget', targets: [], scopeContract: '', source: { path: `${SOURCE_ROOT}/widgets/injection-table.ts`, symbol: 'injectionTable' }, details: { payload: 'render', registryKey: 'demo.widget', executionGuard: 'host' } },
+        { id: 'demo.mutation-guard', kind: 'mutation-guard', targets: [], scopeContract: '', source: { path: `${SOURCE_ROOT}/data/guards.ts`, symbol: 'demo.mutation-guard' }, details: { entityId: 'demo.entity', operations: ['create'], capabilities: ['block'], optimisticLock: 'preserved' } },
+      ],
+    },
+  }
+}
+
+const TARGETS = collectModuleOverrideTargets(facts()).overrideTargets
+function key(domain: string, pathTail: string): string {
+  const target = TARGETS.find((t: ModuleOverrideTarget) => t.domain === domain && t.path[t.path.length - 1] === pathTail)
+  if (!target || target.key === undefined) throw new Error(`[internal] no keyed ${domain} target for ${pathTail}`)
+  return target.key
+}
+
+afterEach(() => resetModuleContractOverridesForTests())
+
+describe('runtime resolver round-trip — positive', () => {
+  it('selects the intended API route method by the generated public key', () => {
+    const getKey = key('routes', 'GET /api/demo/items')
+    const routes = [{ moduleId: 'demo', path: '/demo/items', methods: ['GET', 'POST'], load: async () => ({}) }]
+    const result = applyApiOverridesToManifests(routes as never, { [getKey]: null })
+    expect(result).toHaveLength(1)
+    expect(result[0].methods).toEqual(['POST'])
+  })
+
+  it('selects the intended backend and frontend page by the generated application-route key', () => {
+    const backendKey = key('routes', 'backend:/backend/demo/list')
+    const frontendKey = key('routes', 'frontend:/demo-portal')
+    const backend = applyPageOverridesToManifests([{ moduleId: 'demo', path: '/backend/demo/list', load: async () => ({}) }] as never, { [backendKey]: null }, 'backend')
+    const frontend = applyPageOverridesToManifests([{ moduleId: 'demo', path: '/demo-portal', load: async () => ({}) }] as never, { [frontendKey]: null }, 'frontend')
+    expect(backend).toHaveLength(0)
+    expect(frontend).toHaveLength(0)
+  })
+
+  it('selects the intended worker / injection widget / page middleware by exact key', () => {
+    const workers = applyWorkerOverridesToDescriptors(
+      [{ id: 'demo.worker', queue: 'demo', concurrency: 1, handler: () => undefined }],
+      { [key('workers', 'demo.worker')]: null },
+    )
+    expect(workers).toHaveLength(0)
+
+    const widgets = applyInjectionWidgetOverridesToEntries(
+      [{ moduleId: 'demo', key: 'demo.widget', loader: async () => ({}) }] as never,
+      { [key('widgets', 'demo.widget')]: null },
+    )
+    expect(widgets).toHaveLength(0)
+
+    const guards = applyPageGuardOverridesToEntries(
+      [{ moduleId: 'demo', middleware: [{ id: 'demo.guard', run: async () => undefined }] }] as never,
+      { [key('guards', 'demo.guard')]: null },
+    )
+    expect(guards[0].middleware).toHaveLength(0)
+  })
+
+  it('unregisters the exact DI token via the generated key', () => {
+    const unregistered: string[] = []
+    const container = {
+      register: () => container,
+      unregister: (name: string) => { unregistered.push(name); return container },
+      registrations: { demoService: {} as unknown },
+    }
+    applyDiOverrides({ [key('di', 'demoService')]: null })
+    applyDiOverridesToContainer(container)
+    expect(unregistered).toEqual(['demoService'])
+  })
+})
+
+describe('runtime resolver round-trip — negative (malformed variants do not select)', () => {
+  it('a lowercased / method-less API key does not select the manifest entry', () => {
+    const getKey = key('routes', 'GET /api/demo/items')
+    expect(getKey).toMatch(/^(GET|POST|PUT|PATCH|DELETE) \/api\//)
+    const routes = [{ moduleId: 'demo', path: '/demo/items', methods: ['GET', 'POST'], load: async () => ({}) }]
+    const lowercased = applyApiOverridesToManifests(routes as never, { 'get /api/demo/items': null })
+    expect(lowercased[0].methods).toEqual(['GET', 'POST'])
+    const methodless = applyApiOverridesToManifests(routes as never, { '/api/demo/items': null })
+    expect(methodless[0].methods).toEqual(['GET', 'POST'])
+  })
+
+  it('a UI filesystem path does not select a page; the generated application route does', () => {
+    const filesystemPath = `${SOURCE_ROOT}/backend/demo/list/page.tsx`
+    const wrong = applyPageOverridesToManifests([{ moduleId: 'demo', path: '/backend/demo/list', load: async () => ({}) }] as never, { [filesystemPath]: null }, 'backend')
+    expect(wrong).toHaveLength(1)
+    const backendKey = key('routes', 'backend:/backend/demo/list')
+    expect(backendKey).not.toContain('.tsx')
+    expect(backendKey.startsWith('backend:')).toBe(true)
+  })
+
+  it('a flattened nested widget key does not select the injection entry', () => {
+    const flattened = applyInjectionWidgetOverridesToEntries(
+      [{ moduleId: 'demo', key: 'demo.widget', loader: async () => ({}) }] as never,
+      { 'widgets.injection.demo.widget': null },
+    )
+    expect(flattened).toHaveLength(1)
+  })
+
+  it('a mutation-guard id under page guards does not drop the page middleware', () => {
+    const guards = applyPageGuardOverridesToEntries(
+      [{ moduleId: 'demo', middleware: [{ id: 'demo.guard', run: async () => undefined }] }] as never,
+      { 'demo.mutation-guard': null },
+    )
+    expect(guards[0].middleware).toHaveLength(1)
+    // the mutation guard is never emitted as a guards target
+    expect(TARGETS.some((t) => t.domain === 'guards' && t.key === 'demo.mutation-guard')).toBe(false)
+  })
+
+  it('an unknown DI token is never emitted; emitted tokens correspond to real registrations', () => {
+    expect(TARGETS.some((t) => t.domain === 'di' && t.key === 'nope')).toBe(false)
+    expect(TARGETS.some((t) => t.domain === 'di' && t.key === 'demoService')).toBe(true)
+  })
+
+  it('framework-only nav.groupOrder is never attached to a module target', () => {
+    expect(TARGETS.some((t) => t.domain === 'nav')).toBe(false)
+    expect(TARGETS.some((t) => JSON.stringify(t.path) === JSON.stringify(['nav', 'groupOrder']))).toBe(false)
+  })
+})