create-quiver 0.12.0 → 0.12.1

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

@@ -1,7 +1,57 @@
 function stripJsonComments(text) {
-  return String(text || '')
-    .replace(/^\s*\/\/.*$/gm, '')
-    .replace(/\/\*[\s\S]*?\*\//g, '');
+  const input = String(text || '');
+  let output = '';
+  let inString = false;
+  let escaped = false;
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    const next = input[index + 1];
+
+    if (inString) {
+      output += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      output += char;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      while (index < input.length && input[index] !== '\n') {
+        index += 1;
+      }
+      if (index < input.length) {
+        output += '\n';
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      index += 2;
+      while (index < input.length && !(input[index] === '*' && input[index + 1] === '/')) {
+        if (input[index] === '\n') {
+          output += '\n';
+        }
+        index += 1;
+      }
+      index += 1;
+      continue;
+    }
+
+    output += char;
+  }
+
+  return output;
 }
 
 function parseJsonWithComments(text) {

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

@@ -2,7 +2,7 @@ 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 { buildGraph, normalizeDeclaredDependencies, readAllSlices, SliceGraphError, topoSort } = require('./slice-graph');
 const { resolveSliceContext, toAlias } = require('./slice');
 
 function ensureExists(filePath, message) {
@@ -117,6 +117,17 @@ 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 +189,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}`);
       }
@@ -209,7 +224,7 @@ function checkSliceReadiness(sliceInput, options = {}) {
   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';
 

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

@@ -19,6 +19,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 +116,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)
       : [],
-  );
+  ));
   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 +154,7 @@ function validateScopeSnapshot({ allowedFiles = [], beforeSnapshot, afterSnapsho
     ok: false,
     changedFiles,
     outOfScopeFiles,
-    allowedFiles: Array.from(normalizedAllowedFiles),
+    allowedFiles: normalizedAllowedFiles,
     beforeSnapshot,
     afterSnapshot,
     error,
@@ -121,6 +163,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

@@ -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)) : [],
   };
 }
 

package/src/create-quiver/lib/spec-worktrees.js

@@ -185,6 +185,7 @@ function startSpecWorktree(repoRoot, specInput, options = {}) {
     return {
       ...identity,
       baseRef,
+      dryRun: options.dryRun === true,
       reused: true,
       slice00,
       worktreePath: existingWorktree,
@@ -199,6 +200,17 @@ function startSpecWorktree(repoRoot, specInput, options = {}) {
     throw new Error(formatError('current checkout is not clean. Commit or stash before starting a spec worktree.'));
   }
 
+  if (options.dryRun === true) {
+    return {
+      ...identity,
+      baseRef,
+      currentBranch: currentBranch(repoRoot),
+      dryRun: true,
+      reused: false,
+      slice00,
+    };
+  }
+
   worktreePrune(repoRoot);
   fs.mkdirSync(path.dirname(identity.worktreePath), { recursive: true });
 
@@ -212,6 +224,7 @@ function startSpecWorktree(repoRoot, specInput, options = {}) {
     ...identity,
     baseRef,
     currentBranch: currentBranch(repoRoot),
+    dryRun: false,
     reused: false,
     slice00,
   };
@@ -219,13 +232,14 @@ function startSpecWorktree(repoRoot, specInput, options = {}) {
 
 function formatSpecStartResult(result) {
   return `${[
-    'Spec worktree ready',
+    result.dryRun ? 'Spec worktree start dry-run' : 'Spec worktree ready',
     `Branch: ${result.branchName}`,
     `Base: ${result.baseRef}`,
     `Worktree: ${result.worktreePath}`,
     `Reused: ${result.reused ? 'yes' : 'no'}`,
     `slice-00: ${result.slice00 ? result.slice00.status : 'missing'}`,
-  ].join('\n')}\n`;
+    result.dryRun && !result.reused ? `Would create worktree: ${result.worktreePath}` : '',
+  ].filter(Boolean).join('\n')}\n`;
 }
 
 function closeSpecWorktree(repoRoot, specInput, options = {}) {