@suzumiyaaoba/mdxr 0.1.0

package/src/remark/code-file.ts

@@ -0,0 +1,85 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import type { Node } from "unist";
+import { visit } from "unist-util-visit";
+import type { VFile } from "vfile";
+
+import { langForPath } from "../langs.js";
+import { parseLineRange } from "../lines.js";
+import type { MdxTarget } from "./ast.js";
+import { isFlowElement, jsxAttr } from "./ast.js";
+
+/** A flow element that becomes a `code` node after mutation. */
+interface CodeTarget extends MdxTarget {
+  lang?: string;
+  meta?: string;
+}
+
+/**
+ * `<CodeFile path="src/foo.ts" lines="40-52" lang="ts" />` embeds a real file
+ * from disk as a fenced code block, so code explanations quote the actual
+ * source instead of drifting copies. `path` resolves relative to the
+ * document; `lines` slices a 1-based range; `lang` overrides the extension.
+ * The emitted `code` node carries `title="…"` meta so `remarkCodeMeta` /
+ * `Pre` render the usual filename header — run this before remarkCodeMeta.
+ */
+export const remarkCodeFile = () => (tree: Node, file: VFile) => {
+  visit(tree, "mdxJsxFlowElement", (node: Node) => {
+    if (!isFlowElement(node) || node.name !== "CodeFile") {
+      return;
+    }
+    const rel = jsxAttr(node, "path");
+    if (rel === undefined) {
+      file.fail(
+        "<CodeFile> requires a `path` attribute",
+        node,
+        "mdxr:code-file"
+      );
+    }
+    const abs = path.resolve(file.dirname ?? ".", rel);
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf-8");
+    } catch {
+      file.fail(`<CodeFile> cannot read ${rel}`, node, "mdxr:code-file");
+    }
+
+    const rangeSpec = jsxAttr(node, "lines");
+    let titleSuffix = "";
+    if (rangeSpec !== undefined) {
+      const range = parseLineRange(rangeSpec);
+      if (range === undefined) {
+        file.fail(
+          `<CodeFile> invalid lines range: ${rangeSpec}`,
+          node,
+          "mdxr:code-file"
+        );
+      }
+      const all = content.replace(/\n$/u, "").split("\n");
+      if (range.start > all.length) {
+        file.fail(
+          `<CodeFile> lines ${rangeSpec} out of range (${all.length} lines in ${rel})`,
+          node,
+          "mdxr:code-file"
+        );
+      }
+      content = all.slice(range.start - 1, range.end).join("\n");
+      titleSuffix = `:${rangeSpec}`;
+    }
+
+    // langForPath, not just extname: basename tables cover Makefile,
+    // Dockerfile, .gitignore — extensionless files still get a grammar.
+    const lang = jsxAttr(node, "lang") ?? langForPath(abs);
+    const target: CodeTarget = node;
+    target.type = "code";
+    delete target.name;
+    delete target.attributes;
+    delete target.children;
+    target.lang = lang;
+    // `"` inside a path would close the title="…" meta early — quote it as `'`.
+    const title = rel.replaceAll('"', "'");
+    target.meta = `title="${title}${titleSuffix}"`;
+    target.value = content;
+  });
+};

package/src/remark/code-meta.ts

@@ -0,0 +1,21 @@
+import type { Node } from "unist";
+import { visit } from "unist-util-visit";
+
+import { setHProperty } from "./ast.js";
+
+/**
+ * The mdast→hast conversion drops the code fence info string (`meta`).
+ * Copy it to `hProperties.meta` so it reaches the `pre` element's props.
+ */
+export const remarkCodeMeta = () => (tree: Node) => {
+  visit(tree, "code", (node: Node) => {
+    if (
+      !("meta" in node) ||
+      typeof node.meta !== "string" ||
+      node.meta === ""
+    ) {
+      return;
+    }
+    setHProperty(node, "meta", node.meta);
+  });
+};

package/src/remark/directives.ts

