eidosmd 0.1.0

package/dist/src/core/convert.js

@@ -0,0 +1,37 @@
+// Converting a markdown root to the form the CLI works in: the same framework
+// written as `Framework.yaml` with the guidance as comments and the index
+// inside it, `Framework.md` and each collection's `index.md` removed. The
+// markdown form's prose (section intros, HTML comments) has no field to land
+// in and is left behind; each collection's own description travels.
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { listBlueprints } from './blueprint.js';
+import { loadFramework } from './framework.js';
+import { frameworkToDocument, serializeDocument } from './framework-structured.js';
+import { buildIndexes } from './index-leaf.js';
+export function convertToYaml(framework, dryRun) {
+    const yamlFile = path.join(framework.root, '_eidos', 'Framework.yaml');
+    const actions = [];
+    const removed = [];
+    const text = serializeDocument(frameworkToDocument(framework));
+    actions.push(`write  ${yamlFile}`);
+    actions.push(`rm     ${framework.file}`);
+    removed.push(framework.file);
+    for (const collection of framework.collections) {
+        const leaf = path.join(framework.root, collection.name, 'index.md');
+        if (existsSync(leaf)) {
+            actions.push(`rm     ${leaf}`);
+            removed.push(leaf);
+        }
+    }
+    actions.push(`index  ${yamlFile}`);
+    if (!dryRun) {
+        writeFileSync(yamlFile, text, 'utf8');
+        for (const file of removed) {
+            rmSync(file, { force: true });
+        }
+        const converted = loadFramework(framework.root);
+        buildIndexes(converted, listBlueprints(converted), { check: false });
+    }
+    return { written: yamlFile, removed, actions, dryRun };
+}

package/dist/src/core/framework-markdown.js

