@mrpatronz/nexusflow 0.2.1 → 0.2.3

package/src/generators/index.ts

@@ -8,7 +8,7 @@ import { generateCopilotConfig } from './copilot.js';
 import { generateCursorConfig } from './cursor.js';
 import { buildContextContent } from './base.js';
 import { generateImplementationPlan } from './plan-generator.js';
-import { generateWorkspaceGraphFiles } from '../core/graph.js';
+import { generateSkills } from './skills-generator.js';
 
 /** Maps each assistant to its generator function and the file it produces. */
 const GENERATORS: Record<
@@ -65,6 +65,18 @@ ${feature.description}
 
 ${repoList}
 
+## Project Assumptions (verify with user)
+
+<!-- AI assistants: Fill this in during your first session. List each project and describe what you assume its main purpose, tech stack, and responsibilities are. -->
+
+_(No assumptions recorded yet. AI assistant to populate.)_
+
+## Clarifying Questions for the User
+
+<!-- AI assistants: List any clarifying questions or ambiguities about requirements/architecture here. -->
+
+_(No open questions recorded yet. AI assistant to populate.)_
+
 ## Architecture Decisions
 
 <!-- AI assistants: append decisions here as they are made during development.
@@ -86,12 +98,6 @@ ${progressItems}
      the same debugging. -->
 
 _(No gotchas recorded yet.)_
