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

package/src/lib/generators/module-fact-sources.ts

@@ -0,0 +1,108 @@
+import type {
+  ModuleFactSourceKind,
+  ModuleFactSourceRef,
+  ModuleFactsJsonEntry,
+} from './module-facts'
+
+/**
+ * The subset of a module's facts needed to resolve the provenance index. Both
+ * the in-memory `ModuleFacts` and the emitted `ModuleFactsJsonEntry` satisfy it.
+ */
+export type FactSourceLookupInput = Pick<
+  ModuleFactsJsonEntry,
+  | 'apiRoutes'
+  | 'cliCommands'
+  | 'backendPages'
+  | 'frontendPages'
+  | 'aiTools'
+  | 'aiAgents'
+  | 'ownedContracts'
+  | 'extensionSurfaces'
+  | 'factSources'
+>
+
+export type FactSourceLookup = (kind: ModuleFactSourceKind, id: string) => ModuleFactSourceRef | null
+
+function identityKey(left: string, right: string): string {
+  return JSON.stringify([left, right])
+}
+
+/**
+ * Fact sections that do not serialize a source inline: their provenance lives in
+ * `factSources` under the mapped kind, so a `factRef` into them resolves with one
+ * extra hop. Used by `fact-ref` extension hosts, which reference the fact they
+ * expose rather than a declaration of their own.
+ */
+const SECTION_FACT_KINDS: Record<string, ModuleFactSourceKind> = {
+  entities: 'entity',
+  events: 'event',
+  aclFeatures: 'acl-feature',
+  notifications: 'notification',
+  searchEntities: 'search',
+}
+
+/**
+ * Builds the single provenance lookup every consumer uses. `factSources` entries
+ * carrying an inline `source` resolve directly; `factRef` entries are followed
+ * into the fact section that already serializes the declaration site, so every
+ * proven `(kind, id)` resolves deterministically without duplicated payloads.
+ */
+export function buildFactSourceLookup(facts: FactSourceLookupInput): FactSourceLookup {
+  const bySection = new Map<string, ModuleFactSourceRef>()
+  const register = (factSection: string, factKey: string, source: ModuleFactSourceRef): void => {
+    bySection.set(identityKey(factSection, factKey), source)
+  }
+  for (const route of facts.apiRoutes ?? []) {
+    if (route.sourcePath) register('apiRoutes', route.path, { sourcePath: route.sourcePath })
+  }
+  for (const command of facts.cliCommands ?? []) {
+    register('cliCommands', command.command, { sourcePath: command.sourcePath })
+  }
+  for (const page of facts.backendPages ?? []) register('backendPages', page.path, { sourcePath: page.sourcePath })
+  for (const page of facts.frontendPages ?? []) register('frontendPages', page.path, { sourcePath: page.sourcePath })
+  for (const tool of facts.aiTools ?? []) register('aiTools', tool.name, { sourcePath: tool.sourcePath })
+  for (const agent of facts.aiAgents ?? []) register('aiAgents', agent.id, { sourcePath: agent.sourcePath })
+  for (const [kind, ownedFacts] of Object.entries(facts.ownedContracts ?? {})) {
+    for (const fact of ownedFacts ?? []) register(`ownedContracts.${kind}`, fact.id, fact.source)
+  }
+  for (const contribution of facts.extensionSurfaces?.contributions ?? []) {
+    register('extensionSurfaces.contributions', contribution.id, { sourcePath: contribution.source.path })
+  }
+  const factRefHostTargets = new Map<string, { factSection: string; factKey: string }>()
+  for (const host of facts.extensionSurfaces?.hosts ?? []) {
+    if (host.source.kind === 'fact-ref') {
+      factRefHostTargets.set(host.key, { factSection: host.source.factSection, factKey: host.source.factKey })
+      continue
+    }
+    register('extensionSurfaces.hosts', host.key, { sourcePath: host.source.path })
+  }
+
+  const entries = new Map<string, { source?: ModuleFactSourceRef; factSection?: string; factKey?: string }>()
+  for (const entry of facts.factSources ?? []) {
+    entries.set(identityKey(entry.kind, entry.id), {
+      ...(entry.source ? { source: entry.source } : {}),
+      ...(entry.factRef ? { factSection: entry.factRef.factSection, factKey: entry.factRef.factKey } : {}),
+    })
+  }
+
+  const resolve = (kind: ModuleFactSourceKind, id: string, depth: number): ModuleFactSourceRef | null => {
+    if (depth > 2) return null
+    const entry = entries.get(identityKey(kind, id))
+    if (!entry) return null
+    if (entry.source) return entry.source
+    if (entry.factSection === undefined) return null
+    const factKey = entry.factKey ?? id
+    const direct = bySection.get(identityKey(entry.factSection, factKey))
+    if (direct) return direct
+    if (entry.factSection === 'extensionSurfaces.hosts') {
+      const hostTarget = factRefHostTargets.get(factKey)
+      const hostKind = hostTarget ? SECTION_FACT_KINDS[hostTarget.factSection] : undefined
+      if (hostTarget && hostKind) return resolve(hostKind, hostTarget.factKey, depth + 1)
+      if (hostTarget) return bySection.get(identityKey(hostTarget.factSection, hostTarget.factKey)) ?? null
+    }
+    const sectionKind = SECTION_FACT_KINDS[entry.factSection]
+    return sectionKind ? resolve(sectionKind, factKey, depth + 1) : null
+  }
+
+  return (kind, id) => resolve(kind, id, 0)
+}

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

@@ -29,13 +29,59 @@ export function hasReadableModuleSource(moduleRoot: string): boolean {
   return false
 }
 
