helpforbegs 0.0.0-stage → 1.0.0

package/src/args.js

@@ -0,0 +1,116 @@
+// src/args.js
+// WHY: We avoid heavy argument parsing libraries (like commander or yargs)
+// to keep helpforbegs lightweight, fast to install, and dependency-free for CLI parsing.
+// Parsing process.argv manually teaches us exactly how Node.js receives command-line inputs.
+
+const path = require('path');
+
+/**
+ * Parses raw command-line arguments (process.argv.slice(2))
+ * into an easy-to-use JavaScript object.
+ *
+ * @param {string[]} rawArgs - e.g. ['scan', '--roast', '--path', './my-app']
+ * @returns {object} Parsed command, package target (for `why`), and options
+ */
+function parseArgs(rawArgs = process.argv.slice(2)) {
+  const flags = {
+    json: false,
+    noColor: false,
+    roast: false,
+    targetDir: process.cwd(), // Default to the folder where the user ran the command
+    dryRun: false,
+    yes: false,
+    help: false,
+    version: false,
+    debug: false,
+    isInteractive: true, // Auto-adjusted below for CI / non-TTY
+  };
+
+  const positional = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+
+    if (arg === '--json') {
+      flags.json = true;
+    } else if (arg === '--no-color') {
+      flags.noColor = true;
+    } else if (arg === '--roast') {
+      flags.roast = true;
+    } else if (arg === '--dry-run') {
+      flags.dryRun = true;
+    } else if (arg === '--yes' || arg === '-y') {
+      flags.yes = true;
+    } else if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      flags.version = true;
+    } else if (arg === '--debug') {
+      flags.debug = true;
+    } else if (arg === '--path') {
+      // The user provided --path <directory>. Look at the next argument.
+      const nextArg = rawArgs[i + 1];
+      if (nextArg && !nextArg.startsWith('-')) {
+        flags.targetDir = path.resolve(process.cwd(), nextArg);
+        i++; // Skip the directory string in the next loop iteration
+      }
+    } else if (arg.startsWith('--path=')) {
+      // Support syntax like --path=./subfolder
+      const customPath = arg.slice('--path='.length);
+      flags.targetDir = path.resolve(process.cwd(), customPath);
+    } else if (!arg.startsWith('-')) {
+      positional.push(arg);
+    }
+  }
+
+  // Determine the primary command:
+  // e.g. `helpforbegs` -> 'scan'
+  //      `helpforbegs scan` -> 'scan'
+  //      `helpforbegs remove` -> 'remove'
+  //      `helpforbegs why lodash` -> command: 'why', targetPkg: 'lodash'
+  //      `helpforbegs score` -> 'score'
+  let command = 'scan';
+  let targetPkg = null;
+
+  if (positional.length > 0) {
+    const first = positional[0].toLowerCase();
+    if (first === 'scan' || first === 'remove' || first === 'score') {
+      command = first;
+    } else if (first === 'why') {
+      command = 'why';
+      targetPkg = positional[1] || null; // e.g. 'why express' -> express
+    } else {
+      // If someone types `helpforbegs my-package` without saying 'why',
+      // or an unknown command, we keep 'scan' or treat it safely.
+      command = first;
+    }
+  }
+
+  // TTY and CI detection:
+  // WHY: If the CLI is run inside a script, redirected to a file (`helpforbegs > output.txt`),
+  // or executed inside a CI pipeline (like GitHub Actions), process.stdout.isTTY is false.
+  // In those environments:
+  // 1. We must not emit ANSI escape color codes (they turn into messy symbols in text files).
+  // 2. We cannot ask interactive readline questions (there is no human sitting at a keyboard).
+  const isCI = Boolean(process.env.CI);
+  const isNoColorEnv = Boolean(process.env.NO_COLOR);
+  const isNotTTY = !process.stdout.isTTY;
+
+  if (isCI || isNoColorEnv || isNotTTY || flags.noColor) {
+    flags.noColor = true;
+  }
+
+  if (isCI || isNotTTY) {
+    flags.isInteractive = false;
+  }
+
+  return {
+    command,
+    targetPkg,
+    flags,
+  };
+}
+
+module.exports = {
+  parseArgs,
+};

package/src/astParser.js

