@iamkurubaran/dead-code 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2026-07-07
+
+### Changed
+
+- Updated repository references and packaging metadata to point to the correct GitHub repository.
+- Refreshed the README to be more polished, professional, and developer-friendly.
+
+## [1.0.0] - 2026-07-07
+
+### Added
+
+- Initial release.
+- Cross-file, monorepo-aware detection of unused exports.
+- Static analysis for ES modules (named, default, namespace, dynamic `import()`,
+  re-exports, `as` aliases), CommonJS (`require`, destructured require,
+  `module.exports`, `exports.x`), and TypeScript (`interface`, `type`, `enum`,
+  `namespace`, `export type`).
+- Automatic entry-point discovery from every `package.json` in the tree
+  (`main`, `module`, `bin`, `exports`) plus user-supplied `--entry` globs.
+- Extensionless and `index.*` directory import resolution, including `.js`
+  specifiers that resolve to `.ts` sources.
+- Barrel (`export * from`) usage propagation to avoid false positives.
+- Human-readable terminal reporter and machine-readable `--json` reporter.
+- `--fail-on-found` flag for CI pipelines.
+- Programmatic API via `findDeadCode()`.
+
+[1.0.1]: https://github.com/iamkurubaran/DeadCode/releases/tag/v1.0.1
+[1.0.0]: https://github.com/iamkurubaran/DeadCode/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kurubaran Anandhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @iamkurubaran/dead-code
+
+A fast, zero-config CLI for finding exports that are imported nowhere in your project or monorepo.
+
+[![npm version](https://img.shields.io/npm/v/@iamkurubaran/dead-code.svg)](https://www.npmjs.com/package/@iamkurubaran/dead-code)
+[![npm downloads](https://img.shields.io/npm/dm/@iamkurubaran/dead-code.svg)](https://www.npmjs.com/package/@iamkurubaran/dead-code)
+[![node](https://img.shields.io/node/v/@iamkurubaran/dead-code.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@iamkurubaran/dead-code.svg)](./LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-iamkurubaran%2FDeadCode-181717?logo=github)](https://github.com/iamkurubaran/DeadCode)
+
+## Why this tool exists
+
+Dead exports are easy to miss in growing codebases. They often linger after refactors, redesigns, or API cleanup, and they can make maintenance harder than it needs to be.
+
+`dead-code` helps you find exports that are no longer consumed anywhere in your repository so you can remove them confidently.
+
+## Key features
+
+- Cross-file and cross-package analysis for monorepos
+- Zero configuration and no build step required
+- Support for ES modules, CommonJS, and TypeScript syntax
+- Entry-point awareness for public APIs and package exports
+- Human-readable terminal output and JSON output for CI
+
+## Installation
+
+```bash
+npm install --save-dev @iamkurubaran/dead-code
+```
+
+You can also run it without installing it globally:
+
+```bash
+npx @iamkurubaran/dead-code
+```
+
+Requirements: Node.js 18 or newer.
+
+## Quick start
+
+From the root of your project:
+
+```bash
+npx @iamkurubaran/dead-code
+```
+
+To protect your public API from being reported as unused, add entry points:
+
+```bash
+dead-code --entry "src/index.ts" --entry "src/index.js"
+```
+
+For CI workflows, fail the build when dead exports are found:
+
+```bash
+dead-code --fail-on-found --entry "src/index.ts"
+```
+
+## CLI reference
+
+```bash
+dead-code [paths...] [options]
+```
+
+### Common options
+
+- `-e, --entry <glob>`: treat matching files as public entry points
+- `-i, --ignore <glob>`: exclude additional files or patterns
+- `--cwd <dir>`: analyze a different project root
+- `--json`: emit structured JSON output
+- `--fail-on-found`: exit with code `1` when unused exports are found
+- `-h, --help`: show help
+- `-v, --version`: show the installed version
+
+## Programmatic API
+
+```js
+import { findDeadCode } from '@iamkurubaran/dead-code';
+
+const result = await findDeadCode({
+  cwd: process.cwd(),
+  patterns: ['src/**/*.ts'],
+  entry: ['src/index.ts'],
+  ignore: ['**/*.test.ts']
+});
+
+console.log(result.unused);
+```
+
+## Development
+
+```bash
+git clone https://github.com/iamkurubaran/DeadCode.git
+cd DeadCode
+npm install
+npm test
+```
+
+## Contributing
+
+Contributions are welcome. Please open an issue or submit a pull request if you would like to improve the analyzer, add support for new syntax, or improve the documentation.
+
+## License
+
+[MIT](./LICENSE) © Kurubaran Anandhan

package/bin/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import pc from 'picocolors';
+import { findDeadCode } from '../src/index.js';
+import { reportTerminal } from '../src/reporters/terminal.js';
+import { reportJson } from '../src/reporters/json.js';
+
+const HELP = `
+${pc.bold('dead-code')} — find unused exports across a monorepo
+
+${pc.bold('USAGE')}
+  dead-code [paths...] [options]
+
+${pc.bold('ARGUMENTS')}
+  paths                 One or more glob patterns to scan
+                        (default: **/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts})
+
+${pc.bold('OPTIONS')}
+  -e, --entry <glob>    Mark files as public API entry points (repeatable).
+                        Their exports are never reported as dead.
+  -i, --ignore <glob>   Extra ignore pattern (repeatable).
+      --cwd <dir>       Project root to analyze (default: current directory).
+      --json            Output machine-readable JSON.
+      --fail-on-found   Exit with code 1 if any dead exports are found (CI).
+  -h, --help            Show this help.
+  -v, --version         Show version.
+
+${pc.bold('EXAMPLES')}
+  dead-code
+  dead-code "packages/**/*.ts" --entry "packages/*/src/index.ts"
+  dead-code --json --fail-on-found
+  dead-code src --ignore "**/*.stories.tsx"
+`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const opts = {
+    patterns: [],
+    entry: [],
+    ignore: [],
+    cwd: undefined,
+    json: false,
+    failOnFound: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        console.log(HELP);
+        return 0;
+      case '-v':
+      case '--version': {
+        const { readFile } = await import('node:fs/promises');
+        const { fileURLToPath } = await import('node:url');
+        const url = new URL('../package.json', import.meta.url);
+        const pkg = JSON.parse(await readFile(fileURLToPath(url), 'utf8'));
+        console.log(pkg.version);
+        return 0;
+      }
+      case '-e':
+      case '--entry':
+        opts.entry.push(argv[++i]);
+        break;
+      case '-i':
+      case '--ignore':
+        opts.ignore.push(argv[++i]);
+        break;
+      case '--cwd':
+        opts.cwd = argv[++i];
+        break;
+      case '--json':
+        opts.json = true;
+        break;
+      case '--fail-on-found':
+        opts.failOnFound = true;
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          console.error(pc.red(`Unknown option: ${arg}`));
+          console.error(`Run ${pc.cyan('dead-code --help')} for usage.`);
+          return 2;
+        }
+        opts.patterns.push(arg);
+    }
+  }
+
+  const result = await findDeadCode({
+    cwd: opts.cwd,
+    patterns: opts.patterns,
+    ignore: opts.ignore,
+    entry: opts.entry,
+  });
+
+  if (opts.json) {
+    reportJson(result, result.root);
+  } else {
+    reportTerminal(result, result.root);
+  }
+
+  if (opts.failOnFound && result.unused.length > 0) return 1;
+  return 0;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(pc.red('dead-code crashed:'), err.message);
+    process.exit(2);
+  });

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@iamkurubaran/dead-code",
+  "version": "1.0.2",
+  "description": "Find unused exports across a monorepo — not just per-file. A fast, zero-config CLI that builds a cross-file module graph and reports exports that are imported nowhere.",
+  "keywords": [
+    "dead-code",
+    "unused-exports",
+    "unused-code",
+    "monorepo",
+    "tree-shaking",
+    "linter",
+    "static-analysis",
+    "code-cleanup",
+    "refactoring",
+    "cli",
+    "typescript",
+    "javascript",
+    "esm",
+    "commonjs"
+  ],
+  "license": "MIT",
+  "author": "Kurubaran Anandhan",
+  "type": "module",
+  "bin": {
+    "dead-code": "bin/cli.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "start": "node bin/cli.js",
+    "lint:self": "node bin/cli.js \"src/**/*.js\" \"bin/**/*.js\" --entry \"src/index.js\" --entry \"bin/cli.js\"",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.2",
+    "picocolors": "^1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iamkurubaran/DeadCode.git"
+  },
+  "homepage": "https://github.com/iamkurubaran/DeadCode#readme",
+  "bugs": {
+    "url": "https://github.com/iamkurubaran/DeadCode/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/analyzers/entrypoints.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { resolveImport } from '../utils/paths.js';
+
+/**
+ * Determine the set of entry-point files whose exports form the public API
+ * and should therefore never be flagged as dead.
+ *
+ * Sources:
+ *   - package.json "main", "module", "bin", "exports"
+ *   - test files (they consume exports but are leaves; we treat their imports
+ *     as usage automatically, so no special handling needed here)
+ *   - user-supplied entry globs
+ *
+ * @param {string} root project root
+ * @param {Set<string>} knownFiles resolved set of scanned files
+ * @param {string[]} userEntries extra glob patterns from CLI
+ * @returns {Promise<Set<string>>}
+ */
+export async function resolveEntryPoints(root, knownFiles, userEntries = []) {
+  const entries = new Set();
+
+  // Walk every package.json in the tree (monorepo-aware).
+  const pkgFiles = await fg('**/package.json', {
+    cwd: root,
+    absolute: true,
+    ignore: ['**/node_modules/**'],
+  });
+
+  for (const pkgFile of pkgFiles) {
+    let pkg;
+    try {
+      pkg = JSON.parse(await fs.readFile(pkgFile, 'utf8'));
+    } catch {
+      continue;
+    }
+    const pkgDir = path.dirname(pkgFile);
+    const specifiers = collectPkgEntrySpecifiers(pkg);
+    for (const spec of specifiers) {
+      const normalized = spec.startsWith('.') ? spec : './' + spec;
+      const resolved = resolveImport(
+        path.join(pkgDir, 'package.json'),
+        normalized,
+        knownFiles
+      );
+      if (resolved) entries.add(resolved);
+    }
+  }
+
+  // User-supplied entry globs.
+  if (userEntries.length) {
+    const matched = await fg(userEntries, {
+      cwd: root,
+      absolute: true,
+      ignore: ['**/node_modules/**'],
+    });
+    for (const m of matched) if (knownFiles.has(m)) entries.add(m);
+  }
+
+  return entries;
+}
+
+function collectPkgEntrySpecifiers(pkg) {
+  const out = [];
+  if (typeof pkg.main === 'string') out.push(pkg.main);
+  if (typeof pkg.module === 'string') out.push(pkg.module);
+
+  if (typeof pkg.bin === 'string') out.push(pkg.bin);
+  else if (pkg.bin && typeof pkg.bin === 'object') out.push(...Object.values(pkg.bin));
+
+  collectExportsField(pkg.exports, out);
+  return out.filter((s) => typeof s === 'string');
+}
+
+function collectExportsField(exp, out) {
+  if (!exp) return;
+  if (typeof exp === 'string') {
+    out.push(exp);
+    return;
+  }
+  if (typeof exp === 'object') {
+    for (const value of Object.values(exp)) collectExportsField(value, out);
+  }
+}

package/src/analyzers/graph.js

@@ -0,0 +1,149 @@
+import { resolveImport } from '../utils/paths.js';
+
+/**
+ * Build a cross-file module graph and compute which exports are never
+ * imported anywhere in the project.
+ *
+ * Key ideas that make this monorepo-aware (vs per-file linters):
+ *   1. We resolve every relative import to a concrete file on disk.
+ *   2. Usage is aggregated ACROSS all files: an export is "used" if ANY
+ *      other file imports it (by name, namespace, or via export-star chains).
+ *   3. Entry points (bin, main, exports in package.json, and user globs) are
+ *      roots whose exports are always considered "used" (public API surface).
+ *
+ * @param {Map<string, object>} fileMap  absPath -> scanFile() record
+ * @param {object} opts
+ * @param {Set<string>} opts.entryFiles  absolute paths treated as public roots
+ * @returns {{
+ *   unused: Array<{file:string, name:string, line:number, kind:string}>,
+ *   totalExports: number,
+ *   usedExports: number,
+ *   fileCount: number
+ * }}
+ */
+export function analyze(fileMap, { entryFiles = new Set() } = {}) {
+  const knownFiles = new Set(fileMap.keys());
+
+  // usage[targetFile] = Set of names consumed from that file (or '*' for all)
+  const usage = new Map();
+  const markUsed = (file, name) => {
+    if (!usage.has(file)) usage.set(file, new Set());
+    usage.get(file).add(name);
+  };
+
+  // Track re-export star edges so we can propagate usage transitively:
+  // if file A does `export * from B` and something imports name X from A,
+  // then X counts as used in B too.
+  const starReexports = new Map(); // file -> [targetFile,...]
+
+  // ---- First pass: resolve imports and record direct usage --------------
+  for (const [absPath, record] of fileMap) {
+    for (const imp of record.imports) {
+      const target = resolveImport(absPath, imp.specifier, knownFiles);
+      if (!target) continue; // external package or unresolved
+
+      if (imp.sideEffectOnly) {
+        // Side-effect import doesn't consume any named export, but keeps the
+        // module "reachable". We record nothing name-specific.
+        continue;
+      }
+
+      if (imp.namespace) {
+        markUsed(target, '*');
+        // A namespace/star re-export also creates a passthrough edge.
+        starReexports.set(absPath, [...(starReexports.get(absPath) || []), target]);
+        continue;
+      }
+
+      for (const name of imp.names) {
+        markUsed(target, name);
+      }
+    }
+  }
+
+  // ---- Mark entry-point exports as used (public API) --------------------
+  for (const entry of entryFiles) {
+    if (fileMap.has(entry)) markUsed(entry, '*');
+  }
+
+  // ---- Propagate usage through export-star chains -----------------------
+  // If names are consumed from a barrel file that re-exports *, those names
+  // may actually live in the re-exported target.
+  propagateStarUsage(fileMap, usage, starReexports, knownFiles, markUsed);
+
+  // ---- Second pass: determine unused exports ----------------------------
+  const unused = [];
+  let totalExports = 0;
+  let usedExports = 0;
+
+  for (const [absPath, record] of fileMap) {
+    const usedHere = usage.get(absPath);
+    const allUsed = usedHere && usedHere.has('*');
+
+    for (const exp of record.exports) {
+      if (exp.kind === 'star') continue; // re-export star isn't a named export
+      totalExports++;
+
+      const isUsed = allUsed || (usedHere && usedHere.has(exp.name));
+
+      if (isUsed) {
+        usedExports++;
+      } else {
+        unused.push({
+          file: absPath,
+          name: exp.name,
+          line: exp.line,
+          kind: exp.kind,
+        });
+      }
+    }
+  }
+
+  return {
+    unused,
+    totalExports,
+    usedExports,
+    fileCount: fileMap.size,
+  };
+}
+
+/**
+ * When a barrel re-exports `* from './target'`, and some file imports named
+ * bindings from the barrel, we can't know which names came from which target.
+ * Conservative rule: if a barrel has any '*' usage OR named usage, propagate
+ * '*' to all its star-reexport targets. This avoids false positives (marking
+ * genuinely-used code as dead) at the cost of occasionally missing dead code.
+ */
+function propagateStarUsage(fileMap, usage, starReexports, knownFiles, markUsed) {
+  let changed = true;
+  const guard = new Set();
+  while (changed) {
+    changed = false;
+    for (const [absPath, record] of fileMap) {
+      // Does this file re-export * from somewhere?
+      const starTargets = [];
+      for (const imp of record.imports) {
+        if (imp.namespace && imp.specifier.startsWith('.')) {
+          const target = resolveImport(absPath, imp.specifier, knownFiles);
+          if (target) starTargets.push(target);
+        }
+      }
+      if (starTargets.length === 0) continue;
+
+      const usedHere = usage.get(absPath);
+      const consumed = usedHere && usedHere.size > 0;
+      if (!consumed) continue;
+
+      for (const target of starTargets) {
+        const key = absPath + '->' + target;
+        const before = usage.get(target)?.size || 0;
+        markUsed(target, '*');
+        const after = usage.get(target).size;
+        if (after !== before && !guard.has(key)) {
+          guard.add(key);
+          changed = true;
+        }
+      }
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import fg from 'fast-glob';
+import { scanFile } from './scanners/file.js';
+import { analyze } from './analyzers/graph.js';
+import { resolveEntryPoints } from './analyzers/entrypoints.js';
+import { JS_EXTENSIONS } from './utils/paths.js';
+
+const DEFAULT_IGNORE = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/coverage/**',
+  '**/.next/**',
+  '**/*.d.ts',
+];
+
+/**
+ * Run a full dead-code analysis over a project.
+ *
+ * @param {object} options
+ * @param {string} [options.cwd] project root (default: process.cwd())
+ * @param {string[]} [options.patterns] file globs to scan
+ * @param {string[]} [options.ignore] extra ignore globs
+ * @param {string[]} [options.entry] extra entry-point globs (kept as public API)
+ * @param {boolean} [options.includeTests] treat test files as scannable (default true)
+ * @returns {Promise<object>} analysis result
+ */
+export async function findDeadCode(options = {}) {
+  const root = path.resolve(options.cwd || process.cwd());
+  const patterns =
+    options.patterns && options.patterns.length
+      ? options.patterns
+      : ['**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}'];
+
+  const ignore = [...DEFAULT_IGNORE, ...(options.ignore || [])];
+
+  const files = await fg(patterns, {
+    cwd: root,
+    absolute: true,
+    ignore,
+    dot: false,
+  });
+
+  const supported = files.filter((f) => JS_EXTENSIONS.includes(path.extname(f)));
+
+  // Scan all files in parallel.
+  const records = await Promise.all(
+    supported.map((f) => scanFile(f).catch(() => null))
+  );
+
+  const fileMap = new Map();
+  for (const rec of records) {
+    if (rec) fileMap.set(rec.path, rec);
+  }
+
+  const knownFiles = new Set(fileMap.keys());
+  const entryFiles = await resolveEntryPoints(root, knownFiles, options.entry || []);
+
+  const result = analyze(fileMap, { entryFiles });
+  result.root = root;
+  return result;
+}
+
+export { analyze, scanFile };

package/src/reporters/json.js

@@ -0,0 +1,23 @@
+import { toRelative } from '../utils/paths.js';
+
+export function reportJson(result, root) {
+  const payload = {
+    summary: {
+      files: result.fileCount,
+      totalExports: result.totalExports,
+      usedExports: result.usedExports,
+      unusedExports: result.unused.length,
+    },
+    unused: result.unused
+      .map((u) => ({
+        file: toRelative(root, u.file),
+        name: u.name,
+        line: u.line,
+        kind: u.kind,
+      }))
+      .sort((a, b) =>
+        a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file)
+      ),
+  };
+  console.log(JSON.stringify(payload, null, 2));
+}

package/src/reporters/terminal.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import pc from 'picocolors';
+import { toRelative } from '../utils/paths.js';
+
+const KIND_LABEL = {
+  default: 'default export',
+  variable: 'const/let/var',
+  function: 'function',
+  class: 'class',
+  type: 'type/interface',
+  named: 'named export',
+  cjs: 'commonjs export',
+};
+
+export function reportTerminal(result, root) {
+  const { unused, totalExports, usedExports, fileCount } = result;
+
+  if (unused.length === 0) {
+    console.log(
+      pc.green('✔ No unused exports found') +
+        pc.dim(
+          ` — scanned ${fileCount} files, ${totalExports} exports all reachable.`
+        )
+    );
+    return;
+  }
+
+  // Group by file for readable output.
+  const byFile = new Map();
+  for (const item of unused) {
+    if (!byFile.has(item.file)) byFile.set(item.file, []);
+    byFile.get(item.file).push(item);
+  }
+
+  console.log(
+    pc.bold(pc.red(`✖ Found ${unused.length} unused export${unused.length === 1 ? '' : 's'}`)) +
+      pc.dim(` across ${byFile.size} file${byFile.size === 1 ? '' : 's'}\n`)
+  );
+
+  const sortedFiles = [...byFile.keys()].sort();
+  for (const file of sortedFiles) {
+    const rel = toRelative(root, file);
+    console.log(pc.underline(pc.cyan(rel)));
+    const items = byFile.get(file).sort((a, b) => a.line - b.line);
+    for (const item of items) {
+      const loc = pc.dim(`${rel}:${item.line}`);
+      const kind = pc.dim(`(${KIND_LABEL[item.kind] || item.kind})`);
+      const name = item.name === 'default' ? pc.italic('default') : pc.yellow(item.name);
+      console.log(`  ${pc.red('•')} ${name} ${kind}  ${loc}`);
+    }
+    console.log('');
+  }
+
+  const pct = totalExports ? Math.round((usedExports / totalExports) * 100) : 100;
+  console.log(
+    pc.dim(
+      `Scanned ${fileCount} files · ${usedExports}/${totalExports} exports used (${pct}%)`
+    )
+  );
+}

package/src/scanners/exports.js

@@ -0,0 +1,148 @@
+/**
+ * Extract exported names from a piece of (comment/string-stripped) source.
+ * Returns an array of { name, line, kind } where name === 'default' for
+ * default exports and '*' for a re-export star.
+ */
+export function extractExports(code) {
+  const results = [];
+  const seen = new Set();
+
+  const add = (name, index, kind) => {
+    if (!name) return;
+    const key = name + ':' + index;
+    if (seen.has(key)) return;
+    seen.add(key);
+    results.push({ name, line: lineAt(code, index), kind });
+  };
+
+  // export default ...
+  for (const m of code.matchAll(/\bexport\s+default\b/g)) {
+    add('default', m.index, 'default');
+  }
+
+  // export const/let/var NAME  (also multiple: export const a = 1, b = 2)
+  // Capture the whole declaration up to the statement terminator so that
+  // additional comma-separated bindings after an `=` are not lost.
+  for (const m of code.matchAll(/\bexport\s+(?:const|let|var)\s+([\s\S]*?)(?:;|\n)/g)) {
+    for (const name of parseBindingNames(m[1])) add(name, m.index, 'variable');
+  }
+
+  // export function NAME / export async function NAME / export function* NAME
+  for (const m of code.matchAll(
+    /\bexport\s+(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/g
+  )) {
+    add(m[1], m.index, 'function');
+  }
+
+  // export class NAME
+  for (const m of code.matchAll(/\bexport\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/g)) {
+    add(m[1], m.index, 'class');
+  }
+
+  // TypeScript: export interface/type/enum NAME
+  for (const m of code.matchAll(
+    /\bexport\s+(?:declare\s+)?(?:interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/g
+  )) {
+    add(m[1], m.index, 'type');
+  }
+
+  // export { a, b as c }  and  export { a } from './x'
+  for (const m of code.matchAll(/\bexport\s*\{([^}]*)\}(\s*from\s*['"][^'"]*['"])?/g)) {
+    for (const name of parseExportSpecifiers(m[1])) add(name, m.index, 'named');
+  }
+
+  // export * from './x'  — re-export star (treated as a usage passthrough)
+  for (const m of code.matchAll(/\bexport\s*\*\s*from\s*['"][^'"]*['"]/g)) {
+    add('*', m.index, 'star');
+  }
+
+  // CommonJS: module.exports.NAME = / exports.NAME =
+  for (const m of code.matchAll(/\b(?:module\.)?exports\.([A-Za-z_$][\w$]*)\s*=/g)) {
+    add(m[1], m.index, 'cjs');
+  }
+
+  // CommonJS: module.exports = { a, b, c }
+  for (const m of code.matchAll(/\bmodule\.exports\s*=\s*\{([^}]*)\}/g)) {
+    for (const name of parseObjectKeys(m[1])) add(name, m.index, 'cjs');
+  }
+
+  return results;
+}
+
+function parseBindingNames(fragment) {
+  // Handles: "a = 1, b = 2" and destructuring "{ a, b }" / "[a, b]".
+  // We split on TOP-LEVEL commas only (depth 0), so commas inside an
+  // initializer like `a = f(1, 2), b = 3` don't create phantom bindings.
+  const names = [];
+  const parts = splitTopLevel(fragment);
+  for (let part of parts) {
+    part = part.trim();
+    if (!part) continue;
+    // Take only the binding side (before '=').
+    const binding = part.split('=')[0].trim();
+    // Destructuring pattern -> pull each identifier.
+    if (/^[{[]/.test(binding)) {
+      const inner = binding.replace(/[{}[\]]/g, ' ');
+      for (const seg of inner.split(',')) {
+        const m = seg.trim().match(/([A-Za-z_$][\w$]*)\s*$/);
+        if (m) names.push(m[1]);
+      }
+    } else {
+      const m = binding.match(/^([A-Za-z_$][\w$]*)/);
+      if (m) names.push(m[1]);
+    }
+  }
+  return names;
+}
+
+function splitTopLevel(str) {
+  const parts = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of str) {
+    if (ch === '(' || ch === '[' || ch === '{') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}') depth--;
+    if (ch === ',' && depth === 0) {
+      parts.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+
+function parseExportSpecifiers(inner) {
+  // "a, b as c, type D" -> exported names are a, c, D
+  const names = [];
+  for (let part of inner.split(',')) {
+    part = part.trim().replace(/^type\s+/, '');
+    if (!part) continue;
+    const asMatch = part.match(/\bas\s+([A-Za-z_$][\w$]*)/);
+    if (asMatch) {
+      names.push(asMatch[1]);
+    } else {
+      const m = part.match(/^([A-Za-z_$][\w$]*)/);
+      if (m) names.push(m[1]);
+    }
+  }
+  return names;
+}
+
+function parseObjectKeys(inner) {
+  const names = [];
+  for (const part of inner.split(',')) {
+    const m = part.trim().match(/^([A-Za-z_$][\w$]*)/);
+    if (m) names.push(m[1]);
+  }
+  return names;
+}
+
+function lineAt(code, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < code.length; i++) {
+    if (code[i] === '\n') line++;
+  }
+  return line;
+}

package/src/scanners/file.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import { stripNonCode } from './strip.js';
+import { extractExports } from './exports.js';
+import { extractImports } from './imports.js';
+
+/**
+ * Scan a single file into a normalized record.
+ *
+ * @param {string} absPath
+ * @returns {Promise<{
+ *   path: string,
+ *   exports: Array<{name:string,line:number,kind:string}>,
+ *   imports: Array<{specifier:string,names:string[],namespace:boolean,sideEffectOnly:boolean}>,
+ *   identifiers: Set<string>
+ * }>}
+ */
+export async function scanFile(absPath) {
+  const raw = await fs.readFile(absPath, 'utf8');
+  // For exports we defuse string contents (keywords in strings must not match).
+  // For imports we keep specifiers intact (they live inside strings).
+  const codeForExports = stripNonCode(raw, true);
+  const codeForImports = stripNonCode(raw, false);
+
+  const exportsFound = extractExports(codeForExports);
+  const importsFound = extractImports(codeForImports);
+  const identifiers = collectIdentifiers(codeForExports);
+
+  return {
+    path: absPath,
+    exports: exportsFound,
+    imports: importsFound,
+    identifiers,
+  };
+}
+
+/**
+ * Collect the set of identifier tokens used anywhere in the file. Used to
+ * detect re-exported names that are consumed via `export * from` chains and
+ * to support namespace-import member access heuristics.
+ */
+function collectIdentifiers(code) {
+  const set = new Set();
+  for (const m of code.matchAll(/[A-Za-z_$][\w$]*/g)) {
+    set.add(m[0]);
+  }
+  return set;
+}

package/src/scanners/imports.js

@@ -0,0 +1,177 @@
+/**
+ * Extract imports from (stripped) source. Returns an array of
+ * { specifier, names, namespace, sideEffectOnly }.
+ *
+ *  - names: array of imported binding names as they exist in the *source*
+ *           module (i.e. the original exported names, resolving `as`).
+ *  - namespace: true if `import * as X` or `require(...)` whole-module use,
+ *               meaning ANY export of the target could be used.
+ *  - sideEffectOnly: `import './x'` with no bindings.
+ */
+export function extractImports(code) {
+  const imports = [];
+
+  // ---- ESM: import ... from 'spec' -------------------------------------
+  for (const m of code.matchAll(/\bimport\s+([^;'"]*?)\s+from\s*['"]([^'"]+)['"]/g)) {
+    const clause = m[1].trim();
+    const specifier = m[2];
+    imports.push(parseImportClause(clause, specifier));
+  }
+
+  // ---- ESM: bare import 'spec' (side-effect only) ----------------------
+  for (const m of code.matchAll(/\bimport\s*['"]([^'"]+)['"]/g)) {
+    imports.push({
+      specifier: m[1],
+      names: [],
+      namespace: false,
+      sideEffectOnly: true,
+    });
+  }
+
+  // ---- ESM: dynamic import('spec') -------------------------------------
+  for (const m of code.matchAll(/\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    // Dynamic import returns the namespace object -> any export may be used.
+    imports.push({
+      specifier: m[1],
+      names: [],
+      namespace: true,
+      sideEffectOnly: false,
+    });
+  }
+
+  // ---- ESM: export { a } from 'spec' / export * from 'spec' ------------
+  for (const m of code.matchAll(/\bexport\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
+    imports.push({
+      specifier: m[2],
+      names: parseReexportSourceNames(m[1]),
+      namespace: false,
+      sideEffectOnly: false,
+    });
+  }
+  for (const m of code.matchAll(/\bexport\s*\*\s*from\s*['"]([^'"]+)['"]/g)) {
+    imports.push({
+      specifier: m[1],
+      names: [],
+      namespace: true, // re-export star consumes everything
+      sideEffectOnly: false,
+    });
+  }
+
+  // ---- CJS: const X = require('spec') / destructured -------------------
+  for (const m of code.matchAll(
+    /\b(?:const|let|var)\s+(\{[^}]*\}|[A-Za-z_$][\w$]*)\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+  )) {
+    const binding = m[1].trim();
+    const specifier = m[2];
+    if (binding.startsWith('{')) {
+      imports.push({
+        specifier,
+        names: parseReexportSourceNames(binding.replace(/[{}]/g, '')),
+        namespace: false,
+        sideEffectOnly: false,
+      });
+    } else {
+      imports.push({ specifier, names: [], namespace: true, sideEffectOnly: false });
+    }
+  }
+
+  // ---- CJS: bare require('spec') ---------------------------------------
+  for (const m of code.matchAll(/(?<![.\w$])require\s*\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    // Only count as side-effect if not already captured by an assignment.
+    imports.push({
+      specifier: m[1],
+      names: [],
+      namespace: false,
+      sideEffectOnly: true,
+    });
+  }
+
+  return dedupe(imports);
+}
+
+function parseImportClause(clause, specifier) {
+  const result = { specifier, names: [], namespace: false, sideEffectOnly: false };
+  if (!clause) {
+    result.sideEffectOnly = true;
+    return result;
+  }
+
+  // import * as NS from '...'
+  if (/^\*\s+as\s+[A-Za-z_$][\w$]*$/.test(clause)) {
+    result.namespace = true;
+    return result;
+  }
+
+  // Default binding + optional named/namespace
+  // Examples: "Foo", "Foo, { a, b }", "Foo, * as NS", "{ a, b as c }"
+  let rest = clause;
+
+  // Leading default import (not a brace, not a star)
+  const defaultMatch = rest.match(/^([A-Za-z_$][\w$]*)\s*(?:,|$)/);
+  if (defaultMatch && !rest.startsWith('{') && !rest.startsWith('*')) {
+    result.names.push('default');
+    rest = rest.slice(defaultMatch[0].length).trim();
+  }
+
+  if (rest.startsWith('*')) {
+    result.namespace = true;
+    return result;
+  }
+
+  const braceMatch = rest.match(/\{([^}]*)\}/);
+  if (braceMatch) {
+    for (const name of parseReexportSourceNames(braceMatch[1])) {
+      result.names.push(name);
+    }
+  }
+
+  if (result.names.length === 0 && !result.namespace) {
+    result.sideEffectOnly = true;
+  }
+  return result;
+}
+
+/**
+ * Given the inside of `{ ... }` in an import/re-export, return the names as
+ * they exist in the *source* module. For `a as b`, the source name is `a`.
+ */
+function parseReexportSourceNames(inner) {
+  const names = [];
+  for (let part of inner.split(',')) {
+    part = part.trim().replace(/^type\s+/, '');
+    if (!part) continue;
+    const asMatch = part.match(/^([A-Za-z_$][\w$]*)\s+as\s+/);
+    if (asMatch) {
+      names.push(asMatch[1]);
+    } else {
+      const m = part.match(/^([A-Za-z_$][\w$]*)/);
+      if (m) names.push(m[1]);
+    }
+  }
+  return names;
+}
+
+function dedupe(imports) {
+  const map = new Map();
+  for (const imp of imports) {
+    const existing = map.get(imp.specifier);
+    if (!existing) {
+      map.set(imp.specifier, {
+        specifier: imp.specifier,
+        names: new Set(imp.names),
+        namespace: imp.namespace,
+        sideEffectOnly: imp.sideEffectOnly,
+      });
+    } else {
+      imp.names.forEach((n) => existing.names.add(n));
+      existing.namespace = existing.namespace || imp.namespace;
+      existing.sideEffectOnly = existing.sideEffectOnly && imp.sideEffectOnly;
+    }
+  }
+  return [...map.values()].map((e) => ({
+    specifier: e.specifier,
+    names: [...e.names],
+    namespace: e.namespace,
+    sideEffectOnly: e.sideEffectOnly && e.names.size === 0 && !e.namespace,
+  }));
+}

package/src/scanners/strip.js

@@ -0,0 +1,130 @@
+/**
+ * Remove comments and string/template/regex literal *contents* from source
+ * while preserving byte length and line structure, so that later regex-based
+ * extraction never matches keywords that appear inside strings or comments.
+ *
+ * We replace removed characters with spaces (newlines preserved) so indices
+ * stay stable and line counts remain accurate for reporting.
+ *
+ * This is a lightweight lexer — not a full parser — but it correctly handles
+ * the tricky cases (regex vs division, template literals, nested comments in
+ * strings) well enough for import/export discovery.
+ *
+ * @param {string} src
+ * @returns {string}
+ */
+export function stripNonCode(src, defuseStrings = false) {
+  const out = new Array(src.length);
+  let i = 0;
+  const n = src.length;
+
+  // Tracks whether the previous significant token allows a regex to follow.
+  let prevSignificant = '';
+
+  const blank = (from, to) => {
+    for (let k = from; k < to; k++) {
+      out[k] = src[k] === '\n' ? '\n' : ' ';
+    }
+  };
+
+  while (i < n) {
+    const c = src[i];
+    const next = src[i + 1];
+
+    // Line comment
+    if (c === '/' && next === '/') {
+      let j = i + 2;
+      while (j < n && src[j] !== '\n') j++;
+      blank(i, j);
+      i = j;
+      continue;
+    }
+
+    // Block comment
+    if (c === '/' && next === '*') {
+      let j = i + 2;
+      while (j < n && !(src[j] === '*' && src[j + 1] === '/')) j++;
+      j = Math.min(j + 2, n);
+      blank(i, j);
+      i = j;
+      continue;
+    }
+
+    // Strings: ' " `
+    // We PRESERVE the quotes and contents (import/require specifiers live in
+    // strings and must survive), but we neutralize any alphabetic run inside
+    // the string so stray keywords like "export" in a path can't be matched
+    // as code. Punctuation like . / ' " is kept intact.
+    if (c === '"' || c === "'" || c === '`') {
+      const quote = c;
+      out[i] = c; // keep opening quote
+      let j = i + 1;
+      while (j < n) {
+        if (src[j] === '\\') {
+          out[j] = src[j];
+          out[j + 1] = src[j + 1];
+          j += 2;
+          continue;
+        }
+        if (src[j] === quote) break;
+        // When defusing, replace letters so keywords in strings can't match.
+        out[j] = defuseStrings && /[A-Za-z]/.test(src[j]) ? 'x' : src[j];
+        j++;
+      }
+      out[j] = quote; // keep closing quote
+      i = j + 1;
+      prevSignificant = 'str';
+      continue;
+    }
+
+    // Regex literal — only if a regex can legally start here.
+    if (c === '/' && canRegexFollow(prevSignificant)) {
+      let j = i + 1;
+      let inClass = false;
+      let valid = false;
+      while (j < n) {
+        const cj = src[j];
+        if (cj === '\\') {
+          j += 2;
+          continue;
+        }
+        if (cj === '[') inClass = true;
+        else if (cj === ']') inClass = false;
+        else if (cj === '/' && !inClass) {
+          valid = true;
+          break;
+        } else if (cj === '\n') {
+          break;
+        }
+        j++;
+      }
+      if (valid) {
+        blank(i, j + 1);
+        // skip flags
+        let k = j + 1;
+        while (k < n && /[a-z]/i.test(src[k])) {
+          out[k] = ' ';
+          k++;
+        }
+        i = k;
+        prevSignificant = 'regex';
+        continue;
+      }
+    }
+
+    // Ordinary code character
+    out[i] = c;
+    if (!/\s/.test(c)) {
+      prevSignificant = /[\w$)\].]/.test(c) ? 'value' : c;
+    }
+    i++;
+  }
+
+  return out.join('');
+}
+
+function canRegexFollow(prev) {
+  // A regex cannot follow a value/identifier/closing bracket (that's division).
+  if (prev === 'value' || prev === 'str' || prev === 'regex') return false;
+  return true;
+}

package/src/utils/paths.js

@@ -0,0 +1,56 @@
+import path from 'node:path';
+
+const JS_EXTENSIONS = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts'];
+const INDEX_FILES = JS_EXTENSIONS.map((ext) => `index${ext}`);
+
+/**
+ * Resolve a relative import specifier against the importing file's directory
+ * to an absolute file path on disk. Handles extensionless imports and
+ * directory/index resolution the way bundlers and Node do.
+ *
+ * @param {string} fromFile absolute path of the file containing the import
+ * @param {string} specifier the raw import string (e.g. './utils' or '../a.js')
+ * @param {Set<string>} knownFiles set of absolute file paths we scanned
+ * @returns {string|null} absolute resolved path, or null if unresolved
+ */
+export function resolveImport(fromFile, specifier, knownFiles) {
+  // Only resolve relative imports. Bare specifiers are external packages.
+  if (!specifier.startsWith('.')) return null;
+
+  const base = path.resolve(path.dirname(fromFile), specifier);
+
+  // 1. Exact match (import already had an extension)
+  if (knownFiles.has(base)) return base;
+
+  // 2. Try appending each known extension
+  for (const ext of JS_EXTENSIONS) {
+    const candidate = base + ext;
+    if (knownFiles.has(candidate)) return candidate;
+  }
+
+  // 3. Directory import -> index file
+  for (const indexFile of INDEX_FILES) {
+    const candidate = path.join(base, indexFile);
+    if (knownFiles.has(candidate)) return candidate;
+  }
+
+  // 4. Handle the case where the specifier pointed at a .js file
+  //    but the source on disk is .ts (common in TS projects using
+  //    ESM-style ".js" import specifiers).
+  const parsed = path.parse(base);
+  if (parsed.ext) {
+    const withoutExt = path.join(parsed.dir, parsed.name);
+    for (const ext of JS_EXTENSIONS) {
+      const candidate = withoutExt + ext;
+      if (knownFiles.has(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+export function toRelative(root, file) {
+  return path.relative(root, file) || path.basename(file);
+}
+
+export { JS_EXTENSIONS };