arcshape 0.0.0-stage → 0.1.0

package/tools/arc42-site/generate.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * generate.mjs — arc42 snapshot generator (portable, bundled with the architecture-docs skill).
+ *
+ * Usage:
+ *   node generate.mjs <docsDir> [--out <file>] [--title <name>] [--source-ref <ref>]
+ *
+ * Reads an arc42 documentation folder (README.md + NN-*.md sections with the
+ * architecture-docs skill's frontmatter contract) and writes exactly one
+ * self-contained HTML file: inline styles, inline pre-rendered Mermaid SVGs,
+ * inert JSON data, one ES5 router. No external resources; opens from file://.
+ * Generation is deterministic and never modifies authored files.
+ *
+ * Default output: <docsDir>/../arc42-snapshot.html  (sibling of the docs folder)
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { resolve, join, dirname, relative, sep } from "node:path";
+import { loadDocs, Diagnostic } from "./loadDocs.mjs";
+import {
+  renderMarkdown,
+  extractMermaidSources,
+  renderMermaid,
+} from "./render.mjs";
+import { buildSnapshotHtml } from "./shell.mjs";
+
+const run = promisify(execFile);
+const generatedMarker =
+  "<!-- Generated by ArcShape from canonical Markdown. -->";
+
+function usage(code = 1) {
+  process.stdout.write(
+    [
+      "Usage: node generate.mjs <docsDir> [--out <file>] [--title <name>] [--source-ref <ref>]",
+      "",
+      "  docsDir   folder containing README.md and NN-*.md arc42 sections",
+      "  --out     output HTML path (default: <docsDir>/../arc42-snapshot.html)",
+      "  --title   page title override (default: derived from docsDir parent folder)",
+      "  --source-ref  Git branch, tag, or ref for repository source links (default: current branch)",
+      "",
+    ].join("\n"),
+  );
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--out" || arg === "--title" || arg === "--source-ref") {
+      if (!argv[i + 1] || argv[i + 1].startsWith("--")) usage(1);
+      flags[arg.slice(2)] = argv[i + 1];
+      i += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      usage(0);
+    } else if (arg.startsWith("-")) {
+      usage(1);
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
+}
+
+/** Best-effort git revision of the repository containing docsDir. */
+async function gitRevision(docsDir) {
+  try {
+    const { stdout } = await run("git", ["rev-parse", "HEAD"], {
+      cwd: docsDir,
+    });
+    return stdout.trim();
+  } catch {
+    return undefined;
+  }
+}
+
+async function gitSourceContext(docsDir, sourceRefOverride) {
+  try {
+    const [root, remote, ref] = await Promise.all([
+      run("git", ["rev-parse", "--show-toplevel"], { cwd: docsDir }),
+      run("git", ["remote", "get-url", "origin"], { cwd: docsDir }),
+      run("git", ["branch", "--show-current"], { cwd: docsDir }),
+    ]);
+    const repositoryUrl = githubRepositoryUrl(remote.stdout.trim());
+    return repositoryUrl
+      ? {
+          root: root.stdout.trim(),
+          repositoryUrl,
+          ref: sourceRefOverride || ref.stdout.trim() || "HEAD",
+        }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function githubRepositoryUrl(remote) {
+  const match =
+    /^(?:https:\/\/github\.com\/|git@github\.com:)([^/]+\/[^/]+?)(?:\.git)?$/.exec(
+      remote,
+    );
+  return match ? `https://github.com/${match[1]}` : undefined;
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (positional.length !== 1) usage(1);
+  const docsDir = resolve(positional[0]);
+
+  let docs;
+  try {
+    docs = await loadDocs(docsDir);
+  } catch (error) {
+    if (error instanceof Diagnostic) {
+      process.stderr.write(`arc42-snapshot: ${error.message}\n`);
+      process.exit(2);
+    }
+    throw error;
+  }
+
+  const stackName = flags.title ?? docs.stackName;
+  const outFile = flags.out
+    ? resolve(flags.out)
+    : join(dirname(docsDir), "arc42-snapshot.html");
+  if (!/\.html?$/i.test(outFile)) {
+    throw new Diagnostic(
+      "--out must name an .html or .htm file; authored Markdown is never an output target",
+    );
+  }
+
+  // Route map: section file names and README.md -> hash routes.
+  const fileToRoute = new Map(
+    docs.sections.map((s) => [s.file, `#/section/${s.number}`]),
+  );
+  fileToRoute.set(docs.readme.file, "#/");
+
+  // Pre-render every mermaid diagram across all documents in one batch.
+  const readmeMermaid = extractMermaidSources(docs.readme.body);
+  const sectionMermaid = docs.sections.map((s) =>
+    extractMermaidSources(s.body),
+  );
+  const allMermaid = [...readmeMermaid, ...sectionMermaid.flat()];
+  process.stdout.write(
+    `arc42-snapshot: ${docs.sections.length} sections, ${allMermaid.length} mermaid diagram(s)\n`,
+  );
+  const svgs = await renderMermaid(allMermaid);
+
+  // Distribute the rendered SVGs back to their documents.
+  let cursor = 0;
+  const take = (count) => {
+    const slice = svgs.slice(cursor, cursor + count);
+    cursor += count;
+    return slice;
+  };
+
+  const sourceContext = await gitSourceContext(docsDir, flags["source-ref"]);
+  const toSourcePath = (file) =>
+    sourceContext
+      ? relative(sourceContext.root, join(docsDir, file)).split(sep).join("/")
+      : undefined;
+
+  const readmeRendered = await renderMarkdown(docs.readme.body, {
+    fileToRoute,
+    svgs: take(readmeMermaid.length),
+    title: docs.readme.title,
+    sourceContext,
+    sourceFile: toSourcePath(docs.readme.file),
+  });
+  const sectionsRendered = [];
+  for (let i = 0; i < docs.sections.length; i += 1) {
+    const section = docs.sections[i];
+    const rendered = await renderMarkdown(section.body, {
+      fileToRoute,
+      svgs: take(sectionMermaid[i].length),
+      currentRoute: `#/section/${section.number}`,
+      title: section.title,
+      sourceContext,
+      sourceFile: toSourcePath(section.file),
+    });
+    sectionsRendered.push({
+      number: section.number,
+      title: section.title,
+      description: section.description,
+      html: rendered.html,
+    });
+  }
+
+  const revision = await gitRevision(docsDir);
+  const html = `${generatedMarker}\n${buildSnapshotHtml({
+    readme: {
+      title: docs.readme.title,
+      description: docs.readme.description,
+      html: readmeRendered.html,
+    },
+    sections: sectionsRendered,
+    stackName,
+    revision,
+  })}`;
+
+  await mkdir(dirname(outFile), { recursive: true });
+  try {
+    const existing = await readFile(outFile, "utf8");
+    if (existing === html) {
+      process.stdout.write(
+        `arc42-snapshot: site is already up to date at ${outFile}\n`,
+      );
+      return;
+    }
+    if (!existing.includes(generatedMarker)) {
+      throw new Diagnostic(
+        `output already exists and is not an ArcShape-generated site: ${outFile}; choose another --out path or move the file`,
+      );
+    }
+  } catch (error) {
+    if (error instanceof Diagnostic) throw error;
+    if (error.code !== "ENOENT") throw error;
+  }
+  await writeFile(outFile, html, "utf8");
+  process.stdout.write(`arc42-snapshot: snapshot written to ${outFile}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`arc42-snapshot: ${error.stack ?? error.message}\n`);
+  process.exit(error instanceof Diagnostic ? 2 : 1);
+});

package/tools/arc42-site/loadDocs.mjs

@@ -0,0 +1,196 @@
+/**
+ * loadDocs.mjs — scan an arc42 documentation folder, validate the document contract
+ * and parse every section. Mirrors productshape's "honest diagnostics" principle:
+ * a broken model fails generation rather than producing a page that silently
+ * omits part of the documentation.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join, basename, dirname } from "node:path";
+import * as yaml from "js-yaml";
+
+const ALLOWED_KEYS = new Set(["title", "arc42-section", "description"]);
+const SECTION_FILE = /^(\d{2})-(.+)\.md$/;
+const SECTION_NUMBERS = Array.from({ length: 12 }, (_, index) =>
+  String(index + 1).padStart(2, "0"),
+);
+
+export class Diagnostic extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "Diagnostic";
+  }
+}
+
+/**
+ * Parse the `---\nkey: value\n---` frontmatter block of a Markdown file.
+ * Returns { frontmatter, body } or throws a Diagnostic naming the file.
+ */
+export function parseFrontmatter(raw, fileName) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+  if (!match) {
+    throw new Diagnostic(`${fileName}: missing YAML frontmatter block`);
+  }
+  let frontmatter;
+  try {
+    frontmatter = yaml.load(match[1], { schema: yaml.JSON_SCHEMA }) ?? {};
+  } catch (error) {
+    throw new Diagnostic(
+      `${fileName}: unparseable frontmatter: ${error.message}`,
+    );
+  }
+  if (typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+    throw new Diagnostic(`${fileName}: frontmatter must be a mapping`);
+  }
+  return { frontmatter, body: match[2] };
+}
+
+/**
+ * Load and validate an arc42 docs folder.
+ *
+ * Contract (from the architecture-docs skill):
+ *  - README.md exists, optionally has title/description, never `arc42-section`.
+ *  - Section files are named NN-slug.md with zero-padded numbers.
+ *  - Each has exactly the keys: title, arc42-section, description.
+ *  - arc42-section values are unique and match the file number.
+ *
+ * @param {string} docsDir absolute path to the docs/architecture folder
+ * @returns {{ readme: object, sections: object[], stackName: string }}
+ */
+export async function loadDocs(docsDir) {
+  const entries = await readdir(docsDir, { withFileTypes: true });
+  const mdFiles = entries
+    .filter((entry) => entry.isFile() && /\.md$/i.test(entry.name))
+    .map((e) => e.name)
+    .sort();
+
+  const readmeName = mdFiles.find((n) => n.toLowerCase() === "readme.md");
+  if (!readmeName) {
+    throw new Diagnostic(
+      `${docsDir}: no README.md found — the navigation index is required`,
+    );
+  }
+
+  const sectionFiles = mdFiles.filter((n) => SECTION_FILE.test(n));
+  if (sectionFiles.length === 0) {
+    throw new Diagnostic(`${docsDir}: no NN-*.md section files found`);
+  }
+
+  const problems = mdFiles
+    .filter((name) => name !== readmeName && !SECTION_FILE.test(name))
+    .map(
+      (name) =>
+        `${name}: unexpected Markdown file; name an arc42 section NN-slug.md or move supporting material into a subdirectory`,
+    );
+  const sections = [];
+  const seenNumbers = new Map();
+
+  // --- README: navigation index, never a section itself.
+  const readmeRaw = await readFile(join(docsDir, readmeName), "utf8");
+  const readmeParsed = /^---\r?\n/.test(readmeRaw)
+    ? parseFrontmatter(readmeRaw, readmeName)
+    : { frontmatter: {}, body: readmeRaw };
+  for (const key of Object.keys(readmeParsed.frontmatter)) {
+    if (key === "arc42-section") {
+      problems.push(
+        `${readmeName}: README must not carry arc42-section (it is navigation, not a section)`,
+      );
+    } else if (!["title", "description"].includes(key)) {
+      problems.push(`${readmeName}: unexpected frontmatter key "${key}"`);
+    }
+  }
+  for (const key of ["title", "description"]) {
+    if (
+      key in readmeParsed.frontmatter &&
+      (typeof readmeParsed.frontmatter[key] !== "string" ||
+        !readmeParsed.frontmatter[key].trim())
+    ) {
+      problems.push(
+        `${readmeName}: ${key} must be a nonempty string when present`,
+      );
+    }
+  }
+
+  // --- Sections.
+  for (const name of sectionFiles) {
+    const number = SECTION_FILE.exec(name)[1];
+    const raw = await readFile(join(docsDir, name), "utf8");
+    let parsed;
+    try {
+      parsed = parseFrontmatter(raw, name);
+    } catch (error) {
+      problems.push(error.message);
+      continue;
+    }
+    const fm = parsed.frontmatter;
+    for (const key of Object.keys(fm)) {
+      if (!ALLOWED_KEYS.has(key)) {
+        problems.push(`${name}: unexpected frontmatter key "${key}"`);
+      }
+    }
+    for (const key of ["title", "arc42-section", "description"]) {
+      if (!(key in fm)) {
+        problems.push(`${name}: missing required frontmatter key "${key}"`);
+      } else if (typeof fm[key] !== "string" || !fm[key].trim()) {
+        problems.push(`${name}: ${key} must be a nonempty string`);
+      }
+    }
+    if (!SECTION_NUMBERS.includes(number)) {
+      problems.push(`${name}: section number must be between 01 and 12`);
+    }
+    if (fm["arc42-section"] !== undefined && fm["arc42-section"] !== number) {
+      problems.push(
+        `${name}: arc42-section "${fm["arc42-section"]}" does not match file number ${number}`,
+      );
+    }
+    if (seenNumbers.has(number)) {
+      problems.push(
+        `${name}: duplicate section number ${number} (also ${seenNumbers.get(number)})`,
+      );
+    }
+    seenNumbers.set(number, name);
+
+    sections.push({
+      number,
+      slug: SECTION_FILE.exec(name)[2],
+      file: name,
+      title: String(fm.title ?? name),
+      description: String(fm.description ?? ""),
+      body: parsed.body,
+    });
+  }
+
+  for (const number of SECTION_NUMBERS) {
+    if (!seenNumbers.has(number))
+      problems.push(`required arc42 section ${number} is missing`);
+  }
+
+  if (problems.length > 0) {
+    const error = new Diagnostic(
+      `arc42 document contract violations:\n  - ${problems.join("\n  - ")}`,
+    );
+    error.problems = problems;
+    throw error;
+  }
+
+  sections.sort((a, b) => a.number.localeCompare(b.number));
+
+  // Derive a name from the docsDir's parent (e.g. .../my-project/docs/architecture → "my-project").
+  // Falls back to the docsDir folder name itself if there is no meaningful parent.
+  const parent = basename(dirname(docsDir));
+  const grandparent = basename(dirname(dirname(docsDir)));
+  const stackName =
+    parent === "docs" ? grandparent : parent || basename(docsDir);
+
+  return {
+    readme: {
+      file: readmeName,
+      title: String(
+        readmeParsed.frontmatter.title ?? "Architecture Documentation",
+      ),
+      description: String(readmeParsed.frontmatter.description ?? ""),
+      body: readmeParsed.body,
+    },
+    sections,
+    stackName,
+  };
+}