@corvidlabs/threemd 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# @corvidlabs/threemd
+
+Parser and serializer for the **3md** format: Markdown with a Z axis. A `.3md`
+file is ordinary Markdown extended along one free axis, so you can stack content
+into **planes** and tell the reader what the depth means (time for a planner,
+frames for an animation, layers for annotations, space for a scene).
+
+This package is a faithful TypeScript port of the Swift reference parser
+(`ThreeMD`). The two implementations are pinned to identical behavior by a shared
+conformance suite, so parsing the same document in either language yields the
+same result.
+
+## Install
+
+```bash
+bun add @corvidlabs/threemd
+```
+
+## Usage
+
+```ts
+import { danglingLinks, linkGraph, parse, serialize } from "@corvidlabs/threemd";
+
+const source = `---
+3md: 0.1
+axis: time
+title: My Week
+---
+@plane z=0 label="Monday"
+# Monday
+- [ ] Standup
+
+@plane z=1 label="Tuesday"
+# Tuesday
+`;
+
+const document = parse(source);
+console.log(document.axis);            // "time"
+console.log(document.planes.length);   // 2
+console.log(danglingLinks(document));  // unresolved [[z=N]] references
+console.log(linkGraph(document));      // compact source -> target edge list
+
+// Round trips back to text:
+const text = serialize(document);
+```
+
+`parse` throws a `ParseError` on malformed input; its `code` property names the
+canonical case (`missingFrontmatter`, `invalidFrontmatter`, `missingVersion`,
+`missingPlanePosition`, `invalidPlaneDirective`, or `duplicatePlane`).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The meaning assigned to a 3md document's third (Z) axis.
+ *
+ * The value is always trimmed and lowercased, matching the Swift `Axis` type.
+ * Any string is permitted; common values are `time`, `depth`, `layer`,
+ * `frame`, and `space`.
+ */
+export type Axis = string;
+/**
+ * A single slice of a 3md document positioned along the Z axis.
+ *
+ * `z` is required and orders planes along the document's axis. `x` and `y` are
+ * optional in-plane offsets. Any directive attributes other than `z`, `x`, `y`,
+ * and `label` are preserved in `attributes`.
+ */
+export interface Plane {
+    /** Position along the document's Z axis. */
+    readonly z: number;
+    /** Optional human-readable label, or `null` when absent. */
+    readonly label: string | null;
+    /** Optional horizontal offset within the plane, or `null` when absent. */
+    readonly x: number | null;
+    /** Optional vertical offset within the plane, or `null` when absent. */
+    readonly y: number | null;
+    /** Extra directive attributes that are not `z`, `x`, `y`, or `label`. */
+    readonly attributes: Readonly<Record<string, string>>;
+    /** The Markdown content of this plane, with surrounding blank lines trimmed. */
+    readonly body: string;
+}
+/**
+ * A reference from one plane's Markdown body to another plane by its `z`
+ * position, written `[[z=N]]` or `[[z=N|text]]`.
+ *
+ * Cross-plane links live verbatim inside plane bodies; {@link links} extracts
+ * them in document order. This mirrors the cross-language contract pinned by the
+ * `links-*.json` conformance vectors.
+ */
+export interface CrossPlaneLink {
+    /** The `z` position of the plane whose body contains this link. */
+    readonly sourceZ: number;
+    /** The `z` position the link points at, parsed as a finite decimal. */
+    readonly targetZ: number;
+    /** The optional link text: `null` when absent, `""` when present but empty. */
+    readonly text: string | null;
+    /** Whether a plane with `z === targetZ` exists in the document. */
+    readonly targetExists: boolean;
+}
+/**
+ * A summarized directed edge in a document's cross-plane link graph.
+ *
+ * Multiple `[[z=N]]` links from the same source plane to the same target plane
+ * collapse into one edge with an incremented `count`.
+ */
+export interface CrossPlaneLinkEdge {
+    /** The `z` position of the plane whose body contains the link. */
+    readonly sourceZ: number;
+    /** The target `z` position named by the link. */
+    readonly targetZ: number;
+    /** Whether a plane with `z === targetZ` exists in the document. */
+    readonly targetExists: boolean;
+    /** Number of links collapsed into this edge. */
+    readonly count: number;
+}
+/**
+ * A parsed 3md document: Markdown extended along one free Z axis.
+ */
+export interface Document {
+    /** The declared 3md format version, for example `"0.1"`. */
+    readonly version: string;
+    /** What the Z axis represents in this document (trimmed, lowercased). */
+    readonly axis: Axis;
+    /** Optional document title from the frontmatter, or `null`. */
+    readonly title: string | null;
+    /** Any frontmatter keys other than `3md`, `axis`, and `title`. */
+    readonly metadata: Readonly<Record<string, string>>;
+    /** Markdown content after the frontmatter but before the first plane, or `null`. */
+    readonly preamble: string | null;
+    /** The document's planes, in source order. */
+    readonly planes: readonly Plane[];
+}
+/**
+ * The set of error case names a conforming 3md parser must reject with.
+ *
+ * These mirror the Swift `ParseError` enum cases one to one.
+ */
+export type ParseErrorCode = "missingFrontmatter" | "invalidFrontmatter" | "missingVersion" | "invalidPlaneDirective" | "missingPlanePosition" | "duplicatePlane";
+/**
+ * An error thrown while parsing a 3md document.
+ *
+ * The `code` property names the canonical Swift `ParseError` case, so callers
+ * and the conformance suite can match on it without parsing the message.
+ */
+export declare class ParseError extends Error {
+    /** The canonical Swift `ParseError` case name. */
+    readonly code: ParseErrorCode;
+    /** Optional 1-based line number for directive-related errors. */
+    readonly line: number | undefined;
+    /** Optional human-readable detail string. */
+    readonly detail: string | undefined;
+    constructor(code: ParseErrorCode, message: string, line?: number, detail?: string);
+}
+/**
+ * Parses 3md source text into a {@link Document}.
+ *
+ * Frontmatter is required and must declare a `3md` version key (the format's
+ * magic marker). Planes are introduced by `@plane` directives carrying
+ * `key=value` attributes; the text between directives is plain Markdown. A
+ * document with no directives parses as a single plane at `z = 0`.
+ *
+ * @param source The full contents of a `.3md` file.
+ * @returns The parsed document.
+ * @throws {ParseError} When the source is malformed. The error's `code`
+ *   property names the canonical case (`missingFrontmatter`,
+ *   `invalidFrontmatter`, `missingVersion`, `missingPlanePosition`,
+ *   `invalidPlaneDirective`, or `duplicatePlane`).
+ */
+export declare function parse(source: string): Document;
+/**
+ * Extracts every cross-plane link from a {@link Document}'s plane bodies.
+ *
+ * A cross-plane link matches the regular expression
+ * `\[\[z=([^\]|]+)(?:\|([^\]]*))?\]\]`. The captured target is validated as a
+ * finite decimal with the same grammar as the `z` attribute (see
+ * `parseFiniteDecimal`); if it is not a finite decimal, the sequence is not a
+ * link and is ignored. The optional second group is the link text: `null` when
+ * absent, the captured value (which may be `""`) when present.
+ *
+ * Links are returned in document order: planes in source order, then links left
+ * to right within each body. `targetExists` reports whether any plane in the
+ * document has a `z` strictly equal to the link's target.
+ *
+ * @param document The document to scan.
+ * @returns The extracted cross-plane links, in document order.
+ */
+export declare function links(document: Document): CrossPlaneLink[];
+/**
+ * Returns only cross-plane links whose target plane does not exist.
+ *
+ * @param document The document to scan.
+ * @returns Dangling cross-plane links in document order.
+ */
+export declare function danglingLinks(document: Document): CrossPlaneLink[];
+/**
+ * Returns a compact directed graph of cross-plane references.
+ *
+ * Multiple links with the same source and target collapse into one edge with an
+ * incremented count. The returned edges preserve the first time each
+ * source-target pair appears in the document.
+ *
+ * @param document The document to scan.
+ * @returns Cross-plane graph edges in first encounter order.
+ */
+export declare function linkGraph(document: Document): CrossPlaneLinkEdge[];
+/**
+ * Renders a {@link Document} back into 3md source text.
+ *
+ * The output round-trips through {@link parse}: parsing serialized text yields
+ * an equivalent document for content that does not rely on quote escaping.
+ * Mirrors the Swift `Serializer`.
+ *
+ * @param document The document to render.
+ * @returns The serialized `.3md` contents.
+ */
+export declare function serialize(document: Document): string;

