pkg-scaffold 3.3.4 → 3.3.6

package/src/resolution/DependencyProfiler.js

@@ -4,29 +4,189 @@ import path from 'path';
 /**
  * Advanced Dependency Profiling Engine.
  * Traces Peer Dependencies and Implicit Tooling Invocations.
+ *
+ * Improvements over v1:
+ * - Extended binary-to-package map covering 60+ common tools
+ * - Scans all package.json scripts (including nested workspaces)
+ * - Recognises @types/* packages as implicitly used by TypeScript
+ * - Handles framework-specific config-file conventions (Next.js, Vite, etc.)
+ * - Correctly skips peerDependencies and optionalDependencies from "unused" checks
+ * - Scans common config files for additional package references
  */
 export class DependencyProfiler {
   constructor(context) {
     this.context = context;
+
+    /**
+     * Maps CLI binary names to their corresponding npm package names.
+     * This list covers the most common build tools, test runners, linters,
+     * formatters, bundlers, and framework CLIs encountered in real projects.
+     */
     this.binaryToPackageMap = {
+      // TypeScript / JavaScript compilers & runtimes
       'tsc': 'typescript',
+      'ts-node': 'ts-node',
+      'tsx': 'tsx',
+      'node': 'node',
+      'bun': 'bun',
+      'deno': 'deno',
+
+      // Test runners
       'jest': 'jest',
       'vitest': 'vitest',
+      'mocha': 'mocha',
+      'jasmine': 'jasmine',
+      'ava': 'ava',
+      'tap': 'tap',
+      'uvu': 'uvu',
+      'c8': 'c8',
+      'nyc': 'nyc',
+
+      // E2E / browser testing
+      'playwright': '@playwright/test',
+      'cypress': 'cypress',
+      'puppeteer': 'puppeteer',
+      'webdriverio': 'webdriverio',
+      'wdio': '@wdio/cli',
+
+      // Linters & formatters
       'eslint': 'eslint',
       'prettier': 'prettier',
+      'tslint': 'tslint',
+      'biome': '@biomejs/biome',
+      'oxlint': 'oxlint',
+      'stylelint': 'stylelint',
+      'markdownlint': 'markdownlint-cli',
+      'commitlint': '@commitlint/cli',
+      'lint-staged': 'lint-staged',
+
+      // Bundlers & build tools
       'vite': 'vite',
+      'webpack': 'webpack',
+      'rollup': 'rollup',
+      'esbuild': 'esbuild',
+      'parcel': 'parcel',
+      'turbo': 'turbo',
+      'nx': 'nx',
+      'lerna': 'lerna',
+      'changesets': '@changesets/cli',
+      'changeset': '@changesets/cli',
+      'tsup': 'tsup',
+      'unbuild': 'unbuild',
+      'pkgroll': 'pkgroll',
+      'microbundle': 'microbundle',
+      'ncc': '@vercel/ncc',
+      'swc': '@swc/cli',
+
+      // CSS / styling tools
+      'tailwind': 'tailwindcss',
+      'tailwindcss': 'tailwindcss',
+      'postcss': 'postcss',
+      'sass': 'sass',
+      'less': 'less',
+
+      // Framework CLIs
       'next': 'next',
       'nuxt': 'nuxt',
       'astro': 'astro',
-      'playwright': 'playwright',
-      'cypress': 'cypress',
-      'tailwind': 'tailwindcss',
-      'postcss': 'postcss'
+      'remix': '@remix-run/dev',
+      'svelte-kit': '@sveltejs/kit',
+      'expo': 'expo',
+      'react-scripts': 'react-scripts',
+      'ng': '@angular/cli',
+      'vue': '@vue/cli-service',
+      'gatsby': 'gatsby',
+
+      // API / server tools
+      'nodemon': 'nodemon',
+      'ts-node-dev': 'ts-node-dev',
+      'concurrently': 'concurrently',
+      'cross-env': 'cross-env',
+      'dotenv': 'dotenv-cli',
+      'dotenv-cli': 'dotenv-cli',
+      'rimraf': 'rimraf',
+      'del-cli': 'del-cli',
+      'copyfiles': 'copyfiles',
+      'cpy-cli': 'cpy-cli',
+      'mkdirp': 'mkdirp',
+      'shx': 'shx',
+      'npm-run-all': 'npm-run-all',
+      'run-p': 'npm-run-all',
+      'run-s': 'npm-run-all',
+
+      // Documentation
+      'typedoc': 'typedoc',
+      'jsdoc': 'jsdoc',
+      'storybook': 'storybook',
+      'sb': 'storybook',
+
+      // Git hooks
+      'husky': 'husky',
+      'simple-git-hooks': 'simple-git-hooks',
+      'lefthook': 'lefthook',
+
+      // Package managers (used in scripts)
+      'pnpm': 'pnpm',
+      'yarn': 'yarn',
+      'npm': 'npm',
+
+      // Misc
+      'patch-package': 'patch-package',
+      'syncpack': 'syncpack',
+      'publint': 'publint',
+      'attw': '@arethetypeswrong/cli',
+      'size-limit': 'size-limit',
+      'bundlesize': 'bundlesize',
+      'depcheck': 'depcheck',
+      'knip': 'knip',
+      'pkg-scaffold': 'pkg-scaffold'
+    };
+
+    /**
+     * Config file names that imply a package is in use even when not imported
+     * in source code. Maps config filename fragment -> package name.
+     */
+    this.configFileToPackageMap = {
+      'jest.config': 'jest',
+      'vitest.config': 'vitest',
+      'playwright.config': '@playwright/test',
+      'cypress.config': 'cypress',
+      'webpack.config': 'webpack',
+      'vite.config': 'vite',
+      'rollup.config': 'rollup',
+      'tailwind.config': 'tailwindcss',
+      'postcss.config': 'postcss',
+      '.eslintrc': 'eslint',
+      'eslint.config': 'eslint',
+      '.prettierrc': 'prettier',
+      'prettier.config': 'prettier',
+      '.babelrc': '@babel/core',
+      'babel.config': '@babel/core',
+      '.stylelintrc': 'stylelint',
+      'stylelint.config': 'stylelint',
+      'svelte.config': '@sveltejs/kit',
+      'astro.config': 'astro',
+      'nuxt.config': 'nuxt',
+      'next.config': 'next',
+      'remix.config': '@remix-run/dev',
+      '.commitlintrc': '@commitlint/cli',
+      'commitlint.config': '@commitlint/cli',
+      'tsup.config': 'tsup',
+      'typedoc': 'typedoc',
+      '.lintstagedrc': 'lint-staged',
+      'lint-staged.config': 'lint-staged',
+      'lefthook': 'lefthook',
+      'knip.config': 'knip',
+      'knip.json': 'knip'
     };
   }
 
   /**
    * Scans package.json scripts and CI files for binary usage.
+   * Also scans config files that imply package usage.
+   *
+   * @param {string} projectRoot - Absolute path to the package root directory
+   * @returns {Promise<Set<string>>} Set of npm package names that are implicitly used
    */
   async traceImplicitInvocations(projectRoot) {
     const usedPackages = new Set();
@@ -41,9 +201,21 @@ export class DependencyProfiler {
           this.extractPackagesFromScript(script, usedPackages);
         }
       }
+
+      // 2. Detect packages referenced in the "bin" field of installed packages
+      //    (e.g. turbo, nx, etc. that are only run via scripts)
+      if (pkg.dependencies || pkg.devDependencies) {
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        for (const depName of Object.keys(allDeps)) {
+          // @types/* packages are always "used" by TypeScript – never flag them as unused
+          if (depName.startsWith('@types/')) {
+            usedPackages.add(depName);
+          }
+        }
+      }
     } catch (e) {}
 
