ghostdep 0.1.0

package/dist/src/reporter.js

@@ -0,0 +1,115 @@
+import chalk from 'chalk';
+/**
+ * Outputs a beautifully formatted CLI report summarizing the dependency audit scan results,
+ * color-coded by issue severity using chalk.
+ *
+ * @param report The final ScanReport resulting from the scan
+ */
+export function reportToConsole(report) {
+    const { project, durationMs, ghosts, zombies, duplicates, drifts, health } = report;
+    // Header Banner
+    console.log('\n' + chalk.bold.cyan('👻 ghostdep') + chalk.dim(` v0.1.0`));
+    console.log(chalk.gray('─'.repeat(60)));
+    console.log(`${chalk.bold('Target Project:')}  ${chalk.white(project.name)}`);
+    console.log(`${chalk.bold('Version:')}         ${chalk.white(project.version)}`);
+    console.log(`${chalk.bold('Scan Time:')}       ${chalk.white(durationMs)}ms`);
+    console.log(chalk.gray('─'.repeat(60)) + '\n');
+    // 1. Ghost Dependencies (Highest Priority - Missing Declarations)
+    if (ghosts.length > 0) {
+        console.log(chalk.bold.red(`👻 Ghost Dependencies (${ghosts.length})`));
+        console.log(chalk.dim('   Packages imported in code but not declared in package.json'));
+        console.log(chalk.gray('   ' + '─'.repeat(54)));
+        for (const ghost of ghosts) {
+            console.log(`   ${chalk.red('✗')} ${chalk.bold.white(ghost.name)}`);
+            const filesLimit = 5;
+            const formattedFiles = ghost.files
+                .slice(0, filesLimit)
+                .map((f) => chalk.gray(f))
+                .join(', ');
+            const overflow = ghost.files.length > filesLimit ? chalk.dim(` (+${ghost.files.length - filesLimit} more)`) : '';
+            console.log(`     ${chalk.dim('Files:')}    ${formattedFiles}${overflow}`);
+            console.log(`     ${chalk.dim('Imports:')}  ${chalk.gray(ghost.specifiers.join(', '))}`);
+        }
+        console.log();
+    }
+    // 2. Zombie Dependencies (Unused Declarations)
+    if (zombies.length > 0) {
+        console.log(chalk.bold.yellow(`🧟 Zombie Dependencies (${zombies.length})`));
+        console.log(chalk.dim('   Declared in package.json but never imported or required in code'));
+        console.log(chalk.gray('   ' + '─'.repeat(54)));
+        for (const zombie of zombies) {
+            console.log(`   ${chalk.yellow('⚠')} ${chalk.bold.white(zombie.name)} ${chalk.dim(`(${zombie.declaredVersion})`)} [${chalk.cyan(zombie.type)}]`);
+        }
+        console.log();
+    }
+    // 3. Duplicate Dependency Versions
+    if (duplicates.length > 0) {
+        console.log(chalk.bold.magenta(`📦 Duplicate Package Versions (${duplicates.length})`));
+        console.log(chalk.dim('   Multiple conflicting versions of the same package resolved in node_modules'));
+        console.log(chalk.gray('   ' + '─'.repeat(54)));
+        for (const dup of duplicates) {
+            console.log(`   ${chalk.magenta('⇄')} ${chalk.bold.white(dup.name)}`);
+            for (const instance of dup.versions) {
+                console.log(`     ${chalk.bold.white(instance.version)} resolved at:`);
+                for (const path of instance.paths) {
+                    console.log(`       ${chalk.gray(path)}`);
+                }
+            }
+        }
+        console.log();
+    }
+    // 4. Version Drifts
+    if (drifts.length > 0) {
+        console.log(chalk.bold.blue(`🔄 Version Drift Mismatches (${drifts.length})`));
+        console.log(chalk.dim('   Difference between declared semver ranges and actual installed versions'));
+        console.log(chalk.gray('   ' + '─'.repeat(54)));
+        for (const drift of drifts) {
+            const typeColor = drift.driftType === 'major' || drift.driftType === 'missing'
+                ? chalk.red
+                : drift.driftType === 'minor'
+                    ? chalk.yellow
+                    : chalk.green;
+            const installedStr = drift.installedVersion
+                ? chalk.white(drift.installedVersion)
+                : chalk.red.bold('NOT INSTALLED');
+            console.log(`   ${chalk.blue('ℹ')} ${chalk.bold.white(drift.name)} [${chalk.cyan(drift.dependencyType)}]`);
+            console.log(`     Declared Range:    ${chalk.gray(drift.declaredVersion)}`);
+            console.log(`     Installed Version: ${installedStr}`);
+            console.log(`     Drift Category:    ${typeColor(drift.driftType.toUpperCase())}`);
+        }
+        console.log();
+    }
+    // 5. Overall Health Report Card
+    console.log(chalk.gray('─'.repeat(60)));
+    const gradeColor = health.grade === 'A'
+        ? chalk.bold.green
+        : health.grade === 'B'
+            ? chalk.bold.green
+            : health.grade === 'C'
+                ? chalk.bold.yellow
+                : health.grade === 'D'
+                    ? chalk.bold.yellow
+                    : chalk.bold.red;
+    const scoreColor = health.score >= 90
+        ? chalk.bold.green
+        : health.score >= 75
+            ? chalk.bold.cyan
+            : health.score >= 60
+                ? chalk.bold.yellow
+                : chalk.bold.red;
+    console.log(chalk.bold('📊 HEALTH REPORT CARD'));
+    console.log(chalk.gray('─'.repeat(60)));
+    console.log(`Overall Health Score:  ${scoreColor(health.score)} / 100`);
+    console.log(`Letter Grade Summary:  ${gradeColor(health.grade)}`);
+    if (health.deductions.length > 0) {
+        console.log(`\n${chalk.bold('Deductions Details:')}`);
+        for (const deduction of health.deductions) {
+            console.log(`  ${chalk.red('•')} ${deduction.reason}: ${chalk.red(`-${deduction.penalty} pts`)}`);
+        }
+    }
+    else {
+        console.log(`\n${chalk.bold.green('✨ Clean Audit! All dependencies are fully optimized and healthy.')}`);
+    }
+    console.log(chalk.gray('─'.repeat(60)) + '\n');
+}
+//# sourceMappingURL=reporter.js.map

