@jaimevalasek/aioson 1.22.0 → 1.23.0

package/src/lib/retro/retro-aggregate.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * Agregação determinística para `aioson harness:retro` (requirements §3.1/§7).
+ *
+ * Agrupa findings por CHAVE DETERMINÍSTICA EXATA — nunca por classe semântica
+ * (isso é trabalho do @sheldon). A chave inclui sempre o slug (um finding-ID
+ * como C-01 existe em quase toda feature; nunca agrupar entre features — edge 5).
+ *
+ * Critério anti-opinião (REQ-2): um grupo vira "Proposta candidata" SOMENTE se
+ *   (a) ≥2 ocorrências da mesma chave, OU
+ *   (b) ≥1 ocorrência de severidade high/critical, OU
+ *   (c) a feature tem ≥2 ciclos FAIL→PASS.
+ * Severidade `unknown` nunca satisfaz (b) sozinha; todo o resto vai para
+ * "Observações". (a) é independente de severidade — assinaturas sha1 (severidade
+ * unknown) promovem ao repetir, AC-6.
+ */
+
+const crypto = require('node:crypto');
+
+const SEVERITY_RANK = { critical: 5, high: 4, medium: 3, low: 2, info: 1, unknown: 0 };
+const PHASE_RE = /(?:[-_/]|\b)(ph\d+|phase[-_]?\d+)\b/i;
+
+function severityRank(sev) {
+  return SEVERITY_RANK[sev] ?? 0;
+}
+
+function sha1short(text) {
+  return crypto.createHash('sha1').update(String(text)).digest('hex').slice(0, 12);
+}
+
+/** Token de phase derivado do path da fonte (edge 4 — desambiguação entre phases). */
+function phaseToken(sourcePath) {
+  if (!sourcePath) return '';
+  const m = String(sourcePath).match(PHASE_RE);
+  return m ? m[1].toLowerCase().replace(/[-_]/g, '') : '';
+}
+
+/** Chave determinística exata de um finding (slug sempre incluído). */
+function groupKey(f) {
+  const phase = phaseToken(f.source_path);
+  const prefix = phase ? `${f.feature_slug}::${phase}` : f.feature_slug;
+  if (f.signature) return `${prefix}::sig:${f.signature}`;
+  if (f.finding_id) return `${prefix}::${f.finding_id}`;
+  return `${prefix}::title:${sha1short(f.title || '')}`;
+}
+
+/** Ordenação estável de ocorrências: severidade (critical→low), depois data, depois path. */
+function compareOccurrences(a, b) {
+  const sr = severityRank(b.severity) - severityRank(a.severity);
+  if (sr !== 0) return sr;
+  const da = a.date || '';
+  const db = b.date || '';
+  if (da !== db) return da < db ? -1 : 1;
+  return (a.source_path || '') < (b.source_path || '') ? -1 : (a.source_path || '') > (b.source_path || '') ? 1 : 0;
+}
+
+/**
+ * @param {object} sources — saída de `collectSources` ({ findings, cycles, cost, costByFeature })
+ * @returns {{ candidates, observations, cost }}
+ */
+function aggregate(sources) {
+  const findings = Array.isArray(sources.findings) ? sources.findings : [];
+  const cycles = Array.isArray(sources.cycles) ? sources.cycles : [];
+  const costByFeature = sources.costByFeature || {};
+
+  // Ciclos FAIL→PASS por feature (ordenados por data).
+  const cyclesByFeature = new Map();
+  for (const c of cycles) {
+    if (!cyclesByFeature.has(c.feature_slug)) cyclesByFeature.set(c.feature_slug, []);
+    cyclesByFeature.get(c.feature_slug).push(c);
+  }
+  for (const arr of cyclesByFeature.values()) {
+    arr.sort((a, b) => (a.fail_at < b.fail_at ? -1 : a.fail_at > b.fail_at ? 1 : 0));
+  }
+
+  // Agrupa findings por chave exata.
+  const groups = new Map();
+  for (const f of findings) {
+    const key = groupKey(f);
+    if (!groups.has(key)) groups.set(key, { key, feature_slug: f.feature_slug, finding_id: f.finding_id, signature: f.signature, occurrences: [] });
+    groups.get(key).occurrences.push(f);
+  }
+
+  const candidates = [];
+  const observations = [];
+
+  for (const g of groups.values()) {
+    g.occurrences.sort(compareOccurrences);
+    const maxSeverity = g.occurrences.reduce((acc, o) => (severityRank(o.severity) > severityRank(acc) ? o.severity : acc), 'unknown');
+    const occCount = g.occurrences.length;
+    const featureCycles = cyclesByFeature.get(g.feature_slug) || [];
+
+    const reasons = [];
+    if (occCount >= 2) reasons.push('recurrence');
+    if (severityRank(maxSeverity) >= severityRank('high')) reasons.push('severity');
+    if (featureCycles.length >= 2) reasons.push('fail_pass_cycle');
+
+    const feCost = costByFeature[g.feature_slug] || {};
+    const cost = {
+      occurrences: occCount,
+      corrections: g.occurrences.filter((o) => o.source_type === 'corrections').length,
+      fail_pass_cycles: featureCycles.length,
+      cycle_dates: featureCycles.map((c) => `${c.fail_at}→${c.pass_at}`),
+      execution_events: feCost.execution_events || 0,
+      corrections_bytes: feCost.corrections_bytes || 0,
+      tokens: feCost.token_count_available ? (feCost.token_total || 0) : null
+    };
+
+    if (reasons.length > 0) {
+      candidates.push({
+        key: g.key,
+        feature_slug: g.feature_slug,
+        finding_id: g.finding_id || null,
+        signature: g.signature || null,
+        max_severity: maxSeverity,
+        reasons,
+        occurrences: g.occurrences,
+        corrections_link: (g.occurrences.find((o) => o.source_type === 'corrections') || {}).source_path || null,
+        cost
+      });
+    } else {
+      // Ocorrência única Medium/Low/info/unknown → Observação (uma linha).
+      const o = g.occurrences[0];
+      observations.push({
+        key: g.key,
+        feature_slug: g.feature_slug,
+        finding_id: g.finding_id || null,
+        severity: o.severity,
+        title: o.title,
+        date: o.date,
+        source_path: o.source_path
+      });
+    }
+  }
+
+  // Candidato sintético por feature com ≥2 ciclos sem finding-âncora já candidato.
+  for (const [slug, arr] of cyclesByFeature.entries()) {
+    if (arr.length < 2) continue;
+    const alreadyCovered = candidates.some((c) => c.feature_slug === slug && c.reasons.includes('fail_pass_cycle'));
+    if (alreadyCovered) continue;
+    const feCost = costByFeature[slug] || {};
+    candidates.push({
+      key: `${slug}::cycles`,
+      feature_slug: slug,
+      finding_id: null,
+      signature: null,
+      max_severity: 'unknown',
+      reasons: ['fail_pass_cycle'],
+      occurrences: [],
+      corrections_link: null,
+      cost: {
+        occurrences: 0,
+        corrections: feCost.corrections || 0,
+        fail_pass_cycles: arr.length,
+        cycle_dates: arr.map((c) => `${c.fail_at}→${c.pass_at}`),
+        execution_events: feCost.execution_events || 0,
+        corrections_bytes: feCost.corrections_bytes || 0,
+        tokens: feCost.token_count_available ? (feCost.token_total || 0) : null
+      }
+    });
+  }
+
+  // Ordena candidatos: severidade (critical→low), depois data mais antiga, depois chave.
+  candidates.sort((a, b) => {
+    const sr = severityRank(b.max_severity) - severityRank(a.max_severity);
+    if (sr !== 0) return sr;
+    const da = (a.occurrences[0] && a.occurrences[0].date) || '';
+    const db = (b.occurrences[0] && b.occurrences[0].date) || '';
+    if (da !== db) return da < db ? -1 : 1;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+  });
+
+  // Ordena observações: severidade, depois data, depois chave.
+  observations.sort((a, b) => {
+    const sr = severityRank(b.severity) - severityRank(a.severity);
+    if (sr !== 0) return sr;
+    const da = a.date || '';
+    const db = b.date || '';
+    if (da !== db) return da < db ? -1 : 1;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+  });
+
+  return { candidates, observations, cost: sources.cost || {} };
+}
+
+module.exports = {
+  aggregate,
+  groupKey,
+  severityRank,
+  _internal: { phaseToken, compareOccurrences }
+};