-
-## Open Questions
-
-<!-- Add questions that need human input before the AI can proceed. -->
-
-_(No open questions.)_
 `;
 }
 
@@ -141,12 +147,23 @@ export async function generateContextFiles(
 
   // Generate per-repo architecture maps
   if (ctx.analysis) {
+    const allProduced = new Set<string>();
+    for (const [, a] of ctx.analysis) {
+      if (a.produces) {
+        for (const p of a.produces) {
+          allProduced.add(p.name.toLowerCase());
+        }
+      }
+      // Also treat the repository name as a produced package concept
+      allProduced.add(a.name.toLowerCase());
+    }
+
     for (const repo of ctx.repos) {
       const a = ctx.analysis.get(repo.path);
       if (a) {
         try {
           const { generateRepoMap } = await import('./map-generator.js');
-          await generateRepoMap(repo, a, workspacePath);
+          await generateRepoMap(repo, a, workspacePath, allProduced);
           console.log(chalk.green('  ✔'), `Generated Architecture Map for ${chalk.bold(repo.name)}`);
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
@@ -174,25 +191,26 @@ export async function generateContextFiles(
     }
   }
 
-  // Generate Workspace Architecture Graph
+
+  // Generate implementation plan from dependency analysis (if analysis data available)
   try {
-    await generateWorkspaceGraphFiles(ctx, workspacePath);
+    await generateImplementationPlan(ctx, workspacePath);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(
       chalk.red('  ✖'),
-      `Failed to generate workspace architecture graph: ${message}`,
+      `Failed to generate implementation plan: ${message}`,
     );
   }
 
-  // Generate implementation plan from dependency analysis (if analysis data available)
+  // Generate skills files for selected assistants
   try {
-    await generateImplementationPlan(ctx, workspacePath);
+    await generateSkills(ctx, assistants, workspacePath);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(
       chalk.red('  ✖'),
-      `Failed to generate implementation plan: ${message}`,
+      `Failed to generate skills: ${message}`,
     );
   }
 }

package/src/generators/map-generator.test.ts

@@ -78,4 +78,82 @@ describe('generateRepoMap', () => {
     expect(content).toContain('GET');
     expect(content).toContain('/api/v1/users');
   });
+
+  it('should render messaging topology, run config, and group endpoints by module', async () => {
+    const mockRepo = {
+      name: 'test-repo',
+      path: '/original/path/test-repo',
+      defaultBranch: 'main',
+    };
+
+    const mockAnalysis: ProjectAnalysis = {
+      name: 'test-repo',
+      path: '/original/path/test-repo',
+      techStack: {
+        languages: ['typescript' as Language],
+        frameworks: ['react' as Framework],
+        buildTools: ['vite'],
+        projectType: 'frontend' as const,
+      },
+      endpoints: [
+        { method: 'GET', path: '/api/v1/users', source: 'src/routes/users.ts' },
+        { method: 'POST', path: '/api/v1/users', source: 'src/routes/users.ts' }
+      ],
+      dependencies: [
+        { name: 'my-internal-package', type: 'npm' as const },
+        { name: 'eslint', type: 'npm' as const }
+      ],
+      ports: [],
+      readmeSummary: 'A test repository.',
+      existingAIConfigs: [],
+      messaging: {
+        publishers: [
+          { contractType: 'OrderCreated', topicOrQueue: 'order-events', publisherFile: 'src/services/order.ts' }
+        ],
+        subscribers: [
+          { contractType: 'OrderCreated', handlerFile: 'src/handlers/order.ts', registrationFile: 'src/index.ts' }
+        ]
+      },
+      runConfig: {
+        entryPoints: [
+          { projectPath: 'package.json', type: 'node', command: 'npm run dev' }
+        ],
+        databases: [
+          { provider: 'PostgreSQL', host: 'localhost', configFile: '.env' }
+        ],
+        sharedInfraWarnings: [
+          { resource: 'Database', host: 'staging-db.org', configFile: '.env', warning: '⚠️ SHARED INFRA warning' }
+        ],
+        committedSecrets: [
+          { file: '.env', lineHint: 'DATABASE_PASSWORD' }
+        ],
+        externalDependencies: []
+      }
+    };
+
+    vi.spyOn(globby, 'globby').mockImplementation(async () => []);
+
+    const writtenFiles: Record<string, string> = {};
+    vi.spyOn(fs, 'writeFile').mockImplementation(async (filePath: any, content: any) => {
+      writtenFiles[filePath as string] = content as string;
+      return Promise.resolve();
+    });
+    vi.spyOn(fs, 'readFile').mockImplementation(async () => '## custom rule here');
+
+    await generateRepoMap(mockRepo, mockAnalysis, workspacePath, new Set(['my-internal-package']));
+
+    const expectedOutPath = path.join(workspacePath, 'nexusflow-map-test-repo.md');
+    const content = writtenFiles[expectedOutPath]!;
+
+    expect(content).toContain('## 📨 Messaging Topology');
+    expect(content).toContain('OrderCreated');
+    expect(content).toContain('order-events');
+    expect(content).toContain('## ▶️ Running Locally');
+    expect(content).toContain('### Entry Points');
+    expect(content).toContain('### ⚠️ Shared Infrastructure Warnings');
+    expect(content).toContain('my-internal-package');
+    expect(content).not.toContain('eslint');
+    expect(content).toContain('Endpoint Group (Router/Module/File)');
+    expect(content).toContain('users');
+  });
 });

package/src/generators/map-generator.ts

@@ -8,7 +8,6 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { globby } from 'globby';
 import type { ProjectAnalysis, RepoInfo } from '../types.js';
-import { loadConfig } from '../core/config.js';
 
 interface PatternRule {
   name: string;
@@ -119,6 +118,7 @@ export async function generateRepoMap(
   repo: RepoInfo,
   analysis: ProjectAnalysis,
   workspacePath: string,
+  allProducedPackages: Set<string> = new Set(),
 ): Promise<void> {
   const repoName = repo.name;
   const worktreePath = path.join(workspacePath, repoName);
@@ -133,13 +133,6 @@ export async function generateRepoMap(
   md.push(`> **Note**: Maps are advisory snapshots of the codebase. Always verify route parameters, patterns, and filenames before relying on them.`);
   md.push('');
 
-  const config = await loadConfig();
-  if (config.packContextXml) {
-    const contextXmlPath = path.join(workspacePath, `nexusflow-context-${repoName}.xml`).replace(/\\/g, '/');
-    md.push(`> **AI-friendly Packed Context**: [nexusflow-context-${repoName}.xml](file:///${contextXmlPath})`);
-    md.push(`> — **Instruction**: If you need a complete, AI-friendly XML snapshot of this repository's codebase, read this file.`);
-    md.push('');
-  }
 
   // 1. Solution/Project Layout
   md.push('## 🏗️ Project Layout');
@@ -191,18 +184,55 @@ export async function generateRepoMap(
     md.push('');
   }
 