@@ -0,0 +1,170 @@
+import type { Node, Parent } from "unist";
+import { visit } from "unist-util-visit";
+import type { VFile } from "vfile";
+
+import { isRecord, own } from "../guards.js";
+import { isParent, textContent, toMdxElement } from "./ast.js";
+import { CALLOUT_KINDS, normalizeCalloutKind } from "./callouts.js";
+
+const CONTAINER_COMPONENTS: Record<string, string> = {
+  audit: "Audit",
+  barchart: "BarChart",
+  bench: "Bench",
+  benchmarks: "Benchmarks",
+  board: "Board",
+  bridge: "Bridge",
+  bump: "Bump",
+  bumps: "Bumps",
+  check: "Check",
+  checks: "Checks",
+  comment: "Comment",
+  comments: "Comments",
+  day: "Day",
+  dbfield: "DbField",
+  dbtable: "DbTable",
+  deps: "Deps",
+  endpoints: "Endpoints",
+  entry: "Entry",
+  envvar: "EnvVar",
+  envvars: "EnvVars",
+  files: "Files",
+  finding: "Finding",
+  findings: "Findings",
+  flow: "Flow",
+  funnel: "Funnel",
+  gantt: "Gantt",
+  gauge: "Gauge",
+  gauges: "Gauges",
+  graph: "Graph",
+  hypotheses: "Hypotheses",
+  hypothesis: "Hypothesis",
+  incident: "Incident",
+  linechart: "LineChart",
+  matrix: "Matrix",
+  package: "Package",
+  packages: "Packages",
+  pathway: "Pathway",
+  phase: "Phase",
+  piechart: "PieChart",
+  plan: "Plan",
+  quadrant: "Quadrant",
+  radar: "Radar",
+  release: "Release",
+  review: "Review",
+  sankey: "Sankey",
+  scatter: "Scatter",
+  schema: "Schema",
+  search: "Search",
+  searches: "Searches",
+  service: "Service",
+  statuspage: "StatusPage",
+  steps: "Steps",
+  stop: "Stop",
+  summary: "Summary",
+  terminal: "Terminal",
+  tests: "Tests",
+  timeline: "Timeline",
+  toc: "Toc",
+  trace: "Trace",
+  treemap: "Treemap",
+  uptime: "Uptime",
+  venn: "Venn",
+  verdict: "Verdict",
+  vuln: "Vuln",
+  waterfall: "Waterfall",
+};
+
+interface DirectiveNode extends Parent {
+  name: string;
+  attributes: Record<string, unknown>;
+}
+
+const isDirective = (n: Node): n is DirectiveNode =>
+  "name" in n &&
+  typeof n.name === "string" &&
+  "attributes" in n &&
+  isRecord(n.attributes) &&
+  isParent(n);
+
+/**
+ * remark-directive containers become mdxr components:
+ *   :::note[Optional label]        → <Callout kind="note" title="Optional label">
+ *   :::phase{title="X" status="doing"} → <Phase title="X" status="doing">
+ *   :::plan / :::steps / :::summary / :::timeline → Plan / Steps / Summary / Timeline
+ *   :::flow / :::findings / :::finding / :::files / :::deps
+ *     → Flow / Findings / Finding / Files / Deps
+ *   :::terminal / :::trace / :::hypotheses / :::hypothesis / :::searches / :::search
+ *     → Terminal / Trace / Hypotheses / Hypothesis / Searches / Search
+ *   :::barchart / :::linechart / :::piechart / :::scatter / :::radar
+ *     → BarChart / LineChart / PieChart / Scatter / Radar
+ *   :::funnel / :::quadrant / :::bridge / :::treemap / :::sankey / :::venn
+ *     → Funnel / Quadrant / Bridge / Treemap / Sankey / Venn
+ *   :::review / :::comment / :::checks / :::check / :::audit / :::vuln
+ *     → Review / Comment / Checks / Check / Audit / Vuln
+ *   :::bumps / :::bump / :::packages / :::package
+ *     → Bumps / Bump / Packages / Package
+ *   :::gauges / :::gauge / :::benchmarks / :::bench
+ *     → Gauges / Gauge / Benchmarks / Bench
+ *   :::schema / :::dbtable / :::dbfield / :::envvars / :::envvar
+ *     → Schema / DbTable / DbField / EnvVars / EnvVar
+ *   :::release / :::entry / :::pathway / :::stop / :::incident / :::verdict
+ *     → Release / Entry / Pathway / Stop / Incident / Verdict
+ *   :::statuspage / :::service / :::uptime / :::day
+ *     → StatusPage / Service / Uptime / Day
+ * `non-goal` is accepted as an alias of the `nongoal` callout kind.
+ */
+export const remarkMdxrDirectives = () => (tree: Node, file: VFile) => {
+  visit(
+    tree,
+    ["containerDirective", "leafDirective", "textDirective"],
+    (node: Node) => {
+      if (!isDirective(node)) {
+        return;
+      }
+      const directive = node;
+      const name = normalizeCalloutKind(directive.name);
+      const isContainer = directive.type === "containerDirective";
+      // own-property lookup: `:::toString` would otherwise resolve to
+      // Object.prototype.toString and be "rendered" as a component name.
+      const container = own(CONTAINER_COMPONENTS, name);
+      const component = CALLOUT_KINDS.has(name) ? "Callout" : container;
+      if (component === undefined) {
+        file.message(
+          `Unknown directive ":::${directive.name}"`,
+          directive,
+          "mdxr:directives"
+        );
+        return;
+      }
+      if (!isContainer) {
+        file.message(
+          `:::${directive.name} is a container directive — use three colons`,
+          directive,
+          "mdxr:directives"
+        );
+        return;
+      }
+
+      const attrs: Record<string, unknown> = { ...directive.attributes };
+
+      const [first] = directive.children;
+      const isLabel =
+        first !== undefined &&
+        isRecord(first.data) &&
+        first.data.directiveLabel === true;
+      if (isLabel) {
+        attrs.title ??= textContent(first).trim();
+        directive.children.shift();
+      }
+
+      if (component === "Callout") {
+        toMdxElement(directive, "mdxJsxFlowElement", "Callout", {
+          kind: name,
+          ...attrs,
+        });
+      } else {
+        toMdxElement(directive, "mdxJsxFlowElement", component, attrs);
+      }
+    }
+  );
+};

