codetrellis 0.0.0-stage → 0.3.0

package/src/backend/services/rule-approvals.js

@@ -0,0 +1,275 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var rule_approvals_exports = {};
+__export(rule_approvals_exports, {
+  APPROVALS_DIR: () => APPROVALS_DIR,
+  RULE_CHANGE_NAMESPACE: () => RULE_CHANGE_NAMESPACE,
+  approvalFor: () => approvalFor,
+  approvalYaml: () => approvalYaml,
+  approvalsHere: () => approvalsHere,
+  deviceBytes: () => deviceBytes,
+  keysAt: () => keysAt,
+  parseApproval: () => parseApproval,
+  ruleTerms: () => ruleTerms,
+  signRuleChange: () => signRuleChange,
+  statementBytes: () => statementBytes
+});
+module.exports = __toCommonJS(rule_approvals_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_os = __toESM(require("node:os"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_crypto = require("node:crypto");
+var import_node_child_process = require("node:child_process");
+var import_yaml = require("yaml");
+var import_architecture_rules = require("../../shared/types/architecture-rules");
+var import_confined_fs = require("./confined-fs");
+var import_signed_approvals = require("./signed-approvals");
+var import_signing = require("./task-records/signing");
+var import_trust = require("./task-records/trust");
+const RULE_CHANGE_NAMESPACE = "codetrellis-rule-change";
+const APPROVALS_DIR = ".codetrellis/rules/approvals";
+const KIND = "codetrellis-rule-change";
+const MAX_APPROVALS = 200;
+const MAX_BYTES = 16 * 1024;
+const COMMIT = /^[0-9a-f]{40}$/;
+function ruleTerms(r) {
+  if (!r) return null;
+  const t = termsOf(r);
+  return r.tags?.length ? { ...t, tags: [...r.tags].sort() } : t;
+}
+function termsOf(r) {
+  const terms = { from: r.from, mayNotImport: r.mayNotImport, except: [...r.except].sort(), strength: r.strength };
+  if (r.kind === "folder") return { ...terms, kind: "folder", files: [...r.files ?? []].sort(), kinds: [...r.kinds ?? []].sort(), ...r.exports ? { exports: r.exports } : {} };
+  if (r.kind === "agent") return { ...terms, kind: "agent", in: [...r.in ?? []].sort() };
+  if (r.kind === "grep") return { ...terms, kind: "grep", in: [...r.in ?? []].sort(), ...r.must ? { must: true } : {}, ...r.ignoreCase ? { ignoreCase: true } : {}, ...r.match ? { match: r.match } : {}, ...r.threshold !== void 0 ? { threshold: r.threshold } : {} };
+  return r.kind === "package" || r.kind === "symbol" || r.kind === "calls" ? { ...terms, kind: r.kind, only: [...r.only ?? []].sort(), ...r.match ? { match: r.match } : {}, ...r.threshold !== void 0 ? { threshold: r.threshold } : {} } : terms;
+}
+const statementBytes = (s) => (0, import_signing.canonicalJson)(s);
+const deviceBytes = (bytes) => `${RULE_CHANGE_NAMESPACE}
+${bytes}`;
+function approvalYaml(s, signature) {
+  return "# CodeTrellis: a person approved this change to an architecture rule, in the app.\n# CI accepts the change only if this verifies against keys on the base branch.\n" + (0, import_yaml.stringify)({ kind: KIND, version: 1, statement: statementBytes(s), signature }, { lineWidth: 0 });
+}
+const isTerms = (v) => {
+  if (!v || typeof v !== "object") return false;
+  const t = v;
+  return typeof t.from === "string" && typeof t.mayNotImport === "string" && Array.isArray(t.except) && t.except.every((e) => typeof e === "string") && import_architecture_rules.RULE_STRENGTHS.includes(t.strength);
+};
+function parseApproval(text) {
+  if (Buffer.byteLength(text, "utf8") > MAX_BYTES) return { error: "larger than an approval can be" };
+  let raw;
+  try {
+    raw = (0, import_yaml.parse)(text, { maxAliasCount: 0 });
+  } catch {
+    return { error: "not YAML" };
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: "not an approval" };
+  const r = raw;
+  if (r.kind !== KIND || r.version !== 1 || typeof r.statement !== "string") return { error: "not a rule-change approval this version reads" };
+  const signature = (0, import_signing.parseSignature)(r.signature);
+  if (!signature) return { error: "it has no signature this version reads" };
+  let s;
+  try {
+    s = JSON.parse(r.statement);
+  } catch {
+    return { error: "its statement is not JSON" };
+  }
+  if (s.kind !== KIND || s.version !== 1 || typeof s.rule !== "string" || typeof s.signer !== "string" || typeof s.at !== "string" || !(s.before === null || isTerms(s.before)) || !(s.after === null || isTerms(s.after)) || !(s.base === null || typeof s.base === "string" && COMMIT.test(s.base))) {
+    return { error: "its statement is not a rule change" };
+  }
+  const statement = s;
+  if (statementBytes(statement) !== r.statement) return { error: "its statement is not in canonical form" };
+  return { statement, bytes: r.statement, signature };
+}
+function git(cwd, args) {
+  try {
+    return (0, import_node_child_process.execFileSync)("git", ["-C", cwd, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15e3, maxBuffer: 4 * 1024 * 1024 });
+  } catch {
+    return null;
+  }
+}
+function signRuleChange(projectRoot, change, device, now = Date.now()) {
+  const head = git(projectRoot, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])?.trim() ?? null;
+  const base = head && COMMIT.test(head) ? head : null;
+  const at = new Date(now).toISOString();
+  const draft = (signer) => ({
+    kind: KIND,
+    version: 1,
+    rule: change.rule,
+    before: ruleTerms(change.before),
+    after: ruleTerms(change.after),
+    base,
+    signer,
+    at
+  });
+  let statement = null;
+  let signature = null;
+  const setup = process.env.CODETRELLIS_GIT_SIGN_RECORDS === "0" ? null : (0, import_signed_approvals.signingSetup)(projectRoot);
+  if (setup?.canSign) {
+    statement = draft(setup.signer);
+    try {
+      const value = (0, import_node_child_process.execFileSync)("ssh-keygen", ["-Y", "sign", "-f", setup.keyFile, "-n", RULE_CHANGE_NAMESPACE], {
+        input: statementBytes(statement),
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 15e3
+      });
+      signature = { how: "git", signer: setup.signer, value: value.trim() };
+    } catch (err) {
+      console.warn("[Rules] git could not sign the approval; the device key signs it:", err.message.split("\n")[0]);
+      statement = null;
+    }
+  }
+  if (!statement || !signature) {
+    const key = (0, import_trust.deviceKey)();
+    (0, import_trust.introduceDeviceKey)(projectRoot, device.writer, device.name, key);
+    statement = draft(key.fingerprint);
+    signature = (0, import_signing.signWithDevice)(key, deviceBytes(statementBytes(statement)));
+  }
+  const bytes = statementBytes(statement);
+  const rel = `${APPROVALS_DIR}/${change.rule}-${(0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex").slice(0, 12)}.yaml`;
+  (0, import_confined_fs.writeFileWithin)(projectRoot, rel, approvalYaml(statement, signature), "rule approval");
+  return { file: rel, how: signature.how, as: statement.signer };
+}
+function canonicalFolderOf(file) {
+  try {
+    return import_node_path.default.join(import_node_fs.default.realpathSync(import_node_path.default.dirname(file)), import_node_path.default.basename(file));
+  } catch {
+    return file;
+  }
+}
+function keysAt(projectRoot, commit) {
+  const devices = /* @__PURE__ */ new Map();
+  const listing = git(projectRoot, ["ls-tree", "--name-only", commit, `./${import_trust.KEYS_DIR}/`]);
+  for (const line of (listing ?? "").split("\n").map((l) => l.trim()).filter(Boolean).slice(0, 500)) {
+    const name = import_node_path.default.basename(line);
+    const m = /^([a-f0-9]{8,32})\.yaml$/.exec(name);
+    if (!m) continue;
+    const text = git(projectRoot, ["show", `${commit}:./${import_trust.KEYS_DIR}/${name}`]);
+    if (!text) continue;
+    const parsed = (0, import_signing.parseKeyIntroduction)(text, m[1]);
+    if ("key" in parsed) devices.set(parsed.key.fingerprint, parsed.key.publicKey);
+  }
+  let allowedSigners = null;
+  let tmp = null;
+  const configured = (0, import_signed_approvals.signingSetup)(projectRoot).allowedSigners;
+  if (configured) {
+    const top = git(projectRoot, ["rev-parse", "--show-toplevel"])?.trim();
+    const inRepo = top ? import_node_path.default.relative(import_node_fs.default.realpathSync(top), canonicalFolderOf(import_node_path.default.resolve(configured))) : null;
+    if (inRepo !== null && !inRepo.startsWith("..") && !import_node_path.default.isAbsolute(inRepo)) {
+      const text = git(top, ["show", `${commit}:${inRepo.split(import_node_path.default.sep).join("/")}`]);
+      if (text !== null) {
+        tmp = import_node_fs.default.mkdtempSync(import_node_path.default.join(import_node_os.default.tmpdir(), "codetrellis-signers-"));
+        allowedSigners = import_node_path.default.join(tmp, "allowed_signers");
+        import_node_fs.default.writeFileSync(allowedSigners, text, { mode: 384 });
+      }
+    } else if (import_node_fs.default.existsSync(configured)) {
+      allowedSigners = configured;
+    }
+  }
+  return { devices, allowedSigners, done: () => {
+    if (tmp) import_node_fs.default.rmSync(tmp, { recursive: true, force: true });
+  } };
+}
+function approvalsHere(projectRoot) {
+  const dir = import_node_path.default.join(projectRoot, APPROVALS_DIR);
+  let names;
+  try {
+    names = import_node_fs.default.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".yaml")).map((e) => e.name).sort().slice(0, MAX_APPROVALS);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    const file = `${APPROVALS_DIR}/${name}`;
+    let text;
+    try {
+      text = (0, import_confined_fs.readTextWithin)(projectRoot, file, "rule approval");
+    } catch {
+      continue;
+    }
+    const p = parseApproval(text);
+    if ("statement" in p) out.push({ ...p, file });
+  }
+  return out;
+}
+function approvalFor(projectRoot, change, approvals, keys, mergeBase) {
+  const before = (0, import_signing.canonicalJson)(ruleTerms(change.before));
+  const after = (0, import_signing.canonicalJson)(ruleTerms(change.after));
+  const claims = approvals.filter((a) => a.statement.rule === change.rule && (0, import_signing.canonicalJson)(a.statement.before) === before && (0, import_signing.canonicalJson)(a.statement.after) === after);
+  if (claims.length === 0) return null;
+  let why = "";
+  for (const a of claims) {
+    const s = a.statement;
+    if (!s.base) {
+      why = `${a.file} was not made in a git checkout`;
+      continue;
+    }
+    if (git(projectRoot, ["merge-base", "--is-ancestor", mergeBase, s.base]) === null) {
+      why = `${a.file} was made at ${s.base.slice(0, 7)}, before this change's base (or that commit is not in this clone), so it approves an earlier change`;
+      continue;
+    }
+    if (a.signature.how === "device") {
+      const pub = keys.devices.get(a.signature.key);
+      if (!pub) {
+        why = `${a.file} is signed with a device key the base branch does not list under ${import_trust.KEYS_DIR}/`;
+        continue;
+      }
+      if (a.signature.key !== s.signer || !(0, import_signing.verifyWithDevice)(pub, deviceBytes(a.bytes), a.signature.value)) {
+        why = `${a.file}'s signature does not verify`;
+        continue;
+      }
+      return { ok: true, by: s.signer, how: "device", file: a.file };
+    }
+    if (a.signature.signer !== s.signer) {
+      why = `${a.file} names one signer in its statement and another on its signature`;
+      continue;
+    }
+    const v = (0, import_signed_approvals.verifyRecord)(a.bytes, a.signature.value, s.signer, keys.allowedSigners, RULE_CHANGE_NAMESPACE);
+    if (!v.ok) {
+      why = `${a.file}: ${v.reason}`;
+      continue;
+    }
+    return { ok: true, by: s.signer, how: "git", file: a.file };
+  }
+  return { ok: false, why };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APPROVALS_DIR,
+  RULE_CHANGE_NAMESPACE,
+  approvalFor,
+  approvalYaml,
+  approvalsHere,
+  deviceBytes,
+  keysAt,
+  parseApproval,
+  ruleTerms,
+  signRuleChange,
+  statementBytes
+});

