@laitszkin/apollo-toolkit 4.0.11 → 4.1.1

package/packages/tools/codegraph/dist/lib/cmd-verify.test.js

@@ -0,0 +1,139 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import yaml from 'js-yaml';
+/**
+ * REGTEST-1: Verify that the js-yaml based parser (used in `loadOverlay`)
+ * correctly parses object-format YAML function declarations.
+ *
+ * The fix replaced a custom YAML parser with `js-yaml`. The old parser
+ * incorrectly produced raw string fragments like `"name: init"` when
+ * encountering object-format functions:
+ *
+ *   functions:
+ *     - name: init
+ *       in: string
+ *       out: void
+ *
+ * With `js-yaml`, the parser produces actual objects:
+ *   `{ name: "init", in: "string", out: "void" }`
+ *
+ * This test exercises the same parsing path as `loadOverlay`: reading a YAML
+ * file from disk with `fs.readFileSync`, then parsing with `yaml.load`.
+ */
+describe('REGTEST-1: loadOverlay YAML parser', () => {
+    it('should parse object-format functions and correctly extract .name', () => {
+        const yamlStr = [
+            'slug: test-feature',
+            'submodules:',
+            '  - slug: module-a',
+            '    functions:',
+            '      - name: init',
+            '        in: string',
+            '        out: void',
+            'edges:',
+            '  - from: funcA',
+            '    to: funcB',
+            '    kind: call',
+        ].join('\n');
+        // Parse with js-yaml (same library used by loadOverlay)
+        const data = yaml.load(yamlStr);
+        // Verify object-format function parsing
+        const fn = data.submodules[0].functions[0];
+        assert.strictEqual(typeof fn, 'object', 'object-format function should be parsed as object, not string');
+        assert.strictEqual(fn.name, 'init', 'parsed function .name should be "init"');
+        // Verify the old bug is fixed: no raw "name: init" string
+        assert.notStrictEqual(fn, 'name: init', 'function should NOT be a raw string fragment');
+        assert.notStrictEqual(typeof fn, 'string', 'object-format function should not be a string');
+        // Verify additional fields are preserved
+        assert.strictEqual(fn.in, 'string', 'function "in" field should be preserved');
+        assert.strictEqual(fn.out, 'void', 'function "out" field should be preserved');
+        // Verify string-format functions still work
+        // Note: the YAML above only has object-format functions; string format is tested separately
+    });
+    it('should parse string-format functions correctly', () => {
+        const yamlStr = [
+            'slug: test-feature',
+            'submodules:',
+            '  - slug: module-a',
+            '    functions:',
+            '      - init',
+            '      - process',
+        ].join('\n');
+        const data = yaml.load(yamlStr);
+        const functions = data.submodules[0].functions;
+        assert.strictEqual(functions.length, 2, 'should have 2 string-format functions');
+        assert.strictEqual(typeof functions[0], 'string', 'string-format function should be a string');
+        assert.strictEqual(functions[0], 'init', 'string function name should be "init"');
+        assert.strictEqual(functions[1], 'process', 'string function name should be "process"');
+    });
+    it('should parse mixed object and string format functions', () => {
+        const yamlStr = [
+            'slug: test-feature',
+            'submodules:',
+            '  - slug: module-a',
+            '    functions:',
+            '      - name: init',
+            '        in: string',
+            '        out: void',
+            '      - process',
+            '      - name: render',
+            '        in: string',
+            '        out: void',
+            '      - cleanup',
+        ].join('\n');
+        const data = yaml.load(yamlStr);
+        const functions = data.submodules[0].functions;
+        assert.strictEqual(functions.length, 4, 'should have 4 functions total');
+        // Index 0: object-format
+        assert.strictEqual(typeof functions[0], 'object', 'functions[0] should be object');
+        assert.strictEqual(functions[0].name, 'init');
+        // Index 1: string-format
+        assert.strictEqual(typeof functions[1], 'string', 'functions[1] should be string');
+        assert.strictEqual(functions[1], 'process');
+        // Index 2: object-format
+        assert.strictEqual(typeof functions[2], 'object', 'functions[2] should be object');
+        assert.strictEqual(functions[2].name, 'render');
+        // Index 3: string-format
+        assert.strictEqual(typeof functions[3], 'string', 'functions[3] should be string');
+        assert.strictEqual(functions[3], 'cleanup');
+    });
+    it('should parse feature YAML from disk (same path as loadOverlay)', async () => {
+        // Create a temp directory matching the loadOverlay structure
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-verify-test-'));
+        try {
+            const featuresDir = path.join(tmpDir, 'architecture_diff', 'atlas', 'features');
+            fs.mkdirSync(featuresDir, { recursive: true });
+            const yamlPath = path.join(featuresDir, 'test-feature.yaml');
+            fs.writeFileSync(yamlPath, [
+                'slug: test-feature',
+                'submodules:',
+                '  - slug: module-a',
+                '    functions:',
+                '      - name: init',
+                '        in: string',
+                '        out: void',
+                '    edges:',
+                '      - from: funcA',
+                '        to: funcB',
+                '        kind: call',
+            ].join('\n') + '\n');
+            // Read file and parse (same as loadOverlay)
+            const raw = fs.readFileSync(yamlPath, 'utf8');
+            const data = yaml.load(raw);
+            assert.ok(data, 'parsed data should be truthy');
+            assert.strictEqual(typeof data, 'object', 'parsed data should be an object');
+            assert.strictEqual(data.slug, 'test-feature', 'feature slug should be preserved');
+            const fn = data.submodules[0].functions[0];
+            assert.strictEqual(typeof fn, 'object', 'object-format function parsed from file should be object');
+            assert.strictEqual(fn.name, 'init', 'function .name should be "init"');
+            assert.strictEqual(fn.in, 'string', 'function .in should be "string"');
+            assert.strictEqual(fn.out, 'void', 'function .out should be "void"');
+        }
+        finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});

package/packages/tools/codegraph/dist/lib/formatter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Format structured data for CLI output.
+ *
+ * - TTY mode produces human-readable tables and headings.
+ * - Non-TTY or `--json` produces JSON.stringify with 2-space indent.
+ * - Auto-detects TTY via `process.stdout.isTTY`.
+ */
+export interface FormatOptions {
+    json?: boolean;
+    tty?: boolean;
+}
+/**
+ * Format generic data for output.
+ */
+export declare function formatOutput(data: unknown, options?: FormatOptions): string;
+/**
+ * Format a key-value summary block for human-readable output.
+ * Example:
+ *   Files:       42
+ *   Nodes:     1280
+ *   Edges:     5600
+ */
+export declare function formatSummary(rows: [string, string | number][]): string;
+/**
+ * Format a list of search results as a human-readable table.
+ */
+export declare function formatSearchResults(results: Array<{
+    node: {
+        name: string;
+        kind: string;
+        filePath: string;
+        startLine: number;
+    };
+    score: number;
+}>): string;
+/**
+ * Format an API directory listing for human-readable output.
+ */
+export declare function formatApiList(apis: Array<{
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    signature?: string;
+    callerCount: number;
+    callers?: Array<{
+        name: string;
+        filePath: string;
+        startLine: number;
+    }>;
+}>): string;
+/**
+ * Format an API listing grouped by directory.
+ */
+export declare function formatApiListGrouped(apis: Array<{
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    signature?: string;
+    callerCount: number;
+    callers?: Array<{
+        name: string;
+        filePath: string;
+        startLine: number;
+    }>;
+}>): string;

package/packages/tools/codegraph/dist/lib/formatter.js

@@ -0,0 +1,107 @@
+/**
+ * Format structured data for CLI output.
+ *
+ * - TTY mode produces human-readable tables and headings.
+ * - Non-TTY or `--json` produces JSON.stringify with 2-space indent.
+ * - Auto-detects TTY via `process.stdout.isTTY`.
+ */
+function isTTY(options) {
+    if (options.json)
+        return false;
+    if (options.tty !== undefined)
+        return options.tty;
+    return !!process.stdout.isTTY;
+}
+/**
+ * Format generic data for output.
+ */
+export function formatOutput(data, options = {}) {
+    if (!isTTY(options)) {
+        return JSON.stringify(data, null, 2);
+    }
+    // Fallback: JSON for complex objects in TTY too
+    if (typeof data === 'string')
+        return data;
+    if (data === null || data === undefined)
+        return '';
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * Format a key-value summary block for human-readable output.
+ * Example:
+ *   Files:       42
+ *   Nodes:     1280
+ *   Edges:     5600
+ */
+export function formatSummary(rows) {
+    const width = rows.reduce((max, [key]) => Math.max(max, key.length + 1), 0);
+    return rows
+        .map(([key, val]) => `${key.padEnd(width, ' ')} ${val}`)
+        .join('\n');
+}
+/**
+ * Format a list of search results as a human-readable table.
+ */
+export function formatSearchResults(results) {
+    if (results.length === 0)
+        return 'No results found.';
+    const lines = results.map((r, i) => {
+        const score = (r.score * 100).toFixed(0);
+        return `  ${i + 1}. ${r.node.name}  [${r.node.kind}]  ${r.node.filePath}:${r.node.startLine}  (${score}%)`;
+    });
+    return `Results (${results.length}):\n${lines.join('\n')}`;
+}
+/**
+ * Format an API directory listing for human-readable output.
+ */
+export function formatApiList(apis) {
+    if (apis.length === 0)
+        return 'No public APIs found.';
+    const lines = [];
+    for (const a of apis) {
+        const sig = a.signature ? `  ${a.signature}` : '';
+        lines.push(`  ${a.name}  [${a.kind}]  ${a.filePath}:${a.startLine}  (${a.callerCount} callers)${sig}`);
+        if (a.callerCount > 0 && a.callers) {
+            const callerLines = a.callers.slice(0, 5).map(c => `      Called by: ${c.name}  ${c.filePath}:${c.startLine}`);
+            lines.push(...callerLines);
+            if (a.callerCount > 5)
+                lines.push(`      ... and ${a.callerCount - 5} more`);
+        }
+    }
+    return `APIs (${apis.length}):\n${lines.join('\n')}`;
+}
+/**
+ * Format an API listing grouped by directory.
+ */
+export function formatApiListGrouped(apis) {
+    if (apis.length === 0)
+        return 'No public APIs found.';
+    // Group by directory
+    const groups = new Map();
+    for (const a of apis) {
+        const dir = a.filePath.substring(0, a.filePath.lastIndexOf('/'));
+        if (!groups.has(dir))
+            groups.set(dir, []);
+        groups.get(dir).push(a);
+    }
+    // Render with directory headers
+    const lines = [];
+    const sortedDirs = [...groups.keys()].sort();
+    for (const dir of sortedDirs) {
+        const entries = groups.get(dir);
+        lines.push('');
+        lines.push(`=== ${dir}/ ===`);
+        for (const a of entries) {
+            const sig = a.signature ? `  ${a.signature}` : '';
+            lines.push(`  ${a.name}  [${a.kind}]  ${a.filePath}:${a.startLine}  (${a.callerCount} callers)${sig}`);
+            if (a.callerCount > 0 && a.callers) {
+                const callerLines = a.callers.slice(0, 5).map(c => `      Called by: ${c.name}  ${c.filePath}:${c.startLine}`);
+                lines.push(...callerLines);
+                if (a.callerCount > 5)
+                    lines.push(`      ... and ${a.callerCount - 5} more`);
+            }
+        }
+    }
+    lines.push('');
+    return lines.join('\n').trimStart();
+}

package/packages/tools/codegraph/dist/lib/formatter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/packages/tools/codegraph/dist/lib/formatter.test.js

@@ -0,0 +1,41 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { formatApiList } from './formatter.js';
+describe('formatApiList', () => {
+    it('should show caller names in output when callers exist', () => {
+        const apis = [
+            {
+                name: 'myFunc',
+                kind: 'function',
+                filePath: 'src/a.ts',
+                startLine: 10,
+                callerCount: 3,
+                callers: [
+                    { name: 'callerOne', filePath: 'src/b.ts', startLine: 5 },
+                    { name: 'callerTwo', filePath: 'src/c.ts', startLine: 15 },
+                    { name: 'callerThree', filePath: 'src/d.ts', startLine: 25 },
+                ],
+            },
+        ];
+        const output = formatApiList(apis);
+        assert.ok(output.includes('callerOne'), 'output should contain callerOne');
+        assert.ok(output.includes('callerTwo'), 'output should contain callerTwo');
+        assert.ok(output.includes('callerThree'), 'output should contain callerThree');
+        assert.ok(output.includes('(3 callers)'), 'output should show caller count');
+        assert.ok(output.includes('myFunc'), 'output should contain function name');
+    });
+    it('should show "(0 callers)" when there are no callers', () => {
+        const apis = [
+            {
+                name: 'noCallers',
+                kind: 'function',
+                filePath: 'src/a.ts',
+                startLine: 1,
+                callerCount: 0,
+            },
+        ];
+        const output = formatApiList(apis);
+        assert.ok(output.includes('(0 callers)'), 'output should show zero callers');
+        assert.ok(!output.includes('Called by:'), 'output should not contain caller lines');
+    });
+});

package/packages/tools/codegraph/dist/lib/survey/grouper.d.ts

@@ -0,0 +1,19 @@
+import type { ScanResult } from './scanner.js';
+export interface SubmoduleSuggestion {
+    slug: string;
+    kind: 'api' | 'service' | 'db' | 'ui' | 'pure-fn' | 'queue';
+    role: string;
+    memberFunctions: string[];
+    memberFiles: string[];
+}
+/**
+ * Group scanned symbols into suggested submodule groupings.
+ *
+ * Algorithm (hybrid):
+ * 1. Build adjacency map from call graph: for each symbol, find callees within the scan
+ * 2. BFS on undirected graph to find connected components
+ * 3. Components with >=2 symbols create connectivity-based submodule suggestions
+ * 4. Remaining (isolated) symbols fall back to per-file grouping
+ * 5. Apply mergeByDirectoryPrefix as final step
+ */
+export declare function groupIntoSubmodules(scan: ScanResult, cg: any): SubmoduleSuggestion[];

package/packages/tools/codegraph/dist/lib/survey/grouper.js

@@ -0,0 +1,194 @@
+/**
+ * Group scanned symbols into suggested submodule groupings.
+ *
+ * Algorithm (hybrid):
+ * 1. Build adjacency map from call graph: for each symbol, find callees within the scan
+ * 2. BFS on undirected graph to find connected components
+ * 3. Components with >=2 symbols create connectivity-based submodule suggestions
+ * 4. Remaining (isolated) symbols fall back to per-file grouping
+ * 5. Apply mergeByDirectoryPrefix as final step
+ */
+export function groupIntoSubmodules(scan, cg) {
+    if (scan.allSymbols.length === 0)
+        return [];
+    // --- Phase 1: Build adjacency map from call graph connectivity ---
+    const allNameSet = new Set(scan.allSymbols.map(s => s.name));
+    const adj = new Map();
+    const nodeKeyMap = new Map();
+    for (const sym of scan.allSymbols) {
+        const key = `${sym.filePath}::${sym.name}`;
+        const calleeSet = new Set();
+        adj.set(key, calleeSet);
+        nodeKeyMap.set(key, sym);
+        const nodes = cg.getNodesByName(sym.name);
+        for (const node of nodes) {
+            if (node.filePath !== sym.filePath)
+                continue;
+            const callees = cg.getCallees(node.id);
+            for (const callee of callees) {
+                if (allNameSet.has(callee.node.name)) {
+                    calleeSet.add(callee.node.name);
+                }
+            }
+        }
+    }
+    // Build reverse index: name -> list of symbol keys (for efficient BFS lookup)
+    const nameToKeys = new Map();
+    for (const [key, sym] of nodeKeyMap.entries()) {
+        const arr = nameToKeys.get(sym.name) || [];
+        arr.push(key);
+        nameToKeys.set(sym.name, arr);
+    }
+    // --- Phase 2: BFS to find connected components (undirected graph) ---
+    const visited = new Set();
+    const components = [];
+    for (const key of adj.keys()) {
+        if (visited.has(key))
+            continue;
+        const component = [];
+        const queue = [key];
+        visited.add(key);
+        while (queue.length > 0) {
+            const currentKey = queue.shift();
+            const sym = nodeKeyMap.get(currentKey);
+            component.push(sym);
+            const calleeNames = adj.get(currentKey) || new Set();
+            for (const calleeName of calleeNames) {
+                const targetKeys = nameToKeys.get(calleeName) || [];
+                for (const tk of targetKeys) {
+                    if (!visited.has(tk)) {
+                        visited.add(tk);
+                        queue.push(tk);
+                    }
+                }
+            }
+        }
+        if (component.length > 0) {
+            components.push(component);
+        }
+    }
+    // --- Phase 3: Build suggestions from connected components ---
+    const suggestions = [];
+    const processed = new Set();
+    // Components with >=2 symbols become connectivity-based submodules
+    for (const component of components) {
+        if (component.length < 2)
+            continue;
+        const files = [...new Set(component.map(s => s.filePath))];
+        const representativePath = files[0];
+        const fileName = representativePath.split('/').pop() || '';
+        const slug = fileName.replace(/\.\w+$/, '').replace(/[_ ]/g, '-').toLowerCase();
+        const kind = inferKind(representativePath, component);
+        const role = inferRole(kind, slug, component.filter(s => s.isExported));
+        for (const s of component) {
+            processed.add(`${s.filePath}::${s.name}`);
+        }
+        suggestions.push({
+            slug,
+            kind,
+            role,
+            memberFunctions: [...new Set(component.map(s => s.name))],
+            memberFiles: files,
+        });
+    }
+    // --- Phase 4: Remaining (isolated) symbols fall back to per-file grouping ---
+    for (const file of scan.files) {
+        const unprocessedSymbols = file.symbols.filter(s => !processed.has(`${file.filePath}::${s.name}`));
+        if (unprocessedSymbols.length === 0 && file.symbols.length === 0)
+            continue;
+        const fileName = file.filePath.split('/').pop() || '';
+        const slug = fileName.replace(/\.\w+$/, '').replace(/[_ ]/g, '-').toLowerCase();
+        const kind = inferKind(file.filePath, file.symbols);
+        const symbols = unprocessedSymbols.map(s => s.name);
+        if (symbols.length === 0)
+            continue;
+        for (const s of unprocessedSymbols)
+            processed.add(`${file.filePath}::${s.name}`);
+        const role = inferRole(kind, slug, file.symbols.filter(s => s.isExported));
+        suggestions.push({
+            slug,
+            kind,
+            role,
+            memberFunctions: symbols,
+            memberFiles: [file.filePath],
+        });
+    }
+    // --- Phase 5: Merge small files sharing a directory prefix ---
+    const merged = mergeByDirectoryPrefix(suggestions, scan.directory);
+    return merged;
+}
+function inferKind(filePath, symbols) {
+    const lower = filePath.toLowerCase();
+    // Detect by path patterns
+    if (lower.includes('/api/') || lower.includes('/routes/') || lower.includes('/controller'))
+        return 'api';
+    if (lower.includes('/db/') || lower.includes('/model/') || lower.includes('/repository') || lower.includes('/schema'))
+        return 'db';
+    if (lower.includes('/ui/') || lower.includes('/component/') || lower.includes('/page/') || lower.includes('/view'))
+        return 'ui';
+    if (lower.includes('/queue/') || lower.includes('/job/') || lower.includes('/worker'))
+        return 'queue';
+    // Detect by symbol kinds
+    const hasHandler = symbols.some((s) => s.kind === 'route' || s.kind === 'component');
+    if (hasHandler)
+        return 'api';
+    const hasModel = symbols.some((s) => s.kind === 'interface' || s.kind === 'struct');
+    if (hasModel)
+        return 'db';
+    return 'service';
+}
+function inferRole(kind, slug, exportedSymbols) {
+    const name = slug.replace(/-/g, ' ');
+    switch (kind) {
+        case 'api':
+            return `Handles API requests for ${name}`;
+        case 'db':
+            return `Manages data access and persistence for ${name}`;
+        case 'service':
+            return `Contains business logic for ${name}`;
+        case 'ui':
+            return `Renders UI components for ${name}`;
+        case 'queue':
+            return `Processes background jobs for ${name}`;
+        case 'pure-fn':
+            return `Provides pure utility functions for ${name}`;
+        default:
+            return `Supports ${name} functionality`;
+    }
+}
+function mergeByDirectoryPrefix(suggestions, _directory) {
+    // When there are many single-file suggestions, merge those
+    // that share a common 2-segment directory prefix
+    const prefixMap = new Map();
+    for (const s of suggestions) {
+        if (s.memberFiles.length !== 1) {
+            // Already contains multiple files, keep as-is
+            const key = s.slug;
+            prefixMap.set(key, s);
+            continue;
+        }
+        const filePath = s.memberFiles[0];
+        const parts = filePath.split('/');
+        // Use the parent directory as merge key for files in subdirs
+        const mergeKey = parts.length >= 3 ? parts.slice(0, -1).join('/') : s.slug;
+        if (prefixMap.has(mergeKey)) {
+            const existing = prefixMap.get(mergeKey);
+            existing.memberFunctions.push(...s.memberFunctions);
+            existing.memberFiles.push(...s.memberFiles);
+            // Keep more specific kind
+            if (existing.kind === 'service' && s.kind !== 'service') {
+                existing.kind = s.kind;
+            }
+        }
+        else {
+            prefixMap.set(mergeKey, {
+                slug: mergeKey.replace(/\//g, '-'),
+                kind: s.kind,
+                role: s.role,
+                memberFunctions: [...s.memberFunctions],
+                memberFiles: [...s.memberFiles],
+            });
+        }
+    }
+    return Array.from(prefixMap.values());
+}

package/packages/tools/codegraph/dist/lib/survey/grouper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/packages/tools/codegraph/dist/lib/survey/grouper.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { groupIntoSubmodules } from './grouper.js';
+describe('groupIntoSubmodules', () => {
+    it('groups connected call graph symbols into one submodule (hybrid connectivity grouping)', () => {
+        // -----------------------------------------------------------------------
+        // GIVEN a scan result with functions A, B, C where A calls B and B calls C
+        // (all in the same file, forming a connected chain)
+        // -----------------------------------------------------------------------
+        const filePath = 'src/module.ts';
+        const scan = {
+            directory: 'src',
+            files: [
+                {
+                    filePath,
+                    language: 'typescript',
+                    symbols: [
+                        { name: 'A', kind: 'function', qualifiedName: 'A', startLine: 1, endLine: 5, isExported: true },
+                        { name: 'B', kind: 'function', qualifiedName: 'B', startLine: 6, endLine: 10, isExported: true },
+                        { name: 'C', kind: 'function', qualifiedName: 'C', startLine: 11, endLine: 15, isExported: false },
+                    ],
+                },
+            ],
+            allSymbols: [
+                { name: 'A', kind: 'function', filePath, qualifiedName: 'A', startLine: 1, isExported: true },
+                { name: 'B', kind: 'function', filePath, qualifiedName: 'B', startLine: 6, isExported: true },
+                { name: 'C', kind: 'function', filePath, qualifiedName: 'C', startLine: 11, isExported: false },
+            ],
+            totalFiles: 1,
+            totalSymbols: 3,
+        };
+        // Mock call graph: A -> B -> C
+        const mockCg = {
+            getNodesByName(name) {
+                const nodeId = `node-${name}`;
+                return [{ id: nodeId, filePath }];
+            },
+            getCallees(nodeId) {
+                const calleeMap = {
+                    'node-A': ['B'],
+                    'node-B': ['C'],
+                    'node-C': [],
+                };
+                return (calleeMap[nodeId] || []).map((calleeName) => ({
+                    node: { name: calleeName },
+                }));
+            },
+        };
+        // -----------------------------------------------------------------------
+        // WHEN groupIntoSubmodules(scan, mockCg) runs
+        // -----------------------------------------------------------------------
+        const result = groupIntoSubmodules(scan, mockCg);
+        // -----------------------------------------------------------------------
+        // THEN A, B, C are grouped into one submodule
+        //   (connectivity-based grouping takes priority over per-file isolation)
+        // -----------------------------------------------------------------------
+        assert.equal(result.length, 1, 'should produce exactly one submodule');
+        const sortedMembers = [...result[0].memberFunctions].sort();
+        assert.deepEqual(sortedMembers, ['A', 'B', 'C'], 'should contain A, B, C');
+        assert.ok(result[0].memberFiles.includes(filePath), 'should include the source file in memberFiles');
+    });
+});

package/packages/tools/codegraph/dist/lib/survey/scanner.d.ts

@@ -0,0 +1,31 @@
+export interface FileScan {
+    filePath: string;
+    language: string;
+    symbols: Array<{
+        name: string;
+        kind: string;
+        qualifiedName: string;
+        startLine: number;
+        endLine: number;
+        isExported: boolean;
+        signature?: string;
+    }>;
+}
+export interface ScanResult {
+    directory: string;
+    files: FileScan[];
+    allSymbols: Array<{
+        name: string;
+        kind: string;
+        filePath: string;
+        qualifiedName: string;
+        startLine: number;
+        isExported: boolean;
+    }>;
+    totalFiles: number;
+    totalSymbols: number;
+}
+/**
+ * Scan a directory for all files and symbols tracked by CodeGraph.
+ */
+export declare function scanDirectory(cg: any, dirPath: string): Promise<ScanResult>;