token-pilot 0.8.3 → 0.9.0

package/dist/core/project-detector.js

@@ -0,0 +1,362 @@
+import { readFile, readdir, access } from 'node:fs/promises';
+import { resolve, basename } from 'node:path';
+// ──────────────────────────────────────────────
+// Framework detection maps
+// ──────────────────────────────────────────────
+const PHP_FRAMEWORKS = {
+    'laravel/framework': 'Laravel',
+    'symfony/framework-bundle': 'Symfony',
+    'symfony/symfony': 'Symfony',
+    'yiisoft/yii2': 'Yii 2',
+    'cakephp/cakephp': 'CakePHP',
+    'slim/slim': 'Slim',
+    'codeigniter4/framework': 'CodeIgniter',
+};
+const JS_FRAMEWORKS = {
+    'next': 'Next.js',
+    'react': 'React',
+    'vue': 'Vue',
+    '@angular/core': 'Angular',
+    'svelte': 'Svelte',
+    '@nestjs/core': 'NestJS',
+    'express': 'Express',
+    'fastify': 'Fastify',
+    'nuxt': 'Nuxt',
+    '@remix-run/node': 'Remix',
+};
+const PYTHON_FRAMEWORKS = {
+    'django': 'Django',
+    'flask': 'Flask',
+    'fastapi': 'FastAPI',
+    'tornado': 'Tornado',
+    'starlette': 'Starlette',
+};
+// ──────────────────────────────────────────────
+// Main detection
+// ──────────────────────────────────────────────
+/**
+ * Detect project stacks by reading all config files in parallel.
+ * Returns dual-detection data: ast-index type + config-based stacks.
+ */
+export async function detectProject(projectRoot, astIndexType) {
+    // Read all configs in parallel
+    const [pkgResult, composerResult, cargoResult, pyResult, goResult] = await Promise.allSettled([
+        readJSON(resolve(projectRoot, 'package.json')),
+        readJSON(resolve(projectRoot, 'composer.json')),
+        readText(resolve(projectRoot, 'Cargo.toml')),
+        readText(resolve(projectRoot, 'pyproject.toml')),
+        readText(resolve(projectRoot, 'go.mod')),
+    ]);
+    const configStacks = [];
+    // Parse each config
+    if (pkgResult.status === 'fulfilled' && pkgResult.value) {
+        configStacks.push(parsePackageJson(pkgResult.value, projectRoot));
+    }
+    if (composerResult.status === 'fulfilled' && composerResult.value) {
+        configStacks.push(parseComposerJson(composerResult.value, projectRoot));
+    }
+    if (cargoResult.status === 'fulfilled' && cargoResult.value) {
+        const stack = parseCargoToml(cargoResult.value);
+        if (stack)
+            configStacks.push(stack);
+    }
+    if (pyResult.status === 'fulfilled' && pyResult.value) {
+        const stack = parsePyprojectToml(pyResult.value);
+        if (stack)
+            configStacks.push(stack);
+    }
+    if (goResult.status === 'fulfilled' && goResult.value) {
+        const stack = parseGoMod(goResult.value);
+        if (stack)
+            configStacks.push(stack);
+    }
+    // Determine primary stack
+    const primaryStack = configStacks.length === 1
+        ? configStacks[0]
+        : configStacks.length > 1
+            ? determinePrimary(configStacks)
+            : undefined;
+    // Determine confidence
+    const confidence = determineConfidence(astIndexType, configStacks);
+    // Detect quality tools and CI
+    const [qualityTools, ciPipelines, hasDocker] = await Promise.all([
+        detectQualityTools(projectRoot),
+        detectCI(projectRoot),
+        detectDocker(projectRoot),
+    ]);
+    // Project identity from primary stack
+    const projectName = primaryStack?.name ?? basename(projectRoot);
+    const projectVersion = primaryStack?.version ?? '0.0.0';
+    const projectDescription = primaryStack?.description;
+    return {
+        projectName,
+        projectVersion,
+        projectDescription,
+        astIndexType,
+        configStacks,
+        primaryStack,
+        confidence,
+        qualityTools,
+        ciPipelines,
+        hasDocker,
+    };
+}
+function parsePackageJson(pkg, projectRoot) {
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const framework = detectFramework(allDeps, JS_FRAMEWORKS);
+    const nodeVersion = pkg.engines?.node;
+    return {
+        type: 'Node.js/TypeScript',
+        name: pkg.name ?? basename(projectRoot),
+        version: pkg.version ?? '0.0.0',
+        langVersion: nodeVersion ? `Node ${normalizeVersionConstraint(nodeVersion)}` : undefined,
+        framework: framework ? formatFramework(framework, allDeps) : undefined,
+        description: pkg.description,
+    };
+}
+function parseComposerJson(composer, projectRoot) {
+    const allDeps = { ...composer.require, ...composer['require-dev'] };
+    const framework = detectFramework(allDeps, PHP_FRAMEWORKS);
+    const phpVersion = composer.require?.['php'];
+    return {
+        type: 'PHP',
+        name: composer.name ?? basename(projectRoot),
+        version: composer.version ?? '0.0.0',
+        langVersion: phpVersion ? `PHP ${normalizeVersionConstraint(phpVersion)}` : undefined,
+        framework: framework ? formatFramework(framework, allDeps) : undefined,
+        description: composer.description,
+    };
+}
+function parseCargoToml(text) {
+    const name = text.match(/^name\s*=\s*"(.+?)"/m)?.[1];
+    const version = text.match(/^version\s*=\s*"(.+?)"/m)?.[1];
+    if (!name && !version)
+        return null;
+    return {
+        type: 'Rust',
+        name: name ?? 'unknown',
+        version: version ?? '0.0.0',
+    };
+}
+function parsePyprojectToml(text) {
+    const name = text.match(/^name\s*=\s*"(.+?)"/m)?.[1];
+    const version = text.match(/^version\s*=\s*"(.+?)"/m)?.[1];
+    if (!name && !version)
+        return null;
+    // Try to detect framework from dependencies
+    let framework;
+    for (const [pkg, fw] of Object.entries(PYTHON_FRAMEWORKS)) {
+        if (text.includes(`"${pkg}`) || text.includes(`'${pkg}`)) {
+            framework = fw;
+            break;
+        }
+    }
+    // Python version
+    const pyVersion = text.match(/requires-python\s*=\s*"(.+?)"/)?.[1];
+    return {
+        type: 'Python',
+        name: name ?? 'unknown',
+        version: version ?? '0.0.0',
+        langVersion: pyVersion ? `Python ${normalizeVersionConstraint(pyVersion)}` : undefined,
+        framework,
+    };
+}
+function parseGoMod(text) {
+    const module = text.match(/^module\s+(.+)/m)?.[1]?.trim();
+    if (!module)
+        return null;
+    // Go version
+    const goVersion = text.match(/^go\s+(\S+)/m)?.[1];
+    return {
+        type: 'Go',
+        name: module,
+        version: '0.0.0',
+        langVersion: goVersion ? `Go ${goVersion}` : undefined,
+    };
+}
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+function detectFramework(deps, frameworkMap) {
+    if (!deps)
+        return null;
+    for (const [pkg, name] of Object.entries(frameworkMap)) {
+        if (deps[pkg])
+            return { name, pkg };
+    }
+    return null;
+}
+function formatFramework(fw, deps) {
+    const versionConstraint = deps[fw.pkg];
+    if (!versionConstraint)
+        return fw.name;
+    // Extract major version from constraint: "^12.0" → "12", "~3.4" → "3"
+    const majorMatch = versionConstraint.match(/(\d+)/);
+    return majorMatch ? `${fw.name} ${majorMatch[1]}` : fw.name;
+}
+/**
+ * Normalize version constraint to human-readable form.
+ * ">=8.2" → "8.2+", "^8.2" → "8.2+", "~8.2" → "8.2+", "8.2.*" → "8.2+"
+ */
+function normalizeVersionConstraint(constraint) {
+    const cleaned = constraint.replace(/[>=^~*|<\s]/g, '').split(',')[0].split('|')[0];
+    // Take first version-like segment
+    const version = cleaned.match(/\d+(\.\d+)*/)?.[0];
+    return version ? `${version}+` : constraint;
+}
+/**
+ * Determine primary stack when multiple configs found.
+ * Heuristic: backend languages (PHP, Python, Go, Rust) beat JS/TS as primary
+ * because JS/TS in multi-stack projects is typically frontend tooling.
+ */
+function determinePrimary(stacks) {
+    // Backend-first priority
+    const priority = ['PHP', 'Python', 'Go', 'Rust', 'Node.js/TypeScript'];
+    const sorted = [...stacks].sort((a, b) => priority.indexOf(a.type) - priority.indexOf(b.type));
+    return sorted[0];
+}
+/**
+ * Determine confidence level based on agreement between ast-index and config detection.
+ */
+function determineConfidence(astIndexType, configStacks) {
+    if (!astIndexType && configStacks.length === 0)
+        return 'unknown';
+    if (!astIndexType)
+        return configStacks.length === 1 ? 'medium' : 'medium';
+    if (configStacks.length === 0)
+        return 'medium';
+    // Check if ast-index type matches any config stack
+    const astLower = astIndexType.toLowerCase();
+    const anyMatch = configStacks.some(s => {
+        const typeLower = s.type.toLowerCase();
+        return astLower.includes(typeLower) || typeLower.includes(astLower)
+            || (astLower.includes('javascript') && typeLower.includes('node'))
+            || (astLower.includes('typescript') && typeLower.includes('node'))
+            || (astLower.includes('php') && typeLower === 'php');
+    });
+    if (anyMatch && configStacks.length === 1)
+        return 'high';
+    if (anyMatch && configStacks.length > 1)
+        return 'medium';
+    return 'low'; // Conflict: ast-index says X, configs say Y
+}
+// ──────────────────────────────────────────────
+// Quality & CI detection
+// ──────────────────────────────────────────────
+/** Detect quality/linting tools present in project root */
+export async function detectQualityTools(projectRoot) {
+    const tools = [];
+    const checks = [
+        { files: ['phpstan.neon', 'phpstan.neon.dist'], name: 'PHPStan' },
+        { files: ['psalm.xml', 'psalm.xml.dist'], name: 'Psalm' },
+        { files: ['phpunit.xml', 'phpunit.xml.dist'], name: 'PHPUnit' },
+        { files: ['pest.php'], name: 'Pest' },
+        { files: ['.eslintrc', '.eslintrc.js', '.eslintrc.json', '.eslintrc.yml', 'eslint.config.js', 'eslint.config.mjs'], name: 'ESLint' },
+        { files: ['tsconfig.json'], name: 'TypeScript' },
+        { files: ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mts'], name: 'Vitest' },
+        { files: ['jest.config.js', 'jest.config.ts', 'jest.config.mjs'], name: 'Jest' },
+        { files: ['biome.json', 'biome.jsonc'], name: 'Biome' },
+        { files: ['.prettierrc', '.prettierrc.js', '.prettierrc.json', 'prettier.config.js'], name: 'Prettier' },
+        { files: ['deptrac.yaml', 'deptrac.yml'], name: 'Deptrac' },
+        { files: ['rector.php'], name: 'Rector' },
+        { files: ['ruff.toml', '.ruff.toml'], name: 'Ruff' },
+    ];
+    const results = await Promise.allSettled(checks.map(async (check) => {
+        for (const file of check.files) {
+            try {
+                await access(resolve(projectRoot, file));
+                return check.name;
+            }
+            catch { /* file doesn't exist */ }
+        }
+        return null;
+    }));
+    // Special case: Ruff can also be configured in pyproject.toml [tool.ruff]
+    // Only check if ruff.toml/.ruff.toml not already found
+    const ruffFound = results.some(r => r.status === 'fulfilled' && r.value === 'Ruff');
+    if (!ruffFound) {
+        try {
+            const pyprojectPath = resolve(projectRoot, 'pyproject.toml');
+            const content = await readFile(pyprojectPath, 'utf-8');
+            if (content.includes('[tool.ruff]')) {
+                // Inject Ruff into results manually below
+                results.push({ status: 'fulfilled', value: 'Ruff' });
+            }
+        }
+        catch { /* no pyproject.toml or can't read */ }
+    }
+    for (const r of results) {
+        if (r.status === 'fulfilled' && r.value) {
+            tools.push(r.value);
+        }
+    }
+    return tools;
+}
+/** Detect CI/CD pipelines present in project */
+export async function detectCI(projectRoot) {
+    const pipelines = [];
+    // GitHub Actions
+    try {
+        const ghDir = resolve(projectRoot, '.github', 'workflows');
+        const files = await readdir(ghDir);
+        const ymlCount = files.filter(f => f.endsWith('.yml') || f.endsWith('.yaml')).length;
+        if (ymlCount > 0) {
+            pipelines.push(`GitHub Actions (${ymlCount} workflow${ymlCount > 1 ? 's' : ''})`);
+        }
+    }
+    catch { /* no .github/workflows */ }
+    // GitLab CI
+    try {
+        await access(resolve(projectRoot, '.gitlab-ci.yml'));
+        pipelines.push('GitLab CI');
+    }
+    catch { /* no gitlab ci */ }
+    // Other CI
+    const otherCI = [
+        { file: 'Jenkinsfile', name: 'Jenkins' },
+        { file: '.circleci/config.yml', name: 'CircleCI' },
+        { file: 'bitbucket-pipelines.yml', name: 'Bitbucket Pipelines' },
+        { file: '.travis.yml', name: 'Travis CI' },
+    ];
+    for (const ci of otherCI) {
+        try {
+            await access(resolve(projectRoot, ci.file));
+            pipelines.push(ci.name);
+        }
+        catch { /* not present */ }
+    }
+    return pipelines;
+}
+/** Detect Docker presence */
+export async function detectDocker(projectRoot) {
+    const dockerFiles = ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml'];
+    for (const file of dockerFiles) {
+        try {
+            await access(resolve(projectRoot, file));
+            return true;
+        }
+        catch { /* not present */ }
+    }
+    return false;
+}
+// ──────────────────────────────────────────────
+// File reading helpers
+// ──────────────────────────────────────────────
+async function readJSON(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+async function readText(filePath) {
+    try {
+        return await readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=project-detector.js.map

package/dist/core/validation.d.ts

@@ -40,10 +40,16 @@ export declare function validateReadDiffArgs(args: unknown): {
 };
 /**
  * Validate find_usages arguments.
+ * v1.1: added scope, kind, limit, lang filters.
  */
-export declare function validateFindUsagesArgs(args: unknown): {
+export interface FindUsagesArgs {
     symbol: string;
-};
+    scope?: string;
+    kind?: 'definitions' | 'imports' | 'usages' | 'all';
+    limit?: number;
+    lang?: string;
+}
+export declare function validateFindUsagesArgs(args: unknown): FindUsagesArgs;
 /**
  * Validate smart_read_many arguments.
  */
@@ -67,10 +73,14 @@ export declare function validateRelatedFilesArgs(args: unknown): {
 };
 /**
  * Validate outline arguments.
+ * v1.1: added recursive, max_depth.
  */
-export declare function validateOutlineArgs(args: unknown): {
+export interface OutlineArgs {
     path: string;
-};
+    recursive?: boolean;
+    max_depth?: number;
+}
+export declare function validateOutlineArgs(args: unknown): OutlineArgs;
 export declare function validateFindUnusedArgs(args: unknown): {
     module?: string;
     export_only?: boolean;
@@ -84,6 +94,22 @@ export interface CodeAuditArgs {
     limit?: number;
 }
 export declare function validateCodeAuditArgs(args: unknown): CodeAuditArgs;
+/**
+ * Validate project_overview arguments.
+ * v1.1: added include filter.
+ */
+export interface ProjectOverviewArgs {
+    include?: Array<'stack' | 'ci' | 'quality' | 'architecture'>;
+}
+export declare function validateProjectOverviewArgs(args: unknown): ProjectOverviewArgs;
+/**
+ * Validate module_info arguments.
+ */
+export interface ModuleInfoArgs {
+    module: string;
+    check?: 'deps' | 'dependents' | 'api' | 'unused-deps' | 'all';
+}
+export declare function validateModuleInfoArgs(args: unknown): ModuleInfoArgs;
 /** Detect roots that would cause ast-index to scan the entire filesystem */
 export declare function isDangerousRoot(root: string): boolean;
 //# sourceMappingURL=validation.d.ts.map

package/dist/core/validation.js

@@ -98,9 +98,6 @@ export function validateReadDiffArgs(args) {
         context_lines: optionalNumber(a.context_lines, 'context_lines'),
     };
 }
-/**
- * Validate find_usages arguments.
- */
 export function validateFindUsagesArgs(args) {
     if (!args || typeof args !== 'object') {
         throw new Error('Arguments must be an object.');
@@ -109,7 +106,25 @@ export function validateFindUsagesArgs(args) {
     if (typeof a.symbol !== 'string' || a.symbol.length === 0) {
         throw new Error('Required parameter "symbol" must be a non-empty string.');
     }
-    return { symbol: a.symbol };
+    let kind;
+    if (a.kind !== undefined && a.kind !== null) {
+        const validKinds = ['definitions', 'imports', 'usages', 'all'];
+        if (typeof a.kind !== 'string' || !validKinds.includes(a.kind)) {
+            throw new Error(`"kind" must be one of: ${validKinds.join(', ')}`);
+        }
+        kind = a.kind;
+    }
+    const limit = optionalNumber(a.limit, 'limit');
+    if (limit !== undefined && (limit < 1 || limit > 500)) {
+        throw new Error('"limit" must be between 1 and 500.');
+    }
+    return {
+        symbol: a.symbol,
+        scope: optionalString(a.scope, 'scope'),
+        kind,
+        limit,
+        lang: optionalString(a.lang, 'lang'),
+    };
 }
 /**
  * Validate smart_read_many arguments.
@@ -184,9 +199,6 @@ export function validateRelatedFilesArgs(args) {
     }
     return { path: a.path };
 }
-/**
- * Validate outline arguments.
- */
 export function validateOutlineArgs(args) {
     if (!args || typeof args !== 'object') {
         throw new Error('Arguments must be an object.');
@@ -195,7 +207,15 @@ export function validateOutlineArgs(args) {
     if (typeof a.path !== 'string' || a.path.length === 0) {
         throw new Error('Required parameter "path" must be a non-empty string.');
     }
-    return { path: a.path };
+    const maxDepth = optionalNumber(a.max_depth, 'max_depth');
+    if (maxDepth !== undefined && (maxDepth < 1 || maxDepth > 5)) {
+        throw new Error('"max_depth" must be between 1 and 5.');
+    }
+    return {
+        path: a.path,
+        recursive: optionalBool(a.recursive, 'recursive'),
+        max_depth: maxDepth,
+    };
 }
 export function validateFindUnusedArgs(args) {
     if (!args || typeof args !== 'object')
@@ -234,6 +254,45 @@ export function validateCodeAuditArgs(args) {
         limit: optionalNumber(a.limit, 'limit'),
     };
 }
+const VALID_INCLUDE_SECTIONS = ['stack', 'ci', 'quality', 'architecture'];
+export function validateProjectOverviewArgs(args) {
+    if (!args || typeof args !== 'object')
+        return {};
+    const a = args;
+    if (a.include !== undefined && a.include !== null) {
+        if (!Array.isArray(a.include)) {
+            throw new Error('"include" must be an array of section names.');
+        }
+        for (const item of a.include) {
+            if (typeof item !== 'string' || !VALID_INCLUDE_SECTIONS.includes(item)) {
+                throw new Error(`Each element of "include" must be one of: ${VALID_INCLUDE_SECTIONS.join(', ')}. Got: "${item}"`);
+            }
+        }
+        return { include: a.include };
+    }
+    return {};
+}
+export function validateModuleInfoArgs(args) {
+    if (!args || typeof args !== 'object') {
+        throw new Error('Arguments must be an object with a "module" parameter.');
+    }
+    const a = args;
+    if (typeof a.module !== 'string' || a.module.length === 0) {
+        throw new Error('Required parameter "module" must be a non-empty string.');
+    }
+    let check;
+    if (a.check !== undefined && a.check !== null) {
+        const validChecks = ['deps', 'dependents', 'api', 'unused-deps', 'all'];
+        if (typeof a.check !== 'string' || !validChecks.includes(a.check)) {
+            throw new Error(`"check" must be one of: ${validChecks.join(', ')}`);
+        }
+        check = a.check;
+    }
+    return {
+        module: a.module,
+        check: check ?? 'all',
+    };
+}
 /** Detect roots that would cause ast-index to scan the entire filesystem */
 export function isDangerousRoot(root) {
     const normalized = root.replace(/\/+$/, '') || '/';

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<{