@neetru/cli 2.29.0 → 2.32.0

package/dist/lib/product-docs/check.js

@@ -0,0 +1,489 @@
+/**
+ * Validador OFFLINE dos docs de um produto SaaS — `neetru docs check`.
+ *
+ * Mesmos códigos de regra do validador do Core (PROTOCOLO_WIKI_INTERNA §9.2:
+ * FM, TI, NM, LK, PB, LC) mais os de produto (PROTOCOLO_DOCS_PRODUTOS_SAAS
+ * §8.1: PR001–PR004). IX001 (catálogo do INDEX_MESTRE) não se aplica a produto.
+ *
+ * Níveis: `erro` (falha o check), `aviso` (só falha com --strict) e
+ * `sugestao` (nunca falha — itens "do primeiro mês").
+ */
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import * as path from 'node:path';
+import { parseDoc } from './frontmatter.js';
+import { extractHeadings, extractLinks, normalizeSection, plainHeadingText } from './markdown.js';
+import { DAY_ONE, DAY_ONE_MODELS, FILE_NAME_REGEX, FIRST_MONTH, README_SECTIONS, SKIP_DIRS, TYPE_MODELS, folderRule, topFolder, } from './structure.js';
+import { productCategories, statusesForType } from './taxonomy.js';
+import { productExposesApi, readProductVersion } from './config.js';
+import { changedFiles } from './git.js';
+import { todayIso } from './dates.js';
+const REQUIRED_FIELDS = ['title', 'description', 'category', 'subcategory', 'type', 'status', 'date', 'owner', 'audience'];
+const KNOWN_KEYS = new Set([
+    'title', 'description', 'product', 'category', 'subcategory', 'type', 'status', 'date', 'updated',
+    'owner', 'audience', 'superseded_by', 'archived_at', 'archived_from', 'archive_reason', 'status_evidence',
+    'status_checked_at', 'supersedes', 'related', 'tags', 'status_note', 'order', 'icon', 'adr', 'command',
+]);
+/** §6.2 — chave legada → o que usar. */
+const LEGACY_KEYS = {
+    last_updated: 'updated', lastUpdated: 'updated', updatedAt: 'updated',
+    created: 'date', data: 'date',
+    autor: '(remover — a autoria está no git)', author: '(remover — a autoria está no git)',
+    authors: '(remover — a autoria está no git)', owners: 'owner',
+    relacionado: 'related', relatedDocs: 'related', allowOthers: '(remover)',
+};
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_IN_TEXT = /\d{4}-\d{2}(-\d{2})?/;
+const STAFF_DOMAIN = /core\.neetru\.com/i;
+const PERSONAL_EMAIL = /[\w.+-]+@(gmail|googlemail|hotmail|outlook|live|yahoo|icloud|me|bol|uol|terra|ig)\.[a-z.]+/i;
+function str(v) {
+    if (typeof v === 'string')
+        return v.trim() || undefined;
+    if (typeof v === 'number')
+        return String(v);
+    return undefined;
+}
+function isValidDate(s) {
+    if (!DATE_RE.test(s))
+        return false;
+    const d = new Date(`${s}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s;
+}
+function daysBetween(a, b) {
+    return Math.floor((Date.parse(`${b}T00:00:00Z`) - Date.parse(`${a}T00:00:00Z`)) / 86_400_000);
+}
+function requiredSections(relInDocs, type) {
+    const dayOne = DAY_ONE_MODELS[relInDocs];
+    if (dayOne)
+        return dayOne.filter((x) => x.required);
+    if (!type)
+        return [];
+    return (TYPE_MODELS[type] ?? []).filter((x) => x.required);
+}
+/** Valida UM doc. `relInDocs` é relativo à pasta de docs, com `/`. Função pura. */
+export function checkDocFile(relInDocs, raw, ctx) {
+    const file = `${ctx.docsRoot}/${relInDocs}`;
+    const out = [];
+    const add = (code, level, message, line) => out.push({ file, code, level, message, ...(line ? { line } : {}) });
+    const top = topFolder(relInDocs);
+    const base = path.posix.basename(relInDocs);
+    const isArchive = top === '_archive';
+    const isAudit = top === '_audit';
+    const parsed = parseDoc(raw);
+    const fm = parsed.data;
+    const lineOf = (bodyLine) => parsed.bodyStartLine + bodyLine - 1;
+    // ── FM001 ────────────────────────────────────────────────────────────────
+    if (!parsed.hasFrontmatter) {
+        add('FM001', 'erro', 'Sem frontmatter. Rode `neetru docs init --migrar` para inferir um, ou copie o modelo do protocolo.', 1);
+    }
+    else if (parsed.error) {
+        add('FM001', 'erro', `Frontmatter com YAML inválido: ${parsed.error}.`, 1);
+    }
+    if (isAudit)
+        return out; // §9.4: _audit/ só FM001
+    const fmOk = parsed.hasFrontmatter && !parsed.error;
+    const title = str(fm.title);
+    const status = str(fm.status);
+    // ── _archive/: regras reduzidas (FM001, FM009 e title) ───────────────────
+    if (isArchive) {
+        if (fmOk) {
+            if (!title)
+                add('FM002', 'erro', 'Falta o campo obrigatório `title`.');
+            if (status !== 'archived')
+                add('FM009', 'erro', 'Doc em `_archive/` precisa de `status: archived`.');
+            const missing = ['archived_at', 'archived_from', 'archive_reason'].filter((k) => !str(fm[k]));
+            if (missing.length)
+                add('FM009', 'erro', `Carimbo de arquivamento incompleto: falta ${missing.join(', ')}.`);
+        }
+        return out;
+    }
+    const type = str(fm.type);
+    const family = type ? ctx.taxonomy.types[type] : undefined;
+    const category = str(fm.category);
+    const subcategory = str(fm.subcategory);
+    if (fmOk) {
+        // ── FM002 ──────────────────────────────────────────────────────────────
+        const missing = REQUIRED_FIELDS.filter((k) => !str(fm[k]));
+        if (family === 'vivo' && !str(fm.updated))
+            missing.push('updated');
+        if (missing.length)
+            add('FM002', 'erro', `Falta campo obrigatório: ${missing.join(', ')}.`);
+        // ── PR001 ──────────────────────────────────────────────────────────────
+        const product = str(fm.product);
+        if (!product)
+            add('PR001', 'erro', `Falta \`product: ${ctx.slug}\` (obrigatório em doc de produto).`);
+        else if (product !== ctx.slug)
+            add('PR001', 'erro', `\`product: ${product}\` não bate com o slug do neetru.config.json (${ctx.slug}).`);
+        // ── FM003 / PR003 / FM004 ─────────────────────────────────────────────
+        const cats = productCategories(ctx.taxonomy);
+        if (category) {
+            if (ctx.taxonomy.coreOnlyCategories.includes(category)) {
+                add('PR003', 'erro', `A categoria "${category}" só existe no Core. Em produto use: ${Object.keys(cats).join(', ')}.`);
+            }
+            else if (!cats[category]) {
+                add('FM003', 'erro', `Categoria "${category}" fora da lista. Aceitas: ${Object.keys(cats).join(', ')}.`);
+            }
+            else if (subcategory && !cats[category].includes(subcategory)) {
+                add('FM004', 'erro', `Subcategoria "${subcategory}" não pertence a "${category}". Aceitas: ${cats[category].join(', ')}.`);
+            }
+        }
+        // ── FM005 ──────────────────────────────────────────────────────────────
+        if (type) {
+            if (!family) {
+                add('FM005', 'erro', `Tipo "${type}" fora da lista. Aceitos: ${Object.keys(ctx.taxonomy.types).join(', ')}.`);
+            }
+            else {
+                const rule = folderRule(relInDocs);
+                if (rule && rule.types !== 'qualquer' && !rule.types.includes(type)) {
+                    const where = rule.folder ? `${rule.folder}/` : 'a raiz de docs/';
+                    add('FM005', 'erro', `Tipo "${type}" não é aceito em ${where} (aceitos: ${rule.types.join(', ')}).`);
+                }
+            }
+        }
+        // ── FM006 ──────────────────────────────────────────────────────────────
+        if (type && family && status) {
+            const allowed = statusesForType(ctx.taxonomy, type);
+            if (!allowed.includes(status))
+                add('FM006', 'erro', `Status "${status}" não vale para o tipo "${type}". Aceitos: ${allowed.join(', ')}.`);
+        }
+        // ── FM007 ──────────────────────────────────────────────────────────────
+        for (const k of ['date', 'updated', 'archived_at', 'status_checked_at']) {
+            const v = str(fm[k]);
+            if (v && !isValidDate(v))
+                add('FM007', 'erro', `\`${k}: ${v}\` fora do formato AAAA-MM-DD.`);
+        }
+        const date = str(fm.date);
+        const updated = str(fm.updated);
+        if (date && updated && isValidDate(date) && isValidDate(updated) && updated < date) {
+            add('FM007', 'erro', `\`updated\` (${updated}) é anterior a \`date\` (${date}).`);
+        }
+        // ── FM008 ──────────────────────────────────────────────────────────────
+        if (status === 'superseded') {
+            const sb = str(fm.superseded_by);
+            if (!sb)
+                add('FM008', 'erro', '`status: superseded` sem `superseded_by`.');
+            else if (!ctx.exists(`${ctx.docsRoot}/${sb.replace(/^\.?\/+/, '')}`)) {
+                add('FM008', 'erro', `\`superseded_by: ${sb}\` aponta para arquivo inexistente (caminho relativo a ${ctx.docsRoot}/).`);
+            }
+        }
+        // ── FM009 ──────────────────────────────────────────────────────────────
+        if (status === 'archived')
+            add('FM009', 'erro', '`status: archived` fora de `_archive/` — mova o arquivo (espelhando o caminho) ou mude o status.');
+        // ── FM013 / FM010 ─────────────────────────────────────────────────────
+        const owner = str(fm.owner);
+        if (owner) {
+            if (owner.includes('@') || /^[A-ZÀ-Ú][a-zà-ú]+(\s+[A-ZÀ-Ú][a-zà-ú]+)+$/.test(owner)) {
+                add('FM013', 'erro', `\`owner: ${owner}\` parece pessoa ou e-mail. Use a raia (em produto, \`produto\`).`);
+            }
+            else if (!ctx.taxonomy.owners.includes(owner)) {
+                add('FM010', 'erro', `\`owner: ${owner}\` fora da lista: ${ctx.taxonomy.owners.join(', ')}.`);
+            }
+        }
+        const audience = str(fm.audience);
+        if (audience && !ctx.taxonomy.audiences.includes(audience)) {
+            add('FM010', 'erro', `\`audience: ${audience}\` fora da lista: ${ctx.taxonomy.audiences.join(', ')}.`);
+        }
+        // ── FM011 ──────────────────────────────────────────────────────────────
+        if (family === 'plano' && status && ['done', 'in_progress', 'abandoned'].includes(status) && !str(fm.status_evidence)) {
+            add('FM011', 'aviso', `Plano \`${status}\` sem \`status_evidence\` (arquivo:linha, commit ou PR).`);
+        }
+        // ── FM012 ──────────────────────────────────────────────────────────────
+        for (const k of Object.keys(fm)) {
+            if (KNOWN_KEYS.has(k))
+                continue;
+            if (LEGACY_KEYS[k])
+                add('FM012', 'aviso', `Chave legada \`${k}\` — use ${LEGACY_KEYS[k]}.`);
+            else
+                add('FM012', 'aviso', `Chave desconhecida \`${k}\` (aceita só como metadado de registro).`);
+        }
+        // ── LC001 / LC002 ─────────────────────────────────────────────────────
+        if (family === 'vivo' && status === 'active' && updated && isValidDate(updated) && daysBetween(updated, ctx.today) > 365) {
+            add('LC001', 'aviso', `Doc vivo sem revisão há mais de 365 dias (updated ${updated}) — revisar.`);
+        }
+        if (family === 'plano' && (status === 'proposed' || status === 'in_progress')) {
+            const ref = str(fm.status_checked_at) ?? date;
+            if (ref && isValidDate(ref) && daysBetween(ref, ctx.today) > 90) {
+                add('LC002', 'aviso', `Plano \`${status}\` sem conferência há mais de 90 dias (${ref}) — status incerto.`);
+            }
+        }
+        // ── PB001 ──────────────────────────────────────────────────────────────
+        if (audience === 'publico') {
+            if (STAFF_DOMAIN.test(raw))
+                add('PB001', 'erro', 'Doc público cita o domínio do painel staff do Core. Tire a menção.');
+            const em = raw.match(PERSONAL_EMAIL);
+            if (em)
+                add('PB001', 'erro', `Doc público com e-mail pessoal (${em[0]}).`);
+        }
+    }
+    // ── TI001 / TI002 / TI003–TI007 ──────────────────────────────────────────
+    const headings = extractHeadings(parsed.body);
+    const h1s = headings.filter((h) => h.level === 1);
+    if (h1s.length === 0)
+        add('TI001', 'erro', 'Nenhum H1. O doc precisa de exatamente um H1, igual ao `title`.');
+    else if (h1s.length > 1)
+        add('TI001', 'erro', `${h1s.length} H1 — deixe só um (igual ao \`title\`).`, lineOf(h1s[1].line));
+    if (title && h1s.length >= 1) {
+        const h1 = plainHeadingText(h1s[0].text);
+        if (h1 !== title)
+            add('TI002', 'erro', `H1 ("${h1}") diferente do \`title\` ("${title}").`, lineOf(h1s[0].line));
+    }
+    if (title) {
+        if (title.length > 100)
+            add('TI003', 'erro', `Título com ${title.length} caracteres (máximo 100; ideal até 70).`);
+        else if (title.length > 70)
+            add('TI003', 'aviso', `Título com ${title.length} caracteres (ideal até 70).`);
+        const hasDate = DATE_IN_TEXT.test(title);
+        if (family && family !== 'registro' && hasDate)
+            add('TI004', 'aviso', 'Data no título só na família registro (relatório, incidente, ata).');
+        if (family === 'registro' && !/\d{4}-\d{2}(-\d{2})?\s*$/.test(title))
+            add('TI004', 'aviso', 'Registro sem a data no fim do título ("Assunto — AAAA-MM-DD").');
+        const letters = title.replace(/[^A-Za-zÀ-ÿ]/g, '');
+        const problems = [];
+        if (letters.length > 3 && letters === letters.toUpperCase())
+            problems.push('tudo em MAIÚSCULAS');
+        if (/\p{Extended_Pictographic}/u.test(title))
+            problems.push('emoji');
+        if (/\.$/.test(title))
+            problems.push('ponto final');
+        if (/[`*]|\[.*\]\(/.test(title))
+            problems.push('markdown ou crase');
+        if (/^[A-Z0-9]+(_[A-Z0-9]+)+$/.test(title))
+            problems.push('nome de arquivo como título');
+        if (/^(runbook|spec|guia|adr|rfc|plano|norma|relat[óo]rio|refer[êe]ncia)\s*:/i.test(title))
+            problems.push('rótulo de tipo com dois-pontos');
+        if (/^(neetru core|plataforma interna neetru)\s*[—-]/i.test(title))
+            problems.push('prefixo "Neetru Core —"');
+        if ((title.match(/ — /g) ?? []).length > 1)
+            problems.push('mais de um travessão');
+        if (problems.length)
+            add('TI005', 'aviso', `Título com ${problems.join(', ')}.`);
+    }
+    const description = str(fm.description);
+    if (description) {
+        const issues = [];
+        if (description.length < 40 || description.length > 200)
+            issues.push(`${description.length} caracteres (40 a 200)`);
+        if (!/\.$/.test(description))
+            issues.push('não termina em ponto');
+        if (/[.!?]\s+[A-ZÀ-Ú]/.test(description.replace(/\b(ex|etc|p\.ex|vs|sr|sra|dr)\.\s/gi, '')))
+            issues.push('mais de uma frase');
+        if (issues.length)
+            add('TI006', 'aviso', `Descrição com ${issues.join(', ')}.`);
+    }
+    // TI007: salto de nível e mistura de H2 numerada/não numerada
+    let prev = 1;
+    for (const h of headings) {
+        if (h.level === 1) {
+            prev = 1;
+            continue;
+        }
+        if (h.level > prev + 1) {
+            add('TI007', 'aviso', `Salto de cabeçalho: H${prev} → H${h.level} ("${plainHeadingText(h.text)}").`, lineOf(h.line));
+            break;
+        }
+        prev = h.level;
+    }
+    const h2s = headings.filter((h) => h.level === 2);
+    const numbered = h2s.filter((h) => /^\d+(\.\d+)*[.)]?\s/.test(plainHeadingText(h.text))).length;
+    if (numbered > 0 && numbered < h2s.length)
+        add('TI007', 'aviso', 'Mistura de H2 com e sem número — numere todas ou nenhuma.');
+    // TI008: seções obrigatórias do modelo
+    const req = requiredSections(relInDocs, type);
+    if (req.length) {
+        const have = h2s.map((h) => normalizeSection(h.text));
+        const missingSec = req.filter((r) => {
+            const want = normalizeSection(r.title);
+            return !have.some((x) => x === want || x.startsWith(`${want} `) || x.startsWith(`${want}(`) || x.startsWith(`${want}:`));
+        });
+        if (missingSec.length)
+            add('TI008', 'aviso', `Falta seção obrigatória do modelo: ${missingSec.map((m) => m.title).join(' · ')}.`);
+    }
+    // ── NM001 / NM002 ─────────────────────────────────────────────────────────
+    const nameExempt = relInDocs === 'index.md' || base === 'INDEX.md' || top === 'superpowers' || ctx.legacyNames.has(relInDocs);
+    if (!nameExempt && !FILE_NAME_REGEX.test(base)) {
+        add('NM001', 'erro', `Nome "${base}" fora da regra <PREFIXO>_<ASSUNTO>[_<DATA>].md (MAIÚSCULAS, sem acento, com _). Renomear é decisão humana; para manter, liste em ${ctx.docsRoot}/_nomes-legados.json.`);
+    }
+    if (!nameExempt && family) {
+        const nameHasDate = /_\d{4}-\d{2}(-\d{2})?\.md$/.test(base);
+        if (family === 'registro' && !nameHasDate)
+            add('NM002', 'aviso', 'Registro sem data no nome (…_AAAA-MM-DD.md).');
+        if (family === 'vivo' && nameHasDate)
+            add('NM002', 'aviso', 'Doc vivo com data no nome — data no nome é só de registro.');
+    }
+    // ── LK001 / LK002 ─────────────────────────────────────────────────────────
+    const dirInRepo = path.posix.dirname(file);
+    for (const link of extractLinks(parsed.body)) {
+        const t = link.target;
+        if (/^(https?:)?\/\/core\.neetru\.com\/docs/i.test(t) || /^\/docs\//.test(t)) {
+            add('LK002', 'aviso', `Link absoluto para o portal de docs (${t}) — use link relativo com .md.`, lineOf(link.line));
+            continue;
+        }
+        if (/^[a-z][a-z0-9+.-]*:/i.test(t) || t.startsWith('#') || t.startsWith('/') || t.startsWith('//'))
+            continue;
+        let p = t.split('#')[0].split('?')[0];
+        try {
+            p = decodeURIComponent(p);
+        }
+        catch {
+            /* mantém */
+        }
+        if (!p)
+            continue;
+        const target = path.posix.normalize(path.posix.join(dirInRepo, p));
+        if (target.startsWith('..'))
+            continue; // fora do repo — não dá para conferir
+        if (!ctx.exists(target)) {
+            add('LK001', ctx.changed ? 'erro' : 'aviso', `Link quebrado: ${t}.`, lineOf(link.line));
+        }
+    }
+    return out;
+}
+async function walkMd(absDir, relBase = '') {
+    let entries;
+    try {
+        entries = await fs.readdir(absDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (e.isSymbolicLink())
+            continue;
+        const rel = relBase ? `${relBase}/${e.name}` : e.name;
+        if (e.isDirectory()) {
+            if (SKIP_DIRS.has(e.name))
+                continue;
+            out.push(...(await walkMd(path.join(absDir, e.name), rel)));
+        }
+        else if (e.isFile() && e.name.toLowerCase().endsWith('.md')) {
+            out.push(rel);
+        }
+    }
+    return out.sort();
+}
+/** Lista os `.md` da pasta de docs (relativos a ela, com `/`). */
+export async function listDocFiles(repo) {
+    return walkMd(path.join(repo.cwd, repo.docs.root));
+}
+/** Lê `docs/_nomes-legados.json` (array ou `{ arquivos: [...] }`). */
+export function readLegacyNames(repo) {
+    const p = path.join(repo.cwd, repo.docs.root, '_nomes-legados.json');
+    try {
+        const j = JSON.parse(fsSync.readFileSync(p, 'utf8'));
+        const arr = Array.isArray(j) ? j : j.arquivos;
+        return new Set(Array.isArray(arr) ? arr.filter((x) => typeof x === 'string').map((x) => x.replace(/\\/g, '/')) : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Hoje no fuso dos docs (America/Sao_Paulo ou NEETRU_TZ) — nunca UTC. */
+export { todayIso } from './dates.js';
+/** Checagens do repositório inteiro: mínimo do primeiro dia (PR002), README, CHANGELOG (PR004). */
+export function checkRepoLevel(repo) {
+    const out = [];
+    const exists = (rel) => fsSync.existsSync(path.join(repo.cwd, rel));
+    const withApi = productExposesApi(repo);
+    const docsRoot = repo.docs.root;
+    const remap = (p) => (p.startsWith('docs/') ? `${docsRoot}/${p.slice(5)}` : p);
+    if (!exists(docsRoot)) {
+        out.push({ file: docsRoot, code: 'PR002', level: 'aviso', message: `Pasta ${docsRoot}/ não existe. Rode \`neetru docs init\`.` });
+    }
+    for (const item of DAY_ONE) {
+        if (item.soComApi && !withApi)
+            continue;
+        const p = remap(item.path);
+        if (!exists(p)) {
+            out.push({
+                file: p,
+                code: 'PR002',
+                level: 'aviso',
+                message: `Falta item do mínimo do primeiro dia: ${p}.${item.soComApi ? ' (o produto expõe /api/v1)' : ''} \`neetru docs init\` cria o que falta sem sobrescrever nada.`,
+            });
+        }
+    }
+    // README: 3 seções
+    if (exists('README.md')) {
+        const body = fsSync.readFileSync(path.join(repo.cwd, 'README.md'), 'utf8');
+        const hs = extractHeadings(body).filter((h) => h.level >= 2).map((h) => plainHeadingText(h.text));
+        const missing = README_SECTIONS.filter((sec) => !hs.some((h) => sec.match.test(h)));
+        if (missing.length) {
+            out.push({ file: 'README.md', code: 'PR002', level: 'aviso', message: `README sem a seção: ${missing.map((m) => m.label).join(' · ')}.` });
+        }
+    }
+    // PR004: CHANGELOG com a versão do package.json
+    if (exists('CHANGELOG.md')) {
+        const version = readProductVersion(repo);
+        if (version) {
+            const cl = fsSync.readFileSync(path.join(repo.cwd, 'CHANGELOG.md'), 'utf8');
+            const esc = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            if (!new RegExp(`^#{2,3}\\s*\\[?v?${esc}\\]?(\\s|$)`, 'm').test(cl)) {
+                out.push({ file: 'CHANGELOG.md', code: 'PR004', level: 'aviso', message: `CHANGELOG.md sem entrada para a versão ${version} do package.json ("## [${version}] — AAAA-MM-DD").` });
+            }
+        }
+    }
+    for (const p of FIRST_MONTH) {
+        const rp = remap(p);
+        if (!exists(rp))
+            out.push({ file: rp, code: 'PR002', level: 'sugestao', message: `Recomendado no primeiro mês: ${rp}.` });
+    }
+    if (exists(docsRoot)) {
+        const dec = path.join(repo.cwd, docsRoot, 'decisoes');
+        const hasAdr = fsSync.existsSync(dec) && fsSync.readdirSync(dec).some((f) => /^ADR-\d{4}_/.test(f));
+        if (!hasAdr)
+            out.push({ file: `${docsRoot}/decisoes`, code: 'PR002', level: 'sugestao', message: 'Recomendado no primeiro mês: o primeiro ADR (`neetru docs new adr "<decisão>"`).' });
+    }
+    return out;
+}
+export function summarize(findings, strict) {
+    const counts = { erro: 0, aviso: 0, sugestao: 0 };
+    for (const f of findings)
+        counts[f.level]++;
+    return { ok: counts.erro === 0 && (!strict || counts.aviso === 0), counts };
+}
+/** Roda o validador no repositório do produto. Nunca lança por conteúdo de doc. */
+export async function checkProductDocs(repo, opts) {
+    const docsRoot = repo.docs.root;
+    const all = await listDocFiles(repo);
+    const today = opts.today ?? todayIso();
+    const legacy = readLegacyNames(repo);
+    let targets = all;
+    let changedSet = new Set();
+    let changedBase;
+    let changedFallback = false;
+    const ch = changedFiles(repo.cwd);
+    if (ch) {
+        changedBase = ch.base;
+        changedSet = new Set(ch.files.filter((f) => f.startsWith(`${docsRoot}/`)).map((f) => f.slice(docsRoot.length + 1)));
+    }
+    if (opts.changed) {
+        if (ch)
+            targets = all.filter((f) => changedSet.has(f));
+        else
+            changedFallback = true;
+    }
+    const existsCache = new Map();
+    const exists = (repoRel) => {
+        if (!existsCache.has(repoRel))
+            existsCache.set(repoRel, fsSync.existsSync(path.join(repo.cwd, repoRel)));
+        return existsCache.get(repoRel);
+    };
+    const findings = [];
+    for (const rel of targets) {
+        const raw = await fs.readFile(path.join(repo.cwd, docsRoot, rel), 'utf8');
+        findings.push(...checkDocFile(rel, raw, {
+            taxonomy: opts.taxonomy,
+            slug: repo.slug,
+            docsRoot,
+            exists,
+            legacyNames: legacy,
+            today,
+            changed: opts.changed ? true : changedSet.has(rel),
+        }));
+    }
+    findings.push(...checkRepoLevel(repo));
+    const { ok, counts } = summarize(findings, !!opts.strict);
+    return { ok, findings, counts, filesChecked: targets.length, docsRoot, changedBase, changedFallback };
+}
+//# sourceMappingURL=check.js.map

