@arjunkhera/atlas 0.4.43 → 0.4.44

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.43",
+  "version": "0.4.44",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/lib/gate-check.mjs

@@ -24,7 +24,8 @@
 // the owner's signed act for this repo, this pull request and this head
 // (roadmap R72, signed-act.mjs). The key comes from atlas/owner-signers on the
 // base, never from the head. An act for an older head carries to this head
-// when the new commits only merge the base in with no conflict (item 34b554e7).
+// when the new commits only merge the base in with no conflict (item 34b554e7),
+// or only rebuild the pages that atlas.yaml names under `generated` (item 4ee7cab3).
 //
 // Red wins over owner: the pull request must be fixed before the owner signs.
 // Rules that hold everywhere here:
@@ -36,7 +37,7 @@
 import { spawnSync } from 'node:child_process';
 import { readFileSync, appendFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { classify, changedPaths, compile, matcher, fakeSecret, repoFacts } from './owner-only.mjs';
+import { classify, changedPaths, compile, matcher, fakeSecret, repoFacts, rulesAt, onList } from './owner-only.mjs';
 import { MISSING, HIT, fileHits, hidePath, shippedPaths, ships, termsFromEnv } from './private-terms.mjs';
 import { listChanged } from './changed-tests.mjs';
 import { parseYaml, SECRET_PATTERNS } from '../../shape/check.mjs';
@@ -58,8 +59,8 @@ const CASE_GROUPS = new Set(['unit-test', 'check-block', 'scenario-words']);
 
 export class GateCheckError extends Error {}
 
-function git(root, args, { allowFail = false } = {}) {
-  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+function git(root, args, { allowFail = false, env = process.env } = {}) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, env });
   if (r.error) throw new GateCheckError(`git cannot run: ${r.error.message}`);
   if (r.status !== 0) {
     if (allowFail) return null;
@@ -312,7 +313,7 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
   answer.rows.push(...secretRows(top, mergeBase, headSha, changes));
   if (terms !== undefined) answer.rows.push(...termRows(top, baseSha, headSha, changes, terms));
   answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain, rules: ruleRef, undo }));
-  if (signed) signedRows(top, baseSha, headSha, signed, answer);
+  if (signed) signedRows(top, baseSha, headSha, signed, answer, ruleRef);
   return finish(answer);
 }
 
