@arjunkhera/atlas 0.4.33 → 0.4.34

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -139,7 +139,7 @@ const HELP = `atlas — the door into a repo's Atlas files
       --dry-run                        print what it would open; change nothing
                                        The token is only GITHUB_TOKEN. The atlas-jobs workflow runs both, once a day
 
-  atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, the code each doc names, and in a pull request its tracker item
+  atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, the code each doc names, stale pages, and in a pull request its tracker item, its changed designs and STE on its changed lines
   atlas upkeep replay --root <repo>    what the doc-sources rule would have asked of the last merges; writes nothing
   atlas upkeep procedures --root <repo>  run the procedure steps marked atlas-run; --base <ref> runs only the procedures a change touches
       --last <n>                       how many merges on the first-parent line; default 30

package/door/lib/changed-docs.mjs

@@ -0,0 +1,190 @@
+// The checks of the changed designs, docs and pages (roadmap R65, item
+// 536c8ddd). Code, no model, no key, no network. `atlas upkeep check` runs
+// them. Design: docs/design-docs/upkeep-reads-changes/.
+//
+// 1. Designs. With a pull request, each design folder that it adds or
+//    changes passes the design check of this package. An old design that the
+//    pull request does not touch is not read.
+// 2. STE. With a pull request, each markdown file that it adds or changes is
+//    measured against the STE limits. A finding on a line the pull request
+//    adds or changes fails; one on an unchanged line is only listed, so an
+//    old page does not block a small fix.
+// 3. Pages. Each row of docs/artifacts.json names a build command or a
+//    frozen date. A page whose source changed after the page is listed as
+//    stale, from git dates. A repo with no docs/artifacts.json skips this.
+//
+// archive/, node_modules, fixtures and each folder that atlas.yaml lists
+// under `verbatim:` (text kept word for word, such as docs/intake/) are
+// skipped by 1 and 2. A page with `generated: true` in its front matter is
+// kept by the code that writes it, so 2 skips it too.
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { parseYaml } from '../../shape/check.mjs';
+import { checkDesignFolder, DESIGN_FILE } from './design.mjs';
+import { checkText, markdownUnits } from './ste.mjs';
+
+export const ARTIFACTS = 'docs/artifacts.json';
+const SKIP_PARTS = new Set(['node_modules', 'archive', 'fixtures']);
+const MAX_LISTED = 20;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+const git = (root, args) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 });
+const readText = (root, path) => { try { return readFileSync(join(root, path), 'utf8'); } catch { return null; } };
+
+// The folders that atlas.yaml marks as verbatim, as plain paths with no
+// trailing slash. A missing or unreadable atlas.yaml marks none.
+export function verbatimFolders(root) {
+  const text = readText(root, 'atlas.yaml');
+  if (text === null) return [];
+  let data;
+  try { data = parseYaml(text); } catch { return []; }
+  const list = data && typeof data === 'object' ? data.verbatim : null;
+  if (!Array.isArray(list)) return [];
+  return list.map((one) => String(one).trim().replace(/^\.\//, '').replace(/\/+$/, '')).filter(Boolean);
+}
+
+const under = (path, folder) => path === folder || path.startsWith(`${folder}/`);
+export function skipped(path, verbatim = []) {
+  if (path.split('/').some((part) => SKIP_PARTS.has(part))) return true;
+  return verbatim.some((folder) => under(path, folder));
+}
+
+// The paths a pull request adds or changes, from the merge base of its base
+// to its head. A deleted path is not listed: nothing is left to check.
+export function changedPaths(root, base, head) {
+  const out = git(root, ['diff', '--name-only', '--no-renames', '--diff-filter=d', '-z', '--no-ext-diff', '--no-textconv', `${base}...${head}`]);
+  return out.split('\0').filter(Boolean).sort();
+}
+
+// The line numbers of one file that the pull request adds or changes, from
+// the hunks of a diff with no context.
+export function addedLines(root, base, head, path) {
+  const out = git(root, ['diff', '-U0', '--no-renames', '--no-ext-diff', '--no-textconv', `${base}...${head}`, '--', path]);
+  const lines = new Set();
+  for (const [, start, count] of out.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
+    const first = Number(start);
+    const n = count === undefined ? 1 : Number(count);
+    for (let line = first; line < first + n; line += 1) lines.add(line);
+  }
+  return lines;
+}
+
+// The nearest folder at or above `path` that holds design.yaml, or null.
+function designOf(root, path) {
+  let dir = posix.dirname(path);
+  while (dir && dir !== '.') {
+    if (existsSync(join(root, dir, DESIGN_FILE))) return dir;
+    dir = posix.dirname(dir);
+  }
+  return null;
+}
+
+export function changedDesigns(root, paths, verbatim = []) {
+  const folders = new Set();
+  for (const path of paths) {
+    if (skipped(path, verbatim)) continue;
+    const folder = designOf(root, path);
+    if (folder && !skipped(folder, verbatim)) folders.add(folder);
+  }
+  return [...folders].sort();
+}
+
+const generated = (text) => {
+  const head = /^---\n([\s\S]*?)\n---/.exec(String(text).replace(/\r\n?/g, '\n'));
+  if (!head) return false;
+  try { return parseYaml(head[1])?.generated === true; } catch { return false; }
+};
+
+// The STE findings of one markdown text, split by the lines a pull request
+// changed. A finding names the line its paragraph, item or cell starts on, so
+// a finding counts as changed when any line of that unit changed.
+export function steSplit(text, changed) {
+  const units = markdownUnits(text);
+  const total = text.split('\n').length;
+  const spanOf = (line) => {
+    const next = units.find((unit) => unit.line > line);
+    return [line, next ? next.line - 1 : total];
+  };
+  const out = { changed: [], unchanged: [] };
+  for (const finding of checkText(text)) {
+    const [from, to] = spanOf(finding.line);
+    let hit = false;
+    for (let line = from; line <= to && !hit; line += 1) hit = changed.has(line);
+    (hit ? out.changed : out.unchanged).push(finding);
+  }
+  return out;
+}
+
+// The rows of docs/artifacts.json: each names a build command or a frozen
+// date, and a page whose source changed after it is stale.
+export function artifactRows(root) {
+  const text = readText(root, ARTIFACTS);
+  if (text === null) return { checked: false, findings: [], stale: [] };
+  let data;
+  try { data = JSON.parse(text); } catch (error) { return { checked: true, findings: [`pages: ${ARTIFACTS} is not JSON: ${error.message}`], stale: [] }; }
+  const rows = Array.isArray(data?.artifacts) ? data.artifacts : null;
+  if (!rows) return { checked: true, findings: [`pages: ${ARTIFACTS} has no "artifacts" list`], stale: [] };
+  const findings = [];
+  const stale = [];
+  const lastChange = (path) => {
+    try { return Number(git(root, ['log', '-1', '--format=%ct', '--', path]).trim()) || null; } catch { return null; }
+  };
+  rows.forEach((row, index) => {
+    const name = row?.title ? `"${row.title}"` : `row ${index + 1}`;
+    const build = typeof row?.build === 'string' && row.build.trim() && !/^none\b/i.test(row.build.trim());
+    const frozen = typeof row?.frozen === 'string' && DATE.test(row.frozen);
+    if (row?.frozen !== undefined && !frozen) findings.push(`pages: ${name} in ${ARTIFACTS} has frozen "${row.frozen}"; write a date as YYYY-MM-DD`);
+    else if (!build && !frozen) findings.push(`pages: ${name} in ${ARTIFACTS} names no build command and no frozen date`);
+    if (!build || frozen) return;
+    const page = typeof row.local_path === 'string' ? row.local_path : null;
+    const source = typeof row.source === 'string' ? row.source.replace(/\/+$/, '') : null;
+    if (!page || !source || !existsSync(join(root, page)) || !existsSync(join(root, source))) return;
+    const [pageAt, sourceAt] = [lastChange(page), lastChange(source)];
+    if (pageAt && sourceAt && sourceAt > pageAt) stale.push({ title: row.title ?? null, page, source, build: row.build });
+  });
+  return { checked: true, findings, stale };
+}
+
+// The three checks. `pr` is the pull_request of a GitHub event, or null on
+// the main branch, where 1 and 2 have no change to read.
+export function changedDocFindings(root, { pr = null } = {}) {
+  const findings = [];
+  const notes = [];
+  const verbatim = verbatimFolders(root);
+  const result = { designs: null, pages: null, ste: null, verbatim };
+  const base = pr?.base?.sha;
+  const head = pr?.head?.sha;
+  if (base && head && existsSync(join(root, '.git'))) {
+    let paths = null;
+    try { paths = changedPaths(root, base, head); } catch (error) { findings.push(`changed docs: the changed paths could not be read: ${String(error.message).split('\n')[0]}`); }
+    if (paths) {
+      result.designs = changedDesigns(root, paths, verbatim);
+      for (const folder of result.designs) {
+        const found = checkDesignFolder(join(root, folder));
+        for (const one of found.slice(0, MAX_LISTED)) findings.push(`design: ${folder}/${one.file}:${one.line} ${one.rule}: ${one.why}`);
+        if (found.length > MAX_LISTED) findings.push(`design: ${folder}: ${found.length - MAX_LISTED} more`);
+      }
+      const pages = paths.filter((path) => path.endsWith('.md') && !skipped(path, verbatim));
+      result.ste = { files: 0, changed: 0, unchanged: 0 };
+      for (const path of pages) {
+        let stat;
+        try { stat = statSync(join(root, path)); } catch { continue; }
+        if (!stat.isFile()) continue;
+        const text = readFileSync(join(root, path), 'utf8');
+        if (generated(text)) continue;
+        result.ste.files += 1;
+        const split = steSplit(text, addedLines(root, base, head, path));
+        result.ste.changed += split.changed.length;
+        result.ste.unchanged += split.unchanged.length;
+        for (const one of split.changed) findings.push(`ste: ${path}:${one.line} ${one.rule}: ${one.why}`);
+        if (split.unchanged.length) notes.push(`ste: ${path} has ${split.unchanged.length} finding(s) on lines this pull request does not change, at line(s) ${split.unchanged.slice(0, MAX_LISTED).map((one) => one.line).join(', ')}`);
+      }
+    }
+  }
+  result.pages = artifactRows(root);
+  findings.push(...result.pages.findings);
+  for (const one of result.pages.stale.slice(0, MAX_LISTED)) notes.push(`stale page: ${one.page} is older than its source ${one.source}. Rebuild it: ${one.build}`);
+  if (result.pages.stale.length > MAX_LISTED) notes.push(`stale page: ${result.pages.stale.length - MAX_LISTED} more`);
+  return { findings, notes, ...result };
+}

package/door/lib/upkeep.mjs

@@ -17,6 +17,11 @@
 //    procedure names its code, or why it names none, and each named path
 //    exists. With --event, each doc whose code the pull request changes is
 //    updated in it, or marked "still true" in its text (TOUCHED_DOCS_GATE).
+// 5. Changed docs (roadmap R65, lib/changed-docs.mjs). With --event, each
+//    design folder the pull request adds or changes passes the design check,
+//    and each changed markdown file passes the STE limits on its changed
+//    lines. Each row of docs/artifacts.json names a build or a frozen date,
+//    and a stale page is listed.
 //
 // It reads the tree and the event file, and writes nothing.
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
@@ -24,6 +29,7 @@ import { join, dirname, posix, resolve } from 'node:path';
 import { listChanged } from './changed-tests.mjs';
 import { docSourceFindings, replay } from './doc-sources.mjs';
 import { proceduresCommand } from './procedure-steps.mjs';
+import { changedDocFindings } from './changed-docs.mjs';
 
 // R39 line 4 gates only after the replay of line 3. The replay of the last 30
 // merges (atlas#225): rule "file" pulled in 81 docs over 24 merges, 58 not
@@ -234,6 +240,8 @@ export function upkeepCheck(root, { event = null } = {}) {
   if (dead.length > MAX_LISTED) findings.push(`dead link: ${dead.length - MAX_LISTED} more`);
   const sources = docSourceFindings(root, { pr: event?.pull_request ?? null, gate: TOUCHED_DOCS_GATE });
   findings.push(...sources.findings);
+  const docs = changedDocFindings(root, { pr: event?.pull_request ?? null });
+  findings.push(...docs.findings);
   if (item.checked && !item.ok) findings.push('item: the pull request names no tracker item. Put the item id in the title, the body or the branch, or write "no item:" and a reason');
   // The heading check holds a pull request that names an item, in a repo that
   // keeps the Atlas template. A repo without the template is not held yet.
@@ -244,7 +252,7 @@ export function upkeepCheck(root, { event = null } = {}) {
     if (text.tests.error) findings.push(`pr text: the changed-test list could not be made: ${text.tests.error}`);
     else if (text.tests.checked) findings.push(...changedTestsFindings(event.pull_request.body, text.tests.rows));
   }
-  return { green: findings.length === 0, findings, notes: sources.notes, index, dead, item, text, sources };
+  return { green: findings.length === 0, findings, notes: [...sources.notes, ...docs.notes], index, dead, item, text, sources, docs };
 }
 
 export function upkeepCommand({ what, event: eventFile, json = false, last, base }, root, line) {
@@ -263,6 +271,9 @@ export function upkeepCommand({ what, event: eventFile, json = false, last, base
   line(`pr text: ${result.text.checked ? 'the six headings were read' : 'not checked'}`);
   if (result.text.checked) line(`changed tests: ${result.text.tests?.checked ? (result.text.tests.error ? 'no list' : `${result.text.tests.rows.filter((row) => NAMED_GROUPS.has(row.group)).length} row(s) to name`) : `not checked (${result.text.tests?.why})`}`);
   line(`doc sources: ${result.sources.units} doc(s) and procedure(s)${result.sources.touched ? `; this pull request touches the code of ${result.sources.touched.length}` : ''}`);
+  line(`designs: ${result.docs.designs ? `${result.docs.designs.length} changed design folder(s) checked` : 'not a pull request'}`);
+  line(`ste: ${result.docs.ste ? `${result.docs.ste.files} changed markdown file(s); ${result.docs.ste.changed} finding(s) on changed lines, ${result.docs.ste.unchanged} on other lines` : 'not a pull request'}`);
+  line(`pages: ${result.docs.pages.checked ? `${result.docs.pages.stale.length} stale` : 'no docs/artifacts.json'}`);
   for (const finding of result.findings) line(`  - ${finding}`);
   for (const note of result.notes) line(`  note: ${note}`);
   line(`upkeep check: ${result.green ? 'GREEN' : 'RED'}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.33",
+  "version": "0.4.34",
   "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

@@ -110,7 +110,7 @@ set. A test keeps the two lists equal.
 | `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 jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |
-| `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names, and the tracker item of a pull request. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates. `procedures` runs the procedure steps tagged `atlas-run`; CI runs it with `--base` on each pull request |
+| `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names and stale pages. In a pull request it also reads the tracker item, the changed designs, and STE on the changed lines. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates. `procedures` runs the procedure steps tagged `atlas-run`; CI runs it with `--base` on each pull request |
 | `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
 | `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |