@getrefino/core 0.1.0-rc.5 → 0.1.0-rc.6

package/dist/documents/fields.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Which frontmatter keys Refino offers as article metadata.
+ *
+ * The canonical names are Refino's; the aliases are what sites actually
+ * write. Matching is pragmatic and deliberately conservative: an alias is
+ * only accepted when it can mean one thing, and when two keys in the same
+ * article would map to the same field, neither is matched and the site is
+ * told to say which it meant. Keys Refino does not recognize are left
+ * completely alone — they are still in the file, Refino simply does not
+ * offer them.
+ */
+/** The metadata fields Content Editing V1 knows about. Order is the order the editor shows them in. */
+export declare const METADATA_FIELDS: readonly ["title", "subtitle", "excerpt", "description", "seoTitle", "seoDescription", "author", "date", "ctaLabel", "ctaText"];
+export type MetadataFieldName = (typeof METADATA_FIELDS)[number];
+/** Human labels for the metadata panel. */
+export declare const METADATA_LABELS: Readonly<Record<MetadataFieldName, string>>;
+/**
+ * Frontmatter keys that mean each field. Compared after lowercasing and
+ * dropping `-` and `_`, so `seo_title`, `seoTitle` and `SEO-Title` are one
+ * alias.
+ */
+export declare const METADATA_ALIASES: Readonly<Record<MetadataFieldName, readonly string[]>>;
+export declare function normalizeKey(key: string): string;
+export interface MetadataMatch {
+    readonly field: MetadataFieldName;
+    /** The frontmatter key this field reads and writes. */
+    readonly key: string;
+}
+export interface MetadataMatchResult {
+    readonly matches: readonly MetadataMatch[];
+    /** Fields skipped because more than one key in the article could have been them. */
+    readonly ambiguous: readonly {
+        readonly field: MetadataFieldName;
+        readonly keys: readonly string[];
+    }[];
+}
+/**
+ * Match an article's frontmatter keys to metadata fields.
+ *
+ * `overrides` is the source's `fields` configuration: a canonical field name
+ * mapped to the exact key to use. An override is authoritative — it settles
+ * ambiguity and can name a key that is not an alias of anything.
+ */
+export declare function matchMetadataFields(keys: readonly string[], overrides?: Readonly<Record<string, string>>): MetadataMatchResult;

package/dist/documents/fields.js

@@ -0,0 +1,105 @@
+/**
+ * Which frontmatter keys Refino offers as article metadata.
+ *
+ * The canonical names are Refino's; the aliases are what sites actually
+ * write. Matching is pragmatic and deliberately conservative: an alias is
+ * only accepted when it can mean one thing, and when two keys in the same
+ * article would map to the same field, neither is matched and the site is
+ * told to say which it meant. Keys Refino does not recognize are left
+ * completely alone — they are still in the file, Refino simply does not
+ * offer them.
+ */
+/** The metadata fields Content Editing V1 knows about. Order is the order the editor shows them in. */
+export const METADATA_FIELDS = [
+    "title",
+    "subtitle",
+    "excerpt",
+    "description",
+    "seoTitle",
+    "seoDescription",
+    "author",
+    "date",
+    "ctaLabel",
+    "ctaText",
+];
+/** Human labels for the metadata panel. */
+export const METADATA_LABELS = {
+    title: "Title",
+    subtitle: "Subtitle",
+    excerpt: "Excerpt",
+    description: "Description",
+    seoTitle: "SEO title",
+    seoDescription: "SEO description",
+    author: "Author",
+    date: "Date",
+    ctaLabel: "CTA label",
+    ctaText: "CTA text",
+};
+/**
+ * Frontmatter keys that mean each field. Compared after lowercasing and
+ * dropping `-` and `_`, so `seo_title`, `seoTitle` and `SEO-Title` are one
+ * alias.
+ */
+export const METADATA_ALIASES = {
+    title: ["title", "heading", "headline"],
+    subtitle: ["subtitle", "subhead", "subheading", "tagline", "standfirst"],
+    excerpt: ["excerpt", "summary", "abstract", "blurb", "lede", "lead"],
+    description: ["description", "desc"],
+    seoTitle: ["seotitle", "metatitle", "ogtitle"],
+    seoDescription: ["seodescription", "metadescription", "ogdescription"],
+    author: ["author", "byline", "writtenby"],
+    date: ["date", "publishedat", "publishdate", "pubdate", "published", "publisheddate"],
+    ctaLabel: ["ctalabel", "ctabutton", "calltoactionlabel"],
+    ctaText: ["ctatext", "cta", "calltoaction"],
+};
+export function normalizeKey(key) {
+    return key.toLowerCase().replace(/[-_\s]/g, "");
+}
+const BY_ALIAS = (() => {
+    const map = new Map();
+    for (const field of METADATA_FIELDS) {
+        for (const alias of METADATA_ALIASES[field])
+            map.set(normalizeKey(alias), field);
+    }
+    return map;
+})();
+/**
+ * Match an article's frontmatter keys to metadata fields.
+ *
+ * `overrides` is the source's `fields` configuration: a canonical field name
+ * mapped to the exact key to use. An override is authoritative — it settles
+ * ambiguity and can name a key that is not an alias of anything.
+ */
+export function matchMetadataFields(keys, overrides = {}) {
+    const present = new Set(keys);
+    const claimed = new Map();
+    for (const key of keys) {
+        const field = BY_ALIAS.get(normalizeKey(key));
+        if (!field)
+            continue;
+        const existing = claimed.get(field);
+        if (existing)
+            existing.push(key);
+        else
+            claimed.set(field, [key]);
+    }
+    const matches = [];
+    const ambiguous = [];
+    for (const field of METADATA_FIELDS) {
+        const override = overrides[field];
+        if (override !== undefined) {
+            if (present.has(override))
+                matches.push({ field, key: override });
+            continue;
+        }
+        const candidates = claimed.get(field);
+        if (!candidates || candidates.length === 0)
+            continue;
+        if (candidates.length > 1) {
+            ambiguous.push({ field, keys: candidates });
+            continue;
+        }
+        matches.push({ field, key: candidates[0] });
+    }
+    return { matches, ambiguous };
+}

