@writedocs/generator 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {
@@ -20,7 +20,8 @@
     "build": "node bin/writedocs.js build",
     "init": "node bin/writedocs.js init",
     "build:schema": "esbuild src/lib/config-schema.ts --format=esm --target=node22 --outfile=src/lib/config-schema.js",
-    "prepare": "npm run build:schema"
+    "prepare": "npm run build:schema",
+    "test": "node --test \"scripts/*.test.js\""
   },
   "keywords": [
     "docs",

package/src/lib/config-schema.js

@@ -464,15 +464,33 @@ function issuesDoRamo(ramo) {
   const comIssues = ramo;
   return comIssues?.issues ?? [];
 }
+function maiorProfundidade(lista) {
+  let maior = 0;
+  for (const issue of lista) {
+    const p = issue.caminho.length + (issue.code === "unrecognized_keys" ? 1 : 0);
+    if (p > maior) maior = p;
+  }
+  return maior;
+}
+const planoPorRamo = /* @__PURE__ */ new WeakMap();
+function planoDoRamo(ramo) {
+  const lista = issuesDoRamo(ramo);
+  if (typeof ramo !== "object" || ramo === null) return desembrulharUnioes(lista);
+  const memoizado = planoPorRamo.get(ramo);
+  if (memoizado) return memoizado;
+  const plano = desembrulharUnioes(lista);
+  planoPorRamo.set(ramo, plano);
+  return plano;
+}
 function melhorRamo(ramos) {
   return ramos.map((ramo) => {
-    const lista = issuesDoRamo(ramo);
+    const plano = planoDoRamo(ramo);
     return {
-      lista,
-      n: lista.length,
-      profundidade: Math.max(0, ...lista.map((i) => (i.path ?? []).length))
+      lista: issuesDoRamo(ramo),
+      n: plano.length,
+      profundidade: maiorProfundidade(plano)
     };
-  }).sort((a, b) => a.n - b.n || b.profundidade - a.profundidade)[0].lista;
+  }).sort((a, b) => b.profundidade - a.profundidade || a.n - b.n)[0].lista;
 }
 function desembrulharUnioes(issues, prefixo = []) {
   const saida = [];

package/src/lib/config-schema.ts

@@ -1062,15 +1062,84 @@ function issuesDoRamo(ramo: unknown): IssueCru[] {
   return comIssues?.issues ?? [];
 }
 
+/** O maior valor de `f` sobre a lista, ou 0 se ela for vazia. Um `for` e nao
+ *  `Math.max(0, ...lista.map(f))`: o spread vira argumentos de chamada, e uma
+ *  lista grande o bastante (config com dezenas de milhares de erros) estoura o
+ *  limite de argumentos com RangeError em vez de devolver um numero. */
+function maiorProfundidade(lista: IssuePlano[]): number {
+  let maior = 0;
+  for (const issue of lista) {
+    const p = issue.caminho.length + (issue.code === 'unrecognized_keys' ? 1 : 0);
+    if (p > maior) maior = p;
+  }
+  return maior;
+}
+
+/** Plano ACHATADO de um ramo, memoizado por identidade do ramo.
+ *
+ *  A memoizacao nao e otimizacao, e o que torna o achatamento viavel. Pontuar um
+ *  ramo exige desembrulhar as unioes DENTRO dele, e cada uma dessas tem os seus
+ *  proprios ramos - sem cache, a pontuacao visita o mesmo sub-ramo uma vez por
+ *  caminho que leva ate ele, o que e exponencial na profundidade do aninhamento.
+ *  Medido com grupos aninhados e um erro no fundo: 3,7 ms com 4 niveis, 281 ms
+ *  com 8, 69 SEGUNDOS com 12. Com o cache, os mesmos casos ficam em 0,2 ms,
+ *  porque cada no da arvore de erro do Zod e achatado uma vez so.
+ *
+ *  Se alguem remover este WeakMap por parecer supérfluo, o `writedocs validate`
+ *  passa a travar em configs profundas. Nao remova. */
+const planoPorRamo = new WeakMap<object, IssuePlano[]>();
+
+function planoDoRamo(ramo: unknown): IssuePlano[] {
+  const lista = issuesDoRamo(ramo);
+  if (typeof ramo !== 'object' || ramo === null) return desembrulharUnioes(lista);
+  const memoizado = planoPorRamo.get(ramo);
+  if (memoizado) return memoizado;
+  // Prefixo vazio de proposito: a pontuacao compara ramos entre si, entao a
+  // profundidade tem que ser relativa ao proprio ramo, nao ao documento.
+  const plano = desembrulharUnioes(lista);
+  planoPorRamo.set(ramo, plano);
+  return plano;
+}
+
 /** Escolhe qual ramo de uma uniao o cliente PROVAVELMENTE quis.
  *
- *  Criterio: menos issues primeiro; empate resolvido pelo caminho mais fundo. A
+ *  Criterio: caminho mais fundo primeiro; empate resolvido por menos issues. A
  *  intuicao e a do Gabriel na spec - o ramo certo e o que nao reclama da chave
  *  que o cliente usou -, e a profundidade importa porque um ramo que chegou
  *  fundo antes de falhar (`products.0.product`) reconheceu a forma, enquanto um
  *  que falha na raiz (`expected array, received object`) so recusou o shape.
  *
- *  EMPATE TOTAL (mesmo numero de issues E mesma profundidade): vence o ramo
+ *  DUAS CORRECOES sobre a primeira versao (WD-063), as duas medidas contra o
+ *  `00-kitchen-sink` real - ver o relato de revisao 43:
+ *
+ *  1. PONTUA O RAMO ACHATADO, nao a lista crua. Um ramo que e ele proprio uma
+ *     uniao aparece como UM issue (`invalid_union`) no caminho vazio - ou seja,
+ *     com a MENOR contagem e a MENOR profundidade possiveis, sem que isso diga
+ *     nada sobre o quanto ele reconheceu. Era o caso mais comum que existe: um
+ *     item de `pages` e `string | grupo | link`, e o grupo e outra uniao, entao
+ *     todo erro estrutural dentro de um grupo empatava com o ramo `string` e
+ *     perdia pela ordem de declaracao. O cliente que escrevia
+ *     `{ "group": "G", "pages": 42 }` recebia "expected string, received
+ *     object" - conselho errado, nao so inutil. Achatando primeiro, o mesmo caso
+ *     vira `pages.0.pages: expected array, received number`.
+ *
+ *  2. PROFUNDIDADE EFETIVA: `unrecognized_keys` reporta no caminho do PAI, com a
+ *     chave ofensora em `keys`, entao a profundidade dele sai subestimada em 1.
+ *     Sem a correcao, um ramo que identificou a chave errada perde para um que
+ *     so exigiu um campo ausente. (`validateDocsConfig` ja fazia a mesma conta
+ *     para achar a LINHA; aqui ela entra tambem na pontuacao.)
+ *
+ *  Medido sobre as 60 folhas da `navigation` do `00-kitchen-sink`, trocando o
+ *  tipo de cada uma: a versao anterior apontava o campo exato em 42/60 e PARAVA
+ *  RASO em 18/60 (sempre os mesmos 18: os que ficam sob um `pages`); esta aponta
+ *  60/60 para valor escalar errado e nunca para raso. Para um objeto vazio ou
+ *  parcial no lugar de uma pagina, as duas ficam tecnicamente empatadas (41
+ *  contra 42): a anterior diz "expected string", esta lista os campos que
+ *  faltam para ser um grupo. E o custo aceito desta versao, e substitui o antigo
+ *  (`tabs` e `products` escritos juntos, que agora sai como
+ *  `Unrecognized key: "products"`).
+ *
+ *  EMPATE TOTAL (mesma profundidade E mesmo numero de issues): vence o ramo
  *  declarado primeiro no schema. `Array.prototype.sort` e estavel desde a
  *  ES2019, entao ordenar e pegar o [0] ja entrega isso - se alguem trocar por
  *  uma ordenacao instavel, o desempate vira sorteio. Duas razoes para "o
@@ -1084,14 +1153,14 @@ function issuesDoRamo(ramo: unknown): IssueCru[] {
 function melhorRamo(ramos: unknown[]): IssueCru[] {
   return ramos
     .map((ramo) => {
-      const lista = issuesDoRamo(ramo);
+      const plano = planoDoRamo(ramo);
       return {
-        lista,
-        n: lista.length,
-        profundidade: Math.max(0, ...lista.map((i) => (i.path ?? []).length)),
+        lista: issuesDoRamo(ramo),
+        n: plano.length,
+        profundidade: maiorProfundidade(plano),
       };
     })
-    .sort((a, b) => a.n - b.n || b.profundidade - a.profundidade)[0].lista;
+    .sort((a, b) => b.profundidade - a.profundidade || a.n - b.n)[0].lista;
 }
 
 /** Desembrulha `invalid_union` recursivamente - o ramo escolhido normalmente e