@saulwade/swl-ses 1.4.1 → 1.5.0

package/scripts/audit-tools/dep-doctor.js

@@ -1,320 +1,320 @@
-// Adaptado de temp/ultraship-main/tools/dep-doctor.mjs bajo MIT License
-// Fuente: Houseofmvps/ultraship (https://github.com/Houseofmvps/ultraship)
-'use strict';
-
-const { readFileSync, existsSync, readdirSync, statSync } = require('fs');
-const { join, relative, extname } = require('path');
-const { outputJSON, outputError } = require('./lib/output');
-
-const SKIP_DIRS = new Set([
-  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
-  '__pycache__', '.cache', 'venv', '.venv', 'target', 'vendor',
-  '.tox', 'eggs', '.eggs', 'htmlcov', '.mypy_cache', '.pytest_cache',
-]);
-
-const CODE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json', '.vue', '.svelte']);
-
-/**
- * Recorre un directorio buscando archivos de código.
- * @param {string} dir
- * @returns {string[]}
- */
-function findCodeFiles(dir) {
-  const files = [];
-  function walk(d) {
-    try {
-      for (const entry of readdirSync(d)) {
-        if (entry.startsWith('.') || SKIP_DIRS.has(entry)) continue;
-        const p = join(d, entry);
-        try {
-          const s = statSync(p);
-          if (s.isDirectory()) walk(p);
-          else if (CODE_EXTS.has(extname(entry).toLowerCase())) files.push(p);
-        } catch { /* skip */ }
-      }
-    } catch { /* skip */ }
-  }
-  walk(dir);
-  return files;
-}
-
-// Dependencias usadas implícitamente (herramientas de build, definiciones de tipos)
-const IMPLICIT_DEPS = new Set([
-  'typescript', '@types/node', '@types/react', '@types/react-dom',
-  'eslint', 'prettier', 'vitest', 'jest', 'mocha',
-  'tailwindcss', 'autoprefixer', 'postcss',
-  'drizzle-kit', 'prisma',
-  '@vitejs/plugin-react', 'vite',
-  'tsx', 'ts-node', 'nodemon',
-  'husky', 'lint-staged', 'commitlint',
-  'dotenv', 'cross-env',
-]);
-
-// Paquetes cuyo nombre de import difiere del nombre en package.json
-const IMPORT_ALIASES = {
-  'next': ['next', 'next/'],
-  '@hono/node-server': ['@hono/node-server'],
-  'drizzle-orm': ['drizzle-orm'],
-  '@neondatabase/serverless': ['@neondatabase/serverless'],
-  'better-auth': ['better-auth'],
-  '@anthropic-ai/sdk': ['@anthropic-ai/sdk', 'anthropic'],
-  '@clerk/nextjs': ['@clerk/nextjs'],
-};
-
-/**
- * Detecta dependencias no utilizadas en el directorio dado.
- * @param {string} dir
- * @returns {{ unused: object[], total_deps: number, total_dev_deps: number, error?: string }}
- */
-function detectUnusedDeps(dir) {
-  const pkgPath = join(dir, 'package.json');
-  if (!existsSync(pkgPath)) return { unused: [], error: 'No se encontró package.json', total_deps: 0, total_dev_deps: 0 };
-
-  let pkg;
-  try {
-    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-  } catch (e) {
-    return { unused: [], error: `package.json inválido: ${e.message}`, total_deps: 0, total_dev_deps: 0 };
-  }
-
-  const prodDeps = Object.keys(pkg.dependencies || {});
-  const devDeps = Object.keys(pkg.devDependencies || {});
-
-  const codeFiles = findCodeFiles(dir);
-  const fileContents = new Map();
-  let allCode = '';
-
-  for (const file of codeFiles) {
-    try {
-      const code = readFileSync(file, 'utf8');
-      fileContents.set(file, code);
-      allCode += code + '\n';
-    } catch { /* skip */ }
-  }
-
-  // Incluir archivos de configuración en la raíz
-  const configFiles = [
-    'vite.config.ts', 'vite.config.js', 'next.config.js', 'next.config.mjs',
-    'tailwind.config.js', 'tailwind.config.ts', 'postcss.config.js', 'postcss.config.cjs',
-    'drizzle.config.ts', 'drizzle.config.js', '.eslintrc.js', '.eslintrc.json',
-    'tsconfig.json', 'jest.config.js', 'vitest.config.ts',
-  ];
-  for (const cf of configFiles) {
-    const p = join(dir, cf);
-    if (existsSync(p)) {
-      try {
-        const code = readFileSync(p, 'utf8');
-        fileContents.set(p, code);
-        allCode += code + '\n';
-      } catch { /* skip */ }
-    }
-  }
-
-  // Construir grafo de imports: objetivos de import locales normalizados
-  const allImportTargets = new Set();
-  for (const [, code] of fileContents) {
-    const importRegex = /(?:from\s+|require\s*\(\s*)['"]([^'"]+)['"]/g;
-    let m;
-    while ((m = importRegex.exec(code)) !== null) {
-      const target = m[1];
-      if (target.startsWith('.') || target.startsWith('@/') || target.startsWith('~/')) {
-        const clean = target.replace(/^(?:\.\/|@\/|~\/)/, '').replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '');
-        allImportTargets.add(clean);
-        allImportTargets.add(clean.replace(/\/index$/, ''));
-      }
-    }
-  }
-
-  function isFileReachable(filePath) {
-    const rel = relative(dir, filePath).replace(/\\/g, '/');
-    const noExt = rel.replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '');
-    const noIndex = noExt.replace(/\/index$/, '');
-    const basename = filePath.split(/[/\\]/).pop();
-    if (['page.tsx', 'page.ts', 'page.jsx', 'layout.tsx', 'layout.ts',
-      'main.tsx', 'main.ts', 'App.tsx', 'App.ts', 'index.tsx', 'index.ts',
-      'index.js', 'main.js'].includes(basename)) return true;
-    if (rel.includes('/routes/') || rel.includes('/api/') || rel.includes('/pages/')) return true;
-    if (rel.includes('config')) return true;
-    for (const target of allImportTargets) {
-      if (target === noExt || target === noIndex ||
-        target === `src/${noExt}` || target === `src/${noIndex}` ||
-        noExt.endsWith(`/${target}`) || noIndex.endsWith(`/${target}`)) return true;
-    }
-    return false;
-  }
-
-  function findDepImportFiles(dep) {
-    const aliases = IMPORT_ALIASES[dep] || [dep];
-    const files = [];
-    for (const [filePath, code] of fileContents) {
-      for (const alias of aliases) {
-        if (code.includes(`'${alias}'`) || code.includes(`"${alias}"`) ||
-          code.includes(`'${alias}/`) || code.includes(`"${alias}/`)) {
-          files.push(filePath);
-          break;
-        }
-      }
-      if (dep.startsWith('@') && !files.includes(filePath)) {
-        if (code.includes(`'${dep}'`) || code.includes(`"${dep}"`) ||
-          code.includes(`'${dep}/`) || code.includes(`"${dep}/`)) {
-          files.push(filePath);
-        }
-      }
-    }
-    return files;
-  }
-
-  const unused = [];
-
-  function isUsed(dep) {
-    if (IMPLICIT_DEPS.has(dep)) return true;
-    if (dep.startsWith('@types/')) return true;
-    const aliases = IMPORT_ALIASES[dep] || [dep];
-    for (const alias of aliases) {
-      if (allCode.includes(`'${alias}'`) || allCode.includes(`"${alias}"`)) return true;
-      if (allCode.includes(`'${alias}/`) || allCode.includes(`"${alias}/`)) return true;
-      if (allCode.includes(`require('${alias}')`) || allCode.includes(`require("${alias}")`)) return true;
-    }
-    if (dep.startsWith('@')) {
-      if (allCode.includes(`'${dep}'`) || allCode.includes(`"${dep}"`)) return true;
-      if (allCode.includes(`'${dep}/`) || allCode.includes(`"${dep}/`)) return true;
-    }
-    return false;
-  }
-
-  function isDeadCode(dep) {
-    const importFiles = findDepImportFiles(dep);
-    if (importFiles.length === 0) return true;
-    return importFiles.every(f => !isFileReachable(f));
-  }
-
-  for (const dep of prodDeps) {
-    if (!isUsed(dep)) {
-      unused.push({ name: dep, type: 'production', severity: 'high', message: `"${dep}" está en dependencies pero no se importa en ningún lugar — eliminar para reducir el tamaño de instalación` });
-    } else if (isDeadCode(dep)) {
-      unused.push({ name: dep, type: 'production', severity: 'medium', message: `"${dep}" solo se importa en archivos no alcanzables — eliminar si esos componentes no se necesitan` });
-    }
-  }
-
-  for (const dep of devDeps) {
-    if (!isUsed(dep)) {
-      unused.push({ name: dep, type: 'devDependency', severity: 'low', message: `"${dep}" está en devDependencies pero no se referencia — puede eliminarse` });
-    }
-  }
-
-  return { unused, total_deps: prodDeps.length, total_dev_deps: devDeps.length };
-}
-
-/**
- * Detecta dependencias posiblemente desactualizadas.
- * @param {string} dir
- * @returns {{ outdated: object[] }}
- */
-function detectOutdated(dir) {
-  const pkgPath = join(dir, 'package.json');
-  if (!existsSync(pkgPath)) return { outdated: [] };
-
-  let pkg;
-  try {
-    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-  } catch {
-    return { outdated: [] };
-  }
-
-  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-  const findings = [];
-
-  for (const [name, version] of Object.entries(allDeps)) {
-    if (typeof version !== 'string') continue;
-    const v = version.trim();
-    if (v.startsWith('file:') || v.startsWith('link:') || v.startsWith('workspace:') || v === '*' || v === 'latest') continue;
-
-    // Versión anclada exacta (sin ^ ni ~)
-    if (/^\d/.test(v)) {
-      findings.push({
-        name,
-        version: v,
-        severity: 'low',
-        issue: 'anclada',
-        message: `"${name}@${v}" está anclado a versión exacta — usar ^${v} para recibir actualizaciones de parches`,
-      });
-    }
-
-    // Versiones mayores muy antiguas de paquetes conocidos
-    const majorMatch = v.match(/\d+/);
-    if (majorMatch) {
-      const major = parseInt(majorMatch[0], 10);
-      const knownOld = {
-        'react': 18, 'next': 14, 'vue': 3, 'express': 4, 'hono': 4,
-        'typescript': 5, 'vite': 5, 'tailwindcss': 3, 'eslint': 9,
-        'drizzle-orm': 0, 'prisma': 5, 'zod': 3,
-      };
-      if (knownOld[name] !== undefined && major < knownOld[name] - 1) {
-        findings.push({
-          name,
-          version: v,
-          severity: 'medium',
-          issue: 'mayor_desactualizado',
-          message: `"${name}@${v}" tiene ${knownOld[name] - major}+ versiones mayores de retraso — considerar actualización`,
-        });
-      }
-    }
-  }
-
-  return { outdated: findings };
-}
-
-function main() {
-  const dir = process.argv[2];
-  if (!dir) {
-    outputError('Uso: node dep-doctor.js <directorio-proyecto>');
-    process.exit(0);
-  }
-
-  if (!existsSync(dir)) {
-    outputError(`Ruta no encontrada: ${dir}`);
-    process.exit(0);
-  }
-
-  const unusedResult = detectUnusedDeps(dir);
-  const outdatedResult = detectOutdated(dir);
-
-  outputJSON({
-    success: true,
-    packages_scanned: 1,
-    total_production_deps: unusedResult.total_deps || 0,
-    total_dev_deps: unusedResult.total_dev_deps || 0,
-    unused_count: unusedResult.unused.length,
-    outdated_count: outdatedResult.outdated.length,
-    total_findings: unusedResult.unused.length + outdatedResult.outdated.length,
-    unused: unusedResult.unused,
-    outdated: outdatedResult.outdated,
-  });
-}
-
-main();
-
-module.exports = { detectUnusedDeps, detectOutdated, findCodeFiles, IMPLICIT_DEPS };
-
-/**
- * @complemento Skill("dependencias-auditoria")
- *
- * dep-doctor.js realiza **análisis estático** de dependencias:
- *   - Detecta dependencias declaradas pero nunca importadas en el código fuente.
- *   - Detecta versiones ancladas sin `^`/`~` y versiones mayores muy desactualizadas.
- *   - Sin ejecución de shell, sin red. Seguro para usar en cualquier entorno.
- *   - Rápido (solo lectura de archivos locales).
- *
- * Skill("dependencias-auditoria") realiza **auditoría de seguridad profunda**:
- *   - Consulta bases de datos CVE reales (pip-audit, npm audit, trivy, grype).
- *   - Detecta licencias incompatibles (pip-licenses, license-checker).
- *   - Identifica dependencias abandonadas con fecha de último commit.
- *   - Requiere: red (acceso a advisories), shell (pip-audit, npm, trivy instalados).
- *   - Más lento pero definitivo en vulnerabilidades conocidas.
- *
- * Flujo recomendado:
- *   1. Ejecutar `dep-doctor.js` primero (rápido, sin dependencias externas).
- *      → Eliminar dependencias no usadas reduce la superficie de ataque.
- *   2. Luego invocar `Skill("dependencias-auditoria")` para CVEs y licencias.
- *      → Asegura que las dependencias restantes no tienen vulnerabilidades conocidas.
- */
+// Adaptado de temp/ultraship-main/tools/dep-doctor.mjs bajo MIT License
+// Fuente: Houseofmvps/ultraship (https://github.com/Houseofmvps/ultraship)
+'use strict';
+
+const { readFileSync, existsSync, readdirSync, statSync } = require('fs');
+const { join, relative, extname } = require('path');
+const { outputJSON, outputError } = require('./lib/output');
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '__pycache__', '.cache', 'venv', '.venv', 'target', 'vendor',
+  '.tox', 'eggs', '.eggs', 'htmlcov', '.mypy_cache', '.pytest_cache',
+]);
+
+const CODE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json', '.vue', '.svelte']);
+
+/**
+ * Recorre un directorio buscando archivos de código.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findCodeFiles(dir) {
+  const files = [];
+  function walk(d) {
+    try {
+      for (const entry of readdirSync(d)) {
+        if (entry.startsWith('.') || SKIP_DIRS.has(entry)) continue;
+        const p = join(d, entry);
+        try {
+          const s = statSync(p);
+          if (s.isDirectory()) walk(p);
+          else if (CODE_EXTS.has(extname(entry).toLowerCase())) files.push(p);
+        } catch { /* skip */ }
+      }
+    } catch { /* skip */ }
+  }
+  walk(dir);
+  return files;
+}
+
+// Dependencias usadas implícitamente (herramientas de build, definiciones de tipos)
+const IMPLICIT_DEPS = new Set([
+  'typescript', '@types/node', '@types/react', '@types/react-dom',
+  'eslint', 'prettier', 'vitest', 'jest', 'mocha',
+  'tailwindcss', 'autoprefixer', 'postcss',
+  'drizzle-kit', 'prisma',
+  '@vitejs/plugin-react', 'vite',
+  'tsx', 'ts-node', 'nodemon',
+  'husky', 'lint-staged', 'commitlint',
+  'dotenv', 'cross-env',
+]);
+
+// Paquetes cuyo nombre de import difiere del nombre en package.json
+const IMPORT_ALIASES = {
+  'next': ['next', 'next/'],
+  '@hono/node-server': ['@hono/node-server'],
+  'drizzle-orm': ['drizzle-orm'],
+  '@neondatabase/serverless': ['@neondatabase/serverless'],
+  'better-auth': ['better-auth'],
+  '@anthropic-ai/sdk': ['@anthropic-ai/sdk', 'anthropic'],
+  '@clerk/nextjs': ['@clerk/nextjs'],
+};
+
+/**
+ * Detecta dependencias no utilizadas en el directorio dado.
+ * @param {string} dir
+ * @returns {{ unused: object[], total_deps: number, total_dev_deps: number, error?: string }}
+ */
+function detectUnusedDeps(dir) {
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) return { unused: [], error: 'No se encontró package.json', total_deps: 0, total_dev_deps: 0 };
+
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  } catch (e) {
+    return { unused: [], error: `package.json inválido: ${e.message}`, total_deps: 0, total_dev_deps: 0 };
+  }
+
+  const prodDeps = Object.keys(pkg.dependencies || {});
+  const devDeps = Object.keys(pkg.devDependencies || {});
+
+  const codeFiles = findCodeFiles(dir);
+  const fileContents = new Map();
+  let allCode = '';
+
+  for (const file of codeFiles) {
+    try {
+      const code = readFileSync(file, 'utf8');
+      fileContents.set(file, code);
+      allCode += code + '\n';
+    } catch { /* skip */ }
+  }
+
+  // Incluir archivos de configuración en la raíz
+  const configFiles = [
+    'vite.config.ts', 'vite.config.js', 'next.config.js', 'next.config.mjs',
+    'tailwind.config.js', 'tailwind.config.ts', 'postcss.config.js', 'postcss.config.cjs',
+    'drizzle.config.ts', 'drizzle.config.js', '.eslintrc.js', '.eslintrc.json',
+    'tsconfig.json', 'jest.config.js', 'vitest.config.ts',
+  ];
+  for (const cf of configFiles) {
+    const p = join(dir, cf);
+    if (existsSync(p)) {
+      try {
+        const code = readFileSync(p, 'utf8');
+        fileContents.set(p, code);
+        allCode += code + '\n';
+      } catch { /* skip */ }
+    }
+  }
+
+  // Construir grafo de imports: objetivos de import locales normalizados
+  const allImportTargets = new Set();
+  for (const [, code] of fileContents) {
+    const importRegex = /(?:from\s+|require\s*\(\s*)['"]([^'"]+)['"]/g;
+    let m;
+    while ((m = importRegex.exec(code)) !== null) {
+      const target = m[1];
+      if (target.startsWith('.') || target.startsWith('@/') || target.startsWith('~/')) {
+        const clean = target.replace(/^(?:\.\/|@\/|~\/)/, '').replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '');
+        allImportTargets.add(clean);
+        allImportTargets.add(clean.replace(/\/index$/, ''));
+      }
+    }
+  }
+
+  function isFileReachable(filePath) {
+    const rel = relative(dir, filePath).replace(/\\/g, '/');
+    const noExt = rel.replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '');
+    const noIndex = noExt.replace(/\/index$/, '');
+    const basename = filePath.split(/[/\\]/).pop();
+    if (['page.tsx', 'page.ts', 'page.jsx', 'layout.tsx', 'layout.ts',
+      'main.tsx', 'main.ts', 'App.tsx', 'App.ts', 'index.tsx', 'index.ts',
+      'index.js', 'main.js'].includes(basename)) return true;
+    if (rel.includes('/routes/') || rel.includes('/api/') || rel.includes('/pages/')) return true;
+    if (rel.includes('config')) return true;
+    for (const target of allImportTargets) {
+      if (target === noExt || target === noIndex ||
+        target === `src/${noExt}` || target === `src/${noIndex}` ||
+        noExt.endsWith(`/${target}`) || noIndex.endsWith(`/${target}`)) return true;
+    }
+    return false;
+  }
+
+  function findDepImportFiles(dep) {
+    const aliases = IMPORT_ALIASES[dep] || [dep];
+    const files = [];
+    for (const [filePath, code] of fileContents) {
+      for (const alias of aliases) {
+        if (code.includes(`'${alias}'`) || code.includes(`"${alias}"`) ||
+          code.includes(`'${alias}/`) || code.includes(`"${alias}/`)) {
+          files.push(filePath);
+          break;
+        }
+      }
+      if (dep.startsWith('@') && !files.includes(filePath)) {
+        if (code.includes(`'${dep}'`) || code.includes(`"${dep}"`) ||
+          code.includes(`'${dep}/`) || code.includes(`"${dep}/`)) {
+          files.push(filePath);
+        }
+      }
+    }
+    return files;
+  }
+
+  const unused = [];
+
+  function isUsed(dep) {
+    if (IMPLICIT_DEPS.has(dep)) return true;
+    if (dep.startsWith('@types/')) return true;
+    const aliases = IMPORT_ALIASES[dep] || [dep];
+    for (const alias of aliases) {
+      if (allCode.includes(`'${alias}'`) || allCode.includes(`"${alias}"`)) return true;
+      if (allCode.includes(`'${alias}/`) || allCode.includes(`"${alias}/`)) return true;
+      if (allCode.includes(`require('${alias}')`) || allCode.includes(`require("${alias}")`)) return true;
+    }
+    if (dep.startsWith('@')) {
+      if (allCode.includes(`'${dep}'`) || allCode.includes(`"${dep}"`)) return true;
+      if (allCode.includes(`'${dep}/`) || allCode.includes(`"${dep}/`)) return true;
+    }
+    return false;
+  }
+
+  function isDeadCode(dep) {
+    const importFiles = findDepImportFiles(dep);
+    if (importFiles.length === 0) return true;
+    return importFiles.every(f => !isFileReachable(f));
+  }
+
+  for (const dep of prodDeps) {
+    if (!isUsed(dep)) {
+      unused.push({ name: dep, type: 'production', severity: 'high', message: `"${dep}" está en dependencies pero no se importa en ningún lugar — eliminar para reducir el tamaño de instalación` });
+    } else if (isDeadCode(dep)) {
+      unused.push({ name: dep, type: 'production', severity: 'medium', message: `"${dep}" solo se importa en archivos no alcanzables — eliminar si esos componentes no se necesitan` });
+    }
+  }
+
+  for (const dep of devDeps) {
+    if (!isUsed(dep)) {
+      unused.push({ name: dep, type: 'devDependency', severity: 'low', message: `"${dep}" está en devDependencies pero no se referencia — puede eliminarse` });
+    }
+  }
+
+  return { unused, total_deps: prodDeps.length, total_dev_deps: devDeps.length };
+}
+
+/**
+ * Detecta dependencias posiblemente desactualizadas.
+ * @param {string} dir
+ * @returns {{ outdated: object[] }}
+ */
+function detectOutdated(dir) {
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) return { outdated: [] };
+
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  } catch {
+    return { outdated: [] };
+  }
+
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const findings = [];
+
+  for (const [name, version] of Object.entries(allDeps)) {
+    if (typeof version !== 'string') continue;
+    const v = version.trim();
+    if (v.startsWith('file:') || v.startsWith('link:') || v.startsWith('workspace:') || v === '*' || v === 'latest') continue;
+
+    // Versión anclada exacta (sin ^ ni ~)
+    if (/^\d/.test(v)) {
+      findings.push({
+        name,
+        version: v,
+        severity: 'low',
+        issue: 'anclada',
+        message: `"${name}@${v}" está anclado a versión exacta — usar ^${v} para recibir actualizaciones de parches`,
+      });
+    }
+
+    // Versiones mayores muy antiguas de paquetes conocidos
+    const majorMatch = v.match(/\d+/);
+    if (majorMatch) {
+      const major = parseInt(majorMatch[0], 10);
+      const knownOld = {
+        'react': 18, 'next': 14, 'vue': 3, 'express': 4, 'hono': 4,
+        'typescript': 5, 'vite': 5, 'tailwindcss': 3, 'eslint': 9,
+        'drizzle-orm': 0, 'prisma': 5, 'zod': 3,
+      };
+      if (knownOld[name] !== undefined && major < knownOld[name] - 1) {
+        findings.push({
+          name,
+          version: v,
+          severity: 'medium',
+          issue: 'mayor_desactualizado',
+          message: `"${name}@${v}" tiene ${knownOld[name] - major}+ versiones mayores de retraso — considerar actualización`,
+        });
+      }
+    }
+  }
+
+  return { outdated: findings };
+}
+
+function main() {
+  const dir = process.argv[2];
+  if (!dir) {
+    outputError('Uso: node dep-doctor.js <directorio-proyecto>');
+    process.exit(0);
+  }
+
+  if (!existsSync(dir)) {
+    outputError(`Ruta no encontrada: ${dir}`);
+    process.exit(0);
+  }
+
+  const unusedResult = detectUnusedDeps(dir);
+  const outdatedResult = detectOutdated(dir);
+
+  outputJSON({
+    success: true,
+    packages_scanned: 1,
+    total_production_deps: unusedResult.total_deps || 0,
+    total_dev_deps: unusedResult.total_dev_deps || 0,
+    unused_count: unusedResult.unused.length,
+    outdated_count: outdatedResult.outdated.length,
+    total_findings: unusedResult.unused.length + outdatedResult.outdated.length,
+    unused: unusedResult.unused,
+    outdated: outdatedResult.outdated,
+  });
+}
+
+main();
+
+module.exports = { detectUnusedDeps, detectOutdated, findCodeFiles, IMPLICIT_DEPS };
+
+/**
+ * @complemento Skill("dependencias-auditoria")
+ *
+ * dep-doctor.js realiza **análisis estático** de dependencias:
+ *   - Detecta dependencias declaradas pero nunca importadas en el código fuente.
+ *   - Detecta versiones ancladas sin `^`/`~` y versiones mayores muy desactualizadas.
+ *   - Sin ejecución de shell, sin red. Seguro para usar en cualquier entorno.
+ *   - Rápido (solo lectura de archivos locales).
+ *
+ * Skill("dependencias-auditoria") realiza **auditoría de seguridad profunda**:
+ *   - Consulta bases de datos CVE reales (pip-audit, npm audit, trivy, grype).
+ *   - Detecta licencias incompatibles (pip-licenses, license-checker).
+ *   - Identifica dependencias abandonadas con fecha de último commit.
+ *   - Requiere: red (acceso a advisories), shell (pip-audit, npm, trivy instalados).
+ *   - Más lento pero definitivo en vulnerabilidades conocidas.
+ *
+ * Flujo recomendado:
+ *   1. Ejecutar `dep-doctor.js` primero (rápido, sin dependencias externas).
+ *      → Eliminar dependencias no usadas reduce la superficie de ataque.
+ *   2. Luego invocar `Skill("dependencias-auditoria")` para CVEs y licencias.
+ *      → Asegura que las dependencias restantes no tienen vulnerabilidades conocidas.
+ */