@@ -0,0 +1,233 @@
+// The markdown framework document, `_eidos/Framework.md`: frontmatter for the
+// version and naming convention, and a body indexing the Top-Level docs, the
+// Collections (each a `###` with Leaf, Flavors, Canvas, and grouping bullets),
+// and the property Schema as two tables.
+import { parseFrontmatter } from './frontmatter.js';
+import { groupingProperty, STANDARD_CORE } from './framework-model.js';
+import { DEFAULT_NAMING, isNaming } from './naming.js';
+import { section, sections, stripInlineCode } from './markdown.js';
+import path from 'node:path';
+const DECLARED_BULLETS = new Set(['leaf', 'flavors', 'canvas']);
+function cleanText(text) {
+    return text.replace(/^_+|_+$/g, '').trim();
+}
+function firstParagraph(block) {
+    const lines = [];
+    for (const raw of block.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('-') || line.startsWith('#')) {
+            break;
+        }
+        if (line === '') {
+            if (lines.length > 0) {
+                break;
+            }
+            continue;
+        }
+        lines.push(line);
+    }
+    return lines.join(' ');
+}
+function parseLink(text) {
+    const match = /\[([^\]]*)\]\(([^)]+)\)/.exec(text);
+    if (!match || match[1] === undefined || match[2] === undefined) {
+        return null;
+    }
+    return { title: match[1].trim(), target: match[2].trim() };
+}
+function parseCanvas(value) {
+    const plain = stripInlineCode(value).trim();
+    if (/^file\b/i.test(plain)) {
+        return { mode: 'file' };
+    }
+    const from = /card\s+from\s+#+\s*(.+?)\s*$/i.exec(plain);
+    if (from && from[1]) {
+        return { mode: 'card', section: from[1].trim() };
+    }
+    return { mode: 'card', section: null };
+}
+function flavorFromShape(label, shapeRel) {
+    const file = path.posix.basename(shapeRel.replace(/\\/g, '/')).replace(/\.md$/i, '');
+    const dot = file.indexOf('.');
+    const kind = dot === -1 ? file : file.slice(0, dot);
+    const fromFile = dot === -1 ? file : file.slice(dot + 1);
+    const name = /\.md$/i.test(label) ? fromFile : label;
+    return { name, kind };
+}
+function parseCollections(body) {
+    const block = section(body, 2, 'Collections');
+    if (block === null) {
+        return [];
+    }
+    const out = [];
+    for (const { heading, body: text } of sections(block, 3)) {
+        const collection = {
+            name: heading.text,
+            description: firstParagraph(text),
+            framing: out.length === 0,
+            leaf: null,
+            flavors: [],
+            canvas: null,
+            grouping: null,
+        };
+        let inFlavors = false;
+        let inGrouping = false;
+        for (const line of text.split('\n')) {
+            const bullet = /^-\s+\*\*(.+?):\*\*\s*(.*)$/.exec(line);
+            if (bullet && bullet[1] !== undefined) {
+                const label = bullet[1].trim();
+                const rest = (bullet[2] ?? '').trim();
+                inFlavors = label.toLowerCase() === 'flavors';
+                inGrouping = false;
+                if (label.toLowerCase() === 'leaf') {
+                    collection.leaf = parseLink(rest)?.target ?? null;
+                }
+                else if (label.toLowerCase() === 'canvas') {
+                    collection.canvas = parseCanvas(rest);
+                }
+                else if (!DECLARED_BULLETS.has(label.toLowerCase())) {
+                    collection.grouping = { label, property: null, groups: [] };
+                    inGrouping = true;
+                }
+                continue;
+            }
+            const nested = /^\s+-\s+(.*)$/.exec(line);
+            if (!nested || nested[1] === undefined) {
+                continue;
+            }
+            const item = nested[1].trim();
+            if (inFlavors) {
+                const flavorLine = /^\[(.+?)\]\((.+?)\)\s*(?:—\s*(.*))?$/.exec(item);
+                if (flavorLine && flavorLine[1] && flavorLine[2]) {
+                    // `(default)` in the description marks the default flavor; it is a flag, not prose.
+                    const described = (flavorLine[3] ?? '').trim();
+                    const isDefault = /\(default\)/i.test(described);
+                    const description = described.replace(/\s*\(default\)\.?$/i, '').replace(/\s*\(default\)/i, '').trim();
+                    const { name, kind } = flavorFromShape(flavorLine[1].trim(), flavorLine[2].trim());
+                    collection.flavors.push({
+                        name,
+                        kind,
+                        shape: flavorLine[2].trim(),
+                        description,
+                        isDefault,
+                    });
+                }
+            }
+            else if (inGrouping && collection.grouping) {
+                const groupLine = /^\*\*(.+?)\*\*\s*(?:—\s*(.*))?$/.exec(item);
+                if (groupLine && groupLine[1]) {
+                    collection.grouping.groups.push({ name: groupLine[1].trim(), description: cleanText(groupLine[2] ?? '') });
+                }
+            }
+        }
+        if (collection.flavors.length > 0 && !collection.flavors.some((flavor) => flavor.isDefault)) {
+            const first = collection.flavors[0];
+            if (first) {
+                first.isDefault = true;
+            }
+        }
+        out.push(collection);
+    }
+    return out;
+}
+function parseTable(block) {
+    const rows = [];
+    for (const raw of block.split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('|')) {
+            continue;
+        }
+        const cells = line.replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim());
+        if (cells.length === 0 || cells.every((cell) => /^:?-+:?$/.test(cell) || cell === '')) {
+            continue;
+        }
+        rows.push(cells);
+    }
+    return rows;
+}
+function parseAppliesTo(value) {
+    const plain = stripInlineCode(value).trim();
+    if (plain === '' || plain.toLowerCase() === 'all') {
+        return 'all';
+    }
+    return plain.split(/[,/]/).map((name) => name.trim()).filter((name) => name !== '');
+}
+function parseProperties(block, core) {
+    if (block === null) {
+        return [];
+    }
+    const out = [];
+    for (const cells of parseTable(block)) {
+        const name = stripInlineCode(cells[0] ?? '').trim();
+        if (name === '' || name.toLowerCase() === 'name') {
+            continue;
+        }
+        const type = (cells[1] ?? 'Text').trim();
+        if (core || cells.length < 4) {
+            out.push({ name, type, appliesTo: 'all', meaning: (cells[cells.length - 1] ?? '').trim(), core });
+        }
+        else {
+            out.push({ name, type, appliesTo: parseAppliesTo(cells[2] ?? ''), meaning: (cells[3] ?? '').trim(), core });
+        }
+    }
+    return out;
+}
+function parseTopLevel(body) {
+    const block = section(body, 2, 'Top-Level');
+    if (block === null) {
+        return [];
+    }
+    const out = [];
+    for (const raw of block.split('\n')) {
+        const bullet = /^-\s+(.*)$/.exec(raw.trim());
+        if (!bullet || bullet[1] === undefined) {
+            continue;
+        }
+        const link = parseLink(bullet[1]);
+        if (!link) {
+            continue;
+        }
+        const after = bullet[1].slice(bullet[1].indexOf(')') + 1);
+        const description = cleanText(after.replace(/^\s*—\s*/, ''));
+        out.push({ title: link.title, path: link.target, description });
+    }
+    return out;
+}
+export function parseFrameworkMarkdown(text, root, file) {
+    const { properties, body } = parseFrontmatter(text);
+    const declaredNaming = properties?.['naming'];
+    let naming = DEFAULT_NAMING;
+    let namingError = null;
+    if (declaredNaming !== undefined && declaredNaming !== null) {
+        if (isNaming(declaredNaming)) {
+            naming = declaredNaming;
+        }
+        else {
+            namingError = `naming: ${String(declaredNaming)} is not one of kebab-case, TitleCase, Title Case`;
+        }
+    }
+    const version = properties?.['eidos_version'];
+    const schemaBlock = section(body, 2, 'Schema') ?? '';
+    const coreBlock = section(schemaBlock, 3, 'Eidos Core');
+    const customBlock = section(schemaBlock, 3, 'Custom Properties');
+    const core = parseProperties(coreBlock, true);
+    const custom = parseProperties(customBlock, false);
+    const collections = parseCollections(body);
+    for (const collection of collections) {
+        if (collection.grouping) {
+            collection.grouping.property = groupingProperty(collection, custom);
+        }
+    }
+    return {
+        root,
+        file,
+        format: 'md',
+        eidosVersion: version === undefined || version === null ? null : String(version),
+        naming,
+        namingError,
+        topLevel: parseTopLevel(body),
+        collections,
+        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom },
+        problems: [],
+    };
+}

