@writedocs/generator 0.2.1 → 0.4.0

package/bin/writedocs.js

@@ -22,7 +22,11 @@ import { requireBuildKey } from '../src/cli/build-auth.js';
 // gerado do `.ts` pelo script `prepare` (package.json), entao ele existe tanto
 // no checkout quanto dentro do tarball, e o consumidor nao roda build nenhum.
 // Ver a mesma regra ja escrita em src/cli/write-redirects-file.js.
-import { validateDocsConfig, formatValidationIssues } from '../src/lib/config-schema.js';
+import {
+  validateDocsConfig,
+  formatValidationIssuesDetailed,
+  unknownRootKeyIssues,
+} from '../src/lib/config-schema.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '..');
@@ -92,17 +96,33 @@ program
       process.exit(1);
     }
 
-    const result = validateDocsConfig(fs.readFileSync(configPath, 'utf-8'));
-    if (result.ok) {
-      console.log(`[writedocs] ${configPath} is valid.`);
-      return;
+    const rawText = fs.readFileSync(configPath, 'utf-8');
+    const result = validateDocsConfig(rawText);
+    // Chave desconhecida na raiz e AVISO, nunca erro: a raiz nao e `.strict()`
+    // de proposito (tornar strict quebraria configs existentes), entao o Zod
+    // descarta a chave em silencio. Sem JSON parseavel nao ha chave pra avaliar.
+    const warnings = result.kind === 'invalid_json' ? [] : unknownRootKeyIssues(rawText);
+    const nomeArquivo = path.basename(configPath);
+
+    if (!result.ok) {
+      // A versao longa (linha, frase humana, sugestao) em vez da curta que o
+      // `writedocs build` imprime: aqui o usuario pediu explicitamente um
+      // diagnostico, e tem a tela inteira pra ele.
+      console.error(`[writedocs] ${configPath} failed validation:\n`);
+      console.error(formatValidationIssuesDetailed(result.issues, { fileName: nomeArquivo }));
+      console.error('');
+    }
+
+    if (warnings.length > 0) {
+      console.error(`[writedocs] ${warnings.length} warning${warnings.length === 1 ? '' : 's'}:\n`);
+      console.error(formatValidationIssuesDetailed(warnings, { fileName: nomeArquivo }));
+      console.error('');
     }
 
-    // Mesmo formato que o build imprime num config invalido - mesmo texto,
-    // mesma ordem, montado pelo mesmo formatador.
-    console.error('[writedocs] writedocs.json failed validation:');
-    console.error(formatValidationIssues(result.issues));
-    process.exit(1);
+    if (!result.ok) process.exit(1);
+    // Aviso nao invalida: um config so com avisos continua valido, e sai 0 -
+    // o mesmo criterio que a plataforma usa pra marcar o projeto como `valid`.
+    console.log(`[writedocs] ${configPath} is valid.`);
   });
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.2.1",
+  "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",
@@ -65,6 +66,7 @@
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",
     "gray-matter": "^4.0.3",
+    "jsonc-parser": "3.3.1",
     "katex": "^0.16.47",
     "mermaid": "^11.16.0",
     "pagefind": "^1.5.2",