-function dedupeById(sources: ModuleFactSource[]): ModuleFactSource[] {
-  const seen = new Set<string>()
+function resolveDuplicateModuleIds(
+  sources: ModuleFactSource[],
+  resolver: PackageResolver,
+): ModuleFactSource[] {
+  const sourcesByModule = new Map<string, ModuleFactSource[]>()
+  for (const source of sources) {
+    const matches = sourcesByModule.get(source.moduleId) ?? []
+    matches.push(source)
+    sourcesByModule.set(source.moduleId, matches)
+  }
+
+  const duplicates = [...sourcesByModule.entries()].filter(([, matches]) => matches.length > 1)
+  if (duplicates.length === 0) return sources
+
+  const selectedProviders = new Map<string, Set<string>>()
+  const implicitCoreSelections = new Set<string>()
+  for (const entry of resolver.loadEnabledModules()) {
+    const providers = selectedProviders.get(entry.id) ?? new Set<string>()
+    providers.add(entry.from ?? '@open-mercato/core')
+    selectedProviders.set(entry.id, providers)
+    if (entry.from === undefined) implicitCoreSelections.add(entry.id)
+  }
+
+  const selectedSources = new Map<string, ModuleFactSource>()
+  for (const [moduleId, matches] of duplicates) {
+    const providers = [...new Set(matches.map((source) => source.from ?? '<unknown>'))]
+      .sort((left, right) => left.localeCompare(right))
+    const configuredProviders = [...(selectedProviders.get(moduleId) ?? [])]
+      .sort((left, right) => left.localeCompare(right))
+    const selected = configuredProviders.length === 1
+      ? matches.filter((source) => source.from === configuredProviders[0])
+      : []
+
+    if (selected.length !== 1) {
+      const configured = configuredProviders.length > 0
+        ? implicitCoreSelections.has(moduleId)
+          ? '; src/modules.ts omits "from", which defaults to @open-mercato/core'
+          : `; src/modules.ts selects ${configuredProviders.join(', ')}`
+        : '; src/modules.ts does not select a provider'
+      throw new Error(
+        `[module-facts] duplicate module id "${moduleId}" is provided by ${providers.join(', ')}${configured}. `
+        + 'Select exactly one matching provider in src/modules.ts.',
+      )
+    }
+    selectedSources.set(moduleId, selected[0])
+  }
+
+  const emitted = new Set<string>()
   const result: ModuleFactSource[] = []
   for (const source of sources) {
-    if (seen.has(source.moduleId)) continue
-    seen.add(source.moduleId)
-    result.push(source)
+    if (emitted.has(source.moduleId)) continue
+    emitted.add(source.moduleId)
+    result.push(selectedSources.get(source.moduleId) ?? source)
   }
   return result
 }
@@ -51,8 +97,59 @@ export function discoverPackageModuleSources(resolver: PackageResolver): ModuleF
     for (const discovered of discoverModulesInPackage(pkg.path)) {
       const moduleRoot = path.join(pkg.modulesPath, discovered.moduleId)
       if (!hasReadableModuleSource(moduleRoot)) continue
-      sources.push({ moduleId: discovered.moduleId, moduleRoot, from: pkg.name })
+      sources.push({
+        moduleId: discovered.moduleId,
+        moduleRoot,
+        from: pkg.name,
+        packageVersion: pkg.version ?? null,
+      })
     }
   }
-  return dedupeById(sources)
+  return resolveDuplicateModuleIds(sources, resolver)
+}
+
+/** App-local modules always live under this app-root-relative directory. */
+export const LOCAL_MODULES_DIRECTORY = path.posix.join('src', 'modules')
+
+/**
+ * Locates an app-local module that is projected into the reference bundle rather than the
+ * normal package outputs. `appRoot` is the directory containing `src/modules` — the
+ * create-app template root at build time, the generated app root at scaffold and
+ * `agentic:init` time — so the same module yields the same portable `src/modules/<id>`
+ * provenance from every root. Returns `null` when the module is absent or is not readable
+ * TypeScript source, because a reference bundle built from an unreadable root would claim
+ * an empty surface rather than fail.
+ */
+export function discoverLocalReferenceModuleSource(options: {
+  appRoot: string
+  moduleId: string
+}): ModuleFactSource | null {
+  const moduleRoot = path.join(options.appRoot, 'src', 'modules', options.moduleId)
+  if (!hasReadableModuleSource(moduleRoot)) return null
+  return {
+    moduleId: options.moduleId,
+    moduleRoot,
+    portableSourceRoot: path.posix.join(LOCAL_MODULES_DIRECTORY, options.moduleId),
+    sourceKind: 'local-reference',
+  }
+}
+
+/**
+ * Appends the local reference source to the package batch, rejecting a duplicate module
+ * id *before* assignment. A package that already provides the same id would otherwise be
+ * silently replaced by (or silently replace) the app-local projection, and the emitted
+ * bundle would attribute one module's surfaces to the other's source tree.
+ */
+export function appendLocalReferenceModuleSource(
+  packageSources: readonly ModuleFactSource[],
+  reference: ModuleFactSource,
+): ModuleFactSource[] {
+  const conflict = packageSources.find((source) => source.moduleId === reference.moduleId)
+  if (conflict) {
+    throw new Error(
+      `[module-facts] local reference module "${reference.moduleId}" collides with the module provided by `
+      + `${conflict.from ?? '<unknown package>'}. Rename the app-local module or remove the package providing it.`,
+    )
+  }
+  return [...packageSources, reference]
 }