@saulwade/swl-ses 1.2.1 → 1.3.0

package/scripts/auditar-claudemd.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/auditar-claudemd.js
+ *
+ * Auditor del archivo CLAUDE.md según best practices Anthropic (ADR-0016).
+ *
+ * Verifica:
+ *   - Existencia del archivo (en ./ o en .claude/)
+ *   - Líneas totales (umbral SWL_CLAUDEMD_MAX_LINES, default 200)
+ *   - Bullets/párrafos monolíticos (umbral SWL_CLAUDEMD_MAX_BULLET_CHARS, default 1000)
+ *   - Presencia de secciones canónicas (Stack, Comandos, Code style, Conventions, @references)
+ *   - Uso de @references (al menos 1 si el archivo supera 80 líneas)
+ *   - Placeholders sin reemplazar ([TBD], [TODO], [COMPLETAR])
+ *
+ * Uso:
+ *   node scripts/auditar-claudemd.js [ruta]                # Audita CLAUDE.md (default: ./)
+ *   node scripts/auditar-claudemd.js --json                # Salida JSON
+ *   node scripts/auditar-claudemd.js --strict              # exit 1 si veredicto != OK
+ *
+ * Exit codes:
+ *   0 — OK o WARN (veredicto consultivo)
+ *   1 — ERROR (no existe / placeholders / faltan secciones críticas) o --strict + WARN
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Config ───────────────────────────────────────────────────────────────
+const MAX_LINES = parseInt(process.env.SWL_CLAUDEMD_MAX_LINES, 10) || 200;
+const MAX_BULLET_CHARS =
+  parseInt(process.env.SWL_CLAUDEMD_MAX_BULLET_CHARS, 10) || 1000;
+
+const SECCIONES_CANONICAS = [
+  { nombre: 'Stack', regex: /^##\s+Stack/m },
+  { nombre: 'Comandos', regex: /^##\s+Comandos/m },
+  { nombre: 'Code style', regex: /^##\s+(Code\s+style|Estilo\s+de\s+código)/im },
+  { nombre: 'Conventions', regex: /^##\s+(Conventions|Convenciones)/im },
+];
+
+const PLACEHOLDERS = /\[(TBD|TODO|COMPLETAR|PENDIENTE|XXX|FIXME)\]/g;
+
+// ─── Auditoría ────────────────────────────────────────────────────────────
+
+function ubicarClaudeMd(dir = process.cwd()) {
+  const candidatos = [
+    path.join(dir, 'CLAUDE.md'),
+    path.join(dir, '.claude', 'CLAUDE.md'),
+  ];
+  for (const c of candidatos) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function auditar(rutaClaudeMd) {
+  if (!rutaClaudeMd || !fs.existsSync(rutaClaudeMd)) {
+    return {
+      veredicto: 'ERROR',
+      ruta: rutaClaudeMd,
+      hallazgos: [{
+        severidad: 'ERROR',
+        mensaje: 'CLAUDE.md no existe en el directorio de trabajo',
+        sugerencia: 'Ejecuta `/swl:claudemd init-project` para generarlo',
+      }],
+    };
+  }
+
+  const contenido = fs.readFileSync(rutaClaudeMd, 'utf8');
+  const lineas = contenido.split('\n');
+  const hallazgos = [];
+
+  // 1. Líneas totales
+  if (lineas.length > MAX_LINES) {
+    hallazgos.push({
+      severidad: 'WARN',
+      regla: 'tamano-total',
+      mensaje: `CLAUDE.md tiene ${lineas.length} líneas (umbral: ${MAX_LINES})`,
+      sugerencia: 'Extraer secciones grandes a archivos `@`-referenciados (ej. `@docs/variables-entorno.md`)',
+    });
+  }
+
+  // 2. Bullets/párrafos monolíticos
+  const bulletsMonoliticos = detectarBulletsGigantes(contenido);
+  for (const b of bulletsMonoliticos) {
+    hallazgos.push({
+      severidad: 'WARN',
+      regla: 'bullet-gigante',
+      mensaje: `Bullet/párrafo en línea ${b.linea} tiene ${b.chars} chars (umbral: ${MAX_BULLET_CHARS})`,
+      sugerencia: 'Convertir a tabla, lista jerárquica o extraer a archivo separado',
+      preview: b.preview,
+    });
+  }
+
+  // 3. Secciones canónicas
+  const seccionesAusentes = SECCIONES_CANONICAS.filter(s => !s.regex.test(contenido));
+  if (seccionesAusentes.length > 0) {
+    const nombres = seccionesAusentes.map(s => s.nombre).join(', ');
+    hallazgos.push({
+      severidad: 'WARN',
+      regla: 'secciones-canonicas',
+      mensaje: `Faltan secciones canónicas Anthropic: ${nombres}`,
+      sugerencia: `Agregar las secciones faltantes (ver \`/swl:claudemd refactor\` para template)`,
+    });
+  }
+
+  // 4. @references si el archivo es grande
+  if (lineas.length > 80) {
+    const tieneAtReferences = /@[a-zA-Z][a-zA-Z0-9_\-./]+\.md/.test(contenido);
+    if (!tieneAtReferences) {
+      hallazgos.push({
+        severidad: 'WARN',
+        regla: 'sin-at-references',
+        mensaje: 'Archivo grande (>80 líneas) sin @references a docs externos',
+        sugerencia: 'Usar `@docs/...md` o `@.planning/...md` para enlazar contenido en lugar de duplicarlo',
+      });
+    }
+  }
+
+  // 5. Placeholders sin reemplazar
+  const matches = [...contenido.matchAll(PLACEHOLDERS)];
+  if (matches.length > 0) {
+    hallazgos.push({
+      severidad: 'ERROR',
+      regla: 'placeholders',
+      mensaje: `${matches.length} placeholder(s) sin reemplazar: ${[...new Set(matches.map(m => m[0]))].join(', ')}`,
+      sugerencia: 'Reemplazar todos los placeholders antes de commitear',
+    });
+  }
+
+  // ─── Veredicto ───────────────────────────────────────────────────────────
+  const tieneError = hallazgos.some(h => h.severidad === 'ERROR');
+  const tieneWarn = hallazgos.some(h => h.severidad === 'WARN');
+  const veredicto = tieneError ? 'ERROR' : tieneWarn ? 'WARN' : 'OK';
+
+  return {
+    veredicto,
+    ruta: rutaClaudeMd,
+    metricas: {
+      lineas: lineas.length,
+      bytes: contenido.length,
+      umbral_lineas: MAX_LINES,
+      umbral_bullet_chars: MAX_BULLET_CHARS,
+      secciones_presentes: SECCIONES_CANONICAS.filter(s => s.regex.test(contenido)).map(s => s.nombre),
+      secciones_ausentes: seccionesAusentes.map(s => s.nombre),
+      tiene_at_references: /@[a-zA-Z][a-zA-Z0-9_\-./]+\.md/.test(contenido),
+    },
+    hallazgos,
+  };
+}
+
+/**
+ * Detecta bullets/párrafos cuyo contenido excede MAX_BULLET_CHARS.
+ * Un "bullet" es una línea que empieza con `-` o `*` (ignorando indentación).
+ * Un "párrafo" es bloque de texto contiguo sin línea vacía.
+ */
+function detectarBulletsGigantes(contenido) {
+  const lineas = contenido.split('\n');
+  const gigantes = [];
+  let buffer = '';
+  let lineaInicio = 0;
+  let dentroDeBullet = false;
+  let dentroDeCodeFence = false;
+
+  const flush = () => {
+    if (buffer.length > MAX_BULLET_CHARS) {
+      gigantes.push({
+        linea: lineaInicio + 1,
+        chars: buffer.length,
+        preview: buffer.slice(0, 100) + (buffer.length > 100 ? '…' : ''),
+      });
+    }
+    buffer = '';
+    dentroDeBullet = false;
+  };
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+
+    // Skipear bloques de código (no son bullets)
+    if (/^\s*```/.test(linea)) {
+      flush();
+      dentroDeCodeFence = !dentroDeCodeFence;
+      continue;
+    }
+    if (dentroDeCodeFence) continue;
+
+    // Skipear tablas Markdown (líneas que empiezan con `|`):
+    // las tablas son grandes por naturaleza y no son "bullets monolíticos"
+    if (/^\s*\|/.test(linea)) {
+      flush();
+      continue;
+    }
+
+    // Línea vacía termina el bullet/párrafo actual
+    if (/^\s*$/.test(linea)) {
+      flush();
+      continue;
+    }
+
+    // Header termina el buffer
+    if (/^#/.test(linea)) {
+      flush();
+      continue;
+    }
+
+    // Inicio de nuevo bullet
+    if (/^\s*[-*+]\s/.test(linea)) {
+      flush();
+      lineaInicio = i;
+      buffer = linea;
+      dentroDeBullet = true;
+      continue;
+    }
+
+    // Continuación: si estamos en bullet, acumular; si no, párrafo
+    if (dentroDeBullet) {
+      buffer += '\n' + linea;
+    } else {
+      if (buffer === '') lineaInicio = i;
+      buffer += (buffer ? '\n' : '') + linea;
+    }
+  }
+  flush();
+  return gigantes;
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────
+
+function imprimirReporte(resultado) {
+  const colorVeredicto = {
+    OK: '\x1b[32m',     // verde
+    WARN: '\x1b[33m',   // amarillo
+    ERROR: '\x1b[31m',  // rojo
+  };
+  const reset = '\x1b[0m';
+
+  console.log(`\n${colorVeredicto[resultado.veredicto]}=== AUDITORÍA CLAUDE.md ===${reset}`);
+  console.log(`Veredicto: ${colorVeredicto[resultado.veredicto]}${resultado.veredicto}${reset}`);
+  console.log(`Ruta: ${resultado.ruta || '(no encontrado)'}\n`);
+
+  if (resultado.metricas) {
+    const m = resultado.metricas;
+    console.log(`Métricas:`);
+    console.log(`  - Líneas: ${m.lineas} / ${m.umbral_lineas}`);
+    console.log(`  - Secciones canónicas presentes: ${m.secciones_presentes.length}/4 (${m.secciones_presentes.join(', ') || 'ninguna'})`);
+    if (m.secciones_ausentes.length > 0) {
+      console.log(`  - Secciones ausentes: ${m.secciones_ausentes.join(', ')}`);
+    }
+    console.log(`  - @references: ${m.tiene_at_references ? 'sí' : 'no'}`);
+    console.log('');
+  }
+
+  if (resultado.hallazgos.length === 0) {
+    console.log('Sin hallazgos. CLAUDE.md cumple best practices Anthropic.\n');
+    return;
+  }
+
+  console.log(`Hallazgos (${resultado.hallazgos.length}):\n`);
+  for (const h of resultado.hallazgos) {
+    const color = colorVeredicto[h.severidad] || '';
+    console.log(`  ${color}[${h.severidad}]${reset} ${h.mensaje}`);
+    if (h.sugerencia) console.log(`    → ${h.sugerencia}`);
+    if (h.preview) console.log(`    Preview: ${h.preview}`);
+    console.log('');
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const flagJson = args.includes('--json');
+  const flagStrict = args.includes('--strict');
+  const rutaArg = args.find(a => !a.startsWith('--'));
+
+  const ruta = rutaArg
+    ? path.resolve(rutaArg)
+    : ubicarClaudeMd();
+
+  const resultado = auditar(ruta);
+
+  if (flagJson) {
+    console.log(JSON.stringify(resultado, null, 2));
+  } else {
+    imprimirReporte(resultado);
+  }
+
+  if (resultado.veredicto === 'ERROR') process.exit(1);
+  if (flagStrict && resultado.veredicto === 'WARN') process.exit(1);
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { auditar, ubicarClaudeMd, detectarBulletsGigantes, MAX_LINES, MAX_BULLET_CHARS };

package/scripts/instalador.js

@@ -571,6 +571,10 @@ async function install(opciones) {
         reglas: reglasInstaladas,
         skills: skillsInstalados,
         conteos,
+        // ADR-0016: pasar directorio del proyecto destino para que el
+        // transformador Claude pueda detectar stack/comandos/framework.
+        // Otros transformadores ignoran este campo.
+        dirProyecto: process.cwd(),
       });
 
       if (instrucciones) {

package/scripts/lib/detectar-stack-detallado.js

@@ -0,0 +1,307 @@
+'use strict';
+
+/**
+ * detectar-stack-detallado.js
+ *
+ * Detecta stack del proyecto destino con información rica para generación de
+ * CLAUDE.md (no solo presencia, sino también: framework principal, scripts
+ * disponibles, package manager, deps clave).
+ *
+ * Diferencia con `detectar-stack.js`: ese módulo es para FILTRAR reglas de
+ * lenguaje (presence/absence). Este módulo es para POBLAR el bloque CLAUDE.md
+ * inyectado por el installer con info accionable del proyecto destino.
+ *
+ * Zero-dependencies (solo fs/path nativos). Defensivo: cualquier read failure
+ * devuelve null/undefined, nunca lanza.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Lee package.json del proyecto destino.
+ * @returns {{ name?: string, version?: string, scripts?: object, dependencies?: object, devDependencies?: object } | null}
+ */
+function leerPackageJson(dirProyecto) {
+  return _leerJsonSeguro(path.join(dirProyecto, 'package.json'));
+}
+
+/**
+ * Detecta el package manager Node usado (basado en lockfile).
+ * @returns {'pnpm' | 'yarn' | 'bun' | 'npm' | null}
+ */
+function detectarPackageManagerNode(dirProyecto) {
+  if (fs.existsSync(path.join(dirProyecto, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(dirProyecto, 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(dirProyecto, 'bun.lockb'))) return 'bun';
+  if (fs.existsSync(path.join(dirProyecto, 'package-lock.json'))) return 'npm';
+  if (fs.existsSync(path.join(dirProyecto, 'package.json'))) return 'npm';
+  return null;
+}
+
+/**
+ * Detecta el package manager Python.
+ * @returns {'poetry' | 'uv' | 'pdm' | 'pip' | null}
+ */
+function detectarPackageManagerPython(dirProyecto) {
+  const pyproject = path.join(dirProyecto, 'pyproject.toml');
+  if (fs.existsSync(pyproject)) {
+    const contenido = _leerArchivoSeguro(pyproject) || '';
+    if (contenido.includes('[tool.poetry]')) return 'poetry';
+    if (contenido.includes('[tool.uv]')) return 'uv';
+    if (contenido.includes('[tool.pdm]')) return 'pdm';
+    return 'pip'; // pyproject genérico
+  }
+  if (fs.existsSync(path.join(dirProyecto, 'requirements.txt'))) return 'pip';
+  if (fs.existsSync(path.join(dirProyecto, 'Pipfile'))) return 'pip';
+  return null;
+}
+
+/**
+ * Detecta framework Node a partir de dependencies.
+ * @returns {string | null}
+ */
+function detectarFrameworkNode(packageJson) {
+  if (!packageJson) return null;
+  const deps = { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) };
+
+  if (deps.next) return `Next.js ${_limpiarVersion(deps.next)}`;
+  if (deps['@angular/core']) return `Angular ${_limpiarVersion(deps['@angular/core'])}`;
+  if (deps['@nestjs/core']) return `NestJS ${_limpiarVersion(deps['@nestjs/core'])}`;
+  if (deps.svelte) return `Svelte ${_limpiarVersion(deps.svelte)}`;
+  if (deps.vue) return `Vue ${_limpiarVersion(deps.vue)}`;
+  if (deps.remix || deps['@remix-run/node']) return 'Remix';
+  if (deps.astro) return `Astro ${_limpiarVersion(deps.astro)}`;
+  if (deps.nuxt) return `Nuxt ${_limpiarVersion(deps.nuxt)}`;
+  if (deps.fastify) return `Fastify ${_limpiarVersion(deps.fastify)}`;
+  if (deps.express) return `Express ${_limpiarVersion(deps.express)}`;
+  if (deps.react) return `React ${_limpiarVersion(deps.react)} (sin framework)`;
+
+  return null;
+}
+
+/**
+ * Detecta framework Python leyendo deps en pyproject.toml o requirements.txt.
+ * @returns {string | null}
+ */
+function detectarFrameworkPython(dirProyecto) {
+  const pyproject = _leerArchivoSeguro(path.join(dirProyecto, 'pyproject.toml')) || '';
+  const requirements = _leerArchivoSeguro(path.join(dirProyecto, 'requirements.txt')) || '';
+  const deps = (pyproject + '\n' + requirements).toLowerCase();
+
+  if (deps.includes('fastapi')) return 'FastAPI';
+  if (deps.includes('django')) return 'Django';
+  if (deps.includes('flask')) return 'Flask';
+  if (deps.includes('starlette')) return 'Starlette';
+  if (deps.includes('aiohttp')) return 'aiohttp';
+  return null;
+}
+
+/**
+ * Detecta el ORM/driver de BD principal.
+ * @returns {string | null}
+ */
+function detectarORM(packageJson, dirProyecto) {
+  const depsNode = packageJson
+    ? { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) }
+    : {};
+
+  if (depsNode.prisma || depsNode['@prisma/client']) return 'Prisma';
+  if (depsNode['drizzle-orm']) return 'Drizzle';
+  if (depsNode.typeorm) return 'TypeORM';
+  if (depsNode.sequelize) return 'Sequelize';
+  if (depsNode.mongoose) return 'Mongoose';
+
+  // Python
+  const pyproject = _leerArchivoSeguro(path.join(dirProyecto, 'pyproject.toml')) || '';
+  const requirements = _leerArchivoSeguro(path.join(dirProyecto, 'requirements.txt')) || '';
+  const depsPy = (pyproject + '\n' + requirements).toLowerCase();
+  if (depsPy.includes('sqlalchemy')) return 'SQLAlchemy';
+  if (depsPy.includes('peewee')) return 'Peewee';
+  if (depsPy.includes('tortoise-orm')) return 'Tortoise ORM';
+
+  return null;
+}
+
+/**
+ * Detecta lenguaje principal con confianza (devuelve el más probable).
+ * @returns {{ lenguaje: string, runtime?: string } | null}
+ */
+function detectarLenguajePrincipal(dirProyecto) {
+  // Node.js / TypeScript
+  if (fs.existsSync(path.join(dirProyecto, 'package.json'))) {
+    if (fs.existsSync(path.join(dirProyecto, 'tsconfig.json'))) {
+      return { lenguaje: 'TypeScript', runtime: 'Node.js' };
+    }
+    return { lenguaje: 'JavaScript', runtime: 'Node.js' };
+  }
+  // Python
+  if (
+    fs.existsSync(path.join(dirProyecto, 'pyproject.toml')) ||
+    fs.existsSync(path.join(dirProyecto, 'requirements.txt')) ||
+    fs.existsSync(path.join(dirProyecto, 'setup.py'))
+  ) {
+    return { lenguaje: 'Python' };
+  }
+  // Go
+  if (fs.existsSync(path.join(dirProyecto, 'go.mod'))) return { lenguaje: 'Go' };
+  // Rust
+  if (fs.existsSync(path.join(dirProyecto, 'Cargo.toml'))) return { lenguaje: 'Rust' };
+  // Java / Kotlin
+  if (fs.existsSync(path.join(dirProyecto, 'pom.xml'))) return { lenguaje: 'Java', runtime: 'Maven' };
+  if (
+    fs.existsSync(path.join(dirProyecto, 'build.gradle')) ||
+    fs.existsSync(path.join(dirProyecto, 'build.gradle.kts'))
+  ) {
+    return { lenguaje: 'Java/Kotlin', runtime: 'Gradle' };
+  }
+  // PHP
+  if (fs.existsSync(path.join(dirProyecto, 'composer.json'))) return { lenguaje: 'PHP' };
+  // Swift
+  if (fs.existsSync(path.join(dirProyecto, 'Package.swift'))) return { lenguaje: 'Swift' };
+  // Ruby
+  if (fs.existsSync(path.join(dirProyecto, 'Gemfile'))) return { lenguaje: 'Ruby' };
+  // C# / .NET
+  if (fs.existsSync(path.join(dirProyecto, 'global.json'))) return { lenguaje: 'C#', runtime: '.NET' };
+
+  return null;
+}
+
+/**
+ * Detecta scripts comunes del proyecto (test, dev, build, lint).
+ * Devuelve los scripts npm si existen + comandos típicos del lenguaje.
+ *
+ * @returns {Array<{ comando: string, proposito: string }>}
+ */
+function detectarComandos(dirProyecto) {
+  const comandos = [];
+  const pkg = leerPackageJson(dirProyecto);
+  const pm = detectarPackageManagerNode(dirProyecto);
+
+  if (pkg && pkg.scripts) {
+    const interesantes = ['dev', 'start', 'build', 'test', 'lint', 'typecheck', 'format'];
+    for (const script of interesantes) {
+      if (pkg.scripts[script]) {
+        comandos.push({
+          comando: `${pm || 'npm'} run ${script}`,
+          proposito: _propositoScript(script),
+        });
+      }
+    }
+    // Si tiene "test" como entrypoint puro
+    if (pkg.scripts.test && !comandos.some(c => c.comando.includes('test'))) {
+      comandos.push({ comando: `${pm || 'npm'} test`, proposito: 'Tests' });
+    }
+  }
+
+  // Python
+  const pmPy = detectarPackageManagerPython(dirProyecto);
+  if (pmPy === 'poetry') {
+    comandos.push({ comando: 'poetry install', proposito: 'Instalar dependencias' });
+    comandos.push({ comando: 'poetry run pytest', proposito: 'Tests' });
+  } else if (pmPy === 'uv') {
+    comandos.push({ comando: 'uv sync', proposito: 'Instalar dependencias' });
+    comandos.push({ comando: 'uv run pytest', proposito: 'Tests' });
+  } else if (pmPy === 'pip') {
+    comandos.push({ comando: 'pip install -r requirements.txt', proposito: 'Instalar dependencias' });
+    comandos.push({ comando: 'pytest', proposito: 'Tests' });
+  }
+
+  // Go
+  if (fs.existsSync(path.join(dirProyecto, 'go.mod'))) {
+    comandos.push({ comando: 'go test ./...', proposito: 'Tests' });
+    comandos.push({ comando: 'go build ./...', proposito: 'Build' });
+  }
+
+  // Rust
+  if (fs.existsSync(path.join(dirProyecto, 'Cargo.toml'))) {
+    comandos.push({ comando: 'cargo test', proposito: 'Tests' });
+    comandos.push({ comando: 'cargo build', proposito: 'Build' });
+    comandos.push({ comando: 'cargo clippy', proposito: 'Lint' });
+  }
+
+  return comandos;
+}
+
+/**
+ * Detección integral: devuelve resumen del stack del proyecto destino.
+ *
+ * @returns {{
+ *   lenguajePrincipal: { lenguaje: string, runtime?: string } | null,
+ *   framework: string | null,
+ *   orm: string | null,
+ *   packageManager: string | null,
+ *   comandos: Array<{ comando: string, proposito: string }>,
+ *   detectado: boolean
+ * }}
+ */
+function detectarStackDetallado(dirProyecto) {
+  const lenguajePrincipal = detectarLenguajePrincipal(dirProyecto);
+  const pkg = leerPackageJson(dirProyecto);
+  const framework = detectarFrameworkNode(pkg) || detectarFrameworkPython(dirProyecto);
+  const orm = detectarORM(pkg, dirProyecto);
+  const packageManager =
+    detectarPackageManagerNode(dirProyecto) || detectarPackageManagerPython(dirProyecto);
+  const comandos = detectarComandos(dirProyecto);
+
+  return {
+    lenguajePrincipal,
+    framework,
+    orm,
+    packageManager,
+    comandos,
+    detectado: lenguajePrincipal !== null,
+  };
+}
+
+// ─── Helpers privados ────────────────────────────────────────────────────────
+
+function _leerJsonSeguro(ruta) {
+  try {
+    if (!fs.existsSync(ruta)) return null;
+    return JSON.parse(fs.readFileSync(ruta, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function _leerArchivoSeguro(ruta) {
+  try {
+    if (!fs.existsSync(ruta)) return null;
+    return fs.readFileSync(ruta, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function _limpiarVersion(rango) {
+  // "^15.0.0" → "15", "~3.4.1" → "3"
+  if (typeof rango !== 'string') return '';
+  const m = rango.match(/(\d+)/);
+  return m ? m[1] : '';
+}
+
+function _propositoScript(nombre) {
+  const map = {
+    dev: 'Servidor de desarrollo',
+    start: 'Iniciar app',
+    build: 'Build de producción',
+    test: 'Tests',
+    lint: 'Lint',
+    typecheck: 'Verificar tipos',
+    format: 'Formatear código',
+  };
+  return map[nombre] || nombre;
+}
+
+module.exports = {
+  detectarStackDetallado,
+  detectarLenguajePrincipal,
+  detectarFrameworkNode,
+  detectarFrameworkPython,
+  detectarORM,
+  detectarPackageManagerNode,
+  detectarPackageManagerPython,
+  detectarComandos,
+  leerPackageJson,
+};