package/src/remark/file-paths.ts

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import type { Node } from "unist";
+import { visitParents } from "unist-util-visit-parents";
+import type { VFile } from "vfile";
+
+import { splitPathLines } from "../lines.js";
+import type { MdxTarget } from "./ast.js";
+import { toMdxElement } from "./ast.js";
+
+/**
+ * Inline code that names a real file path — `` `src/mdx.ts` `` — becomes a
+ * `<FileRef>` chip, so prose references get the same editor link, icon, and
+ * copy button as an explicit component. The value must contain a `/` (a bare
+ * `file.ts` stays code) and resolve to an existing file relative to the
+ * document; a trailing `:N`/`:N-M` becomes `lines`. Paths inside links are
+ * left alone — a chip can't nest inside <a>. Runs late in the pipeline so
+ * directive labels and heading slugs are already computed.
+ */
+export const remarkFilePaths = () => (tree: Node, file: VFile) => {
+  const dir = file.dirname ?? ".";
+  const resolve = (
+    value: string
+  ): { lines?: string; path: string } | undefined => {
+    if (!value.includes("/") || value.includes("://")) {
+      return undefined;
+    }
+    const target = splitPathLines(value);
+    if (existsSync(path.resolve(dir, target.path))) {
+      return target;
+    }
+    // A file literally named "x.ts:2" beats the lines interpretation.
+    return target.lines !== undefined && existsSync(path.resolve(dir, value))
+      ? { path: value }
+      : undefined;
+  };
+  visitParents(tree, "inlineCode", (node: Node, ancestors: Node[]) => {
+    // Links keep plain code — FileRef renders its own <a>, and nested
+    // anchors break in the HTML parser. Raw JSX <a> wrappers count too:
+    // they're mdxJsx elements, not "link" nodes.
+    const inLink = ancestors.some(
+      (a) =>
+        a.type === "link" ||
+        a.type === "linkReference" ||
+        ((a.type === "mdxJsxTextElement" || a.type === "mdxJsxFlowElement") &&
+          (a as MdxTarget).name === "a")
+    );
+    if (inLink || !("value" in node) || typeof node.value !== "string") {
+      return;
+    }
+    const target = resolve(node.value);
+    if (target === undefined) {
+      return;
+    }
+    const el: MdxTarget = node;
+    toMdxElement(el, "mdxJsxTextElement", "FileRef", {
+      lines: target.lines,
+      path: target.path,
+    });
+    el.children = [];
+    delete el.value;
+  });
+};

package/src/remark/headings.ts

