project-scan 1.0.0

package/lib/md-report.js

@@ -0,0 +1,277 @@
+'use strict';
+/**
+ * md-report.js — Generates Markdown summary files from scan + test results.
+ * Produces: SUMMARY.md, ONBOARDING.md, TESTS.md
+ */
+
+const path = require('path');
+
+// ─── SUMMARY.md ───────────────────────────────────────────────────────────────
+
+function generateSummary(scanResult, testResults) {
+  const { projectName, scannedAt, languages, frameworks, databases, cloud, pipelines, structure, totalFiles, packageMeta, envFilesFound } = scanResult;
+
+  const totalPassed  = testResults.reduce((s, r) => s + (r.passed  || 0), 0);
+  const totalFailed  = testResults.reduce((s, r) => s + (r.failed  || 0), 0);
+  const totalSkipped = testResults.reduce((s, r) => s + (r.skipped || 0), 0);
+  const overallPass  = totalFailed === 0 && testResults.some(r => r.status === 'passed');
+  const testBadge    = testResults.length === 0 ? '⚪ No tests'
+                     : overallPass ? `✅ PASSING (${totalPassed} tests)` : `❌ FAILING (${totalFailed} failures)`;
+
+  const pills = (arr) => arr.length > 0 ? arr.map(i => `\`${i}\``).join(' · ') : '_None detected_';
+
+  const testSuiteSummary = testResults.map(r => {
+    const icon = r.status === 'passed' ? '✅' : r.status === 'failed' ? '❌' : r.status === 'error' ? '⚠️' : '⏭️';
+    const ms   = r.duration ? `${(r.duration/1000).toFixed(2)}s` : '—';
+    return `| ${icon} ${r.suite} | ${r.passed||0} | ${r.failed||0} | ${r.skipped||0} | ${ms} |`;
+  }).join('\n');
+
+  const entryPoints = (structure.entryPoints || []).slice(0, 8).map(f => `  - \`${f}\``).join('\n') || '  - _None detected_';
+  const testFiles   = (structure.testFiles   || []).slice(0, 12).map(f => `  - \`${f}\``).join('\n') || '  - _None detected_';
+
+  return `# 📋 ${projectName} — Project Summary
+
+> **Scanned:** ${scannedAt}  
+> **Project type:** ${structure.type}  
+> **Total files scanned:** ${totalFiles.toLocaleString()}  
+> **Test status:** ${testBadge}
+
+${packageMeta?.description ? `> ${packageMeta.description}\n` : ''}
+---
+
+## 💻 Languages
+${pills(languages)}
+
+## ⚙️ Frameworks & Libraries
+${pills(frameworks)}
+
+## 🗄️ Databases & Storage
+${pills(databases)}
+
+## ☁️ Cloud & API Services
+${pills(cloud)}
+
+## 🔄 CI/CD Pipelines
+${pills(pipelines)}
+
+---
+
+## 📁 Project Structure
+
+**Type:** ${structure.type}
+
+**Top-level directories:**
+${structure.parts.length > 0 ? structure.parts.map(p => `- \`/${p}\``).join('\n') : '- _No subdirectories_'}
+
+**Entry points:**
+${entryPoints}
+
+**Test files found (${(structure.testFiles||[]).length}):**
+${testFiles}
+
+---
+
+## 🧪 Test Summary
+
+| Suite | ✅ Passed | ❌ Failed | ⏭️ Skipped | ⏱ Duration |
+|-------|-----------|-----------|------------|------------|
+${testSuiteSummary || '| — | — | — | — | — |'}
+
+**Total: ${totalPassed} passed · ${totalFailed} failed · ${totalSkipped} skipped**
+
+${envFilesFound.length > 0 ? `---\n\n## 🔒 Environment Files\n${envFilesFound.map(f => `- \`${f}\``).join('\n')}` : ''}
+---
+
+_Generated by [project-scan](https://npmjs.com/package/project-scan)_
+`;
+}
+
+// ─── ONBOARDING.md ────────────────────────────────────────────────────────────
+
+function generateOnboarding(scanResult) {
+  const { projectName, scannedAt, languages, frameworks, databases, cloud, pipelines, structure, packageMeta } = scanResult;
+
+  const pills = (arr) => arr.length > 0 ? arr.map(i => `- **${i}**`).join('\n') : '- _None detected_';
+
+  const detectSetupCmd = () => {
+    const cmds = [];
+    if (languages.includes('JavaScript') || languages.includes('TypeScript')) {
+      cmds.push('npm install  # or: yarn install / pnpm install');
+    }
+    if (languages.includes('Python')) {
+      cmds.push('pip install -r requirements.txt  # or: pip install -e .');
+    }
+    if (languages.includes('Go')) cmds.push('go mod download');
+    if (languages.includes('Rust')) cmds.push('cargo build');
+    if (languages.includes('Java') || languages.includes('Kotlin')) cmds.push('mvn install  # or: ./gradlew build');
+    if (languages.includes('PHP')) cmds.push('composer install');
+    if (languages.includes('Ruby')) cmds.push('bundle install');
+    if (languages.includes('Dart')) cmds.push('flutter pub get  # or: dart pub get');
+    return cmds.length > 0 ? cmds.join('\n') : '# No standard setup detected';
+  };
+
+  const detectRunCmd = () => {
+    const scripts = packageMeta?.scripts || {};
+    const lines = [];
+    if (scripts.dev)   lines.push(`npm run dev    # ${scripts.dev}`);
+    if (scripts.start) lines.push(`npm start      # ${scripts.start}`);
+    if (!lines.length && languages.includes('Python')) lines.push('python main.py  # or: uvicorn main:app');
+    if (!lines.length && languages.includes('Go'))     lines.push('go run .');
+    if (!lines.length && languages.includes('Rust'))   lines.push('cargo run');
+    return lines.join('\n') || '# Check README for run instructions';
+  };
+
+  const archLines = [];
+  archLines.push('```');
+  archLines.push(`┌──────────────────────────────────────────────────┐`);
+  archLines.push(`│  Project: ${projectName.padEnd(39)}│`);
+  archLines.push(`│  Type:    ${structure.type.padEnd(39)}│`);
+  archLines.push(`│                                                  │`);
+  structure.parts.forEach(p => {
+    archLines.push(`│  ├── /${p.padEnd(43)}│`);
+  });
+  archLines.push(`└──────────────────────────────────────────────────┘`);
+  archLines.push('```');
+
+  return `# 🚀 Onboarding Guide — ${projectName}
+
+> **Auto-generated on:** ${scannedAt}  
+> **Project type:** ${structure.type}
+
+---
+
+## 1. Technology Stack
+
+### Languages
+${pills(languages)}
+
+### Frameworks & Libraries
+${pills(frameworks)}
+
+### Databases & Storage
+${pills(databases)}
+
+### Cloud & API Services
+${pills(cloud)}
+
+### CI/CD Pipelines
+${pills(pipelines)}
+
+---
+
+## 2. Architecture Overview
+
+${archLines.join('\n')}
+
+${(structure.entryPoints||[]).length > 0 ? `### Entry Points\n${structure.entryPoints.slice(0,8).map(f => `- \`${f}\``).join('\n')}` : ''}
+
+---
+
+## 3. Getting Started
+
+### Install dependencies
+\`\`\`bash
+${detectSetupCmd()}
+\`\`\`
+
+### Run the project
+\`\`\`bash
+${detectRunCmd()}
+\`\`\`
+
+### Run tests
+\`\`\`bash
+npx project-scan --tests-only
+# or use the local runner:
+bash run_tests.sh
+\`\`\`
+
+### Generate this report again
+\`\`\`bash
+npx project-scan --report
+\`\`\`
+
+---
+
+_Generated by [project-scan](https://npmjs.com/package/project-scan)_
+`;
+}
+
+// ─── TESTS.md ─────────────────────────────────────────────────────────────────
+
+function generateTestsReport(scanResult, testResults) {
+  const { projectName, scannedAt } = scanResult;
+
+  const totalPassed  = testResults.reduce((s, r) => s + (r.passed  || 0), 0);
+  const totalFailed  = testResults.reduce((s, r) => s + (r.failed  || 0), 0);
+  const totalSkipped = testResults.reduce((s, r) => s + (r.skipped || 0), 0);
+  const totalTests   = totalPassed + totalFailed + totalSkipped;
+  const overallPass  = totalFailed === 0 && testResults.some(r => r.status === 'passed');
+
+  const statusBanner = overallPass
+    ? `> ## ✅ ALL TESTS PASSING\n> ${totalPassed}/${totalTests} tests passed`
+    : totalFailed > 0
+    ? `> ## ❌ ${totalFailed} TEST(S) FAILING\n> ${totalPassed} passed · ${totalFailed} failed · ${totalSkipped} skipped`
+    : `> ## ⏭️ NO TESTS RAN\n> No test suites were executed`;
+
+  const suiteDetails = testResults.map(r => {
+    const icon = r.status === 'passed' ? '✅' : r.status === 'failed' ? '❌' : r.status === 'error' ? '⚠️' : '⏭️';
+    const ms   = r.duration ? `${(r.duration/1000).toFixed(2)}s` : '—';
+    const output = r.output ? `\n\n<details>\n<summary>Output log</summary>\n\n\`\`\`\n${r.output.slice(-2000)}\n\`\`\`\n</details>` : '';
+    const error  = r.error  ? `\n\n> **Error:** ${r.error}` : '';
+    return `### ${icon} ${r.suite}\n\n| Metric | Value |\n|--------|-------|\n| Status | \`${r.status}\` |\n| Passed | ${r.passed||0} |\n| Failed | ${r.failed||0} |\n| Skipped | ${r.skipped||0} |\n| Duration | ${ms} |\n${r.suites ? `| Suites | ${r.suites} |\n` : ''}${output}${error}`;
+  }).join('\n\n---\n\n');
+
+  const testFilesList = (scanResult.structure.testFiles || []).slice(0, 30).map(f => `- \`${f}\``).join('\n') || '- _None found_';
+
+  return `# 🧪 Test Report — ${projectName}
+
+> **Generated:** ${scannedAt}  
+> **Project:** \`${projectName}\`
+
+${statusBanner}
+
+---
+
+## Summary
+
+| Suite | Status | ✅ Passed | ❌ Failed | ⏭️ Skipped | ⏱ Duration |
+|-------|--------|-----------|-----------|------------|------------|
+${testResults.map(r => {
+  const icon = r.status === 'passed' ? '✅' : r.status === 'failed' ? '❌' : r.status === 'error' ? '⚠️' : '⏭️';
+  return `| ${r.suite} | ${icon} ${r.status} | ${r.passed||0} | ${r.failed||0} | ${r.skipped||0} | ${r.duration ? (r.duration/1000).toFixed(2)+'s' : '—'} |`;
+}).join('\n') || '| — | — | — | — | — | — |'}
+
+**Total: ${totalPassed} passed · ${totalFailed} failed · ${totalSkipped} skipped · ${totalTests} total**
+
+---
+
+## Test Files Detected
+
+${testFilesList}
+
+---
+
+## Detailed Suite Results
+
+${suiteDetails || '_No test suites ran._'}
+
+---
+
+## How to Run Tests
+
+\`\`\`bash
+# Run all tests via project-scan
+npx project-scan --tests-only
+
+# Or re-run manually
+bash run_tests.sh
+\`\`\`
+
+---
+
+_Generated by [project-scan](https://npmjs.com/package/project-scan)_
+`;
+}
+
+module.exports = { generateSummary, generateOnboarding, generateTestsReport };

