@modularcloud/cspec 0.1.0

package/bin/cspec.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@modularcloud/cspec",
+  "version": "0.1.0",
+  "description": "Minimal MDX content block compiler implementing the cspec reusable-block subset.",
+  "type": "module",
+  "bin": {
+    "cspec": "bin/cspec.js"
+  },
+  "exports": {
+    ".": "./src/runtime.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "build": "node ./bin/cspec.js build",
+    "prepack": "node --test"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "cspec",
+    "xspec",
+    "mdx",
+    "markdown",
+    "compiler",
+    "content"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {}
+}

package/src/cli.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+import { formatError } from "./errors.js";
+import { assertFresh, loadWorkspace, writeOutputs } from "./workspace.js";
+
+export async function runCli(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const [command = "build", ...rest] = args;
+  try {
+    if (command === "build") {
+      const workspace = await loadWorkspace(process.cwd());
+      writeOutputs(workspace);
+      io.stdout.write(`Built ${workspace.documents.length} file(s).\n`);
+      return;
+    }
+    if (command === "check") {
+      const workspace = await loadWorkspace(process.cwd());
+      assertFresh(workspace);
+      io.stdout.write("cspec check passed.\n");
+      return;
+    }
+    if (command === "ids") {
+      const workspace = await loadWorkspace(process.cwd());
+      io.stdout.write(formatIds(workspace, rest));
+      return;
+    }
+    if (command === "--help" || command === "-h") {
+      io.stdout.write("Usage: cspec <build|check|ids> [--tree|--json]\n");
+      return;
+    }
+    throw new Error(`Unknown command "${command}".`);
+  } catch (error) {
+    io.stderr.write(`${formatError(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+function formatIds(workspace, args) {
+  if (args.includes("--json")) {
+    return `${JSON.stringify({
+      files: workspace.documents.map((doc) => ({
+        file: path.relative(workspace.cwd, doc.file),
+        ids: [...doc.blocks.values()].map((block) => ({ id: block.id, segments: block.segments }))
+      }))
+    }, null, 2)}\n`;
+  }
+  if (args.includes("--tree")) {
+    return workspace.documents.map((doc) => `${path.relative(workspace.cwd, doc.file)}\n${treeLines(doc.root.children, "")}`).join("\n");
+  }
+  return workspace.documents.map((doc) => {
+    const ids = [...doc.blocks.keys()].map((id) => `  ${id}`).join("\n");
+    return `${path.relative(workspace.cwd, doc.file)}${ids ? `\n${ids}` : ""}\n`;
+  }).join("\n");
+}
+
+function treeLines(blocks, prefix) {
+  return blocks.map((block, index) => {
+    const last = index === blocks.length - 1;
+    const branch = last ? "└─ " : "├─ ";
+    const nextPrefix = `${prefix}${last ? "   " : "│  "}`;
+    const children = block.children.length ? `\n${treeLines(block.children, nextPrefix)}` : "";
+    return `${prefix}${branch}${block.id}${children}`;
+  }).join("\n") + "\n";
+}

package/src/config.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CspecError } from "./errors.js";
+
+export async function loadConfig(cwd) {
+  const candidates = ["cspec.config.js", "cspec.config.mjs", "cspec.config.cjs", "cspec.config.ts"];
+  for (const name of candidates) {
+    const file = path.join(cwd, name);
+    if (!fs.existsSync(file)) continue;
+    const config = name.endsWith(".ts") ? loadTsConfig(file) : await importConfig(file);
+    return normalizeConfig(config);
+  }
+  return normalizeConfig({
+    specs: { default: ["**/*.mdx"] },
+    markdown: { emit: true }
+  });
+}
+
+async function importConfig(file) {
+  const module = await import(`${pathToFileUrl(file)}?t=${Date.now()}`);
+  return module.default ?? module;
+}
+
+function loadTsConfig(file) {
+  const source = fs.readFileSync(file, "utf8")
+    .replace(/^\s*import\s+.*?(?:;\s*)?$/gm, "")
+    .replace(/export\s+default\s+defineConfig\s*\(/, "return (")
+    .replace(/export\s+default\s+/, "return ");
+  try {
+    return Function("defineConfig", source)((value) => value);
+  } catch (error) {
+    throw new CspecError(`Unable to load ${path.basename(file)}: ${error.message}`, { file });
+  }
+}
+
+function normalizeConfig(config) {
+  return {
+    specs: config?.specs && Object.keys(config.specs).length ? config.specs : { default: ["**/*.mdx"] },
+    markdown: {
+      emit: config?.markdown?.emit !== false
+    }
+  };
+}
+
+function pathToFileUrl(file) {
+  return `file://${file.split(path.sep).map(encodeURIComponent).join("/")}`;
+}

package/src/errors.js

@@ -0,0 +1,15 @@
+export class CspecError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "CspecError";
+    this.details = details;
+  }
+}
+
+export function formatError(error) {
+  if (!error?.details?.file) return error.message;
+  const location = error.details.line
+    ? `${error.details.file}:${error.details.line}`
+    : error.details.file;
+  return `${location}: ${error.message}`;
+}

