spec-gen-cli 1.2.4 → 1.2.6

package/dist/core/analyzer/unified-search.js

@@ -0,0 +1,237 @@
+/**
+ * Unified Search
+ *
+ * Combines code and spec indexes with cross-scoring to boost results
+ * that are linked through bidirectional mappings.
+ *
+ * Usage:
+ *   const results = await UnifiedSearch.unifiedSearch(
+ *     outputDir,
+ *     "validate user authentication",
+ *     embedSvc,
+ *     { limit: 10 }
+ *   );
+ */
+import { join } from 'node:path';
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const DEFAULT_CONFIG = {
+    directMappingBoost: 0.3,
+    reverseMappingBoost: 0.3,
+    mutualMappingBoost: 0.5,
+    additionalLinkBoost: 0.1,
+    maxAdditionalBoost: 0.3,
+};
+// ============================================================================
+// MAPPING INDEX
+// ============================================================================
+/**
+ * Build a bidirectional mapping index from mapping.json
+ */
+export function buildBidirectionalMapping(mappings) {
+    const functionToRequirements = new Map();
+    const requirementToFunctions = new Map();
+    for (const m of mappings) {
+        if (!m.requirement || !m.domain || !m.functions)
+            continue;
+        // Use dot+camelCase format to match spec vector index IDs (e.g. 'auth.validateToken')
+        const reqCamel = m.requirement.charAt(0).toLowerCase() + m.requirement.slice(1);
+        const requirementKey = `${m.domain}.${reqCamel}`;
+        // Build function → requirements mapping
+        for (const fn of m.functions) {
+            if (!fn.file || !fn.name)
+                continue;
+            const functionKey = `${fn.file}::${fn.name}`;
+            const existing = functionToRequirements.get(functionKey) ?? [];
+            existing.push({ domain: m.domain, requirement: m.requirement });
+            functionToRequirements.set(functionKey, existing);
+        }
+        // Build requirement → functions mapping
+        const functions = m.functions
+            .filter((f) => f.file && f.name)
+            .map((f) => ({ file: f.file, name: f.name }));
+        if (functions.length > 0) {
+            requirementToFunctions.set(requirementKey, functions);
+        }
+    }
+    return { functionToRequirements, requirementToFunctions };
+}
+// ============================================================================
+// CROSS-SCORING ALGORITHM
+// ============================================================================
+/**
+ * Calculate cross-scoring boost based on bidirectional mappings
+ */
+export function calculateCrossScore(result, mappingIndex, config) {
+    const linkedArtifacts = [];
+    let mappingBoost = 0;
+    if ('filePath' in result.record) {
+        // This is a code result - look for linked requirements
+        const rec = result.record;
+        const functionKey = `${rec.filePath}::${rec.name}`;
+        const requirements = mappingIndex.functionToRequirements.get(functionKey);
+        if (requirements && requirements.length > 0) {
+            mappingBoost += config.directMappingBoost;
+            // Add linked requirements as artifacts
+            for (const req of requirements) {
+                const reqCamel = req.requirement.charAt(0).toLowerCase() + req.requirement.slice(1);
+                const artifactId = `${req.domain}.${reqCamel}`;
+                linkedArtifacts.push({
+                    type: 'spec',
+                    id: artifactId,
+                    score: result.score,
+                });
+            }
+            // Additional boost for multiple links (capped)
+            const additionalBoost = Math.min((requirements.length - 1) * config.additionalLinkBoost, config.maxAdditionalBoost);
+            mappingBoost += additionalBoost;
+        }
+    }
+    else {
+        // This is a spec result - look for linked functions
+        const specRec = result.record;
+        const requirementKey = specRec.id;
+        const functions = mappingIndex.requirementToFunctions.get(requirementKey);
+        if (functions && functions.length > 0) {
+            mappingBoost += config.reverseMappingBoost;
+            // Add linked functions as artifacts
+            for (const fn of functions) {
+                const artifactId = `${fn.file}::${fn.name}`;
+                linkedArtifacts.push({
+                    type: 'code',
+                    id: artifactId,
+                    score: result.score,
+                });
+            }
+            // Additional boost for multiple links (capped)
+            const additionalBoost = Math.min((functions.length - 1) * config.additionalLinkBoost, config.maxAdditionalBoost);
+            mappingBoost += additionalBoost;
+        }
+    }
+    return { mappingBoost, linkedArtifacts };
+}
+/**
+ * Determine result type based on source and linked artifacts
+ */
+export function determineResultType(result, linkedArtifacts) {
+    const isCode = 'filePath' in result.record;
+    if (isCode && linkedArtifacts.some(art => art.type === 'spec'))
+        return 'both';
+    if (!isCode && linkedArtifacts.some(art => art.type === 'code'))
+        return 'both';
+    return isCode ? 'code' : 'spec';
+}
+/**
+ * Extract source metadata from result
+ */
+export function extractSourceMetadata(result) {
+    if ('filePath' in result.record) {
+        const rec = result.record;
+        return {
+            filePath: rec.filePath,
+            functionName: rec.name,
+            className: rec.className || undefined,
+            language: rec.language,
+        };
+    }
+    else {
+        const rec = result.record;
+        return {
+            domain: rec.domain,
+            section: rec.section,
+            title: rec.title,
+        };
+    }
+}
+// ============================================================================
+// UNIFIED SEARCH
+// ============================================================================
+export class UnifiedSearch {
+    /**
+     * Unified search that combines code and spec indexes with cross-scoring
+     */
+    static async unifiedSearch(outputDir, query, embedSvc, opts = {}) {
+        const { limit = 10, language, domain, section, config = {} } = opts;
+        const scoringConfig = { ...DEFAULT_CONFIG, ...config };
+        // Import index classes dynamically
+        const { VectorIndex } = await import('./vector-index.js');
+        const { SpecVectorIndex } = await import('./spec-vector-index.js');
+        // Load mapping index
+        const mappingJsonPath = join(outputDir, 'mapping.json');
+        let mappingIndex = {
+            functionToRequirements: new Map(),
+            requirementToFunctions: new Map(),
+        };
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const raw = JSON.parse(await readFile(mappingJsonPath, 'utf-8'));
+            mappingIndex = buildBidirectionalMapping(raw.mappings ?? []);
+        }
+        catch {
+            // Non-fatal - proceed without cross-scoring
+        }
+        // Execute parallel searches
+        const svc = embedSvc ?? null;
+        const [codeResults, specResults] = await Promise.all([
+            VectorIndex.search(outputDir, query, svc, { limit: limit * 3, language }).catch(() => []),
+            svc
+                ? SpecVectorIndex.search(outputDir, query, svc, { limit: limit * 3, domain, section }).catch(() => [])
+                : Promise.resolve([]),
+        ]);
+        // Combine and score results
+        const allResults = [];
+        // Process code results
+        for (const result of codeResults) {
+            const { mappingBoost, linkedArtifacts } = calculateCrossScore(result, mappingIndex, scoringConfig);
+            const finalScore = result.score + mappingBoost;
+            const resultType = determineResultType(result, linkedArtifacts);
+            allResults.push({
+                result,
+                unified: {
+                    id: result.record.id,
+                    type: resultType,
+                    score: finalScore,
+                    baseScore: result.score,
+                    mappingBoost,
+                    source: extractSourceMetadata(result),
+                    linkedArtifacts,
+                },
+            });
+        }
+        // Process spec results
+        for (const result of specResults) {
+            const { mappingBoost, linkedArtifacts } = calculateCrossScore(result, mappingIndex, scoringConfig);
+            const finalScore = result.score + mappingBoost;
+            const resultType = determineResultType(result, linkedArtifacts);
+            allResults.push({
+                result,
+                unified: {
+                    id: result.record.id,
+                    type: resultType,
+                    score: finalScore,
+                    baseScore: result.score,
+                    mappingBoost,
+                    source: extractSourceMetadata(result),
+                    linkedArtifacts,
+                },
+            });
+        }
+        // Sort by final score
+        allResults.sort((a, b) => b.unified.score - a.unified.score);
+        // Return top results
+        return allResults.slice(0, limit).map(r => r.unified);
+    }
+}
+// ============================================================================
+// UTILITIES
+// ============================================================================
+/**
+ * Check if unified search is available
+ */
+export async function unifiedSearchAvailable(outputDir) {
+    const { VectorIndex } = await import('./vector-index.js');
+    const { SpecVectorIndex } = await import('./spec-vector-index.js');
+    return VectorIndex.exists(outputDir) && SpecVectorIndex.exists(outputDir);
+}
+//# sourceMappingURL=unified-search.js.map

