create-quiver 0.12.0 → 0.13.0

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

@@ -2,8 +2,9 @@ const fs = require('fs');
 const path = require('path');
 const { catFileExists, currentBranch, hasLocalBranch, hasRemoteBranch, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeList } = require('./git');
 const { parseJsonWithComments } = require('./json');
-const { buildGraph, readAllSlices, SliceGraphError, topoSort } = require('./slice-graph');
-const { resolveSliceContext, toAlias } = require('./slice');
+const { buildGraph, normalizeDeclaredDependencies, readAllSlices, SliceGraphError, topoSort } = require('./slice-graph');
+const { resolveSliceContext, toAlias, validateSliceMetaForStart } = require('./slice');
+const { validateProjectRelativePaths } = require('./paths');
 
 function ensureExists(filePath, message) {
   if (!fs.existsSync(filePath)) {
@@ -111,12 +112,30 @@ function validateLocalSliceArtifacts(repoRoot, slice) {
     throw new Error('create-quiver: slice.json.files contiene entradas invalidas.');
   }
   console.log('PASS: slice.json declara archivos de alcance.');
+
+  validateSliceMetaForStart(slice);
+  console.log('PASS: slice.json declara metadata git compatible con start-slice.');
+
+  validateProjectRelativePaths(slice.files, 'slice.json files/allowed_write_paths');
+  validateProjectRelativePaths(slice.expectedReadPaths, 'slice.json expected_read_paths');
+  console.log('PASS: slice.json declara rutas relativas seguras dentro del proyecto.');
 }
 
 function baseRecoveryMessage(remote, baseBranch) {
   return `No se encontro la base '${baseBranch}' como rama local ni como '${remote}/${baseBranch}'. Para validacion estructural usa --local; para validacion contra otra base usa --base <branch>; o configura/fetchea el remoto '${remote}'.`;
 }
 
+function resolveReadinessRoot(localMode) {
+  try {
+    return runGit(['rev-parse', '--show-toplevel'], process.cwd());
+  } catch (error) {
+    if (localMode) {
+      return process.cwd();
+    }
+    throw error;
+  }
+}
+
 function validateSliceDocumentedOnBase(repoRoot, slice, options = {}) {
   const gate = options.gate || 'execution';
   const remote = options.remote || 'origin';
@@ -178,8 +197,12 @@ function validateDeclaredDependencyContract(repoRoot, slice) {
       throw new Error(`create-quiver: depends_on contiene referencias duplicadas en ${currentRef}.`);
     }
 
+    const normalizedDeclared = normalizeDeclaredDependencies(currentNode, declared);
+    if (normalizedDeclared.length !== new Set(normalizedDeclared).size) {
+      throw new Error(`create-quiver: depends_on contiene referencias duplicadas en ${currentRef}.`);
+    }
     const currentSet = new Set(currentNode.depends_on || []);
-    for (const dep of declared) {
+    for (const dep of normalizedDeclared) {
       if (!currentSet.has(dep)) {
         throw new Error(`create-quiver: depends_on apunta a una referencia inexistente o invalida: ${dep}`);
       }
@@ -204,12 +227,17 @@ function validateDeclaredDependencyContract(repoRoot, slice) {
   }
 }
 
+function localCheckSummary() {
+  console.log('INFO: Modo local: checks ejecutados: spec docs, briefs, metadata git, scope declarado, rutas seguras, dependencias y gate.');
+  console.log('INFO: Modo local: checks omitidos: existencia en base remota/local y overlap contra worktrees activos.');
+}
+
 function checkSliceReadiness(sliceInput, options = {}) {
   const gate = options.gate || 'execution';
   const localMode = options.local === true;
   const strictOverlap = options.strictOverlap === true;
   const remote = options.remote || 'origin';
-  const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
+  const repoRoot = resolveReadinessRoot(localMode);
   const slice = resolveSliceContext(repoRoot, sliceInput);
   const baseBranch = options.baseBranch || slice.baseBranch || 'develop';
 
@@ -247,6 +275,9 @@ function checkSliceReadiness(sliceInput, options = {}) {
   }
 
   validateDeclaredDependencyContract(repoRoot, slice);
+  if (localMode) {
+    localCheckSummary();
+  }
 
   switch (gate) {
     case 'ready':
@@ -356,22 +387,47 @@ function checkPrReadiness(sliceInput) {
 
 function checkScope(sliceInput, options = {}) {
   const strict = options.strict === true;
+  const remote = options.remote || 'origin';
   const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
   const slice = resolveSliceContext(repoRoot, sliceInput);
   const declared = slice.files;
+  validateProjectRelativePaths(declared, 'slice scope path');
+
+  const explicitBaseBranch = typeof options.baseBranch === 'string' ? options.baseBranch.trim() : '';
+  const candidateBaseBranches = Array.from(new Set([
+    explicitBaseBranch,
+    slice.baseBranch,
+    'main',
+    'develop',
+    'master',
+  ].filter(Boolean)));
+
+  let baseRef = '';
+  let baseSource = '';
+  for (const candidate of candidateBaseBranches) {
+    if (hasRemoteBranch(repoRoot, candidate, remote)) {
+      baseRef = `${remote}/${candidate}`;
+      baseSource = explicitBaseBranch === candidate ? '--base' : candidate === slice.baseBranch ? 'slice.git.base_branch' : 'fallback';
+      break;
+    }
+    if (hasLocalBranch(repoRoot, candidate)) {
+      baseRef = candidate;
+      baseSource = explicitBaseBranch === candidate ? '--base' : candidate === slice.baseBranch ? 'slice.git.base_branch' : 'fallback';
+      break;
+    }
+  }
 
   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);
+  if (baseRef) {
+    touchedRaw = runGit(['diff', '--name-only', `${baseRef}...HEAD`], repoRoot);
+    console.log(`INFO: check-scope base: ${baseRef} (${baseSource}).`);
   } else {
-    console.log('WARN: No se encontro rama origin/develop ni develop. Saltando check de scope.');
+    console.log(`WARN: No se encontro base para check-scope. Probadas: ${candidateBaseBranches.join(', ')}. Usa --base <branch> o configura git.base_branch en slice.json.`);
     return;
   }
 
   if (!touchedRaw) {
-    console.log('WARN: No se encontraron archivos modificados respecto de develop.');
+    console.log(`WARN: No se encontraron archivos modificados respecto de ${baseRef}.`);
     return;
   }
 

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

@@ -1,6 +1,7 @@
 const { statusPorcelain } = require('./git');
 const { normalizeContextPath } = require('./ai/safety');
 const { checkScope } = require('./readiness');
+const { validateProjectRelativePaths } = require('./paths');
 
 class ScopeValidationError extends Error {
   constructor(code, message, details = {}) {
@@ -19,6 +20,48 @@ function normalizeScopePath(filePath) {
   return normalizeContextPath(filePath);
 }
 
+function globToRegExp(pattern) {
+  const source = String(pattern || '')
+    .split('')
+    .map((char, index, chars) => {
+      if (char === '*') {
+        return chars[index + 1] === '*' ? '\0' : '[^/]*';
+      }
+      if (char === '\0') {
+        return '.*';
+      }
+      return /[\\^$+?.()|[\]{}]/.test(char) ? `\\${char}` : char;
+    })
+    .join('')
+    .replace(/\0\[\^\/\]\*/g, '.*');
+
+  return new RegExp(`^${source}$`);
+}
+
+function allowedPathMatches(filePath, allowedPath) {
+  const file = normalizeScopePath(filePath);
+  const allowed = normalizeScopePath(allowedPath);
+
+  if (!file || !allowed) {
+    return false;
+  }
+
+  if (file === allowed) {
+    return true;
+  }
+
+  if (allowed.endsWith('/**')) {
+    const prefix = allowed.slice(0, -3);
+    return file === prefix || file.startsWith(`${prefix}/`);
+  }
+
+  if (allowed.includes('*')) {
+    return globToRegExp(allowed).test(file);
+  }
+
+  return false;
+}
+
 function parseStatusPorcelain(text) {
   if (!text) {
     return [];
@@ -74,30 +117,30 @@ function diffWorktreeSnapshots(beforeSnapshot, afterSnapshot) {
 }
 
 function validateScopeSnapshot({ allowedFiles = [], beforeSnapshot, afterSnapshot, strict = true } = {}) {
-  const normalizedAllowedFiles = new Set(
+  const normalizedAllowedFiles = Array.from(new Set(
     Array.isArray(allowedFiles)
-      ? allowedFiles.map(normalizeScopePath).filter(Boolean)
+      ? validateProjectRelativePaths(allowedFiles, 'allowed scope path').map(normalizeScopePath).filter(Boolean)
       : [],
-  );
+  ));
   const changedFiles = diffWorktreeSnapshots(beforeSnapshot, afterSnapshot);
-  const outOfScopeFiles = changedFiles.filter((file) => !normalizedAllowedFiles.has(file));
+  const outOfScopeFiles = changedFiles.filter((file) => !normalizedAllowedFiles.some((allowedFile) => allowedPathMatches(file, allowedFile)));
 
   if (outOfScopeFiles.length === 0) {
     return {
       ok: true,
       changedFiles,
       outOfScopeFiles,
-      allowedFiles: Array.from(normalizedAllowedFiles),
+      allowedFiles: normalizedAllowedFiles,
       beforeSnapshot,
       afterSnapshot,
     };
   }
 
   const message = formatError(
-    `scope violation detected: changed files outside slice.json.files: ${outOfScopeFiles.join(', ')}`,
+    `scope violation detected: changed files outside declared slice scope: ${outOfScopeFiles.join(', ')}`,
   );
   const error = new ScopeValidationError('SCOPE_VIOLATION', message, {
-    allowedFiles: Array.from(normalizedAllowedFiles),
+    allowedFiles: normalizedAllowedFiles,
     beforeSnapshot,
     afterSnapshot,
     changedFiles,
@@ -112,7 +155,7 @@ function validateScopeSnapshot({ allowedFiles = [], beforeSnapshot, afterSnapsho
     ok: false,
     changedFiles,
     outOfScopeFiles,
-    allowedFiles: Array.from(normalizedAllowedFiles),
+    allowedFiles: normalizedAllowedFiles,
     beforeSnapshot,
     afterSnapshot,
     error,
@@ -121,6 +164,7 @@ function validateScopeSnapshot({ allowedFiles = [], beforeSnapshot, afterSnapsho
 
 module.exports = {
   ScopeValidationError,
+  allowedPathMatches,
   captureWorktreeSnapshot,
   diffWorktreeSnapshots,
   checkScope,

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

@@ -66,6 +66,15 @@ function sortFileList(files) {
   return Array.from(new Set((Array.isArray(files) ? files : []).map((file) => String(file)).filter(Boolean))).sort((a, b) => a.localeCompare(b));
 }
 
+function resolveWriteScope(json) {
+  const allowedWritePaths = sortFileList(json?.allowed_write_paths);
+  if (allowedWritePaths.length > 0) {
+    return allowedWritePaths;
+  }
+
+  return sortFileList(json?.files);
+}
+
 function normalizeDependencyRef(slice, dependency) {
   const dep = String(dependency || '').trim();
   if (!dep) {
@@ -95,6 +104,61 @@ function normalizeDependencyRef(slice, dependency) {
   return `${slice.specSlug}/${dep}`;
 }
 
+function readSliceFile(rootDir, rootName, specSlug, sliceDirName) {
+  const sliceDir = path.join(rootDir, rootName, specSlug, 'slices', sliceDirName);
+  const slicePath = path.join(sliceDir, 'slice.json');
+  if (!fs.existsSync(slicePath)) {
+    return null;
+  }
+
+  const json = parseJsonWithComments(fs.readFileSync(slicePath, 'utf8'));
+  const sliceId = String(json.slice_id || sliceDirName).trim();
+  const ref = `${specSlug}/${sliceId}`;
+  return {
+    ref,
+    specFamily: rootName,
+    specSlug,
+    sliceId,
+    slicePath,
+    sliceDir,
+    files: resolveWriteScope(json),
+    expected_read_paths: sortFileList(json.expected_read_paths),
+    allowed_write_paths: sortFileList(json.allowed_write_paths),
+    validation_hints: sortFileList(json.validation_hints),
+    dependencies: Array.isArray(json.dependencies) ? json.dependencies.map((item) => String(item).trim()).filter(Boolean) : [],
+    depends_on: Array.isArray(json.depends_on) ? json.depends_on.map((item) => String(item).trim()).filter(Boolean) : [],
+    parallel_safe: typeof json.parallel_safe === 'string' ? json.parallel_safe : null,
+    parallel_safe_reason: typeof json.parallel_safe_reason === 'string' ? json.parallel_safe_reason : null,
+    status: typeof json.status === 'string' ? json.status : 'draft',
+    ticket: typeof json.ticket === 'string' ? json.ticket : '',
+    title: typeof json.title === 'string' ? json.title : sliceId,
+    json,
+  };
+}
+
+function readSpecSlices(rootDir, rootName, specSlug) {
+  const slicesDir = path.join(rootDir, rootName, specSlug, 'slices');
+  if (!fs.existsSync(slicesDir)) {
+    return [];
+  }
+
+  const slices = [];
+
+  for (const sliceEntry of fs.readdirSync(slicesDir, { withFileTypes: true })) {
+    if (!sliceEntry.isDirectory() || isPlaceholderSliceDir(sliceEntry.name)) {
+      continue;
+    }
+
+    const slice = readSliceFile(rootDir, rootName, specSlug, sliceEntry.name);
+    if (slice) {
+      slices.push(slice);
+    }
+  }
+
+  slices.sort((left, right) => compareSliceRefs(left.ref, right.ref));
+  return slices;
+}
+
 function readAllSlices(rootDir) {
   const roots = ['specs', 'specs-fix'];
   const slices = [];
@@ -110,44 +174,7 @@ function readAllSlices(rootDir) {
         continue;
       }
 
-      const specSlug = specEntry.name;
-      const slicesDir = path.join(rootPath, specSlug, 'slices');
-      if (!fs.existsSync(slicesDir)) {
-        continue;
-      }
-
-      for (const sliceEntry of fs.readdirSync(slicesDir, { withFileTypes: true })) {
-        if (!sliceEntry.isDirectory() || isPlaceholderSliceDir(sliceEntry.name)) {
-          continue;
-        }
-
-        const sliceDir = path.join(slicesDir, sliceEntry.name);
-        const slicePath = path.join(sliceDir, 'slice.json');
-        if (!fs.existsSync(slicePath)) {
-          continue;
-        }
-
-        const json = parseJsonWithComments(fs.readFileSync(slicePath, 'utf8'));
-        const sliceId = String(json.slice_id || sliceEntry.name).trim();
-        const ref = `${specSlug}/${sliceId}`;
-        slices.push({
-          ref,
-          specFamily: rootName,
-          specSlug,
-          sliceId,
-          slicePath,
-          sliceDir,
-          files: sortFileList(json.files),
-          dependencies: Array.isArray(json.dependencies) ? json.dependencies.map((item) => String(item).trim()).filter(Boolean) : [],
-          depends_on: Array.isArray(json.depends_on) ? json.depends_on.map((item) => String(item).trim()).filter(Boolean) : [],
-          parallel_safe: typeof json.parallel_safe === 'string' ? json.parallel_safe : null,
-          parallel_safe_reason: typeof json.parallel_safe_reason === 'string' ? json.parallel_safe_reason : null,
-          status: typeof json.status === 'string' ? json.status : 'draft',
-          ticket: typeof json.ticket === 'string' ? json.ticket : '',
-          title: typeof json.title === 'string' ? json.title : sliceId,
-          json,
-        });
-      }
+      slices.push(...readSpecSlices(rootDir, rootName, specEntry.name));
     }
   }
 
@@ -171,6 +198,75 @@ function declaredDependenciesForSlice(slice) {
   return null;
 }
 
+function readSliceByRef(rootDir, ref) {
+  const value = String(ref || '').trim();
+  const slashIndex = value.indexOf('/');
+  if (slashIndex === -1) {
+    return null;
+  }
+
+  const specSlug = value.slice(0, slashIndex);
+  const sliceId = value.slice(slashIndex + 1);
+  if (!specSlug || !sliceId) {
+    return null;
+  }
+
+  for (const rootName of ['specs', 'specs-fix']) {
+    const direct = readSliceFile(rootDir, rootName, specSlug, sliceId);
+    if (direct) {
+      return direct;
+    }
+
+    for (const slice of readSpecSlices(rootDir, rootName, specSlug)) {
+      if (slice.ref === value) {
+        return slice;
+      }
+    }
+  }
+
+  return null;
+}
+
+function readSlicesForSpec(rootDir, specSlug) {
+  const targetSpec = String(specSlug || '').trim();
+  if (!targetSpec) {
+    return readAllSlices(rootDir);
+  }
+
+  const byRef = new Map();
+  const queue = [];
+
+  function addSlice(slice) {
+    if (!slice || byRef.has(slice.ref)) {
+      return;
+    }
+    byRef.set(slice.ref, slice);
+    queue.push(slice);
+  }
+
+  for (const rootName of ['specs', 'specs-fix']) {
+    for (const slice of readSpecSlices(rootDir, rootName, targetSpec)) {
+      addSlice(slice);
+    }
+  }
+
+  while (queue.length > 0) {
+    const slice = queue.shift();
+    for (const dep of declaredDependenciesForSlice(slice) || []) {
+      if (byRef.has(dep)) {
+        continue;
+      }
+
+      const dependencySlice = readSliceByRef(rootDir, dep);
+      if (dependencySlice) {
+        addSlice(dependencySlice);
+      }
+    }
+  }
+
+  return Array.from(byRef.values()).sort((left, right) => compareSliceRefs(left.ref, right.ref));
+}
+
 function inferDependencies(slices) {
   const bySpec = new Map();
   const normalized = slices.map((slice) => ({
@@ -454,7 +550,11 @@ module.exports = {
   detectFileConflicts,
   inferDependencies,
   isFoundationSliceId,
+  normalizeDeclaredDependencies,
+  normalizeDependencyRef,
   readAllSlices,
+  readSlicesForSpec,
   naturalNumberFromSliceId,
+  resolveWriteScope,
   topoSort,
 };

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

@@ -1,7 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { parseJsonWithComments } = require('./json');
-const { normalizeGitBashDrivePath, relativePosixPath, resolveTargetRoot, specRelativePathFromPath, toPosixPath } = require('./paths');
+const { assertPathInsideRoot, normalizeGitBashDrivePath, relativePosixPath, resolveTargetRoot, specRelativePathFromPath, toPosixPath } = require('./paths');
 
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -42,14 +42,18 @@ function readSliceMeta(slicePath) {
   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';
+  const allowedWritePaths = Array.isArray(json.allowed_write_paths) ? json.allowed_write_paths.map((item) => String(item)) : [];
+  const legacyFiles = Array.isArray(json.files) ? json.files.map((item) => String(item)) : [];
 
   return {
     acceptance: Array.isArray(json.acceptance) ? json.acceptance : [],
+    allowedWritePaths,
     baseBranch,
     branchName,
     branchSlug,
     branchType,
-    files: Array.isArray(json.files) ? json.files : [],
+    expectedReadPaths: Array.isArray(json.expected_read_paths) ? json.expected_read_paths.map((item) => String(item)) : [],
+    files: allowedWritePaths.length > 0 ? allowedWritePaths : legacyFiles,
     git,
     isBaseline: sliceId.startsWith('slice-00'),
     json,
@@ -60,6 +64,7 @@ function readSliceMeta(slicePath) {
     status,
     tests: Array.isArray(json.tests) ? json.tests : [],
     ticket,
+    validationHints: Array.isArray(json.validation_hints) ? json.validation_hints.map((item) => String(item)) : [],
   };
 }
 
@@ -84,9 +89,12 @@ function validateSliceMetaForStart(slice) {
     throw new Error(`create-quiver: git.branch_type invalido: "${slice.branchType}". Usa "feature", "bugfix" o "hotfix".`);
   }
 
-  const allowedBaseBranches = allowedBaseByType[slice.branchType];
-  if (!allowedBaseBranches.includes(slice.baseBranch)) {
-    throw new Error(`create-quiver: git.base_branch invalido para ${slice.branchType}. Usa "${allowedBaseBranches.join('" o "')}".`);
+  if (!/^[A-Za-z0-9._/-]+$/.test(slice.baseBranch)
+    || slice.baseBranch.includes('..')
+    || slice.baseBranch.startsWith('/')
+    || slice.baseBranch.endsWith('/')
+    || slice.baseBranch.includes('\\')) {
+    throw new Error('create-quiver: git.base_branch invalido. Usa una rama base valida como "main", "develop", "master" o "release/2026".');
   }
 
   const expectedBranchName = `${slice.branchType}/${slice.ticket}-${slice.branchSlug}`;
@@ -111,6 +119,7 @@ function resolveRepoSlicePath(repoRoot, relSlicePath) {
 function resolveSliceContext(repoRoot, slicePath) {
   const canonicalRepoRoot = canonicalizePath(repoRoot);
   let absSlicePath = resolveSlicePath(slicePath);
+  assertPathInsideRoot(canonicalRepoRoot, absSlicePath, 'slice path');
   let relSlicePath = relativePosixPath(canonicalRepoRoot, absSlicePath);
   let parts = relSlicePath.split('/');