package/dist/src/core/framework-model.js

@@ -0,0 +1,48 @@
+// The framework model: everything a framework document declares, whichever
+// of `_eidos/Framework.md`, `.yaml`, or `.json` it is. The version and naming
+// convention, the Top-Level docs, the Collections (each with flavors, canvas
+// style, and grouping), and the property Schema.
+import { kebab } from './naming.js';
+export const FRAMEWORK_DIR = '_eidos';
+export function isFrameworkFormat(value) {
+    return value === 'md' || value === 'yaml';
+}
+export const FRAMEWORK_FILES = [
+    { name: 'Framework.md', format: 'md' },
+    { name: 'Framework.yaml', format: 'yaml' },
+    { name: 'Framework.yml', format: 'yaml' },
+];
+export const PROPERTY_TYPES = ['Text', 'List', 'Number', 'Checkbox', 'Date', 'Date & time'];
+export class FrameworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FrameworkError';
+    }
+}
+// The standard's own five, used when a Framework.md carries no core block.
+export const STANDARD_CORE = [
+    { name: 'id', type: 'Text', appliesTo: 'all', meaning: 'Stable, unique, kebab-case identity. Assigned once, never renamed.', core: true },
+    { name: 'title', type: 'Text', appliesTo: 'all', meaning: 'Human-readable name.', core: true },
+    { name: 'summary', type: 'Text', appliesTo: 'all', meaning: 'One plain line: what this blueprint is. The source for the collection index.', core: true },
+    { name: 'flavor', type: 'Text', appliesTo: 'all', meaning: 'Which flavor this blueprint follows. Absent = the collection default.', core: true },
+    { name: 'connects_to', type: 'List', appliesTo: 'all', meaning: 'Blueprints this one connects to on the canvas, each a link.', core: true },
+];
+// `Domains` -> `domain`: the custom property that carries a collection's group,
+// matched by the grouping label's singular against the properties scoped to it.
+export function groupingProperty(collection, custom) {
+    if (!collection.grouping) {
+        return null;
+    }
+    const label = kebab(collection.grouping.label);
+    const candidates = new Set([label, label.replace(/s$/, ''), label.replace(/ies$/, 'y'), label.replace(/es$/, '')]);
+    const scoped = custom.filter((property) => appliesTo(property, collection.name));
+    const match = scoped.find((property) => candidates.has(kebab(property.name)));
+    return match ? match.name : null;
+}
+export function appliesTo(property, collectionName) {
+    if (property.appliesTo === 'all') {
+        return true;
+    }
+    const wanted = collectionName.toLowerCase();
+    return property.appliesTo.some((name) => name.toLowerCase() === wanted || kebab(name) === kebab(collectionName));
+}

