Encontre seu caminho em um bundle grande: okf 1.11.0

A okf é uma gem Ruby para trabalhar com bundles OKF, onde um bundle é um diretório de arquivos markdown e cada arquivo é um conceito, lidos por você e pelo seu agente da mesma fonte (o que é OKF, se esta é sua primeira olhada).

Um bundle pequeno não precisa de navegação. Você lista, você lê, acabou. Em algum ponto depois de uns cem conceitos isso deixa de ser verdade, e a ferramenta que estava ajudando passa a te entregar mais do que você consegue segurar: o okf index devolve a árvore de diretórios inteira, e a árvore é justamente o que você estava tentando não ler de uma vez.

A okf 1.11.0 é sobre essa lacuna. O diretório vira algo sobre o qual você pergunta, que você corta e pelo qual você filtra, em todo verbo que lê.

okf dirs: a forma, e onde está o peso

$ okf dirs ./.okf

Todo diretório que a árvore tem, com o número de conceitos que moram diretamente em cada um, a raiz primeiro e o total por último. Qualquer caminho de bundle funciona, e @seu-bundle nomeia a mesma coisa depois que o bundle está registrado.

Diretórios intermediários vazios, os que existem só para conectar a árvore, aparecem como 0 em vez de serem silenciosamente somados aos filhos, então a coluna fecha com a contagem real de conceitos do bundle. Cada linha também carrega uma contagem subtree definida como exatamente o que --dir naquela linha devolve, então o número e a flag nunca podem discordar. A tabela humana só imprime essa coluna onde algum diretório de fato aninha; o --json sempre a carrega. Sem isso, uma árvore profunda lê como só zeros no topo, que é justamente onde você ia perguntar onde está a massa.

--depth: um mapa do qual você pode pedir menos

O --depth N no index e no dirs limita quantos níveis de diretório abaixo do ponto de partida você mantém. No bundle da própria gem, 29 conceitos em 5 diretórios:

$ okf index @okf --json | wc -c
14345
$ okf index @okf --json --depth 0 | wc -c
2099

14.345 bytes viram 2.099, e cada palavra da prosa autorada da raiz continua ali, junto com os nomes dos diretórios abaixo dela. O que o corte remove é o texto dentro desses diretórios, que você pede um nível por vez.

O tamanho dessa economia é o tamanho da sua árvore, e nada além disso. O @okf tem um nível de profundidade, então o --depth 1 nele devolve os 14.345 bytes inteiros, sem mudança: não há nada abaixo do nível 1 para cortar, e a flag não finge o contrário. É numa árvore profunda que ela se paga.

Descarte também o texto e as listagens por diretório e vai mais longe ainda, para 1.461 bytes com --except body,listing, mas fique claro sobre qual flag comprou qual corte: o --depth escolhe quanta árvore você mantém, o --except body é o que remove o que as pessoas escreveram.

O corte é relativo, não absoluto. O ponto de partida é o --dir quando você dá um, e a raiz do bundle quando não dá, então --dir a/b --depth 1 lê "a/b e um nível abaixo dele" sem você ter que descobrir antes quão fundo a/b está. Subida e descida seguem eixos separados, e é por isso que o --depth nunca limita a corrente de volta até a raiz.

Estreite para um galho e os ancestrais sobem junto, a prosa do index.md da raiz primeiro entre eles, então um diretório nunca é mostrado à deriva do contexto autorado que diz o que ele é. Essas linhas saem com uma seta à frente, ficam fora do total, e o --no-ancestors as descarta.

--dir: um filtro, a mesma regra em todo lugar

O --dir PATH entra no conjunto de filtros compartilhado por search, catalog, files, types e tags, e o index o aceita como seletor repetível.

Uma regra governa todos eles: um conceito casa quando o dir dele é o caminho ou fica abaixo dele. Então --dir platform alcança platform/services/api, --dir platform/services estreita, e --dir . significa a raiz sozinha, sem caso especial. root é a grafia sem aspas de ., e o casamento ignora maiúsculas.

Em volta disso, os rollups se atualizaram. O tags --by dir corta o índice de tags pelo caminho inteiro. O stats ganhou dirs e by_dir, lidos do mesmo mapa que o okf dirs lista, então os dois verbos não conseguem reportar um número diferente de diretórios. As linhas de busca agora carregam o dir completo ao lado do primeiro segmento que já tinham.

