project-scan 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# 🔍 project-scan
+
+> **Universal Project Summarizer & Test Runner**  
+> Scan any project, detect its full stack, run all its tests, and generate beautiful reports — in one command.
+
+---
+
+## Install
+
+```bash
+# Use without installing (recommended for any project)
+npx project-scan
+
+# Install globally for permanent use
+npm install -g project-scan
+```
+
+---
+
+## Usage
+
+Run from the **root of any project**:
+
+```bash
+cd your-project
+npx project-scan
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| _(default)_ | Scan + run tests + write all reports |
+| `--scan-only` | Only scan — skip running tests |
+| `--tests-only` | Only run tests — skip scan |
+| `--html` | Also open HTML report in browser |
+| `--no-html` | Skip HTML report generation |
+| `--out <dir>` | Write reports to a custom directory |
+| `--json` | Print raw scan+test JSON to stdout |
+| `--quiet, -q` | Suppress console output |
+| `--help, -h` | Show help |
+
+### Examples
+
+```bash
+# Full scan + tests + all reports
+npx project-scan
+
+# Scan only (no test execution)
+npx project-scan --scan-only
+
+# Run tests only
+npx project-scan --tests-only
+
+# Write reports to ./docs
+npx project-scan --out ./docs
+
+# Open HTML report in browser
+npx project-scan --html
+
+# Get raw JSON output for CI pipelines
+npx project-scan --json > scan-result.json
+```
+
+---
+
+## What it generates
+
+| File | Description |
+|------|-------------|
+| `SUMMARY.md` | Quick project overview with test pass/fail status |
+| `ONBOARDING.md` | Full onboarding guide with stack breakdown + setup commands |
+| `TESTS.md` | Detailed per-suite test results with output logs |
+| `PROJECT_REPORT.html` | Visual self-contained HTML report, open in any browser |
+
+---
+
+## Supported Languages
+
+| Language | Detection |
+|----------|-----------|
+| JavaScript | `package.json`, `.js` files |
+| TypeScript | `tsconfig.json`, `.ts` files |
+| Python | `requirements.txt`, `pyproject.toml`, `.py` files |
+| Java | `pom.xml`, `build.gradle`, `.java` files |
+| Kotlin | `build.gradle.kts`, `.kt` files |
+| Go | `go.mod`, `.go` files |
+| Rust | `Cargo.toml`, `.rs` files |
+| C/C++ | `CMakeLists.txt`, `Makefile`, `.cpp/.c` files |
+| C# | `.csproj`, `.sln`, `.cs` files |
+| PHP | `composer.json`, `.php` files |
+| Ruby | `Gemfile`, `.rb` files |
+| Swift | `Package.swift`, `.swift` files |
+| Dart/Flutter | `pubspec.yaml`, `.dart` files |
+| Scala | `build.sbt`, `.scala` files |
+| Elixir | `mix.exs`, `.ex` files |
+| Shell | `.sh`, `.bash` files |
+| Terraform | `.tf`, `.tfvars` files |
+
+---
+
+## Supported Test Frameworks
+
+| Framework | Language |
+|-----------|----------|
+| **Jest** | JavaScript / TypeScript |
+| **Vitest** | JavaScript / TypeScript |
+| **Mocha** | JavaScript / TypeScript |
+| **pytest** | Python |
+| **go test** | Go |
+| **cargo test** | Rust |
+| **Maven (mvn test)** | Java / Kotlin |
+| **Gradle (./gradlew test)** | Java / Kotlin |
+| **PHPUnit** | PHP |
+| **RSpec** | Ruby |
+| **Flutter/Dart test** | Dart |
+| **dotnet test** | C# |
+
+---
+
+## Detected Databases & Storage
+
+`MongoDB` · `PostgreSQL` · `MySQL` · `SQLite` · `Redis` · `Supabase` · `Prisma` · `Firebase` · `DynamoDB` · `Elasticsearch` · `SQL Server` · `Cassandra`
+
+Detection uses: npm dependency names, `.env` key prefixes, and config file presence.
+
+---
+
+## Detected Cloud & API Services
+
+`AWS` · `Google Cloud` · `Azure` · `Vercel` · `Netlify` · `Heroku` · `Cloudflare` · `Railway` · `Render` · `ImageKit`
+
+---
+
+## Detected CI/CD Pipelines
+
+`GitHub Actions` · `GitLab CI` · `CircleCI` · `Travis CI` · `Jenkins` · `Drone` · `Bitbucket Pipelines` · `Azure Pipelines`
+
+---
+
+## Works on Any Project
+
+`project-scan` is **project-agnostic**. It works on:
+
+- ✅ Node.js / React / Next.js / Vue / Angular apps
+- ✅ Python / Django / Flask / FastAPI projects
+- ✅ Java / Spring Boot / Gradle / Maven projects
+- ✅ Go / Rust / C++ / C# projects
+- ✅ Ruby on Rails / PHP Laravel apps
+- ✅ Flutter / Dart mobile apps
+- ✅ Monorepos and multi-language projects
+- ✅ Completely empty or new projects (shows what's missing)
+
+---
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/scan.yml
+- name: Scan project
+  run: npx project-scan --tests-only --json > test-results.json
+```
+
+```bash
+# Use exit code in CI (exits 1 if any test fails)
+npx project-scan --tests-only || exit 1
+```
+
+---
+
+## License
+
+MIT

