pkg-scaffold 3.3.3 → 3.3.5

package/src/resolution/CircularDetector.js

@@ -1,31 +1,14 @@
-/**
- * ============================================================================
- * Circular Dependency Detector for pkg-scaffold v3.3.0
- * 
- * Copyright (C) 2026 DreamLongYT
- * Licensed under the Apache License, Version 2.0.
- * "The Original Code was made by DreamLongYT"
- * ============================================================================
- * Implements a high-performance Tarjan-based algorithm to
- * detect circular dependencies in the codebase graph.
- * Addresses Knip Issue #1734.
- */
-
 export class CircularDetector {
   constructor(context) {
     this.context = context;
     this.cycles = [];
   }
 
-  /**
-   * Detects cycles in the provided dependency graph using Tarjan's SCC algorithm
-   * @param {Map} graph - The codebase dependency graph
-   * @returns {Array} List of detected cycles
-   */
   detectCycles(graph, context = null) {
     if (context) this.context = context;
     this.cwd = context?.cwd || this.context?.cwd || process.cwd();
     this.cycles = [];
+    
     let index = 0;
     const stack = [];
     const indices = new Map();
@@ -63,7 +46,6 @@ export class CircularDetector {
         if (component.length > 1) {
           this.cycles.push(component.reverse());
         } else {
-          // Check for self-loops
           const node = graph.get(v);
           if (node && node.outgoingEdges && node.outgoingEdges.has(v)) {
             this.cycles.push([v]);
@@ -81,18 +63,11 @@ export class CircularDetector {
     return this.cycles;
   }
 
-  /**
-   * Formats cycles for reporting with file paths
-   */
   formatCycles() {
     return this.cycles.map(cycle => {
       const paths = cycle.map(p => {
-        // Extract relative path for readability
         let rel = p.replace(this.context.cwd, '').replace(/^\//, '');
-        // Convert absolute Windows paths
-        if (rel.includes(':\\')) {
-          rel = rel.split(':\\')[1] || rel;
-        }
+        if (rel.includes(':\\')) rel = rel.split(':\\')[1] || rel;
         return rel;
       });
       if (cycle.length === 1) return `${paths[0]} -> (self-loop)`;
@@ -100,17 +75,12 @@ export class CircularDetector {
     });
   }
 
-  /**
-   * Gets detailed cycle information
-   */
   getCycleDetails() {
     return this.cycles.map((cycle, idx) => ({
       cycleId: idx + 1,
       files: cycle.map(p => {
         let rel = p.replace(this.context.cwd, '').replace(/^\//, '');
-        if (rel.includes(':\\')) {
-          rel = rel.split(':\\')[1] || rel;
-        }
+        if (rel.includes(':\\')) rel = rel.split(':\\')[1] || rel;
         return rel;
       }),
       length: cycle.length,
@@ -118,5 +88,4 @@ export class CircularDetector {
     }));
   }
 }
-
 export default CircularDetector;

package/src/resolution/ConfigLoader.js

@@ -13,40 +13,68 @@ export class ConfigLoader {
 
   async loadConfig(projectRoot) {
     const searchPaths = [
+      'pkg-scaffold.json',
+      'pkg-scaffold.jsonc',
+      '.pkg-scaffold.json',
+      '.pkg-scaffold.jsonc',
+      'pkg-scaffold.js',
+      'pkg-scaffold.ts',
+      'pkg-scaffold/config.json',
       'scaffold.config.js',
       'scaffold.config.mjs',
       '.scaffoldrc.json',
       '.scaffoldrc'
     ];
 
+    let config = this.getDefaultConfig();
+
+    // Try package.json first
+    try {
+      const pkgPath = path.join(projectRoot, 'package.json');
+      const pkgContent = await fs.readFile(pkgPath, 'utf8');
+      const pkg = JSON.parse(pkgContent);
+      if (pkg['pkg-scaffold']) {
+        Object.assign(config, pkg['pkg-scaffold']);
+      }
+    } catch (e) {
+      // ignore
+    }
+
     for (const fileName of searchPaths) {
       const fullPath = path.join(projectRoot, fileName);
       try {
         await fs.access(fullPath);
         
-        if (fileName.endsWith('.js') || fileName.endsWith('.mjs')) {
+        if (fileName.endsWith('.js') || fileName.endsWith('.mjs') || fileName.endsWith('.ts')) {
           const module = await import(pathToFileURL(fullPath).href);
-          return module.default || module;
+          Object.assign(config, module.default || module);
+          break;
         } else {
           const content = await fs.readFile(fullPath, 'utf8');
-          return JSON.parse(content);
+          // Very basic JSONC parsing (strip comments)
+          const stripped = content.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, '');
+          Object.assign(config, JSON.parse(stripped));
+          break;
         }
       } catch (e) {
         continue;
       }
     }
 
-    return this.getDefaultConfig();
+    return config;
   }
 
   getDefaultConfig() {
     return {
-      entryPoints: ['src/index.ts', 'index.js'],
+      entryPoints: ['src/index.ts', 'index.js', 'src/index.js', 'src/main.ts', 'src/main.js'],
       exclude: [
         'node_modules/**',
         'dist/**',
+        'build/**',
         '**/*.test.ts',
-        '**/*.spec.ts'
+        '**/*.spec.ts',
+        '**/*.test.js',
+        '**/*.spec.js'
       ],
       plugins: [],
       rules: {

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;
+  }
 }