@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/frontmatter-canonico.js

@@ -0,0 +1,509 @@
+'use strict';
+
+/**
+ * Parser canónico zero-deps para el subconjunto YAML/JSON versionado por SWL.
+ * Rechaza sintaxis fuera del contrato en lugar de degradar silenciosamente.
+ */
+
+function normalizarLF(contenido) {
+  return String(contenido).replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+}
+
+function crearError(codigo, mensaje, locator, extras = {}) {
+  const error = new Error(mensaje);
+  Object.assign(error, { codigo, locator, ...extras });
+  return error;
+}
+
+function locatorLinea(linea, fin = linea) {
+  return { kind: 'line-range', startLine: linea, endLine: fin };
+}
+
+function extraerPrefijoValor(texto, indice) {
+  const prefijo = texto.slice(0, indice).trimStart().replace(/^-\s+/u, '');
+  const par = prefijo.match(/^[A-Za-z_][A-Za-z0-9_-]*:\s*(.*)$/u);
+  if (par) return par[1];
+  return prefijo;
+}
+
+function contenidoElementoActual(prefijo, omitirCorchete) {
+  const ultimoSeparador = prefijo.lastIndexOf(',');
+  if (ultimoSeparador >= 0) return prefijo.slice(ultimoSeparador + 1).trim();
+  return prefijo.slice(omitirCorchete ? 1 : 0).trim();
+}
+
+function iniciaStringQuoted(texto, indice, esContenidoInline = false) {
+  if (esContenidoInline) {
+    return !contenidoElementoActual(texto.slice(0, indice), false);
+  }
+  const prefijo = extraerPrefijoValor(texto, indice);
+  if (!prefijo.trim()) return true;
+  if (!prefijo.trimStart().startsWith('[')) return false;
+  return !contenidoElementoActual(prefijo, true);
+}
+
+function quitarComentario(linea) {
+  let comilla = null;
+  for (let indice = 0; indice < linea.length; indice += 1) {
+    const caracter = linea[indice];
+    if (caracter === '\\' && comilla === '"') indice += 1;
+    else if (caracter === "'" && comilla === "'" && linea[indice + 1] === "'") indice += 1;
+    else if (caracter === comilla) comilla = null;
+    else if (
+      !comilla
+      && (caracter === '"' || caracter === "'")
+      && iniciaStringQuoted(linea, indice)
+    ) comilla = caracter;
+    else if (!comilla && caracter === '#' && /\s/u.test(linea[indice - 1] || ' ')) {
+      return linea.slice(0, indice).trimEnd();
+    }
+  }
+  return linea.trimEnd();
+}
+
+function prepararLineas(yaml, lineaBase) {
+  return yaml.split('\n').map((raw, indice) => {
+    const linea = lineaBase + indice;
+    if (raw.includes('\t')) throw crearError(
+      'YAML_TAB_PROHIBIDO',
+      `Tab prohibido en línea ${linea}`,
+      locatorLinea(linea)
+    );
+    const indent = raw.match(/^ */u)[0].length;
+    if (raw.trim() && indent % 2 !== 0) throw crearError(
+      'YAML_INDENTACION_INVALIDA',
+      `Indentación ambigua en línea ${linea}`,
+      locatorLinea(linea)
+    );
+    return { raw, text: quitarComentario(raw), indent, linea };
+  });
+}
+
+function siguienteUtil(lineas, indice) {
+  let actual = indice;
+  while (actual < lineas.length && !lineas[actual].text.trim()) actual += 1;
+  return actual;
+}
+
+function ocultarContenidoEntreComillas(texto) {
+  const visible = [...texto];
+  let comilla = null;
+  for (let indice = 0; indice < visible.length; indice += 1) {
+    const caracter = visible[indice];
+    if (
+      !comilla
+      && (caracter === '"' || caracter === "'")
+      && iniciaStringQuoted(texto, indice)
+    ) {
+      comilla = caracter;
+      visible[indice] = ' ';
+    } else if (comilla === '"' && caracter === '\\') {
+      visible[indice] = ' ';
+      if (indice + 1 < visible.length) visible[indice += 1] = ' ';
+    } else if (comilla === "'" && caracter === "'" && visible[indice + 1] === "'") {
+      visible[indice] = ' ';
+      visible[indice += 1] = ' ';
+    } else if (caracter === comilla) {
+      comilla = null;
+      visible[indice] = ' ';
+    } else if (comilla) visible[indice] = ' ';
+  }
+  return visible.join('');
+}
+
+function validarSintaxisProhibida(texto, linea) {
+  const valor = ocultarContenidoEntreComillas(texto).trim();
+  const reglas = [
+    [/^<<\s*:/u, 'YAML_MERGE_PROHIBIDO'],
+    [/(^|\s)&[^\s,\]]+/u, 'YAML_ANCHOR_PROHIBIDO'],
+    [/(^|\s)\*[^\s,\]]+/u, 'YAML_ALIAS_PROHIBIDO'],
+    [/(^|\s)![^\s,\]]+/u, 'YAML_TAG_PROHIBIDO'],
+  ];
+  for (const [patron, codigo] of reglas) {
+    if (patron.test(valor)) throw crearError(codigo, `${codigo} en línea ${linea}`, locatorLinea(linea));
+  }
+  if (/[{}]/u.test(valor)) throw crearError(
+    'YAML_TIPO_NO_SOPORTADO',
+    `Mapa inline no soportado en línea ${linea}`,
+    locatorLinea(linea)
+  );
+}
+
+function separarInline(contenido, linea) {
+  const elementos = [];
+  let inicio = 0;
+  let comilla = null;
+  for (let indice = 0; indice <= contenido.length; indice += 1) {
+    const caracter = contenido[indice];
+    if (caracter === '\\' && comilla === '"') indice += 1;
+    else if (caracter === "'" && comilla === "'" && contenido[indice + 1] === "'") indice += 1;
+    else if (caracter === comilla) comilla = null;
+    else if (
+      !comilla
+      && (caracter === '"' || caracter === "'")
+      && iniciaStringQuoted(contenido, indice, true)
+    ) comilla = caracter;
+    else if (!comilla && (caracter === ',' || indice === contenido.length)) {
+      elementos.push(contenido.slice(inicio, indice).trim());
+      inicio = indice + 1;
+    }
+  }
+  if (comilla) throw crearError('YAML_ESCALAR_INVALIDO', 'Comilla sin cierre', locatorLinea(linea));
+  if (elementos.some((elemento) => elemento === '')) throw crearError(
+    'YAML_ESCALAR_INVALIDO',
+    'Elemento vacío en array inline',
+    locatorLinea(linea)
+  );
+  return elementos;
+}
+
+function parsearComillaSimple(valor, linea) {
+  if (!valor.endsWith("'")) throw crearError(
+    'YAML_ESCALAR_INVALIDO',
+    'String inválido',
+    locatorLinea(linea)
+  );
+  const interior = valor.slice(1, -1);
+  let resultado = '';
+  for (let indice = 0; indice < interior.length; indice += 1) {
+    if (interior[indice] !== "'") resultado += interior[indice];
+    else if (interior[indice + 1] === "'") {
+      resultado += "'";
+      indice += 1;
+    } else throw crearError(
+      'YAML_ESCALAR_INVALIDO',
+      'String inválido',
+      locatorLinea(linea)
+    );
+  }
+  return resultado;
+}
+
+function parsearComillas(valor, linea) {
+  if (valor.startsWith('"')) {
+    try {
+      return JSON.parse(valor);
+    } catch {
+      throw crearError('YAML_ESCALAR_INVALIDO', 'String inválido', locatorLinea(linea));
+    }
+  }
+  return parsearComillaSimple(valor, linea);
+}
+
+function parsearEscalar(texto, linea) {
+  const valor = texto.trim();
+  if (valor.startsWith('"') || valor.startsWith("'")) return parsearComillas(valor, linea);
+  if (valor.startsWith('[') && valor.endsWith(']')) {
+    const interior = valor.slice(1, -1).trim();
+    return interior ? separarInline(interior, linea).map((item) => parsearEscalar(item, linea)) : [];
+  }
+  validarSintaxisProhibida(valor, linea);
+  if (valor === 'null') return null;
+  if (valor === 'true' || valor === 'false') return valor === 'true';
+  if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/u.test(valor)) return Number(valor);
+  if (valor.startsWith('[')) throw crearError(
+    'YAML_TIPO_NO_SOPORTADO',
+    'Array inline inválido',
+    locatorLinea(linea)
+  );
+  return valor;
+}
+
+function registrarCampo(campos, ruta, clave, inicio, fin) {
+  const metadata = {
+    claveFuente: clave,
+    locator: locatorLinea(inicio, fin),
+  };
+  campos[ruta.join('.')] = metadata;
+  if (ruta.length === 1) campos[clave] = metadata;
+}
+
+function contenidoBloque(lineas, indice, indent, estilo) {
+  const partes = [];
+  let actual = indice + 1;
+  while (actual < lineas.length) {
+    const linea = lineas[actual];
+    if (linea.raw.trim() && linea.indent <= indent) break;
+    partes.push(linea.raw.trim() ? linea.raw.slice(indent + 2) : '');
+    actual += 1;
+  }
+  const valor = estilo === '|'
+    ? `${partes.join('\n')}\n`
+    : `${partes.join('\n').replace(/([^\n])\n(?=[^\n])/gu, '$1 ')}\n`;
+  return { valor, siguiente: actual, fin: Math.max(lineas[indice].linea, lineas[actual - 1]?.linea) };
+}
+
+function extraerPar(texto, linea) {
+  validarSintaxisProhibida(texto, linea);
+  const match = texto.match(/^([A-Za-z_][A-Za-z0-9_-]*):(?:\s*(.*))?$/u);
+  if (!match) throw crearError(
+    'YAML_ESTRUCTURA_INVALIDA',
+    `Clave inválida en línea ${linea}`,
+    locatorLinea(linea)
+  );
+  return { clave: match[1], resto: match[2] || '' };
+}
+
+function parsearValorPar(lineas, indice, indent, resto, campos, ruta) {
+  if (resto === '|' || resto === '>') return contenidoBloque(lineas, indice, indent, resto);
+  if (resto) return { valor: parsearEscalar(resto, lineas[indice].linea), siguiente: indice + 1 };
+  const proximo = siguienteUtil(lineas, indice + 1);
+  if (proximo >= lineas.length || lineas[proximo].indent <= indent) {
+    return { valor: null, siguiente: indice + 1 };
+  }
+  if (lineas[proximo].indent !== indent + 2) throw crearError(
+    'YAML_INDENTACION_INVALIDA',
+    `Indentación inválida en línea ${lineas[proximo].linea}`,
+    locatorLinea(lineas[proximo].linea)
+  );
+  return parsearNodo(lineas, proximo, indent + 2, campos, ruta);
+}
+
+function parsearMapa(lineas, indice, indent, campos, ruta = []) {
+  const valor = {};
+  let actual = indice;
+  let ultimaLinea = lineas[indice]?.linea;
+  while ((actual = siguienteUtil(lineas, actual)) < lineas.length) {
+    const linea = lineas[actual];
+    if (linea.indent < indent) break;
+    if (linea.indent !== indent || linea.text.trimStart().startsWith('- ')) throw crearError(
+      'YAML_INDENTACION_INVALIDA',
+      `Indentación inválida en línea ${linea.linea}`,
+      locatorLinea(linea.linea)
+    );
+    const { clave, resto } = extraerPar(linea.text.trim(), linea.linea);
+    if (Object.hasOwn(valor, clave)) throw crearError(
+      'YAML_CLAVE_DUPLICADA',
+      `Clave duplicada ${clave}`,
+      locatorLinea(linea.linea),
+      { clave }
+    );
+    const resultado = parsearValorPar(lineas, actual, indent, resto, campos, [...ruta, clave]);
+    valor[clave] = resultado.valor;
+    ultimaLinea = resultado.fin || lineas[Math.max(actual, resultado.siguiente - 1)].linea;
+    registrarCampo(campos, [...ruta, clave], clave, linea.linea, ultimaLinea);
+    actual = resultado.siguiente;
+  }
+  return { valor, siguiente: actual, fin: ultimaLinea };
+}
+
+function parsearItemMapa(lineas, indice, indent, contenido, campos, ruta) {
+  const copia = lineas.slice();
+  copia[indice] = {
+    ...lineas[indice],
+    text: `${' '.repeat(indent + 2)}${contenido}`,
+    indent: indent + 2,
+  };
+  return parsearMapa(copia, indice, indent + 2, campos, ruta);
+}
+
+function parsearLista(lineas, indice, indent, campos, ruta = []) {
+  const valor = [];
+  let actual = indice;
+  let ultimaLinea = lineas[indice]?.linea;
+  while ((actual = siguienteUtil(lineas, actual)) < lineas.length) {
+    const linea = lineas[actual];
+    if (linea.indent < indent) break;
+    if (linea.indent !== indent || !linea.text.trimStart().startsWith('- ')) break;
+    const contenido = linea.text.trimStart().slice(2).trim();
+    const esMapa = /^[A-Za-z_][A-Za-z0-9_-]*:/u.test(contenido);
+    const resultado = esMapa
+      ? parsearItemMapa(lineas, actual, indent, contenido, campos, [...ruta, String(valor.length)])
+      : { valor: parsearEscalar(contenido, linea.linea), siguiente: actual + 1 };
+    valor.push(resultado.valor);
+    ultimaLinea = resultado.fin || linea.linea;
+    actual = resultado.siguiente;
+  }
+  return { valor, siguiente: actual, fin: ultimaLinea };
+}
+
+function parsearNodo(lineas, indice, indent, campos, ruta = []) {
+  const actual = siguienteUtil(lineas, indice);
+  if (actual >= lineas.length) return { valor: null, siguiente: actual };
+  const esLista = lineas[actual].text.trimStart().startsWith('- ');
+  return esLista
+    ? parsearLista(lineas, actual, indent, campos, ruta)
+    : parsearMapa(lineas, actual, indent, campos, ruta);
+}
+
+function separarFrontmatter(contenido) {
+  const buffer = normalizarLF(contenido);
+  if (!buffer.startsWith('---\n')) return { buffer, yaml: null, cuerpo: buffer };
+  const cierre = buffer.indexOf('\n---\n', 4);
+  if (cierre < 0) throw crearError(
+    'FRONTMATTER_DELIMITADOR_INVALIDO',
+    'Frontmatter sin delimitador de cierre',
+    locatorLinea(1)
+  );
+  return {
+    buffer,
+    yaml: buffer.slice(4, cierre),
+    cuerpo: buffer.slice(cierre + 5),
+  };
+}
+
+function parsearFrontmatter(contenido, opciones = {}) {
+  void opciones;
+  const { yaml, cuerpo } = separarFrontmatter(contenido);
+  if (yaml === null) return { valor: null, campos: {}, cuerpo };
+  const campos = {};
+  const lineas = prepararLineas(yaml, 2);
+  const inicio = siguienteUtil(lineas, 0);
+  if (inicio < lineas.length && lineas[inicio].indent !== 0) throw crearError(
+    'YAML_INDENTACION_RAIZ_INVALIDA',
+    `La raíz debe iniciar en columna cero, línea ${lineas[inicio].linea}`,
+    locatorLinea(lineas[inicio].linea)
+  );
+  const resultado = parsearNodo(lineas, inicio, 0, campos);
+  const adicional = siguienteUtil(lineas, resultado.siguiente);
+  if (adicional < lineas.length) throw crearError(
+    'YAML_CONTENIDO_ADICIONAL',
+    `Contenido YAML adicional en línea ${lineas[adicional].linea}`,
+    locatorLinea(lineas[adicional].linea)
+  );
+  return { valor: resultado.valor, campos, cuerpo };
+}
+
+function byteOffset(texto, indice) {
+  return Buffer.byteLength(texto.slice(0, indice), 'utf8');
+}
+
+function omitirEspacios(estado) {
+  while (/\s/u.test(estado.texto[estado.indice] || '')) estado.indice += 1;
+}
+
+function errorJSON(estado, mensaje, inicio = estado.indice, fin = inicio + 1, extras = {}) {
+  throw crearError('JSON_INVALIDO', mensaje, {
+    kind: 'byte-range',
+    start: byteOffset(estado.texto, inicio),
+    end: byteOffset(estado.texto, fin),
+  }, extras);
+}
+
+function leerCadenaJSON(estado) {
+  const inicio = estado.indice;
+  estado.indice += 1;
+  while (estado.indice < estado.texto.length) {
+    const caracter = estado.texto[estado.indice];
+    if (caracter === '\\') estado.indice += 2;
+    else if (caracter === '"') {
+      estado.indice += 1;
+      const raw = estado.texto.slice(inicio, estado.indice);
+      try {
+        return { valor: JSON.parse(raw), inicio, fin: estado.indice };
+      } catch {
+        errorJSON(estado, 'String JSON inválido', inicio, estado.indice);
+      }
+    } else estado.indice += 1;
+  }
+  errorJSON(estado, 'String JSON sin cierre', inicio, estado.indice);
+}
+
+function escaparPointer(token) {
+  return token.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+function leerLiteralJSON(estado) {
+  const resto = estado.texto.slice(estado.indice);
+  const match = resto.match(/^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/u);
+  if (!match) errorJSON(estado, 'Valor JSON inválido');
+  estado.indice += match[0].length;
+}
+
+function leerArregloJSON(estado, pointer) {
+  estado.indice += 1;
+  omitirEspacios(estado);
+  let indice = 0;
+  if (estado.texto[estado.indice] === ']') {
+    estado.indice += 1;
+    return;
+  }
+  while (true) {
+    if (estado.indice >= estado.texto.length) errorJSON(estado, 'Array JSON sin cierre');
+    leerValorJSON(estado, `${pointer}/${indice}`);
+    omitirEspacios(estado);
+    if (estado.texto[estado.indice] === ']') {
+      estado.indice += 1;
+      return;
+    }
+    if (estado.texto[estado.indice] !== ',') errorJSON(estado, 'Separador de array inválido');
+    estado.indice += 1;
+    indice += 1;
+  }
+}
+
+function registrarPropiedadJSON(estado, pointer, cadena) {
+  estado.propiedades[pointer] = {
+    claveFuente: cadena.valor,
+    locator: {
+      kind: 'byte-range',
+      start: byteOffset(estado.texto, cadena.inicio),
+      end: byteOffset(estado.texto, cadena.fin),
+    },
+  };
+}
+
+function errorDuplicadoJSON(estado, cadena) {
+  throw crearError('JSON_CLAVE_DUPLICADA', `Clave JSON duplicada: ${cadena.valor}`, {
+    kind: 'byte-range',
+    start: byteOffset(estado.texto, cadena.inicio),
+    end: byteOffset(estado.texto, cadena.fin),
+  }, { clave: cadena.valor });
+}
+
+function leerObjetoJSON(estado, pointer) {
+  estado.indice += 1;
+  omitirEspacios(estado);
+  const claves = new Set();
+  if (estado.texto[estado.indice] === '}') {
+    estado.indice += 1;
+    return;
+  }
+  while (true) {
+    if (estado.indice >= estado.texto.length) errorJSON(estado, 'Objeto JSON sin cierre');
+    if (estado.texto[estado.indice] !== '"') errorJSON(estado, 'Clave JSON inválida');
+    const cadena = leerCadenaJSON(estado);
+    if (claves.has(cadena.valor)) errorDuplicadoJSON(estado, cadena);
+    claves.add(cadena.valor);
+    const hijo = `${pointer}/${escaparPointer(cadena.valor)}`;
+    registrarPropiedadJSON(estado, hijo, cadena);
+    omitirEspacios(estado);
+    if (estado.texto[estado.indice] !== ':') errorJSON(estado, 'Falta dos puntos');
+    estado.indice += 1;
+    leerValorJSON(estado, hijo);
+    omitirEspacios(estado);
+    if (estado.texto[estado.indice] === '}') {
+      estado.indice += 1;
+      return;
+    }
+    if (estado.texto[estado.indice] !== ',') errorJSON(estado, 'Separador de objeto inválido');
+    estado.indice += 1;
+    omitirEspacios(estado);
+  }
+}
+
+function leerValorJSON(estado, pointer) {
+  omitirEspacios(estado);
+  const caracter = estado.texto[estado.indice];
+  if (caracter === '{') leerObjetoJSON(estado, pointer);
+  else if (caracter === '[') leerArregloJSON(estado, pointer);
+  else if (caracter === '"') leerCadenaJSON(estado);
+  else leerLiteralJSON(estado);
+  omitirEspacios(estado);
+}
+
+function parsearJSONSeguro(contenido, opciones = {}) {
+  void opciones;
+  const buffer = normalizarLF(contenido);
+  const estado = { texto: buffer, indice: 0, propiedades: {} };
+  leerValorJSON(estado, '');
+  if (estado.indice !== buffer.length) errorJSON(estado, 'Contenido JSON adicional');
+  const valor = JSON.parse(buffer);
+  return { valor, propiedades: estado.propiedades, buffer };
+}
+
+module.exports = {
+  normalizarLF,
+  parsearFrontmatter,
+  parsearJSONSeguro,
+};