@@ -323,7 +324,7 @@ export function judge({ root, base, head, body = '', redMain = [], rules = null,
 // the base after the touch does not carry it (security review S1). A head job
 // named like a check is never cleared: the owner's view of the gate could be
 // that job's forgery (security review S1).
-function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer) {
+function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer, ruleRef = baseSha) {
   if (!answer.rows.some((row) => row.kind === 'owner') || answer.rows.some((row) => row.kind === 'red')) return;
   const note = (cause) => answer.rows.push({ kind: 'note', class: 'signed', cause });
   if (texts === null) { note('the comments of the pull request could not be read, so no signed act counts'); return; }
@@ -336,7 +337,7 @@ function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer
   let found = findAct(verified, { kind: 'merge', repo, pr: Number(pr), base: baseRef, merge_base: answer.merge_base, head: headSha });
   let carried = null;
   if (!found) {
-    carried = carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef }, answer);
+    carried = carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef, ruleRef }, answer);
     if (carried?.found) found = carried.found;
   }
   if (!found) {
@@ -348,8 +349,9 @@ function signedRows(root, baseSha, headSha, { repo, pr, baseRef, texts }, answer
   const locked = answer.rows.filter((row) => row.kind === 'owner' && row.class === 'gate-checks');
   if (locked.length) { note('a signed act never clears a head job named like a check: remove that job'); return; }
   for (const row of answer.rows) if (row.kind === 'owner') row.kind = 'signed';
-  answer.signed = { key: found.key, signed_at: found.signed_at, verified: found.verified, ...(carried?.found ? { carried_from: found.act.head } : {}) };
-  if (carried?.found) note(`the owner signed head ${found.act.head.slice(0, 7)} with key ${found.key} at ${found.signed_at}; this head only adds ${carried.merges} clean merge(s) of the base`);
+  answer.signed = { key: found.key, signed_at: found.signed_at, verified: found.verified, ...(carried?.found ? { carried_from: found.act.head } : {}), ...(carried?.pages?.length ? { pages: carried.pages, pages_checks: carried.checks } : {}) };
+  if (carried?.found && carried.pages?.length) note(`the owner signed head ${found.act.head.slice(0, 7)} with key ${found.key} at ${found.signed_at}; this head only adds ${carried.merges} merge(s) of the base and rebuilds ${carried.pages.length} generated page(s), which the required check(s) ${carried.checks.join(', ')} prove`);
+  else if (carried?.found) note(`the owner signed head ${found.act.head.slice(0, 7)} with key ${found.key} at ${found.signed_at}; this head only adds ${carried.merges} clean merge(s) of the base`);
   else note(`the owner signed this head with key ${found.key} at ${found.signed_at}`);
 }
 
@@ -377,7 +379,7 @@ const contains = (root, older, newer) => spawnSync('git', [MERGE_BASE, '--is-anc
 // 5. Only the newest touch on this pull request carries, so a rollback to a
 //    head that the owner moved past does not clear.
 // It fails closed: a commit or a merge that git cannot read stops the carry.
-function carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef }, answer) {
+function carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef, ruleRef = baseSha }, answer) {
   const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
   // Every valid merge act of this pull request, on any base branch and head.
   const mine = [];
@@ -398,10 +400,13 @@ function carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef }, answe
   }).slice(0, CARRY_TRIES);
   if (!candidates.length) return { why: 'the newest signed act of this pull request names another base branch or head' };
   if (answer.rows.some((row) => row.kind === 'owner' && row.class === 'brake')) return { why: 'the brake is on, so the owner signs this head' };
+  const pages = generatedAt(root, baseSha);
+  for (const cause of pages.notes) answer.rows.push({ kind: 'note', class: 'signed', cause });
+  const built = pages.entries.length ? { entries: pages.entries, rules: rulesAt({ root, ref: ruleRef }).rules } : null;
   let why = null;
   for (const one of candidates) {
-    const result = carryOne(root, baseSha, headSha, answer.merge_base, one.act);
-    if (result.merges) return { found: one, merges: result.merges };
+    const result = carryOne(root, baseSha, headSha, answer.merge_base, one.act, built);
+    if (result.ok) return { found: one, merges: result.merges, pages: result.pages, checks: result.checks };
     why ??= result.why;
   }
   return { why: `${why} (${candidates.length} signed head(s) tried)` };
