docguard-cli 0.10.0 → 0.11.1

package/cli/scanners/integrations.mjs

@@ -0,0 +1,116 @@
+/**
+ * External Integrations Scanner — what third-party services does this project talk to?
+ *
+ * Recognizes common SDKs/clients across all detected ecosystems (JS/TS, Python,
+ * Rust, Go, Java, Ruby, PHP, .NET) by name-matching dependencies against a
+ * curated registry. Output is the project's external-system surface — the kind
+ * of "this integrates with AWS S3, Stripe, OpenAI, Sentry" facts the AI agent
+ * uses to write INTEGRATIONS.md.
+ *
+ * Deterministic facts; the agent narrates. Zero NPM dependencies.
+ */
+
+import { detectEcosystems } from './project-type.mjs';
+
+/**
+ * Registry of integrations. Each entry: a category label + name patterns to
+ * match against dependency keys (substring, lowercased). Add new SDKs here.
+ */
+const REGISTRY = [
+  // ── Cloud ──
+  { name: 'AWS', category: 'Cloud', patterns: ['@aws-sdk/', 'aws-sdk', 'boto3', 'aws-sdk-go', 'aws-sdk-rust', 'aws.sdk', 'amazon-aws'] },
+  { name: 'Google Cloud', category: 'Cloud', patterns: ['@google-cloud/', 'google-cloud-', 'gcloud'] },
+  { name: 'Azure', category: 'Cloud', patterns: ['@azure/', 'azure-', 'azure.sdk'] },
+  { name: 'Cloudflare', category: 'Cloud', patterns: ['cloudflare', 'wrangler', '@cloudflare/'] },
+  { name: 'Vercel', category: 'Cloud', patterns: ['@vercel/', 'vercel/'] },
+  // ── Databases / storage ──
+  { name: 'PostgreSQL', category: 'Database', patterns: ['pg', '@neondatabase/serverless', 'postgres', 'psycopg', 'sqlx', 'lib/pq'] },
+  { name: 'MySQL',      category: 'Database', patterns: ['mysql2', 'mysql-connector', 'pymysql'] },
+  { name: 'MongoDB',    category: 'Database', patterns: ['mongoose', 'mongodb', 'pymongo'] },
+  { name: 'DynamoDB',   category: 'Database', patterns: ['@aws-sdk/client-dynamodb', 'aws-sdk/dynamodb', 'boto3.dynamodb'] },
+  { name: 'Redis',      category: 'Database', patterns: ['redis', 'ioredis', 'redis-rs', 'go-redis'] },
+  { name: 'Supabase',   category: 'Database', patterns: ['@supabase/', 'supabase-py', 'supabase-go'] },
+  { name: 'Firebase',   category: 'Database', patterns: ['firebase', '@firebase/', 'firebase-admin', 'pyrebase'] },
+  // ── Payments ──
+  { name: 'Stripe',     category: 'Payments', patterns: ['stripe', '@stripe/', 'stripe-go', 'stripe-java'] },
+  { name: 'Braintree',  category: 'Payments', patterns: ['braintree'] },
+  { name: 'PayPal',     category: 'Payments', patterns: ['@paypal/', 'paypal-checkout'] },
+  // ── Auth ──
+  { name: 'Auth0',      category: 'Auth', patterns: ['@auth0/', 'auth0-'] },
+  { name: 'Clerk',      category: 'Auth', patterns: ['@clerk/'] },
+  { name: 'NextAuth',   category: 'Auth', patterns: ['next-auth', '@auth/'] },
+  { name: 'Passport',   category: 'Auth', patterns: ['passport', 'passport-'] },
+  { name: 'Cognito',    category: 'Auth', patterns: ['@aws-sdk/client-cognito-identity', 'amazon-cognito-identity-js', 'aws-amplify'] },
+  // ── AI ──
+  { name: 'OpenAI',     category: 'AI', patterns: ['openai'] },
+  { name: 'Anthropic',  category: 'AI', patterns: ['@anthropic-ai/sdk', 'anthropic'] },
+  { name: 'LangChain',  category: 'AI', patterns: ['langchain', '@langchain/'] },
+  { name: 'Hugging Face', category: 'AI', patterns: ['huggingface', '@huggingface/', 'transformers'] },
+  // ── Messaging / email ──
+  { name: 'Twilio',     category: 'Messaging', patterns: ['twilio'] },
+  { name: 'SendGrid',   category: 'Messaging', patterns: ['@sendgrid/', 'sendgrid'] },
+  { name: 'Mailgun',    category: 'Messaging', patterns: ['mailgun', 'mailgun.js'] },
+  { name: 'Resend',     category: 'Messaging', patterns: ['resend'] },
+  { name: 'Slack',      category: 'Messaging', patterns: ['@slack/', 'slack-sdk', 'slack_sdk'] },
+  { name: 'Bird (MessageBird)', category: 'Messaging', patterns: ['messagebird', 'bird-sdk', '@birdapp/'] },
+  // ── Observability ──
+  { name: 'Sentry',     category: 'Observability', patterns: ['@sentry/', 'sentry-sdk', 'sentry-go'] },
+  { name: 'Datadog',    category: 'Observability', patterns: ['dd-trace', '@datadog/', 'datadog'] },
+  { name: 'OpenTelemetry', category: 'Observability', patterns: ['@opentelemetry/', 'opentelemetry-'] },
+  { name: 'Pino',       category: 'Observability', patterns: ['pino'] },
+  // ── Search ──
+  { name: 'Algolia',    category: 'Search', patterns: ['algoliasearch', '@algolia/', 'algolia'] },
+  { name: 'Elasticsearch', category: 'Search', patterns: ['@elastic/elasticsearch', 'elasticsearch'] },
+  { name: 'Meilisearch',category: 'Search', patterns: ['meilisearch'] },
+  { name: 'Typesense',  category: 'Search', patterns: ['typesense'] },
+  // ── Queues ──
+  { name: 'SQS',        category: 'Queue', patterns: ['@aws-sdk/client-sqs'] },
+  { name: 'RabbitMQ',   category: 'Queue', patterns: ['amqplib', 'pika'] },
+  { name: 'Kafka',      category: 'Queue', patterns: ['kafkajs', 'sarama', 'confluent-kafka'] },
+  // ── Storage ──
+  { name: 'S3',         category: 'Storage', patterns: ['@aws-sdk/client-s3', 'multer-s3', 'boto3.s3'] },
+];
+
+function depKeys(deps) {
+  return Object.keys(deps).map(k => k.toLowerCase());
+}
+
+function matches(keys, patterns) {
+  const evidence = [];
+  for (const p of patterns) {
+    const needle = p.toLowerCase();
+    for (const k of keys) {
+      if (k.includes(needle)) evidence.push(k);
+    }
+  }
+  return evidence;
+}
+
+/**
+ * Detect external integrations across all ecosystems in the project.
+ * @returns {Array<{ name, category, ecosystems: string[], evidence: string[] }>}
+ */
+export function detectIntegrations(projectDir, config = {}) {
+  const ecosystems = detectEcosystems(projectDir, config);
+  const found = new Map(); // name -> { name, category, ecosystems:Set, evidence:Set }
+
+  for (const eco of ecosystems) {
+    const keys = depKeys(eco.deps);
+    if (keys.length === 0) continue;
+    for (const entry of REGISTRY) {
+      const ev = matches(keys, entry.patterns);
+      if (ev.length === 0) continue;
+      let row = found.get(entry.name);
+      if (!row) {
+        row = { name: entry.name, category: entry.category, ecosystems: new Set(), evidence: new Set() };
+        found.set(entry.name, row);
+      }
+      row.ecosystems.add(eco.language);
+      for (const e of ev) row.evidence.add(e);
+    }
+  }
+
+  return [...found.values()]
+    .map(r => ({ name: r.name, category: r.category, ecosystems: [...r.ecosystems], evidence: [...r.evidence] }))
+    .sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+}

