create-quiver 0.17.4 → 0.17.6

package/src/create-quiver/lib/ai/analyze-project-docs.js

@@ -15,6 +15,43 @@ const ANALYZE_DOC_PROPOSAL_SCHEMA_VERSION = 1;
 const ANALYZE_DOC_PROPOSAL_KIND = 'quiver-analyze-project-doc-proposal';
 const ANALYZE_MANAGED_START = '<!-- quiver:analyze-project:start -->';
 const ANALYZE_MANAGED_END = '<!-- quiver:analyze-project:end -->';
+const CONTEXT_PREP_MANAGED_START = '<!-- quiver:context-prep:start -->';
+const CONTEXT_PREP_MANAGED_END = '<!-- quiver:context-prep:end -->';
+
+const CRITICAL_SCAFFOLD_PLACEHOLDER_PATTERNS = [
+  /\[Uno o dos parrafos que expliquen el proyecto\.\]/i,
+  /\[Frase principal del proyecto\]/i,
+  /\[Describe el usuario principal\.\]/i,
+  /\[Objetivo actual \d+\]/i,
+  /\[Datos sensibles que nunca se guardan\]/i,
+  /\[Datos que si se guardan\]/i,
+  /\[Medida de seguridad importante\]/i,
+  /\[One or two paragraphs? that explain the project\.\]/i,
+  /\[Project tagline\]/i,
+  /\[Describe the primary user\.\]/i,
+  /\[Current goal \d+\]/i,
+  /\[Sensitive data that is never stored\]/i,
+  /\[Data that is stored\]/i,
+  /\[Important security measure\]/i,
+  /\[Short project summary\.\]/i,
+  /\[Description\]/i,
+  /\[TODO: confirm [^\]\n]+\]/i,
+  /\[TODO: confirmar [^\]\n]+\]/i,
+];
+
+const SCAFFOLD_BOILERPLATE_PATTERNS = [
+  /^purpose:\s*"Human-readable project overview"$/i,
+  /^applies_when:\s*"onboarding, review"$/i,
+  /^supersedes:\s*null$/i,
+  /^El stack, package manager y comandos se generan en `docs\/PROJECT_MAP\.md` despues de ejecutar `analyze`\.$/i,
+  /^The stack, package manager, and command surface are generated in `docs\/PROJECT_MAP\.md` after analysis\.$/i,
+  /^If sos agente IA, lee `AI_CONTEXT\.md`\./i,
+  /^Read `AI_CONTEXT\.md` first if you are an AI agent\./i,
+  /^Use `npx create-quiver ai prepare-context --dry-run`/i,
+  /^TODO: confirm any repo fact/i,
+  /^Assumption: missing README_FOR_AI\.md/i,
+  /^Pending confirmation:/i,
+];
 
 const docProposalEntrySchema = z.object({
   path: z.string().trim().min(1),
@@ -67,6 +104,10 @@ function normalizeDocContent(content) {
   return `${String(content || '').replace(/\s+$/g, '')}\n`;
 }
 
+function normalizeNewlines(content) {
+  return String(content || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
 function managedBlock(content) {
   return [
     ANALYZE_MANAGED_START,
@@ -76,8 +117,240 @@ function managedBlock(content) {
   ].join('\n');
 }
 
+function findManagedBlockRange(content, startMarker, endMarker) {
+  const text = normalizeNewlines(content);
+  const start = text.indexOf(startMarker);
+  const end = text.indexOf(endMarker);
+  if (start < 0 || end <= start) {
+    return null;
+  }
+  return {
+    start,
+    end: end + endMarker.length,
+    content: text.slice(start + startMarker.length, end),
+  };
+}
+
+function removeManagedBlock(content, startMarker, endMarker) {
+  const text = normalizeNewlines(content);
+  const range = findManagedBlockRange(text, startMarker, endMarker);
+  if (!range) {
+    return {
+      content: text,
+      removed: false,
+      block: '',
+    };
+  }
+  return {
+    content: `${text.slice(0, range.start)}${text.slice(range.end)}`.replace(/\n{3,}/g, '\n\n').trimEnd(),
+    removed: true,
+    block: range.content,
+  };
+}
+
+function splitFrontmatter(content) {
+  const text = normalizeNewlines(content);
+  if (!text.startsWith('---\n')) {
+    return {
+      frontmatter: '',
+      body: text,
+      valid: false,
+      present: false,
+    };
+  }
+  const match = text.slice(4).match(/\n---\n/);
+  if (!match || match.index === undefined) {
+    return {
+      frontmatter: '',
+      body: text,
+      valid: false,
+      present: true,
+    };
+  }
+  const endIndex = 4 + match.index + '\n---\n'.length;
+  return {
+    frontmatter: text.slice(0, endIndex),
+    body: text.slice(endIndex),
+    valid: true,
+    present: true,
+  };
+}
+
+function collectCriticalPlaceholders(content) {
+  const findings = [];
+  const text = normalizeNewlines(content);
+  for (const pattern of CRITICAL_SCAFFOLD_PLACEHOLDER_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      findings.push(match[0]);
+    }
+  }
+  return [...new Set(findings)].sort();
+}
+
+function isCriticalPlaceholderLine(line) {
+  const trimmed = String(line || '').trim();
+  return CRITICAL_SCAFFOLD_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+
+function isScaffoldBoilerplateLine(line) {
+  const trimmed = String(line || '')
+    .replace(/^[-*]\s+/, '')
+    .replace(/^>\s*/, '')
+    .trim();
+  if (!trimmed) {
+    return true;
+  }
+  if (/^#+\s+/.test(trimmed)) {
+    return true;
+  }
+  if (/^last_updated:\s*"/i.test(trimmed) || /^token_cost:\s*\d+/i.test(trimmed)) {
+    return true;
+  }
+  if (/^Files Considered$|^Assumptions$|^Risks$|^Contradictions$|^Omitted Paths$/i.test(trimmed.replace(/^#+\s*/, ''))) {
+    return true;
+  }
+  return SCAFFOLD_BOILERPLATE_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+
+function significantHumanLines(content) {
+  return normalizeNewlines(content)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length >= 12)
+    .filter((line) => !isCriticalPlaceholderLine(line))
+    .filter((line) => !isScaffoldBoilerplateLine(line));
+}
+
+function classifyAnalyzeProjectDoc(currentContent) {
+  const current = normalizeNewlines(currentContent);
+  const frontmatter = splitFrontmatter(current);
+  const withoutAnalyze = removeManagedBlock(frontmatter.body, ANALYZE_MANAGED_START, ANALYZE_MANAGED_END);
+  const withoutContextPrep = removeManagedBlock(withoutAnalyze.content, CONTEXT_PREP_MANAGED_START, CONTEXT_PREP_MANAGED_END);
+  const visibleBody = withoutContextPrep.content.trim();
+  const visiblePlaceholders = collectCriticalPlaceholders(visibleBody);
+  const contextPrepPlaceholders = collectCriticalPlaceholders(withoutContextPrep.block);
+  const humanLines = significantHumanLines(visibleBody);
+  const contextPrepHumanLines = significantHumanLines(withoutContextPrep.block);
+  const hasManagedOnly = !visibleBody && (withoutAnalyze.removed || withoutContextPrep.removed);
+
+  let classification = 'unknown';
+  if (!current.trim()) {
+    classification = 'managed_only';
+  } else if (hasManagedOnly) {
+    classification = 'managed_only';
+  } else if (visiblePlaceholders.length > 0 && humanLines.length === 0) {
+    classification = 'scaffold';
+  } else if (visiblePlaceholders.length > 0 && humanLines.length > 0) {
+    classification = 'partial_scaffold';
+  } else if (withoutAnalyze.removed || withoutContextPrep.removed) {
+    classification = humanLines.length > 0 ? 'mixed' : 'managed_only';
+  } else if (humanLines.length > 0) {
+    classification = 'human_content';
+  }
+
+  return {
+    classification,
+    frontmatter,
+    visible_body: visibleBody,
+    has_analyze_project_block: withoutAnalyze.removed,
+    has_context_prep_block: withoutContextPrep.removed,
+    context_prep_is_scaffold: withoutContextPrep.removed && contextPrepHumanLines.length === 0 && contextPrepPlaceholders.length > 0,
+    critical_placeholders: visiblePlaceholders,
+    context_prep_placeholders: contextPrepPlaceholders,
+    human_line_count: humanLines.length,
+  };
+}
+
+function composeWithFrontmatter(frontmatter, body) {
+  const prefix = frontmatter?.valid ? `${frontmatter.frontmatter.trimEnd()}\n\n` : '';
+  return `${prefix}${normalizeDocContent(body)}`;
+}
+
+function visibleAnalyzeProjectContent(proposedContent) {
+  return normalizeDocContent(proposedContent).trimEnd();
+}
+
+function buildPreservedContentSection(content) {
+  const body = normalizeNewlines(content).trim();
+  if (!body) {
+    return '';
+  }
+  return `## Existing Content Preserved\n\n${body}`;
+}
+
+function normalizedMarkdownEquivalent(left, right) {
+  return normalizeNewlines(left).trim() === normalizeNewlines(right).trim();
+}
+
+function mergeAnalyzeProjectDoc(currentContent, proposedContent) {
+  const current = normalizeNewlines(currentContent);
+  const proposedVisible = visibleAnalyzeProjectContent(proposedContent);
+  const classification = classifyAnalyzeProjectDoc(current);
+  const currentWithoutAnalyze = removeManagedBlock(classification.frontmatter.body, ANALYZE_MANAGED_START, ANALYZE_MANAGED_END);
+  const currentWithoutContextPrep = removeManagedBlock(currentWithoutAnalyze.content, CONTEXT_PREP_MANAGED_START, CONTEXT_PREP_MANAGED_END);
+  const bodyWithoutManaged = currentWithoutContextPrep.content.trim();
+  const report = {
+    classification: classification.classification,
+    strategy: 'preserve-and-update-managed-block',
+    scaffold_replaced: false,
+    human_content_preserved: false,
+    analyze_project_block_replaced: classification.has_analyze_project_block,
+    context_prep_removed: false,
+    critical_placeholders: classification.critical_placeholders,
+    warnings: [],
+  };
+
+  let visibleBody;
+  if (['scaffold', 'managed_only'].includes(classification.classification)) {
+    visibleBody = proposedVisible;
+    report.strategy = classification.classification === 'scaffold'
+      ? 'replace-scaffold-primary-content'
+      : 'replace-managed-only-content';
+    report.scaffold_replaced = classification.classification === 'scaffold';
+  } else if (['partial_scaffold', 'mixed'].includes(classification.classification)) {
+    const cleaned = bodyWithoutManaged
+      .split('\n')
+      .filter((line) => !isCriticalPlaceholderLine(line))
+      .join('\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim();
+    const preserved = normalizedMarkdownEquivalent(cleaned, proposedVisible)
+      ? ''
+      : buildPreservedContentSection(cleaned);
+    visibleBody = preserved ? `${proposedVisible}\n\n${preserved}` : proposedVisible;
+    report.strategy = 'replace-placeholders-preserve-human-content';
+    report.scaffold_replaced = classification.critical_placeholders.length > 0;
+    report.human_content_preserved = Boolean(preserved);
+  } else {
+    visibleBody = bodyWithoutManaged
+      ? `${bodyWithoutManaged}\n\n${managedBlock(proposedContent).trimEnd()}`
+      : managedBlock(proposedContent).trimEnd();
+    report.human_content_preserved = bodyWithoutManaged.trim().length > 0;
+    if (classification.classification === 'unknown') {
+      report.warnings.push('document classification is unknown; preserved existing content and updated managed block only');
+    }
+    return {
+      content: composeWithFrontmatter(classification.frontmatter, visibleBody),
+      report,
+    };
+  }
+
+  if (classification.has_context_prep_block && (classification.context_prep_is_scaffold || classification.context_prep_placeholders.length > 0)) {
+    report.context_prep_removed = true;
+  }
+
+  return {
+    content: composeWithFrontmatter(
+      classification.frontmatter,
+      `${visibleBody}\n\n${managedBlock(proposedContent).trimEnd()}`,
+    ),
+    report,
+  };
+}
+
 function mergeManagedBlock(currentContent, proposedContent) {
-  const current = String(currentContent || '');
+  const current = normalizeNewlines(currentContent);
   const block = managedBlock(proposedContent);
   const startIndex = current.indexOf(ANALYZE_MANAGED_START);
   const endIndex = current.indexOf(ANALYZE_MANAGED_END);
@@ -253,9 +526,10 @@ function buildAnalyzeProjectWritePlan(repoRoot, proposal) {
     const destinationPath = path.join(repoRoot, doc.path);
     const exists = fs.existsSync(destinationPath);
     const currentContent = exists ? fs.readFileSync(destinationPath, 'utf8') : '';
-    const proposedContent = doc.action === 'skip'
-      ? currentContent
-      : mergeManagedBlock(currentContent, doc.content);
+    const merged = doc.action === 'skip'
+      ? { content: currentContent, report: { classification: 'skipped', strategy: 'skip' } }
+      : mergeAnalyzeProjectDoc(currentContent, doc.content);
+    const proposedContent = merged.content;
     const changed = currentContent.replace(/\r\n/g, '\n') !== proposedContent.replace(/\r\n/g, '\n');
     const action = doc.action === 'skip' || !changed ? 'skip' : exists ? 'update' : 'create';
 
@@ -271,6 +545,7 @@ function buildAnalyzeProjectWritePlan(repoRoot, proposal) {
       before_sha256: exists ? sha256(currentContent) : null,
       after_sha256: action === 'skip' ? (exists ? sha256(currentContent) : null) : sha256(proposedContent),
       diff: buildDiffSnippet(doc.path, currentContent, proposedContent),
+      merge_report: merged.report,
     };
   });
 }
@@ -368,12 +643,17 @@ module.exports = {
   ANALYZE_DOC_PROPOSAL_SCHEMA_VERSION,
   ANALYZE_MANAGED_END,
   ANALYZE_MANAGED_START,
+  CONTEXT_PREP_MANAGED_END,
+  CONTEXT_PREP_MANAGED_START,
   AnalyzeProjectDocsError,
   analyzeProjectDocProposalSchema,
   buildAnalyzeProjectDocProposal,
   buildAnalyzeProjectWritePlan,
+  classifyAnalyzeProjectDoc,
+  collectCriticalPlaceholders,
   createAnalyzeProjectSnapshot,
   formatAnalyzeProjectDiffPreview,
+  mergeAnalyzeProjectDoc,
   mergeManagedBlock,
   normalizeAnalyzeProjectDocProposal,
   parseAnalyzeProjectDocProposal,

package/src/create-quiver/lib/ai/analyze-project-proposal.js

@@ -127,6 +127,7 @@ const proposalManifestSchema = z.object({
   repair_manifest: relativePathSchema('repair_manifest').nullable(),
   doc_paths: z.array(relativePathSchema('doc_paths')).default([]),
   doc_before_hashes: z.record(z.string().trim().min(1), z.string().trim().min(1).nullable()).default({}),
+  merge_plan: z.array(z.record(z.string(), z.unknown())).default([]),
   proposal_sha256: z.string().trim().min(1),
   events: z.array(z.record(z.string(), z.unknown())).default([]),
 }).strict();
@@ -139,6 +140,7 @@ const writeManifestActionSchema = z.object({
   snapshot_path: relativePathSchema('actions.snapshot_path').nullable(),
   dirty: z.boolean().default(false),
   status: z.enum(['planned', 'written', 'skipped', 'failed']).default('planned'),
+  merge_report: z.record(z.string(), z.unknown()).optional(),
 }).strict();
 
 const writeManifestSchema = z.object({
@@ -419,9 +421,16 @@ function writeAnalyzeProjectProposalArtifacts(repoRoot, options = {}) {
   const proposalJson = `${JSON.stringify(proposal, null, 2)}\n`;
   const proposalHash = sha256(proposalJson);
   const docBeforeHashes = {};
+  const mergePlan = [];
 
   for (const item of writePlan) {
     docBeforeHashes[item.path] = item.before_sha256 || null;
+    mergePlan.push({
+      path: item.path,
+      action: item.action,
+      dirty: item.dirty === true,
+      merge_report: item.merge_report || null,
+    });
   }
 
   const selectedContextPath = artifactPathFromRef(options.selectedContextManifest)
@@ -441,6 +450,7 @@ function writeAnalyzeProjectProposalArtifacts(repoRoot, options = {}) {
     repair_manifest: repairPath,
     doc_paths: writePlan.map((item) => item.path),
     doc_before_hashes: docBeforeHashes,
+    merge_plan: mergePlan,
     proposal_sha256: proposalHash,
     events: [
       {
@@ -524,6 +534,7 @@ function writeAnalyzeProjectWriteManifest(repoRoot, options = {}) {
       snapshot_path: snapshotEntry?.snapshot_path || null,
       dirty: item.dirty === true,
       status,
+      merge_report: item.merge_report || undefined,
     };
   });
   const validation = options.validation || {