@@ -411,7 +416,7 @@ function carryAct(root, baseSha, headSha, verified, { repo, pr, baseRef }, answe
 // gate makes depends on the commits alone.
 const PINNED = { ...process.env, GIT_NO_REPLACE_OBJECTS: '1', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' };
 
-function carryOne(root, baseSha, headSha, mergeBase, act) {
+function carryOne(root, baseSha, headSha, mergeBase, act, built = null) {
   const old = commitOf(root, act.head);
   if (old !== act.head) return { why: `the signed head ${act.head.slice(0, 7)} is not a commit in this clone` };
   if (commitOf(root, act.merge_base) !== act.merge_base) return { why: `the signed merge base ${act.merge_base.slice(0, 7)} is not a commit in this clone` };
@@ -424,15 +429,97 @@ function carryOne(root, baseSha, headSha, mergeBase, act) {
   // commits after the signed merge base. A merge may bring in only one of
   // them, never a middle commit of a merged pull request (finding 3).
   const tips = new Set((git(root, ['rev-list', '--first-parent', baseSha, `^${act.merge_base}`], { allowFail: true }) ?? '').split('\n').filter(Boolean));
+  const pages = new Set();
+  const checks = new Set();
+  let merges = 0;
   for (const sha of shas) {
-    const [tree, ...parents] = (git(root, ['show', '-s', '--format=%T %P', sha], { allowFail: true }) ?? '').trim().split(' ');
+    const [tree, ...parents] = (git(root, ['show', '-s', '--format=%T %P', sha], { allowFail: true, env: PINNED }) ?? '').trim().split(' ');
+    // Item 4ee7cab3: a commit on the branch that only rebuilds generated pages.
+    // No check names its parent. H0 comes into this head only down the first
+    // parents, because each second parent is a tip of the base, so the parent
+    // is H0 or a new commit (security review, finding 5).
+    if (parents.length === 1 && built) {
+      const off = offPages(root, `${parents[0]}^{tree}`, tree, built, pages, checks);
+      if (off) return { why: `commit ${sha.slice(0, 7)} is not a merge of two parents, and ${off}` };
+      continue;
+    }
     if (parents.length !== 2) return { why: `commit ${sha.slice(0, 7)} is not a merge of two parents` };
     if (!tips.has(parents[1])) return { why: `merge ${sha.slice(0, 7)} brings in ${parents[1].slice(0, 7)}, which was never a tip of the base after the touch` };
-    const made = spawnSync('git', ['-c', 'merge.renames=true', '-c', 'merge.conflictStyle=merge', 'merge-tree', '--write-tree', '--no-messages', '--end-of-options', parents[0], parents[1]], { cwd: root, encoding: 'utf8', env: PINNED, timeout: 30_000 });
-    if (made.status !== 0) return { why: `merge ${sha.slice(0, 7)} has a conflict, so its fix needs a new touch` };
-    if (made.stdout.split('\n')[0].trim() !== tree) return { why: `merge ${sha.slice(0, 7)} changes more than a clean merge of its parents` };
+    merges += 1;
+    const made = spawnSync('git', ['-c', 'merge.renames=true', '-c', 'merge.conflictStyle=merge', 'merge-tree', '--write-tree', '-z', '--name-only', '--no-messages', '--end-of-options', parents[0], parents[1]], { cwd: root, encoding: 'utf8', env: PINNED, timeout: 30_000 });
+    // 0 is a clean merge, 1 a merge with a conflict; anything else fails closed.
+    if (made.status !== 0 && made.status !== 1) return { why: `git cannot merge the parents of ${sha.slice(0, 7)}` };
+    const [madeTree, ...conflicted] = made.stdout.split('\0').filter(Boolean);
+    if (made.status === 0 && madeTree === tree) continue;
+    if (!built) return { why: made.status === 1 ? `merge ${sha.slice(0, 7)} has a conflict, so its fix needs a new touch` : `merge ${sha.slice(0, 7)} changes more than a clean merge of its parents` };
+    // A conflict counts only in a generated page, and the merge may differ
+    // from the tree that git makes only in generated pages.
+    const outside = conflicted.find((path) => !pageOf(built, path));
+    if (outside) return { why: `merge ${sha.slice(0, 7)} has a conflict in ${outside}, which no generated entry names, so its fix needs a new touch` };
+    const off = offPages(root, madeTree, tree, built, pages, checks);
+    if (off) return { why: `merge ${sha.slice(0, 7)} changes more than a clean merge of its parents: ${off}` };
+  }
+  return { ok: true, merges, pages: [...pages].sort(), checks: [...checks].sort() };
+}
+
+// ------------------------------------------------------------------ generated pages
+
+// Tracker item 4ee7cab3. A repo can name pages that a script builds from its
+// code, and the required check that proves each page equals the build:
+//
+//   generated:
+//     - path: docs/manual/reference/
+//       check: tests · unit
+//       why: node docs/manual/extract/run.mjs --check
+//
+// The list comes from the base, never from the head. An entry counts only
+// when its check is a required check of the base and its path is a plain
+// path that is not the repo root, .github/ or atlas.yaml. The gate never
+// builds a page: nothing of the head runs. It only proves that a new commit
+// changes a generated page and nothing else, and it names the check that
+// proves the page. A merge needs every required check green, so a page that
+// differs from the build stops the merge in that check.
+const PAGE_PATH = /^(?!\.github(?:\/|$))(?!atlas\.yaml$)(?!atlas\/)[A-Za-z0-9_][A-Za-z0-9_.-]*(?:\/[A-Za-z0-9_][A-Za-z0-9_.-]*)*\/?$/;
+export function generatedAt(root, ref) {
+  let facts;
+  try { facts = parseYaml(textAt(root, ref, 'atlas.yaml') ?? '') ?? {}; } catch { return { entries: [], notes: ['atlas.yaml on the base cannot be read, so no generated page counts'] }; }
+  if (facts.generated === undefined || facts.generated === null) return { entries: [], notes: [] };
+  if (!Array.isArray(facts.generated)) return { entries: [], notes: ['atlas.yaml generated is not a list, so no generated page counts'] };
+  const required = new Set(Array.isArray(facts.required_checks) ? facts.required_checks.map(String) : []);
+  const entries = [];
+  const notes = [];
+  facts.generated.forEach((entry, index) => {
+    const path = entry && typeof entry === 'object' ? entry.path : null;
+    const check = entry && typeof entry === 'object' ? entry.check : null;
+    if (typeof path !== 'string' || !PAGE_PATH.test(path) || path.split('/').some((part) => part === '..' || part === '.')) notes.push(`atlas.yaml generated entry ${index + 1} does not count: its path is not a plain path`);
+    else if (typeof check !== 'string' || !required.has(check)) notes.push(`atlas.yaml generated entry ${index + 1} does not count: its check is not a required check of the base`);
+    else entries.push({ path, check });
+  });
+  return { entries, notes };
+}
+
+const pageOf = (built, path) => built.entries.find((entry) => (entry.path.endsWith('/') ? path.startsWith(entry.path) : path === entry.path)) ?? null;
+
+// Null when tree b differs from tree a only in generated pages that both trees
+// hold as plain files, which the owner-only list does not name. A page that
+// is added, removed or made a link counts as a change the owner did not see.
+// Otherwise the first reason.
+function offPages(root, a, b, built, pages, checks) {
+  const out = git(root, ['diff-tree', '-r', '-z', '--no-renames', '--no-textconv', '--no-ext-diff', a, b], { allowFail: true, env: PINNED });
+  if (out === null) return 'git cannot compare its trees';
+  const parts = out.split('\0');
+  const found = [];
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    const [oldMode, newMode, , , status] = parts[i].replace(/^:/, '').split(' ');
+    const path = parts[i + 1];
+    const entry = pageOf(built, path);
+    if (!entry) return `it changes ${path}, which no generated entry names`;
+    if (status !== 'M' || oldMode !== '100644' || newMode !== '100644') return `it adds, removes or retypes the generated page ${path}`;
+    if (onList(built.rules, path)) return `the generated page ${path} is on the owner-only list`;
+    found.push({ path, check: entry.check });
   }
-  return { merges: shas.length };
+  for (const one of found) { pages.add(one.path); checks.add(one.check); }
+  return null;
 }
 
 // Line 1: while the brake is on, every pull request of the repo comes to the

package/door/lib/gate.mjs

@@ -426,7 +426,10 @@ export function gateCopyRefusals(gh, repo, pull) {
 export function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks, homesRef = baseRef, audit = false }) {
   const homes = homesAt(gh, repo, homesRef, checks);
   const sides = sidesOf(gh, repo, head, baseRef);
-  const baseChanged = audit ? () => '' : baseChangedOf(gh, repo, pr);
+  // The audit keeps the base-change pin: a merged pull request still lists
+  // its events, and a run made while it pointed at a side branch used that
+  // branch's file (security review of item 4ee7cab3, finding 1).
+  const baseChanged = baseChangedOf(gh, repo, pr);
   const runOf = suiteRuns(gh, repo);
   const kept = [];
   const refused = [];

package/owner-only.yaml

@@ -235,4 +235,5 @@ atlas_yaml:
     - kinds
     - up_to_date
     - brake
+    - generated
     - spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.43",
+  "version": "0.4.44",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",