@mermaid-js/language-service 0.0.0-stage → 13.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 - 2022 Knut Sveidqvist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @mermaid-js/language-service
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An editor-agnostic language service for Mermaid: diagnostics, go to definition, references, rename, hover, completion (front-matter `config:` included), folding, semantic tokens, and a cursor ↔ AST map for live previews. It has no runtime dependencies. `@mermaid-js/core` is a peer, and each diagram's language support (its _facet_) is an optional peer that loads on `preload()`.
+
+Use it directly, or through an adapter: `@mermaid-js/language-server` for any LSP editor, `@mermaid-js/language-service-codemirror` for CodeMirror 6, `@mermaid-js/language-service-monaco` for Monaco.
+
+## Setup
+
+```sh
+npm install @mermaid-js/language-service @mermaid-js/core @mermaid-js/diagram-flowchart
+```
+
+```ts
+import { createLanguageService } from '@mermaid-js/language-service';
+
+const service = createLanguageService();
+await service.preload(); // load the facets before the first update
+
+const doc = service.update('file:///a.mmd', text); // synchronous, complete, immutable
+doc.diagnostics();
+doc.completions(offset);
+doc.rename(offset, 'NewName'); // { edits } or { refused: reason }
+doc.lineFoldingRanges(); // folds by line, as editors show them
+doc.lineSemanticTokens(); // tokens cut per line
+```
+
+Call `preload()` (or `preload({ types: ['flowchart'] })`) once, before the first `update`. A type whose facet is not loaded gets a `LANGUAGE_NOT_LOADED` diagnostic and generic features only; a facet that fails to load gets `LANGUAGE_LOAD_FAILED`, and one whose parser throws gets `LANGUAGE_FACET_FAILED`. `preload` never rejects.
+
+Positions are UTF-16 offsets into the whole text (front matter included). `doc.lines()` converts to 0-based line and column.
+
+## Third-party diagram types
+
+Pass their rows to `createLanguageService({ facets: [{ type, id, detector, load }] })`. A facet is written against the types this package re-exports (`LanguageFacet`, `ParseResult`, `ProbeResult`, `DocumentView`, `HoverTarget`, …). The shared golden suite runs from `@mermaid-js/language-service/testing` (Node only).
+
+The language server does not load third-party facets by default: a client opts in with `initializationOptions: { mermaid: { plugins: true } }` (D157), so opening an untrusted folder runs none of its code.
+
+## Bundlers
+
+- **Optional peers.** The first-party facets are dynamic imports of optional peers, such as `@mermaid-js/diagram-flowchart/language`. Bundlers resolve them at build time: install the diagram packages you want, or mark the missing ones external. Otherwise the build can fail instead of the service reporting `LANGUAGE_LOAD_FAILED`.
+- **No top-level `await` of `preload()` in a Vite entry.** The facet and config-schema chunks import shared code from the entry chunk. An entry that awaits them at top level never finishes loading, with no error. Wrap the setup in a function: `async function start() { await service.preload(); … } void start();`.
+
+## Limitations
+
+- Language support exists for flowchart, sequence, class, state and ER diagrams. Other types get generic features: comments, directives, and front-matter config.

package/dist/ast.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `astAt` / `rangeOf` (R-LANG-6, D97): between source offsets and semantic AST ids, so a host
+ * with a live preview maps the cursor to `[data-ast]` elements and a clicked element back.
+ */
+import type { AstId, AstNode, Range } from '@mermaid-js/core/parser-kit';
+/**
+ * Ids of the AST nodes around `offset` (a node contains the offsets from its start to its end,
+ * both included), innermost first: deeper nodes first, then shorter ones. The document root
+ * is left out.
+ */
+export declare function astAt(root: AstNode | undefined, offset: number): AstId[];
+/** Every AST id → its source range. */
+export declare function astRanges(root: AstNode | undefined): Map<AstId, Range>;

package/dist/ast.js

