explico 0.12.0 → 0.13.1

package/dist/compiler/exports/markdown/serialize.js

@@ -0,0 +1,527 @@
+import { gfmTableToMarkdown } from "mdast-util-gfm-table";
+import { mathToMarkdown } from "mdast-util-math";
+import { toMarkdown } from "mdast-util-to-markdown";
+import { captionTitle } from "../../../components/float-name.js";
+import { stripNotationMarkers } from "../../../reference/math-glyphs.mjs";
+const text = (value) => ({ type: "text", value });
+const html = (value) => ({ type: "html", value });
+const strong = (children) => ({ type: "strong", children });
+const emphasis = (children) => ({ type: "emphasis", children });
+const paragraph = (children) => ({ type: "paragraph", children });
+const link = (url, children) => ({ type: "link", url, children });
+const anchor = (id) => html(`<a id="${id.replace(/"/gu, "&quot;")}"></a>`);
+function plainTex(tex) {
+  return stripNotationMarkers(tex).trim();
+}
+function cellTex(tex) {
+  return tex.replace(/\\\|/gu, "\\Vert ").replace(/\|/gu, "\\vert ");
+}
+const ALERTS = {
+  note: "NOTE",
+  tip: "TIP",
+  caution: "WARNING",
+  danger: "CAUTION"
+};
+function plainText(inlines) {
+  return inlines.map((inline) => {
+    switch (inline.kind) {
+      case "text":
+      case "code":
+        return inline.value;
+      case "math":
+        return plainTex(inline.tex);
+      case "break":
+        return " ";
+      case "cite":
+        return `[${inline.number}]`;
+      case "memoMark":
+        return inline.label;
+      default:
+        return "children" in inline ? plainText(inline.children) : "";
+    }
+  }).join("");
+}
+function diagramEdges(geometry) {
+  const nearest = ([x, y]) => {
+    let best = -1;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    geometry.nodes.forEach((node, index) => {
+      const dx = Math.max(node.x - x, 0, x - (node.x + node.width));
+      const dy = Math.max(node.y - y, 0, y - (node.y + node.height));
+      const distance = Math.hypot(dx, dy);
+      if (distance < bestDistance) [best, bestDistance] = [index, distance];
+    });
+    return best;
+  };
+  return geometry.edges.flatMap((edge) => {
+    const start = edge[0];
+    const end = edge.at(-1);
+    if (!start || !end) return [];
+    const from = nearest(start);
+    const to = nearest(end);
+    return from === -1 || to === -1 || from === to ? [] : [[from, to]];
+  });
+}
+class MarkdownWriter {
+  constructor(context) {
+    this.context = context;
+    this.route = context.page.route;
+    this.notationAnchors = new Map(context.page.notation.map((entry) => [entry.key, entry.anchor]));
+  }
+  context;
+  route;
+  notationAnchors;
+  /** The link to an anchor on a page: into its file when the download has it, else the website. */
+  targetUrl(target) {
+    const file = this.context.documentFiles.get(target.route);
+    if (file !== void 0) {
+      if (!target.anchor) return file || "#";
+      return `${file}#${target.anchor}`;
+    }
+    const base = this.context.canonicalBaseUrl;
+    if (!base) return void 0;
+    return `${base}${target.route ? `${target.route}/` : ""}${target.anchor ? `#${target.anchor}` : ""}`;
+  }
+  inline(inline, inTable = false) {
+    switch (inline.kind) {
+      case "text":
+        return [text(inline.value)];
+      case "emphasis":
+        return [emphasis(this.inlines(inline.children, inTable))];
+      case "strong":
+        return [strong(this.inlines(inline.children, inTable))];
+      case "superscript":
+        return [html("<sup>"), ...this.inlines(inline.children, inTable), html("</sup>")];
+      case "subscript":
+        return [html("<sub>"), ...this.inlines(inline.children, inTable), html("</sub>")];
+      case "code":
+        return [{ type: "inlineCode", value: inline.value }];
+      case "math": {
+        const tex = plainTex(inline.tex);
+        return tex ? [{ type: "inlineMath", value: inTable ? cellTex(tex) : tex }] : [];
+      }
+      case "break":
+        return inTable ? [html("<br>")] : [{ type: "break" }];
+      case "link":
+        return [link(inline.href, this.inlines(inline.children, inTable))];
+      case "ref": {
+        const url = this.targetUrl(inline.target);
+        const children = this.inlines(inline.children, inTable);
+        return url ? [link(url, children)] : children;
+      }
+      case "term": {
+        const target = this.notationAnchors.get(inline.key);
+        const children = this.inlines(inline.children, inTable);
+        return target ? [link(`#${target}`, children)] : children;
+      }
+      case "cite":
+        return [link(`#${inline.anchor}`, [text(`[${inline.number}]`)])];
+      case "memoMark":
+        return [html("<sup>"), link(`#${inline.anchor}`, [text(inline.label)]), html("</sup>")];
+      case "noteMark":
+        return [link(`#${inline.anchor}`, this.inlines(inline.children, inTable))];
+    }
+  }
+  inlines(inlines, inTable = false) {
+    return inlines.flatMap((inline) => this.inline(inline, inTable));
+  }
+  /** A choice's label, its math as math like the prompt's. */
+  optionLabel(option) {
+    return option.labelSegments ? this.segments(option.labelSegments) : [text(option.label)];
+  }
+  segments(segments) {
+    return segments.flatMap(
+      (segment) => segment.type === "math" ? [{ type: "inlineMath", value: plainTex(segment.latex) }] : [text(segment.value)]
+    );
+  }
+  /** A float's caption line: its number and short caption in bold, then the long one. */
+  captionLine(label, block, extra = []) {
+    const short = block.short?.trim();
+    const head = short ? `${label}. ${captionTitle(short)}` : `${label}.`;
+    const long = [...this.inlines(block.caption), ...extra.length > 0 ? [text(" "), ...this.inlines(extra)] : []];
+    return [strong([text(head)]), ...long.length > 0 ? [text(" "), ...long] : []];
+  }
+  picture(key, alt) {
+    const file = this.context.pictures.get(key);
+    return file ? { type: "image", url: file, alt } : void 0;
+  }
+  table(block) {
+    const rows = [...block.head, ...block.body];
+    const spans = rows.some((row2) => row2.some((cell2) => cell2.colspan > 1 || cell2.rowspan > 1));
+    const caption = block.number ? [paragraph([anchor(block.anchor), ...this.captionLine(`Table ${block.number}`, block)])] : [];
+    if (spans) return [...caption, ...this.htmlTable(block)];
+    const columns = Math.max(0, ...rows.map((row2) => row2.length));
+    if (columns === 0) return caption;
+    const cell = (source) => ({
+      type: "tableCell",
+      children: source ? this.inlines(source.children, true) : []
+    });
+    const row = (cells) => ({
+      type: "tableRow",
+      children: Array.from({ length: columns }, (_, index) => cell(cells[index]))
+    });
+    const head = block.head[0] ?? [];
+    const firstBody = block.body[0] ?? head;
+    const table = {
+      type: "table",
+      align: Array.from({ length: columns }, (_, index) => (firstBody[index] ?? head[index])?.align ?? null),
+      children: [row(head), ...block.head.slice(1).map(row), ...block.body.map(row)]
+    };
+    return [...caption, table];
+  }
+  /**
+   * A table with spanning cells as HTML, which pipe tables cannot hold. Each
+   * cell's content stands on lines of its own, so Markdown (and its math)
+   * still reads it.
+   */
+  htmlTable(block) {
+    const cellHtml = (cell) => {
+      const tag = cell.header ? "th" : "td";
+      const attributes = [
+        ...cell.colspan > 1 ? [`colspan="${cell.colspan}"`] : [],
+        ...cell.rowspan > 1 ? [`rowspan="${cell.rowspan}"`] : [],
+        ...cell.align ? [`align="${cell.align}"`] : []
+      ];
+      const content = serializeNodes([paragraph(this.inlines(cell.children))]).trim();
+      return [`<${tag}${attributes.length > 0 ? ` ${attributes.join(" ")}` : ""}>`, "", content, "", `</${tag}>`];
+    };
+    const lines = [
+      "<table>",
+      ...block.head.flatMap((row) => ["<tr>", ...row.flatMap(cellHtml), "</tr>"]),
+      ...block.body.flatMap((row) => ["<tr>", ...row.flatMap(cellHtml), "</tr>"]),
+      "</table>"
+    ];
+    return [{ type: "html", value: lines.join("\n") }];
+  }
+  /** A diagram's boxes and arrows as a list: what the picture shows, as text. */
+  diagramText(geometry) {
+    const label = (index) => {
+      const node = geometry.nodes[index];
+      return [
+        ...node.text ? [text(node.text)] : [],
+        ...node.text && node.tex ? [text(" ")] : [],
+        ...node.tex ? [{ type: "inlineMath", value: plainTex(node.tex) }] : []
+      ];
+    };
+    const edges = diagramEdges(geometry);
+    const joined = new Set(edges.flat());
+    const items = [
+      ...edges.map(([from, to]) => ({
+        type: "listItem",
+        spread: false,
+        children: [paragraph([...label(from), text(" \u2192 "), ...label(to)])]
+      })),
+      ...geometry.nodes.map((_, index) => index).filter((index) => !joined.has(index)).map((index) => ({ type: "listItem", spread: false, children: [paragraph(label(index))] }))
+    ];
+    if (items.length === 0) return [];
+    return [
+      paragraph([emphasis([text("The diagram as text:")])]),
+      { type: "list", ordered: false, spread: false, children: items }
+    ];
+  }
+  /** A titled quote: a memo, a short note, an example set, a check. */
+  quote(title, children, id) {
+    return {
+      type: "blockquote",
+      children: [paragraph([...id ? [anchor(id)] : [], strong(title)]), ...children]
+    };
+  }
+  check(block) {
+    const items = this.context.checkItems.get(block.assessmentId) ?? [];
+    const questions = {
+      type: "list",
+      ordered: true,
+      spread: false,
+      children: items.map((item) => ({
+        type: "listItem",
+        spread: false,
+        children: [
+          paragraph(this.segments(item.promptSegments)),
+          ...item.type === "single-choice" && item.options && item.options.length > 0 ? [
+            {
+              type: "list",
+              ordered: false,
+              spread: false,
+              children: item.options.map(
+                (option, index) => ({
+                  type: "listItem",
+                  spread: false,
+                  children: [
+                    paragraph([text(`(${String.fromCharCode(97 + index)}) `), ...this.optionLabel(option)])
+                  ]
+                })
+              )
+            }
+          ] : []
+        ]
+      }))
+    };
+    return this.quote(
+      [text(`Knowledge check ${block.number}: `), ...this.inlines(block.title)],
+      [
+        ...items.length > 0 ? [questions] : [],
+        paragraph([emphasis([text("Answers: "), link("#answers", [text("end of the chapter")]), text(".")])])
+      ],
+      block.anchor
+    );
+  }
+  block(block, inBox = false) {
+    switch (block.kind) {
+      case "heading": {
+        const content = [
+          ...block.anchor ? [anchor(block.anchor)] : [],
+          ...block.number ? [text(`${block.number} `)] : [],
+          ...this.inlines(block.children)
+        ];
+        if (inBox) return [paragraph([strong(content)])];
+        const depth = Math.min(Math.max(block.level, 2), 6);
+        return [{ type: "heading", depth, children: content }];
+      }
+      case "paragraph": {
+        const children = this.inlines(block.children);
+        return children.length > 0 ? [paragraph(children)] : [];
+      }
+      case "list":
+        return [
+          {
+            type: "list",
+            ordered: block.ordered,
+            ...block.ordered && block.start ? { start: block.start } : {},
+            spread: false,
+            children: block.items.map((item) => ({
+              type: "listItem",
+              spread: false,
+              children: this.blocks(item, inBox)
+            }))
+          }
+        ];
+      case "equation":
+        return [
+          paragraph([anchor(block.anchor)]),
+          { type: "math", value: `${plainTex(block.tex)}
+\\tag{${block.number}}` }
+        ];
+      case "displayMath":
+        return [{ type: "math", value: plainTex(block.tex) }];
+      case "figure": {
+        const alt = block.alt ?? [block.short && captionTitle(block.short), plainText(block.caption)].filter(Boolean).join(" ");
+        const image = this.picture(block.anchor, alt || "Figure");
+        const missing = [
+          emphasis([
+            text("Interactive figure"),
+            ...this.context.canonicalBaseUrl ? [text(": "), link(`${this.context.canonicalBaseUrl}${this.route}/#${block.anchor}`, [text("see it on the course website")])] : [],
+            text(".")
+          ])
+        ];
+        return [
+          paragraph([anchor(block.anchor), ...image ? [image] : missing]),
+          paragraph(this.captionLine(`Figure ${block.number}`, block, block.live))
+        ];
+      }
+      case "diagram": {
+        const image = this.picture(block.anchor, block.short ?? plainText(block.caption) ?? "Diagram");
+        return [
+          paragraph([anchor(block.anchor), ...image ? [image] : []]),
+          paragraph(this.captionLine(`Diagram ${block.number}`, block)),
+          ...this.diagramText(block.geometry)
+        ];
+      }
+      case "table":
+        return this.table(block);
+      case "memo":
+        return [
+          this.quote(
+            [text(`Memo ${block.label}: `), ...this.inlines(block.title)],
+            this.blocks(block.children, true),
+            block.anchor
+          )
+        ];
+      case "note":
+        return [this.quote([text(block.title)], this.blocks(block.children, true), block.anchor)];
+      case "aside": {
+        const title = this.inlines(block.title);
+        return [
+          {
+            type: "blockquote",
+            children: [
+              paragraph([
+                html(`[!${ALERTS[block.variant] ?? "NOTE"}]`),
+                ...title.length > 0 ? [text("\n"), strong(title)] : []
+              ]),
+              ...this.blocks(block.children, true)
+            ]
+          }
+        ];
+      }
+      case "fold":
+        return [
+          ...block.title && block.title.length > 0 ? [paragraph([strong(this.inlines(block.title))])] : [],
+          ...this.blocks(block.children, inBox)
+        ];
+      case "examples":
+        return [
+          this.quote(
+            [text(`Example ${block.number}: `), ...this.inlines(block.title)],
+            block.items.flatMap((item) => [paragraph([strong(this.inlines(item.title))]), ...this.blocks(item.children, true)]),
+            block.anchor
+          )
+        ];
+      case "check":
+        return [this.check(block)];
+      case "quote":
+        return [{ type: "blockquote", children: this.blocks(block.children, inBox) }];
+      case "image": {
+        const image = this.picture(block.src, block.alt);
+        return image ? [paragraph([image])] : [];
+      }
+      case "code":
+        return [{ type: "code", value: block.value }];
+      case "rule":
+        return [{ type: "thematicBreak" }];
+      case "references":
+        return [
+          { type: "heading", depth: 2, children: [text("References")] },
+          {
+            type: "list",
+            ordered: true,
+            start: Number.parseInt(block.items[0]?.number ?? "1", 10) || 1,
+            spread: false,
+            children: block.items.map((item) => ({
+              type: "listItem",
+              spread: false,
+              children: [paragraph([anchor(item.anchor), ...this.inlines(item.children)])]
+            }))
+          }
+        ];
+    }
+  }
+  blocks(blocks, inBox = false) {
+    return blocks.flatMap((block) => this.block(block, inBox));
+  }
+  notation(entries, remarks) {
+    if (entries.length === 0) return [];
+    return [
+      { type: "heading", depth: 2, children: [text("Notation")] },
+      ...remarks.map((remark) => paragraph([emphasis(this.inlines(remark))])),
+      {
+        type: "list",
+        ordered: false,
+        spread: false,
+        children: entries.map((entry) => {
+          const symbol = entry.symbolTex ? plainTex(entry.symbolTex) : "";
+          const line = [
+            anchor(entry.anchor),
+            ...symbol ? [{ type: "inlineMath", value: symbol }, text(" ")] : [],
+            strong([...this.inlines(entry.label), text(".")]),
+            ...entry.summary.length > 0 ? [text(" "), ...this.inlines(entry.summary)] : [],
+            ...entry.units ? [text(" "), emphasis([text("Units:")]), text(" "), ...this.inlines(entry.units), text(".")] : []
+          ];
+          return {
+            type: "listItem",
+            spread: false,
+            children: [
+              paragraph(line),
+              ...entry.formulaTex ? [{ type: "math", value: plainTex(entry.formulaTex) }] : []
+            ]
+          };
+        })
+      }
+    ];
+  }
+  answers(checks) {
+    if (checks.length === 0) return [];
+    return [
+      { type: "heading", depth: 2, children: [anchor("answers"), text("Answers to the knowledge checks")] },
+      ...checks.flatMap((check) => {
+        const items = this.context.checkItems.get(check.assessmentId) ?? [];
+        return [
+          paragraph([
+            strong([link(`#${check.anchor}`, [text(`Knowledge check ${check.number}`)]), text(": "), ...this.inlines(check.title)])
+          ]),
+          {
+            type: "list",
+            ordered: true,
+            spread: false,
+            children: items.map((item) => {
+              const answer = [];
+              if (item.type === "single-choice" && item.options) {
+                const index = item.options.findIndex((option) => option.id === item.correctOptionId);
+                if (index !== -1) {
+                  answer.push(
+                    strong([text(`(${String.fromCharCode(97 + index)}) `), ...this.optionLabel(item.options[index]), text(".")]),
+                    text(" ")
+                  );
+                }
+              } else if (item.type === "numeric" && item.answer) {
+                answer.push(
+                  strong([text(String(item.answer.value))]),
+                  text(` (accepted within \xB1${item.answer.tolerance}). `)
+                );
+              }
+              return { type: "listItem", spread: false, children: [paragraph([...answer, ...this.segments(item.explanationSegments)])] };
+            })
+          }
+        ];
+      })
+    ];
+  }
+}
+function serializeNodes(children) {
+  const root = { type: "root", children };
+  return toMarkdown(root, {
+    bullet: "-",
+    emphasis: "*",
+    strong: "*",
+    fence: "`",
+    fences: true,
+    rule: "-",
+    listItemIndent: "one",
+    incrementListMarker: true,
+    extensions: [gfmTableToMarkdown(), mathToMarkdown()]
+  });
+}
+function checksOf(blocks) {
+  const checks = [];
+  const visit = (list) => {
+    for (const block of list) {
+      if (block.kind === "check") checks.push(block);
+      if (block.kind === "list") block.items.forEach(visit);
+      if (block.kind === "examples") block.items.forEach((item) => visit(item.children));
+      if ("children" in block && Array.isArray(block.children) && block.kind !== "paragraph" && block.kind !== "heading") {
+        visit(block.children);
+      }
+    }
+  };
+  visit(blocks);
+  return checks;
+}
+function serializeMarkdownPage(context, options = {}) {
+  const writer = new MarkdownWriter(context);
+  const { page, source } = context;
+  const sourceLine = source ? [
+    text("From "),
+    emphasis([text(source.course)]),
+    ...source.version ? [text(`, version ${source.version}`)] : [],
+    text("."),
+    ...source.url ? [text(" Interactive version: "), link(source.url, [text(source.url)]), text(".")] : []
+  ] : [];
+  return serializeNodes([
+    {
+      type: "heading",
+      depth: 1,
+      children: [anchor("_top"), ...options.number ? [text(`${options.number} `)] : [], text(page.title)]
+    },
+    ...sourceLine.length > 0 ? [paragraph(sourceLine)] : [],
+    ...writer.blocks(page.blocks),
+    ...writer.notation(page.notation, page.notationRemarks),
+    ...writer.answers(checksOf(page.blocks))
+  ]);
+}
+function serializeMarkdownNodes(children) {
+  return serializeNodes(children);
+}
+export {
+  diagramEdges,
+  serializeMarkdownNodes,
+  serializeMarkdownPage
+};

