@cleartrip/frontguard 0.1.4 → 0.1.7

package/dist/cli.js

@@ -4,7 +4,7 @@ import g, { stdin, stdout, cwd } from 'process';
 import f from 'readline';
 import * as tty from 'tty';
 import { WriteStream } from 'tty';
-import path, { sep, normalize, delimiter, resolve, dirname } from 'path';
+import path4, { sep, normalize, delimiter, resolve, dirname } from 'path';
 import fs from 'fs/promises';
 import { createRequire } from 'module';
 import fs4 from 'fs';
@@ -2461,15 +2461,18 @@ export default defineConfig({
   //   bundle: { enabled: true, maxDeltaBytes: 50_000, maxTotalBytes: null },
   //   cycles: { enabled: true },
   //   deadCode: { enabled: true, gate: 'info' },
-  //   // LLM in CI needs a key in the *runner* (GitHub secret). IDE keys (Cursor Enterprise)
-  //   // are not available in Actions \u2014 use paste workflow instead:
-  //   //   frontguard run --append ./.frontguard/review-notes.md
-  //   // or FRONTGUARD_MANUAL_APPENDIX_FILE / FRONTGUARD_MANUAL_APPENDIX
+  //   // LLM: cloud keys in CI, or local Ollama (no API key) on dev/self-hosted runners:
+  //   //   ollama serve && ollama pull llama3.2
+  //   // Paste workflow (no key): frontguard run --append ./.frontguard/review-notes.md
   //   llm: {
   //     enabled: true,
-  //     provider: 'openai',
-  //     apiKeyEnv: 'OPENAI_API_KEY',
+  //     provider: 'ollama',
+  //     model: 'llama3.2',
+  //     ollamaUrl: 'http://127.0.0.1:11434',
+  //     perFindingFixes: true,
+  //     maxFixSuggestions: 8,
   //   },
+  //   // llm: { enabled: true, provider: 'openai', apiKeyEnv: 'OPENAI_API_KEY' },
   // },
 })
 `;
@@ -2497,19 +2500,19 @@ async function ensureDir(dir) {
   await fs.mkdir(dir, { recursive: true });
 }
 async function initFrontGuard(cwd) {
-  const gh = path.join(cwd, ".github", "workflows");
+  const gh = path4.join(cwd, ".github", "workflows");
   await ensureDir(gh);
-  const wfPath = path.join(gh, "frontguard.yml");
+  const wfPath = path4.join(gh, "frontguard.yml");
   await fs.writeFile(wfPath, WORKFLOW, "utf8");
-  const cfgPath = path.join(cwd, "frontguard.config.js");
+  const cfgPath = path4.join(cwd, "frontguard.config.js");
   try {
     await fs.access(cfgPath);
   } catch {
     await fs.writeFile(cfgPath, CONFIG, "utf8");
   }
-  const tplRoot = path.join(cwd, ".github");
+  const tplRoot = path4.join(cwd, ".github");
   await ensureDir(tplRoot);
-  const tplPath = path.join(tplRoot, "pull_request_template.md");
+  const tplPath = path4.join(tplRoot, "pull_request_template.md");
   try {
     await fs.access(tplPath);
   } catch {
@@ -2517,6 +2520,76 @@ async function initFrontGuard(cwd) {
   }
 }
 
+// src/ci/bitbucket-pr-snippet.ts
+function bitbucketPipelineResultsUrl() {
+  const full = process.env.BITBUCKET_REPO_FULL_NAME?.trim();
+  const bn = process.env.BITBUCKET_BUILD_NUMBER?.trim();
+  if (full && bn) {
+    return `https://bitbucket.org/${full}/pipelines/results/${bn}`;
+  }
+  const ws = process.env.BITBUCKET_WORKSPACE?.trim();
+  const slug = process.env.BITBUCKET_REPO_SLUG?.trim();
+  if (ws && slug && bn) {
+    return `https://bitbucket.org/${ws}/${slug}/pipelines/results/${bn}`;
+  }
+  return null;
+}
+function bitbucketDownloadsPageUrl() {
+  const full = process.env.BITBUCKET_REPO_FULL_NAME?.trim();
+  if (full) return `https://bitbucket.org/${full}/downloads/`;
+  const ws = process.env.BITBUCKET_WORKSPACE?.trim();
+  const slug = process.env.BITBUCKET_REPO_SLUG?.trim();
+  if (ws && slug) return `https://bitbucket.org/${ws}/${slug}/downloads/`;
+  return null;
+}
+function formatBitbucketPrSnippet(report) {
+  const publicReport = process.env.FRONTGUARD_PUBLIC_REPORT_URL?.trim();
+  const downloadsName = process.env.FRONTGUARD_REPORT_DOWNLOAD_NAME?.trim();
+  const downloadsPage = bitbucketDownloadsPageUrl();
+  const pipeline = bitbucketPipelineResultsUrl();
+  let linkLine;
+  if (publicReport) {
+    linkLine = `**[Open full FrontGuard report (HTML)](${publicReport})** \u2014 interactive report in the browser (all findings).`;
+  } else if (downloadsName && downloadsPage) {
+    linkLine = `**[Repo Downloads](${downloadsPage})** \u2014 open \`${downloadsName}\` (uploaded by this pipeline). Download the file, then open it in a browser.`;
+  } else if (pipeline) {
+    linkLine = [
+      `**[Open this pipeline run](${pipeline})** (Bitbucket login required).`,
+      "On that page: open the **Artifacts** section \u2192 download **`frontguard-report.html`** \u2192 open the file in your browser to see the full interactive report."
+    ].join(" ");
+  } else {
+    linkLine = "_Run FrontGuard inside Bitbucket Pipelines so `BITBUCKET_REPO_FULL_NAME` and `BITBUCKET_BUILD_NUMBER` are set, or set `FRONTGUARD_PUBLIC_REPORT_URL` after uploading the HTML._";
+  }
+  const { riskScore, results } = report;
+  const blocks = results.reduce(
+    (n3, r4) => n3 + r4.findings.filter((f4) => f4.severity === "block").length,
+    0
+  );
+  const warns = results.reduce(
+    (n3, r4) => n3 + r4.findings.filter((f4) => f4.severity === "warn").length,
+    0
+  );
+  const lines = [
+    "## FrontGuard",
+    "",
+    `**Risk:** ${riskScore} \xB7 **Blocking:** ${blocks} \xB7 **Warnings:** ${warns}`,
+    "",
+    linkLine,
+    "",
+    "| Check | Status |",
+    "|:--|:--|"
+  ];
+  for (const r4 of results) {
+    const status = r4.skipped ? `Skipped (${r4.skipped.slice(0, 80)}${r4.skipped.length > 80 ? "\u2026" : ""})` : r4.findings.length === 0 ? "Clean" : `${r4.findings.length} finding(s)`;
+    lines.push(`| \`${r4.checkId}\` | ${status} |`);
+  }
+  lines.push("");
+  lines.push(
+    publicReport ? "_All findings and suggested fixes are in the linked HTML report._" : "_Summary only \u2014 use the link above for the full interactive report._"
+  );
+  return lines.join("\n");
+}
+
 // src/ci/parse-ai-disclosure.ts
 function extractAiSection(body) {
   const lines = body.split(/\r?\n/);
@@ -2614,10 +2687,10 @@ async function resolvePrNumber() {
   const raw = process.env.FRONTGUARD_PR_NUMBER ?? process.env.PR_NUMBER;
   const n3 = Number(raw);
   if (Number.isFinite(n3) && n3 > 0) return n3;
-  const path14 = process.env.GITHUB_EVENT_PATH;
-  if (!path14) return null;
+  const path16 = process.env.GITHUB_EVENT_PATH;
+  if (!path16) return null;
   try {
-    const payload = JSON.parse(await fs.readFile(path14, "utf8"));
+    const payload = JSON.parse(await fs.readFile(path16, "utf8"));
     const num = payload.pull_request?.number;
     return typeof num === "number" && num > 0 ? num : null;
   } catch {
@@ -2797,7 +2870,11 @@ var defaultConfig = {
       model: "gpt-4o-mini",
       apiKeyEnv: "OPENAI_API_KEY",
       maxDiffChars: 48e3,
-      timeoutMs: 6e4
+      timeoutMs: 6e4,
+      ollamaUrl: "http://127.0.0.1:11434",
+      perFindingFixes: false,
+      maxFixSuggestions: 12,
+      maxFileContextChars: 24e3
     }
   }
 };
@@ -2824,7 +2901,7 @@ function stripExtends(c4) {
 }
 async function loadExtendsLayer(cwd, spec) {
   if (!spec) return {};
-  const req = createRequire(path.join(cwd, "package.json"));
+  const req = createRequire(path4.join(cwd, "package.json"));
   const specs = Array.isArray(spec) ? spec : [spec];
   let merged = {};
   for (const s3 of specs) {
@@ -2843,7 +2920,7 @@ async function loadExtendsLayer(cwd, spec) {
 async function loadConfig(cwd) {
   let userFile = null;
   for (const name of CONFIG_NAMES) {
-    const full = path.join(cwd, name);
+    const full = path4.join(cwd, name);
     if (!fs4.existsSync(full)) continue;
     try {
       const mod = await importConfig(full);
@@ -2873,7 +2950,7 @@ function hasDep(deps, name) {
 async function detectStack(cwd) {
   let pkg = {};
   try {
-    const raw = await fs.readFile(path.join(cwd, "package.json"), "utf8");
+    const raw = await fs.readFile(path4.join(cwd, "package.json"), "utf8");
     pkg = JSON.parse(raw);
   } catch {
     return {
@@ -2893,7 +2970,7 @@ async function detectStack(cwd) {
   const isMonorepo = Boolean(pkg.workspaces);
   let tsStrict = null;
   try {
-    const tsconfigPath = path.join(cwd, "tsconfig.json");
+    const tsconfigPath = path4.join(cwd, "tsconfig.json");
     const tsRaw = await fs.readFile(tsconfigPath, "utf8");
     const ts = JSON.parse(tsRaw);
     if (typeof ts.compilerOptions?.strict === "boolean") {
@@ -2903,15 +2980,15 @@ async function detectStack(cwd) {
   }
   let pm = "unknown";
   try {
-    await fs.access(path.join(cwd, "pnpm-lock.yaml"));
+    await fs.access(path4.join(cwd, "pnpm-lock.yaml"));
     pm = "pnpm";
   } catch {
     try {
-      await fs.access(path.join(cwd, "yarn.lock"));
+      await fs.access(path4.join(cwd, "yarn.lock"));
       pm = "yarn";
     } catch {
       try {
-        await fs.access(path.join(cwd, "package-lock.json"));
+        await fs.access(path4.join(cwd, "package-lock.json"));
         pm = "npm";
       } catch {
         pm = "npm";
@@ -2931,6 +3008,61 @@ async function detectStack(cwd) {
     tsStrict
   };
 }
+function formatStackOneLiner(s3) {
+  const bits = [];
+  if (s3.hasNext) bits.push("Next.js");
+  if (s3.hasReactNative) bits.push("React Native");
+  else if (s3.hasReact) bits.push("React");
+  if (s3.hasTypeScript) bits.push("TypeScript");
+  if (s3.tsStrict === true) bits.push("strict TS");
+  bits.push(`pkg: ${s3.packageManager}`);
+  return bits.join(" \xB7 ") || "unknown";
+}
+function stripFileUrl(p2) {
+  let s3 = p2.trim();
+  if (!/^file:/i.test(s3)) return s3;
+  s3 = s3.replace(/^file:\/\//i, "");
+  if (process.platform === "win32" && s3.startsWith("/")) {
+    const m3 = s3.match(/^\/([A-Za-z]:\/.*)$/);
+    if (m3) return m3[1];
+  }
+  return s3;
+}
+function isUnderDir(parent, child) {
+  const rel = path4.relative(parent, child);
+  return rel === "" || !rel.startsWith("..") && !path4.isAbsolute(rel);
+}
+function toRepoRelativePath(cwd, filePath) {
+  if (!filePath?.trim()) return void 0;
+  const raw = stripFileUrl(filePath);
+  const resolvedCwd = path4.resolve(cwd);
+  const absFile = path4.isAbsolute(raw) ? path4.resolve(raw) : path4.resolve(resolvedCwd, raw);
+  if (!isUnderDir(resolvedCwd, absFile)) {
+    return raw.split(/[/\\]/g).join("/");
+  }
+  let rel = path4.relative(resolvedCwd, absFile);
+  if (!rel || rel === ".") {
+    return path4.basename(absFile);
+  }
+  return rel.split(path4.sep).join("/");
+}
+function stripRepoAbsolutePaths(cwd, text) {
+  if (!text || !cwd.trim()) return text;
+  const resolvedCwd = path4.resolve(cwd);
+  const asPosix = (s3) => s3.replace(/\\/g, "/");
+  const cwdPosix = asPosix(resolvedCwd);
+  let out = asPosix(text);
+  const prefixes = [.../* @__PURE__ */ new Set([cwdPosix + "/", resolvedCwd + path4.sep])].filter(
+    (p2) => p2.length > 1
+  );
+  for (const prefix of prefixes) {
+    const norm = prefix.replace(/\\/g, "/");
+    if (out.includes(norm)) {
+      out = out.split(norm).join("");
+    }
+  }
+  return out;
+}
 var d2 = (e3, t3) => () => (t3 || e3((t3 = { exports: {} }).exports, t3), t3.exports);
 var f3 = /* @__PURE__ */ createRequire(import.meta.url);
 var p = /^path$/i;
@@ -3546,7 +3678,7 @@ async function pathExists(file) {
   }
 }
 async function resolveBin(cwd, name) {
-  const local = path.join(cwd, "node_modules", ".bin", name);
+  const local = path4.join(cwd, "node_modules", ".bin", name);
   if (await pathExists(local)) return local;
   const win = local + ".cmd";
   if (await pathExists(win)) return win;
@@ -3602,7 +3734,7 @@ async function runNpx(cwd, args) {
 // src/checks/eslint.ts
 async function hasEslintDependency(cwd) {
   try {
-    const raw = await fs.readFile(path.join(cwd, "package.json"), "utf8");
+    const raw = await fs.readFile(path4.join(cwd, "package.json"), "utf8");
     const p2 = JSON.parse(raw);
     return Boolean(p2.devDependencies?.eslint || p2.dependencies?.eslint);
   } catch {
@@ -3621,7 +3753,7 @@ async function hasEslintConfig(cwd) {
     ".eslintrc.yml"
   ];
   for (const c4 of candidates) {
-    if (await pathExists(path.join(cwd, c4))) return true;
+    if (await pathExists(path4.join(cwd, c4))) return true;
   }
   return false;
 }
@@ -3677,20 +3809,19 @@ async function runEslint(cwd, config, _stack) {
   }
   try {
     const rows = JSON.parse(stdout2);
-    let n3 = 0;
     for (const row of rows) {
+      const relFile = toRepoRelativePath(cwd, row.filePath);
       for (const m3 of row.messages) {
-        if (n3++ >= 40) break;
         findings.push({
           id: `eslint-${m3.ruleId ?? "unknown"}`,
           severity: "warn",
           message: m3.message,
-          file: row.filePath,
+          file: relFile,
           detail: m3.line ? `line ${m3.line}` : void 0
         });
       }
     }
-    if (n3 === 0) {
+    if (findings.length === 0) {
       findings.push({
         id: "eslint-failed",
         severity: "warn",
@@ -3778,7 +3909,7 @@ async function runTypeScript(cwd, config, stack) {
       skipped: "disabled in config"
     };
   }
-  const hasTs = stack.hasTypeScript || await pathExists(path.join(cwd, "tsconfig.json"));
+  const hasTs = stack.hasTypeScript || await pathExists(path4.join(cwd, "tsconfig.json"));
   if (!hasTs) {
     return {
       checkId: "typescript",
@@ -3891,7 +4022,7 @@ async function runSecrets(cwd, config, pr) {
       });
       break;
     }
-    const full = path.join(cwd, rel);
+    const full = path4.join(cwd, rel);
     let content;
     try {
       content = await fs.readFile(full, "utf8");
@@ -3917,7 +4048,7 @@ async function runSecrets(cwd, config, pr) {
   };
 }
 function isProbablyTextFile(rel) {
-  const ext = path.extname(rel).toLowerCase();
+  const ext = path4.extname(rel).toLowerCase();
   return TEXT_EXT.has(ext);
 }
 
@@ -4210,12 +4341,12 @@ async function runCycles(cwd, config, stack) {
   }
   let entry = cfg.entries[0] ?? "src";
   for (const e3 of cfg.entries) {
-    if (await pathExists(path.join(cwd, e3))) {
+    if (await pathExists(path4.join(cwd, e3))) {
       entry = e3;
       break;
     }
   }
-  if (!await pathExists(path.join(cwd, entry))) {
+  if (!await pathExists(path4.join(cwd, entry))) {
     return {
       checkId: "cycles",
       findings: [],
@@ -4339,7 +4470,7 @@ async function sumGlobBytes(cwd, patterns) {
     });
     for (const rel of files) {
       try {
-        const st = await fs.stat(path.join(cwd, rel));
+        const st = await fs.stat(path4.join(cwd, rel));
         total += st.size;
       } catch {
       }
@@ -4348,7 +4479,7 @@ async function sumGlobBytes(cwd, patterns) {
   return total;
 }
 async function readBaseline(cwd, relPath, baseRef) {
-  const disk = path.join(cwd, relPath);
+  const disk = path4.join(cwd, relPath);
   try {
     const raw = await fs.readFile(disk, "utf8");
     return JSON.parse(raw);
@@ -4523,7 +4654,7 @@ async function runCwv(cwd, config, stack, pr) {
   const findings = [];
   const sev2 = gateSeverity5(cfg.gate);
   for (const rel of toScan.slice(0, 400)) {
-    const full = path.join(cwd, rel);
+    const full = path4.join(cwd, rel);
     let text;
     try {
       text = await fs.readFile(full, "utf8");
@@ -4608,7 +4739,7 @@ async function runCustomRules(cwd, config, restrictToFiles) {
       });
       break;
     }
-    const full = path.join(cwd, rel);
+    const full = path4.join(cwd, rel);
     let content;
     try {
       content = await fs.readFile(full, "utf8");
@@ -4739,7 +4870,7 @@ async function runAiAssistedStrict(cwd, config, pr) {
   const gate = cfg.gate;
   const findings = [];
   for (const rel of files) {
-    const full = path.join(cwd, rel);
+    const full = path4.join(cwd, rel);
     let content;
     try {
       content = await fs.readFile(full, "utf8");
@@ -4797,8 +4928,268 @@ function applyAiAssistedEscalation(results, pr, config) {
 
 // src/report/builder.ts
 var import_picocolors = __toESM(require_picocolors());
+
+// src/lib/html-escape.ts
+function escapeHtml(s3) {
+  return s3.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+// src/report/html-report.ts
+function shieldUrl(label, message, color) {
+  const q2 = new URLSearchParams({ label, message, color, style: "for-the-badge" });
+  return `https://img.shields.io/static/v1?${q2}`;
+}
+function riskColor(risk) {
+  if (risk === "LOW") return "brightgreen";
+  if (risk === "MEDIUM") return "orange";
+  return "red";
+}
+function modeColor(mode) {
+  return mode === "enforce" ? "critical" : "blue";
+}
+function countColor(kind, n3) {
+  if (kind === "block") return n3 === 0 ? "brightgreen" : "critical";
+  if (kind === "info") return n3 === 0 ? "inactive" : "informational";
+  if (n3 === 0) return "brightgreen";
+  if (n3 <= 10) return "yellow";
+  return "orange";
+}
+function parseLineHint(detail) {
+  if (!detail) return 0;
+  const m3 = /^line\s+(\d+)/i.exec(detail.trim());
+  return m3 ? Number(m3[1]) : 0;
+}
+function normalizeFinding(cwd, f4) {
+  return {
+    file: toRepoRelativePath(cwd, f4.file),
+    message: stripRepoAbsolutePaths(cwd, f4.message),
+    detail: f4.detail ? stripRepoAbsolutePaths(cwd, f4.detail) : void 0
+  };
+}
+function sortFindings(cwd, items) {
+  return [...items].sort((a3, b3) => {
+    const af = toRepoRelativePath(cwd, a3.f.file) ?? "";
+    const bf = toRepoRelativePath(cwd, b3.f.file) ?? "";
+    if (af !== bf) return af.localeCompare(bf);
+    const lineA = parseLineHint(a3.f.detail);
+    const lineB = parseLineHint(b3.f.detail);
+    if (lineA !== lineB) return lineA - lineB;
+    return a3.f.message.localeCompare(b3.f.message);
+  });
+}
+function formatDuration(ms) {
+  if (ms < 1e3) return `${ms} ms`;
+  const s3 = Math.round(ms / 1e3);
+  if (s3 < 60) return `${s3}s`;
+  const m3 = Math.floor(s3 / 60);
+  const r4 = s3 % 60;
+  return r4 ? `${m3}m ${r4}s` : `${m3}m`;
+}
+function renderFindingCard(cwd, r4, f4) {
+  const d3 = normalizeFinding(cwd, f4);
+  const sevClass = f4.severity === "block" ? "sev-block" : f4.severity === "warn" ? "sev-warn" : "sev-info";
+  const fixBlock = f4.suggestedFix ? `<div class="suggested-fix"><h5>Suggested fix <span class="tag">LLM</span></h5><div class="fix-md">${escapeHtml(f4.suggestedFix.summary)}</div>${f4.suggestedFix.code ? `<pre class="code"><code>${escapeHtml(f4.suggestedFix.code)}</code></pre>` : ""}<p class="disclaimer">Suggestions are non-binding; review and test before applying.</p></div>` : "";
+  const hintRow = d3.detail && !d3.detail.includes("\n") && d3.detail.length <= 220 && !d3.detail.includes("|") ? `<tr><th>Hint</th><td>${escapeHtml(d3.detail)}</td></tr>` : "";
+  const detailFence = d3.detail && (d3.detail.includes("\n") || d3.detail.length > 220 || d3.detail.includes("|")) ? `<pre class="code"><code>${escapeHtml(d3.detail)}</code></pre>` : "";
+  return `<article class="card ${sevClass}"><h4>${escapeHtml(d3.file ?? "\u2014")} <span class="muted">\xB7</span> ${escapeHtml(d3.message)}</h4><table class="meta"><tr><th>Check</th><td><code>${escapeHtml(r4.checkId)}</code></td></tr><tr><th>Rule</th><td><code>${escapeHtml(f4.id)}</code></td></tr>${d3.file ? `<tr><th>File</th><td><code>${escapeHtml(d3.file)}</code></td></tr>` : ""}${hintRow}</table>${detailFence}${fixBlock}</article>`;
+}
+function buildHtmlReport(p2) {
+  const {
+    cwd,
+    riskScore,
+    mode,
+    stack,
+    pr,
+    results,
+    warns,
+    infos,
+    blocks,
+    lines,
+    llmAppendix
+  } = p2;
+  const modeLabel = mode === "enforce" ? "enforce" : "warn only";
+  const badges = [
+    ["risk", riskScore, riskColor(riskScore)],
+    ["mode", modeLabel, modeColor(mode)],
+    ["blocking", String(blocks), countColor("block", blocks)],
+    ["warnings", String(warns), countColor("warn", warns)],
+    ["info", String(infos), countColor("info", infos)]
+  ];
+  const badgeImgs = badges.map(([l3, m3, c4]) => {
+    const alt = `${l3}: ${m3}`;
+    return `<img class="badge" src="${escapeHtml(shieldUrl(l3, m3, c4))}" alt="${escapeHtml(alt)}" loading="lazy" />`;
+  }).join(" ");
+  const checkRows = results.map((r4) => {
+    const status = r4.skipped ? `Skipped \u2014 ${escapeHtml(r4.skipped)}` : r4.findings.length === 0 ? "Clean" : `${r4.findings.length} finding(s)`;
+    return `<tr><td>${r4.skipped ? "\u23ED\uFE0F" : r4.findings.length === 0 ? "\u{1F7E2}" : r4.findings.some((x3) => x3.severity === "block") ? "\u{1F534}" : "\u{1F7E1}"}</td><td><strong>${escapeHtml(r4.checkId)}</strong></td><td>${status}</td><td>${r4.skipped ? "\u2014" : r4.findings.length}</td><td>${formatDuration(r4.durationMs)}</td></tr>`;
+  }).join("\n");
+  const blockItems = sortFindings(
+    cwd,
+    results.flatMap(
+      (r4) => r4.findings.filter((f4) => f4.severity === "block").map((f4) => ({ r: r4, f: f4 }))
+    )
+  );
+  const warnItems = sortFindings(
+    cwd,
+    results.flatMap(
+      (r4) => r4.findings.filter((f4) => f4.severity === "warn").map((f4) => ({ r: r4, f: f4 }))
+    )
+  );
+  const infoItems = sortFindings(
+    cwd,
+    results.flatMap(
+      (r4) => r4.findings.filter((f4) => f4.severity === "info").map((f4) => ({ r: r4, f: f4 }))
+    )
+  );
+  const byCheck = /* @__PURE__ */ new Map();
+  for (const item of warnItems) {
+    const list = byCheck.get(item.r.checkId) ?? [];
+    list.push(item);
+    byCheck.set(item.r.checkId, list);
+  }
+  const checkOrder = [...byCheck.keys()].sort((a3, b3) => a3.localeCompare(b3));
+  const blockingHtml = blockItems.length === 0 ? '<p class="ok">No blocking findings.</p>' : blockItems.map(({ r: r4, f: f4 }) => renderFindingCard(cwd, r4, f4)).join("\n");
+  let warningsHtml = "";
+  if (warnItems.length === 0) {
+    warningsHtml = '<p class="ok">No warnings.</p>';
+  } else {
+    for (const cid of checkOrder) {
+      const group = sortFindings(cwd, byCheck.get(cid));
+      warningsHtml += `<h3 class="grp">${escapeHtml(cid)} <span class="count">(${group.length})</span></h3>`;
+      warningsHtml += group.map(({ r: r4, f: f4 }) => renderFindingCard(cwd, r4, f4)).join("\n");
+    }
+  }
+  const infoHtml = infoItems.length === 0 ? '<p class="muted">No info notes.</p>' : infoItems.map(({ r: r4, f: f4 }) => renderFindingCard(cwd, r4, f4)).join("\n");
+  const prBlock = pr && lines != null ? `<tr><th>PR size</th><td>${lines} LOC (+${pr.additions} / \u2212${pr.deletions}) \xB7 ${pr.changedFiles} files</td></tr>` : "";
+  const appendix = llmAppendix?.trim() ? `<section class="appendix"><h2>AI / manual appendix</h2><pre class="md-raw">${escapeHtml(llmAppendix.trim())}</pre></section>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>FrontGuard report</title>
+  <style>
+    :root {
+      --bg: #0f1419;
+      --panel: #1a2332;
+      --text: #e7ecf3;
+      --muted: #8b9aab;
+      --border: #2d3d52;
+      --block: #f87171;
+      --warn: #fbbf24;
+      --info: #38bdf8;
+      --accent: #a78bfa;
+      --ok: #4ade80;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0; font-family: ui-sans-serif, system-ui, sans-serif;
+      background: var(--bg); color: var(--text); line-height: 1.5;
+      padding: 1.5rem clamp(1rem, 4vw, 2.5rem) 3rem;
+      max-width: 58rem; margin-left: auto; margin-right: auto;
+    }
+    h1 { font-size: 1.5rem; margin: 0 0 1rem; letter-spacing: -0.02em; }
+    h2 { font-size: 1.15rem; margin: 2rem 0 0.75rem; color: var(--accent); border-bottom: 1px solid var(--border); padding-bottom: 0.35rem; }
+    h3.grp { margin: 1.5rem 0 0.5rem; font-size: 1rem; color: var(--warn); }
+    h3.grp .count { color: var(--muted); font-weight: normal; }
+    h4 { font-size: 0.95rem; margin: 0 0 0.5rem; font-weight: 600; }
+    h5 { font-size: 0.8rem; margin: 0 0 0.35rem; text-transform: uppercase; letter-spacing: 0.04em; color: var(--accent); }
+    .badges { margin-bottom: 1.25rem; display: flex; flex-wrap: wrap; gap: 0.35rem; align-items: center; }
+    .badge { height: 28px; width: auto; max-width: 100%; image-rendering: crisp-edges; }
+    details { background: var(--panel); border: 1px solid var(--border); border-radius: 8px; margin-bottom: 0.75rem; }
+    details.open-default { border-color: #3d4f6a; }
+    summary {
+      cursor: pointer; padding: 0.65rem 1rem; font-weight: 600;
+      list-style: none; display: flex; align-items: center; gap: 0.5rem;
+    }
+    summary::-webkit-details-marker { display: none; }
+    details[open] > summary { border-bottom: 1px solid var(--border); }
+    .details-body { padding: 0.75rem 1rem 1rem; }
+    table.results { width: 100%; border-collapse: collapse; font-size: 0.875rem; margin: 0.5rem 0 1rem; }
+    table.results th, table.results td { border: 1px solid var(--border); padding: 0.45rem 0.6rem; text-align: left; }
+    table.results th { background: #243044; color: var(--muted); font-weight: 600; }
+    .snapshot { width: 100%; border-collapse: collapse; font-size: 0.9rem; margin: 0.5rem 0; }
+    .snapshot th, .snapshot td { border: 1px solid var(--border); padding: 0.5rem 0.65rem; vertical-align: top; }
+    .snapshot th { width: 10rem; background: #243044; color: var(--muted); text-align: left; }
+    .card {
+      border: 1px solid var(--border); border-radius: 8px; padding: 0.85rem 1rem;
+      margin-bottom: 0.65rem; background: #131c28;
+    }
+    .card.sev-block { border-left: 4px solid var(--block); }
+    .card.sev-warn { border-left: 4px solid var(--warn); }
+    .card.sev-info { border-left: 4px solid var(--info); }
+    table.meta { width: 100%; font-size: 0.8rem; border-collapse: collapse; margin: 0.5rem 0; }
+    table.meta th { text-align: left; color: var(--muted); width: 5.5rem; padding: 0.2rem 0.5rem 0.2rem 0; vertical-align: top; }
+    table.meta td { padding: 0.2rem 0; }
+    .muted { color: var(--muted); }
+    .ok { color: var(--ok); }
+    pre.code {
+      margin: 0.5rem 0 0; padding: 0.65rem 0.75rem; background: #0a0e14; border-radius: 6px;
+      overflow: auto; font-size: 0.78rem; border: 1px solid var(--border);
+    }
+    pre.code code { font-family: ui-monospace, monospace; white-space: pre; }
+    .suggested-fix {
+      margin-top: 0.75rem; padding-top: 0.75rem; border-top: 1px dashed var(--border);
+    }
+    .fix-md { font-size: 0.85rem; white-space: pre-wrap; margin: 0.25rem 0 0.5rem; }
+    .tag {
+      font-size: 0.65rem; background: var(--accent); color: var(--bg);
+      padding: 0.1rem 0.35rem; border-radius: 4px; vertical-align: middle;
+    }
+    .disclaimer { font-size: 0.72rem; color: var(--muted); margin: 0.5rem 0 0; }
+    .appendix pre.md-raw {
+      white-space: pre-wrap; font-size: 0.85rem; background: var(--panel);
+      padding: 1rem; border-radius: 8px; border: 1px solid var(--border);
+    }
+    footer { margin-top: 2.5rem; padding-top: 1rem; border-top: 1px solid var(--border); font-size: 0.8rem; color: var(--muted); }
+  </style>
+</head>
+<body>
+  <h1>FrontGuard review</h1>
+  <div class="badges">${badgeImgs}</div>
+
+  <h2>Snapshot</h2>
+  <table class="snapshot">
+    <tr><th>Risk</th><td><strong>${riskScore}</strong> (heuristic)</td></tr>
+    <tr><th>Mode</th><td>${escapeHtml(modeLabel)}</td></tr>
+    <tr><th>Stack</th><td>${escapeHtml(formatStackOneLiner(stack))}</td></tr>
+    ${prBlock}
+  </table>
+
+  <h2>Check results</h2>
+  <table class="results">
+    <thead><tr><th></th><th>Check</th><th>Status</th><th>#</th><th>Time</th></tr></thead>
+    <tbody>${checkRows}</tbody>
+  </table>
+
+  <details class="open-default" open>
+    <summary>Blocking (${blocks})</summary>
+    <div class="details-body">${blockingHtml}</div>
+  </details>
+
+  <details class="open-default" open>
+    <summary>Warnings (${warns})</summary>
+    <div class="details-body">${warningsHtml}</div>
+  </details>
+
+  <details>
+    <summary>Info (${infos})</summary>
+    <div class="details-body">${infoHtml}</div>
+  </details>
+
+  ${appendix}
+
+  <footer>
+    <p>Self-contained HTML report \u2014 open locally or from CI artifacts. Badges load from <a href="https://shields.io" style="color: var(--info);">shields.io</a>.</p>
+  </footer>
+</body>
+</html>`;
+}
+
+// src/report/builder.ts
 function buildReport(stack, pr, results, options) {
   const mode = options?.mode ?? "warn";
+  const cwd = options?.cwd ?? process.cwd();
   const allFindings = results.flatMap(
     (r4) => r4.findings.map((f4) => ({ ...f4, checkId: r4.checkId }))
   );
@@ -4808,6 +5199,7 @@ function buildReport(stack, pr, results, options) {
   const lines = pr != null ? pr.additions + pr.deletions : null;
   const riskScore = scoreRisk(blocks, warns, lines, pr?.changedFiles ?? 0);
   const markdown = formatMarkdown({
+    cwd,
     riskScore,
     mode,
     stack,
@@ -4829,17 +5221,20 @@ function buildReport(stack, pr, results, options) {
     infos,
     blocks
   });
-  return { riskScore, stack, pr, results, markdown, consoleText };
-}
-function formatStackOneLiner(s3) {
-  const bits = [];
-  if (s3.hasNext) bits.push("Next.js");
-  if (s3.hasReactNative) bits.push("React Native");
-  else if (s3.hasReact) bits.push("React");
-  if (s3.hasTypeScript) bits.push("TypeScript");
-  if (s3.tsStrict === true) bits.push("strict TS");
-  bits.push(`pkg: ${s3.packageManager}`);
-  return bits.join(" \xB7 ") || "unknown";
+  const html = options?.emitHtml === true ? buildHtmlReport({
+    cwd,
+    riskScore,
+    mode,
+    stack,
+    pr,
+    results,
+    warns,
+    infos,
+    blocks,
+    lines,
+    llmAppendix: options?.llmAppendix ?? null
+  }) : null;
+  return { riskScore, stack, pr, results, markdown, consoleText, html };
 }
 function scoreRisk(blocks, warns, lines, files) {
   let score = 0;
@@ -4855,8 +5250,104 @@ function scoreRisk(blocks, warns, lines, files) {
   if (score >= 2) return "MEDIUM";
   return "LOW";
 }
+function shieldImageUrl(label, message, color) {
+  const q2 = new URLSearchParams({
+    label,
+    message,
+    color,
+    style: "for-the-badge"
+  });
+  return `https://img.shields.io/static/v1?${q2}`;
+}
+function mdShield(alt, label, message, color) {
+  return `![${alt}](${shieldImageUrl(label, message, color)})`;
+}
+function riskEmoji(risk) {
+  if (risk === "LOW") return "\u{1F7E2}";
+  if (risk === "MEDIUM") return "\u{1F7E0}";
+  return "\u{1F534}";
+}
+function riskShieldColor(risk) {
+  if (risk === "LOW") return "brightgreen";
+  if (risk === "MEDIUM") return "orange";
+  return "red";
+}
+function modeShieldColor(mode) {
+  return mode === "enforce" ? "critical" : "blue";
+}
+function countShieldColor(kind, n3) {
+  if (kind === "block") return n3 === 0 ? "brightgreen" : "critical";
+  if (kind === "info") return n3 === 0 ? "inactive" : "informational";
+  if (n3 === 0) return "brightgreen";
+  if (n3 <= 10) return "yellow";
+  return "orange";
+}
+function formatDuration2(ms) {
+  if (ms < 1e3) return `${ms} ms`;
+  const s3 = Math.round(ms / 1e3);
+  if (s3 < 60) return `${s3}s`;
+  const m3 = Math.floor(s3 / 60);
+  const r4 = s3 % 60;
+  return r4 ? `${m3}m ${r4}s` : `${m3}m`;
+}
+function healthEmojiForCheck(r4) {
+  if (r4.skipped) return "\u23ED\uFE0F";
+  if (r4.findings.length === 0) return "\u{1F7E2}";
+  const hasBlock = r4.findings.some((f4) => f4.severity === "block");
+  if (hasBlock) return "\u{1F534}";
+  return "\u{1F7E1}";
+}
+function normalizeFindingDisplay(cwd, f4) {
+  const file = toRepoRelativePath(cwd, f4.file);
+  const message = stripRepoAbsolutePaths(cwd, f4.message);
+  const detail = f4.detail ? stripRepoAbsolutePaths(cwd, f4.detail) : void 0;
+  return { file, message, detail };
+}
+function sanitizeFence(cwd, s3) {
+  return stripRepoAbsolutePaths(cwd, s3).replace(/\r\n/g, "\n").replace(/```/g, "`\u200B``");
+}
+function findingTitleLine(file, message) {
+  const msg = message.length > 200 ? `${message.slice(0, 197).trimEnd()}\u2026` : message;
+  const loc = file ? `\`${file}\`` : "_no file_";
+  return `${loc} \u2014 ${msg}`;
+}
+function parseLineHint2(detail) {
+  if (!detail) return 0;
+  const m3 = /^line\s+(\d+)/i.exec(detail.trim());
+  return m3 ? Number(m3[1]) : 0;
+}
+function appendDetailAfterTable(sb, cwd, detail) {
+  if (!detail?.trim()) return;
+  const d3 = detail.trim();
+  const oneLine = !d3.includes("\n");
+  const safeForTable = oneLine && d3.length <= 200 && !d3.includes("|") && !d3.includes("`");
+  if (safeForTable) {
+    sb.push(`| **Hint** | ${d3} |`);
+    return;
+  }
+  sb.push("");
+  sb.push("*Detail*");
+  sb.push("");
+  sb.push("```text");
+  sb.push(sanitizeFence(cwd, d3));
+  sb.push("```");
+}
+function appendSuggestedFix(sb, cwd, f4) {
+  if (!f4.suggestedFix) return;
+  sb.push("");
+  sb.push("_Suggested fix (LLM \u2014 non-binding):_");
+  sb.push("");
+  sb.push(f4.suggestedFix.summary);
+  if (f4.suggestedFix.code) {
+    sb.push("");
+    sb.push("```text");
+    sb.push(sanitizeFence(cwd, f4.suggestedFix.code));
+    sb.push("```");
+  }
+}
 function formatMarkdown(p2) {
   const {
+    cwd,
     riskScore,
     mode,
     stack,
@@ -4869,99 +5360,202 @@ function formatMarkdown(p2) {
     llmAppendix
   } = p2;
   const sb = [];
-  sb.push("## FrontGuard review brief");
+  const sortWithCwd = (items) => [...items].sort((a3, b3) => {
+    const af = toRepoRelativePath(cwd, a3.f.file) ?? "";
+    const bf = toRepoRelativePath(cwd, b3.f.file) ?? "";
+    if (af !== bf) return af.localeCompare(bf);
+    const lineA = parseLineHint2(a3.f.detail);
+    const lineB = parseLineHint2(b3.f.detail);
+    if (lineA !== lineB) return lineA - lineB;
+    return a3.f.message.localeCompare(b3.f.message);
+  });
+  sb.push("## \u2728 FrontGuard review brief");
   sb.push("");
+  const modeLabel = mode === "enforce" ? "enforce" : "warn only";
+  const badgeLine = [
+    mdShield("Risk level", "risk", riskScore, riskShieldColor(riskScore)),
+    mdShield("CI mode", "mode", modeLabel, modeShieldColor(mode)),
+    mdShield("Blocking", "blocking", String(blocks), countShieldColor("block", blocks)),
+    mdShield("Warnings", "warnings", String(warns), countShieldColor("warn", warns)),
+    mdShield("Info", "info notes", String(infos), countShieldColor("info", infos))
+  ].join(" ");
+  sb.push(badgeLine);
+  sb.push("");
+  sb.push("---");
+  sb.push("");
+  sb.push("### \u{1F4CC} Snapshot");
+  sb.push("");
+  sb.push("| | |");
+  sb.push("|:--|:--|");
+  sb.push(`| **Composite risk** | ${riskEmoji(riskScore)} **${riskScore}** \u2014 heuristic from blocks, warnings, and PR size. |`);
   sb.push(
-    `**Risk:** ${riskScore} \xB7 **Mode:** ${mode === "enforce" ? "enforce (CI may fail on `block`)" : "warn-only"}`
+    `| **Gate mode** | ${mode === "enforce" ? "\u{1F512} **Enforce** \u2014 CI fails when a `block` finding is present." : "\u{1F6C8} **Warn only** \u2014 findings are advisory unless you use `--enforce`."} |`
   );
-  if (pr?.aiAssisted) {
-    sb.push("");
+  sb.push(`| **Stack detected** | ${formatStackOneLiner(stack)} |`);
+  if (pr && lines != null) {
     sb.push(
-      "**AI-assisted PR:** Stricter static pass is active (security / footgun patterns on changed files; secrets & `any` deltas may be escalated). **Human review** still required for correctness and product rules."
+      `| **PR size** | \u{1F4CF} **${lines}** LOC ( +${pr.additions} / \u2212${pr.deletions} ) \xB7 **${pr.changedFiles}** files |`
     );
   }
   sb.push("");
-  sb.push(`**Stack:** ${formatStackOneLiner(stack)}`);
-  if (pr && lines != null) {
+  if (pr?.aiAssisted) {
     sb.push(
-      `**Size:** ${lines} lines (+${pr.additions} / -${pr.deletions}) across ${pr.changedFiles} files`
+      "> **\u{1F916} AI-assisted PR** \u2014 Stricter static checks run on changed files (security / footguns; secrets & `any` deltas may escalate). This does not replace human review for behavior or product rules."
     );
+    sb.push("");
   }
-  sb.push("");
+  sb.push("> **How to read this report**");
+  sb.push(">");
+  sb.push("> | Symbol | Meaning |");
+  sb.push("> |:--|:--|");
+  sb.push("> | \u{1F7E2} | Check passed or skipped cleanly |");
+  sb.push("> | \u{1F7E1} | Warnings only \u2014 review recommended |");
+  sb.push("> | \u{1F534} | Blocking (`block`) severity present |");
+  sb.push("> | \u23ED\uFE0F | Check skipped (see reason in table) |");
+  sb.push(">");
   sb.push(
-    blocks > 0 ? `**Blocking (\`block\`) findings:** ${blocks}` : "**Blocking (`block`) findings:** 0"
+    "> Paths in findings are **relative to the repo root**. Each issue below has a small field table and optional detail."
   );
-  sb.push(`**Warnings:** ${warns} \xB7 **Info:** ${infos}`);
   sb.push("");
-  sb.push("### Check summary");
+  sb.push("---");
+  sb.push("");
+  sb.push("### \u{1F4CB} Check results");
+  sb.push("");
+  sb.push("| | Check | Status | Findings | Duration |");
+  sb.push("|:--:|:--|:--|:-:|--:|");
   for (const r4 of results) {
-    const status = r4.skipped ? `\u23ED\uFE0F skipped (${r4.skipped})` : r4.findings.length === 0 ? "\u2705 clean" : `\u26A0\uFE0F ${r4.findings.length} finding(s)`;
-    sb.push(`- **${r4.checkId}** \u2014 ${status} (${r4.durationMs}ms)`);
+    const he2 = healthEmojiForCheck(r4);
+    let status;
+    if (r4.skipped) {
+      const why = r4.skipped.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+      const short = why.length > 120 ? `${why.slice(0, 117)}\u2026` : why;
+      status = `\u23ED\uFE0F **Skipped** \u2014 ${short}`;
+    } else if (r4.findings.length === 0) {
+      status = "\u2705 **Clean**";
+    } else {
+      status = "\u26A0\uFE0F **Issues**";
+    }
+    const nFind = r4.skipped ? "\u2014" : String(r4.findings.length);
+    sb.push(
+      `| ${he2} | **${r4.checkId}** | ${status} | **${nFind}** | ${formatDuration2(r4.durationMs)} |`
+    );
   }
   sb.push("");
-  const blockFindings = results.flatMap(
-    (r4) => r4.findings.filter((f4) => f4.severity === "block").map((f4) => ({ r: r4, f: f4 }))
+  const blockFindings = sortWithCwd(
+    results.flatMap(
+      (r4) => r4.findings.filter((f4) => f4.severity === "block").map((f4) => ({ r: r4, f: f4 }))
+    )
   );
-  if (blockFindings.length) {
-    sb.push("### Blocking");
-    for (const { f: f4 } of blockFindings.slice(0, 40)) {
-      const loc = f4.file ? ` \`${f4.file}\`` : "";
-      sb.push(`- ${f4.message}${loc}`);
-      if (f4.detail) {
-        sb.push(
-          `  - <details><summary>detail</summary>
-
-\`\`\`text
-${f4.detail}
-\`\`\`
-
-</details>`
-        );
-      }
+  sb.push(`### \u{1F6D1} Blocking \u2014 ${blocks} issue${blocks === 1 ? "" : "s"}`);
+  sb.push("");
+  if (blockFindings.length === 0) {
+    sb.push("*\u2705 No blocking findings \u2014 nothing mapped to severity `block`.*");
+  } else {
+    for (const { r: r4, f: f4 } of blockFindings) {
+      const d3 = normalizeFindingDisplay(cwd, f4);
+      sb.push("---");
+      sb.push("");
+      sb.push(`#### ${findingTitleLine(d3.file, d3.message)}`);
+      sb.push("");
+      sb.push(`| Field | Value |`);
+      sb.push(`|:--|:--|`);
+      sb.push(`| **Check** | \`${r4.checkId}\` |`);
+      sb.push(`| **Rule / id** | \`${f4.id}\` |`);
+      if (d3.file) sb.push(`| **File** | \`${d3.file}\` |`);
+      appendDetailAfterTable(sb, cwd, d3.detail);
+      appendSuggestedFix(sb, cwd, f4);
+      sb.push("");
     }
-    sb.push("");
   }
-  const warnFindings = results.flatMap(
-    (r4) => r4.findings.filter((f4) => f4.severity === "warn").map((f4) => ({ r: r4, f: f4 }))
+  sb.push("");
+  const warnFindings = sortWithCwd(
+    results.flatMap(
+      (r4) => r4.findings.filter((f4) => f4.severity === "warn").map((f4) => ({ r: r4, f: f4 }))
+    )
   );
-  if (warnFindings.length) {
-    sb.push("### Warnings");
-    for (const { f: f4 } of warnFindings.slice(0, 30)) {
-      const loc = f4.file ? ` \`${f4.file}\`` : "";
-      sb.push(`- ${f4.message}${loc}`);
-      if (f4.detail) {
-        sb.push(
-          `  - <details><summary>detail</summary>
-
-\`\`\`text
-${f4.detail}
-\`\`\`
-
-</details>`
-        );
+  sb.push(
+    `### \u26A0\uFE0F Warnings \u2014 ${warns} issue${warns === 1 ? "" : "s"} (by check)`
+  );
+  sb.push("");
+  if (warnFindings.length === 0) {
+    sb.push("*\u{1F389} No warnings \u2014 nice work.*");
+  } else {
+    const byCheck = /* @__PURE__ */ new Map();
+    for (const item of warnFindings) {
+      const list = byCheck.get(item.r.checkId) ?? [];
+      list.push(item);
+      byCheck.set(item.r.checkId, list);
+    }
+    const checkOrder = [...byCheck.keys()].sort((a3, b3) => a3.localeCompare(b3));
+    for (const checkId of checkOrder) {
+      const group = sortWithCwd(byCheck.get(checkId));
+      sb.push(`#### \u{1F4C2} \`${checkId}\` \xB7 ${group.length} finding${group.length === 1 ? "" : "s"}`);
+      sb.push("");
+      for (const { r: r4, f: f4 } of group) {
+        const d3 = normalizeFindingDisplay(cwd, f4);
+        sb.push("---");
+        sb.push("");
+        sb.push(`##### ${findingTitleLine(d3.file, d3.message)}`);
+        sb.push("");
+        sb.push(`| Field | Value |`);
+        sb.push(`|:--|:--|`);
+        sb.push(`| **Check** | \`${r4.checkId}\` |`);
+        sb.push(`| **Rule / id** | \`${f4.id}\` |`);
+        if (d3.file) sb.push(`| **File** | \`${d3.file}\` |`);
+        appendDetailAfterTable(sb, cwd, d3.detail);
+        appendSuggestedFix(sb, cwd, f4);
+        sb.push("");
       }
     }
-    if (warnFindings.length > 30) {
-      sb.push(`- _\u2026and ${warnFindings.length - 30} more_`);
-    }
-    sb.push("");
   }
-  const infoFindings = results.flatMap(
-    (r4) => r4.findings.filter((f4) => f4.severity === "info").map((f4) => ({ r: r4, f: f4 }))
+  sb.push("");
+  const infoFindings = sortWithCwd(
+    results.flatMap(
+      (r4) => r4.findings.filter((f4) => f4.severity === "info").map((f4) => ({ r: r4, f: f4 }))
+    )
   );
-  if (infoFindings.length) {
-    sb.push("### Notes");
-    for (const { f: f4 } of infoFindings.slice(0, 20)) {
-      sb.push(`- ${f4.message}`);
+  sb.push(`### \u2139\uFE0F Info & notes \u2014 ${infos} item${infos === 1 ? "" : "s"}`);
+  sb.push("");
+  if (infoFindings.length === 0) {
+    sb.push("*No info-level notes.*");
+  } else {
+    for (const { r: r4, f: f4 } of infoFindings) {
+      const d3 = normalizeFindingDisplay(cwd, f4);
+      sb.push("---");
+      sb.push("");
+      sb.push(`#### ${findingTitleLine(d3.file, d3.message)}`);
+      sb.push("");
+      sb.push(`| Field | Value |`);
+      sb.push(`|:--|:--|`);
+      sb.push(`| **Check** | \`${r4.checkId}\` |`);
+      sb.push(`| **Rule / id** | \`${f4.id}\` |`);
+      if (d3.file) sb.push(`| **File** | \`${d3.file}\` |`);
+      appendDetailAfterTable(sb, cwd, d3.detail);
+      appendSuggestedFix(sb, cwd, f4);
+      sb.push("");
     }
-    sb.push("");
   }
+  sb.push("");
   if (llmAppendix?.trim()) {
+    sb.push("### \u{1F916} AI / manual appendix");
+    sb.push("");
     sb.push(llmAppendix.trim());
     sb.push("");
   }
   sb.push("---");
-  sb.push("_Generated by FrontGuard \u2014 configure with `frontguard.config.js`_");
+  sb.push("");
+  sb.push(
+    mdShield(
+      "Generated by",
+      "report",
+      "FrontGuard",
+      "blueviolet"
+    )
+  );
+  sb.push("");
+  sb.push(
+    "_Configure checks in `frontguard.config.js` \xB7 [Shields.io](https://shields.io) badge images load in Bitbucket PR comments (HTML tags like `<details>` are not supported there)._"
+  );
   return sb.join("\n");
 }
 function formatConsole(p2) {
@@ -4988,6 +5582,185 @@ function formatConsole(p2) {
   return lines.join("\n");
 }
 
+// src/llm/ollama.ts
+async function callOllamaChat(opts) {
+  const fetch = getFetch();
+  const base = opts.baseUrl.replace(/\/$/, "");
+  const controller = new AbortController();
+  const t3 = setTimeout(() => controller.abort(), opts.timeoutMs);
+  try {
+    const res = await fetch(`${base}/api/chat`, {
+      method: "POST",
+      signal: controller.signal,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: opts.model,
+        messages: [{ role: "user", content: opts.prompt }],
+        stream: false,
+        options: { temperature: 0.2 }
+      })
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Ollama HTTP ${res.status}: ${body.slice(0, 400)}`);
+    }
+    const data = await res.json();
+    const text = data.message?.content?.trim();
+    if (!text) throw new Error("Ollama returned empty content");
+    return text;
+  } finally {
+    clearTimeout(t3);
+  }
+}
+
+// src/llm/finding-fixes.ts
+async function safeReadRepoFile(cwd, rel, maxChars) {
+  const root = path4.resolve(cwd);
+  const abs = path4.resolve(root, rel);
+  const relToRoot = path4.relative(root, abs);
+  if (relToRoot.startsWith("..") || path4.isAbsolute(relToRoot)) return null;
+  try {
+    let t3 = await fs.readFile(abs, "utf8");
+    if (t3.length > maxChars) {
+      t3 = t3.slice(0, maxChars) + `
+
+/* \u2026 truncated after ${maxChars} chars (FrontGuard context limit) \u2026 */
+`;
+    }
+    return t3;
+  } catch {
+    return null;
+  }
+}
+function parseFixResponse(raw) {
+  const codeMatch = /```(?:\w+)?\n([\s\S]*?)```/m.exec(raw);
+  const code = codeMatch?.[1]?.trim();
+  let summary = codeMatch ? raw.replace(codeMatch[0], "").trim() : raw.trim();
+  summary = summary.replace(/^#{1,6}\s+Fix\s*$/m, "").trim();
+  return { summary: summary || raw.trim(), code };
+}
+async function enrichFindingsWithOllamaFixes(opts) {
+  const { cwd, config, stack, results } = opts;
+  const cfg = config.checks.llm;
+  if (!cfg.enabled || cfg.provider !== "ollama" || !cfg.perFindingFixes) {
+    return results;
+  }
+  let pkgSnippet = "";
+  try {
+    const pj = await fs.readFile(path4.join(cwd, "package.json"), "utf8");
+    pkgSnippet = pj.slice(0, 4e3);
+  } catch {
+    pkgSnippet = "";
+  }
+  const stackLabel = formatStackOneLiner(stack);
+  const out = results.map((r4) => ({
+    ...r4,
+    findings: r4.findings.map((f4) => ({ ...f4 }))
+  }));
+  let budget = cfg.maxFixSuggestions;
+  for (let ri = 0; ri < out.length && budget > 0; ri++) {
+    const r4 = out[ri];
+    for (let fi = 0; fi < r4.findings.length && budget > 0; fi++) {
+      const f4 = r4.findings[fi];
+      if (f4.severity !== "warn" && f4.severity !== "block") continue;
+      if (!f4.file) continue;
+      budget -= 1;
+      const fileContent = await safeReadRepoFile(
+        cwd,
+        f4.file,
+        cfg.maxFileContextChars
+      );
+      const prompt2 = [
+        "You are a senior frontend engineer. A static checker flagged an issue in a pull request.",
+        "Use ONLY the repo context below (stack summary, package.json excerpt, file content).",
+        "If context is insufficient, say what is missing instead of guessing.",
+        "",
+        "Reply in Markdown with exactly these sections:",
+        "### Why",
+        "(1\u20133 short sentences: root cause and product/engineering risk.)",
+        "### Fix",
+        "(Minimal, concrete change. Put code in a single fenced block with a language tag, e.g. ```ts)",
+        "",
+        `Repo stack: ${stackLabel}`,
+        "",
+        "package.json excerpt:",
+        "```json",
+        pkgSnippet || "{}",
+        "```",
+        "",
+        `check: ${r4.checkId}`,
+        `rule/id: ${f4.id}`,
+        `severity: ${f4.severity}`,
+        `message: ${f4.message}`,
+        f4.detail ? `detail: ${f4.detail}` : "",
+        "",
+        f4.file ? `file (repo-relative): ${f4.file}` : "",
+        "",
+        fileContent ? "File content:\n```\n" + fileContent + "\n```" : "_No file content could be read (binary or path issue)._"
+      ].filter(Boolean).join("\n");
+      try {
+        const raw = await callOllamaChat({
+          baseUrl: cfg.ollamaUrl,
+          model: cfg.model,
+          prompt: prompt2,
+          timeoutMs: Math.min(cfg.timeoutMs, 12e4)
+        });
+        const parsed = parseFixResponse(raw);
+        r4.findings[fi] = {
+          ...f4,
+          suggestedFix: {
+            summary: parsed.summary,
+            ...parsed.code ? { code: parsed.code } : {}
+          }
+        };
+      } catch {
+        r4.findings[fi] = {
+          ...f4,
+          suggestedFix: {
+            summary: "_Could not reach Ollama or the model timed out. Is `ollama serve` running and `checks.llm.model` installed?_"
+          }
+        };
+      }
+    }
+  }
+  return out;
+}
+var MAX_CHARS = 2e5;
+async function loadManualAppendix(opts) {
+  const { cwd, filePath } = opts;
+  const envFile = process.env.FRONTGUARD_MANUAL_APPENDIX_FILE?.trim();
+  const resolvedPath = filePath?.trim() || envFile;
+  if (resolvedPath) {
+    const abs = path4.isAbsolute(resolvedPath) ? resolvedPath : path4.join(cwd, resolvedPath);
+    try {
+      let text = await fs.readFile(abs, "utf8");
+      if (text.length > MAX_CHARS) {
+        text = text.slice(0, MAX_CHARS) + "\n\n_(truncated)_\n";
+      }
+      const t3 = text.trim();
+      if (t3) {
+        return `### Contributed review notes
+
+_Pasted or file-based (no CI API key)._ 
+
+${t3}`;
+      }
+    } catch {
+    }
+  }
+  const inline = process.env.FRONTGUARD_MANUAL_APPENDIX?.trim();
+  if (inline) {
+    let text = inline;
+    if (text.length > MAX_CHARS) {
+      text = text.slice(0, MAX_CHARS) + "\n\n_(truncated)_\n";
+    }
+    return `### Contributed review notes
+
+${text.trim()}`;
+  }
+  return null;
+}
+
 // src/llm/review.ts
 function safeGetEnv(name) {
   const v3 = process.env[name];
@@ -4997,21 +5770,23 @@ async function runLlmReview(opts) {
   const { cwd, config, pr, results } = opts;
   const cfg = config.checks.llm;
   if (!cfg.enabled) return null;
-  const apiKey = safeGetEnv(cfg.apiKeyEnv);
-  if (!apiKey) {
-    if (process.env.FRONTGUARD_LLM_SHOW_NO_KEY_HINT !== "1") {
-      return null;
+  if (cfg.provider !== "ollama") {
+    const apiKey2 = safeGetEnv(cfg.apiKeyEnv);
+    if (!apiKey2) {
+      if (process.env.FRONTGUARD_LLM_SHOW_NO_KEY_HINT !== "1") {
+        return null;
+      }
+      return [
+        "### AI review (automated CI)",
+        "",
+        "_No API key in this environment._ IDE credentials do not reach CI runners.",
+        "",
+        "**Options:**",
+        "1. **Manual** \u2014 Paste notes into a file, then `frontguard run --append ./notes.md` (or `FRONTGUARD_MANUAL_APPENDIX_FILE`).",
+        `2. **Org CI** \u2014 Map an approved inference key to \`${cfg.apiKeyEnv}\` via your secret store.`,
+        '3. **Local Ollama** \u2014 Set `checks.llm.provider` to `"ollama"` (no API key; see docs).'
+      ].join("\n");
     }
-    return [
-      "### AI review (automated CI)",
-      "",
-      "_No API key in this environment._ IDE credentials do not reach GitHub Actions.",
-      "",
-      "**Options:**",
-      "1. **Manual** \u2014 Paste notes from Cursor/ChatGPT/Claude into a file, then `frontguard run --append ./notes.md` (or `FRONTGUARD_MANUAL_APPENDIX_FILE`).",
-      `2. **Org CI** \u2014 Map an approved inference key to \`${cfg.apiKeyEnv}\` via your secret store.`,
-      "3. **Docs in PR** \u2014 Rely on the PR template \u201CAI assistance\u201D section for reviewer context."
-    ].join("\n");
   }
   if (!await gitOk(cwd)) {
     return "_LLM review skipped: not a git repository_";
@@ -5035,7 +5810,7 @@ async function runLlmReview(opts) {
     "",
     pr ? `PR title: ${pr.title}
 PR body excerpt:
-${pr.body.slice(0, 2e3)}` : "No GitHub PR context (local run).",
+${pr.body.slice(0, 2e3)}` : "No PR context from the event payload (local run).",
     "",
     "Existing automated findings (may be incomplete):",
     summaryLines || "(none)",
@@ -5045,6 +5820,23 @@ ${pr.body.slice(0, 2e3)}` : "No GitHub PR context (local run).",
     diff,
     "```"
   ].join("\n");
+  if (cfg.provider === "ollama") {
+    try {
+      const text = await callOllamaChat({
+        baseUrl: cfg.ollamaUrl,
+        model: cfg.model,
+        prompt: prompt2,
+        timeoutMs: cfg.timeoutMs
+      });
+      return `### AI review (non-binding, Ollama)
+
+${text}`;
+    } catch (e3) {
+      const msg = e3 instanceof Error ? e3.message : String(e3);
+      return `_Ollama request failed: ${msg}_`;
+    }
+  }
+  const apiKey = safeGetEnv(cfg.apiKeyEnv);
   const controller = new AbortController();
   const t3 = setTimeout(() => controller.abort(), cfg.timeoutMs);
   try {
@@ -5121,41 +5913,6 @@ async function callAnthropic(model, apiKey, prompt2, signal) {
   if (!text) throw new Error("Anthropic returned empty content");
   return text;
 }
-var MAX_CHARS = 2e5;
-async function loadManualAppendix(opts) {
-  const { cwd, filePath } = opts;
-  const envFile = process.env.FRONTGUARD_MANUAL_APPENDIX_FILE?.trim();
-  const resolvedPath = filePath?.trim() || envFile;
-  if (resolvedPath) {
-    const abs = path.isAbsolute(resolvedPath) ? resolvedPath : path.join(cwd, resolvedPath);
-    try {
-      let text = await fs.readFile(abs, "utf8");
-      if (text.length > MAX_CHARS) {
-        text = text.slice(0, MAX_CHARS) + "\n\n_(truncated)_\n";
-      }
-      const t3 = text.trim();
-      if (t3) {
-        return `### Contributed review notes
-
-_Pasted or file-based (no CI API key)._ 
-
-${t3}`;
-      }
-    } catch {
-    }
-  }
-  const inline = process.env.FRONTGUARD_MANUAL_APPENDIX?.trim();
-  if (inline) {
-    let text = inline;
-    if (text.length > MAX_CHARS) {
-      text = text.slice(0, MAX_CHARS) + "\n\n_(truncated)_\n";
-    }
-    return `### Contributed review notes
-
-${text.trim()}`;
-  }
-  return null;
-}
 
 // src/commands/run.ts
 async function runFrontGuard(opts) {
@@ -5190,7 +5947,7 @@ async function runFrontGuard(opts) {
   const bundle = await runBundle(opts.cwd, config, stack);
   const prHygiene = runPrHygiene(config, pr);
   const prSize = runPrSize(config, pr);
-  const results = [
+  let results = [
     eslint,
     prettier,
     typescript,
@@ -5206,6 +5963,12 @@ async function runFrontGuard(opts) {
     prSize
   ];
   applyAiAssistedEscalation(results, pr, config);
+  results = await enrichFindingsWithOllamaFixes({
+    cwd: opts.cwd,
+    config,
+    stack,
+    results
+  });
   const manualAppendix = await loadManualAppendix({
     cwd: opts.cwd,
     filePath: opts.append ?? null
@@ -5217,7 +5980,19 @@ async function runFrontGuard(opts) {
     results
   });
   const llmAppendix = [manualAppendix, automatedAppendix].filter(Boolean).join("\n\n") || null;
-  const report = buildReport(stack, pr, results, { mode, llmAppendix });
+  const report = buildReport(stack, pr, results, {
+    mode,
+    llmAppendix,
+    cwd: opts.cwd,
+    emitHtml: Boolean(opts.htmlOut)
+  });
+  if (opts.htmlOut && report.html) {
+    await fs.writeFile(opts.htmlOut, report.html, "utf8");
+  }
+  if (opts.prCommentOut) {
+    const snippet = formatBitbucketPrSnippet(report);
+    await fs.writeFile(opts.prCommentOut, snippet, "utf8");
+  }
   if (opts.markdown) {
     g.stdout.write(report.markdown + "\n");
   } else {
@@ -5269,6 +6044,14 @@ var run = defineCommand({
     append: {
       type: "string",
       description: "Append markdown from a file (paste from IDE/ChatGPT/Claude; no CI API key needed)"
+    },
+    htmlOut: {
+      type: "string",
+      description: "Write interactive HTML report (use with CI artifacts; PR comment links to download)"
+    },
+    prCommentOut: {
+      type: "string",
+      description: "Write short Markdown for Bitbucket PR comment (summary + pipeline link for HTML artifact)"
     }
   },
   run: async ({ args }) => {
@@ -5277,7 +6060,9 @@ var run = defineCommand({
       ci: Boolean(args.ci),
       markdown: Boolean(args.markdown),
       enforce: Boolean(args.enforce),
-      append: typeof args.append === "string" ? args.append : null
+      append: typeof args.append === "string" ? args.append : null,
+      htmlOut: typeof args.htmlOut === "string" ? args.htmlOut : null,
+      prCommentOut: typeof args.prCommentOut === "string" ? args.prCommentOut : null
     });
   }
 });