Convertir TOML a NDJSON

Un documento TOML es una tabla. La especificación no permite que un archivo TOML sea una lista en su nivel superior, así que el límite entre registros que el JSON delimitado por saltos de línea necesita no aparece nunca dentro de un mismo archivo: el documento entero se convierte en una línea.

Para casi cualquier otro origen eso sería una limitación. Aquí es la forma del problema: nadie quiere un `pyproject.toml` troceado, y todo el que convierte uno a NDJSON está construyendo una colección en la que cada archivo es un registro. La unidad del formato y la unidad de la pregunta coinciden, cosa que no pasa en todos los pares de este sitio.

En España hay un motivo formal, y no sólo de curiosidad, para necesitar esto. El Esquema Nacional de Seguridad obliga a mantener un inventario actualizado de los componentes de un sistema, y en cuanto ese sistema es software propio la relación de componentes vive dispersa en manifiestos: un `pyproject.toml` por servicio, un `Cargo.toml` por paquete, un archivo de configuración por herramienta.

Reunirlos en un único conjunto de líneas convierte una obligación documental en una consulta. Qué paquetes fijan una versión concreta de una biblioteca, cuáles no declaran licencia, cuáles siguen apuntando a una edición antigua del lenguaje: todo eso pasa a ser una pregunta sobre un archivo en lugar de un recorrido manual por cuarenta repositorios cada vez que alguien la formula.

El flujo es: convertir cada archivo y añadir la línea a una salida que crece. Como cada línea es un valor JSON completo y autónomo y no hay nada envolviendo el conjunto —ni corchetes, ni comas entre registros—, la concatenación es el paso de fusión entero.

Dos líneas procedentes de dos conversiones son un archivo NDJSON válido de dos registros. Eso también significa que el orden es tuyo: puedes ordenar por repositorio, por equipo o por fecha de conversión simplemente decidiendo en qué orden concatenas, y no hay ninguna estructura que se rompa por ello.

Un registro sin origen es casi inútil dentro de un inventario. El conversor lee el contenido de un archivo y nada más: no conoce la ruta, ni el repositorio, ni el commit, así que la línea que produce no lleva ningún campo que diga de dónde salió.

Añádelo tú, en uno de dos momentos. Un paso con `jq` durante la concatenación puede inyectar la ruta por línea, deja los TOML intactos y es lo adecuado para una flota que no es tuya. La alternativa es una clave dentro de cada TOML que lo identifique, que sobrevive a todas las conversiones futuras pero implica editar archivos de otros equipos. Lo primero escala; lo segundo es más honesto cuando el archivo debería identificarse a sí mismo de todas formas.

JSON compacto: sin sangría, sin espacio tras los dos puntos, con las claves en el orden en que las declaró el TOML y con un salto de línea al final. Las tablas se convierten en objetos anidados y los arrays de tablas en arrays de objetos, de modo que una lista de autores o un conjunto de destinos de compilación llegan con la forma que un motor de consultas espera.

Y llegan anidados de verdad, no aplanados en columnas con puntos. Esa transformación existe en este conversor y se aplica al ir hacia CSV, TSV, SQL, INI, XLSX o Parquet; hacia JSON, YAML, TOML, XML y NDJSON el árbol se conserva. Es la diferencia entre poder preguntar por `tool.ruff.line-length` y tener que reconstruirlo desde un nombre de columna.

TOML es raro por tener cuatro tipos temporales en lugar de uno, y la conversión no los aplasta contra un instante UTC común. Un valor `1979-05-27T07:32:00Z` sale como la cadena `1979-05-27T07:32:00.000Z`; uno escrito con `+02:00` conserva ese desfase en vez de normalizarse; `1979-05-27` sigue siendo una fecha sin hora y `07:32:00` sigue siendo una hora sin fecha.

Dos consecuencias para el inventario. Son cadenas, porque JSON no tiene tipo temporal, así que casi cualquier cargador necesitará una indicación de esquema para leerlas como marcas de tiempo. Y todas ganan una parte de milisegundos que no estaba en el manifiesto: `07:32:00` se convierte en `07:32:00.000`, lo que da igual para comparar instantes y rompe cualquier comparación contra un literal escrito en la forma corta.

