create-quiver 0.6.0 → 0.7.0

package/src/create-quiver/lib/readiness.js

@@ -0,0 +1,300 @@
+const fs = require('fs');
+const path = require('path');
+const { catFileExists, currentBranch, hasLocalBranch, hasRemoteBranch, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeList } = require('./git');
+const { resolveSliceContext, toAlias } = require('./slice');
+
+function ensureExists(filePath, message) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(message);
+  }
+}
+
+function walkSlices(rootDir, acc, repoRoot) {
+  if (!fs.existsSync(rootDir)) {
+    return;
+  }
+
+  for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+    const fullPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      walkSlices(fullPath, acc, repoRoot);
+      continue;
+    }
+
+    if (entry.isFile() && entry.name === 'slice.json' && fullPath.includes(`${path.sep}slices${path.sep}`)) {
+      const json = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+      const branchName = json.git?.branch_name;
+      if (!branchName) {
+        continue;
+      }
+      acc.set(branchName, {
+        sliceId: json.slice_id || '',
+        files: Array.isArray(json.files) ? json.files : [],
+      });
+    }
+  }
+}
+
+function parseWorktrees(text) {
+  const entries = [];
+  const chunks = text.trim().split('\n\n').filter(Boolean);
+
+  for (const chunk of chunks) {
+    const entry = {};
+    for (const line of chunk.split('\n')) {
+      const idx = line.indexOf(' ');
+      if (idx === -1) {
+        continue;
+      }
+      entry[line.slice(0, idx)] = line.slice(idx + 1);
+    }
+    entries.push(entry);
+  }
+
+  return entries;
+}
+
+function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles) {
+  const sliceMap = new Map();
+  walkSlices(path.join(repoRoot, 'specs'), sliceMap, repoRoot);
+  walkSlices(path.join(repoRoot, 'specs-fix'), sliceMap, repoRoot);
+
+  const worktrees = parseWorktrees(runGit(['worktree', 'list', '--porcelain'], repoRoot));
+  const warnings = [];
+
+  for (const entry of worktrees) {
+    const worktreePath = entry.worktree;
+    const branchRef = entry.branch || '';
+    const branchName = branchRef.replace('refs/heads/', '');
+
+    if (!branchName || branchName === currentBranchName || worktreePath === repoRoot) {
+      continue;
+    }
+
+    const meta = sliceMap.get(branchName);
+    if (!meta || meta.sliceId.startsWith('slice-00')) {
+      continue;
+    }
+
+    const dirty = statusPorcelain(worktreePath) !== '';
+    const aheadCount = revListCount(worktreePath, 'origin/develop..HEAD');
+    const active = dirty || aheadCount > 0;
+
+    if (!active) {
+      continue;
+    }
+
+    const overlap = currentFiles.filter((item) => meta.files.includes(item));
+    if (overlap.length > 0) {
+      warnings.push(`${branchName}|${overlap.join(', ')}`);
+    }
+  }
+
+  return warnings;
+}
+
+function checkSliceReadiness(sliceInput, options = {}) {
+  const gate = options.gate || 'execution';
+  const strictOverlap = options.strictOverlap === true;
+  const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
+  const slice = resolveSliceContext(repoRoot, sliceInput);
+
+  for (const specFile of ['SPEC.md', 'STATUS.md', 'EVIDENCE_REPORT.md']) {
+    ensureExists(path.join(repoRoot, slice.specDirRel, specFile), `create-quiver: falta '${slice.specDirRel}/${specFile}'.`);
+  }
+  console.log('PASS: El spec local tiene SPEC.md, STATUS.md y EVIDENCE_REPORT.md.');
+
+  if (catFileExists(repoRoot, `origin/develop:${slice.sliceRel}`)) {
+    console.log('PASS: El slice ya existe en origin/develop (PR base documental mergeado).');
+  } else if (gate === 'validation') {
+    console.log('WARN: El slice no existe todavia en origin/develop. El PR base documental sigue pendiente de merge. Podes abrir el PR del slice igual — el humano mergea en orden.');
+  } else {
+    throw new Error('create-quiver: el slice no existe en origin/develop. Mergea primero el PR base documental.');
+  }
+
+  const overlapWarnings = collectOverlapWarnings(repoRoot, currentBranch(repoRoot), slice.files);
+  if (overlapWarnings.length === 0) {
+    console.log('PASS: No se detecto overlap con worktrees activos.');
+  } else {
+    for (const warning of overlapWarnings) {
+      const [overlapBranch, overlapFiles] = warning.split('|');
+      if (strictOverlap) {
+        throw new Error(`create-quiver: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
+      }
+      console.log(`WARN: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
+    }
+  }
+
+  switch (gate) {
+    case 'ready':
+      if (slice.status !== 'ready') {
+        throw new Error(`create-quiver: Gate ready: slice.json debe estar en status=ready. Estado actual: ${slice.status}. Completa la especificacion en el Track 1 antes de pasar a ejecucion.`);
+      }
+      console.log('PASS: Gate ready: el slice esta marcado como ready para ejecucion.');
+      break;
+    case 'execution':
+      if (slice.status === 'blocked') {
+        throw new Error('create-quiver: El slice esta bloqueado (status=blocked). Resolve el bloqueante antes de ejecutar.');
+      }
+      if (slice.status === 'cancelled') {
+        throw new Error('create-quiver: El slice esta cancelado (status=cancelled).');
+      }
+      if (slice.status === 'completed') {
+        console.log('WARN: El slice ya figura como completed. Revisa si realmente corresponde reejecutarlo.');
+      }
+      if (slice.status === 'draft') {
+        console.log("WARN: El slice esta en estado 'draft'. Considera marcarlo como 'ready' antes de ejecutar.");
+      }
+      console.log('PASS: Gate execution: metadata y precondiciones minimas OK.');
+      break;
+    case 'validation':
+      if (slice.status !== 'completed') {
+        throw new Error('create-quiver: Para gate validation, slice.json debe estar en status=completed.');
+      }
+      if (!slice.json.completed_at) {
+        throw new Error('create-quiver: Para gate validation, slice.json debe tener completed_at.');
+      }
+      if (!slice.json.started_at) {
+        throw new Error('create-quiver: Para gate validation, slice.json debe tener started_at.');
+      }
+      if (!slice.json.actual_hours || Number(slice.json.actual_hours) <= 0) {
+        throw new Error('create-quiver: Para gate validation, slice.json debe tener actual_hours > 0.');
+      }
+      console.log('PASS: Gate validation: slice marcado como completado y con trazabilidad minima.');
+      break;
+  }
+}
+
+function checkPrReadiness(sliceInput) {
+  const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
+  const scriptDir = path.dirname(__filename);
+  const slice = resolveSliceContext(repoRoot, sliceInput);
+  const current = currentBranch(repoRoot);
+  const prPath = path.join(path.dirname(slice.sliceAbs), 'pr.md');
+
+  checkSliceReadiness(slice.sliceAbs, { gate: 'validation' });
+  checkScope(slice.sliceAbs, { strict: true });
+
+  if (!slice.branchName) {
+    throw new Error('create-quiver: Falta git.branch_name en el slice.');
+  }
+  if (!fs.existsSync(prPath)) {
+    throw new Error('create-quiver: Falta pr.md junto al slice.');
+  }
+  if (current !== slice.branchName) {
+    throw new Error(`create-quiver: Debes ejecutar este check desde la rama del slice. Actual: ${current} Esperada: ${slice.branchName}`);
+  }
+  console.log('PASS: La rama actual coincide con la rama declarada por el slice.');
+  if (statusPorcelain(repoRoot) !== '') {
+    throw new Error('create-quiver: El worktree no esta limpio. Cerra la implementacion antes de abrir el PR.');
+  }
+  console.log('PASS: El worktree esta limpio.');
+
+  const aheadCount = revListCount(repoRoot, 'origin/develop..HEAD');
+  if (aheadCount <= 0) {
+    if (mergeBaseIsAncestor(repoRoot, 'HEAD', 'origin/develop')) {
+      throw new Error('create-quiver: La rama ya fue absorbida por origin/develop. Este gate aplica antes del merge.');
+    }
+    throw new Error('create-quiver: La rama no tiene commits propios respecto de origin/develop.');
+  }
+  console.log('PASS: La rama tiene commits propios contra origin/develop.');
+
+  const prText = fs.readFileSync(prPath, 'utf8');
+  for (const heading of ['## Title', '## Summary', '## Scope', '## Files', '## How to Test (DETAILED - REQUIRED)', '## Evidence', '## Rollback', '## Risks / Notes']) {
+    if (!prText.includes(heading)) {
+      throw new Error(`create-quiver: Falta la seccion obligatoria '${heading}' en pr.md.`);
+    }
+  }
+  console.log('PASS: pr.md contiene las secciones obligatorias.');
+
+  for (const subheading of ['### Required Environment', '### Worktree Access', '### Run the Project', '### Use Cases', '### Technical Verification']) {
+    if (!prText.includes(subheading)) {
+      throw new Error(`create-quiver: Falta la subseccion '${subheading}' dentro de How to Test.`);
+    }
+  }
+  console.log('PASS: How to Test incluye entorno, acceso al worktree, arranque, casos de uso y verificación técnica.');
+
+  if (!/#### Case [0-9]+:/.test(prText)) {
+    throw new Error('create-quiver: How to Test debe tener al menos un caso de uso documentado (#### Case 1: ...).');
+  }
+  console.log('PASS: Al menos un caso de uso documentado.');
+
+  if (!/git revert /.test(prText)) {
+    throw new Error('create-quiver: Rollback debe incluir al menos un comando git revert.');
+  }
+  console.log('PASS: Rollback incluye comando git revert.');
+
+  if (/^\s*-\s*`manual review`$/mi.test(prText) || /^\s*-\s*`visual check`$/mi.test(prText) || /^\s*-\s*`screen test`$/mi.test(prText) || /^\s*-\s*`visual validation`$/mi.test(prText)) {
+    throw new Error('create-quiver: How to Test cannot rely only on generic phrases.');
+  }
+
+  console.log(`PASS: Gate PR listo para '${slice.sliceId}'.`);
+}
+
+function checkScope(sliceInput, options = {}) {
+  const strict = options.strict === true;
+  const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
+  const slice = resolveSliceContext(repoRoot, sliceInput);
+  const declared = slice.files;
+
+  let touchedRaw = '';
+  if (hasRemoteBranch(repoRoot, 'develop')) {
+    touchedRaw = runGit(['diff', '--name-only', 'origin/develop...HEAD'], repoRoot);
+  } else if (hasLocalBranch(repoRoot, 'develop')) {
+    touchedRaw = runGit(['diff', '--name-only', 'develop...HEAD'], repoRoot);
+  } else {
+    console.log('WARN: No se encontro rama origin/develop ni develop. Saltando check de scope.');
+    return;
+  }
+
+  if (!touchedRaw) {
+    console.log('WARN: No se encontraron archivos modificados respecto de develop.');
+    return;
+  }
+
+  const touched = touchedRaw.trim().split('\n').filter(Boolean);
+  const autoAllowed = [
+    /^specs\//,
+    /^docs\//,
+    /^\.worktrees\//,
+    /WORKTREE_CONTEXT\.md$/,
+    /EVIDENCE_REPORT\.md$/,
+    /STATUS\.md$/,
+    /SPEC\.md$/,
+    /\/pr\.md$/,
+    /\/slice\.json$/,
+  ];
+
+  const outOfScope = touched.filter((file) => {
+    if (declared.includes(file)) return false;
+    if (autoAllowed.some((re) => re.test(file))) return false;
+    return true;
+  });
+
+  if (outOfScope.length === 0) {
+    console.log('PASS: Todos los archivos tocados estan dentro del scope declarado en slice.json.');
+    return;
+  }
+
+  let violationCount = 0;
+  for (const file of outOfScope) {
+    violationCount += 1;
+    if (strict) {
+      throw new Error(`create-quiver: Archivo fuera del scope: ${file}`);
+    }
+    console.log(`WARN: Archivo fuera del scope: ${file}`);
+  }
+
+  if (violationCount > 0) {
+    if (strict) {
+      throw new Error(`${violationCount} archivo(s) fuera del scope declarado. Actualiza slice.json.files o revierte los cambios fuera de alcance.`);
+    }
+    console.log(`WARN: ${violationCount} archivo(s) fuera del scope declarado. Considera actualizar slice.json.files o revertir los cambios no previstos.`);
+  }
+}
+
+module.exports = {
+  checkPrReadiness,
+  checkScope,
+  checkSliceReadiness,
+};

package/src/create-quiver/lib/scope.js

@@ -0,0 +1,5 @@
+const { checkScope } = require('./readiness');
+
+module.exports = {
+  checkScope,
+};

package/src/create-quiver/lib/slice.js

@@ -0,0 +1,194 @@
+const fs = require('fs');
+const path = require('path');
+const { resolveTargetRoot, toPosixPath } = require('./paths');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function canonicalizePath(dirPath) {
+  try {
+    return fs.realpathSync(dirPath);
+  } catch {
+    return path.resolve(dirPath);
+  }
+}
+
+function toAlias(ticket) {
+  const parts = String(ticket || '').split('-').filter(Boolean);
+  const prefix = (parts[0] || 'GEN').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
+  const suffix = (parts[parts.length - 1] || '00').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
+  const short = prefix.length <= 3 ? prefix : prefix.slice(0, 3);
+  return `${short || 'GEN'}-${suffix || '00'}`;
+}
+
+function resolveSlicePath(sliceInput) {
+  if (!fs.existsSync(sliceInput)) {
+    throw new Error(`create-quiver: no existe el slice '${sliceInput}'.`);
+  }
+
+  return canonicalizePath(sliceInput);
+}
+
+function readSliceMeta(slicePath) {
+  const json = readJson(slicePath);
+  const ticket = typeof json.ticket === 'string' ? json.ticket.trim() : '';
+  const git = json.git ?? {};
+  const branchType = typeof git.branch_type === 'string' ? git.branch_type.trim() : '';
+  const baseBranch = typeof git.base_branch === 'string' ? git.base_branch.trim() : '';
+  const branchSlug = typeof git.branch_slug === 'string' ? git.branch_slug.trim() : '';
+  const branchName = typeof git.branch_name === 'string' ? git.branch_name.trim() : '';
+  const sliceId = typeof json.slice_id === 'string' ? json.slice_id.trim() : '';
+  const status = String(json.status || 'draft').trim() || 'draft';
+
+  return {
+    acceptance: Array.isArray(json.acceptance) ? json.acceptance : [],
+    baseBranch,
+    branchName,
+    branchSlug,
+    branchType,
+    files: Array.isArray(json.files) ? json.files : [],
+    git,
+    isBaseline: sliceId.startsWith('slice-00'),
+    json,
+    sliceId,
+    slicePath,
+    specFamily: null,
+    specSlug: null,
+    status,
+    tests: Array.isArray(json.tests) ? json.tests : [],
+    ticket,
+  };
+}
+
+function validateSliceMetaForStart(slice) {
+  if (!slice.sliceId) {
+    throw new Error('create-quiver: falta "slice_id" en el slice.');
+  }
+  if (!slice.ticket) {
+    throw new Error('create-quiver: falta "ticket" en el slice.');
+  }
+  if (!slice.branchType || !slice.baseBranch || !slice.branchSlug || !slice.branchName) {
+    throw new Error('create-quiver: el bloque "git" debe incluir "branch_type", "base_branch", "branch_slug" y "branch_name".');
+  }
+
+  const expectedBaseByType = {
+    feature: 'develop',
+    bugfix: 'develop',
+    hotfix: 'main',
+  };
+
+  if (!expectedBaseByType[slice.branchType]) {
+    throw new Error(`create-quiver: git.branch_type invalido: "${slice.branchType}". Usa "feature", "bugfix" o "hotfix".`);
+  }
+
+  const expectedBaseBranch = expectedBaseByType[slice.branchType];
+  if (slice.baseBranch !== expectedBaseBranch) {
+    throw new Error(`create-quiver: git.base_branch invalido para ${slice.branchType}. Esperado: "${expectedBaseBranch}".`);
+  }
+
+  const expectedBranchName = `${slice.branchType}/${slice.ticket}-${slice.branchSlug}`;
+  if (slice.branchName !== expectedBranchName) {
+    throw new Error(`create-quiver: git.branch_name invalido. Esperado: "${expectedBranchName}".`);
+  }
+}
+
+function resolveSliceContext(repoRoot, slicePath) {
+  const absSlicePath = resolveSlicePath(slicePath);
+  const relSlicePath = toPosixPath(path.relative(repoRoot, absSlicePath));
+  const parts = relSlicePath.split('/');
+
+  if (parts[0] !== 'specs' && parts[0] !== 'specs-fix') {
+    throw new Error('create-quiver: el slice debe vivir dentro de specs/ o specs-fix/.');
+  }
+
+  const specFamily = parts[0];
+  const specSlug = parts[1];
+  const specDirRel = `${specFamily}/${specSlug}`;
+  const specDirAbs = path.join(repoRoot, specDirRel);
+  const slice = readSliceMeta(absSlicePath);
+  slice.specFamily = specFamily;
+  slice.specSlug = specSlug;
+  slice.specDirRel = specDirRel;
+  slice.specDirAbs = specDirAbs;
+  slice.sliceRel = relSlicePath;
+  slice.sliceAbs = absSlicePath;
+  slice.prPath = path.join(path.dirname(absSlicePath), 'pr.md');
+  return slice;
+}
+
+function activeSlicePath(repoRoot) {
+  return path.join(repoRoot, 'docs', 'ai', 'ACTIVE_SLICE.md');
+}
+
+function renderActiveSlice(slice) {
+  const lines = [
+    '# Active Slice',
+    '',
+    '## Slice ID',
+    '',
+    slice.sliceId || 'slice-unknown',
+    '',
+    '## Title',
+    '',
+    slice.json.title || slice.sliceId || 'Untitled slice',
+    '',
+    '## Objective',
+    '',
+    slice.json.objective || 'Sin objetivo declarado.',
+    '',
+    '## allowed_files',
+  ];
+
+  if (Array.isArray(slice.files) && slice.files.length > 0) {
+    for (const file of slice.files) {
+      lines.push(`- ${file}`);
+    }
+  } else {
+    lines.push('- n/a');
+  }
+
+  lines.push('', '## Validation Commands');
+  if (Array.isArray(slice.tests) && slice.tests.length > 0) {
+    for (const command of slice.tests) {
+      lines.push(`- ${command}`);
+    }
+  } else {
+    lines.push('- n/a');
+  }
+
+  lines.push('', '## Definition of Done');
+  if (Array.isArray(slice.acceptance) && slice.acceptance.length > 0) {
+    for (const item of slice.acceptance) {
+      lines.push(`- ${item}`);
+    }
+  } else {
+    lines.push('- n/a');
+  }
+
+  lines.push('', '## Prohibition', '', 'Do not edit any file outside allowed_files.', '');
+
+  return `${lines.join('\n')}\n`;
+}
+
+function worktreesRootForRepo(repoRoot, branchName) {
+  const repoName = path.basename(repoRoot);
+  const repoParent = path.dirname(repoRoot);
+  return process.env.SLICE_WORKTREES_DIR || path.join(repoParent, '.worktrees', repoName);
+}
+
+function safeBranchName(branchName) {
+  return String(branchName || '').replace(/[^A-Za-z0-9._-]/g, '-');
+}
+
+module.exports = {
+  canonicalizePath,
+  readSliceMeta,
+  resolveSliceContext,
+  safeBranchName,
+  activeSlicePath,
+  renderActiveSlice,
+  toAlias,
+  validateSliceMetaForStart,
+  worktreesRootForRepo,
+};

package/src/create-quiver/lib/state.js

@@ -0,0 +1,89 @@
+const fs = require('fs');
+const path = require('path');
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, '.quiver', 'state.json');
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readState(projectRoot) {
+  const filePath = statePath(projectRoot);
+
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeState(projectRoot, nextState) {
+  const stateDir = path.join(projectRoot, '.quiver');
+  ensureDir(stateDir);
+  fs.writeFileSync(statePath(projectRoot), `${JSON.stringify(nextState, null, 2)}\n`);
+  return statePath(projectRoot);
+}
+
+function updateStateForInit(projectRoot, projectName, cliVersion) {
+  const currentState = readState(projectRoot) || {};
+  const now = new Date().toISOString();
+  const nextState = {
+    ...currentState,
+    quiver_version: cliVersion,
+    project_name: projectName || currentState.project_name || '',
+    initialized_version: currentState.initialized_version || cliVersion,
+    migrated_version: currentState.migrated_version ?? null,
+    last_initialized_at: currentState.last_initialized_at || now,
+    last_migration_at: currentState.last_migration_at ?? null,
+    last_analysis_at: currentState.last_analysis_at ?? null,
+  };
+
+  writeState(projectRoot, nextState);
+  return nextState;
+}
+
+function updateStateForMigrate(projectRoot, projectName, cliVersion) {
+  const currentState = readState(projectRoot) || {};
+  const now = new Date().toISOString();
+  const nextState = {
+    ...currentState,
+    quiver_version: cliVersion,
+    project_name: projectName || currentState.project_name || '',
+    initialized_version: currentState.initialized_version ?? null,
+    migrated_version: cliVersion,
+    last_initialized_at: currentState.last_initialized_at ?? null,
+    last_migration_at: now,
+    last_analysis_at: currentState.last_analysis_at ?? null,
+  };
+
+  writeState(projectRoot, nextState);
+  return nextState;
+}
+
+function updateStateForAnalyze(projectRoot, cliVersion) {
+  const currentState = readState(projectRoot);
+
+  if (!currentState) {
+    return null;
+  }
+
+  const nextState = {
+    ...currentState,
+    quiver_version: cliVersion,
+    last_analysis_at: new Date().toISOString(),
+  };
+
+  writeState(projectRoot, nextState);
+  return nextState;
+}
+
+module.exports = {
+  readState,
+  statePath,
+  updateStateForAnalyze,
+  updateStateForInit,
+  updateStateForMigrate,
+  writeState,
+};