@arjunkhera/atlas 0.4.43 → 0.4.45

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.43",
+  "version": "0.4.45",
   "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.45",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/shape/check.mjs

@@ -38,7 +38,7 @@ export const sha256 = (text) => createHash('sha256').update(String(text ?? ''),
 // Whether a copy is current or behind is not decided here. CI has no package
 // and no network. The session verb decides it, from the release list that
 // ships beside this file in the package, shape/releases.json.
-export const CHECK_VERSION = 8;
+export const CHECK_VERSION = 9;
 
 // ---------------------------------------------------------------------------
 // The spec. One object per version. The check reads a version it has here and
@@ -1550,6 +1550,33 @@ export function counts(files) {
 // check version 6 five cases switched the rule off and printed a warning that
 // a person merges the file. Nothing switches it off now. The base copy scores,
 // and the base kind and spec score both trees, so no case needs to.
+// A head whose atlas.yaml names a spec that this copy of the check cannot
+// read. A head with no spec, or with an atlas.yaml that does not read, is not
+// one: those stay errors.
+export function headSpecUnread(facts) {
+  const spec = facts?.spec;
+  return spec !== undefined && spec !== null && spec !== '' && !Object.hasOwn(SPECS, String(spec));
+}
+
+// The head of a move to a newer spec: no part is scored, but every file the
+// newer spec can read for facts is swept for secrets. That is atlas.yaml, each
+// file under atlas/, and each facts file that atlas.yaml points to by a plain
+// path. The trust checks of the pattern list and the owner_only checks run as
+// in scan, so a newer spec cannot turn either of them from red into owner.
+export function sweepHead({ root, repoId = null, secretPatterns: patterns = secretPatterns() }) {
+  const { facts } = readFacts(root);
+  const errors = [...ownerOnlyErrors(facts)];
+  const usable = Array.isArray(patterns) && patterns.every((pattern) => pattern instanceof RegExp) ? patterns : [];
+  if (!usable.length) errors.push('the secret pattern list is empty or is not a list of patterns, so a credential value could not be caught; this check cannot be trusted');
+  const missed = canaryMisses();
+  if (missed.length) errors.push(`${missed.length} secret pattern(s) no longer catch their own canary: ${missed.join(', ')}; this check cannot be trusted`);
+  const context = { root, secretPatterns: usable, errors };
+  const files = facts?.files && typeof facts.files === 'object' && !Array.isArray(facts.files) ? facts.files : {};
+  const pointed = Object.values(files).filter((path) => plainPath(path) && isFile(root, path));
+  for (const path of new Set(['atlas.yaml', ...walk(root, 'atlas'), ...pointed])) secretIn(context, path, readText(root, path));
+  return { ok: false, check_version: CHECK_VERSION, repo: repoId, kind: null, spec: facts?.spec ?? null, swept_only: true, files: [], by_reference: [], counts: counts([]), errors };
+}
+
 export const OWNER_CASES = Object.freeze(['check-file', 'workflow', 'kind', 'spec', 'moved', 'first-run']);
 
 const fileHash = (root, path) => { const text = readText(root, path); return text === null ? null : sha256(text); };
@@ -1633,8 +1660,9 @@ export function noLoss({ headRoot, baseRoot, baseSha = null, baseCommit = null,
   if (String(out.head_facts.kind) !== String(scoreAs.kind)) {
     owner('kind', `atlas.yaml names kind "${scoreAs.kind}" at the base and "${out.head_facts.kind}" at the head; this pull request changes which parts the repo needs`);
   }
+  const unread = Object.hasOwn(SPECS, String(scoreAs.spec)) && headSpecUnread(headRead.facts);
   if (String(out.head_facts.spec) !== String(scoreAs.spec)) {
-    owner('spec', `atlas.yaml names spec "${scoreAs.spec}" at the base and "${out.head_facts.spec}" at the head; this pull request changes what the spec version means`);
+    owner('spec', `atlas.yaml names spec "${scoreAs.spec}" at the base and "${out.head_facts.spec}" at the head; this pull request changes what the spec version means${unread ? `; this copy of the check, check version ${CHECK_VERSION}, cannot read spec "${out.head_facts.spec}", so it did not score the head and only swept it for secrets` : ''}`);
   }
 
   // 3. Does the diff change the gate itself? The base copy judges, so the
@@ -1645,6 +1673,12 @@ export function noLoss({ headRoot, baseRoot, baseSha = null, baseCommit = null,
     }
   }
 
+  // A head on a spec this copy cannot read is a move to a newer spec. This
+  // copy has no yardstick for the head, so it compares nothing. The spec row
+  // above sends it to the owner, and the gate still sweeps the head for
+  // secrets (roadmap R62: the base copy judged the move to spec 3 red).
+  if (unread) return out;
+
   // 4. Score both trees, by the same yardstick, and compare part by part. The
   // head is scored twice: at its own pointers, and at the base's.
   const base = scan({ root: baseRoot, repoId, secretPatterns: patterns, scoreAs });
@@ -1988,7 +2022,9 @@ export function gateFromGit({ git, baseCommit, headCommit, repoId = null, trees
     }
     mkdirSync(baseRoot, { recursive: true });
     mkdirSync(headRoot, { recursive: true });
-    const report = scan({ root: headRoot, repoId, secretPatterns: patterns });
+    const baseFacts = readFacts(baseRoot).facts;
+    const swept = baseFacts && Object.hasOwn(SPECS, String(baseFacts.spec)) && headSpecUnread(readFacts(headRoot).facts);
+    const report = swept ? sweepHead({ root: headRoot, repoId, secretPatterns: patterns }) : scan({ root: headRoot, repoId, secretPatterns: patterns });
     const state = noLoss({ headRoot, baseRoot, baseCommit: mergeBase, repoId, secretPatterns: patterns });
     // A link or a submodule that the head adds or changes is never read, so the
     // check cannot judge it. The owner reads it.

package/shape/releases.json

@@ -47,6 +47,11 @@
       "check_version": 8,
       "sha256": "8cf521f6e8f89ae65a257c521c583281e0c3c27ef968b4bd96eb336a8d095795",
       "workflow_sha256": "fcddebef030e6564f97e1a5fb81c8ad1b3084ebef9622167c6565698312dcdd7"
+    },
+    {
+      "check_version": 9,
+      "sha256": "87896abfc09afd22724cfa645bbb5ef029d83887caf70f38b88d00b21cddef02",
+      "workflow_sha256": "fcddebef030e6564f97e1a5fb81c8ad1b3084ebef9622167c6565698312dcdd7"
     }
   ]
 }