package/dist/core/analyzer/unified-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-search.js","sourceRoot":"","sources":["../../../src/core/analyzer/unified-search.ts"],"names":[],"mappings":"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"}

package/dist/core/generator/openspec-format-generator.d.ts

@@ -5,6 +5,8 @@
  * specification files.
  */
 import type { PipelineResult } from './spec-pipeline.js';
+import type { DependencyGraphResult } from '../analyzer/dependency-graph.js';
+import type { MappingArtifact } from './mapping-generator.js';
 /**
  * Generated spec file
  */
@@ -28,6 +30,8 @@ export interface GeneratorOptions {
     includeTechnicalNotes?: boolean;
     /** Maximum line width for wrapping */
     maxLineWidth?: number;
+    /** Dependency graph for cross-domain dependency sections */
+    depGraph?: DependencyGraphResult;
 }
 /**
  * OpenSpec Format Generator
@@ -36,9 +40,10 @@ export declare class OpenSpecFormatGenerator {
     private options;
     constructor(options?: GeneratorOptions);
     /**
-     * Generate all spec files from pipeline result
+     * Generate all spec files from pipeline result.
+     * Pass mappingArtifact to annotate each Requirement with `> Implementation: file:line`.
      */
-    generateSpecs(result: PipelineResult): GeneratedSpec[];
+    generateSpecs(result: PipelineResult, mappingArtifact?: MappingArtifact): GeneratedSpec[];
     /**
      * Group entities, services, and endpoints by domain
      */
