vanilla-builder 0.0.0-stage → 0.2.0

package/src/compress.js

@@ -0,0 +1,44 @@
+// gzip y brotli asíncronos (en el pool de hilos de libuv) y calculados una sola vez por contenido:
+// el informe de tamaños y los archivos .gz/.br precomprimidos comparten el mismo resultado.
+import zlib from 'node:zlib';
+import { promisify } from 'node:util';
+
+const gzip = promisify(zlib.gzip);
+const brotli = promisify(zlib.brotliCompress);
+const cache = new WeakMap();
+
+function entry(buf) {
+  let e = cache.get(buf);
+  if (!e) cache.set(buf, (e = {}));
+  return e;
+}
+
+export function gzipOf(buf) {
+  const e = entry(buf);
+  return (e.gzip ??= gzip(buf, { level: 9 }));
+}
+
+export function brotliOf(buf) {
+  const e = entry(buf);
+  return (e.brotli ??= brotli(buf, {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: 11,
+      [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: buf.length,
+    },
+  }));
+}
+
+/** Ejecuta fn sobre cada elemento con como mucho `limit` tareas a la vez; conserva el orden del resultado. */
+export async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  const lane = async () => {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await fn(items[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, lane));
+  return out;
+}

package/src/config.js

@@ -0,0 +1,197 @@
+// Carga, combina y valida la configuración (builder.config.json / .mjs + opciones de la CLI).
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { BuildError } from './util.js';
+
+export const CONFIG_FILES = ['builder.config.json', 'builder.config.mjs', 'builder.config.js'];
+
+export const DEFAULTS = {
+  root: '.',
+  outDir: 'dist',
+  entries: 'auto',
+  include: [],
+  ignore: [],
+  defaultIgnore: true,
+  unreferenced: 'process',
+  base: '/',
+  hash: false,
+  sourcemap: false,
+  clean: true,
+  verify: true,
+  sri: 'auto',
+  html: { minify: true, removeComments: true, collapseWhitespace: 'auto' },
+  css: { minify: true, bundle: true, target: 'esnext' },
+  js: {
+    minify: true,
+    bundle: true,
+    target: 'auto',
+    mergeClassic: 'auto',
+    keepNames: false,
+    drop: [],
+    legalComments: 'eof',
+    define: {},
+    chunkDir: 'assets',
+    minifier: 'esbuild',
+  },
+  json: { minify: true },
+  obfuscate: false,
+  // Librerías de terceros: se detectan solas y no se ofuscan salvo que se pida.
+  dependencies: { detect: true, obfuscate: false, include: [], exclude: [] },
+  compress: false,
+  // Caché persistente de las transformaciones lentas (ofuscación, terser) entre compilaciones.
+  cache: true,
+  // Hilos para ofuscar/comprimir en paralelo: "auto" (núcleos - 1, máx. 8), un número, o 0 (sin hilos).
+  workers: 'auto',
+};
+
+const NESTED = ['html', 'css', 'js', 'json', 'dependencies'];
+const ENUMS = {
+  unreferenced: ['process', 'copy', 'skip'],
+  sri: ['auto', true, false],
+  sourcemap: [false, true, 'hidden', 'inline'],
+  'js.mergeClassic': ['auto', true, false],
+  'js.legalComments': ['none', 'inline', 'eof'],
+  'html.collapseWhitespace': ['auto', true, false],
+  'js.minifier': ['esbuild', 'terser'],
+  compress: [false, true, 'gzip', 'brotli'],
+};
+const OBF_PRESETS = ['low', 'medium', 'high', 'max'];
+
+function levenshtein(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++)
+    for (let j = 1; j <= b.length; j++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return d[a.length][b.length];
+}
+
+function suggest(key, options) {
+  const best = options.map((o) => [o, levenshtein(key, o)]).sort((x, y) => x[1] - y[1])[0];
+  return best && best[1] <= 3 ? ` ¿Quisiste decir "${best[0]}"?` : '';
+}
+
+function checkKeys(obj, defaults, prefix, errors) {
+  for (const key of Object.keys(obj)) {
+    if (key === '$schema') continue;
+    if (!(key in defaults)) errors.push(`Opción desconocida "${prefix}${key}".${suggest(key, Object.keys(defaults))}`);
+  }
+}
+
+const asList = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+export function normalizeConfig(raw, errors = []) {
+  const user = raw ?? {};
+  if (typeof user !== 'object' || Array.isArray(user)) throw new BuildError('La configuración debe ser un objeto JSON.');
+  checkKeys(user, DEFAULTS, '', errors);
+  const cfg = { ...DEFAULTS, ...user };
+  for (const k of NESTED) {
+    const v = user[k];
+    if (v === false) cfg[k] = k === 'dependencies' ? { ...DEFAULTS[k], detect: false } : { ...DEFAULTS[k], minify: false };
+    else if (v === true || v == null) cfg[k] = { ...DEFAULTS[k] };
+    else if (typeof v === 'object') {
+      checkKeys(v, DEFAULTS[k], `${k}.`, errors);
+      cfg[k] = { ...DEFAULTS[k], ...v };
+    } else errors.push(`"${k}" debe ser un objeto o true/false.`);
+  }
+  for (const k of ['include', 'ignore']) {
+    cfg[k] = asList(cfg[k]);
+    if (cfg[k].some((x) => typeof x !== 'string')) errors.push(`"${k}" debe ser una lista de rutas o patrones (texto).`);
+  }
+  for (const k of ['include', 'exclude']) {
+    cfg.dependencies[k] = asList(cfg.dependencies[k]);
+    if (cfg.dependencies[k].some((x) => typeof x !== 'string')) errors.push(`"dependencies.${k}" debe ser una lista de rutas o patrones (texto).`);
+  }
+  for (const k of ['detect', 'obfuscate']) if (typeof cfg.dependencies[k] !== 'boolean') errors.push(`"dependencies.${k}" debe ser true o false.`);
+  if (cfg.entries !== 'auto') {
+    cfg.entries = asList(cfg.entries);
+    if (!cfg.entries.length || cfg.entries.some((x) => typeof x !== 'string'))
+      errors.push('"entries" debe ser "auto" o una lista de archivos/patrones.');
+  }
+  for (const [key, allowed] of Object.entries(ENUMS)) {
+    const [a, b] = key.split('.');
+    const value = b ? cfg[a][b] : cfg[a];
+    if (!allowed.includes(value)) errors.push(`"${key}" debe ser uno de: ${allowed.map((x) => JSON.stringify(x)).join(', ')}.`);
+  }
+  if (typeof cfg.outDir !== 'string' || !cfg.outDir.trim()) errors.push('"outDir" debe ser una ruta.');
+  if (typeof cfg.base !== 'string' || !cfg.base.startsWith('/')) errors.push('"base" debe empezar con "/" (ej. "/" o "/mi-sitio/").');
+  else if (!cfg.base.endsWith('/')) cfg.base += '/';
+  if (typeof cfg.hash !== 'boolean') errors.push('"hash" debe ser true o false.');
+  if (typeof cfg.cache !== 'boolean') errors.push('"cache" debe ser true o false.');
+  if (!(cfg.workers === 'auto' || (Number.isInteger(cfg.workers) && cfg.workers >= 0 && cfg.workers <= 64)))
+    errors.push('"workers" debe ser "auto" o un número entre 0 y 64.');
+  cfg.js.drop = asList(cfg.js.drop);
+  if (cfg.js.drop.some((d) => !['console', 'debugger'].includes(d))) errors.push('"js.drop" solo admite "console" y "debugger".');
+  if (typeof cfg.js.chunkDir !== 'string' || /(^|\/)\.\.(\/|$)|^\//.test(cfg.js.chunkDir))
+    errors.push('"js.chunkDir" debe ser una carpeta relativa.');
+  for (const k of ['css', 'js']) {
+    const t = cfg[k].target;
+    if (!(typeof t === 'string' || (Array.isArray(t) && t.every((x) => typeof x === 'string'))))
+      errors.push(`"${k}.target" debe ser texto o lista (ej. "es2020" o ["chrome90","safari15"]).`);
+  }
+  const o = cfg.obfuscate;
+  if (o === true) cfg.obfuscate = 'medium';
+  else if (!(o === false || OBF_PRESETS.includes(o) || (o && typeof o === 'object' && !Array.isArray(o))))
+    errors.push(`"obfuscate" debe ser false, true, ${OBF_PRESETS.map((p) => `"${p}"`).join(', ')} o un objeto de opciones de javascript-obfuscator.`);
+  return cfg;
+}
+
+async function readConfigFile(file) {
+  if (file.endsWith('.json')) {
+    const text = fs.readFileSync(file, 'utf8').replace(/^/, '');
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new BuildError(`No pude leer ${path.basename(file)}: JSON inválido (${err.message}).`);
+    }
+  }
+  const mod = await import(`${pathToFileURL(file).href}?t=${fs.statSync(file).mtimeMs}`);
+  return typeof mod.default === 'function' ? await mod.default() : mod.default;
+}
+
+export function findConfigFile(dir) {
+  for (const name of CONFIG_FILES) {
+    const file = path.join(dir, name);
+    if (fs.existsSync(file)) return file;
+  }
+  return null;
+}
+
+/**
+ * Resuelve la configuración final.
+ * @param {{dir?: string, config?: string, overrides?: object, cwd?: string}} opts
+ */
+export async function loadConfig({ dir = '.', config, overrides = {}, cwd = process.cwd() } = {}) {
+  const projectDir = path.resolve(cwd, dir);
+  if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) throw new BuildError(`La carpeta del proyecto no existe: ${projectDir}`);
+  const configFile = config ? path.resolve(cwd, config) : findConfigFile(projectDir);
+  if (config && !fs.existsSync(configFile)) throw new BuildError(`No existe el archivo de configuración: ${configFile}`);
+  const fileCfg = configFile ? await readConfigFile(configFile) : {};
+  const merged = mergeOverrides(fileCfg ?? {}, overrides);
+  const errors = [];
+  const cfg = normalizeConfig(merged, errors);
+  if (errors.length) throw new BuildError('La configuración tiene errores:', errors);
+  const baseDir = configFile ? path.dirname(configFile) : projectDir;
+  cfg.root = path.resolve(baseDir, cfg.root);
+  if (!fs.existsSync(cfg.root)) throw new BuildError(`"root" no existe: ${cfg.root}`);
+  // esbuild resuelve los enlaces simbólicos de lo que importa; si la raíz no es la ruta real, el mismo
+  // módulo aparece con dos rutas (pasa en macOS con /tmp → /private/tmp, o al abrir el proyecto por un enlace).
+  cfg.root = fs.realpathSync(cfg.root);
+  cfg.outDir = path.resolve(cfg.root, cfg.outDir);
+  cfg.configFile = configFile;
+  return cfg;
+}
+
+function mergeOverrides(base, over) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    if (v === undefined) continue;
+    if (NESTED.includes(k) && v && typeof v === 'object' && !Array.isArray(v)) {
+      const prev = base[k];
+      out[k] = { ...(prev && typeof prev === 'object' ? prev : prev === false ? { minify: false } : {}), ...v };
+    } else if (['include', 'ignore'].includes(k)) {
+      out[k] = [...asList(base[k]), ...asList(v)];
+    } else out[k] = v;
+  }
+  return out;
+}