package/src/backend/services/rule-baseline.js

@@ -0,0 +1,134 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var rule_baseline_exports = {};
+__export(rule_baseline_exports, {
+  BASELINE_FILE: () => BASELINE_FILE,
+  baselineAt: () => baselineAt,
+  baselineOf: () => baselineOf,
+  baselineYaml: () => baselineYaml,
+  parseBaseline: () => parseBaseline,
+  ratchet: () => ratchet,
+  readBaseline: () => readBaseline
+});
+module.exports = __toCommonJS(rule_baseline_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_child_process = require("node:child_process");
+var import_yaml = require("yaml");
+var import_architecture_rule = require("./architecture-rule");
+var import_confined_fs = require("./confined-fs");
+const BASELINE_FILE = ".codetrellis/rules/baseline.yaml";
+const MAX_ENTRIES = 2e4;
+const entry = (e) => `${e.from} > ${e.to}`;
+function parseBaseline(text) {
+  const out = /* @__PURE__ */ new Map();
+  let raw;
+  try {
+    raw = (0, import_yaml.parse)(text, { maxAliasCount: 0 });
+  } catch {
+    return out;
+  }
+  const rules = raw && typeof raw === "object" ? raw.rules : null;
+  if (!rules || typeof rules !== "object" || Array.isArray(rules)) return out;
+  let n = 0;
+  for (const [id, list] of Object.entries(rules)) {
+    if (!Array.isArray(list)) continue;
+    const set = /* @__PURE__ */ new Set();
+    for (const x of list) {
+      if (typeof x !== "string" || !x.includes(" > ") || ++n > MAX_ENTRIES) continue;
+      set.add(x.trim());
+    }
+    out.set(id, set);
+  }
+  return out;
+}
+function baselineYaml(b) {
+  const rules = {};
+  for (const id of [...b.keys()].sort()) rules[id] = [...b.get(id)].sort();
+  return "# CodeTrellis: imports that already broke each rule when it was baselined.\n# The check fails on any breach not listed here, and this file may only shrink.\n# Written by `codetrellis rules baseline`; fix a breach, then run it again.\n" + (0, import_yaml.stringify)({ rules }, { lineWidth: 0 });
+}
+function baselineOf(rules, edges) {
+  const out = /* @__PURE__ */ new Map();
+  for (const r of rules) {
+    if (r.strength === "guide") continue;
+    out.set(r.id, new Set((0, import_architecture_rule.checkEdges)([r], edges).map(entry)));
+  }
+  return out;
+}
+function readBaseline(projectRoot) {
+  if (!import_node_fs.default.existsSync(import_node_path.default.join(projectRoot, BASELINE_FILE))) return null;
+  try {
+    return parseBaseline((0, import_confined_fs.readTextWithin)(projectRoot, BASELINE_FILE, "rule baseline"));
+  } catch {
+    return null;
+  }
+}
+function baselineAt(projectRoot, commit) {
+  try {
+    const text = (0, import_node_child_process.execFileSync)("git", ["-C", projectRoot, "show", `${commit}:./${BASELINE_FILE}`], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 16 * 1024 * 1024 });
+    return parseBaseline(text);
+  } catch {
+    return null;
+  }
+}
+function ratchet(base, head, rules, edges) {
+  const out = [];
+  for (const [id, entries] of head ?? /* @__PURE__ */ new Map()) {
+    const was = base?.get(id);
+    if (!was) continue;
+    const added = [...entries].filter((e) => !was.has(e));
+    if (added.length) {
+      out.push({ rule: id, kind: "grew", words: `\u2717 This change adds ${added.length} ${added.length === 1 ? "entry" : "entries"} to the baseline of ${id} (${added.slice(0, 3).join(", ")}${added.length > 3 ? ", \u2026" : ""}); a baseline may only shrink.` });
+    }
+  }
+  if (!base) return out;
+  for (const r of rules) {
+    const listed = base.get(r.id);
+    if (!listed || r.strength === "guide") continue;
+    const breaches = (0, import_architecture_rule.checkEdges)([r], edges);
+    for (const b of breaches) {
+      if (listed.has(entry(b))) continue;
+      out.push({ rule: r.id, kind: "breach", from: b.from, to: b.to, words: `\u2717 ${b.from} imports ${b.to}, which the rule \u201C${(0, import_architecture_rule.ruleStatement)({ ...r, except: [] })}\u201D forbids, and its baseline does not list it` });
+    }
+    const left = breaches.filter((b) => listed.has(entry(b))).length;
+    if (left < listed.size) {
+      out.push({ rule: r.id, kind: "fell", words: `\u2193 ${r.id}: ${left} ${left === 1 ? "breach" : "breaches"} left, down from ${listed.size} in the baseline. Run \`codetrellis rules baseline\` to lock in the lower count.` });
+    }
+  }
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BASELINE_FILE,
+  baselineAt,
+  baselineOf,
+  baselineYaml,
+  parseBaseline,
+  ratchet,
+  readBaseline
+});