@@ -0,0 +1,131 @@
+import type { Node, Parent } from "unist";
+import { visit } from "unist-util-visit";
+
+import { isFlowElement, jsxAttr, setHProperty, textContent } from "./ast.js";
+
+interface HeadingNode extends Parent {
+  depth: number;
+  type: "heading";
+}
+
+const isHeading = (n: Node): n is HeadingNode => n.type === "heading";
+
+/** GitHub-style slug: lowercase, punctuation stripped, spaces → `-`. */
+const slugify = (text: string): string =>
+  text
+    .toLowerCase()
+    .trim()
+    .replaceAll(/[^\p{L}\p{N}_\s-]/gu, "")
+    .replaceAll(/\s+/gu, "-");
+
+/** Positive-int attribute or fallback — "0"/"abc" both become `fallback`. */
+const depthAttr = (
+  node: Parameters<typeof jsxAttr>[0],
+  name: string,
+  fallback: number
+): number => {
+  const raw = jsxAttr(node, name);
+  const n = Number(raw);
+  return raw === undefined || !Number.isInteger(n) || n < 1 ? fallback : n;
+};
+
+interface TocItem {
+  children: TocItem[];
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+/** Nest a flat heading list by depth (an h3 under the previous h2, …). */
+const nest = (headings: TocItem[]): TocItem[] => {
+  const roots: TocItem[] = [];
+  const stack: TocItem[] = [];
+  for (const h of headings) {
+    while (stack.length > 0 && (stack.at(-1)?.depth ?? 0) >= h.depth) {
+      stack.pop();
+    }
+    const parent = stack.at(-1);
+    if (parent === undefined) {
+      roots.push(h);
+    } else {
+      parent.children.push(h);
+    }
+    stack.push(h);
+  }
+  return roots;
+};
+
+interface ListNode extends Parent {
+  ordered?: boolean;
+  spread?: boolean;
+}
+
+const toList = (items: TocItem[]): ListNode => ({
+  children: items.map((item) => ({
+    children: [
+      {
+        children: [
+          {
+            children: [{ type: "text", value: item.text }],
+            type: "link",
+            url: `#${item.slug}`,
+          },
+        ],
+        type: "paragraph",
+      },
+      ...(item.children.length > 0 ? [toList(item.children)] : []),
+    ],
+    spread: false,
+    type: "listItem",
+  })),
+  ordered: false,
+  spread: false,
+  type: "list",
+});
+
+/**
+ * Two jobs, one pass over the document:
+ * 1. Every heading gets an `id` (GitHub-style slug, deduplicated), enabling
+ *    deep links.
+ * 2. `<Toc>` elements (`:::toc` included) get a nested link list injected as
+ *    children — `depth`/`min` attributes bound the heading levels included
+ *    (defaults: h2–h3, i.e. min=2 depth=3).
+ */
+export const remarkMdxrHeadings = () => (tree: Node) => {
+  const counts = new Map<string, number>();
+  const used = new Set<string>();
+  const headings: TocItem[] = [];
+
+  visit(tree, "heading", (node: Node) => {
+    if (!isHeading(node)) {
+      return;
+    }
+    const text = textContent(node).trim();
+    const base = slugify(text) || "section";
+    let count = counts.get(base) ?? 0;
+    let slug = count === 0 ? base : `${base}-${count}`;
+    // A suffixed slug can still collide with a literal heading ("a-1" after
+    // "a","a" generates a-1 first) — keep bumping until the id is unused.
+    while (used.has(slug)) {
+      count += 1;
+      slug = `${base}-${count}`;
+    }
+    counts.set(base, count + 1);
+    used.add(slug);
+
+    setHProperty(node, "id", slug);
+    headings.push({ children: [], depth: node.depth, slug, text });
+  });
+
+  visit(tree, "mdxJsxFlowElement", (node: Node) => {
+    if (!isFlowElement(node) || node.name !== "Toc") {
+      return;
+    }
+    const minDepth = depthAttr(node, "min", 2);
+    const maxDepth = depthAttr(node, "depth", 3);
+    const items = headings.filter(
+      (h) => h.depth >= minDepth && h.depth <= maxDepth && h.text !== ""
+    );
+    node.children = items.length === 0 ? [] : [toList(nest(items))];
+  });
+};

package/src/remark/no-js.ts

@@ -0,0 +1,40 @@
+import type { Node } from "unist";
+import { visit } from "unist-util-visit";
+import type { VFile } from "vfile";
+
+import { isRecord } from "../guards.js";
+
+const JS_NODES = ["mdxjsEsm", "mdxFlowExpression", "mdxTextExpression"];
+const JSX_ELEMENTS = ["mdxJsxFlowElement", "mdxJsxTextElement"];
+
+const MESSAGE =
+  "JavaScript expressions and import/export statements are not allowed in mdxr documents. Add a component via mdxr.config.ts instead.";
+
+/**
+ * mdxr documents are data, not code: reject ESM imports/exports and JS
+ * expressions (`{...}`) — including inside JSX attributes (`prop={x}`,
+ * `{...spread}`), which `visit` never reaches because attributes are not
+ * children. Extensibility happens through mdxr.config.ts, not through
+ * executable markup inside the document.
+ */
+export const remarkNoJs = () => (tree: Node, file: VFile) => {
+  visit(tree, JS_NODES, (node: Node) => {
+    file.fail(MESSAGE, node, "mdxr:no-js");
+  });
+  visit(tree, JSX_ELEMENTS, (node: Node) => {
+    if (!("attributes" in node) || !Array.isArray(node.attributes)) {
+      return;
+    }
+    for (const attr of node.attributes) {
+      // String-valued attributes are data; `{expr}` values and `{...x}`
+      // spreads are live JavaScript evaluated at render time.
+      if (
+        isRecord(attr) &&
+        (attr.type !== "mdxJsxAttribute" ||
+          (attr.value !== null && typeof attr.value !== "string"))
+      ) {
+        file.fail(MESSAGE, node, "mdxr:no-js");
+      }
+    }
+  });
+};