@spec-wave/cli 0.30.0 → 0.33.0

package/src/commands/implement.mjs

@@ -9,7 +9,7 @@ import {
   PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE, labelNames,
 } from '../config.mjs';
 import { getIssue, listIssueComments, listBlockedBy, getFileContent } from '../api/github-rest.mjs';
-import { listSubIssues, getIssueParent, addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import { listSubIssues, getIssueParent } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { bugDocPaths } from '../lib/bug-doc.mjs';
 import { missingDocMessage, existsOnRemote } from '../lib/doc-availability.mjs';
@@ -17,10 +17,12 @@ import { loadArtifact } from '../lib/doc-source.mjs';
 import { buildBugContext } from '../lib/bug-context.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
-import { loadProjectConfig, resolveField } from '../lib/board.mjs';
+import { loadProjectConfig } from '../lib/board.mjs';
 import { planBoardMoves, applyBoardMoves } from '../lib/implement-board.mjs';
 import { extractPathsFromPlan, buildCodeDigest } from '../lib/code-digest.mjs';
-import { findConfigPath, resolveFromRoot } from '../lib/project-root.mjs';
+import { findConfigPath, resolveFromRoot, loadConfig } from '../lib/project-root.mjs';
+import { loadFeatureStories, loadBoardSnapshot, cachedSubIssues } from '../lib/story-graph.mjs';
+import { resolveCacheTtl } from '../lib/net-cache.mjs';
 
 // Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
 const WORK_DIR = '.spec-wave';
@@ -263,44 +265,41 @@ function buildContext({
  * Etapa de cada item no board, por número. Best-effort: qualquer falha vira
  * `null` para aquele item (tratado como "não implementado" por quem consome).
  *
- * A leitura passa por `addProjectItem`, que é MUTAÇÃO — adiciona o item ao
- * Project se ainda não estiver lá. Por isso a consulta inteira é pulada em
- * dry-run: um dry-run não pode ter efeito remoto.
+ * UM `listProjectItems` paginado (leitura PURA) no lugar do par
+ * addProjectItem+getItemSingleSelectValue por item — que custava 2 chamadas e
+ * era MUTAÇÃO em caminho de leitura. Duas consequências:
+ *  • dry-run agora VÊ as Etapas reais (a leitura deixou de ter efeito remoto);
+ *  • `fresh: true` sempre — o que sai daqui alimenta gates de ESCRITA
+ *    (`skipped` do plano, `featureCanAdvance`), e gate não decide com cache.
+ *    O snapshot fresco é gravado no cache mesmo assim: o `order`/`merge`
+ *    seguinte da sessão o reaproveita de graça.
  *
  * @param {string} token
  * @param {Array<{number:number, nodeId:string}>} items
- * @param {{dryRun?:boolean, warnOnSkip?:boolean}} [opts]
+ * @param {{warnOnSkip?:boolean}} [opts]
  * @returns {Promise<Map<number, string|null>>}
  */
-async function fetchStagesOf(token, items, { dryRun = false, warnOnSkip = false } = {}) {
+async function fetchStagesOf(token, items, { warnOnSkip = false } = {}) {
   const stageOf = new Map();
   if (items.length === 0) return stageOf;
   const { project, error: projectError } = loadProjectConfig();
-  if (dryRun) {
-    if (warnOnSkip) {
-      p.log.warn(
-        'Dry-run: Etapas do board não consultadas (a consulta adicionaria itens ao Project); ' +
-        'nenhuma Story será considerada implementada.'
-      );
-    }
-    return stageOf;
-  }
   if (projectError) {
     if (warnOnSkip) {
       p.log.warn(`${projectError} — Etapas do board não consultadas; nenhuma Story será considerada implementada.`);
     }
     return stageOf;
   }
-  const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
-  if (!etapaField?.id) return stageOf;
-  await Promise.all(items.map(async (s) => {
-    try {
-      const itemId = await addProjectItem(token, project.id, s.nodeId);
-      stageOf.set(s.number, await getItemSingleSelectValue(token, itemId, etapaField.id));
-    } catch {
-      stageOf.set(s.number, null);
+  try {
+    const { root } = loadConfig();
+    const snapshot = await loadBoardSnapshot({ token, project, root, fresh: true });
+    for (const s of items) {
+      stageOf.set(s.number, snapshot.index.get(s.number)?.fields?.Etapa ?? null);
     }
-  }));
+  } catch (err) {
+    if (warnOnSkip) {
+      p.log.warn(`Etapas do board não consultáveis agora (${err.message}); nenhuma Story será considerada implementada.`);
+    }
+  }
   return stageOf;
 }
 
@@ -576,10 +575,25 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
   });
 }
 
-async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun, repoRoot }) {
-  // F1. Stories (sub-issues) da Feature.
-  const subs = await listSubIssues(token, feature.node_id).catch(() => []);
-  const stories = subs.filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun, repoRoot, refresh = false }) {
+  const ttlSec = resolveCacheTtl(config);
+
+  // F1-F2. Stories da Feature com as arestas já resolvidas (lib/story-graph):
+  // dependency-map.json/decomposition.md ∪ linhas "Depende de:" do body — zero
+  // chamada por Story (o blocked_by só-de-UI entra via `order --remote`/`--sync`).
+  let carga;
+  try {
+    carga = await loadFeatureStories({
+      token, owner, repo, root: repoRoot,
+      feature: { number: feature.number, nodeId: feature.node_id, title: feature.title },
+      refresh, ttlSec,
+    });
+  } catch (err) {
+    p.log.error(`Não foi possível listar as Stories da Feature #${feature.number}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const stories = carga.stories;
   if (stories.length === 0) {
     p.log.error(
       `Feature #${feature.number} não tem Stories (sub-issues). ` +
@@ -589,24 +603,19 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
     return;
   }
   p.log.info(`Feature com ${stories.length} story(ies): ${stories.map(s => `#${s.number}`).join(', ')}`);
+  for (const w of carga.warnings) p.log.warn(w);
 
   // F1-board. Feature → Desenvolvimento (In Progress) já no início.
   await applyBoardMoves({ token, dryRun, moves: planBoardMoves('start', {
     feature: { nodeId: feature.node_id, number: feature.number },
   }) });
 
-  // F2. Dependências de cada Story: linha "Depende de:" do body ∪ blocked_by nativo.
-  const enriched = await Promise.all(stories.map(async (s) => {
-    let body = s.body;
-    if (!body) body = (await getIssue(token, owner, repo, s.number).catch(() => null))?.body || '';
-    const deps = new Set(parseDependencies(body));
-    const blocked = await listBlockedBy(token, owner, repo, s.number).catch(() => []);
-    for (const b of blocked) deps.add(b.number);
-    return { number: s.number, title: s.title, nodeId: s.nodeId, body: body || '', dependsOn: [...deps] };
+  const enriched = stories.map(s => ({
+    number: s.number, title: s.title, nodeId: s.nodeId, body: s.body || '', dependsOn: s.dependsOn,
   }));
 
   // F3. Etapa de cada Story no board (best-effort — sem board, nada é pulado).
-  const stageOf = await fetchStagesOf(token, enriched, { dryRun, warnOnSkip: true });
+  const stageOf = await fetchStagesOf(token, enriched, { warnOnSkip: true });
 
   // F4. Planejamento: pendentes em ordem topológica, puladas, ciclos.
   const { pending, skipped, cycle } = planFeatureImplementation(
@@ -641,10 +650,13 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   }
   p.log.info(`Ordem de implementação: ${pending.map(s => `#${s.number}`).join(' → ')}`);
 
-  // F5. Tasks de cada Story pendente.
+  // F5. Tasks de cada Story pendente (cache `subissues-<story>` com TTL —
+  // título/corpo de Task não mudam no meio de uma sessão de implement).
   const noTasks = [];
   for (const s of pending) {
-    const storySubs = await listSubIssues(token, s.nodeId).catch(() => []);
+    const { subs: storySubs } = await cachedSubIssues({
+      token, owner, repo, root: repoRoot, parent: { number: s.number, nodeId: s.nodeId }, refresh, ttlSec,
+    }).catch(() => ({ subs: [] }));
     s.tasks = storySubs
       .filter(t => detectIssueType({ title: t.title, labels: t.labels }) === 'Task')
       .map(t => ({ number: t.number, title: t.title, body: t.body || '', nodeId: t.nodeId }));
@@ -775,7 +787,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   });
 }
 
-export async function implement({ issue: issueArg, featureDir: featureDirOpt, dryRun }) {
+export async function implement({ issue: issueArg, featureDir: featureDirOpt, dryRun, refresh = false }) {
   const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
   if (!Number.isInteger(issueNumber)) {
     p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 12 ou #12.`);
@@ -846,7 +858,7 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     p.log.info(`Task única #${issueNumber}.`);
   } else if (type === 'Feature') {
     // Modo Feature: Stories pendentes em ordem de dependência, contexto único.
-    await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun, repoRoot });
+    await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun, repoRoot, refresh });
     return;
   } else if (type === 'Bug') {
     // Modo Bug: sem tasks e sem spec/plan — o trabalho é investigar antes de
@@ -996,7 +1008,7 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
       // Sem irmãs, esta era a única Story: a Feature avança direto (nada a
       // consultar). Com irmãs, todas precisam já estar em Code Review+.
       if (siblingStories.length > 0) {
-        const stageOf = await fetchStagesOf(token, siblingStories, { dryRun });
+        const stageOf = await fetchStagesOf(token, siblingStories, {});
         if (!featureCanAdvance(siblingStories, stageOf)) return;
       }
       await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {

package/src/commands/merge.mjs

@@ -21,12 +21,14 @@ import chalk from 'chalk';
 
 import { resolveToken } from '../api/auth.mjs';
 import {
-  getIssue, getPR, getRepoDefaultBranch, updatePRBase, mergePR, deleteBranch, listBlockedBy,
+  getIssue, getPR, getRepoDefaultBranch, updatePRBase, mergePR, deleteBranch,
 } from '../api/github-rest.mjs';
-import { listSubIssues, listIssuePullRequests } from '../api/github-graphql.mjs';
+import { listIssuePullRequests } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
-import { resolveRepoContext } from '../lib/project-root.mjs';
+import { orderStories } from '../lib/dependencies.mjs';
+import { resolveRepoContext, loadConfig } from '../lib/project-root.mjs';
+import { loadFeatureStories } from '../lib/story-graph.mjs';
+import { resolveCacheTtl, invalidateCache } from '../lib/net-cache.mjs';
 import { CONFIG_FILE } from '../config.mjs';
 import { acquireLock, releaseLock } from './run.mjs';
 import { codeReview } from './code-review.mjs';
@@ -108,7 +110,12 @@ export function planMerge({ sorted = [], byNumber = new Map(), prsByStory = new
   return { fila, concluidas, semPr, bloqueios, avisos };
 }
 
-export async function merge({ feature: featureArg, yes = false, dryRun = false, keepBranches = false } = {}) {
+export async function merge({
+  feature: featureArg, yes = false, dryRun = false, keepBranches = false,
+  remote = false, refresh = false,
+} = {}) {
+  const { config: fileConfig, root: repoRoot } = loadConfig();
+  const ttlSec = resolveCacheTtl(fileConfig);
   if (process.env.GITHUB_ACTIONS === 'true') {
     p.log.error('`spec-wave merge` é um comando local — dentro do Actions o merge é decisão humana.');
     process.exitCode = 1;
@@ -163,29 +170,46 @@ export async function merge({ feature: featureArg, yes = false, dryRun = false,
     return;
   }
 
-  // As Stories e a ordem — as mesmas fontes do `order`.
-  let subs;
+  // As Stories e a ordem — as mesmas fontes do `order` (lib/story-graph).
+  //
+  // Política de coerência: no PLANO (sem --yes), as arestas locais bastam —
+  // mostrar a fila não muda nada. Na EXECUÇÃO, blocked_by remoto FRESCO é
+  // obrigatório: o merge de PRs empilhados é irreversível ("merge parcial de
+  // pilha é o pior estado"), e a aresta criada só pela UI é exatamente a que as
+  // fontes locais não enxergam. S chamadas num comando raro é o preço certo.
+  const executa = Boolean(yes) && !dryRun;
+  let carga;
   try {
-    subs = await listSubIssues(token, featureIssue.node_id);
+    carga = await loadFeatureStories({
+      token, owner, repo, root: repoRoot,
+      feature: { number: featureNumber, nodeId: featureIssue.node_id, title: featureIssue.title },
+      remote: executa || remote,
+      refresh: executa || refresh,
+      ttlSec,
+    });
   } catch (err) {
     s.stop('');
     p.log.error(`Não foi possível listar as sub-issues: ${err.message}`);
     process.exitCode = 1;
     return;
   }
-  const stories = subs.filter(x => detectIssueType({ title: x.title, labels: x.labels }) === 'Story');
+  const stories = carga.stories;
   if (stories.length === 0) {
     s.stop('');
     p.log.info(`Feature #${featureNumber} não tem Stories — nada a mergear.`);
     p.outro('Nada a fazer.');
     return;
   }
+  for (const w of carga.warnings) p.log.warn(w);
+  if (!executa && !remote) {
+    p.log.info(chalk.dim(
+      `Ordem calculada de ${carga.origin.edges} — blocked_by criado só pela UI não entra no plano ` +
+      '(a execução com --yes reconsulta tudo fresco).'
+    ));
+  }
 
-  const enriched = await Promise.all(stories.map(async (st) => {
-    const fromBody = parseDependencies(st.body);
-    const fromBlockedBy = (await listBlockedBy(token, owner, repo, st.number).catch(() => []))
-      .map(b => b.number);
-    return { number: st.number, title: st.title, nodeId: st.nodeId, dependsOn: [...new Set([...fromBody, ...fromBlockedBy])] };
+  const enriched = stories.map(st => ({
+    number: st.number, title: st.title, nodeId: st.nodeId, dependsOn: st.dependsOn,
   }));
   const byNumber = new Map(enriched.map(x => [x.number, x]));
   const { order: sorted, cycle } = orderStories(
@@ -283,6 +307,11 @@ export async function merge({ feature: featureArg, yes = false, dryRun = false,
     }
   } finally {
     releaseLock(lock);
+    // Merges fecham issues e movem o board: todo cache de leitura desta sessão
+    // envelheceu de uma vez (o de board já cai dentro do advanceToStage).
+    if (mergedHeads.length > 0) {
+      invalidateCache(repoRoot, 'board-items', 'blockedby-*', 'subissues-*', 'issue-*');
+    }
   }
 
   p.outro(