create-quiver 0.17.1 → 0.17.3

package/src/create-quiver/index.js

@@ -230,7 +230,7 @@ const COMMAND_HELP_GROUPS = [
       ['ai active-slice status|reconcile', 'Inspect or dry-run reconcile local active-slice state from every supported source.'],
       ['ai status', 'Show current AI lifecycle phase, approved versions, blockers, and next command.'],
       ['ai resume', 'Resume guidance from the last valid lifecycle phase without chat memory.'],
-      ['ai analyze-project', 'Read and explain a bounded project sample without provider execution or writes.'],
+      ['ai analyze-project', 'Analyze a bounded project sample and generate audited documentation proposals.'],
       ['ai onboard', 'Run or print the planner onboarding prompt with a token-aware context pack.'],
       ['ai prepare-context', 'Preview or write docs-only AI context updates with assumptions and risks.'],
       ['ai agent set|list|show|doctor|repair', 'Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets.'],
@@ -330,6 +330,7 @@ function printUsage(language = DEFAULT_LANGUAGE) {
   npx create-quiver ai status [options]
   npx create-quiver ai resume [options]
   npx create-quiver ai analyze-project [--deep] [--dry-run] [--json]
+  npx create-quiver ai analyze-project apply --run <run-id>
   npx create-quiver ai inspect [options]
   npx create-quiver ai export [--format json|markdown]
   npx create-quiver ai specs list [--json]
@@ -396,6 +397,10 @@ ${helpText(help, 'headings', 'options', 'Options:')}
       --include-source        ${optionDescription(help, 'For ai analyze-project, include source files without requiring --deep')}
       --include-tests         ${optionDescription(help, 'For ai analyze-project, include test files in the sample')}
       --include-db            ${optionDescription(help, 'For ai analyze-project, include schema, migration, and DB files in the sample')}
+      --apply-docs            ${optionDescription(help, 'For ai analyze-project, apply validated documentation proposals through the safe docs workflow')}
+      --save-proposal         ${optionDescription(help, 'For ai analyze-project, save a validated documentation proposal without writing final docs')}
+      --diff                  ${optionDescription(help, 'For ai analyze-project, show or save the proposed documentation diff')}
+      --allow-dirty-docs      ${optionDescription(help, 'For ai analyze-project, allow dirty target docs checks where the safe apply workflow supports it')}
       --scope <path|name>     ${optionDescription(help, 'For ai analyze-project, restrict discovery to a repo path or workspace name')}
       --print-prompt          ${optionDescription(help, 'Print the exact AI prompt and exit without executing provider CLIs')}
       --with-planner          ${optionDescription(help, 'Enable planner-assisted behavior on commands that explicitly support it')}
@@ -579,6 +584,10 @@ function parseArgs(argv, options = {}) {
     aiAnalyzeIncludeDb: false,
     aiAnalyzeIncludeSource: false,
     aiAnalyzeIncludeTests: false,
+    aiAnalyzeApplyDocs: false,
+    aiAnalyzeSaveProposal: false,
+    aiAnalyzeDiff: false,
+    aiAnalyzeAllowDirtyDocs: false,
     aiAnalyzeMaxBytes: null,
     aiAnalyzeMaxFiles: null,
     aiAnalyzeScope: '',
@@ -763,6 +772,30 @@ function parseArgs(argv, options = {}) {
       continue;
     }
 
+    if (arg === '--apply-docs') {
+      result.aiAnalyzeApplyDocs = true;
+      result.aiAnalyzeOptionUsed = true;
+      continue;
+    }
+
+    if (arg === '--save-proposal') {
+      result.aiAnalyzeSaveProposal = true;
+      result.aiAnalyzeOptionUsed = true;
+      continue;
+    }
+
+    if (arg === '--diff') {
+      result.aiAnalyzeDiff = true;
+      result.aiAnalyzeOptionUsed = true;
+      continue;
+    }
+
+    if (arg === '--allow-dirty-docs') {
+      result.aiAnalyzeAllowDirtyDocs = true;
+      result.aiAnalyzeOptionUsed = true;
+      continue;
+    }
+
     if (arg === '--max-files') {
       const value = args[++index];
       if (typeof value === 'undefined') {
@@ -1332,6 +1365,15 @@ function parseArgs(argv, options = {}) {
     if (result.aiCommand === 'run' && !result.aiRunCommand && positional.length > 0) {
       result.aiRunCommand = positional.shift();
     }
+    if (result.aiCommand === 'analyze-project' && !result.aiSecondaryCommand && positional.length > 0) {
+      result.aiSecondaryCommand = positional.shift();
+    }
+    if (result.aiCommand === 'analyze-project' && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'apply') {
+      throw new Error(formatError(`unsupported ai analyze-project subcommand: ${result.aiSecondaryCommand}. Supported tasks: apply`));
+    }
+    if (result.aiCommand === 'analyze-project' && result.aiSecondaryCommand === 'apply' && !result.aiRunId) {
+      throw new Error(formatError('ai analyze-project apply requires --run <run-id>'));
+    }
     if ((result.aiCommand === 'specs' || result.aiCommand === 'slices' || result.aiCommand === 'models' || result.aiCommand === 'trace' || result.aiCommand === 'active-slice') && !result.aiSecondaryCommand && positional.length > 0) {
       result.aiSecondaryCommand = positional.shift();
     }
@@ -1470,6 +1512,33 @@ function parseArgs(argv, options = {}) {
     throw new Error(formatError('--global is only supported by config language set. Use: npx create-quiver config language set <en|es> --global'));
   }
 
+  if (result.mode === 'ai' && result.aiCommand === 'analyze-project') {
+    if (result.review && result.aiAnalyzeApplyDocs) {
+      throw new Error(formatError('ai analyze-project --apply-docs cannot be combined with --review'));
+    }
+    if (result.dryRun && result.aiAnalyzeApplyDocs) {
+      throw new Error(formatError('ai analyze-project --dry-run cannot be combined with --apply-docs'));
+    }
+    if (result.dryRun && result.aiAnalyzeSaveProposal) {
+      throw new Error(formatError('ai analyze-project --dry-run cannot be combined with --save-proposal'));
+    }
+    if (result.dryRun && result.aiSecondaryCommand === 'apply') {
+      throw new Error(formatError('ai analyze-project apply --run cannot be combined with --dry-run'));
+    }
+    if (result.aiSecondaryCommand === 'apply' && (result.aiAnalyzeApplyDocs || result.aiAnalyzeSaveProposal || result.review)) {
+      throw new Error(formatError('ai analyze-project apply --run cannot be combined with --apply-docs, --save-proposal, or --review'));
+    }
+    if (result.aiSecondaryCommand === 'apply' && result.aiRunId === 'latest' && result.force) {
+      throw new Error(formatError('ai analyze-project apply --run latest cannot be combined with --yes'));
+    }
+    if (result.aiSecondaryCommand === 'apply' && result.aiRunId === 'latest' && result.json) {
+      throw new Error(formatError('ai analyze-project apply --run latest cannot be combined with --json'));
+    }
+    if (result.json && result.aiAnalyzeApplyDocs && !result.force) {
+      throw new Error(formatError('ai analyze-project --json with --apply-docs requires --yes'));
+    }
+  }
+
   return result;
 }
 
@@ -2862,6 +2931,9 @@ function buildDoctorCommandReport(projectRoot) {
 
   const suggestedFixes = [
     ...doctorReport.recommendations,
+    doctorReport.warnings.some((warning) => String(warning).includes('AGENTS.md'))
+      ? 'Repair AGENTS.md contract: npx create-quiver doctor --fix --dry-run, then npx create-quiver doctor --fix'
+      : '',
     !hasQuiverState
       ? 'Run migration first: npx create-quiver migrate'
       : !hasScanArtifacts
@@ -3516,6 +3588,10 @@ async function run(argv) {
       await runAiAnalyzeProject(process.cwd(), {
         deep: args.aiAnalyzeDeep,
         dryRun: args.dryRun,
+        allowDirtyDocs: args.aiAnalyzeAllowDirtyDocs,
+        applyDocs: args.aiAnalyzeApplyDocs,
+        applyRun: args.aiSecondaryCommand === 'apply',
+        diff: args.aiAnalyzeDiff,
         force: args.force,
         includeDb: args.aiAnalyzeIncludeDb,
         includeSource: args.aiAnalyzeIncludeSource,
@@ -3525,10 +3601,16 @@ async function run(argv) {
         language: args.language,
         maxBytes: args.aiAnalyzeMaxBytes || undefined,
         maxFiles: args.aiAnalyzeMaxFiles || undefined,
+        model: args.aiModel || undefined,
         printPrompt: args.aiPrintPrompt,
+        provider: args.aiProvider || undefined,
+        providerExplicit: args.aiProviderExplicit,
         review: args.review,
+        runId: args.aiRunId || undefined,
+        saveProposal: args.aiAnalyzeSaveProposal,
         scope: args.aiAnalyzeScope || undefined,
         strict: args.strict,
+        timeout: args.aiTimeout || undefined,
       });
       return;
     }

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

@@ -0,0 +1,269 @@
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+
+const {
+  buildAnalyzeProjectWritePlan,
+  createAnalyzeProjectSnapshot,
+  writeAnalyzeProjectDocs,
+} = require('./analyze-project-docs');
+const {
+  buildAnalyzeProjectProposalArtifactPaths,
+  normalizeAnalyzeProjectProposalManifest,
+  writeAnalyzeProjectProposalArtifacts,
+  writeAnalyzeProjectWriteManifest,
+} = require('./analyze-project-proposal');
+const { validateAnalyzeProjectPostWrite } = require('./analyze-project-validation');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+class AnalyzeProjectApplyError extends Error {
+  constructor(message, issues = []) {
+    super(formatError(message));
+    this.name = 'AnalyzeProjectApplyError';
+    this.code = 'AI_ANALYZE_PROJECT_APPLY_BLOCKED';
+    this.issues = issues;
+  }
+}
+
+function sha256(contents) {
+  return crypto.createHash('sha256').update(String(contents || ''), 'utf8').digest('hex');
+}
+
+function readCurrentHash(item) {
+  if (!fs.existsSync(item.destinationPath)) {
+    return null;
+  }
+  return sha256(fs.readFileSync(item.destinationPath, 'utf8'));
+}
+
+function collectWrittenDocs(writePlan) {
+  const written = [];
+  for (const item of writePlan) {
+    if (item.action === 'skip') {
+      continue;
+    }
+    if (readCurrentHash(item) === item.after_sha256) {
+      written.push(item.path);
+    }
+  }
+  return written;
+}
+
+function assertAnalyzeProjectApplyPreflight(writePlan, proposalManifest, options = {}) {
+  const issues = [];
+  const beforeHashes = proposalManifest?.doc_before_hashes || {};
+
+  for (const item of writePlan) {
+    if (item.action === 'skip') {
+      continue;
+    }
+    if (item.dirty === true && options.allowDirtyDocs !== true) {
+      issues.push({
+        path: item.path,
+        issue: 'dirty-target-doc',
+        message: 'target documentation already has human content; --yes requires --allow-dirty-docs or interactive review',
+      });
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(beforeHashes, item.path)) {
+      issues.push({
+        path: item.path,
+        issue: 'missing-before-hash',
+        message: 'proposal manifest is missing the current doc hash for this target path',
+      });
+      continue;
+    }
+
+    const currentHash = readCurrentHash(item);
+    const expectedHash = beforeHashes[item.path] || null;
+    if (currentHash !== expectedHash) {
+      issues.push({
+        path: item.path,
+        issue: 'stale-target-doc',
+        message: 'target documentation changed after the proposal was built',
+        expected_sha256: expectedHash,
+        current_sha256: currentHash,
+      });
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new AnalyzeProjectApplyError(
+      'ai analyze-project --apply-docs --yes blocked before writing final docs',
+      issues,
+    );
+  }
+
+  return { ok: true, issues: [] };
+}
+
+function validationFromWriteError(error, options = {}) {
+  return {
+    ok: false,
+    strict: options.strict === true,
+    errors: [{
+      path: null,
+      issue: 'write-failed',
+      message: error?.message || 'analyze-project doc write failed',
+    }],
+    warnings: [],
+  };
+}
+
+function normalizeLoadedProposalArtifacts(runId, proposalArtifacts = {}, proposalManifest = null) {
+  const paths = buildAnalyzeProjectProposalArtifactPaths(runId);
+  const manifestData = normalizeAnalyzeProjectProposalManifest(proposalManifest || proposalArtifacts.manifest_data || {});
+  return {
+    root: proposalArtifacts.root || paths.root,
+    proposal_json: proposalArtifacts.proposal_json || manifestData.proposal_json,
+    proposal_markdown: proposalArtifacts.proposal_markdown || manifestData.proposal_markdown,
+    proposal_diff: proposalArtifacts.proposal_diff || manifestData.proposal_diff,
+    manifest: proposalArtifacts.manifest || paths.manifest,
+    proposal_sha256: proposalArtifacts.proposal_sha256 || manifestData.proposal_sha256,
+    doc_paths: proposalArtifacts.doc_paths || manifestData.doc_paths || [],
+    changed_docs: proposalArtifacts.changed_docs || manifestData.doc_paths || [],
+    manifest_data: manifestData,
+    files: Array.isArray(proposalArtifacts.files)
+      ? proposalArtifacts.files
+      : [
+        manifestData.proposal_json,
+        manifestData.proposal_markdown,
+        manifestData.proposal_diff,
+        paths.manifest,
+      ],
+  };
+}
+
+function applyAnalyzeProjectDocProposal(repoRoot, options = {}) {
+  const runId = String(options.runId || '').trim();
+  const proposal = options.proposal;
+  const now = options.now instanceof Date ? options.now : new Date(options.now || Date.now());
+  const writePlan = buildAnalyzeProjectWritePlan(repoRoot, proposal);
+  const applyEvents = Array.isArray(options.events) ? options.events : [];
+  const proposalArtifacts = options.proposalArtifacts
+    ? normalizeLoadedProposalArtifacts(runId, options.proposalArtifacts, options.proposalManifest)
+    : writeAnalyzeProjectProposalArtifacts(repoRoot, {
+      runId,
+      now,
+      provider: options.provider,
+      language: options.language,
+      proposal,
+      writePlan,
+      selectedContextManifest: options.selectedContextManifest,
+      repairManifest: options.repairManifest,
+      events: [{ type: 'proposal-saved-before-apply', at: now.toISOString() }],
+    });
+
+  try {
+    assertAnalyzeProjectApplyPreflight(writePlan, proposalArtifacts.manifest_data, {
+      allowDirtyDocs: options.allowDirtyDocs === true,
+    });
+  } catch (error) {
+    error.proposal_artifacts = proposalArtifacts;
+    error.write_plan = writePlan;
+    throw error;
+  }
+
+  const snapshot = createAnalyzeProjectSnapshot(repoRoot, { run_id: runId }, writePlan, {
+    providerArtifact: options.providerArtifact,
+    proposal,
+    now,
+  });
+  const plannedManifest = writeAnalyzeProjectWriteManifest(repoRoot, {
+    runId,
+    now,
+    proposalManifest: proposalArtifacts.manifest,
+    snapshot,
+    writePlan,
+    strict: options.strict === true,
+    status: 'planned',
+    events: [
+      ...applyEvents,
+      { type: 'write-planned', at: now.toISOString() },
+    ],
+  });
+
+  let writtenDocs = [];
+  try {
+    writtenDocs = writeAnalyzeProjectDocs(writePlan);
+  } catch (error) {
+    const partialDocs = collectWrittenDocs(writePlan);
+    const failedManifest = writeAnalyzeProjectWriteManifest(repoRoot, {
+      runId,
+      now: new Date(),
+      proposalManifest: proposalArtifacts.manifest,
+      snapshot,
+      writePlan,
+      writtenDocs: partialDocs,
+      validation: validationFromWriteError(error, { strict: options.strict === true }),
+      partialWrite: partialDocs.length > 0,
+      status: 'completed',
+      events: [
+        ...applyEvents,
+        { type: 'write-planned', at: now.toISOString() },
+        { type: 'write-failed', at: new Date().toISOString(), message: error?.message || 'write failed' },
+      ],
+    });
+    error.write_manifest = failedManifest;
+    error.snapshot = snapshot;
+    error.written_docs = partialDocs;
+    throw error;
+  }
+
+  const writeReport = {
+    ...options.report,
+    apply_docs: true,
+    writes: writtenDocs,
+    doc_proposal: proposal,
+    write_plan: options.summarizeWritePlan
+      ? options.summarizeWritePlan(writePlan)
+      : writePlan,
+    snapshot,
+    written_docs: writtenDocs,
+    proposal_artifacts: {
+      root: proposalArtifacts.root,
+      proposal_json: proposalArtifacts.proposal_json,
+      proposal_markdown: proposalArtifacts.proposal_markdown,
+      proposal_diff: proposalArtifacts.proposal_diff,
+      manifest: proposalArtifacts.manifest,
+      proposal_sha256: proposalArtifacts.proposal_sha256,
+      proposal_edited: options.proposalEdited === true,
+    },
+    write_manifest: {
+      path: plannedManifest.path,
+    },
+  };
+  const postWriteValidation = validateAnalyzeProjectPostWrite(repoRoot, writeReport, {
+    strict: options.strict === true,
+  });
+  const finalManifest = writeAnalyzeProjectWriteManifest(repoRoot, {
+    runId,
+    now: new Date(),
+    proposalManifest: proposalArtifacts.manifest,
+    snapshot,
+    writePlan,
+    writtenDocs,
+    validation: postWriteValidation,
+    partialWrite: false,
+    status: 'completed',
+    events: [
+      ...applyEvents,
+      { type: 'write-planned', at: now.toISOString() },
+      { type: 'write-completed', at: new Date().toISOString(), written_docs: writtenDocs },
+    ],
+  });
+
+  return {
+    ...writeReport,
+    post_write_validation: postWriteValidation,
+    write_manifest: finalManifest,
+  };
+}
+
+module.exports = {
+  AnalyzeProjectApplyError,
+  applyAnalyzeProjectDocProposal,
+  assertAnalyzeProjectApplyPreflight,
+};

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

@@ -2,7 +2,11 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { getContextPathExclusionReason } = require('./safety');
-const { classifyProjectFile, summarizeByReason } = require('./analyze-project-sampling');
+const {
+  classifyProjectFile,
+  isLockfilePath,
+  summarizeByReason,
+} = require('./analyze-project-sampling');
 
 const BINARY_EXTENSIONS = new Set([
   '.7z',
@@ -38,6 +42,20 @@ const BINARY_EXTENSIONS = new Set([
   '.woff2',
   '.zip',
 ]);
+const STRUCTURAL_TEXT_EXTENSIONS = new Set([
+  '.cjs',
+  '.cts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.mts',
+  '.ts',
+  '.tsx',
+  '.vue',
+  '.svelte',
+]);
+const MAX_STRUCTURAL_FILES = 80;
+const MAX_STRUCTURAL_FILE_BYTES = 20_000;
 
 function toPosix(filePath) {
   return String(filePath || '').replace(/\\/g, '/');
@@ -80,12 +98,95 @@ function detectPackageManager(repoRoot) {
   return 'unknown';
 }
 
+function packageManagerFromLockfile(filePath) {
+  const base = path.posix.basename(toPosix(filePath)).toLowerCase();
+  if (base === 'package-lock.json') return 'npm';
+  if (base === 'pnpm-lock.yaml') return 'pnpm';
+  if (base === 'yarn.lock') return 'yarn';
+  if (base === 'bun.lockb') return 'bun';
+  if (base === 'cargo.lock') return 'cargo';
+  if (base === 'gemfile.lock') return 'bundler';
+  if (base === 'composer.lock') return 'composer';
+  if (base === 'poetry.lock') return 'poetry';
+  if (base === 'go.sum') return 'go';
+  return 'unknown';
+}
+
 function readPackageJson(repoRoot, relativeDir = '.') {
   const packagePath = path.join(repoRoot, relativeDir, 'package.json');
   const pkg = fs.existsSync(packagePath) ? safeReadJson(packagePath) : null;
   return pkg && typeof pkg === 'object' ? pkg : null;
 }
 
+function dependencyNamesFromPackageJson(packageJson) {
+  const names = [
+    ...Object.keys(packageJson?.dependencies || {}),
+    ...Object.keys(packageJson?.devDependencies || {}),
+    ...Object.keys(packageJson?.peerDependencies || {}),
+    ...Object.keys(packageJson?.optionalDependencies || {}),
+  ];
+  return uniqueSorted(names);
+}
+
+function summarizeNpmLockfile(lockfilePath) {
+  const lock = safeReadJson(lockfilePath);
+  if (!lock || typeof lock !== 'object') {
+    return {
+      dependency_count: null,
+      dependency_count_source: 'unreadable-package-lock',
+    };
+  }
+
+  if (lock.packages && typeof lock.packages === 'object') {
+    return {
+      dependency_count: Object.keys(lock.packages).filter(Boolean).length,
+      dependency_count_source: 'package-lock.packages',
+    };
+  }
+
+  if (lock.dependencies && typeof lock.dependencies === 'object') {
+    return {
+      dependency_count: Object.keys(lock.dependencies).length,
+      dependency_count_source: 'package-lock.dependencies',
+    };
+  }
+
+  return {
+    dependency_count: 0,
+    dependency_count_source: 'package-lock.empty',
+  };
+}
+
+function summarizeLockfiles(repoRoot, files) {
+  const packageJson = readPackageJson(repoRoot);
+  const topDependencies = dependencyNamesFromPackageJson(packageJson).slice(0, 30);
+
+  return files
+    .filter((file) => isLockfilePath(file.path))
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .map((file) => {
+      const manager = packageManagerFromLockfile(file.path);
+      const lockfilePath = path.join(repoRoot, file.path);
+      const details = manager === 'npm'
+        ? summarizeNpmLockfile(lockfilePath)
+        : {
+            dependency_count: null,
+            dependency_count_source: 'not-estimated',
+          };
+
+      return {
+        path: file.path,
+        package_manager: manager,
+        bytes: file.bytes || 0,
+        content_included: false,
+        dependency_count: details.dependency_count,
+        dependency_count_source: details.dependency_count_source,
+        top_dependencies: topDependencies,
+        reason: 'lockfile summarized as metadata; full content excluded from provider sample by default',
+      };
+    });
+}
+
 function expandWorkspacePattern(repoRoot, pattern) {
   const normalized = toPosix(pattern).trim();
   if (!normalized || normalized.startsWith('!')) {
@@ -352,12 +453,122 @@ function detectStack(repoRoot, files) {
   };
 }
 
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function extractImportSpecifiers(content) {
+  const imports = [];
+  const patterns = [
+    /\bimport\s+[^'"]*from\s+['"]([^'"]+)['"]/g,
+    /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+    /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  ];
+  for (const pattern of patterns) {
+    for (const match of content.matchAll(pattern)) {
+      imports.push(match[1]);
+    }
+  }
+  return uniqueSorted(imports).slice(0, 12);
+}
+
+function extractExportNames(content) {
+  const exports = [];
+  const patterns = [
+    /\bexport\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/g,
+    /\bexport\s+(?:const|let|var|class)\s+([A-Za-z0-9_$]+)/g,
+    /\bexport\s+default\s+(?:function\s+)?([A-Za-z0-9_$]+)?/g,
+  ];
+  for (const pattern of patterns) {
+    for (const match of content.matchAll(pattern)) {
+      exports.push(match[1] || 'default');
+    }
+  }
+  return uniqueSorted(exports).slice(0, 12);
+}
+
+function isRoutePath(filePath) {
+  return /(^|\/)(routes?|controllers?|pages\/api|app\/api)(\/|$)/i.test(filePath)
+    || /(^|\/)app\/.+\/(page|route)\.[jt]sx?$/i.test(filePath)
+    || /(^|\/)pages\/.+\.[jt]sx?$/i.test(filePath);
+}
+
+function isComponentPath(filePath) {
+  const basename = path.posix.basename(filePath).replace(/\.[^.]+$/, '');
+  return /(^|\/)components?\//i.test(filePath) || /^[A-Z][A-Za-z0-9]+$/.test(basename);
+}
+
+function isContextPath(filePath) {
+  return /(^|\/)(contexts?|providers?)\//i.test(filePath) || /(?:context|provider)\.[jt]sx?$/i.test(filePath);
+}
+
+function buildStructuralMap(repoRoot, files, detected) {
+  const warnings = [];
+  const routeFiles = [];
+  const componentFiles = [];
+  const contextFiles = [];
+  const importEntries = [];
+  const exportEntries = [];
+  let scannedFiles = 0;
+
+  for (const file of files.slice().sort((a, b) => a.path.localeCompare(b.path))) {
+    if (isRoutePath(file.path)) routeFiles.push(file.path);
+    if (isComponentPath(file.path)) componentFiles.push(file.path);
+    if (isContextPath(file.path)) contextFiles.push(file.path);
+
+    const extension = path.extname(file.path).toLowerCase();
+    if (!STRUCTURAL_TEXT_EXTENSIONS.has(extension)) {
+      continue;
+    }
+    if (scannedFiles >= MAX_STRUCTURAL_FILES) {
+      warnings.push({ path: file.path, issue: 'structural-file-budget-exhausted' });
+      continue;
+    }
+    if (file.bytes > MAX_STRUCTURAL_FILE_BYTES) {
+      warnings.push({ path: file.path, issue: 'structural-file-too-large' });
+      continue;
+    }
+
+    try {
+      const content = fs.readFileSync(path.join(repoRoot, file.path), 'utf8');
+      const imports = extractImportSpecifiers(content);
+      const exports = extractExportNames(content);
+      if (imports.length > 0) {
+        importEntries.push({ path: file.path, imports });
+      }
+      if (exports.length > 0) {
+        exportEntries.push({ path: file.path, exports });
+      }
+      scannedFiles += 1;
+    } catch (error) {
+      warnings.push({ path: file.path, issue: error.code || 'structural-read-failed' });
+    }
+  }
+
+  return {
+    schema_version: 1,
+    files_scanned: scannedFiles,
+    files_considered: files.length,
+    warnings: warnings.slice(0, 40),
+    routes: uniqueSorted(routeFiles).slice(0, 80),
+    components: uniqueSorted(componentFiles).slice(0, 80),
+    contexts: uniqueSorted(contextFiles).slice(0, 40),
+    configs: (detected.configs || []).slice(0, 80),
+    scripts: Object.keys(detected.scripts || {}).sort(),
+    imports: importEntries.slice(0, 80),
+    exports: exportEntries.slice(0, 80),
+  };
+}
+
 function discoverProjectFiles(repoRoot, options = {}) {
   const resolvedRepoRoot = path.resolve(repoRoot);
   const workspaceRoots = discoverWorkspaceRoots(resolvedRepoRoot);
   const analysisRoot = resolveAnalysisRoot(resolvedRepoRoot, options.scope, workspaceRoots);
   const walked = walkFiles(resolvedRepoRoot, analysisRoot.absolutePath);
   const packageJson = readPackageJson(resolvedRepoRoot);
+  const detected = detectStack(resolvedRepoRoot, walked.files);
+  detected.lockfiles = summarizeLockfiles(resolvedRepoRoot, walked.files);
+  detected.structural_map = buildStructuralMap(resolvedRepoRoot, walked.files, detected);
 
   return {
     project: {
@@ -376,7 +587,7 @@ function discoverProjectFiles(repoRoot, options = {}) {
     skippedSummary: summarizeByReason(walked.skipped),
     safetyExclusions: walked.safetyExclusions,
     safetySummary: summarizeByReason(walked.safetyExclusions),
-    detected: detectStack(resolvedRepoRoot, walked.files),
+    detected,
   };
 }
 

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

@@ -329,7 +329,9 @@ function writeAnalyzeProjectDocs(writePlan) {
       continue;
     }
     fs.mkdirSync(path.dirname(item.destinationPath), { recursive: true });
-    fs.writeFileSync(item.destinationPath, item.proposedContent);
+    const tempPath = `${item.destinationPath}.quiver-tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tempPath, item.proposedContent);
+    fs.renameSync(tempPath, item.destinationPath);
     writtenDocs.push(item.path);
   }
   return writtenDocs;