signoff-cli 0.0.0-stage → 4.0.0

package/lib/checkpoint.js

@@ -0,0 +1,184 @@
+"use strict";
+// Signed checkpoints for the P4 ledger.
+//
+// The ledger is already an append-only hash chain, which catches edits but not
+// deletion: truncate the file and every remaining line still verifies. A
+// checkpoint is a signed statement "at seq N the head was H and the tree root was
+// R"; it is written once, shipped somewhere the repo cannot reach (release notes,
+// CI summary, a colleague's message), and any later truncation or rewrite shows up
+// as a mismatch. The anchor line is the thing you publish:
+//
+//   signoff1:<seq>:<head12>:<root16>
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const p4 = require("./p4");
+const core = require("./core");
+const signlib = require("./sign");
+
+const VERSION = 1;
+const PREFIX = "signoff1";
+
+function sha256(s) {
+  return crypto.createHash("sha256").update(String(s), "utf8").digest("hex");
+}
+
+function checkpointPath() {
+  return path.join(path.dirname(p4.ledgerPath()), "checkpoint.json");
+}
+
+// Binary Merkle root over the per-record hashes; an odd node is paired with
+// itself, the usual convention, so the root is stable for any length.
+function merkleRoot(hashes) {
+  if (!hashes.length) return sha256("signoff:empty");
+  let level = hashes.map((h) => sha256("leaf:" + h));
+  while (level.length > 1) {
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      const a = level[i];
+      const b = i + 1 < level.length ? level[i + 1] : a;
+      next.push(sha256("node:" + a + b));
+    }
+    level = next;
+  }
+  return level[0];
+}
+
+// The exact bytes a signature covers. Versioned so a future format cannot be
+// replayed against this one.
+function payload(seq, head, root) {
+  return ["signoff-checkpoint", "v" + VERSION, String(seq), head, root].join("\n");
+}
+
+function anchorOf(seq, head, root) {
+  return `${PREFIX}:${seq}:${String(head).slice(0, 12)}:${String(root).slice(0, 16)}`;
+}
+
+function summarize() {
+  const chain = p4.entries();
+  const head = chain.length ? String(chain[chain.length - 1].hash || "") : "genesis";
+  const root = merkleRoot(chain.map((r) => String(r.hash || "")));
+  return { seq: chain.length, head, root, chain };
+}
+
+function create(opts) {
+  const o = opts || {};
+  const s = summarize();
+  const body = payload(s.seq, s.head, s.root);
+  let key = null;
+  let sig = null;
+  if (o.sign !== false) {
+    // A checkpoint nobody can attribute is decoration. If the machine has no key,
+    // make a repo-local one (same convention as guard --sign) instead of silently
+    // producing an unsigned file.
+    let keyPath = signlib.findKey();
+    if (!keyPath) {
+      keyPath = signlib.generateKey(path.join(path.dirname(p4.ledgerPath()), "keys"));
+      if (keyPath) process.env.SIGNOFF_SIGN_KEY = keyPath;
+    }
+    const signed = signlib.sign(body);
+    if (signed) {
+      key = signed.key;
+      sig = signed.sig;
+    }
+  }
+  const cp = {
+    version: VERSION,
+    seq: s.seq,
+    head: s.head,
+    root: s.root,
+    ts: p4.timestamp(),
+    repo: p4.repoKey(),
+    key: key,
+    sig: sig,
+    anchor: anchorOf(s.seq, s.head, s.root),
+  };
+  const file = o.file || checkpointPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(cp, null, 2) + "\n", "utf8");
+  return { ok: true, file, checkpoint: cp };
+}
+
+function readCheckpoint(file) {
+  const f = file || checkpointPath();
+  if (!fs.existsSync(f)) return null;
+  try {
+    const d = JSON.parse(fs.readFileSync(f, "utf8"));
+    return d && typeof d === "object" ? d : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+// Why a checkpoint would not verify, in the order a reader should care about:
+// missing, truncated (rollback), rewritten, bad signature.
+function verdict(cp, opts) {
+  const o = opts || {};
+  const root = o.root || process.cwd();
+  const problems = [];
+  if (!cp) {
+    return { ok: false, state: "missing", problems: ["no checkpoint written yet"] };
+  }
+  let chain;
+  try {
+    chain = p4.entries();
+  } catch (e) {
+    return { ok: false, state: "unreadable", problems: [String((e && e.message) || e)] };
+  }
+  const seq = Number(cp.seq);
+  const head = String(cp.head || "");
+  const rootHash = String(cp.root || "");
+  if (!Number.isFinite(seq) || seq < 0) problems.push("checkpoint seq is not a number");
+  if (!/^[0-9a-f]{64}$/.test(head) && head !== "genesis") problems.push("checkpoint head is not a hash");
+  if (seq > chain.length) {
+    problems.push(`ledger has ${chain.length} records but the checkpoint covers ${seq} (records were removed)`);
+  } else {
+    const actualHead = seq === 0 ? "genesis" : String(chain[seq - 1].hash || "");
+    if (actualHead !== head) problems.push(`record ${seq} hashes to ${actualHead.slice(0, 12)}, checkpoint says ${head.slice(0, 12)}`);
+    const actualRoot = merkleRoot(chain.slice(0, seq).map((r) => String(r.hash || "")));
+    if (actualRoot !== rootHash) problems.push("tree root does not match the checkpoint");
+  }
+  if (o.anchor) {
+    const want = anchorOf(seq, head, rootHash);
+    const got = core.pyStrip ? core.pyStrip(String(o.anchor)) : String(o.anchor).trim();
+    if (got !== want) problems.push(`published anchor '${got}' does not match local '${want}'`);
+  }
+  // Signature last: a chain that already fails cannot be rescued by a valid sig.
+  let state = "unsigned";
+  if (!problems.length) {
+    if (!cp.key || !cp.sig) {
+      if (!o.allowUnsigned) problems.push("checkpoint is not signed");
+    } else {
+      const allowed = signlib.allowedKeys(root);
+      const r = signlib.verify(payload(seq, head, rootHash), cp.key, cp.sig, allowed);
+      state = r.state;
+      if (!r.ok || state === "bad-signature" || state === "unverifiable") {
+        problems.push("signature: " + (r.reason || state));
+      }
+    }
+  }
+  return {
+    ok: problems.length === 0,
+    state: problems.length && state === "unsigned" ? "unsigned" : state,
+    seq,
+    head,
+    root: rootHash,
+    anchor: anchorOf(seq, head, rootHash),
+    problems,
+  };
+}
+
+module.exports = {
+  VERSION,
+  PREFIX,
+  create,
+  readCheckpoint,
+  verdict,
+  summarize,
+  merkleRoot,
+  payload,
+  anchorOf,
+  checkpointPath,
+};

package/lib/ci.js

@@ -0,0 +1,58 @@
+"use strict";
+// GitHub Actions output.
+//
+// A gate that prints a paragraph is invisible in a PR: the reviewer sees "job
+// failed" and scrolls a log. These helpers turn findings into annotations that
+// land on the changed line, and a step summary that survives the run.
+
+const fs = require("fs");
+
+function isCI() {
+  return String(process.env.GITHUB_ACTIONS || "").toLowerCase() === "true";
+}
+
+// GitHub's workflow-command escaping: % -> %25, CR -> %0D, LF -> %0A. A property
+// value additionally escapes , and : .
+function escData(s) {
+  return String(s).replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+
+function escProp(s) {
+  return escData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+
+// list: [{file, line, rule, message, level}]
+function annotate(list) {
+  if (!isCI()) return 0;
+  let n = 0;
+  for (const f of list || []) {
+    if (!f || !f.file) continue;
+    const level = f.level === "warning" ? "warning" : "error";
+    const props = [`file=${escProp(f.file)}`];
+    if (f.line) props.push(`line=${Number(f.line)}`);
+    if (f.rule) props.push(`title=${escProp("signoff/" + f.rule)}`);
+    const msg = f.message || `${f.rule || "signoff"} finding`;
+    process.stdout.write(`::${level} ${props.join(",")}::${escData(msg)}\n`);
+    n++;
+  }
+  return n;
+}
+
+function summary(md) {
+  const p = process.env.GITHUB_STEP_SUMMARY;
+  if (!p || !md) return false;
+  try {
+    fs.appendFileSync(p, String(md).replace(/\r\n/g, "\n") + "\n", "utf8");
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function table(rows, headers) {
+  const head = `| ${headers.join(" | ")} |`;
+  const sep = `| ${headers.map(() => "---").join(" | ")} |`;
+  return [head, sep, ...rows.map((r) => `| ${r.join(" | ")} |`)].join("\n");
+}
+
+module.exports = { isCI, annotate, summary, table, escData, escProp };

package/lib/core.js

@@ -0,0 +1,120 @@
+"use strict";
+// Shared helpers for the JavaScript gate implementations.
+// The gates are pure Node (>=18) on purpose: `npm i -g dsh-signoff` must give the
+// full P1-P5 set on any machine that can run npm, with no Python and no degraded mode.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const ROOT = path.join(__dirname, "..");
+
+function nowISO() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function readJSON(p, dflt) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch (e) {
+    return dflt;
+  }
+}
+
+function writeJSON(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + "\n", "utf8");
+}
+
+function writeText(p, text) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, text, "utf8");
+}
+
+function stateDir(cwd) {
+  const d = path.join(cwd || process.cwd(), ".signoff");
+  fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+function statePath(cwd, name) {
+  return path.join(stateDir(cwd), name);
+}
+
+function git(args, cwd) {
+  const r = spawnSync("git", args, { cwd: cwd || process.cwd(), encoding: "utf8", windowsHide: true });
+  return { code: r.status === null ? 127 : r.status, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
+}
+
+function json(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+function die(msg, code) {
+  process.stderr.write(String(msg) + "\n");
+  return code === undefined ? 1 : code;
+}
+
+// Minimal argv parser: `--flag`, `--key value`, `--key=value`, positionals.
+function parseArgs(argv, spec) {
+  const out = { _: [] };
+  for (const [k, v] of Object.entries(spec || {})) out[k] = v;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      const key = (eq === -1 ? a.slice(2) : a.slice(2, eq)).replace(/-([a-z])/g, (m, c) => c.toUpperCase());
+      let val;
+      if (eq !== -1) val = a.slice(eq + 1);
+      else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) val = argv[++i];
+      else val = true;
+      if (out[key] === undefined || Array.isArray(out[key])) {
+        if (Array.isArray(out[key])) out[key].push(val);
+        else out[key] = val;
+      } else if (val === true) out[key] = true;
+      else out[key] = val;
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function appendJsonl(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.appendFileSync(p, JSON.stringify(obj) + "\n", "utf8");
+}
+
+function sha256(text) {
+  return require("crypto").createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+// ~/.signoff, overridable for tests and for machines with a different home layout.
+function homeDir() {
+  const override = process.env.SIGNOFF_HOME;
+  if (override) {
+    fs.mkdirSync(override, { recursive: true });
+    return override;
+  }
+  const h = process.env.HOME || process.env.USERPROFILE || process.cwd();
+  const d = path.join(h, ".signoff");
+  fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+module.exports = {
+  ROOT,
+  nowISO,
+  readJSON,
+  writeJSON,
+  writeText,
+  stateDir,
+  statePath,
+  git,
+  json,
+  die,
+  parseArgs,
+  appendJsonl,
+  sha256,
+  homeDir,
+};

package/lib/cov.js

@@ -0,0 +1,253 @@
+"use strict";
+// Line coverage for the change, not for the repo.
+//
+// P2 grades scenarios - it answers "was this behaviour exercised". This answers a
+// narrower, harder question: of the lines this commit touches, how many did the
+// suite actually execute? It reads whatever the project already produces
+// (istanbul JSON, python `coverage json`, lcov.info) so no extra runner is needed.
+
+const fs = require("fs");
+const path = require("path");
+const core = require("./core");
+
+const USAGE =
+  "usage: signoff cov [-h] [--min PCT] [--diff] [--base REF] [--file PATH] [--json] [--allow-missing]";
+const HELP =
+  USAGE +
+  "\n\n" +
+  [
+    "options:",
+    "  -h, --help     show this help message and exit",
+    "  --min PCT      fail when changed-line coverage is below PCT (default 80)",
+    "  --diff         only count lines added by the change (default: whole files)",
+    "  --base REF     diff against REF (default: HEAD, or origin/main when present)",
+    "  --file PATH    read this coverage file instead of auto-detecting",
+    "  --json         print one JSON line",
+    "  --allow-missing pass when no coverage data exists instead of failing",
+  ].join("\n") +
+  "\n";
+
+const CANDIDATES = [
+  "coverage/coverage-final.json",
+  "coverage.json",
+  "coverage/lcov.info",
+  "lcov.info",
+  "coverage/lcov/lcov.info",
+];
+
+function norm(p) {
+  return String(p).replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+// ---- readers -------------------------------------------------------------
+
+function fromPython(obj, root) {
+  const out = new Map();
+  for (const [file, d] of Object.entries(obj.files || {})) {
+    const hit = new Set((d.executed_lines || []).map(Number));
+    const miss = new Set((d.missing_lines || []).map(Number));
+    const all = new Set([...hit, ...miss]);
+    if (!all.size) continue;
+    out.set(norm(path.isAbsolute(file) ? path.relative(root, file) : file), { hit, all });
+  }
+  return out;
+}
+
+function fromIstanbul(obj, root) {
+  const out = new Map();
+  for (const [file, d] of Object.entries(obj)) {
+    if (!d || typeof d !== "object" || !d.statementMap || !d.s) continue;
+    const hit = new Set();
+    const all = new Set();
+    for (const [id, st] of Object.entries(d.statementMap)) {
+      const ln = st && st.start ? st.start.line : 0;
+      if (!ln) continue;
+      all.add(ln);
+      if (Number((d.s || {})[id] || 0) > 0) hit.add(ln);
+    }
+    if (all.size) out.set(norm(path.isAbsolute(file) ? path.relative(root, file) : file), { hit, all });
+  }
+  return out;
+}
+
+function fromLcov(text) {
+  const out = new Map();
+  let cur = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    if (line.startsWith("SF:")) {
+      cur = { file: norm(line.slice(3).trim()), hit: new Set(), all: new Set() };
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith("DA:")) {
+      const [ln, count] = line.slice(3).split(",");
+      const n = Number(ln);
+      if (!n) continue;
+      cur.all.add(n);
+      if (Number(count) > 0) cur.hit.add(n);
+    }
+    if (line === "end_of_record") {
+      if (cur.all.size) out.set(cur.file, { hit: cur.hit, all: cur.all });
+      cur = null;
+    }
+  }
+  if (cur && cur.all.size) out.set(cur.file, { hit: cur.hit, all: cur.all });
+  return out;
+}
+
+function load(root, explicit) {
+  const tried = explicit ? [explicit] : CANDIDATES;
+  for (const rel of tried) {
+    const p = path.isAbsolute(rel) ? rel : path.join(root, rel);
+    if (!fs.existsSync(p)) continue;
+    const text = fs.readFileSync(p, "utf8");
+    if (/\/(coverage-final|coverage)\.json$|^coverage\.json$|\.json$/.test(rel)) {
+      let obj;
+      try {
+        obj = JSON.parse(text);
+      } catch (e) {
+        continue;
+      }
+      const map = obj && obj.files ? fromPython(obj, root) : fromIstanbul(obj, root);
+      if (map.size) return { source: rel, map };
+    } else {
+      const map = fromLcov(text);
+      if (map.size) return { source: rel, map };
+    }
+  }
+  return { source: null, map: new Map() };
+}
+
+// ---- diff ----------------------------------------------------------------
+
+function baseRef(root, given) {
+  if (given) return given;
+  const originMain = core.git(["rev-parse", "--verify", "--quiet", "origin/main"], root);
+  if (originMain.code === 0 && originMain.out.trim()) return "origin/main";
+  const head = core.git(["rev-parse", "--verify", "--quiet", "HEAD"], root);
+  return head.code === 0 ? "HEAD" : null;
+}
+
+// Added line numbers per file, from a zero-context diff. Deleted lines are not
+// coverage targets: nothing can execute a line that no longer exists.
+function changedLines(root, base) {
+  const r = core.git(["diff", "--unified=0", "--no-color", base, "--"], root);
+  const out = new Map();
+  if (r.code !== 0) return out;
+  let file = null;
+  for (const line of r.out.split(/\r?\n/)) {
+    if (line.startsWith("+++ b/")) {
+      file = norm(line.slice(6).trim());
+      continue;
+    }
+    if (line.startsWith("+++ ") && line.includes("/dev/null")) {
+      file = null;
+      continue;
+    }
+    const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (!m || !file) continue;
+    const start = Number(m[1]);
+    const count = m[2] === undefined ? 1 : Number(m[2]);
+    if (!out.has(file)) out.set(file, new Set());
+    for (let i = 0; i < count; i++) out.get(file).add(start + i);
+  }
+  return out;
+}
+
+function parse(argv) {
+  const a = { min: 80, diff: false, base: null, file: null, json: false, allowMissing: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const tok = String(argv[i]);
+    const val = () => {
+      if (tok.includes("=")) return tok.slice(tok.indexOf("=") + 1);
+      if (i + 1 >= argv.length) return undefined;
+      i++;
+      return String(argv[i]);
+    };
+    if (tok === "-h" || tok === "--help") a.help = true;
+    else if (tok === "--diff") a.diff = true;
+    else if (tok === "--json") a.json = true;
+    else if (tok === "--allow-missing") a.allowMissing = true;
+    else if (tok === "--min" || tok.startsWith("--min=")) {
+      const v = val();
+      if (v === undefined || Number.isNaN(Number(v))) return { error: "argument --min: expected a number" };
+      a.min = Number(v);
+    } else if (tok === "--base" || tok.startsWith("--base=")) {
+      const v = val();
+      if (v === undefined) return { error: "argument --base: expected one argument" };
+      a.base = v;
+    } else if (tok === "--file" || tok.startsWith("--file=")) {
+      const v = val();
+      if (v === undefined) return { error: "argument --file: expected one argument" };
+      a.file = v;
+    } else if (tok.startsWith("-") && tok.length > 1) return { error: `unrecognized arguments: ${tok}` };
+  }
+  return a;
+}
+
+function run(argv) {
+  const a = parse(argv || []);
+  if (a.error) {
+    process.stderr.write(USAGE + "\n" + `signoff cov: error: ${a.error}\n`);
+    return 2;
+  }
+  if (a.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  const root = core.git(["rev-parse", "--show-toplevel"], process.cwd()).out.trim() || process.cwd();
+  const { source, map } = load(root, a.file);
+  if (!map.size) {
+    const msg = a.allowMissing ? "no coverage data (allowed)" : "no coverage data found (looked for " + CANDIDATES.join(", ") + ")";
+    if (a.json) core.json({ gate: "cov", ok: !!a.allowMissing, source: null, reason: msg });
+    else process.stdout.write(`[cov] ${a.allowMissing ? "PASS" : "FAIL"} ${msg}\n`);
+    return a.allowMissing ? 0 : 2;
+  }
+
+  const base = baseRef(root, a.base);
+  const changed = a.diff && base ? changedLines(root, base) : null;
+  const files = [];
+  let covered = 0;
+  let total = 0;
+  for (const [file, data] of map) {
+    const wanted = changed ? changed.get(file) : data.all;
+    if (!wanted || !wanted.size) continue;
+    let fTotal = 0;
+    let fHit = 0;
+    for (const ln of wanted) {
+      if (!data.all.has(ln)) continue; // line exists but the runner did not instrument it
+      fTotal++;
+      if (data.hit.has(ln)) fHit++;
+    }
+    if (!fTotal) continue;
+    covered += fHit;
+    total += fTotal;
+    files.push({ file, covered: fHit, total: fTotal, pct: Math.round((fHit / fTotal) * 1000) / 10 });
+  }
+  files.sort((x, y) => x.pct - y.pct || x.file.localeCompare(y.file));
+  const pct = total ? Math.round((covered / total) * 1000) / 10 : 100;
+  const ok = total === 0 || pct >= a.min;
+
+  core.writeJSON(path.join(root, ".signoff", "cov.json"), {
+    gate: "cov",
+    ok,
+    source,
+    base,
+    mode: changed ? "diff" : "files",
+    covered,
+    total,
+    pct,
+    min: a.min,
+    files,
+  });
+
+  if (a.json) {
+    core.json({ gate: "cov", ok, source, mode: changed ? "diff" : "files", covered, total, pct, min: a.min, files: files.length });
+  } else {
+    for (const f of files.slice(0, 10)) console.log(`[cov] ${String(f.pct).padStart(5)}%  ${f.covered}/${f.total}  ${f.file}`);
+    console.log(`[cov] ${ok ? "PASS" : "FAIL"} ${pct}% of ${changed ? "changed" : "instrumented"} lines (min ${a.min}%), source=${source}`);
+  }
+  return ok ? 0 : 1;
+}
+
+module.exports = { run, USAGE, HELP, load, changedLines, fromLcov };