arcshape 0.0.0-stage → 0.1.0

package/bin/site.mjs

@@ -0,0 +1,59 @@
+import { spawnSync } from "node:child_process";
+import { resolve, join } from "node:path";
+
+export async function runSite(args, { packageRoot }) {
+  const options = parseOptions(args);
+  if (options.help) {
+    process.stdout.write(
+      "Usage: arcshape site build [--docs <directory>] [--out <html-file>] [--title <name>] [--source-ref <ref>]\n\n",
+    );
+    process.stdout.write(
+      "Build a self-contained reader site from the canonical architecture Markdown.\n",
+    );
+    return { exitCode: 0 };
+  }
+  if (options.command !== "build") {
+    throw new Error("expected `arcshape site build`; use --help for options");
+  }
+
+  const docsDir = resolve(process.cwd(), options.docs ?? "docs/architecture");
+  const outFile = resolve(
+    process.cwd(),
+    options.out ?? "docs/architecture-site/index.html",
+  );
+  const generator = join(packageRoot, "tools", "arc42-site", "generate.mjs");
+  const argv = [generator, docsDir, "--out", outFile];
+  if (options.title) argv.push("--title", options.title);
+  if (options.sourceRef) argv.push("--source-ref", options.sourceRef);
+  const result = spawnSync(process.execPath, argv, { stdio: "inherit" });
+  if (result.error) throw result.error;
+  return { exitCode: result.status ?? 1 };
+}
+
+function parseOptions(args) {
+  const options = { help: false };
+  let index = 0;
+  if (args[0] === "build") {
+    options.command = "build";
+    index = 1;
+  } else if (args[0] === "--help" || args[0] === "-h") options.help = true;
+  else if (args[0] !== undefined) {
+    options.command = args[0];
+    index = 1;
+  }
+  for (; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (["--docs", "--out", "--title", "--source-ref"].includes(arg)) {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--"))
+        throw new Error(`${arg} requires a value`);
+      if (arg === "--docs") options.docs = value;
+      if (arg === "--out") options.out = value;
+      if (arg === "--title") options.title = value;
+      if (arg === "--source-ref") options.sourceRef = value;
+      index += 1;
+    } else throw new Error(`unknown site option: ${arg}`);
+  }
+  return options;
+}

package/bin/sync.mjs

