@jxsuite/parser 3.0.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -48,7 +48,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.4.13",
+    "@jxsuite/markup": "^1.0.0",
     "@jxsuite/schema": "^4.0.0",
     "@shikijs/langs": "^4.5.0",
     "@shikijs/themes": "^4.5.0",
@@ -68,6 +68,7 @@
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.3",
     "@jxsuite/runtime": "^5.0.0",
+    "@jxsuite/test-support": "^0.0.0",
     "@types/mdast": "^4.0.4",
     "ajv": "^8.20.0"
   },

package/src/Content.class.json

@@ -18,9 +18,11 @@
     "settings": {
       "icon": "grid-four",
       "label": "Content Types",
+      "intro": "Each content type is a collection, such as blog posts, team members or events: a folder of entries that share the fields you define here.",
       "order": 50,
       "layout": "map",
       "entry": {
+        "noun": "content type",
         "ui": { "schema": { "control": "schema-builder" } },
         "newEntry": {
           "source": "./content/${key}/",

package/src/content-loader.ts

@@ -17,7 +17,7 @@
  * @module @jxsuite/parser/content-loader
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, extname, relative, resolve } from "node:path";
 import {
   assetUrlFor,
@@ -182,6 +182,25 @@ export function localesForExpansion(projectConfig: ProjectConfig | undefined): s
   return resolveI18n(projectConfig ?? {}).i18n?.locales ?? [];
 }
 
+/**
+ * Whether `path` (relative to `root`) exists with exactly this spelling.
+ *
+ * `existsSync` alone answers "is there a directory called `fr-ca`" with yes when only `fr-CA`
+ * exists, on a case-insensitive filesystem (macOS and Windows by default), so the spelling that
+ * wins would depend on the machine. The filesystem's own name for the entry, from `realpath`, is
+ * compared segment for segment instead, which is the same answer everywhere.
+ */
+function existsWithSpelling(root: string, path: string): boolean {
+  const full = resolve(root, path);
+  if (!existsSync(full)) {
+    return false;
+  }
+  const wanted = full.split(/[\\/]/).filter(Boolean);
+  const actual = realpathSync.native(full).split(/[\\/]/).filter(Boolean);
+  const tail = actual.slice(-wanted.length);
+  return wanted.every((segment, index) => segment === tail[index]);
+}
+
 /**
  * The directory a locale's entries live in, out of the spellings that can legitimately be on disk.
  *
@@ -204,7 +223,7 @@ export function localeSource(root: string, source: string, locale: string): stri
   const candidates = [locale, locale.toLowerCase()];
   for (const spelling of candidates) {
     const path = source.split(LOCALE_PLACEHOLDER).join(spelling);
-    if (existsSync(resolve(root, path))) {
+    if (existsWithSpelling(root, path)) {
       return path;
     }
   }

package/src/highlight.ts

@@ -80,6 +80,16 @@ function getHighlighter(): HighlighterCore {
     ],
     themes: [githubLight, githubDark],
   });
+  /* The first tokenization in a process comes out wrong in the dark theme (a space after `a` takes
+     the identifier blue, `=` loses its keyword red) and every later one of the same code is right,
+     on macOS and on Linux alike, so the first block of a build differed from every copy of it. The
+     cause is inside Shiki's first use of its JavaScript regex engine; one throwaway call before
+     anything is returned makes the first real call the second. */
+  _highlighter.codeToTokens("const a = 1;", {
+    defaultColor: false,
+    lang: "javascript",
+    themes: THEMES,
+  });
   return _highlighter;
 }
 
@@ -98,7 +108,16 @@ export function highlightFence(code: string, info: string): (JxElement | string)
   if (!h.getLoadedLanguages().includes(lang)) {
     return null;
   }
-  const { tokens } = h.codeToTokens(code, { defaultColor: false, lang, themes: THEMES });
+  /* No per-line time limit (Shiki's default is 500 ms). With one, a line that tokenizes slowly
+     (the first line of a grammar, while its regexes are still being compiled, on a loaded CI runner)
+     is cut short and its rest painted in whatever scope it stopped in, so the same fence built
+     twice could highlight differently. A build's output must not depend on the machine's speed. */
+  const { tokens } = h.codeToTokens(code, {
+    defaultColor: false,
+    lang,
+    themes: THEMES,
+    tokenizeTimeLimit: 0,
+  });
   const out: (JxElement | string)[] = [];
   for (const [i, line] of tokens.entries()) {
     if (i > 0) {

package/src/html-to-jx.ts

@@ -1,9 +1,9 @@
 /**
  * Html-to-jx — compatibility shim.
  *
- * The HTML → Jx conversion pipeline moved to `@jxsuite/markup/html-to-jx`; this module
- * re-exports it so the parser's historical `@jxsuite/parser/html-to-jx` entrypoint keeps
- * working for downstream consumers.
+ * The HTML → Jx conversion pipeline moved to `@jxsuite/markup/html-to-jx`; this module re-exports
+ * it so the parser's historical `@jxsuite/parser/html-to-jx` entrypoint keeps working for
+ * downstream consumers.
  *
  * @module @jxsuite/parser/html-to-jx
  * @license MIT

package/src/md-html.ts

@@ -1,9 +1,9 @@
 /**
  * Md-html — compatibility shim.
  *
- * The browser-safe markdown → sanitized HTML pipeline moved to `@jxsuite/markup/md-html`;
- * this module re-exports it so the parser's historical `@jxsuite/parser/md-html`
- * entrypoint keeps working for downstream consumers.
+ * The browser-safe markdown → sanitized HTML pipeline moved to `@jxsuite/markup/md-html`; this
+ * module re-exports it so the parser's historical `@jxsuite/parser/md-html` entrypoint keeps
+ * working for downstream consumers.
  *
  * @module @jxsuite/parser/md-html
  * @license MIT

package/src/serialize.ts

@@ -30,12 +30,15 @@ import {
   tagNameCandidates,
 } from "@jxsuite/schema/guards";
 import type { TagNameSlot } from "@jxsuite/schema/guards";
+import remarkParse from "remark-parse";
 import remarkStringify from "remark-stringify";
 import remarkDirective from "remark-directive";
 import remarkGfm from "remark-gfm";
 import { stringify } from "yaml";
 import { htmlToJx } from "@jxsuite/markup/html-to-jx";
 import { expandDotPaths } from "./transpile.ts";
+import { bodyText, frontmatterText, markdownMarkers, spliceFrontmatter } from "./source-style.ts";
+import type { MarkdownMarkers } from "./source-style.ts";
 import type {
   JsonObject,
   JsonValue,
@@ -256,6 +259,12 @@ export interface SerializeOptions<ScopeValue = JxDocumentValue> {
   allowlist?: ReadonlySet<string> | string[];
   /** Roundtrip mode: emit YAML frontmatter from non-children doc keys (default true). */
   frontmatter?: boolean;
+  /**
+   * Roundtrip mode: the text the document was read from. Every frontmatter key whose value is
+   * unchanged keeps its own spelling (quotes, wrapping, block style, comments), and the body is
+   * written with the emphasis, strong and bullet markers the source used (`source-style.ts`).
+   */
+  source?: string;
 }
 
 // ═════════════════════════════════════════════════════════════════════════════
@@ -567,6 +576,112 @@ function hasJxProps(el: JxElement) {
   return false;
 }
 
+/**
+ * The attributes each markdown-native tag can state in markdown syntax: a link's `href` and
+ * `title`, an image's `src`, `alt` and `title`, an ordered list's `start`. Any other attribute (an
+ * image's `width` and `height`, a heading's `id`) has no markdown spelling, so an element that
+ * carries one is written as a directive, which keeps every attribute, rather than as markdown that
+ * would drop it.
+ */
+const MD_ATTRIBUTES = new Map([
+  ["a", new Set(["href", "title"])],
+  ["img", new Set(["alt", "src", "title"])],
+  ["ol", new Set(["start"])],
+]);
+
+/** Whether every attribute an element carries has a markdown spelling for its tag. */
+function hasOnlyMarkdownAttributes(el: JxElement, tag: string): boolean {
+  const allowed = MD_ATTRIBUTES.get(tag);
+  return Object.keys(el.attributes ?? {}).every((name) => allowed?.has(name) ?? false);
+}
+
+/**
+ * The parts of a table. They are markdown only inside a table GFM can write ({@link isGfmTable}),
+ * which converts them itself; met anywhere else (a directive table's `tbody`, a stray `tr`) they
+ * are directives, since they have no markdown form of their own.
+ */
+const TABLE_PARTS: ReadonlySet<string> = new Set(["tbody", "td", "th", "thead", "tr"]);
+
+/** A table part's children, without the whitespace an HTML source left between its tags. */
+function partChildren(el: JxElement): (JxElement | string)[] {
+  return childList(el).filter((child) => !isString(child) || child.trim() !== "");
+}
+
+/** `slot` as a plain element of `tag`: no attributes and no Jx props, or `null`. */
+function plainPart(slot: JxElement | string | undefined, tag: string): JxElement | null {
+  if (slot === undefined || isString(slot) || slot.tagName !== tag) {
+    return null;
+  }
+  const attributes = Object.keys(slot.attributes ?? {});
+  return attributes.length === 0 && !hasJxProps(slot) ? slot : null;
+}
+
+/** Whether a table cell holds only what a GFM cell can: one line of inline content. */
+function isGfmCell(cell: JxElement): boolean {
+  if (cell.textContent != null) {
+    return !String(cell.textContent).includes("\n");
+  }
+  return childList(cell).every((child) =>
+    isString(child)
+      ? !child.includes("\n")
+      : isString(child.tagName) && (MD_INLINE.has(child.tagName) || child.tagName === "span"),
+  );
+}
+
+/** A row's cells when every one is a plain `cellTag` holding GFM cell content, else `null`. */
+function gfmRowCells(row: JxElement | string | undefined, cellTag: string): JxElement[] | null {
+  const tr = plainPart(row, "tr");
+  if (!tr || tr.textContent != null) {
+    return null;
+  }
+  const cells: JxElement[] = [];
+  for (const slot of partChildren(tr)) {
+    const cell = plainPart(slot, cellTag);
+    if (!cell || !isGfmCell(cell)) {
+      return null;
+    }
+    cells.push(cell);
+  }
+  return cells.length > 0 ? cells : null;
+}
+
+/**
+ * The rows of a table GFM can write and read back as the same element tree, or `null`: a `thead`
+ * holding one row of `th` cells, then optionally a `tbody` whose every row has as many `td` cells,
+ * none of them carrying an attribute or anything but one line of inline content. That is exactly
+ * the shape the parser makes of a pipe table. Any other table (no header row, `td` cells in the
+ * head, a caption, a class) would come back as a different tree, so it stays a directive.
+ */
+function gfmTableRows(el: JxElement): { head: JxElement[]; body: JxElement[][] } | null {
+  if (el.textContent != null) {
+    return null;
+  }
+  const [headSlot, bodySlot, ...rest] = partChildren(el);
+  const thead = plainPart(headSlot, "thead");
+  if (!thead || rest.length > 0) {
+    return null;
+  }
+  const headRows = partChildren(thead);
+  const head = headRows.length === 1 ? gfmRowCells(headRows[0], "th") : null;
+  if (!head) {
+    return null;
+  }
+  if (bodySlot === undefined) {
+    return { body: [], head };
+  }
+  const tbody = plainPart(bodySlot, "tbody");
+  const rows = tbody ? partChildren(tbody) : [];
+  const body: JxElement[][] = [];
+  for (const row of rows) {
+    const cells = gfmRowCells(row, "td");
+    if (!cells || cells.length !== head.length) {
+      return null;
+    }
+    body.push(cells);
+  }
+  return body.length > 0 ? { body, head } : null;
+}
+
 function convertJxNode(
   slot: JxDocumentValue | undefined,
   isBlock: boolean,
@@ -586,8 +701,19 @@ function convertJxNode(
 
   const tag = serializableTag(el.tagName) || "div";
 
-  // Not markdown-native or carries Jx-specific props → directive
-  if (!allowlist.has(tag) || hasJxProps(el)) {
+  /* Not markdown-native, carries Jx-specific props or an attribute markdown cannot spell, or is a
+     table part outside a GFM table → directive. So is an image standing at block level: markdown
+     has only the inline `![alt](src)`, which would run into the paragraph beside it, and the
+     `::img{…}` leaf it was read from is its exact form. */
+  const tableRows = tag === "table" ? gfmTableRows(el) : null;
+  if (
+    !allowlist.has(tag) ||
+    hasJxProps(el) ||
+    !hasOnlyMarkdownAttributes(el, tag) ||
+    TABLE_PARTS.has(tag) ||
+    (tag === "table" && tableRows === null) ||
+    (isBlock && tag === "img")
+  ) {
     return convertToDirective(el, isBlock, allowlist);
   }
 
@@ -696,39 +822,21 @@ function convertJxNode(
     }
 
     case "table": {
-      // Flatten thead/tbody back to rows
-      const rows: MdastNode[] = [];
-      for (const section of childList(el)) {
-        if (isString(section)) {
-          continue;
-        }
-        if (section.tagName === "thead" || section.tagName === "tbody") {
-          for (const row of childList(section)) {
-            const mdRow = convertJxNode(row, true, allowlist);
-            if (mdRow) {
-              if (section.tagName === "thead") {
-                for (const cell of mdRow.children ?? []) {
-                  cell.isHeader = true;
-                }
-              }
-              rows.push(mdRow);
-            }
-          }
-        }
-      }
-      return { children: rows, type: "table" };
-    }
-
-    case "tableRow": {
-      return {
-        children: convertJxChildren(childList(el), false, allowlist),
+      // Flatten thead/tbody back to rows: the header row first, as GFM writes it.
+      const { body, head } = tableRows ?? { body: [], head: [] };
+      const row = (cells: readonly JxElement[], isHeader: boolean): MdastNode => ({
+        children: cells.map((cell) => ({
+          children: inline(cell),
+          type: "tableCell",
+          ...(isHeader && { isHeader: true }),
+        })),
         type: "tableRow",
+      });
+      return {
+        children: [row(head, true), ...body.map((cells) => row(cells, false))],
+        type: "table",
       };
     }
-
-    case "tableCell": {
-      return { children: inline(el), type: "tableCell" };
-    }
     default: {
       break;
     }
@@ -1736,6 +1844,10 @@ export function serializeJxMarkdown<ScopeValue>(
    `declare module`, so the type-aware linter sees this import as an error type, not that Plugin. */
 const remarkStringifyPlugin = remarkStringify as UnifiedPlugin;
 
+/* SAFETY: remark-parse is a shorthand `declare module` in the root types.d.ts (its default import is
+   `any`); it default-exports a unified attacher taking no settings, the UnifiedPlugin shape. */
+const remarkParsePlugin = remarkParse as UnifiedPlugin;
+
 /** A fresh unified processor, seen through the surface this module drives. */
 function createProcessor(): UnifiedProcessor {
   /* SAFETY: unified() returns a Processor, which has the use/parse/runSync/stringify members
@@ -1760,25 +1872,57 @@ function serializeRoundtrip<ScopeValue>(
     }
 
     if (Object.keys(frontmatter).length > 0) {
-      lines.push("---", stringify(frontmatter).trim(), "---", "");
+      const sourceYaml = opts.source === undefined ? null : frontmatterText(opts.source);
+      const spliced =
+        sourceYaml === null
+          ? null
+          : spliceFrontmatter(frontmatter, sourceYaml, (values) => stringifyFrontmatter(values));
+      lines.push("---", spliced ?? stringifyFrontmatter(frontmatter), "---", "");
     }
   }
 
   if (Array.isArray(doc.children) && doc.children.length > 0) {
     const mdast = jxToMdast(doc, opts);
+    const markers =
+      opts.source === undefined
+        ? { bullet: "-", emphasis: "*", strong: "*" }
+        : sourceMarkers(opts.source);
     const processor = createProcessor()
       .use(remarkGfm)
       .use(remarkDirective)
-      .use(remarkStringifyPlugin, { bullet: "-", emphasis: "*", strong: "*" });
-    const md = processor.stringify(mdast);
-
-    lines.push(md);
+      .use(remarkStringifyPlugin, { ...markers });
+    // Runs of blank lines are squeezed in the body only: inside the frontmatter they are a block
+    // Scalar's own text (a `|-` excerpt's paragraph breaks), and squeezing them edits a value.
+    lines.push(processor.stringify(mdast).replaceAll(/\n{3,}/g, "\n\n"));
   }
 
-  return `${lines
-    .join("\n")
-    .replaceAll(/\n{3,}/g, "\n\n")
-    .trim()}\n`;
+  return `${lines.join("\n").trim()}\n`;
+}
+
+/**
+ * The frontmatter block's YAML, written so that every reader gets back the values it was given.
+ *
+ * - `lineWidth: 0`: a long string stays on its line. Folding it (`>`) is a style the author did not
+ *   choose, and a one-word edit that refolds every paragraph of an excerpt is a diff nobody can
+ *   review.
+ * - YAML 1.1 quoting: a string that a YAML 1.1 reader would type (`"2024-07-26T17:39:36Z"`, a
+ *   timestamp; `"yes"`, a boolean) stays quoted. The 1.2 core schema this package reads with calls
+ *   them strings unquoted, but the loaders a site's other tools use (js-yaml, gray-matter) do not,
+ *   and a date that was a string must not become a `Date` because Studio saved the file.
+ */
+/** The markers the body of `source` was written with (`source-style.ts`). */
+function sourceMarkers(source: string): MarkdownMarkers {
+  const body = bodyText(source);
+  const tree = createProcessor()
+    .use(remarkParsePlugin)
+    .use(remarkGfm)
+    .use(remarkDirective)
+    .parse(body);
+  return markdownMarkers(tree, body);
+}
+
+function stringifyFrontmatter(frontmatter: DirectiveProps): string {
+  return stringify(frontmatter, { lineWidth: 0, version: "1.1" }).trim();
 }
 
 function serializeExport<ScopeValue>(doc: JxDocument, opts: SerializeOptions<ScopeValue>): string {

package/src/source-style.ts

@@ -0,0 +1,236 @@
+/**
+ * What a Markdown file's own text says about how it is written, read back so a save keeps it.
+ *
+ * Studio saves a Markdown document by serializing a Jx tree, and a tree holds values, not spelling.
+ * Without the text the file was read as, every save re-spells everything: a quoted `"717-669-8739"`
+ * loses its quotes, a plain scalar the author wrapped over three lines is joined, a long string
+ * becomes a `|` block, and `_emphasis_` becomes `*emphasis*`. A one-word edit then produces a diff
+ * of the whole file. The serializer's `source` option hands that text back, and this module is what
+ * reads it:
+ *
+ * - {@link spliceFrontmatter} keeps every top-level frontmatter key whose value did not change as the
+ *   exact bytes it was read as, re-stringifies only the keys that changed, drops the removed ones
+ *   and appends the new ones.
+ * - {@link markdownMarkers} reports the emphasis, strong and bullet markers the body was written
+ *   with, so the stringifier writes them the same way.
+ *
+ * @module @jxsuite/parser/source-style
+ * @license MIT
+ */
+
+import { isMap, isScalar, parseDocument } from "yaml";
+import type { Node, Pair } from "yaml";
+import { isJsonObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JxDocumentValue } from "@jxsuite/schema/types";
+import type { MdastNode } from "./types.ts";
+
+/** Opening `---` line, the block's text, and the closing `---` line. */
+const FRONTMATTER_RE = /^---\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/u;
+
+/**
+ * The YAML text of a source's leading frontmatter block, without its fences; `null` when the source
+ * opens with none. An empty block (`---` twice) is the empty string.
+ */
+export function frontmatterText(source: string): string | null {
+  const match = FRONTMATTER_RE.exec(source);
+  if (!match) {
+    return null;
+  }
+  return match[1] ?? "";
+}
+
+/** The source with its leading frontmatter block (fences included) taken off. */
+export function bodyText(source: string): string {
+  return source.replace(FRONTMATTER_RE, "");
+}
+
+/** A frontmatter value as `yaml.parse` and a Jx document both hold it. */
+type FrontmatterValue = JxDocumentValue | undefined;
+
+/** A frontmatter block's values by key. */
+export type FrontmatterValues = Record<string, FrontmatterValue>;
+
+/** Whether two frontmatter values are the same value: JSON equality, key order ignored. */
+export function sameValue(a: FrontmatterValue, b: FrontmatterValue): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return (
+      Array.isArray(a) &&
+      Array.isArray(b) &&
+      a.length === b.length &&
+      a.every((item, index) => sameValue(item, b[index]))
+    );
+  }
+  if (!isJsonObject(a) || !isJsonObject(b)) {
+    return false;
+  }
+  const keys = Object.keys(a).filter((key) => a[key] !== undefined);
+  const otherKeys = Object.keys(b).filter((key) => b[key] !== undefined);
+  return keys.length === otherKeys.length && keys.every((key) => sameValue(a[key], b[key]));
+}
+
+/** The offset of the start of the line `offset` sits on. */
+function lineStart(text: string, offset: number): number {
+  return text.lastIndexOf("\n", offset - 1) + 1;
+}
+
+/** The offset just past the end of the line `offset` sits on (past its newline, when it has one). */
+function lineEnd(text: string, offset: number): number {
+  const newline = text.indexOf("\n", offset);
+  return newline === -1 ? text.length : newline + 1;
+}
+
+/** One top-level key of the source block: where its text starts and ends, and its value. */
+interface SourceEntry {
+  key: string;
+  /** Offset of the first line of the key. */
+  start: number;
+  /** Offset just past the last line of its value. */
+  valueEnd: number;
+  value: FrontmatterValue;
+}
+
+/** The source block's top-level keys, in order; `null` when the block is not a plain block map. */
+function sourceEntries(text: string): SourceEntry[] | null {
+  const doc = parseDocument(text);
+  if (doc.errors.length > 0 || doc.warnings.length > 0) {
+    return null;
+  }
+  const { contents } = doc;
+  if (!isMap(contents) || contents.flow === true) {
+    return null;
+  }
+  /* SAFETY: a parsed document's map holds parsed pairs, whose key and value are nodes (or null for
+     a key with no value); `parseDocument` builds no other shape. */
+  const pairs = contents.items as Pair<Node, Node | null>[];
+  const keys: { name: string; range: [number, number, number] }[] = [];
+  for (const { key } of pairs) {
+    if (!isScalar(key) || !key.range || !isString(key.value)) {
+      return null;
+    }
+    keys.push({ name: key.value, range: key.range });
+  }
+  // A block map's JS is a plain object keyed by the string keys just checked.
+  const js: unknown = doc.toJS();
+  const values = isJsonObject(js) ? js : {};
+  const entries: SourceEntry[] = [];
+  for (const [index, { name, range }] of keys.entries()) {
+    const end = pairs[index]?.value?.range?.[1] ?? range[1];
+    entries.push({
+      key: name,
+      start: lineStart(text, range[0]),
+      value: values[name],
+      valueEnd: lineEnd(text, Math.max(end - 1, range[0])),
+    });
+  }
+  return entries;
+}
+
+/**
+ * The frontmatter block's YAML, keeping the source's own text for every key that did not change.
+ *
+ * A top-level key whose value equals the value the source spelled is copied from the source byte
+ * for byte, its comments and blank lines with it. A key whose value changed is written by `write`
+ * in the source key's place, keeping the comment lines that followed it. A key the document no
+ * longer has is dropped, and a key the source never had is written by `write` after the last one.
+ * Anything above the first key (a leading comment) is kept.
+ *
+ * @param frontmatter The values the document holds now.
+ * @param source The YAML text the file was read with ({@link frontmatterText}).
+ * @param write Writes a mapping of keys as YAML, without a trailing newline.
+ * @returns The new block's text, or `null` when the source is not a block map this can splice (a
+ *   flow map, a parse error, a non-string key), in which case the caller writes the whole block.
+ */
+export function spliceFrontmatter(
+  frontmatter: FrontmatterValues,
+  source: string,
+  write: (values: FrontmatterValues) => string,
+): string | null {
+  const entries = sourceEntries(source);
+  if (!entries) {
+    return null;
+  }
+  const present = (key: string) =>
+    Object.hasOwn(frontmatter, key) && frontmatter[key] !== undefined;
+  const segments: string[] = [];
+  const head = source.slice(0, entries[0]?.start ?? source.length);
+  if (head.trim().length > 0) {
+    segments.push(head);
+  }
+  for (const [index, entry] of entries.entries()) {
+    const chunkEnd = entries[index + 1]?.start ?? source.length;
+    if (!present(entry.key)) {
+      continue;
+    }
+    if (sameValue(entry.value, frontmatter[entry.key])) {
+      segments.push(source.slice(entry.start, chunkEnd));
+      continue;
+    }
+    const tail = source.slice(Math.min(entry.valueEnd, chunkEnd), chunkEnd);
+    segments.push(`${write({ [entry.key]: frontmatter[entry.key] })}\n${tail}`);
+  }
+  const known = new Set(entries.map((entry) => entry.key));
+  const added: FrontmatterValues = {};
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (!known.has(key) && value !== undefined) {
+      added[key] = value;
+    }
+  }
+  if (Object.keys(added).length > 0) {
+    segments.push(write(added));
+  }
+  return segments
+    .map((segment) => (segment.endsWith("\n") ? segment : `${segment}\n`))
+    .join("")
+    .replace(/\s+$/u, "");
+}
+
+/** The markers a Markdown body was written with, for remark-stringify's options of the same name. */
+export interface MarkdownMarkers {
+  emphasis: "*" | "_";
+  strong: "*" | "_";
+  bullet: "-" | "*" | "+";
+}
+
+/** The part of a unist position this module reads. */
+interface StartPosition {
+  start?: { offset?: number };
+}
+
+/** The source offset a parsed mdast node starts at, when the parser recorded one. */
+function startOffset(node: MdastNode): number | null {
+  /* SAFETY: remark-parse gives every node it parses a unist `Position`, whose `start` is a point
+     carrying an `offset`; a hand-built node has none, and every read below is optional. */
+  const position = node.position as StartPosition | undefined;
+  const offset = position?.start?.offset;
+  return isNumber(offset) ? offset : null;
+}
+
+/**
+ * The emphasis, strong and bullet markers `tree` (parsed from `source`) was written with: the first
+ * of each kind decides. A kind the body never uses keeps the house default (`*`, `*`, `-`).
+ */
+export function markdownMarkers(tree: MdastNode, source: string): MarkdownMarkers {
+  const markers: MarkdownMarkers = { bullet: "-", emphasis: "*", strong: "*" };
+  const seen = new Set<string>();
+  const visit = (node: MdastNode) => {
+    const offset = startOffset(node);
+    if (offset !== null && !seen.has(node.type)) {
+      const char = source[offset];
+      if ((node.type === "emphasis" || node.type === "strong") && (char === "*" || char === "_")) {
+        markers[node.type] = char;
+        seen.add(node.type);
+      } else if (node.type === "listItem" && (char === "-" || char === "*" || char === "+")) {
+        markers.bullet = char;
+        seen.add(node.type);
+      }
+    }
+    for (const child of node.children ?? []) {
+      visit(child);
+    }
+  };
+  visit(tree);
+  return markers;
+}