package/dist/documents/file-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The path-generic persistence seam.
+ *
+ * `ContentAdapter` is bound to one file — the copy file — at construction,
+ * which is exactly right for copy and no use at all for articles, of which
+ * there are many. A store reads and writes any allow-listed path in the same
+ * repository, with the same conflict rule: a write on a revision that has
+ * moved is refused, never merged.
+ *
+ * Two implementations ship: `createLocalFileStore` in
+ * `@getrefino/core/local-file` (development) and `createGitHubFileStore` in
+ * `@getrefino/github` (production). `createGitHubContentAdapter` is built on
+ * the same store, so copy and articles commit through one code path.
+ */
+import type { CommitInfo } from "../adapter.js";
+export interface SourceFile {
+    /** The file exactly as stored. */
+    readonly text: string;
+    /** Opaque revision of these bytes: a git blob SHA, or a hash of the file. */
+    readonly revision: string;
+}
+export interface SourceFileWrite {
+    readonly path: string;
+    readonly text: string;
+    /** The revision the new text was derived from. A store must refuse a stale one. */
+    readonly baseRevision: string;
+    /** Commit message, for stores that make commits. */
+    readonly message: string;
+}
+export interface SourceFileWriteResult {
+    readonly revision: string;
+    readonly commit?: CommitInfo;
+}
+export interface SourceFileStore {
+    /** Human-readable name for logs, e.g. "github" or "local-file". */
+    readonly name: string;
+    /** Read a repository-relative path. Returns null when it does not exist. */
+    readFile(path: string): Promise<SourceFile | null>;
+    /**
+     * Write a repository-relative path.
+     * Must throw `ContentError` with code `CONFLICT` when the stored revision
+     * is not `baseRevision`.
+     */
+    writeFile(write: SourceFileWrite): Promise<SourceFileWriteResult>;
+}

package/dist/documents/file-store.js

@@ -0,0 +1 @@
+export {};