@@ -0,0 +1,32 @@
+/**
+ * Ids of the AST nodes around `offset` (a node contains the offsets from its start to its end,
+ * both included), innermost first: deeper nodes first, then shorter ones. The document root
+ * is left out.
+ */
+export function astAt(root, offset) {
+    if (!root)
+        return [];
+    const hits = [];
+    const walk = (node, depth) => {
+        for (const c of node.children ?? []) {
+            if (c.range.start > offset || offset > c.range.end)
+                continue;
+            hits.push({ id: c.id, depth, size: c.range.end - c.range.start });
+            walk(c, depth + 1);
+        }
+    };
+    walk(root, 0);
+    return hits.sort((a, b) => b.depth - a.depth || a.size - b.size).map((h) => h.id);
+}
+/** Every AST id → its source range. */
+export function astRanges(root) {
+    const out = new Map();
+    const walk = (node) => {
+        out.set(node.id, node.range);
+        for (const c of node.children ?? [])
+            walk(c);
+    };
+    if (root)
+        walk(root);
+    return out;
+}

package/dist/completion.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Completion (DESIGN §4.5, D95, D96). Front matter answers first: an offset inside it gets
+ * front-matter keys and values from the config schema, and nothing else. The diagram text is
+ * the facet's: the text is parsed again with `probe: offset` and the facet maps the probe to
+ * items. A text whose type is not detected (empty, or a header being typed) gets every loaded
+ * facet's answer on its first line: the diagram keywords.
+ */
+import type { CompletionItem } from '@mermaid-js/core/parser-kit';
+import type { FrontMatterTree } from './config/front-matter.ts';
+import type { DocumentContext } from './context.ts';
+/** Whether the front matter (fences included; an unclosed one to the end) owns `offset`. */
+export declare function inFrontMatter(fm: FrontMatterTree, offset: number): boolean;
+export declare function completions(ctx: DocumentContext, fm: FrontMatterTree | undefined, offset: number): CompletionItem[];
+/**
+ * Characters after which an editor asks for completions without a typed word: front-matter
+ * `:`, arrows (`-`, `=`, `.`), `&`, `@`, `{` (shape data) and `,`. Every adapter uses this one
+ * list (LSP `triggerCharacters`, Monaco's, CodeMirror's activation while typing).
+ */
+export declare const COMPLETION_TRIGGERS: readonly string[];

package/dist/completion.js

@@ -0,0 +1,51 @@
+import { frontMatterCompletions } from "./config/completion.js";
+/** Whether the front matter (fences included; an unclosed one to the end) owns `offset`. */
+export function inFrontMatter(fm, offset) {
+    return fm.range.start <= offset && (offset < fm.range.end || fm.unclosed);
+}
+/** `facet`'s items for `text` at `offset`. */
+function facetItems(facet, text, offset) {
+    const result = facet.parse(text, { keepTokens: true, probe: offset });
+    return result.probe ? facet.completions(result.probe, { text, result }) : [];
+}
+/** The header keywords of every loaded facet, on the first line of an undetected text. */
+function headerItems(ctx, offset) {
+    const { text, start } = ctx;
+    const nl = text.slice(start).search(/[\r\n]/);
+    const lineEnd = nl < 0 ? text.length : start + nl;
+    if (offset < start || offset > lineEnd)
+        return [];
+    const head = text.slice(0, lineEnd);
+    const out = [];
+    for (const facet of ctx.available) {
+        for (const item of facetItems(facet, head, offset)) {
+            if (item.kind === 'keyword' && !out.some((x) => x.label === item.label))
+                out.push(item);
+        }
+    }
+    return out;
+}
+export function completions(ctx, fm, offset) {
+    if (fm !== undefined && inFrontMatter(fm, offset))
+        return frontMatterCompletions(ctx, fm, offset);
+    if (ctx.entry === undefined)
+        return headerItems(ctx, offset);
+    if (!ctx.facet)
+        return [];
+    return facetItems(ctx.facet, ctx.text, offset);
+}
+/**
+ * Characters after which an editor asks for completions without a typed word: front-matter
+ * `:`, arrows (`-`, `=`, `.`), `&`, `@`, `{` (shape data) and `,`. Every adapter uses this one
+ * list (LSP `triggerCharacters`, Monaco's, CodeMirror's activation while typing).
+ */
+export const COMPLETION_TRIGGERS = Object.freeze([
+    ':',
+    '-',
+    '=',
+    '.',
+    '&',
+    '@',
+    '{',
+    ',',
+]);

package/dist/config/completion.d.ts

@@ -0,0 +1,4 @@
+import type { CompletionItem } from '@mermaid-js/core/parser-kit';
+import type { DocumentContext } from '../context.ts';
+import type { FrontMatterTree } from './front-matter.ts';
+export declare function frontMatterCompletions(ctx: DocumentContext, fm: FrontMatterTree, offset: number): CompletionItem[];