package/dist/src/reporter.js.map

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

package/dist/src/scanner.d.ts

@@ -0,0 +1,12 @@
+import { ScanReport, ScanOptions } from './types.js';
+/**
+ * Executes a full dependency audit scan of the target project directory.
+ *
+ * Runs all detectors (ghosts, zombies, duplicates, drifts) concurrently,
+ * computes the overall project health score, and generates a structured report.
+ *
+ * @param partialOptions Configuration overrides for the scanning process
+ * @returns Fully populated ScanReport
+ */
+export declare function runScan(partialOptions?: Partial<ScanOptions>): Promise<ScanReport>;
+//# sourceMappingURL=scanner.d.ts.map

package/dist/src/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/scanner.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,cAAc,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmD5F"}

package/dist/src/scanner.js

@@ -0,0 +1,62 @@
+import { readPackageJson, scanFiles } from './utils/fs.js';
+import { detectGhosts } from './detectors/ghosts.js';
+import { detectZombies } from './detectors/zombies.js';
+import { detectDuplicates } from './detectors/duplicates.js';
+import { detectDrifts } from './detectors/drift.js';
+import { calculateHealthScore } from './health.js';
+/**
+ * Executes a full dependency audit scan of the target project directory.
+ *
+ * Runs all detectors (ghosts, zombies, duplicates, drifts) concurrently,
+ * computes the overall project health score, and generates a structured report.
+ *
+ * @param partialOptions Configuration overrides for the scanning process
+ * @returns Fully populated ScanReport
+ */
+export async function runScan(partialOptions = {}) {
+    const startTime = Date.now();
+    // 1. Resolve configuration options with defaults
+    const options = {
+        cwd: partialOptions.cwd || process.cwd(),
+        include: partialOptions.include || ['**/*.{js,jsx,ts,tsx,mjs,cjs}'],
+        exclude: partialOptions.exclude || [],
+        includeDev: partialOptions.includeDev ?? false,
+        ...(partialOptions.penalties ? { penalties: partialOptions.penalties } : {}),
+    };
+    try {
+        // 2. Read package.json metadata
+        const packageJson = await readPackageJson(options.cwd);
+        // 3. Scan the codebase directory for source files
+        const sourceFiles = await scanFiles(options.cwd, options.include, options.exclude);
+        // 4. Run diagnostics concurrently for optimal performance
+        const [ghosts, zombies, duplicates, drifts] = await Promise.all([
+            detectGhosts(options.cwd, sourceFiles, packageJson, options.includeDev),
+            detectZombies(sourceFiles, packageJson, options.includeDev),
+            detectDuplicates(options.cwd),
+            detectDrifts(options.cwd, packageJson, options.includeDev),
+        ]);
+        // 5. Calculate dependency health score
+        const health = calculateHealthScore(ghosts, zombies, duplicates, drifts, options.penalties);
+        const endTime = Date.now();
+        const durationMs = endTime - startTime;
+        // 6. Build and return the final report
+        return {
+            timestamp: new Date().toISOString(),
+            durationMs,
+            project: {
+                name: packageJson.name || 'unnamed-project',
+                version: packageJson.version || '0.0.0',
+            },
+            ghosts,
+            zombies,
+            duplicates,
+            drifts,
+            health,
+        };
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Scan execution failed: ${err.message}`);
+    }
+}
+//# sourceMappingURL=scanner.js.map

package/dist/src/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,iBAAuC,EAAE;IACrE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,iDAAiD;IACjD,MAAM,OAAO,GAAgB;QAC3B,GAAG,EAAE,cAAc,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;QACxC,OAAO,EAAE,cAAc,CAAC,OAAO,IAAI,CAAC,8BAA8B,CAAC;QACnE,OAAO,EAAE,cAAc,CAAC,OAAO,IAAI,EAAE;QACrC,UAAU,EAAE,cAAc,CAAC,UAAU,IAAI,KAAK;QAC9C,GAAG,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,cAAc,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC;IAEF,IAAI,CAAC;QACH,gCAAgC;QAChC,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAEvD,kDAAkD;QAClD,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAEnF,0DAA0D;QAC1D,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC9D,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC;YACvE,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC;YAC3D,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC;YAC7B,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC;SAC3D,CAAC,CAAC;QAEH,uCAAuC;QACvC,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAE5F,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;QAEvC,uCAAuC;QACvC,OAAO;YACL,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,UAAU;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,WAAW,CAAC,IAAI,IAAI,iBAAiB;gBAC3C,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,OAAO;aACxC;YACD,MAAM;YACN,OAAO;YACP,UAAU;YACV,MAAM;YACN,MAAM;SACP,CAAC;IACJ,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAc,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,115 @@
+export interface GhostDependency {
+    /** Name of the imported package that is not declared in package.json */
+    name: string;
+    /** List of files (relative paths) where this package was imported */
+    files: string[];
+    /** The import specifiers used in code (e.g. "lodash/map") */
+    specifiers: string[];
+}
+export interface ZombieDependency {
+    /** Name of the package declared in package.json but not used in code */
+    name: string;
+    /** Section under which it is declared in package.json */
+    type: 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+    /** The version range declared in package.json */
+    declaredVersion: string;
+}
+export interface DuplicateDependencyInstance {
+    /** The resolved actual version */
+    version: string;
+    /** Paths to the directory in node_modules resolving to this version */
+    paths: string[];
+}
+export interface DuplicateDependency {
+    /** Name of the package with duplicate versions installed */
+    name: string;
+    /** Array of installed versions and their locations */
+    versions: DuplicateDependencyInstance[];
+}
+export interface VersionDrift {
+    /** Name of the package */
+    name: string;
+    /** Section under which it is declared in package.json */
+    dependencyType: 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+    /** The version range declared in package.json */
+    declaredVersion: string;
+    /** The actual version resolved/installed in node_modules (null if not installed) */
+    installedVersion: string | null;
+    /** Categorization of the drift gap */
+    driftType: 'major' | 'minor' | 'patch' | 'missing' | 'none';
+}
+export interface HealthDeduction {
+    /** Reason for the deduction (e.g. "2 ghost dependencies detected") */
+    reason: string;
+    /** Points deducted from the 100 base score */
+    penalty: number;
+}
+export interface HealthScore {
+    /** Overall calculated health score from 0 to 100 */
+    score: number;
+    /** Letter grade based on the score */
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    /** Quantities of various issues found */
+    metrics: {
+        ghosts: number;
+        zombies: number;
+        duplicates: number;
+        drifts: number;
+    };
+    /** Detail of deductions applied to reach the final score */
+    deductions: HealthDeduction[];
+}
+export interface ProjectMetadata {
+    /** Name of the analyzed project from package.json */
+    name: string;
+    /** Version of the analyzed project from package.json */
+    version: string;
+}
+export interface PackageJson {
+    name?: string;
+    version?: string;
+    packageManager?: string;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+}
+export interface ScanReport {
+    /** Timestamp when the scan was executed */
+    timestamp: string;
+    /** Time taken to run the analysis in milliseconds */
+    durationMs: number;
+    /** Analyzed project's metadata */
+    project: ProjectMetadata;
+    /** Detected ghost dependencies */
+    ghosts: GhostDependency[];
+    /** Detected zombie dependencies */
+    zombies: ZombieDependency[];
+    /** Detected duplicate package versions */
+    duplicates: DuplicateDependency[];
+    /** Detected version drift issues */
+    drifts: VersionDrift[];
+    /** Overall calculated health metrics */
+    health: HealthScore;
+}
+export interface ScanOptions {
+    /** Working directory to scan (defaults to process.cwd()) */
+    cwd: string;
+    /** Glob patterns to search for source code files */
+    include: string[];
+    /** Glob patterns to exclude from source code scan (e.g. node_modules, dist, test files) */
+    exclude: string[];
+    /** Whether to scan and include devDependencies in audits */
+    includeDev: boolean;
+    /** Custom penalties for issues when calculating the health score */
+    penalties?: {
+        ghost?: number;
+        zombie?: number;
+        duplicate?: number;
+        driftMajor?: number;
+        driftMinor?: number;
+        driftPatch?: number;
+        missing?: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

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

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/utils/fs.d.ts

@@ -0,0 +1,29 @@
+import { PackageJson } from '../types.js';
+/**
+ * Generic utility to read and parse a JSON file asynchronously.
+ *
+ * @param filePath Absolute path to the JSON file
+ * @returns Parsed JSON object of type T
+ * @throws Error if the file cannot be read or parsed
+ */
+export declare function readJson<T = unknown>(filePath: string): Promise<T>;
+/**
+ * Reads and parses package.json from the specified directory path.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @returns Parsed PackageJson object
+ * @throws Error if the file cannot be read or parsed
+ */
+export declare function readPackageJson(projectRoot: string): Promise<PackageJson>;
+/**
+ * Recursively scans folders for source files matching specified patterns,
+ * ignoring .git, node_modules, and common build/output directories.
+ *
+ * @param directory Absolute path to the directory to scan
+ * @param patterns Array of glob patterns to match (defaults to common JS/TS extensions)
+ * @param extraIgnores Optional array of extra glob patterns to ignore
+ * @returns List of absolute file paths matching the scan
+ * @throws Error if directory scanning fails
+ */
+export declare function scanFiles(directory: string, patterns?: string[], extraIgnores?: string[]): Promise<string[]>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/src/utils/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/utils/fs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAWxE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAG/E;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAM,EAAqC,EACrD,YAAY,GAAE,MAAM,EAAO,GAC1B,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BnB"}

package/dist/src/utils/fs.js

@@ -0,0 +1,72 @@
+import { join } from 'path';
+import { promises as fs } from 'fs';
+import fg from 'fast-glob';
+/**
+ * Generic utility to read and parse a JSON file asynchronously.
+ *
+ * @param filePath Absolute path to the JSON file
+ * @returns Parsed JSON object of type T
+ * @throws Error if the file cannot be read or parsed
+ */
+export async function readJson(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            throw new Error(`JSON file was not found at "${filePath}".`);
+        }
+        throw new Error(`Failed to read or parse JSON file at "${filePath}": ${err.message}`);
+    }
+}
+/**
+ * Reads and parses package.json from the specified directory path.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @returns Parsed PackageJson object
+ * @throws Error if the file cannot be read or parsed
+ */
+export async function readPackageJson(projectRoot) {
+    const filePath = join(projectRoot, 'package.json');
+    return readJson(filePath);
+}
+/**
+ * Recursively scans folders for source files matching specified patterns,
+ * ignoring .git, node_modules, and common build/output directories.
+ *
+ * @param directory Absolute path to the directory to scan
+ * @param patterns Array of glob patterns to match (defaults to common JS/TS extensions)
+ * @param extraIgnores Optional array of extra glob patterns to ignore
+ * @returns List of absolute file paths matching the scan
+ * @throws Error if directory scanning fails
+ */
+export async function scanFiles(directory, patterns = ['**/*.{js,jsx,ts,tsx,mjs,cjs}'], extraIgnores = []) {
+    try {
+        const defaultIgnores = [
+            '**/node_modules/**',
+            '**/.git/**',
+            '**/dist/**',
+            '**/build/**',
+            '**/coverage/**',
+            '**/.nyc_output/**',
+        ];
+        const ignore = [...defaultIgnores, ...extraIgnores];
+        // fast-glob requires forward slashes for cross-platform glob matching
+        const cleanDir = directory.replace(/\\/g, '/');
+        const files = await fg(patterns, {
+            cwd: cleanDir,
+            ignore,
+            absolute: true,
+            onlyFiles: true,
+            dot: false, // Don't match dotfiles by default (e.g. .eslintrc) unless specified
+        });
+        return files;
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Failed to scan files in directory "${directory}": ${err.message}`);
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/src/utils/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../../src/utils/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,MAAM,WAAW,CAAC;AAG3B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAc,QAAgB;IAC1D,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAM,CAAC;IAClC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAA8B,CAAC;QAC3C,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,IAAI,CAAC,CAAC;QAC/D,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,yCAAyC,QAAQ,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,WAAmB;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IACnD,OAAO,QAAQ,CAAc,QAAQ,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,SAAiB,EACjB,WAAqB,CAAC,8BAA8B,CAAC,EACrD,eAAyB,EAAE;IAE3B,IAAI,CAAC;QACH,MAAM,cAAc,GAAG;YACrB,oBAAoB;YACpB,YAAY;YACZ,YAAY;YACZ,aAAa;YACb,gBAAgB;YAChB,mBAAmB;SACpB,CAAC;QAEF,MAAM,MAAM,GAAG,CAAC,GAAG,cAAc,EAAE,GAAG,YAAY,CAAC,CAAC;QAEpD,sEAAsE;QACtE,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAE/C,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC/B,GAAG,EAAE,QAAQ;YACb,MAAM;YACN,QAAQ,EAAE,IAAI;YACd,SAAS,EAAE,IAAI;YACf,GAAG,EAAE,KAAK,EAAE,oEAAoE;SACjF,CAAC,CAAC;QAEH,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAc,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,sCAAsC,SAAS,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACtF,CAAC;AACH,CAAC"}

package/dist/src/utils/packageManager.d.ts

@@ -0,0 +1,20 @@
+import { PackageJson } from '../types.js';
+export type PackageManagerType = 'npm' | 'yarn' | 'pnpm';
+/**
+ * Reads and parses package.json from the specified directory path.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @returns Parsed PackageJson object
+ * @throws Error if the file cannot be read or parsed
+ */
+export declare function readPackageJson(projectRoot: string): Promise<PackageJson>;
+/**
+ * Detects the active package manager of the project by verifying lockfiles
+ * or inspecting the "packageManager" property in package.json.
+ * Defaults to "npm" if no package manager can be identified.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @returns The identified package manager ('npm' | 'yarn' | 'pnpm')
+ */
+export declare function detectPackageManager(projectRoot: string): Promise<PackageManagerType>;
+//# sourceMappingURL=packageManager.d.ts.map

package/dist/src/utils/packageManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageManager.d.ts","sourceRoot":"","sources":["../../../src/utils/packageManager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAY/E;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuC3F"}

package/dist/src/utils/packageManager.js

@@ -0,0 +1,74 @@
+import { join } from 'path';
+import { promises as fs } from 'fs';
+/**
+ * Reads and parses package.json from the specified directory path.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @returns Parsed PackageJson object
+ * @throws Error if the file cannot be read or parsed
+ */
+export async function readPackageJson(projectRoot) {
+    const filePath = join(projectRoot, 'package.json');
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            throw new Error(`package.json was not found at "${filePath}".`);
+        }
+        throw new Error(`Failed to parse package.json at "${filePath}": ${err.message}`);
+    }
+}
+/**
+ * Detects the active package manager of the project by verifying lockfiles
+ * or inspecting the "packageManager" property in package.json.
+ * Defaults to "npm" if no package manager can be identified.
+ *
+ * @param projectRoot Absolute path to the project root directory
+ * @returns The identified package manager ('npm' | 'yarn' | 'pnpm')
+ */
+export async function detectPackageManager(projectRoot) {
+    try {
+        const checkFileExists = async (filename) => {
+            try {
+                await fs.access(join(projectRoot, filename));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const [hasPnpm, hasYarn, hasNpm] = await Promise.all([
+            checkFileExists('pnpm-lock.yaml'),
+            checkFileExists('yarn.lock'),
+            checkFileExists('package-lock.json'),
+        ]);
+        if (hasPnpm)
+            return 'pnpm';
+        if (hasYarn)
+            return 'yarn';
+        if (hasNpm)
+            return 'npm';
+        // Fallback: inspect packageManager field inside package.json
+        try {
+            const pkg = await readPackageJson(projectRoot);
+            if (pkg.packageManager) {
+                const [name] = pkg.packageManager.split('@');
+                if (name === 'npm' || name === 'yarn' || name === 'pnpm') {
+                    return name;
+                }
+            }
+        }
+        catch {
+            // Fallback silently if package.json does not exist or fails parsing
+        }
+        return 'npm';
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Package manager detection failed: ${err.message}`);
+    }
+}
+//# sourceMappingURL=packageManager.js.map

package/dist/src/utils/packageManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageManager.js","sourceRoot":"","sources":["../../../src/utils/packageManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AAKpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,WAAmB;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IACnD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAA8B,CAAC;QAC3C,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,kCAAkC,QAAQ,IAAI,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACnF,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,WAAmB;IAC5D,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,KAAK,EAAE,QAAgB,EAAoB,EAAE;YACnE,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;gBAC7C,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACnD,eAAe,CAAC,gBAAgB,CAAC;YACjC,eAAe,CAAC,WAAW,CAAC;YAC5B,eAAe,CAAC,mBAAmB,CAAC;SACrC,CAAC,CAAC;QAEH,IAAI,OAAO;YAAE,OAAO,MAAM,CAAC;QAC3B,IAAI,OAAO;YAAE,OAAO,MAAM,CAAC;QAC3B,IAAI,MAAM;YAAE,OAAO,KAAK,CAAC;QAEzB,6DAA6D;QAC7D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,WAAW,CAAC,CAAC;YAC/C,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;gBACvB,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAC7C,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;oBACzD,OAAO,IAA0B,CAAC;gBACpC,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;QACtE,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAc,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "ghostdep",
+  "version": "0.1.0",
+  "description": "A production-ready CLI and library to detect ghost, zombie, duplicate, and drifted dependencies in Node.js and TypeScript projects.",
+  "keywords": [
+    "ghost-dependencies",
+    "zombie-dependencies",
+    "dependency-drift",
+    "duplicate-dependencies",
+    "dependency-health",
+    "npm",
+    "typescript",
+    "cli",
+    "esm"
+  ],
+  "homepage": "https://github.com/yourusername/ghostdep#readme",
+  "bugs": {
+    "url": "https://github.com/yourusername/ghostdep/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/ghostdep.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "ghostdep": "./dist/bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "build:watch": "tsc --project tsconfig.build.json --watch",
+    "clean": "rimraf dist",
+    "prebuild": "npm run clean",
+    "dev": "tsx bin/cli.ts",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"bin/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"bin/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"bin/**/*.ts\" \"*.json\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"bin/**/*.ts\" \"*.json\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run lint && npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2",
+    "semver": "^7.6.2",
+    "typescript": "^5.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.2",
+    "@types/semver": "^7.5.8",
+    "@typescript-eslint/eslint-plugin": "^7.13.0",
+    "@typescript-eslint/parser": "^7.13.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "prettier": "^3.3.1",
+    "rimraf": "^5.0.7",
+    "tsx": "^4.15.1",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}