token-pilot 0.8.3 → 0.10.0

package/dist/handlers/smart-diff.js

@@ -0,0 +1,257 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve } from 'node:path';
+import { estimateTokens } from '../core/token-estimator.js';
+const execFileAsync = promisify(execFile);
+// ──────────────────────────────────────────────
+// Handler
+// ──────────────────────────────────────────────
+const SMALL_DIFF_THRESHOLD = 30;
+const MAX_FILES = 50;
+const MAX_OUTPUT_LINES = 500;
+export async function handleSmartDiff(args, projectRoot, astIndex) {
+    // 1. Build git command
+    const gitArgs = buildGitArgs(args, projectRoot);
+    // 2. Execute git diff
+    let rawDiff;
+    try {
+        const { stdout } = await execFileAsync('git', gitArgs, {
+            cwd: projectRoot,
+            timeout: 10000,
+            maxBuffer: 5 * 1024 * 1024,
+        });
+        rawDiff = stdout;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('not a git repository') || msg.includes('fatal:')) {
+            return { content: [{ type: 'text', text: 'Not a git repository. smart_diff requires git.' }], rawTokens: 0 };
+        }
+        return { content: [{ type: 'text', text: `git diff failed: ${msg}` }], rawTokens: 0 };
+    }
+    const rawTokens = estimateTokens(rawDiff);
+    if (!rawDiff.trim()) {
+        const scopeLabel = args.scope ?? 'unstaged';
+        return {
+            content: [{ type: 'text', text: `NO CHANGES (${scopeLabel}): working tree is clean.` }],
+            rawTokens: 0,
+        };
+    }
+    // 3. Parse unified diff
+    const fileDiffs = parseUnifiedDiff(rawDiff);
+    if (fileDiffs.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'NO CHANGES: diff parsed but no file changes found.' }],
+            rawTokens,
+        };
+    }
+    // 4. Map hunks to symbols (parallel, capped)
+    const filesToProcess = fileDiffs.slice(0, MAX_FILES);
+    const symbolChanges = new Map();
+    const outlineResults = await Promise.allSettled(filesToProcess
+        .filter(f => !f.isBinary && !f.isDeleted)
+        .map(async (f) => {
+        const absPath = resolve(projectRoot, f.path);
+        const structure = await astIndex.outline(absPath);
+        return { path: f.path, structure };
+    }));
+    for (const result of outlineResults) {
+        if (result.status === 'fulfilled' && result.value.structure) {
+            const { path, structure } = result.value;
+            const fd = filesToProcess.find(f => f.path === path);
+            if (fd) {
+                symbolChanges.set(path, mapHunksToSymbols(fd.hunks, structure));
+            }
+        }
+    }
+    // 5. Format output
+    const output = formatSmartDiff(fileDiffs, filesToProcess, symbolChanges, args, rawTokens);
+    return { content: [{ type: 'text', text: output }], rawTokens };
+}
+// ──────────────────────────────────────────────
+// Git command builder
+// ──────────────────────────────────────────────
+function buildGitArgs(args, projectRoot) {
+    const base = [];
+    switch (args.scope) {
+        case 'staged':
+            base.push('diff', '--cached');
+            break;
+        case 'commit':
+            base.push('show', '--format=', args.ref);
+            break;
+        case 'branch':
+            base.push('diff', `${args.ref}...HEAD`);
+            break;
+        case 'unstaged':
+        default:
+            base.push('diff');
+            break;
+    }
+    if (args.path) {
+        base.push('--', args.path);
+    }
+    return base;
+}
+// ──────────────────────────────────────────────
+// Unified diff parser
+// ──────────────────────────────────────────────
+export function parseUnifiedDiff(raw) {
+    const files = [];
+    let current = null;
+    let currentHunk = null;
+    for (const line of raw.split('\n')) {
+        // New file
+        if (line.startsWith('diff --git ')) {
+            if (current)
+                files.push(current);
+            const match = line.match(/diff --git a\/(.+?) b\/(.+)/);
+            current = {
+                path: match?.[2] ?? '',
+                oldPath: match?.[1] !== match?.[2] ? match?.[1] : undefined,
+                addedLines: 0,
+                removedLines: 0,
+                hunks: [],
+                isBinary: false,
+                isNew: false,
+                isDeleted: false,
+            };
+            currentHunk = null;
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith('new file mode')) {
+            current.isNew = true;
+        }
+        else if (line.startsWith('deleted file mode')) {
+            current.isDeleted = true;
+        }
+        else if (line.startsWith('Binary files')) {
+            current.isBinary = true;
+        }
+        else if (line.startsWith('rename from ')) {
+            current.oldPath = line.slice(12);
+        }
+        else if (line.startsWith('@@ ')) {
+            const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+            currentHunk = {
+                newStart: match ? parseInt(match[1], 10) : 0,
+                newCount: match?.[2] ? parseInt(match[2], 10) : 1,
+                lines: [],
+            };
+            current.hunks.push(currentHunk);
+        }
+        else if (currentHunk) {
+            if (line.startsWith('+') && !line.startsWith('+++')) {
+                current.addedLines++;
+                currentHunk.lines.push(line);
+            }
+            else if (line.startsWith('-') && !line.startsWith('---')) {
+                current.removedLines++;
+                currentHunk.lines.push(line);
+            }
+            else if (line.startsWith(' ')) {
+                currentHunk.lines.push(line);
+            }
+        }
+    }
+    if (current)
+        files.push(current);
+    return files;
+}
+// ──────────────────────────────────────────────
+// Symbol mapping
+// ──────────────────────────────────────────────
+function flattenSymbols(symbols, prefix = '') {
+    const result = [];
+    for (const sym of symbols) {
+        const name = prefix ? `${prefix}.${sym.name}` : sym.name;
+        result.push({
+            name,
+            kind: sym.kind,
+            start: sym.location.startLine,
+            end: sym.location.endLine,
+        });
+        if (sym.children.length > 0) {
+            result.push(...flattenSymbols(sym.children, sym.kind === 'class' || sym.kind === 'interface' ? sym.name : ''));
+        }
+    }
+    return result;
+}
+export function mapHunksToSymbols(hunks, structure) {
+    const allSymbols = flattenSymbols(structure.symbols);
+    const changedSymbols = new Map();
+    for (const hunk of hunks) {
+        const hunkStart = hunk.newStart;
+        const hunkEnd = hunk.newStart + hunk.newCount - 1;
+        for (const sym of allSymbols) {
+            if (hunkStart <= sym.end && hunkEnd >= sym.start) {
+                if (!changedSymbols.has(sym.name)) {
+                    changedSymbols.set(sym.name, {
+                        name: sym.name,
+                        kind: sym.kind,
+                        changeType: 'MODIFIED',
+                        lineRange: `[L${sym.start}-${sym.end}]`,
+                    });
+                }
+            }
+        }
+    }
+    return Array.from(changedSymbols.values());
+}
+// ──────────────────────────────────────────────
+// Output formatter
+// ──────────────────────────────────────────────
+function formatSmartDiff(allFiles, processedFiles, symbolChanges, args, rawTokens) {
+    const totalAdded = allFiles.reduce((s, f) => s + f.addedLines, 0);
+    const totalRemoved = allFiles.reduce((s, f) => s + f.removedLines, 0);
+    const scopeLabel = args.scope ?? 'unstaged';
+    const lines = [];
+    lines.push(`CHANGES: ${allFiles.length} file${allFiles.length !== 1 ? 's' : ''}, +${totalAdded} -${totalRemoved} (${scopeLabel})`);
+    lines.push('');
+    for (const fd of processedFiles) {
+        if (lines.length >= MAX_OUTPUT_LINES) {
+            lines.push(`... truncated (${allFiles.length - processedFiles.indexOf(fd)} more files)`);
+            break;
+        }
+        // File header
+        const changeLabel = fd.isNew ? ' [NEW]' : fd.isDeleted ? ' [DELETED]' : '';
+        const renameLabel = fd.oldPath ? ` (renamed from ${fd.oldPath})` : '';
+        const binaryLabel = fd.isBinary ? ' [BINARY]' : '';
+        lines.push(`${fd.path} (+${fd.addedLines} -${fd.removedLines})${changeLabel}${renameLabel}${binaryLabel}`);
+        if (fd.isBinary) {
+            lines.push('');
+            continue;
+        }
+        // Symbol changes
+        const symbols = symbolChanges.get(fd.path);
+        if (symbols && symbols.length > 0) {
+            for (const sc of symbols) {
+                lines.push(`  ${sc.changeType}: ${sc.name}() ${sc.lineRange}`);
+            }
+        }
+        // Small diff: include actual hunks
+        const totalHunkLines = fd.hunks.reduce((s, h) => s + h.lines.length, 0);
+        if (totalHunkLines <= SMALL_DIFF_THRESHOLD && totalHunkLines > 0) {
+            for (const hunk of fd.hunks) {
+                lines.push(`    @@ L${hunk.newStart}`);
+                for (const hl of hunk.lines) {
+                    lines.push(`    ${hl}`);
+                }
+            }
+        }
+        else if (totalHunkLines > SMALL_DIFF_THRESHOLD) {
+            lines.push(`  (${totalHunkLines} lines changed — use read_symbol for details)`);
+        }
+        lines.push('');
+    }
+    if (allFiles.length > MAX_FILES) {
+        lines.push(`Showing ${MAX_FILES} of ${allFiles.length} changed files. Use path filter to narrow.`);
+        lines.push('');
+    }
+    lines.push(`HINT: Use read_symbol(path, symbol) to see full changed code, read_diff(path) for line-level diff.`);
+    lines.push(`RAW DIFF: ~${rawTokens} tokens → smart_diff: ~${estimateTokens(lines.join('\n'))} tokens`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=smart-diff.js.map

package/dist/server.js

@@ -27,9 +27,12 @@ import { handleReadForEdit } from './handlers/read-for-edit.js';
 import { handleRelatedFiles } from './handlers/related-files.js';
 import { handleOutline } from './handlers/outline.js';
 import { handleCodeAudit } from './handlers/code-audit.js';
+import { handleModuleInfo } from './handlers/module-info.js';
+import { handleSmartDiff } from './handlers/smart-diff.js';
+import { handleExploreArea } from './handlers/explore-area.js';
 import { detectContextMode } from './integration/context-mode-detector.js';
 import { estimateTokens } from './core/token-estimator.js';
-import { resolveSafePath, validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, } from './core/validation.js';
+import { resolveSafePath, validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, } from './core/validation.js';
 export async function createServer(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     const astIndex = new AstIndexClient(projectRoot, config.astIndex.timeout, {
@@ -182,6 +185,8 @@ export async function createServer(projectRoot, options) {
             '• Reading file again → smart_read (returns compact reminder, not full content)',
             '• Multiple files → smart_read_many (batch, max 20)',
             '• Code quality audit → code_audit (TODOs, deprecated, structural code patterns)',
+            '• Reviewing git changes → smart_diff (structural diff with symbol mapping, not raw patch)',
+            '• Starting work on an area → explore_area (outline + imports + tests + git log in one call)',
             '',
             'WHEN TO USE DEFAULT TOOLS (Token Pilot adds no value):',
             '• Small files (≤200 lines) → smart_read returns full content anyway, same as Read',
@@ -198,8 +203,9 @@ export async function createServer(projectRoot, options) {
             '• Text pattern search/counting → Grep (regex, count mode)',
             '• Security audit → Grep for: password, token, secret, credential, hardcoded, api_key, TODO.*security',
             '• Deep dive into specific code → read_symbol (after finding issues)',
+            '• Module architecture → module_info (deps, dependents, public API, unused deps)',
             '',
-            'WORKFLOW: project_overview → smart_read → read_symbol → read_for_edit → edit → read_diff',
+            'WORKFLOW: project_overview → explore_area → smart_read → read_symbol → read_for_edit → edit → smart_diff',
         ].join('\n'),
     });
     server.setRequestHandler(ListToolsRequestSchema, () => ({
@@ -291,21 +297,31 @@ export async function createServer(projectRoot, options) {
             // --- Search & navigation ---
             {
                 name: 'find_usages',
-                description: 'Use INSTEAD OF Grep/ripgrep for finding symbol references. Semantic search across the project — groups results by: definitions, imports, usages.',
+                description: 'Use INSTEAD OF Grep/ripgrep for finding symbol references. Semantic search across the project — groups results by: definitions, imports, usages. (v1.1: added scope, kind, limit, lang filters)',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         symbol: { type: 'string', description: 'Symbol name to find usages of' },
+                        scope: { type: 'string', description: 'Filter results by path prefix (e.g., "src/Domain/")' },
+                        kind: { type: 'string', enum: ['definitions', 'imports', 'usages', 'all'], description: 'Show only specific section (default: "all")' },
+                        limit: { type: 'number', description: 'Max results per category (default: 50, max: 500)' },
+                        lang: { type: 'string', description: 'Filter by language/extension (e.g., "php", "typescript")' },
                     },
                     required: ['symbol'],
                 },
             },
             {
                 name: 'project_overview',
-                description: 'START HERE for unfamiliar codebases. Shows project type, architecture, framework detection, directory structure with symbol counts. Use before exploring code.',
+                description: 'START HERE for unfamiliar codebases. Shows project type (dual-detection: ast-index + config files), architecture, framework detection, quality tools, CI, directory map. (v1.1: added include filter)',
                 inputSchema: {
                     type: 'object',
-                    properties: {},
+                    properties: {
+                        include: {
+                            type: 'array',
+                            items: { type: 'string', enum: ['stack', 'ci', 'quality', 'architecture'] },
+                            description: 'Sections to include (default: all). Use ["stack"] for quick type check, ["quality","ci"] for tooling overview.',
+                        },
+                    },
                 },
             },
             {
@@ -321,11 +337,13 @@ export async function createServer(projectRoot, options) {
             },
             {
                 name: 'outline',
-                description: 'Use INSTEAD OF listing dir + reading each file. One call returns all symbols (classes, functions, methods, routes) for every code file in a directory.',
+                description: 'Use INSTEAD OF listing dir + reading each file. One call returns all symbols (classes, functions, methods, routes) for every code file in a directory. (v1.1: added recursive, max_depth)',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         path: { type: 'string', description: 'Directory path' },
+                        recursive: { type: 'boolean', description: 'Recursively outline subdirectories (default: false)' },
+                        max_depth: { type: 'number', description: 'Max recursion depth when recursive=true (default: 2, max: 5)' },
                     },
                     required: ['path'],
                 },
@@ -371,6 +389,51 @@ export async function createServer(projectRoot, options) {
                     required: ['check'],
                 },
             },
+            {
+                name: 'module_info',
+                description: 'Analyze module dependencies, dependents, public API, and unused deps. Use for architecture understanding and dependency cleanup.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        module: { type: 'string', description: 'Module name or path pattern (e.g., "auth", "src/Domain/")' },
+                        check: {
+                            type: 'string',
+                            enum: ['deps', 'dependents', 'api', 'unused-deps', 'all'],
+                            description: 'What to check: "deps" (dependencies), "dependents" (who depends on this), "api" (public symbols), "unused-deps" (dead dependencies), "all" (everything). Default: "all"',
+                        },
+                    },
+                    required: ['module'],
+                },
+            },
+            // --- Diff & exploration ---
+            {
+                name: 'smart_diff',
+                description: 'Use INSTEAD OF raw git diff. Shows changed files with AST symbol mapping — which functions/classes were modified/added/removed. Small diffs include hunks, large diffs show summary.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        scope: { type: 'string', enum: ['unstaged', 'staged', 'commit', 'branch'], description: 'Diff scope (default: "unstaged")' },
+                        path: { type: 'string', description: 'Filter to specific file or directory' },
+                        ref: { type: 'string', description: 'Git ref — required for scope="commit" (commit hash) or scope="branch" (branch name)' },
+                    },
+                },
+            },
+            {
+                name: 'explore_area',
+                description: 'One-call exploration of a directory: outline (all symbols), imports (external deps + who imports this area), tests (matching test files), recent git changes. Use INSTEAD OF separate outline + related_files + git log calls.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'Directory path (or file path — will use its parent directory)' },
+                        include: {
+                            type: 'array',
+                            items: { type: 'string', enum: ['outline', 'imports', 'tests', 'changes'] },
+                            description: 'Sections to include (default: all)',
+                        },
+                    },
+                    required: ['path'],
+                },
+            },
         ],
     }));
     // Helper: get real full-file token count for honest analytics
