@vasanth-mv/pqs-cli 1.1.0

package/bin/pqs.entry.js

@@ -0,0 +1,693 @@
+/**
+ * pqs — Code Quality Studio CLI
+ * Entry point bundled by build.mjs → dist/pqs.js
+ */
+import { readFileSync, readdirSync, statSync, existsSync, writeFileSync } from "fs";
+import { resolve, extname, basename, relative, join } from "path";
+import { tmpdir } from "os";
+import { execSync } from "child_process";
+import process from "process";
+
+/* global __PQS_VERSION__ */
+const PQS_VERSION = typeof __PQS_VERSION__ !== "undefined" ? __PQS_VERSION__ : "1.0.0";
+
+// ── Analyzers (imported directly — bypass localStorage in index.js) ──────────
+import { analysePlaywright }           from "../../src/analyzers/playwright.js";
+import { analyseJavaApiLocally }       from "../../src/analyzers/javaApi.js";
+import { analyseTypeScriptLocally }    from "../../src/analyzers/typescript.js";
+import { analysePlaywrightJavaLocally }   from "../../src/analyzers/playwrightJava.js";
+import { analysePlaywrightPythonLocally } from "../../src/analyzers/playwrightPython.js";
+import { analyseTsFrontendLocally }    from "../../src/analyzers/tsFrontend.js";
+import { analysePythonApiLocally }     from "../../src/analyzers/pythonApi.js";
+import { analysePythonFrontendLocally }from "../../src/analyzers/pythonFrontend.js";
+import { analyseJavaCoreLocally }      from "../../src/analyzers/javaCore.js";
+import { analyseRestAssuredLocally }   from "../../src/analyzers/restAssured.js";
+import { analyseKarateLocally }        from "../../src/analyzers/karate.js";
+import { analysePytestApiLocally }     from "../../src/analyzers/pytestApi.js";
+import { analysePostmanLocally }       from "../../src/analyzers/postman.js";
+import { analyseSeleniumJavaLocally }  from "../../src/analyzers/seleniumJava.js";
+import { analyseSeleniumCsharpLocally }from "../../src/analyzers/seleniumCsharp.js";
+import { analyseCypressLocally }       from "../../src/analyzers/cypress.js";
+import { analyseAppiumJavaLocally }    from "../../src/analyzers/appiumJava.js";
+import { analyseToscaXmlLocally }      from "../../src/analyzers/toscaXml.js";
+import { AUDIT_STACKS }                from "../../src/stacks/definitions.js";
+
+// ── Runner map ────────────────────────────────────────────────────────────────
+const RUNNERS = {
+  playwright:        analysePlaywright,
+  java_api:          analyseJavaApiLocally,
+  typescript:        analyseTypeScriptLocally,
+  playwright_java:   analysePlaywrightJavaLocally,
+  playwright_python: analysePlaywrightPythonLocally,
+  ts_frontend:       analyseTsFrontendLocally,
+  python_api:        analysePythonApiLocally,
+  python_frontend:   analysePythonFrontendLocally,
+  java_frontend:     analyseJavaCoreLocally,
+  restassured:       analyseRestAssuredLocally,
+  karate:            analyseKarateLocally,
+  pytest_api:        analysePytestApiLocally,
+  postman:           analysePostmanLocally,
+  selenium_java:     analyseSeleniumJavaLocally,
+  selenium_csharp:   analyseSeleniumCsharpLocally,
+  cypress:           analyseCypressLocally,
+  appium_java:       analyseAppiumJavaLocally,
+  tosca_xml:         analyseToscaXmlLocally,
+};
+
+// ── ANSI colours ─────────────────────────────────────────────────────────────
+let useColor = process.stdout.isTTY !== false;
+const C = {
+  reset:   () => useColor ? "\x1b[0m"  : "",
+  bold:    () => useColor ? "\x1b[1m"  : "",
+  dim:     () => useColor ? "\x1b[2m"  : "",
+  red:     () => useColor ? "\x1b[31m" : "",
+  yellow:  () => useColor ? "\x1b[33m" : "",
+  blue:    () => useColor ? "\x1b[34m" : "",
+  cyan:    () => useColor ? "\x1b[36m" : "",
+  green:   () => useColor ? "\x1b[32m" : "",
+  magenta: () => useColor ? "\x1b[35m" : "",
+  gray:    () => useColor ? "\x1b[90m" : "",
+  bgRed:   () => useColor ? "\x1b[41m" : "",
+};
+const b  = (s) => `${C.bold()}${s}${C.reset()}`;
+const dim = (s) => `${C.dim()}${s}${C.reset()}`;
+
+// ── Arg parser ────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = { paths: [], stack: null, severity: "all", category: null, output: "pretty", help: false, listStacks: false, readReport: null, open: false };
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h")        { args.help = true; }
+    else if (a === "--list-stacks")          { args.listStacks = true; }
+    else if (a === "--no-color")             { useColor = false; }
+    else if ((a === "--stack" || a === "-s") && argv[i+1])  { args.stack = argv[++i]; }
+    else if ((a === "--severity" || a === "-S") && argv[i+1]) { args.severity = argv[++i]; }
+    else if ((a === "--category" || a === "-c") && argv[i+1]) { args.category = argv[++i]; }
+    else if ((a === "--output" || a === "-o") && argv[i+1])   { args.output = argv[++i]; }
+    else if ((a === "--read-report" || a === "-r") && argv[i+1]) { args.readReport = argv[++i]; }
+    else if (a === "--open")                 { args.open = true; }
+    else if (!a.startsWith("-"))             { args.paths.push(a); }
+    i++;
+  }
+  return args;
+}
+
+// ── File collector ────────────────────────────────────────────────────────────
+function collectFiles(inputPath, stackId) {
+  const pattern = AUDIT_STACKS[stackId]?.filePattern;
+  const abs = resolve(inputPath);
+  if (!existsSync(abs)) { console.error(`  Path not found: ${abs}`); process.exit(1); }
+  const stat = statSync(abs);
+  if (stat.isFile()) return [abs];
+
+  const out = [];
+  function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") walk(full);
+      else if (entry.isFile() && (!pattern || pattern.test(entry.name))) out.push(full);
+    }
+  }
+  walk(abs);
+  return out;
+}
+
+// ── Auto-detect stack ─────────────────────────────────────────────────────────
+function detectStack(files) {
+  // Score each stack by how many files match its pattern
+  const scores = {};
+  for (const [id, stack] of Object.entries(AUDIT_STACKS)) {
+    if (!stack.filePattern) continue;
+    scores[id] = files.filter(f => stack.filePattern.test(basename(f))).length;
+  }
+  const best = Object.entries(scores).sort((a, b) => b[1] - a[1])[0];
+  return best && best[1] > 0 ? best[0] : "playwright";
+}
+
+// ── Grade helper ──────────────────────────────────────────────────────────────
+function grade(score) {
+  if (score >= 90) return { letter: "A", color: C.green() };
+  if (score >= 75) return { letter: "B", color: C.cyan() };
+  if (score >= 60) return { letter: "C", color: C.yellow() };
+  if (score >= 40) return { letter: "D", color: C.magenta() };
+  return { letter: "F", color: C.red() };
+}
+
+// ── Severity badge ────────────────────────────────────────────────────────────
+function sevBadge(sev) {
+  if (sev === "critical") return `${C.bold()}${C.red()} CRIT ${C.reset()}`;
+  if (sev === "warning")  return `${C.bold()}${C.yellow()} WARN ${C.reset()}`;
+  return `${C.blue()} INFO ${C.reset()}`;
+}
+
+// ── Help text ─────────────────────────────────────────────────────────────────
+function printHelp() {
+  console.log(`
+${b("pqs")} — Code Quality Studio CLI  ${dim(`v${PQS_VERSION}`)}
+
+${b("USAGE")}
+  pqs [path...]                   Analyse files/folders (defaults to current directory)
+  pqs --list-stacks               List all available stacks
+  pqs --read-report <file>        Print summary of a saved JSON report
+
+${b("OPTIONS")}
+  -s, --stack  <id>               Force a stack (see --list-stacks for IDs)
+  -S, --severity <level>          Filter findings: all | critical | warning | info
+  -c, --category <id>             Filter by category id
+  -o, --output  <fmt>             Output format: pretty | json | summary
+  -r, --read-report <file>        Read a saved JSON report and print summary
+      --open                      Open the HTML report in the browser after analysis
+      --no-color                  Disable ANSI colours
+  -h, --help                      Show this help
+
+${b("EXAMPLES")}
+  pqs ./tests/
+  pqs ./tests/ --stack cypress --severity critical
+  pqs ./tests/ --output json > report.json
+  pqs ./tests/ --open                          # run + open HTML in browser
+  pqs --read-report report.json --open         # open saved report in browser
+  pqs ./e2e/ -s selenium_java -S warning
+  pqs . --list-stacks
+`);
+}
+
+// ── List stacks ───────────────────────────────────────────────────────────────
+function printStacks() {
+  console.log(`\n${b("Available stacks")}\n`);
+  const groups = {};
+  for (const [id, s] of Object.entries(AUDIT_STACKS)) {
+    if (!groups[s.group]) groups[s.group] = [];
+    groups[s.group].push({ id, s });
+  }
+  for (const [group, items] of Object.entries(groups)) {
+    console.log(`  ${C.cyan()}${C.bold()}${group}${C.reset()}`);
+    for (const { id, s } of items) {
+      console.log(`    ${C.bold()}${id.padEnd(20)}${C.reset()} ${s.icon} ${s.name}  ${dim(s.fileAccept)}`);
+    }
+    console.log();
+  }
+}
+
+// ── Pretty output ─────────────────────────────────────────────────────────────
+function printPretty(stackId, results, args) {
+  const stack = AUDIT_STACKS[stackId];
+  const allFindings = results.flatMap(r => r.result.findings ?? []);
+  const shown = allFindings.filter(f =>
+    (args.severity === "all" || f.severity === args.severity) &&
+    (!args.category || f.category === args.category)
+  );
+
+  const crit = allFindings.filter(f => f.severity === "critical").length;
+  const warn = allFindings.filter(f => f.severity === "warning").length;
+  const info = allFindings.filter(f => f.severity === "info").length;
+  const avgScore = results.length
+    ? Math.round(results.reduce((s, r) => s + (r.result.overallScore ?? 0), 0) / results.length)
+    : 0;
+  const { letter, color: gc } = grade(avgScore);
+
+  console.log();
+  console.log(`${C.cyan()}${C.bold()}  Code Quality Studio${C.reset()}  ${dim("─")} ${stack.icon} ${b(stack.name)}`);
+  console.log(`  ${dim("─".repeat(52))}`);
+  console.log(`  Files analysed : ${b(String(results.length))}`);
+  console.log(`  Overall score  : ${gc}${C.bold()}${avgScore}/100  Grade ${letter}${C.reset()}`);
+  console.log(`  Findings       : ${C.red()}${C.bold()}${crit} critical${C.reset()}  ${C.yellow()}${warn} warning${C.reset()}  ${C.blue()}${info} info${C.reset()}`);
+  console.log(`  ${dim("─".repeat(52))}`);
+
+  // Per-file summary
+  console.log(`\n${b("  FILES")}\n`);
+  for (const { file, result } of results) {
+    const g = grade(result.overallScore ?? 0);
+    const fc = result.findings.filter(f => f.severity === "critical").length;
+    const fw = result.findings.filter(f => f.severity === "warning").length;
+    const fi = result.findings.filter(f => f.severity === "info").length;
+    const fname = basename(file);
+    const badge = `${g.color}${C.bold()}${(result.overallScore ?? 0).toString().padStart(3)}${C.reset()}`;
+    const counts = [
+      fc ? `${C.red()}${fc}c${C.reset()}` : null,
+      fw ? `${C.yellow()}${fw}w${C.reset()}` : null,
+      fi ? `${C.blue()}${fi}i${C.reset()}` : null,
+    ].filter(Boolean).join(" ");
+    console.log(`  ${badge}  ${fname.padEnd(40)} ${counts || dim("clean")}`);
+  }
+
+  if (shown.length === 0) {
+    console.log(`\n  ${C.green()}${C.bold()}✓ No findings match the current filter.${C.reset()}\n`);
+    return;
+  }
+
+  // Findings grouped by file
+  const byFile = {};
+  for (const f of shown) {
+    if (!byFile[f._file]) byFile[f._file] = [];
+    byFile[f._file].push(f);
+  }
+
+  console.log(`\n${b("  FINDINGS")}  ${dim(`(${shown.length} shown)`)}\n`);
+
+  for (const [file, findings] of Object.entries(byFile)) {
+    const fname = basename(file);
+    console.log(`  ${C.cyan()}${C.bold()}${fname}${C.reset()}  ${dim(relative(process.cwd(), file))}`);
+
+    // Group by severity for clean display
+    for (const sev of ["critical", "warning", "info"]) {
+      const sevFindings = findings.filter(f => f.severity === sev);
+      if (!sevFindings.length) continue;
+      for (const f of sevFindings) {
+        const lineRef = f.line ? `${C.gray()}:${f.line}${C.reset()}` : "";
+        const ruleTag = dim(`[${f.ruleId}]`);
+        console.log(`    ${sevBadge(sev)} ${b(f.title)} ${ruleTag}${lineRef}`);
+        console.log(`           ${dim(f.description)}`);
+        if (f.fix && !f.fix.includes("\n")) {
+          console.log(`           ${C.green()}Fix:${C.reset()} ${dim(f.fix)}`);
+        }
+        console.log();
+      }
+    }
+  }
+
+  // Category score summary
+  if (results.length === 1 && results[0].result.categoryScores) {
+    const cats = stack.categories ?? [];
+    console.log(`  ${b("CATEGORY SCORES")}\n`);
+    for (const cat of cats) {
+      const s = results[0].result.categoryScores[cat.id] ?? 100;
+      const { letter: gl } = grade(s);
+      const bar = "█".repeat(Math.round(s / 10)).padEnd(10, "░");
+      const gc2 = grade(s);
+      console.log(`  ${gc2.color}${bar}${C.reset()} ${s.toString().padStart(3)}  ${cat.icon} ${cat.label}`);
+    }
+    console.log();
+  }
+}
+
+// ── Summary output ────────────────────────────────────────────────────────────
+function printSummary(stackId, results) {
+  const stack = AUDIT_STACKS[stackId];
+  const allFindings = results.flatMap(r => r.result.findings ?? []);
+  const crit = allFindings.filter(f => f.severity === "critical").length;
+  const warn = allFindings.filter(f => f.severity === "warning").length;
+  const avgScore = results.length
+    ? Math.round(results.reduce((s, r) => s + (r.result.overallScore ?? 0), 0) / results.length)
+    : 0;
+  console.log(`pqs ${stack.icon} ${stack.name} · ${results.length} files · score ${avgScore} · ${crit} critical · ${warn} warning`);
+  if (crit > 0) process.exitCode = 1;
+}
+
+// ── JSON output ───────────────────────────────────────────────────────────────
+function printJson(stackId, results, args) {
+  const stack = AUDIT_STACKS[stackId];
+  const allFindings = results.flatMap(r => r.result.findings ?? []).filter(f =>
+    (args.severity === "all" || f.severity === args.severity) &&
+    (!args.category || f.category === args.category)
+  );
+  console.log(JSON.stringify({
+    stack: { id: stackId, name: stack.name },
+    files: results.length,
+    avgScore: results.length
+      ? Math.round(results.reduce((s, r) => s + (r.result.overallScore ?? 0), 0) / results.length)
+      : 0,
+    summary: {
+      critical: allFindings.filter(f => f.severity === "critical").length,
+      warning:  allFindings.filter(f => f.severity === "warning").length,
+      info:     allFindings.filter(f => f.severity === "info").length,
+    },
+    results: results.map(({ file, result }) => ({
+      file,
+      overallScore: result.overallScore,
+      categoryScores: result.categoryScores,
+      findings: result.findings.filter(f =>
+        (args.severity === "all" || f.severity === args.severity) &&
+        (!args.category || f.category === args.category)
+      ),
+    })),
+  }, null, 2));
+}
+
+// ── HTML Report Generator ─────────────────────────────────────────────────────
+function buildHtmlReport(report) {
+  const { stack, files, avgScore, summary, results = [] } = report;
+  const gradeColor = avgScore >= 90 ? "#16a34a" : avgScore >= 75 ? "#0891b2" : avgScore >= 60 ? "#d97706" : "#dc2626";
+  const gradeLetter = avgScore >= 90 ? "A" : avgScore >= 75 ? "B" : avgScore >= 60 ? "C" : avgScore >= 40 ? "D" : "F";
+
+  // Top files by critical count
+  const sortedFiles = [...results].sort((a, b) => {
+    const ac = (a.findings ?? []).filter(f => f.severity === "critical").length;
+    const bc = (b.findings ?? []).filter(f => f.severity === "critical").length;
+    return bc - ac;
+  });
+
+  // Top rules
+  const ruleCounts = {};
+  for (const r of results) {
+    for (const f of (r.findings ?? [])) {
+      if (!ruleCounts[f.ruleId]) ruleCounts[f.ruleId] = { count: 0, title: f.title, sev: f.severity };
+      ruleCounts[f.ruleId].count++;
+    }
+  }
+  const topRules = Object.entries(ruleCounts).sort((a, b) => b[1].count - a[1].count).slice(0, 10);
+
+  // Category averages
+  const catTotals = {}; const catCounts2 = {};
+  for (const r of results) {
+    for (const [cat, score] of Object.entries(r.categoryScores ?? {})) {
+      catTotals[cat] = (catTotals[cat] ?? 0) + score;
+      catCounts2[cat] = (catCounts2[cat] ?? 0) + 1;
+    }
+  }
+  const catAvgs = Object.entries(catTotals)
+    .map(([cat, total]) => ({ cat, avg: Math.round(total / catCounts2[cat]) }))
+    .sort((a, b) => a.avg - b.avg);
+
+  const sevColor = sev => sev === "critical" ? "#dc2626" : sev === "warning" ? "#d97706" : "#2563eb";
+  const sevBg = sev => sev === "critical" ? "#fef2f2" : sev === "warning" ? "#fffbeb" : "#eff6ff";
+  const scoreCol = s => s >= 90 ? "#16a34a" : s >= 75 ? "#0891b2" : s >= 60 ? "#d97706" : "#dc2626";
+
+  const filesHtml = sortedFiles.map(r => {
+    const fc = (r.findings ?? []).filter(f => f.severity === "critical").length;
+    const fw = (r.findings ?? []).filter(f => f.severity === "warning").length;
+    const fi = (r.findings ?? []).filter(f => f.severity === "info").length;
+    const sc = r.overallScore ?? 0;
+    const fname = basename(r.file ?? "");
+    const findingsHtml = (r.findings ?? []).map(f => `
+      <div style="padding:8px 12px;border-bottom:1px solid #f1f5f9;display:flex;gap:10px;align-items:flex-start">
+        <span style="background:${sevBg(f.severity)};color:${sevColor(f.severity)};font-size:10px;font-weight:700;padding:2px 6px;border-radius:4px;white-space:nowrap;margin-top:2px">${f.severity.toUpperCase().slice(0,4)}</span>
+        <div>
+          <div style="font-weight:600;font-size:13px;color:#1e293b">${f.title ?? ""} <span style="font-size:11px;color:#94a3b8;font-weight:400">[${f.ruleId ?? ""}]${f.line ? ` :${f.line}` : ""}</span></div>
+          <div style="font-size:12px;color:#64748b;margin-top:2px">${f.description ?? ""}</div>
+          ${f.fix ? `<div style="font-size:11px;color:#059669;margin-top:3px">💡 ${f.fix}</div>` : ""}
+        </div>
+      </div>`).join("");
+    return `
+    <details style="border:1px solid #e2e8f0;border-radius:8px;margin-bottom:8px;overflow:hidden">
+      <summary style="padding:12px 16px;cursor:pointer;display:flex;align-items:center;gap:12px;background:#f8fafc;list-style:none;user-select:none">
+        <span style="background:${scoreCol(sc)};color:#fff;font-weight:700;font-size:13px;padding:3px 10px;border-radius:6px;min-width:36px;text-align:center">${sc}</span>
+        <span style="font-weight:600;font-size:14px;color:#1e293b;flex:1">${fname}</span>
+        ${fc ? `<span style="background:#fef2f2;color:#dc2626;font-size:12px;font-weight:700;padding:2px 8px;border-radius:4px">${fc} critical</span>` : ""}
+        ${fw ? `<span style="background:#fffbeb;color:#d97706;font-size:12px;font-weight:700;padding:2px 8px;border-radius:4px">${fw} warn</span>` : ""}
+        ${fi ? `<span style="background:#eff6ff;color:#2563eb;font-size:12px;font-weight:700;padding:2px 8px;border-radius:4px">${fi} info</span>` : ""}
+      </summary>
+      <div style="font-size:11px;color:#94a3b8;padding:4px 16px;background:#f8fafc;border-bottom:1px solid #e2e8f0">${r.file ?? ""}</div>
+      ${findingsHtml || `<div style="padding:12px 16px;color:#64748b;font-size:13px">✓ No findings</div>`}
+    </details>`;
+  }).join("");
+
+  const rulesHtml = topRules.map(([ruleId, info]) => `
+    <tr>
+      <td style="padding:8px 12px;font-weight:700;color:${sevColor(info.sev)};font-size:18px">${info.count}</td>
+      <td style="padding:8px 12px;font-family:monospace;font-size:12px;color:#64748b">${ruleId}</td>
+      <td style="padding:8px 12px;font-size:13px;color:#1e293b">${info.title}</td>
+      <td style="padding:8px 12px"><span style="background:${sevBg(info.sev)};color:${sevColor(info.sev)};font-size:11px;font-weight:700;padding:2px 6px;border-radius:4px">${info.sev}</span></td>
+    </tr>`).join("");
+
+  const catsHtml = catAvgs.map(({ cat, avg }) => {
+    const pct = avg;
+    const col = scoreCol(avg);
+    return `
+    <div style="display:flex;align-items:center;gap:12px;margin-bottom:8px">
+      <div style="width:110px;font-size:12px;color:#64748b;text-align:right">${cat}</div>
+      <div style="flex:1;background:#e2e8f0;border-radius:4px;height:12px;overflow:hidden">
+        <div style="width:${pct}%;background:${col};height:100%;border-radius:4px;transition:width .3s"></div>
+      </div>
+      <div style="width:36px;font-weight:700;font-size:13px;color:${col}">${avg}</div>
+    </div>`;
+  }).join("");
+
+  const now = new Date().toLocaleString();
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>pqs Report — ${stack?.name ?? "Code Quality"}</title>
+<style>
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#f1f5f9;color:#1e293b;min-height:100vh}
+  .header{background:linear-gradient(135deg,#0f172a 0%,#1e293b 100%);color:#fff;padding:32px 40px}
+  .header h1{font-size:28px;font-weight:800;letter-spacing:-0.5px}
+  .header .sub{font-size:14px;color:#94a3b8;margin-top:4px}
+  .stats{display:flex;gap:16px;margin-top:24px;flex-wrap:wrap}
+  .stat{background:rgba(255,255,255,0.07);border:1px solid rgba(255,255,255,0.1);border-radius:10px;padding:16px 24px;min-width:140px}
+  .stat .val{font-size:32px;font-weight:800;line-height:1}
+  .stat .lbl{font-size:12px;color:#94a3b8;margin-top:4px;text-transform:uppercase;letter-spacing:.5px}
+  .body{max-width:1200px;margin:0 auto;padding:32px 24px}
+  .section{background:#fff;border-radius:12px;box-shadow:0 1px 3px rgba(0,0,0,.08);margin-bottom:24px;overflow:hidden}
+  .section-head{padding:16px 20px;border-bottom:1px solid #f1f5f9;font-weight:700;font-size:15px;color:#0f172a;display:flex;align-items:center;gap:8px}
+  .section-body{padding:20px}
+  table{width:100%;border-collapse:collapse}
+  tr:hover{background:#f8fafc}
+  details>summary::-webkit-details-marker{display:none}
+  @media(max-width:600px){.stats{gap:10px}.stat{min-width:120px;padding:12px 16px}}
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>⚡ pqs Code Quality Report</h1>
+  <div class="sub">${stack?.name ?? ""} &nbsp;·&nbsp; Generated ${now} &nbsp;·&nbsp; pqs v${PQS_VERSION}</div>
+  <div class="stats">
+    <div class="stat"><div class="val" style="color:${gradeColor}">${avgScore}<span style="font-size:18px;margin-left:4px">${gradeLetter}</span></div><div class="lbl">Overall Score</div></div>
+    <div class="stat"><div class="val">${files}</div><div class="lbl">Files Analysed</div></div>
+    <div class="stat"><div class="val" style="color:#dc2626">${summary.critical}</div><div class="lbl">Critical</div></div>
+    <div class="stat"><div class="val" style="color:#d97706">${summary.warning}</div><div class="lbl">Warning</div></div>
+    <div class="stat"><div class="val" style="color:#2563eb">${summary.info}</div><div class="lbl">Info</div></div>
+  </div>
+</div>
+
+<div class="body">
+
+  ${catAvgs.length ? `
+  <div class="section">
+    <div class="section-head">📊 Category Scores</div>
+    <div class="section-body">${catsHtml}</div>
+  </div>` : ""}
+
+  <div class="section">
+    <div class="section-head">🔴 Top Rule Violations</div>
+    <div class="section-body" style="padding:0">
+      <table>
+        <thead><tr style="background:#f8fafc;font-size:11px;text-transform:uppercase;color:#64748b">
+          <th style="padding:8px 12px;text-align:left">Count</th>
+          <th style="padding:8px 12px;text-align:left">Rule ID</th>
+          <th style="padding:8px 12px;text-align:left">Description</th>
+          <th style="padding:8px 12px;text-align:left">Severity</th>
+        </tr></thead>
+        <tbody>${rulesHtml}</tbody>
+      </table>
+    </div>
+  </div>
+
+  <div class="section">
+    <div class="section-head">📁 Files &nbsp;<span style="font-size:12px;color:#94a3b8;font-weight:400">click a file to expand findings</span></div>
+    <div class="section-body">${filesHtml}</div>
+  </div>
+
+</div>
+</body>
+</html>`;
+}
+
+function openHtmlReport(htmlContent) {
+  const tmp = join(tmpdir(), `pqs-report-${Date.now()}.html`);
+  writeFileSync(tmp, htmlContent, "utf8");
+  const cmd = process.platform === "win32" ? `start "" "${tmp}"` :
+               process.platform === "darwin" ? `open "${tmp}"` : `xdg-open "${tmp}"`;
+  try { execSync(cmd); } catch { /* ignore */ }
+  console.log(`\n  ${dim("HTML report:")} ${tmp}\n`);
+  return tmp;
+}
+
+// ── Read Report Summary ───────────────────────────────────────────────────────
+function printReportSummary(filePath) {
+  const abs = resolve(filePath);
+  if (!existsSync(abs)) {
+    console.error(`  Report file not found: ${abs}`);
+    process.exit(1);
+  }
+  let report;
+  try { report = JSON.parse(readFileSync(abs, "utf8")); }
+  catch { console.error(`  Could not parse JSON: ${abs}`); process.exit(1); }
+
+  const { stack, files, avgScore, summary, results = [] } = report;
+  const { letter, color: gc } = grade(avgScore);
+
+  console.log();
+  console.log(`${C.cyan()}${C.bold()}  Code Quality Studio${C.reset()}  ${dim("─")}  ${b("Report Summary")}`);
+  console.log(`  ${dim("─".repeat(52))}`);
+  console.log(`  Stack          : ${b(stack?.name ?? stack?.id ?? "unknown")}`);
+  console.log(`  Files analysed : ${b(String(files))}`);
+  console.log(`  Overall score  : ${gc}${C.bold()}${avgScore}/100  Grade ${letter}${C.reset()}`);
+  console.log(`  Findings       : ${C.red()}${C.bold()}${summary.critical} critical${C.reset()}  ${C.yellow()}${summary.warning} warning${C.reset()}  ${C.blue()}${summary.info} info${C.reset()}`);
+  console.log(`  ${dim("─".repeat(52))}`);
+
+  // ── Top 10 worst files ────────────────────────────────────────────────────
+  const sorted = [...results].sort((a, b) => {
+    const ac = (a.findings ?? []).filter(f => f.severity === "critical").length;
+    const bc = (b.findings ?? []).filter(f => f.severity === "critical").length;
+    return bc - ac || (a.overallScore ?? 0) - (b.overallScore ?? 0);
+  });
+
+  console.log(`\n${b("  TOP FILES BY CRITICAL FINDINGS")}\n`);
+  const top = sorted.filter(r => (r.findings ?? []).some(f => f.severity === "critical")).slice(0, 10);
+  if (top.length === 0) {
+    console.log(`  ${C.green()}${C.bold()}✓ No critical findings in any file!${C.reset()}`);
+  } else {
+    for (const r of top) {
+      const fc = (r.findings ?? []).filter(f => f.severity === "critical").length;
+      const fw = (r.findings ?? []).filter(f => f.severity === "warning").length;
+      const { color: sc } = grade(r.overallScore ?? 0);
+      const fname = basename(r.file ?? "unknown");
+      console.log(`  ${sc}${C.bold()}${(r.overallScore ?? 0).toString().padStart(3)}${C.reset()}  ${fname.padEnd(45)} ${C.red()}${fc}c${C.reset()} ${C.yellow()}${fw}w${C.reset()}`);
+    }
+  }
+
+  // ── Top recurring rule violations ─────────────────────────────────────────
+  const ruleCounts = {};
+  for (const r of results) {
+    for (const f of (r.findings ?? [])) {
+      if (f.severity === "critical") {
+        ruleCounts[f.ruleId] = ruleCounts[f.ruleId] ?? { count: 0, title: f.title, sev: f.severity };
+        ruleCounts[f.ruleId].count++;
+      }
+    }
+  }
+  const topRules = Object.entries(ruleCounts).sort((a, b) => b[1].count - a[1].count).slice(0, 8);
+
+  if (topRules.length > 0) {
+    console.log(`\n${b("  TOP CRITICAL RULES  (most violations)")}\n`);
+    for (const [ruleId, info] of topRules) {
+      console.log(`  ${C.red()}${C.bold()}${String(info.count).padStart(4)}x${C.reset()}  ${dim(`[${ruleId}]`)}  ${info.title}`);
+    }
+  }
+
+  // ── Category score breakdown ──────────────────────────────────────────────
+  const catTotals = {};
+  const catCounts = {};
+  for (const r of results) {
+    if (!r.categoryScores) continue;
+    for (const [cat, score] of Object.entries(r.categoryScores)) {
+      catTotals[cat] = (catTotals[cat] ?? 0) + score;
+      catCounts[cat] = (catCounts[cat] ?? 0) + 1;
+    }
+  }
+  const catAvgs = Object.entries(catTotals)
+    .map(([cat, total]) => ({ cat, avg: Math.round(total / catCounts[cat]) }))
+    .sort((a, b) => a.avg - b.avg);
+
+  if (catAvgs.length > 0) {
+    console.log(`\n${b("  CATEGORY AVERAGES")}\n`);
+    for (const { cat, avg } of catAvgs) {
+      const bar = "█".repeat(Math.round(avg / 10)).padEnd(10, "░");
+      const gc2 = grade(avg);
+      console.log(`  ${gc2.color}${bar}${C.reset()} ${avg.toString().padStart(3)}  ${cat}`);
+    }
+  }
+
+  console.log();
+  console.log(`  ${dim(`Report: ${abs}`)}`);
+  console.log();
+  return report;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help)       { printHelp();   process.exit(0); }
+  if (args.listStacks) { printStacks(); process.exit(0); }
+  if (args.readReport) {
+    const report = printReportSummary(args.readReport);
+    if (args.open && report) openHtmlReport(buildHtmlReport(report));
+    process.exit(0);
+  }
+
+  const inputPaths = args.paths.length ? args.paths : ["."];
+
+  // Collect all files first (for stack auto-detection)
+  let allFiles = inputPaths.flatMap(p => {
+    try { return collectFiles(p, args.stack ?? "playwright"); }
+    catch { return []; }
+  });
+
+  // Determine stack
+  let stackId = args.stack;
+  if (!stackId) {
+    stackId = detectStack(allFiles);
+    if (args.output === "pretty") {
+      console.log(`${dim(`  Auto-detected stack: ${stackId}`)}`);
+    }
+  }
+  if (!RUNNERS[stackId]) {
+    console.error(`Unknown stack: "${stackId}". Run pqs --list-stacks for valid IDs.`);
+    process.exit(1);
+  }
+
+  // Re-collect with the correct stack file pattern
+  allFiles = inputPaths.flatMap(p => {
+    try { return collectFiles(p, stackId); }
+    catch { return []; }
+  });
+
+  if (allFiles.length === 0) {
+    const stack = AUDIT_STACKS[stackId];
+    console.error(`  No ${stack.fileAccept} files found in: ${inputPaths.join(", ")}`);
+    process.exit(1);
+  }
+
+  // Run analysis
+  const runner = RUNNERS[stackId];
+  const results = [];
+  for (const file of allFiles) {
+    let content;
+    try { content = readFileSync(file, "utf8"); }
+    catch { console.error(`  Cannot read: ${file}`); continue; }
+
+    const result = runner(basename(file), content, { disabledRuleIds: new Set() });
+    // Tag each finding with its source file for later grouping
+    for (const f of result.findings ?? []) f._file = file;
+    results.push({ file, result });
+  }
+
+  // Output
+  if (args.output === "json") {
+    printJson(stackId, results, args);
+  } else if (args.output === "summary") {
+    printSummary(stackId, results);
+  } else {
+    printPretty(stackId, results, args);
+  }
+
+  // Open HTML report in browser if --open flag set
+  if (args.open) {
+    const stack = AUDIT_STACKS[stackId];
+    const allFindings = results.flatMap(r => r.result.findings ?? []);
+    const report = {
+      stack: { id: stackId, name: stack.name },
+      files: results.length,
+      avgScore: results.length
+        ? Math.round(results.reduce((s, r) => s + (r.result.overallScore ?? 0), 0) / results.length)
+        : 0,
+      summary: {
+        critical: allFindings.filter(f => f.severity === "critical").length,
+        warning:  allFindings.filter(f => f.severity === "warning").length,
+        info:     allFindings.filter(f => f.severity === "info").length,
+      },
+      results: results.map(({ file, result }) => ({
+        file,
+        overallScore: result.overallScore,
+        categoryScores: result.categoryScores,
+        findings: result.findings,
+      })),
+    };
+    openHtmlReport(buildHtmlReport(report));
+  }
+
+  // Exit with non-zero if any criticals found (useful for CI)
+  const hasCritical = results.some(r =>
+    r.result.findings?.some(f => f.severity === "critical")
+  );
+  if (hasCritical && args.severity !== "info" && args.severity !== "warning") {
+    process.exitCode = 1;
+  }
+}
+
+main().catch(err => { console.error(err); process.exit(1); });