feat(extract): fix cross-module connection detection regression (#269) - #270

Closes #269

Problem

riviere extract fails to detect 15 cross-module event subscription connections. Regression from PR #267 (per-module ts-morph Projects).

Verified by npm run verify:connections in ecommerce-demo-app:

Missing connections (15 false negatives):
  - [async] shipping:event:ShipmentDispatched -> orders:eventHandler:handle
  - [async] shipping:event:ShipmentDelivered -> orders:eventHandler:handle
  - [async] payment:event:PaymentFailed -> orders:eventHandler:handle
  - [async] payment:event:PaymentCompleted -> orders:eventHandler:handle
  - [async] inventory:event:InventoryReserved -> orders:eventHandler:handle
  - [async] orders:event:OrderConfirmed -> shipping:eventHandler:OrderConfirmedHandler
  - [async] shipping:event:ShipmentCreated -> inventory:eventHandler:ShipmentCreatedHandler
  - [async] orders:event:OrderPlaced -> inventory:eventHandler:OrderPlacedHandler
  - [async] orders:event:OrderCancelled -> inventory:eventHandler:OrderCancelledHandler
  - [async] orders:event:OrderPlaced -> payment:eventHandler:OrderPlacedHandler
  - [async] orders:event:OrderCancelled -> payment:eventHandler:OrderCancelledHandler
  - [async] shipping:event:ShipmentDispatched -> notifications:eventHandler:ShipmentDispatchedHandler
  - [async] shipping:event:ShipmentDelivered -> notifications:eventHandler:ShipmentDeliveredHandler
  - [async] payment:event:PaymentCompleted -> notifications:eventHandler:PaymentCompletedHandler
  - [async] orders:event:OrderPlaced -> notifications:eventHandler:OrderPlacedHandler

Root Cause

File: packages/riviere-cli/src/features/extract/domain/detect-connections-per-module.ts

// Line 25: filters to module-only components
const moduleComponents = enrichedComponents.filter((c) => c.domain === ctx.module.name)
// Line 30: passes only module components to detectConnections
const result = detectConnections(ctx.project, moduleComponents, ...)

detectConnections (packages/riviere-extract-ts/src/features/extraction/domain/connection-detection/detect-connections.ts) bundles 4 strategies. Two do cross-module metadata matching and break when given only one module's components:

Subscribe: when processing the orders module, events like ShipmentDispatched (shipping module) aren't in scope → _unresolved.

Publish: same cross-module matching problem. Currently hidden in ecommerce-demo-app because publishers and events are co-located within modules, but any codebase with cross-module publish→event relationships will break.

Implementation

Step 1: Create detectPerModuleConnections in riviere-extract-ts

File: packages/riviere-extract-ts/src/features/extraction/domain/connection-detection/detect-connections.ts

New function that runs only source-scanning strategies (need a Project, work per-module):

• buildCallGraph
• detectConfigurableConnections

export function detectPerModuleConnections(
  project: Project,
  components: readonly EnrichedComponent[],
  options: ConnectionDetectionOptions,
  globMatcher: GlobMatcher,
): { links: ExtractedLink[], timings: Partial<ConnectionTimings> }

Step 2: Create detectCrossModuleConnections in riviere-extract-ts

File: same as Step 1

New function that runs metadata-matching strategies (need all components, run once after per-module loop):

• detectSubscribeConnections
• detectPublishConnections

Both are pure metadata matching — no AST/Project needed. The previous AST fallback in detectPublishConnections was removed (SD-001 violation: fail-fast over silent fallbacks). When publishedEventType metadata is missing, strict mode throws ConnectionDetectionError and lenient mode returns an _uncertain link.

export function detectCrossModuleConnections(
  allComponents: readonly EnrichedComponent[],
  options: Pick<ConnectionDetectionOptions, 'allowIncomplete' | 'repository'>,
): { links: ExtractedLink[], timings: Partial<ConnectionTimings> }

Inside this function:

• detectPublishConnections is called once with all components
• detectSubscribeConnections is called once with all components

Step 3: Update detectConnectionsPerModule in riviere-cli

File: packages/riviere-cli/src/features/extract/domain/detect-connections-per-module.ts

Two-phase orchestration:

export function detectConnectionsPerModule(
  moduleContexts: ModuleContext[],
  enrichedComponents: EnrichedComponent[],
  repositoryName: string,
  allowIncomplete: boolean,
): PerModuleConnectionResult {
  const links: ExtractedLink[] = []
  const timings: ConnectionTimings[] = []

  // Phase 1: Per-module — source-scanning strategies (need Project + module source files)
  for (const ctx of moduleContexts) {
    const moduleComponents = enrichedComponents.filter((c) => c.domain === ctx.module.name)
    if (moduleComponents.length === 0) continue
    const result = detectPerModuleConnections(ctx.project, moduleComponents, {
      allowIncomplete,
      moduleGlobs: [posix.join(ctx.module.path, ctx.module.glob)],
      repository: repositoryName,
    }, matchesGlob)
    links.push(...result.links)
    timings.push(result.timings)
  }

  // Phase 2: Cross-module — metadata-matching strategies (need ALL components)
  const crossModuleResult = detectCrossModuleConnections(
    enrichedComponents,
    { allowIncomplete, repository: repositoryName },
  )
  links.push(...crossModuleResult.links)

  return { links: deduplicateCrossStrategy(links), timings }
}

Step 4: Export new functions from riviere-extract-ts

File: packages/riviere-extract-ts/src/index.ts

Export detectPerModuleConnections and detectCrossModuleConnections. Keep existing detectConnections export for backward compatibility.

Step 5: Tests

Unit tests in riviere-extract-ts (new spec files or extend detect-connections.spec.ts):

• detectPerModuleConnections — produces call graph and configurable links only, no async links
• detectCrossModuleConnections — produces subscribe and publish links, resolves cross-module matches where handler is in module A and event is in module B
• Edge cases: empty components, single module, all components in one module, publisher without publishedEventType metadata (strict throws, lenient returns _uncertain)

Integration test in riviere-cli (detect-connections-per-module.spec.ts — new):

• Two modules: events in module A, handlers in module B → subscribe links resolve
• Publisher in module A, event in module B → publish links resolve
• Deduplication works across both phases

Files to Modify

Acceptance Criteria

• All 15 cross-module subscribe links resolve correctly (no _unresolved or _uncertain)
• Publish connections still work (no regression — all publish links in ecommerce-demo-app continue to pass)
• --allow-incomplete flag still works
• 100% test coverage maintained in riviere-extract-ts and riviere-cli
• npm run verify:connections in ecommerce-demo-app shows exactly 4 remaining failures: 2 missing HTTP links + 2 missing external links (these are out of scope for this issue)

Verification

# In ecommerce-demo-app after implementing this issue:
npm run verify:connections

# Expected output:
# Extracted N total links (N certain, 0 uncertain)
# Extracted 0 external links
# Connection mismatch!
#
# Missing connections (2 false negatives):
#   - [sync] bff:useCase:PlaceOrderBFFUseCase -> orders:api:handle
#   - [sync] bff:useCase:PlaceOrderBFFUseCase -> inventory:api:CheckStockEndpoint
# Missing external links (2 false negatives):
#   - [sync] bff:useCase:PlaceOrderBFFUseCase -> Fraud Detection Service (external)
#   - [sync] bff:useCase:PlaceOrderBFFUseCase -> Customer Service (external)
#
# The 15 subscribe connections that were previously missing should all pass.
# The 4 remaining failures (2 HTTP + 2 external) are tracked in a separate issue.

Amendment

AST fallback in detectPublishConnections was intentionally removed (SD-001 violation - fail-fast over silent fallbacks). When publishedEventType metadata is missing, strict mode throws ConnectionDetectionError and lenient mode returns _uncertain link. This eliminates the need for Map<string, Project> in detectCrossModuleConnections - it now takes only allComponents. The ecommerce-demo-app verify:connections check requires manual post-merge verification.

Summary by CodeRabbit

• New Features

  • Per-module and cross-module connection detection with aggregated timing and deduplicated links.
  • Publish–subscribe detection now resolves via component metadata for more reliable event matching.

• Tests

  • Added comprehensive unit tests covering per-module, cross-module, async publish detection, timing aggregation, and metadata strict/lenient behaviors.

• Chores

  • Minor script path calculation tweak for worktree creation.