@arjunkhera/atlas 0.4.45 → 0.4.47

package/door/lib/upkeep.mjs

@@ -7,7 +7,8 @@
 //
 // 1. Docs index. docs/index.md lists each .md file under docs/. A file in a
 //    design folder (a folder that holds design.yaml) counts as listed when the
-//    index lists that folder's design.yaml. Each listed path exists.
+//    index lists that folder's design.yaml. Each listed path exists. The rule
+//    is the shape check's own, docsIndexRule (roadmap R62 line 5).
 // 2. Dead links. Each relative link in a tracked .md file names a file or a
 //    folder that exists. archive/ is frozen, and test fixtures are planted on
 //    purpose, so both are skipped; so is text inside code.
@@ -24,8 +25,9 @@
 //    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';
-import { join, dirname, posix, resolve } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { DOCS_INDEX_PATH, docsIndexRule, markdownFiles, proseOf, linkTargets } from '../../shape/check.mjs';
 import { listChanged } from './changed-tests.mjs';
 import { docSourceFindings, replay } from './doc-sources.mjs';
 import { proceduresCommand } from './procedure-steps.mjs';
@@ -37,62 +39,13 @@ import { changedDocFindings } from './changed-docs.mjs';
 // touched doc with no update and no mark a note, not a finding.
 export const TOUCHED_DOCS_GATE = true;
 
-const INDEX = 'docs/index.md';
-const SKIP_DIRS = new Set(['node_modules', 'archive', 'fixtures']);
+const INDEX = DOCS_INDEX_PATH;
 const MAX_LISTED = 20;
 
-// Every .md file under the root, as a posix path. Dot folders, node_modules,
-// archive/ and any folder named fixtures are skipped.
-export function markdownFiles(root, under = '') {
-  const out = [];
-  const walk = (rel) => {
-    let entries;
-    try { entries = readdirSync(join(root, rel), { withFileTypes: true }); } catch { return; }
-    for (const entry of entries) {
-      if (entry.name.startsWith('.')) continue;
-      const path = rel ? `${rel}/${entry.name}` : entry.name;
-      if (entry.isDirectory()) { if (!SKIP_DIRS.has(entry.name)) walk(path); }
-      else if (entry.isFile() && entry.name.endsWith('.md')) out.push(path);
-    }
-  };
-  walk(under);
-  return out.sort();
-}
-
-// Text outside code: fenced blocks of three or more marks, and inline code.
-export function proseOf(text) {
-  const lines = String(text ?? '').split('\n');
-  const kept = [];
-  let fence = null;
-  for (const one of lines) {
-    const open = one.match(/^\s*(`{3,}|~{3,})/);
-    if (fence) {
-      if (open && open[1][0] === fence[0] && open[1].length >= fence.length && !one.trim().slice(open[1].length).trim()) fence = null;
-      kept.push('');
-      continue;
-    }
-    if (open) { fence = open[1]; kept.push(''); continue; }
-    kept.push(one.replace(/`+[^`\n]*`+/g, ''));
-  }
-  return kept.join('\n');
-}
-
-// The relative link targets in one markdown text, with their line numbers.
-export function linkTargets(text) {
-  const out = [];
-  proseOf(text).split('\n').forEach((one, index) => {
-    for (const [, angled, bare] of one.matchAll(/\]\(\s*(?:<([^>\n]+)>|([^)\s]+))(?:\s+"[^"]*")?\s*\)/g)) {
-      const raw = angled ?? bare;
-      const target = raw.split('#')[0].split('?')[0];
-      if (!target || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith('#')) continue;
-      if (/[{}$*\\]/.test(target)) continue;
-      let decoded = target;
-      try { decoded = decodeURIComponent(target); } catch { /* keep it as written */ }
-      out.push({ target: decoded, line: index + 1 });
-    }
-  });
-  return out;
-}
+// markdownFiles, proseOf and linkTargets live in the shape check, beside the
+// one docs index rule (roadmap R62 line 5). They stay exported here, so their
+// readers keep one door.
+export { markdownFiles, proseOf, linkTargets };
 
 export function deadLinks(root) {
   const dead = [];
@@ -106,32 +59,11 @@ export function deadLinks(root) {
   return dead;
 }
 
-// The nearest folder at or above `file` that holds design.yaml, or null.
-function designFolderOf(root, file) {
-  let dir = posix.dirname(file);
-  while (dir && dir !== '.' && dir !== 'docs') {
-    if (existsSync(join(root, dir, 'design.yaml'))) return dir;
-    dir = posix.dirname(dir);
-  }
-  return null;
-}
-
+// The docs index rule is the shape check's, so the check and this command
+// give one count on one tree (roadmap R62 line 5).
 export function docsIndex(root) {
-  if (!existsSync(join(root, 'docs')) || !statSync(join(root, 'docs')).isDirectory()) return { checked: false, unlisted: [], gone: [] };
-  if (!existsSync(join(root, INDEX))) return { checked: true, missing: true, unlisted: markdownFiles(root, 'docs'), gone: [] };
-  const listed = new Set();
-  for (const { target } of linkTargets(readFileSync(join(root, INDEX), 'utf8'))) {
-    if (target.startsWith('/')) continue;
-    const path = posix.normalize(posix.join('docs', target)).replace(/\/$/, '');
-    if (path.startsWith('docs/')) listed.add(path);
-  }
-  const unlisted = markdownFiles(root, 'docs').filter((path) => {
-    if (path === INDEX || listed.has(path)) return false;
-    const folder = designFolderOf(root, path);
-    return !(folder && listed.has(`${folder}/design.yaml`));
-  });
-  const gone = [...listed].filter((path) => !existsSync(join(root, path))).sort();
-  return { checked: true, unlisted, gone };
+  const { checked, missing, unlisted, gone } = docsIndexRule(root);
+  return missing ? { checked, missing, unlisted, gone } : { checked, unlisted, gone };
 }
 
 const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;

package/owner-only.yaml

@@ -218,22 +218,30 @@ floor:
 # does not follow names out of it (shape/check.mjs, the exemption).
 entry_map: docs/index.md
 
-# The keys of atlas.yaml whose change is always owner-only. A change to any
-# other key is owner-only too, until roadmap R62 lists the safe ones. The one
-# change that passes is an addition under `parts:`.
+# The key rule for atlas.yaml (roadmap R2 line 11, R62 line 3). Each key of
+# atlas.yaml is on one of the two lists. A pull request may add entries under
+# an add_only key and merge on green; any other change to it, and any change
+# to a fixed key, comes to the owner. A key on neither list comes to the owner
+# too, until a pull request puts it on one.
 atlas_yaml:
   add_only:
     - parts
+    - procedures
+    - files
+    - kinds_of_change
   fixed:
-    - owner_only
+    - spec
+    - product
+    - repo
     - areas
+    - owner_only
     - required_checks
-    - product
     - product_paths
-    - repo
-    - kind
-    - kinds
     - up_to_date
     - brake
+    - live
+    - jobs
+    - design
     - generated
-    - spec
+    - verbatim
+    - private_terms

package/package.json

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