package/src/css.js

@@ -0,0 +1,166 @@
+// CSS: empaqueta @import, reescribe url() según la ubicación final y minifica con esbuild.
+import path from 'node:path';
+import * as esbuild from 'esbuild';
+import { relFrom, toPosix } from './util.js';
+
+/**
+ * image-set("a.png" 1x) no lo reescribe esbuild al mover el CSS de carpeta.
+ * Se convierte a la forma equivalente image-set(url("a.png") 1x), que sí reescribe.
+ */
+export function imageSetStringsToUrl(css) {
+  const re = /(?:-webkit-)?image-set\(/gi;
+  let out = '';
+  let last = 0;
+  let m;
+  while ((m = re.exec(css))) {
+    let i = m.index + m[0].length;
+    let depth = 1;
+    let chunk = '';
+    let segStart = i;
+    const flush = (end) => {
+      chunk += css.slice(segStart, end);
+    };
+    while (i < css.length && depth > 0) {
+      const c = css[i];
+      if (c === '"' || c === "'") {
+        let j = i + 1;
+        while (j < css.length && css[j] !== c) j += css[j] === '\\' ? 2 : 1;
+        if (depth === 1) {
+          flush(i);
+          chunk += `url(${css.slice(i, j + 1)})`;
+          segStart = j + 1;
+        }
+        i = j + 1;
+        continue;
+      }
+      if (c === '(') depth++;
+      else if (c === ')') depth--;
+      i++;
+    }
+    flush(i);
+    out += css.slice(last, m.index + m[0].length) + chunk;
+    last = i;
+    re.lastIndex = i;
+  }
+  return last === 0 ? css : out + css.slice(last);
+}
+
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+
+function cssPlugin(ctx, { outRel, consumed, label }) {
+  return {
+    name: 'vanilla-builder-css',
+    setup(b) {
+      b.onResolve({ filter: /.*/ }, (args) => {
+        if (args.kind === 'entry-point') return undefined;
+        const spec = args.path;
+        if (EXTERNAL.test(spec) || /\{\{|\$\{/.test(spec)) return { path: spec, external: true };
+        const isStdin = !args.importer || args.importer === '<stdin>';
+        const fromRel = isStdin ? label : (relFrom(ctx.root, args.importer) ?? label);
+        const baseDir = args.resolveDir ? (relFrom(ctx.root, args.resolveDir) ?? '') : path.posix.dirname(fromRel);
+        const r = ctx.resolve(spec, baseDir);
+        if (r.status !== 'ok') {
+          ctx.reportBroken(fromRel, spec, r);
+          return { path: spec, external: true };
+        }
+        if (args.kind === 'import-rule') return { path: ctx.abs(r.rel) };
+        // url(): el archivo se copia a su ruta final y la URL se recalcula desde el CSS de salida.
+        ctx.registerAsset(r.rel, fromRel);
+        const target = ctx.assetOut(r.rel);
+        let url = path.posix.relative(path.posix.dirname(outRel), target);
+        if (!url) url = path.posix.basename(target);
+        url = url
+          .split('/')
+          .map((s) => (s === '..' ? s : encodeURIComponent(s)))
+          .join('/');
+        return { path: url + r.info.suffix, external: true };
+      });
+      b.onLoad({ filter: /\.css$/i }, (args) => {
+        const rel = relFrom(ctx.root, args.path);
+        if (rel == null) return undefined;
+        consumed.add(rel);
+        const { text } = ctx.readText(rel, { kind: 'css' });
+        return { contents: imageSetStringsToUrl(text), loader: 'css' };
+      });
+    },
+  };
+}
+
+/**
+ * Compila una hoja de estilos.
+ * @param {object} ctx contexto del builder
+ * @param {{entry?: string, inline?: {code: string, baseDir: string, label: string}, outRel: string}} job
+ */
+export async function buildCss(ctx, job) {
+  const cfg = ctx.cfg;
+  const consumed = new Set();
+  const common = {
+    bundle: cfg.css.bundle,
+    write: false,
+    minify: cfg.css.minify,
+    target: cfg.css.target,
+    logLevel: 'silent',
+    absWorkingDir: ctx.root,
+    outfile: path.join(ctx.root, '__vb_out__', job.outRel),
+    plugins: [cssPlugin(ctx, { outRel: job.outRel, consumed, label: job.entry ?? job.inline?.label })],
+    legalComments: cfg.css.minify ? cfg.js.legalComments : 'inline',
+    charset: 'ascii',
+    sourcemap: job.inline
+      ? false
+      : cfg.sourcemap === 'hidden'
+        ? 'external'
+        : cfg.sourcemap === 'inline'
+          ? 'inline'
+          : cfg.sourcemap
+            ? 'linked'
+            : false,
+  };
+  let result;
+  try {
+    result = job.inline
+      ? await esbuild.build({
+          ...common,
+          stdin: {
+            contents: imageSetStringsToUrl(job.inline.code),
+            resolveDir: ctx.abs(job.inline.baseDir),
+            loader: 'css',
+            sourcefile: job.inline.label,
+          },
+        })
+      : await esbuild.build({ ...common, entryPoints: [ctx.abs(job.entry)] });
+  } catch (err) {
+    return { error: esbuildErrorText(err, ctx.root) };
+  }
+  for (const w of result.warnings) ctx.warn(`CSS: ${formatMessage(w, ctx.root)}`, job.entry ?? job.inline?.label);
+  let code = '';
+  let map = null;
+  for (const f of result.outputFiles) {
+    if (f.path.endsWith('.map')) map = f.text;
+    else code = f.text;
+  }
+  if (job.inline) code = code.replace(/\n$/, '');
+  return { code, map, inputs: [...consumed] };
+}
+
+/** Minifica el contenido de un atributo style="" sin tocar sus URLs. */
+export async function minifyStyleAttr(value, target) {
+  if (!value.trim()) return value;
+  try {
+    const r = await esbuild.transform(`*{${value}}`, { loader: 'css', minify: true, target, charset: 'ascii', logLevel: 'silent' });
+    const m = /^\*\{([\s\S]*)\}\s*$/.exec(r.code);
+    if (!m || r.warnings.length) return value;
+    return m[1];
+  } catch {
+    return value;
+  }
+}
+
+export function formatMessage(m, root) {
+  const loc = m.location ? `${toPosix(path.relative(root, path.resolve(root, m.location.file)))}:${m.location.line}:${m.location.column + 1} ` : '';
+  return `${loc}${m.text}`;
+}
+
+export function esbuildErrorText(err, root) {
+  if (err?.errors?.length) return err.errors.map((e) => formatMessage(e, root)).join('\n');
+  return err?.message ?? String(err);
+}

package/src/deps.js

@@ -0,0 +1,199 @@
+// Detección de librerías de terceros (jQuery, Bootstrap, paquetes de npm...).
+// No se ofuscan: no aporta nada, las hace más lentas y puede romper su licencia.
+
+const DEP_DIRS = /(^|\/)(node_modules|bower_components|jspm_packages|web_modules|vendors?|third[-_]?party|external|externals)\//i;
+const MIN_NAME = /[.-](min|prod|production)\.m?js$|\.umd(\.min)?\.m?js$/i;
+// Nombres de librerías conocidas, con o sin versión: jquery-3.7.1.js, bootstrap.bundle.js, chart.umd.js...
+const KNOWN = new RegExp(
+  `^(${[
+    'jquery(?:[.-]ui)?',
+    'zepto',
+    'bootstrap',
+    'popper',
+    '@popperjs',
+    'lodash',
+    'underscore',
+    'moment(?:-with-locales)?',
+    'dayjs',
+    'luxon',
+    'd3',
+    'three',
+    'vue',
+    'react',
+    'react-dom',
+    'preact',
+    'angular',
+    'alpine',
+    'alpinejs',
+    'htmx',
+    'axios',
+    'gsap',
+    'swiper',
+    'leaflet',
+    'mapbox-gl',
+    'sweetalert2?',
+    'toastr',
+    'select2',
+    'datatables',
+    'jquery\\.dataTables',
+    'fullcalendar',
+    'prism',
+    'marked',
+    'dompurify',
+    'handlebars',
+    'mustache',
+    'backbone',
+    'knockout',
+    'socket\\.io',
+    'pdf(?:\\.worker)?',
+    'tinymce',
+    'ckeditor',
+    'quill',
+    'lottie',
+    'fontawesome',
+    'modernizr',
+    'core-js',
+    'regenerator-runtime',
+    'tailwind(?:css)?',
+    'bulma',
+    'uikit',
+    'materialize',
+    'fancybox',
+    'slick',
+    'owl\\.carousel',
+    'isotope',
+    'masonry',
+    'imagesloaded',
+    'inputmask',
+    'flatpickr',
+    'pikaday',
+    'nouislider',
+    'requirejs',
+    'es-module-shims',
+    'workbox-[\\w-]+',
+    'firebase(?:-[\\w-]+)?',
+    'plyr',
+    'howler',
+    'pixi',
+    'phaser',
+    'konva',
+    'echarts',
+    'apexcharts',
+    'highcharts',
+    'plotly',
+    'mathjax',
+    'katex',
+    'mermaid',
+    'codemirror',
+    'monaco',
+    'xlsx',
+    'jszip',
+    'filesaver',
+    'jspdf',
+    'html2canvas',
+    'qrcode',
+    'crypto-js',
+    'immutable',
+    'rxjs',
+    'mobx',
+    'redux',
+    'i18next',
+    'intl-tel-input',
+    'libphonenumber',
+    'cropper',
+    'dropzone',
+    'tippy',
+    'micromodal',
+    'glightbox',
+    'splide',
+    'flickity',
+    'scrollreveal',
+    'locomotive-scroll',
+    'lenis',
+    'barba',
+    'swup',
+  ].join('|')})(?:[.@_-][\\w.-]*)?\\.m?js$`,
+  'i',
+);
+
+// Marca escrita por el usuario en el primer comentario del archivo.
+const PRAGMA = /@builder-(dependency|dependencia|own|propio)\b/i;
+// Envoltorio UMD/AMD/CommonJS: el formato con el que se publican las librerías para usarlas con <script>.
+const UMD = [
+  /typeof\s+define\s*===?\s*["']function["']\s*&&\s*define\.amd/,
+  /typeof\s+exports\s*===?\s*["']object["']\s*&&\s*typeof\s+module\s*!==?\s*["']undefined["']/,
+  /typeof\s+module\s*===?\s*["']object["']\s*&&\s*(?:typeof\s+)?module\.exports/,
+];
+
+/**
+ * Marca explícita en el propio archivo: un comentario inicial con @builder-dependency o @builder-own.
+ * @returns {'dependency'|'own'|null}
+ */
+export function dependencyPragma(code = '') {
+  const head = code.slice(0, 2000);
+  const comment = /^\s*(?:\/\*[\s\S]*?\*\/|\/\/[^\n]*)/.exec(head)?.[0] ?? '';
+  const m = PRAGMA.exec(comment);
+  if (!m) return null;
+  return /^(dependency|dependencia)$/i.test(m[1]) ? 'dependency' : 'own';
+}
+
+/** Nombre "de paquete" de un archivo: jquery-3.7.1.min.js → jquery, chart.umd.js → chart. */
+export function packageLikeName(fileName) {
+  return fileName
+    .toLowerCase()
+    .replace(/\.(m?js|cjs)$/, '')
+    .replace(/[.-](min|prod|production|umd|esm|es|module|cjs|iife|bundle|browser|global|dist)\b/g, '')
+    .replace(/[@.-]v?\d+(\.\d+){1,3}(-[\w.]+)?$/, '')
+    .replace(/[.-](min|prod|production|umd|esm|es|module|cjs|iife|bundle|browser|global|dist)$/g, '');
+}
+
+/**
+ * Nombres de los paquetes declarados en el package.json del proyecto, normalizados
+ * (chart.js → chart, @popperjs/core → popperjs), para reconocer copias a mano en js/.
+ * @returns {Map<string, string>} nombre normalizado → nombre en package.json
+ */
+export function packageNames(pkg) {
+  const names = new Map();
+  // devDependencies no: suelen ser herramientas (eslint, prettier…) y darían falsos positivos.
+  for (const field of ['dependencies', 'peerDependencies', 'optionalDependencies']) {
+    for (const full of Object.keys(pkg?.[field] ?? {})) {
+      const lower = full.toLowerCase();
+      const [scope, bare] = lower.startsWith('@') ? lower.slice(1).split('/') : [null, lower];
+      for (const n of [bare, scope]) {
+        if (!n || n.length < 3) continue;
+        for (const key of [n, n.replace(/\.js$/, '')]) if (!names.has(key)) names.set(key, full);
+      }
+    }
+  }
+  // Nombres demasiado genéricos para concluir nada solo por el nombre del archivo.
+  for (const generic of ['core', 'utils', 'util', 'app', 'main', 'index', 'common', 'types', 'lib', 'api']) names.delete(generic);
+  return names;
+}
+
+/**
+ * ¿Parece una librería de terceros? Devuelve el motivo o null.
+ * @param {string} rel ruta relativa (POSIX)
+ * @param {string} code contenido
+ * @param {{packages?: Map<string, string>}} [hints] nombres de package.json del proyecto
+ */
+export function detectDependency(rel, code = '', hints = {}) {
+  if (DEP_DIRS.test(rel)) return `está en ${rel.match(DEP_DIRS)[2]}/`;
+  const name = rel.split('/').pop();
+  if (KNOWN.test(name)) return 'nombre de librería conocida';
+  if (MIN_NAME.test(name)) return 'versión ya compilada (.min.js / .umd.js)';
+  const pkgName = packageLikeName(name);
+  if (hints.packages?.has(pkgName)) return `se llama como el paquete "${hints.packages.get(pkgName)}" de tu package.json`;
+  const edges = code.length > 8000 ? code.slice(0, 5000) + code.slice(-3000) : code;
+  if (UMD.some((re) => re.test(edges))) return 'envoltorio UMD/AMD (formato de librería publicada)';
+  // Cabecera de librería publicada: /*! o @license con número de versión (jQuery v3.7.1, Bootstrap v5.3.0...).
+  // Una cabecera propia sin versión ("/*! Mi app (c) 2026 */") no basta.
+  const header = /^\s*\/\*[\s\S]*?\*\//.exec(code.slice(0, 3000))?.[0] ?? '';
+  if ((/^\s*\/\*!/.test(header) || /@(license|preserve)\b/.test(header)) && /\bv?\d+\.\d+(\.\d+)?\b/.test(header))
+    return 'cabecera de licencia con versión';
+  // Código ya minificado: pocas líneas muy largas.
+  if (code.length > 4000) {
+    const lines = code.split('\n').length;
+    if (code.length / lines > 500) return 'código ya minificado';
+  }
+  return null;
+}