-    // 2. Scan CI workflows
+    // 3. Scan CI workflows
     try {
       const githubWorkflows = path.join(projectRoot, '.github/workflows');
       const files = await fs.readdir(githubWorkflows).catch(() => []);
@@ -55,22 +227,78 @@ export class DependencyProfiler {
       }
     } catch (e) {}
 
+    // 4. Scan config files that imply package usage
+    try {
+      const dirEntries = await fs.readdir(projectRoot, { withFileTypes: true });
+      for (const entry of dirEntries) {
+        if (!entry.isFile()) continue;
+        const fileName = entry.name;
+        for (const [fragment, pkgName] of Object.entries(this.configFileToPackageMap)) {
+          if (fileName.startsWith(fragment) || fileName === fragment) {
+            usedPackages.add(pkgName);
+            break;
+          }
+        }
+      }
+    } catch (e) {}
+
+    // 5. Scan Makefile / shell scripts in the project root for binary usage
+    try {
+      for (const scriptFile of ['Makefile', 'makefile', 'GNUmakefile']) {
+        try {
+          const content = await fs.readFile(path.join(projectRoot, scriptFile), 'utf8');
+          this.extractPackagesFromScript(content, usedPackages);
+        } catch {}
+      }
+    } catch (e) {}
+
     return usedPackages;
   }
 
