godpowers 0.15.0

package/lib/reverse-sync.js

@@ -0,0 +1,332 @@
+/**
+ * Reverse Sync
+ *
+ * Scans the codebase, updates linkage, detects drift, and appends
+ * "Implementation:" / "Source:" / "Resolved in:" footers to artifacts
+ * inside a fenced section that does NOT touch human-written content.
+ *
+ * Per plan question 9: never overwrites human prose. Only appends inside
+ * <!-- godpowers:linkage:begin --> ... <!-- godpowers:linkage:end -->
+ * sections per artifact, same pattern as AGENTS.md fence.
+ *
+ * Public API:
+ *   run(projectRoot, opts) -> { scanResult, drift, footers, reviews }
+ *   appendFooters(projectRoot) -> [...]
+ *   buildPrdFooter(linkage) -> string
+ *   buildArchFooter(linkage) -> string
+ *   ...etc
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const linkage = require('./linkage');
+const scanner = require('./code-scanner');
+const drift = require('./drift-detector');
+const reviewRequired = require('./review-required');
+const impeccable = require('./impeccable-bridge');
+
+const FENCE_BEGIN = '<!-- godpowers:linkage:begin -->';
+const FENCE_END = '<!-- godpowers:linkage:end -->';
+
+/**
+ * Read a file, find existing fenced section. Return { exists, before, fenced, after }.
+ */
+function readFenced(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, before: '', fenced: '', after: '' };
+  }
+  const content = fs.readFileSync(filePath, 'utf8');
+  const beginIdx = content.indexOf(FENCE_BEGIN);
+  const endIdx = content.indexOf(FENCE_END);
+  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
+    return { exists: true, before: content, fenced: '', after: '' };
+  }
+  return {
+    exists: true,
+    before: content.slice(0, beginIdx),
+    fenced: content.slice(beginIdx + FENCE_BEGIN.length, endIdx),
+    after: content.slice(endIdx + FENCE_END.length)
+  };
+}
+
+/**
+ * Write fenced section into a file. Idempotent.
+ */
+function writeFenced(filePath, sectionContent) {
+  if (!fs.existsSync(filePath)) return { written: false, reason: 'file-missing' };
+  const parsed = readFenced(filePath);
+  const fencedBlock = `${FENCE_BEGIN}\n${sectionContent}\n${FENCE_END}`;
+  let next;
+  if (parsed.fenced === '') {
+    // No fence yet. Append at the end.
+    const sep = parsed.before.endsWith('\n\n') ? '' : (parsed.before.endsWith('\n') ? '\n' : '\n\n');
+    next = `${parsed.before}${sep}${fencedBlock}\n`;
+  } else {
+    next = `${parsed.before}${fencedBlock}${parsed.after}`;
+  }
+  fs.writeFileSync(filePath, next);
+  return { written: true, hadFenceBefore: parsed.fenced !== '' };
+}
+
+// ============================================================================
+// Per-artifact footer builders
+// ============================================================================
+
+/**
+ * Build PRD footer: "Implementation:" links per requirement.
+ */
+function buildPrdFooter(projectRoot) {
+  const fwd = linkage.readForward(projectRoot);
+  const lines = [];
+  lines.push('## Implementation Linkage');
+  lines.push('');
+  lines.push('> Auto-generated by /god-sync. Do not edit; edit your code annotations and re-sync.');
+  lines.push('');
+  // Group by P-MUST / P-SHOULD / P-COULD
+  const groups = { 'P-MUST': [], 'P-SHOULD': [], 'P-COULD': [] };
+  for (const [id, files] of Object.entries(fwd)) {
+    if (linkage.classifyId(id) !== 'prd') continue;
+    const tier = id.split('-').slice(0, 2).join('-'); // P-MUST, P-SHOULD, P-COULD
+    if (groups[tier]) groups[tier].push({ id, files });
+  }
+  for (const tier of ['P-MUST', 'P-SHOULD', 'P-COULD']) {
+    if (groups[tier].length === 0) continue;
+    lines.push(`### ${tier} requirements`);
+    lines.push('');
+    for (const { id, files } of groups[tier].sort((a, b) => a.id.localeCompare(b.id))) {
+      lines.push(`- **${id}** -> ${files.map(f => `\`${f}\``).join(', ')}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build ARCH footer: Source: per container; Pattern: per ADR.
+ */
+function buildArchFooter(projectRoot) {
+  const fwd = linkage.readForward(projectRoot);
+  const lines = [];
+  lines.push('## Implementation Linkage');
+  lines.push('');
+  lines.push('> Auto-generated by /god-sync. Do not edit.');
+  lines.push('');
+
+  const containers = [];
+  const adrs = [];
+  for (const [id, files] of Object.entries(fwd)) {
+    const kind = linkage.classifyId(id);
+    if (kind === 'container') containers.push({ id, files });
+    else if (kind === 'adr') adrs.push({ id, files });
+  }
+
+  if (containers.length > 0) {
+    lines.push('### Containers');
+    lines.push('');
+    for (const { id, files } of containers.sort((a, b) => a.id.localeCompare(b.id))) {
+      const dirs = [...new Set(files.map(f => path.dirname(f)))].sort();
+      lines.push(`- **${id}** (Source: ${dirs.map(d => `\`${d}\``).join(', ')})`);
+    }
+    lines.push('');
+  }
+  if (adrs.length > 0) {
+    lines.push('### ADRs');
+    lines.push('');
+    for (const { id, files } of adrs.sort((a, b) => a.id.localeCompare(b.id))) {
+      lines.push(`- **${id}** Pattern: ${files.map(f => `\`${f}\``).join(', ')}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build STACK footer: per dep, count of usage files.
+ */
+function buildStackFooter(projectRoot) {
+  const fwd = linkage.readForward(projectRoot);
+  const lines = [];
+  lines.push('## Usage Linkage');
+  lines.push('');
+  lines.push('> Auto-generated by /god-sync. Counts of code references.');
+  lines.push('');
+  const stackEntries = [];
+  for (const [id, files] of Object.entries(fwd)) {
+    if (linkage.classifyId(id) !== 'stack') continue;
+    stackEntries.push({ id, count: files.length });
+  }
+  if (stackEntries.length > 0) {
+    for (const { id, count } of stackEntries.sort((a, b) => a.id.localeCompare(b.id))) {
+      lines.push(`- **${id}**: used in ${count} file(s)`);
+    }
+  } else {
+    lines.push('(no stack-decision linkage recorded yet; add `// Implements: S-{slug}` annotations)');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Build DESIGN footer: per token, usage count; per component, implementing files.
+ */
+function buildDesignFooter(projectRoot) {
+  const fwd = linkage.readForward(projectRoot);
+  const lines = [];
+  lines.push('## Implementation Linkage');
+  lines.push('');
+  lines.push('> Auto-generated by /god-sync. Token usage and component implementations.');
+  lines.push('');
+  const tokens = [];
+  const components = [];
+  for (const [id, files] of Object.entries(fwd)) {
+    const kind = linkage.classifyId(id);
+    if (kind === 'token') tokens.push({ id, files });
+    else if (kind === 'design') components.push({ id, files });
+  }
+  if (tokens.length > 0) {
+    lines.push('### Token usage');
+    lines.push('');
+    for (const { id, files } of tokens.sort((a, b) => a.id.localeCompare(b.id))) {
+      lines.push(`- **${id}**: used in ${files.length} file(s)`);
+    }
+    lines.push('');
+  }
+  if (components.length > 0) {
+    lines.push('### Components');
+    lines.push('');
+    for (const { id, files } of components.sort((a, b) => a.id.localeCompare(b.id))) {
+      lines.push(`- **${id}** Implements: ${files.map(f => `\`${f}\``).join(', ')}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build ROADMAP footer: milestones with "Closed by:" if linked code commits known.
+ * V1: just lists linked files.
+ */
+function buildRoadmapFooter(projectRoot) {
+  const fwd = linkage.readForward(projectRoot);
+  const lines = [];
+  lines.push('## Implementation Linkage');
+  lines.push('');
+  lines.push('> Auto-generated by /god-sync. Files implementing each milestone.');
+  lines.push('');
+  for (const [id, files] of Object.entries(fwd)) {
+    if (linkage.classifyId(id) !== 'milestone') continue;
+    lines.push(`- **${id}** -> ${files.map(f => `\`${f}\``).join(', ')}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ============================================================================
+// Top-level orchestration
+// ============================================================================
+
+const ARTIFACT_TARGETS = [
+  { type: 'prd', path: '.godpowers/prd/PRD.md', build: buildPrdFooter },
+  { type: 'arch', path: '.godpowers/arch/ARCH.md', build: buildArchFooter },
+  { type: 'roadmap', path: '.godpowers/roadmap/ROADMAP.md', build: buildRoadmapFooter },
+  { type: 'stack', path: '.godpowers/stack/DECISION.md', build: buildStackFooter },
+  { type: 'design', path: 'DESIGN.md', build: buildDesignFooter }
+];
+
+/**
+ * Append fenced footers to all artifacts based on the current linkage map.
+ */
+function appendFooters(projectRoot) {
+  const results = [];
+  for (const t of ARTIFACT_TARGETS) {
+    const full = path.join(projectRoot, t.path);
+    if (!fs.existsSync(full)) continue;
+    const footer = t.build(projectRoot);
+    const r = writeFenced(full, footer);
+    results.push({ type: t.type, path: t.path, ...r });
+  }
+  return results;
+}
+
+/**
+ * Run a full reverse-sync cycle.
+ *
+ * 1. Scan code for linkage signals
+ * 2. Apply scan to linkage map
+ * 3. Run drift detection
+ * 4. Run impeccable detect on UI files (when installed)
+ * 5. Append fenced footers to artifacts
+ * 6. Surface drift findings to REVIEW-REQUIRED.md
+ *
+ * Returns aggregate summary.
+ */
+function run(projectRoot, opts = {}) {
+  const scanResult = scanner.scan(projectRoot, opts);
+  const applyResult = scanner.applyScan(projectRoot, scanResult);
+
+  const driftResult = drift.detectAll(projectRoot);
+
+  let impeccableFindings = [];
+  if (opts.runImpeccable !== false) {
+    const isInstalled = impeccable.isInstalled(projectRoot);
+    if (isInstalled && opts.uiFiles && opts.uiFiles.length > 0) {
+      for (const f of opts.uiFiles) {
+        const r = impeccable.runDetect(f, { cwd: projectRoot });
+        if (r.findings) impeccableFindings.push(...r.findings.map(x => ({ ...x, file: f })));
+      }
+    }
+  }
+
+  const footers = appendFooters(projectRoot);
+
+  // Surface drift + impeccable findings to REVIEW-REQUIRED.md
+  const reviewItems = [];
+  for (const f of driftResult.findings) {
+    reviewItems.push({
+      severity: f.severity,
+      id: f.artifactId,
+      file: f.file,
+      message: f.message
+    });
+  }
+  for (const f of impeccableFindings) {
+    reviewItems.push({
+      severity: f.severity || 'warning',
+      id: f.id || null,
+      file: f.file,
+      message: f.message || JSON.stringify(f)
+    });
+  }
+  if (reviewItems.length > 0) {
+    reviewRequired.appendBatch(projectRoot, {
+      source: 'reverse-sync',
+      summary: `${driftResult.summary.errors} drift errors, ${driftResult.summary.warnings} drift warnings, ${impeccableFindings.length} impeccable findings`,
+      items: reviewItems
+    });
+  }
+
+  return {
+    scanResult,
+    applyResult,
+    driftResult,
+    impeccableFindings,
+    footers,
+    reviewItems
+  };
+}
+
+module.exports = {
+  run,
+  appendFooters,
+  buildPrdFooter,
+  buildArchFooter,
+  buildRoadmapFooter,
+  buildStackFooter,
+  buildDesignFooter,
+  readFenced,
+  writeFenced,
+  FENCE_BEGIN,
+  FENCE_END,
+  ARTIFACT_TARGETS
+};

package/lib/review-required.js

@@ -0,0 +1,224 @@
+/**
+ * REVIEW-REQUIRED.md manager.
+ *
+ * Append-only registry of pending reviews. Cleared by /god-review-changes.
+ * Populated by:
+ *   - god-updater on /god-sync (after impact analysis from forward propagation)
+ *   - god-updater on reverse-sync (drift detection findings)
+ *   - god-design-reviewer with WARN verdicts (warnings flow here; BLOCKs go
+ *     to .godpowers/design/REJECTED.md instead)
+ *
+ * File format: append-only markdown with section per review batch.
+ *
+ * Public API:
+ *   path(projectRoot) -> string
+ *   appendBatch(projectRoot, batch) -> void
+ *   readEntries(projectRoot) -> [{ batchId, timestamp, source, items }]
+ *   clear(projectRoot) -> void
+ *   itemCount(projectRoot) -> number
+ *   formatBatch(batch) -> markdown
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function filePath(projectRoot) {
+  return path.join(projectRoot, 'REVIEW-REQUIRED.md');
+}
+
+function rejectedPath(projectRoot) {
+  return path.join(projectRoot, '.godpowers', 'design', 'REJECTED.md');
+}
+
+/**
+ * Append a review batch to REVIEW-REQUIRED.md.
+ *
+ * batch = {
+ *   source: 'design-impact' | 'prd-change' | 'arch-change' | 'reverse-sync-drift' | ...
+ *   summary: 'one-line description',
+ *   items: [{ id, file, severity: 'error'|'warning'|'info', message, suggestion? }]
+ * }
+ */
+function appendBatch(projectRoot, batch) {
+  const file = filePath(projectRoot);
+  const ts = new Date().toISOString();
+  const id = `${ts.replace(/[:.]/g, '-')}-${batch.source}`;
+
+  const header = fs.existsSync(file) ? '' : `# Review Required
+
+> Pending reviews surfaced by /god-sync, design changes, and drift detection.
+> Each batch documents what changed, why it needs review, and what to do.
+> Cleared by \`/god-review-changes\` when items are resolved.
+
+`;
+
+  const body = formatBatch({ ...batch, id, timestamp: ts });
+  fs.writeFileSync(file, header + (fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '') + body + '\n');
+  return { id, path: file, items: batch.items.length };
+}
+
+/**
+ * Format a batch as markdown.
+ */
+function formatBatch(batch) {
+  const lines = [];
+  lines.push(`## Batch: ${batch.id || 'unnamed'}`);
+  lines.push('');
+  lines.push(`- **Timestamp**: ${batch.timestamp || new Date().toISOString()}`);
+  lines.push(`- **Source**: ${batch.source}`);
+  lines.push(`- **Summary**: ${batch.summary}`);
+  lines.push('');
+  if (batch.items && batch.items.length > 0) {
+    lines.push('### Items');
+    lines.push('');
+    for (const item of batch.items) {
+      const sev = (item.severity || 'info').toUpperCase();
+      const id = item.id ? `[${item.id}]` : '';
+      const msg = `[${sev}] ${id} ${item.file ? '`' + item.file + '`' : ''}: ${item.message}`;
+      lines.push(`- ${msg.trim()}`);
+      if (item.suggestion) {
+        lines.push(`  - Suggestion: ${item.suggestion}`);
+      }
+    }
+  } else {
+    lines.push('### Items');
+    lines.push('');
+    lines.push('(none)');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Parse REVIEW-REQUIRED.md back into structured batches. Best-effort.
+ */
+function readEntries(projectRoot) {
+  const file = filePath(projectRoot);
+  if (!fs.existsSync(file)) return [];
+  const content = fs.readFileSync(file, 'utf8');
+  const batches = [];
+  const lines = content.split('\n');
+  let current = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith('## Batch:')) {
+      if (current) batches.push(current);
+      current = {
+        batchId: line.replace('## Batch:', '').trim(),
+        timestamp: '',
+        source: '',
+        summary: '',
+        items: []
+      };
+    } else if (current) {
+      const tsMatch = line.match(/\*\*Timestamp\*\*:\s*(.+)/);
+      if (tsMatch) current.timestamp = tsMatch[1].trim();
+      const srcMatch = line.match(/\*\*Source\*\*:\s*(.+)/);
+      if (srcMatch) current.source = srcMatch[1].trim();
+      const sumMatch = line.match(/\*\*Summary\*\*:\s*(.+)/);
+      if (sumMatch) current.summary = sumMatch[1].trim();
+      if (line.startsWith('- [')) {
+        const m = line.match(/^- \[(\w+)\]\s*(?:\[([^\]]+)\])?\s*(?:`([^`]+)`)?\s*:\s*(.+)$/);
+        if (m) {
+          current.items.push({
+            severity: m[1].toLowerCase(),
+            id: m[2] || null,
+            file: m[3] || null,
+            message: m[4].trim()
+          });
+        }
+      }
+    }
+  }
+  if (current) batches.push(current);
+  return batches;
+}
+
+/**
+ * Clear all review-required entries (after they've been addressed).
+ */
+function clear(projectRoot) {
+  const file = filePath(projectRoot);
+  if (!fs.existsSync(file)) return { cleared: false, reason: 'missing' };
+  fs.unlinkSync(file);
+  return { cleared: true };
+}
+
+/**
+ * Count of pending items (across all batches).
+ */
+function itemCount(projectRoot) {
+  return readEntries(projectRoot).reduce((sum, b) => sum + b.items.length, 0);
+}
+
+// ============================================================================
+// REJECTED.md (design-reviewer BLOCK verdicts)
+// ============================================================================
+
+/**
+ * Append a rejected design change.
+ *
+ * rejection = {
+ *   verdict: 'BLOCK',
+ *   stage1: 'misaligned' | 'needs-discussion',
+ *   stage2: 'errors' | 'warnings' | 'passes',
+ *   diffSummary: 'short summary',
+ *   findings: [{ severity, code, message }],
+ *   resolutionRequired: 'what to fix before resubmitting'
+ * }
+ */
+function appendRejection(projectRoot, rejection) {
+  const file = rejectedPath(projectRoot);
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const ts = new Date().toISOString();
+
+  const header = fs.existsSync(file) ? '' : `# Design Changes Rejected
+
+> Append-only audit trail of DESIGN.md / PRODUCT.md changes that
+> god-design-reviewer blocked. Each entry documents what was attempted,
+> why it was rejected, and what must change before resubmission.
+
+`;
+
+  const lines = [];
+  lines.push(`## Rejected: ${ts}`);
+  lines.push('');
+  lines.push(`### Verdict`);
+  lines.push(`${rejection.verdict || 'BLOCK'}`);
+  lines.push('');
+  lines.push(`### Stages`);
+  lines.push(`- Stage 1 (spec): ${rejection.stage1 || 'unknown'}`);
+  lines.push(`- Stage 2 (quality): ${rejection.stage2 || 'unknown'}`);
+  lines.push('');
+  lines.push(`### Diff scope`);
+  lines.push(rejection.diffSummary || '(no summary)');
+  lines.push('');
+  if (rejection.findings && rejection.findings.length > 0) {
+    lines.push(`### Findings`);
+    for (const f of rejection.findings) {
+      lines.push(`- [${(f.severity || 'error').toUpperCase()}] ${f.code || ''} ${f.message}`);
+    }
+    lines.push('');
+  }
+  if (rejection.resolutionRequired) {
+    lines.push(`### Resolution required`);
+    lines.push(rejection.resolutionRequired);
+    lines.push('');
+  }
+
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  fs.writeFileSync(file, header + existing + lines.join('\n') + '\n');
+  return { path: file, timestamp: ts };
+}
+
+module.exports = {
+  path: filePath,
+  rejectedPath,
+  appendBatch,
+  formatBatch,
+  readEntries,
+  clear,
+  itemCount,
+  appendRejection
+};