techbro 0.0.0-stage → 0.5.0

package/assets/review.mjs

@@ -0,0 +1,721 @@
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NAME_RE = /^[A-Za-z0-9._-]{1,100}$/;
+const SAFE_PATH_RE = /^[A-Za-z0-9._@+\-/]{1,400}$/;
+const WRITE_PERMS = ["write", "maintain", "admin"];
+const MAX_UNPACKED = 2 * 1024 * 1024 * 1024;
+const MAX_LCOV = 5 * 1024 * 1024;
+
+const FAIL_ON = ["ERROR", "WARNING", "INFO", "none"];
+const SONAR_MODES = ["optional", "required", "off"];
+const RUST_VERSION_RE = /^(stable|beta|\d{1,2}\.\d{1,3}(\.\d{1,3})?)$/;
+const SEV_RANK = { INFO: 1, WARNING: 2, ERROR: 3, UNKNOWN: 3 };
+
+const REMEDIATION = {
+  "techbro.js.eval": "Remove eval; parse data with JSON.parse or use explicit functions instead of executing strings.",
+  "techbro.js.new-function": "Avoid the Function constructor; use a normal function or a safe lookup table.",
+  "techbro.py.eval": "Remove eval; use ast.literal_eval or json.loads for data, explicit dispatch for behavior.",
+  "techbro.py.subprocess-shell": "Pass an argument list and omit shell=True; never interpolate untrusted input into a shell string.",
+  "techbro.any.private-key": "Remove the key from the repository, rotate it, and load it from a secret store.",
+  "techbro.any.aws-access-key": "Remove the credential, rotate it in AWS, and load it from a secret store.",
+  "techbro.any.github-token": "Remove the token, revoke it in GitHub, and use a secret store or workflow token.",
+  "techbro.any.slack-token": "Remove the token, revoke it in Slack, and use a secret store.",
+  "techbro.rust.shell-command": "Invoke programs directly with Command::new(program).args([...]) instead of sh -c with built strings.",
+  "techbro.rust.unsafe-block": "Prefer safe abstractions; if unsafe is required, keep it minimal and document the invariants.",
+  "techbro.rust.unwrap": "Handle the error or None case explicitly (match, ?, or expect with context) instead of unwrap.",
+};
+const GENERIC_REMEDIATION = "Review this finding against team standards, fix the underlying issue, or ask a reviewer about the rule.";
+export const remediationFor = (rule) => (Object.hasOwn(REMEDIATION, rule) ? REMEDIATION[rule] : GENERIC_REMEDIATION);
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const fail = (m) => {
+  throw new Error(m);
+};
+
+export function safeRelPath(p) {
+  if (typeof p !== "string") return null;
+  const s = p.replace(/^(\.\/)+/, "");
+  if (!SAFE_PATH_RE.test(s) || s.startsWith("/") || s.split("/").some((x) => x === ".." || x === "")) return null;
+  return s;
+}
+
+function workdirOf(v) {
+  if (v === undefined || v === "" || v === ".") return ".";
+  const s = safeRelPath(v);
+  if (!s) fail(`invalid workdir/path in config: ${JSON.stringify(v)}`);
+  return s;
+}
+
+const oneLine = (v, what) => {
+  if (typeof v !== "string" || v.length > 500 || /[\r\n\0]/.test(v)) fail(`invalid ${what} in config (single line, max 500 chars)`);
+  return v;
+};
+
+export function parseGithubUrl(url) {
+  const m = /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(String(url ?? "").trim());
+  if (!m) fail(`not a GitHub repository URL: ${JSON.stringify(String(url).slice(0, 100))}`);
+  return { owner: m[1], repo: m[2] };
+}
+
+export function normalizeTest(t) {
+  if (t === undefined || t === null) return null;
+  if (!isObj(t)) fail("config test must be an object");
+  if (!t.command) return null;
+  const runtime = t.runtime ?? "system";
+  if (!["node", "rust-node", "system"].includes(runtime)) fail(`unsupported test runtime "${runtime}" (node|rust-node|system)`);
+  const nodeVersion = t.nodeVersion ?? "20";
+  if (!/^(\d{1,2}(\.\d+){0,2}|lts\/\*)$/.test(String(nodeVersion))) fail("invalid nodeVersion in config");
+  return {
+    runtime,
+    nodeVersion: String(nodeVersion),
+    workdir: workdirOf(t.workdir),
+    install: t.install ? oneLine(t.install, "install") : "",
+    command: oneLine(t.command, "command"),
+    coverage: t.coverage ? workdirOf(t.coverage) : "",
+    rustVersion: runtime === "rust-node" ? rustVersionOf(t.rustVersion) : "",
+  };
+}
+
+function rustVersionOf(v) {
+  if (v === undefined || v === "") return "";
+  const s = v;
+  if (typeof s !== "string" || !RUST_VERSION_RE.test(s)) fail("invalid rustVersion in config (stable|beta|X.Y[.Z])");
+  return s;
+}
+
+function checkKeys(o, allowed, what) {
+  for (const k of Object.keys(o)) if (!allowed.includes(k)) fail(`unknown key "${k}" in ${what} config`);
+}
+
+export function normalizeSecurity(s) {
+  if (s === undefined) return { failOn: "ERROR" };
+  if (!isObj(s)) fail("config security must be an object");
+  checkKeys(s, ["failOn"], "security");
+  const failOn = s.failOn ?? "ERROR";
+  if (!FAIL_ON.includes(failOn)) fail(`invalid security.failOn ${JSON.stringify(failOn)} (ERROR|WARNING|INFO|none)`);
+  return { failOn };
+}
+
+const DUP_MODES = ["required", "off"];
+const PERCENT_RE = /^\d{1,3}(\.\d{1,4})?$/;
+const validPercent = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 100 && PERCENT_RE.test(String(n));
+
+export function normalizeDuplication(d) {
+  if (d === undefined) return { mode: "required", maxPercent: 10 };
+  if (!isObj(d)) fail("config duplication must be an object");
+  checkKeys(d, ["mode", "maxPercent"], "duplication");
+  const mode = d.mode ?? "required";
+  if (!DUP_MODES.includes(mode)) fail(`invalid duplication.mode ${JSON.stringify(mode)} (required|off)`);
+  const maxPercent = d.maxPercent ?? 10;
+  if (!validPercent(maxPercent)) fail("invalid duplication.maxPercent (number 0..100, up to 4 decimals)");
+  return { mode, maxPercent };
+}
+
+export function normalizeSonar(s) {
+  if (s === undefined) return { mode: "optional", projectKey: "" };
+  if (!isObj(s)) fail("config sonar must be an object");
+  checkKeys(s, ["projectKey", "mode"], "sonar");
+  const mode = s.mode ?? "optional";
+  if (!SONAR_MODES.includes(mode)) fail(`invalid sonar.mode ${JSON.stringify(mode)} (optional|required|off)`);
+  const key = s.projectKey;
+  if (key !== undefined && (typeof key !== "string" || !/^[A-Za-z0-9_.:-]{1,400}$/.test(key))) fail("invalid sonar projectKey in config");
+  return { mode, projectKey: key ?? "" };
+}
+
+export function validateInputs({ project, sha, requestId }) {
+  if (project !== undefined && !NAME_RE.test(project)) fail("invalid project name");
+  if (!SHA_RE.test(sha ?? "")) fail("sha must be 40 lowercase hex characters");
+  if (!UUID_RE.test(requestId ?? "")) fail("request_id must be a UUID");
+}
+
+const REPO_RE = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?)\/([A-Za-z0-9._-]{1,100})$/;
+
+export function parseRepository(repository) {
+  const m = REPO_RE.exec(typeof repository === "string" ? repository : "");
+  if (!m || m[2] === "." || m[2] === "..") fail("invalid repository");
+  return { owner: m[1], repo: m[2] };
+}
+
+function canonicalUrl(url) {
+  try {
+    const { owner, repo } = parseGithubUrl(url);
+    return `${owner}/${repo}`.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+export function buildPlan({ inputs, repository, eventName, actor, refName, defaultBranch, projects, members, config, permission }) {
+  validateInputs({ sha: inputs?.sha, requestId: inputs?.requestId });
+  if (eventName !== "workflow_dispatch") fail(`review must be started by workflow_dispatch, got ${eventName}`);
+  const { owner, repo } = parseRepository(repository);
+  if (!defaultBranch || refName !== defaultBranch) fail(`workflow must be dispatched on the default branch (${defaultBranch}), got ${refName}`);
+  if (!WRITE_PERMS.includes(permission)) fail(`${actor} lacks write access to ${owner}/${repo}`);
+  const list = isObj(members) && Array.isArray(members.members) ? members.members : fail("members.json is malformed");
+  if (!list.some((m) => String(m).toLowerCase() === String(actor).toLowerCase())) fail(`${actor} is not in members.json`);
+  const all = isObj(projects) && Array.isArray(projects.projects) ? projects.projects : fail("projects.json is malformed");
+  const want = `${owner}/${repo}`.toLowerCase();
+  const matches = all.filter((p) => isObj(p) && canonicalUrl(p.url) === want);
+  if (matches.length === 0) fail(`repository ${owner}/${repo} is not registered in projects.json`);
+  if (matches.length > 1) fail(`repository ${owner}/${repo} is registered more than once in projects.json`);
+  const name = matches[0].name;
+  if (typeof name !== "string" || !NAME_RE.test(name)) fail("registered project name is invalid");
+  const pc = isObj(config?.projects) && Object.hasOwn(config.projects, name) && isObj(config.projects[name]) ? config.projects[name] : {};
+  const sonar = normalizeSonar(pc.sonar);
+  const security = normalizeSecurity(pc.security);
+  const dup = normalizeDuplication(pc.duplication);
+  return {
+    project: name,
+    sha: inputs.sha,
+    requestId: inputs.requestId,
+    owner,
+    repo,
+    test: normalizeTest(pc.test),
+    sonarKey: sonar.projectKey,
+    sonarMode: sonar.mode,
+    failOn: security.failOn,
+    dupMode: dup.mode,
+    dupMaxPercent: dup.maxPercent,
+  };
+}
+
+export function cleanFinding(f) {
+  const rule = typeof f?.rule === "string" && /^[\w.\-/:]{1,300}$/.test(f.rule) ? f.rule : null;
+  const p = safeRelPath(f?.path);
+  const num = (n) => (Number.isInteger(n) && n >= 0 && n <= 10_000_000 ? n : null);
+  const line = num(f?.line);
+  if (!rule || !p || line === null) return null;
+  const severity = ["ERROR", "WARNING", "INFO"].includes(f.severity) ? f.severity : "UNKNOWN";
+  const cwe = [...new Set((Array.isArray(f.cwe) ? f.cwe : []).map((c) => /^CWE-\d{1,5}/.exec(String(c))?.[0]).filter(Boolean))].slice(0, 5);
+  return { rule, path: p, line, endLine: num(f.endLine) ?? line, severity, cwe };
+}
+
+export function sanitizeOpengrep(raw, rc) {
+  if (!isObj(raw) || !Array.isArray(raw.results)) return { status: "error", exitCode: rc, total: 0, dropped: 0, bySeverity: {}, findings: [] };
+  const findings = [];
+  let dropped = 0;
+  for (const r of raw.results.slice(0, 5000)) {
+    const cwe = r?.extra?.metadata?.cwe;
+    const f = cleanFinding({
+      rule: r?.check_id,
+      path: r?.path,
+      line: r?.start?.line,
+      endLine: r?.end?.line,
+      severity: r?.extra?.severity,
+      cwe: Array.isArray(cwe) ? cwe : cwe ? [cwe] : [],
+    });
+    if (f) findings.push(f);
+    else dropped++;
+  }
+  const scanErrors = Array.isArray(raw.errors) ? raw.errors.length : 0;
+  const status = rc !== 0 || !Number.isInteger(rc) ? "error" : scanErrors ? "partial" : "ok";
+  return { status, exitCode: rc, scanErrors, total: findings.length, dropped, bySeverity: countBy(findings), findings };
+}
+
+const MAX_CLONES = 200;
+const JS_STATUS = ["ok", "error"];
+const DUP_REMEDIATION = "Review the duplicated regions and reduce duplication where it improves clarity; do not extract an abstraction blindly.";
+
+function cleanClonePart(f) {
+  const p = safeRelPath(typeof f?.name === "string" ? f.name : null);
+  const n = (v) => (Number.isInteger(v) && v >= 0 && v <= 10_000_000 ? v : null);
+  const start = n(f?.start);
+  const end = n(f?.end);
+  if (!p || start === null || end === null) return null;
+  return { path: p, start, end };
+}
+
+export function sanitizeJscpd(raw, rc) {
+  const bad = { status: "error", exitCode: Number.isInteger(rc) ? rc : null, percentage: 0, lines: 0, duplicatedLines: 0, clones: 0, locations: [] };
+  const t = raw?.statistics?.total;
+  if (rc !== 0 || !isObj(raw) || !isObj(t) || !Array.isArray(raw.duplicates)) return bad;
+  const pct = t.percentage;
+  const ok = (v) => Number.isFinite(v) && v >= 0 && v <= 1e12;
+  if (!(typeof pct === "number" && Number.isFinite(pct) && pct >= 0 && pct <= 100) || !ok(t.lines) || !ok(t.duplicatedLines) || !ok(t.clones)) return bad;
+  const locations = [];
+  for (const d of raw.duplicates.slice(0, MAX_CLONES)) {
+    const a = cleanClonePart(d?.firstFile);
+    const b = cleanClonePart(d?.secondFile);
+    if (a && b) locations.push({ a, b });
+  }
+  return { status: "ok", exitCode: 0, percentage: pct, lines: t.lines, duplicatedLines: t.duplicatedLines, clones: t.clones, locations };
+}
+
+export function loadVerified(file, sha, max = 2 * 1024 * 1024) {
+  try {
+    if (!/^[0-9a-f]{64}$/.test(sha ?? "")) return null;
+    const st = fs.lstatSync(file);
+    if (!st.isFile() || st.size > max) return null;
+    const buf = fs.readFileSync(file);
+    if (createHash("sha256").update(buf).digest("hex") !== sha) return null;
+    return JSON.parse(buf.toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+const countBy = (fs_) => fs_.reduce((a, f) => ((a[f.severity] = (a[f.severity] ?? 0) + 1), a), {});
+
+export function lcovToGenericXml(text, { srcRoot, workdir, workspaceSrc }) {
+  const root = fs.realpathSync(srcRoot);
+  const base = path.resolve(root, workdir);
+  const files = new Map();
+  let cur = null;
+  let skipped = 0;
+  let records = 0;
+  for (const line of text.split(/\r?\n/)) {
+    if (line.startsWith("SF:")) {
+      records++;
+      cur = null;
+      const sf = line.slice(3).trim();
+      let abs = path.isAbsolute(sf) ? sf : path.resolve(base, sf);
+      if (workspaceSrc && abs.startsWith(workspaceSrc + path.sep)) abs = path.join(root, abs.slice(workspaceSrc.length));
+      try {
+        const st = fs.lstatSync(abs);
+        const real = fs.realpathSync(abs);
+        const rel = path.relative(root, real);
+        if (!st.isFile() || rel.startsWith("..") || path.isAbsolute(rel) || !safeRelPath(rel.split(path.sep).join("/"))) throw new Error("x");
+        cur = files.get(rel) ?? new Map();
+        files.set(rel, cur);
+      } catch {
+        skipped++;
+      }
+    } else if (line.startsWith("DA:") && cur) {
+      const m = /^DA:(\d{1,8}),(\d{1,12})(?:,.*)?$/.exec(line);
+      if (m && Number(m[1]) > 0) cur.set(Number(m[1]), (cur.get(Number(m[1])) ?? 0) + Number(m[2]));
+    }
+    if (files.size > 20000) fail("too many files in LCOV");
+  }
+  let out = '<coverage version="1">\n';
+  let lines = 0;
+  for (const [rel, das] of files) {
+    out += `  <file path="${rel.split(path.sep).join("/")}">\n`;
+    for (const [n, hits] of das) {
+      out += `    <lineToCover lineNumber="${n}" covered="${hits > 0}"/>\n`;
+      lines++;
+    }
+    out += "  </file>\n";
+  }
+  return { xml: out + "</coverage>\n", stats: { records, files: files.size, lines, skipped } };
+}
+
+export function readBoundedRegular(file, max) {
+  const st = fs.lstatSync(file);
+  if (!st.isFile()) fail("not a regular file");
+  if (st.size > max) fail("file too large");
+  return fs.readFileSync(file, "utf8");
+}
+
+export function sonarGate({ hostUrl, hasToken, projectKey, defaultHead, mode = "required" }) {
+  if (mode === "off") return { status: "off", reason: "disabled by config (sonar.mode off)" };
+  let host = null;
+  try {
+    const u = new URL(hostUrl ?? "");
+    if (u.protocol === "https:" && !u.username && !u.password && !u.search && !u.hash) host = u.origin + u.pathname.replace(/\/$/, "");
+  } catch {
+    // invalid
+  }
+  if (!host) return { status: "incomplete", reason: "SONAR_HOST_URL variable missing or not a plain https URL" };
+  if (!hasToken) return { status: "incomplete", reason: "SONAR_TOKEN secret missing" };
+  if (!projectKey) return { status: "incomplete", reason: "sonar.projectKey not configured for this project" };
+  if (!defaultHead) return { status: "unsupported-revision", reason: "SonarQube Community analyzes only the project default branch head; this sha is not it" };
+  return { status: "ready", host };
+}
+
+const METRICS = ["bugs", "vulnerabilities", "code_smells", "security_hotspots", "coverage", "alert_status"];
+
+export function cleanMetrics(measures) {
+  const out = {};
+  for (const m of Array.isArray(measures) ? measures : []) {
+    if (!METRICS.includes(m?.metric)) continue;
+    const v = String(m.value ?? "");
+    if (m.metric === "alert_status" ? ["OK", "WARN", "ERROR", "NONE"].includes(v) : /^\d{1,12}(\.\d+)?$/.test(v)) out[m.metric] = v;
+  }
+  return out;
+}
+
+const OG_STATUS = ["ok", "partial", "error"];
+const SN_STATUS = ["ok", "incomplete", "unsupported-revision", "failed", "off"];
+
+function derivePolicy(outs, authorized) {
+  const dupMode = DUP_MODES.includes(outs.dup_mode) ? outs.dup_mode : null;
+  const dupMax = PERCENT_RE.test(String(outs.dup_max_percent ?? "")) && Number(outs.dup_max_percent) <= 100 ? Number(outs.dup_max_percent) : null;
+  const failOn = FAIL_ON.includes(outs.fail_on) ? outs.fail_on : null;
+  const sonarMode = SONAR_MODES.includes(outs.sonar_mode) ? outs.sonar_mode : null;
+  return {
+    failOn: failOn ?? "INFO",
+    sonarMode: sonarMode ?? "required",
+    dupMode: dupMode ?? "required",
+    dupMax: dupMax ?? 0,
+    invalid: authorized && (!failOn || !sonarMode || !dupMode || dupMax === null),
+  };
+}
+
+export function deriveReport({ inputs, needs, opengrep, sonar, jscpd, runUrl }) {
+  const res = (j) => needs?.[j]?.result ?? "skipped";
+  const outs = needs?.authorize?.outputs ?? {};
+  const incomplete = [];
+  const failures = [];
+  const notes = [];
+  let valid = true;
+  try {
+    validateInputs({ sha: inputs?.sha, requestId: inputs?.requestId });
+  } catch {
+    valid = false;
+  }
+  const policy = derivePolicy(outs, res("authorize") === "success");
+  if (policy.invalid) failures.push("review policy outputs missing or invalid (failing closed)");
+  if (res("authorize") !== "success") incomplete.push("authorization failed or did not run");
+  else if (res("prepare") !== "success") incomplete.push("source snapshot failed (see prepare job)");
+
+  const oc = (v) => (["success", "failure", "skipped"].includes(v) ? v : "unknown");
+  let tests;
+  if (res("authorize") !== "success" || res("prepare") !== "success") tests = { status: "skipped" };
+  else if (outs.test_configured !== "true") {
+    tests = { status: "not-configured" };
+    incomplete.push("tests not configured in .github/techbro-review.json");
+  } else {
+    const t = needs?.tests?.outputs ?? {};
+    tests = { status: oc(t.install_outcome) === "failure" ? "install-failed" : oc(t.test_outcome) === "success" ? "passed" : oc(t.test_outcome) === "failure" ? "failed" : "unknown" };
+    if (res("tests") !== "success" || tests.status === "unknown") incomplete.push("tests did not complete");
+    else if (tests.status !== "passed") failures.push(`tests ${tests.status}`);
+  }
+
+  let og;
+  if (res("opengrep") === "skipped") {
+    og = { status: "skipped", total: 0, bySeverity: {}, findings: [] };
+    incomplete.push("opengrep did not run");
+  } else if (res("opengrep") !== "success" || !isObj(opengrep) || !OG_STATUS.includes(opengrep.status)) {
+    og = { status: "error", total: 0, bySeverity: {}, findings: [] };
+    failures.push("opengrep job failed or its result is missing/untrusted");
+  } else {
+    const findings = (Array.isArray(opengrep.findings) ? opengrep.findings : [])
+      .map(cleanFinding)
+      .filter(Boolean)
+      .slice(0, 5000);
+    og = { status: opengrep.status, total: findings.length, bySeverity: countBy(findings), findings: findings.map((f) => ({ ...f, remediation: remediationFor(f.rule) })) };
+    if (og.status !== "ok") failures.push(`opengrep ${og.status}`);
+    if (policy.failOn !== "none") {
+      const hits = findings.filter((f) => SEV_RANK[f.severity] >= SEV_RANK[policy.failOn]).length;
+      if (hits) failures.push(`opengrep findings at or above ${policy.failOn}: ${hits}`);
+    }
+  }
+
+  let dup;
+  if (policy.dupMode === "off") {
+    dup = { status: "off", mode: "off", threshold: policy.dupMax, percentage: 0, clones: 0, locations: [] };
+    notes.push("duplication check skipped: disabled by config (duplication.mode off)");
+  } else {
+    const base = { mode: "required", threshold: policy.dupMax, percentage: 0, clones: 0, locations: [] };
+    if (res("jscpd") === "skipped") {
+      dup = { ...base, status: "skipped" };
+      incomplete.push("jscpd did not run");
+    } else if (res("jscpd") !== "success" || !isObj(jscpd) || !JS_STATUS.includes(jscpd.status)) {
+      dup = { ...base, status: "error" };
+      failures.push("jscpd job failed or its result is missing/untrusted");
+    } else {
+      const clean = sanitizeJscpd(
+        { statistics: { total: { percentage: jscpd.percentage, lines: jscpd.lines, duplicatedLines: jscpd.duplicatedLines, clones: jscpd.clones } }, duplicates: (Array.isArray(jscpd.locations) ? jscpd.locations : []).map((l) => ({ firstFile: { name: l?.a?.path, start: l?.a?.start, end: l?.a?.end }, secondFile: { name: l?.b?.path, start: l?.b?.start, end: l?.b?.end } })) },
+        jscpd.status === "ok" ? 0 : 1,
+      );
+      if (clean.status !== "ok") {
+        dup = { ...base, status: "error" };
+        failures.push("jscpd failed or reported invalid statistics");
+      } else {
+        const over = clean.percentage > policy.dupMax;
+        dup = { ...base, status: over ? "threshold-exceeded" : "ok", percentage: clean.percentage, lines: clean.lines, duplicatedLines: clean.duplicatedLines, clones: clean.clones, locations: clean.locations, remediation: over ? DUP_REMEDIATION : undefined };
+        if (over) failures.push(`duplication ${clean.percentage.toFixed(2)}% exceeds ${policy.dupMax}%`);
+      }
+    }
+  }
+
+  let sn;
+  const optional = policy.sonarMode === "optional";
+  if (policy.sonarMode === "off") {
+    sn = { status: "off", reason: "disabled by config (sonar.mode off)" };
+    notes.push("sonar skipped: disabled by config (sonar.mode off)");
+  } else if (res("sonar") === "skipped") {
+    sn = { status: "skipped" };
+    incomplete.push("sonar did not run");
+  } else if (res("sonar") !== "success" || !isObj(sonar) || !SN_STATUS.includes(sonar.status) || sonar.status === "off") {
+    sn = { status: "failed", reason: "sonar job failed or its result is missing/untrusted" };
+    failures.push(sn.reason);
+  } else {
+    sn = sonar;
+    if (sn.status === "failed") failures.push(`sonar failed${sn.reason ? `: ${sn.reason}` : ""}`);
+    else if (sn.status !== "ok") {
+      const msg = `sonar ${sn.status}${sn.reason ? `: ${sn.reason}` : ""}`;
+      if (optional) {
+        sn = { ...sn, status: "skipped-optional" };
+        notes.push(`${msg} (skipped-optional: sonar.mode optional)`);
+      } else incomplete.push(msg);
+    } else if (sn.metrics?.alert_status === "ERROR") {
+      sn = { ...sn, status: "gate-failed" };
+      failures.push("sonar quality gate failed");
+    }
+  }
+
+  return {
+    schemaVersion: 3,
+    policy: { failOn: policy.failOn, sonarMode: policy.sonarMode, duplication: { mode: policy.dupMode, maxPercent: policy.dupMax } },
+    project: NAME_RE.test(inputs?.project ?? "") ? inputs.project : "unknown",
+    sha: valid ? inputs.sha : "invalid",
+    requestId: valid ? inputs.requestId : "invalid",
+    runUrl: /^https:\/\/github\.com\/[\w.\-/]+$/.test(runUrl ?? "") ? runUrl : "",
+    jobs: Object.fromEntries(["authorize", "prepare", "tests", "opengrep", "jscpd", "sonar"].map((j) => [j, oc(res(j))])),
+    tests,
+    opengrep: og,
+    sonar: sn,
+    duplication: dup,
+    complete: incomplete.length === 0,
+    incomplete,
+    failures,
+    notes,
+    pass: incomplete.length === 0 && failures.length === 0,
+  };
+}
+
+const esc = (s) => String(s).replace(/[^\w .\-/:@+]/g, "_");
+
+export function reportMarkdown(r) {
+  const L = [`# techbro review: ${esc(r.project)} @ ${esc(r.sha.slice(0, 12))}`, "", `request \`${esc(r.requestId)}\` - ${r.complete ? "complete" : "**INCOMPLETE**"}`, ""];
+  L.push("| job | result |", "| --- | --- |", ...Object.entries(r.jobs).map(([k, v]) => `| ${k} | ${v} |`), "");
+  L.push(`- tests: ${esc(r.tests.status)}`);
+  L.push(`- opengrep: ${esc(r.opengrep.status)}, findings ${r.opengrep.total ?? 0} (${esc(JSON.stringify(r.opengrep.bySeverity ?? {}))})`);
+  if (r.duplication) L.push(`- duplication: ${esc(r.duplication.status)}, ${Number(r.duplication.percentage ?? 0).toFixed(2)}% (max ${Number(r.duplication.threshold ?? 0)}%), clones ${Number(r.duplication.clones ?? 0)}`);
+  L.push(`- sonar: ${esc(r.sonar.status)} ${esc(JSON.stringify(r.sonar.metrics ?? {}))}${r.sonar.coverage ? ` coverage import: ${esc(r.sonar.coverage.status)}` : ""}`);
+  if (r.incomplete.length) L.push("", "## Incomplete", ...r.incomplete.map((x) => `- ${esc(x)}`));
+  if (r.failures?.length) L.push("", "## Failures", ...r.failures.map((x) => `- ${esc(x)}`));
+  if (r.notes?.length) L.push("", "## Notes", ...r.notes.map((x) => `- ${esc(x)}`));
+  if (r.opengrep.findings?.length) {
+    L.push("", "## Opengrep findings (metadata only)", "| severity | rule | location | remediation |", "| --- | --- | --- | --- |");
+    for (const f of r.opengrep.findings.slice(0, 50)) L.push(`| ${f.severity} | ${esc(f.rule)} | ${esc(f.path)}:${f.line} | ${esc(f.remediation ?? remediationFor(f.rule))} |`);
+  }
+  if (r.duplication?.locations?.length) {
+    L.push("", "## Duplicated regions (locations only)", "| first | second |", "| --- | --- |");
+    for (const l of r.duplication.locations.slice(0, 20)) L.push(`| ${esc(l.a.path)}:${l.a.start}-${l.a.end} | ${esc(l.b.path)}:${l.b.start}-${l.b.end} |`);
+    if (r.duplication.remediation) L.push("", esc(r.duplication.remediation));
+  }
+  return L.join("\n") + "\n";
+}
+
+function setOutput(k, v) {
+  v = String(v);
+  if (/[\r\n]/.test(v)) fail(`output ${k} contains a newline`);
+  fs.appendFileSync(process.env.GITHUB_OUTPUT, `${k}=${v}\n`);
+}
+
+async function api(token, p, init = {}) {
+  const res = await fetch(`https://api.github.com${p}`, {
+    ...init,
+    headers: { Authorization: `Bearer ${token}`, Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28", "User-Agent": "techbro-review" },
+    signal: AbortSignal.timeout(60000),
+  });
+  return res;
+}
+
+async function apiJson(token, p) {
+  const res = await api(token, p);
+  if (!res.ok) fail(`GitHub ${res.status} for ${p.split("?")[0]}`);
+  return res.json();
+}
+
+function removeUnsafe(dir) {
+  let total = 0;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isSymbolicLink()) fs.rmSync(p);
+    else if (e.isDirectory()) total += removeUnsafe(p);
+    else if (e.isFile()) total += fs.statSync(p).size;
+    else fs.rmSync(p, { force: true });
+  }
+  return total;
+}
+
+function emitHash(file) {
+  setOutput("sha", createHash("sha256").update(fs.readFileSync(file)).digest("hex"));
+}
+const readJson = (f) => JSON.parse(fs.readFileSync(f, "utf8"));
+const writeJson = (f, v) => {
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, JSON.stringify(v, null, 2) + "\n");
+};
+
+const commands = {
+  async authorize() {
+    const e = process.env;
+    const { owner, repo } = parseRepository(e.REPOSITORY);
+    const dir = e.TEAM_DIR || fail("TEAM_DIR not set");
+    const res = await api(e.GH_TOKEN, `/repos/${owner}/${repo}/collaborators/${encodeURIComponent(e.ACTOR)}/permission`);
+    const permission = res.ok ? (await res.json()).permission : "none";
+    const cfg = path.join(dir, "techbro-review.json");
+    const plan = buildPlan({
+      inputs: { sha: e.INPUT_SHA, requestId: e.INPUT_REQUEST_ID },
+      repository: e.REPOSITORY,
+      eventName: e.EVENT_NAME,
+      actor: e.ACTOR,
+      refName: e.REF_NAME,
+      defaultBranch: e.DEFAULT_BRANCH,
+      projects: readJson(path.join(dir, "projects.json")),
+      members: readJson(path.join(dir, "members.json")),
+      config: fs.existsSync(cfg) ? readJson(cfg) : {},
+      permission,
+    });
+    writeJson("ctl/plan.json", plan);
+    const t = plan.test;
+    for (const [k, v] of Object.entries({
+      ok: "true", project: plan.project, sha: plan.sha, owner: plan.owner, repo: plan.repo, sonar_key: plan.sonarKey,
+      test_configured: t ? "true" : "false", test_runtime: t?.runtime ?? "", test_node_version: t?.nodeVersion ?? "",
+      test_workdir: t?.workdir ?? ".", test_install: t?.install ?? "", test_command: t?.command ?? "", test_coverage: t?.coverage ?? "",
+      test_rust_version: t?.rustVersion ?? "", fail_on: plan.failOn, sonar_mode: plan.sonarMode,
+      dup_mode: plan.dupMode, dup_max_percent: plan.dupMaxPercent,
+    })) setOutput(k, v);
+  },
+
+  async snapshot() {
+    const e = process.env;
+    const plan = readJson("ctl/plan.json");
+    const headFile = "checkout/.git/HEAD";
+    if (!fs.lstatSync(headFile).isFile() || fs.readFileSync(headFile, "utf8").trim() !== plan.sha) fail("checked-out commit does not match the requested sha");
+    const base = `/repos/${plan.owner}/${plan.repo}`;
+    const repo = await apiJson(e.GH_TOKEN, base);
+    const head = await apiJson(e.GH_TOKEN, `${base}/commits/${encodeURIComponent(repo.default_branch)}`);
+    fs.mkdirSync("snapshot", { recursive: true });
+    fs.cpSync("checkout", "snapshot", { recursive: true, verbatimSymlinks: true, filter: (src) => path.basename(src) !== ".git" });
+    if (removeUnsafe("snapshot") > MAX_UNPACKED) fail("unpacked source exceeds size limit");
+    setOutput("default_head", head.sha === plan.sha ? "true" : "false");
+  },
+
+  async sanitize() {
+    let raw = null;
+    try {
+      raw = readJson(process.env.RAW);
+    } catch {
+      // missing or invalid raw output
+    }
+    writeJson(process.env.OUT, sanitizeOpengrep(raw, Number(process.env.RC)));
+    emitHash(process.env.OUT);
+  },
+
+  async "jscpd-sanitize"() {
+    let raw = null;
+    try {
+      raw = JSON.parse(readBoundedRegular(process.env.RAW, 200 * 1024 * 1024));
+    } catch {
+      // missing, oversized or invalid raw output
+    }
+    writeJson(process.env.OUT, sanitizeJscpd(raw, Number(process.env.RC)));
+    emitHash(process.env.OUT);
+  },
+
+  async "sonar-gate"() {
+    const e = process.env;
+    const g = sonarGate({ hostUrl: e.SONAR_HOST_URL, hasToken: e.HAS_TOKEN === "true", projectKey: e.SONAR_KEY, defaultHead: e.DEFAULT_HEAD === "true", mode: e.SONAR_MODE });
+    setOutput("status", g.status);
+    writeJson(e.GATE_OUT, g);
+  },
+
+  async "sonar-coverage"() {
+    const e = process.env;
+    const plan = readJson("ctl/plan.json");
+    const cov = { status: "none" };
+    const lcov = path.join(e.COV_DIR, "lcov.info");
+    if (plan.test?.coverage && fs.existsSync(lcov)) {
+      try {
+        const { xml, stats } = lcovToGenericXml(readBoundedRegular(lcov, MAX_LCOV), { srcRoot: "src", workdir: plan.test.workdir, workspaceSrc: path.join(e.GITHUB_WORKSPACE, "src") });
+        Object.assign(cov, stats, { status: stats.files === 0 ? "empty" : stats.skipped ? "partial" : "ok" });
+        if (stats.files > 0) {
+          fs.writeFileSync(e.COV_XML, xml);
+          setOutput("arg", `-Dsonar.coverageReportPaths=${e.COV_XML}`);
+        }
+      } catch (err) {
+        cov.status = "invalid";
+        cov.reason = String(err.message).slice(0, 100);
+      }
+    } else if (plan.test?.coverage) cov.status = "missing";
+    writeJson(e.COV_OUT, cov);
+  },
+
+  async "sonar-result"() {
+    const e = process.env;
+    const gate = readJson(e.GATE_OUT);
+    const coverage = fs.existsSync(e.COV_OUT) ? readJson(e.COV_OUT) : { status: "none" };
+    const r = { status: gate.status, reason: gate.reason, coverage };
+    if (gate.status === "ready") {
+      const key = encodeURIComponent(e.SONAR_KEY);
+      const auth = "Basic " + Buffer.from(`${e.SONAR_TOKEN}:`).toString("base64");
+      const get = async (p) => {
+        const res = await fetch(`${gate.host}${p}`, { headers: { Authorization: auth }, signal: AbortSignal.timeout(30000) });
+        if (!res.ok) fail(`sonar API ${res.status}`);
+        return res.json();
+      };
+      const scanOk = e.SCAN_OUTCOME === "success";
+      try {
+        const m = await get(`/api/measures/component?component=${key}&metricKeys=${METRICS.join(",")}`);
+        r.metrics = cleanMetrics(m?.component?.measures);
+        r.dashboard = `${gate.host}/dashboard?id=${key}`;
+        if (scanOk || r.metrics.alert_status === "ERROR") {
+          r.status = "ok";
+          delete r.reason;
+        } else {
+          r.status = "failed";
+          r.reason = "scanner failed";
+        }
+      } catch (err) {
+        r.status = "failed";
+        r.reason = scanOk ? String(err.message).slice(0, 100) : "scanner failed";
+      }
+    }
+    delete r.host;
+    writeJson(e.OUT, r);
+    emitHash(e.OUT);
+  },
+
+  async report() {
+    const e = process.env;
+    const og = loadVerified(path.join(e.ART_DIR, "techbro-opengrep-result", "opengrep.json"), e.OG_SHA);
+    const sn = loadVerified(path.join(e.ART_DIR, "techbro-sonar-result", "sonar.json"), e.SN_SHA);
+    const sonar = isObj(sn)
+      ? {
+          status: SN_STATUS.includes(sn.status) ? sn.status : "failed",
+          reason: typeof sn.reason === "string" ? esc(sn.reason).slice(0, 200) : undefined,
+          metrics: cleanMetrics(Object.entries(sn.metrics ?? {}).map(([metric, value]) => ({ metric, value }))),
+          coverage: isObj(sn.coverage) ? { status: esc(sn.coverage.status).slice(0, 20) } : undefined,
+          dashboard: typeof sn.dashboard === "string" && /^https:\/\/[\w.\-:/?=%]+$/.test(sn.dashboard) ? sn.dashboard : undefined,
+        }
+      : null;
+    const jd = loadVerified(path.join(e.ART_DIR, "techbro-jscpd-result", "jscpd.json"), e.JD_SHA);
+    const jscpd = isObj(jd) ? jd : null;
+    const opengrep = isObj(og) ? { status: og.status, findings: Array.isArray(og.findings) ? og.findings : [] } : null;
+    const report = deriveReport({
+      inputs: { project: e.INPUT_PROJECT, sha: e.INPUT_SHA, requestId: e.INPUT_REQUEST_ID },
+      needs: JSON.parse(e.NEEDS),
+      opengrep,
+      sonar,
+      jscpd,
+      runUrl: e.RUN_URL,
+    });
+    writeJson("report/report.json", report);
+    const md = reportMarkdown(report);
+    fs.writeFileSync("report/report.md", md);
+    if (e.GITHUB_STEP_SUMMARY) fs.appendFileSync(e.GITHUB_STEP_SUMMARY, md);
+    if (!report.pass) process.exitCode = 1;
+  },
+};
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const cmd = commands[process.argv[2]];
+  if (!cmd) {
+    console.error(`unknown command: ${process.argv[2]}`);
+    process.exit(2);
+  }
+  cmd().catch((err) => {
+    console.error(`techbro-review: ${err.message}`);
+    process.exit(1);
+  });
+}