@saulwade/swl-ses 1.5.1 → 1.6.0

package/hooks/lib/text-similarity.js

@@ -1,241 +1,241 @@
-'use strict';
-
-/**
- * text-similarity.js — utilidades para fuzzy matching en español.
- *
- * Cero dependencias. Compatible Node 18+.
- *
- * Funciones expuestas:
- *   - quitarAcentos(texto): normaliza diacríticos preservando ñ
- *   - tokenizar(texto): divide en palabras (≥1 char)
- *   - stemES(palabra): stemmer ligero español (Porter-light)
- *   - levenshtein(a, b): distancia de edición
- *   - fuzzyContains(haystack, needle, opts): true si needle aparece de forma
- *     aproximada en haystack
- *
- * Diseño:
- *   - El stemmer remueve UN solo sufijo por palabra (no recursivo).
- *   - Palabras de ≤3 chars no se stemean.
- *   - El threshold de Levenshtein es adaptativo: 0 (≤3), 1 (4-7), 2 (8+).
- *
- * Origen: ADR 0013 sección 3B (mayo 2026).
- */
-
-// ---------------------------------------------------------------------------
-// Normalización
-// ---------------------------------------------------------------------------
-
-const COMBINADORES_RE = /[̀-ͯ]/g;
-// ñ y Ñ en NFD se descomponen a n/N + U+0303. Usamos sentinels (caracteres
-// privados de uso +) para preservarlos sin colisión con texto real.
-const N_TILDE_NFD = /ñ/g;
-const N_TILDE_NFD_UPPER = /Ñ/g;
-const SENTINEL_LOWER = '';
-const SENTINEL_UPPER = '';
-
-/**
- * Remueve acentos preservando ñ. Lowercase y uppercase.
- * @param {string} texto
- * @returns {string}
- */
-function quitarAcentos(texto) {
-  if (!texto) return '';
-  return String(texto)
-    .normalize('NFD')
-    .replace(N_TILDE_NFD, SENTINEL_LOWER)
-    .replace(N_TILDE_NFD_UPPER, SENTINEL_UPPER)
-    .replace(COMBINADORES_RE, '')
-    .replace(new RegExp(SENTINEL_LOWER, 'g'), 'ñ')
-    .replace(new RegExp(SENTINEL_UPPER, 'g'), 'Ñ');
-}
-
-/**
- * Divide texto en tokens (palabras) preservando solo letras y números.
- * @param {string} texto
- * @returns {string[]}
- */
-function tokenizar(texto) {
-  if (!texto) return [];
-  const matches = String(texto).toLowerCase().match(/[a-záéíóúñü0-9]+/g);
-  return matches || [];
-}
-
-// ---------------------------------------------------------------------------
-// Stemmer Porter-light español
-// ---------------------------------------------------------------------------
-
-/**
- * Sufijos ordenados de más largo a más corto. El primer match gana.
- * Cada entry es [sufijo, longitudMinimaResto].
- * Si la palabra tras quitar el sufijo es < longitudMinimaResto, no se aplica.
- *
- * Nota: el sufijo 's' tiene minResto=4 (no 3) para evitar que palabras como
- * "tres" o "más" se stemmen a stems de 3 chars que generan falsos matches.
- */
-const SUFIJOS_ES = [
-  // Verbos largos (gerundio + clítico)
-  ['iendolo', 4], ['iendola', 4], ['iendolos', 4], ['iendolas', 4],
-  ['andolo', 4], ['andola', 4], ['andolos', 4], ['andolas', 4],
-  // Sustantivos compuestos
-  ['amientos', 4], ['imientos', 4], ['amiento', 4], ['imiento', 4],
-  // Adjetivos -ación/-ición/-mente
-  ['aciones', 4], ['iciones', 4], ['acion', 4], ['icion', 4],
-  ['mente', 4],
-  // Plurales -dades / abstractos
-  ['idades', 4], ['idad', 4], ['dades', 4], ['dad', 3],
-  // Adjetivos -ico/a + plurales
-  ['icos', 3], ['icas', 3], ['ico', 3], ['ica', 3],
-  // Participios
-  ['ados', 3], ['adas', 3], ['ado', 3], ['ada', 3],
-  ['idos', 3], ['idas', 3], ['ido', 3], ['ida', 3],
-  // Gerundios
-  ['iendo', 3], ['ando', 3],
-  // Plurales / verbos comunes
-  ['ciones', 3], ['cion', 3],
-  // Infinitivos
-  ['ar', 3], ['er', 3], ['ir', 3],
-  // Plurales simples
-  ['es', 3], ['as', 3], ['os', 3],
-  ['s', 4],
-];
-
-/**
- * Stemmer ligero para español. Remueve UN sufijo por palabra. No recursivo.
- *
- * @param {string} palabra
- * @returns {string} stem normalizado (sin acentos, lowercase)
- */
-function stemES(palabra) {
-  if (!palabra || palabra.length <= 3) {
-    return palabra ? quitarAcentos(palabra.toLowerCase()) : palabra;
-  }
-
-  const sin = quitarAcentos(palabra.toLowerCase());
-
-  for (const [sufijo, minResto] of SUFIJOS_ES) {
-    if (sin.endsWith(sufijo) && sin.length - sufijo.length >= minResto) {
-      return sin.slice(0, sin.length - sufijo.length);
-    }
-  }
-  return sin;
-}
-
-// ---------------------------------------------------------------------------
-// Distancia de Levenshtein (DP iterativa con dos filas)
-// ---------------------------------------------------------------------------
-
-/**
- * Distancia de edición clásica. O(min(a,b)) memoria.
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-function levenshtein(a, b) {
-  if (a === b) return 0;
-  if (!a) return b.length;
-  if (!b) return a.length;
-
-  if (a.length > b.length) [a, b] = [b, a];
-
-  let prev = new Array(a.length + 1);
-  let curr = new Array(a.length + 1);
-
-  for (let i = 0; i <= a.length; i++) prev[i] = i;
-
-  for (let j = 1; j <= b.length; j++) {
-    curr[0] = j;
-    for (let i = 1; i <= a.length; i++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[i] = Math.min(
-        curr[i - 1] + 1,
-        prev[i] + 1,
-        prev[i - 1] + cost
-      );
-    }
-    [prev, curr] = [curr, prev];
-  }
-  return prev[a.length];
-}
-
-// ---------------------------------------------------------------------------
-// Fuzzy contains
-// ---------------------------------------------------------------------------
-
-/**
- * Threshold de Levenshtein adaptativo según longitud de la palabra.
- * @param {string} palabra
- * @returns {number}
- */
-function thresholdAdaptativo(palabra) {
-  if (palabra.length <= 3) return 0;
-  if (palabra.length <= 7) return 1;
-  return 2;
-}
-
-/**
- * Verifica si `needle` aparece en `haystack` con tolerancia.
- *
- * Estrategia (orden):
- *   1. Match exacto de substring sobre normalizado (sin acentos, lowercase).
- *   2. Multi-token: cada token del needle debe matchear con algún token del
- *      haystack vía exacto, stem o Levenshtein.
- *
- * @param {string} haystack
- * @param {string} needle
- * @param {object} [opts]
- * @param {boolean} [opts.exact=false] - solo match exacto (sin fuzzy)
- * @param {boolean} [opts.useStem=true] - aplicar stemming
- * @param {number}  [opts.threshold=null] - override threshold
- * @returns {boolean}
- */
-function fuzzyContains(haystack, needle, opts = {}) {
-  const { exact = false, useStem = true, threshold = null } = opts;
-
-  if (!haystack || !needle) return false;
-
-  const haystackNorm = quitarAcentos(haystack.toLowerCase());
-  const needleNorm = quitarAcentos(needle.toLowerCase());
-
-  if (haystackNorm.includes(needleNorm)) return true;
-  if (exact) return false;
-
-  const needleTokens = tokenizar(needleNorm);
-  const haystackTokens = tokenizar(haystackNorm);
-
-  if (needleTokens.length === 0 || haystackTokens.length === 0) return false;
-
-  return needleTokens.every((nt) =>
-    haystackTokens.some((ht) => coincideToken(ht, nt, useStem, threshold))
-  );
-}
-
-/**
- * Compara dos tokens individuales con tolerancia.
- * @param {string} ht
- * @param {string} nt
- * @param {boolean} useStem
- * @param {number|null} threshold
- * @returns {boolean}
- */
-function coincideToken(ht, nt, useStem, threshold) {
-  if (ht === nt) return true;
-
-  if (useStem) {
-    const sht = stemES(ht);
-    const snt = stemES(nt);
-    if (sht === snt && sht.length >= 3) return true;
-  }
-
-  const t = threshold !== null ? threshold : thresholdAdaptativo(nt);
-  if (t === 0) return false;
-  return levenshtein(ht, nt) <= t;
-}
-
-module.exports = {
-  quitarAcentos,
-  tokenizar,
-  stemES,
-  levenshtein,
-  fuzzyContains,
-  _internals: { thresholdAdaptativo, coincideToken, SUFIJOS_ES },
-};
+'use strict';
+
+/**
+ * text-similarity.js — utilidades para fuzzy matching en español.
+ *
+ * Cero dependencias. Compatible Node 18+.
+ *
+ * Funciones expuestas:
+ *   - quitarAcentos(texto): normaliza diacríticos preservando ñ
+ *   - tokenizar(texto): divide en palabras (≥1 char)
+ *   - stemES(palabra): stemmer ligero español (Porter-light)
+ *   - levenshtein(a, b): distancia de edición
+ *   - fuzzyContains(haystack, needle, opts): true si needle aparece de forma
+ *     aproximada en haystack
+ *
+ * Diseño:
+ *   - El stemmer remueve UN solo sufijo por palabra (no recursivo).
+ *   - Palabras de ≤3 chars no se stemean.
+ *   - El threshold de Levenshtein es adaptativo: 0 (≤3), 1 (4-7), 2 (8+).
+ *
+ * Origen: ADR 0013 sección 3B (mayo 2026).
+ */
+
+// ---------------------------------------------------------------------------
+// Normalización
+// ---------------------------------------------------------------------------
+
+const COMBINADORES_RE = /[̀-ͯ]/g;
+// ñ y Ñ en NFD se descomponen a n/N + U+0303. Usamos sentinels (caracteres
+// privados de uso +) para preservarlos sin colisión con texto real.
+const N_TILDE_NFD = /ñ/g;
+const N_TILDE_NFD_UPPER = /Ñ/g;
+const SENTINEL_LOWER = '';
+const SENTINEL_UPPER = '';
+
+/**
+ * Remueve acentos preservando ñ. Lowercase y uppercase.
+ * @param {string} texto
+ * @returns {string}
+ */
+function quitarAcentos(texto) {
+  if (!texto) return '';
+  return String(texto)
+    .normalize('NFD')
+    .replace(N_TILDE_NFD, SENTINEL_LOWER)
+    .replace(N_TILDE_NFD_UPPER, SENTINEL_UPPER)
+    .replace(COMBINADORES_RE, '')
+    .replace(new RegExp(SENTINEL_LOWER, 'g'), 'ñ')
+    .replace(new RegExp(SENTINEL_UPPER, 'g'), 'Ñ');
+}
+
+/**
+ * Divide texto en tokens (palabras) preservando solo letras y números.
+ * @param {string} texto
+ * @returns {string[]}
+ */
+function tokenizar(texto) {
+  if (!texto) return [];
+  const matches = String(texto).toLowerCase().match(/[a-záéíóúñü0-9]+/g);
+  return matches || [];
+}
+
+// ---------------------------------------------------------------------------
+// Stemmer Porter-light español
+// ---------------------------------------------------------------------------
+
+/**
+ * Sufijos ordenados de más largo a más corto. El primer match gana.
+ * Cada entry es [sufijo, longitudMinimaResto].
+ * Si la palabra tras quitar el sufijo es < longitudMinimaResto, no se aplica.
+ *
+ * Nota: el sufijo 's' tiene minResto=4 (no 3) para evitar que palabras como
+ * "tres" o "más" se stemmen a stems de 3 chars que generan falsos matches.
+ */
+const SUFIJOS_ES = [
+  // Verbos largos (gerundio + clítico)
+  ['iendolo', 4], ['iendola', 4], ['iendolos', 4], ['iendolas', 4],
+  ['andolo', 4], ['andola', 4], ['andolos', 4], ['andolas', 4],
+  // Sustantivos compuestos
+  ['amientos', 4], ['imientos', 4], ['amiento', 4], ['imiento', 4],
+  // Adjetivos -ación/-ición/-mente
+  ['aciones', 4], ['iciones', 4], ['acion', 4], ['icion', 4],
+  ['mente', 4],
+  // Plurales -dades / abstractos
+  ['idades', 4], ['idad', 4], ['dades', 4], ['dad', 3],
+  // Adjetivos -ico/a + plurales
+  ['icos', 3], ['icas', 3], ['ico', 3], ['ica', 3],
+  // Participios
+  ['ados', 3], ['adas', 3], ['ado', 3], ['ada', 3],
+  ['idos', 3], ['idas', 3], ['ido', 3], ['ida', 3],
+  // Gerundios
+  ['iendo', 3], ['ando', 3],
+  // Plurales / verbos comunes
+  ['ciones', 3], ['cion', 3],
+  // Infinitivos
+  ['ar', 3], ['er', 3], ['ir', 3],
+  // Plurales simples
+  ['es', 3], ['as', 3], ['os', 3],
+  ['s', 4],
+];
+
+/**
+ * Stemmer ligero para español. Remueve UN sufijo por palabra. No recursivo.
+ *
+ * @param {string} palabra
+ * @returns {string} stem normalizado (sin acentos, lowercase)
+ */
+function stemES(palabra) {
+  if (!palabra || palabra.length <= 3) {
+    return palabra ? quitarAcentos(palabra.toLowerCase()) : palabra;
+  }
+
+  const sin = quitarAcentos(palabra.toLowerCase());
+
+  for (const [sufijo, minResto] of SUFIJOS_ES) {
+    if (sin.endsWith(sufijo) && sin.length - sufijo.length >= minResto) {
+      return sin.slice(0, sin.length - sufijo.length);
+    }
+  }
+  return sin;
+}
+
+// ---------------------------------------------------------------------------
+// Distancia de Levenshtein (DP iterativa con dos filas)
+// ---------------------------------------------------------------------------
+
+/**
+ * Distancia de edición clásica. O(min(a,b)) memoria.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a) return b.length;
+  if (!b) return a.length;
+
+  if (a.length > b.length) [a, b] = [b, a];
+
+  let prev = new Array(a.length + 1);
+  let curr = new Array(a.length + 1);
+
+  for (let i = 0; i <= a.length; i++) prev[i] = i;
+
+  for (let j = 1; j <= b.length; j++) {
+    curr[0] = j;
+    for (let i = 1; i <= a.length; i++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[i] = Math.min(
+        curr[i - 1] + 1,
+        prev[i] + 1,
+        prev[i - 1] + cost
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[a.length];
+}
+
+// ---------------------------------------------------------------------------
+// Fuzzy contains
+// ---------------------------------------------------------------------------
+
+/**
+ * Threshold de Levenshtein adaptativo según longitud de la palabra.
+ * @param {string} palabra
+ * @returns {number}
+ */
+function thresholdAdaptativo(palabra) {
+  if (palabra.length <= 3) return 0;
+  if (palabra.length <= 7) return 1;
+  return 2;
+}
+
+/**
+ * Verifica si `needle` aparece en `haystack` con tolerancia.
+ *
+ * Estrategia (orden):
+ *   1. Match exacto de substring sobre normalizado (sin acentos, lowercase).
+ *   2. Multi-token: cada token del needle debe matchear con algún token del
+ *      haystack vía exacto, stem o Levenshtein.
+ *
+ * @param {string} haystack
+ * @param {string} needle
+ * @param {object} [opts]
+ * @param {boolean} [opts.exact=false] - solo match exacto (sin fuzzy)
+ * @param {boolean} [opts.useStem=true] - aplicar stemming
+ * @param {number}  [opts.threshold=null] - override threshold
+ * @returns {boolean}
+ */
+function fuzzyContains(haystack, needle, opts = {}) {
+  const { exact = false, useStem = true, threshold = null } = opts;
+
+  if (!haystack || !needle) return false;
+
+  const haystackNorm = quitarAcentos(haystack.toLowerCase());
+  const needleNorm = quitarAcentos(needle.toLowerCase());
+
+  if (haystackNorm.includes(needleNorm)) return true;
+  if (exact) return false;
+
+  const needleTokens = tokenizar(needleNorm);
+  const haystackTokens = tokenizar(haystackNorm);
+
+  if (needleTokens.length === 0 || haystackTokens.length === 0) return false;
+
+  return needleTokens.every((nt) =>
+    haystackTokens.some((ht) => coincideToken(ht, nt, useStem, threshold))
+  );
+}
+
+/**
+ * Compara dos tokens individuales con tolerancia.
+ * @param {string} ht
+ * @param {string} nt
+ * @param {boolean} useStem
+ * @param {number|null} threshold
+ * @returns {boolean}
+ */
+function coincideToken(ht, nt, useStem, threshold) {
+  if (ht === nt) return true;
+
+  if (useStem) {
+    const sht = stemES(ht);
+    const snt = stemES(nt);
+    if (sht === snt && sht.length >= 3) return true;
+  }
+
+  const t = threshold !== null ? threshold : thresholdAdaptativo(nt);
+  if (t === 0) return false;
+  return levenshtein(ht, nt) <= t;
+}
+
+module.exports = {
+  quitarAcentos,
+  tokenizar,
+  stemES,
+  levenshtein,
+  fuzzyContains,
+  _internals: { thresholdAdaptativo, coincideToken, SUFIJOS_ES },
+};