@@ -0,0 +1,228 @@
+// src/astParser.js
+// WHY: Regular expressions can be easily fooled by commented-out code
+// or strings containing "require('foo')". Using @babel/parser ensures we
+// inspect the real AST (Abstract Syntax Tree) with 100% syntactic precision.
+
+const babelParser = require('@babel/parser');
+const path = require('path');
+const { scanWithRegex, normalizePackageName } = require('./fallbackParser');
+
+/**
+ * Determines the exact Babel plugins needed based on the file extension.
+ *
+ * Rule from user:
+ * - .ts: ['typescript']
+ * - .tsx: ['typescript', 'jsx']
+ * - .js / .jsx / .mjs / .cjs: ['jsx']
+ *
+ * @param {string} ext - e.g. '.tsx'
+ * @returns {string[]}
+ */
+function getBabelPlugins(ext) {
+  const normalizedExt = (ext || '').toLowerCase();
+  if (normalizedExt === '.ts') {
+    return ['typescript'];
+  }
+  if (normalizedExt === '.tsx') {
+    return ['typescript', 'jsx'];
+  }
+  return ['jsx'];
+}
+
+/**
+ * Traverses an AST tree without needing an external walker library.
+ *
+ * @param {object} node - Current AST node
+ * @param {(node: object) => void} visitor - Function called for each node
+ */
+function walkAST(node, visitor) {
+  if (!node || typeof node !== 'object') {
+    return;
+  }
+
+  visitor(node);
+
+  for (const key of Object.keys(node)) {
+    // Avoid traversing parent references or metadata to prevent infinite loops
+    if (key === 'loc' || key === 'comments' || key === 'tokens') {
+      continue;
+    }
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (item && typeof item === 'object') {
+          walkAST(item, visitor);
+        }
+      }
+    } else if (child && typeof child === 'object') {
+      walkAST(child, visitor);
+    }
+  }
+}
+
+/**
+ * Safely extracts a string value from an argument node.
+ * Handles both plain 'string' literals and non-dynamic template literals like `pkg`.
+ *
+ * @param {object} argNode
+ * @returns {string|null}
+ */
+function extractStringArgument(argNode) {
+  if (!argNode) return null;
+  if (argNode.type === 'StringLiteral') {
+    return argNode.value;
+  }
+  if (argNode.type === 'TemplateLiteral' && argNode.expressions.length === 0 && argNode.quasis.length === 1) {
+    return argNode.quasis[0].value.raw;
+  }
+  return null;
+}
+
+/**
+ * Parses a code string into AST, extracts all imported/required package names,
+ * and falls back to regex if the file has syntax errors.
+ *
+ * @param {string} code - Source code text
+ * @param {string} filePath - Path to the file (used to decide plugins & line numbers)
+ * @param {object} [options]
+ * @param {Set<string>} [options.knownAliases] - Path aliases to ignore
+ * @returns {{ imports: Array<{ packageName: string, rawSpecifier: string, line: number, isTypeOnly: boolean }>, warning: string|null }}
+ */
+function parseImports(code, filePath, options = {}) {
+  const ext = path.extname(filePath);
+  const plugins = getBabelPlugins(ext);
+  const knownAliases = options.knownAliases || new Set();
+  const rawImports = [];
+  let warning = null;
+
+  try {
+    const ast = babelParser.parse(code, {
+      sourceType: 'unambiguous', // Automatically detects CommonJS vs ES Modules
+      plugins: plugins,
+      errorRecovery: true, // Recovers from non-fatal syntax errors
+      attachComment: false,
+    });
+
+    walkAST(ast, (node) => {
+      // 1. Static ES Module Imports: `import foo from 'pkg'` or `import 'pkg'`
+      if (node.type === 'ImportDeclaration') {
+        if (node.source && typeof node.source.value === 'string') {
+          const isTypeOnly = node.importKind === 'type';
+          rawImports.push({
+            rawSpecifier: node.source.value,
+            line: node.loc ? node.loc.start.line : 1,
+            isTypeOnly,
+          });
+        }
+      }
+
+      // 2. ES Module Re-exports: `export { x } from 'pkg'` or `export * from 'pkg'`
+      else if (node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration') {
+        if (node.source && typeof node.source.value === 'string') {
+          const isTypeOnly = node.exportKind === 'type';
+          rawImports.push({
+            rawSpecifier: node.source.value,
+            line: node.loc ? node.loc.start.line : 1,
+            isTypeOnly,
+          });
+        }
+      }
+
+      // 3. CommonJS `require('pkg')`, `require.resolve('pkg')`, and dynamic `import('pkg')`
+      else if (node.type === 'CallExpression') {
+        // require('pkg')
+        if (node.callee.type === 'Identifier' && node.callee.name === 'require' && node.arguments.length > 0) {
+          const specifier = extractStringArgument(node.arguments[0]);
+          if (specifier) {
+            rawImports.push({
+              rawSpecifier: specifier,
+              line: node.loc ? node.loc.start.line : 1,
+              isTypeOnly: false,
+            });
+          }
+        }
+
+        // require.resolve('pkg')
+        else if (
+          node.callee.type === 'MemberExpression' &&
+          node.callee.object.type === 'Identifier' &&
+          node.callee.object.name === 'require' &&
+          node.callee.property.type === 'Identifier' &&
+          node.callee.property.name === 'resolve' &&
+          node.arguments.length > 0
+        ) {
+          const specifier = extractStringArgument(node.arguments[0]);
+          if (specifier) {
+            rawImports.push({
+              rawSpecifier: specifier,
+              line: node.loc ? node.loc.start.line : 1,
+              isTypeOnly: false,
+            });
+          }
+        }
+
+        // Dynamic import('pkg')
+        else if (node.callee.type === 'Import' && node.arguments.length > 0) {
+          const specifier = extractStringArgument(node.arguments[0]);
+          if (specifier) {
+            rawImports.push({
+              rawSpecifier: specifier,
+              line: node.loc ? node.loc.start.line : 1,
+              isTypeOnly: false,
+            });
+          }
+        }
+      }
+
+      // 4. TypeScript `import foo = require('pkg')`
+      else if (node.type === 'TSImportEqualsDeclaration') {
+        if (
+          node.moduleReference &&
+          node.moduleReference.type === 'TSExternalModuleReference' &&
+          node.moduleReference.expression &&
+          typeof node.moduleReference.expression.value === 'string'
+        ) {
+          rawImports.push({
+            rawSpecifier: node.moduleReference.expression.value,
+            line: node.loc ? node.loc.start.line : 1,
+            isTypeOnly: false,
+          });
+        }
+      }
+    });
+  } catch (err) {
+    // If AST parsing fails, use our safe fallback regex scanner for this file
+    warning = `Could not fully read ${filePath}`;
+    const fallbackResults = scanWithRegex(code, filePath, { knownAliases });
+    return {
+      imports: fallbackResults,
+      warning,
+    };
+  }
+
+  // Normalize all raw specifiers into npm package names
+  const normalizedImports = [];
+  for (const item of rawImports) {
+    const packageName = normalizePackageName(item.rawSpecifier, knownAliases);
+    if (packageName) {
+      normalizedImports.push({
+        packageName,
+        rawSpecifier: item.rawSpecifier,
+        line: item.line,
+        isTypeOnly: item.isTypeOnly,
+      });
+    }
+  }
+
+  return {
+    imports: normalizedImports,
+    warning,
+  };
+}
+
+module.exports = {
+  parseImports,
+  getBabelPlugins,
+  normalizePackageName,
+  walkAST,
+};