`inf` y `nan` son literales válidos en TOML y JSON no tiene manera de representarlos, así que ambos se escriben como `null`. Un límite configurado como infinito y un límite sin configurar acaban idénticos en el conjunto de datos, y nada lo advierte por el camino.

La distinción entre entero y flotante también se va: `1.0` se serializa como `1`. Importa si una consulta pretende distinguir una versión de un recuento, o si vas a comparar el campo con lo que escribió otro equipo. Cuando esos valores son significativos, entrecomíllalos en el TOML para que crucen como texto.

TOML 1.0 exige enteros de 64 bits con signo y los números de JSON son dobles de coma flotante, así que un valor por encima de unos nueve mil billones no puede representarse con exactitud. Comprobado con `a = 9223372036854775807`: el analizador se detiene con un error que dice que el valor entero no puede representarse sin pérdida y señala la línea, en lugar de escribir un número redondeado.

Para un inventario ése es justamente el comportamiento correcto. Un número mal a lo largo de diez mil registros es indistinguible de uno bien, y descubrirlo seis meses después no arregla las consultas ya hechas. Cuando ocurra, entrecomilla el valor en el archivo de origen: en todos los casos reales en los que aparece se trata de un identificador y no de una cantidad.

Las configuraciones de proyectos distintos no tienen las mismas secciones. Una declara una tabla de herramientas con tres analizadores dentro, la siguiente no declara ninguna, la tercera usa una clave que no usa nadie más. Cada línea lleva sólo las claves de su archivo, lo cual es una ventaja real frente a aplanar la misma colección en una tabla donde las columnas tendrían que ser la unión de todo.

Cuánto cuesta eso lo decide el destino. Un almacén que aplica el esquema al leer maneja registros irregulares de forma nativa y permite preguntar por una clave que sólo tienen algunos. Un cargador con esquema fijo rechazará los casos raros o descartará los campos. Mira el archivo más amplio y el más escueto de la colección antes de definir el destino, no después de cargar ocho mil registros.

Los comentarios de un TOML son el razonamiento de la configuración: por qué una dependencia está fijada, a qué incidencia pertenece un apaño, qué significa un número mágico. NDJSON es JSON por línea y JSON no tiene sintaxis de comentarios, así que todo eso desaparece del conjunto.

Es aceptable para un inventario e inaceptable como migración. Quien pregunta qué paquetes fijan una versión no necesita la prosa de alrededor; quien pretendiera sustituir los TOML por algo generado a partir de estos datos la estaría tirando. Usa el flujo para hacer preguntas sobre las configuraciones y deja las configuraciones donde están.

Si sólo tienes una configuración que leer, conviértela a JSON. El JSON con sangría se lee, `jq` lo trata igual y un archivo de una única línea es peor para todo excepto para añadirlo a otro. NDJSON se gana el sitio en el momento en que hay muchos archivos y van a parar a algún sitio.

La otra frontera es la repetición. Si el inventario hay que rehacerlo cada trimestre, el trabajo pertenece a un script que recorra el árbol, analice cada archivo con una biblioteca TOML de verdad y emita las líneas con la ruta ya puesta. Este conversor sirve para montar el conjunto la primera vez, decidir si las preguntas que responde merecen automatizarse, y hacerlo sin que ninguno de los archivos salga de tu equipo.

El análisis y la escritura son JavaScript corriente dentro de esta pestaña. No se descarga ningún motor, no se sube nada, no hay cuenta ni cupo diario, y el tope de 100 MB por archivo lo superará ningún manifiesto jamás: éstos se miden en kilobytes.

Que no salgan importa porque un archivo de configuración no siempre es inocuo. Un `pyproject.toml` puede llevar la dirección de un registro interno, un `Cargo.toml` puede apuntar a un repositorio privado por SSH, y hay configuraciones de herramientas con credenciales dentro que nunca debieron estar ahí. Que la conversión no las transmita es lo que hace que puedas hacer esto en el trabajo.