package/cli/scanners/memory-plan.mjs

@@ -0,0 +1,242 @@
+/**
+ * Memory Plan — the orchestration artifact behind AI-powered Generate.
+ *
+ * DocGuard's job (per the v2 vision) is to ORCHESTRATE: scan the codebase, build
+ * the code-truth skeleton in marked sections, and emit a structured **agent task
+ * manifest** telling the AI exactly what prose to write for each section,
+ * grounded in scanned facts. The agent then writes the content; DocGuard verifies.
+ *
+ * This is language-aware: the set of documents and sections depends on the
+ * detected project profile (a Rust CLI gets no Screens/API doc; a webapp does).
+ *
+ * Pure read-only assembly. Zero NPM dependencies.
+ */
+
+import { detectProjectProfile } from './project-type.mjs';
+import { detectDocTools } from './doc-tools.mjs';
+import { scanRoutesDeep } from './routes.mjs';
+import { scanSchemasDeep } from './schemas.mjs';
+import { scanFrontend } from './frontend.mjs';
+import { grepEnvUsage } from '../shared-source.mjs';
+import { detectIntegrations } from './integrations.mjs';
+
+const md = {
+  table(headers, rows) {
+    const head = `| ${headers.join(' | ')} |`;
+    const sep = `| ${headers.map(() => '---').join(' | ')} |`;
+    const body = rows.map(r => `| ${r.join(' | ')} |`).join('\n');
+    return [head, sep, body].join('\n');
+  },
+};
+
+/**
+ * Build the full memory plan for a project.
+ * @returns {{ profile, surface, docs, agentTasks }}
+ *   docs[].sections[]: { id, source:'code', body } OR { id, source:'human', task, grounding }
+ *   agentTasks: flattened prose tasks the AI must write.
+ */
+export function buildMemoryPlan(projectDir, config = {}) {
+  const profile = detectProjectProfile(projectDir, config);
+  const primaryFramework = profile.primary?.framework || profile.frameworks[0] || '';
+
+  // ── Gather the code-truth surface ──
+  const docTools = detectDocTools(projectDir);
+  const routes = scanRoutesDeep(projectDir, { framework: profile.frameworks.join(' ') }, docTools, { config });
+  const schemas = scanSchemasDeep(projectDir, { framework: primaryFramework }, docTools);
+  const entities = schemas.entities || [];
+  const isWebFrontend = profile.ecosystems.some(e => e.kind === 'webapp');
+  const fe = isWebFrontend
+    ? scanFrontend(projectDir, config)
+    : { screens: [], components: [], stores: [], hooks: [], contexts: [], apiCalls: [],
+        i18n: { usedKeys: [], locales: [], missing: [] },
+        framework: null, stateLib: null, dataLib: null };
+  const envVars = [...grepEnvUsage(projectDir, config)].sort();
+  const integrations = detectIntegrations(projectDir, config);
+
+  const surface = {
+    profile,
+    endpoints: routes.map(r => ({ method: r.method, path: r.path, auth: !!r.auth })),
+    entities: entities.map(e => ({ name: e.name, fields: e.fields || [] })),
+    screens: fe.screens,
+    components: fe.components,
+    envVars,
+    integrations,
+    stores: fe.stores,
+    hooks: fe.hooks,
+    contexts: fe.contexts,
+    apiCalls: fe.apiCalls,
+    i18n: fe.i18n,
+    frontend: { framework: fe.framework, stateLib: fe.stateLib, dataLib: fe.dataLib },
+  };
+
+  // ── Compose documents + sections (language/kind-aware) ──
+  const docs = [];
+  const agentTasks = [];
+  const addTask = (doc, sectionId, instruction, grounding) => {
+    agentTasks.push({ doc, sectionId, instruction, grounding });
+    return { id: sectionId, source: 'human', task: instruction, grounding };
+  };
+
+  // ARCHITECTURE — always.
+  {
+    const sections = [];
+    const stackRows = [
+      ...profile.ecosystems.map(e => [e.dir, e.language, e.framework || '—', e.kind]),
+    ];
+    sections.push({
+      id: 'tech-stack',
+      source: 'code',
+      body: md.table(['Path', 'Language', 'Framework', 'Kind'], stackRows),
+    });
+    sections.push(addTask('docs-canonical/ARCHITECTURE.md', 'overview',
+      'Write a 2-3 sentence System Overview: what this project does and who uses it.',
+      { languages: profile.languages, frameworks: profile.frameworks, kind: profile.kind }));
+    sections.push(addTask('docs-canonical/ARCHITECTURE.md', 'components',
+      'Describe the major components/modules and their responsibilities, using the real directories below.',
+      { ecosystems: profile.ecosystems.map(e => ({ dir: e.dir, language: e.language, framework: e.framework })) }));
+
+    // Frontend modules (stores/hooks/contexts) — code-truth section when present.
+    const feCounts = surface.stores.length + surface.hooks.length + surface.contexts.length;
+    if (feCounts > 0) {
+      const feRows = [
+        ['Stores',   String(surface.stores.length),   surface.stores.slice(0, 4).map(s => `\`${s.name}\``).join(', ') || '—'],
+        ['Hooks',    String(surface.hooks.length),    surface.hooks.slice(0, 4).map(s => `\`${s.name}\``).join(', ') || '—'],
+        ['Contexts', String(surface.contexts.length), surface.contexts.slice(0, 4).map(s => `\`${s.name}\``).join(', ') || '—'],
+      ].filter(r => r[1] !== '0');
+      sections.push({
+        id: 'frontend-modules',
+        source: 'code',
+        body: md.table(['Kind', 'Count', 'Examples'], feRows),
+      });
+    }
+    docs.push({ path: 'docs-canonical/ARCHITECTURE.md', sections });
+  }
+
+  // API-REFERENCE — only if there's an API surface.
+  if (surface.endpoints.length > 0) {
+    const rows = surface.endpoints.map(e => [`\`${e.method}\``, `\`${e.path}\``, e.auth ? '🔒' : '🔓']);
+    const sections = [{
+      id: 'endpoints',
+      source: 'code',
+      body: md.table(['Method', 'Path', 'Auth'], rows),
+    }];
+    sections.push(addTask('docs-canonical/API-REFERENCE.md', 'overview',
+      `Write a short intro describing the API (${surface.endpoints.length} endpoints) and its auth model.`,
+      { endpointCount: surface.endpoints.length, framework: primaryFramework }));
+    docs.push({ path: 'docs-canonical/API-REFERENCE.md', sections });
+  }
+
+  // DATA-MODEL — only if entities detected.
+  if (surface.entities.length > 0) {
+    const rows = surface.entities.map(e => [`\`${e.name}\``, String((e.fields || []).length)]);
+    const sections = [{
+      id: 'entities',
+      source: 'code',
+      body: md.table(['Entity', 'Fields'], rows),
+    }];
+    sections.push(addTask('docs-canonical/DATA-MODEL.md', 'relationships',
+      'Describe the relationships between the entities below and any key indexes.',
+      { entities: surface.entities.map(e => e.name) }));
+    docs.push({ path: 'docs-canonical/DATA-MODEL.md', sections });
+  }
+
+  // SCREENS — only for web frontends with screens.
+  if (surface.screens.length > 0) {
+    const rows = surface.screens.map(s => [`\`${s.path}\``, s.component || '—']);
+    const sections = [{
+      id: 'screens',
+      source: 'code',
+      body: md.table(['Route', 'Screen'], rows),
+    }];
+    sections.push(addTask('docs-canonical/SCREENS.md', 'flows',
+      `Group the ${surface.screens.length} screens into features/user-flows and describe each flow.`,
+      { screens: surface.screens.map(s => s.path), components: surface.components.length }));
+    docs.push({ path: 'docs-canonical/SCREENS.md', sections });
+  }
+
+  // INTEGRATIONS — external services / SDKs detected from deps.
+  if (surface.integrations.length > 0) {
+    const rows = surface.integrations.map(i => [i.category, `**${i.name}**`, i.evidence.slice(0, 3).join(', ')]);
+    const sections = [{
+      id: 'integrations',
+      source: 'code',
+      body: md.table(['Category', 'Service', 'Evidence (SDK)'], rows),
+    }];
+    sections.push(addTask('docs-canonical/INTEGRATIONS.md', 'overview',
+      `Describe each detected integration: what role it plays in this system, which module(s) use it, and any operational notes (auth, credentials, regions).`,
+      { integrations: surface.integrations.map(i => ({ name: i.name, category: i.category })) }));
+    docs.push({ path: 'docs-canonical/INTEGRATIONS.md', sections });
+  }
+
+  // FEATURES — derived from screens + endpoints when there's a UI surface.
+  if (surface.screens.length > 0) {
+    const groups = {};
+    for (const s of surface.screens) {
+      const seg = (s.path.split('/').filter(Boolean)[0] || 'root');
+      (groups[seg] ??= []).push(s);
+    }
+    const rows = Object.entries(groups)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([area, list]) => [`/${area === 'root' ? '' : area}`, String(list.length), list.slice(0, 4).map(s => s.component || s.path).join(', ')]);
+    const sections = [{
+      id: 'feature-areas',
+      source: 'code',
+      body: md.table(['Area', 'Screens', 'Examples'], rows),
+    }];
+    sections.push(addTask('docs-canonical/FEATURES.md', 'features',
+      `Turn the candidate feature areas below into a clear feature inventory. For each area: what user job it serves, which screens belong to it, which endpoints back it (use the apiCalls map below as evidence), and the success criteria.`,
+      {
+        areas: Object.keys(groups),
+        screenCount: surface.screens.length,
+        endpointCount: surface.endpoints.length,
+        apiCalls: surface.apiCalls.slice(0, 30).map(c => ({ method: c.method, path: c.path })),
+        storeCount: surface.stores.length,
+      }));
+    docs.push({ path: 'docs-canonical/FEATURES.md', sections });
+  }
+
+  // ENVIRONMENT — env vars + setup.
+  if (surface.envVars.length > 0) {
+    const rows = surface.envVars.map(v => [`\`${v}\``, '<!-- describe -->']);
+    const sections = [{
+      id: 'env-vars',
+      source: 'code',
+      body: md.table(['Variable', 'Description'], rows),
+    }];
+    sections.push(addTask('docs-canonical/ENVIRONMENT.md', 'setup',
+      'Write the Prerequisites and Setup Steps (clone → install → run) for this stack.',
+      { languages: profile.languages, frameworks: profile.frameworks }));
+    docs.push({ path: 'docs-canonical/ENVIRONMENT.md', sections });
+  }
+
+  // ── docs-implementation/ — tribal knowledge the AGENT writes (no code section) ──
+  // These can't be derived from code; they capture lessons learned, current
+  // state, and operational procedures. DocGuard emits guided prompts; the
+  // agent reads git history / chat / human notes and writes them.
+  docs.push({
+    path: 'docs-implementation/KNOWN-GOTCHAS.md',
+    sections: [
+      addTask('docs-implementation/KNOWN-GOTCHAS.md', 'gotchas',
+        'Document the non-obvious lessons that have bitten this team. For each: symptom → cause → fix. Mine git log (commit messages, revert/hotfix commits), recent PRs, and chat history. Keep entries terse and actionable.',
+        { integrations: surface.integrations.map(i => i.name), primary: profile.primary?.framework }),
+    ],
+  });
+  docs.push({
+    path: 'docs-implementation/CURRENT-STATE.md',
+    sections: [
+      addTask('docs-implementation/CURRENT-STATE.md', 'state',
+        'Snapshot of what is shipped vs in-flight vs planned. What is deployed (where, which versions), which features are behind flags, what is known tech debt. Mine CHANGELOG, deploy logs, feature-flag config, GitHub Issues/Projects.',
+        { kind: profile.kind, languages: profile.languages }),
+    ],
+  });
+  docs.push({
+    path: 'docs-implementation/RUNBOOKS.md',
+    sections: [
+      addTask('docs-implementation/RUNBOOKS.md', 'runbooks',
+        'Operational procedures for production: deploy, rollback, hot-fix, common incidents, on-call escalation. For each runbook: when to use, exact steps, and the verification check. Mine scripts/, .github/workflows, deploy docs, and chat history.',
+        { integrations: surface.integrations.map(i => i.name) }),
+    ],
+  });
+
+  return { profile, surface, docs, agentTasks };
+}