O --area e o tags --by area estão depreciados nesta release. Os dois só enxergavam o primeiro segmento do caminho de um conceito, que é o nível que o --dir e o --by dir agora cobrem inteiro. Eles mantêm o comportamento antigo exatamente e avisam uma vez por execução no stderr, com o --json no stdout intocado, e saem numa release futura. Juntar --area com --depth ou --dir passa a ser recusado (saída 2), porque a flag antiga respondia com a união dos dois, que é uma resposta a nenhuma das duas perguntas.

Um bundle servido para de reconstruir o índice de busca a cada request

Todo request a um bundle servido reconstruía o corpus de busca inteiro do zero. Toda consulta pagava por uma construção completa de índice antes de conseguir ranquear qualquer coisa, um custo que cresce junto com o bundle e que você sentia em cada ida e volta entre tecla e resultado.

O corpus agora é construído uma vez e mantido, com a construção movida para o boot, onde o okf server a aquece de propósito. Uma consulta agora custa o que consultar custa, e não carrega mais o custo de montar aquilo que está sendo consultado.

Um corpus mantido é um retrato, do mesmo jeito que o grafo é, então o hub o descarta a qualquer escrita no registry. Um índice mantido sobrevivendo ao conjunto de que foi construído é uma resposta errada em vez de uma resposta lenta, e lenta é a falha melhor.

Um servidor de bundle único finalmente busca em si mesmo

O GET /search?q= era rota só do hub, concebida como a rota entre bundles. Isso deixava o okf server ./docs com uma paleta Cmd-K que não achava nada, mesmo com um bundle sendo um conjunto de um elemento perfeitamente legal. Um servidor de bundle único e o hub agora respondem com a mesma forma de busca, então um cliente escrito contra um funciona contra o outro sem mudança. Uma linha vinda de um servidor de bundle único não carrega slug, que é como ela evita responder como se fosse um conjunto.

Um okf render estático segue sem anunciar endpoint nenhum, porque não há servidor atrás dele para perguntar.

O modo cluster segue a árvore de diretórios

A página do grafo agrupava conceitos numa fila achatada de caixas, uma por primeiro segmento de caminho, a mesma projeção com perda que o --area era. Um cluster é um diretório agora, e as caixas aninham do jeito que os diretórios aninham, até uma profundidade que você escolhe num select ao lado do de layout. A profundidade 1 é o padrão e desenha exatamente a visão antiga, um bundle plano não recebe controle nenhum, e um toque numa caixa segue abrindo o mapa daquele diretório.

A outra mudança é nas suas mãos. Uma caixa de cluster é cenário, não alça: o interior vazio dela é o maior alvo de arraste da tela, então arrastar para olhar em volta arrastava o diretório em vez da vista, e quanto maior o cluster, pior. O arraste simples agora move a tela, e o ⌥ drag move uma caixa quando você quer isso mesmo, listado na folha do ?.

Também corrigido

• O --dir aceita o rótulo que as visões imprimem. O okf index rotula uma linha como tables/, e colar isso de volta na flag não casava nada e saía com 0: um resultado vazio sob uma contagem que concordava com ele.
• A corrente do --dir preserva as maiúsculas, então ancestrais de um diretório escrito com maiúscula param de sumir da corrente que existe para situar o galho.
• Um acerto da paleta num servidor de bundle único não dá mais 404 nem recarrega a página inteira para chegar num nó que já estava na tela.

Atualizando

$ gem update okf

Se você embute a biblioteca, OKF::Server::Hub::SEARCH_LIMIT e Hub::SEARCH_ENGINE foram removidos. Os dois migraram para OKF::Server::App, que agora define o payload de /search com que os dois hosts respondem, então leia OKF::Server::App::SEARCH_LIMIT e App::SEARCH_ENGINE no lugar. Se você usa a CLI em scripts, o --area e o tags --by area ainda funcionam e agora avisam, então troque por --dir e --by dir antes de uma release futura tirá-los.

Como obter

$ okf dirs ./.okf
$ okf index ./.okf --depth 1

Qualquer caminho de bundle funciona e nada precisa estar registrado antes. O okf registry set . dá um nome àquele bundle, e daí @seu-bundle o endereça de qualquer diretório. Novo na okf: gem install okf, e depois comece por aqui.

O que a página do grafo faz com essa mesma árvore chega na 1.12.0. O detalhe completo está no changelog.