package/dist/lib/product-docs/config.d.ts

@@ -0,0 +1,66 @@
+export declare const CONFIG_FILES: readonly ["neetru.config.json", ".neetru.json"];
+export interface DocsConfig {
+    protocolVersion: number;
+    root: string;
+    publish: boolean;
+    publishOnDeploy: boolean;
+    api: boolean;
+}
+export declare const DEFAULT_DOCS_CONFIG: DocsConfig;
+export interface ProductRepo {
+    /**
+     * Base dos caminhos dos docs: a pasta que contém a pasta de docs. É a pasta do
+     * `neetru.config.json` no caso comum; num monorepo com `docs.root` acima do
+     * config (ex.: `apps/painel/neetru.config.json` + `docs/` na raiz), é a raiz
+     * do repositório git. `README.md`/`CHANGELOG.md` do produto ficam aqui.
+     */
+    cwd: string;
+    /** Pasta do `neetru.config.json` (e do `package.json` do produto). */
+    configDir: string;
+    configPath: string;
+    /** Raiz do repositório git (null fora de git). */
+    gitRoot: string | null;
+    raw: Record<string, unknown>;
+    slug: string;
+    name: string;
+    /** `docs.root` aqui é RELATIVO a `cwd`, com `/` (ex.: `docs`). */
+    docs: DocsConfig;
+    /** A chave `docs` existia no arquivo (antes de qualquer default). */
+    hasDocsKey: boolean;
+    /**
+     * `docs.root` não estava no config e a pasta foi achada na raiz do git
+     * (monorepo). Valor RELATIVO AO CONFIG a gravar (ex.: `../../docs`).
+     */
+    docsRootInferred?: string;
+}
+export declare class ProductConfigMissingError extends Error {
+    constructor(cwd: string);
+}
+export declare class ProductConfigInvalidError extends Error {
+    constructor(file: string, why: string);
+}
+export declare function normalizeDocsConfig(x: unknown): DocsConfig;
+/**
+ * Lê o config do produto procurando `neetru.config.json` (ou `.neetru.json`)
+ * em `start` e nas pastas ACIMA até a raiz do repositório git (fora de git,
+ * só em `start`). `docs.root` é relativo ao config e pode apontar acima dele
+ * (`../../docs`), desde que fique DENTRO da raiz do repositório git — fora
+ * disso (ou caminho absoluto) é recusado.
+ * Lança `ProductConfigMissingError`/`ProductConfigInvalidError`.
+ */
+export declare function loadProductRepo(start: string): Promise<ProductRepo>;
+/** Versão do `package.json` do produto (pasta do config; senão a base). */
+export declare function readProductVersion(repo: ProductRepo): string | undefined;
+/**
+ * Garante a chave `docs` no config, acrescentando SÓ as subchaves que faltam
+ * (nunca muda valor existente, salvo as listadas em `override`). Devolve as
+ * subchaves acrescentadas/alteradas.
+ */
+export declare function ensureDocsKey(repo: ProductRepo, extra?: Partial<DocsConfig>, dryRun?: boolean, 
+/** Subchaves de `extra` que valem mesmo se já existirem (pedido explícito do usuário). */
+override?: string[]): Promise<string[]>;
+/**
+ * O produto expõe `/api/v1`? `docs.api: true`, ou app móvel registrado
+ * (`.neetru/mobile.json` com apps), ou o config declara `mobile`/`integrations`.
+ */
+export declare function productExposesApi(repo: ProductRepo): boolean;