package/dist/index.js

@@ -0,0 +1,424 @@
+// src/index.ts
+class ParseError extends Error {
+  code;
+  line;
+  detail;
+  constructor(code, message, line, detail) {
+    super(message);
+    this.name = "ParseError";
+    this.code = code;
+    this.line = line;
+    this.detail = detail;
+    Object.setPrototypeOf(this, ParseError.prototype);
+  }
+}
+var RESERVED_PLANE_KEYS = new Set(["z", "x", "y", "label"]);
+function trimWhitespace(value) {
+  return value.replace(/^[ \t]+/, "").replace(/[ \t]+$/, "");
+}
+function firstToken(line) {
+  for (const token of line.split(/[ \t]+/)) {
+    if (token.length > 0) {
+      return token;
+    }
+  }
+  return "";
+}
+function tokenize(input, line) {
+  const tokens = [];
+  let current = "";
+  let activeQuote = null;
+  let escaped = false;
+  for (const character of input) {
+    if (activeQuote !== null) {
+      current += character;
+      if (escaped) {
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === activeQuote) {
+        activeQuote = null;
+      }
+    } else if (character === '"' || character === "'") {
+      activeQuote = character;
+      current += character;
+    } else if (character === " " || character === "\t") {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = "";
+      }
+    } else {
+      current += character;
+    }
+  }
+  if (activeQuote !== null) {
+    throw new ParseError("invalidPlaneDirective", `Invalid @plane directive on line ${line}: unterminated quote in '${input}'`, line, `unterminated quote in '${input}'`);
+  }
+  if (current.length > 0) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+function unquote(value) {
+  if (value.length < 2) {
+    return value;
+  }
+  const first = value[0];
+  const last = value[value.length - 1];
+  if (first === '"' && last === '"' || first === "'" && last === "'") {
+    return unescapeValue(value.slice(1, -1));
+  }
+  return value;
+}
+function unescapeValue(value) {
+  let result = "";
+  let escaping = false;
+  for (const character of value) {
+    if (escaping) {
+      result += character;
+      escaping = false;
+    } else if (character === "\\") {
+      escaping = true;
+    } else {
+      result += character;
+    }
+  }
+  if (escaping) {
+    result += "\\";
+  }
+  return result;
+}
+function fenceCharacter(trimmed) {
+  if (trimmed.startsWith("```")) {
+    return "`";
+  }
+  if (trimmed.startsWith("~~~")) {
+    return "~";
+  }
+  return null;
+}
+function collapse(lines) {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && trimWhitespace(lines[start] ?? "") === "") {
+    start += 1;
+  }
+  while (end > start && trimWhitespace(lines[end - 1] ?? "") === "") {
+    end -= 1;
+  }
+  if (start >= end) {
+    return null;
+  }
+  return lines.slice(start, end).join(`
+`);
+}
+function parseFiniteDecimal(text) {
+  const pattern = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+  if (!pattern.test(text)) {
+    return null;
+  }
+  const value = Number(text);
+  return Number.isFinite(value) ? value : null;
+}
+function extractFrontmatter(lines) {
+  let index = 0;
+  while (index < lines.length && trimWhitespace(lines[index] ?? "") === "") {
+    index += 1;
+  }
+  if (index >= lines.length || trimWhitespace(lines[index] ?? "") !== "---") {
+    throw new ParseError("missingFrontmatter", "3md documents must begin with a '---' frontmatter block.");
+  }
+  index += 1;
+  const fields = [];
+  while (index < lines.length) {
+    const trimmed = trimWhitespace(lines[index] ?? "");
+    if (trimmed === "---") {
+      const bodyStart = index + 1;
+      const body = bodyStart < lines.length ? lines.slice(bodyStart) : [];
+      return { fields, bodyStartLine: index + 2, body };
+    }
+    if (trimmed !== "" && !trimmed.startsWith("#")) {
+      const separator = trimmed.indexOf(":");
+      if (separator < 0) {
+        throw new ParseError("invalidFrontmatter", `Invalid frontmatter: expected 'key: value', found '${trimmed}'`, undefined, `expected 'key: value', found '${trimmed}'`);
+      }
+      const key = trimWhitespace(trimmed.slice(0, separator));
+      const raw = trimWhitespace(trimmed.slice(separator + 1));
+      fields.push({ key, value: unquote(raw) });
+    }
+    index += 1;
+  }
+  throw new ParseError("invalidFrontmatter", "Invalid frontmatter: frontmatter block was not closed with '---'", undefined, "frontmatter block was not closed with '---'");
+}
+function interpretFrontmatter(fields) {
+  let version = null;
+  let axis = "layer";
+  let title = null;
+  const metadata = Object.create(null);
+  for (const field of fields) {
+    switch (field.key.toLowerCase()) {
+      case "3md":
+        version = field.value;
+        break;
+      case "axis":
+        axis = trimWhitespace(field.value).toLowerCase();
+        break;
+      case "title":
+        title = field.value;
+        break;
+      default:
+        metadata[field.key] = field.value;
+        break;
+    }
+  }
+  if (version === null || version.length === 0) {
+    throw new ParseError("missingVersion", "Frontmatter is missing the required '3md' version key.");
+  }
+  return { version, axis, title, metadata };
+}
+function parseDirective(trimmed, line) {
+  const remainder = trimWhitespace(trimmed.slice("@plane".length));
+  const result = Object.create(null);
+  for (const token of tokenize(remainder, line)) {
+    const separator = token.indexOf("=");
+    if (separator < 0) {
+      throw new ParseError("invalidPlaneDirective", `Invalid @plane directive on line ${line}: expected key=value, found '${token}'`, line, `expected key=value, found '${token}'`);
+    }
+    const key = trimWhitespace(token.slice(0, separator)).toLowerCase();
+    const value = unquote(trimWhitespace(token.slice(separator + 1)));
+    if (key.length === 0) {
+      throw new ParseError("invalidPlaneDirective", `Invalid @plane directive on line ${line}: empty attribute key in '${token}'`, line, `empty attribute key in '${token}'`);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function optionalDouble(value, key, line) {
+  if (value === undefined) {
+    return null;
+  }
+  const parsed = parseFiniteDecimal(value);
+  if (parsed === null) {
+    throw new ParseError("invalidPlaneDirective", `Invalid @plane directive on line ${line}: ${key} must be a finite decimal number, found '${value}'`, line, `${key} must be a finite decimal number, found '${value}'`);
+  }
+  return parsed;
+}
+function makePlane(pending) {
+  const attributes = pending.attributes;
+  const line = pending.lineNumber;
+  const zRaw = attributes["z"];
+  if (zRaw === undefined) {
+    throw new ParseError("missingPlanePosition", `The @plane directive on line ${line} is missing a 'z' position.`, line);
+  }
+  const z = parseFiniteDecimal(zRaw);
+  if (z === null) {
+    throw new ParseError("invalidPlaneDirective", `Invalid @plane directive on line ${line}: z must be a finite decimal number, found '${zRaw}'`, line, `z must be a finite decimal number, found '${zRaw}'`);
+  }
+  const x = optionalDouble(attributes["x"], "x", line);
+  const y = optionalDouble(attributes["y"], "y", line);
+  const labelRaw = attributes["label"];
+  const label = labelRaw === undefined ? null : labelRaw;
+  const extras = Object.create(null);
+  for (const attributeKey of Object.keys(attributes)) {
+    if (!RESERVED_PLANE_KEYS.has(attributeKey)) {
+      const attributeValue = attributes[attributeKey];
+      if (attributeValue !== undefined) {
+        extras[attributeKey] = attributeValue;
+      }
+    }
+  }
+  const body = collapse(pending.bodyLines) ?? "";
+  return { z, label, x, y, attributes: extras, body };
+}
+function parseBody(lines, bodyStartLine) {
+  const seenZ = new Set;
+  const planes = [];
+  let pending = null;
+  const preambleLines = [];
+  let fence = null;
+  const flushPending = () => {
+    if (pending === null) {
+      return;
+    }
+    const plane = makePlane(pending);
+    if (seenZ.has(plane.z)) {
+      throw new ParseError("duplicatePlane", `Two planes share the same z position: ${plane.z}`, undefined, String(plane.z));
+    }
+    seenZ.add(plane.z);
+    planes.push(plane);
+  };
+  lines.forEach((raw, offset) => {
+    const lineNumber = bodyStartLine + offset;
+    const trimmed = trimWhitespace(raw);
+    let isDirective = false;
+    if (fence !== null) {
+      if (trimmed.startsWith(fence.repeat(3))) {
+        fence = null;
+      }
+    } else {
+      const opened = fenceCharacter(trimmed);
+      if (opened !== null) {
+        fence = opened;
+      } else if (raw[0] !== " " && raw[0] !== "\t" && firstToken(raw) === "@plane") {
+        isDirective = true;
+      }
+    }
+    if (!isDirective) {
+      if (pending !== null) {
+        pending.bodyLines.push(raw);
+      } else {
+        preambleLines.push(raw);
+      }
+      return;
+    }
+    flushPending();
+    const attributes = parseDirective(trimmed, lineNumber);
+    pending = { lineNumber, attributes, bodyLines: [] };
+  });
+  flushPending();
+  const preamble = collapse(preambleLines);
+  if (planes.length === 0) {
+    if (preamble === null) {
+      return { preamble: null, planes: [] };
+    }
+    return {
+      preamble: null,
+      planes: [{ z: 0, label: null, x: null, y: null, attributes: Object.create(null), body: preamble }]
+    };
+  }
+  return { preamble, planes };
+}
+function parse(source) {
+  let normalized = source.replace(/\r\n/g, `
+`);
+  if (normalized.charCodeAt(0) === 65279) {
+    normalized = normalized.slice(1);
+  }
+  const lines = normalized.split(`
+`);
+  const frontmatter = extractFrontmatter(lines);
+  const interpreted = interpretFrontmatter(frontmatter.fields);
+  const { preamble, planes } = parseBody(frontmatter.body, frontmatter.bodyStartLine);
+  return {
+    version: interpreted.version,
+    axis: interpreted.axis,
+    title: interpreted.title,
+    metadata: interpreted.metadata,
+    preamble,
+    planes
+  };
+}
+function links(document) {
+  const result = [];
+  const targets = new Set(document.planes.map((plane) => plane.z));
+  for (const plane of document.planes) {
+    const pattern = /\[\[z=([-+0-9eE.]{1,40})(?:\|([^\]\n]{0,400}))?\]\]/g;
+    let match = pattern.exec(plane.body);
+    while (match !== null) {
+      const targetZ = parseFiniteDecimal(match[1] ?? "");
+      if (targetZ !== null) {
+        const rawText = match[2];
+        result.push({
+          sourceZ: plane.z,
+          targetZ,
+          text: rawText === undefined ? null : rawText,
+          targetExists: targets.has(targetZ)
+        });
+      }
+      match = pattern.exec(plane.body);
+    }
+  }
+  return result;
+}
+function danglingLinks(document) {
+  return links(document).filter((link) => !link.targetExists);
+}
+function linkGraph(document) {
+  const edges = [];
+  const indexByKey = new Map;
+  for (const link of links(document)) {
+    const key = `${link.sourceZ}\x00${link.targetZ}`;
+    const index = indexByKey.get(key);
+    if (index === undefined) {
+      indexByKey.set(key, edges.length);
+      edges.push({
+        sourceZ: link.sourceZ,
+        targetZ: link.targetZ,
+        targetExists: link.targetExists,
+        count: 1
+      });
+    } else {
+      const existing = edges[index];
+      if (existing !== undefined) {
+        edges[index] = { ...existing, count: existing.count + 1 };
+      }
+    }
+  }
+  return edges;
+}
+function formatNumber(value) {
+  if (Number.isInteger(value) && Math.abs(value) < 1000000000000000) {
+    return String(value);
+  }
+  return String(value);
+}
+function quoteIfNeeded(value, forceQuote = false) {
+  const needsQuote = forceQuote || value.includes(" ") || value.includes("\t") || value.includes('"') || value.includes("\\") || value.length === 0;
+  if (!needsQuote) {
+    return value;
+  }
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+  return `"${escaped}"`;
+}
+function frontmatterLines(document) {
+  const lines = ["---", `3md: ${document.version}`, `axis: ${document.axis}`];
+  if (document.title !== null) {
+    lines.push(`title: ${quoteIfNeeded(document.title)}`);
+  }
+  for (const key of Object.keys(document.metadata).sort()) {
+    lines.push(`${key}: ${quoteIfNeeded(document.metadata[key] ?? "")}`);
+  }
+  lines.push("---");
+  return lines;
+}
+function directiveLine(plane) {
+  const parts = ["@plane", `z=${formatNumber(plane.z)}`];
+  if (plane.label !== null) {
+    parts.push(`label=${quoteIfNeeded(plane.label, true)}`);
+  }
+  if (plane.x !== null) {
+    parts.push(`x=${formatNumber(plane.x)}`);
+  }
+  if (plane.y !== null) {
+    parts.push(`y=${formatNumber(plane.y)}`);
+  }
+  for (const key of Object.keys(plane.attributes).sort()) {
+    parts.push(`${key}=${quoteIfNeeded(plane.attributes[key] ?? "", true)}`);
+  }
+  return parts.join(" ");
+}
+function serialize(document) {
+  const lines = frontmatterLines(document);
+  if (document.preamble !== null) {
+    lines.push("");
+    lines.push(document.preamble);
+  }
+  for (const plane of document.planes) {
+    lines.push("");
+    lines.push(directiveLine(plane));
+    if (plane.body.length > 0) {
+      lines.push(plane.body);
+    }
+  }
+  return lines.join(`
+`) + `
+`;
+}
+export {
+  serialize,
+  parse,
+  links,
+  linkGraph,
+  danglingLinks,
+  ParseError
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@corvidlabs/threemd",
+  "version": "1.0.0",
+  "description": "Parser and serializer for the 3md format: Markdown with a Z axis.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["3md", "markdown", "parser", "serializer", "z-axis", "file-format", "corvidlabs"],
+  "repository": { "type": "git", "url": "git+https://github.com/CorvidLabs/3md.git", "directory": "js" },
+  "homepage": "https://github.com/CorvidLabs/3md#readme",
+  "bugs": { "url": "https://github.com/CorvidLabs/3md/issues" },
+  "publishConfig": { "access": "public" },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.6.0"
+  }
+}