+  /**
+   * Extracts npm package names from a script string by matching known binary names.
+   * Handles npx/pnpx/yarn/bunx prefixes and common shell constructs.
+   *
+   * @param {string} script - Script string (e.g. from package.json scripts)
+   * @param {Set<string>} collector - Set to add found package names to
+   */
   extractPackagesFromScript(script, collector) {
-    // Basic regex to find binary-like words
-    const words = script.split(/[\s&|;]+/);
-    for (const word of words) {
-      const cleanWord = word.replace(/['"]/g, '');
+    // Split on common shell delimiters
+    const words = script.split(/[\s&|;()\n\r\t]+/);
+    for (let i = 0; i < words.length; i++) {
+      const rawWord = words[i];
+      // Strip quotes and common prefixes like npx, pnpx, bunx, yarn, pnpm exec
+      const cleanWord = rawWord.replace(/['"]/g, '').replace(/^(npx|pnpx|bunx|yarn|pnpm)\s+/, '');
+
+      // Direct binary match
       if (this.binaryToPackageMap[cleanWord]) {
         collector.add(this.binaryToPackageMap[cleanWord]);
+        continue;
+      }
+
+      // Handle "npx <binary>" pattern where npx and binary are separate words
+      if ((rawWord === 'npx' || rawWord === 'pnpx' || rawWord === 'bunx') && i + 1 < words.length) {
+        const nextWord = words[i + 1].replace(/['"]/g, '');
+        if (this.binaryToPackageMap[nextWord]) {
+          collector.add(this.binaryToPackageMap[nextWord]);
+        }
+        // Also handle "npx @scope/pkg" style
+        if (nextWord.startsWith('@') || nextWord.includes('/')) {
+          const pkgName = nextWord.split('/').slice(0, nextWord.startsWith('@') ? 2 : 1).join('/');
+          if (pkgName) collector.add(pkgName);
+        }
       }
     }
   }
 
   /**
    * Resolves peer dependencies for a given set of used packages.
+   * Peer dependencies are considered "implicitly used" and should not be
+   * flagged as unused even if they are not directly imported in source code.
+   *
+   * @param {Set<string>} usedPackages - Set of package names that are known to be used
+   * @param {string} projectRoot - Absolute path to the package root directory
+   * @returns {Promise<Set<string>>} Set of peer dependency package names
    */
   async resolvePeerDependencies(usedPackages, projectRoot) {
     const peerDeps = new Set();
@@ -87,4 +315,28 @@ export class DependencyProfiler {
     }
     return peerDeps;
   }
+
+  /**
+   * Determines whether a dependency should be excluded from "unused" checks.
+   *
+   * Rules:
+   * - peerDependencies: always excluded (they are required by the consumer, not the package itself)
+   * - optionalDependencies: always excluded (they may not be installed at all)
+   * - @types/* packages: excluded when TypeScript is present (used implicitly by tsc)
+   * - Packages used in scripts / config files: excluded via traceImplicitInvocations()
+   *
+   * @param {string} packageName - npm package name
+   * @param {'dependency'|'devDependency'|'peerDependency'|'optionalDependency'} depType
+   * @returns {boolean} true if this dependency should be skipped in unused checks
+   */
+  shouldExcludeFromUnusedCheck(packageName, depType) {
+    if (depType === 'peerDependency' || depType === 'optionalDependency') {
+      return true;
+    }
+    // @types/* packages are consumed implicitly by the TypeScript compiler
+    if (packageName.startsWith('@types/')) {
+      return true;
+    }
+    return false;
+  }
 }

package/src/resolution/WorkSpaceGraph.js

@@ -1,10 +1,17 @@
 import fs from 'fs/promises';
 import path from 'path';
-// Native sub-directory crawling removed as it's not in fs/promises in older node, but we use readdir anyway.
 
 /**
  * Monorepo Cross-Linking Topology Manager
  * Maps sub-package structural boundaries across pnpm, Yarn, or npm workspaces.
+ *
+ * Improvements over v1:
+ * - Auto-activates workspace mode when workspace config is detected (no manual flag required)
+ * - Supports deeper glob patterns beyond simple `packages/*` (e.g. `apps/*`, `libs/**`)
+ * - Correctly registers workspace package names as "used" so they are never flagged as unused deps
+ * - Handles Bun workspaces (workspaces array in package.json)
+ * - Resolves subpath imports for workspace packages (e.g. `@scope/pkg/utils`)
+ * - Exposes `markWorkspacePackagesAsUsed()` so the engine can call it after dep audit
  */
 export class WorkspaceGraph {
   constructor(context) {
@@ -15,6 +22,7 @@ export class WorkspaceGraph {
 
   /**
    * Checks the environment layout to discover and map local workspace packages.
+   * This method is idempotent and safe to call multiple times.
    */
   async initializeWorkspaceMesh() {
     const rootPackageJsonPath = path.join(this.context.cwd, 'package.json');
@@ -23,7 +31,7 @@ export class WorkspaceGraph {
     let workspaceGlobs = [];
     this.hoistedDependencies = new Set();
 
-    // Load hoisted dependencies from root package.json (Knip Issue #1792 fix)
+    // Load hoisted dependencies from root package.json
     try {
       const rootPkg = JSON.parse(await fs.readFile(rootPackageJsonPath, 'utf8'));
       const deps = { ...rootPkg.dependencies, ...rootPkg.devDependencies };
@@ -32,7 +40,7 @@ export class WorkspaceGraph {
       // No root package.json or unreadable
     }
 
-    // Protocol A: Check for pnpm workspace configurations
+    // Protocol A: Check for pnpm workspace configurations (pnpm-workspace.yaml)
     try {
       const yaml = await fs.readFile(pnpmWorkspacePath, 'utf8');
       const lines = yaml.split('\n');
@@ -40,26 +48,33 @@ export class WorkspaceGraph {
 
       for (const line of lines) {
         const trimmed = line.trim();
-        if (trimmed.startsWith('packages:')) {
+        if (trimmed === 'packages:') {
           insidePackagesBlock = true;
           continue;
         }
-        if (insidePackagesBlock && trimmed.startsWith('-')) {
-          const pattern = trimmed.replace(/^-|['"]/g, '').trim();
-          workspaceGlobs.push(pattern);
+        if (insidePackagesBlock) {
+          if (trimmed.startsWith('-')) {
+            const pattern = trimmed.replace(/^-\s*/, '').replace(/['"]/g, '').trim();
+            if (pattern) workspaceGlobs.push(pattern);
+          } else if (trimmed && !trimmed.startsWith('#')) {
+            // Another top-level key encountered – stop reading packages block
+            insidePackagesBlock = false;
+          }
         }
       }
     } catch {
       // pnpm structure absent; check package.json workspace array paths instead
     }
 
-    // Protocol B: Check for Yarn/npm workspaces array inside the root package.json
+    // Protocol B: Check for Yarn/npm/Bun workspaces array inside the root package.json
     if (workspaceGlobs.length === 0) {
       try {
         const pkgText = await fs.readFile(rootPackageJsonPath, 'utf8');
         const pkg = JSON.parse(pkgText);
         if (pkg.workspaces) {
-          workspaceGlobs = Array.isArray(pkg.workspaces) ? pkg.workspaces : (pkg.workspaces.packages || []);
+          workspaceGlobs = Array.isArray(pkg.workspaces)
+            ? pkg.workspaces
+            : (pkg.workspaces.packages || []);
         }
       } catch {
         // No workspaces found
@@ -68,6 +83,15 @@ export class WorkspaceGraph {
 
     if (workspaceGlobs.length > 0) {
       this.context.isWorkspaceEnabled = true;
+      if (this.context.verbose) {
+        console.log(`🌐 Auto-detected monorepo layout with ${workspaceGlobs.length} glob patterns.`);
+      }
+    } else if (this.context.isWorkspaceEnabled) {
+      // Force enabled via flag but no patterns found; default to standard packages/*
+      workspaceGlobs = ['packages/*'];
+      if (this.context.verbose) {
+        console.log(`🌐 Workspace mode forced via flag. Using default patterns: ${workspaceGlobs.join(', ')}`);
+      }
     } else {
       return; // Workspace mesh maps skipped for single-package targets
     }
@@ -76,48 +100,116 @@ export class WorkspaceGraph {
     for (const pattern of workspaceGlobs) {
       await this.locatePackagesViaPattern(pattern);
     }
+
+    // Register all discovered workspace packages as "used" external packages so they
+    // are never incorrectly flagged as unused dependencies.
+    this.markWorkspacePackagesAsUsed();
   }
 
+  /**
+   * Expands a workspace glob pattern and registers all found packages.
+   * Supports patterns like:
+   *   - `packages/*`       (one level deep)
+   *   - `apps/*`           (one level deep)
+   *   - `packages/**`      (recursive – all subdirectories)
+   *   - `packages/core`    (explicit single package)
+   */
   async locatePackagesViaPattern(globPattern) {
-    // Normalizes wildcards down into base query directories
     const standardizedPattern = globPattern.replace(/\\/g, '/');
+
+    // Determine if this is a recursive pattern (`**`) or a simple wildcard (`*`)
+    const isRecursive = standardizedPattern.includes('**');
+    const isWildcard = standardizedPattern.includes('*');
+
+    if (!isWildcard) {
+      // Explicit path: treat the pattern itself as a single package directory
+      const absolutePath = path.resolve(this.context.cwd, standardizedPattern);
+      await this._tryRegisterPackage(absolutePath);
+      return;
+    }
+
+    // Extract the base directory before the first wildcard segment
     const baseDir = standardizedPattern.split('/*')[0];
     const absoluteSearchPath = path.resolve(this.context.cwd, baseDir);
 
+    if (isRecursive) {
+      await this._scanDirectoryRecursively(absoluteSearchPath);
+    } else {
+      await this._scanDirectoryShallow(absoluteSearchPath);
+    }
+  }
+
+  /**
+   * Scans a directory one level deep for workspace packages.
+   */
+  async _scanDirectoryShallow(absoluteSearchPath) {
     try {
       const contents = await fs.readdir(absoluteSearchPath, { withFileTypes: true });
-      
       for (const entity of contents) {
         if (!entity.isDirectory()) continue;
-        
         const subPackageDir = path.join(absoluteSearchPath, entity.name);
-        const manifestFile = path.join(subPackageDir, 'package.json');
-        
-        try {
-          const data = await fs.readFile(manifestFile, 'utf8');
-          const pkg = JSON.parse(data);
-          
-          if (pkg.name) {
-            const entryPoints = this.calculatePackageExportsEntries(pkg, subPackageDir);
-            
-            this.packageManifests.set(pkg.name, {
-              packageName: pkg.name,
-              rootDirectory: subPackageDir,
-              manifestPath: manifestFile,
-              entryPoints
-            });
-
-            this.workspacePackageNames.add(pkg.name);
-          }
-        } catch {
-          // package.json parsing failed; ignore invalid directory roots
-        }
+        await this._tryRegisterPackage(subPackageDir);
       }
     } catch {
       // Unreadable target directories; pass tracking
     }
   }
 
+  /**
+   * Recursively scans a directory tree for workspace packages.
+   * Stops descending into `node_modules` directories.
+   */
+  async _scanDirectoryRecursively(absoluteSearchPath) {
+    try {
+      const contents = await fs.readdir(absoluteSearchPath, { withFileTypes: true });
+      for (const entity of contents) {
+        if (!entity.isDirectory()) continue;
+        if (entity.name === 'node_modules' || entity.name === '.git') continue;
+        const subDir = path.join(absoluteSearchPath, entity.name);
+        // Try to register as a package first
+        const registered = await this._tryRegisterPackage(subDir);
+        // If not a package root itself, recurse deeper
+        if (!registered) {
+          await this._scanDirectoryRecursively(subDir);
+        }
+      }
+    } catch {
+      // Unreadable directories; pass
+    }
+  }
+
+  /**
+   * Attempts to register a directory as a workspace package.
+   * Returns true if a valid package.json with a `name` field was found.
+   */
+  async _tryRegisterPackage(packageDir) {
+    const manifestFile = path.join(packageDir, 'package.json');
+    try {
+      const data = await fs.readFile(manifestFile, 'utf8');
+      const pkg = JSON.parse(data);
+      
+      if (pkg.name) {
+        const entryPoints = this.calculatePackageExportsEntries(pkg, packageDir);
+        
+        this.packageManifests.set(pkg.name, {
+          packageName: pkg.name,
+          rootDirectory: packageDir,
+          manifestPath: manifestFile,
+          entryPoints
+        });
+
+        this.workspacePackageNames.add(pkg.name);
+        // Also register the package root so the resolver can identify files
+        // inside this package as "internal" rather than node_modules.
+        this.context.monorepoPackageRoots.add(packageDir);
+        return true;
+      }
+    } catch {
+      // package.json parsing failed; ignore invalid directory roots
+    }
+    return false;
+  }
+
   /**
    * Tracks package entry points by evaluating standard fields and main/exports configurations.
    */
@@ -127,8 +219,9 @@ export class WorkspaceGraph {
     // Trace traditional entry fields
     if (pkg.main) entries.add(path.resolve(pkgDir, pkg.main));
     if (pkg.module) entries.add(path.resolve(pkgDir, pkg.module));
-    if (pkg.browser) entries.add(path.resolve(pkgDir, pkg.browser));
+    if (pkg.browser && typeof pkg.browser === 'string') entries.add(path.resolve(pkgDir, pkg.browser));
     if (pkg.types) entries.add(path.resolve(pkgDir, pkg.types));
+    if (pkg.typings) entries.add(path.resolve(pkgDir, pkg.typings));
 
     // Handle deep nested conditional exports matrices block parameters
     if (pkg.exports) {
@@ -157,6 +250,8 @@ export class WorkspaceGraph {
       if (exportsValue.startsWith('.')) {
         collected.add(path.resolve(pkgDir, exportsValue));
       }
+    } else if (Array.isArray(exportsValue)) {
+      exportsValue.forEach(v => this.recursivelyUnwindExports(v, pkgDir, collected));
     } else if (typeof exportsValue === 'object' && exportsValue !== null) {
       for (const val of Object.values(exportsValue)) {
         this.recursivelyUnwindExports(val, pkgDir, collected);
@@ -164,6 +259,19 @@ export class WorkspaceGraph {
     }
   }
 
+  /**
+   * Marks all registered workspace package names as used in the global
+   * `usedExternalPackages` set so they are never flagged as unused dependencies.
+   *
+   * This must be called after `initializeWorkspaceMesh()` and before the
+   * unused-dependency report is generated.
+   */
+  markWorkspacePackagesAsUsed() {
+    for (const pkgName of this.workspacePackageNames) {
+      this.context.usedExternalPackages.add(pkgName);
+    }
+  }
+
   /**
    * Checks if an import specifier matches a package registered in our workspace mesh.
    */