@@ -63,6 +68,16 @@ export declare class OpenSpecFormatGenerator {
      * Generate the API spec
      */
     private generateApiSpec;
+    /**
+     * Emit `> Implementation: \`file:line\`` after a Requirement header when a
+     * high-confidence mapping entry exists.  Mutates `lines` in-place.
+     */
+    private emitImplementationHint;
+    /**
+     * Build `## Dependencies` section for a domain spec using depGraph edges.
+     * Returns an empty array if no depGraph or no cross-domain edges found.
+     */
+    private buildDependencySection;
     /**
      * Add a scenario to the lines array
      */

package/dist/core/generator/openspec-format-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openspec-format-generator.d.ts","sourceRoot":"","sources":["../../../src/core/generator/openspec-format-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,cAAc,EAOf,MAAM,oBAAoB,CAAC;AAM5B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,cAAc,GAAG,KAAK,GAAG,KAAK,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IAC/B,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA8BD;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,OAAO,CAA6B;gBAEhC,OAAO,GAAE,gBAAqB;IAI1C;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,EAAE;IAuBtD;;OAEG;IACH,OAAO,CAAC,aAAa;IAmGrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA2G5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAuM1B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA+IhC;;OAEG;IACH,OAAO,CAAC,eAAe;IAwGvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAuBjB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA2D9D;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,aAAa,EAAE,CAGjB"}
+{"version":3,"file":"openspec-format-generator.d.ts","sourceRoot":"","sources":["../../../src/core/generator/openspec-format-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,cAAc,EAOf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAM9D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,cAAc,GAAG,KAAK,GAAG,KAAK,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IAC/B,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAgCD;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,OAAO,CAAkB;gBAErB,OAAO,GAAE,gBAAqB;IAK1C;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,aAAa,EAAE;IAuBzF;;OAEG;IACH,OAAO,CAAC,aAAa;IAmGrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA2G5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiN1B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA+IhC;;OAEG;IACH,OAAO,CAAC,eAAe;IAwGvB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAqB9B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAyE9B;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAuBjB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA2D9D;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,aAAa,EAAE,CAGjB"}

package/dist/core/generator/openspec-format-generator.js

@@ -4,9 +4,6 @@
  * Takes structured LLM outputs and formats them into clean OpenSpec-compatible
  * specification files.
  */
-// ============================================================================
-// CONSTANTS
-// ============================================================================
 const DEFAULT_OPTIONS = {
     version: '1.0.0',
     style: 'detailed',
@@ -23,19 +20,21 @@ const DEFAULT_OPTIONS = {
 export class OpenSpecFormatGenerator {
     options;
     constructor(options = {}) {
-        this.options = { ...DEFAULT_OPTIONS, ...options };
+        const { depGraph, ...rest } = options;
+        this.options = { ...DEFAULT_OPTIONS, ...rest, depGraph };
     }
     /**
-     * Generate all spec files from pipeline result
+     * Generate all spec files from pipeline result.
+     * Pass mappingArtifact to annotate each Requirement with `> Implementation: file:line`.
      */
-    generateSpecs(result) {
+    generateSpecs(result, mappingArtifact) {
         const specs = [];
         const domains = this.groupByDomain(result);
         // 1. Overview spec
         specs.push(this.generateOverviewSpec(result.survey, domains, result.architecture));
         // 2. Domain specs
         for (const domain of domains) {
-            specs.push(this.generateDomainSpec(domain, result.survey));
+            specs.push(this.generateDomainSpec(domain, result.survey, mappingArtifact));
         }
         // 3. Architecture spec
         specs.push(this.generateArchitectureSpec(result.architecture, result.survey, domains));
@@ -250,7 +249,7 @@ export class OpenSpecFormatGenerator {
     /**
      * Generate a domain spec
      */
-    generateDomainSpec(domain, _survey) {
+    generateDomainSpec(domain, _survey, mappingArtifact) {
         const lines = [];
         const now = new Date();
         const date = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')} ${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`;
@@ -332,8 +331,10 @@ export class OpenSpecFormatGenerator {
         // Service operation requirements
         for (const service of domain.services) {
             for (const operation of (service.operations ?? [])) {
-                lines.push(`### Requirement: ${this.formatRequirementName(operation.name)}`);
+                const reqName = this.formatRequirementName(operation.name);
+                lines.push(`### Requirement: ${reqName}`);
                 lines.push('');
+                this.emitImplementationHint(lines, reqName, domain.name, mappingArtifact);
                 const opDesc = (operation.description ?? '').replace(/^\s*(shall|must|should|may)\s+/i, '');
                 lines.push(`The system SHALL ${opDesc.toLowerCase()}`);
                 lines.push('');
@@ -378,6 +379,7 @@ export class OpenSpecFormatGenerator {
                     const reqName = this.formatRequirementName(endpoint.purpose || `${endpoint.method}${endpoint.path}`);
                     lines.push(`### Requirement: ${reqName}`);
                     lines.push('');
+                    this.emitImplementationHint(lines, reqName, domain.name, mappingArtifact);
                     const epPurpose = (endpoint.purpose ?? 'handle this endpoint').replace(/^\s*(shall|must|should|may)\s+/i, '');
                     lines.push(`The system SHALL ${epPurpose.toLowerCase()}`);
                     lines.push('');
@@ -392,6 +394,7 @@ export class OpenSpecFormatGenerator {
                 const reqName = this.formatRequirementName(`${domain.name}Overview`);
                 lines.push(`### Requirement: ${reqName}`);
                 lines.push('');
+                this.emitImplementationHint(lines, reqName, domain.name, mappingArtifact);
                 lines.push(`The ${domain.name} domain SHALL provide its documented functionality.`);
                 lines.push('');
                 lines.push(`#### Scenario: ${reqName}Works`);
@@ -420,6 +423,11 @@ export class OpenSpecFormatGenerator {
             }
             lines.push('');
         }
+        // Cross-domain dependency section (requires depGraph)
+        const depSection = this.buildDependencySection(domain.name, domain.files);
+        if (depSection.length > 0) {
+            lines.push(...depSection);
+        }
         return {
             path: `openspec/specs/${domain.name.toLowerCase()}/spec.md`,
             content: lines.join('\n'),
@@ -645,6 +653,99 @@ export class OpenSpecFormatGenerator {
             type: 'api',
         };
     }
+    /**
+     * Emit `> Implementation: \`file:line\`` after a Requirement header when a
+     * high-confidence mapping entry exists.  Mutates `lines` in-place.
+     */
+    emitImplementationHint(lines, reqName, domainName, mappingArtifact) {
+        if (!mappingArtifact)
+            return;
+        const normReq = reqName.toLowerCase().replace(/[^a-z0-9]/g, '');
+        const match = mappingArtifact.mappings.find(m => {
+            const normM = m.requirement.toLowerCase().replace(/[^a-z0-9]/g, '');
+            return normM === normReq && m.domain.toLowerCase() === domainName.toLowerCase();
+        });
+        if (!match || match.functions.length === 0)
+            return;
+        const best = [...match.functions].sort((a, b) => {
+            const order = { llm: 0, semantic: 1, heuristic: 2 };
+            return (order[a.confidence] ?? 3) - (order[b.confidence] ?? 3);
+        })[0];
+        lines.push(`> Implementation: \`${best.name}\` in \`${best.file}\` · confidence: ${best.confidence}`);
+        lines.push('');
+    }
+    /**
+     * Build `## Dependencies` section for a domain spec using depGraph edges.
+     * Returns an empty array if no depGraph or no cross-domain edges found.
+     */
+    buildDependencySection(domainName, _domainFiles) {
+        const depGraph = this.options.depGraph;
+        if (!depGraph)
+            return [];
+        // Resolve the cluster for this domain from depGraph
+        const cluster = depGraph.clusters.find(c => c.suggestedDomain.toLowerCase() === domainName.toLowerCase());
+        if (!cluster || cluster.files.length === 0)
+            return [];
+        const domainFileSet = new Set(cluster.files);
+        // Build file → cluster mapping
+        const clusterByFile = new Map();
+        for (const c of depGraph.clusters) {
+            for (const f of c.files) {
+                if (!clusterByFile.has(f)) {
+                    clusterByFile.set(f, { id: c.id, suggestedDomain: c.suggestedDomain });
+                }
+            }
+        }
+        // Scan edges for cross-domain calls
+        const callsInto = new Map(); // target domain → imported names
+        const calledBy = new Map(); // source domain → imported names
+        for (const edge of depGraph.edges) {
+            const srcInDomain = domainFileSet.has(edge.source);
+            const tgtInDomain = domainFileSet.has(edge.target);
+            if (srcInDomain === tgtInDomain)
+                continue; // intra-domain or unrelated
+            if (srcInDomain) {
+                const tgtCluster = clusterByFile.get(edge.target);
+                const tgtDomain = tgtCluster?.suggestedDomain.toLowerCase();
+                if (tgtDomain && tgtDomain !== domainName.toLowerCase()) {
+                    if (!callsInto.has(tgtDomain))
+                        callsInto.set(tgtDomain, new Set());
+                    for (const name of (edge.importedNames ?? []))
+                        callsInto.get(tgtDomain).add(name);
+                }
+            }
+            else {
+                const srcCluster = clusterByFile.get(edge.source);
+                const srcDomain = srcCluster?.suggestedDomain.toLowerCase();
+                if (srcDomain && srcDomain !== domainName.toLowerCase()) {
+                    if (!calledBy.has(srcDomain))
+                        calledBy.set(srcDomain, new Set());
+                    for (const name of (edge.importedNames ?? []))
+                        calledBy.get(srcDomain).add(name);
+                }
+            }
+        }
+        if (callsInto.size === 0 && calledBy.size === 0)
+            return [];
+        const lines = ['## Dependencies', ''];
+        if (calledBy.size > 0) {
+            lines.push('### Called by this domain');
+            for (const [srcDomain, names] of [...calledBy.entries()].sort()) {
+                const nameList = [...names].slice(0, 3).map(n => `\`${n}\``).join(', ');
+                lines.push(`- \`${srcDomain}\`${nameList ? ` → ${nameList}` : ''}`);
+            }
+            lines.push('');
+        }
+        if (callsInto.size > 0) {
+            lines.push('### Calls into');
+            for (const [tgtDomain, names] of [...callsInto.entries()].sort()) {
+                const nameList = [...names].slice(0, 3).map(n => `\`${n}\``).join(', ');
+                lines.push(`- \`${tgtDomain}\`${nameList ? ` → ${nameList}` : ''}`);
+            }
+            lines.push('');
+        }
+        return lines;
+    }
     /**
      * Add a scenario to the lines array
      */
@@ -669,7 +770,7 @@ export class OpenSpecFormatGenerator {
             return 'Unnamed';
         return name
             .split(/[\s_-]+/)
-            .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
             .join('');
     }
     /**