Converter TOML para NDJSON

Um documento TOML é uma tabela. Não existe arquivo TOML que seja uma lista no nível raiz — a especificação não permite — então a fronteira de registro que o NDJSON precisa nunca aparece dentro de um único arquivo. O documento inteiro vira uma linha.

Para a maioria das origens isso seria uma limitação. Aqui é a forma do problema: ninguém quer um pyproject.toml dividido em fragmentos, e todo mundo que converte um para NDJSON está construindo uma coleção onde cada arquivo é um registro. A unidade do formato e a unidade da pergunta coincidem, o que não é verdade em todo par deste site.

O fluxo é: converta cada arquivo, anexe a linha a uma saída crescente. Como cada linha é um valor JSON completo e independente e nada envolve o arquivo — sem array externo, sem vírgulas entre registros — concatenar é toda a etapa de junção. Duas linhas de duas conversões são um NDJSON válido de dois registros.

O que isso dá é um conjunto de dados que você consegue consultar. Quais crates fixam uma versão específica de dependência, quais pacotes não declaram licença, quais repositórios ainda usam uma edição antiga — tudo isso vira uma consulta sobre a coleção em vez de um script que percorre diretórios e interpreta arquivos.

Um registro sem origem é quase inútil num inventário. O conversor lê o conteúdo de um arquivo e nada mais — não sabe o caminho, o repositório nem o commit — então a linha que produz não tem campo dizendo de onde veio.

Adicione você mesmo, em um de dois momentos. Uma passada com jq durante a concatenação pode injetar uma chave de caminho por linha, mantendo os arquivos TOML intocados. Alternativamente, uma chave dentro de cada arquivo TOML o nomeia, o que sobrevive a toda conversão futura mas significa editar arquivos que pertencem a outras pessoas.

JSON compacto: sem indentação, sem espaços depois de dois-pontos, chaves na ordem que o TOML declarou, terminando com uma quebra de linha. Tabelas viram objetos aninhados e arrays de tabelas viram arrays de objetos, então uma lista de autores ou um conjunto de alvos de build chega na forma que um motor de consulta espera.

A linha é tão longa quanto o config for. Um pyproject.toml tem alguns kilobytes e um config gerado ao lado de um lockfile pode ser bem maior, e um leitor que processa uma linha por vez precisa manter a linha inteira na memória. Isso raramente é problema em tamanho de config, mas vale saber.

TOML tem tipos temporais reais e JSON não, então toda data e data-hora vira string. Deslocamentos de fuso sobrevivem em vez de ser normalizados para UTC, uma data local chega exatamente como escrita, e uma hora local ganha um componente de milissegundo que não tinha na origem.

Dois literais de ponto flutuante têm perda de um jeito que nada relata: inf e nan são TOML válido e viram null em JSON, então um limite infinito configurado e um não configurado ficam indistinguíveis no conjunto de dados. A distinção entre inteiro e float também se perde, já que 1.0 serializa como 1.

TOML 1.0 exige inteiros de 64 bits assinados e números JSON são doubles IEEE, então um valor acima de aproximadamente nove quatrilhões não pode ser representado exatamente. O interpretador para com um erro nomeando a linha em vez de escrever um número arredondado no seu conjunto de dados.

Esse é o comportamento correto especialmente para um inventário, onde um número errado seria indistinguível de um certo entre dez mil registros. Quando isso acontecer, coloque o valor entre aspas como string no arquivo de origem — era um identificador, não uma quantidade, em todo caso real em que isso aparece.

Configs de projetos diferentes não vão ter as mesmas seções. Um declara uma tabela de ferramenta com três linters, o próximo não declara nenhuma, um terceiro usa uma chave que ninguém mais usa. Toda linha carrega só as chaves que seu arquivo tinha, uma vantagem real sobre achatar a mesma coleção numa tabela onde as colunas teriam que ser a união de tudo.

O destino decide quanto isso custa. Um banco com schema na leitura lida nativamente com registros irregulares. Um carregador com schema fixo vai rejeitar os casos fora do padrão ou descartar os campos. Amostre os arquivos mais largos e mais estreitos da coleção antes de definir o destino.

Se você só tem um config para ler, converta para JSON em vez disso. JSON indentado é legível, o jq lida igual, e um arquivo de uma linha é pior para todo propósito exceto anexar. O NDJSON ganha seu espaço no ponto em que há muitos arquivos e eles estão indo para algum lugar.

A outra fronteira é recorrência. Se o inventário precisa ser reconstruído numa agenda, o trabalho pertence a um script que percorre a árvore, interpreta cada arquivo com uma biblioteca TOML de verdade e emite as linhas já com o caminho anexado. Este conversor é para construir o conjunto de dados pela primeira vez.