package/cli/scanners/project-type.mjs

@@ -0,0 +1,310 @@
+/**
+ * Project-Type Detection — the language-agnostic spine.
+ *
+ * DocGuard documents ANY project, not just JS/web. This scanner identifies
+ * every ecosystem present (polyglot/monorepo-aware) from its manifest files and
+ * extracts deterministic facts (language, framework, kind, dependencies, entry
+ * points). The AI agent then writes language-appropriate prose grounded in
+ * these facts.
+ *
+ * Supported ecosystems:
+ *   JS/TS · Python · Rust · Go · Java/Kotlin · Ruby · PHP · C#/.NET
+ *
+ * Zero NPM dependencies — minimal manifest parsing with Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative, dirname, basename } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage', 'target',
+  '.cache', '__pycache__', '.venv', 'venv', 'vendor', '.turbo', '.vercel',
+  'bin', 'obj', '.gradle', '.idea', 'cdk.out', '.claude',
+]);
+
+// Manifest filename → ecosystem language.
+const MANIFESTS = [
+  { file: 'package.json', lang: 'JavaScript' },
+  { file: 'pyproject.toml', lang: 'Python' },
+  { file: 'requirements.txt', lang: 'Python' },
+  { file: 'setup.py', lang: 'Python' },
+  { file: 'Pipfile', lang: 'Python' },
+  { file: 'Cargo.toml', lang: 'Rust' },
+  { file: 'go.mod', lang: 'Go' },
+  { file: 'pom.xml', lang: 'Java' },
+  { file: 'build.gradle', lang: 'Java' },
+  { file: 'build.gradle.kts', lang: 'Kotlin' },
+  { file: 'Gemfile', lang: 'Ruby' },
+  { file: 'composer.json', lang: 'PHP' },
+];
+
+function readSafe(p) { try { return readFileSync(p, 'utf-8'); } catch { return ''; } }
+function readJson(p) { try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { return null; } }
+
+/** Recursively find manifest files (bounded depth, ignoring vendor dirs). */
+function findManifests(projectDir, maxDepth = 4) {
+  const found = []; // { absDir, file, lang }
+  const walk = (dir, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+        walk(join(dir, e.name), depth + 1);
+      } else if (e.isFile()) {
+        const m = MANIFESTS.find(x => x.file === e.name);
+        if (m) found.push({ absDir: dir, file: e.name, lang: m.lang });
+        else if (e.name.endsWith('.csproj')) found.push({ absDir: dir, file: e.name, lang: 'C#' });
+      }
+    }
+  };
+  walk(resolve(projectDir), 0);
+  return found;
+}
+
+// ── Dependency extraction per ecosystem ──────────────────────────────────────
+
+/** Extract names from a TOML [section] of `name = "ver"` lines (Cargo, etc.). */
+function tomlSectionDeps(content, sections) {
+  const deps = {};
+  const lines = content.split('\n');
+  let active = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    const sec = line.match(/^\[([^\]]+)\]/);
+    if (sec) { active = sections.includes(sec[1]); continue; }
+    if (!active || !line || line.startsWith('#')) continue;
+    const m = line.match(/^([A-Za-z0-9_.\-]+)\s*=\s*(?:"([^"]*)"|\{[^}]*version\s*=\s*"([^"]*)"|\{)/);
+    if (m) deps[m[1]] = m[2] || m[3] || '*';
+  }
+  return deps;
+}
+
+/** pyproject [project] dependencies = ["pkg>=1", ...] and poetry table form. */
+function pyprojectDeps(content) {
+  const deps = {};
+  // PEP 621 array form
+  const arr = content.match(/dependencies\s*=\s*\[([\s\S]*?)\]/);
+  if (arr) {
+    for (const m of arr[1].matchAll(/["']([A-Za-z0-9_.\-]+)\s*[><=~!\[]?/g)) deps[m[1]] = '*';
+  }
+  // Poetry table form
+  Object.assign(deps, tomlSectionDeps(content, ['tool.poetry.dependencies']));
+  return deps;
+}
+
+function requirementsDeps(content) {
+  const deps = {};
+  for (const raw of content.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith('-')) continue;
+    const m = line.match(/^([A-Za-z0-9_.\-]+)\s*(?:[><=~!]=?\s*([0-9][\w.\-]*))?/);
+    if (m) deps[m[1].toLowerCase()] = m[2] || '*';
+  }
+  return deps;
+}
+
+function goModDeps(content) {
+  const deps = {};
+  // require ( ... ) block + single-line requires
+  const block = content.match(/require\s*\(([\s\S]*?)\)/);
+  const collect = (text) => {
+    for (const m of text.matchAll(/^\s*([\w.\-/]+)\s+v([\w.\-]+)/gm)) deps[m[1]] = 'v' + m[2];
+  };
+  if (block) collect(block[1]);
+  for (const m of content.matchAll(/^require\s+([\w.\-/]+)\s+v([\w.\-]+)/gm)) deps[m[1]] = 'v' + m[2];
+  return deps;
+}
+
+function gradleDeps(content) {
+  const deps = {};
+  for (const m of content.matchAll(/(?:implementation|api|compile|testImplementation)\s*[(\s]['"]([^'":]+):([^'":]+)(?::([^'"]+))?['"]/g)) {
+    deps[`${m[1]}:${m[2]}`] = m[3] || '*';
+  }
+  return deps;
+}
+
+function pomDeps(content) {
+  const deps = {};
+  for (const m of content.matchAll(/<dependency>[\s\S]*?<groupId>([^<]+)<\/groupId>[\s\S]*?<artifactId>([^<]+)<\/artifactId>/g)) {
+    deps[`${m[1].trim()}:${m[2].trim()}`] = '*';
+  }
+  return deps;
+}
+
+function gemfileDeps(content) {
+  const deps = {};
+  for (const m of content.matchAll(/^\s*gem\s+['"]([^'"]+)['"]/gm)) deps[m[1]] = '*';
+  return deps;
+}
+
+function csprojDeps(content) {
+  const deps = {};
+  for (const m of content.matchAll(/<PackageReference\s+Include="([^"]+)"(?:\s+Version="([^"]+)")?/g)) {
+    deps[m[1]] = m[2] || '*';
+  }
+  return deps;
+}
+
+// ── Framework + kind classification per ecosystem ────────────────────────────
+
+function has(deps, ...names) {
+  const keys = Object.keys(deps).map(k => k.toLowerCase());
+  return names.some(n => keys.some(k => k === n.toLowerCase() || k.endsWith('/' + n.toLowerCase()) || k.endsWith(':' + n.toLowerCase())));
+}
+
+function classify(lang, dir, deps) {
+  let framework = null;
+  let kind = 'library';
+
+  if (lang === 'JavaScript' || lang === 'TypeScript') {
+    if (has(deps, 'next')) { framework = 'Next.js'; kind = 'webapp'; }
+    else if (has(deps, 'react', 'vue', '@angular/core', 'svelte', '@sveltejs/kit', 'nuxt')) { framework = has(deps,'react')?'React':has(deps,'vue')?'Vue':'Frontend'; kind = 'webapp'; }
+    else if (has(deps, 'express', 'fastify', 'hono', 'koa', '@nestjs/core')) { framework = has(deps,'express')?'Express':has(deps,'fastify')?'Fastify':has(deps,'@nestjs/core')?'NestJS':'Hono'; kind = 'api'; }
+  } else if (lang === 'Python') {
+    if (has(deps, 'django') || existsSync(join(dir, 'manage.py'))) { framework = 'Django'; kind = 'webapp'; }
+    else if (has(deps, 'fastapi')) { framework = 'FastAPI'; kind = 'api'; }
+    else if (has(deps, 'flask')) { framework = 'Flask'; kind = 'api'; }
+    else if (has(deps, 'starlette')) { framework = 'Starlette'; kind = 'api'; }
+    else if (has(deps, 'click', 'typer')) { framework = has(deps,'typer')?'Typer':'Click'; kind = 'cli'; }
+  } else if (lang === 'Rust') {
+    if (has(deps, 'actix-web')) { framework = 'Actix Web'; kind = 'service'; }
+    else if (has(deps, 'axum')) { framework = 'Axum'; kind = 'service'; }
+    else if (has(deps, 'rocket')) { framework = 'Rocket'; kind = 'service'; }
+    else if (has(deps, 'warp', 'tide')) { framework = has(deps,'warp')?'Warp':'Tide'; kind = 'service'; }
+    else if (has(deps, 'clap', 'structopt')) { framework = 'Clap'; kind = 'cli'; }
+    if (existsSync(join(dir, 'src/main.rs')) && kind === 'library') kind = 'cli';
+    else if (existsSync(join(dir, 'src/lib.rs')) && !framework) kind = 'library';
+  } else if (lang === 'Go') {
+    if (has(deps, 'gin', 'gin-gonic/gin')) { framework = 'Gin'; kind = 'service'; }
+    else if (has(deps, 'echo', 'labstack/echo')) { framework = 'Echo'; kind = 'service'; }
+    else if (has(deps, 'chi', 'go-chi/chi')) { framework = 'Chi'; kind = 'service'; }
+    else if (has(deps, 'fiber', 'gofiber/fiber')) { framework = 'Fiber'; kind = 'service'; }
+    else if (existsSync(join(dir, 'main.go')) || existsSync(join(dir, 'cmd'))) kind = 'service';
+  } else if (lang === 'Java' || lang === 'Kotlin') {
+    if (has(deps, 'spring-boot-starter-web', 'spring-boot-starter', 'org.springframework.boot:spring-boot-starter-web')) { framework = 'Spring Boot'; kind = 'api'; }
+  } else if (lang === 'Ruby') {
+    if (has(deps, 'rails')) { framework = 'Rails'; kind = 'webapp'; }
+    else if (has(deps, 'sinatra')) { framework = 'Sinatra'; kind = 'api'; }
+  } else if (lang === 'PHP') {
+    if (has(deps, 'laravel/framework')) { framework = 'Laravel'; kind = 'webapp'; }
+    else if (has(deps, 'symfony/framework-bundle')) { framework = 'Symfony'; kind = 'webapp'; }
+  } else if (lang === 'C#') {
+    if (has(deps, 'Microsoft.AspNetCore.App') || /Sdk="Microsoft\.NET\.Sdk\.Web"/.test('')) { framework = 'ASP.NET Core'; kind = 'api'; }
+  }
+
+  return { framework, kind };
+}
+
+// ── Per-manifest ecosystem builder ───────────────────────────────────────────
+
+function buildEcosystem(projectDir, m) {
+  const path = join(m.absDir, m.file);
+  const content = readSafe(path);
+  let deps = {};
+  let lang = m.lang;
+  let kind = null;
+  let entryPoints = [];
+
+  if (m.file === 'package.json') {
+    const pkg = readJson(path) || {};
+    deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (deps.typescript || existsSync(join(m.absDir, 'tsconfig.json'))) lang = 'TypeScript';
+    if (pkg.bin) { kind = 'cli'; entryPoints = typeof pkg.bin === 'string' ? [pkg.bin] : Object.values(pkg.bin); }
+    else if (pkg.main || pkg.module || pkg.exports) entryPoints = [pkg.main || pkg.module].filter(Boolean);
+  } else if (m.file === 'pyproject.toml') {
+    deps = pyprojectDeps(content);
+  } else if (m.file === 'requirements.txt') {
+    deps = requirementsDeps(content);
+  } else if (m.file === 'Pipfile') {
+    deps = tomlSectionDeps(content, ['packages']);
+  } else if (m.file === 'setup.py') {
+    for (const mm of content.matchAll(/['"]([A-Za-z0-9_.\-]+)(?:[><=~!]=?[\w.\-]+)?['"]/g)) deps[mm[1].toLowerCase()] = '*';
+  } else if (m.file === 'Cargo.toml') {
+    deps = tomlSectionDeps(content, ['dependencies']);
+  } else if (m.file === 'go.mod') {
+    deps = goModDeps(content);
+  } else if (m.file === 'pom.xml') {
+    deps = pomDeps(content);
+  } else if (m.file === 'build.gradle' || m.file === 'build.gradle.kts') {
+    deps = gradleDeps(content);
+  } else if (m.file === 'Gemfile') {
+    deps = gemfileDeps(content);
+  } else if (m.file === 'composer.json') {
+    const c = readJson(path) || {};
+    deps = { ...(c.require || {}), ...(c['require-dev'] || {}) };
+  } else if (m.file.endsWith('.csproj')) {
+    deps = csprojDeps(content);
+  }
+
+  const cls = classify(lang, m.absDir, deps);
+  return {
+    language: lang,
+    manifest: relative(resolve(projectDir), path) || m.file,
+    dir: relative(resolve(projectDir), m.absDir) || '.',
+    framework: cls.framework,
+    kind: kind || cls.kind || 'library',
+    deps,
+    entryPoints,
+  };
+}
+
+/**
+ * Detect every ecosystem present in the repo (polyglot-aware).
+ * Multiple manifests in the same dir+language merge into one ecosystem.
+ * @returns {Array<{ language, manifest, dir, framework, kind, deps, entryPoints }>}
+ */
+export function detectEcosystems(projectDir, _config = {}) {
+  const manifests = findManifests(projectDir);
+  const byKey = new Map(); // `${dir}::${lang-family}` → ecosystem
+
+  // Group Python manifests (pyproject/requirements/setup/Pipfile) in same dir.
+  const langFamily = (lang) => (lang === 'TypeScript' ? 'JavaScript' : lang);
+
+  for (const m of manifests) {
+    const eco = buildEcosystem(projectDir, m);
+    const key = `${eco.dir}::${langFamily(eco.language)}`;
+    if (byKey.has(key)) {
+      // Merge deps + prefer the richer framework/kind/manifest.
+      const cur = byKey.get(key);
+      cur.deps = { ...cur.deps, ...eco.deps };
+      if (!cur.framework && eco.framework) cur.framework = eco.framework;
+      if (cur.kind === 'library' && eco.kind !== 'library') cur.kind = eco.kind;
+      if (eco.language === 'TypeScript') cur.language = 'TypeScript';
+      // Re-classify with merged deps.
+      const cls = classify(cur.language, join(resolve(projectDir), cur.dir === '.' ? '' : cur.dir), cur.deps);
+      if (!cur.framework) cur.framework = cls.framework;
+    } else {
+      byKey.set(key, eco);
+    }
+  }
+
+  return [...byKey.values()];
+}
+
+/**
+ * Top-level project profile.
+ * @returns {{ ecosystems, primary, polyglot, languages, frameworks, kind }}
+ */
+export function detectProjectProfile(projectDir, config = {}) {
+  const ecosystems = detectEcosystems(projectDir, config);
+
+  // Primary = the root-level ecosystem, else the one with the most deps.
+  const rootEco = ecosystems.find(e => e.dir === '.');
+  const primary = rootEco
+    || [...ecosystems].sort((a, b) => Object.keys(b.deps).length - Object.keys(a.deps).length)[0]
+    || null;
+
+  const languages = [...new Set(ecosystems.map(e => e.language))];
+  const frameworks = [...new Set(ecosystems.map(e => e.framework).filter(Boolean))];
+
+  return {
+    ecosystems,
+    primary,
+    polyglot: languages.length > 1,
+    languages,
+    frameworks,
+    kind: primary?.kind || 'unknown',
+  };
+}