@spec-wave/cli 0.28.0 → 0.30.0

package/src/lib/qa-report.mjs

@@ -0,0 +1,340 @@
+// Relatório de execução do QA — módulo PURO, sem I/O.
+//
+// O comentário de veredito é a FONTE DE ESTADO entre execuções: rodar com
+// `--only` lê o último relatório da issue para compor o estado acumulado dos
+// cenários que não rodaram desta vez. O marcador HTML da primeira linha é
+// CONTRATO com a UI do SpecWave — mudar o formato exige bump de versão
+// (`v1` → `v2`).
+
+import { createHash } from 'node:crypto';
+import { REQUIRED_BUG_SECTIONS } from '../config.mjs';
+
+export const QA_REPORT_VERSION = 1;
+
+/** Vereditos aceitos por cenário. */
+export const QA_VERDICTS = ['pass', 'fail', 'blocked'];
+
+export const QA_REPORT_MARKER_RE =
+  /<!--\s*spec-wave:qa-report\s+v(?<version>\d+)\s+issue=(?<issue>\d+)\s+run=(?<run>\d+)\s+verdict=(?<verdict>pass|fail|blocked)\s+planSha=(?<planSha>[0-9a-f]+)\s+headSha=(?<headSha>[0-9a-f?]+)\s*-->/g;
+
+// Origem de um Bug aberto por reprovação de QA — gravado no CORPO da issue do
+// Bug. É a chave da idempotência: re-executar o mesmo cenário reprovado não
+// abre um segundo Bug, comenta no que já existe.
+export const QA_ORIGIN_MARKER_RE =
+  /<!--\s*spec-wave:qa-origin\s+issue=(?<issue>\d+)\s+cenario=(?<cenario>\d+)\s*-->/;
+
+/** Monta o marcador do relatório (função PURA). */
+export function qaReportMarker({ issue, run, verdict, planSha, headSha }) {
+  return `<!-- spec-wave:qa-report v${QA_REPORT_VERSION} issue=${issue} run=${run} ` +
+    `verdict=${verdict} planSha=${planSha} headSha=${headSha || '?'} -->`;
+}
+
+/** Monta o marcador de origem de um Bug de QA (função PURA). */
+export function qaOriginMarker({ issue, cenario }) {
+  return `<!-- spec-wave:qa-origin issue=${issue} cenario=${cenario} -->`;
+}
+
+/**
+ * O corpo de um Bug aberto veio deste cenário? (função PURA)
+ *
+ * @param {string} body corpo da issue do Bug
+ * @param {{issue:number, cenario:number}} origem Story dona + número do cenário
+ * @returns {boolean}
+ */
+export function matchesQaOrigin(body, { issue, cenario }) {
+  const m = QA_ORIGIN_MARKER_RE.exec(String(body || ''));
+  if (!m) return false;
+  return parseInt(m.groups.issue, 10) === issue && parseInt(m.groups.cenario, 10) === cenario;
+}
+
+/** SHA curto (7 hex) do conteúdo do plano — vai no marcador do relatório. */
+export function shortSha(content) {
+  return createHash('sha1').update(String(content ?? ''), 'utf-8').digest('hex').slice(0, 7);
+}
+
+/**
+ * Veredito agregado da execução (função PURA).
+ *
+ * `fail` vence `blocked` de propósito: com um defeito confirmado, o desfecho é
+ * vermelho (abre Bug) mesmo que outro cenário tenha ficado bloqueado. `blocked`
+ * sem nenhum `fail` é INCONCLUSIVO — ambiente quebrado não é defeito de
+ * produto, então nada move e nenhum Bug nasce.
+ *
+ * @param {Array<{verdict:string}>} results
+ * @returns {'pass'|'fail'|'blocked'}
+ */
+export function aggregateVerdict(results = []) {
+  if (results.some(r => r.verdict === 'fail')) return 'fail';
+  if (results.some(r => r.verdict === 'blocked')) return 'blocked';
+  return 'pass';
+}
+
+/**
+ * Valida o payload de resultados escrito pelo executor (função PURA).
+ *
+ * O executor (o agente acionado por `qa.command`) grava um JSON com o veredito
+ * de cada cenário. Fora do contrato → erro nomeando o campo: um resultado
+ * ilegível não pode virar aprovação nem reprovação.
+ *
+ * @param {*} payload objeto lido do arquivo de resultados
+ * @param {number[]} expected números dos cenários que DEVIAM ter sido executados
+ * @returns {Array<{numero:number, verdict:'pass'|'fail'|'blocked', evidencia:string}>}
+ */
+export function validateQaResults(payload, expected = []) {
+  if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.scenarios)) {
+    throw new Error('o arquivo de resultados deveria ser {"scenarios": [...]}.');
+  }
+  const out = new Map();
+  payload.scenarios.forEach((item, i) => {
+    const at = `scenarios[${i}]`;
+    const numero = Number(item?.cenario);
+    if (!Number.isInteger(numero) || numero <= 0) {
+      throw new Error(`${at}.cenario deveria ser o número posicional do cenário, veio ${JSON.stringify(item?.cenario)}.`);
+    }
+    const verdict = String(item?.verdict || '').toLowerCase();
+    if (!QA_VERDICTS.includes(verdict)) {
+      throw new Error(
+        `${at}.verdict = ${JSON.stringify(item?.verdict)} não é aceito ` +
+        `(aceitos, exatamente: ${QA_VERDICTS.join(' | ')}).`
+      );
+    }
+    out.set(numero, {
+      numero,
+      verdict,
+      evidencia: String(item?.evidencia ?? '').trim(),
+    });
+  });
+  const missing = expected.filter(n => !out.has(n));
+  if (missing.length > 0) {
+    throw new Error(
+      `faltou o veredito do(s) cenário(s) ${missing.join(', ')} — cenário que não pôde ` +
+      'ser executado deve vir como "blocked", nunca ser omitido.'
+    );
+  }
+  return expected.map(n => out.get(n));
+}
+
+/**
+ * Compõe o estado acumulado quando a execução foi parcial (`--only`) —
+ * função PURA.
+ *
+ * Cenários não executados nesta corrida herdam o veredito do ÚLTIMO relatório;
+ * sem relatório anterior, contam como pendentes (nunca como pass): a aprovação
+ * exige que todos os alvos tenham passado em ALGUMA corrida registrada.
+ *
+ * @param {object} params
+ * @param {Array<{numero:number, verdict:string, evidencia:string}>} params.executed
+ * @param {Map<number, {verdict:string}>} [params.previous] numero → resultado anterior
+ * @param {number[]} params.allNumbers todos os cenários do escopo
+ * @returns {{ combined: Array, pendingNumbers: number[] }}
+ */
+export function combineWithPrevious({ executed = [], previous = new Map(), allNumbers = [] } = {}) {
+  const executedBy = new Map(executed.map(r => [r.numero, r]));
+  const combined = [];
+  const pendingNumbers = [];
+  for (const n of allNumbers) {
+    if (executedBy.has(n)) {
+      combined.push({ ...executedBy.get(n), carried: false });
+      continue;
+    }
+    const prev = previous.get(n);
+    if (prev) {
+      combined.push({ numero: n, verdict: prev.verdict, evidencia: prev.evidencia || '(corrida anterior)', carried: true });
+    } else {
+      pendingNumbers.push(n);
+    }
+  }
+  return { combined, pendingNumbers };
+}
+
+const RESULTS_JSON_RE = /```json spec-wave:qa-results\s*\n([\s\S]*?)\n```/;
+
+/**
+ * Último relatório de QA de uma issue (função PURA).
+ *
+ * Lê os comentários em ordem cronológica; o mais recente vence. O estado por
+ * cenário sai do bloco JSON cercado — reparsear a tabela markdown seria frágil.
+ *
+ * @param {Array<{body?:string}>} comments comentários da issue, em ordem
+ * @returns {{ run: number, verdict: string|null, results: Map<number,object> }}
+ */
+export function parseLastQaReport(comments = []) {
+  let run = 0;
+  let verdict = null;
+  let results = new Map();
+  for (const comment of comments) {
+    const body = String(comment?.body || '');
+    QA_REPORT_MARKER_RE.lastIndex = 0;
+    const m = QA_REPORT_MARKER_RE.exec(body);
+    if (!m) continue;
+    run = Math.max(run, parseInt(m.groups.run, 10));
+    verdict = m.groups.verdict;
+    const bloco = body.match(RESULTS_JSON_RE);
+    if (!bloco) continue;
+    try {
+      const payload = JSON.parse(bloco[1]);
+      if (Array.isArray(payload?.scenarios)) {
+        results = new Map(payload.scenarios
+          .filter(s => Number.isInteger(s?.cenario))
+          .map(s => [s.cenario, { verdict: s.verdict, evidencia: s.evidencia || '' }]));
+      }
+    } catch { /* bloco ilegível não vira estado */ }
+  }
+  return { run, verdict, results };
+}
+
+const VERDICT_ICON = { pass: '✅ pass', fail: '❌ fail', blocked: '⚪ blocked' };
+
+// Evidência entra numa célula de tabela markdown: sem quebra de linha, sem pipe
+// e sem fechar o marcador HTML antes da hora.
+function sanitizeCell(text, max = 200) {
+  const clean = String(text ?? '')
+    .replace(/-->/g, '--‑>')
+    .replace(/\|/g, '\\|')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}
+
+/**
+ * Monta o comentário de relatório de QA (função PURA).
+ *
+ * Primeira linha = marcador (contrato com a UI). O bloco JSON no fim é o que a
+ * próxima execução com `--only` lê para compor o estado acumulado.
+ *
+ * @param {object} params
+ * @param {number} params.issue issue onde o relatório será postado
+ * @param {string} params.scope ex.: "Story #412" ou "Feature #360"
+ * @param {number} params.run número desta execução (1ª, 2ª…)
+ * @param {'pass'|'fail'|'blocked'} params.verdict veredito agregado
+ * @param {string} params.planSha sha curto do qa-plan.md executado
+ * @param {string} [params.headSha] sha curto do HEAD do checkout
+ * @param {Array<{numero, verdict, evidencia, carried?}>} params.results
+ * @param {Array<{number:number, cenario:number, existing?:boolean}>} [params.bugs]
+ * @param {number[]} [params.pendingNumbers] cenários sem veredito em corrida parcial
+ * @param {string} [params.trailer] linha final livre (o que acontece a seguir)
+ * @returns {string} markdown
+ */
+export function renderQaReport({
+  issue, scope, run, verdict, planSha, headSha, results = [], bugs = [],
+  pendingNumbers = [], trailer = '',
+} = {}) {
+  const parts = [
+    qaReportMarker({ issue, run, verdict, planSha, headSha }),
+    '## 🧪 Relatório de QA (spec-wave)',
+    `**Escopo:** ${scope} · **Cenários:** ${results.length} · **Execução:** ${run}ª`,
+  ];
+
+  const linhas = ['| Cenário | Veredito | Evidência |', '|---|---|---|'];
+  for (const r of results) {
+    const carried = r.carried ? ' _(corrida anterior)_' : '';
+    linhas.push(`| ${r.numero} | ${VERDICT_ICON[r.verdict] || r.verdict} | ${sanitizeCell(r.evidencia)}${carried} |`);
+  }
+  parts.push(linhas.join('\n'));
+
+  if (pendingNumbers.length > 0) {
+    parts.push(
+      `⚠️ Cenário(s) ainda **sem veredito** em nenhuma corrida: ${pendingNumbers.join(', ')} — ` +
+      'a aprovação só sai quando todos tiverem passado.'
+    );
+  }
+  if (bugs.length > 0) {
+    parts.push(
+      '**Bugs abertos:** ' +
+      bugs.map(b => `#${b.number} (cenário ${b.cenario}${b.existing ? ', já existia' : ''})`).join(', ')
+    );
+  }
+  if (trailer) parts.push(trailer);
+
+  parts.push([
+    '```json spec-wave:qa-results',
+    JSON.stringify({
+      issue,
+      run,
+      verdict,
+      scenarios: results.map(r => ({
+        cenario: r.numero, verdict: r.verdict, evidencia: sanitizeCell(r.evidencia, 400),
+      })),
+    }, null, 2),
+    '```',
+  ].join('\n'));
+
+  return parts.join('\n\n');
+}
+
+/**
+ * bug.md DETERMINÍSTICO de um cenário reprovado (função PURA).
+ *
+ * Exceção documentada à regra "nunca escreva o bug.md à mão" (spec §2.1):
+ * quando o Bug nasce de um cenário de QA reprovado, a reprodução, o
+ * esperado/obtido e o teste de regressão JÁ EXISTEM e são determinísticos — são
+ * o próprio cenário e a saída real da execução. Regenerar por IA só
+ * introduziria alucinação sobre uma execução observada.
+ *
+ * Emite EXATAMENTE as seis seções de REQUIRED_BUG_SECTIONS (o validate compara
+ * byte a byte com `# <seção>`).
+ *
+ * @param {object} params
+ * @param {string} params.title título do Bug (sem o prefixo [BUG])
+ * @param {{anchor, numero, story, criterio, precondicoes, passos, esperado}} params.scenario
+ * @param {string} params.evidence evidência bruta da reprovação
+ * @param {string} params.severity P0–P3
+ * @param {string} [params.headSha] commit do checkout onde a reprova aconteceu
+ * @param {number|null} [params.featureNumber]
+ * @returns {string} markdown
+ */
+export function renderQaBugDoc({
+  title, scenario, evidence, severity, headSha = null, featureNumber = null,
+} = {}) {
+  const [
+    reproducao, esperadoObtido, impacto, causaRaiz, escopo, regressao,
+  ] = REQUIRED_BUG_SECTIONS;
+  const passos = scenario.passos
+    ? scenario.passos
+    : '_(o cenário não declara passos — ver o corpo do cenário no qa-plan.md)_';
+  const pre = scenario.precondicoes ? `**Pré-condições:** ${scenario.precondicoes}\n\n` : '';
+  return [
+    `# [BUG] ${title}`,
+    '',
+    `> Aberto automaticamente pela reprovação do **${scenario.anchor}** do plano de QA` +
+    `${featureNumber ? ` da Feature #${featureNumber}` : ''} (Story #${scenario.story})` +
+    `${headSha ? `, no commit \`${headSha}\`` : ''}. Conteúdo determinístico: cenário + saída real da execução.`,
+    '',
+    `## ${reproducao}`,
+    '',
+    pre + passos,
+    '',
+    `## ${esperadoObtido}`,
+    '',
+    `**Critério:** ${scenario.criterio || '—'}`,
+    '',
+    `**Esperado:** ${scenario.esperado || '—'}`,
+    '',
+    `**Obtido:** ${evidence || '(sem evidência registrada)'}`,
+    '',
+    `## ${impacto}`,
+    '',
+    `Severidade **${severity}**. O critério de aceite acima está descumprido na Story #${scenario.story} — ` +
+    'a Story não avança de 🧪 QA enquanto este Bug estiver aberto.',
+    '',
+    `## ${causaRaiz}`,
+    '',
+    '_A investigar durante a correção — este documento registra uma execução observada, ' +
+    'não uma hipótese de causa._',
+    '',
+    `## ${escopo}`,
+    '',
+    '_A definir na investigação. O fix precisa fazer o cenário abaixo passar sem alterar o critério de aceite._',
+    '',
+    `## ${regressao}`,
+    '',
+    `Re-executar o cenário reprovado após o fix:`,
+    '',
+    '```bash',
+    `npx @spec-wave/cli@latest qa ${scenario.story} --only ${scenario.numero}`,
+    '```',
+    '',
+    `O veredito precisa ser **pass** com o mesmo esperado: ${scenario.esperado || '—'}`,
+    '',
+  ].join('\n');
+}