@spec-wave/cli 0.13.0 → 0.15.0

package/src/lib/decomposition-doc.mjs

@@ -0,0 +1,451 @@
+// Documento de decomposição (docs/features/<slug>/decomposition.md) — módulo
+// PURO, sem I/O e sem dependências.
+//
+// O decompose deixou de criar issues direto do JSON do modelo. Antes, quando a
+// crítica reprovava, o rascunho era descartado e os achados citavam uma "Story 5"
+// que não existia em lugar nenhum — nem na issue, nem no repo, nem no log da
+// Action. Agora o rascunho é gravado aqui, o humano revisa e corrige, e só a
+// label spec-wave:decompose-apply cria as issues.
+//
+// Por isso o formato precisa ser ao mesmo tempo (a) legível e editável à mão e
+// (b) reversível: render(parse(render(x))) === render(x). Sem a reversibilidade,
+// uma edição humana desaparece silenciosamente no apply — o pior erro possível
+// aqui, porque ninguém percebe.
+//
+// Gramática (v1):
+//
+//   # Decomposição — <título da issue>
+//   <!-- spec-wave:decomposition v1 issue=360 kind=stories -->
+//
+//   ## Story 1 — <título curto>
+//
+//   **User story:** Como <perfil>, quero <objetivo>, para <benefício>
+//   **Depende de:** Story 1, Story 2          (ou "—" para nenhuma)
+//
+//   <corpo livre, multi-linha>
+//
+//   ### Task 1.1 — <título curto>
+//
+//   <corpo livre, multi-linha>
+//
+// kind=tasks (RFC) não tem Stories — as tasks ficam em "## Task N — <título>".
+
+// Nome do arquivo dentro do diretório da feature/RFC.
+export const DECOMPOSITION_FILE = 'decomposition.md';
+
+// Versão do formato, gravada no marcador. Um arquivo de versão MAIOR faz o parse
+// falhar pedindo update da CLI, em vez de interpretar errado em silêncio.
+export const DOC_VERSION = 1;
+
+// Só estas três formas são estrutura. "## Backend" ou "### Detalhes" no corpo de
+// uma story NÃO são título de seção — é o que permite corpo com markdown livre.
+const STORY_RE    = /^##[ \t]+Story[ \t]+(\d+)[ \t]*(?:[—–:-][ \t]*)?(.*)$/i;
+const RFC_TASK_RE = /^##[ \t]+Task[ \t]+(\d+)[ \t]*(?:[—–:-][ \t]*)?(.*)$/i;
+const TASK_RE     = /^###[ \t]+Task[ \t]+(\d+(?:\.\d+)*)[ \t]*(?:[—–:-][ \t]*)?(.*)$/i;
+// Espelho das três acima, tolerando as barras de escape já aplicadas.
+const STRUCTURAL_RE = /^\\*#{2,3}[ \t]+(?:Story|Task)[ \t]+\d/i;
+
+const H1_RE         = /^#[ \t]+(.*)$/;
+const MARKER_RE     = /^<!--[ \t]*spec-wave:decomposition[ \t]+(.*?)-->[ \t]*$/i;
+const USER_STORY_RE = /^\*\*User story:?\*\*:?[ \t]*(.*)$/i;
+const DEPENDS_RE    = /^\*\*Depende de:?\*\*:?[ \t]*(.*)$/i;
+const EMPTY_VALUE_RE = /^(—|–|-|nenhuma|nenhum|none|n\/a)$/i;
+const FENCE_RE      = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+
+function invalid(reason) {
+  return new Error(`decomposition.md inválido: ${reason}.`);
+}
+
+/**
+ * Rastreador de blocos de código. O MESMO rastreador roda no parse e no escape
+ * do render — é isso que garante que uma linha "## Story 2 — x" dentro de um
+ * bloco ```…``` não vire seção nem receba barra de escape.
+ *
+ * Regras do CommonMark que importam aqui: a cerca tem 3+ caracteres, o
+ * fechamento usa o mesmo caractere e comprimento >= o da abertura, e uma cerca
+ * de crase não aceita crase na info string.
+ */
+function fenceScanner() {
+  let open = null;
+  return {
+    // true quando a linha pertence a um bloco de código (abertura, conteúdo ou
+    // fechamento): nela nada é interpretado como estrutura.
+    inFence(line) {
+      const m = FENCE_RE.exec(line);
+      if (m) {
+        const char = m[1][0];
+        const len = m[1].length;
+        if (!open) {
+          if (!(char === '`' && m[2].includes('`'))) {
+            open = { char, len };
+            return true;
+          }
+        } else if (char === open.char && len >= open.len && m[2].trim() === '') {
+          open = null;
+          return true;
+        }
+      }
+      return open !== null;
+    },
+    isOpen() { return open !== null; },
+    marker() { return open ? open.char.repeat(open.len) : ''; },
+  };
+}
+
+// Um corpo que abre bloco de código e não fecha engoliria todos os títulos
+// seguintes. Fechamos na ESCRITA para o arquivo nascer sempre parseável; no
+// parse, esse mesmo desbalanceamento vira erro — lá ele veio de edição humana.
+function balanceFences(text) {
+  const scan = fenceScanner();
+  for (const line of text.split('\n')) scan.inFence(line);
+  return scan.isOpen() ? `${text}\n${scan.marker()}` : text;
+}
+
+// Barra de escape em linhas do corpo que imitariam um título de seção. `\#` é
+// escape válido de CommonMark: o GitHub renderiza "## Story 9 — x" literal, e o
+// parse remove exatamente uma barra — reversível mesmo em texto já escapado.
+function escapeStructural(text) {
+  const scan = fenceScanner();
+  return text.split('\n')
+    .map(line => (scan.inFence(line) || !STRUCTURAL_RE.test(line) ? line : `\\${line}`))
+    .join('\n');
+}
+
+function unescapeStructural(text) {
+  const scan = fenceScanner();
+  return text.split('\n')
+    .map(line => (
+      !scan.inFence(line) && line.startsWith('\\') && STRUCTURAL_RE.test(line)
+        ? line.slice(1)
+        : line
+    ))
+    .join('\n');
+}
+
+// Título e user story ocupam UMA linha na gramática; texto multi-linha vindo do
+// modelo é achatado aqui, senão quebraria o seccionamento.
+function flatten(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+// Apara as linhas em branco das PONTAS mantendo o miolo intacto — linha em
+// branco no meio do corpo é conteúdo.
+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;
+}
+
+function renderBody(value) {
+  const lines = trimBlankEdges(String(value ?? '').replace(/\r\n?/g, '\n').split('\n'));
+  if (lines.length === 0) return '';
+  return escapeStructural(balanceFences(lines.join('\n')));
+}
+
+function readBody(lines) {
+  return unescapeStructural(trimBlankEdges(lines).join('\n'));
+}
+
+// Mesma regra que o loop de criação aplicava sobre o JSON do modelo: índices
+// 0-based, sem duplicatas, apenas para stories ANTERIORES; campo ausente =
+// dependência sequencial da story anterior; [] explícito = sem dependências.
+// Aplicada no RENDER, para o arquivo já nascer com a decisão materializada.
+function normalizeDependsOn(dependsOn, index) {
+  if (!Array.isArray(dependsOn)) return index > 0 ? [index - 1] : [];
+  return [...new Set(dependsOn.filter(d => Number.isInteger(d) && d >= 0 && d < index))]
+    .sort((a, b) => a - b);
+}
+
+/**
+ * Renderiza o decomposition.md (função PURA — testável).
+ *
+ * A saída é CANÔNICA: numeração recalculada por posição, dependências resolvidas
+ * e ordenadas, títulos achatados, corpos com cercas balanceadas e linhas
+ * ambíguas escapadas. Aceita direto a shape do JSON do modelo, então o
+ * decompose não precisa de conversão intermediária.
+ *
+ * @param {object} model
+ * @param {string} [model.title] título da issue (vai para o H1)
+ * @param {number|null} [model.issueNumber] número da issue (marcador)
+ * @param {'stories'|'tasks'} [model.kind] Feature → stories; RFC → tasks
+ * @param {string} [model.preamble] nota livre entre o marcador e a 1ª seção
+ * @param {Array<object>} [model.stories] stories (kind=stories)
+ * @param {Array<object>} [model.tasks] tasks (kind=tasks)
+ * @returns {string} markdown terminado em \n
+ */
+export function renderDecompositionDoc({
+  title = '', issueNumber = null, kind = 'stories', preamble = '', stories = [], tasks = [],
+} = {}) {
+  if (kind !== 'stories' && kind !== 'tasks') {
+    throw new Error(`decomposition.md: kind inválido "${kind}" (use "stories" ou "tasks").`);
+  }
+
+  const attrs = [`v${DOC_VERSION}`];
+  const issue = Number(issueNumber);
+  if (Number.isInteger(issue) && issue > 0) attrs.push(`issue=${issue}`);
+  attrs.push(`kind=${kind}`);
+
+  const head = flatten(title) ? `# Decomposição — ${flatten(title)}` : '# Decomposição';
+  const blocks = [`${head}\n<!-- spec-wave:decomposition ${attrs.join(' ')} -->`];
+
+  const note = renderBody(preamble);
+  if (note) blocks.push(note);
+
+  const pushItem = (heading, item) => {
+    blocks.push(`${heading} — ${flatten(item?.title) || '(sem título)'}`);
+    const body = renderBody(item?.body);
+    if (body) blocks.push(body);
+  };
+
+  if (kind === 'tasks') {
+    (tasks || []).forEach((task, i) => pushItem(`## Task ${i + 1}`, task));
+  } else {
+    (stories || []).forEach((story, i) => {
+      blocks.push(`## Story ${i + 1} — ${flatten(story?.title) || '(sem título)'}`);
+      const deps = normalizeDependsOn(story?.dependsOn, i);
+      // As DUAS linhas de campo saem SEMPRE, seguidas de linha em branco: é essa
+      // linha em branco que impede um corpo começando com "**Depende de:** …" de
+      // ser confundido com o campo.
+      blocks.push([
+        `**User story:** ${flatten(story?.userStory) || '—'}`,
+        `**Depende de:** ${deps.length ? deps.map(d => `Story ${d + 1}`).join(', ') : '—'}`,
+      ].join('\n'));
+      const body = renderBody(story?.body);
+      if (body) blocks.push(body);
+      (story?.tasks || []).forEach((task, j) => pushItem(`### Task ${i + 1}.${j + 1}`, task));
+    });
+  }
+
+  return `${blocks.join('\n\n')}\n`;
+}
+
+function parseMarker(attrs) {
+  const text = String(attrs || '');
+  const version = /(?:^|\s)v(\d+)(?:\s|$)/.exec(text);
+  const issue = /\bissue=(\d+)\b/.exec(text);
+  const kind = /\bkind=(stories|tasks)\b/i.exec(text);
+  return {
+    version: version ? parseInt(version[1], 10) : DOC_VERSION,
+    issueNumber: issue ? parseInt(issue[1], 10) : null,
+    kind: kind ? kind[1].toLowerCase() : null,
+  };
+}
+
+// "# Decomposição — X" → "X"; "# Decomposição" → "". Sem esta segunda parte, o
+// próprio prefixo viraria o título na segunda passada do round-trip.
+function stripDocTitle(raw) {
+  const text = flatten(raw);
+  const m = /^Decomposição(?:[ \t]*[—–:-][ \t]*(.*))?$/i.exec(text);
+  return m ? (m[1] || '').trim() : text;
+}
+
+function requireTitle(value, anchor) {
+  const title = flatten(value);
+  if (!title) {
+    const hashes = /^Story \d+$|^Task \d+$/.test(anchor) ? '##' : '###';
+    throw invalid(`${anchor} está sem título — use "${hashes} ${anchor} — título curto"`);
+  }
+  return title;
+}
+
+// "Story 1, Story 3" → [0, 2]. Linha ausente ou "—" → []. Referência a si mesma
+// ou a uma story POSTERIOR é erro: num arquivo editado à mão, filtrar em
+// silêncio (como se fazia com o JSON do modelo) esconderia o engano do humano.
+function parseDependsValue(raw, index, anchor) {
+  if (raw === null || raw === undefined) return [];
+  const value = raw.trim();
+  if (!value || EMPTY_VALUE_RE.test(value)) return [];
+  const matches = [...value.matchAll(/story[ \t]*(\d+)/gi)];
+  if (matches.length === 0) {
+    throw invalid(
+      `não entendi "**Depende de:** ${value}" em ${anchor} — use "Story 1, Story 2" ou "—"`
+    );
+  }
+  const out = [];
+  for (const m of matches) {
+    const n = parseInt(m[1], 10);
+    if (n < 1 || n - 1 >= index) {
+      throw invalid(
+        `${anchor} depende de "Story ${n}", que não é uma Story anterior a ela — ` +
+        'dependências só apontam para trás'
+      );
+    }
+    if (!out.includes(n - 1)) out.push(n - 1);
+  }
+  return out.sort((a, b) => a - b);
+}
+
+// Os campos valem SÓ no primeiro bloco não-vazio abaixo do título. É o que deixa
+// o corpo conter uma linha "**Depende de:** #12" sem que ela vire campo.
+function splitStorySection(lines, anchor) {
+  let i = 0;
+  while (i < lines.length && !lines[i].trim()) i++;
+  let userStory = null;
+  let depends = null;
+  while (i < lines.length && lines[i].trim()) {
+    const us = USER_STORY_RE.exec(lines[i]);
+    const dep = us ? null : DEPENDS_RE.exec(lines[i]);
+    if (!us && !dep) break;
+    if (us) {
+      if (userStory !== null) throw invalid(`${anchor} tem duas linhas "**User story:**"`);
+      userStory = us[1].trim();
+    } else {
+      if (depends !== null) throw invalid(`${anchor} tem duas linhas "**Depende de:**"`);
+      depends = dep[1].trim();
+    }
+    i++;
+  }
+  return {
+    userStory: !userStory || EMPTY_VALUE_RE.test(userStory) ? '' : userStory,
+    depends,
+    body: readBody(lines.slice(i)),
+  };
+}
+
+/**
+ * Interpreta o decomposition.md (função PURA — testável).
+ *
+ * Devolve exatamente a shape que o loop de criação de issues consome
+ * (`stories[].{title,userStory,body,dependsOn,tasks[]}`, com dependsOn 0-based),
+ * mais os metadados do marcador e a âncora estável de cada item ("Story 3",
+ * "Task 3.2") — é a âncora que a crítica cita no comentário da issue.
+ *
+ * A numeração ESCRITA no arquivo é ignorada: a posição manda. Assim um humano que
+ * insere uma Story no meio sem renumerar não quebra nada (o render devolve a
+ * numeração corrigida no ciclo seguinte).
+ *
+ * Lança Error em pt-BR sempre citando a âncora do item problemático — a mensagem
+ * vai para o log da Action e para o comentário da issue.
+ *
+ * @param {string} markdown conteúdo do arquivo
+ * @returns {{version:number, issueNumber:number|null, kind:'stories'|'tasks',
+ *            title:string, preamble:string, stories:object[], tasks:object[]}}
+ */
+export function parseDecompositionDoc(markdown) {
+  const text = String(markdown ?? '').replace(/\r\n?/g, '\n');
+  if (!text.trim()) throw invalid('o arquivo está vazio');
+
+  const scan = fenceScanner();
+  const sections = [];
+  const preamble = [];
+  let current = null;
+  let marker = null;
+  let title = '';
+  let sawH1 = false;
+
+  for (const line of text.split('\n')) {
+    // inFence PRECISA ser chamado uma vez por linha, na ordem — é ele que
+    // mantém o estado do bloco de código.
+    if (!scan.inFence(line)) {
+      const story = STORY_RE.exec(line);
+      const rfcTask = story ? null : RFC_TASK_RE.exec(line);
+      const task = story || rfcTask ? null : TASK_RE.exec(line);
+      const m = story || rfcTask || task;
+      if (m) {
+        current = {
+          type: story ? 'story' : rfcTask ? 'rfc-task' : 'task',
+          num: m[1],
+          title: m[2],
+          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;
+        }
+      }
+    }
+    (current ? current.lines : preamble).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) {
+    throw invalid(
+      `não encontrei o marcador \`<!-- spec-wave:decomposition v${DOC_VERSION} … -->\` — ` +
+      'o arquivo não parece um decomposition.md do spec-wave'
+    );
+  }
+  if (marker.version > DOC_VERSION) {
+    throw invalid(
+      `está no formato v${marker.version} e esta CLI entende até v${DOC_VERSION} — ` +
+      'atualize o @spec-wave/cli'
+    );
+  }
+
+  const kind = marker.kind || (sections.some(s => s.type === 'story') ? 'stories' : 'tasks');
+  const doc = {
+    version: marker.version,
+    issueNumber: marker.issueNumber,
+    kind,
+    title,
+    preamble: readBody(preamble),
+    stories: [],
+    tasks: [],
+  };
+
+  if (kind === 'tasks') {
+    const alien = sections.find(s => s.type !== 'rfc-task');
+    if (alien) {
+      throw invalid(
+        'em um documento kind=tasks só cabem títulos "## Task N — …"; encontrei ' +
+        `"${alien.type === 'story' ? `## Story ${alien.num}` : `### Task ${alien.num}`}"`
+      );
+    }
+    doc.tasks = sections.map((s, i) => {
+      const anchor = `Task ${i + 1}`;
+      return { anchor, title: requireTitle(s.title, anchor), body: readBody(s.lines) };
+    });
+    if (doc.tasks.length === 0) throw invalid('não encontrei nenhuma Task ("## Task 1 — …")');
+    return doc;
+  }
+
+  for (const section of sections) {
+    if (section.type === 'story') {
+      const anchor = `Story ${doc.stories.length + 1}`;
+      const { userStory, depends, body } = splitStorySection(section.lines, anchor);
+      doc.stories.push({
+        anchor,
+        title: requireTitle(section.title, anchor),
+        userStory,
+        body,
+        dependsOn: parseDependsValue(depends, doc.stories.length, anchor),
+        tasks: [],
+      });
+      continue;
+    }
+    if (section.type === 'rfc-task') {
+      throw invalid(
+        `"## Task ${section.num}" aparece em um documento de Stories — ` +
+        'Tasks de Story usam "### Task N.M — …"'
+      );
+    }
+    if (doc.stories.length === 0) {
+      throw invalid(
+        `a Task "${flatten(section.title) || section.num}" aparece antes de qualquer ` +
+        '"## Story N — …"'
+      );
+    }
+    const story = doc.stories[doc.stories.length - 1];
+    const anchor = `Task ${doc.stories.length}.${story.tasks.length + 1}`;
+    story.tasks.push({ anchor, title: requireTitle(section.title, anchor), body: readBody(section.lines) });
+  }
+
+  if (doc.stories.length === 0) throw invalid('não encontrei nenhuma Story ("## Story 1 — …")');
+  return doc;
+}

package/src/lib/implement-board.mjs

@@ -67,9 +67,22 @@ export function planBoardMoves(phase, {
  * Executa os movimentos no Projects v2. Best-effort: qualquer falha vira
  * warn e a implementação continua. Usa PROJECT_TOKEN quando definido (PAT
  * com scope de Project em org — mesmo padrão do code-review/qa).
+ *
+ * Com `dryRun`, apenas ANUNCIA os movimentos: nada é escrito no GitHub. Sem
+ * isso, `implement --dry-run` movia cards de verdade (foi o caso da #239, que
+ * saiu de Todo para In Progress numa execução em que nada foi executado) —
+ * um dry-run não pode ter efeito colateral remoto.
  */
-export async function applyBoardMoves({ token, moves, cwd = process.cwd(), log = p.log }) {
+export async function applyBoardMoves({
+  token, moves, cwd = process.cwd(), log = p.log, dryRun = false,
+}) {
   if (!moves || moves.length === 0) return;
+  if (dryRun) {
+    for (const m of moves) {
+      log.info(`board (dry-run): ${m.label} → ${m.stage} (${m.status}) — não aplicado`);
+    }
+    return;
+  }
   try {
     const { project, error } = loadProjectConfig({ cwd });
     if (error) {