package/dist/documents/frontmatter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A span parser for YAML frontmatter.
+ *
+ * It does not build a document tree and it cannot serialize one. For each
+ * top-level entry it records where the key is, where its value is, and how
+ * that value is written. Reading a field is a slice; writing one replaces a
+ * single span and leaves every other byte of the file alone.
+ *
+ * That is the whole reason it exists: key order, unknown keys, comments,
+ * indentation, blank lines and quoting style are preserved because they are
+ * never in the code path. Anything this parser cannot represent honestly is
+ * reported as not editable rather than guessed at.
+ *
+ * The YAML subset understood here is the one blog frontmatter actually uses:
+ * top-level scalar entries in plain, single-quoted, double-quoted, literal
+ * (`|`) or folded (`>`) form.
+ */
+export type ScalarStyle = "plain" | "empty" | "single" | "double" | "literal" | "folded";
+export interface FrontmatterEntry {
+    readonly key: string;
+    /** Offset of the first character of the entry's key line. */
+    readonly entryStart: number;
+    /** Offset just past the entry's last line, including its line terminator. */
+    readonly entryEnd: number;
+    /** The span a write replaces. */
+    readonly valueStart: number;
+    readonly valueEnd: number;
+    readonly style: ScalarStyle | "unsupported";
+    /** The decoded value, or null when the style is unsupported. */
+    readonly value: string | null;
+    /** Why this entry cannot be edited, when it cannot. */
+    readonly reason: string | null;
+    /** Literal and folded entries only: the header token and the content indent. */
+    readonly block: {
+        readonly header: string;
+        readonly indent: string;
+    } | null;
+}
+export interface FrontmatterBlock {
+    /** Offset of the opening fence. */
+    readonly start: number;
+    /** Offset just past the closing fence's line terminator. */
+    readonly end: number;
+    readonly entries: readonly FrontmatterEntry[];
+}
+interface Line {
+    readonly start: number;
+    /** End of the text, before the line terminator. */
+    readonly contentEnd: number;
+    /** End including the line terminator. */
+    readonly end: number;
+    readonly text: string;
+}
+export declare function splitLines(text: string): Line[];
+export declare function encodeDouble(value: string): string;
+export declare function encodeSingle(value: string): string;
+/** Whether a value can be written as a plain scalar without changing what it means. */
+export declare function isPlainSafe(value: string): boolean;
+/**
+ * Find and parse the leading frontmatter block. Returns null when the file
+ * does not open with one, which is not an error: a Markdown file without
+ * frontmatter simply has no metadata fields.
+ */
+export declare function parseFrontmatter(text: string): FrontmatterBlock | null;
+/** The replacement text for one entry's value span. Throws when the style cannot carry the value. */
+export declare function renderScalar(text: string, entry: FrontmatterEntry, value: string): string;
+export {};

package/dist/documents/frontmatter.js

