Method execute

src/tools/codegraph/find-dead-code.ts:185–334

(args: z.infer<typeof FindDeadCodeArgs>, ctx: ToolContext)

  argsSchema = FindDeadCodeArgs;

  async execute(args: z.infer<typeof FindDeadCodeArgs>, ctx: ToolContext): Promise<ToolResult> {
    const root = args.path ? path.join(ctx.cwd, args.path) : ctx.cwd;
    const maxFiles = args.max_files ?? 10_000;
    const scope = args.scope ?? 'all';
    const includeTests = args.include_tests ?? false;

    const files = await walkSource(root, maxFiles);

    // package.json for entry-point hinting
    let pkg: any = null;
    let pkgUnparseable = false;
    const pkgPath = path.join(ctx.cwd, 'package.json');
    try {
      pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'));
    } catch (err: any) {
      // A missing package.json is fine — just no entry-point hints. But a
      // corrupt one means we proceed with NO deps/entry hints, which inflates
      // false positives; warn so the user knows results may be unreliable.
      if (err?.code !== 'ENOENT') {
        pkgUnparseable = true;
        logger.warn(`Failed to parse ${pkgPath}: ${err?.message ?? err}`);
      }
    }

    const lines: string[] = [];
    lines.push(`# Dead Code Report`);
    lines.push(`Scanned ${files.length} source file(s) in ${path.relative(ctx.cwd, root) || '.'}`);
    lines.push(`Scope: ${scope}${includeTests ? ' (incl. tests)' : ' (excl. tests)'}`);
    if (pkgUnparseable) {
      lines.push(`⚠ package.json exists but could not be parsed — entry-point detection is degraded, so results below may contain extra false positives.`);
    }
    lines.push('');

    // ─── 1. Orphaned files ───
    const orphanedFiles: { rel: string; isEntry: boolean; reason: string }[] = [];
    if (scope === 'files' || scope === 'all') {
      // For each non-test file, check if anyone references it
      const refSources = includeTests ? files : files.filter(f => !f.isTest);
      for (const target of files) {
        if (target.isTest) continue; // we don't flag test files as dead
        const isEntry = isLikelyEntryPoint(target.rel, pkg);
        if (isEntry) continue; // skip entry points

        const patterns = buildReferencePatterns(target.rel);
        let referenced = false;
        for (const src of refSources) {
          if (src.abs === target.abs) continue;
          for (const pat of patterns) {
            if (src.content.includes(pat)) { referenced = true; break; }
          }
          if (referenced) break;
        }
        if (!referenced) {
          orphanedFiles.push({
            rel: target.rel,
            isEntry: false,
            reason: 'No imports detected. May still be referenced by config, dynamic import, or framework convention.',
          });