package/src/lib/config-schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { findNodeAtLocation, parseTree } from "jsonc-parser";
 const navPageSchema = z.string();
 const navGroupPagesSchema = z.lazy(
   () => z.object({
@@ -446,6 +447,210 @@ function positionFromJsonError(message, rawText) {
 function formatValidationIssues(issues) {
   return issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n");
 }
+function formatValidationIssuesDetailed(issues, { fileName = "writedocs.json" } = {}) {
+  return issues.map((i) => {
+    const temCampo = i.path !== "(root)";
+    const local = i.line ? `${fileName}:${i.line}` : i.path;
+    const linhas = [`  ${local}${i.line && temCampo ? `  (${i.path})` : ""}`];
+    linhas.push(`    ${i.humanMessage ?? i.message}`);
+    if (i.suggestion) linhas.push(`    ${i.suggestion}`);
+    if (i.humanMessage && i.message !== i.humanMessage) linhas.push(`    (${i.message})`);
+    return linhas.join("\n");
+  }).join("\n\n");
+}
+const ROOT_ALLOWED_EXTRA_KEYS = Object.freeze(["$schema"]);
+function issuesDoRamo(ramo) {
+  if (Array.isArray(ramo)) return 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 plano = planoDoRamo(ramo);
+    return {
+      lista: issuesDoRamo(ramo),
+      n: plano.length,
+      profundidade: maiorProfundidade(plano)
+    };
+  }).sort((a, b) => b.profundidade - a.profundidade || a.n - b.n)[0].lista;
+}
+function desembrulharUnioes(issues, prefixo = []) {
+  const saida = [];
+  for (const issue of issues) {
+    const caminho = [...prefixo, ...issue.path ?? []];
+    const ramos = issue.code === "invalid_union" ? issue.errors ?? issue.unionErrors : null;
+    if (Array.isArray(ramos) && ramos.length > 0) {
+      saida.push(...desembrulharUnioes(melhorRamo(ramos), caminho));
+    } else {
+      saida.push({ ...issue, caminho });
+    }
+  }
+  return saida;
+}
+function criarLocalizador(rawText) {
+  let arvore;
+  try {
+    arvore = parseTree(rawText);
+  } catch {
+    arvore = void 0;
+  }
+  return (caminho) => {
+    if (!arvore || caminho.length === 0) return null;
+    const no = findNodeAtLocation(arvore, caminho);
+    if (!no) return null;
+    const antes = rawText.slice(0, no.offset);
+    return { line: antes.split("\n").length, column: no.offset - antes.lastIndexOf("\n") };
+  };
+}
+function docKeyDoCaminho(caminho) {
+  const primeiro = caminho[0];
+  return typeof primeiro === "string" && primeiro ? `config.${primeiro}` : "config";
+}
+const ARTIGO_POR_TIPO = {
+  string: "a piece of text",
+  number: "a number",
+  boolean: "true or false",
+  array: "a list",
+  object: "an object",
+  null: "null"
+};
+const COMO_ESCREVER = {
+  string: 'Write the value in double quotes, like "Core Platform".',
+  number: "Write the value as a bare number, like 3 - no quotes.",
+  boolean: "Write true or false - no quotes.",
+  array: "Write the value as a list in square brackets: [ ... ].",
+  object: "Write the value as an object in curly braces: { ... }."
+};
+function tipoReal(valor) {
+  if (valor === void 0) return "missing";
+  if (valor === null) return "null";
+  if (Array.isArray(valor)) return "array";
+  return typeof valor;
+}
+function valorEm(raiz, caminho) {
+  let atual = raiz;
+  for (const passo of caminho) {
+    if (atual === null || typeof atual !== "object") return void 0;
+    atual = atual[passo];
+  }
+  return atual;
+}
+function comoCampo(caminho) {
+  return caminho.length > 0 ? `"${caminho.join(".")}"` : "writedocs.json";
+}
+function fraseChaveDesconhecida(chaves, dentroDe) {
+  const onde = dentroDe.length > 0 ? ` inside "${dentroDe.join(".")}"` : "";
+  const lista = chaves.map((k) => `"${k}"`).join(", ");
+  return {
+    humanMessage: chaves.length === 1 ? `${lista} is not a writedocs.json option${onde}.` : `${lista} are not writedocs.json options${onde}.`,
+    suggestion: "Remove it, or check the spelling - options are case-sensitive."
+  };
+}
+function humanizar(issue, raiz) {
+  const campo = comoCampo(issue.caminho);
+  switch (issue.code) {
+    case "invalid_type": {
+      const esperado = issue.expected ?? "a different type";
+      const recebido = tipoReal(valorEm(raiz, issue.caminho));
+      if (recebido === "missing") {
+        return {
+          humanMessage: `${campo} is required, but writedocs.json does not set it.`,
+          suggestion: `Add ${campo} with ${ARTIGO_POR_TIPO[esperado] ?? `a ${esperado}`} as its value.`
+        };
+      }
+      return {
+        humanMessage: `${campo} must be ${ARTIGO_POR_TIPO[esperado] ?? `a ${esperado}`}, but writedocs.json has ${ARTIGO_POR_TIPO[recebido] ?? `a ${recebido}`}.`,
+        suggestion: COMO_ESCREVER[esperado]
+      };
+    }
+    case "unrecognized_keys": {
+      const chaves = issue.keys ?? [];
+      if (chaves.length === 0) return {};
+      return fraseChaveDesconhecida(chaves, issue.caminho);
+    }
+    case "invalid_value": {
+      const opcoes = (issue.values ?? []).map((v) => JSON.stringify(v)).join(", ");
+      return {
+        humanMessage: `${campo} must be one of: ${opcoes}.`,
+        suggestion: "Replace the value with one of the options above."
+      };
+    }
+    case "too_small": {
+      const unidade = issue.origin === "array" ? "item" : "character";
+      const minimo = issue.minimum ?? 1;
+      return {
+        humanMessage: `${campo} needs at least ${minimo} ${unidade}${minimo === 1 ? "" : "s"}.`,
+        suggestion: issue.origin === "array" ? "Add an entry, or remove the field entirely." : void 0
+      };
+    }
+    case "too_big": {
+      const unidade = issue.origin === "array" ? "item" : "character";
+      const maximo = issue.maximum ?? 0;
+      return { humanMessage: `${campo} allows at most ${maximo} ${unidade}${maximo === 1 ? "" : "s"}.` };
+    }
+    case "invalid_format":
+      return {
+        humanMessage: `${campo} is not a valid ${issue.format ?? "value"}.`,
+        suggestion: "Check the format against the documentation for this field."
+      };
+    case "invalid_union":
+      return {
+        humanMessage: `${campo} does not match any of the shapes writedocs.json accepts here.`,
+        suggestion: "Check the documentation for the shapes this field accepts."
+      };
+    case "custom":
+      return { humanMessage: issue.message };
+    default:
+      return {};
+  }
+}
+function unknownRootKeyIssues(rawText) {
+  let raiz;
+  try {
+    raiz = JSON.parse(rawText);
+  } catch {
+    return [];
+  }
+  if (raiz === null || typeof raiz !== "object" || Array.isArray(raiz)) return [];
+  const conhecidas = /* @__PURE__ */ new Set([...Object.keys(docsConfigSchema.shape), ...ROOT_ALLOWED_EXTRA_KEYS]);
+  const localizar = criarLocalizador(rawText);
+  return Object.keys(raiz).filter((chave) => !conhecidas.has(chave)).map((chave) => {
+    const frase = fraseChaveDesconhecida([chave], []);
+    return {
+      path: chave,
+      // O mesmo formato singular da mensagem `unrecognized_keys` do Zod, pra
+      // que aviso e erro sejam indistinguiveis por quem so le `message`.
+      message: `Unrecognized key: "${chave}"`,
+      code: "unrecognized_keys",
+      ...localizar([chave]) ?? {},
+      ...frase,
+      // `config`, e NAO `config.<chave>`: a chave aqui e o que o cliente
+      // digitou errado, e derivar a docKey dela faria cada erro de digitacao
+      // inventar uma chave nova. O conjunto de docKeys tem que ser fechado -
+      // `config` mais um por campo do schema, nada alem disso -, senao quem
+      // mapeia chave -> URL do outro lado nao tem lista pra mapear.
+      docKey: "config"
+    };
+  });
+}
 function validateDocsConfig(rawText) {
   let raw;
   try {
@@ -458,28 +663,48 @@ function validateDocsConfig(rawText) {
       data: null,
       kind: "invalid_json",
       parseError,
-      issues: [{ path: "(root)", message: parseError.message, code: "invalid_json", ...posicao ?? {} }]
+      issues: [
+        {
+          path: "(root)",
+          message: parseError.message,
+          code: "invalid_json",
+          ...posicao ?? {},
+          humanMessage: "writedocs.json is not valid JSON, so none of it could be checked.",
+          suggestion: posicao ? `Look at line ${posicao.line} - a missing comma, an extra trailing comma, or an unclosed bracket is the usual cause.` : "A missing comma, an extra trailing comma, or an unclosed bracket is the usual cause.",
+          docKey: "config"
+        }
+      ]
     };
   }
   const result = docsConfigSchema.safeParse(raw);
   if (!result.success) {
+    const localizar = criarLocalizador(rawText);
     return {
       ok: false,
       data: null,
       kind: "schema",
-      issues: result.error.issues.map((i) => ({
-        path: i.path.join(".") || "(root)",
-        message: i.message,
-        code: i.code
-      }))
+      issues: desembrulharUnioes(result.error.issues).map((i) => {
+        const alvoDaLinha = i.code === "unrecognized_keys" && i.keys?.length ? [...i.caminho, i.keys[0]] : i.caminho;
+        return {
+          path: i.caminho.join(".") || "(root)",
+          message: i.message,
+          code: i.code,
+          ...localizar(alvoDaLinha) ?? localizar(i.caminho) ?? {},
+          ...humanizar(i, raw),
+          docKey: docKeyDoCaminho(i.caminho)
+        };
+      })
     };
   }
   return { ok: true, data: result.data, issues: [] };
 }
 export {
+  ROOT_ALLOWED_EXTRA_KEYS,
   docsConfigSchema,
   formatValidationIssues,
+  formatValidationIssuesDetailed,
   mergeSeo,
   seoFieldsSchema,
+  unknownRootKeyIssues,
   validateDocsConfig
 };

package/src/lib/config-schema.ts

@@ -24,6 +24,13 @@
 // entao a troca nao muda comportamento nenhum, so tira o astro do caminho de
 // quem importa isto de fora do gerador.)
 import { z } from 'zod';
+// WD-063: `parseTree` + `findNodeAtLocation` traduzem o caminho de um erro
+// (`navigation.products.0.product`) para o offset dele no TEXTO, que e o que
+// vira linha. E o parser de JSON do VS Code: zero dependencias, nada de `node:`,
+// entao continua bundlavel pro Worker da plataforma. Escrever o scanner a mao
+// foi tentado e deu errado (perdia todo caminho aninhado, que e justamente o que
+// importa aqui) - nao repita.
+import { findNodeAtLocation, parseTree } from 'jsonc-parser';
 
 // ---------------------------------------------------------------------
 // Pages & groups - the leaf content any container ultimately bottoms out
@@ -929,6 +936,19 @@ export type ValidationIssue = {
   code?: string;
   line?: number;
   column?: number;
+  /** WD-063: a mesma coisa que `message`, dita para gente. ADICIONAL, nunca
+   *  substituto - `message` continua sendo o texto do Zod verbatim, que e o que
+   *  o `writedocs build` imprime e o que o WD-062 grava em `validation_issues`.
+   *  Quem exibe escolhe qual dos dois mostrar. */
+  humanMessage?: string;
+  /** O que fazer a respeito, quando da pra dizer algo concreto. */
+  suggestion?: string;
+  /** Chave ESTAVEL de documentacao (`config.styles`), nunca uma URL: uma URL
+   *  cravada num pacote npm fica quebrada em toda instalacao ate a proxima
+   *  release, e o mesmo erro e exibido pela CLI e pelo dashboard, que podem
+   *  querer destinos diferentes. O mapa chave -> URL mora do lado de quem
+   *  renderiza. */
+  docKey?: string;
 };
 
 /** Sucesso carrega os dados ja validados (com os defaults do schema aplicados);
@@ -965,11 +985,400 @@ function positionFromJsonError(message: string, rawText: string): { line: number
 
 /** O corpo da mensagem de erro, uma linha por problema - exatamente o formato
  *  que o `writedocs build` imprime desde sempre (`  - campo: mensagem`). Fica
- *  aqui, e nao em cada chamador, pra que CLI e plataforma nao possam divergir. */
+ *  aqui, e nao em cada chamador, pra que CLI e plataforma nao possam divergir.
+ *
+ *  NAO mudou no WD-063, de proposito: continua imprimindo `message` (o texto do
+ *  Zod). O que melhorou foi o CONTEUDO dos issues - a uniao desembrulhada faz o
+ *  `path` apontar pro campo real em vez de parar em `navigation`. Quem quiser a
+ *  versao com frase humana e linha usa formatValidationIssuesDetailed. */
 export function formatValidationIssues(issues: ValidationIssue[]): string {
   return issues.map((i) => `  - ${i.path}: ${i.message}`).join('\n');
 }
 
+/** A versao longa, para quem tem uma tela inteira (a CLI hoje, o dashboard do
+ *  WD-065 se quiser): caminho, linha, frase humana, sugestao, e a mensagem do
+ *  Zod por ultimo, entre parenteses, pra quem precisa do texto exato.
+ *
+ *  Mora aqui pelo mesmo motivo que a irma curta: se cada consumidor montasse a
+ *  sua, a CLI e a plataforma divergiriam na primeira mudanca - que e exatamente
+ *  o que o AC do WD-066 proibe. `fileName` so entra na referencia de linha. */
+export function formatValidationIssuesDetailed(
+  issues: ValidationIssue[],
+  { fileName = 'writedocs.json' }: { fileName?: string } = {}
+): string {
+  return issues
+    .map((i) => {
+      const temCampo = i.path !== '(root)';
+      const local = i.line ? `${fileName}:${i.line}` : i.path;
+      const linhas = [`  ${local}${i.line && temCampo ? `  (${i.path})` : ''}`];
+      linhas.push(`    ${i.humanMessage ?? i.message}`);
+      if (i.suggestion) linhas.push(`    ${i.suggestion}`);
+      if (i.humanMessage && i.message !== i.humanMessage) linhas.push(`    (${i.message})`);
+      return linhas.join('\n');
+    })
+    .join('\n\n');
+}
+
+// ---------------------------------------------------------------------
+// WD-063 — do issue do Zod para "onde esta o erro, e o que fazer"
+//
+// Tres transformacoes, nesta ordem:
+//   1. desembrulhar `invalid_union` (senao todo erro dentro da navigation vira
+//      `navigation: "Invalid input"`, que e inutil num arquivo de 10 KB);
+//   2. achar a linha no texto, pelo caminho ja desembrulhado;
+//   3. escrever a frase humana, a sugestao e a docKey - POR CODIGO do Zod, nao
+//      por campo: um mapa por campo teria 17 entradas so na raiz e centenas no
+//      total, e envelheceria a cada campo novo do schema.
+// ---------------------------------------------------------------------
+
+/** Chaves que a raiz aceita sem ser campo do schema, e que por isso NAO devem
+ *  gerar aviso de chave desconhecida. Deliberadamente minuscula: a raiz nao e
+ *  `.strict()` justamente pra nao quebrar configs existentes, e `$schema` foi um
+ *  dos argumentos dessa decisao - avisar sobre ele contradiria o que o protegeu.
+ *  Se esta lista passar de dois ou tres nomes, o problema e outro e a raiz
+ *  precisa de outra conversa. */
+export const ROOT_ALLOWED_EXTRA_KEYS: readonly string[] = Object.freeze(['$schema']);
+
+type IssueCru = {
+  code?: string;
+  path?: (string | number)[];
+  message: string;
+  expected?: string;
+  values?: unknown[];
+  keys?: string[];
+  minimum?: number;
+  maximum?: number;
+  origin?: string;
+  format?: string;
+  errors?: unknown[];
+  unionErrors?: unknown[];
+};
+
+type IssuePlano = IssueCru & { caminho: (string | number)[] };
+
+function issuesDoRamo(ramo: unknown): IssueCru[] {
+  if (Array.isArray(ramo)) return ramo as IssueCru[];
+  const comIssues = ramo as { issues?: 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: 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.
+ *
+ *  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
+ *  primeiro" em vez de "todos os empatados":
+ *    - um engano do cliente tem que virar UMA mensagem. Emitir os 5 ramos
+ *      empatados de um `"navigation": {}` produz cinco exigencias que se
+ *      contradizem ("tabs e obrigatorio", "versions e obrigatorio", ...);
+ *    - determinismo: a mesma config sempre da a mesma mensagem. Um palpite
+ *      instavel seria pior que um palpite ruim.
+ *  E nada se perde no palpite errado: `message` continua sendo o texto do Zod. */
+function melhorRamo(ramos: unknown[]): IssueCru[] {
+  return ramos
+    .map((ramo) => {
+      const plano = planoDoRamo(ramo);
+      return {
+        lista: issuesDoRamo(ramo),
+        n: plano.length,
+        profundidade: maiorProfundidade(plano),
+      };
+    })
+    .sort((a, b) => b.profundidade - a.profundidade || a.n - b.n)[0].lista;
+}
+
+/** Desembrulha `invalid_union` recursivamente - o ramo escolhido normalmente e
+ *  outra uniao (cada produto da navigation e, por sua vez, uma uniao de formas),
+ *  entao para so quando chega num erro concreto. Sem recursao, o
+ *  `navigation.products.0` para em "Invalid input" de novo, um nivel abaixo. */
+function desembrulharUnioes(issues: IssueCru[], prefixo: (string | number)[] = []): IssuePlano[] {
+  const saida: IssuePlano[] = [];
+  for (const issue of issues) {
+    const caminho = [...prefixo, ...(issue.path ?? [])];
+    const ramos = issue.code === 'invalid_union' ? issue.errors ?? issue.unionErrors : null;
+    if (Array.isArray(ramos) && ramos.length > 0) {
+      saida.push(...desembrulharUnioes(melhorRamo(ramos), caminho));
+    } else {
+      saida.push({ ...issue, caminho });
+    }
+  }
+  return saida;
+}
+
+/** Parseia o texto UMA vez e devolve "caminho -> linha/coluna". Devolve null
+ *  quando o no nao existe no texto (campo obrigatorio ausente e o caso comum):
+ *  `line` ausente e melhor que `line` inventada. */
+function criarLocalizador(rawText: string): (caminho: (string | number)[]) => { line: number; column: number } | null {
+  let arvore: ReturnType<typeof parseTree> | undefined;
+  try {
+    arvore = parseTree(rawText);
+  } catch {
+    arvore = undefined;
+  }
+  return (caminho) => {
+    if (!arvore || caminho.length === 0) return null;
+    const no = findNodeAtLocation(arvore, caminho);
+    if (!no) return null;
+    const antes = rawText.slice(0, no.offset);
+    return { line: antes.split('\n').length, column: no.offset - antes.lastIndexOf('\n') };
+  };
+}
+
+/** `styles.primaryColor` -> `config.styles`. Primeiro segmento so, com fallback
+ *  pra `config`: o conjunto tem que ficar pequeno e estavel, porque vira
+ *  superficie publica no instante em que alguem mapear chave -> URL. */
+function docKeyDoCaminho(caminho: (string | number)[]): string {
+  const primeiro = caminho[0];
+  return typeof primeiro === 'string' && primeiro ? `config.${primeiro}` : 'config';
+}
+
+const ARTIGO_POR_TIPO: Record<string, string> = {
+  string: 'a piece of text',
+  number: 'a number',
+  boolean: 'true or false',
+  array: 'a list',
+  object: 'an object',
+  null: 'null',
+};
+
+const COMO_ESCREVER: Record<string, string> = {
+  string: 'Write the value in double quotes, like "Core Platform".',
+  number: 'Write the value as a bare number, like 3 - no quotes.',
+  boolean: 'Write true or false - no quotes.',
+  array: 'Write the value as a list in square brackets: [ ... ].',
+  object: 'Write the value as an object in curly braces: { ... }.',
+};
+
+/** O tipo que o cliente REALMENTE escreveu, lido do JSON ja parseado em vez de
+ *  extraido da mensagem do Zod por regex - o Zod v4 nao carrega `received` como
+ *  propriedade, so dentro do texto, e depender do texto quebra na primeira vez
+ *  que ele mudar de forma. */
+function tipoReal(valor: unknown): string {
+  if (valor === undefined) return 'missing';
+  if (valor === null) return 'null';
+  if (Array.isArray(valor)) return 'array';
+  return typeof valor;
+}
+
+function valorEm(raiz: unknown, caminho: (string | number)[]): unknown {
+  let atual: unknown = raiz;
+  for (const passo of caminho) {
+    if (atual === null || typeof atual !== 'object') return undefined;
+    atual = (atual as Record<string | number, unknown>)[passo];
+  }
+  return atual;
+}
+
+function comoCampo(caminho: (string | number)[]): string {
+  return caminho.length > 0 ? `"${caminho.join('.')}"` : 'writedocs.json';
+}
+
+/** A frase de chave desconhecida, num lugar so.
+ *
+ *  Decisao 6: chave desconhecida em sub-objeto strict e ERRO e na raiz e AVISO -
+ *  a assimetria de SEVERIDADE e intencional e fica. A de VOCABULARIO nao: os
+ *  dois caminhos chamam esta funcao, entao os dois dizem exatamente a mesma
+ *  coisa, e so quem chama decide o peso. */
+function fraseChaveDesconhecida(chaves: string[], dentroDe: (string | number)[]) {
+  const onde = dentroDe.length > 0 ? ` inside "${dentroDe.join('.')}"` : '';
+  const lista = chaves.map((k) => `"${k}"`).join(', ');
+  return {
+    humanMessage:
+      chaves.length === 1
+        ? `${lista} is not a writedocs.json option${onde}.`
+        : `${lista} are not writedocs.json options${onde}.`,
+    suggestion: 'Remove it, or check the spelling - options are case-sensitive.',
+  };
+}
+
+/** A frase humana + a sugestao, escolhidas pelo CODIGO do Zod. `raiz` e o JSON
+ *  ja parseado, usado so pra saber o que o cliente escreveu de fato. */
+function humanizar(issue: IssuePlano, raiz: unknown): { humanMessage?: string; suggestion?: string } {
+  const campo = comoCampo(issue.caminho);
+  switch (issue.code) {
+    case 'invalid_type': {
+      const esperado = issue.expected ?? 'a different type';
+      const recebido = tipoReal(valorEm(raiz, issue.caminho));
+      if (recebido === 'missing') {
+        return {
+          humanMessage: `${campo} is required, but writedocs.json does not set it.`,
+          suggestion: `Add ${campo} with ${ARTIGO_POR_TIPO[esperado] ?? `a ${esperado}`} as its value.`,
+        };
+      }
+      return {
+        humanMessage: `${campo} must be ${ARTIGO_POR_TIPO[esperado] ?? `a ${esperado}`}, but writedocs.json has ${ARTIGO_POR_TIPO[recebido] ?? `a ${recebido}`}.`,
+        suggestion: COMO_ESCREVER[esperado],
+      };
+    }
+    case 'unrecognized_keys': {
+      // O Zod agrega as chaves sobrando numa mensagem so, com o `path` no PAI.
+      const chaves = issue.keys ?? [];
+      if (chaves.length === 0) return {};
+      return fraseChaveDesconhecida(chaves, issue.caminho);
+    }
+    case 'invalid_value': {
+      const opcoes = (issue.values ?? []).map((v) => JSON.stringify(v)).join(', ');
+      return {
+        humanMessage: `${campo} must be one of: ${opcoes}.`,
+        suggestion: 'Replace the value with one of the options above.',
+      };
+    }
+    case 'too_small': {
+      const unidade = issue.origin === 'array' ? 'item' : 'character';
+      const minimo = issue.minimum ?? 1;
+      return {
+        humanMessage: `${campo} needs at least ${minimo} ${unidade}${minimo === 1 ? '' : 's'}.`,
+        suggestion: issue.origin === 'array' ? 'Add an entry, or remove the field entirely.' : undefined,
+      };
+    }
+    case 'too_big': {
+      const unidade = issue.origin === 'array' ? 'item' : 'character';
+      const maximo = issue.maximum ?? 0;
+      return { humanMessage: `${campo} allows at most ${maximo} ${unidade}${maximo === 1 ? '' : 's'}.` };
+    }
+    case 'invalid_format':
+      return {
+        humanMessage: `${campo} is not a valid ${issue.format ?? 'value'}.`,
+        suggestion: 'Check the format against the documentation for this field.',
+      };
+    case 'invalid_union':
+      // So chega aqui se o desembrulho nao achou ramo nenhum (uniao sem
+      // `errors`). Raro, mas melhor dizer o que aconteceu do que "Invalid input".
+      return {
+        humanMessage: `${campo} does not match any of the shapes writedocs.json accepts here.`,
+        suggestion: 'Check the documentation for the shapes this field accepts.',
+      };
+    case 'custom':
+      // As mensagens de `.refine()` deste schema ja sao frases escritas pra
+      // gente ("Each scripts.head/scripts.body entry needs exactly one of..."),
+      // entao reescrever seria piorar. Repassa como frase humana pra que quem
+      // exibe so `humanMessage` nao fique sem nada.
+      return { humanMessage: issue.message };
+    default:
+      return {};
+  }
+}
+
+/** Avisos de chave desconhecida na RAIZ.
+ *
+ *  A raiz nao e `.strict()` (decidido no E11-desenho-geral: tornar strict
+ *  quebraria configs existentes), entao o Zod descarta a chave em silencio e
+ *  nao ha issue nenhum. Quem quiser avisar chama isto. Mora aqui, e nao na
+ *  plataforma, pelo motivo de sempre: era o unico texto escrito pela plataforma,
+ *  e enquanto ele viver la os dois lados podem divergir.
+ *
+ *  Severidade e de quem chama - isto so descreve o problema. `validateDocsConfig`
+ *  deliberadamente NAO chama: um config valido continua saindo com `issues: []`,
+ *  porque a plataforma repassa `issues` como `errors` e um aviso ali viraria
+ *  erro. */
+export function unknownRootKeyIssues(rawText: string): ValidationIssue[] {
+  let raiz: unknown;
+  try {
+    raiz = JSON.parse(rawText);
+  } catch {
+    return [];
+  }
+  if (raiz === null || typeof raiz !== 'object' || Array.isArray(raiz)) return [];
+  const conhecidas = new Set([...Object.keys(docsConfigSchema.shape), ...ROOT_ALLOWED_EXTRA_KEYS]);
+  const localizar = criarLocalizador(rawText);
+  return Object.keys(raiz as Record<string, unknown>)
+    .filter((chave) => !conhecidas.has(chave))
+    .map((chave) => {
+      const frase = fraseChaveDesconhecida([chave], []);
+      return {
+        path: chave,
+        // O mesmo formato singular da mensagem `unrecognized_keys` do Zod, pra
+        // que aviso e erro sejam indistinguiveis por quem so le `message`.
+        message: `Unrecognized key: "${chave}"`,
+        code: 'unrecognized_keys',
+        ...(localizar([chave]) ?? {}),
+        ...frase,
+        // `config`, e NAO `config.<chave>`: a chave aqui e o que o cliente
+        // digitou errado, e derivar a docKey dela faria cada erro de digitacao
+        // inventar uma chave nova. O conjunto de docKeys tem que ser fechado -
+        // `config` mais um por campo do schema, nada alem disso -, senao quem
+        // mapeia chave -> URL do outro lado nao tem lista pra mapear.
+        docKey: 'config',
+      };
+    });
+}
+
 export function validateDocsConfig(rawText: string): ValidationResult {
   let raw: unknown;
   try {
@@ -982,21 +1391,45 @@ export function validateDocsConfig(rawText: string): ValidationResult {
       data: null,
       kind: 'invalid_json',
       parseError,
-      issues: [{ path: '(root)', message: parseError.message, code: 'invalid_json', ...(posicao ?? {}) }],
+      issues: [
+        {
+          path: '(root)',
+          message: parseError.message,
+          code: 'invalid_json',
+          ...(posicao ?? {}),
+          humanMessage: 'writedocs.json is not valid JSON, so none of it could be checked.',
+          suggestion: posicao
+            ? `Look at line ${posicao.line} - a missing comma, an extra trailing comma, or an unclosed bracket is the usual cause.`
+            : 'A missing comma, an extra trailing comma, or an unclosed bracket is the usual cause.',
+          docKey: 'config',
+        },
+      ],
     };
   }
 
   const result = docsConfigSchema.safeParse(raw);
   if (!result.success) {
+    const localizar = criarLocalizador(rawText);
     return {
       ok: false,
       data: null,
       kind: 'schema',
-      issues: result.error.issues.map((i) => ({
-        path: i.path.join('.') || '(root)',
-        message: i.message,
-        code: i.code,
-      })),
+      issues: desembrulharUnioes(result.error.issues as IssueCru[]).map((i) => {
+        // Para chave desconhecida o `path` do Zod aponta pro PAI (`footer`), e a
+        // chave ofensora vem em `keys`. Para a LINHA vale a pena descer ate ela
+        // (`footer.banana`), que e onde o cliente precisa olhar; o `path` fica
+        // como o Zod deu, pra nao mudar o que a plataforma ja grava.
+        const alvoDaLinha =
+          i.code === 'unrecognized_keys' && i.keys?.length ? [...i.caminho, i.keys[0]] : i.caminho;
+        return {
+          path: i.caminho.join('.') || '(root)',
+          message: i.message,
+          code: i.code,
+          ...(localizar(alvoDaLinha) ?? localizar(i.caminho) ?? {}),
+          ...humanizar(i, raw),
+          docKey: docKeyDoCaminho(i.caminho),
+        };
+      }),
     };
   }