@sandrinio/vbounce 1.6.0 → 1.8.0

package/scripts/validate_state.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * validate_state.mjs
+ * Validates .bounce/state.json schema.
+ * Usage: ./scripts/validate_state.mjs
+ * Also exportable: import { validateState } from './validate_state.mjs'
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const STATE_FILE = path.join(ROOT, '.bounce', 'state.json');
+
+const VALID_STATES = [
+  'Draft', 'Refinement', 'Ready to Bounce', 'Bouncing',
+  'QA Passed', 'Architect Passed', 'Done', 'Escalated', 'Parking Lot'
+];
+
+/**
+ * Validates a state object. Returns { valid, errors }.
+ * @param {object} state
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateState(state) {
+  const errors = [];
+
+  if (!state || typeof state !== 'object') {
+    return { valid: false, errors: ['state.json must be a JSON object'] };
+  }
+
+  if (!state.sprint_id || !/^S-\d{2}$/.test(state.sprint_id)) {
+    errors.push(`sprint_id "${state.sprint_id}" must match S-XX format (e.g. S-05)`);
+  }
+
+  if (!state.delivery_id || !/^D-\d{2}$/.test(state.delivery_id)) {
+    errors.push(`delivery_id "${state.delivery_id}" must match D-NN format (e.g. D-02)`);
+  }
+
+  if (!state.stories || typeof state.stories !== 'object') {
+    errors.push('stories field must be an object');
+  } else {
+    for (const [id, story] of Object.entries(state.stories)) {
+      if (!VALID_STATES.includes(story.state)) {
+        errors.push(`Story ${id}: invalid state "${story.state}". Must be one of: ${VALID_STATES.join(', ')}`);
+      }
+      if (typeof story.qa_bounces !== 'number' || !Number.isInteger(story.qa_bounces) || story.qa_bounces < 0) {
+        errors.push(`Story ${id}: qa_bounces must be a non-negative integer, got "${story.qa_bounces}"`);
+      }
+      if (typeof story.arch_bounces !== 'number' || !Number.isInteger(story.arch_bounces) || story.arch_bounces < 0) {
+        errors.push(`Story ${id}: arch_bounces must be a non-negative integer, got "${story.arch_bounces}"`);
+      }
+      if (story.state === 'Done' && story.worktree) {
+        errors.push(`Story ${id}: state is "Done" but worktree "${story.worktree}" is still set (should be null)`);
+      }
+    }
+  }
+
+  if (state.updated_at) {
+    const d = new Date(state.updated_at);
+    if (isNaN(d.getTime())) {
+      errors.push(`updated_at "${state.updated_at}" is not a valid ISO 8601 timestamp`);
+    }
+  } else {
+    errors.push('updated_at field is required');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// CLI entry point
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  if (!fs.existsSync(STATE_FILE)) {
+    console.error(`ERROR: ${STATE_FILE} not found. Run: vbounce sprint init S-XX D-XX`);
+    process.exit(1);
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+  } catch (e) {
+    console.error(`ERROR: state.json is not valid JSON — ${e.message}`);
+    process.exit(1);
+  }
+
+  const { valid, errors } = validateState(state);
+
+  if (valid) {
+    console.log(`VALID: state.json — sprint ${state.sprint_id}, ${Object.keys(state.stories || {}).length} stories`);
+    process.exit(0);
+  } else {
+    console.error('INVALID: state.json has errors:');
+    errors.forEach(e => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+}

package/scripts/vdoc_match.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+/**
+ * vdoc_match.mjs
+ * Reads vdocs/_manifest.json and matches story scope against doc tags,
+ * descriptions, and key files. Returns relevant doc paths and blast radius.
+ *
+ * Usage:
+ *   ./scripts/vdoc_match.mjs --story STORY-005-02
+ *   ./scripts/vdoc_match.mjs --files "src/auth/index.ts,src/middleware/auth.ts"
+ *   ./scripts/vdoc_match.mjs --keywords "authentication,jwt,login"
+ *
+ * Output: JSON to stdout, human-readable to stderr
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+// ── Config ────────────────────────────────────────────────────────
+
+const configPath = path.join(ROOT, 'vbounce.config.json');
+const config = fs.existsSync(configPath)
+  ? JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  : {};
+
+const MAX_MATCHES = config.vdocMaxMatches || 3;
+const VDOCS_DIR = path.join(ROOT, 'vdocs');
+const MANIFEST_PATH = path.join(VDOCS_DIR, '_manifest.json');
+const SLICES_DIR = path.join(VDOCS_DIR, '_slices');
+
+// ── Parse args ────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+let storyId = null;
+let inputFiles = [];
+let inputKeywords = [];
+let outputFormat = 'human'; // human | json | context
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--story':   storyId = args[++i]; break;
+    case '--files':   inputFiles = args[++i].split(',').map(f => f.trim()); break;
+    case '--keywords': inputKeywords = args[++i].split(',').map(k => k.trim().toLowerCase()); break;
+    case '--json':    outputFormat = 'json'; break;
+    case '--context': outputFormat = 'context'; break;
+  }
+}
+
+if (!storyId && inputFiles.length === 0 && inputKeywords.length === 0) {
+  console.error('Usage: vdoc_match.mjs --story STORY-ID | --files "f1,f2" | --keywords "k1,k2"');
+  console.error('  --json     Output JSON to stdout');
+  console.error('  --context  Output context-pack markdown to stdout');
+  process.exit(1);
+}
+
+// ── Load manifest ─────────────────────────────────────────────────
+
+if (!fs.existsSync(MANIFEST_PATH)) {
+  if (outputFormat === 'json') {
+    console.log(JSON.stringify({ matches: [], blastRadius: [], reason: 'no_manifest' }));
+  } else {
+    console.error('No vdocs/_manifest.json found — skipping vdoc matching');
+  }
+  process.exit(0); // Graceful no-op
+}
+
+const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+const docs = manifest.documentation || [];
+
+// ── Extract search terms from story ───────────────────────────────
+
+if (storyId) {
+  // Find story spec to extract keywords and file references
+  const storyPattern = new RegExp(storyId.replace(/[-]/g, '[-]'));
+  const storyFiles = findFiles(path.join(ROOT, 'product_plans'), storyPattern);
+
+  if (storyFiles.length > 0) {
+    const storyContent = fs.readFileSync(storyFiles[0], 'utf8').toLowerCase();
+
+    // Extract file paths mentioned in the story
+    const fileRefs = storyContent.match(/(?:src|lib|app|pages|components|api|services|scripts)\/[^\s,)'"]+/g) || [];
+    inputFiles.push(...fileRefs);
+
+    // Extract tags from story frontmatter
+    const tagMatch = storyContent.match(/tags:\s*\[([^\]]+)\]/);
+    if (tagMatch) {
+      inputKeywords.push(...tagMatch[1].split(',').map(t => t.trim().replace(/['"]/g, '')));
+    }
+
+    // Use story name parts as keywords
+    const nameParts = storyId.split('-').slice(3).join('-').replace(/_/g, ' ').split(/\s+/);
+    inputKeywords.push(...nameParts.filter(p => p.length > 2));
+  }
+}
+
+// ── Score each doc ────────────────────────────────────────────────
+
+const scored = docs.map(doc => {
+  let score = 0;
+  const reasons = [];
+
+  // 1. File path overlap (strongest signal)
+  const docKeyFiles = extractKeyFiles(doc);
+  const fileOverlap = inputFiles.filter(f => docKeyFiles.some(kf => kf.includes(f) || f.includes(kf)));
+  if (fileOverlap.length > 0) {
+    score += fileOverlap.length * 10;
+    reasons.push(`file overlap: ${fileOverlap.join(', ')}`);
+  }
+
+  // 2. Tag match
+  const docTags = (doc.tags || []).map(t => t.toLowerCase());
+  const tagOverlap = inputKeywords.filter(k => docTags.includes(k));
+  if (tagOverlap.length > 0) {
+    score += tagOverlap.length * 5;
+    reasons.push(`tag match: ${tagOverlap.join(', ')}`);
+  }
+
+  // 3. Description keyword match
+  const desc = (doc.description || '').toLowerCase();
+  const descMatches = inputKeywords.filter(k => desc.includes(k));
+  if (descMatches.length > 0) {
+    score += descMatches.length * 3;
+    reasons.push(`description match: ${descMatches.join(', ')}`);
+  }
+
+  // 4. Title keyword match
+  const title = (doc.title || '').toLowerCase();
+  const titleMatches = inputKeywords.filter(k => title.includes(k));
+  if (titleMatches.length > 0) {
+    score += titleMatches.length * 2;
+    reasons.push(`title match: ${titleMatches.join(', ')}`);
+  }
+
+  return { ...doc, score, reasons };
+}).filter(d => d.score > 0).sort((a, b) => b.score - a.score);
+
+// ── Top matches ───────────────────────────────────────────────────
+
+const topMatches = scored.slice(0, MAX_MATCHES);
+
+// ── Blast radius (deps of matched docs) ──────────────────────────
+
+const matchedFeatures = new Set(topMatches.map(d => d.title));
+const blastRadius = [];
+
+for (const match of topMatches) {
+  const deps = match.deps || [];
+  for (const dep of deps) {
+    if (!matchedFeatures.has(dep)) {
+      const depDoc = docs.find(d => d.title === dep || d.filepath.toLowerCase().includes(dep.toLowerCase().replace(/\s+/g, '_')));
+      if (depDoc) {
+        blastRadius.push({ feature: dep, doc: depDoc.filepath, triggeredBy: match.title });
+      } else {
+        blastRadius.push({ feature: dep, doc: null, triggeredBy: match.title });
+      }
+    }
+  }
+}
+
+// ── Output ────────────────────────────────────────────────────────
+
+const result = {
+  matches: topMatches.map(d => ({
+    filepath: d.filepath,
+    title: d.title,
+    score: d.score,
+    reasons: d.reasons,
+    deps: d.deps || [],
+  })),
+  blastRadius,
+};
+
+if (outputFormat === 'json') {
+  console.log(JSON.stringify(result, null, 2));
+} else if (outputFormat === 'context') {
+  // Output context-pack markdown using slices where available
+  if (topMatches.length === 0) {
+    console.log('<!-- No vdoc matches found -->');
+  } else {
+    console.log('## vdoc Context');
+    console.log('');
+    for (const match of topMatches) {
+      const sliceName = match.filepath.replace(/_DOC\.md$/, '_SLICE.md').replace(/\.md$/, '_SLICE.md');
+      const slicePath = path.join(SLICES_DIR, sliceName);
+      const fullPath = path.join(VDOCS_DIR, match.filepath);
+
+      if (fs.existsSync(slicePath)) {
+        console.log(fs.readFileSync(slicePath, 'utf8'));
+      } else if (fs.existsSync(fullPath)) {
+        // Fallback: extract Overview section from full doc
+        const content = fs.readFileSync(fullPath, 'utf8');
+        const overviewMatch = content.match(/## Overview\s*\n(?:<!--[^>]*-->\s*\n)?\s*([\s\S]*?)(?=\n---|\n##)/);
+        if (overviewMatch) {
+          console.log(`### ${match.title}`);
+          console.log(overviewMatch[1].trim().split('\n').slice(0, 5).join('\n'));
+          console.log('');
+        }
+      }
+      console.log('');
+    }
+
+    if (blastRadius.length > 0) {
+      console.log('### Blast Radius Warning');
+      console.log('Changes to matched features may also affect:');
+      for (const br of blastRadius) {
+        console.log(`- **${br.feature}** (triggered by ${br.triggeredBy})${br.doc ? ` — see ${br.doc}` : ''}`);
+      }
+      console.log('');
+    }
+  }
+} else {
+  // Human-readable to stderr
+  if (topMatches.length === 0) {
+    console.error('No vdoc matches found for the given scope.');
+  } else {
+    console.error(`\n✓ ${topMatches.length} vdoc match(es) found:\n`);
+    for (const match of topMatches) {
+      console.error(`  ${match.filepath} (score: ${match.score})`);
+      console.error(`    ${match.reasons.join(' | ')}`);
+    }
+    if (blastRadius.length > 0) {
+      console.error(`\n⚠ Blast radius — also affected:`);
+      for (const br of blastRadius) {
+        console.error(`  ${br.feature} (via ${br.triggeredBy})`);
+      }
+    }
+    console.error('');
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+function findFiles(dir, pattern) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) results.push(...findFiles(full, pattern));
+    else if (pattern.test(e.name)) results.push(full);
+  }
+  return results;
+}
+
+function extractKeyFiles(doc) {
+  // From manifest entry — check if keyFiles exist in frontmatter-style
+  const files = [];
+  if (doc.keyFiles) files.push(...doc.keyFiles);
+
+  // Also try reading the doc to get Key Files table
+  const docPath = path.join(VDOCS_DIR, doc.filepath);
+  if (fs.existsSync(docPath)) {
+    const content = fs.readFileSync(docPath, 'utf8');
+    const keyFilesMatch = content.match(/## Key Files[\s\S]*?\|[^|]+\|[^|]+\|[^|]+\|([\s\S]*?)(?=\n---|\n##)/);
+    if (keyFilesMatch) {
+      const rows = keyFilesMatch[1].split('\n').filter(r => r.includes('|'));
+      for (const row of rows) {
+        const cells = row.split('|').map(c => c.trim());
+        const filePath = cells[1]?.replace(/`/g, '');
+        if (filePath && filePath.includes('/')) files.push(filePath);
+      }
+    }
+  }
+  return files;
+}

package/scripts/vdoc_staleness.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * vdoc_staleness.mjs
+ * Cross-references Dev Reports' files_modified against vdoc manifest key files.
+ * Generates a targeted Scribe task file listing stale docs.
+ *
+ * Usage:
+ *   ./scripts/vdoc_staleness.mjs S-05
+ *
+ * Output: .bounce/scribe-task-S-05.md
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+const sprintId = process.argv[2];
+if (!sprintId) {
+  console.error('Usage: vdoc_staleness.mjs S-XX');
+  process.exit(1);
+}
+
+const VDOCS_DIR = path.join(ROOT, 'vdocs');
+const MANIFEST_PATH = path.join(VDOCS_DIR, '_manifest.json');
+
+// ── Check manifest ────────────────────────────────────────────────
+
+if (!fs.existsSync(MANIFEST_PATH)) {
+  console.log('No vdocs/_manifest.json found — skipping staleness check');
+  process.exit(0);
+}
+
+const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+const docs = manifest.documentation || [];
+
+// ── Collect all files_modified from Dev Reports ───────────────────
+
+const allModifiedFiles = new Set();
+const storyModifications = {}; // storyId -> files
+
+function findDevReports(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) results.push(...findDevReports(full));
+    else if (e.name.endsWith('-dev.md')) results.push(full);
+  }
+  return results;
+}
+
+const reportDirs = [
+  path.join(ROOT, '.bounce', 'reports'),
+  path.join(ROOT, '.bounce', 'archive', sprintId),
+];
+
+for (const dir of reportDirs) {
+  const reports = findDevReports(dir);
+  for (const report of reports) {
+    try {
+      const content = fs.readFileSync(report, 'utf8');
+      const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+      if (!fmMatch) continue;
+      const fm = yaml.load(fmMatch[1]) || {};
+      const files = fm.files_modified || [];
+      const storyMatch = path.basename(report).match(/STORY-[\w-]+/);
+      const storyId = storyMatch ? storyMatch[0] : 'unknown';
+      storyModifications[storyId] = files;
+      files.forEach(f => allModifiedFiles.add(f));
+    } catch { /* skip malformed reports */ }
+  }
+}
+
+if (allModifiedFiles.size === 0) {
+  console.log('No files_modified found in Dev Reports — nothing to check');
+  process.exit(0);
+}
+
+// ── Cross-reference against manifest key files ────────────────────
+
+const staleDocs = [];
+
+for (const doc of docs) {
+  // Get key files from doc frontmatter or Key Files section
+  const docKeyFiles = [];
+
+  // From manifest entry
+  if (doc.keyFiles) docKeyFiles.push(...doc.keyFiles);
+
+  // From the doc file itself
+  const docPath = path.join(VDOCS_DIR, doc.filepath);
+  if (fs.existsSync(docPath)) {
+    const content = fs.readFileSync(docPath, 'utf8');
+
+    // Parse frontmatter keyFiles
+    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+      try {
+        const fm = yaml.load(fmMatch[1]) || {};
+        if (fm.keyFiles) docKeyFiles.push(...fm.keyFiles);
+      } catch { /* ignore */ }
+    }
+
+    // Parse Key Files table
+    const tableMatch = content.match(/## Key Files[\s\S]*?\|[^|]+\|[^|]+\|[^|]+\|([\s\S]*?)(?=\n---|\n##)/);
+    if (tableMatch) {
+      const rows = tableMatch[1].split('\n').filter(r => r.includes('|'));
+      for (const row of rows) {
+        const cells = row.split('|').map(c => c.trim());
+        const filePath = cells[1]?.replace(/`/g, '');
+        if (filePath && filePath.includes('/')) docKeyFiles.push(filePath);
+      }
+    }
+  }
+
+  // Check for overlap
+  const uniqueKeyFiles = [...new Set(docKeyFiles)];
+  const overlapping = uniqueKeyFiles.filter(kf =>
+    [...allModifiedFiles].some(mf => mf.includes(kf) || kf.includes(mf))
+  );
+
+  if (overlapping.length > 0) {
+    // Find which stories touched these files
+    const touchedBy = [];
+    for (const [sid, files] of Object.entries(storyModifications)) {
+      if (files.some(f => overlapping.some(o => f.includes(o) || o.includes(f)))) {
+        touchedBy.push(sid);
+      }
+    }
+
+    staleDocs.push({
+      filepath: doc.filepath,
+      title: doc.title,
+      overlappingFiles: overlapping,
+      touchedBy,
+    });
+  }
+}
+
+if (staleDocs.length === 0) {
+  console.log('✓ No stale vdocs detected — all docs are current');
+  process.exit(0);
+}
+
+// ── Generate Scribe task file ─────────────────────────────────────
+
+const taskLines = [
+  `---`,
+  `sprint_id: "${sprintId}"`,
+  `mode: "audit"`,
+  `stale_docs: ${staleDocs.length}`,
+  `generated: "${new Date().toISOString().split('T')[0]}"`,
+  `---`,
+  ``,
+  `# Scribe Task: ${sprintId} — Targeted Doc Update`,
+  ``,
+  `> Auto-generated by staleness detection. ${staleDocs.length} doc(s) need updating.`,
+  ``,
+  `## Stale Documents`,
+  ``,
+  `| Doc | Title | Files Modified | Touched By |`,
+  `|-----|-------|---------------|------------|`,
+  ...staleDocs.map(d =>
+    `| ${d.filepath} | ${d.title} | ${d.overlappingFiles.slice(0, 3).join(', ')}${d.overlappingFiles.length > 3 ? ` (+${d.overlappingFiles.length - 3})` : ''} | ${d.touchedBy.join(', ')} |`
+  ),
+  ``,
+  `## Instructions`,
+  ``,
+  `For each stale doc:`,
+  `1. Read the current doc and the Dev Reports from the stories listed above`,
+  `2. Re-read the modified source files to understand what changed`,
+  `3. Update only the affected sections — do not rewrite the entire doc`,
+  `4. Bump frontmatter \`version\` (increment by 1) and set \`lastUpdated\` to today`,
+  `5. Update the manifest entry if tags or description need adjustment`,
+  `6. Regenerate the context slice in \`vdocs/_slices/\``,
+  ``,
+  `## Priority`,
+  ``,
+  ...staleDocs.map(d => {
+    const fileCount = d.overlappingFiles.length;
+    const priority = fileCount >= 3 ? 'HIGH' : fileCount >= 2 ? 'MEDIUM' : 'LOW';
+    return `- **${d.filepath}**: ${priority} (${fileCount} key file(s) modified)`;
+  }),
+];
+
+const taskFile = path.join(ROOT, '.bounce', `scribe-task-${sprintId}.md`);
+fs.writeFileSync(taskFile, taskLines.join('\n'));
+
+console.log(`✓ Scribe task written to .bounce/scribe-task-${sprintId}.md`);
+console.log(`  ${staleDocs.length} stale doc(s) detected:`);
+for (const d of staleDocs) {
+  console.log(`  - ${d.filepath} (${d.overlappingFiles.length} key files modified by ${d.touchedBy.join(', ')})`);
+}