token-pilot 0.8.3 → 0.9.0

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,7 +1,5 @@
 import type { AstIndexClient } from '../ast-index/client.js';
-export interface OutlineArgs {
-    path: string;
-}
+import type { OutlineArgs } from '../core/validation.js';
 export declare function handleOutline(args: OutlineArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
     content: Array<{
         type: 'text';

package/dist/handlers/outline.js

@@ -22,7 +22,28 @@ export async function handleOutline(args, projectRoot, astIndex) {
                 }],
         };
     }
-    // List code files and subdirectories (1 level)
+    const recursive = args.recursive ?? false;
+    const maxDepth = args.max_depth ?? 2;
+    const sections = [];
+    await outlineDir(absPath, sections, 0, recursive ? maxDepth : 0, projectRoot, astIndex);
+    sections.push('HINT: Use outline(path) on subdirs, smart_read(path) for file structure, read_symbol(path, symbol) for source code.');
+    return { content: [{ type: 'text', text: sections.join('\n') }] };
+}
+/** Max output lines to prevent runaway recursive outlines */
+const MAX_OUTLINE_LINES = 500;
+/**
+ * Outline a single directory. When depth < maxDepth and recursive,
+ * recurse into subdirectories. Otherwise show file counts only.
+ */
+async function outlineDir(absPath, sections, depth, maxDepth, projectRoot, astIndex) {
+    // Guard: stop if output is already too large
+    if (sections.length >= MAX_OUTLINE_LINES) {
+        if (!sections[sections.length - 1]?.startsWith('⚠')) {
+            sections.push(`⚠ Output truncated at ${MAX_OUTLINE_LINES} lines. Use outline() on specific subdirectories for details.`);
+        }
+        return;
+    }
+    // List code files and subdirectories
     const entries = await readdir(absPath, { withFileTypes: true });
     const codeFiles = [];
     const subdirs = [];
@@ -38,53 +59,63 @@ export async function handleOutline(args, projectRoot, astIndex) {
         }
     }
     if (codeFiles.length === 0 && subdirs.length === 0) {
-        return {
-            content: [{
-                    type: 'text',
-                    text: `No code files or subdirectories found in "${args.path}".`,
-                }],
-        };
+        if (depth === 0) {
+            sections.push(`No code files or subdirectories found in "${relative(projectRoot, absPath) || '.'}".`);
+        }
+        return;
     }
     // Sort
     codeFiles.sort();
     subdirs.sort();
     const relDir = relative(projectRoot, absPath) || '.';
+    const indent = '  '.repeat(depth);
     const totalLabel = codeFiles.length > 0 ? `${codeFiles.length} files` : '';
     const subLabel = subdirs.length > 0 ? `${subdirs.length} subdirs` : '';
     const countLabel = [totalLabel, subLabel].filter(Boolean).join(', ');
-    const sections = [`OUTLINE: ${relDir}/ (${countLabel})`, ''];
-    // Show subdirectories with file counts (recursive scan)
+    sections.push(`${indent}OUTLINE: ${relDir}/ (${countLabel})`);
+    sections.push('');
+    // Show subdirectories
     if (subdirs.length > 0) {
-        for (const sub of subdirs) {
-            const subPath = resolve(absPath, sub);
-            const fileCount = await countCodeFiles(subPath);
-            sections.push(`  ${sub}/ (${fileCount} code files)`);
+        if (depth < maxDepth) {
+            // Recursive: outline each subdir
+            for (const sub of subdirs) {
+                const subPath = resolve(absPath, sub);
+                await outlineDir(subPath, sections, depth + 1, maxDepth, projectRoot, astIndex);
+            }
+        }
+        else {
+            // Non-recursive: show file counts only
+            for (const sub of subdirs) {
+                const subPath = resolve(absPath, sub);
+                const fileCount = await countCodeFiles(subPath);
+                sections.push(`${indent}  ${sub}/ (${fileCount} code files)`);
+            }
+            sections.push('');
         }
-        sections.push('');
     }
     // Show code files at this level with AST outline
+    const fileIndent = '  '.repeat(depth + 1);
+    const symbolIndent = depth + 2;
     for (const filePath of codeFiles) {
         const name = basename(filePath);
         try {
             const structure = await astIndex.outline(filePath);
             if (!structure) {
-                sections.push(`${name} (no AST)`);
+                sections.push(`${fileIndent}${name} (no AST)`);
                 sections.push('');
                 continue;
             }
-            sections.push(`${name} (${structure.meta.lines} lines)`);
+            sections.push(`${fileIndent}${name} (${structure.meta.lines} lines)`);
             for (const sym of structure.symbols) {
-                formatCompactSymbol(sym, sections, 1);
+                formatCompactSymbol(sym, sections, symbolIndent);
             }
             sections.push('');
         }
         catch {
-            sections.push(`${name} (outline failed)`);
+            sections.push(`${fileIndent}${name} (outline failed)`);
             sections.push('');
         }
     }
-    sections.push('HINT: Use outline(path) on subdirs, smart_read(path) for file structure, read_symbol(path, symbol) for source code.');
-    return { content: [{ type: 'text', text: sections.join('\n') }] };
 }
 /**
  * Format a symbol in compact outline form.

package/dist/handlers/project-overview.d.ts

@@ -1,5 +1,6 @@
 import type { AstIndexClient } from '../ast-index/client.js';
-export declare function handleProjectOverview(projectRoot: string, astIndex: AstIndexClient): Promise<{
+import type { ProjectOverviewArgs } from '../core/validation.js';
+export declare function handleProjectOverview(args: ProjectOverviewArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
     content: Array<{
         type: 'text';
         text: string;