@arjunkhera/atlas 0.3.41 → 0.3.43

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -33,6 +33,7 @@ import { verdictCommand as testsVerdict, namedCommand as testsNamed, rerunComman
 import { runKept } from '../tests/kept.mjs';
 import { sweepCommand as testsSweep, coversCommand as testsCovers } from '../tests/sweep.mjs';
 import { issuesCommand as testsIssues } from './lib/issues.mjs';
+import { changedCommand as testsChanged } from './lib/changed-tests.mjs';
 import { upkeepCommand } from './lib/upkeep.mjs';
 import { judgeCommand } from './lib/judge.mjs';
 
@@ -81,6 +82,10 @@ const HELP = `atlas — the door into a repo's Atlas files
       --run <id>                       the run; default the newest run in the evidence folder
       --base <ref>                     the base of the pull request; flaky is a fail for an assertion it names. With no base every flaky is a fail
       --covers                         also name the assertions of a scenario whose covers path the change touches
+  atlas tests changed --root <repo> --base <ref>   list each test that a pull request adds, changes, renames or removes, as JSON
+      --head <ref>                     the head of the pull request; default HEAD. Only committed files count
+      --out <file>                     write the JSON here; default the terminal
+      --text                           print a short table instead of the JSON
   atlas tests named --root <area>      list the assertions that a pull request names
       --base <ref>                     the base: an assertion is named when its words changed or it is new
       --covers                         also name the assertions of a scenario whose covers path the change touches
@@ -103,7 +108,7 @@ const HELP = `atlas — the door into a repo's Atlas files
       --evidence <dir>                 where the evidence files go; default <area>/test/evidence
       --scenario <id>                  run one scenario only
 
-  atlas tests rerun --root <area> --run <id>   list the scenario test files whose first attempt did not end well
+  atlas tests rerun --root <area> --run <id> [--language python]   list the scenario test files whose first attempt did not end well
       --tests <dir>                    the test folder of the area; default test. The test files are in <dir>/scenarios
       --evidence <dir>                 where the evidence files are; default <area>/test/evidence
 
@@ -146,7 +151,7 @@ export const FLAGS = Object.freeze({
   ste: { share: 'switch', terms: 'value' },
   design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
   view: { product: 'value', name: 'value', out: 'value' },
-  tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value' },
+  tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
   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' },
@@ -343,13 +348,14 @@ async function testsCommand(chosen) {
   if (what === 'write') return testsWrite({ dryRun: Boolean(chosen['dry-run']) }, root, PACKAGE_ROOT, line);
   if (what === 'proof') return testsProof({ run: chosen.run, own: chosen.own, evidence: chosen.evidence, base: chosen.base, covers: Boolean(chosen.covers) }, root, line);
   if (what === 'verdict') return testsVerdict({ run: chosen.run, base: chosen.base, evidence: chosen.evidence, covers: Boolean(chosen.covers) }, root, line);
+  if (what === 'changed') return testsChanged({ base: chosen.base, head: chosen.head, out: chosen.out, text: Boolean(chosen.text) }, root, line);
   if (what === 'named') return testsNamed({ base: chosen.base, covers: Boolean(chosen.covers) }, root, line);
   if (what === 'sweep') return testsSweep({ evidence: chosen.evidence, since: chosen.since, base: chosen.base, out: chosen.out, text: Boolean(chosen.text) }, root, line);
   if (what === 'covers') return testsCovers({ itemId: chosen._[2], evidence: chosen.evidence, json: Boolean(chosen.json) }, root, line);
   if (what === 'kept') return (await runKept({ root, evidenceDir: chosen.evidence, only: chosen.scenario ?? null, write: (text) => process.stdout.write(text) })).exit;
-  if (what === 'rerun') return testsRerun({ run: chosen.run, evidence: chosen.evidence, tests: chosen.tests }, root, line);
+  if (what === 'rerun') return testsRerun({ run: chosen.run, evidence: chosen.evidence, tests: chosen.tests, language: chosen.language ?? 'javascript' }, root, line);
   if (what === 'issues') return testsIssues({ findings: chosen.findings, repo: chosen.repo, max: chosen.max, bot: chosen.bot, dryRun: Boolean(chosen['dry-run']), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
-  throw new Error(`there is no tests verb "${what ?? ''}". Use check, write, proof, verdict, named, sweep, covers, kept, issues or rerun.`);
+  throw new Error(`there is no tests verb "${what ?? ''}". Use check, write, proof, verdict, named, changed, sweep, covers, kept, issues or rerun.`);
 }
 
 function upkeepVerb(chosen) {

package/door/kit-releases.json

@@ -44,6 +44,10 @@
     {
       "kit_sha256": "ea6dc64f5ae4b5caca925a9613c829f5738d16b21d2664434dada208027b60b6",
       "first_package": "0.3.38"
+    },
+    {
+      "kit_sha256": "8d6ae3c4dede74bafe292a992de3ef650e5c5566fb282081a9de23b8d30d9025",
+      "first_package": "0.3.39"
     }
   ]
 }

package/door/lib/changed-tests.mjs

@@ -0,0 +1,420 @@
+// `atlas tests changed`: the list of test things that a pull request adds, changes, renames or
+// removes (roadmap R3, tracker item 62a3b4d0; design docs/design-docs/changed-test-list/).
+//
+// It compares the head with its merge base. It reads both sides as git objects only: it never
+// imports, runs or loads a file of the head, so a pull request cannot change how its own list is
+// made. The group rules live here, in the package. In CI the later checks run the base copy.
+//
+// The answer is JSON with fixed keys (version `changed_tests: 1`). Every row has the same seven keys:
+//   { area, group, status, path, from, id, content_changed }
+// `area`, `group`, `path` and `id` together name a row. The fails-before and passes-after checks write
+// the case names of their JUnit results in their own answers, against that name; this list stays fixed.
+//
+// The command lists; it never judges. It exits 0 when it can read the diff, and 2 on a usage error.
+import { spawnSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { resolve, posix } from 'node:path';
+import { parseScenario, addFingerprints, fingerprintOf } from '../../tests/scenario.mjs';
+import { parseYaml } from '../../tests/yaml.mjs';
+
+export const VERSION = 1;
+export const GROUPS = Object.freeze(['scenario-words', 'check-block', 'unit-test', 'runner-config', 'test-script', 'test-helper', 'kit-manifest']);
+export const STATUSES = Object.freeze(['added', 'changed', 'renamed', 'removed']);
+export const ROW_KEYS = Object.freeze(['area', 'group', 'status', 'path', 'from', 'id', 'content_changed']);
+export const ANSWER_KEYS = Object.freeze(['changed_tests', 'base', 'merge_base', 'head', 'counts', 'other_paths', 'rows']);
+
+// The git verb that finds the common ancestor. The word is built, as in tests/verdict.mjs: a package
+// test refuses the plain word in the door (it guards the old ancestry code).
+const MERGE_BASE = ['merge', 'base'].join('-');
+
+function git(cwd, args, { allowFail = false } = {}) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  if (r.error) throw new Error(`git cannot run: ${r.error.message}`);
+  if (r.status !== 0) {
+    if (allowFail) return null;
+    throw new Error(`git ${args.join(' ')} failed: ${(r.stderr || r.stdout || '').trim().split('\n')[0]}`);
+  }
+  return r.stdout;
+}
+
+const usage = (message) => Object.assign(new Error(message), { usage: true });
+const show = (cwd, sha, path) => git(cwd, ['show', `${sha}:${path}`], { allowFail: true });
+const keyOf = (id) => String(id).replace(/#[0-9a-f]+$/, '');
+
+// ---------------------------------------------------------------- the rules for each group
+
+const RUNNER_CONFIG = /^(vitest\.config\.[^/]+|vitest\.[^/]+\.config\.[^/]+|jest\.config\.[^/]+|playwright\.config\.[^/]+|\.mocharc(\.[^/]+)?|pytest\.ini|tox\.ini)$/;
+const UNIT_TEST = /^([^/]+\.(test|spec)\.[^/]+|test_[^/]+\.py|[^/]+_test\.py|[^/]+_test\.go)$/;
+// A helper folder at any depth. These names mean tests in every tool that uses them.
+const HELPER_ANY = new Set(['__tests__', '__snapshots__', 'testdata']);
+// A helper folder only at the top of the repo or of an area. Deeper, such a name can be product code
+// (the Atlas test kit ships in packages/atlas/tests/).
+const HELPER_TOP = new Set(['test', 'tests', 'spec', 'fixtures', 'golden']);
+// Test settings that live inside a package.json, beside the test scripts.
+const PACKAGE_TEST_KEYS = Object.freeze(['jest', 'vitest', 'mocha', 'ava', 'c8', 'nyc']);
+const SCENARIO_TEST = /(^|\/)tests?\/scenarios\/[^/]+(\.test\.mjs|_test\.py)$/;
+const TEST_SCRIPT = /^(pre|post)?test(:.*)?$/;
+const SKIP_SCENARIO = /(^|\/)(map|README)\.md$/;
+// A check id reads "<scenario>/e<n>", with or without its "#<fingerprint>".
+const CHECK_ID = /^[\w.-]+\/e\d+(#[0-9a-f]+)?$/;
+
+// An area is a folder that holds atlas/tests.yaml. A folder inside a test folder is a fixture, not an area.
+const FIXTURE_PART = new Set([...HELPER_ANY, ...HELPER_TOP]);
+const isKitManifest = (path) => /(^|\/)atlas\/tests\.yaml$/.test(path) || /(^|\/)tests?\/atlas\/manifest\.json$/.test(path);
+// A scenario file of an area: <area>/scenarios/**.md, where <area>/atlas/tests.yaml exists on one side.
+function scenarioArea(path, areas) {
+  if (!path.endsWith('.md') || SKIP_SCENARIO.test(path)) return null;
+  for (const area of areas) {
+    const prefix = area ? `${area}/scenarios/` : 'scenarios/';
+    if (path.startsWith(prefix)) return area;
+  }
+  return null;
+}
+
+// The area of a path: the longest area that holds it, or '' (the repo root).
+export function areaOf(path, areas = ['']) {
+  for (const area of [...areas].sort((a, b) => b.length - a.length)) if (!area || path.startsWith(`${area}/`)) return area;
+  return '';
+}
+
+function isHelper(path, areas) {
+  const name = posix.basename(path);
+  if (name === 'conftest.py' || name.endsWith('.snap')) return true;
+  const area = areaOf(path, areas);
+  const dirs = (area ? path.slice(area.length + 1) : path).split('/').slice(0, -1);
+  return dirs.some((d) => HELPER_ANY.has(d)) || HELPER_TOP.has(dirs[0]) || HELPER_TOP.has(path.split('/')[0]);
+}
+
+// The first rule that matches wins, in the order of the design (routes part).
+export function groupOf(path, areas = ['']) {
+  const name = posix.basename(path);
+  if (isKitManifest(path)) return 'kit-manifest';
+  if (scenarioArea(path, areas) !== null) return 'scenario-words';
+  if (SCENARIO_TEST.test(path)) return 'check-block';
+  if (RUNNER_CONFIG.test(name) || name === 'pyproject.toml' || name === 'setup.cfg' || name === 'noxfile.py') return 'runner-config';
+  if (name === 'package.json') return 'test-script';
+  // A snapshot is named after its test file (`a.test.ts.snap`), but it is data that a test reads.
+  if (name.endsWith('.snap')) return 'test-helper';
+  if (UNIT_TEST.test(name)) return 'unit-test';
+  if (isHelper(path, areas)) return 'test-helper';
+  return null;
+}
+
+// ---------------------------------------------------------------- readers of one side
+
+// The pytest section of a pyproject.toml or a setup.cfg, or '' when it has none.
+export function pytestSection(text, name) {
+  if (text === null) return '';
+  const head = name === 'setup.cfg' ? /^\[tool:pytest\]\s*$/ : /^\[tool\.pytest(\.[^\]]+)?\]\s*$/;
+  const out = [];
+  let inside = false;
+  for (const line of text.replace(/\r\n?/g, '\n').split('\n')) {
+    if (/^\s*\[/.test(line)) inside = head.test(line.trim());
+    if (inside) out.push(line);
+  }
+  return out.join('\n');
+}
+
+// The test scripts of a package.json: { name: command }. null when the file does not read as JSON.
+export function testScripts(text) {
+  if (text === null) return {};
+  let value;
+  try { value = JSON.parse(text); } catch { return null; }
+  if (!value || typeof value !== 'object') return {};
+  const scripts = value.scripts && typeof value.scripts === 'object' ? value.scripts : {};
+  const out = Object.fromEntries(Object.entries(scripts).filter(([name]) => TEST_SCRIPT.test(name)));
+  // A test setting key reads "key:<name>", so it never meets a script name.
+  for (const key of PACKAGE_TEST_KEYS) if (key in value) out[`key:${key}`] = JSON.stringify(value[key]);
+  return out;
+}
+
+// Skips a string, a template string, a comment or a regular expression that starts at `i`.
+// Returns the index after it, or `i` when nothing starts there. Throws when it does not end.
+function skipToken(src, i, prev) {
+  const c = src[i];
+  const n = src[i + 1];
+  if (c === '/' && n === '/') { const end = src.indexOf('\n', i); return end < 0 ? src.length : end; }
+  if (c === '/' && n === '*') { const end = src.indexOf('*/', i + 2); if (end < 0) throw new Error('open comment'); return end + 2; }
+  if (c === '"' || c === "'") {
+    for (let j = i + 1; j < src.length; j += 1) {
+      if (src[j] === '\\') { j += 1; continue; }
+      if (src[j] === c) return j + 1;
+      if (src[j] === '\n') break;
+    }
+    throw new Error('open string');
+  }
+  if (c === '`') {
+    for (let j = i + 1; j < src.length; j += 1) {
+      if (src[j] === '\\') { j += 1; continue; }
+      if (src[j] === '`') return j + 1;
+      if (src[j] === '$' && src[j + 1] === '{') { j = balanced(src, j + 1, '{', '}') - 1; }
+    }
+    throw new Error('open template');
+  }
+  // A slash starts a regular expression after an operator or an opening bracket, never after a value.
+  if (c === '/' && (prev === null || /[(,=:[!&|?{};+\-*%<>~^]/.test(prev))) {
+    let inClass = false;
+    for (let j = i + 1; j < src.length; j += 1) {
+      if (src[j] === '\\') { j += 1; continue; }
+      if (src[j] === '\n') break;
+      if (src[j] === '[') inClass = true;
+      else if (src[j] === ']') inClass = false;
+      else if (src[j] === '/' && !inClass) { let k = j + 1; while (/[a-z]/i.test(src[k] ?? '')) k += 1; return k; }
+    }
+    throw new Error('open regular expression');
+  }
+  return i;
+}
+
+// The index after the bracket that closes the one at `open`. Throws when it does not close.
+function balanced(src, open, opener, closer) {
+  let depth = 0;
+  let prev = null;
+  for (let i = open; i < src.length;) {
+    const after = skipToken(src, i, prev);
+    if (after !== i) { i = after; prev = 'a'; continue; }
+    const c = src[i];
+    if (c === opener) depth += 1;
+    else if (c === closer) { depth -= 1; if (depth === 0) return i + 1; }
+    if (!/\s/.test(c)) prev = c;
+    i += 1;
+  }
+  throw new Error('open bracket');
+}
+
+// The check blocks of a scenario test file: Map of check key ("scenario/e1") to its text.
+// JavaScript: each `<name>.check("<id>", …)` call. Python: each `with <name>.check("<id>"):` block.
+// Returns null when the file cannot be read to the end; then the caller lists the whole file.
+export function checkBlocks(text, path) {
+  if (text === null) return new Map();
+  const blocks = new Map();
+  const src = text.replace(/\r\n?/g, '\n');
+  try {
+    if (path.endsWith('.py')) {
+      const lines = src.split('\n');
+      for (let i = 0; i < lines.length; i += 1) {
+        const m = /^(\s*)with\s+\w+\.check\(\s*(["'])([^"']+)\2\s*\)\s*(as\s+\w+\s*)?:\s*(#.*)?$/.exec(lines[i]);
+        if (!m || !CHECK_ID.test(m[3])) continue;
+        const indent = m[1].length;
+        let j = i + 1;
+        while (j < lines.length && (lines[j].trim() === '' || lines[j].search(/\S/) > indent)) j += 1;
+        add(blocks, keyOf(m[3]), lines.slice(i, j).join('\n').trimEnd());
+      }
+      return blocks;
+    }
+    const call = /\b\w+\.check\(\s*(["'`])([^"'`\n]+)\1/g;
+    let m;
+    let from = 0;
+    while ((m = call.exec(src))) {
+      if (m.index < from || !CHECK_ID.test(m[2])) continue;
+      const open = src.indexOf('(', m.index);
+      const end = balanced(src, open, '(', ')');
+      add(blocks, keyOf(m[2]), src.slice(m.index, end));
+      from = end;
+      call.lastIndex = end;
+    }
+    return blocks;
+  } catch {
+    return null;
+  }
+}
+
+// Two blocks with one id are kept as one text, so a second copy shows as a change.
+function add(map, key, text) { map.set(key, map.has(key) ? `${map.get(key)}\n${text}` : text); }
+
+// The assertions and the case tables of one scenario file on one side: Map of id to fingerprint.
+// null when the file does not parse.
+function scenarioPrints(text, path, testsText) {
+  if (text === null) return { id: null, prints: new Map() };
+  let tests = null;
+  try { const v = testsText === null ? null : parseYaml(testsText).value; tests = v && typeof v === 'object' ? v : null; } catch { tests = null; }
+  let s;
+  try { s = parseScenario(text, path); } catch { return null; }
+  if (!s || !s.id) return null;
+  addFingerprints(s, tests);
+  const prints = new Map();
+  for (const a of s.assertions) prints.set(a.id, a.fp ?? fingerprintOf(a.words));
+  for (const [name, table] of s.tables ?? []) prints.set(name, table.fingerprint ?? fingerprintOf(JSON.stringify(table)));
+  return { id: s.id, prints };
+}
+
+// ---------------------------------------------------------------- the list
+
+const row = (area, group, status, path, from = null, id = null, contentChanged = null) => ({ area, group, status, path, from, id, content_changed: contentChanged });
+
+// Rows for the ids of two sides: added, changed or removed. `inner` names each id.
+function compareMaps(baseMap, headMap, make) {
+  const out = [];
+  for (const [id, text] of headMap) {
+    if (!baseMap.has(id)) out.push(make('added', id));
+    else if (baseMap.get(id) !== text) out.push(make('changed', id));
+  }
+  for (const id of baseMap.keys()) if (!headMap.has(id)) out.push(make('removed', id));
+  return out;
+}
+
+// The changes of the diff, from `git diff --name-status -z`. A copy reads as added.
+function diffEntries(cwd, from, to) {
+  const parts = git(cwd, ['diff', '--name-status', '-M', '-z', '--no-ext-diff', '--no-textconv', from, to]).split('\0');
+  const out = [];
+  for (let i = 0; i < parts.length && parts[i];) {
+    const code = parts[i][0];
+    if (code === 'R' || code === 'C') {
+      out.push({ status: code === 'R' ? 'renamed' : 'added', from: code === 'R' ? parts[i + 1] : null, path: parts[i + 2] });
+      i += 3;
+    } else {
+      out.push({ status: code === 'A' ? 'added' : code === 'D' ? 'removed' : 'changed', from: null, path: parts[i + 1] });
+      i += 2;
+    }
+  }
+  return out;
+}
+
+// The areas on one side: each folder that holds atlas/tests.yaml. '' is the repo root.
+function areasAt(cwd, sha) {
+  const listed = git(cwd, ['ls-tree', '-r', '--name-only', '-z', sha], { allowFail: true }) ?? '';
+  return listed.split('\0')
+    .filter((p) => p === 'atlas/tests.yaml' || p.endsWith('/atlas/tests.yaml'))
+    .map((p) => p.slice(0, -'atlas/tests.yaml'.length).replace(/\/$/, ''))
+    .filter((area) => !area.split('/').some((part) => FIXTURE_PART.has(part)));
+}
+
+function scenarioFilesAt(cwd, sha, area) {
+  const dir = area ? `${area}/scenarios` : 'scenarios';
+  const listed = git(cwd, ['ls-tree', '-r', '--name-only', '-z', sha, '--', dir], { allowFail: true }) ?? '';
+  return listed.split('\0').filter((p) => p.endsWith('.md') && !SKIP_SCENARIO.test(p));
+}
+
+const testsYamlOf = (area) => (area ? `${area}/atlas/tests.yaml` : 'atlas/tests.yaml');
+
+// Lists the test things that the head changes against `base`. Returns the JSON answer.
+export function listChanged({ root, base, head = 'HEAD' }) {
+  if (!base) throw usage('give the base: --base <ref>');
+  for (const ref of [base, head]) if (String(ref).startsWith('-')) throw usage(`"${ref}" is not a ref`);
+  const cwd = resolve(root);
+  const top = git(cwd, ['rev-parse', '--show-toplevel']).trim();
+  const shallow = (git(top, ['rev-parse', '--is-shallow-repository'], { allowFail: true }) ?? '').trim() === 'true';
+  const hint = shallow ? ' This clone is shallow. Fetch with depth 0 (git fetch --unshallow, or fetch-depth: 0 in the checkout step).' : '';
+  const commit = (ref) => (git(top, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`], { allowFail: true }) ?? '').trim();
+  const baseSha = commit(base);
+  if (!baseSha) throw new Error(`the base "${base}" is not a commit in this repo.${hint}`);
+  const headSha = commit(head);
+  if (!headSha) throw new Error(`the head "${head}" is not a commit in this repo.`);
+  const mergeBase = (git(top, [MERGE_BASE, '--end-of-options', baseSha, headSha], { allowFail: true }) ?? '').trim();
+  if (!mergeBase) throw new Error(`the base "${base}" and the head have no common commit that this clone holds.${hint}`);
+  if (mergeBase === headSha && baseSha !== headSha) throw new Error(`the base "${base}" is ahead of the head (the merge base is the head). Give the base the pull request targets.`);
+
+  const entries = diffEntries(top, mergeBase, headSha);
+  const areas = [...new Set([...areasAt(top, mergeBase), ...areasAt(top, headSha)])].sort((a, b) => b.length - a.length);
+  const rows = [];
+  const other = [];
+
+  // A changed tests.yaml can change the fingerprints of every scenario of its area, so those are read too.
+  const scenarioPairs = new Map();
+  const addPair = (path, from) => { if (from || !scenarioPairs.has(path)) scenarioPairs.set(path, from ?? path); };
+  for (const e of entries) {
+    if (!e.path.endsWith('atlas/tests.yaml')) continue;
+    const area = e.path.slice(0, -'atlas/tests.yaml'.length).replace(/\/$/, '');
+    if (!areas.includes(area)) continue;
+    for (const p of new Set([...scenarioFilesAt(top, mergeBase, area), ...scenarioFilesAt(top, headSha, area)])) addPair(p, null);
+  }
+  const blob = (sha, path) => (git(top, ['rev-parse', '--verify', '--quiet', `${sha}:${path}`], { allowFail: true }) ?? '').trim();
+
+  for (const e of entries) {
+    const path = e.path;
+    const group = groupOf(path, areas) ?? (e.from ? groupOf(e.from, areas) : null);
+    if (!group) { other.push(path); continue; }
+    const area = areaOf(path, areas);
+    const before = e.from ?? path;
+    // A rename says whether the bytes moved as they were. Other statuses leave it null.
+    const moved = e.status === 'renamed' ? blob(mergeBase, before) !== blob(headSha, path) : null;
+    const fileRow = (status = e.status) => row(area, group, status, path, e.status === 'renamed' ? e.from : null, null, moved);
+    const idRow = (status, id) => row(area, group, status, path, null, id);
+    if (group === 'scenario-words') { addPair(path, e.from); continue; }
+    if (group === 'check-block') {
+      if (e.status === 'added' || e.status === 'removed') { rows.push(fileRow()); continue; }
+      if (e.status === 'renamed') rows.push(fileRow());
+      const b = checkBlocks(show(top, mergeBase, before), before);
+      const h = checkBlocks(show(top, headSha, path), path);
+      if (b === null || h === null) { if (e.status !== 'renamed') rows.push(fileRow('changed')); continue; }
+      const blockRows = compareMaps(b, h, idRow);
+      rows.push(...blockRows);
+      // Code outside the blocks (a setup, a helper inside the file) changed: the file itself is a row.
+      if (!blockRows.length && e.status === 'changed') rows.push(fileRow('changed'));
+      continue;
+    }
+    if (group === 'test-script') {
+      const b = testScripts(show(top, mergeBase, before));
+      const h = testScripts(show(top, headSha, path));
+      if (b === null || h === null) { rows.push(fileRow()); continue; }
+      const scriptRows = compareMaps(new Map(Object.entries(b)), new Map(Object.entries(h)), idRow);
+      if (!scriptRows.length) other.push(path);
+      rows.push(...scriptRows);
+      continue;
+    }
+    if (group === 'runner-config') {
+      const name = posix.basename(path);
+      if (name === 'pyproject.toml' || name === 'setup.cfg') {
+        const b = pytestSection(show(top, mergeBase, before), name);
+        const h = pytestSection(show(top, headSha, path), name);
+        if (b === h) { other.push(path); continue; }
+        rows.push(fileRow(!b ? 'added' : !h ? 'removed' : 'changed'));
+        continue;
+      }
+    }
+    rows.push(fileRow());
+  }
+
+  for (const [path, from] of scenarioPairs) {
+    const area = scenarioArea(path, areas) ?? scenarioArea(from, areas) ?? '';
+    const headText = show(top, headSha, path);
+    const b = scenarioPrints(show(top, mergeBase, from), from, show(top, mergeBase, testsYamlOf(area)));
+    const h = scenarioPrints(headText, path, show(top, headSha, testsYamlOf(area)));
+    if (b === null || h === null) {
+      rows.push(row(area, 'scenario-words', headText === null ? 'removed' : 'changed', path));
+      continue;
+    }
+    const scenarioId = h.id ?? b.id;
+    rows.push(...compareMaps(b.prints, h.prints, (status, id) => row(area, 'scenario-words', status, path, null, `${scenarioId}/${id}`)));
+  }
+
+  const order = (r) => [r.area, GROUPS.indexOf(r.group), r.path, r.id ?? '', STATUSES.indexOf(r.status)];
+  rows.sort((x, y) => {
+    const a = order(x);
+    const b = order(y);
+    for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+    return 0;
+  });
+  const counts = Object.fromEntries(STATUSES.map((s) => [s, rows.filter((r) => r.status === s).length]));
+  return { changed_tests: VERSION, base, merge_base: mergeBase, head: headSha, counts, other_paths: [...new Set(other)].sort(), rows };
+}
+
+// ---------------------------------------------------------------- the command
+
+const oneLine = (text) => String(text).replace(/[\u0000-\u001f\u007f]/g, ' ');
+
+export function renderText(answer) {
+  const c = answer.counts;
+  const out = [`${answer.rows.length} test change(s) against ${oneLine(answer.base)} (merge base ${answer.merge_base.slice(0, 7)}): ${c.added} added, ${c.changed} changed, ${c.renamed} renamed, ${c.removed} removed`];
+  for (const r of answer.rows) {
+    const tail = [r.id ? oneLine(r.id) : null, r.from ? `(from ${oneLine(r.from)})` : null].filter(Boolean).join('  ');
+    out.push(`  ${r.status.padEnd(8)} ${r.group.padEnd(14)} ${oneLine(r.path)}${tail ? `  ${tail}` : ''}`);
+  }
+  out.push(`${answer.other_paths.length} other changed path(s) match no test rule.`);
+  return out;
+}
+
+export function changedCommand({ base, head, out, text = false }, root, line) {
+  try {
+    const answer = listChanged({ root, base, head: head ?? 'HEAD' });
+    const json = `${JSON.stringify(answer, null, 2)}\n`;
+    if (out) writeFileSync(resolve(out), json);
+    if (text) for (const l of renderText(answer)) line(l);
+    else if (!out) process.stdout.write(json);
+    else line(`Wrote ${out}: ${answer.rows.length} test change(s).`);
+    return 0;
+  } catch (error) {
+    line(`changed: ${error.message}`);
+    return error.usage ? 2 : 1;
+  }
+}

package/door/lib/tests.mjs

@@ -31,9 +31,12 @@ export class KitRefusal extends Error {
   constructor(message) { super(message); this.name = 'KitRefusal'; }
 }
 
+// Python bytecode (__pycache__) is never part of the kit: a dev tree that ran a
+// Python test may hold it, and it must not reach a repo.
 function filesUnder(dir, prefix = '') {
   const out = [];
   for (const name of readdirSync(dir).sort()) {
+    if (name === '__pycache__') continue;
     const full = join(dir, name);
     if (statSync(full).isDirectory()) out.push(...filesUnder(full, `${prefix}${name}/`));
     else out.push(`${prefix}${name}`);

package/package.json

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

package/skills/lead/SKILL.md

@@ -101,7 +101,7 @@ set. A test keeps the two lists equal.
 | `atlas kind-drift` | When the repo record and `atlas.yaml` may disagree on the kind; this command retires in stage 2, the onboarding stage |
 | `atlas code-read` | To resolve the citations of a code digest |
 | `atlas ste` | Before each publish; `--share` before a page goes to anyone else |
-| `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `kept` runs the kept tests of a path 1 area and writes their evidence. `proof`, `verdict`, `named`, `covers` and `rerun` read the results of a run. `sweep` and `issues` run the daily sweep |
+| `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `kept` runs the kept tests of a path 1 area and writes their evidence. `proof`, `verdict`, `named`, `covers` and `rerun` read the results of a run. `changed` lists each test that a pull request changes, as JSON, for the gate's test checks. `sweep` and `issues` run the daily sweep |
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
 | `atlas upkeep` | `check` before you ask for a merge: the docs index, dead doc links, and the tracker item a pull request names. The daily upkeep run calls it on the main branch |

package/skills/tests/SKILL.md

@@ -358,6 +358,31 @@ not counted, and the test passes.
 After the product is ready, a lost connection, a server exit or a time-out is
 `fail`. `blocked` is for a guard refusal, a start-up fault and the first-call check.
 
+### A test in Python
+
+Use the Python library when the runner of the area is Python. Its header,
+`test/atlas/contract.py`, holds a worked example.
+
+1. Name the file `test/scenarios/<name>_test.py`. List a Python runner in
+   `runner` of `tests.yaml`. `runner` may be a list, one runner for each
+   language.
+2. Before the import, set `sys.dont_write_bytecode = True`. Put
+   `test/atlas` on `sys.path`, and import `scenario` from `contract`.
+   Run Python with `-B`: the check refuses bytecode in the test folder.
+   Never run it with `-O`, which removes every assert.
+3. Decorate the body: `@scenario("../../scenarios/<name>.md", adapter=adapter)`.
+4. Write each check as a `with` block that holds an assert statement:
+   `with run.check("<scenario>/e1#<fingerprint>"):`. Use `run.gate` for a gate.
+   To keep a short proof, set `proof.value` in `with ... as proof:`.
+5. Use `run.not_exercised` and `run.wait_for`, in snake case.
+6. Give the driver of each way in through the adapter (`define_adapter`).
+   Build its child environment with `child_env`.
+
+The library reads the scenario through node, so the runner needs node and
+python3. It does not yet start an environment, give run secrets, repeat a
+run, ask a judge or ship drivers. Each of these ends `blocked`. Write such a
+scenario with `contract.mjs`.
+
 ### A model in the test
 
 A model makes a test vary and costs money. Three parts of the kit handle it.

package/tests/bridge.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// The bridge for a contract library in another language (design section 8.1).
+// A library in Python, say, must read a scenario exactly as the link check
+// reads it: the same parser, the same fingerprints, the same tests.yaml check
+// and the same guard comparison. So it does not parse the words itself. It
+// runs this file and reads one JSON object:
+//
+//   node bridge.mjs load <scenario.md>
+//   -> { root, file, environment, evidenceDir, guardRefusal, tests, envSpec, shippedDrivers, wayGuardParts,
+//        scenario: { id, title, file, sha256, method, fields, through, ways, repeat,
+//                    assertions: [{ id, fullId, kind, gate, ways, fp, names, line }],
+//                    tables: { T1: { name, kind, header, rows, fingerprint, cases } } } }
+//
+// `cases` is every case of a combination table (every combination, or a set
+// that holds every pair), so the other language need not make them again.
+// A fault in the scenario or in tests.yaml prints { error } and exits 1.
+// The environment and the folders come from the same variables as
+// contract.mjs: ATLAS_ENV, CI, ATLAS_EVIDENCE_DIR and ATLAS_GUARDS_FROM.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readTestsYaml, checkTestsYaml, compareGuardParts, resolveEnvironments, GUARD_PARTS } from './tests-yaml.mjs';
+import { SHIPPED_DRIVERS } from './drivers/index.mjs';
+import { readScenario, addFingerprints, combinations, pairs } from './scenario.mjs';
+
+function findRoot(file) {
+  let dir = dirname(file);
+  for (;;) {
+    if (existsSync(join(dir, 'atlas', 'tests.yaml'))) return dir;
+    const up = dirname(dir);
+    if (up === dir) throw new Error(`no atlas/tests.yaml above ${file}`);
+    dir = up;
+  }
+}
+
+export function loadForLibrary(path, env = process.env) {
+  const file = resolve(String(path));
+  const root = findRoot(file);
+  const yaml = readTestsYaml(join(root, 'atlas', 'tests.yaml'));
+  const findings = checkTestsYaml(yaml);
+  if (findings.length) throw new Error(`atlas/tests.yaml: ${findings.map((f) => `line ${f.line}: ${f.message}`).join('; ')}`);
+  const sc = readScenario(file);
+  if (sc.problems.length) throw new Error(`${path}: ${sc.problems.map((p) => `line ${p.line}: ${p.message}`).join('; ')}`);
+  const tests = yaml.value;
+  addFingerprints(sc, tests);
+  // The same rule as contract.mjs: a branch whose guard parts differ from the main branch copy is refused.
+  let guardRefusal = null;
+  if (env.ATLAS_GUARDS_FROM) {
+    try {
+      const changes = compareGuardParts(readFileSync(env.ATLAS_GUARDS_FROM, 'utf8'), yaml.value);
+      if (changes.length) guardRefusal = `the guard parts of atlas/tests.yaml differ from the main branch copy (${changes.map((c) => c.part).join(', ')}); the run is refused. A change to a guard part comes to the owner`;
+    } catch (error) {
+      guardRefusal = `ATLAS_GUARDS_FROM names a file that cannot be read as tests.yaml (${error.code ?? error.message}); the run is refused`;
+    }
+  }
+  const environment = env.ATLAS_ENV ?? (env.CI ? 'ci' : 'local');
+  const evidenceDir = env.ATLAS_EVIDENCE_DIR ?? join(root, 'test', 'evidence');
+  const tables = {};
+  for (const [name, t] of sc.tables) {
+    const cases = t.kind === 'combination' ? (t.cover === 'pair' ? pairs(t.dimensions) : combinations(t.dimensions)) : null;
+    tables[name] = { name, kind: t.kind, header: t.header ?? null, rows: t.rows ?? [], fingerprint: t.fingerprint, cases };
+  }
+  return {
+    root, file, environment, evidenceDir, guardRefusal, tests,
+    // What a library in another language must refuse until it has its own form of the guard.
+    shippedDrivers: SHIPPED_DRIVERS,
+    wayGuardParts: GUARD_PARTS.filter((p) => p.startsWith('ways-in.*.')).map((p) => p.slice('ways-in.*.'.length)),
+    envSpec: resolveEnvironments(tests.environments ?? {})[environment] ?? null,
+    scenario: {
+      id: sc.id, title: sc.title, file: sc.file, sha256: sc.sha256, method: sc.method,
+      names: [...new Set([...sc.start, ...sc.steps, ...sc.assertions].flatMap((x) => x.names ?? []))],
+      fields: sc.fields, through: sc.through, ways: sc.ways ?? sc.through, repeat: sc.repeat ?? null,
+      assertions: sc.assertions.map((a) => ({ id: a.id, fullId: a.fullId, kind: a.kind, gate: Boolean(a.gate), ways: a.ways ?? sc.through, fp: a.fp, names: a.names ?? [], line: a.line })),
+      tables,
+    },
+  };
+}
+
+export function main(argv, write = (text) => process.stdout.write(text)) {
+  const [verb, path] = argv;
+  if (verb !== 'load' || !path) { process.stderr.write('bridge: use "bridge.mjs load <scenario.md>"\n'); return 2; }
+  try {
+    write(`${JSON.stringify(loadForLibrary(path))}\n`);
+    return 0;
+  } catch (error) {
+    write(`${JSON.stringify({ error: error.message })}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));