pruny 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build
+        run: bun run build
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build
+        run: bun run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,65 @@
+# pruny
+
+Find and remove unused Next.js API routes. 🪓
+
+## Install
+
+```bash
+npm install -g pruny
+# or
+npx pruny
+```
+
+## Usage
+
+```bash
+# Scan current directory
+pruny
+
+# Scan specific folder
+pruny --dir ./src
+
+# Delete unused routes
+pruny --fix
+
+# Output as JSON
+pruny --json
+
+# Verbose output
+pruny -v
+```
+
+## Config
+
+Create `pruny.config.json` (optional):
+
+```json
+{
+  "dir": "./",
+  "ignore": {
+    "routes": ["/api/webhooks/**", "/api/cron/**"],
+    "folders": ["node_modules", ".next", "dist"],
+    "files": ["*.test.ts"]
+  },
+  "extensions": [".ts", ".tsx", ".js", ".jsx"]
+}
+```
+
+## Features
+
+- 🔍 Detects unused Next.js API routes
+- 🗑️ `--fix` flag to delete unused routes
+- ⚡ Auto-detects `vercel.json` cron routes
+- 📁 Default ignores: `node_modules`, `.next`, `dist`, `.git`
+- 🎨 Beautiful CLI output
+
+## How it works
+
+1. Finds all `app/api/**/route.ts` files
+2. Scans codebase for `fetch('/api/...')` patterns
+3. Reports routes with no references
+4. `--fix` deletes the route folder
+
+## License
+
+MIT

package/bin/pruny.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.js');

package/bun.lock

