vanilla-builder 0.0.0-stage → 0.1.0

package/src/config.js

@@ -0,0 +1,190 @@
+// 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,
+};
+
+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.');
+  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,140 @@
+// 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',
+);
+
+/**
+ * ¿Parece una librería de terceros? Devuelve el motivo o null.
+ * @param {string} rel ruta relativa (POSIX)
+ * @param {string} code contenido
+ */
+export function detectDependency(rel, code = '') {
+  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)';
+  // 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;
+}

package/src/files.js

@@ -0,0 +1,152 @@
+// Recorre el proyecto y decide qué archivos forman parte del sitio.
+import fs from 'node:fs';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { CONFIG_FILES } from './config.js';
+import { relFrom, toPosix, extOf } from './util.js';
+
+/** Archivos de desarrollo que nunca deberían publicarse. Se desactiva con defaultIgnore:false. */
+export const DEFAULT_IGNORE = [
+  '**/node_modules/**',
+  '**/.git/**',
+  '**/.svn/**',
+  '**/.hg/**',
+  '**/.vscode/**',
+  '**/.idea/**',
+  '**/.DS_Store',
+  '**/Thumbs.db',
+  '**/desktop.ini',
+  '**/*.log',
+  'package.json',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'bun.lockb',
+  '.gitignore',
+  '.gitattributes',
+  '.editorconfig',
+  '.npmrc',
+  '.nvmrc',
+  '**/.prettierrc*',
+  '**/.eslintrc*',
+  '**/eslint.config.*',
+  '**/prettier.config.*',
+  'tsconfig.json',
+  'jsconfig.json',
+  '**/*.test.js',
+  '**/*.spec.js',
+  '**/__tests__/**',
+  '**/*.map',
+];
+
+/** Secretos: se excluyen siempre por defecto y se avisa. */
+export const SECRET_PATTERNS = ['**/.env', '**/.env.*', '**/*.pem', '**/*.key', '**/id_rsa*'];
+
+/** "carpeta/" equivale a "carpeta/**"; "./x" a "x". */
+const normalizePattern = (p) => {
+  const s = toPosix(p).replace(/^\.\//, '');
+  return s.endsWith('/') ? `${s}**` : s;
+};
+const matcher = (patterns) => (patterns.length ? picomatch(patterns.map(normalizePattern), { dot: true, nocase: true }) : () => false);
+
+/**
+ * Lista los archivos del proyecto con el motivo de exclusión de cada uno.
+ * @returns {{files: Map<string, {rel:string, abs:string, size:number, ext:string}>, ignored: Array<{rel:string, reason:string}>}}
+ */
+export function scanProject(cfg) {
+  const root = cfg.root;
+  const outRel = relFrom(root, cfg.outDir);
+  const builtIn = [...CONFIG_FILES];
+  if (outRel) builtIn.push(`${outRel}/**`, outRel);
+  if (cfg.configFile) {
+    const rel = relFrom(root, cfg.configFile);
+    if (rel) builtIn.push(rel);
+  }
+  // Carpetas temporales de compilaciones anteriores interrumpidas.
+  builtIn.push('**/.*.builder-tmp-*/**', '**/.*.builder-old-*/**');
+  const isBuiltIn = matcher(builtIn);
+  const isDefault = cfg.defaultIgnore ? matcher(DEFAULT_IGNORE) : () => false;
+  const isSecret = cfg.defaultIgnore ? matcher(SECRET_PATTERNS) : () => false;
+  const isUser = matcher(cfg.ignore);
+  const isIncluded = matcher(cfg.include);
+
+  const files = new Map();
+  const ignored = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      ignored.push({ rel: relFrom(root, dir) || '.', reason: `no se pudo leer (${err.code})` });
+      return;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      const rel = relFrom(root, abs);
+      let isDir = entry.isDirectory();
+      let isFile = entry.isFile();
+      if (entry.isSymbolicLink()) {
+        // Se sigue el enlace a archivos; no a carpetas (evita ciclos).
+        try {
+          const st = fs.statSync(abs);
+          isFile = st.isFile();
+          isDir = false;
+          if (st.isDirectory()) ignored.push({ rel, reason: 'enlace simbólico a carpeta (no se sigue)' });
+        } catch {
+          ignored.push({ rel, reason: 'enlace simbólico roto' });
+          continue;
+        }
+      }
+      if (isBuiltIn(rel) || isBuiltIn(`${rel}/`)) continue;
+      if (isDir) {
+        // Las carpetas excluidas no se recorren, salvo que include apunte dentro.
+        const probe = `${rel}/__probe__`;
+        const byUser = isUser(rel) || isUser(probe);
+        const wanted = cfg.include.some((p) => normalizePattern(p).startsWith(`${rel}/`) || p.startsWith('**'));
+        if ((byUser || isDefault(probe)) && !wanted) {
+          ignored.push({ rel: `${rel}/`, reason: byUser ? 'ignore (configuración)' : 'excluido por defecto' });
+          continue;
+        }
+        walk(abs);
+        continue;
+      }
+      if (!isFile) continue;
+      const forced = isIncluded(rel);
+      let reason = null;
+      if (!forced) {
+        if (isSecret(rel)) reason = 'posible secreto (excluido por seguridad)';
+        else if (isUser(rel)) reason = 'ignore (configuración)';
+        else if (isDefault(rel)) reason = 'excluido por defecto';
+      }
+      if (reason) {
+        ignored.push({ rel, reason });
+        continue;
+      }
+      const size = fs.statSync(abs).size;
+      files.set(rel, { rel, abs, size, ext: extOf(rel), forced });
+    }
+  };
+  walk(root);
+  return { files, ignored };
+}
+
+/** Resuelve patrones (o rutas exactas) contra los archivos del proyecto. */
+export function matchFiles(files, patterns) {
+  const out = [];
+  const missing = [];
+  for (const pattern of patterns) {
+    const norm = toPosix(pattern).replace(/^\.\//, '');
+    if (picomatch.scan(norm).isGlob) {
+      const isMatch = picomatch(norm, { dot: true, nocase: true });
+      const hits = [...files.keys()].filter((rel) => isMatch(rel));
+      if (!hits.length) missing.push(pattern);
+      out.push(...hits);
+    } else if (files.has(norm)) out.push(norm);
+    else missing.push(pattern);
+  }
+  return { matched: [...new Set(out)], missing };
+}
+
+export const globMatcher = matcher;