datatools-dev/docs/CLI-REFERENCE.es.md

> 🌐 **Idioma:** Español · [English](CLI-REFERENCE.md)

# Referencia de la CLI

> ⚠️ Los comandos, banderas y valores de las opciones son **idénticos en ambos idiomas**. La CLI emite todos sus mensajes en inglés; este documento traduce las explicaciones, no los comandos.

Tres módulos de CLI, uno por cada herramienta Lista:

| Módulo | Comando | Propósito |
|--------|---------|---------|
| `src.cli` | `python -m src.cli FILE` | Eliminador de duplicados |
| `src.cli_text_clean` | `python -m src.cli_text_clean FILE` | Limpiador de texto |
| `src.cli_analyze` | `python -m src.cli_analyze FILE` | Analizador (escaneo de solo lectura) |

Cada comando es **previsualización por defecto** — añade `--apply` para escribir la salida.

---

# Eliminador de duplicados

```
python -m src.cli ARCHIVO_ENTRADA [OPCIONES]
```

## Opciones

### Generales
- `--apply` — escribe los archivos de salida (por defecto: previsualización).
- `-o, --output RUTA` — ruta de salida (por defecto `{input}_deduplicated.csv`).

### Selección de columnas
- `-s, --subset COLS` — columnas separadas por comas en las que hacer la coincidencia (por defecto: detección automática).
- `-k, --key COLS` — columnas de clave fuerte; cada una se convierte en una estrategia independiente de coincidencia exacta (`fb_id`, `ein`, `sku`).

### Coincidencia difusa
- `--fuzzy COLS` — columnas separadas por comas para coincidencia difusa.
- `-a, --algorithm ALG` — `levenshtein` / `jaro_winkler` (por defecto) / `token_set_ratio`.
- `-t, --threshold N` — similitud 0-100 (por defecto 85).

### Normalización
- `--normalize COL:TIPO` — pares `col:tipo` separados por comas. Tipos: `email`, `phone`, `name`, `address`, `string`.

| Tipo | Efecto | Ejemplo |
|------|--------|---------|
| `email` | minúsculas, elimina puntos de Gmail, elimina `+etiqueta` | `John.Doe+x@gmail.com` → `johndoe@gmail.com` |
| `phone` | E.164 (extensión preservada) | `(555) 123-4567 ext 100` → `+15551234567;ext=100` |
| `name` | elimina títulos + sufijos + partículas, baja a minúsculas | `Dr. Charles de Gaulle Jr.` → `charles gaulle` |
| `address` | abreviaturas USPS + nombre de estado → 2 letras, minúsculas | `123 Main Street, California` → `123 main st ca` |
| `string` | recorta + colapsa + minúsculas | `  HELLO   WORLD  ` → `hello world` |

### Selección del superviviente
- `--survivor REGLA` — `first` (por defecto) / `last` / `most-complete` / `most-recent`.
- `--date-column COL` — obligatoria para `most-recent`.
- `--merge` — rellena los huecos del superviviente desde las filas eliminadas.

### Revisión interactiva
- `--review` — pregunta s/n/saltar por cada grupo de coincidencias con diff lado a lado.

### Configuración
- `--config RUTA` — carga toda la configuración desde un JSON.
- `--save-config RUTA` — guarda la configuración actual en un JSON.

### Manejo de archivos
- `--sheet NOMBRE|N` — nombre de hoja de Excel o índice base 0.
- `--encoding ENC` — anula la codificación autodetectada.
- `--header-row N` — fila de encabezado en base 0.

## Recetas

```bash
# Deduplicación básica con autodetección
python -m src.cli customers.csv [--apply]

# Coincidencia difusa de nombres al 80%
python -m src.cli customers.csv --fuzzy name --threshold 80 --apply

# Múltiples claves fuertes (lógica OR)
python -m src.cli donors.csv --key fb_id,ein --apply

# Fila más completa + fusionar campos faltantes
python -m src.cli contacts.csv --survivor most-complete --merge --apply

# Más reciente + fusión
python -m src.cli contacts.csv --survivor most-recent --date-column updated_at --merge --apply

# Revisión interactiva
python -m src.cli customers.csv --review --apply

# Guardar / cargar perfil
python -m src.cli customers.csv --fuzzy name --threshold 80 --save-config dedup.json
python -m src.cli new.csv       --config dedup.json --apply

# Excel
python -m src.cli data.xlsx --sheet "Sales" --apply
```

## Algoritmos

- **`jaro_winkler`** (por defecto) — el mejor para cadenas cortas (nombres); pondera los primeros caracteres.
- **`levenshtein`** — ratio de distancia de edición; errores tipográficos y transposiciones.
- **`token_set_ratio`** — el mejor para direcciones; ignora el orden de las palabras.

## Detección automática

Cuando no se pasan banderas `--subset` / `--fuzzy`, las columnas se detectan por su nombre:

| Patrón | Algoritmo | Umbral | Normalizador | Clave |
|---------|-----------|-----------|------------|-----|
| Email | exacto | 100% | email | fuerte |
| Teléfono | exacto | 100% | phone | fuerte |
| Nombre | jaro_winkler | 85% | name | débil |
| Dirección | token_set_ratio | 80% | address | débil |

**Reglas de estrategia**: claves fuertes → OR independiente; claves débiles → AND emparejadas con cada clave fuerte; sin claves fuertes → las débiles se promueven a independientes; sin patrones → coincidencia exacta en todas las columnas.