@@ -0,0 +1,79 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "unused_variable",
+      "dependencies": {
+        "chalk": "^5.3.0",
+        "commander": "^12.0.0",
+        "fast-glob": "^3.3.2",
+        "minimatch": "^10.1.2",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "@types/minimatch": "^6.0.0",
+        "typescript": "^5.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@isaacs/balanced-match": ["@isaacs/balanced-match@4.0.1", "", {}, "sha512-yzMTt9lEb8Gv7zRioUilSglI0c0smZ9k5D65677DLWLtWJaXIS3CqcGyUFByYKlnUj6TkjLVs54fBl6+TiGQDQ=="],
+
+    "@isaacs/brace-expansion": ["@isaacs/brace-expansion@5.0.1", "", { "dependencies": { "@isaacs/balanced-match": "^4.0.1" } }, "sha512-WMz71T1JS624nWj2n2fnYAuPovhv7EUhk69R6i9dsVyzxt5eM3bjwvgk9L+APE1TRscGysAVMANkB0jh0LQZrQ=="],
+
+    "@nodelib/fs.scandir": ["@nodelib/fs.scandir@2.1.5", "", { "dependencies": { "@nodelib/fs.stat": "2.0.5", "run-parallel": "^1.1.9" } }, "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g=="],
+
+    "@nodelib/fs.stat": ["@nodelib/fs.stat@2.0.5", "", {}, "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A=="],
+
+    "@nodelib/fs.walk": ["@nodelib/fs.walk@1.2.8", "", { "dependencies": { "@nodelib/fs.scandir": "2.1.5", "fastq": "^1.6.0" } }, "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg=="],
+
+    "@types/bun": ["@types/bun@1.3.8", "", { "dependencies": { "bun-types": "1.3.8" } }, "sha512-3LvWJ2q5GerAXYxO2mffLTqOzEu5qnhEAlh48Vnu8WQfnmSwbgagjGZV6BoHKJztENYEDn6QmVd949W4uESRJA=="],
+
+    "@types/minimatch": ["@types/minimatch@6.0.0", "", { "dependencies": { "minimatch": "*" } }, "sha512-zmPitbQ8+6zNutpwgcQuLcsEpn/Cj54Kbn7L5pX0Os5kdWplB7xPgEh/g+SWOB/qmows2gpuCaPyduq8ZZRnxA=="],
+
+    "@types/node": ["@types/node@25.2.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-BkmoP5/FhRYek5izySdkOneRyXYN35I860MFAGupTdebyE66uZaR+bXLHq8k4DirE5DwQi3NuhvRU1jqTVwUrQ=="],
+
+    "braces": ["braces@3.0.3", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="],
+
+    "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="],
+
+    "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
+
+    "commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
+    "fast-glob": ["fast-glob@3.3.3", "", { "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", "glob-parent": "^5.1.2", "merge2": "^1.3.0", "micromatch": "^4.0.8" } }, "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg=="],
+
+    "fastq": ["fastq@1.20.1", "", { "dependencies": { "reusify": "^1.0.4" } }, "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw=="],
+
+    "fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
+
+    "glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
+
+    "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
+
+    "is-glob": ["is-glob@4.0.3", "", { "dependencies": { "is-extglob": "^2.1.1" } }, "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg=="],
+
+    "is-number": ["is-number@7.0.0", "", {}, "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng=="],
+
+    "merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="],
+
+    "micromatch": ["micromatch@4.0.8", "", { "dependencies": { "braces": "^3.0.3", "picomatch": "^2.3.1" } }, "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA=="],
+
+    "minimatch": ["minimatch@10.1.2", "", { "dependencies": { "@isaacs/brace-expansion": "^5.0.1" } }, "sha512-fu656aJ0n2kcXwsnwnv9g24tkU5uSmOlTjd6WyyaKm2Z+h1qmY6bAjrcaIxF/BslFqbZ8UBtbJi7KgQOZD2PTw=="],
+
+    "picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
+    "queue-microtask": ["queue-microtask@1.2.3", "", {}, "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="],
+
+    "reusify": ["reusify@1.1.0", "", {}, "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw=="],
+
+    "run-parallel": ["run-parallel@1.2.0", "", { "dependencies": { "queue-microtask": "^1.2.2" } }, "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA=="],
+
+    "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pruny",
+  "version": "1.0.0",
+  "description": "Find and remove unused Next.js API routes",
+  "type": "module",
+  "bin": {
+    "pruny": "./bin/pruny.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node",
+    "dev": "bun run ./src/index.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "unused",
+    "api",
+    "routes",
+    "nextjs",
+    "cleanup",
+    "lint"
+  ],
+  "author": "webnaresh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webnaresh/pruny"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fast-glob": "^3.3.2",
+    "minimatch": "^10.1.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/minimatch": "^6.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Config } from './types.js';
+
+const DEFAULT_CONFIG: Config = {
+  dir: './',
+  ignore: {
+    routes: [],
+    folders: ['node_modules', '.next', 'dist', '.git', 'coverage', '.turbo'],
+    files: ['*.test.ts', '*.spec.ts', '*.test.tsx', '*.spec.tsx'],
+  },
+  extensions: ['.ts', '.tsx', '.js', '.jsx'],
+};
+
+interface CLIOptions {
+  dir?: string;
+  config?: string;
+}
+
+/**
+ * Load config from file or use defaults
+ */
+export function loadConfig(options: CLIOptions): Config {
+  const configPath = options.config || findConfigFile(options.dir || './');
+
+  let fileConfig: Partial<Config> = {};
+
+  if (configPath && existsSync(configPath)) {
+    try {
+      const content = readFileSync(configPath, 'utf-8');
+      fileConfig = JSON.parse(content);
+    } catch {
+      // Ignore parse errors, use defaults
+    }
+  }
+
+  // Merge configs
+  return {
+    dir: options.dir || fileConfig.dir || DEFAULT_CONFIG.dir,
+    ignore: {
+      routes: fileConfig.ignore?.routes || DEFAULT_CONFIG.ignore.routes,
+      folders: fileConfig.ignore?.folders || DEFAULT_CONFIG.ignore.folders,
+      files: fileConfig.ignore?.files || DEFAULT_CONFIG.ignore.files,
+    },
+    extensions: fileConfig.extensions || DEFAULT_CONFIG.extensions,
+  };
+}
+
+/**
+ * Find config file in directory
+ */
+function findConfigFile(dir: string): string | null {
+  const candidates = ['pruny.config.json', '.prunyrc.json', '.prunyrc'];
+
+  for (const name of candidates) {
+    const path = join(dir, name);
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { scan } from './scanner.js';
+import { loadConfig } from './config.js';
+
+const program = new Command();
+
+program
+  .name('pruny')
+  .description('Find and remove unused Next.js API routes')
+  .version('1.0.0')
+  .option('-d, --dir <path>', 'Target directory to scan', './')
+  .option('--fix', 'Delete unused API routes')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--json', 'Output as JSON')
+  .option('-v, --verbose', 'Show detailed info')
+  .action(async (options) => {
+    const config = loadConfig({
+      dir: options.dir,
+      config: options.config,
+    });
+
+    // Resolve absolute path
+    const absoluteDir = config.dir.startsWith('/')
+      ? config.dir
+      : join(process.cwd(), config.dir);
+    config.dir = absoluteDir;
+
+    if (options.verbose) {
+      console.log(chalk.dim('\nConfig:'));
+      console.log(chalk.dim(JSON.stringify(config, null, 2)));
+      console.log('');
+    }
+
+    console.log(chalk.bold('\n🔍 Scanning for unused API routes...\n'));
+
+    try {
+      const result = await scan(config);
+
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      // Summary
+      console.log(chalk.bold('📊 Results\n'));
+      console.log(`   Total routes:  ${result.total}`);
+      console.log(chalk.green(`   Used routes:   ${result.used}`));
+      console.log(chalk.red(`   Unused routes: ${result.unused}`));
+      console.log('');
+
+      if (result.total === 0) {
+        console.log(chalk.yellow('⚠️  No API routes found.\n'));
+        return;
+      }
+
+      const unused = result.routes.filter((r) => !r.used);
+
+      if (unused.length === 0) {
+        console.log(chalk.green('✅ All API routes are used!\n'));
+        return;
+      }
+
+      // List unused routes
+      console.log(chalk.red.bold('❌ Unused routes:\n'));
+      for (const route of unused) {
+        console.log(chalk.red(`   ${route.path}`));
+        console.log(chalk.dim(`      → ${route.filePath}`));
+      }
+      console.log('');
+
+      // Show used routes in verbose mode
+      if (options.verbose) {
+        const used = result.routes.filter((r) => r.used);
+        if (used.length > 0) {
+          console.log(chalk.green.bold('✅ Used routes:\n'));
+          for (const route of used) {
+            console.log(chalk.green(`   ${route.path}`));
+            if (route.references.length > 0) {
+              for (const ref of route.references.slice(0, 3)) {
+                console.log(chalk.dim(`      ← ${ref}`));
+              }
+              if (route.references.length > 3) {
+                console.log(
+                  chalk.dim(`      ... and ${route.references.length - 3} more`)
+                );
+              }
+            }
+          }
+          console.log('');
+        }
+      }
+
+      // --fix: Delete unused routes
+      if (options.fix) {
+        console.log(chalk.yellow.bold('🗑️  Deleting unused routes...\n'));
+
+        for (const route of unused) {
+          const routeDir = dirname(join(config.dir, route.filePath));
+          try {
+            rmSync(routeDir, { recursive: true, force: true });
+            console.log(chalk.red(`   Deleted: ${route.filePath}`));
+          } catch (err) {
+            console.log(
+              chalk.yellow(`   Failed to delete: ${route.filePath}`)
+            );
+          }
+        }
+
+        console.log(
+          chalk.green(`\n✅ Deleted ${unused.length} unused route(s).\n`)
+        );
+      } else {
+        console.log(
+          chalk.dim('💡 Run with --fix to delete unused routes.\n')
+        );
+      }
+    } catch (err) {
+      console.error(chalk.red('Error scanning:'), err);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/patterns.ts

@@ -0,0 +1,46 @@
+/**
+ * Regex patterns to detect API route usage in source files
+ */
+export const API_PATTERNS: RegExp[] = [
+  // fetch('/api/...')
+  /fetch\s*\(\s*['"`]\/api\/([^'"`\s)]+)['"`]/g,
+
+  // fetch(`/api/...`)
+  /fetch\s*\(\s*`\/api\/([^`\s)]+)`/g,
+
+  // axios.get('/api/...')
+  /axios\.\w+\s*\(\s*['"`]\/api\/([^'"`\s)]+)['"`]/g,
+
+  // useSWR('/api/...')
+  /useSWR\s*\(\s*['"`]\/api\/([^'"`\s)]+)['"`]/g,
+
+  // useQuery with /api/
+  /queryFn.*['"`]\/api\/([^'"`\s)]+)['"`]/g,
+
+  // Generic string containing /api/
+  /['"`]\/api\/([^'"`\s]+)['"`]/g,
+];
+
+/**
+ * Extract all API paths referenced in content
+ */
+export function extractApiPaths(content: string): string[] {
+  const paths = new Set<string>();
+
+  for (const pattern of API_PATTERNS) {
+    // Reset regex lastIndex
+    pattern.lastIndex = 0;
+
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(content)) !== null) {
+      // Full path including /api/
+      const fullMatch = match[0];
+      const pathMatch = fullMatch.match(/\/api\/[^'"`\s)]+/);
+      if (pathMatch) {
+        paths.add(pathMatch[0]);
+      }
+    }
+  }
+
+  return Array.from(paths);
+}

package/src/scanner.ts

@@ -0,0 +1,188 @@
+import fg from 'fast-glob';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { extractApiPaths } from './patterns.js';
+import type { Config, ApiRoute, ScanResult, VercelConfig } from './types.js';
+import { minimatch } from 'minimatch';
+
+/**
+ * Extract route path from file path
+ * e.g., app/api/users/route.ts -> /api/users
+ */
+function extractRoutePath(filePath: string): string {
+  // Remove src/ prefix if present
+  let path = filePath.replace(/^src\//, '');
+
+  // Remove app/ prefix
+  path = path.replace(/^app\//, '');
+
+  // Remove route.{ts,tsx,js,jsx} suffix
+  path = path.replace(/\/route\.(ts|tsx|js|jsx)$/, '');
+
+  return '/' + path;
+}
+
+/**
+ * Check if a route matches any ignore pattern
+ */
+function shouldIgnoreRoute(routePath: string, ignorePatterns: string[]): boolean {
+  return ignorePatterns.some((pattern) => minimatch(routePath, pattern));
+}
+
+/**
+ * Normalize API path for comparison
+ * Removes trailing slashes, query params, dynamic segments for matching
+ */
+function normalizeApiPath(path: string): string {
+  return path
+    .replace(/\/$/, '') // Remove trailing slash
+    .replace(/\?.*$/, '') // Remove query params
+    .replace(/\$\{[^}]+\}/g, '*') // Replace template literals with wildcard
+    .toLowerCase();
+}
+
+/**
+ * Check if a route is referenced by any of the found paths
+ */
+function isRouteReferenced(routePath: string, foundPaths: string[]): boolean {
+  const normalizedRoute = normalizeApiPath(routePath);
+
+  return foundPaths.some((foundPath) => {
+    const normalizedFound = normalizeApiPath(foundPath);
+
+    // Exact match
+    if (normalizedRoute === normalizedFound) return true;
+
+    // Route is prefix of found path (for dynamic routes)
+    if (normalizedFound.startsWith(normalizedRoute)) return true;
+
+    // Found path matches route pattern
+    if (minimatch(normalizedFound, normalizedRoute)) return true;
+
+    return false;
+  });
+}
+
+/**
+ * Load vercel.json and get cron paths
+ */
+function getVercelCronPaths(dir: string): string[] {
+  const vercelPath = join(dir, 'vercel.json');
+
+  if (!existsSync(vercelPath)) {
+    return [];
+  }
+
+  try {
+    const content = readFileSync(vercelPath, 'utf-8');
+    const config: VercelConfig = JSON.parse(content);
+
+    if (!config.crons) {
+      return [];
+    }
+
+    return config.crons.map((cron) => cron.path);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scan for unused API routes
+ */
+export async function scan(config: Config): Promise<ScanResult> {
+  const cwd = config.dir;
+
+  // 1. Find all API route files
+  const routePatterns = [
+    'app/api/**/route.{ts,tsx,js,jsx}',
+    'src/app/api/**/route.{ts,tsx,js,jsx}',
+  ];
+
+  const routeFiles = await fg(routePatterns, {
+    cwd,
+    ignore: config.ignore.folders,
+  });
+
+  if (routeFiles.length === 0) {
+    return { total: 0, used: 0, unused: 0, routes: [] };
+  }
+
+  // 2. Build route map
+  const routes: ApiRoute[] = routeFiles.map((file) => ({
+    path: extractRoutePath(file),
+    filePath: file,
+    used: false,
+    references: [],
+  }));
+
+  // 3. Mark vercel cron routes as used
+  const cronPaths = getVercelCronPaths(cwd);
+  for (const cronPath of cronPaths) {
+    const route = routes.find((r) => r.path === cronPath);
+    if (route) {
+      route.used = true;
+      route.references.push('vercel.json (cron)');
+    }
+  }
+
+  // 4. Find all source files to scan
+  const extGlob = `**/*{${config.extensions.join(',')}}`;
+  const sourceFiles = await fg(extGlob, {
+    cwd,
+    ignore: [...config.ignore.folders, ...config.ignore.files],
+  });
+
+  // 5. Collect all API paths referenced in codebase
+  const allReferencedPaths: Set<string> = new Set();
+  const fileReferences: Map<string, string[]> = new Map();
+
+  for (const file of sourceFiles) {
+    const filePath = join(cwd, file);
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const paths = extractApiPaths(content);
+
+      if (paths.length > 0) {
+        fileReferences.set(file, paths);
+        paths.forEach((p) => allReferencedPaths.add(p));
+      }
+    } catch {
+      // Skip files that can't be read
+    }
+  }
+
+  // 6. Mark routes as used if referenced
+  const referencedArray = Array.from(allReferencedPaths);
+
+  for (const route of routes) {
+    // Skip ignored routes
+    if (shouldIgnoreRoute(route.path, config.ignore.routes)) {
+      route.used = true;
+      route.references.push('(ignored by config)');
+      continue;
+    }
+
+    // Check if already marked (e.g., by vercel cron)
+    if (route.used) continue;
+
+    // Check references
+    if (isRouteReferenced(route.path, referencedArray)) {
+      route.used = true;
+
+      // Find which files reference this route
+      for (const [file, paths] of fileReferences) {
+        if (paths.some((p) => isRouteReferenced(route.path, [p]))) {
+          route.references.push(file);
+        }
+      }
+    }
+  }
+
+  return {
+    total: routes.length,
+    used: routes.filter((r) => r.used).length,
+    unused: routes.filter((r) => !r.used).length,
+    routes,
+  };
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+export interface IgnoreConfig {
+  routes: string[];
+  folders: string[];
+  files: string[];
+}
+
+export interface Config {
+  dir: string;
+  ignore: IgnoreConfig;
+  extensions: string[];
+}
+
+export interface ApiRoute {
+  /** API path like /api/users */
+  path: string;
+  /** File path like app/api/users/route.ts */
+  filePath: string;
+  /** Whether the route is used */
+  used: boolean;
+  /** Files that reference this route */
+  references: string[];
+}
+
+export interface ScanResult {
+  total: number;
+  used: number;
+  unused: number;
+  routes: ApiRoute[];
+}
+
+export interface VercelConfig {
+  crons?: Array<{ path: string; schedule: string }>;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}