package/src/lib/retro/retro-render.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * Renderiza o dossiê retrospectivo em Markdown (requirements §3.1).
+ *
+ * Saída byte-estável exceto `generated_at` (AC-4): nenhuma fonte de
+ * não-determinismo além do timestamp injetado pelo caller. As 4 seções existem
+ * SEMPRE — vazias com placeholder. O conteúdo do dossiê é um artefato em idioma
+ * fixo (pt-BR, conforme §3.1); `--locale` afeta só as mensagens de stdout.
+ */
+
+const SOURCE_ORDER = ['qa_reports', 'corrections', 'dossier_trail', 'execution_events', 'attempts', 'failure_signatures', 'devlogs'];
+
+// Defesa em profundidade (SF-01): o dossiê vira contexto do @sheldon. Texto livre
+// minerado (títulos) é apresentado como DADO inline, nunca como estrutura Markdown
+// injetável. Neutraliza newlines/controles/bidi/zero-width — impede que um título
+// forjado injete um header `## …`, um fence ``` ou um bloco de instrução no dossiê.
+// Determinístico e byte-estável: identidade sobre texto limpo (sem esses chars).
+const INJECTABLE_CHARS_RE = new RegExp(
+  '[\\u0000-\\u001F\\u007F\\u200B-\\u200F\\u2028\\u2029\\u202A-\\u202E\\u2066-\\u2069\\uFEFF]',
+  'g'
+);
+
+function neutralizeText(value) {
+  if (value === null || value === undefined) return '';
+  return String(value).replace(INJECTABLE_CHARS_RE, ' ').trim();
+}
+
+function severityLabel(sev) {
+  return sev || 'unknown';
+}
+
+function fmtCost(cost) {
+  const parts = [
+    `ocorrências ${cost.occurrences}`,
+    `correções ${cost.corrections}`,
+    `ciclos FAIL→PASS ${cost.fail_pass_cycles}${cost.cycle_dates && cost.cycle_dates.length ? ` (${cost.cycle_dates.join('; ')})` : ''}`,
+    `eventos ${cost.execution_events}`,
+    `bytes corrections ${cost.corrections_bytes}`,
+    `tokens ${cost.tokens === null || cost.tokens === undefined ? 'n/d' : cost.tokens}`
+  ];
+  return parts.join(', ');
+}
+
+function renderCandidate(c) {
+  const lines = [];
+  const anchor = c.finding_id || (c.signature ? `sig:${c.signature.slice(0, 12)}` : c.key);
+  lines.push(`### ${c.key}`);
+  lines.push('');
+  lines.push(`- Âncora: ${anchor} | severidade máxima: ${severityLabel(c.max_severity)} | motivos: ${c.reasons.join(', ')}`);
+  if (c.occurrences.length > 0) {
+    lines.push(`- Ocorrências (${c.occurrences.length}):`);
+    for (const o of c.occurrences) {
+      const id = o.finding_id || (o.signature ? `sig:${o.signature.slice(0, 12)}` : '—');
+      lines.push(`  - (${o.feature_slug}, ${id}, ${severityLabel(o.severity)}, ${o.date || 'sem-data'}, ${o.source_path}, ${o.status})`);
+    }
+  } else {
+    lines.push('- Ocorrências: ciclos FAIL→PASS recorrentes (sem finding-âncora único)');
+  }
+  lines.push(`- Correções aplicadas: ${c.corrections_link || '—'}`);
+  lines.push(`- Custo de retrabalho: ${fmtCost(c.cost)}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderObservation(o) {
+  const id = o.finding_id || '—';
+  return `- (${o.feature_slug}, ${id}, ${severityLabel(o.severity)}, ${o.date || 'sem-data'}) — ${neutralizeText(o.title) || id} [${o.source_path}]`;
+}
+
+function renderFrontmatter({ mode, slug, windowN, featuresMined, counts, candidatesCount, observationsCount, generatedAt }) {
+  const lines = ['---'];
+  if (mode === 'window') {
+    lines.push(`window: last-${windowN}`);
+  } else {
+    lines.push(`feature: ${slug}`);
+  }
+  lines.push(`generated_at: ${generatedAt}`);
+  lines.push('generated_by: harness-retro');
+  lines.push('schema_version: "1.0"');
+  lines.push(`features_mined: [${featuresMined.join(', ')}]`);
+  lines.push('sources:');
+  for (const key of SOURCE_ORDER) {
+    lines.push(`  ${key}: ${counts[key] || 0}`);
+  }
+  lines.push(`candidates: ${candidatesCount}`);
+  lines.push(`observations: ${observationsCount}`);
+  lines.push('---');
+  return lines.join('\n');
+}
+
+/**
+ * @param {object} opts
+ * @param {'feature'|'window'} opts.mode
+ * @param {string} [opts.slug]
+ * @param {number} [opts.windowN]
+ * @param {string[]} opts.featuresMined
+ * @param {object} opts.counts — contagens por fonte
+ * @param {Array} opts.candidates
+ * @param {Array} opts.observations
+ * @param {string[]} opts.minedPaths
+ * @param {string[]} opts.warnings
+ * @param {string} opts.dossierRelPath — path relativo deste dossiê (para o Próximo passo)
+ * @param {string} opts.generatedAt — ISO 8601 (única fonte de não-determinismo)
+ * @returns {string}
+ */
+function renderDossier(opts) {
+  const {
+    mode, slug, windowN, featuresMined, counts,
+    candidates, observations, minedPaths, warnings, dossierRelPath, generatedAt
+  } = opts;
+
+  const blocks = [];
+
+  blocks.push(renderFrontmatter({
+    mode, slug, windowN, featuresMined, counts,
+    candidatesCount: candidates.length, observationsCount: observations.length, generatedAt
+  }));
+
+  const title = mode === 'window' ? `Dossiê retrospectivo — janela last-${windowN}` : `Dossiê retrospectivo — ${slug}`;
+  blocks.push(`\n# ${title}\n`);
+
+  // 1. Propostas candidatas
+  const sec1 = ['## Propostas candidatas', ''];
+  if (candidates.length === 0) {
+    sec1.push('_(nenhuma proposta candidata — nenhum item atende ao critério REQ-2)_');
+  } else {
+    for (const c of candidates) sec1.push(renderCandidate(c));
+  }
+  blocks.push(sec1.join('\n'));
+
+  // 2. Observações
+  const sec2 = ['', '## Observações', ''];
+  if (observations.length === 0) {
+    sec2.push('_(nenhuma observação)_');
+  } else {
+    for (const o of observations) sec2.push(renderObservation(o));
+  }
+  blocks.push(sec2.join('\n'));
+
+  // 3. Trilha minerada
+  const sec3 = ['', '## Trilha minerada', '', '### Paths minerados'];
+  if (minedPaths.length === 0) {
+    sec3.push('- _(nenhum path encontrado)_');
+  } else {
+    for (const p of minedPaths) sec3.push(`- ${p}`);
+  }
+  sec3.push('', '### Contagens por fonte');
+  for (const key of SOURCE_ORDER) {
+    sec3.push(`- ${key}: ${counts[key] || 0}`);
+  }
+  sec3.push('', '### Avisos');
+  if (warnings.length === 0) {
+    sec3.push('- _(nenhum aviso — todas as fontes lidas sem degradação)_');
+  } else {
+    for (const w of warnings) sec3.push(`- ${w}`);
+  }
+  blocks.push(sec3.join('\n'));
+
+  // 4. Próximo passo (texto fixo — REQ-5)
+  const sec4 = [
+    '',
+    '## Próximo passo',
+    '',
+    `Ative o @sheldon sob demanda para analisar este dossiê (\`${dossierRelPath}\`):`,
+    '',
+    '```',
+    `aioson agent:prompt sheldon . --task="analisar ${dossierRelPath}"`,
+    '```',
+    '',
+    'Critério de promoção (REQ-2): só vira proposta o item com ≥2 ocorrências da mesma chave determinística, ≥1 finding High/Critical, ou ≥2 ciclos FAIL→PASS na mesma feature.',
+    '',
+    '@sheldon classifica as classes de falha citando as ocorrências deste dossiê e propõe deltas que aterrissam APENAS em `.aioson/learnings/` e `.aioson/rules/`, sempre com aprovação humana. A CLI minera e materializa; ela nunca auto-aplica deltas.',
+    ''
+  ];
+  blocks.push(sec4.join('\n'));
+
+  // Normaliza para LF e garante newline final único (byte-estável).
+  return `${blocks.join('\n').replace(/\r\n/g, '\n').replace(/\n+$/, '')}\n`;
+}
+
+module.exports = {
+  renderDossier,
+  _internal: { renderFrontmatter, renderCandidate, fmtCost, neutralizeText, SOURCE_ORDER }
+};