package/src/generate.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+
+export function generatedFilesFor(doc, options) {
+  const base = doc.file.replace(/\.mdx$/i, "");
+  const files = [
+    {
+      file: `${base}.cspec.ts`,
+      content: generateTypeScript(doc)
+    }
+  ];
+  if (options.markdownEmit) {
+    files.push({
+      file: `${base}.md`,
+      content: `${doc.root.compiled}\n`
+    });
+  }
+  return files;
+}
+
+export function generateTypeScript(doc) {
+  const name = safeConstName(path.basename(doc.file, ".mdx"));
+  const tree = { $: doc.root.compiled };
+  for (const block of doc.blocks.values()) {
+    let cursor = tree;
+    for (const segment of block.segments) {
+      cursor[segment] ??= {};
+      cursor = cursor[segment];
+    }
+    cursor.$ = block.compiled;
+  }
+  return `const ${name} = ${printObject(tree, 0)} as const;\n\nexport default ${name};\n`;
+}
+
+function safeConstName(name) {
+  const cleaned = name.replace(/\W+/g, "_").replace(/^(\d)/, "_$1");
+  return cleaned || "SPEC";
+}
+
+function printObject(value, depth) {
+  if (typeof value === "string") return JSON.stringify(value);
+  const indent = "  ".repeat(depth);
+  const childIndent = "  ".repeat(depth + 1);
+  const entries = Object.entries(value);
+  if (entries.length === 0) return "{}";
+  const body = entries
+    .map(([key, child]) => `${childIndent}${printKey(key)}: ${printObject(child, depth + 1)}`)
+    .join(",\n");
+  return `{\n${body}\n${indent}}`;
+}
+
+function printKey(key) {
+  return /^[A-Za-z_$][\w$]*$/.test(key) ? key : JSON.stringify(key);
+}