+  // 1.5. Messaging Topology
+  md.push('## 📨 Messaging Topology');
+  md.push('');
+  if (analysis.messaging && (analysis.messaging.publishers.length > 0 || analysis.messaging.subscribers.length > 0)) {
+    if (analysis.messaging.publishers.length > 0) {
+      md.push('### Publishes');
+      md.push('| Message Contract | Topic/Queue/Channel | Publisher (file) |');
+      md.push('|---|---|---|');
+      for (const p of analysis.messaging.publishers) {
+        const fileLink = p.publisherFile
+          ? `[${path.basename(p.publisherFile)}](file:///${path.join(worktreePath, p.publisherFile)})`
+          : '—';
+        md.push(`| ${p.contractType} | ${p.topicOrQueue} | ${fileLink} |`);
+      }
+      md.push('');
+    }
+
+    if (analysis.messaging.subscribers.length > 0) {
+      md.push('### Subscribes');
+      md.push('| Message Contract | Handler (file) | Registered in |');
+      md.push('|---|---|---|');
+      for (const s of analysis.messaging.subscribers) {
+        const handlerLink = s.handlerFile
+          ? `[${path.basename(s.handlerFile)}](file:///${path.join(worktreePath, s.handlerFile)})`
+          : '—';
+        const regLink = s.registrationFile
+          ? `[${path.basename(s.registrationFile)}](file:///${path.join(worktreePath, s.registrationFile)})`
+          : '—';
+        md.push(`| ${s.contractType} | ${handlerLink} | ${regLink} |`);
+      }
+      md.push('');
+    }
+  } else {
+    md.push('_No pub/sub messaging patterns detected in this repository._');
+    md.push('');
+  }
+
   // 2. Extensible Usage Pattern Scanning
   md.push('## 💡 Detected Architectural Patterns & Usages');
   md.push('');
 
   const detectedLanguages = analysis.techStack.languages;
-  const patternCounts = new Map<string, { label: string; count: number; description: string }>();
+  const patternExamples = new Map<string, { label: string; firstFile?: string; description: string }>();
 
-  // Initialize counts
+  // Initialize examples
   for (const lang of detectedLanguages) {
     const rules = LANG_PATTERNS[lang] || [];
     for (const rule of rules) {
-      patternCounts.set(rule.name, { label: rule.label, count: 0, description: rule.description });
+      patternExamples.set(rule.name, { label: rule.label, description: rule.description });
     }
   }
 
