@modularcloud/cspec 0.1.0 → 0.2.0

package/src/glob.js

@@ -1,42 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,221 +0,0 @@
-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

@@ -1,89 +0,0 @@
-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/workspace.js

@@ -1,37 +0,0 @@
-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 });
-    }
-  }
-}