package/src/glob.js

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function discoverFiles(cwd, specs) {
+  const patterns = Object.values(specs).flat();
+  const files = new Set();
+  for (const pattern of patterns) {
+    for (const file of walk(cwd)) {
+      const rel = path.relative(cwd, file).split(path.sep).join("/");
+      if (isGenerated(rel)) continue;
+      if (matchGlob(pattern, rel)) files.add(file);
+    }
+  }
+  return [...files].sort();
+}
+
+function walk(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".git") continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walk(full));
+    else if (entry.isFile()) files.push(full);
+  }
+  return files;
+}
+
+function isGenerated(rel) {
+  return rel.endsWith(".cspec.ts") || rel.endsWith(".md");
+}
+
+export function matchGlob(pattern, rel) {
+  if (pattern.startsWith("**/") && matchGlob(pattern.slice(3), rel)) return true;
+  if (pattern.includes("/**/") && matchGlob(pattern.replace("/**/", "/"), rel)) return true;
+  const escaped = pattern.split(/(\*\*|\*)/g).map((part) => {
+    if (part === "**") return ".*";
+    if (part === "*") return "[^/]*";
+    return part.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  return new RegExp(`^${escaped}$`).test(rel);
+}

package/src/ids.js

@@ -0,0 +1,45 @@
+import { CspecError } from "./errors.js";
+
+const RESERVED = new Set(["$", "__proto__", "prototype", "constructor"]);
+
+export function splitId(id, details = {}) {
+  if (typeof id !== "string") {
+    throw new CspecError("Block id must be a string.", details);
+  }
+  if (id.trim() !== id) {
+    throw new CspecError(`Invalid block id "${id}"; ids must not have leading or trailing whitespace.`, details);
+  }
+  const segments = id.split(".");
+  for (const segment of segments) validateSegment(segment, details);
+  return segments;
+}
+
+export function validateSegment(segment, details = {}) {
+  if (!segment) {
+    throw new CspecError("Invalid empty id segment.", details);
+  }
+  if (segment.trim() !== segment) {
+    throw new CspecError(`Invalid id segment "${segment}"; segments must not have leading or trailing whitespace.`, details);
+  }
+  if (/[\u0000-\u001f\u007f]/u.test(segment)) {
+    throw new CspecError(`Invalid id segment "${segment}"; control characters are not allowed.`, details);
+  }
+  if (RESERVED.has(segment)) {
+    const reason = segment === "$" ? '"$" is reserved for block values.' : `"${segment}" is reserved.`;
+    throw new CspecError(`Invalid id segment "${segment}"; ${reason}`, details);
+  }
+}
+
+export function assertStructuralId(id, parentId, details = {}) {
+  splitId(id, details);
+  if (parentId && !id.startsWith(`${parentId}.`)) {
+    throw new CspecError(
+      `Child block id must begin with parent id plus ".".\nExpected id matching "${parentId}.<segment>".\nReceived "${id}".`,
+      details
+    );
+  }
+}
+
+export function idToSegments(id) {
+  return id ? id.split(".") : [];
+}

package/src/parser.js

@@ -0,0 +1,221 @@
+import path from "node:path";
+import { CspecError } from "./errors.js";
+import { assertStructuralId, idToSegments } from "./ids.js";
+
+const TAG_RE = /<\/?(S|Spec)\b[^>]*>/g;
+const IMPORT_RE = /^\s*import\s+([^'";]+?)\s+from\s+["']([^"']+)["']\s*;?\s*$/gm;
+const EXTERNAL_REF_RE = /\{([A-Za-z_$][\w$]*(?:(?:\.[A-Za-z_$][\w$]*)|(?:\["(?:[^"\\]|\\.)*"\])|(?:\['(?:[^'\\]|\\.)*'\]))*)\.\$\}/g;
+const LOCAL_REF_RE = /\{\s*ref\s*\(([^)]*)\)\s*\.\$\s*\}/g;
+
+export function parseSource(file, source) {
+  const imports = parseImports(source);
+  const root = makeBlock("", null, 0, source.length, 0, source.length, "root");
+  const stack = [root];
+  const blocks = new Map();
+  const rangesToRemove = imports.map((item) => expandStandaloneRange(source, item.start, item.end));
+
+  for (const match of source.matchAll(TAG_RE)) {
+    const raw = match[0];
+    const index = match.index;
+    const closing = raw.startsWith("</");
+    if (closing) {
+      if (stack.length === 1) {
+        throw new CspecError(`Unexpected closing ${raw}.`, { file, line: lineAt(source, index) });
+      }
+      const block = stack.pop();
+      const expected = `</${block.tag}>`;
+      if (raw !== expected) {
+        throw new CspecError(`Mismatched block tag. Expected ${expected}, received ${raw}.`, {
+          file,
+          line: lineAt(source, index)
+        });
+      }
+      block.closeStart = index;
+      block.closeEnd = index + raw.length;
+      block.contentEnd = index;
+      rangesToRemove.push(
+        expandStandaloneRange(source, block.openStart, block.openEnd),
+        expandStandaloneRange(source, block.closeStart, block.closeEnd)
+      );
+      continue;
+    }
+
+    const tag = match[1];
+    const parent = stack[stack.length - 1];
+    const id = parseIdAttribute(raw);
+    if (!id) {
+      throw new CspecError(`Non-root <${tag}> block is missing required id.`, { file, line: lineAt(source, index) });
+    }
+    assertStructuralId(id, parent.id, { file, line: lineAt(source, index) });
+    if (blocks.has(id)) {
+      throw new CspecError(`Duplicate block id "${id}".`, { file, line: lineAt(source, index) });
+    }
+
+    const block = makeBlock(id, parent.id || null, index, index + raw.length, index + raw.length, null, tag);
+    block.segments = idToSegments(id);
+    block.line = lineAt(source, index);
+    parent.children.push(block);
+    blocks.set(id, block);
+    stack.push(block);
+  }
+
+  if (stack.length > 1) {
+    const block = stack[stack.length - 1];
+    throw new CspecError(`Unclosed <${block.tag}> block "${block.id}".`, { file, line: block.line });
+  }
+
+  root.children = root.children.sort((a, b) => a.openStart - b.openStart);
+  return {
+    file,
+    source,
+    root,
+    blocks,
+    imports,
+    rangesToRemove,
+    references: parseReferences(source, imports)
+  };
+}
+
+function makeBlock(id, parentId, openStart, openEnd, contentStart, contentEnd, tag) {
+  return {
+    id,
+    parentId,
+    openStart,
+    openEnd,
+    contentStart,
+    contentEnd,
+    closeStart: null,
+    closeEnd: null,
+    tag,
+    children: [],
+    segments: [],
+    line: 1,
+    compiled: null
+  };
+}
+
+function parseIdAttribute(raw) {
+  const doubleMatch = raw.match(/\bid\s*=\s*"([^"]*)"/);
+  if (doubleMatch) return doubleMatch[1];
+  const singleMatch = raw.match(/\bid\s*=\s*'([^']*)'/);
+  if (singleMatch) return singleMatch[1];
+  return null;
+}
+
+function expandStandaloneRange(source, start, end) {
+  const lineStart = source.lastIndexOf("\n", start - 1) + 1;
+  const nextNewline = source.indexOf("\n", end);
+  const lineEnd = nextNewline === -1 ? source.length : nextNewline + 1;
+  const before = source.slice(lineStart, start);
+  const after = source.slice(end, nextNewline === -1 ? source.length : nextNewline);
+  if (/^[ \t]*$/.test(before) && /^[ \t]*$/.test(after)) {
+    return [lineStart, lineEnd];
+  }
+  return [start, end];
+}
+
+function parseImports(source) {
+  const imports = [];
+  for (const match of source.matchAll(IMPORT_RE)) {
+    const specifier = match[2];
+    const clause = match[1].trim();
+    const start = match.index;
+    const end = start + match[0].length;
+    if (specifier === "cspec") {
+      imports.push({ kind: "cspec", clause, specifier, start, end });
+      continue;
+    }
+    if (specifier.endsWith(".cspec")) {
+      const local = clause.match(/^([A-Za-z_$][\w$]*)$/)?.[1];
+      if (local) imports.push({ kind: "module", local, specifier, start, end });
+    }
+  }
+  return imports;
+}
+
+function parseReferences(source, imports) {
+  const importedNames = new Set(imports.filter((item) => item.kind === "module").map((item) => item.local));
+  const references = [];
+
+  for (const match of source.matchAll(LOCAL_REF_RE)) {
+    const arg = match[1].trim();
+    const literal = parseStringLiteral(arg);
+    references.push({
+      kind: "local",
+      raw: match[0],
+      start: match.index,
+      end: match.index + match[0].length,
+      id: literal,
+      validStatic: literal !== null,
+      expression: arg
+    });
+  }
+
+  for (const match of source.matchAll(EXTERNAL_REF_RE)) {
+    const expression = match[1];
+    const [name] = expression.split(/[.\[]/, 1);
+    if (!importedNames.has(name)) continue;
+    references.push({
+      kind: "external",
+      raw: match[0],
+      start: match.index,
+      end: match.index + match[0].length,
+      local: name,
+      path: memberExpressionToPath(expression.slice(name.length)),
+      expression
+    });
+  }
+
+  return references.sort((a, b) => a.start - b.start);
+}
+
+function parseStringLiteral(value) {
+  if (!/^(['"])(?:\\.|(?!\1).)*\1$/s.test(value)) return null;
+  try {
+    return JSON.parse(value[0] === "'" ? `"${value.slice(1, -1).replace(/"/g, '\\"')}"` : value);
+  } catch {
+    return value.slice(1, -1);
+  }
+}
+
+function memberExpressionToPath(expression) {
+  const segments = [];
+  let rest = expression;
+  while (rest) {
+    const dot = rest.match(/^\.(?!\$)([A-Za-z_$][\w$]*)/);
+    if (dot) {
+      segments.push(dot[1]);
+      rest = rest.slice(dot[0].length);
+      continue;
+    }
+    const bracket = rest.match(/^\[(["'])((?:\\.|(?!\1).)*)\]/s);
+    if (bracket) {
+      segments.push(unescapeQuoted(bracket[2]));
+      rest = rest.slice(bracket[0].length);
+      continue;
+    }
+    break;
+  }
+  return segments.join(".");
+}
+
+function unescapeQuoted(value) {
+  try {
+    return JSON.parse(`"${value.replace(/"/g, '\\"')}"`);
+  } catch {
+    return value.replace(/\\(['"\\])/g, "$1");
+  }
+}
+
+export function resolveImportPath(fromFile, specifier) {
+  const base = path.resolve(path.dirname(fromFile), specifier.replace(/\.cspec$/, ".mdx"));
+  return base;
+}
+
+export function lineAt(source, index) {
+  let line = 1;
+  for (let i = 0; i < index; i += 1) {
+    if (source.charCodeAt(i) === 10) line += 1;
+  }
+  return line;
+}

package/src/render.js

@@ -0,0 +1,89 @@
+import { CspecError } from "./errors.js";
+import { lineAt, resolveImportPath } from "./parser.js";
+
+export function compileWorkspace(documents) {
+  const byFile = new Map(documents.map((doc) => [doc.file, doc]));
+  const context = { byFile, stack: [] };
+  for (const doc of documents) {
+    compileBlock(doc, doc.root, context);
+    for (const block of doc.blocks.values()) compileBlock(doc, block, context);
+  }
+}
+
+export function compileBlock(doc, block, context) {
+  const key = `${doc.file}#${block.id || "$"}`;
+  if (block.compiled !== null) return block.compiled;
+  const cycleAt = context.stack.indexOf(key);
+  if (cycleAt !== -1) {
+    const cycle = context.stack.slice(cycleAt).concat(key).map((item) => item.split("#")[1]).join(" -> ");
+    throw new CspecError(`Embedding cycle detected:\n${cycle}`, { file: doc.file, line: block.line });
+  }
+  context.stack.push(key);
+  const start = block.id ? block.contentStart : 0;
+  const end = block.id ? block.contentEnd : doc.source.length;
+  block.compiled = renderRange(doc, start, end, context);
+  context.stack.pop();
+  return block.compiled;
+}
+
+function renderRange(doc, start, end, context) {
+  const removals = doc.rangesToRemove
+    .filter(([a, b]) => b > start && a < end)
+    .map(([a, b]) => [Math.max(a, start), Math.min(b, end), ""]);
+  const replacements = doc.references
+    .filter((ref) => ref.start >= start && ref.end <= end)
+    .map((ref) => [ref.start, ref.end, resolveReference(doc, ref, context)]);
+  const edits = removals.concat(replacements).sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+
+  let out = "";
+  let cursor = start;
+  for (const [a, b, value] of edits) {
+    if (a < cursor) continue;
+    out += doc.source.slice(cursor, a);
+    out += value;
+    cursor = b;
+  }
+  out += doc.source.slice(cursor, end);
+  return trimOuterBlankLines(out);
+}
+
+function resolveReference(doc, ref, context) {
+  if (ref.kind === "local") {
+    if (!ref.validStatic) {
+      throw new CspecError("ref(...) requires a static string literal.", {
+        file: doc.file,
+        line: lineAt(doc.source, ref.start)
+      });
+    }
+    const target = doc.blocks.get(ref.id);
+    if (!target) {
+      throw new CspecError(`Unknown local block reference "${ref.id}".`, {
+        file: doc.file,
+        line: lineAt(doc.source, ref.start)
+      });
+    }
+    return compileBlock(doc, target, context);
+  }
+
+  const imported = doc.imports.find((item) => item.kind === "module" && item.local === ref.local);
+  const targetFile = resolveImportPath(doc.file, imported.specifier);
+  const targetDoc = context.byFile.get(targetFile);
+  if (!targetDoc) {
+    throw new CspecError(`Unresolved import ${imported.specifier}.`, {
+      file: doc.file,
+      line: lineAt(doc.source, ref.start)
+    });
+  }
+  const target = ref.path ? targetDoc.blocks.get(ref.path) : targetDoc.root;
+  if (!target) {
+    throw new CspecError(`Unknown block reference ${ref.expression}.`, {
+      file: doc.file,
+      line: lineAt(doc.source, ref.start)
+    });
+  }
+  return compileBlock(targetDoc, target, context);
+}
+
+function trimOuterBlankLines(value) {
+  return value.replace(/^\s*\n/, "").replace(/\n\s*$/, "");
+}

package/src/runtime.js

@@ -0,0 +1,13 @@
+export function S(props) {
+  return props?.children ?? null;
+}
+
+export const Spec = S;
+
+export function ref(id) {
+  return { id, $: "" };
+}
+
+export function defineConfig(config) {
+  return config;
+}

package/src/workspace.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./config.js";
+import { discoverFiles } from "./glob.js";
+import { parseSource } from "./parser.js";
+import { compileWorkspace } from "./render.js";
+import { generatedFilesFor } from "./generate.js";
+import { CspecError } from "./errors.js";
+
+export async function loadWorkspace(cwd) {
+  const config = await loadConfig(cwd);
+  const files = discoverFiles(cwd, config.specs);
+  const documents = files.map((file) => parseSource(file, fs.readFileSync(file, "utf8")));
+  compileWorkspace(documents);
+  return { cwd, config, documents };
+}
+
+export function expectedOutputs(workspace) {
+  return workspace.documents.flatMap((doc) =>
+    generatedFilesFor(doc, { markdownEmit: workspace.config.markdown.emit })
+  );
+}
+
+export function writeOutputs(workspace) {
+  for (const output of expectedOutputs(workspace)) {
+    fs.writeFileSync(output.file, output.content);
+  }
+}
+
+export function assertFresh(workspace) {
+  for (const output of expectedOutputs(workspace)) {
+    const rel = path.relative(workspace.cwd, output.file);
+    if (!fs.existsSync(output.file) || fs.readFileSync(output.file, "utf8") !== output.content) {
+      throw new CspecError(`Generated file ${rel} is stale.\nRun cspec build.`, { file: output.file });
+    }
+  }
+}