@@ -231,11 +261,12 @@ export async function generateRepoMap(
         for (const lang of detectedLanguages) {
           const rules = LANG_PATTERNS[lang] || [];
           for (const rule of rules) {
+            const val = patternExamples.get(rule.name)!;
+            if (val.firstFile) continue; // Already found an example
+
             rule.regex.lastIndex = 0;
-            const matches = content.match(rule.regex);
-            if (matches) {
-              const val = patternCounts.get(rule.name)!;
-              val.count += matches.length;
+            if (rule.regex.test(content)) {
+              val.firstFile = file.replace(/\\/g, '/');
             }
           }
         }
@@ -246,22 +277,41 @@ export async function generateRepoMap(
   }
 
   md.push('### Static Analysis Findings');
-  if (patternCounts.size > 0) {
-    for (const [, v] of patternCounts) {
-      md.push(`- **${v.label}**: Found ${v.count} occurrence(s). _(${v.description})_`);
+  let hasFindings = false;
+  if (patternExamples.size > 0) {
+    for (const [, v] of patternExamples) {
+      if (v.firstFile) {
+        hasFindings = true;
+        const fileLink = `[${path.basename(v.firstFile)}](file:///${path.join(worktreePath, v.firstFile).replace(/\\/g, '/')})`;
+        md.push(`- **${v.label}** example: ${fileLink} _(${v.description})_`);
+      }
     }
-  } else {
+  }
+  if (!hasFindings) {
     md.push('_No architectural usage patterns detected via static analysis._');
   }
   md.push('');
 
   md.push('### Packages Present (Dependencies)');
-  if (analysis.dependencies.length > 0) {
-    for (const dep of analysis.dependencies) {
+  // Filter dependencies: only show internal packages produced by repos in this workspace,
+  // or those matching a common organization namespace prefix (e.g. if one package is MyOrg.Common, then MyOrg.*).
+  const internalPrefixes = Array.from(allProducedPackages).map(p => {
+    const parts = p.split('.');
+    return parts.length > 1 ? parts[0] + '.' : null;
+  }).filter((p): p is string => p !== null);
+
+  const filteredDeps = analysis.dependencies.filter(dep => {
+    const depNameLower = dep.name.toLowerCase();
+    if (allProducedPackages.has(depNameLower)) return true;
+    return internalPrefixes.some(prefix => depNameLower.startsWith(prefix));
+  });
+
+  if (filteredDeps.length > 0) {
+    for (const dep of filteredDeps) {
       md.push(`- \`${dep.name}\` (${dep.version || 'unknown version'})`);
     }
   } else {
-    md.push('_No package dependencies detected._');
+    md.push('_No cross-repo or organization-internal package dependencies detected._');
   }
   md.push('');
 
@@ -269,13 +319,46 @@ export async function generateRepoMap(
   md.push('## 🔌 API Endpoints');
   md.push('');
   if (analysis.endpoints.length > 0) {
-    md.push('| Method | Route | Controller/Source File |');
-    md.push('|:---|:---|:---|');
+    md.push('| Endpoint Group (Router/Module/File) | Route Prefix / Pattern | Verbs | Source File |');
+    md.push('|:---|:---|:---|:---|');
+
+    // Group endpoints by source file
+    const grouped = new Map<string, typeof analysis.endpoints>();
     for (const ep of analysis.endpoints) {
-      const sourceLink = ep.source
-        ? `[${path.basename(ep.source)}](file:///${path.join(worktreePath, ep.source)})`
+      const src = ep.source || 'Unknown';
+      if (!grouped.has(src)) {
+        grouped.set(src, []);
+      }
+      grouped.get(src)!.push(ep);
+    }
+
+    const findCommonPrefix = (paths: string[]): string => {
+      if (paths.length === 0) return '';
+      if (paths.length === 1) return paths[0]!;
+      const sorted = [...paths].sort();
+      const first = sorted[0]!.split('/');
+      const last = sorted[sorted.length - 1]!.split('/');
+      const common: string[] = [];
+      for (let i = 0; i < first.length; i++) {
+        if (first[i] === last[i]) {
+          common.push(first[i]!);
+        } else {
+          break;
+        }
+      }
+      const prefix = common.join('/');
+      return prefix || '/';
+    };
+
+    for (const [src, eps] of grouped) {
+      const groupName = src !== 'Unknown' ? path.basename(src, path.extname(src)) : 'Inferred';
+      const paths = eps.map(e => e.path);
+      const commonPrefix = findCommonPrefix(paths);
+      const verbs = Array.from(new Set(eps.map(e => e.method.toUpperCase()))).join(', ');
+      const sourceLink = src !== 'Unknown'
+        ? `[${path.basename(src)}](file:///${path.join(worktreePath, src).replace(/\\/g, '/')})`
         : '—';
-      md.push(`| \`${ep.method}\` | \`${ep.path}\` | ${sourceLink} |`);
+      md.push(`| ${groupName} | \`${commonPrefix}\` | \`${verbs}\` | ${sourceLink} |`);
     }
   } else {
     md.push('_No endpoints detected._');
@@ -324,6 +407,50 @@ export async function generateRepoMap(
   }
   md.push('');
 
+  // 4.5. Running Locally
+  md.push('## ▶️ Running Locally');
+  md.push('');
+  if (analysis.runConfig) {
+    const { entryPoints, databases, sharedInfraWarnings, committedSecrets } = analysis.runConfig;
+
+    if (entryPoints.length > 0) {
+      md.push('### Entry Points');
+      for (const ep of entryPoints) {
+        md.push(`- **${ep.type.toUpperCase()} App**: \`${ep.command || 'dotnet run'}\` (configured in \`${ep.projectPath}\`)`);
+      }
+      md.push('');
+    }
+
+    if (databases.length > 0) {
+      md.push('### Databases & Data Stores');
+      md.push('| Provider | Target Host | Config File |');
+      md.push('|---|---|---|');
+      for (const db of databases) {
+        md.push(`| ${db.provider} | ${db.host} | \`${db.configFile}\` |`);
+      }
+      md.push('');
+    }
+
+    if (sharedInfraWarnings.length > 0) {
+      md.push('### ⚠️ Shared Infrastructure Warnings');
+      for (const w of sharedInfraWarnings) {
+        md.push(`- ${w.warning}`);
+      }
+      md.push('');
+    }
+
+    if (committedSecrets.length > 0) {
+      md.push('### 🔒 Potential Committed Secrets');
+      for (const s of committedSecrets) {
+        md.push(`- **Warning**: Possible plaintext secret/key/password found in \`${s.file}\` (key hint: \`${s.lineHint}\`)`);
+      }
+      md.push('');
+    }
+  } else {
+    md.push('_No run configurations detected._');
+    md.push('');
+  }
+
   // 5. Custom Skills
   md.push('## 🛠️ Custom Agent Skills');
   md.push('');
@@ -363,41 +490,25 @@ export async function generateRepoMap(
   md.push('');
 
   // 7. Project-Specific Conventions (Agent-Defined)
+  md.push('## 📝 Discovered Conventions');
+  md.push('');
+  
   const conventionsFile = path.join(workspacePath, `nexusflow-conventions-${repoName}.md`);
-  let hasConventions = false;
-  try {
-    await fs.access(conventionsFile);
-    hasConventions = true;
-  } catch {}
-
-  if (!hasConventions) {
-    const starterContent = [
-      `# Project Conventions — ${repoName}`,
-      '',
-      `<!--`,
-      `This file is dedicated for the AI assistant and developers to document project-specific conventions.`,
-      `Any corrections or guidelines discovered during implementation should be appended here.`,
-      `The NexusFlow generator will automatically merge these into the architecture map during sync.`,
-      `-->`,
-      '',
-      `## 📌 Custom Rules & Discovered Conventions`,
-      '- ',
-    ].join('\n');
-    try {
-      await fs.writeFile(conventionsFile, starterContent, 'utf-8');
-    } catch {}
-  }
-
   let customConventions = '';
   try {
     customConventions = await fs.readFile(conventionsFile, 'utf-8');
+    // Strip the title from the old conventions file if present
+    customConventions = customConventions.replace(/^#\s+.+\n?/, '').trim();
   } catch {}
 
   if (customConventions) {
-    md.push('## 📝 Project-Specific Conventions (Agent-Defined)');
-    md.push('');
     md.push(customConventions);
     md.push('');
+  } else {
+    md.push('<!-- AI assistants: Document any project-specific conventions, gotchas, or coding rules discovered here. -->');
+    md.push('');
+    md.push('- None recorded yet.');
+    md.push('');
   }
 
   const outPath = path.join(workspacePath, `nexusflow-map-${repoName}.md`);

package/src/generators/plan-generator.ts

@@ -15,22 +15,11 @@ import type {
   DependencyGraph,
 } from '../types.js';
 
-// ─── Constants ────────────────────────────────────────────────────────────
-
-/** Repo-name substrings that signal a shared/foundation package. */
-const SHARED_PACKAGE_KEYWORDS = ['shared', 'common', 'contracts', 'types'];
-
-/** Project types that act as backend producers. */
-const BACKEND_TYPES = ['api', 'backend', 'service'];
-
-/** Project types that act as frontend consumers. */
-const FRONTEND_TYPES = ['frontend', 'webapp', 'app'];
-
 // ─── Dependency Graph Builder ─────────────────────────────────────────────
 
 /**
- * Build a dependency graph by analysing package dependencies, API
- * relationships and shared-package conventions across the workspace repos.
+ * Build a dependency graph by analysing package dependencies
+ * across the workspace repos.
  *
  * @param analysis  Per-repo analysis results, keyed by repo path.
  * @param repos     Metadata for every repo in the workspace.
@@ -88,67 +77,16 @@ export function buildDependencyGraph(
     for (const dep of a.dependencies) {
       const depNameLower = dep.name.toLowerCase();
 
-      // 1. Direct match with a produced package
+      // Direct match with a produced package
       if (packageToRepo.has(depNameLower)) {
         const targetRepo = packageToRepo.get(depNameLower)!;
         if (targetRepo !== repo.name) {
           addEdge(graph, repo.name, targetRepo);
         }
-      } else {
-        // 2. Check if the dependency contains or is contained by a produced package name
-        for (const [prodPkg, targetRepo] of packageToRepo) {
-          if (targetRepo === repo.name) continue;
-          if (depNameLower.includes(prodPkg) || prodPkg.includes(depNameLower)) {
-            addEdge(graph, repo.name, targetRepo);
-          }
-        }
-      }
-    }
-  }
-
-  // ── 2. API relationships (frontend → backend heuristic) ─────────────
-  for (const repoA of repos) {
-    const analysisA = analysisByName.get(repoA.name);
-    if (!analysisA) continue;
-
-    const typeA = analysisA.techStack.projectType;
-
-    if (!BACKEND_TYPES.includes(typeA)) continue;
-
-    for (const repoB of repos) {
-      if (repoB.name === repoA.name) continue;
-
-      const analysisB = analysisByName.get(repoB.name);
-      if (!analysisB) continue;
-
-      const typeB = analysisB.techStack.projectType;
-      if (FRONTEND_TYPES.includes(typeB)) {
-        // B (frontend) depends on A (backend)
-        addEdge(graph, repoB.name, repoA.name);
       }
     }
   }
 
-  // ── 3. Shared-type packages are always foundation ───────────────────
-  for (const repo of repos) {
-    const isShared = SHARED_PACKAGE_KEYWORDS.some((kw) =>
-      repo.name.toLowerCase().includes(kw),
-    );
-    if (!isShared) continue;
-
-    const node = graph.get(repo.name);
-    if (!node) continue;
-
-    // Ensure no outgoing deps (it's a leaf producer)
-    node.dependsOn = [];
-
-    // Every other repo that doesn't already depend on it — add edge
-    for (const other of repos) {
-      if (other.name === repo.name) continue;
-      addEdge(graph, other.name, repo.name);
-    }
-  }
-
   return graph;
 }
 
@@ -297,25 +235,19 @@ export async function generateImplementationPlan(
 
     md.push('```');
     md.push('');
+    md.push('> ⚠️ This diagram is derived from detected package dependencies (`package.json`, `.csproj`, etc.) only.');
+    md.push('> If you changed a package, the producing repo must release/build before consumer repos can merge.');
+    md.push('');
 
     // ── Phase descriptions ──────────────────────────────────────────────
     md.push('## Suggested Implementation Order');
     md.push('');
 
-    const phaseLabels = [
-      'Foundation',
-      'Core Services',
-      'Integration Layer',
-      'Consumers',
-      'Final',
-    ];
-
     for (let i = 0; i < phases.length; i++) {
       const phase = phases[i];
-      const label = phaseLabels[Math.min(i, phaseLabels.length - 1)];
       const ordinal = ordinalWord(i + 1);
 
-      md.push(`### Phase ${i + 1}: ${label}`);
+      md.push(`### Phase ${i + 1}`);
       md.push('');
       md.push(`**Repos:** ${phase.join(', ')}`);
       md.push('');
@@ -421,6 +353,52 @@ export async function generateImplementationPlan(
     }
     md.push('');
 
+    // ── Cross-Repo Messaging Roll-up ────────────────────────────────────
+    md.push('## 📨 Cross-Repo Messaging');
+    md.push('');
+    md.push('| Publisher Repo | Message | → Subscriber Repo | Handler |');
+    md.push('|---|---|---|---|');
+
+    interface CrossRepoMessage {
+      pubRepo: string;
+      message: string;
+      subRepo: string;
+      handler: string;
+    }
+    const crossRepoMessages: CrossRepoMessage[] = [];
+
+    for (const [pubPath, pubA] of analysis) {
+      if (!pubA.messaging || !pubA.messaging.publishers) continue;
+      for (const pub of pubA.messaging.publishers) {
+        // Find subscribers in other repos matching this contract type
+        for (const [subPath, subA] of analysis) {
+          if (subPath === pubPath) continue;
+          if (!subA.messaging || !subA.messaging.subscribers) continue;
+          for (const sub of subA.messaging.subscribers) {
+            const pubContract = pub.contractType.toLowerCase().trim();
+            const subContract = sub.contractType.toLowerCase().trim();
+            if (pubContract === subContract && pubContract !== 'goservicebusmessage' && pubContract !== 'servicebusmessage') {
+              crossRepoMessages.push({
+                pubRepo: pubA.name,
+                message: pub.contractType,
+                subRepo: subA.name,
+                handler: sub.handlerFile,
+              });
+            }
+          }
+        }
+      }
+    }
+
+    if (crossRepoMessages.length > 0) {
+      for (const m of crossRepoMessages) {
+        md.push(`| \`${m.pubRepo}\` | \`${m.message}\` | \`${m.subRepo}\` | \`${m.handler}\` |`);
+      }
+    } else {
+      md.push('| _No cross-repo messaging detected_ | | | |');
+    }
+    md.push('');
+
     // ── Local Package Development Loop Tip ──────────────────────────────
     md.push('## 💡 Local Package Development Loop');
     md.push('');