@arjunkhera/atlas 0.3.8 → 0.3.10

package/door/lib/design.mjs

@@ -1,148 +1,229 @@
-// The design check. It reads one markdown design doc made from the
-// walkthrough template and flags each place where the doc breaks the shape:
-// a summary, four named parts of steps, an example and a picture in every
-// step, a definition of done, the kind of change, and a reference part.
+// The design check. A design is a folder: `design.yaml` names its title and
+// its kinds, and each part is one markdown file with `part: <id>` in its
+// front matter. The parts registry, `skills/sdlc-task/design/parts.yaml`,
+// says which kind needs which part.
 //
-// It proves the shape, not the quality. A person still judges whether an
-// example is good. It never rewrites a word.
-//
-// Grammar: a part is a line `## Part N — <name>`; a step is a line
-// `### Step N — <title>`. A step's text is the prose between its heading and
-// its `Example:` line. Lists, tables, code and quotes do not count as prose.
-import { readFileSync } from 'node:fs';
+// The check flags what a script can see: a needed part that is missing or
+// empty, a state line (state lives in the tracker), a code with no row in
+// the Key, a part the registry does not know, and a figure whose tags do not
+// close. It proves the shape, not the quality. It never rewrites a word.
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, dirname, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../shape/check.mjs';
 
-export const PARTS = Object.freeze(['What and why', 'How it flows', 'How it works', 'Decisions and done']);
-export const REFERENCE = Object.freeze({ name: 'Reference', sections: ['Approaches considered', 'Risks', 'Test plan'] });
-export const REQUIRED_SECTIONS = Object.freeze(['Definition of done', 'Kind of change, impact and undo']);
-export const MAX_STEP_SENTENCES = 3;
-export const MAX_SUMMARY_PARAGRAPHS = 2;
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const PARTS_FILE = join(PACKAGE_ROOT, 'skills', 'sdlc-task', 'design', 'parts.yaml');
+export const DESIGN_FILE = 'design.yaml';
+export const NEEDS = Object.freeze(['needed', 'optional', 'none', 'shared']);
+// design.yaml holds what a design is, never where it stands.
+export const DESIGN_KEYS = Object.freeze(['title', 'item', 'product', 'kinds', 'shared', 'look']);
+export const STATE_KEYS = Object.freeze(['status', 'state', 'stage', 'approved', 'locked', 'lock', 'shipped', 'delivered']);
+export const PART_KEYS = Object.freeze(['part', 'title']);
 