package/dist/src/core/framework-structured.js

@@ -0,0 +1,334 @@
+// The YAML framework document, `_eidos/Framework.yaml`: the same model as the
+// markdown form, as fields in the frontmatter's snake_case, for a root that
+// scripts and agents read.
+// Paths are relative to `_eidos/`, as the markdown links are. A structured
+// document also carries the generated index under `index`, one list per
+// collection, which `eidos index` rewrites in place without disturbing
+// anything a person wrote around it.
+import { Document, isMap, isPair, isScalar, parse as parseYaml, parseDocument } from 'yaml';
+import { groupingProperty, STANDARD_CORE, } from './framework-model.js';
+import { DEFAULT_NAMING, isNaming } from './naming.js';
+function isPlain(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    return typeof value === 'string' ? value : String(value);
+}
+function list(value) {
+    return Array.isArray(value) ? value : [];
+}
+function parseDocumentText(source) {
+    try {
+        return { value: parseYaml(source), error: null };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? (cause.message.split('\n')[0] ?? cause.message) : String(cause);
+        return { value: null, error: message };
+    }
+}
+function readCanvas(value, where, problems) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (value === 'file') {
+        return { mode: 'file' };
+    }
+    if (value === 'card') {
+        return { mode: 'card', section: null };
+    }
+    if (isPlain(value)) {
+        if (value['mode'] === 'file') {
+            return { mode: 'file' };
+        }
+        if (value['mode'] === 'card') {
+            const section = value['section'];
+            return { mode: 'card', section: section === undefined || section === null ? null : text(section) };
+        }
+    }
+    problems.push(`${where}: canvas must be file, card, or { mode: card, section: <Section> }`);
+    return null;
+}
+function readFlavor(value, where, problems) {
+    if (!isPlain(value) || text(value['name']) === '' || text(value['shape']) === '') {
+        problems.push(`${where}: every flavor needs a name and a shape`);
+        return null;
+    }
+    const shape = text(value['shape']).replace(/\\/g, '/');
+    const file = shape.split('/').pop() ?? shape;
+    const stem = file.replace(/\.md$/i, '');
+    const dot = stem.indexOf('.');
+    return {
+        name: text(value['name']),
+        kind: dot === -1 ? stem : stem.slice(0, dot),
+        shape,
+        description: text(value['description']),
+        isDefault: value['default'] === true,
+    };
+}
+function readCollection(value, index, problems) {
+    const where = `collections[${index}]`;
+    if (!isPlain(value) || text(value['name']) === '') {
+        problems.push(`${where}: a collection needs a name`);
+        return null;
+    }
+    const name = text(value['name']);
+    const flavors = list(value['flavors'])
+        .map((flavor, position) => readFlavor(flavor, `${where} (${name}) flavors[${position}]`, problems))
+        .filter((flavor) => flavor !== null);
+    if (flavors.length > 0 && !flavors.some((flavor) => flavor.isDefault)) {
+        const first = flavors[0];
+        if (first) {
+            first.isDefault = true;
+        }
+    }
+    const collection = {
+        name,
+        description: text(value['description']),
+        framing: index === 0,
+        leaf: null,
+        flavors,
+        canvas: readCanvas(value['canvas'], `${where} (${name})`, problems),
+        grouping: null,
+    };
+    const grouping = value['grouping'];
+    if (grouping !== undefined && grouping !== null) {
+        if (!isPlain(grouping) || text(grouping['label']) === '') {
+            problems.push(`${where} (${name}): grouping needs a label`);
+        }
+        else {
+            const property = grouping['property'];
+            collection.grouping = {
+                label: text(grouping['label']),
+                property: property === undefined || property === null || text(property) === '' ? null : text(property),
+                groups: list(grouping['groups'])
+                    .filter((group) => isPlain(group) && text(group['name']) !== '')
+                    .map((group) => ({ name: text(group['name']), description: text(group['description']) })),
+            };
+        }
+    }
+    return collection;
+}
+function readProperty(value, where, core, problems) {
+    if (!isPlain(value) || text(value['name']) === '') {
+        problems.push(`${where}: a property needs a name`);
+        return null;
+    }
+    let applies = 'all';
+    const declared = value['applies_to'];
+    if (!core && declared !== undefined && declared !== null && declared !== 'all') {
+        if (Array.isArray(declared)) {
+            applies = declared.map(text).filter((name) => name !== '');
+        }
+        else if (typeof declared === 'string') {
+            applies = declared
+                .split(/[,/]/)
+                .map((name) => name.trim())
+                .filter((name) => name !== '');
+        }
+        else {
+            problems.push(`${where}: applies_to must be all or a list of collections`);
+        }
+    }
+    return { name: text(value['name']), type: text(value['type']) || 'Text', appliesTo: applies, meaning: text(value['meaning']), core };
+}
+export function readEmbeddedIndex(value) {
+    if (!isPlain(value)) {
+        return null;
+    }
+    const out = {};
+    for (const [collection, entries] of Object.entries(value)) {
+        out[collection] = list(entries)
+            .filter(isPlain)
+            .map((entry) => {
+            const item = {
+                id: entry['id'] === undefined || entry['id'] === null ? null : text(entry['id']),
+                title: text(entry['title']),
+                summary: entry['summary'] === undefined || entry['summary'] === null || text(entry['summary']) === '' ? null : text(entry['summary']),
+                path: text(entry['path']),
+            };
+            if (entry['group'] !== undefined && entry['group'] !== null) {
+                item.group = text(entry['group']);
+            }
+            return item;
+        });
+    }
+    return out;
+}
+export function parseFrameworkStructured(source, root, file) {
+    const problems = [];
+    const { value, error } = parseDocumentText(source);
+    const document = isPlain(value) ? value : {};
+    if (error) {
+        problems.push(`not valid YAML: ${error}`);
+    }
+    else if (!isPlain(value)) {
+        problems.push('the document must be a mapping of fields');
+    }
+    let naming = DEFAULT_NAMING;
+    let namingError = null;
+    const declaredNaming = document['naming'];
+    if (declaredNaming !== undefined && declaredNaming !== null) {
+        if (isNaming(declaredNaming)) {
+            naming = declaredNaming;
+        }
+        else {
+            namingError = `naming: ${text(declaredNaming)} is not one of kebab-case, TitleCase, Title Case`;
+        }
+    }
+    const collections = list(document['collections'])
+        .map((collection, index) => readCollection(collection, index, problems))
+        .filter((collection) => collection !== null);
+    if (!Array.isArray(document['collections']) && !error && isPlain(value)) {
+        problems.push('collections must be a list; the first is the framing collection');
+    }
+    const schema = isPlain(document['schema']) ? document['schema'] : {};
+    const core = list(schema['core'])
+        .map((property, index) => readProperty(property, `schema.core[${index}]`, true, problems))
+        .filter((property) => property !== null);
+    const custom = list(schema['custom'])
+        .map((property, index) => readProperty(property, `schema.custom[${index}]`, false, problems))
+        .filter((property) => property !== null);
+    for (const collection of collections) {
+        if (collection.grouping && collection.grouping.property === null) {
+            collection.grouping.property = groupingProperty(collection, custom);
+        }
+    }
+    const topLevel = list(document['top_level'])
+        .filter((doc) => isPlain(doc) && text(doc['path']) !== '')
+        .map((doc) => ({ title: text(doc['title']) || text(doc['path']), path: text(doc['path']), description: text(doc['description']) }));
+    const version = document['eidos_version'];
+    return {
+        root,
+        file,
+        format: 'yaml',
+        eidosVersion: version === undefined || version === null ? null : text(version),
+        naming,
+        namingError,
+        topLevel,
+        collections,
+        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom },
+        problems,
+    };
+}
+// The document form of a framework: what `eidos framework --json` prints and
+// what a YAML file holds, without the generated index.
+// Keys land in the order a reader expects: version and naming, then the
+// top-level docs, the collections, and the schema; `index` is added last by
+// `eidos index`.
+export function frameworkToDocument(framework) {
+    const document = {};
+    if (framework.eidosVersion !== null) {
+        document.eidos_version = framework.eidosVersion;
+    }
+    document.naming = framework.naming;
+    if (framework.topLevel.length > 0) {
+        document.top_level = framework.topLevel.map((doc) => {
+            const entry = { title: doc.title, path: doc.path };
+            if (doc.description) {
+                entry.description = doc.description;
+            }
+            return entry;
+        });
+    }
+    document.collections = framework.collections.map((collection) => {
+        const entry = { name: collection.name };
+        if (collection.description) {
+            entry.description = collection.description;
+        }
+        if (collection.canvas) {
+            if (collection.canvas.mode === 'file') {
+                entry.canvas = 'file';
+            }
+            else if (collection.canvas.section === null) {
+                entry.canvas = 'card';
+            }
+            else {
+                entry.canvas = { mode: 'card', section: collection.canvas.section };
+            }
+        }
+        entry.flavors = collection.flavors.map((flavor) => {
+            const item = { name: flavor.name, shape: flavor.shape };
+            if (flavor.description) {
+                item.description = flavor.description;
+            }
+            if (flavor.isDefault) {
+                item.default = true;
+            }
+            return item;
+        });
+        if (collection.grouping) {
+            entry.grouping = { label: collection.grouping.label };
+            if (collection.grouping.property) {
+                entry.grouping.property = collection.grouping.property;
+            }
+            if (collection.grouping.groups.length > 0) {
+                entry.grouping.groups = collection.grouping.groups.map((group) => {
+                    const item = { name: group.name };
+                    if (group.description) {
+                        item.description = group.description;
+                    }
+                    return item;
+                });
+            }
+        }
+        return entry;
+    });
+    document.schema = {
+        core: framework.schema.core.map(({ name, type, meaning }) => ({ name, type, meaning })),
+        custom: framework.schema.custom.map(({ name, type, appliesTo: applies, meaning }) => ({ name, type, applies_to: applies, meaning })),
+    };
+    return document;
+}
+const YAML_GUIDANCE = {
+    eidos_version: ' The Eidos version this framework targets; migrate reads and bumps it.',
+    naming: ' How files, folders, and links are named: kebab-case | TitleCase | Title Case. Settled once.',
+    top_level: ' The top-level documents, README first: one entry per one-of-a-kind doc (a Roadmap, a Vision).',
+    collections: " The collections, the first of them the framing one. Each declares its flavors (one default), how a canvas draws it, and its grouping.\n Add a group under `grouping.groups` with a one-line description; add a flavor with a shape file in shapes/.",
+    schema: ' The property contract. `core` is the standard\'s and moves with eidos_version; `custom` is yours: name, type (Text | List | Number | Checkbox | Date | Date & time), applies_to (all or a list), meaning.',
+    index: ' Generated by `eidos index`; never hand-edited. One list per collection, in the order the markdown index would use.',
+};
+// A YAML document a person will edit gets the guidance the markdown seed
+// keeps as prose, as comments above each top-level key.
+function annotateYaml(document) {
+    if (!isMap(document.contents)) {
+        return;
+    }
+    document.commentBefore = ' The framework document: the structure this root is written in. Fields are documented in `eidos standard`.';
+    document.contents.items.forEach((pair, index) => {
+        if (!isPair(pair) || !isScalar(pair.key)) {
+            return;
+        }
+        const guidance = YAML_GUIDANCE[String(pair.key.value)];
+        if (guidance !== undefined) {
+            pair.key.commentBefore = guidance;
+            pair.key.spaceBefore = index > 0;
+        }
+    });
+}
+export function serializeDocument(document) {
+    const yamlDocument = new Document(document);
+    annotateYaml(yamlDocument);
+    return yamlDocument.toString({ lineWidth: 0 });
+}
+// Rewrite only the `index` key of a YAML document, keeping every other line,
+// comment, and style a person chose. Returns the new text.
+export function withEmbeddedIndex(source, index) {
+    const document = parseDocument(source);
+    // A scalar key node carries the guidance comment; on an existing key `set`
+    // keeps the pair (and whatever comment it already has) and swaps the value.
+    const key = document.createNode('index');
+    if (!document.has('index') && isScalar(key)) {
+        key.commentBefore = YAML_GUIDANCE['index'] ?? null;
+        key.spaceBefore = true;
+    }
+    document.set(key, index);
+    return document.toString({ lineWidth: 0 });
+}
+// The `index` a YAML document currently holds, or null.
+export function embeddedIndexOf(source) {
+    const { value } = parseDocumentText(source);
+    return isPlain(value) ? readEmbeddedIndex(value['index']) : null;
+}