package/bin/project-scan.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * project-scan — Universal project summarizer & test runner
+ *
+ * Usage:
+ *   npx project-scan              # scan + run tests + generate all reports
+ *   npx project-scan --scan-only  # scan only, no tests
+ *   npx project-scan --tests-only # run tests only, no scan output
+ *   npx project-scan --report     # generate reports from last scan
+ *   npx project-scan --html       # also open HTML report in browser
+ *   npx project-scan --no-html    # skip HTML report
+ *   npx project-scan --out <dir>  # write reports to a custom directory
+ *   npx project-scan --help       # show help
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─── Parse flags ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const flags = {
+  scanOnly:  args.includes('--scan-only'),
+  testsOnly: args.includes('--tests-only'),
+  html:      !args.includes('--no-html'),
+  openHtml:  args.includes('--html') || args.includes('--open'),
+  help:      args.includes('--help') || args.includes('-h'),
+  quiet:     args.includes('--quiet') || args.includes('-q'),
+  json:      args.includes('--json'),
+  outDir:    (() => { const i = args.indexOf('--out'); return i !== -1 ? args[i+1] : null; })(),
+};
+
+// ─── Colors ───────────────────────────────────────────────────────────────────
+
+const isTTY = process.stdout.isTTY;
+const c = {
+  reset:  isTTY ? '\x1b[0m'  : '',
+  bold:   isTTY ? '\x1b[1m'  : '',
+  dim:    isTTY ? '\x1b[2m'  : '',
+  green:  isTTY ? '\x1b[32m' : '',
+  red:    isTTY ? '\x1b[31m' : '',
+  yellow: isTTY ? '\x1b[33m' : '',
+  cyan:   isTTY ? '\x1b[36m' : '',
+  blue:   isTTY ? '\x1b[34m' : '',
+  magenta:isTTY ? '\x1b[35m' : '',
+  white:  isTTY ? '\x1b[97m' : '',
+};
+
+function log(msg) { if (!flags.quiet) process.stdout.write(msg + '\n'); }
+function dim(msg) { log(`${c.dim}${msg}${c.reset}`); }
+function step(msg) { log(`\n${c.cyan}${c.bold}▶ ${msg}${c.reset}`); }
+function ok(msg)   { log(`  ${c.green}✔${c.reset} ${msg}`); }
+function warn(msg) { log(`  ${c.yellow}⚠${c.reset} ${msg}`); }
+function fail(msg) { log(`  ${c.red}✖${c.reset} ${msg}`); }
+function info(msg) { log(`  ${c.blue}ℹ${c.reset} ${msg}`); }
+
+// ─── Help ─────────────────────────────────────────────────────────────────────
+
+if (flags.help) {
+  console.log(`
+${c.bold}${c.cyan}project-scan${c.reset} — Universal Project Summarizer & Test Runner
+
+${c.bold}USAGE${c.reset}
+  npx project-scan [flags]
+  project-scan [flags]          (if installed globally)
+
+${c.bold}FLAGS${c.reset}
+  ${c.green}(default)${c.reset}              Scan project + run tests + write all reports
+  ${c.green}--scan-only${c.reset}            Only scan project, skip running tests
+  ${c.green}--tests-only${c.reset}           Only run tests, skip scan report
+  ${c.green}--html${c.reset}                 Open HTML report in browser after generation
+  ${c.green}--no-html${c.reset}              Skip HTML report generation
+  ${c.green}--out <dir>${c.reset}            Write reports to a custom directory (default: current dir)
+  ${c.green}--json${c.reset}                 Print raw scan+test JSON to stdout
+  ${c.green}--quiet, -q${c.reset}            Suppress console output
+  ${c.green}--help, -h${c.reset}             Show this help
+
+${c.bold}OUTPUTS${c.reset}
+  SUMMARY.md        Quick project overview with test status
+  ONBOARDING.md     Full onboarding guide with stack + setup commands
+  TESTS.md          Detailed per-suite test results
+  PROJECT_REPORT.html  Visual HTML report (open in any browser)
+
+${c.bold}SUPPORTED LANGUAGES${c.reset}
+  JavaScript · TypeScript · Python · Java · Kotlin · Go · Rust
+  C/C++ · C# · PHP · Ruby · Swift · Dart · Scala · Elixir · R · Shell
+
+${c.bold}SUPPORTED TEST FRAMEWORKS${c.reset}
+  Jest · Vitest · Mocha · pytest · Go test · Cargo test
+  Maven · Gradle · PHPUnit · RSpec · Flutter/Dart · dotnet test
+
+${c.bold}DETECTED DATABASES${c.reset}
+  MongoDB · PostgreSQL · MySQL · SQLite · Redis · Supabase
+  Prisma · Firebase · DynamoDB · Elasticsearch · SQL Server · Cassandra
+
+${c.bold}DETECTED CLOUD${c.reset}
+  AWS · Google Cloud · Azure · Vercel · Netlify · Heroku
+  Cloudflare · Railway · Render · ImageKit
+
+${c.bold}DETECTED CI/CD${c.reset}
+  GitHub Actions · GitLab CI · CircleCI · Travis CI
+  Jenkins · Drone · Bitbucket Pipelines · Azure Pipelines
+
+${c.bold}EXAMPLES${c.reset}
+  cd my-project && npx project-scan
+  npx project-scan --scan-only --out ./docs
+  npx project-scan --tests-only --json
+`);
+  process.exit(0);
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const rootDir = process.cwd();
+  const outDir  = flags.outDir ? path.resolve(rootDir, flags.outDir) : rootDir;
+
+  if (flags.outDir) {
+    fs.mkdirSync(outDir, { recursive: true });
+  }
+
+  printBanner(rootDir);
+
+  // ── 1. Scan ───────────────────────────────────────────────────────────────
+  step('Scanning project structure, languages, and stack...');
+  const { scan } = require(path.join(__dirname, '..', 'lib/scanner'));
+  const scanResult = scan(rootDir);
+
+  if (!flags.testsOnly) {
+    printScanSummary(scanResult);
+  }
+
+  // ── 2. Run tests ──────────────────────────────────────────────────────────
+  let testResults = [];
+  if (!flags.scanOnly) {
+    step('Detecting and running test suites...');
+    const { runAllTests } = require(path.join(__dirname, '..', 'lib/test-runner'));
+    testResults = runAllTests(rootDir);
+    printTestResults(testResults);
+  }
+
+  // ── 3. Generate reports ───────────────────────────────────────────────────
+  if (!flags.testsOnly || flags.scanOnly === false) {
+    step('Writing reports...');
+    const { generateSummary, generateOnboarding, generateTestsReport } = require(path.join(__dirname, '..', 'lib/md-report'));
+
+    const summaryPath    = path.join(outDir, 'SUMMARY.md');
+    const onboardPath    = path.join(outDir, 'ONBOARDING.md');
+    const testsPath      = path.join(outDir, 'TESTS.md');
+
+    fs.writeFileSync(summaryPath,  generateSummary(scanResult, testResults));
+    fs.writeFileSync(onboardPath,  generateOnboarding(scanResult));
+    fs.writeFileSync(testsPath,    generateTestsReport(scanResult, testResults));
+
+    ok(`SUMMARY.md    → ${path.relative(rootDir, summaryPath) || 'SUMMARY.md'}`);
+    ok(`ONBOARDING.md → ${path.relative(rootDir, onboardPath) || 'ONBOARDING.md'}`);
+    ok(`TESTS.md      → ${path.relative(rootDir, testsPath)   || 'TESTS.md'}`);
+
+    if (flags.html) {
+      const { generateHTML } = require(path.join(__dirname, '..', 'lib/html-report'));
+      const htmlPath = path.join(outDir, 'PROJECT_REPORT.html');
+      fs.writeFileSync(htmlPath, generateHTML(scanResult, testResults));
+      ok(`PROJECT_REPORT.html → ${path.relative(rootDir, htmlPath) || 'PROJECT_REPORT.html'}`);
+
+      if (flags.openHtml) {
+        openInBrowser(htmlPath);
+      }
+    }
+  }
+
+  // ── 4. JSON output ─────────────────────────────────────────────────────────
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ scan: scanResult, tests: testResults }, null, 2) + '\n');
+  }
+
+  // ── 5. Final status ────────────────────────────────────────────────────────
+  const totalFailed = testResults.reduce((s, r) => s + (r.failed || 0), 0);
+  const totalPassed = testResults.reduce((s, r) => s + (r.passed || 0), 0);
+
+  log('');
+  log(`${c.bold}${'─'.repeat(50)}${c.reset}`);
+  if (!flags.scanOnly && testResults.length > 0) {
+    if (totalFailed > 0) {
+      log(`${c.red}${c.bold}  ✖ ${totalFailed} test(s) failed.${c.reset}`);
+      process.exitCode = 1;
+    } else if (totalPassed > 0) {
+      log(`${c.green}${c.bold}  ✔ All ${totalPassed} tests passed.${c.reset}`);
+    } else {
+      log(`${c.yellow}${c.bold}  ○ No tests ran.${c.reset}`);
+    }
+  }
+  log(`${c.dim}  Done. Reports written to: ${outDir}${c.reset}`);
+  log('');
+}
+
+// ─── Pretty-print scan summary ────────────────────────────────────────────────
+
+function printScanSummary(r) {
+  const box = (label, items, color) => {
+    if (!items || items.length === 0) return;
+    log(`\n  ${c.bold}${color}${label}${c.reset}`);
+    items.forEach(i => log(`    ${c.dim}·${c.reset} ${i}`));
+  };
+
+  log(`\n  ${c.bold}${c.white}Project:${c.reset} ${r.projectName}  ${c.dim}(${r.structure.type})${c.reset}`);
+  log(`  ${c.dim}${r.totalFiles.toLocaleString()} files scanned · ${r.scannedAt}${c.reset}`);
+
+  box('💻  Languages',          r.languages,  c.blue);
+  box('⚙️   Frameworks',        r.frameworks, c.magenta);
+  box('🗄️   Databases',         r.databases,  c.cyan);
+  box('☁️   Cloud & APIs',       r.cloud,      c.green);
+  box('🔄  CI/CD Pipelines',    r.pipelines,  c.yellow);
+
+  if (r.structure.entryPoints?.length > 0) {
+    log(`\n  ${c.bold}${c.dim}Entry points:${c.reset}`);
+    r.structure.entryPoints.slice(0, 6).forEach(f => log(`    ${c.dim}${f}${c.reset}`));
+  }
+}
+
+// ─── Pretty-print test results ────────────────────────────────────────────────
+
+function printTestResults(results) {
+  let totalPassed = 0, totalFailed = 0, totalSkipped = 0;
+
+  for (const r of results) {
+    const icon  = r.status === 'passed' ? `${c.green}✔` : r.status === 'failed' ? `${c.red}✖` : r.status === 'error' ? `${c.yellow}⚠` : `${c.dim}○`;
+    const ms    = r.duration ? `${c.dim} (${(r.duration/1000).toFixed(2)}s)${c.reset}` : '';
+    log(`\n  ${icon}${c.reset} ${c.bold}${r.suite}${c.reset}${ms}`);
+
+    if (r.passed !== undefined)  { log(`    ${c.green}✔ ${r.passed} passed${c.reset}`);   totalPassed  += r.passed;  }
+    if (r.failed > 0)             { log(`    ${c.red}✖ ${r.failed} failed${c.reset}`);    totalFailed  += r.failed;  }
+    if (r.skipped > 0)            { log(`    ${c.dim}○ ${r.skipped} skipped${c.reset}`);  totalSkipped += r.skipped; }
+    if (r.suites)                 { log(`    ${c.dim}${r.suites}${c.reset}`); }
+    if (r.status === 'skipped' && r.output)  { warn(r.output); }
+    if (r.status === 'error'   && r.error)   { fail(r.error.slice(0, 200)); }
+
+    // Print first failed test details
+    if (r.status === 'failed' && r.output) {
+      const lines = r.output.split('\n').filter(l => l.includes('✖') || l.includes('FAIL') || l.includes('Error') || l.includes('expect'));
+      if (lines.length > 0) {
+        log(`    ${c.dim}${c.red}${lines.slice(0, 5).join('\n    ')}${c.reset}`);
+      }
+    }
+  }
+
+  log(`\n  ${c.bold}Total: ${c.green}${totalPassed} passed${c.reset} · ${c.red}${totalFailed} failed${c.reset} · ${c.dim}${totalSkipped} skipped${c.reset}`);
+}
+
+// ─── Banner ───────────────────────────────────────────────────────────────────
+
+function printBanner(rootDir) {
+  const name = path.basename(rootDir);
+  log('');
+  log(`${c.cyan}${c.bold}╔══════════════════════════════════════════════╗${c.reset}`);
+  log(`${c.cyan}${c.bold}║   🔍  project-scan  ·  Universal Analyzer    ║${c.reset}`);
+  log(`${c.cyan}${c.bold}╚══════════════════════════════════════════════╝${c.reset}`);
+  dim(`  Scanning: ${rootDir}`);
+}
+
+// ─── Open in browser ──────────────────────────────────────────────────────────
+
+function openInBrowser(filePath) {
+  const { execSync } = require('child_process');
+  const url = `file://${filePath}`;
+  try {
+    const platform = process.platform;
+    if (platform === 'darwin')  execSync(`open "${filePath}"`,       { stdio: 'ignore' });
+    else if (platform === 'win32') execSync(`start "" "${filePath}"`,{ stdio: 'ignore', shell: true });
+    else execSync(`xdg-open "${filePath}" 2>/dev/null || sensible-browser "${filePath}" 2>/dev/null || true`, { stdio: 'ignore' });
+    ok(`Opening ${url} in browser`);
+  } catch { warn(`Could not auto-open browser. Open manually: ${url}`); }
+}
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+
+main().catch(err => {
+  process.stderr.write(`\n${c.red}✖ project-scan error: ${err.message}${c.reset}\n`);
+  if (process.env.DEBUG) process.stderr.write(err.stack + '\n');
+  process.exit(1);
+});