package/lib/scanner.js

@@ -0,0 +1,280 @@
+'use strict';
+/**
+ * scanner.js — Universal project scanner
+ * Detects languages, frameworks, databases, cloud infra, and CI/CD pipelines
+ * by inspecting config files and source extensions recursively.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─── Signature maps ──────────────────────────────────────────────────────────
+
+const LANGUAGE_SIGS = {
+  JavaScript:  { files: ['package.json'], exts: ['.js', '.mjs', '.cjs'] },
+  TypeScript:  { files: ['tsconfig.json'], exts: ['.ts', '.tsx'] },
+  Python:      { files: ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile', 'setup.cfg'], exts: ['.py'] },
+  Java:        { files: ['pom.xml', 'build.gradle', 'build.gradle.kts'], exts: ['.java'] },
+  Kotlin:      { files: ['settings.gradle.kts', 'build.gradle.kts'], exts: ['.kt', '.kts'] },
+  Go:          { files: ['go.mod', 'go.sum'], exts: ['.go'] },
+  Rust:        { files: ['Cargo.toml', 'Cargo.lock'], exts: ['.rs'] },
+  'C/C++':     { files: ['CMakeLists.txt', 'Makefile', 'meson.build'], exts: ['.c', '.cpp', '.cc', '.cxx', '.h', '.hpp'] },
+  'C#':        { files: [], exts: ['.cs', '.csproj', '.sln'] },
+  PHP:         { files: ['composer.json', 'composer.lock'], exts: ['.php'] },
+  Ruby:        { files: ['Gemfile', 'Gemfile.lock', '.ruby-version'], exts: ['.rb'] },
+  Swift:       { files: ['Package.swift'], exts: ['.swift'] },
+  Dart:        { files: ['pubspec.yaml', 'pubspec.lock'], exts: ['.dart'] },
+  Scala:       { files: ['build.sbt'], exts: ['.scala'] },
+  Elixir:      { files: ['mix.exs', 'mix.lock'], exts: ['.ex', '.exs'] },
+  Lua:         { files: [], exts: ['.lua'] },
+  R:           { files: ['DESCRIPTION', 'NAMESPACE'], exts: ['.r', '.R'] },
+  Shell:       { files: [], exts: ['.sh', '.bash', '.zsh'] },
+  PowerShell:  { files: [], exts: ['.ps1', '.psm1'] },
+  Terraform:   { files: [], exts: ['.tf', '.tfvars'] },
+  YAML:        { files: [], exts: ['.yaml', '.yml'] },
+  Dockerfile:  { files: ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml'], exts: [] },
+};
+
+const FRAMEWORK_SIGS = {
+  // Frontend
+  React:        { files: [], deps: ['react', 'react-dom'] },
+  'Next.js':    { files: ['next.config.js', 'next.config.ts', 'next.config.mjs'], deps: ['next'] },
+  Vue:          { files: ['vue.config.js'], deps: ['vue'] },
+  Angular:      { files: ['angular.json'], deps: ['@angular/core'] },
+  Svelte:       { files: ['svelte.config.js'], deps: ['svelte'] },
+  Vite:         { files: ['vite.config.js', 'vite.config.ts', 'vite.config.mjs'], deps: ['vite'] },
+  Nuxt:         { files: ['nuxt.config.js', 'nuxt.config.ts'], deps: ['nuxt'] },
+  Gatsby:       { files: ['gatsby-config.js', 'gatsby-config.ts'], deps: ['gatsby'] },
+  // Backend
+  Express:      { files: [], deps: ['express'] },
+  Fastify:      { files: [], deps: ['fastify'] },
+  NestJS:       { files: ['nest-cli.json'], deps: ['@nestjs/core'] },
+  Koa:          { files: [], deps: ['koa'] },
+  Hapi:         { files: [], deps: ['@hapi/hapi'] },
+  Django:       { files: ['manage.py'], deps: [] },
+  Flask:        { files: [], deps: [] },
+  FastAPI:      { files: [], deps: [] },
+  Laravel:      { files: ['artisan'], deps: [] },
+  Rails:        { files: ['config/routes.rb', 'Gemfile'], deps: [] },
+  Spring:       { files: [], deps: [] }, // detected via pom.xml content
+  // Mobile
+  'React Native': { files: [], deps: ['react-native'] },
+  Flutter:      { files: ['pubspec.yaml'], deps: [] },
+  // Testing frameworks
+  Jest:         { files: ['jest.config.js', 'jest.config.ts', 'jest.config.mjs'], deps: ['jest'] },
+  Vitest:       { files: ['vitest.config.js', 'vitest.config.ts'], deps: ['vitest'] },
+  Mocha:        { files: ['.mocharc.js', '.mocharc.yml'], deps: ['mocha'] },
+  Pytest:       { files: ['pytest.ini', 'pyproject.toml'], deps: [] },
+};
+
+const DATABASE_SIGS = {
+  MongoDB:      { files: [], deps: ['mongoose', 'mongodb'], envKeys: ['MONGO_URI', 'MONGODB_URI', 'MONGO_URL'] },
+  PostgreSQL:   { files: [], deps: ['pg', 'postgres', 'typeorm'], envKeys: ['DATABASE_URL', 'POSTGRES_URL', 'PG_URL'] },
+  MySQL:        { files: [], deps: ['mysql', 'mysql2', 'sequelize'], envKeys: ['MYSQL_URL', 'DATABASE_URL'] },
+  SQLite:       { files: ['database.db', 'db.sqlite', 'local.db'], deps: ['better-sqlite3', 'sqlite3', 'sqlite'] },
+  Redis:        { files: [], deps: ['ioredis', 'redis'], envKeys: ['REDIS_URL', 'REDIS_HOST'] },
+  Supabase:     { files: [], deps: ['@supabase/supabase-js'], envKeys: ['SUPABASE_URL'] },
+  Prisma:       { files: ['prisma/schema.prisma', 'schema.prisma'], deps: ['prisma', '@prisma/client'] },
+  Firebase:     { files: ['firebase.json', '.firebaserc'], deps: ['firebase', 'firebase-admin'], envKeys: ['FIREBASE_PROJECT_ID'] },
+  DynamoDB:     { files: [], deps: ['@aws-sdk/client-dynamodb', 'dynamoose'], envKeys: ['AWS_DYNAMODB_TABLE'] },
+  Elasticsearch:{ files: [], deps: ['@elastic/elasticsearch'], envKeys: ['ELASTICSEARCH_URL'] },
+  'SQL Server': { files: [], deps: ['mssql', 'tedious'], envKeys: ['MSSQL_HOST'] },
+  Cassandra:    { files: [], deps: ['cassandra-driver'], envKeys: [] },
+};
+
+const CLOUD_SIGS = {
+  AWS:          { files: ['serverless.yml', 'serverless.yaml', 'sam.yaml', 'template.yaml', 'cdk.json', '.aws/config'], deps: ['aws-sdk', '@aws-sdk/client-s3'], envKeys: ['AWS_REGION', 'AWS_ACCESS_KEY_ID'] },
+  'Google Cloud':{ files: ['app.yaml', '.gcloudignore', 'cloudbuild.yaml'], deps: ['@google-cloud/storage', '@google-cloud/firestore'], envKeys: ['GOOGLE_CLOUD_PROJECT', 'GCLOUD_PROJECT'] },
+  Azure:        { files: ['azure-pipelines.yml', 'azure-functions.json'], deps: ['@azure/storage-blob', '@azure/identity'], envKeys: ['AZURE_TENANT_ID', 'AZURE_CLIENT_ID'] },
+  Vercel:       { files: ['vercel.json', '.vercel/project.json'], deps: [], envKeys: ['VERCEL_URL'] },
+  Netlify:      { files: ['netlify.toml', '_redirects', '_headers'], deps: ['netlify'], envKeys: ['NETLIFY_SITE_ID'] },
+  Heroku:       { files: ['Procfile', 'app.json'], deps: [], envKeys: ['HEROKU_APP_NAME'] },
+  Cloudflare:   { files: ['wrangler.toml', 'wrangler.json'], deps: ['wrangler', '@cloudflare/workers-types'], envKeys: [] },
+  Railway:      { files: ['railway.json', 'railway.toml'], deps: [], envKeys: ['RAILWAY_PROJECT_ID'] },
+  Render:       { files: ['render.yaml'], deps: [], envKeys: ['RENDER_SERVICE_ID'] },
+  ImageKit:     { files: [], deps: ['imagekit', '@imagekit/nodejs'], envKeys: ['IMAGEKIT_URL_ENDPOINT', 'IMAGEKIT_PUBLIC_KEY'] },
+};
+
+const CI_SIGS = {
+  'GitHub Actions': { files: ['.github/workflows'] },
+  'GitLab CI':      { files: ['.gitlab-ci.yml'] },
+  'CircleCI':       { files: ['.circleci/config.yml'] },
+  'Travis CI':      { files: ['.travis.yml'] },
+  Jenkins:          { files: ['Jenkinsfile'] },
+  Drone:            { files: ['.drone.yml'] },
+  Bitbucket:        { files: ['bitbucket-pipelines.yml'] },
+  'Azure Pipelines':{ files: ['azure-pipelines.yml'] },
+  TeamCity:         { files: ['.teamcity'] },
+};
+
+// ─── Helper utilities ────────────────────────────────────────────────────────
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '__pycache__',
+  'venv', '.venv', 'env', 'target', 'vendor', '.gradle', 'coverage', '.nyc_output',
+  'out', 'bin', 'obj', '.idea', '.vscode', '.dart_tool', '.pub-cache']);
+
+function walk(dir, depth = 0, maxDepth = 4) {
+  if (depth > maxDepth) return [];
+  let results = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) results = results.concat(walk(full, depth + 1, maxDepth));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function fileExists(root, rel) {
+  // rel can be a file or directory check
+  return fs.existsSync(path.join(root, rel));
+}
+
+function readJSON(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+function readText(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+function allDeps(pkgJson) {
+  if (!pkgJson) return [];
+  return [
+    ...Object.keys(pkgJson.dependencies || {}),
+    ...Object.keys(pkgJson.devDependencies || {}),
+    ...Object.keys(pkgJson.peerDependencies || {}),
+  ];
+}
+
+// ─── Main scanner ────────────────────────────────────────────────────────────
+
+function scan(rootDir) {
+  const allFiles = walk(rootDir);
+  const relFiles = allFiles.map(f => f.slice(rootDir.length + 1).replace(/\\/g, '/'));
+  const relFileSet = new Set(relFiles);
+
+  // Collect all extensions present
+  const extSet = new Set(allFiles.map(f => path.extname(f).toLowerCase()).filter(Boolean));
+
+  // Collect all package.json deps across the whole tree
+  const allPackageDeps = new Set();
+  const packageJsonFiles = allFiles.filter(f => path.basename(f) === 'package.json' && !f.includes('node_modules'));
+  for (const pf of packageJsonFiles) {
+    const pkg = readJSON(pf);
+    if (pkg) allDeps(pkg).forEach(d => allPackageDeps.add(d));
+  }
+
+  // Collect .env keys present
+  const envKeys = new Set();
+  const envFiles = allFiles.filter(f => /\.env(\.|$)/.test(path.basename(f)) && !f.includes('node_modules'));
+  for (const ef of envFiles) {
+    readText(ef).split('\n').forEach(line => {
+      const m = line.match(/^([A-Z_][A-Z0-9_]*)=/);
+      if (m) envKeys.add(m[1]);
+    });
+  }
+
+  // ── Languages ──────────────────────────────────────────────────────────────
+  const languages = [];
+  for (const [lang, sig] of Object.entries(LANGUAGE_SIGS)) {
+    const byFile = sig.files.some(f => relFileSet.has(f) || relFiles.some(r => r.endsWith('/' + f) || r === f));
+    const byExt  = sig.exts.some(e => extSet.has(e));
+    if (byFile || byExt) languages.push(lang);
+  }
+
+  // ── Frameworks ─────────────────────────────────────────────────────────────
+  const frameworks = [];
+  for (const [fw, sig] of Object.entries(FRAMEWORK_SIGS)) {
+    const byFile = sig.files.some(f => relFileSet.has(f) || relFiles.some(r => r === f || r.endsWith('/' + f)));
+    const byDep  = sig.deps.some(d => allPackageDeps.has(d));
+    if (byFile || byDep) frameworks.push(fw);
+  }
+  // Extra: detect Python frameworks from requirements/pyproject text
+  const reqText = readText(path.join(rootDir, 'requirements.txt')) + readText(path.join(rootDir, 'pyproject.toml')) + readText(path.join(rootDir, 'Pipfile'));
+  if (/django/i.test(reqText) && !frameworks.includes('Django')) frameworks.push('Django');
+  if (/flask/i.test(reqText) && !frameworks.includes('Flask')) frameworks.push('Flask');
+  if (/fastapi/i.test(reqText) && !frameworks.includes('FastAPI')) frameworks.push('FastAPI');
+  if (/pytest/i.test(reqText) && !frameworks.includes('Pytest')) frameworks.push('Pytest');
+  // Spring Boot from pom.xml
+  const pomText = readText(path.join(rootDir, 'pom.xml'));
+  if (/spring-boot/i.test(pomText) && !frameworks.includes('Spring Boot')) frameworks.push('Spring Boot');
+  if (/spring-web/i.test(pomText) && !frameworks.includes('Spring MVC')) frameworks.push('Spring MVC');
+
+  // ── Databases ──────────────────────────────────────────────────────────────
+  const databases = [];
+  for (const [db, sig] of Object.entries(DATABASE_SIGS)) {
+    const byFile = sig.files.some(f => relFileSet.has(f));
+    const byDep  = sig.deps.some(d => allPackageDeps.has(d));
+    const byEnv  = (sig.envKeys || []).some(k => envKeys.has(k));
+    if (byFile || byDep || byEnv) databases.push(db);
+  }
+
+  // ── Cloud / API services ───────────────────────────────────────────────────
+  const cloud = [];
+  for (const [svc, sig] of Object.entries(CLOUD_SIGS)) {
+    const byFile = sig.files.some(f => relFileSet.has(f) || relFiles.some(r => r === f || r.startsWith(f + '/')));
+    const byDep  = (sig.deps || []).some(d => allPackageDeps.has(d));
+    const byEnv  = (sig.envKeys || []).some(k => envKeys.has(k));
+    if (byFile || byDep || byEnv) cloud.push(svc);
+  }
+
+  // ── CI/CD pipelines ────────────────────────────────────────────────────────
+  const pipelines = [];
+  for (const [ci, sig] of Object.entries(CI_SIGS)) {
+    const found = sig.files.some(f => relFileSet.has(f) || relFiles.some(r => r === f || r.startsWith(f + '/')));
+    if (found) pipelines.push(ci);
+  }
+
+  // ── Structural overview ────────────────────────────────────────────────────
+  const structure = detectStructure(rootDir, relFiles);
+
+  // ── Package metadata ───────────────────────────────────────────────────────
+  const rootPkg = readJSON(path.join(rootDir, 'package.json'));
+
+  return {
+    projectName:  path.basename(rootDir),
+    rootDir,
+    scannedAt:    new Date().toISOString(),
+    languages:    [...new Set(languages)],
+    frameworks:   [...new Set(frameworks)],
+    databases:    [...new Set(databases)],
+    cloud:        [...new Set(cloud)],
+    pipelines:    [...new Set(pipelines)],
+    structure,
+    packageMeta:  rootPkg ? { name: rootPkg.name, version: rootPkg.version, description: rootPkg.description, scripts: rootPkg.scripts } : null,
+    totalFiles:   allFiles.length,
+    envFilesFound: envFiles.map(f => path.relative(rootDir, f)),
+  };
+}
+
+function detectStructure(rootDir, relFiles) {
+  const struct = { type: 'unknown', parts: [] };
+  const hasFrontend = fileExists(rootDir, 'frontend') || fileExists(rootDir, 'client') || fileExists(rootDir, 'web');
+  const hasBackend  = fileExists(rootDir, 'backend')  || fileExists(rootDir, 'server') || fileExists(rootDir, 'api');
+  const hasMobile   = fileExists(rootDir, 'mobile')   || fileExists(rootDir, 'app')    || relFiles.some(f => f.endsWith('.dart') || f.endsWith('.swift'));
+
+  if (hasFrontend && hasBackend) { struct.type = 'Fullstack'; }
+  else if (hasFrontend)          { struct.type = 'Frontend SPA'; }
+  else if (hasBackend)           { struct.type = 'Backend API'; }
+  else if (hasMobile)            { struct.type = 'Mobile App'; }
+  else                           { struct.type = 'Monolith / Other'; }
+
+  const dirs = fs.readdirSync(rootDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && !SKIP_DIRS.has(e.name))
+    .map(e => e.name);
+  struct.parts = dirs;
+
+  // Discover key files
+  struct.entryPoints    = relFiles.filter(f => /\b(server|app|main|index)\.(js|ts|py|go|rs|java|cs|rb|php)$/.test(f) && !f.includes('node_modules'));
+  struct.testFiles      = relFiles.filter(f => /(__tests__|test|spec).*\.(test|spec)\.(js|ts|py|go|java|rb|php|rs)$/.test(f) || /\.(test|spec)\.(js|ts|py|go)$/.test(f));
+  struct.configFiles    = relFiles.filter(f => /(\.env|docker-compose|Dockerfile|\.github|Jenkinsfile|\.travis|jest\.config|tsconfig|vite\.config|next\.config|package\.json)/.test(f) && !f.includes('node_modules'));
+
+  return struct;
+}
+
+module.exports = { scan };