@@ -476,7 +539,8 @@ export async function createServer(projectRoot, options) {
                     return usagesResult;
                 }
                 case 'project_overview': {
-                    const overviewResult = await handleProjectOverview(projectRoot, astIndex);
+                    const overviewArgs = validateProjectOverviewArgs(args);
+                    const overviewResult = await handleProjectOverview(overviewArgs, projectRoot, astIndex);
                     const overviewText = overviewResult.content[0]?.text ?? '';
                     overviewResult.content[0] = { type: 'text', text: `TOKEN PILOT v${pkgVersion}\n\n${overviewText}` };
                     const ovTokens = estimateTokens(overviewResult.content[0].text);
@@ -513,6 +577,33 @@ export async function createServer(projectRoot, options) {
                     analytics.record({ tool: 'code_audit', path: auditArgs.check, tokensReturned: estimateTokens(auditText), tokensWouldBe: estimateTokens(auditText), timestamp: Date.now() });
                     return auditResult;
                 }
+                case 'module_info': {
+                    const moduleArgs = validateModuleInfoArgs(args);
+                    const moduleResult = await handleModuleInfo(moduleArgs, projectRoot, astIndex);
+                    const moduleText = moduleResult.content[0]?.text ?? '';
+                    // Estimate: manual analysis would require reading all module files + grepping deps
+                    const moduleWouldBe = estimateTokens(moduleText) * 5;
+                    analytics.record({ tool: 'module_info', path: moduleArgs.module, tokensReturned: estimateTokens(moduleText), tokensWouldBe: moduleWouldBe, timestamp: Date.now() });
+                    return moduleResult;
+                }
+                case 'smart_diff': {
+                    const sdArgs = validateSmartDiffArgs(args);
+                    const sdResult = await handleSmartDiff(sdArgs, projectRoot, astIndex);
+                    const sdText = sdResult.content[0]?.text ?? '';
+                    const sdTokens = estimateTokens(sdText);
+                    analytics.record({ tool: 'smart_diff', path: sdArgs.path ?? sdArgs.scope ?? 'unstaged', tokensReturned: sdTokens, tokensWouldBe: sdResult.rawTokens || sdTokens, timestamp: Date.now() });
+                    return { content: sdResult.content };
+                }
+                case 'explore_area': {
+                    const eaArgs = validateExploreAreaArgs(args);
+                    const eaResult = await handleExploreArea(eaArgs, projectRoot, astIndex);
+                    const eaText = eaResult.content[0]?.text ?? '';
+                    const eaTokens = estimateTokens(eaText);
+                    // Without explore_area, agent would call: outline + related_files + git log = ~3-5x tokens
+                    const eaWouldBe = eaTokens * 4;
+                    analytics.record({ tool: 'explore_area', path: eaArgs.path, tokensReturned: eaTokens, tokensWouldBe: eaWouldBe, timestamp: Date.now() });
+                    return eaResult;
+                }
                 default:
                     return {
                         content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "description": "Save 60-80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
   "type": "module",
   "main": "dist/index.js",