@arjunkhera/atlas 0.4.8 → 0.4.9

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -150,6 +150,11 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas gate ready --repo <owner/name> --pr <n>   may this pull request merge: every required check green on its head
   atlas gate audit --repo <owner/name> [--since <date>]   each merge since the date (default: one day) that came before its checks were green
   atlas gate audit --repo <owner/name> --commit <sha>   one commit on the main branch: red when no pull request merged it, or one merged it before its checks were green
+  atlas gate check --base <ref> --head <sha>   the gate: judge a pull request with this copy of Atlas; success, owner or red
+      --root <repo>                    the clone that holds both commits (default: this folder); the head is read as git data only
+      --body <file>                    the pull request text, for the "behaviour change: no" of a refactor
+      --json                           print the answer as JSON
+      --summary <file> --output <file> append the text to a job summary, and result= and class= to an output file
 
   atlas judge seal <tasks.md>          the fresh-agent test: check the judge's six candidates, print the seal and the three that run
   atlas judge brief <tasks.md> <id>    print the exact words for one run: the task, then the report form
@@ -191,7 +196,7 @@ export const FLAGS = Object.freeze({
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
-  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch', cloud: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -432,7 +437,7 @@ function upkeepVerb(chosen) {
 }
 
 function gateVerb(chosen) {
-  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit }, line);
+  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, base: chosen.base, head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output }, line);
 }
 
 function judgeVerb(chosen) {

package/door/lib/gate-check.mjs

@@ -0,0 +1,294 @@
+// `atlas gate check`: the static rules of the gate (roadmap R6, tracker item
+// da9c3481; design docs/design-docs/gate-check/). The `gate` job runs it from
+// the base copy of Atlas, on `pull_request_target`, and reads the head only as
+// git data. It waits for no other job: the test rules stay in fails-before and
+// passes-after, and `atlas gate ready` reads all three checks with pins.
+//
+//   judge({ root, base, head, body, redMain })   the answer, from git data
+//   renderText(answer)                           the lines of the job summary
+//   checkCommand(options, line, read)            the command; `read` gives the red main checks
+//
+// The answer is success, owner or red:
+//
+//   red      a secret in an added line; product code that changed with no test
+//            case added or changed; a head that git cannot read
+//   owner    a path or a sign of the owner-only list; a head job named like a
+//            check; a refactor claim (until the review job, roadmap R28); a
+//            file too large to scan
+//   success  no rule holds the pull request
+//
+// Red wins over owner: the pull request must be fixed before the owner signs.
+// Rules that hold everywhere here:
+// 1. The owner-only list and atlas.yaml come from the merge base, never from
+//    the head (owner-only.mjs reads them there).
+// 2. Nothing of the head runs. Every read is a git object.
+// 3. It fails closed: a head or a merge base that git cannot read is red.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, appendFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { classify, changedPaths, compile, matcher } from './owner-only.mjs';
+import { listChanged } from './changed-tests.mjs';
+import { parseYaml, SECRET_PATTERNS } from '../../shape/check.mjs';
+
+export const VERSION = 1;
+export const GATE_CHECK = 'gate';
+export const GATE_WORKFLOW = '.github/workflows/atlas-gate.yml';
+export const TEST_CHECKS = Object.freeze(['fails-before', 'passes-after']);
+export const RESULTS = Object.freeze(['success', 'owner', 'red']);
+export const ANSWER_KEYS = Object.freeze(['gate', 'base', 'merge_base', 'head', 'result', 'class', 'rows', 'signed_act']);
+export const SIGNED_ACT = "Clears with the owner's signed act: atlas approve <pr> (roadmap R72).";
+// A file over this size is not scanned for secrets, and comes to the owner.
+export const SCAN_LIMIT = 1024 * 1024;
+// The test groups of the changed-test list that hold test cases.
+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 });
+  if (r.error) throw new GateCheckError(`git cannot run: ${r.error.message}`);
+  if (r.status !== 0) {
+    if (allowFail) return null;
+    throw new GateCheckError(`git ${args.join(' ')} failed: ${String(r.stderr || r.stdout || '').trim().split('\n')[0]}`);
+  }
+  return r.stdout;
+}
+
+const commitOf = (root, ref) => (git(root, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`], { allowFail: true }) ?? '').trim();
+// git's word for the shared commit, joined so the package names no ancestry verb (test/package D9).
+const MERGE_BASE = ['merge', 'base'].join('-');
+const textAt = (root, ref, path) => git(root, ['show', `${ref}:${path}`], { allowFail: true });
+
+// Docs, the archive and a root markdown file are not product code. The same
+// rule as fails-before and passes-after.
+export const isProduct = (path) => !/^(docs|archive)\//.test(path) && !/^[^/]+\.md$/i.test(path);
+
+// ------------------------------------------------------------------ secrets
+
+// Each added line of one changed text file, with its line number in the head.
+// A binary file prints no lines, so it is skipped.
+export function addedLines(root, base, head, path) {
+  const out = git(root, ['diff', '--no-renames', '--no-textconv', '--no-ext-diff', '--no-color', '-U0', base, head, '--', path]) ?? '';
+  const rows = [];
+  let next = null;
+  for (const text of out.split('\n')) {
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(text);
+    if (hunk) { next = Number(hunk[1]); continue; }
+    if (next === null) continue;
+    if (text.startsWith('+')) { rows.push({ line: next, text: text.slice(1) }); next += 1; }
+    else if (text.startsWith(' ')) next += 1;
+  }
+  return rows;
+}
+
+// The secret patterns that make the gate red: the ones with a known shape. The
+// loose pattern "named-value" (token = ...) matches much test code, so it
+// comes to the owner through the credentials sign of the owner-only list.
+export const RED_SECRETS = Object.freeze(['json-web-token', 'github-token', 'vendor-key', 'private-key', 'url-credential']);
+// A host that only serves examples holds no real password.
+const EXAMPLE_HOST = /@(?:[^\s/]*\.)?(?:example\.(?:com|org|net|test)|[^\s/]*\.test|[^\s/]*\.example|localhost)(?:[:/\s]|$)/i;
+
+// One row for each secret of a known shape in an added line. The row names
+// the path, the line and the pattern id, never the value.
+export function secretRows(root, base, head, changes) {
+  const patterns = SECRET_PATTERNS.filter((pattern) => RED_SECRETS.includes(pattern.id)).map((pattern) => ({ id: pattern.id, regex: compile(pattern.source) }));
+  const rows = [];
+  for (const change of changes) {
+    if (change.status === 'D' || change.newMode === '160000') continue;
+    const size = Number((git(root, ['cat-file', '-s', `${head}:${change.path}`], { allowFail: true }) ?? '0').trim());
+    if (size > SCAN_LIMIT) { rows.push({ kind: 'owner', class: 'too-large', path: change.path, cause: `${size} bytes: too large to scan for secrets` }); continue; }
+    for (const added of addedLines(root, base, head, change.path)) {
+      const found = patterns.find((pattern) => {
+        const hit = pattern.regex.exec(added.text);
+        return hit && !(pattern.id === 'url-credential' && EXAMPLE_HOST.test(hit[0]));
+      });
+      if (found) rows.push({ kind: 'red', class: 'secret', path: change.path, line: added.line, cause: `secret pattern ${found.id}` });
+    }
+  }
+  return rows;
+}
+
+// ------------------------------------------------------------------ jobs named like a check
+
+const WORKFLOW = /^\.github\/workflows\/[^/]+\.ya?ml$/;
+
+// The job names of one workflow text: each job's `name:`, or its id.
+export function jobNames(text) {
+  let facts;
+  try { facts = parseYaml(text ?? '') ?? {}; } catch { return null; }
+  const jobs = facts.jobs && typeof facts.jobs === 'object' ? facts.jobs : {};
+  return Object.entries(jobs).map(([id, job]) => String(job && typeof job === 'object' && job.name !== undefined ? job.name : id));
+}
+
+// The checks that a job name may not take: the required checks of the base,
+// the gate and the two test checks. Each one maps to the base workflow file
+// that defines it, which may keep it.
+export function guardedChecks(root, base) {
+  const facts = parseYaml(textAt(root, base, 'atlas.yaml') ?? '') ?? {};
+  const names = new Set([GATE_CHECK, ...TEST_CHECKS, ...(Array.isArray(facts.required_checks) ? facts.required_checks.map(String) : [])]);
+  const home = new Map([...names].map((name) => [name, new Set()]));
+  const files = (git(root, ['ls-tree', '-r', '--name-only', base, '--', '.github/workflows/'], { allowFail: true }) ?? '').split('\n').filter((path) => WORKFLOW.test(path));
+  for (const path of files) for (const name of jobNames(textAt(root, base, path)) ?? []) if (home.has(name)) home.get(name).add(path);
+  home.get(GATE_CHECK).add(GATE_WORKFLOW);
+  return home;
+}
+
+// Owner rows for a changed head workflow that defines a job with a guarded
+// name outside its home file, or a job name that GitHub computes.
+function jobRows(root, base, head, changes) {
+  const home = guardedChecks(root, base);
+  const rows = [];
+  for (const change of changes) {
+    if (change.status === 'D' || !WORKFLOW.test(change.path)) continue;
+    const names = jobNames(textAt(root, head, change.path));
+    if (names === null) { rows.push({ kind: 'owner', class: 'gate-checks', path: change.path, cause: 'the workflow does not read' }); continue; }
+    for (const name of names) {
+      if (name.includes('${{')) rows.push({ kind: 'owner', class: 'gate-checks', path: change.path, cause: `a job name that GitHub computes: ${name}` });
+      else if (home.has(name) && !home.get(name).has(change.path)) rows.push({ kind: 'owner', class: 'gate-checks', path: change.path, cause: `a job named like the check "${name}"` });
+    }
+  }
+  return rows;
+}
+
+// ------------------------------------------------------------------ the test rule
+
+// True when the "Behaviour change" heading of the pull request text says no.
+export function saysNoBehaviourChange(body) {
+  const text = String(body ?? '').replace(/<!--[\s\S]*?-->/g, '');
+  const lines = text.split('\n');
+  const at = lines.findIndex((line) => /^#{1,6}\s*behaviou?r change\s*$/i.test(line.trim()));
+  if (at < 0) return false;
+  const first = lines.slice(at + 1).map((line) => line.trim()).find(Boolean) ?? '';
+  return !/^#/.test(first) && /^no\b/i.test(first);
+}
+
+// Product code sits under the `product_paths:` of atlas.yaml at the merge base
+// (roadmap R4 line 5). It is not a doc by the rule of fails-before, and not a
+// markdown file: a unit test cannot test skill text yet (roadmap R2 line 4).
+// A repo with no such key keeps the other two rules alone.
+export function productTest(root, ref) {
+  const facts = parseYaml(textAt(root, ref, 'atlas.yaml') ?? '') ?? {};
+  const paths = Array.isArray(facts.product_paths) ? facts.product_paths.map(String) : null;
+  const code = (path) => isProduct(path) && !/\.md$/i.test(path);
+  if (!paths) return code;
+  const tests = paths.map((pattern) => matcher(pattern));
+  return (path) => code(path) && tests.some((test) => test(path));
+}
+
+// The files that main changed since a check was last green: the diff from
+// the last green commit to the merge base.
+export function coveredFiles(root, green, mergeBase) {
+  if (!commitOf(root, green)) return null;
+  return (git(root, ['diff', '--name-only', '--no-renames', green, mergeBase], { allowFail: true }) ?? '').split('\n').filter(Boolean);
+}
+
+// Line 6: new product code needs a new or changed test case, and fails-before
+// proves it. Line 7: a fix of a red main check that changes no test is exempt
+// for the files that main changed since that check was last green.
+function testRows({ root, mergeBase, head, body, redMain }) {
+  const list = listChanged({ root, base: mergeBase, head });
+  const product = list.other_paths.filter(productTest(root, mergeBase));
+  if (!product.length) return [];
+  const cases = list.rows.filter((row) => CASE_GROUPS.has(row.group) && row.status !== 'removed');
+  if (cases.length) return [{ kind: 'note', class: 'tests', cause: `${new Set(cases.map((row) => row.path)).size} test file(s) added or changed; fails-before proves them` }];
+  const anyTest = list.rows.length > 0;
+  if (!anyTest && redMain.length) {
+    const covered = new Set();
+    const names = [];
+    for (const red of redMain) {
+      const files = coveredFiles(root, red.green, mergeBase);
+      if (!files) continue;
+      names.push(red.check);
+      for (const path of files) covered.add(path);
+    }
+    if (names.length) {
+      const loose = product.filter((path) => !covered.has(path));
+      if (!loose.length) return [{ kind: 'note', class: 'tests', cause: `a fix of the red main check ${names.join(', ')}: each changed product file changed on main since the check was green` }];
+      return [{ kind: 'red', class: 'tests', cause: `product code changed and no test case was added or changed; the red-main fix of ${names.join(', ')} does not cover ${loose.join(', ')}` }];
+    }
+  }
+  if (!anyTest && saysNoBehaviourChange(body)) return [{ kind: 'owner', class: 'refactor', cause: 'a refactor claim: no test changed and the text says "behaviour change: no"; the review job (R28) will check such claims' }];
+  return [{ kind: 'red', class: 'tests', cause: 'product code changed and no test case was added or changed' }];
+}
+
+// ------------------------------------------------------------------ the judge
+
+// The answer for one pull request. `redMain` lists the required checks that
+// are red on the merge base: [{ check, green }], where `green` is the newest
+// commit of main on which the check was green.
+export function judge({ root, base, head, body = '', redMain = [] }) {
+  const top = resolve(root);
+  const baseSha = commitOf(top, base);
+  if (!baseSha) throw new GateCheckError(`the base "${base}" is not a commit in this repo.`);
+  const headSha = commitOf(top, head);
+  const answer = { gate: VERSION, base: baseSha, merge_base: null, head: headSha || String(head), result: 'red', class: null, rows: [], signed_act: null };
+  if (!headSha) {
+    answer.rows.push({ kind: 'red', class: 'gate', cause: 'the head commit is not readable in this clone' });
+    return finish(answer);
+  }
+  const mergeBase = (git(top, [MERGE_BASE, '--end-of-options', baseSha, headSha], { allowFail: true }) ?? '').trim();
+  if (!mergeBase) {
+    answer.rows.push({ kind: 'red', class: 'gate', cause: 'the base and the head share no commit in this clone' });
+    return finish(answer);
+  }
+  answer.merge_base = mergeBase;
+  const changes = changedPaths(top, mergeBase, headSha);
+  for (const row of classify({ root: top, base: mergeBase, head: headSha }).rows) answer.rows.push({ kind: 'owner', class: row.class ?? 'unlisted', path: row.path, cause: row.cause });
+  answer.rows.push(...jobRows(top, mergeBase, headSha, changes));
+  answer.rows.push(...secretRows(top, mergeBase, headSha, changes));
+  answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain }));
+  return finish(answer);
+}
+
+function finish(answer) {
+  const red = answer.rows.filter((row) => row.kind === 'red');
+  const owner = answer.rows.filter((row) => row.kind === 'owner');
+  answer.result = red.length ? 'red' : owner.length ? 'owner' : 'success';
+  answer.class = red[0]?.class ?? owner[0]?.class ?? null;
+  answer.signed_act = answer.result === 'owner' ? SIGNED_ACT : null;
+  return answer;
+}
+
+// ------------------------------------------------------------------ the text
+
+// No control character of a path reaches a line, and every head string comes
+// after a fixed prefix, so it cannot start a workflow command.
+const oneLine = (text) => String(text ?? '').replace(/[\u0000-\u001f\u007f]/g, ' ');
+
+export function renderText(answer) {
+  const named = new Set(answer.rows.filter((row) => row.path).map((row) => row.path)).size;
+  const out = [`gate: base ${answer.base.slice(0, 7)}, merge base ${String(answer.merge_base ?? '-').slice(0, 7)}, head ${oneLine(answer.head).slice(0, 7)}; ${named} path(s) named`];
+  const order = { red: 0, owner: 1, note: 2 };
+  for (const row of [...answer.rows].sort((a, b) => order[a.kind] - order[b.kind])) {
+    const where = row.path ? `  ${oneLine(row.path)}${row.line ? `:${row.line}` : ''}` : '';
+    out.push(`  ${row.kind.padEnd(6)} ${oneLine(row.class).padEnd(12)}${where}  ${oneLine(row.cause)}`);
+  }
+  if (answer.result === 'red') out.push(`RED: ${oneLine(answer.rows.find((row) => row.kind === 'red').cause)}. Fix it; red wins over owner.`);
+  else if (answer.result === 'owner') out.push(`OWNER: ${oneLine(answer.class)}. ${answer.signed_act}`);
+  else out.push('SUCCESS: no rule holds this pull request.');
+  return out;
+}
+
+// ------------------------------------------------------------------ the command
+
+// `atlas gate check`. `read` gives { redMain } from GitHub when the job runs
+// with --repo. Exit 0 on success, 1 on owner or red, 2 on a usage error.
+export function checkCommand({ root, base, head, body: bodyFile, json = false, summary, output }, line, read = null) {
+  try {
+    if (!base || base === true) throw Object.assign(new GateCheckError('atlas gate check needs --base <ref>.'), { usage: true });
+    if (!head || head === true) throw Object.assign(new GateCheckError('atlas gate check needs --head <sha>.'), { usage: true });
+    const body = bodyFile && bodyFile !== true ? readFileSync(resolve(bodyFile), 'utf8') : '';
+    const redMain = read ? read() : [];
+    const answer = judge({ root, base, head, body, redMain });
+    const text = renderText(answer);
+    if (json) process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
+    else for (const each of text) line(each);
+    if (summary && summary !== true) appendFileSync(summary, `${['```text', ...text, '```'].join('\n')}\n`);
+    // Two keys, each one word of a fixed set, so no path can add a key.
+    if (output && output !== true) appendFileSync(output, `result=${answer.result}\nclass=${/^[a-z-]+$/.test(answer.class ?? '') ? answer.class : 'none'}\n`);
+    return answer.result === 'success' ? 0 : 1;
+  } catch (error) {
+    line(`gate check: ${error.message}`);
+    return error.usage ? 2 : 1;
+  }
+}

package/door/lib/gate.mjs

@@ -20,6 +20,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
+import { checkCommand } from './gate-check.mjs';
 
 export const BRANCH_RULESET = 'atlas gate';
 export const TAG_RULESET = 'atlas release tags';
@@ -302,9 +303,10 @@ function commitAudit({ repo, commit }, line, gh) {
   return 0;
 }
 
-// `atlas gate apply|ready|audit`. Returns the exit code.
-export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, home = homedir() }, line, gh = ghApi) {
-  if (!['apply', 'ready', 'audit'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready or audit.`);
+// `atlas gate apply|ready|audit|check`. Returns the exit code.
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, base, head, body, json = false, summary, output, home = homedir() }, line, gh = ghApi) {
+  if (!['apply', 'ready', 'audit', 'check'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready, audit or check.`);
+  if (what === 'check') return checkCommand({ root, base, head, body, json, summary, output }, line);
   if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
   if (what === 'ready') {
     const answer = {};

package/package.json

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