package/dist/compiler/exports/markdown-export.d.ts

@@ -0,0 +1,39 @@
+import { Manifest } from '../manifest.js';
+import { ExportLogger, PreparedChapters } from './export-chapters.js';
+import '../../curriculum/validation.js';
+import '../../reference/consistency.js';
+import '../../course-config-rRtME5UV.js';
+import '../../rules/catalog.js';
+import '../../rules/course-rules.js';
+import '../collections.js';
+import '../../reference/types.js';
+import '../../reference/gate-retired-keys.js';
+import '../../reference/lint-ignore.js';
+import '../../reference/equations-validate.js';
+import '../../reference/tables-validate.js';
+import '../../reference/keyed-float-validate.js';
+import '../../reference/figures-validate.js';
+import '../../reference/diagrams-validate.js';
+import '../../reference/examples-validate.js';
+import '../../reference/folds-validate.js';
+import '../../reference/knowledge-checks-validate.js';
+import '../../reference/raw-floats-validate.js';
+import '../../reference/lab-katex-validate.js';
+import '../../reference/gate-math.js';
+import '../../reference/mixed-content.js';
+import '../../reference/gloss.js';
+import '../../rules/waivers.js';
+import '../knowledge-version.js';
+import '../lesson-derivation.js';
+import './static-tree.js';
+import './html-tree.js';
+import 'parse5';
+import './latex/capture.js';
+
+declare function writeMarkdownExports(directory: URL, manifest: Manifest, options?: {
+    readonly logger?: ExportLogger;
+    readonly projectRoot?: string;
+    readonly prepared?: PreparedChapters;
+}): Promise<void>;
+
+export { writeMarkdownExports };