@@ -0,0 +1,407 @@
+/**
+ * A span parser for YAML frontmatter.
+ *
+ * It does not build a document tree and it cannot serialize one. For each
+ * top-level entry it records where the key is, where its value is, and how
+ * that value is written. Reading a field is a slice; writing one replaces a
+ * single span and leaves every other byte of the file alone.
+ *
+ * That is the whole reason it exists: key order, unknown keys, comments,
+ * indentation, blank lines and quoting style are preserved because they are
+ * never in the code path. Anything this parser cannot represent honestly is
+ * reported as not editable rather than guessed at.
+ *
+ * The YAML subset understood here is the one blog frontmatter actually uses:
+ * top-level scalar entries in plain, single-quoted, double-quoted, literal
+ * (`|`) or folded (`>`) form.
+ */
+export function splitLines(text) {
+    const lines = [];
+    let start = 0;
+    for (;;) {
+        const index = text.indexOf("\n", start);
+        if (index === -1) {
+            if (start < text.length || lines.length === 0) {
+                lines.push({ start, contentEnd: text.length, end: text.length, text: text.slice(start) });
+            }
+            return lines;
+        }
+        const contentEnd = index > start && text[index - 1] === "\r" ? index - 1 : index;
+        lines.push({ start, contentEnd, end: index + 1, text: text.slice(start, contentEnd) });
+        start = index + 1;
+    }
+}
+const FENCE = /^---[ \t]*$/;
+const CLOSING_FENCE = /^(?:---|\.\.\.)[ \t]*$/;
+/** A top-level entry: an unquoted key at column zero followed by a colon. */
+const KEY_LINE = /^([A-Za-z0-9_][A-Za-z0-9_.-]*)[ \t]*:(?=[ \t]|$)/;
+/** A block scalar header we can reproduce byte for byte. `|+` and `|2` are not on the list. */
+const BLOCK_HEADER = /^([|>])(-?)$/;
+const PLAIN_UNSAFE_FIRST = new Set([
+    "-", "?", ":", ",", "[", "]", "{", "}", "#", "&", "*", "!", "|", ">", "'", '"', "%", "@", "`",
+]);
+/** Anything below a space that is not a tab, and DEL. A regex of these is both unreadable and lint-hostile. */
+function hasControlCharacters(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code === 0x09)
+            continue;
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function isBlank(text) {
+    return text.trim().length === 0;
+}
+function isIndented(text) {
+    return text.length > 0 && (text[0] === " " || text[0] === "\t");
+}
+function indentOf(text) {
+    return /^[ \t]*/.exec(text)[0];
+}
+function plainTrim(value) {
+    return value.replace(/[ \t]+$/, "");
+}
+/**
+ * Where a plain scalar ends on its line: before a ` #` comment, and before
+ * any trailing whitespace. YAML only starts a comment when the `#` is
+ * preceded by whitespace, so `a#b` is one scalar.
+ */
+function plainScalarEnd(text, from, limit) {
+    for (let index = from + 1; index < limit; index += 1) {
+        if (text[index] !== "#")
+            continue;
+        const previous = text[index - 1];
+        if (previous !== " " && previous !== "\t")
+            continue;
+        let end = index - 1;
+        while (end > from && (text[end - 1] === " " || text[end - 1] === "\t"))
+            end -= 1;
+        return end;
+    }
+    let end = limit;
+    while (end > from && (text[end - 1] === " " || text[end - 1] === "\t"))
+        end -= 1;
+    return end;
+}
+/** Read a quoted token starting at `from`. Returns its end offset, or -1 if unterminated. */
+function quotedEnd(text, from, limit) {
+    const quote = text[from];
+    for (let index = from + 1; index < limit; index += 1) {
+        const char = text[index];
+        if (quote === "'") {
+            if (char !== "'")
+                continue;
+            if (text[index + 1] === "'") {
+                index += 1;
+                continue;
+            }
+            return index + 1;
+        }
+        if (char === "\\") {
+            index += 1;
+        }
+        else if (char === '"') {
+            return index + 1;
+        }
+    }
+    return -1;
+}
+function decodeSingle(raw) {
+    return raw.slice(1, -1).replace(/''/g, "'");
+}
+function decodeDouble(raw) {
+    let out = "";
+    const body = raw.slice(1, -1);
+    for (let index = 0; index < body.length; index += 1) {
+        const char = body[index];
+        if (char !== "\\") {
+            out += char;
+            continue;
+        }
+        const next = body[index + 1];
+        index += 1;
+        switch (next) {
+            case "n":
+                out += "\n";
+                break;
+            case "t":
+                out += "\t";
+                break;
+            case "r":
+                out += "\r";
+                break;
+            case '"':
+                out += '"';
+                break;
+            case "\\":
+                out += "\\";
+                break;
+            case "/":
+                out += "/";
+                break;
+            case " ":
+                out += " ";
+                break;
+            case "u": {
+                const hex = body.slice(index + 1, index + 5);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                    return null;
+                out += String.fromCharCode(Number.parseInt(hex, 16));
+                index += 4;
+                break;
+            }
+            default:
+                return null;
+        }
+    }
+    return out;
+}
+export function encodeDouble(value) {
+    let out = '"';
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        if (char === '"')
+            out += '\\"';
+        else if (char === "\\")
+            out += "\\\\";
+        else if (char === "\n")
+            out += "\\n";
+        else if (char === "\t")
+            out += "\\t";
+        else if (char === "\r")
+            out += "\\r";
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        else
+            out += char;
+    }
+    return `${out}"`;
+}
+export function encodeSingle(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Whether a value can be written as a plain scalar without changing what it means. */
+export function isPlainSafe(value) {
+    if (value.length === 0)
+        return false;
+    if (value !== value.trim())
+        return false;
+    if (/[\n\r\t]/.test(value))
+        return false;
+    if (PLAIN_UNSAFE_FIRST.has(value[0]))
+        return false;
+    if (value.includes(": ") || value.endsWith(":"))
+        return false;
+    if (/[ \t]#/.test(value))
+        return false;
+    return !hasControlCharacters(value);
+}
+function unsupported(key, entryStart, entryEnd, valueStart, valueEnd, reason) {
+    return { key, entryStart, entryEnd, valueStart, valueEnd, style: "unsupported", value: null, reason, block: null };
+}
+function readBlockScalar(lines, index, last, key, entryStart, entryEnd, colonEnd, header) {
+    const contentLines = lines.slice(index + 1, last + 1);
+    const headerEnd = lines[index].contentEnd;
+    if (contentLines.length === 0) {
+        return unsupported(key, entryStart, entryEnd, colonEnd, headerEnd, "the block scalar has no content");
+    }
+    const indent = indentOf(contentLines[0].text);
+    const valueEnd = lines[last].contentEnd;
+    if (indent.length === 0) {
+        return unsupported(key, entryStart, entryEnd, colonEnd, valueEnd, "the block scalar is not indented");
+    }
+    const parts = [];
+    for (const line of contentLines) {
+        if (isBlank(line.text)) {
+            parts.push("");
+            continue;
+        }
+        if (!line.text.startsWith(indent)) {
+            return unsupported(key, entryStart, entryEnd, colonEnd, valueEnd, "the block scalar's indentation is uneven");
+        }
+        parts.push(line.text.slice(indent.length));
+    }
+    if (header.startsWith("|")) {
+        return {
+            key, entryStart, entryEnd, valueStart: colonEnd, valueEnd,
+            style: "literal", value: parts.join("\n"), reason: null, block: { header, indent },
+        };
+    }
+    // Folded: lines join with a space, a blank line becomes a newline. A line
+    // indented further than the block keeps its own breaks, which this parser
+    // does not reproduce, so it is refused.
+    if (parts.some((part) => part.length > 0 && (part[0] === " " || part[0] === "\t"))) {
+        return unsupported(key, entryStart, entryEnd, colonEnd, valueEnd, "the folded value contains a more-indented line");
+    }
+    let folded = "";
+    for (const part of parts) {
+        if (part === "") {
+            folded += "\n";
+            continue;
+        }
+        if (folded.length > 0 && !folded.endsWith("\n"))
+            folded += " ";
+        folded += part;
+    }
+    return {
+        key, entryStart, entryEnd, valueStart: colonEnd, valueEnd,
+        style: "folded", value: folded, reason: null, block: { header, indent },
+    };
+}
+function readEntry(text, lines, index, lastLine) {
+    const line = lines[index];
+    const match = KEY_LINE.exec(line.text);
+    const key = match[1];
+    const colonEnd = line.start + match[0].length;
+    // Continuation lines: indented lines, plus blank lines that are followed by
+    // another indented line. A comment at column zero belongs to no entry.
+    let last = index;
+    for (let scan = index + 1; scan <= lastLine; scan += 1) {
+        const candidate = lines[scan];
+        if (isBlank(candidate.text))
+            continue;
+        if (!isIndented(candidate.text))
+            break;
+        last = scan;
+    }
+    const entryStart = line.start;
+    const entryEnd = lines[last].end;
+    const next = last + 1;
+    const inlineRaw = text.slice(colonEnd, line.contentEnd);
+    const leading = indentOf(inlineRaw);
+    const inlineStart = colonEnd + leading.length;
+    const inline = inlineRaw.slice(leading.length);
+    const commentOnly = inline.startsWith("#");
+    const inlineText = commentOnly ? "" : inline;
+    if (BLOCK_HEADER.test(plainTrim(inlineText))) {
+        const header = plainTrim(inlineText);
+        return { entry: readBlockScalar(lines, index, last, key, entryStart, entryEnd, colonEnd, header), next };
+    }
+    if (last !== index) {
+        // Indented lines under something that is not a block scalar: a nested
+        // map, a sequence, or a multi-line scalar. Readable, not writable
+        // through a single span.
+        const reason = inlineText.length === 0
+            ? "the value is a nested map or list, not a single value"
+            : "the value continues across several lines";
+        return { entry: unsupported(key, entryStart, entryEnd, inlineStart, line.contentEnd, reason), next };
+    }
+    if (inlineText.length === 0) {
+        const valueEnd = commentOnly ? inlineStart : line.contentEnd;
+        return {
+            entry: { key, entryStart, entryEnd, valueStart: inlineStart, valueEnd, style: "empty", value: "", reason: null, block: null },
+            next,
+        };
+    }
+    const first = inlineText[0];
+    if (first === "'" || first === '"') {
+        const end = quotedEnd(text, inlineStart, line.contentEnd);
+        if (end === -1) {
+            return { entry: unsupported(key, entryStart, entryEnd, inlineStart, line.contentEnd, "the quoted value is not closed on the same line"), next };
+        }
+        const value = first === "'" ? decodeSingle(text.slice(inlineStart, end)) : decodeDouble(text.slice(inlineStart, end));
+        if (value === null) {
+            return { entry: unsupported(key, entryStart, entryEnd, inlineStart, end, "the quoted value uses an escape Refino does not reproduce"), next };
+        }
+        // Anything after the closing quote other than spaces or a comment is not
+        // something this parser understands.
+        const trailing = text.slice(end, line.contentEnd).trim();
+        if (trailing.length > 0 && !trailing.startsWith("#")) {
+            return { entry: unsupported(key, entryStart, entryEnd, inlineStart, end, "there is more after the quoted value than a comment"), next };
+        }
+        return {
+            entry: {
+                key, entryStart, entryEnd, valueStart: inlineStart, valueEnd: end,
+                style: first === "'" ? "single" : "double", value, reason: null, block: null,
+            },
+            next,
+        };
+    }
+    if (PLAIN_UNSAFE_FIRST.has(first)) {
+        return {
+            entry: unsupported(key, entryStart, entryEnd, inlineStart, line.contentEnd, `the value starts with "${first}", which Refino does not edit`),
+            next,
+        };
+    }
+    const valueEnd = plainScalarEnd(text, inlineStart, line.contentEnd);
+    return {
+        entry: {
+            key, entryStart, entryEnd, valueStart: inlineStart, valueEnd,
+            style: "plain", value: text.slice(inlineStart, valueEnd), reason: null, block: null,
+        },
+        next,
+    };
+}
+/**
+ * Find and parse the leading frontmatter block. Returns null when the file
+ * does not open with one, which is not an error: a Markdown file without
+ * frontmatter simply has no metadata fields.
+ */
+export function parseFrontmatter(text) {
+    const lines = splitLines(text);
+    if (lines.length === 0)
+        return null;
+    const opening = lines[0];
+    if (!FENCE.test(opening.text))
+        return null;
+    let closing = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (CLOSING_FENCE.test(lines[index].text)) {
+            closing = index;
+            break;
+        }
+    }
+    if (closing === -1)
+        return null;
+    const entries = [];
+    let index = 1;
+    while (index < closing) {
+        const line = lines[index];
+        if (isBlank(line.text) || line.text.trimStart().startsWith("#") || !KEY_LINE.test(line.text)) {
+            index += 1;
+            continue;
+        }
+        const read = readEntry(text, lines, index, closing - 1);
+        entries.push(read.entry);
+        index = Math.max(read.next, index + 1);
+    }
+    // A key written twice is ambiguous; neither copy is editable.
+    const counts = new Map();
+    for (const entry of entries)
+        counts.set(entry.key, (counts.get(entry.key) ?? 0) + 1);
+    const resolved = entries.map((entry) => (counts.get(entry.key) ?? 0) > 1
+        ? unsupported(entry.key, entry.entryStart, entry.entryEnd, entry.valueStart, entry.valueEnd, `"${entry.key}" appears more than once in the frontmatter`)
+        : entry);
+    return { start: opening.start, end: lines[closing].end, entries: resolved };
+}
+/** The replacement text for one entry's value span. Throws when the style cannot carry the value. */
+export function renderScalar(text, entry, value) {
+    switch (entry.style) {
+        case "plain":
+        case "empty": {
+            const rendered = isPlainSafe(value) ? value : encodeDouble(value);
+            // `key:` with nothing after it needs a space; `key: x` already has one.
+            return text[entry.valueStart - 1] === ":" ? ` ${rendered}` : rendered;
+        }
+        case "single":
+            return value.includes("\n") ? encodeDouble(value) : encodeSingle(value);
+        case "double":
+            return encodeDouble(value);
+        case "literal": {
+            const { header, indent } = entry.block;
+            const body = value.split("\n").map((line) => (line.length === 0 ? "" : indent + line)).join("\n");
+            return ` ${header}\n${body}`;
+        }
+        case "folded": {
+            const { header, indent } = entry.block;
+            if (value.includes("\n")) {
+                throw new Error(`"${entry.key}" is a folded block scalar and the new value contains a line break`);
+            }
+            return ` ${header}\n${indent}${value}`;
+        }
+        default:
+            throw new Error(`"${entry.key}" is not an editable frontmatter value`);
+    }
+}