package/dist/config/completion.js

@@ -0,0 +1,430 @@
+/**
+ * Front-matter completion (D96): keys and values of front matter in block or flow style, with
+ * plain or quoted keys (#169). Top level:
+ * `title`, `displayMode`, `config`. Under `config`: the schema's keys, leaving out removed and
+ * moved keys, the keys diagram text cannot set (core's secure list) and `look` (D153); a
+ * diagram section only when it is the one the renderer reads for the detected type (every
+ * section while no type is detected yet). Values: the key's enum, or `true`/`false`.
+ * Inserted text follows the document's line ends and the line's indent (tabs or spaces); in
+ * flow style a key is inserted as `key: `, and a quoted key as its name only.
+ *
+ * The cursor's place comes from the text, not the tree: a key being typed is not YAML yet.
+ * One forward scan over the lines before the cursor finds the flow collections (`{…}`, `[…]`)
+ * and skips those that close before it; inside one, the scan of it gives the keys on the way.
+ * In block style the parent keys come from one backward scan over the lines above. Both are
+ * linear.
+ */
+import { lineEnd } from '@mermaid-js/core/parser-kit';
+import { configSection, liveKeys, mapAt, secureKeys } from "./front-matter.js";
+import { FRONT_MATTER_KEYS } from "./hover.js";
+import { SchemaView } from "./schema.js";
+/** A key as completion reads it: plain, or a `"…"` or `'…'` key whose text is a plain key. */
+const KEY = String.raw `(?:([\w$][\w$-]*)|"([\w$-]+)"|'([\w$-]+)')`;
+/** A key being typed: indent, an opening quote if any, the text so far. */
+const KEY_LINE = /^([ \t]*)(["']?)([\w$-]*)$/;
+const VALUE_LINE = new RegExp(String.raw `^([ \t]*)${KEY}[ \t]*:[ \t]+([^\s#'"]*)$`);
+/** A parent line: `key:` with nothing (or a comment) after it. */
+const PARENT_LINE = new RegExp(String.raw `^${KEY}[ \t]*:[ \t]*(?:#.*)?$`);
+/** A line that opens a flow collection: `key: {`, `- [`, or a bare `{` (a root document). */
+const FLOW_LINE = new RegExp(String.raw `^([ \t]*)(?:${KEY}[ \t]*:[ \t]+|(-[ \t]+))?[{[]`);
+const PLAIN_KEY = /[\w$-]/;
+/** Characters of a plain value inside a flow collection, as far as completion goes. */
+const FLOW_VALUE = /[^\s,[\]{}#'"]/;
+const FLOW_BLANK = /[\s,[\]{}]/;
+/** The key a {@link KEY} match names, from its first group at `at`. */
+function keyOf(m, at) {
+    return (m[at] ?? m[at + 1] ?? m[at + 2]);
+}
+/** Where the line holding `offset` starts. */
+function lineStartOf(text, offset, floor) {
+    return Math.max(floor, text.lastIndexOf('\n', offset - 1) + 1);
+}
+/** End of the run of characters matching `re` from `at` (stops at `limit`). */
+function runEnd(text, at, limit, re) {
+    let i = at;
+    while (i < limit && re.test(text.charAt(i)))
+        i++;
+    return i;
+}
+/**
+ * The keys of the block mappings that hold a line indented by `indent`, outermost first, or
+ * `undefined` when the lines above do not nest block mappings down to it.
+ */
+function parentPath(text, fm, lineStart, indent) {
+    const base = fm.indent;
+    if (indent < base)
+        return undefined;
+    const path = [];
+    let threshold = indent;
+    let end = lineStart;
+    while (threshold > base && end > fm.yamlRange.start) {
+        const start = lineStartOf(text, end - 1, fm.yamlRange.start);
+        const line = text.slice(start, end).replace(/\r?\n$/, '');
+        end = start;
+        const content = line.trimStart();
+        if (content === '' || content.startsWith('#'))
+            continue;
+        const ind = line.length - content.length;
+        if (ind >= threshold)
+            continue;
+        const key = PARENT_LINE.exec(content.trimEnd());
+        if (key === null)
+            return undefined;
+        path.unshift(keyOf(key, 1));
+        threshold = ind;
+    }
+    return threshold <= base ? path : undefined;
+}
+/** A short type for the list: `string`, `boolean`, `object`, … */
+function shortType(schema, node) {
+    if (schema.shape(node) !== 'leaf')
+        return 'object';
+    const n = schema.resolve(node);
+    return n.type === undefined ? 'any' : [n.type].flat().join(' | ');
+}
+/** A string as a YAML plain scalar when it reads back as itself, else single-quoted. */
+function yamlString(s) {
+    const plain = /^[A-Za-z_][\w.-]*$/.test(s) && !/^(?:true|false|null|yes|no|on|off|y|n)$/i.test(s);
+    return plain ? s : `'${s.replace(/'/g, "''")}'`;
+}
+/** Whether a root config key is offered: a diagram section only when it is the type's own. */
+function offered(ctx, schema, key) {
+    if (key === 'look' || secureKeys().has(key))
+        return false;
+    if (!schema.isDiagramSection(key) || ctx.entry === undefined)
+        return true;
+    return key === configSection(ctx);
+}
+/** Whether a config path is somewhere completion offers nothing (`sequence.*` in a flowchart). */
+function closedPath(ctx, schema, path) {
+    return (path.length > 0 && !offered(ctx, schema, path[0])) || path.includes('look');
+}
+/** The document's line end, and the indent one level below `indent`. */
+function layout(text, fm, indent) {
+    const eol = text.slice(fm.range.start, fm.range.end).includes('\r\n') ? '\r\n' : '\n';
+    return [eol, indent + (indent.includes('\t') ? '\t' : '  ')];
+}
+function keyItems(ctx, fm, parent, range, style, indent) {
+    const [eol, inner] = layout(ctx.text, fm, indent);
+    const insert = (key, object) => {
+        if (style === 'name')
+            return key;
+        return object && style === 'block' ? `${key}:${eol}${inner}` : `${key}: `;
+    };
+    // Keys already in this mapping, other than the one being typed.
+    const present = new Set((mapAt(fm.root, parent)?.pairs ?? [])
+        .filter((p) => p.keyRange.end < range.start || p.keyRange.start > range.end)
+        .map((p) => p.key));
+    if (parent.length === 0) {
+        return Object.entries(FRONT_MATTER_KEYS)
+            .filter(([key]) => !present.has(key))
+            .map(([key, doc]) => ({
+            label: key,
+            kind: 'property',
+            insertText: insert(key, key === 'config'),
+            range,
+            detail: key === 'config' ? 'object' : 'string',
+            documentation: doc,
+        }));
+    }
+    if (parent[0] !== 'config' || ctx.schema === undefined)
+        return [];
+    const schema = new SchemaView(ctx.schema);
+    const path = parent.slice(1);
+    if (closedPath(ctx, schema, path))
+        return [];
+    const node = schema.at(path);
+    if (node === undefined || schema.shape(node) !== 'closed')
+        return [];
+    const props = schema.properties(node);
+    return liveKeys(props)
+        .filter((key) => !present.has(key) && key !== 'look')
+        .filter((key) => path.length > 0 || offered(ctx, schema, key))
+        .map((key) => {
+        const child = props.get(key);
+        const description = schema.resolve(child).description?.trim();
+        const item = {
+            label: key,
+            kind: 'property',
+            insertText: insert(key, schema.shape(child) !== 'leaf'),
+            range,
+            detail: shortType(schema, child),
+        };
+        return description === undefined ? item : { ...item, documentation: description };
+    });
+}
+function valueItems(ctx, path, range) {
+    if (ctx.schema === undefined)
+        return [];
+    const schema = new SchemaView(ctx.schema);
+    const config = path.slice(1);
+    let at;
+    // Top-level `displayMode` is `config.gantt.displayMode`: offered where gantt config is.
+    if (path.length === 1 && path[0] === 'displayMode') {
+        if (offered(ctx, schema, 'gantt'))
+            at = schema.at(['gantt', 'displayMode']);
+    }
+    else if (path[0] === 'config' && config.length > 0 && !closedPath(ctx, schema, config))
+        at = schema.at(config);
+    if (at === undefined)
+        return [];
+    const node = schema.resolve(at);
+    const docs = node['meta:enum'] ?? {};
+    const types = node.type === undefined ? [] : [node.type].flat();
+    const values = node.enum ?? (types.includes('boolean') ? [true, false] : []);
+    return values.map((v) => {
+        const text = typeof v === 'string' ? yamlString(v) : JSON.stringify(v);
+        const doc = typeof v === 'string' && Object.hasOwn(docs, v) ? docs[v] : undefined;
+        const item = { label: text, kind: 'value', insertText: text, range };
+        const withDetail = v === node.default ? { ...item, detail: 'default' } : item;
+        return doc === undefined ? withDetail : { ...withDetail, documentation: doc };
+    });
+}
+/** The offset after a quoted value opening at `at` (or `limit` when it is never closed). */
+function quotedEnd(text, at, limit) {
+    const q = text.charAt(at);
+    for (let i = at + 1; i < limit; i++) {
+        const c = text.charAt(i);
+        if (q === '"' && c === '\\')
+            i++;
+        else if (c === q && q === "'" && text.charAt(i + 1) === q)
+            i++;
+        else if (c === q)
+            return i + 1;
+    }
+    return limit;
+}
+/** The place at `range` in `frame`, or `null` when nothing is offered there. */
+function placeIn(frame, range, quoted) {
+    if (frame.path === undefined || !frame.map || frame.done)
+        return null;
+    if (!frame.value)
+        return { kind: 'key', path: frame.path, range, quoted };
+    if (frame.key === undefined || quoted)
+        return null;
+    return { kind: 'value', path: [...frame.path, frame.key], range, quoted };
+}
+/**
+ * A scan of the flow collection opening at `open`, whose keys from the root are `path`, up to
+ * `limit`, for the cursor at `offset`. Each step reads one token at `i`, and returns the
+ * cursor's place (`null`: nothing is offered there) once the token holds the cursor.
+ */
+class FlowScan {
+    text;
+    path;
+    offset;
+    limit;
+    stack = [];
+    i;
+    constructor(text, open, path, offset, limit) {
+        this.text = text;
+        this.path = path;
+        this.offset = offset;
+        this.limit = limit;
+        this.i = open;
+    }
+    /** The cursor's place when it is inside the collection, else the offset after it. */
+    run() {
+        const { text, offset } = this;
+        while (this.i < this.limit) {
+            const c = text.charAt(this.i);
+            const top = this.stack.at(-1);
+            if (c === '{' || c === '[') {
+                // The cursor right before a bracket is between tokens, as before a `,`.
+                if (top !== undefined && this.i === offset)
+                    return placeIn(top, this.here(), false);
+                this.open(c, top);
+                continue;
+            }
+            if (top === undefined)
+                return this.i;
+            if (this.i === offset && (FLOW_BLANK.test(c) || c === ':' || c === '#'))
+                return placeIn(top, this.here(), false);
+            const r = this.step(c, top);
+            if (r !== undefined)
+                return r;
+            if (this.stack.length === 0)
+                return this.i;
+        }
+        const top = this.stack.at(-1);
+        return top === undefined ? this.i : placeIn(top, this.here(), false);
+    }
+    here() {
+        return { start: this.offset, end: this.offset };
+    }
+    /** A nested collection: its path goes through the key whose value it is. */
+    open(c, top) {
+        let inner = this.path;
+        if (top !== undefined) {
+            const keyed = top.map && top.value && top.key !== undefined && top.path !== undefined;
+            inner = keyed ? [...top.path, top.key] : undefined;
+            top.done = true;
+        }
+        this.stack.push({ map: c === '{', path: inner, value: false, done: false });
+        this.i++;
+    }
+    /** One token other than an opening bracket; the place when it holds the cursor. */
+    step(c, top) {
+        const { text } = this;
+        if (c === '}' || c === ']') {
+            this.stack.pop();
+            this.i++;
+        }
+        else if (c === ',') {
+            top.key = undefined;
+            top.value = false;
+            top.done = false;
+            this.i++;
+        }
+        else if (/\s/.test(c)) {
+            this.i++;
+        }
+        else if (c === '#' && /\s/.test(text.charAt(this.i - 1))) {
+            const end = Math.min(lineEnd(text, this.i), this.limit);
+            if (this.offset > this.i && this.offset <= end)
+                return null;
+            this.i = end;
+        }
+        else if (c === ':' && top.map && !top.value) {
+            top.value = true;
+            this.i++;
+        }
+        else if (c === '"' || c === "'") {
+            return this.quoted(c, top);
+        }
+        else {
+            return this.plain(top);
+        }
+        return undefined;
+    }
+    /** A quoted scalar; the cursor inside the quotes types a key. */
+    quoted(q, top) {
+        const { text, offset } = this;
+        const at = this.i;
+        const end = quotedEnd(text, at, this.limit);
+        const closed = end > at + 1 && text.charAt(end - 1) === q;
+        if (offset > at && (offset < end || !closed)) {
+            if (!/^[\w$-]*$/.test(text.slice(at + 1, offset)))
+                return null;
+            return placeIn(top, { start: at + 1, end: runEnd(text, offset, this.limit, PLAIN_KEY) }, true);
+        }
+        if (top.map && !top.value)
+            top.key = text.slice(at + 1, end - 1);
+        else
+            top.done = true;
+        this.i = end;
+        return undefined;
+    }
+    /** A plain scalar: to a flow indicator, the line end, `: ` after a key, or ` #`. */
+    plain(top) {
+        const { text, offset } = this;
+        const start = this.i;
+        const inKey = top.map && !top.value;
+        let i = start;
+        while (i < this.limit) {
+            const d = text.charAt(i);
+            if (',[]{}\r\n'.includes(d))
+                break;
+            if (d === ':' && inKey && FLOW_BLANK.test(text.charAt(i + 1) || ' '))
+                break;
+            if (d === '#' && /\s/.test(text.charAt(i - 1)))
+                break;
+            i++;
+        }
+        this.i = i;
+        if (offset >= start && offset <= i) {
+            const re = inKey ? PLAIN_KEY : FLOW_VALUE;
+            for (let k = start; k < offset; k++)
+                if (!re.test(text.charAt(k)))
+                    return null;
+            return placeIn(top, { start, end: runEnd(text, offset, this.limit, re) }, false);
+        }
+        if (inKey)
+            top.key = text.slice(start, i).trim();
+        else
+            top.done = true;
+        return undefined;
+    }
+}
+/**
+ * The cursor's place when it is inside a flow collection, from one forward scan over the lines
+ * before it that skips the collections closing before it. `undefined` when it is not inside one
+ * (block style), `null` when it is but nothing is offered there.
+ */
+function flowPlace(text, fm, offset) {
+    const yaml = fm.yamlRange;
+    let lineStart = yaml.start;
+    let first = true;
+    while (lineStart < yaml.end && lineStart <= offset) {
+        const end = runEnd(text, lineStart, yaml.end, /[^\r\n]/);
+        const line = text.slice(lineStart, end);
+        let next = end;
+        const m = FLOW_LINE.exec(line);
+        if (m !== null) {
+            const open = lineStart + m[0].length - 1;
+            const indent = m[1].length;
+            // The keys on the way: `key: {` under its block parents, none for `- {`, a root `{`.
+            let path = false;
+            if (m[2] !== undefined || m[3] !== undefined || m[4] !== undefined) {
+                const parent = parentPath(text, fm, lineStart, indent);
+                path = parent === undefined ? undefined : [...parent, keyOf(m, 2)];
+            }
+            else if (m[5] !== undefined)
+                path = undefined;
+            else if (first && indent === fm.indent)
+                path = [];
+            if (path !== false && open < offset) {
+                const r = new FlowScan(text, open, path, offset, yaml.end).run();
+                if (typeof r !== 'number')
+                    return r;
+                next = r;
+            }
+        }
+        if (line.trim() !== '' && !line.trimStart().startsWith('#'))
+            first = false;
+        const e = runEnd(text, next, yaml.end, /[^\r\n]/);
+        if (e >= yaml.end)
+            break;
+        lineStart = e + (text.startsWith('\r\n', e) ? 2 : 1);
+    }
+    return undefined;
+}
+export function frontMatterCompletions(ctx, fm, offset) {
+    const { text } = ctx;
+    const yaml = fm.yamlRange;
+    if (offset < yaml.start || offset > yaml.end)
+        return [];
+    const lineStart = lineStartOf(text, offset, yaml.start);
+    const cursorLineEnd = runEnd(text, offset, yaml.end, /[^\r\n]/);
+    const prefix = text.slice(lineStart, offset);
+    const flow = flowPlace(text, fm, offset);
+    if (flow === null)
+        return [];
+    if (flow !== undefined) {
+        if (flow.kind === 'value')
+            return valueItems(ctx, flow.path, flow.range);
+        const colon = /^[ \t]*:/.test(text.slice(flow.range.end, cursorLineEnd));
+        return keyItems(ctx, fm, flow.path, flow.range, flow.quoted || colon ? 'name' : 'flow', '');
+    }
+    const key = KEY_LINE.exec(prefix);
+    if (key !== null) {
+        const indent = key[1];
+        const parent = parentPath(text, fm, lineStart, indent.length);
+        if (parent === undefined)
+            return [];
+        const end = runEnd(text, offset, cursorLineEnd, PLAIN_KEY);
+        const colon = /^[ \t]*:/.test(text.slice(end, cursorLineEnd));
+        const style = key[2] !== '' || colon ? 'name' : 'block';
+        return keyItems(ctx, fm, parent, { start: offset - key[3].length, end }, style, indent);
+    }
+    const value = VALUE_LINE.exec(prefix);
+    if (value !== null) {
+        const parent = parentPath(text, fm, lineStart, value[1].length);
+        if (parent === undefined)
+            return [];
+        const end = runEnd(text, offset, cursorLineEnd, /[^\s#]/);
+        const range = { start: offset - value[5].length, end };
+        return valueItems(ctx, [...parent, keyOf(value, 2)], range);
+    }
+    return [];
+}

package/dist/config/front-matter.d.ts

@@ -0,0 +1,50 @@
+import type { Diagnostic, Range } from '@mermaid-js/core/parser-kit';
+import type { YamlMapNode, YamlNode, YamlPair } from '@mermaid-js/core/preprocess';
+import type { DocumentContext } from '../context.ts';
+import type { SchemaNode } from './schema.ts';
+/** The front matter of one snapshot, read once. */
+export interface FrontMatterTree {
+    /** The whole block, fences included; an unclosed one runs to the end of the text. */
+    readonly range: Range;
+    /** The YAML between the fences (to the end of the text when unclosed). */
+    readonly yamlRange: Range;
+    /** The fence's indent, which every YAML line shares. */
+    readonly indent: number;
+    /** No closing fence: the block runs to the end of the text, as preprocess reads it. */
+    readonly unclosed: boolean;
+    /** The document's root node; `null` when nothing could be read. */
+    readonly root: YamlNode | null;
+    /**
+     * The tree mode's YAML diagnostics (#168): one per bad line, where preprocess (and so the
+     * renderer, D91) stops at the first. Empty for an unclosed block, which preprocess does not
+     * read as YAML.
+     */
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function frontMatterTree(ctx: DocumentContext): FrontMatterTree | undefined;
+/**
+ * The config section the renderer resolves this type's config with (mermaid's `sectionOf`:
+ * the plugin id): a first-party row's generated `section` (none for a type with no v13
+ * package), a third-party row's id.
+ */
+export declare function configSection(ctx: DocumentContext): string | undefined;
+/** The mapping at a key path from the root (the first pair of a key), if there is one. */
+export declare function mapAt(root: YamlNode | null, path: readonly string[]): YamlMapNode | undefined;
+/** The key whose text holds `offset` (or ends at it), with its path from the root. */
+export declare function keyAt(root: YamlNode | null, offset: number): {
+    path: string[];
+    pair: YamlPair;
+} | undefined;
+/** The known key closest to `key`, when one is close enough to be a typo of it. */
+export declare function closest(key: string, known: Iterable<string>): string | undefined;
+/** Keys a user can still set (not removed or moved). */
+export declare function liveKeys(props: Map<string, SchemaNode>): string[];
+/** Keys diagram text cannot set: core's integrator-only and secure keys (R-SEC-5, R-SEC-6). */
+export declare function secureKeys(): ReadonlySet<string>;
+/**
+ * The config warnings a render gives for this front matter (core `resolveText`: unknown,
+ * removed, moved and secure keys, `look`, unsafe values), each on the key it names, an
+ * unknown one with a "did you mean" among the keys diagram text can set. None for an
+ * unclosed front matter or YAML with errors, which a render reads no config from.
+ */
+export declare function configDiagnostics(ctx: DocumentContext, fm: FrontMatterTree | undefined): Diagnostic[];