contextforge-cli-ai-prompt-pirates 0.4.0

package/src/analyzers/dependencies.js

@@ -0,0 +1,110 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+
+const IMPORT_RE = /(?:import\s+.*?\s+from\s+['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\))/g;
+
+/**
+ * Build import graph and dependency flow chains (§7.4).
+ */
+export function analyzeDependencies(projectRoot, scanResult, config, codeInsights = null) {
+  const graph = [];
+  const roleMap = new Map();
+
+  const sourceFiles = scanResult.relativePaths
+    .filter((p) => /\.(js|jsx|ts|tsx|mjs|cjs)$/.test(p))
+    .filter((p) => !p.includes('node_modules'))
+    .slice(0, 80);
+
+  for (const rel of sourceFiles) {
+    const full = path.join(projectRoot, rel);
+    try {
+      const content = fs.readFileSync(full, 'utf8');
+      const imports = [];
+      let m;
+      IMPORT_RE.lastIndex = 0;
+      while ((m = IMPORT_RE.exec(content)) !== null) {
+        const target = m[1] || m[2];
+        if (target.startsWith('.') || target.startsWith('@/')) {
+          imports.push(target);
+        }
+      }
+      const role = inferRole(rel);
+      if (role) roleMap.set(rel, role);
+
+      if (imports.length) {
+        graph.push({
+          file: rel,
+          role,
+          imports: [...new Set(imports)].slice(0, 12),
+        });
+      }
+    } catch {
+      /* skip */
+    }
+  }
+
+  const chains = buildDependencyChains(graph, roleMap, codeInsights);
+  const flowHints = [];
+
+  if (chains.length) {
+    flowHints.push(...chains.slice(0, 8));
+  }
+  if (graph.some((g) => g.file.includes('middleware'))) {
+    flowHints.push('Middleware → routes/controllers (cross-cutting layer)');
+  }
+  if (graph.some((g) => g.role === 'controller' && g.imports.some((i) => i.includes('service')))) {
+    flowHints.push('Controllers → Services (thin controller pattern)');
+  }
+  if (graph.some((g) => g.role === 'service' && g.imports.some((i) => i.includes('model')))) {
+    flowHints.push('Services → Models / data layer');
+  }
+
+  return {
+    sampleSize: sourceFiles.length,
+    edges: graph.slice(0, 50),
+    chains,
+    flowHints: [...new Set(flowHints)],
+    summary:
+      graph.length > 0
+        ? `Mapped ${graph.length} files with local imports; ${chains.length} dependency chain(s) inferred.`
+        : 'No local import graph extracted.',
+  };
+}
+
+function inferRole(filePath) {
+  if (/middleware/i.test(filePath)) return 'middleware';
+  if (/controllers?/i.test(filePath)) return 'controller';
+  if (/routes?/i.test(filePath)) return 'route';
+  if (/services?/i.test(filePath)) return 'service';
+  if (/models?/i.test(filePath)) return 'model';
+  if (/components?/i.test(filePath)) return 'component';
+  return null;
+}
+
+function buildDependencyChains(graph, roleMap, codeInsights) {
+  const chains = [];
+
+  const hasAuth = codeInsights?.modules?.middleware?.length ||
+    graph.some((g) => /auth|jwt|passport/i.test(g.file));
+  const hasJwt = graph.some((g) => /jwt|jsonwebtoken/i.test(JSON.stringify(g.imports)));
+
+  if (hasAuth && roleMap.has('middleware') || graph.some((g) => g.role === 'middleware')) {
+    chains.push('Request → Auth Middleware → Route → Controller → Service → Model/DB');
+  } else if (graph.some((g) => g.role === 'route' && graph.some((x) => x.role === 'controller'))) {
+    chains.push('Client → Route → Controller → Service → Database');
+  }
+
+  if (hasJwt) {
+    chains.push('AuthService → JWT → Middleware → UserModel');
+  }
+
+  const services = graph.filter((g) => g.role === 'service');
+  const controllers = graph.filter((g) => g.role === 'controller');
+  if (controllers.length && services.length) {
+    const ctrl = path.basename(controllers[0].file);
+    const svc = path.basename(services[0].file);
+    chains.push(`${ctrl} → ${svc} → data layer`);
+  }
+
+  return [...new Set(chains)];
+}

package/src/analyzers/detection-quality.js

@@ -0,0 +1,106 @@
+/**
+ * Cross-check scan results so context.md accuracy reflects real evidence.
+ * @param {object} snapshot
+ */
+export function assessDetectionQuality(snapshot) {
+  const ts = snapshot.techStack || {};
+  const code = snapshot.codeInsights || {};
+  const arch = snapshot.architecture;
+  const db = snapshot.database || {};
+  const warnings = [];
+  const strengths = [];
+  let score = 70;
+
+  const signalCount = ts.signals?.length || 0;
+  if (signalCount >= 5) {
+    strengths.push(`${signalCount} detection signals from package.json and config files`);
+    score += 10;
+  } else if (signalCount >= 1) {
+    strengths.push('Some stack signals detected from dependencies');
+  } else {
+    warnings.push('No dependency signals — add a package.json with dependencies');
+    score -= 25;
+  }
+
+  if (ts.confidence === 'high') {
+    strengths.push('Tech stack confidence: high (package.json + multiple categories)');
+    score += 5;
+  } else if (ts.confidence === 'low') {
+    warnings.push('Tech stack confidence is low — verify Frontend/Backend sections manually');
+    score -= 15;
+  }
+
+  const hasExpress = (ts.backend || []).some((b) => /express/i.test(b));
+  const hasRoutes = (code.apiEndpoints?.length || 0) > 0 || (snapshot.ast?.routesCount || 0) > 0;
+  if (hasExpress && !hasRoutes) {
+    warnings.push('Express detected but few routes found — check server/ or routes/ folders');
+    score -= 5;
+  } else if (hasExpress && hasRoutes) {
+    strengths.push('Backend framework matches detected API routes');
+    score += 5;
+  }
+
+  const hasOrmDep = (ts.orm || []).length || (ts.database || []).some((d) => /mongo|sql|prisma/i.test(d));
+  const hasModels = (db.models || []).length > 0;
+  if (hasOrmDep && !hasModels) {
+    warnings.push('Database library detected but no models/schemas parsed — add model files or schema.prisma');
+    score -= 8;
+  } else if (hasModels) {
+    strengths.push(`Database schemas parsed (${db.models.length} model(s))`);
+    score += 8;
+  }
+
+  const hasReact = (ts.frontend || []).some((f) => /react/i.test(f));
+  const hasComponents = (code.modules?.components?.length || 0) > 0;
+  if (hasReact && !hasComponents) {
+    warnings.push('React detected but no components/ folder — may be minimal UI or different structure');
+  } else if (hasReact && hasComponents) {
+    strengths.push('Frontend framework matches component files in tree');
+    score += 5;
+  }
+
+  if ((ts.auth || []).length && !code.modules?.middleware?.length) {
+    strengths.push('Auth libraries detected from dependencies');
+  }
+
+  if (arch?.primary?.confidence === 'high') {
+    strengths.push(`Architecture "${arch.primary.label}" matched with high confidence`);
+    score += 5;
+  } else if (arch?.primary?.confidence === 'low') {
+    warnings.push('Architecture pattern is uncertain — confirm MVC/layered/monolith manually');
+    score -= 5;
+  }
+
+  if (!snapshot.projectMeta?.scripts?.length) {
+    warnings.push('No npm scripts found — run init from project root with package.json');
+    score -= 5;
+  }
+
+  if (snapshot.filesScanned < 10) {
+    warnings.push('Very few files scanned — check .contextforge/config.json ignore list');
+    score -= 10;
+  } else if (snapshot.filesScanned >= 30) {
+    strengths.push(`${snapshot.filesScanned} files scanned for analysis`);
+    score += 5;
+  }
+
+  score = Math.max(0, Math.min(100, score));
+
+  let grade = 'medium';
+  if (score >= 80) grade = 'high';
+  else if (score < 55) grade = 'low';
+
+  return {
+    score,
+    grade,
+    strengths,
+    warnings,
+    reliableForAi: score >= 65 && signalCount >= 2,
+    summary:
+      grade === 'high'
+        ? 'Detection is strong — context.md should closely match this project.'
+        : grade === 'medium'
+          ? 'Detection is usable — verify sections marked with lower confidence.'
+          : 'Detection is weak — add package.json, standard folders, and run generate again.',
+  };
+}

package/src/analyzers/eslint-runner.js

@@ -0,0 +1,56 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+
+/**
+ * Run ESLint if available and configured in project.
+ * @param {string} projectRoot
+ * @param {string[]} relativePaths
+ */
+export async function runEslintIfAvailable(projectRoot, relativePaths) {
+  const eslintConfigs = relativePaths.filter(
+    (p) =>
+      /^\.eslintrc/i.test(path.basename(p)) ||
+      p.endsWith('eslint.config.js') ||
+      p.endsWith('eslint.config.mjs')
+  );
+
+  if (!eslintConfigs.length) {
+    return { ran: false, issues: [], summary: 'No ESLint config found' };
+  }
+
+  try {
+    const { ESLint } = await import('eslint');
+    const eslint = new ESLint({ cwd: projectRoot });
+    const results = await eslint.lintFiles(['**/*.{js,jsx,ts,tsx,mjs,cjs}']);
+
+    const issues = [];
+    for (const result of results) {
+      for (const msg of result.messages.slice(0, 5)) {
+        if (msg.severity >= 1) {
+          issues.push({
+            severity: msg.severity === 2 ? 'high' : 'medium',
+            type: 'eslint',
+            file: path.relative(projectRoot, result.filePath).replace(/\\/g, '/'),
+            message: `${msg.ruleId || 'eslint'}: ${msg.message} (line ${msg.line})`,
+            ruleId: msg.ruleId,
+          });
+        }
+      }
+    }
+
+    return {
+      ran: true,
+      issues: issues.slice(0, 30),
+      summary:
+        issues.length > 0
+          ? `ESLint found ${issues.length} issue(s)`
+          : 'ESLint passed with no issues in scanned files',
+    };
+  } catch (err) {
+    return {
+      ran: false,
+      issues: [],
+      summary: `ESLint not run: ${err.message?.split('\n')[0]}`,
+    };
+  }
+}

package/src/analyzers/folder-tree.js

@@ -0,0 +1,60 @@
+/**
+ * Build a nested tree object from relative paths (depth-limited).
+ * @param {string[]} relativePaths
+ * @param {number} maxDepth
+ */
+export function buildFolderTree(relativePaths, maxDepth = 4) {
+  const root = {};
+
+  const dirSet = new Set();
+  for (const p of relativePaths) {
+    const parts = p.replace(/\\/g, '/').split('/');
+    for (let i = 1; i < parts.length; i++) {
+      dirSet.add(parts.slice(0, i).join('/'));
+    }
+    if (parts.length === 1) {
+      root[p] = root[p] || null;
+    }
+  }
+
+  for (const dir of [...dirSet].sort()) {
+    const parts = dir.split('/');
+    if (parts.length > maxDepth) continue;
+
+    let node = root;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      if (!node[part]) {
+        node[part] = i === parts.length - 1 ? {} : {};
+      }
+      if (typeof node[part] === 'object' && node[part] !== null) {
+        node = node[part];
+      }
+    }
+  }
+
+  return root;
+}
+
+export function renderTreeAscii(node, prefix = '', isLast = true, depth = 0, maxDepth = 4) {
+  if (depth > maxDepth) return '';
+
+  const lines = [];
+  const entries = Object.keys(node).sort();
+
+  entries.forEach((key, index) => {
+    const last = index === entries.length - 1;
+    const connector = last ? '└── ' : '├── ';
+    lines.push(`${prefix}${connector}${key}`);
+
+    const child = node[key];
+    if (child && typeof child === 'object' && Object.keys(child).length > 0) {
+      const extension = last ? '    ' : '│   ';
+      lines.push(
+        renderTreeAscii(child, prefix + extension, last, depth + 1, maxDepth)
+      );
+    }
+  });
+
+  return lines.filter(Boolean).join('\n');
+}

package/src/analyzers/git-insights.js

@@ -0,0 +1,94 @@
+import simpleGit from 'simple-git';
+import fs from 'fs-extra';
+import path from 'node:path';
+
+const NARRATIVE_PATTERNS = [
+  { re: /redux\s*→\s*zustand|migrat.*zustand|zustand.*instead/i, text: 'Migrated Redux → Zustand (mentioned in commit history).' },
+  { re: /refactor.*(api|service|modular)/i, text: 'Refactored API into modular services architecture.' },
+  { re: /migrat/i, text: 'Architecture or schema migration activity in recent commits.' },
+  { re: /add.*(auth|jwt|oauth)/i, text: 'Authentication-related changes in project timeline.' },
+  { re: /docker|deploy|vercel|nginx/i, text: 'Deployment or infrastructure changes recorded.' },
+  { re: /prisma|schema|database/i, text: 'Database schema evolution in recent commits.' },
+  { re: /dependenc|bump|upgrade/i, text: 'Dependency upgrades in recent development.' },
+  { re: /fix.*(bug|memory|leak)/i, text: 'Bug or stability fixes in recent history.' },
+];
+
+/**
+ * @param {string} projectRoot
+ * @param {number} limit
+ */
+export async function collectGitInsights(projectRoot, limit = 20) {
+  const result = {
+    available: false,
+    commits: [],
+    insights: [],
+    narratives: [],
+    branch: null,
+    timeline: [],
+    packageChanges: null,
+  };
+
+  try {
+    const git = simpleGit(projectRoot);
+    const isRepo = await git.checkIsRepo();
+    if (!isRepo) {
+      result.insights.push('Not a git repository — git history skipped.');
+      return result;
+    }
+
+    result.available = true;
+    result.branch = (await git.branch()).current;
+
+    const log = await git.log({ maxCount: limit });
+    result.commits = log.all.map((c) => ({
+      hash: c.hash.slice(0, 7),
+      date: c.date,
+      author: c.author_name,
+      message: c.message,
+    }));
+
+    result.timeline = log.all.slice(0, 8).map((c) => ({
+      date: c.date?.slice(0, 10),
+      event: c.message.split('\n')[0].slice(0, 80),
+    }));
+
+    const messages = log.all.map((c) => c.message);
+    const narratives = [];
+    const insights = [];
+
+    for (const { re, text } of NARRATIVE_PATTERNS) {
+      if (messages.some((m) => re.test(m))) {
+        narratives.push(text);
+      }
+    }
+
+    try {
+      const pkgPath = path.join(projectRoot, 'package.json');
+      if (await fs.pathExists(pkgPath)) {
+        const diff = await git.diff(['HEAD~5', 'HEAD', '--', 'package.json']);
+        if (diff && diff.length > 50) {
+          result.packageChanges = 'package.json modified in last 5 commits';
+          insights.push('Recent dependency or script changes in package.json');
+        }
+      }
+    } catch {
+      /* optional */
+    }
+
+    if (narratives.length === 0 && log.all.length > 0) {
+      insights.push(`Analyzed ${log.all.length} recent commits on branch "${result.branch}".`);
+    }
+
+    result.narratives = narratives;
+    result.insights = [...narratives, ...insights];
+  } catch (err) {
+    const msg = err.message || String(err);
+    if (msg.includes('ENOENT') || msg.includes('git')) {
+      result.insights.push('Git not available in PATH — install Git to enable commit history and timeline.');
+    } else {
+      result.insights.push(`Git analysis unavailable: ${msg.split('\n')[0]}`);
+    }
+  }
+
+  return result;
+}

package/src/analyzers/project-meta.js

@@ -0,0 +1,98 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+
+const ENTRY_PATTERNS = [
+  /^server\/index\.(js|ts|mjs|cjs)$/i,
+  /^src\/index\.(js|ts|tsx|jsx)$/i,
+  /^src\/main\.(js|ts|tsx)$/i,
+  /^index\.(js|ts|mjs|cjs)$/i,
+  /^app\.(js|ts|tsx)$/i,
+  /^bin\/[^/]+\.(js|mjs)$/i,
+];
+
+/**
+ * Package scripts, entry points, env var names, workspaces — for detailed context.md.
+ * @param {string} projectRoot
+ * @param {object} configFiles
+ * @param {string[]} relativePaths
+ */
+export async function analyzeProjectMeta(projectRoot, configFiles, relativePaths) {
+  const pkg = configFiles.packageJson;
+  const meta = {
+    scripts: [],
+    engines: null,
+    workspaces: null,
+    packageVersion: null,
+    entryPoints: [],
+    envVarNames: [],
+    dependenciesSummary: { production: 0, development: 0, topProduction: [] },
+  };
+
+  if (pkg) {
+    meta.packageVersion = pkg.version || null;
+    if (pkg.engines) {
+      meta.engines = Object.entries(pkg.engines)
+        .map(([k, v]) => `${k} ${v}`)
+        .join(', ');
+    }
+    if (pkg.workspaces) {
+      meta.workspaces = Array.isArray(pkg.workspaces)
+        ? pkg.workspaces.join(', ')
+        : typeof pkg.workspaces === 'object'
+          ? JSON.stringify(pkg.workspaces)
+          : String(pkg.workspaces);
+    }
+    if (pkg.scripts) {
+      meta.scripts = Object.entries(pkg.scripts).map(([name, cmd]) => ({
+        name,
+        command: String(cmd),
+      }));
+    }
+    const prod = Object.keys(pkg.dependencies || {});
+    const dev = Object.keys(pkg.devDependencies || {});
+    meta.dependenciesSummary = {
+      production: prod.length,
+      development: dev.length,
+      topProduction: prod.slice(0, 20),
+    };
+    if (pkg.main) meta.entryPoints.push({ type: 'main', path: pkg.main });
+    if (pkg.bin) {
+      const bins =
+        typeof pkg.bin === 'string'
+          ? [{ name: pkg.name || 'cli', path: pkg.bin }]
+          : Object.entries(pkg.bin).map(([name, p]) => ({ name, path: p }));
+      meta.entryPoints.push(...bins.map((b) => ({ type: 'bin', ...b })));
+    }
+  }
+
+  for (const rel of relativePaths) {
+    if (ENTRY_PATTERNS.some((re) => re.test(rel))) {
+      if (!meta.entryPoints.some((e) => e.path === rel)) {
+        meta.entryPoints.push({ type: 'detected', path: rel });
+      }
+    }
+  }
+
+  const envExamplePath = path.join(projectRoot, '.env.example');
+  if (await fs.pathExists(envExamplePath)) {
+    try {
+      const content = await fs.readFile(envExamplePath, 'utf8');
+      meta.envVarNames = parseEnvKeys(content);
+    } catch {
+      /* skip */
+    }
+  }
+
+  return meta;
+}
+
+function parseEnvKeys(content) {
+  const keys = [];
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const m = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)=/);
+    if (m) keys.push(m[1]);
+  }
+  return [...new Set(keys)].slice(0, 40);
+}

