contextforge-cli-ai-prompt-pirates 0.4.0

package/src/generators/context-markdown.js

@@ -0,0 +1,571 @@
+import fs from 'fs-extra';
+import { getOutputPath, OUTPUT_FILES } from '../core/paths.js';
+import { renderTreeAscii } from '../analyzers/folder-tree.js';
+import { confidenceBadge } from '../core/confidence.js';
+import { buildMermaidDiagrams, wrapMermaid } from './mermaid.js';
+
+function joinSection(title, lines) {
+  const body = lines.filter((l) => l !== null && l !== undefined && l !== '').join('\n');
+  if (!body.trim()) return '';
+  return `## ${title}\n\n${body}\n\n`;
+}
+
+function bullets(items, empty = '_None detected_') {
+  if (!items?.length) return empty;
+  return items.map((i) => `- ${i}`).join('\n');
+}
+
+/**
+ * Detailed context.md aligned with requirements §7.9 and §8.
+ */
+export async function renderContextMarkdown(projectRoot, snapshot) {
+  const ts = snapshot.techStack;
+  const arch = snapshot.architecture;
+  const db = snapshot.database;
+  const auth = snapshot.authDeploy;
+  const git = snapshot.git;
+  const bugs = snapshot.bugs;
+  const deps = snapshot.dependencies;
+  const code = snapshot.codeInsights;
+  const conf = snapshot.confidence || {};
+  const meta = snapshot.projectMeta;
+  const mermaid = buildMermaidDiagrams(snapshot);
+
+  const treeAscii = renderTreeAscii(snapshot.folderTree, '', true, 0, snapshot.config?.maxTreeDepth || 4);
+
+  const frontendLine = formatStackLine(ts.frontend, ts.styling);
+  const backendLine = formatStackLine(ts.backend, ts.http);
+  const databaseLine = formatStackLine([...ts.database, ...ts.orm]);
+  const stateLine = ts.state?.length ? bullets(ts.state) : null;
+  const authLine = formatStackLine(auth.authentication.length ? auth.authentication : ts.auth);
+  const deployLine = formatStackLine(auth.deployment.length ? auth.deployment : ts.deploy);
+
+  let md = `# Project Context
+
+> **ContextForge** — AI-ready repository memory  
+> Generated: ${snapshot.generatedAt}  
+> Project: **${snapshot.projectName}**  
+> Use with ChatGPT, Claude, Cursor, GitHub Copilot
+
+---
+
+`;
+
+  md += joinSection('Project Overview', [
+    snapshot.description ? `**Description:** ${snapshot.description}` : null,
+    `**Root:** \`${snapshot.projectRoot}\``,
+    meta?.packageVersion ? `**Version:** ${meta.packageVersion}` : null,
+    meta?.engines ? `**Engines:** ${meta.engines}` : null,
+    meta?.workspaces ? `**Workspaces:** ${meta.workspaces}` : null,
+    `**Files scanned:** ${snapshot.filesScanned}`,
+    `**Detection confidence:** ${ts.confidence}`,
+    conf.overall ? `**Overall accuracy:** ${confidenceBadge(conf.overall)}` : null,
+    code?.projectStructure?.length
+      ? `**Key directories:** ${code.projectStructure.join(', ')}`
+      : snapshot.projectDirs?.length
+        ? `**Detected dirs:** ${snapshot.projectDirs.join(', ')}`
+        : null,
+    code?.summary ? `\n${code.summary}` : null,
+  ]);
+
+  md += renderDetectionReliability(snapshot.detectionQuality, ts);
+  md += renderQuickReference(snapshot);
+  md += renderProjectStatistics(code, snapshot.ast);
+  md += renderTechStackDetailed(ts);
+
+  if (snapshot.changelog) {
+    const ch = snapshot.changelog;
+    md += joinSection('What Changed Since Last Run', [
+      `**Last run:** ${ch.runAt}`,
+      ch.previousRunAt ? `**Previous run:** ${ch.previousRunAt}` : null,
+      `**Status:** ${ch.hasChanges ? 'Changes detected' : 'No changes'}`,
+      ch.summary,
+      ch.addedFiles?.length
+        ? `**New files (${ch.addedFiles.length}):** ${ch.addedFiles.slice(0, 8).map((f) => `\`${f}\``).join(', ')}${ch.addedFiles.length > 8 ? '...' : ''}`
+        : null,
+      ch.modifiedFiles?.length
+        ? `**Modified (${ch.modifiedFiles.length}):** ${ch.modifiedFiles.slice(0, 8).map((f) => `\`${f}\``).join(', ')}${ch.modifiedFiles.length > 8 ? '...' : ''}`
+        : null,
+      ch.removedFiles?.length
+        ? `**Removed (${ch.removedFiles.length}):** ${ch.removedFiles.slice(0, 5).map((f) => `\`${f}\``).join(', ')}`
+        : null,
+      ch.techStackChanged?.length ? bullets(ch.techStackChanged) : null,
+      ch.architectureChanged ? `**Architecture:** ${ch.architectureChanged}` : null,
+      '_See `.contextforge/CHANGES.md` for full history._',
+    ]);
+  }
+
+  if (conf.overall) {
+    md += joinSection('Accuracy Confidence', [
+      `| Area | Confidence |`,
+      `|------|------------|`,
+      `| Tech stack | ${confidenceBadge(conf.techStack)} |`,
+      `| Architecture | ${confidenceBadge(conf.architecture)} |`,
+      `| Database | ${confidenceBadge(conf.database)} |`,
+      `| API routes | ${confidenceBadge(conf.apiRoutes)} |`,
+      `| Git history | ${confidenceBadge(conf.git)} |`,
+      `| Issues detected | ${confidenceBadge(conf.bugs)} |`,
+      `| **Overall** | **${confidenceBadge(conf.overall)}** |`,
+    ]);
+  }
+
+  md += renderAiEnrichmentSections(snapshot.aiEnrichment);
+
+  md += joinSection('Frontend', [
+    frontendLine || '_No frontend framework detected from dependencies._',
+    ts.styling?.length ? `**Styling:** ${ts.styling.join(', ')}` : null,
+  ]);
+
+  md += joinSection('Backend', [
+    backendLine || '_No backend framework detected._',
+    ts.http?.length ? `**HTTP client:** ${ts.http.join(', ')}` : null,
+  ]);
+
+  md += joinSection('Database', [
+    databaseLine || '_No database/ORM detected._',
+    db.provider ? `**Provider:** ${db.provider}` : null,
+    db.migrations?.length ? `**Migrations path:** ${db.migrations.slice(0, 3).join(', ')}` : null,
+  ]);
+
+  if (stateLine) {
+    md += joinSection('State Management', [stateLine]);
+  }
+
+  if (ts.testing?.length) {
+    md += joinSection('Testing', [bullets(ts.testing)]);
+  }
+
+  md += joinSection('Architecture', [
+    `**Pattern:** ${arch.primary.displayLabel} (${arch.primary.confidence} confidence)`,
+    arch.allMatches.length > 1
+      ? `**Also matches:** ${arch.allMatches.map((m) => m.label).join(', ')}`
+      : null,
+    arch.folderHierarchy?.length
+      ? `**Top-level layout:** ${arch.folderHierarchy.slice(0, 12).join(', ')}`
+      : null,
+    mermaid.architectureFlow ? wrapMermaid(mermaid.architectureFlow) : null,
+  ]);
+
+  md += joinSection('API Flow', [
+    arch.apiFlow ? `**Primary flow:** ${arch.apiFlow}` : null,
+    arch.dependencyFlow ? `**Dependency flow:** ${arch.dependencyFlow}` : null,
+    code?.pipelineFlow ? `**Inferred pipeline:** ${code.pipelineFlow}` : null,
+    renderRoutesTable(code?.apiEndpoints, snapshot.ast?.routes),
+  ]);
+
+  if (code?.modules?.middleware?.length) {
+    md += joinSection('Middleware', [
+      bullets(
+        code.modules.middleware.map((m) => `\`${m.file}\`${m.name ? ` — ${m.name}` : ''}`)
+      ),
+    ]);
+  }
+
+  if (code?.modules?.components?.length) {
+    md += joinSection('UI Components', [
+      ...code.modules.components.slice(0, 15).map((c) => {
+        const names = c.components?.length ? ` (${c.components.join(', ')})` : '';
+        return `- \`${c.file}\`${names}`;
+      }),
+    ]);
+  }
+
+  if (meta?.scripts?.length) {
+    md += joinSection('npm Scripts & Commands', [
+      '| Script | Command |',
+      '|--------|---------|',
+      ...meta.scripts.map((s) => `| \`${s.name}\` | \`${s.command.replace(/\|/g, '\\|')}\` |`),
+      '',
+      '_Run these from the project root._',
+    ]);
+  }
+
+  if (meta?.entryPoints?.length) {
+    md += joinSection('Entry Points', [
+      bullets(
+        meta.entryPoints.map(
+          (e) => `**${e.type}**${e.name ? ` (${e.name})` : ''}: \`${e.path}\``
+        )
+      ),
+    ]);
+  }
+
+  if (meta?.envVarNames?.length) {
+    md += joinSection('Environment Variables', [
+      '_Variable names from `.env.example` (values are never read)._',
+      '',
+      bullets(meta.envVarNames.map((k) => `\`${k}\``)),
+    ]);
+  }
+
+  if (meta?.dependenciesSummary?.production > 0) {
+    md += joinSection('Dependencies Overview', [
+      `**Production:** ${meta.dependenciesSummary.production} packages`,
+      `**Development:** ${meta.dependenciesSummary.development} packages`,
+      meta.dependenciesSummary.topProduction?.length
+        ? `**Key production deps:** ${meta.dependenciesSummary.topProduction.join(', ')}`
+        : null,
+    ]);
+  }
+
+  md += joinSection('Folder Structure', [
+    treeAscii ? `\`\`\`\n${treeAscii}\n\`\`\`` : '_No folder tree available._',
+  ]);
+
+  if (db.models?.length) {
+    md += joinSection('Database Schemas', [
+      db.orm ? `**ORM:** ${db.orm}` : null,
+      db.enums?.length ? `**Enums:** ${db.enums.join(', ')}` : null,
+      '**Entity diagram:**',
+      '```',
+      db.textDiagram || '(see models in schema files)',
+      '```',
+      ...db.models.slice(0, 8).map((m) => {
+        const rel = m.relations?.length ? ` → relates to: ${m.relations.join(', ')}` : '';
+        return `- **${m.name}**: ${(m.fields || []).join(', ')}${rel}`;
+      }),
+      mermaid.databaseEr ? wrapMermaid(mermaid.databaseEr) : null,
+    ]);
+  }
+
+  md += joinSection('Authentication', [
+    authLine || '_No auth library detected._',
+    auth.hints?.length ? bullets(auth.hints) : null,
+  ]);
+
+  md += joinSection('Deployment', [
+    deployLine || '_No deployment platform detected._',
+    snapshot.configFiles?.filter((p) => /docker|vercel|netlify|nginx/i.test(p)).length
+      ? `**Config:** ${snapshot.configFiles.filter((p) => /docker|vercel|netlify|nginx/i.test(p)).join(', ')}`
+      : null,
+  ]);
+
+  md += joinSection('Business Logic Summary', [
+    code?.summary || '_No dedicated business-logic layer identified._',
+    code?.modules?.services?.length
+      ? `**Services (${code.modules.services.length}):** ${code.modules.services.slice(0, 8).map((s) => `\`${s.file}\``).join(', ')}`
+      : null,
+    code?.modules?.controllers?.length
+      ? `**Controllers (${code.modules.controllers.length}):** ${code.modules.controllers.slice(0, 6).map((c) => `\`${c.file}\``).join(', ')}`
+      : null,
+    code?.businessLogic?.length
+      ? [
+          '**Exported service functions:**',
+          bullets(code.businessLogic.slice(0, 12).map((b) => `${b.name} (\`${b.file}\`)`)),
+        ].join('\n')
+      : null,
+  ]);
+
+  md += joinSection('Dependency Relationships', [
+    deps?.summary || null,
+    deps?.chains?.length
+      ? ['**Inferred chains:**', bullets(deps.chains)].join('\n')
+      : null,
+    deps?.flowHints?.length ? bullets(deps.flowHints) : null,
+    deps?.edges?.length
+      ? [
+          '**Sample import graph:**',
+          ...deps.edges.slice(0, 8).map(
+            (e) => `- \`${e.file}\`${e.role ? ` (${e.role})` : ''} → ${e.imports.slice(0, 4).join(', ')}`
+          ),
+        ].join('\n')
+      : null,
+  ]);
+
+  if (git.available || git.insights?.length) {
+    md += joinSection('Git Intelligence', [
+      git.branch ? `**Current branch:** ${git.branch}` : null,
+      git.narratives?.length
+        ? ['**Timeline insights:**', bullets(git.narratives)].join('\n')
+        : null,
+      git.insights?.length ? bullets(git.insights) : null,
+      git.packageChanges ? `- ${git.packageChanges}` : null,
+      git.timeline?.length
+        ? [
+            '**Recent timeline:**',
+            '',
+            '| Date | Event |',
+            '|------|-------|',
+            ...git.timeline.map((t) => `| ${t.date} | ${t.event.replace(/\|/g, '/')} |`),
+          ].join('\n')
+        : null,
+      git.commits?.length
+        ? [
+            '**Recent commits:**',
+            '',
+            '| Commit | Date | Author | Message |',
+            '|--------|------|--------|---------|',
+            ...git.commits.slice(0, 12).map(
+              (c) =>
+                `| ${c.hash} | ${c.date?.slice(0, 10) || ''} | ${c.author} | ${c.message.replace(/\|/g, '/').slice(0, 55)} |`
+            ),
+          ].join('\n')
+        : null,
+    ]);
+  }
+
+  md += joinSection('Possible Issues', [
+    bugs.summary,
+    bugs.issues?.length
+      ? bugs.issues.map((i) => `- **[${i.severity}]** ${i.message} — \`${i.file}\``).join('\n')
+      : '- No issues flagged by static heuristics.',
+  ]);
+
+  md += joinSection('Suggested Improvements', [
+    bullets(generateSuggestions(snapshot)),
+  ]);
+
+  const standards = [];
+  if (snapshot.configFiles?.some((p) => /eslint/i.test(p))) {
+    standards.push('ESLint is configured — run linter before commits');
+  }
+  if (snapshot.configFiles?.some((p) => /prettier/i.test(p))) {
+    standards.push('Prettier is configured — match existing formatting');
+  }
+  if (ts.confidence === 'high') {
+    standards.push('Tech stack detected from package.json — prefer existing libraries over new deps');
+  }
+  if (code?.fileStats?.services) {
+    standards.push('Place reusable logic in services/, not routes or controllers');
+  }
+  if (standards.length) {
+    md += joinSection('Coding Standards', [bullets(standards)]);
+  }
+
+  if (code?.patterns?.length) {
+    md += joinSection('Code Patterns Detected', [bullets(code.patterns)]);
+  }
+
+  if (code?.importantRules?.length) {
+    md += joinSection('Important Rules', [bullets(code.importantRules)]);
+  }
+
+  if (snapshot.configFiles?.length) {
+    md += joinSection('Key Config Files', [
+      bullets(snapshot.configFiles.slice(0, 25)),
+      '',
+      '_Sensitive files (.env, keys) are never read by ContextForge._',
+    ]);
+  }
+
+  md += `---
+
+## How to Use This File
+
+1. Add to **Cursor rules**: _Read \`.contextforge/context.md\` before coding._  
+2. Run \`npx contextforge prompt\` to paste into any AI chat.  
+3. Regenerate: \`npx contextforge generate\` or \`npx contextforge watch\`
+
+`;
+
+  await fs.writeFile(getOutputPath(projectRoot, OUTPUT_FILES.contextMd), md, 'utf8');
+  return md;
+}
+
+function renderAiEnrichmentSections(ai) {
+  if (!ai?.sections) return '';
+
+  const s = ai.sections;
+  const header = `*Enriched by **${ai.provider}** (\`${ai.model}\`) at ${ai.generatedAt}*`;
+
+  let out = `## AI-Enhanced Analysis\n\n${header}\n\n`;
+
+  const blocks = [
+    ['Executive Summary', s.executiveSummary],
+    ['Tech Stack (AI Narrative)', s.techStackNarrative],
+    ['Architecture Deep Dive', s.architectureDeepDive],
+    ['API & Data Flow', s.apiAndDataFlow],
+    ['Business Logic Analysis', s.businessLogicAnalysis],
+    ['Database Analysis', s.databaseAnalysis],
+    ['Authentication Notes', s.authenticationNotes],
+    ['Deployment Notes', s.deploymentNotes],
+    ['Git Evolution', s.gitEvolution],
+    ['AI — Important Rules', Array.isArray(s.importantRules) ? bullets(s.importantRules) : s.importantRules],
+    ['AI — Coding Conventions', Array.isArray(s.codingConventions) ? bullets(s.codingConventions) : s.codingConventions],
+    ['AI — Possible Issues', Array.isArray(s.possibleIssues) ? bullets(s.possibleIssues) : s.possibleIssues],
+    ['AI — Suggested Improvements', Array.isArray(s.suggestedImprovements) ? bullets(s.suggestedImprovements) : s.suggestedImprovements],
+  ];
+
+  for (const [title, body] of blocks) {
+    if (body && String(body).trim()) {
+      out += joinSection(title, [typeof body === 'string' ? body : body]);
+    }
+  }
+
+  return out;
+}
+
+function renderDetectionReliability(quality, ts) {
+  if (!quality) return '';
+
+  const lines = [
+    `**Detection score:** ${quality.score}/100 (${quality.grade} reliability)`,
+    quality.summary,
+    ts.packageJsonCount > 1
+      ? `**Monorepo:** ${ts.packageJsonCount} package.json file(s) merged for stack detection`
+      : '_Single package.json used for dependency detection._',
+    quality.reliableForAi
+      ? '✓ **Suitable for AI context** — scan evidence is consistent.'
+      : '⚠ **Verify manually** — some sections may be incomplete before trusting AI output.',
+  ];
+
+  if (quality.strengths?.length) {
+    lines.push('', '**What was detected reliably:**', bullets(quality.strengths));
+  }
+  if (quality.warnings?.length) {
+    lines.push('', '**Verify or improve:**', bullets(quality.warnings));
+  }
+
+  lines.push(
+    '',
+    '_Accuracy depends on: `package.json`, folder layout, model/schema files, and route parsing. Re-run `generate` after changing stack._'
+  );
+
+  return joinSection('Detection Reliability (read this first)', lines);
+}
+
+function renderQuickReference(snapshot) {
+  const ts = snapshot.techStack;
+  const arch = snapshot.architecture;
+  const db = snapshot.database;
+  const auth = snapshot.authDeploy;
+
+  const rows = [
+    ['Frontend', [...(ts.frontend || []), ...(ts.styling || [])].join(', ') || '—'],
+    ['Backend', (ts.backend || []).join(', ') || '—'],
+    ['Database / ORM', [...(ts.database || []), ...(ts.orm || [])].join(', ') || '—'],
+    ['State', (ts.state || []).join(', ') || '—'],
+    [
+      'Auth',
+      [...new Set([...(auth.authentication || []), ...(ts.auth || [])])].join(', ') || '—',
+    ],
+    ['Deploy', [...(auth.deployment || []), ...(ts.deploy || [])].join(', ') || '—'],
+    ['Architecture', arch?.primary?.label || '—'],
+    ['API style', arch?.apiFlow || snapshot.codeInsights?.pipelineFlow || '—'],
+  ];
+
+  return joinSection('At a Glance (AI Quick Reference)', [
+    '_Copy this table into any AI chat for instant project context._',
+    '',
+    '| Area | Detected |',
+    '|------|----------|',
+    ...rows.map(([a, b]) => `| **${a}** | ${b} |`),
+  ]);
+}
+
+function renderProjectStatistics(code, ast) {
+  if (!code?.fileStats && !ast?.routesCount) return '';
+  const fs = code?.fileStats || {};
+  const rows = [
+    `| Metric | Count |`,
+    `|--------|-------|`,
+    fs.totalSource ? `| Source files analyzed | ${fs.totalSource} |` : null,
+    fs.routes ? `| Route modules | ${fs.routes} |` : null,
+    fs.services ? `| Service modules | ${fs.services} |` : null,
+    fs.components ? `| Component files | ${fs.components} |` : null,
+    ast?.filesParsed ? `| AST-parsed files | ${ast.filesParsed} |` : null,
+    ast?.routesCount ? `| Routes (AST) | ${ast.routesCount} |` : null,
+    code?.apiEndpoints?.length ? `| API endpoints (total) | ${code.apiEndpoints.length} |` : null,
+    code?.businessLogic?.length
+      ? `| Exported service functions | ${code.businessLogic.length} |`
+      : null,
+  ].filter(Boolean);
+  if (rows.length <= 2) return '';
+  return joinSection('Project Statistics', rows);
+}
+
+function renderTechStackDetailed(ts) {
+  const categories = [
+    ['Frontend', ts.frontend],
+    ['Backend', ts.backend],
+    ['Database', ts.database],
+    ['ORM', ts.orm],
+    ['Styling', ts.styling],
+    ['State', ts.state],
+    ['Testing', ts.testing],
+    ['Authentication', ts.auth],
+    ['HTTP client', ts.http],
+    ['Deployment', ts.deploy],
+  ];
+
+  const lines = [
+    '| Category | Technologies |',
+    '|----------|--------------|',
+    ...categories
+      .filter(([, items]) => items?.length)
+      .map(([cat, items]) => `| ${cat} | ${items.join(', ')} |`),
+  ];
+
+  if (lines.length <= 1) return '';
+
+  const signalBlock =
+    ts.signals?.length > 0
+      ? ['', '**Detection signals:**', bullets(ts.signals.slice(0, 15)), ts.signals.length > 15 ? '_…and more_' : null]
+      : [];
+
+  return joinSection('Tech Stack (Detailed)', [...lines, ...signalBlock.filter((x) => x != null)]);
+}
+
+function renderRoutesTable(endpoints = [], astRoutes = []) {
+  const merged = dedupeRoutesForTable(endpoints, astRoutes);
+  if (!merged.length) {
+    return '_No explicit HTTP routes parsed — may be CLI, library, or serverless._';
+  }
+  return [
+    '**Registered routes / handlers:**',
+    '',
+    '| Method | Path | File | Source |',
+    '|--------|------|------|--------|',
+    ...merged.slice(0, 30).map(
+      (e) =>
+        `| ${e.method} | ${e.path} | \`${e.file}\` | ${e.source || 'scan'} |`
+    ),
+    merged.length > 30 ? `\n_+ ${merged.length - 30} more routes not shown_` : null,
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+function dedupeRoutesForTable(endpoints, astRoutes) {
+  const list = [...(endpoints || [])];
+  for (const r of astRoutes || []) {
+    list.push({
+      method: r.method,
+      path: r.path,
+      file: r.file,
+      source: 'ast',
+    });
+  }
+  const seen = new Set();
+  return list.filter((e) => {
+    const key = `${e.method}:${e.path}:${e.file}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function formatStackLine(primary, extra = []) {
+  const all = [...(primary || []), ...(extra || [])];
+  const unique = [...new Set(all)];
+  return unique.length ? unique.join(' + ') : null;
+}
+
+function generateSuggestions(snapshot) {
+  const tips = [
+    'Keep controllers thin; business logic belongs in services',
+    'Use consistent validation (Zod/Joi) at API boundaries',
+    'Reference this file in AI sessions to avoid re-explaining the stack',
+  ];
+  const ts = snapshot.techStack;
+  if (ts.confidence === 'low') {
+    tips.push('Add explicit dependencies to package.json for richer detection');
+  }
+  if (!snapshot.database?.models?.length && (ts.database.length || ts.orm.length)) {
+    tips.push('Add schema.prisma or model files for database section accuracy');
+  }
+  if (snapshot.bugs?.issues?.some((i) => i.severity === 'high')) {
+    tips.push('Review high-severity issues in Possible Issues section first');
+  }
+  return tips;
+}

package/src/generators/mermaid.js

@@ -0,0 +1,59 @@
+/**
+ * Generate Mermaid diagrams for context.md.
+ * @param {object} snapshot
+ */
+export function buildMermaidDiagrams(snapshot) {
+  const diagrams = {};
+
+  diagrams.architectureFlow = buildArchitectureMermaid(snapshot);
+  diagrams.databaseEr = buildDatabaseMermaid(snapshot);
+
+  return diagrams;
+}
+
+function buildArchitectureMermaid(snapshot) {
+  const flow = snapshot.architecture?.apiFlow;
+  if (!flow) return null;
+
+  if (flow.includes('→')) {
+    const steps = flow.split('→').map((s) => s.trim()).filter(Boolean);
+    if (steps.length < 2) return null;
+    let chart = 'flowchart LR\n';
+    steps.forEach((step, i) => {
+      const id = `n${i}`;
+      const label = step.replace(/[^\w\s/-]/g, '').slice(0, 40);
+      chart += `  ${id}["${label}"]\n`;
+      if (i > 0) chart += `  n${i - 1} --> ${id}\n`;
+    });
+    return chart;
+  }
+
+  return null;
+}
+
+function buildDatabaseMermaid(snapshot) {
+  const models = snapshot.database?.models;
+  if (!models?.length) return null;
+
+  let er = 'erDiagram\n';
+  for (const m of models.slice(0, 8)) {
+    const name = m.name || 'Entity';
+    er += `  ${name} {\n`;
+    const fields = (m.fields || []).slice(0, 6);
+    for (const f of fields) {
+      er += `    string ${f}\n`;
+    }
+    er += `  }\n`;
+    if (m.relations?.length) {
+      for (const rel of m.relations.slice(0, 3)) {
+        er += `  ${name} ||--o{ ${rel} : has\n`;
+      }
+    }
+  }
+  return er;
+}
+
+export function wrapMermaid(code) {
+  if (!code) return '';
+  return `\`\`\`mermaid\n${code.trim()}\n\`\`\``;
+}

package/src/index.js

@@ -0,0 +1,13 @@
+export { runPipeline } from './core/pipeline.js';
+export {
+  loadConfig,
+  writeDefaultConfig,
+  syncConfigFile,
+  isInitialized,
+  DEFAULT_CONFIG,
+} from './core/config.js';
+export { detectFileChanges } from './scanner/change-detector.js';
+export { detectTechStack } from './detectors/tech-stack.js';
+export { analyzeArchitecture } from './detectors/architecture.js';
+export { scanRepository } from './scanner/repo-scanner.js';
+export { enrichWithAI, isAiAvailable, scheduleBackgroundEnrichment } from './services/ai/index.js';

package/src/scanner/change-detector.js

@@ -0,0 +1,24 @@
+import { scanRepository } from './repo-scanner.js';
+import { loadFileIndex } from './file-index.js';
+import { computeFileDiff } from '../analyzers/changelog.js';
+
+/**
+ * Quick check: did any tracked file content change since last run?
+ * @param {string} projectRoot
+ * @param {object} config
+ */
+export async function detectFileChanges(projectRoot, config) {
+  const scanResult = await scanRepository(projectRoot, config);
+  const previousIndex = await loadFileIndex(projectRoot);
+  const fileDiff = computeFileDiff(previousIndex, scanResult.files);
+  return {
+    hasChanges: fileDiff.hasFileChanges,
+    fileDiff,
+    scanResult,
+    counts: {
+      added: fileDiff.added.length,
+      modified: fileDiff.modified.length,
+      removed: fileDiff.removed.length,
+    },
+  };
+}