package/src/backend/services/rule-changes.js

@@ -0,0 +1,162 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key2 of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key2) && key2 !== except)
+        __defProp(to, key2, { get: () => from[key2], enumerable: !(desc = __getOwnPropDesc(from, key2)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var rule_changes_exports = {};
+__export(rule_changes_exports, {
+  NEEDS: () => NEEDS,
+  changeWords: () => changeWords,
+  diffRules: () => diffRules
+});
+module.exports = __toCommonJS(rule_changes_exports);
+var import_architecture_rule = require("./architecture-rule");
+const key = (e) => e.to.startsWith("folder:") ? `${e.from}>folder` : `${e.from}>${e.to}`;
+const breaches = (rule, edges) => (0, import_architecture_rule.checkEdges)([rule], edges).map((b) => ({ from: b.from, to: b.to }));
+const minus = (a, b) => {
+  const drop = new Set(b.map(key));
+  return a.filter((e) => !drop.has(key(e)));
+};
+const imports = (n, r) => {
+  const noun = r?.kind === "grep" ? r.must ? "file" : "line" : "import";
+  return `${n} ${noun}${n === 1 ? "" : "s"}`;
+};
+const sameSet = (a, b) => a.length === b.length && [...a].sort().every((x, i) => x === [...b].sort()[i]);
+function textEffect(base, head) {
+  const pathsSame = (base.kind ?? "imports") === (head.kind ?? "imports") && base.from === head.from && base.mayNotImport === head.mayNotImport && (base.match ?? null) === (head.match ?? null);
+  const threshold = (base.threshold ?? null) === (head.threshold ?? null) ? "same" : (head.threshold ?? 1) < (base.threshold ?? 1) ? "tightens" : "loosens";
+  const baseOnly = base.only ?? [];
+  const headOnly = head.only ?? [];
+  const onlySame = sameSet(baseOnly, headOnly);
+  const onlyShrank = headOnly.every((o) => baseOnly.includes(o));
+  const allowed = (b = [], h = []) => sameSet(b, h) ? "same" : b.length === 0 && h.length > 0 || h.length > 0 && h.every((x) => b.includes(x)) ? "tightens" : "loosens";
+  const folder = [
+    allowed(base.files, head.files),
+    allowed(base.kinds, head.kinds),
+    base.exports === head.exports ? "same" : head.exports === "one" ? "tightens" : "loosens"
+  ];
+  const grepSame = sameSet(base.in ?? [], head.in ?? []) && !!base.must === !!head.must && !!base.ignoreCase === !!head.ignoreCase;
+  const baseTags = base.tags ?? [];
+  const headTags = head.tags ?? [];
+  const tags = sameSet(baseTags, headTags) ? "same" : baseTags.every((t) => headTags.includes(t)) ? "tightens" : "loosens";
+  const folderSame = folder.every((f) => f === "same") && grepSame && threshold === "same" && tags === "same";
+  const folderTighter = folder.every((f) => f !== "loosens") && grepSame && threshold !== "loosens" && tags !== "loosens";
+  if (pathsSame && onlySame && sameSet(base.except, head.except) && folderSame) return "same";
+  if (pathsSame && onlyShrank && head.except.every((e) => base.except.includes(e)) && folderTighter) return "tightens";
+  return "loosens";
+}
+const RANK = { guide: 0, warn: 1, block: 2 };
+function strengthEffect(base, head) {
+  const d = RANK[head.strength] - RANK[base.strength];
+  return d === 0 ? "same" : d > 0 ? "tightens" : "loosens";
+}
+const stated = (r) => `\u201C${(0, import_architecture_rule.ruleStatement)(r)}\u201D`;
+function diffRules(base, head, edges) {
+  const out = [];
+  const before = new Map(base.map((r) => [r.id, r]));
+  const after = new Map(head.map((r) => [r.id, r]));
+  for (const [id, b] of before) {
+    const h = after.get(id);
+    if (!h) {
+      const allowed2 = breaches(b, edges);
+      out.push({
+        rule: id,
+        change: "removed",
+        effect: "loosens",
+        allowed: allowed2,
+        forbidden: [],
+        before: b,
+        after: null,
+        words: `\u2717 This change removes the rule \u201C${(0, import_architecture_rule.ruleStatement)({ ...b, except: [] })}\u201D (${id})${allowed2.length ? `: ${imports(allowed2.length, b)} it forbade become allowed` : ""}. Loosening a rule needs a person's approval in the app.`
+      });
+      continue;
+    }
+    const text = textEffect(b, h);
+    const strength = strengthEffect(b, h);
+    if (text === "same" && strength === "same") {
+      if (b.because !== h.because) {
+        out.push({ rule: id, change: "changed", effect: "reworded", allowed: [], forbidden: [], before: b, after: h, words: `\xB7 This change rewords why the rule ${id} exists.` });
+      }
+      continue;
+    }
+    const was = breaches(b, edges);
+    const now = breaches(h, edges);
+    if (text === "same") {
+      const n = was.length;
+      out.push(strength === "loosens" ? {
+        rule: id,
+        change: "changed",
+        effect: "loosens",
+        allowed: b.strength === "block" ? was : [],
+        forbidden: [],
+        before: b,
+        after: h,
+        words: `\u2717 This change lowers the rule ${id} from ${b.strength} to ${h.strength}${n && b.strength === "block" ? `: ${imports(n, b)} that break it would no longer fail CI` : ""}. Loosening a rule needs a person's approval in the app.`
+      } : {
+        rule: id,
+        change: "changed",
+        effect: "tightens",
+        allowed: [],
+        forbidden: h.strength === "block" ? now : [],
+        before: b,
+        after: h,
+        words: `\u26A0 This change raises the rule ${id} from ${b.strength} to ${h.strength}${now.length && h.strength === "block" ? `: ${imports(now.length, h)} already in the code would fail CI` : ""}.`
+      });
+      continue;
+    }
+    const allowed = minus(was, now);
+    const forbidden = minus(now, was);
+    const effect = text === "loosens" || strength === "loosens" || allowed.length > 0 ? "loosens" : "tightens";
+    const at = (r) => b.strength === h.strength ? "" : ` at ${r.strength}`;
+    const what = `${stated(b)}${at(b)} to ${stated(h)}${at(h)}`;
+    out.push({
+      rule: id,
+      change: "changed",
+      effect,
+      allowed,
+      forbidden,
+      before: b,
+      after: h,
+      words: effect === "loosens" ? `\u2717 This change loosens the rule ${id}, from ${what}${allowed.length ? `: ${imports(allowed.length, b)} it forbade become allowed` : ""}. Loosening a rule needs a person's approval in the app.` : `\u26A0 This change tightens the rule ${id}, from ${what}${forbidden.length ? `: ${imports(forbidden.length, h)} already in the code would break it` : ""}.`
+    });
+  }
+  for (const [id, h] of after) {
+    if (before.has(id)) continue;
+    const forbidden = breaches(h, edges);
+    out.push({
+      rule: id,
+      change: "added",
+      effect: "tightens",
+      allowed: [],
+      forbidden,
+      before: null,
+      after: h,
+      words: `\u26A0 This change adds the rule \u201C${(0, import_architecture_rule.ruleStatement)({ ...h, except: [] })}\u201D (${id}) at ${h.strength}${forbidden.length ? `: ${imports(forbidden.length, h)} already in the code would break it` : ""}. It is checked once it is on the base branch.`
+    });
+  }
+  return out;
+}
+const NEEDS = " Loosening a rule needs a person's approval in the app.";
+function changeWords(c) {
+  if (c.effect !== "loosens" || !c.approval) return c.words;
+  if (c.approval.ok) return `\u2713 ${c.words.replace(/^✗ /, "").replace(NEEDS, "")} ${c.approval.by} approved it in the app, signed (${c.approval.file}).`;
+  return `${c.words} An approval is attached, but ${c.approval.why}.`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NEEDS,
+  changeWords,
+  diffRules
+});

package/src/backend/services/rule-preview.js

@@ -0,0 +1,47 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var rule_preview_exports = {};
+__export(rule_preview_exports, {
+  NO_CHANGE: () => NO_CHANGE,
+  previewChange: () => previewChange,
+  previewJson: () => previewJson
+});
+module.exports = __toCommonJS(rule_preview_exports);
+var import_architecture_rules = require("./architecture-rules");
+var import_rule_changes = require("./rule-changes");
+const NO_CHANGE = "This changes nothing about how code is judged.";
+function previewChange(projectRoot, id, next, edges) {
+  const current = (0, import_architecture_rules.findRule)(projectRoot, id);
+  const change = (0, import_rule_changes.diffRules)(current ? [current] : [], next ? [next] : [], edges ?? [])[0] ?? null;
+  const breaches = edges && next && next.strength !== "guide" ? (0, import_architecture_rules.checkEdges)([next], edges).length : null;
+  return { change, breaches, words: change ? change.words : NO_CHANGE, needsConfirm: change?.effect === "loosens" };
+}
+function previewJson(p) {
+  return {
+    change: p.change ? { rule: p.change.rule, change: p.change.change, effect: p.change.effect, allowed: p.change.allowed, forbidden: p.change.forbidden, words: p.change.words } : null,
+    words: p.words,
+    breaches: p.breaches,
+    needsConfirm: p.needsConfirm
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NO_CHANGE,
+  previewChange,
+  previewJson
+});