## Archivos de salida (con `--apply`)

| Archivo | Contenido |
|------|----------|
| `{stem}_deduplicated.csv` | Datos limpios |
| `{stem}_removed.csv` | Filas eliminadas |
| `{stem}_match_groups.csv` | `_group_id`, `_is_survivor`, `_confidence`, `_matched_on`, `_original_row` + columnas originales |

Registro: `logs/dedup_YYYYMMDD_HHMMSS.log`.

---

# Limpiador de texto

```
python -m src.cli_text_clean ARCHIVO_ENTRADA [OPCIONES]
```

Higiene a nivel de carácter. Ver [TECHNICAL.md §10.2](TECHNICAL.md) (solo en inglés) para la especificación.

## Opciones

### Generales
- `--apply` — escribe la salida (por defecto: previsualización).
- `-o, --output RUTA` — ruta de salida (por defecto `{input}_cleaned.csv`).
- `--preset NOMBRE` — `minimal` / `excel-hygiene` (por defecto) / `paranoid`.

### Alcance
- `--columns COLS` — columnas separadas por comas a limpiar (por defecto: todas las columnas de texto).
- `--skip COLS` — excluye estas columnas.

### Anulaciones por operación (anulan el preset activo)
- `--no-trim`, `--no-collapse`, `--no-nfc`, `--nfkc`, `--no-smart-chars`, `--no-zero-width`, `--no-bom`, `--no-control`, `--no-line-endings`.

### Mayúsculas / minúsculas
- `--case MODO` — `upper` / `lower` / `title` / `sentence`. O por columna: `--case title:name,upper:sku`.
- El modo título preserva los tokens en mayúsculas (`USA`) y deja en minúsculas las partículas internas (`of`, `and`).

### Auditoría + configuración
- `--full-changelog` — escribe todos los cambios (por defecto se limita a los primeros 1000).
- `--config RUTA` / `--save-config RUTA`.

### Archivo
- `--sheet`, `--encoding`, `--header-row` — iguales que en el Eliminador de duplicados.

## Presets

| Preset | Qué hace |
|--------|--------------|
| `minimal` | Solo recorte y colapso. |
| `excel-hygiene` (por defecto) | Recorte, colapso, NFC, plegado de caracteres tipográficos, eliminación de caracteres invisibles, eliminación de BOM, eliminación de caracteres de control, normalización de finales de línea. |
| `paranoid` | `excel-hygiene` + plegado de compatibilidad NFKC (con pérdida). |

## Recetas

```bash
# Valores por defecto seguros (previsualiza, luego aplica)
python -m src.cli_text_clean messy.csv [--apply]

# Solo recorte y colapso, sin tocar Unicode
python -m src.cli_text_clean messy.csv --preset minimal --apply

# Nombres en formato título, SKUs en mayúsculas
python -m src.cli_text_clean people.csv --case title:name,upper:sku --apply

# Limpiar solo columnas concretas
python -m src.cli_text_clean orders.csv --columns vendor,product --apply

# Excluir una columna de notas en texto libre
python -m src.cli_text_clean tickets.csv --skip notes --apply
```

## Archivos de salida (con `--apply`)

| Archivo | Contenido |
|------|----------|
| `{stem}_cleaned.csv` | Datos limpios |
| `{stem}_changes.csv` | `row`, `column`, `old`, `new`, `ops_applied` (limitado a 1000; `--full-changelog` quita el límite) |

Registro: `logs/text_clean_YYYYMMDD_HHMMSS.log`.

---

# Analizador

```
python -m src.cli_analyze ARCHIVO_ENTRADA [OPCIONES]
```

Escaneo de solo lectura; muestra todos los hallazgos del detector sin modificar el archivo.

## Opciones
- `--sample-rows N` — límite de filas escaneadas (por defecto 1000).
- `--json` — imprime los hallazgos como un array JSON en stdout.
- `--strict` — sale con código no cero ante cualquier hallazgo `warn`/`error`.

## Esquema JSON (un objeto por hallazgo)

```json
{
  "id": "smart_punctuation_in_data",
  "severity": "warn",
  "confidence": "high",
  "fix_action": "fold_smart_punctuation",
  "pre_applied": false,
  "tool": "02_text_cleaner",
  "count": 17,
  "description": "17 cell(s) contain curly quotes…",
  "column": null,
  "samples": [{"row": 3, "column": "name", "value": "“Alice”"}]
}
```

## Significado de los campos
- `severity` — `info` / `warn` / `error`. Solo `error` bloquea la verificación de la GUI.
- `confidence` — `high` (un clic), `medium` (previsualiza), `low` (opt-in).
- `fix_action` — id del algoritmo en `src/core/fixes.py`. Vacío si es solo informativo.
- `pre_applied` — `true` para correcciones ya aplicadas durante la lectura a nivel de bytes.

## Detectores

Puntuación tipográfica, espacios NBSP / Unicode, caracteres de ancho cero, encabezados sucios, relleno con espacios, centinelas tipo null, huellas de mojibake, columnas de email con mayúsculas/minúsculas mezcladas, formatos de fecha inconsistentes, filas casi duplicadas, identificadores con ceros a la izquierda, finales de línea mezclados, fallo de decodificación de codificación, presencia de U+FFFD.

Agregar un detector: añade la entrada en `analyze.py` y la corrección correspondiente en `fixes.py`. Ningún otro punto de llamada cambia.