@@ -0,0 +1,352 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import {
+  dirname,
+  isAbsolute,
+  join,
+  parse,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+import { runConfluenceSync } from "./confluence.mjs";
+import { syncConfluencePages } from "./confluence-pages.mjs";
+
+const MANIFEST_NAME = ".arcshape-sync.json";
+
+export async function runSync(args) {
+  const [provider, ...providerArgs] = args;
+  if (provider === "--help" || provider === "-h" || provider === undefined) {
+    printHelp();
+    return { exitCode: 0 };
+  }
+  if (provider === "confluence") {
+    const options = parseConfluenceOptions(providerArgs);
+    if (options.help) {
+      printHelp();
+      return { exitCode: 0 };
+    }
+    if (options.spaceId || options.parentId || options.titlePrefix) {
+      if (options.pageId)
+        throw new Error(
+          "use either --page-id or the multi-page --space-id/--parent-id destination",
+        );
+      return syncConfluencePages(options);
+    }
+    return runConfluenceSync(options);
+  }
+  if (provider !== "obsidian")
+    throw new Error("supported sync providers: obsidian, confluence");
+
+  const options = parseOptions(providerArgs);
+  if (options.help) {
+    printHelp();
+    return { exitCode: 0 };
+  }
+  if (!options.vault) throw new Error("sync obsidian requires --vault <path>");
+
+  const repository = resolve(process.cwd());
+  const docsRoot = resolve(repository, options.docs ?? "docs/architecture");
+  const vaultRoot = resolve(repository, options.vault);
+  const relativeTarget = options.path ?? `Architecture/${basename(repository)}`;
+  const targetRoot = resolve(vaultRoot, relativeTarget);
+  if (!isInside(vaultRoot, targetRoot) || targetRoot === vaultRoot)
+    throw new Error("--path must select a child directory inside the vault");
+  if (!(await isDirectory(vaultRoot)))
+    throw new Error(`Obsidian vault directory does not exist: ${vaultRoot}`);
+  if (await hasSymlink(vaultRoot, targetRoot))
+    throw new Error("Obsidian target path contains a symbolic link");
+
+  const includeRoots = await Promise.all(
+    (options.include ?? []).map(async (include) => {
+      const path = resolve(repository, include);
+      if (!isInside(repository, path))
+        throw new Error(
+          `--include must stay inside the repository: ${include}`,
+        );
+      if (await isSymlink(path))
+        throw new Error(`--include path cannot be a symbolic link: ${include}`);
+      if (!(await isDirectory(path)))
+        throw new Error(
+          `--include must select a Markdown directory: ${include}`,
+        );
+      return path;
+    }),
+  );
+  const sourceRoots = [docsRoot, ...includeRoots];
+  const contentByPath = new Map();
+  const commonRoot = commonAncestor(sourceRoots);
+  for (const sourceRoot of sourceRoots) {
+    for (const file of await collectMarkdown(sourceRoot)) {
+      const absolutePath = join(sourceRoot, file.path);
+      const path = relative(commonRoot, absolutePath).split(sep).join("/");
+      contentByPath.set(path, file.content);
+    }
+  }
+  const sourceFiles = [...contentByPath].map(([path, content]) => ({
+    path,
+    content,
+  }));
+  if (sourceFiles.length === 0)
+    throw new Error(`no Markdown files found under ${docsRoot}`);
+  const manifestPath = join(targetRoot, MANIFEST_NAME);
+  if (await isSymlink(manifestPath))
+    throw new Error(
+      `refusing to read a symbolic-link manifest: ${manifestPath}`,
+    );
+  const manifest = await readManifest(manifestPath);
+  const nextManifest = { version: 1, files: { ...manifest.files } };
+  const created = [];
+  const updated = [];
+  const unchanged = [];
+  const conflicts = [];
+  const seenSourcePaths = new Set();
+
+  for (const source of sourceFiles) {
+    seenSourcePaths.add(source.path);
+    const destination = resolve(targetRoot, source.path);
+    if (!isInside(targetRoot, destination)) {
+      conflicts.push({ path: source.path, reason: "resolved outside target" });
+      continue;
+    }
+    if (await hasSymlink(targetRoot, destination)) {
+      conflicts.push({
+        path: source.path,
+        reason: "target path is a symbolic link",
+      });
+      continue;
+    }
+
+    const sourceDigest = digest(source.content);
+    const previousDigest = manifest.files[source.path];
+    let destinationContent;
+    try {
+      destinationContent = await readFile(destination);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+
+    if (destinationContent === undefined) {
+      if (!options.dryRun) {
+        await mkdir(dirname(destination), { recursive: true });
+        try {
+          await writeFile(destination, source.content, { flag: "wx" });
+        } catch (error) {
+          if (error.code !== "EEXIST") throw error;
+          conflicts.push({
+            path: source.path,
+            reason: "a vault file appeared during synchronization",
+          });
+          continue;
+        }
+      }
+      created.push(source.path);
+      nextManifest.files[source.path] = sourceDigest;
+    } else {
+      const destinationDigest = digest(destinationContent);
+      if (destinationDigest === sourceDigest) {
+        unchanged.push(source.path);
+        nextManifest.files[source.path] = sourceDigest;
+      } else if (
+        previousDigest !== undefined &&
+        destinationDigest === previousDigest
+      ) {
+        if (!options.dryRun) await writeFile(destination, source.content);
+        updated.push(source.path);
+        nextManifest.files[source.path] = sourceDigest;
+      } else {
+        conflicts.push({
+          path: source.path,
+          reason: "vault copy has local edits; review or reconcile it manually",
+        });
+      }
+    }
+  }
+
+  const orphaned = Object.keys(manifest.files).filter(
+    (path) => !seenSourcePaths.has(path),
+  );
+  if (!options.dryRun && !conflicts.length) {
+    await mkdir(targetRoot, { recursive: true });
+    await writeFile(manifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`);
+  }
+
+  const result = {
+    action: options.dryRun ? "dry-run" : "sync",
+    provider: "obsidian",
+    source: docsRoot,
+    target: targetRoot,
+    created,
+    updated,
+    unchanged,
+    orphaned,
+    conflicts,
+  };
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return { exitCode: conflicts.length ? 1 : 0, result };
+}
+
+function printHelp() {
+  process.stdout.write(
+    "Usage: arcshape sync obsidian --vault <directory> [--docs <directory>] [--include <Markdown-directory>] [--path <vault-subdirectory>] [--dry-run]\n\n",
+  );
+  process.stdout.write(
+    "       arcshape sync confluence --base-url <url> --page-id <id> [--docs <directory>] [--dry-run]\n",
+  );
+  process.stdout.write(
+    "       arcshape sync confluence --base-url <url> --space-id <id> --parent-id <id> [--docs <directory>] [--include <file-or-directory>] [--title-prefix <name>] [--dry-run]\n",
+  );
+  process.stdout.write(
+    "Sync canonical Markdown to Obsidian or Confluence. Multi-page sync creates one page per arc42 section under a parent page.\n",
+  );
+  process.stdout.write(
+    "Vault and page edits are preserved and reported as conflicts. Confluence credentials use CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN by default.\n",
+  );
+}
+
+function parseConfluenceOptions(args) {
+  const options = { dryRun: false, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--dry-run") options.dryRun = true;
+    else if (
+      [
+        "--base-url",
+        "--page-id",
+        "--space-id",
+        "--parent-id",
+        "--title-prefix",
+        "--include",
+        "--docs",
+        "--email-env",
+        "--token-env",
+      ].includes(arg)
+    ) {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--"))
+        throw new Error(`${arg} requires a value`);
+      if (arg === "--base-url") options.baseUrl = value;
+      else if (arg === "--page-id") options.pageId = value;
+      else if (arg === "--space-id") options.spaceId = value;
+      else if (arg === "--parent-id") options.parentId = value;
+      else if (arg === "--title-prefix") options.titlePrefix = value;
+      else if (arg === "--include") (options.include ??= []).push(value);
+      else if (arg === "--docs") options.docs = value;
+      else if (arg === "--email-env") options.emailEnv = value;
+      else options.tokenEnv = value;
+      index += 1;
+    } else throw new Error(`Unknown Confluence sync option: ${arg}`);
+  }
+  return options;
+}
+
+function parseOptions(args) {
+  const options = { dryRun: false, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--dry-run") options.dryRun = true;
+    else if (["--vault", "--docs", "--include", "--path"].includes(arg)) {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--"))
+        throw new Error(`${arg} requires a value`);
+      if (arg === "--vault") options.vault = value;
+      else if (arg === "--docs") options.docs = value;
+      else if (arg === "--include") (options.include ??= []).push(value);
+      else options.path = value;
+      index += 1;
+    } else throw new Error(`Unknown sync option: ${arg}`);
+  }
+  return options;
+}
+
+async function collectMarkdown(root, parent = "") {
+  const entries = await readdir(join(root, parent), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((left, right) =>
+    left.name.localeCompare(right.name),
+  )) {
+    const path = join(parent, entry.name);
+    if (entry.isDirectory()) files.push(...(await collectMarkdown(root, path)));
+    else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md"))
+      files.push({ path, content: await readFile(join(root, path)) });
+  }
+  return files;
+}
+
+async function readManifest(path) {
+  try {
+    const manifest = JSON.parse(await readFile(path, "utf8"));
+    if (
+      manifest.version !== 1 ||
+      manifest.files === null ||
+      typeof manifest.files !== "object" ||
+      Array.isArray(manifest.files) ||
+      Object.values(manifest.files).some(
+        (value) =>
+          typeof value !== "string" || !/^sha256:[a-f\d]{64}$/.test(value),
+      )
+    )
+      throw new Error("manifest has an unsupported or invalid format");
+    return manifest;
+  } catch (error) {
+    if (error.code === "ENOENT") return { version: 1, files: {} };
+    throw new Error(`cannot read sync manifest: ${error.message}`);
+  }
+}
+
+function digest(content) {
+  return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+
+function isInside(root, path) {
+  const rel = relative(root, path);
+  return (
+    rel === "" ||
+    (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`))
+  );
+}
+
+async function isDirectory(path) {
+  try {
+    return (await lstat(path)).isDirectory();
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function isSymlink(path) {
+  try {
+    return (await lstat(path)).isSymbolicLink();
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function hasSymlink(root, path) {
+  const parts = relative(root, path).split(sep);
+  let current = root;
+  for (const part of parts) {
+    current = join(current, part);
+    if (await isSymlink(current)) return true;
+  }
+  return false;
+}
+
+function basename(path) {
+  return path.split(/[\\/]/).filter(Boolean).at(-1) ?? "architecture";
+}
+
+function commonAncestor(paths) {
+  const [first, ...rest] = paths.map((path) => resolve(path));
+  let candidate = first;
+  while (rest.some((path) => !isInside(candidate, path))) {
+    const parent = dirname(candidate);
+    if (parent === candidate) return parse(candidate).root;
+    candidate = parent;
+  }
+  return candidate;
+}

package/bin/validate-links.mjs

@@ -0,0 +1,98 @@
+import { access, readFile } from "node:fs/promises";
+import { isAbsolute, resolve, sep } from "node:path";
+import { marked } from "marked";
+import GithubSlugger from "github-slugger";
+
+export async function validateMarkdownLinks(
+  documents,
+  repositoryRoot,
+  docsDir,
+) {
+  const problems = [];
+  for (const document of documents) {
+    const source = resolve(docsDir, document.file);
+    const tokens = marked.lexer(document.body);
+    const links = [];
+    marked.walkTokens(tokens, (token) => {
+      if (token.type === "link" || token.type === "image")
+        links.push(token.href);
+    });
+    for (const href of links) {
+      if (!href || href.startsWith("#")) continue;
+      let target;
+      try {
+        target = new URL(href, "https://arcshape.invalid");
+      } catch {
+        problems.push(`${document.file}: invalid link destination ${href}`);
+        continue;
+      }
+      if (target.origin !== "https://arcshape.invalid") continue;
+      let pathname;
+      try {
+        pathname = decodeURIComponent(href.split(/[?#]/, 1)[0]);
+      } catch {
+        problems.push(`${document.file}: invalid URL encoding in ${href}`);
+        continue;
+      }
+      const resolvedTarget = pathname.startsWith("/")
+        ? resolve(repositoryRoot, pathname.slice(1))
+        : resolve(source, "..", pathname);
+      const relativePath = relativeFromRoot(repositoryRoot, resolvedTarget);
+      if (
+        isAbsolute(relativePath) ||
+        relativePath === ".." ||
+        relativePath.startsWith(`..${sep}`)
+      ) {
+        problems.push(`${document.file}: link escapes the repository: ${href}`);
+        continue;
+      }
+      try {
+        await access(resolvedTarget);
+      } catch {
+        problems.push(`${document.file}: missing local target ${href}`);
+        continue;
+      }
+      if (!target.hash || !pathname.toLowerCase().endsWith(".md")) continue;
+      let fragment;
+      try {
+        fragment = decodeURIComponent(target.hash.slice(1));
+      } catch {
+        problems.push(
+          `${document.file}: invalid heading URL encoding in ${href}`,
+        );
+        continue;
+      }
+      try {
+        const targetContents = await readFile(resolvedTarget, "utf8");
+        const slugger = new GithubSlugger();
+        let found = false;
+        marked.walkTokens(marked.lexer(targetContents), (candidate) => {
+          if (
+            candidate.type === "heading" &&
+            slugger.slug(candidate.text) === fragment
+          )
+            found = true;
+        });
+        if (!found)
+          problems.push(
+            `${document.file}: missing heading #${fragment} in ${href}`,
+          );
+      } catch {
+        problems.push(
+          `${document.file}: cannot read local Markdown target ${href}`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+function relativeFromRoot(root, path) {
+  const normalizedRoot = resolve(root);
+  const normalizedPath = resolve(path);
+  return normalizedPath.startsWith(`${normalizedRoot}${sep}`)
+    ? normalizedPath.slice(normalizedRoot.length + 1)
+    : normalizedPath === normalizedRoot
+      ? ""
+      : normalizedPath;
+}

package/bin/validate.mjs

@@ -0,0 +1,126 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { loadDocs } from "../tools/arc42-site/loadDocs.mjs";
+import { verifyProductCitations } from "./product-citations.mjs";
+import { validateMarkdownLinks } from "./validate-links.mjs";
+
+export async function runValidate(args, runtime = {}) {
+  const options = parseOptions(args);
+  if (options.help) {
+    process.stdout.write(
+      "Usage: arcshape validate [--docs <directory>] [--links] [--citations] [--format text|json]\n\n",
+    );
+    process.stdout.write(
+      "Validate the README and all twelve Markdown arc42 sections. Use --links to check local links and --citations to verify ProductShape citations when a model is present.\n",
+    );
+    return { exitCode: 0 };
+  }
+
+  const workingDirectory = resolve(runtime.cwd ?? process.cwd());
+  const docsDir = resolve(
+    workingDirectory,
+    options.docs ?? "docs/architecture",
+  );
+  const docsRelativeToWorkingDirectory = relative(workingDirectory, docsDir);
+  const repositoryRoot =
+    isAbsolute(docsRelativeToWorkingDirectory) ||
+    docsRelativeToWorkingDirectory === ".." ||
+    docsRelativeToWorkingDirectory.startsWith(`..${sep}`)
+      ? docsDir
+      : workingDirectory;
+  try {
+    const docs = await loadDocs(docsDir);
+    const diagnostics = options.links
+      ? await validateMarkdownLinks(
+          [docs.readme, ...docs.sections],
+          repositoryRoot,
+          docsDir,
+        )
+      : [];
+    const productCitations = options.citations
+      ? await verifyProductCitations({
+          repositoryRoot: workingDirectory,
+          docsDir,
+          productShapeCliPath: runtime.productShapeCliPath,
+        })
+      : undefined;
+    const result = {
+      valid:
+        diagnostics.length === 0 &&
+        productCitations?.status !== "invalid" &&
+        productCitations?.status !== "unavailable",
+      docs: docsDir,
+      sections: docs.sections.length,
+      title: docs.readme.title,
+      diagnostics,
+      ...(productCitations ? { productCitations } : {}),
+    };
+    printResult(result, options.format);
+    return { exitCode: result.valid ? 0 : 1, result };
+  } catch (error) {
+    const problems = error.problems ?? [error.message];
+    const result = {
+      valid: false,
+      docs: docsDir,
+      sections: 0,
+      diagnostics: problems,
+    };
+    printResult(result, options.format);
+    return { exitCode: 1, result };
+  }
+}
+
+function printResult(result, format) {
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  if (result.valid) {
+    process.stdout.write(
+      `Valid arc42 documentation: ${result.sections} sections (${result.docs})\n`,
+    );
+  } else {
+    process.stderr.write(`Invalid arc42 documentation (${result.docs}):\n`);
+    for (const diagnostic of result.diagnostics)
+      process.stderr.write(`  - ${diagnostic}\n`);
+  }
+  if (result.productCitations?.status === "skipped")
+    process.stdout.write(
+      `ProductShape citations skipped: ${result.productCitations.reason}\n`,
+    );
+  else if (result.productCitations?.status === "verified")
+    process.stdout.write(
+      `ProductShape citations verified: ${result.productCitations.summary.total} citation(s)\n`,
+    );
+  else if (result.productCitations) {
+    process.stderr.write(
+      `ProductShape citation verification ${result.productCitations.status}: ${result.productCitations.reason ?? "see diagnostics"}\n`,
+    );
+  }
+  for (const diagnostic of result.productCitations?.diagnostics ?? []) {
+    const write =
+      diagnostic.severity === "warning" ? process.stdout : process.stderr;
+    write.write(
+      `  - ${diagnostic.severity ?? "error"} ${diagnostic.code ?? ""} ${diagnostic.file ?? ""}: ${diagnostic.message ?? JSON.stringify(diagnostic)}\n`,
+    );
+  }
+}
+
+function parseOptions(args) {
+  const options = { format: "text", help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--links") options.links = true;
+    else if (arg === "--citations") options.citations = true;
+    else if (arg === "--docs" || arg === "--format") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--"))
+        throw new Error(`${arg} requires a value`);
+      if (arg === "--docs") options.docs = value;
+      else if (value === "text" || value === "json") options.format = value;
+      else throw new Error("--format must be text or json");
+      index += 1;
+    } else throw new Error(`Unknown validate option: ${arg}`);
+  }
+  return options;
+}