package/src/cli/commands/changes.js

@@ -0,0 +1,36 @@
+import { loadChangesHistory } from '../../analyzers/changelog.js';
+import { isInitialized } from '../../core/config.js';
+import path from 'node:path';
+import { getContextForgeRoot } from '../../core/paths.js';
+import fs from 'fs-extra';
+
+export async function changesCommand(projectRoot, options = {}) {
+  if (!(await isInitialized(projectRoot))) {
+    console.error('ContextForge not initialized. Run: npx contextforge init');
+    process.exit(1);
+  }
+
+  const limit = options.limit || 10;
+  const history = await loadChangesHistory(projectRoot, limit);
+  const changesMd = path.join(getContextForgeRoot(projectRoot), 'CHANGES.md');
+
+  console.log('\nContextForge — Change history\n');
+
+  if (history.runs.length === 0) {
+    console.log('  No runs recorded yet. Run: npx contextforge generate');
+    return;
+  }
+
+  for (const run of history.runs) {
+    const when = run.runAt?.slice(0, 19).replace('T', ' ') || '?';
+    const icon = run.hasChanges ? '~' : '=';
+    console.log(`  ${icon} ${when}  ${run.summary}`);
+    if (run.added || run.modified || run.removed) {
+      console.log(`      files: +${run.added} ~${run.modified} -${run.removed}`);
+    }
+  }
+
+  if (await fs.pathExists(changesMd)) {
+    console.log(`\n  Full log: .contextforge/CHANGES.md\n`);
+  }
+}