ghostdep 0.1.0

package/README.md

@@ -0,0 +1,176 @@
+# ghostdep 👻
+
+[![CI](https://github.com/yourusername/ghostdep/actions/workflows/ci.yml/badge.svg)](https://github.com/yourusername/ghostdep/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/ghostdep.svg?style=flat)](https://www.npmjs.com/package/ghostdep)
+[![license](https://img.shields.io/npm/l/ghostdep.svg)](https://github.com/yourusername/ghostdep/blob/main/LICENSE)
+
+An ultra-fast, zero-config **npm dependency scanner** and **nodejs tooling** utility to analyze, audit, and optimize your project dependencies. Instantly audit project health, calculate a dependency health score, and prune duplicate or version drift mismatches.
+
+Use **ghostdep** to optimize your dependency tree, secure build-time scripts, and clean up your `package.json` configurations.
+
+---
+
+## 📖 Table of Contents
+- [Introduction](#-introduction)
+- [Features](#-features)
+- [Installation](#-installation)
+- [CLI Commands & Usage](#-cli-commands--usage)
+- [Examples](#-examples)
+- [Programmatic API](#-programmatic-api)
+- [FAQ](#-faq)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+---
+
+## 🌟 Introduction
+
+In modern Node.js and TypeScript codebases, dependencies can rapidly drift. Issues like **ghost dependencies** (importing packages in your code that are not declared in `package.json`) and **unused dependencies** (packages declared but never actually used) bloat lockfiles, slow down installation times, and cause runtime crashes in containerized/production environments.
+
+`ghostdep` resolves these problems by scanning your source code, comparing actual imports with your `package.json` declarations, walking the `node_modules` hierarchy, and calculating a precise **dependency health score**.
+
+---
+
+## ✨ Features
+
+- 👻 **Ghost Dependency Detection**: Identify packages installed in `node_modules` and used in code, but missing from `package.json`.
+- 🧟 **Zombie Dependency Detection**: Spot **unused dependencies** that are declared but never imported or required in your codebase.
+- 📦 **Duplicate Package Finder**: Scan the active node_modules tree (with full PNPM symlink cycle protection) to identify package bloat from multiple resolved versions.
+- 🔄 **Version Drift Auditing**: Compare declared semver ranges in `package.json` with actual installed versions to trace major, minor, or patch drifts.
+- 📊 **Dependency Health Score**: Get an automated quality grade (A-F) based on customizable penalties.
+- ⚡ **TS Compiler AST Parser**: Scans code utilizing the TypeScript Compiler API for ESM imports/exports, dynamic imports, and CommonJS require statements.
+
+---
+
+## 🚀 Installation
+
+Install globally to use the CLI anywhere:
+
+```bash
+npm install -g ghostdep
+```
+
+Or install locally in your project:
+
+```bash
+npm install --save-dev ghostdep
+```
+
+---
+
+## 💻 CLI Commands & Usage
+
+Run the scanner directly from your project folder:
+
+```bash
+npx ghostdep
+```
+
+### Options
+
+```
+Usage: ghostdep [options] [command]
+
+Audit Node.js/TypeScript projects for ghost, zombie, duplicate, and drifted dependencies.
+
+Options:
+  -V, --version       output the version number
+  -d, --cwd <path>    Working directory of the target project (default: current directory)
+  --include-dev       Include devDependencies in analysis checks (default: false)
+  --include <patterns> Comma-separated glob patterns of source files to include
+  --exclude <patterns> Comma-separated glob patterns of source files to ignore
+  -h, --help          display help for command
+
+Commands:
+  scan                Scan project dependencies and print a detailed console report (default)
+  json                Scan project dependencies and output a raw JSON report
+  health              Scan project dependencies and print only the health score & grade summary
+  help [command]      display help for command
+```
+
+---
+
+## 📝 Examples
+
+### Pretty Report Output
+To execute a standard audit scan in the current directory and display a clean terminal report:
+```bash
+npx ghostdep scan
+```
+
+### CI/CD Automation (JSON Output)
+To capture a full structured JSON report file for logging or build pipeline consumption:
+```bash
+npx ghostdep json > report.json
+```
+
+### Quick Score Summary
+To query just the final computed health grade of the codebase:
+```bash
+npx ghostdep health
+# Output: Health Score: 95/100 (A)
+```
+
+---
+
+## ⚙️ Programmatic API
+
+You can import `ghostdep` directly into your Node.js/TypeScript scripts:
+
+```typescript
+import { runScan } from 'ghostdep';
+
+async function audit() {
+  const report = await runScan({
+    cwd: '/path/to/project',
+    includeDev: true,
+    exclude: ['**/test/**', '**/dist/**']
+  });
+
+  console.log(`Project: ${report.project.name} (v${report.project.version})`);
+  console.log(`Overall Score: ${report.health.score}% (${report.health.grade})`);
+  
+  if (report.ghosts.length > 0) {
+    console.log('Detected Ghost dependencies:', report.ghosts.map(g => g.name));
+  }
+}
+
+audit();
+```
+
+---
+
+## ❓ FAQ
+
+### What are "Ghost Dependencies"?
+Ghost dependencies are packages that your code imports (e.g. `import axios from 'axios'`), but which are not listed in your `package.json` dependencies. This often happens because the package is installed transitively by another dependency, meaning your code works locally but will fail when deployed or run in environments with flat node_modules trees.
+
+### What are "Zombie Dependencies"?
+Zombie dependencies are the opposite: they are listed in your `package.json` file but are never imported or required in your codebase. These waste disk space, slow down `npm install` times, and create security/maintenance overhead.
+
+### Does it support PNPM and Yarn?
+Yes! `ghostdep` implements a symlink-resolving walk algorithm that successfully navigates PNPM virtual stores (`.pnpm`) and Yarn workspaces without infinite loops or duplicate evaluation of symlinks.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+1. Fork the repository.
+2. Create your feature branch (`git checkout -b feature/amazing-feature`).
+3. Commit your changes (`git commit -m 'Add amazing feature'`).
+4. Push to the branch (`git push origin feature/amazing-feature`).
+5. Open a Pull Request.
+
+Make sure to run formatting and test suites before committing:
+```bash
+npm run format
+npm run lint
+npm test
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/bin/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":""}

package/dist/bin/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { runScan } from '../src/scanner.js';
+import { reportToConsole } from '../src/reporter.js';
+const program = new Command();
+// Setup CLI defaults, options, and help metadata
+program
+    .name('ghostdep')
+    .description('Audit Node.js/TypeScript projects for ghost, zombie, duplicate, and drifted dependencies.')
+    .version('0.1.0')
+    .option('-d, --cwd <path>', 'Working directory of the target project', process.cwd())
+    .option('--include-dev', 'Include devDependencies in analysis checks', false)
+    .option('--include <patterns>', 'Comma-separated glob patterns of source files to include')
+    .option('--exclude <patterns>', 'Comma-separated glob patterns of source files to ignore');
+/**
+ * Utility helper to parse comma-separated CLI inputs into string arrays.
+ */
+function parseList(value) {
+    return value ? value.split(',').map((item) => item.trim()) : undefined;
+}
+/**
+ * Common execution runner that triggers the scanner and formats the report.
+ */
+async function executeScan(format) {
+    const options = program.opts();
+    try {
+        const scanOptions = {
+            cwd: options['cwd'] || process.cwd(),
+            includeDev: !!options['includeDev'],
+        };
+        const includeList = parseList(options['include']);
+        if (includeList) {
+            scanOptions.include = includeList;
+        }
+        const excludeList = parseList(options['exclude']);
+        if (excludeList) {
+            scanOptions.exclude = excludeList;
+        }
+        // Import the type ScanOptions inside bin/cli.ts
+        const report = await runScan(scanOptions);
+        if (format === 'json') {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else if (format === 'health') {
+            const score = report.health.score;
+            const grade = report.health.grade;
+            const gradeColor = grade === 'A' || grade === 'B'
+                ? chalk.bold.green
+                : grade === 'C' || grade === 'D'
+                    ? chalk.bold.yellow
+                    : chalk.bold.red;
+            const scoreColor = score >= 90
+                ? chalk.bold.green
+                : score >= 75
+                    ? chalk.bold.cyan
+                    : score >= 60
+                        ? chalk.bold.yellow
+                        : chalk.bold.red;
+            console.log(`Health Score: ${scoreColor(score)}/100 (${gradeColor(grade)})`);
+        }
+        else {
+            reportToConsole(report);
+        }
+        // Set non-zero exit code if critical issue (ghost dependencies) is discovered
+        if (report.ghosts.length > 0) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        const err = error;
+        console.error(chalk.red.bold(`\nError: ${err.message}`));
+        process.exit(1);
+    }
+}
+// 1. Default action (when no subcommand is passed)
+program.action(async () => {
+    await executeScan('pretty');
+});
+// 2. "scan" subcommand (same behavior as default, but explicit)
+program
+    .command('scan')
+    .description('Scan project dependencies and print a detailed console report (default action)')
+    .action(async () => {
+    await executeScan('pretty');
+});
+// 3. "json" subcommand (outputs raw JSON report for CI/pipeline consumption)
+program
+    .command('json')
+    .description('Scan project dependencies and output a raw JSON report')
+    .action(async () => {
+    await executeScan('json');
+});
+// 4. "health" subcommand (outputs only the score summary)
+program
+    .command('health')
+    .description('Scan project dependencies and print only the health score & grade summary')
+    .action(async () => {
+    await executeScan('health');
+});
+// Run parser
+program.parse(process.argv);
+//# sourceMappingURL=cli.js.map

package/dist/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/detectors/drift.d.ts

@@ -0,0 +1,12 @@
+import { VersionDrift, PackageJson } from '../types.js';
+/**
+ * Detects version drift issues: discrepancies between the declared semver ranges
+ * in package.json and the actual installed package versions in node_modules.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @param packageJson Parsed package.json object
+ * @param includeDev Whether to include devDependencies in the drift check
+ * @returns Array of VersionDrift results
+ */
+export declare function detectDrifts(projectRoot: string, packageJson: PackageJson, includeDev?: boolean): Promise<VersionDrift[]>;
+//# sourceMappingURL=drift.d.ts.map

package/dist/src/detectors/drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.d.ts","sourceRoot":"","sources":["../../../src/detectors/drift.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAqDxD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,WAAW,EACxB,UAAU,GAAE,OAAe,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC,CA4CzB"}

package/dist/src/detectors/drift.js

@@ -0,0 +1,95 @@
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import semver from 'semver';
+/**
+ * Resolves the installed version of a package by reading its package.json inside node_modules.
+ */
+async function getInstalledVersion(projectRoot, packageName) {
+    const packageJsonPath = join(projectRoot, 'node_modules', packageName, 'package.json');
+    try {
+        const content = await fs.readFile(packageJsonPath, 'utf8');
+        const pkg = JSON.parse(content);
+        return pkg.version || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Calculates the semver drift type between a declared range and the installed version.
+ */
+function calculateDriftType(declaredRange, installedVersion) {
+    if (!installedVersion) {
+        return 'missing';
+    }
+    // If the range is not valid semver (e.g. workspace:*, git URL, file path, latest)
+    if (!semver.validRange(declaredRange)) {
+        // Exact string match comparison fallback
+        return declaredRange === installedVersion ? 'none' : 'major';
+    }
+    const minVersion = semver.minVersion(declaredRange);
+    if (!minVersion) {
+        return 'none';
+    }
+    const diff = semver.diff(minVersion.version, installedVersion);
+    if (!diff) {
+        return 'none';
+    }
+    if (diff === 'major' || diff === 'premajor') {
+        return 'major';
+    }
+    if (diff === 'minor' || diff === 'preminor') {
+        return 'minor';
+    }
+    if (diff === 'patch' || diff === 'prepatch' || diff === 'prerelease') {
+        return 'patch';
+    }
+    return 'none';
+}
+/**
+ * Detects version drift issues: discrepancies between the declared semver ranges
+ * in package.json and the actual installed package versions in node_modules.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @param packageJson Parsed package.json object
+ * @param includeDev Whether to include devDependencies in the drift check
+ * @returns Array of VersionDrift results
+ */
+export async function detectDrifts(projectRoot, packageJson, includeDev = false) {
+    try {
+        const candidates = [];
+        const addCandidates = (deps, dependencyType) => {
+            if (deps) {
+                for (const [name, version] of Object.entries(deps)) {
+                    candidates.push({ name, declaredVersion: version, dependencyType });
+                }
+            }
+        };
+        addCandidates(packageJson.dependencies, 'dependencies');
+        if (includeDev) {
+            addCandidates(packageJson.devDependencies, 'devDependencies');
+        }
+        addCandidates(packageJson.peerDependencies, 'peerDependencies');
+        addCandidates(packageJson.optionalDependencies, 'optionalDependencies');
+        const drifts = [];
+        for (const candidate of candidates) {
+            const installedVersion = await getInstalledVersion(projectRoot, candidate.name);
+            const driftType = calculateDriftType(candidate.declaredVersion, installedVersion);
+            if (driftType !== 'none') {
+                drifts.push({
+                    name: candidate.name,
+                    dependencyType: candidate.dependencyType,
+                    declaredVersion: candidate.declaredVersion,
+                    installedVersion,
+                    driftType,
+                });
+            }
+        }
+        return drifts;
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Version drift detection failed: ${err.message}`);
+    }
+}
+//# sourceMappingURL=drift.js.map

package/dist/src/detectors/drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.js","sourceRoot":"","sources":["../../../src/detectors/drift.ts"],"names":[],"mappings":"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"}

package/dist/src/detectors/duplicates.d.ts

@@ -0,0 +1,13 @@
+import { DuplicateDependency } from '../types.js';
+/**
+ * Detects packages with duplicate versions installed under node_modules.
+ *
+ * Works cross-platform and supports npm, pnpm, and yarn by walking the active
+ * dependency graph in node_modules, resolving symlinks canonical-paths (to handle
+ * pnpm structures without infinite loops) and tracking visited packages.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @returns Array of DuplicateDependency details
+ */
+export declare function detectDuplicates(projectRoot: string): Promise<DuplicateDependency[]>;
+//# sourceMappingURL=duplicates.d.ts.map

package/dist/src/detectors/duplicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplicates.d.ts","sourceRoot":"","sources":["../../../src/detectors/duplicates.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAA+B,MAAM,aAAa,CAAC;AAE/E;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAiJ1F"}

package/dist/src/detectors/duplicates.js

@@ -0,0 +1,151 @@
+import { promises as fs } from 'fs';
+import { join } from 'path';
+/**
+ * Detects packages with duplicate versions installed under node_modules.
+ *
+ * Works cross-platform and supports npm, pnpm, and yarn by walking the active
+ * dependency graph in node_modules, resolving symlinks canonical-paths (to handle
+ * pnpm structures without infinite loops) and tracking visited packages.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @returns Array of DuplicateDependency details
+ */
+export async function detectDuplicates(projectRoot) {
+    const nodeModulesPath = join(projectRoot, 'node_modules');
+    const visitedPaths = new Set();
+    // Maps: packageName -> Map(versionString -> Array of relative path strings)
+    const packageVersionsMap = new Map();
+    /**
+     * Helper recursive function to walk package directories.
+     */
+    async function walk(dirPath, relativePathPrefix) {
+        try {
+            // Canonicalize the path to handle symlinks (crucial for pnpm / yarn berry)
+            const realPath = await fs.realpath(dirPath);
+            if (visitedPaths.has(realPath)) {
+                return;
+            }
+            visitedPaths.add(realPath);
+            let pkgName;
+            let pkgVersion;
+            // Try reading package.json of the current directory
+            try {
+                const pkgJsonContent = await fs.readFile(join(dirPath, 'package.json'), 'utf8');
+                const pkgJson = JSON.parse(pkgJsonContent);
+                pkgName = pkgJson.name;
+                pkgVersion = pkgJson.version;
+            }
+            catch {
+                // No valid package.json in this directory, skip reading it as a package
+            }
+            if (pkgName && pkgVersion) {
+                let versionMap = packageVersionsMap.get(pkgName);
+                if (!versionMap) {
+                    versionMap = new Map();
+                    packageVersionsMap.set(pkgName, versionMap);
+                }
+                let pathsList = versionMap.get(pkgVersion);
+                if (!pathsList) {
+                    pathsList = [];
+                    versionMap.set(pkgVersion, pathsList);
+                }
+                pathsList.push(relativePathPrefix);
+            }
+            // Check for nested node_modules folder (typical in npm / yarn classic)
+            const nestedNodeModules = join(dirPath, 'node_modules');
+            try {
+                const entries = await fs.readdir(nestedNodeModules, { withFileTypes: true });
+                for (const entry of entries) {
+                    // Skip internal/hidden folders
+                    if (entry.name.startsWith('.')) {
+                        continue;
+                    }
+                    if (entry.isDirectory() || entry.isSymbolicLink()) {
+                        const entryPath = join(nestedNodeModules, entry.name);
+                        const nextPrefix = relativePathPrefix
+                            ? `${relativePathPrefix}/node_modules/${entry.name}`
+                            : `node_modules/${entry.name}`;
+                        if (entry.name.startsWith('@')) {
+                            // Read scoped packages directory
+                            try {
+                                const scopeEntries = await fs.readdir(entryPath, { withFileTypes: true });
+                                for (const scopeEntry of scopeEntries) {
+                                    if (scopeEntry.isDirectory() || scopeEntry.isSymbolicLink()) {
+                                        const scopeEntryPath = join(entryPath, scopeEntry.name);
+                                        const scopeNextPrefix = `${nextPrefix}/${scopeEntry.name}`;
+                                        await walk(scopeEntryPath, scopeNextPrefix);
+                                    }
+                                }
+                            }
+                            catch {
+                                // Ignore failures to read scoped package directories
+                            }
+                        }
+                        else {
+                            await walk(entryPath, nextPrefix);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Nested node_modules directory does not exist or is unreadable
+            }
+        }
+        catch {
+            // Path resolution failed (e.g. broken symlink), skip directory safely
+        }
+    }
+    // Start walking from the root node_modules directory
+    try {
+        const rootEntries = await fs.readdir(nodeModulesPath, { withFileTypes: true });
+        for (const entry of rootEntries) {
+            if (entry.name.startsWith('.')) {
+                continue;
+            }
+            if (entry.isDirectory() || entry.isSymbolicLink()) {
+                const entryPath = join(nodeModulesPath, entry.name);
+                const relativePrefix = `node_modules/${entry.name}`;
+                if (entry.name.startsWith('@')) {
+                    try {
+                        const scopeEntries = await fs.readdir(entryPath, { withFileTypes: true });
+                        for (const scopeEntry of scopeEntries) {
+                            if (scopeEntry.isDirectory() || scopeEntry.isSymbolicLink()) {
+                                const scopeEntryPath = join(entryPath, scopeEntry.name);
+                                const scopeRelativePrefix = `${relativePrefix}/${scopeEntry.name}`;
+                                await walk(scopeEntryPath, scopeRelativePrefix);
+                            }
+                        }
+                    }
+                    catch {
+                        // Ignore scoped subdirectory read errors
+                    }
+                }
+                else {
+                    await walk(entryPath, relativePrefix);
+                }
+            }
+        }
+    }
+    catch {
+        // node_modules doesn't exist, is unreadable, or project isn't installed
+    }
+    // Format and collect final duplicates mapping
+    const duplicates = [];
+    for (const [name, versionMap] of packageVersionsMap.entries()) {
+        if (versionMap.size > 1) {
+            const versions = [];
+            for (const [version, paths] of versionMap.entries()) {
+                versions.push({
+                    version,
+                    paths,
+                });
+            }
+            duplicates.push({
+                name,
+                versions,
+            });
+        }
+    }
+    return duplicates;
+}
+//# sourceMappingURL=duplicates.js.map

package/dist/src/detectors/duplicates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplicates.js","sourceRoot":"","sources":["../../../src/detectors/duplicates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACxD,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IAEvC,4EAA4E;IAC5E,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEpE;;OAEG;IACH,KAAK,UAAU,IAAI,CAAC,OAAe,EAAE,kBAA0B;QAC7D,IAAI,CAAC;YACH,2EAA2E;YAC3E,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC/B,OAAO;YACT,CAAC;YACD,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAE3B,IAAI,OAA2B,CAAC;YAChC,IAAI,UAA8B,CAAC;YAEnC,oDAAoD;YACpD,IAAI,CAAC;gBACH,MAAM,cAAc,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;gBAChF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAwC,CAAC;gBAClF,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;gBACvB,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACP,wEAAwE;YAC1E,CAAC;YAED,IAAI,OAAO,IAAI,UAAU,EAAE,CAAC;gBAC1B,IAAI,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACjD,IAAI,CAAC,UAAU,EAAE,CAAC;oBAChB,UAAU,GAAG,IAAI,GAAG,EAAoB,CAAC;oBACzC,kBAAkB,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAC9C,CAAC;gBAED,IAAI,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;gBAC3C,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,SAAS,GAAG,EAAE,CAAC;oBACf,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;gBACxC,CAAC;gBAED,SAAS,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACrC,CAAC;YAED,uEAAuE;YACvE,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;YACxD,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC7E,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;oBAC5B,+BAA+B;oBAC/B,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;wBAC/B,SAAS;oBACX,CAAC;oBAED,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;wBAClD,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;wBACtD,MAAM,UAAU,GAAG,kBAAkB;4BACnC,CAAC,CAAC,GAAG,kBAAkB,iBAAiB,KAAK,CAAC,IAAI,EAAE;4BACpD,CAAC,CAAC,gBAAgB,KAAK,CAAC,IAAI,EAAE,CAAC;wBAEjC,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;4BAC/B,iCAAiC;4BACjC,IAAI,CAAC;gCACH,MAAM,YAAY,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;gCAC1E,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;oCACtC,IAAI,UAAU,CAAC,WAAW,EAAE,IAAI,UAAU,CAAC,cAAc,EAAE,EAAE,CAAC;wCAC5D,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;wCACxD,MAAM,eAAe,GAAG,GAAG,UAAU,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC;wCAC3D,MAAM,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;oCAC9C,CAAC;gCACH,CAAC;4BACH,CAAC;4BAAC,MAAM,CAAC;gCACP,qDAAqD;4BACvD,CAAC;wBACH,CAAC;6BAAM,CAAC;4BACN,MAAM,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;wBACpC,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,gEAAgE;YAClE,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;QACxE,CAAC;IACH,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/E,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/B,SAAS;YACX,CAAC;YAED,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;gBAClD,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBACpD,MAAM,cAAc,GAAG,gBAAgB,KAAK,CAAC,IAAI,EAAE,CAAC;gBAEpD,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC/B,IAAI,CAAC;wBACH,MAAM,YAAY,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;wBAC1E,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;4BACtC,IAAI,UAAU,CAAC,WAAW,EAAE,IAAI,UAAU,CAAC,cAAc,EAAE,EAAE,CAAC;gCAC5D,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;gCACxD,MAAM,mBAAmB,GAAG,GAAG,cAAc,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC;gCACnE,MAAM,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC;4BAClD,CAAC;wBACH,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC;wBACP,yCAAyC;oBAC3C,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;IAC1E,CAAC;IAED,8CAA8C;IAC9C,MAAM,UAAU,GAA0B,EAAE,CAAC;IAE7C,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,kBAAkB,CAAC,OAAO,EAAE,EAAE,CAAC;QAC9D,IAAI,UAAU,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,QAAQ,GAAkC,EAAE,CAAC;YACnD,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;gBACpD,QAAQ,CAAC,IAAI,CAAC;oBACZ,OAAO;oBACP,KAAK;iBACN,CAAC,CAAC;YACL,CAAC;YACD,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI;gBACJ,QAAQ;aACT,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/src/detectors/ghosts.d.ts

@@ -0,0 +1,13 @@
+import { GhostDependency, PackageJson } from '../types.js';
+/**
+ * Detects ghost dependencies: packages imported in the source code
+ * that are installed in node_modules but not listed in package.json.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @param sourceFiles List of absolute paths of source files to analyze
+ * @param packageJson Parsed package.json object
+ * @param includeDev Whether to include devDependencies as declared packages
+ * @returns Array of detected ghost dependencies
+ */
+export declare function detectGhosts(projectRoot: string, sourceFiles: string[], packageJson: PackageJson, includeDev?: boolean): Promise<GhostDependency[]>;
+//# sourceMappingURL=ghosts.d.ts.map

package/dist/src/detectors/ghosts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ghosts.d.ts","sourceRoot":"","sources":["../../../src/detectors/ghosts.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAiJ3D;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,WAAW,EACxB,UAAU,GAAE,OAAe,GAC1B,OAAO,CAAC,eAAe,EAAE,CAAC,CAoE5B"}