package/src/binMapper.js

@@ -0,0 +1,167 @@
+// src/binMapper.js
+// WHY: When a user installs CLI tools like "rimraf", "nodemon", or "eslint",
+// they don't `require('rimraf')` in code. Instead, they write `"clean": "rimraf dist"`
+// in package.json scripts.
+// By reading each installed package's "bin" field in node_modules, we discover
+// what terminal commands it provides, and we can check if the user runs those commands in their scripts.
+
+const fs = require('fs');
+const path = require('path');
+
+// Standard fallback command mappings for common development tools.
+// WHY: If a user hasn't run `npm install` yet, node_modules is missing.
+// Having built-in knowledge of standard tool commands (e.g. `tsc` comes from `typescript`)
+// ensures we still recognize script usage and avoid false positives!
+const DEFAULT_KNOWN_BINS = new Map([
+  ['tsc', 'typescript'],
+  ['eslint', 'eslint'],
+  ['prettier', 'prettier'],
+  ['jest', 'jest'],
+  ['nodemon', 'nodemon'],
+  ['vite', 'vite'],
+  ['webpack', 'webpack'],
+  ['rimraf', 'rimraf'],
+  ['cross-env', 'cross-env'],
+  ['ts-node', 'ts-node'],
+  ['tsx', 'tsx'],
+  ['babel', '@babel/cli'],
+  ['mocha', 'mocha'],
+  ['vitest', 'vitest'],
+  ['concurrently', 'concurrently'],
+  ['npm-run-all', 'npm-run-all'],
+]);
+
+/**
+ * Discovers CLI binary commands provided by all installed packages in node_modules.
+ *
+ * @param {string} projectDir - Root folder containing package.json and node_modules
+ * @returns {{ binToPkg: Map<string, string>, pkgToBins: Map<string, string[]>, missingNodeModules: boolean }}
+ */
+function mapInstalledBins(projectDir) {
+  // Pre-seed with known standard binaries as a safety baseline
+  const binToPkg = new Map(DEFAULT_KNOWN_BINS);
+  const pkgToBins = new Map();
+  const nodeModulesPath = path.join(projectDir, 'node_modules');
+
+  if (!fs.existsSync(nodeModulesPath)) {
+    // If node_modules hasn't been installed yet, don't crash!
+    // Simply report that node_modules is missing so the analyzer can inform the user.
+    return {
+      binToPkg,
+      pkgToBins,
+      missingNodeModules: true,
+    };
+  }
+
+  function readPkgJson(pkgName, pkgJsonPath) {
+    try {
+      if (fs.existsSync(pkgJsonPath)) {
+        const content = fs.readFileSync(pkgJsonPath, 'utf8');
+        const pkgData = JSON.parse(content);
+
+        if (pkgData.bin) {
+          const bins = [];
+          if (typeof pkgData.bin === 'string') {
+            // If "bin" is a string, the command name defaults to the package name
+            // (or unscoped name for scoped packages)
+            const defaultBinName = pkgName.startsWith('@') ? pkgName.split('/')[1] : pkgName;
+            binToPkg.set(defaultBinName, pkgName);
+            bins.push(defaultBinName);
+          } else if (typeof pkgData.bin === 'object' && pkgData.bin !== null) {
+            for (const binName of Object.keys(pkgData.bin)) {
+              binToPkg.set(binName, pkgName);
+              bins.push(binName);
+            }
+          }
+
+          if (bins.length > 0) {
+            pkgToBins.set(pkgName, bins);
+          }
+        }
+      }
+    } catch {
+      // Ignore unparseable or corrupted package.json files inside node_modules
+    }
+  }
+
+  try {
+    const entries = fs.readdirSync(nodeModulesPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      if (entry.name.startsWith('@')) {
+        // Handle scoped packages like @babel/cli inside node_modules/@babel/
+        const scopePath = path.join(nodeModulesPath, entry.name);
+        try {
+          const scopedEntries = fs.readdirSync(scopePath, { withFileTypes: true });
+          for (const scopedEntry of scopedEntries) {
+            if (scopedEntry.isDirectory()) {
+              const fullPkgName = `${entry.name}/${scopedEntry.name}`;
+              const pkgJsonPath = path.join(scopePath, scopedEntry.name, 'package.json');
+              readPkgJson(fullPkgName, pkgJsonPath);
+            }
+          }
+        } catch {
+          // Skip unreadable scope folders
+        }
+      } else if (!entry.name.startsWith('.')) {
+        // Standard non-scoped package
+        const pkgJsonPath = path.join(nodeModulesPath, entry.name, 'package.json');
+        readPkgJson(entry.name, pkgJsonPath);
+      }
+    }
+  } catch {
+    return {
+      binToPkg,
+      pkgToBins,
+      missingNodeModules: false,
+    };
+  }
+
+  return {
+    binToPkg,
+    pkgToBins,
+    missingNodeModules: false,
+  };
+}
+
+/**
+ * Checks all package.json scripts to see which packages are executed via CLI commands.
+ *
+ * @param {Record<string, string>} scripts - The "scripts" object from package.json
+ * @param {Map<string, string>} binToPkg - Map of commandName -> packageName
+ * @returns {Map<string, Array<{ scriptName: string, command: string }>>} - Map of packageName -> where it was used
+ */
+function findBinUsageInScripts(scripts = {}, binToPkg = new Map()) {
+  const usageByPkg = new Map();
+
+  for (const [scriptName, scriptCmd] of Object.entries(scripts)) {
+    if (typeof scriptCmd !== 'string') continue;
+
+    // Check each known binary name to see if it is invoked as a word in the script
+    for (const [binName, pkgName] of binToPkg.entries()) {
+      // Escape regex special chars in command name
+      const escapedBin = binName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      // Match the command as a standalone word or at the start of a command pipeline
+      const wordRegex = new RegExp(`(^|[;&|\\s])${escapedBin}(\\s|$|[;&|])`);
+
+      if (wordRegex.test(scriptCmd)) {
+        if (!usageByPkg.has(pkgName)) {
+          usageByPkg.set(pkgName, []);
+        }
+        usageByPkg.get(pkgName).push({
+          scriptName,
+          command: binName,
+        });
+      }
+    }
+  }
+
+  return usageByPkg;
+}
+
+module.exports = {
+  mapInstalledBins,
+  findBinUsageInScripts,
+};