package/lib/html-report.js

@@ -0,0 +1,174 @@
+'use strict';
+/**
+ * html-report.js — Generates a self-contained HTML report
+ * from scanner and test-runner results.
+ */
+
+function generateHTML(scanResult, testResults) {
+  const { projectName, scannedAt, languages, frameworks, databases, cloud, pipelines, structure, packageMeta, totalFiles, 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 totalTests   = totalPassed + totalFailed + totalSkipped;
+  const overallPass  = testResults.length > 0 && totalFailed === 0 && testResults.some(r => r.status !== 'skipped');
+  const overallBadge = testResults.length === 0 ? 'NO TESTS' : (overallPass ? 'ALL PASSED' : (totalFailed > 0 ? `${totalFailed} FAILED` : 'SKIPPED'));
+  const badgeColor   = overallPass ? '#22c55e' : (totalFailed > 0 ? '#ef4444' : '#94a3b8');
+
+  const pill = (text, color = '#3b82d4') =>
+    `<span style="display:inline-block;padding:2px 10px;border-radius:999px;background:${color}18;color:${color};border:1px solid ${color}40;font-size:12px;font-weight:600;margin:2px 3px 2px 0">${esc(text)}</span>`;
+
+  const sectionTitle = (t) =>
+    `<h2 style="font-size:15px;font-weight:700;margin:28px 0 10px;padding-bottom:6px;border-bottom:1px solid #e5e7eb;color:#1f2328">${t}</h2>`;
+
+  const card = (content, extra = '') =>
+    `<div style="background:#f7f8fa;border:1px solid #e5e7eb;border-radius:8px;padding:16px 18px;margin-bottom:10px${extra}">${content}</div>`;
+
+  // Test suite rows
+  const testRows = testResults.map(r => {
+    const icon   = r.status === 'passed' ? '✔' : r.status === 'failed' ? '✖' : r.status === 'error' ? '⚠' : '○';
+    const color  = r.status === 'passed' ? '#22c55e' : r.status === 'failed' ? '#ef4444' : r.status === 'error' ? '#f59e0b' : '#94a3b8';
+    const ms     = r.duration ? `${(r.duration / 1000).toFixed(2)}s` : '—';
+    const output = r.output ? `<pre style="margin:8px 0 0;padding:10px;background:#1e1e2e;color:#cdd6f4;border-radius:5px;font-size:11px;overflow-x:auto;white-space:pre-wrap;max-height:220px;overflow-y:auto">${esc(r.output.slice(-2500))}</pre>` : '';
+    const errOut = r.error ? `<pre style="margin:8px 0 0;padding:10px;background:#2a0a0a;color:#fca5a5;border-radius:5px;font-size:11px;overflow-x:auto;white-space:pre-wrap">${esc(r.error)}</pre>` : '';
+    const suitesMeta = r.suites ? `<span style="margin-left:8px;color:#57606a;font-size:12px">(${r.suites})</span>` : '';
+    return `
+    <div style="border:1px solid #e5e7eb;border-radius:7px;padding:14px 16px;margin-bottom:8px;background:#fff">
+      <div style="display:flex;align-items:center;justify-content:space-between;flex-wrap:wrap;gap:4px">
+        <span style="font-weight:600;color:#1f2328;font-size:14px">
+          <span style="color:${color};margin-right:6px;font-size:16px">${icon}</span>${esc(r.suite)}${suitesMeta}
+        </span>
+        <div style="display:flex;gap:12px;align-items:center;flex-wrap:wrap">
+          ${r.passed  !== undefined ? `<span style="color:#22c55e;font-size:12px;font-weight:700">${r.passed} passed</span>` : ''}
+          ${r.failed  !== undefined && r.failed > 0  ? `<span style="color:#ef4444;font-size:12px;font-weight:700">${r.failed} failed</span>` : ''}
+          ${r.skipped !== undefined && r.skipped > 0 ? `<span style="color:#94a3b8;font-size:12px;font-weight:700">${r.skipped} skipped</span>` : ''}
+          <span style="color:#57606a;font-size:12px">${ms}</span>
+        </div>
+      </div>
+      ${output}${errOut}
+    </div>`;
+  }).join('');
+
+  // Structure tree
+  const structureLines = structure.parts.map(p => `<li style="margin:2px 0"><code>/${p}</code></li>`).join('');
+  const entryPoints    = (structure.entryPoints || []).slice(0, 12).map(f => `<li style="margin:2px 0;color:#57606a;font-size:12px"><code>${esc(f)}</code></li>`).join('');
+  const testFilesList  = (structure.testFiles || []).slice(0, 20).map(f => `<li style="margin:2px 0;color:#57606a;font-size:12px"><code>${esc(f)}</code></li>`).join('');
+
+  const progressBar = totalTests > 0 ? `
+    <div style="background:#e5e7eb;border-radius:999px;height:10px;margin:10px 0;overflow:hidden">
+      <div style="background:#22c55e;height:100%;width:${Math.round((totalPassed/totalTests)*100)}%;display:inline-block;border-radius:999px 0 0 999px"></div>
+    </div>
+    <div style="display:flex;gap:16px;font-size:12px;color:#57606a">
+      <span>✔ <b style="color:#22c55e">${totalPassed}</b> passed</span>
+      <span>✖ <b style="color:${totalFailed>0?'#ef4444':'#94a3b8'}">${totalFailed}</b> failed</span>
+      <span>○ <b>${totalSkipped}</b> skipped</span>
+      <span style="margin-left:auto">${totalTests} total assertions</span>
+    </div>` : '';
+
+  const envSection = envFilesFound.length > 0 ? `
+    ${sectionTitle('🔒 Environment Files Found')}
+    ${card(envFilesFound.map(f => `<code style="margin-right:8px">${esc(f)}</code>`).join(''))}` : '';
+
+  const pkgSection = packageMeta ? `
+    ${sectionTitle('📦 Package Metadata')}
+    ${card(`
+      <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:8px">
+        ${packageMeta.name ? `<div><span style="color:#57606a;font-size:12px">Name</span><br><b>${esc(packageMeta.name)}</b></div>` : ''}
+        ${packageMeta.version ? `<div><span style="color:#57606a;font-size:12px">Version</span><br><b>${esc(packageMeta.version)}</b></div>` : ''}
+        ${packageMeta.description ? `<div style="grid-column:1/-1"><span style="color:#57606a;font-size:12px">Description</span><br>${esc(packageMeta.description)}</div>` : ''}
+        ${packageMeta.scripts && Object.keys(packageMeta.scripts).length > 0 ? `<div style="grid-column:1/-1"><span style="color:#57606a;font-size:12px">Scripts</span><br>${Object.keys(packageMeta.scripts).map(s => `<code style="margin-right:6px">${esc(s)}</code>`).join('')}</div>` : ''}
+      </div>
+    `)}` : '';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Project Scan — ${esc(projectName)}</title>
+<style>
+  *{box-sizing:border-box}
+  body{font-family:-apple-system,"Segoe UI",system-ui,sans-serif;font-size:14px;line-height:1.6;background:#fff;color:#1f2328;margin:0;padding:24px 16px}
+  .wrap{max-width:820px;margin:0 auto}
+  code{font-family:"SFMono-Regular",Consolas,"Liberation Mono",Menlo,monospace;font-size:12px;background:#f0f3f6;padding:1px 5px;border-radius:3px}
+  ul{margin:6px 0;padding-left:20px} li{margin:1px 0}
+  @media(max-width:600px){.grid2{grid-template-columns:1fr!important}}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+  <!-- Header -->
+  <div style="display:flex;align-items:flex-start;justify-content:space-between;flex-wrap:wrap;gap:10px;margin-bottom:24px;padding-bottom:18px;border-bottom:2px solid #e5e7eb">
+    <div>
+      <h1 style="margin:0;font-size:22px;font-weight:800;color:#1f2328">🔍 ${esc(projectName)}</h1>
+      <p style="margin:4px 0 0;color:#57606a;font-size:12px">Universal Project Scan &nbsp;·&nbsp; ${new Date(scannedAt).toLocaleString()} &nbsp;·&nbsp; ${totalFiles.toLocaleString()} files scanned</p>
+    </div>
+    <div style="text-align:right">
+      <div style="display:inline-block;padding:6px 16px;border-radius:8px;background:${badgeColor}18;border:1.5px solid ${badgeColor};color:${badgeColor};font-weight:800;font-size:14px;letter-spacing:.5px">${overallBadge}</div>
+      <div style="margin-top:4px;color:#57606a;font-size:11px">Test Status</div>
+    </div>
+  </div>
+
+  <!-- Project type -->
+  <div style="margin-bottom:20px">
+    <span style="font-size:13px;color:#57606a">Project type: </span>
+    <b style="color:#3b82d4">${esc(structure.type)}</b>
+  </div>
+
+  <!-- Stack overview grid -->
+  <div class="grid2" style="display:grid;grid-template-columns:1fr 1fr;gap:12px;margin-bottom:4px">
+
+    ${sectionTitle('💻 Languages')}
+    <div></div>
+    ${languages.length > 0 ? `<div style="grid-column:1/-1">${languages.map(l => pill(l, '#3b82d4')).join('')}</div>` : `<div style="grid-column:1/-1;color:#94a3b8">None detected</div>`}
+
+    ${sectionTitle('⚙️ Frameworks & Libraries')}
+    <div></div>
+    ${frameworks.length > 0 ? `<div style="grid-column:1/-1">${frameworks.map(f => pill(f, '#7c5cd8')).join('')}</div>` : `<div style="grid-column:1/-1;color:#94a3b8">None detected</div>`}
+
+    ${sectionTitle('🗄️ Databases & Storage')}
+    <div></div>
+    ${databases.length > 0 ? `<div style="grid-column:1/-1">${databases.map(d => pill(d, '#0891b2')).join('')}</div>` : `<div style="grid-column:1/-1;color:#94a3b8">None detected</div>`}
+
+    ${sectionTitle('☁️ Cloud & API Services')}
+    <div></div>
+    ${cloud.length > 0 ? `<div style="grid-column:1/-1">${cloud.map(c => pill(c, '#059669')).join('')}</div>` : `<div style="grid-column:1/-1;color:#94a3b8">None detected</div>`}
+
+    ${sectionTitle('🔄 CI/CD Pipelines')}
+    <div></div>
+    ${pipelines.length > 0 ? `<div style="grid-column:1/-1">${pipelines.map(p => pill(p, '#d97706')).join('')}</div>` : `<div style="grid-column:1/-1;color:#94a3b8">None detected</div>`}
+
+  </div>
+
+  <!-- Structure -->
+  ${sectionTitle('📁 Project Structure')}
+  <div style="display:grid;grid-template-columns:1fr 1fr 1fr;gap:10px">
+    ${card(`<b style="font-size:12px;color:#57606a;display:block;margin-bottom:6px">TOP-LEVEL DIRECTORIES</b><ul>${structureLines || '<li style="color:#94a3b8">None</li>'}</ul>`)}
+    ${card(`<b style="font-size:12px;color:#57606a;display:block;margin-bottom:6px">ENTRY POINTS</b><ul>${entryPoints || '<li style="color:#94a3b8">None found</li>'}</ul>`)}
+    ${card(`<b style="font-size:12px;color:#57606a;display:block;margin-bottom:6px">TEST FILES (${(structure.testFiles||[]).length})</b><ul>${testFilesList || '<li style="color:#94a3b8">None found</li>'}</ul>`)}
+  </div>
+
+  ${pkgSection}
+  ${envSection}
+
+  <!-- Test Results -->
+  ${sectionTitle('🧪 Test Results')}
+  ${progressBar}
+  <div style="margin-top:12px">${testRows || `<div style="color:#94a3b8;padding:16px 0">No test results available.</div>`}</div>
+
+  <!-- Footer -->
+  <div style="margin-top:40px;padding-top:12px;border-top:1px solid #e5e7eb;text-align:center;color:#94a3b8;font-size:11px">
+    Generated by <b>project-scan</b> &nbsp;·&nbsp; <a href="https://github.com" style="color:#3b82d4">npm i -g project-scan</a>
+  </div>
+
+</div>
+</body>
+</html>`;
+}
+
+function esc(str) {
+  return String(str || '').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');
+}
+
+module.exports = { generateHTML };