-const PART_LINE = /^## Part (\d+) [—–-] (.+?)\s*$/;
-const STEP_LINE = /^### Step (\d+) [—–-] (.+?)\s*$/;
-const EXAMPLE_LINE = /^Example\b[^:\n]*:/;
-const PICTURE_LINE = /^Picture:\s*(.*)$/;
-const DIAGRAM_FENCE = /^```\s*(mermaid|svg|diagram|dot|graphviz)\b/i;
+// A code: capitals then a number, such as M1, A1.7, US-3 or D-6. Common
+// technical names that look like codes are not codes.
+const CODE = /(?<![\w./-])[A-Z]{1,4}-?\d+(?:\.\d+)*(?![\w/-])/g;
+export const NOT_CODES = Object.freeze(new Set(['UTF-8', 'UTF-16', 'UTF8', 'SHA1', 'SHA256', 'SHA384', 'SHA512', 'MD5', 'S3', 'EC2', 'ARM64', 'X86', 'HTTP2', 'HTTP3', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'P50', 'P90', 'P95', 'P99', 'ES2020', 'ES2022', 'ISO8601', 'RFC3339', 'OAUTH2', 'IPV4', 'IPV6', 'PDF2', 'MP3', 'MP4', 'K8S']));
+// A state line, in three shapes: a status label with a state word
+// ("Status: approved", "**State** — locked"), a state word with a date
+// ("Approved 2026-10-09"), and a sentence that says the design is approved,
+// locked or shipped.
+const STATE_WORDS = 'draft|proposed|approved|locked|building|built|shipped|delivered|done|in progress|waiting(?: on [\\w ]+)?';
+const STATE_LINE = new RegExp([
+  `^(?:[-*]\\s+)?(?:\\*\\*)?(?:status|state|stage)(?:\\*\\*)?\\s*(?::|—|–|\\s-\\s)\\s*(?:\\*\\*)?\\s*(?:${STATE_WORDS})\\b`,
+  '^(?:\\*\\*)?(?:approved|locked|shipped|delivered)(?:\\*\\*)?\\s+(?:on\\s+)?\\d{4}-\\d{2}-\\d{2}',
+  '\\b(?:this|the)\\s+design\\s+(?:is|was|has been)\\s+(?:now\\s+)?(?:approved|locked|shipped|delivered)\\b',
+].join('|'), 'i');
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
+// HTML lets these close themselves, so the tag check skips them.
+const OPTIONAL_CLOSE = new Set(['li', 'p', 'td', 'th', 'tr', 'thead', 'tbody', 'tfoot', 'dt', 'dd', 'option', 'colgroup']);
+// A figure draws; it never reaches the network, and its style never reaches the page.
+const FIGURE_NETWORK = /\bfetch\s*\(|XMLHttpRequest|WebSocket|EventSource|sendBeacon|\bimport\s*\(|<(?:script|img|iframe|link)\b[^>]*\b(?:src|href)\s*=\s*["']?(?:https?:)?\/\//i;
+// Files a folder may hold beside its parts: an index, for a repo whose docs
+// lint needs every page linked, and a readme.
+export const INDEX_FILES = Object.freeze(['index.md', 'README.md']);
 
-// Code spans and links go first, so a dot in `atlas.yaml` or a URL never
-// ends a sentence. A sentence ends at . ! or ? before a space and a capital.
-export function sentenceCount(text) {
-  const plain = text
-    .replace(/`[^`]*`/g, ' Code ')
-    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
-    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
-    .replace(/\s+/g, ' ')
-    .trim();
-  if (!plain) return 0;
-  return plain.split(/(?<=[.!?])\s+(?=["“(]?[A-Z])/).filter((one) => /[A-Za-z0-9]/.test(one)).length;
+export function loadRegistry(path = PARTS_FILE) {
+  const data = parseYaml(readFileSync(path, 'utf8'));
+  const kinds = data.kinds.map((one) => one.id);
+  for (const part of data.parts) {
+    for (const kind of kinds) {
+      if (!NEEDS.includes(part[kind])) throw new Error(`${basename(path)}: part "${part.id}" has no valid "${kind}" value; use ${NEEDS.join(', ')}`);
+    }
+  }
+  return { ...data, kindIds: kinds, byId: new Map(data.parts.map((part) => [part.id, part])) };
 }
 
-// Prose lines only: not a list item, a table row, a quote or a code block.
-function proseOf(lines) {
-  const out = [];
-  let fenced = false;
-  for (const line of lines) {
-    if (/^```/.test(line.trim())) { fenced = !fenced; continue; }
-    if (fenced) continue;
-    const trimmed = line.trim();
-    if (!trimmed || /^([-*+]|\d+[.)])\s/.test(trimmed) || trimmed.startsWith('|') || trimmed.startsWith('>')) { out.push(''); continue; }
-    if (/^\s{2,}\S/.test(line) && out.length && out[out.length - 1] === '') { out.push(''); continue; }
-    out.push(trimmed);
+// What one design needs: each part id with "needed" or "optional", and the
+// kinds that need it. A part that two kinds use appears once.
+export function needsOf(meta, registry) {
+  const kinds = Array.isArray(meta.kinds) ? meta.kinds : [];
+  const out = new Map();
+  for (const part of registry.parts) {
+    let need = null;
+    const by = [];
+    for (const kind of kinds) {
+      let value = part[kind];
+      if (value === 'shared') value = meta.shared === true ? 'needed' : 'optional';
+      if (value === 'needed') { need = 'needed'; by.push(kind); }
+      else if (value === 'optional' && need !== 'needed') need = 'optional';
+    }
+    if (need) out.set(part.id, { need, by });
   }
   return out;
 }
 
-function paragraphs(lines) {
-  return proseOf(lines).join('\n').split(/\n\s*\n/).map((one) => one.trim()).filter(Boolean);
+export function frontMatter(source) {
+  const text = String(source).replace(/\r\n?/g, '\n');
+  const match = text.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) return { meta: {}, body: text, bodyLine: 1 };
+  return { meta: parseYaml(match[1]) ?? {}, body: text.slice(match[0].length), bodyLine: match[0].split('\n').length };
 }
 
-// Split the doc into level-2 sections, each with its start line and body.
-function sectionsOf(lines) {
-  const sections = [];
-  let current = null;
-  let fenced = false;
-  lines.forEach((line, index) => {
-    if (/^```/.test(line.trim())) fenced = !fenced;
-    if (!fenced && line.startsWith('## ')) {
-      current = { heading: line.slice(3).trim(), line: index + 1, body: [] };
-      sections.push(current);
-    } else if (current) current.body.push({ text: line, line: index + 1 });
+export function readDesign(folder) {
+  const root = resolve(folder);
+  if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`${folder} is not a folder. A design is a folder with ${DESIGN_FILE} and one file for each part.`);
+  const metaPath = join(root, DESIGN_FILE);
+  const meta = existsSync(metaPath) ? (parseYaml(readFileSync(metaPath, 'utf8')) ?? {}) : null;
+  const names = readdirSync(root).filter((name) => name.endsWith('.md')).sort();
+  const index = names.filter((name) => INDEX_FILES.includes(name)).map((name) => ({ file: name, text: readFileSync(join(root, name), 'utf8') }));
+  const parts = names.filter((name) => !INDEX_FILES.includes(name)).map((name) => {
+    const { meta: head, body, bodyLine } = frontMatter(readFileSync(join(root, name), 'utf8'));
+    return { file: name, head, part: head.part ?? null, title: head.title ?? null, body, bodyLine };
   });
-  return sections;
+  return { root, meta, parts, index };
 }
 
-function stepsOf(section) {
-  const steps = [];
-  let current = null;
-  let fenced = false;
-  for (const row of section.body) {
-    if (/^```/.test(row.text.trim())) fenced = !fenced;
-    const match = !fenced && row.text.match(STEP_LINE);
-    if (match) { current = { number: Number(match[1]), title: match[2], line: row.line, body: [] }; steps.push(current); continue; }
-    if (!fenced && row.text.startsWith('### ')) { current = null; continue; }
-    if (current) current.body.push(row);
-  }
-  return steps;
+// Lines outside code fences, with their line numbers; `figure` fences are
+// returned apart, so the check can read their tags.
+function scanLines(body, firstLine) {
+  const prose = [];
+  const figures = [];
+  let fence = null;
+  body.split('\n').forEach((text, index) => {
+    const line = firstLine + index;
+    const open = text.match(/^\s*```+\s*(\S*)(?:\s+(\S+))?/);
+    if (open && !fence) { fence = { info: open[1], type: open[2] ?? null, line, lines: [] }; return; }
+    if (fence && /^\s*```+\s*$/.test(text)) { if (fence.info === 'figure' || fence.info === 'woodcut') figures.push(fence); fence = null; return; }
+    if (fence) { fence.lines.push(text); return; }
+    prose.push({ text, line });
+  });
+  if (fence) figures.push({ ...fence, open: true });
+  return { prose, figures };
 }
 
-function checkStep(step, finding) {
-  const label = `step "${step.title}"`;
-  const exampleIndex = step.body.findIndex((row) => EXAMPLE_LINE.test(row.text.trim()));
-  if (exampleIndex === -1) finding(step.line, 'example', `${label} has no Example block`);
-  const before = (exampleIndex === -1 ? step.body : step.body.slice(0, exampleIndex)).map((row) => row.text);
-  const count = paragraphs(before).reduce((sum, one) => sum + sentenceCount(one), 0);
-  if (count > MAX_STEP_SENTENCES) finding(step.line, 'step-text', `${label} has ${count} sentences before its example; the limit is ${MAX_STEP_SENTENCES}`);
-  const pictures = step.body.filter((row) => PICTURE_LINE.test(row.text.trim()));
-  const sketched = pictures.some((row) => {
-    const sketch = row.text.trim().match(PICTURE_LINE)[1];
-    return /→|->/.test(sketch) && !/\bTBD\b/i.test(sketch);
-  });
-  const drawn = step.body.some((row) => DIAGRAM_FENCE.test(row.text.trim()) || /<svg[\s>]/i.test(row.text) || /!\[[^\]]*\]\([^)]+\)/.test(row.text));
-  if (!sketched && !drawn) {
-    const why = pictures.length ? 'its Picture line has no arrow (→), or says TBD' : 'it has no Picture line and no diagram block';
-    finding(step.line, 'picture', `${label} has no picture: ${why}`);
+const isEmpty = (body) => !body.replace(/<!--[\s\S]*?-->/g, '').split('\n').some((line) => line.trim() && !/^#{1,6}\s/.test(line.trim()));
+
+// Code spans, links and quotes are not checked for codes: a quote is the
+// owner's own words, and a link target is not text.
+function codesIn(text) {
+  if (/^\s*>/.test(text)) return [];
+  const plain = text.replace(/`[^`]*`/g, ' ').replace(/\]\([^)]*\)/g, ']').replace(/https?:\/\/\S+/g, ' ');
+  return plain.match(CODE) ?? [];
+}
+
+export function figureFault(html) {
+  const text = html.replace(/<!--[\s\S]*?-->/g, '');
+  if (/<style\b/i.test(text)) return 'a figure may not hold a <style> block: it would reach the whole page; use style attributes';
+  if (FIGURE_NETWORK.test(text)) return 'a figure may not reach the network: no fetch, no dynamic import and no remote src or href';
+  const scripts = text.match(/<script\b/gi)?.length ?? 0;
+  const closed = text.match(/<\/script>/gi)?.length ?? 0;
+  if (scripts !== closed) return 'a script block does not close';
+  const plain = text.replace(/<script\b[\s\S]*?<\/script>/gi, '');
+  const stack = [];
+  for (const match of plain.matchAll(/<(\/?)([a-zA-Z][\w:-]*)\b[^>]*?(\/?)>/g)) {
+    const [, closing, rawName, self] = match;
+    const name = rawName.toLowerCase();
+    if (self || VOID.has(name) || OPTIONAL_CLOSE.has(name)) continue;
+    if (!closing) { stack.push(name); continue; }
+    if (stack[stack.length - 1] !== name) return `</${name}> closes ${stack.length ? `<${stack[stack.length - 1]}>` : 'nothing'}`;
+    stack.pop();
   }
+  return stack.length ? `<${stack[stack.length - 1]}> does not close` : null;
 }
 
-export function checkDesign(text) {
+export function checkDesign(design, registry = loadRegistry()) {
   const findings = [];
-  const finding = (line, rule, why) => findings.push({ line, rule, why });
-  const lines = String(text).split(/\r?\n/);
-  const sections = sectionsOf(lines);
-  const named = (name) => sections.find((section) => section.heading.toLowerCase() === name.toLowerCase());
-
-  const summary = named('Summary');
-  if (!summary) finding(1, 'summary', 'the doc has no "## Summary" section');
-  else {
-    const count = paragraphs(summary.body.map((row) => row.text)).length;
-    if (count === 0) finding(summary.line, 'summary', 'the Summary is empty');
-    if (count > MAX_SUMMARY_PARAGRAPHS) finding(summary.line, 'summary', `the Summary has ${count} paragraphs; the limit is ${MAX_SUMMARY_PARAGRAPHS}`);
+  const finding = (file, line, rule, why) => findings.push({ file, line, rule, why });
+  const { meta } = design;
+  if (!meta) {
+    finding(DESIGN_FILE, 1, 'design-yaml', `the folder has no ${DESIGN_FILE}; it names the title and the kinds`);
+    return findings;
   }
-
-  const parts = sections.map((section) => ({ section, match: section.heading.match(/^Part (\d+) [—–-] (.+?)\s*$/) })).filter((one) => one.match);
-  for (const name of PARTS) {
-    const part = parts.find((one) => one.match[2].toLowerCase() === name.toLowerCase());
-    if (!part) { finding(1, 'part', `the doc has no part "${name}" (a line "## Part N — ${name}")`); continue; }
-    const steps = stepsOf(part.section);
-    if (!steps.length) finding(part.section.line, 'part', `part "${name}" has no "### Step N — <title>" line`);
-    for (const step of steps) checkStep(step, finding);
+  if (!meta.title) finding(DESIGN_FILE, 1, 'design-yaml', 'design.yaml has no title');
+  for (const key of Object.keys(meta)) {
+    if (STATE_KEYS.includes(key.toLowerCase())) finding(DESIGN_FILE, 1, 'state', `design.yaml has "${key}"; state lives in the tracker`);
+    else if (!DESIGN_KEYS.includes(key)) finding(DESIGN_FILE, 1, 'design-yaml', `design.yaml has an unknown key "${key}"; the keys are ${DESIGN_KEYS.join(', ')}`);
   }
-
-  for (const name of REQUIRED_SECTIONS) {
-    if (!named(name)) finding(1, 'section', `the doc has no "## ${name}" section`);
+  const kinds = Array.isArray(meta.kinds) ? meta.kinds : [];
+  if (!kinds.length) finding(DESIGN_FILE, 1, 'kind', `design.yaml names no kinds; pick one or more of ${registry.kindIds.join(', ')}`);
+  for (const kind of kinds) {
+    if (!registry.kindIds.includes(kind)) finding(DESIGN_FILE, 1, 'kind', `"${kind}" is not a kind; the kinds are ${registry.kindIds.join(', ')}`);
   }
 
-  const reference = parts.find((one) => one.match[2].toLowerCase() === REFERENCE.name.toLowerCase());
-  if (!reference) finding(1, 'reference', `the doc has no part "${REFERENCE.name}" (a line "## Part N — ${REFERENCE.name}")`);
-  else {
-    const headings = reference.section.body.filter((row) => row.text.startsWith('### ')).map((row) => row.text.slice(4).trim().toLowerCase());
-    for (const name of REFERENCE.sections) {
-      if (!headings.includes(name.toLowerCase())) finding(reference.section.line, 'reference', `the Reference part has no "### ${name}"`);
+  const needs = needsOf(meta, registry);
+  const seen = new Map();
+  const keyText = [];
+  const codes = [];
+  for (const one of design.parts) {
+    if (!one.part) { finding(one.file, 1, 'unknown-part', `${one.file} has no "part:" line in its front matter`); continue; }
+    for (const key of Object.keys(one.head)) {
+      if (STATE_KEYS.includes(key.toLowerCase())) finding(one.file, 1, 'state', `the front matter has "${key}"; state lives in the tracker`);
+      else if (!PART_KEYS.includes(key)) finding(one.file, 1, 'unknown-part', `the front matter has an unknown key "${key}"; the keys are ${PART_KEYS.join(', ')}`);
+    }
+    if (!registry.byId.has(one.part)) {
+      const tracker = registry.tracker.some((row) => row.id === one.part);
+      finding(one.file, 1, tracker ? 'state' : 'unknown-part', tracker
+        ? `"${one.part}" is read from the tracker; a design keeps no copy of it`
+        : `"${one.part}" is not a part in parts.yaml`);
+      continue;
+    }
+    if (seen.has(one.part)) { finding(one.file, 1, 'duplicate', `part "${one.part}" is also in ${seen.get(one.part)}`); continue; }
+    seen.set(one.part, one.file);
+    if (!needs.has(one.part)) finding(one.file, 1, 'unknown-part', `part "${one.part}" is not used by the kinds ${kinds.join(', ') || '(none)'}`);
+    if (isEmpty(one.body)) finding(one.file, one.bodyLine, 'empty', `part "${one.part}" is empty; write what it holds, or "No change" and why`);
+    const { prose, figures } = scanLines(one.body, one.bodyLine);
+    for (const row of prose) {
+      const trimmed = row.text.trim();
+      if (!trimmed.startsWith('|') && !trimmed.startsWith('>') && STATE_LINE.test(trimmed)) {
+        finding(one.file, row.line, 'state', `"${trimmed.slice(0, 60)}" is a state line; state lives in the tracker`);
+      }
+      if (one.part === 'key') keyText.push(row.text);
+      else for (const code of codesIn(row.text)) codes.push({ code, file: one.file, line: row.line });
+    }
+    for (const figure of figures) {
+      let fault = figure.open ? 'the figure block does not close' : null;
+      if (!fault && figure.info === 'woodcut') {
+        if (!/^wc-[a-z-]+$/.test(figure.type ?? '')) fault = 'a woodcut block names its figure type, such as "woodcut wc-flowchart"';
+        else { try { JSON.parse(figure.lines.join('\n')); } catch (error) { fault = `the woodcut data is not JSON: ${error.message}`; } }
+      } else if (!fault) fault = figureFault(figure.lines.join('\n'));
+      if (fault) finding(one.file, figure.line, 'figure', fault);
     }
   }
-
-  return findings.sort((a, b) => a.line - b.line);
+  for (const [id, { need, by }] of needs) {
+    if (need === 'needed' && !seen.has(id)) {
+      const part = registry.byId.get(id);
+      const shared = by.some((kind) => part[kind] === 'shared') ? ', because the design is shared' : '';
+      finding(DESIGN_FILE, 1, 'missing', `the design has no part "${id}" (${part.name}), needed by ${by.join(', ')}${shared}`);
+    }
+  }
+  const key = keyText.join('\n');
+  const reported = new Set();
+  for (const { code, file, line } of codes) {
+    if (NOT_CODES.has(code.toUpperCase()) || reported.has(code) || new RegExp(`(?<![\\w-])${code.replace(/\./g, '\\.')}(?![\\w-])`).test(key)) continue;
+    reported.add(code);
+    finding(file, line, 'key', `the code "${code}" has no row in the Key`);
+  }
+  for (const one of design.index ?? []) {
+    for (const part of design.parts) {
+      if (!one.text.includes(`(${part.file})`) && !one.text.includes(`(./${part.file})`)) finding(one.file, 1, 'index', `${one.file} does not link ${part.file}`);
+    }
+  }
+  const order = (one) => (one.file === DESIGN_FILE ? '' : one.file);
+  return findings.sort((a, b) => order(a).localeCompare(order(b)) || a.line - b.line);
 }
 
-export function checkDesignFile(path) {
-  return checkDesign(readFileSync(path, 'utf8'));
+export function checkDesignFolder(folder, registry) {
+  return checkDesign(readDesign(folder), registry);
 }

package/door/lib/markdown.mjs

@@ -0,0 +1,160 @@
+// A small markdown renderer for design pages. It grew from the renderer of
+// the dev-team manual, docs/manual/build.mjs, and reads the same blocks:
+// headings, paragraphs, lists, tables, quotes, code, and woodcut figures.
+// It adds one block: a fence whose info string is `figure` holds the HTML of
+// a custom figure, and goes into the page as it is.
+//
+// No dependencies. The text is the repo's own; a custom figure is trusted
+// the same way a page in the repo is.
+export const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export const slug = (text) => String(text).toLowerCase().replace(/<[^>]+>/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+// ctx: { page, link(href) -> { href, part } | null, figures: [] }
+export function inline(text, ctx) {
+  const codes = [];
+  let s = text.replace(/`([^`]+)`/g, (_, code) => {
+    codes.push(`<code>${esc(code)}</code>`);
+    return `\u0000${codes.length - 1}\u0000`;
+  });
+  s = esc(s);
+  s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label, href) => link(label, href.replace(/&amp;/g, '&'), ctx));
+  s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  s = s.replace(/(^|[\s(])\*([^*\s][^*]*)\*/g, '$1<em>$2</em>');
+  s = s.replace(/(^|[\s(])_([^_\s][^_]*)_(?=[\s).,;:]|$)/g, '$1<em>$2</em>');
+  return s.replace(/\u0000(\d+)\u0000/g, (_, index) => codes[index]);
+}
+
+function link(label, href, ctx) {
+  if (/^https?:/.test(href)) return `<a href="${esc(href)}" target="_blank" rel="noopener">${label}</a>`;
+  const part = ctx.partOf ? ctx.partOf(href) : null;
+  if (part) return `<a href="#${esc(part)}" data-part="${esc(part)}">${label}</a>`;
+  if (href.startsWith('#')) return `<a href="${esc(href)}">${label}</a>`;
+  // A repo file: show it as a path, not a live link.
+  return `<span class="path" title="${esc(href)}">${label}</span>`;
+}
+
+const cellsOf = (row) => {
+  const s = row.trim().replace(/^\|/, '').replace(/\|$/, '');
+  const out = [''];
+  let inCode = false;
+  for (let k = 0; k < s.length; k += 1) {
+    const ch = s[k];
+    if (ch === '\\' && s[k + 1] === '|') { out[out.length - 1] += '|'; k += 1; continue; }
+    if (ch === '`') inCode = !inCode;
+    if (ch === '|' && !inCode) { out.push(''); continue; }
+    out[out.length - 1] += ch;
+  }
+  return out.map((cell) => cell.trim());
+};
+
+export function render(body, ctx) {
+  const lines = body.replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  const para = [];
+  let title = null;
+  let i = 0;
+  const flush = () => {
+    if (!para.length) return;
+    out.push(`<p>${inline(para.join(' ').trim(), ctx)}</p>`);
+    para.length = 0;
+  };
+  while (i < lines.length) {
+    const line = lines[i];
+    const fence = line.match(/^\s*```+\s*(.*)$/);
+    if (fence) {
+      flush();
+      const info = fence[1].trim();
+      const buf = [];
+      i += 1;
+      while (i < lines.length && !/^\s*```+\s*$/.test(lines[i])) buf.push(lines[i++]);
+      i += 1;
+      const woodcut = info.match(/^woodcut\s+(wc-[a-z-]+)/);
+      if (woodcut) {
+        let data;
+        try { data = JSON.parse(buf.join('\n')); } catch (error) { throw new Error(`${ctx.file}: bad woodcut JSON in ${woodcut[1]}: ${error.message}`); }
+        ctx.figures.push(woodcut[1]);
+        out.push(`<figure class="fig"><${woodcut[1]}><script type="application/json">${JSON.stringify(data).replace(/<\//g, '<\\/')}</script></${woodcut[1]}></figure>`);
+      } else if (info === 'figure') {
+        ctx.figures.push('custom');
+        out.push(`<figure class="fig custom">${buf.join('\n')}</figure>`);
+      } else {
+        out.push(`<pre class="code"${info ? ` data-lang="${esc(info)}"` : ''}><code>${esc(buf.join('\n'))}</code></pre>`);
+      }
+      continue;
+    }
+    const heading = line.match(/^(#{1,4})\s+(.*)$/);
+    if (heading) {
+      flush();
+      const level = heading[1].length;
+      const text = heading[2].trim();
+      i += 1;
+      // The first level-one heading is the part's title; the page draws it.
+      if (level === 1 && title === null && !out.length) { title = text; continue; }
+      const tag = Math.min(level + 1, 4);
+      out.push(`<h${tag} id="${esc(`${ctx.page}--${slug(text)}`)}">${inline(text, ctx)}</h${tag}>`);
+      continue;
+    }
+    if (/^\s*>/.test(line)) {
+      flush();
+      const buf = [];
+      while (i < lines.length && /^\s*>/.test(lines[i])) buf.push(lines[i++].replace(/^\s*>\s?/, ''));
+      out.push(`<blockquote>${render(buf.join('\n'), { ...ctx, page: `${ctx.page}-q` }).html}</blockquote>`);
+      continue;
+    }
+    if (/^\s*\|/.test(line) && i + 1 < lines.length && /^\s*\|?\s*:?-{2,}/.test(lines[i + 1])) {
+      flush();
+      const head = cellsOf(line);
+      i += 2;
+      const rows = [];
+      while (i < lines.length && /^\s*\|/.test(lines[i])) rows.push(cellsOf(lines[i++]));
+      out.push(`<div class="tablewrap"><table><thead><tr>${head.map((cell) => `<th>${inline(cell, ctx)}</th>`).join('')}</tr></thead><tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${inline(cell, ctx)}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`);
+      continue;
+    }
+    if (/^\s*([-*]|\d+\.)\s+/.test(line)) {
+      flush();
+      const result = list(lines, i, ctx);
+      out.push(result.html);
+      i = result.next;
+      continue;
+    }
+    if (/^\s*$/.test(line)) { flush(); i += 1; continue; }
+    para.push(line.trim());
+    i += 1;
+  }
+  flush();
+  return { title, html: out.join('\n') };
+}
+
+function list(lines, start, ctx) {
+  const indentOf = (line) => line.match(/^(\s*)/)[1].length;
+  const base = indentOf(lines[start]);
+  const ordered = /^\s*\d+\./.test(lines[start]);
+  const items = [];
+  let i = start;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (/^\s*$/.test(line)) {
+      const next = lines[i + 1];
+      if (next !== undefined && indentOf(next) >= base && /^\s*([-*]|\d+\.)\s+/.test(next)) { i += 1; continue; }
+      if (next !== undefined && indentOf(next) > base) { i += 1; continue; }
+      break;
+    }
+    const indent = indentOf(line);
+    const match = line.match(/^\s*([-*]|\d+\.)\s+(.*)$/);
+    if (match && indent === base) { items.push({ text: [match[2]], sub: [] }); i += 1; continue; }
+    if (indent > base && items.length) {
+      if (/^\s*([-*]|\d+\.)\s+/.test(line)) {
+        const result = list(lines, i, ctx);
+        items[items.length - 1].sub.push(result.html);
+        i = result.next;
+        continue;
+      }
+      items[items.length - 1].text.push(line.trim());
+      i += 1;
+      continue;
+    }
+    break;
+  }
+  const tag = ordered ? 'ol' : 'ul';
+  return { html: `<${tag}>${items.map((item) => `<li>${inline(item.text.join(' '), ctx)}${item.sub.join('')}</li>`).join('')}</${tag}>`, next: i };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "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 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. `proof` prints the proof table of one run |
-| `atlas design` | Before you render a design doc made from the walkthrough template |
+| `atlas design` | `check` before you show a design; `build` to make its page |
 
 A person merges every file that `atlas tooling` writes.
 A person merges every file that `atlas tests write` writes.