token-pilot 0.8.3 → 0.10.0

package/dist/handlers/explore-area.js

@@ -0,0 +1,280 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readdir, stat } from 'node:fs/promises';
+import { resolve, relative, basename, dirname } from 'node:path';
+import { resolveSafePath } from '../core/validation.js';
+import { outlineDir, CODE_EXTENSIONS } from './outline.js';
+const execFileAsync = promisify(execFile);
+// ──────────────────────────────────────────────
+// Constants
+// ──────────────────────────────────────────────
+const MAX_IMPORT_FILES = 20;
+const MAX_OUTPUT_LINES = 500;
+// ──────────────────────────────────────────────
+// Handler
+// ──────────────────────────────────────────────
+export async function handleExploreArea(args, projectRoot, astIndex) {
+    // Resolve path — if it points to a file, use its parent directory
+    let absPath = resolveSafePath(projectRoot, args.path);
+    const pathStat = await stat(absPath).catch(() => null);
+    if (!pathStat) {
+        return {
+            content: [{ type: 'text', text: `Path "${args.path}" not found.` }],
+        };
+    }
+    if (!pathStat.isDirectory()) {
+        absPath = dirname(absPath);
+    }
+    const relDir = relative(projectRoot, absPath) || '.';
+    const include = args.include ?? ['outline', 'imports', 'tests', 'changes'];
+    // Collect code files for import/test analysis
+    const codeFiles = await listCodeFiles(absPath);
+    // Run all sections in parallel
+    const [outlineSection, importsSection, testsSection, changesSection] = await Promise.allSettled([
+        include.includes('outline') ? buildOutlineSection(absPath, projectRoot, astIndex) : Promise.resolve(null),
+        include.includes('imports') ? buildImportsSection(codeFiles, absPath, projectRoot, astIndex) : Promise.resolve(null),
+        include.includes('tests') ? buildTestsSection(codeFiles, absPath, projectRoot) : Promise.resolve(null),
+        include.includes('changes') ? buildChangesSection(relDir, projectRoot) : Promise.resolve(null),
+    ]);
+    // Assemble output
+    const lines = [];
+    const subdirCount = await countSubdirs(absPath);
+    lines.push(`AREA: ${relDir}/ (${codeFiles.length} code files${subdirCount > 0 ? `, ${subdirCount} subdirs` : ''})`);
+    lines.push('');
+    // Outline
+    const outlineLines = extractResult(outlineSection);
+    if (outlineLines) {
+        lines.push('STRUCTURE:');
+        lines.push(...outlineLines);
+        lines.push('');
+    }
+    // Imports
+    const importLines = extractResult(importsSection);
+    if (importLines) {
+        lines.push(...importLines);
+    }
+    // Tests
+    const testLines = extractResult(testsSection);
+    if (testLines) {
+        lines.push(...testLines);
+    }
+    // Changes
+    const changeLines = extractResult(changesSection);
+    if (changeLines) {
+        lines.push(...changeLines);
+    }
+    // Truncate if needed
+    if (lines.length > MAX_OUTPUT_LINES) {
+        lines.length = MAX_OUTPUT_LINES;
+        lines.push('... truncated. Use outline() on specific subdirectories for details.');
+    }
+    lines.push('HINT: Use smart_read(file) for details, read_symbol(path, symbol) for source code, find_usages(symbol) for references.');
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+// ──────────────────────────────────────────────
+// Outline section — reuses outlineDir from outline.ts
+// ──────────────────────────────────────────────
+async function buildOutlineSection(absPath, projectRoot, astIndex) {
+    const sections = [];
+    await outlineDir(absPath, sections, 0, 2, projectRoot, astIndex);
+    return sections;
+}
+// ──────────────────────────────────────────────
+// Imports section — aggregate external deps + who imports this area
+// ──────────────────────────────────────────────
+async function buildImportsSection(codeFiles, absPath, projectRoot, astIndex) {
+    if (!astIndex.isAvailable() || astIndex.isDisabled() || astIndex.isOversized()) {
+        return [];
+    }
+    const filesToAnalyze = codeFiles.slice(0, MAX_IMPORT_FILES);
+    const externalDeps = new Set();
+    const internalDeps = new Set();
+    const relDir = relative(projectRoot, absPath) || '.';
+    // Get imports for each file
+    const importResults = await Promise.allSettled(filesToAnalyze.map(f => astIndex.fileImports(f)));
+    for (const result of importResults) {
+        if (result.status !== 'fulfilled' || !result.value)
+            continue;
+        for (const imp of result.value) {
+            const source = imp.source;
+            if (!source)
+                continue;
+            if (source.startsWith('.') || source.startsWith('/')) {
+                // Internal import — track if it's outside this area
+                const resolved = resolve(absPath, source);
+                if (!resolved.startsWith(absPath)) {
+                    const relImport = relative(projectRoot, resolved).replace(/\.[^.]+$/, '');
+                    internalDeps.add(relImport);
+                }
+            }
+            else {
+                // External package
+                const pkg = source.startsWith('@') ? source.split('/').slice(0, 2).join('/') : source.split('/')[0];
+                externalDeps.add(pkg);
+            }
+        }
+    }
+    // Find who imports files from this area (reverse dependencies)
+    const importedBy = new Set();
+    const fileBasenames = filesToAnalyze.map(f => basename(f).replace(/\.[^.]+$/, ''));
+    const refResults = await Promise.allSettled(fileBasenames.slice(0, 10).map(name => astIndex.refs(name, 10)));
+    for (const result of refResults) {
+        if (result.status !== 'fulfilled' || !result.value)
+            continue;
+        const refs = result.value;
+        if (refs.imports) {
+            for (const imp of refs.imports) {
+                const impFile = imp.path;
+                if (!impFile)
+                    continue;
+                const relFile = relative(projectRoot, impFile);
+                // Only include files outside this area
+                if (!relFile.startsWith(relDir)) {
+                    importedBy.add(relFile.replace(/\.[^.]+$/, ''));
+                }
+            }
+        }
+    }
+    const lines = [];
+    if (externalDeps.size > 0) {
+        const deps = Array.from(externalDeps).sort().slice(0, 20);
+        lines.push(`IMPORTS: ${deps.join(', ')}${externalDeps.size > 20 ? ` ... (${externalDeps.size} total)` : ''}`);
+    }
+    if (internalDeps.size > 0) {
+        const deps = Array.from(internalDeps).sort().slice(0, 10);
+        lines.push(`INTERNAL DEPS: ${deps.join(', ')}${internalDeps.size > 10 ? ` ... (${internalDeps.size} total)` : ''}`);
+    }
+    if (importedBy.size > 0) {
+        const importers = Array.from(importedBy).sort().slice(0, 10);
+        lines.push(`IMPORTED BY: ${importers.join(', ')}${importedBy.size > 10 ? ` ... (${importedBy.size} total)` : ''}`);
+    }
+    if (lines.length > 0)
+        lines.push('');
+    return lines;
+}
+// ──────────────────────────────────────────────
+// Tests section — find test/spec files matching area files
+// ──────────────────────────────────────────────
+async function buildTestsSection(codeFiles, absPath, projectRoot) {
+    const testFiles = [];
+    const areaFileNames = new Set(codeFiles.map(f => basename(f).replace(/\.[^.]+$/, '')));
+    // Scan for test files: check area dir + common test dirs
+    const dirsToScan = [absPath];
+    // Check for sibling __tests__ or tests directory
+    const parent = dirname(absPath);
+    const areaName = basename(absPath);
+    const testDirCandidates = [
+        resolve(absPath, '__tests__'),
+        resolve(absPath, 'tests'),
+        resolve(absPath, 'test'),
+        resolve(parent, '__tests__', areaName),
+        resolve(parent, 'tests', areaName),
+    ];
+    for (const testDir of testDirCandidates) {
+        const testDirStat = await stat(testDir).catch(() => null);
+        if (testDirStat?.isDirectory()) {
+            dirsToScan.push(testDir);
+        }
+    }
+    // Also check project-level test directories
+    const projectTestDirs = [
+        resolve(projectRoot, 'tests'),
+        resolve(projectRoot, 'test'),
+        resolve(projectRoot, '__tests__'),
+    ];
+    for (const testDir of projectTestDirs) {
+        if (dirsToScan.includes(testDir))
+            continue;
+        const testDirStat = await stat(testDir).catch(() => null);
+        if (testDirStat?.isDirectory()) {
+            dirsToScan.push(testDir);
+        }
+    }
+    for (const dir of dirsToScan) {
+        try {
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                const name = entry.name;
+                if (name.includes('.test.') || name.includes('.spec.') || name.includes('_test.') || name.includes('_spec.')) {
+                    // Check if this test corresponds to an area file
+                    const testBase = name
+                        .replace(/\.(test|spec)\./, '.')
+                        .replace(/_(test|spec)\./, '.')
+                        .replace(/\.[^.]+$/, '');
+                    if (areaFileNames.has(testBase) || dir !== absPath) {
+                        const relPath = relative(projectRoot, resolve(dir, name));
+                        if (!testFiles.includes(relPath)) {
+                            testFiles.push(relPath);
+                        }
+                    }
+                }
+            }
+        }
+        catch { /* skip unreadable dirs */ }
+    }
+    if (testFiles.length === 0)
+        return [];
+    const lines = [];
+    lines.push(`TESTS: ${testFiles.join(', ')}`);
+    lines.push('');
+    return lines;
+}
+// ──────────────────────────────────────────────
+// Changes section — recent git log for this area
+// ──────────────────────────────────────────────
+async function buildChangesSection(relDir, projectRoot) {
+    try {
+        const { stdout } = await execFileAsync('git', ['log', '--oneline', '-5', '--', relDir], { cwd: projectRoot, timeout: 5000 });
+        if (!stdout.trim())
+            return [];
+        const lines = [];
+        lines.push('RECENT CHANGES:');
+        for (const line of stdout.trim().split('\n')) {
+            lines.push(`  ${line}`);
+        }
+        lines.push('');
+        return lines;
+    }
+    catch {
+        return [];
+    }
+}
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+function extractResult(settled) {
+    if (settled.status === 'fulfilled' && settled.value && settled.value.length > 0) {
+        return settled.value;
+    }
+    return null;
+}
+async function listCodeFiles(dirPath) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            if (entry.isFile()) {
+                const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
+                if (CODE_EXTENSIONS.has(ext)) {
+                    files.push(resolve(dirPath, entry.name));
+                }
+            }
+        }
+        return files.sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function countSubdirs(dirPath) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        return entries.filter(e => e.isDirectory()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=explore-area.js.map

package/dist/handlers/find-usages.d.ts

@@ -1,7 +1,5 @@
 import type { AstIndexClient } from '../ast-index/client.js';
-export interface FindUsagesArgs {
-    symbol: string;
-}
+import type { FindUsagesArgs } from '../core/validation.js';
 /**
  * Find all usages of a symbol across the project.
  *
@@ -9,6 +7,8 @@ export interface FindUsagesArgs {
  * with `search` (text: catches imports and self-references that refs misses).
  * Filter search results to exact word matches only (no substring matches).
  * Deduplicate by file:line.
+ *
+ * v1.1: added scope, kind, limit, lang post-filters.
  */
 export declare function handleFindUsages(args: FindUsagesArgs, astIndex: AstIndexClient): Promise<{
     content: Array<{

package/dist/handlers/find-usages.js

@@ -4,6 +4,23 @@
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+/** Extension map for lang filter (best-effort) */
+const LANG_EXT_MAP = {
+    typescript: ['.ts', '.tsx'],
+    javascript: ['.js', '.jsx', '.mjs', '.cjs'],
+    php: ['.php'],
+    python: ['.py'],
+    rust: ['.rs'],
+    go: ['.go'],
+    java: ['.java'],
+    ruby: ['.rb'],
+    csharp: ['.cs'],
+    kotlin: ['.kt', '.kts'],
+    swift: ['.swift'],
+    dart: ['.dart'],
+    vue: ['.vue'],
+    svelte: ['.svelte'],
+};
 /**
  * Find all usages of a symbol across the project.
  *
@@ -11,6 +28,8 @@ function escapeRegex(s) {
  * with `search` (text: catches imports and self-references that refs misses).
  * Filter search results to exact word matches only (no substring matches).
  * Deduplicate by file:line.
+ *
+ * v1.1: added scope, kind, limit, lang post-filters.
  */
 export async function handleFindUsages(args, astIndex) {
     if (astIndex.isDisabled() || astIndex.isOversized()) {
@@ -47,29 +66,89 @@ export async function handleFindUsages(args, astIndex) {
     // Categorize additional results
     const additionalImports = additional.filter(r => /\bimport\b/.test(r.text));
     const additionalOther = additional.filter(r => !/\bimport\b/.test(r.text));
-    // Merge imports: refs.imports + additional imports
-    const allImports = [
+    // Build mutable result arrays
+    let definitions = refs.definitions.map(d => ({ file: d.path, line: d.line, text: (d.signature ?? d.name).trim() }));
+    let allImports = [
         ...refs.imports.map(i => ({ file: i.path, line: i.line, text: (i.context ?? i.name).trim() })),
         ...additionalImports.map(r => ({ file: r.file, line: r.line, text: r.text })),
     ];
-    // Total count
-    const totalCount = refs.definitions.length + allImports.length + refs.usages.length + additionalOther.length;
+    let allUsages = [
+        ...refs.usages.map(u => ({ file: u.path, line: u.line, text: (u.context ?? u.name).trim() })),
+        ...additionalOther,
+    ];
+    // ─── Post-filters (v1.1) ───
+    // 1. Scope filter — by path prefix
+    if (args.scope) {
+        const scopePrefix = args.scope;
+        definitions = definitions.filter(d => d.file.includes(scopePrefix));
+        allImports = allImports.filter(i => i.file.includes(scopePrefix));
+        allUsages = allUsages.filter(u => u.file.includes(scopePrefix));
+    }
+    // 2. Lang filter — best-effort by file extension
+    if (args.lang) {
+        const langLower = args.lang.toLowerCase();
+        const exts = LANG_EXT_MAP[langLower] ?? [`.${langLower}`];
+        const matchesLang = (file) => exts.some(e => file.endsWith(e));
+        definitions = definitions.filter(d => matchesLang(d.file));
+        allImports = allImports.filter(i => matchesLang(i.file));
+        allUsages = allUsages.filter(u => matchesLang(u.file));
+    }
+    // 3. Kind filter — select sections
+    const kind = args.kind ?? 'all';
+    if (kind !== 'all') {
+        switch (kind) {
+            case 'definitions':
+                allImports = [];
+                allUsages = [];
+                break;
+            case 'imports':
+                definitions = [];
+                allUsages = [];
+                break;
+            case 'usages':
+                definitions = [];
+                allImports = [];
+                break;
+        }
+    }
+    // 4. Limit — per category
+    const limit = args.limit ?? 50;
+    definitions = definitions.slice(0, limit);
+    allImports = allImports.slice(0, limit);
+    allUsages = allUsages.slice(0, limit);
+    // ─── Output ───
+    const totalCount = definitions.length + allImports.length + allUsages.length;
     if (totalCount === 0) {
         const hints = [`No usages found for "${args.symbol}".`];
+        if (args.scope)
+            hints.push(`  (filtered by scope: "${args.scope}")`);
+        if (args.lang)
+            hints.push(`  (filtered by lang: "${args.lang}")`);
+        if (args.kind && args.kind !== 'all')
+            hints.push(`  (filtered by kind: "${args.kind}")`);
         if (!astIndex.isAvailable()) {
             hints.push('WARNING: ast-index is not available.');
         }
         return { content: [{ type: 'text', text: hints.join('\n') }] };
     }
+    // Build header with active filters
+    const filterHints = [];
+    if (args.scope)
+        filterHints.push(`scope="${args.scope}"`);
+    if (args.lang)
+        filterHints.push(`lang=${args.lang}`);
+    if (args.kind && args.kind !== 'all')
+        filterHints.push(`kind=${args.kind}`);
+    const filterStr = filterHints.length > 0 ? ` [${filterHints.join(', ')}]` : '';
     const lines = [
-        `REFS: "${args.symbol}" (${totalCount} total: ${refs.definitions.length} definitions, ${allImports.length} imports, ${refs.usages.length + additionalOther.length} usages)`,
+        `REFS: "${args.symbol}" (${totalCount} total: ${definitions.length} definitions, ${allImports.length} imports, ${allUsages.length} usages)${filterStr}`,
         '',
     ];
-    if (refs.definitions.length > 0) {
+    if (definitions.length > 0) {
         lines.push('DEFINITIONS:');
-        for (const d of refs.definitions) {
-            lines.push(`  ${d.path}:${d.line}`);
-            lines.push(`    ${(d.signature ?? d.name).trim()}`);
+        for (const d of definitions) {
+            lines.push(`  ${d.file}:${d.line}`);
+            lines.push(`    ${d.text}`);
         }
         lines.push('');
     }
@@ -81,10 +160,6 @@ export async function handleFindUsages(args, astIndex) {
         }
         lines.push('');
     }
-    const allUsages = [
-        ...refs.usages.map(u => ({ file: u.path, line: u.line, text: (u.context ?? u.name).trim() })),
-        ...additionalOther,
-    ];
     if (allUsages.length > 0) {
         lines.push('USAGES:');
         for (const u of allUsages) {

package/dist/handlers/module-info.d.ts

@@ -0,0 +1,9 @@
+import type { AstIndexClient } from '../ast-index/client.js';
+import type { ModuleInfoArgs } from '../core/validation.js';
+export declare function handleModuleInfo(args: ModuleInfoArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=module-info.d.ts.map

package/dist/handlers/module-info.js

@@ -0,0 +1,123 @@
+import { relative } from 'node:path';
+export async function handleModuleInfo(args, projectRoot, astIndex) {
+    // Degradation check
+    if (astIndex.isDisabled() || astIndex.isOversized()) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: '⚠ ast-index unavailable — module_info requires ast-index.\n' +
+                        'DEGRADED: Use find_usages() + related_files() as alternatives for dependency analysis.',
+                }],
+        };
+    }
+    const check = args.check ?? 'all';
+    const sections = [];
+    // Resolve module
+    const moduleList = await astIndex.modules(args.module);
+    const moduleName = moduleList.length > 0 ? moduleList[0].name : args.module;
+    const modulePath = moduleList.length > 0 ? moduleList[0].path : args.module;
+    sections.push(`MODULE: ${moduleName} (${modulePath})`);
+    if (moduleList.length === 0) {
+        sections.push('');
+        sections.push(`⚠ Module "${args.module}" not found by ast-index.`);
+        sections.push('');
+        // List available modules as hint
+        const allModules = await astIndex.modules();
+        if (allModules.length > 0) {
+            sections.push(`Available modules (${allModules.length}):`);
+            for (const m of allModules.slice(0, 20)) {
+                sections.push(`  ${m.name} (${m.path})`);
+            }
+            if (allModules.length > 20) {
+                sections.push(`  ... and ${allModules.length - 20} more`);
+            }
+        }
+        else {
+            sections.push('No modules detected. ast-index module analysis requires a modular project structure.');
+            sections.push('HINT: Use find_usages() for cross-file symbol references, related_files() for import graphs.');
+        }
+        return { content: [{ type: 'text', text: sections.join('\n') }] };
+    }
+    sections.push('');
+    // Run requested checks in parallel
+    const checks = check === 'all'
+        ? ['deps', 'dependents', 'api', 'unused-deps']
+        : [check];
+    const results = await Promise.allSettled(checks.map(async (c) => {
+        switch (c) {
+            case 'deps': return { type: 'deps', data: await astIndex.moduleDeps(args.module) };
+            case 'dependents': return { type: 'dependents', data: await astIndex.moduleDependents(args.module) };
+            case 'api': return { type: 'api', data: await astIndex.moduleApi(args.module) };
+            case 'unused-deps': return { type: 'unused-deps', data: await astIndex.unusedDeps(args.module) };
+        }
+    }));
+    for (const r of results) {
+        if (r.status !== 'fulfilled')
+            continue;
+        const { type, data } = r.value;
+        switch (type) {
+            case 'deps': {
+                if (data.length > 0) {
+                    sections.push(`DEPENDENCIES (${data.length}):`);
+                    for (const d of data) {
+                        const typeHint = d.type ? ` [${d.type}]` : '';
+                        sections.push(`  → ${d.name} (${d.path})${typeHint}`);
+                    }
+                }
+                else {
+                    sections.push('DEPENDENCIES: none detected');
+                }
+                sections.push('');
+                break;
+            }
+            case 'dependents': {
+                if (data.length > 0) {
+                    sections.push(`DEPENDENTS (${data.length} modules depend on this):`);
+                    for (const d of data) {
+                        sections.push(`  ← ${d.name} (${d.path})`);
+                    }
+                }
+                else {
+                    sections.push('DEPENDENTS: none — this module is a leaf');
+                }
+                sections.push('');
+                break;
+            }
+            case 'api': {
+                if (data.length > 0) {
+                    sections.push(`PUBLIC API (${data.length} symbols):`);
+                    for (const a of data) {
+                        const loc = `${rel(projectRoot, a.file)}:${a.line}`;
+                        const sig = a.signature ? ` — ${a.signature}` : '';
+                        sections.push(`  ${a.kind} ${a.name}${sig}  (${loc})`);
+                    }
+                }
+                else {
+                    sections.push('PUBLIC API: none detected');
+                }
+                sections.push('');
+                break;
+            }
+            case 'unused-deps': {
+                if (data.length > 0) {
+                    sections.push(`UNUSED DEPENDENCIES (${data.length}):`);
+                    for (const d of data) {
+                        const reason = d.reason ? ` — ${d.reason}` : ' — imported but no symbols used';
+                        sections.push(`  ⚠ ${d.name} (${d.path})${reason}`);
+                    }
+                }
+                else {
+                    sections.push('UNUSED DEPENDENCIES: none — all dependencies are used');
+                }
+                sections.push('');
+                break;
+            }
+        }
+    }
+    sections.push('HINT: Use smart_read() on module files, find_usages() for cross-module references.');
+    return { content: [{ type: 'text', text: sections.join('\n') }] };
+}
+function rel(projectRoot, absPath) {
+    return relative(projectRoot, absPath) || absPath;
+}
+//# sourceMappingURL=module-info.js.map

package/dist/handlers/outline.d.ts

@@ -1,11 +1,15 @@
 import type { AstIndexClient } from '../ast-index/client.js';
-export interface OutlineArgs {
-    path: string;
-}
+import type { OutlineArgs } from '../core/validation.js';
+export declare const CODE_EXTENSIONS: Set<string>;
 export declare function handleOutline(args: OutlineArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
     content: Array<{
         type: 'text';
         text: string;
     }>;
 }>;
+/**
+ * Outline a single directory. When depth < maxDepth and recursive,
+ * recurse into subdirectories. Otherwise show file counts only.
+ */
+export declare function outlineDir(absPath: string, sections: string[], depth: number, maxDepth: number, projectRoot: string, astIndex: AstIndexClient): Promise<void>;
 //# sourceMappingURL=outline.d.ts.map