afterpresets 0.2.0 → 0.3.0

package/runtime/scripts/ae-sdk-docs/convert.js

@@ -0,0 +1,430 @@
+"use strict";
+
+// Markdown clean-up for one page of the After Effects SDK guide (MkDocs
+// source). Turns what only renders well in a browser into compact Markdown an
+// agent reads cheaply:
+//
+//   grid tables       (+----+ ... +====+, padded to the widest cell, which is
+//                      most of the guide's bytes) -> pipe tables when every cell
+//                      is one short line, otherwise one list item per row
+//   <pre lang="cpp">  (function signatures inside table cells, with <br/> as
+//                      line breaks) -> fenced code blocks
+//   !!! note          admonitions -> "> **Note:** ..." quotes
+//   ---               horizontal rules -> dropped
+//   ![alt](img.png)   screenshots -> "(Screenshot: alt)"
+//
+// Code fences pass through untouched. Links are left alone here; split.js
+// rewrites them once it knows which output file holds each heading.
+
+const FENCE = /^(\s*)(`{3,}|~{3,})/;
+const GRID_BORDER = /^\s*\+[-=:+]+\+\s*$/;
+const ADMONITION = /^(\s*)(!!!|\?\?\?\+?)\s+([A-Za-z]+)(?:\s+"([^"]*)")?\s*$/;
+const RULE = /^\s*(-{3,}|\*{3,}|_{3,})\s*$/;
+const PIPE_SEPARATOR = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
+const PIPE_TABLE_MAX_LINE = 180;
+
+/** Heading slugs the way Python-Markdown's toc extension makes them (MkDocs default). */
+function slugify(text) {
+  const plain = stripInline(text)
+    .normalize("NFKD")
+    .replace(/[^\x00-\x7f]/g, "");
+  return plain
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .toLowerCase()
+    .replace(/[-\s]+/g, "-");
+}
+
+/** Heading text without Markdown: what the browser shows. */
+function stripInline(text) {
+  return String(text)
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .replace(/[`*]/g, "")
+    .replace(/\\(.)/g, "$1")
+    .trim();
+}
+
+/** Assigns unique slugs in document order: "x", "x_1", "x_2" like Python-Markdown. */
+function uniqueSlugger() {
+  const seen = new Set();
+  return function (text) {
+    const base = slugify(text);
+    let slug = base;
+    let n = 1;
+    while (seen.has(slug)) slug = base + "_" + n++;
+    seen.add(slug);
+    return slug;
+  };
+}
+
+/** <pre> content in the guide escapes "*" as Markdown ("\\*"); in C it is always a plain "*". */
+function preText(text) {
+  return decodeEntities(text).replace(/\\\*/g, "*");
+}
+
+function decodeEntities(text) {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&");
+}
+
+function isFenceOpen(line) {
+  return FENCE.test(line);
+}
+
+/** Index after the fence that opens at `start` (or lines.length if unclosed). */
+function fenceEnd(lines, start) {
+  const m = lines[start].match(FENCE);
+  const marker = m[2][0];
+  const len = m[2].length;
+  for (let i = start + 1; i < lines.length; i++) {
+    const close = lines[i].match(/^\s*(`{3,}|~{3,})\s*$/);
+    if (close && close[1][0] === marker && close[1].length >= len) return i + 1;
+  }
+  return lines.length;
+}
+
+function dedent(lines) {
+  let min = Infinity;
+  lines.forEach((l) => {
+    if (l.trim()) min = Math.min(min, l.match(/^ */)[0].length);
+  });
+  if (!isFinite(min) || min === 0) return lines.slice();
+  return lines.map((l) => l.slice(Math.min(min, l.match(/^ */)[0].length)));
+}
+
+function trimBlankEdges(lines) {
+  let a = 0;
+  let b = lines.length;
+  while (a < b && !lines[a].trim()) a++;
+  while (b > a && !lines[b - 1].trim()) b--;
+  return lines.slice(a, b);
+}
+
+// ---------------------------------------------------------------------------
+// Grid tables
+
+/**
+ * Parses a pandoc/markdown_grid_tables table. Returns { header: [text] | null,
+ * rows: [[cellLines]] } where each cell is an array of Markdown lines.
+ * Throws if a row does not line up with the border (the caller keeps the raw
+ * table then).
+ */
+function parseGridTable(lines) {
+  const border = lines[0].replace(/\s+$/, "");
+  const cuts = [];
+  for (let i = 0; i < border.length; i++) if (border[i] === "+") cuts.push(i);
+  if (cuts.length < 2) throw new Error("not a grid table");
+  const groups = [];
+  let headerCount = -1;
+  let current = [];
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].replace(/\s+$/, "");
+    if (line.trimStart()[0] === "+") {
+      if (current.length) groups.push(current);
+      current = [];
+      if (line.indexOf("=") !== -1) headerCount = groups.length;
+      continue;
+    }
+    cuts.forEach((c) => {
+      if (line[c] !== "|") throw new Error("grid table row does not line up: " + line.slice(0, 60));
+    });
+    current.push(line);
+  }
+  if (current.length) groups.push(current);
+  const width = cuts.length - 1;
+  const cells = groups.map((group) => {
+    const columns = cuts.slice(0, -1).map(() => []);
+    group.forEach((line) => {
+      const segs = cuts.slice(0, -1).map((start, k) => line.slice(start + 1, cuts[k + 1]));
+      joinSplitPre(segs);
+      segs.forEach((seg, k) => columns[k].push(seg.replace(/\s+$/, "")));
+    });
+    // Cells hold Markdown too (notes, lists): convert it like page text.
+    return columns.map((raw) => tidy(convertLines(cleanCell(trimBlankEdges(dedent(raw))), [])));
+  });
+  if (!width) throw new Error("not a grid table");
+  let header = null;
+  let rows = cells;
+  if (headerCount > 0) {
+    header = cells[0].map((cell) => stripInline(cell.join(" ")));
+    rows = cells.slice(headerCount);
+  }
+  return { header, rows };
+}
+
+/**
+ * The guide has a table where one <pre> signature runs across several column
+ * borders on the same line. Glue such a <pre> back into its first cell.
+ */
+function joinSplitPre(segs) {
+  for (let k = 0; k < segs.length; k++) {
+    const opened = (segs[k].match(/<pre[\s>]/g) || []).length;
+    const closed = (segs[k].match(/<\/pre>/g) || []).length;
+    if (opened <= closed) continue;
+    let j = k + 1;
+    while (j < segs.length && segs[k].lastIndexOf("</pre>") < segs[k].lastIndexOf("<pre")) {
+      segs[k] = segs[k].replace(/\s+$/, "") + segs[j].replace(/^\s+/, " ");
+      segs[j] = "";
+      j++;
+    }
+  }
+}
+
+/** Splits a pipe-table row into trimmed cell texts (escaped \| stays in the cell). */
+function pipeCells(line) {
+  const inner = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  const cells = [];
+  let cur = "";
+  for (let i = 0; i < inner.length; i++) {
+    if (inner[i] === "\\" && inner[i + 1] === "|") {
+      cur += "\\|";
+      i++;
+    } else if (inner[i] === "|") {
+      cells.push(cur.trim());
+      cur = "";
+    } else cur += inner[i];
+  }
+  cells.push(cur.trim());
+  return cells;
+}
+
+/** Parses a pipe table (header, |---| row, rows) into the shape of parseGridTable. */
+function parsePipeTable(lines) {
+  const header = pipeCells(lines[0]).map((c) => stripInline(c));
+  const rows = lines.slice(2).map((line) => {
+    const cells = pipeCells(line);
+    while (cells.length < header.length) cells.push("");
+    return cells.slice(0, header.length).map((c) => cleanCell(c ? [c] : []));
+  });
+  return { header, rows };
+}
+
+/** Converts HTML that only appears inside cells: <pre lang> signatures and <br>. */
+function cleanCell(lines) {
+  const out = [];
+  lines.forEach((line) => {
+    const pre = line.match(/^\s*<pre(?:\s+lang="([^"]*)")?>([\s\S]*?)<\/pre>\s*$/);
+    if (pre) {
+      if (out.length && out[out.length - 1].trim()) out.push("");
+      out.push("```" + (pre[1] || ""));
+      preText(pre[2])
+        .split(/<br\s*\/?>/)
+        .forEach((l) => out.push(l.replace(/\s+$/, "")));
+      out.push("```");
+      return;
+    }
+    const inlined = line.replace(/<pre(?:\s+lang="[^"]*")?>([\s\S]*?)<\/pre>/g, (m, code) => "`" + preText(code).replace(/<br\s*\/?>/g, " ") + "`");
+    inlined.split(/<br\s*\/?>/).forEach((l) => out.push(l.replace(/\s+$/, "")));
+  });
+  // Blank line after a code block that is followed by text.
+  const spaced = [];
+  out.forEach((line, i) => {
+    spaced.push(line);
+    if (line === "```" && i + 1 < out.length && out[i + 1].trim() && isClosingFence(out, i)) spaced.push("");
+  });
+  return spaced;
+}
+
+function isClosingFence(lines, index) {
+  let count = 0;
+  for (let i = 0; i <= index; i++) if (/^```/.test(lines[i])) count++;
+  return count % 2 === 0;
+}
+
+function isSingleLine(cell) {
+  return cell.length <= 1 && !/^```/.test(cell[0] || "");
+}
+
+function escapePipes(text) {
+  return text.replace(/(^|[^\\])\|/g, "$1\\|");
+}
+
+/** A plain paragraph line: can follow "- **key**: " on the same line. */
+function isParagraphLine(line) {
+  return !!line && !/^\s*(```|~~~|[-*+]\s|\d+[.)]\s|>|#|\|)/.test(line);
+}
+
+function renderTable(table) {
+  const { header, rows } = table;
+  const width = rows.length ? rows[0].length : header ? header.length : 0;
+  const allShort = rows.every((row) => row.every(isSingleLine));
+  if (header && allShort && width <= 4) {
+    const lineOf = (cells) => "| " + cells.map((c) => escapePipes(c)).join(" | ") + " |";
+    const body = rows.map((row) => lineOf(row.map((c) => c[0] || "")));
+    if (body.every((l) => l.length <= PIPE_TABLE_MAX_LINE)) {
+      return [lineOf(header), "|" + header.map(() => "---").join("|") + "|"].concat(body);
+    }
+  }
+  return renderRowsAsList(header, rows, width);
+}
+
+function renderRowsAsList(header, rows, width) {
+  // The key is column 0; the body is the longest other column; the rest are
+  // short "Label: value" notes next to the key.
+  let bodyCol = width > 1 ? 1 : 0;
+  if (width > 2) {
+    let best = -1;
+    for (let k = 1; k < width; k++) {
+      const total = rows.reduce((sum, row) => sum + row[k].join("\n").length, 0);
+      if (total > best) {
+        best = total;
+        bodyCol = k;
+      }
+    }
+  }
+  const out = [];
+  rows.forEach((row) => {
+    const keyCell = row[0];
+    let body = width > 1 ? row[bodyCol].slice() : [];
+    let key = keyCell[0] || "";
+    if (keyCell.length > 1) body = keyCell.slice(1).concat(body.length ? [""] : [], body);
+    const notes = [];
+    const longNotes = [];
+    for (let k = 1; k < width; k++) {
+      if (k === bodyCol) continue;
+      const cell = row[k];
+      if (!cell.length || !cell.join("").trim()) continue;
+      const label = header && header[k] ? header[k] + ": " : "";
+      if (isSingleLine(cell)) notes.push(label + cell[0]);
+      else longNotes.push([""].concat(label ? ["*" + header[k] + ":*"] : [], cell));
+    }
+    longNotes.forEach((note) => (body = body.concat(note)));
+    body = trimBlankEdges(body);
+    let head = "- " + (key ? (/\*\*/.test(key) ? key : "**" + key + "**") : "");
+    if (notes.length) head += " (" + notes.join("; ") + ")";
+    if (body.length && isParagraphLine(body[0])) {
+      head += (key || notes.length ? ": " : "") + body[0].trim();
+      body = body.slice(1);
+    }
+    out.push(head);
+    body.forEach((line) => out.push(line ? "  " + line : ""));
+    out.push("");
+  });
+  return trimBlankEdges(out);
+}
+
+// ---------------------------------------------------------------------------
+// Blocks
+
+function convertLines(lines, warnings) {
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (isFenceOpen(line)) {
+      const end = fenceEnd(lines, i);
+      for (let k = i; k < end; k++) out.push(lines[k].replace(/\s+$/, ""));
+      i = end;
+      continue;
+    }
+    if (GRID_BORDER.test(line)) {
+      let end = i + 1;
+      while (end < lines.length && /^\s*[+|]/.test(lines[end])) end++;
+      const indent = line.match(/^\s*/)[0];
+      const raw = lines.slice(i, end);
+      let rendered;
+      try {
+        rendered = renderTable(parseGridTable(raw.map((l) => l.slice(indent.length))));
+      } catch (error) {
+        warnings.push("kept a table as is: " + error.message);
+        rendered = raw.map((l) => l.replace(/\s+$/, ""));
+      }
+      out.push("");
+      rendered.forEach((l) => out.push(l ? indent + l : ""));
+      out.push("");
+      i = end;
+      continue;
+    }
+    if (/^\s*\|/.test(line) && i + 1 < lines.length && PIPE_SEPARATOR.test(lines[i + 1])) {
+      let end = i + 2;
+      while (end < lines.length && /^\s*\|/.test(lines[end])) end++;
+      const indent = line.match(/^\s*/)[0];
+      out.push("");
+      renderTable(parsePipeTable(lines.slice(i, end))).forEach((l) => out.push(l ? indent + l : ""));
+      out.push("");
+      i = end;
+      continue;
+    }
+    const pre = line.match(/^(\s*)<pre(?:\s+lang="([^"]*)")?>/);
+    if (pre) {
+      let end = i;
+      while (end < lines.length && lines[end].indexOf("</pre>") === -1) end++;
+      const raw = lines.slice(i, Math.min(end + 1, lines.length)).join("\n");
+      const code = preText(raw.replace(/^\s*<pre[^>]*>/, "").replace(/<\/pre>[\s\S]*$/, ""))
+        .split(/<br\s*\/?>|\n/)
+        .map((l) => l.replace(/\s+$/, ""));
+      out.push("", pre[1] + "```" + (pre[2] || ""));
+      code.forEach((l) => out.push(l ? pre[1] + l : ""));
+      out.push(pre[1] + "```", "");
+      i = end + 1;
+      continue;
+    }
+    const adm = line.match(ADMONITION);
+    if (adm) {
+      const indent = adm[1].length;
+      let end = i + 1;
+      while (end < lines.length && (!lines[end].trim() || lines[end].match(/^ */)[0].length >= indent + 4)) end++;
+      while (end > i + 1 && !lines[end - 1].trim()) end--;
+      const body = trimBlankEdges(convertLines(dedent(lines.slice(i + 1, end)), warnings));
+      const kind = adm[3].charAt(0).toUpperCase() + adm[3].slice(1).toLowerCase();
+      const label = "**" + (adm[4] ? adm[4] : kind) + ":**";
+      if (body.length && isParagraphLine(body[0])) body[0] = label + " " + body[0];
+      else body.unshift(label);
+      out.push("");
+      body.forEach((l) => out.push(adm[1] + (l ? "> " + l : ">")));
+      out.push("");
+      i = end;
+      continue;
+    }
+    if (RULE.test(line)) {
+      out.push("");
+      i++;
+      continue;
+    }
+    out.push(
+      line
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, (m, alt) => "(Screenshot: " + (alt || "image") + ")")
+        .replace(/<br\s*\/?>/g, " ")
+        .replace(/\s+$/, "")
+    );
+    i++;
+  }
+  return out;
+}
+
+/** Collapses runs of blank lines (outside code) to one. */
+function tidy(lines) {
+  const out = [];
+  let inFence = false;
+  lines.forEach((line) => {
+    if (/^\s*(`{3,}|~{3,})/.test(line)) inFence = !inFence;
+    if (!inFence && !line.trim() && (!out.length || !out[out.length - 1].trim())) return;
+    out.push(line);
+  });
+  return trimBlankEdges(out);
+}
+
+/** Returns { lines, warnings } for one source page. */
+function convertPage(markdown) {
+  const warnings = [];
+  const lines = String(markdown).replace(/\r\n?/g, "\n").split("\n");
+  return { lines: tidy(convertLines(lines, warnings)), warnings };
+}
+
+module.exports = {
+  convertPage,
+  parseGridTable,
+  parsePipeTable,
+  renderTable,
+  slugify,
+  stripInline,
+  uniqueSlugger,
+  fenceEnd,
+  isFenceOpen,
+};