@spec-wave/cli 0.29.0 → 0.32.0

package/src/lib/qa-plan-doc.mjs

@@ -0,0 +1,340 @@
+// Plano de QA (docs/features/<slug>/qa-plan.md) — módulo PURO, sem I/O.
+//
+// A etapa 🧪 QA era a única do fluxo sem artefato: a validação funcional era
+// manual e não deixava rastro. O qa-plan.md fecha esse buraco — um arquivo por
+// FEATURE (D-QA1), derivado dos critérios de aceite da spec.md, com uma seção
+// `## Cenário N — Story #X` por cenário. O comando `qa <n>` executa esses
+// cenários e o veredito verde/vermelho move o board ou abre Bugs.
+//
+// As regras de parsing ESPELHAM as do decomposition.md de propósito (mesmo
+// fenceScanner, mesma regra "a posição manda, não o número escrito"): quem já
+// edita um, sabe editar o outro.
+//
+// Gramática (v1):
+//
+//   # Plano de QA — <título da Feature>
+//   <!-- spec-wave:qa-plan v1 issue=360 -->
+//
+//   ## Cenário 1 — Story #412
+//
+//   **Critério:** AC-2 — cliente vê apenas os próprios pedidos
+//   **Pré-condições:** dois usuários autenticáveis
+//   **Passos:**
+//   1. Autenticar como usuário A
+//   2. `GET /pedidos`
+//   **Esperado:** resposta 200 contendo somente pedidos de A
+//
+// `**Critério:**` e `**Esperado:**` são obrigatórios; `**Pré-condições:**` e
+// `**Passos:**` são opcionais. O corpo aceita markdown livre.
+
+import { fenceScanner } from './decomposition-doc.mjs';
+import { findIncompleteDocSigns } from './doc-completeness.mjs';
+
+/** Nome do arquivo dentro do diretório da feature. */
+export const QA_PLAN_FILE = 'qa-plan.md';
+
+// Versão do formato, gravada no marcador. Versão MAIOR que a conhecida faz o
+// parse falhar pedindo update da CLI — nunca interpretar errado em silêncio.
+export const QA_PLAN_VERSION = 1;
+
+// Só esta forma é estrutura; "## Detalhes" no corpo de um cenário não é seção.
+// `Story #X` é obrigatório no título — cenário sem dono não tem para quem
+// abrir Bug na reprova.
+const SCENARIO_RE = /^##[ \t]+Cen[aá]rio[ \t]+(\d+)[ \t]*(?:[—–:-][ \t]*)?(?:Story[ \t]*#(\d+))?[ \t]*(.*)$/i;
+const H1_RE = /^#[ \t]+(.*)$/;
+const MARKER_RE = /^<!--[ \t]*spec-wave:qa-plan[ \t]+(.*?)-->[ \t]*$/i;
+
+// Campos da gramática. Valem em qualquer ponto do corpo do cenário (não só no
+// primeiro bloco): o exemplo canônico intercala `**Passos:**` multi-linha entre
+// eles, e restringir ao primeiro bloco quebraria o formato que o próprio
+// gerador emite.
+const FIELD_RE = /^\*\*(Crit[eé]rio|Pr[eé]-?condi[çc][oõ]es|Passos|Esperado):?\*\*:?[ \t]*(.*)$/i;
+
+function invalid(reason) {
+  return new Error(`qa-plan.md inválido: ${reason}.`);
+}
+
+function flatten(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+function trimBlankEdges(lines) {
+  const out = [...lines];
+  while (out.length && !out[0].trim()) out.shift();
+  while (out.length && !out[out.length - 1].trim()) out.pop();
+  return out;
+}
+
+// Canoniza o nome do campo (sem acento/caixa) para a chave do objeto.
+function fieldKey(raw) {
+  const norm = String(raw).normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+  if (norm.startsWith('criterio')) return 'criterio';
+  if (norm.startsWith('pre')) return 'precondicoes';
+  if (norm === 'passos') return 'passos';
+  return 'esperado';
+}
+
+function parseMarker(attrs) {
+  const text = String(attrs || '');
+  const version = /(?:^|\s)v(\d+)(?:\s|$)/.exec(text);
+  const issue = /\bissue=(\d+)\b/.exec(text);
+  return {
+    version: version ? parseInt(version[1], 10) : QA_PLAN_VERSION,
+    issueNumber: issue ? parseInt(issue[1], 10) : null,
+  };
+}
+
+// "# Plano de QA — X" → "X".
+function stripDocTitle(raw) {
+  const text = flatten(raw);
+  const m = /^Plano de QA(?:[ \t]*[—–:-][ \t]*(.*))?$/i.exec(text);
+  return m ? (m[1] || '').trim() : text;
+}
+
+/**
+ * Interpreta o qa-plan.md (função PURA — testável).
+ *
+ * A numeração ESCRITA é ignorada: a posição manda. Inserir um cenário no meio
+ * sem renumerar funciona — a âncora `Cenário N` sai da posição, e o render
+ * devolve a numeração corrigida no ciclo seguinte.
+ *
+ * `Story #X` ausente no título é ERRO de parse (o campo é obrigatório na
+ * gramática); referência a issue que não é sub-issue da Feature é erro de
+ * VALIDAÇÃO (validateQaPlan) — o parser não conhece a árvore de issues.
+ *
+ * @param {string} markdown conteúdo do arquivo
+ * @param {object} [opts]
+ * @param {boolean} [opts.requireMarker] default true; false para conteúdo
+ *        recém-gerado pelo modelo, que ganha o marcador no render canônico
+ * @returns {{version:number, issueNumber:number|null, title:string,
+ *            scenarios: Array<{anchor:string, numero:number, story:number,
+ *            criterio:string, precondicoes:string, passos:string,
+ *            esperado:string, body:string}>}}
+ */
+export function parseQaPlanDoc(markdown, { requireMarker = true } = {}) {
+  const text = String(markdown ?? '').replace(/\r\n?/g, '\n');
+  if (!text.trim()) throw invalid('o arquivo está vazio');
+
+  const scan = fenceScanner();
+  const sections = [];
+  let current = null;
+  let marker = null;
+  let title = '';
+  let sawH1 = false;
+
+  for (const line of text.split('\n')) {
+    if (!scan.inFence(line)) {
+      const m = SCENARIO_RE.exec(line);
+      if (m) {
+        current = { num: m[1], story: m[2] ? parseInt(m[2], 10) : null, rest: m[3] || '', lines: [] };
+        sections.push(current);
+        continue;
+      }
+      if (!current) {
+        const mk = MARKER_RE.exec(line.trim());
+        if (mk && !marker) {
+          marker = parseMarker(mk[1]);
+          continue;
+        }
+        const h1 = H1_RE.exec(line);
+        if (h1 && !sawH1) {
+          title = stripDocTitle(h1[1]);
+          sawH1 = true;
+          continue;
+        }
+      }
+    }
+    if (current) current.lines.push(line);
+  }
+
+  if (scan.isOpen()) {
+    throw invalid(
+      'há um bloco de código (```) aberto e nunca fechado — feche-o para que os ' +
+      'títulos seguintes voltem a ser reconhecidos'
+    );
+  }
+  if (!marker && requireMarker) {
+    throw invalid(
+      `não encontrei o marcador \`<!-- spec-wave:qa-plan v${QA_PLAN_VERSION} … -->\` — ` +
+      'o arquivo não parece um qa-plan.md do spec-wave'
+    );
+  }
+  if (marker && marker.version > QA_PLAN_VERSION) {
+    throw invalid(
+      `está no formato v${marker.version} e esta CLI entende até v${QA_PLAN_VERSION} — ` +
+      'atualize o @spec-wave/cli'
+    );
+  }
+  if (sections.length === 0) {
+    throw invalid('não encontrei nenhum cenário ("## Cenário 1 — Story #<n>")');
+  }
+
+  const scenarios = sections.map((s, i) => {
+    const anchor = `Cenário ${i + 1}`;
+    if (!s.story) {
+      throw invalid(
+        `${anchor} está sem a Story dona — o título precisa ser ` +
+        `"## Cenário N — Story #<issue>" (encontrei "## Cenário ${s.num}${s.rest ? ` — ${s.rest}` : ''}")`
+      );
+    }
+    const fields = { criterio: '', precondicoes: '', passos: '', esperado: '' };
+    // `Passos` é o único campo multi-linha: acumula até o próximo campo.
+    let collecting = null;
+    const fieldScan = fenceScanner();
+    for (const line of s.lines) {
+      const inFence = fieldScan.inFence(line);
+      const f = inFence ? null : FIELD_RE.exec(line);
+      if (f) {
+        const key = fieldKey(f[1]);
+        fields[key] = (f[2] || '').trim();
+        collecting = key === 'passos' ? 'passos' : null;
+        continue;
+      }
+      if (collecting === 'passos' && line.trim()) {
+        fields.passos = fields.passos ? `${fields.passos}\n${line}` : line;
+      } else if (collecting && !line.trim()) {
+        collecting = null;
+      }
+    }
+    return {
+      anchor,
+      numero: i + 1,
+      story: s.story,
+      criterio: fields.criterio,
+      precondicoes: fields.precondicoes,
+      passos: fields.passos,
+      esperado: fields.esperado,
+      body: trimBlankEdges(s.lines).join('\n'),
+    };
+  });
+
+  return {
+    version: marker?.version ?? QA_PLAN_VERSION,
+    issueNumber: marker?.issueNumber ?? null,
+    title,
+    scenarios,
+  };
+}
+
+/**
+ * Renderiza o qa-plan.md CANÔNICO (função PURA).
+ *
+ * Numeração recalculada por posição e marcador sempre presente — é por isso que
+ * o conteúdo recém-gerado pelo modelo passa por parse + render antes de ser
+ * publicado: o arquivo nasce parseável mesmo que o modelo tenha errado a
+ * numeração ou omitido o marcador.
+ *
+ * @param {object} model
+ * @param {string} [model.title] título da Feature (H1)
+ * @param {number|null} [model.issueNumber]
+ * @param {Array<{story:number, body:string}>} [model.scenarios]
+ * @returns {string} markdown terminado em \n
+ */
+export function renderQaPlanDoc({ title = '', issueNumber = null, scenarios = [] } = {}) {
+  const attrs = [`v${QA_PLAN_VERSION}`];
+  const issue = Number(issueNumber);
+  if (Number.isInteger(issue) && issue > 0) attrs.push(`issue=${issue}`);
+
+  const head = flatten(title) ? `# Plano de QA — ${flatten(title)}` : '# Plano de QA';
+  const blocks = [`${head}\n<!-- spec-wave:qa-plan ${attrs.join(' ')} -->`];
+
+  scenarios.forEach((s, i) => {
+    blocks.push(`## Cenário ${i + 1} — Story #${s.story}`);
+    const body = trimBlankEdges(String(s.body ?? '').replace(/\r\n?/g, '\n').split('\n')).join('\n');
+    if (body) blocks.push(body);
+  });
+
+  return `${blocks.join('\n\n')}\n`;
+}
+
+/**
+ * Validação DETERMINÍSTICA do plano, antes da crítica (função PURA).
+ *
+ * Barata e mais confiável que a IA para o que é checável sem julgamento:
+ *  1. toda Story sub-issue da Feature tem ≥ 1 cenário;
+ *  2. todo `Story #X` referenciado é sub-issue real da Feature;
+ *  3. todo cenário tem `**Critério:**` e `**Esperado:**` não vazios;
+ *  4. nenhum sinal objetivo de truncamento (mesmo helper do `validate`).
+ *
+ * Falha aqui evita gastar uma chamada de crítica com um arquivo quebrado.
+ *
+ * @param {object} params
+ * @param {ReturnType<typeof parseQaPlanDoc>} params.doc plano parseado
+ * @param {Array<{number:number, title?:string, state?:string|null,
+ *         stateReason?:string|null}>} params.stories Stories sub-issues da Feature
+ * @param {string} [params.content] markdown bruto (para os sinais de truncamento)
+ * @returns {string[]} erros em pt-BR (vazio = plano válido)
+ */
+export function validateQaPlan({ doc, stories = [], content = '' } = {}) {
+  const errors = [];
+  const byNumber = new Map(stories.map(s => [s.number, s]));
+
+  for (const s of doc?.scenarios || []) {
+    if (!byNumber.has(s.story)) {
+      errors.push(
+        `${s.anchor} referencia a Story #${s.story}, que não é sub-issue desta Feature — ` +
+        'corrija o número (ou o plano está desatualizado em relação à decomposição).'
+      );
+    }
+    if (!s.criterio) {
+      errors.push(`${s.anchor} está sem \`**Critério:**\` — todo cenário precisa dizer QUAL critério de aceite valida.`);
+    }
+    if (!s.esperado) {
+      errors.push(`${s.anchor} está sem \`**Esperado:**\` — sem resultado esperado não há como dar veredito.`);
+    }
+  }
+
+  // Story descartada no rescopo não precisa de cenário; as demais, sim.
+  const covered = new Set((doc?.scenarios || []).map(s => s.story));
+  for (const story of stories) {
+    const descartada = story.state === 'closed' && story.stateReason === 'not_planned';
+    if (!descartada && !covered.has(story.number)) {
+      errors.push(
+        `A Story #${story.number}${story.title ? ` (${story.title})` : ''} não tem nenhum cenário — ` +
+        'toda Story da Feature precisa de ao menos um.'
+      );
+    }
+  }
+
+  for (const problem of findIncompleteDocSigns(content || '')) {
+    errors.push(`O arquivo parece incompleto: ${problem}`);
+  }
+
+  return errors;
+}
+
+/**
+ * Cenários-alvo de uma execução (função PURA).
+ *
+ * `qa <feature>` → todos cujas Stories ainda não têm `qa-approved`;
+ * `qa <story>`   → só os daquela Story;
+ * `--only`       → filtra por número POSICIONAL (coerente com o parser).
+ *
+ * @param {object} params
+ * @param {ReturnType<typeof parseQaPlanDoc>} params.doc
+ * @param {number|null} [params.story] limita à Story (modo `qa <story>`)
+ * @param {number[]} [params.approvedStories] Stories com `spec-wave:qa-approved`
+ * @param {number[]|null} [params.only] números de cenário do `--only`
+ * @returns {{ targets: Array, skippedApproved: Array, unknownOnly: number[] }}
+ */
+export function resolveTargetScenarios({ doc, story = null, approvedStories = [], only = null } = {}) {
+  const approved = new Set(approvedStories);
+  let targets = doc?.scenarios || [];
+  let skippedApproved = [];
+
+  if (story != null) {
+    targets = targets.filter(s => s.story === story);
+  } else {
+    skippedApproved = targets.filter(s => approved.has(s.story));
+    targets = targets.filter(s => !approved.has(s.story));
+  }
+
+  let unknownOnly = [];
+  if (Array.isArray(only) && only.length > 0) {
+    const wanted = new Set(only);
+    unknownOnly = only.filter(n => !targets.some(s => s.numero === n));
+    targets = targets.filter(s => wanted.has(s.numero));
+  }
+
+  return { targets, skippedApproved, unknownOnly };
+}