melusine 0.1.0

package/src/cli.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { formatRunFailure, generateTest, parse, runText, validateCatalog } from './index.js';
+import { initProject } from './scaffold.js';
+
+/**
+ * @typedef {import('./types.js').Catalog} Catalog
+ * @typedef {import('./types.js').Diagnostic} Diagnostic
+ * @typedef {import('./types.js').Gap} Gap
+ * @typedef {import('./types.js').RunResult} RunResult
+ */
+
+const HELP = `melusine - test Mermaid journey charts with reusable catalogs
+
+Usage:
+  melusine validate <journey.md> [--catalog <catalog.js>] [--export <name>] [--json]
+  melusine test <journey.md> --catalog <catalog.js> [--export <name>] [--json]
+  melusine compile <journey.md> --catalog <catalog.js> [--export <name>] --out <file>
+  melusine init [--force]
+
+Commands:
+  validate  Parse and validate a chart. With --catalog, also validate catalog references.
+  test      Execute a journey directly with a catalog.
+  compile   Write a node:test wrapper that calls the same direct runner.
+  init      Create a project-local starter catalog, journey, and package scripts.
+
+Options:
+  -c, --catalog <file>      ESM module exporting a catalog.
+      --export <name>       Named catalog export to load.
+  -o, --out <file>          Output file for compile.
+      --force               Overwrite starter files during init.
+      --json                Print machine-readable output.
+  -h, --help                Show this help.
+
+Catalog loading:
+  The CLI uses --export when provided. Otherwise it loads default, then catalog.
+
+Examples:
+  melusine init
+  melusine validate journeys/example.journey.md --catalog melusine.catalog.js
+  melusine test journeys/example.journey.md --catalog melusine.catalog.js
+  melusine compile journeys/example.journey.md --catalog melusine.catalog.js --out journeys/example.test.mjs
+`;
+
+/**
+ * CLI entrypoint.
+ *
+ * @param {string[]} argv Raw process arguments.
+ * @param {{ cwd?: string, stdout?: NodeJS.WritableStream, stderr?: NodeJS.WritableStream }} [io]
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function main(argv = process.argv.slice(2), io = {}) {
+  const cwd = io.cwd ?? process.cwd();
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+
+  try {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+      stdout.write(HELP);
+      return 0;
+    }
+
+    const command = argv[0];
+    const args = argv.slice(1);
+
+    if (command === 'validate') return validateCommand(args, { cwd, stdout, stderr });
+    if (command === 'test') return testCommand(args, { cwd, stdout, stderr });
+    if (command === 'compile') return compileCommand(args, { cwd, stdout, stderr });
+    if (command === 'init') return initCommand(args, { cwd, stdout });
+
+    stderr.write(`unknown command '${command}'\n\n${HELP}`);
+    return 1;
+  } catch (error) {
+    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ cwd: string, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream }} io
+ * @returns {Promise<number>}
+ */
+async function validateCommand(argv, io) {
+  const parsedArgs = parseArgs(argv);
+  const journeyPath = parsedArgs.positionals[0];
+  if (!journeyPath) throw new Error('validate requires <journey.md>');
+
+  const absoluteJourneyPath = resolve(io.cwd, journeyPath);
+  const text = await readFile(absoluteJourneyPath, 'utf8');
+  const parsed = parse(text);
+  let diagnostics = parsed.diagnostics;
+
+  if (!hasErrors(diagnostics) && parsedArgs.flags.catalog) {
+    const catalog = await loadCatalog(resolve(io.cwd, parsedArgs.flags.catalog), parsedArgs.flags.exportName);
+    diagnostics = diagnostics.concat(validateCatalog(parsed.graph, parsed.bindings, catalog));
+  }
+
+  if (parsedArgs.flags.json) {
+    io.stdout.write(`${JSON.stringify({
+      ok: !hasErrors(diagnostics),
+      diagnostics,
+      nodeCount: parsed.graph.nodes.size,
+      edgeCount: parsed.graph.edges.length,
+      start: parsed.graph.start,
+    }, null, 2)}\n`);
+  } else {
+    reportDiagnostics(diagnostics, io.stderr);
+    if (!hasErrors(diagnostics)) io.stderr.write(`valid: ${journeyPath}\n`);
+  }
+
+  return hasErrors(diagnostics) ? 1 : 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ cwd: string, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream }} io
+ * @returns {Promise<number>}
+ */
+async function testCommand(argv, io) {
+  const parsedArgs = parseArgs(argv);
+  const journeyPath = parsedArgs.positionals[0];
+  if (!journeyPath) throw new Error('test requires <journey.md>');
+  if (!parsedArgs.flags.catalog) throw new Error('test requires --catalog <catalog.js>');
+
+  const text = await readFile(resolve(io.cwd, journeyPath), 'utf8');
+  const catalog = await loadCatalog(resolve(io.cwd, parsedArgs.flags.catalog), parsedArgs.flags.exportName);
+  const result = await runText(text, catalog);
+
+  if (parsedArgs.flags.json) {
+    io.stdout.write(`${JSON.stringify(toJsonRunResult(result), null, 2)}\n`);
+  } else if (result.ok) {
+    io.stderr.write(`passed: ${journeyPath}\n`);
+  } else {
+    reportRunResult(result, io.stderr);
+  }
+
+  return result.ok ? 0 : 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ cwd: string, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream }} io
+ * @returns {Promise<number>}
+ */
+async function compileCommand(argv, io) {
+  const parsedArgs = parseArgs(argv);
+  const journeyPath = parsedArgs.positionals[0];
+  if (!journeyPath) throw new Error('compile requires <journey.md>');
+  if (!parsedArgs.flags.catalog) throw new Error('compile requires --catalog <catalog.js>');
+  if (!parsedArgs.flags.out) throw new Error('compile requires --out <file>');
+
+  const absoluteJourneyPath = resolve(io.cwd, journeyPath);
+  const absoluteCatalogPath = resolve(io.cwd, parsedArgs.flags.catalog);
+  const absoluteOutPath = resolve(io.cwd, parsedArgs.flags.out);
+  const text = await readFile(absoluteJourneyPath, 'utf8');
+  const parsed = parse(text);
+
+  let diagnostics = parsed.diagnostics;
+  if (!hasErrors(diagnostics)) {
+    const catalog = await loadCatalog(absoluteCatalogPath, parsedArgs.flags.exportName);
+    diagnostics = diagnostics.concat(validateCatalog(parsed.graph, parsed.bindings, catalog));
+  }
+  reportDiagnostics(diagnostics, io.stderr);
+  if (hasErrors(diagnostics)) return 1;
+
+  const testName = typeof parsed.meta.journey === 'string' ? `journey: ${parsed.meta.journey}` : undefined;
+  const code = generateTest({
+    journeyPath: absoluteJourneyPath,
+    catalogPath: absoluteCatalogPath,
+    outPath: absoluteOutPath,
+    exportName: parsedArgs.flags.exportName,
+    testName,
+  });
+
+  await mkdir(dirname(absoluteOutPath), { recursive: true });
+  await writeFile(absoluteOutPath, code, 'utf8');
+  io.stderr.write(`compiled: ${absoluteOutPath}\n`);
+  return 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ cwd: string, stdout: NodeJS.WritableStream }} io
+ * @returns {Promise<number>}
+ */
+async function initCommand(argv, io) {
+  const parsedArgs = parseArgs(argv);
+  const written = await initProject(io.cwd, { force: parsedArgs.flags.force });
+  for (const path of written) {
+    io.stdout.write(`created: ${path}\n`);
+  }
+  return 0;
+}
+
+/**
+ * @typedef {object} ParsedArgs
+ * @property {string[]} positionals
+ * @property {{ catalog?: string, exportName?: string, out?: string, force: boolean, json: boolean }} flags
+ */
+
+/**
+ * @param {string[]} argv
+ * @returns {ParsedArgs}
+ */
+function parseArgs(argv) {
+  /** @type {string[]} */
+  const positionals = [];
+  /** @type {ParsedArgs['flags']} */
+  const flags = { force: false, json: false };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '-c' || arg === '--catalog') {
+      flags.catalog = requireValue(argv, i, arg);
+      i += 1;
+    } else if (arg === '-o' || arg === '--out') {
+      flags.out = requireValue(argv, i, arg);
+      i += 1;
+    } else if (arg === '--export' || arg === '--catalog-export') {
+      flags.exportName = requireValue(argv, i, arg);
+      i += 1;
+    } else if (arg === '--json') {
+      flags.json = true;
+    } else if (arg === '--force') {
+      flags.force = true;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`unknown option '${arg}'`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  return { positionals, flags };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {number} index
+ * @param {string} flag
+ * @returns {string}
+ */
+function requireValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith('-')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+/**
+ * @param {string} catalogPath
+ * @param {string | undefined} exportName
+ * @returns {Promise<Catalog>}
+ */
+async function loadCatalog(catalogPath, exportName) {
+  const module = await import(pathToFileURL(catalogPath).href);
+  const candidate = exportName ? module[exportName] : (module.default ?? module.catalog);
+
+  if (!candidate) {
+    const suffix = exportName ? `export '${exportName}'` : 'a default export or named export `catalog`';
+    throw new Error(`catalog module must provide ${suffix}`);
+  }
+
+  return candidate;
+}
+
+/**
+ * @param {Diagnostic[]} diagnostics
+ * @param {NodeJS.WritableStream} stream
+ */
+function reportDiagnostics(diagnostics, stream) {
+  for (const diagnostic of diagnostics) {
+    const node = diagnostic.node ? ` [${diagnostic.node}]` : '';
+    stream.write(`${diagnostic.severity} ${diagnostic.code}${node}: ${diagnostic.message}\n`);
+  }
+}
+
+/**
+ * @param {RunResult} result
+ * @param {NodeJS.WritableStream} stream
+ */
+function reportRunResult(result, stream) {
+  reportDiagnostics(result.diagnostics, stream);
+  for (const gap of result.gaps) {
+    stream.write(`gap ${gap.kind} [${gap.nodeId}]: ${gap.reason}\n`);
+  }
+  for (const error of result.errors) {
+    stream.write(`error [${error.nodeId}]: ${error.message}\n`);
+  }
+  for (const score of result.scores) {
+    if (score.role === 'outcome' && !score.result.pass) {
+      stream.write(`failed scorer [${score.node.id}]: ${score.result.message ?? 'score did not pass'}\n`);
+    }
+  }
+}
+
+/**
+ * @param {Diagnostic[]} diagnostics
+ * @returns {boolean}
+ */
+function hasErrors(diagnostics) {
+  return diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+}
+
+/**
+ * @param {RunResult} result
+ * @returns {object}
+ */
+function toJsonRunResult(result) {
+  return {
+    ok: result.ok,
+    diagnostics: result.diagnostics,
+    gaps: result.gaps,
+    errors: result.errors,
+    scores: result.scores.map((score) => ({
+      nodeId: score.node.id,
+      entryKey: score.entryKey,
+      role: score.role,
+      branch: score.branch,
+      result: score.result,
+    })),
+    failure: result.ok ? undefined : formatRunFailure(result),
+  };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  process.exitCode = await main();
+}

package/src/compile.js

@@ -0,0 +1,3 @@
+// @ts-check
+
+export { run as compile, runText as compileText } from './run.js';

package/src/generate.js

@@ -0,0 +1,52 @@
+// @ts-check
+
+import { basename, dirname, relative, sep } from 'node:path';
+
+/**
+ * @typedef {import('./types.js').GenerateOptions} GenerateOptions
+ */
+
+/**
+ * Generate a small node:test wrapper that calls Melusine's direct runner.
+ *
+ * @param {GenerateOptions} options Generation options.
+ * @returns {string}
+ */
+export function generateTest(options) {
+  const packageName = options.packageName ?? 'melusine';
+  const outDir = options.outPath ? dirname(options.outPath) : process.cwd();
+  const journeySpecifier = toImportSpecifier(relative(outDir, options.journeyPath));
+  const catalogSpecifier = toImportSpecifier(relative(outDir, options.catalogPath));
+  const testName = options.testName ?? `journey: ${basename(options.journeyPath)}`;
+  const catalogExpression = options.exportName
+    ? `catalogModule[${JSON.stringify(options.exportName)}]`
+    : '(catalogModule.default ?? catalogModule.catalog)';
+
+  return [
+    `import test from 'node:test';`,
+    `import assert from 'node:assert/strict';`,
+    `import { readFile } from 'node:fs/promises';`,
+    `import { formatRunFailure, runText } from ${JSON.stringify(packageName)};`,
+    `import * as catalogModule from ${JSON.stringify(catalogSpecifier)};`,
+    ``,
+    `const catalog = ${catalogExpression};`,
+    `const journeyUrl = new URL(${JSON.stringify(journeySpecifier)}, import.meta.url);`,
+    ``,
+    `test(${JSON.stringify(testName)}, async () => {`,
+    `  assert.ok(catalog && typeof catalog === 'object', 'catalog module did not export a catalog object');`,
+    `  const text = await readFile(journeyUrl, 'utf8');`,
+    `  const result = await runText(text, catalog);`,
+    `  assert.equal(result.ok, true, formatRunFailure(result));`,
+    `});`,
+    ``,
+  ].join('\n');
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function toImportSpecifier(value) {
+  const normalized = value.split(sep).join('/');
+  return normalized.startsWith('.') ? normalized : `./${normalized}`;
+}

package/src/index.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+export { parse } from './parse.js';
+export { task, scorer, todo, hole, normalizeScoreResult, validateCatalog } from './catalog.js';
+export { run, runText, formatRunFailure } from './run.js';
+export { compile, compileText } from './compile.js';
+export { generateTest } from './generate.js';
+export * from './types.js';
+
+/**
+ * @typedef {import('./types.js').NodeKind} NodeKind
+ * @typedef {import('./types.js').Node} Node
+ * @typedef {import('./types.js').Edge} Edge
+ * @typedef {import('./types.js').JourneyGraph} JourneyGraph
+ * @typedef {import('./types.js').Binding} Binding
+ * @typedef {import('./types.js').Diagnostic} Diagnostic
+ * @typedef {import('./types.js').ParseResult} ParseResult
+ * @typedef {import('./types.js').NodeConfig} NodeConfig
+ * @typedef {import('./types.js').CatalogCall} CatalogCall
+ * @typedef {import('./types.js').TaskEntry} TaskEntry
+ * @typedef {import('./types.js').ScorerEntry} ScorerEntry
+ * @typedef {import('./types.js').CatalogEntry} CatalogEntry
+ * @typedef {import('./types.js').Catalog} Catalog
+ * @typedef {import('./types.js').ScoreResult} ScoreResult
+ * @typedef {import('./types.js').Gap} Gap
+ * @typedef {import('./types.js').RunResult} RunResult
+ * @typedef {import('./types.js').RunOptions} RunOptions
+ */

package/src/parse.js

@@ -0,0 +1,263 @@
+// @ts-check
+
+import YAML from 'yaml';
+import { validate } from './validate.js';
+
+/**
+ * @typedef {import('./types.js').Binding} Binding
+ * @typedef {import('./types.js').Diagnostic} Diagnostic
+ * @typedef {import('./types.js').Edge} Edge
+ * @typedef {import('./types.js').JourneyGraph} JourneyGraph
+ * @typedef {import('./types.js').Node} Node
+ * @typedef {import('./types.js').NodeKind} NodeKind
+ * @typedef {import('./types.js').ParseResult} ParseResult
+ */
+
+const ID = '[A-Za-z][A-Za-z0-9_-]*';
+const PROCESS_RE = new RegExp(`^(${ID})\\s*\\[\\s*(?:"([^"\`]*)"|([^\`\\]]*?))\\s*\\]$`, 'u');
+const DECISION_RE = new RegExp(`^(${ID})\\s*\\{\\s*(?:"([^"\`]*)"|([^\`}]*?))\\s*\\}$`, 'u');
+const TERMINAL_RE = new RegExp(`^(${ID})\\s*\\(\\s*\\[\\s*(?:"([^"\`]*)"|([^\`\\]]*?))\\s*\\]\\s*\\)$`, 'u');
+const BARE_RE = new RegExp(`^${ID}$`, 'u');
+
+/**
+ * Parse Markdown containing optional YAML frontmatter and the first Mermaid
+ * flowchart fence into the journey IR.
+ *
+ * Author mistakes are reported as diagnostics. This function only throws for
+ * ordinary JavaScript programmer errors outside the supported input contract.
+ *
+ * @param {string} text Markdown journey text.
+ * @returns {ParseResult}
+ */
+export function parse(text) {
+  /** @type {Diagnostic[]} */
+  const diagnostics = [];
+  const split = splitFrontmatter(text);
+  const { bindings, meta } = parseFrontmatter(split.frontmatter, diagnostics);
+  const mermaid = extractMermaid(split.body);
+
+  if (!mermaid) {
+    return {
+      graph: { nodes: new Map(), edges: [], start: '' },
+      bindings,
+      meta,
+      diagnostics: diagnostics.concat({
+        severity: 'error',
+        code: 'JOURNEY_NO_MERMAID',
+        message: 'no mermaid code block found',
+      }),
+    };
+  }
+
+  const parsed = parseMermaid(mermaid, diagnostics);
+  const validationDiagnostics = validate(parsed.graph);
+  return {
+    graph: parsed.graph,
+    bindings,
+    meta,
+    diagnostics: diagnostics.concat(validationDiagnostics),
+  };
+}
+
+/**
+ * @param {string} text
+ * @returns {{ frontmatter: string | undefined, body: string }}
+ */
+function splitFrontmatter(text) {
+  if (!text.startsWith('---\n') && !text.startsWith('---\r\n')) {
+    return { frontmatter: undefined, body: text };
+  }
+
+  const match = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/u.exec(text);
+  if (!match) {
+    return { frontmatter: undefined, body: text };
+  }
+
+  return {
+    frontmatter: match[1],
+    body: text.slice(match[0].length),
+  };
+}
+
+/**
+ * @param {string | undefined} frontmatter
+ * @param {Diagnostic[]} diagnostics
+ * @returns {{ bindings: Map<string, Binding>, meta: Record<string, unknown> }}
+ */
+function parseFrontmatter(frontmatter, diagnostics) {
+  /** @type {Map<string, Binding>} */
+  const bindings = new Map();
+  /** @type {Record<string, unknown>} */
+  const meta = {};
+
+  if (frontmatter === undefined) {
+    return { bindings, meta };
+  }
+
+  try {
+    const document = YAML.parse(frontmatter) ?? {};
+    if (!isRecord(document)) {
+      return { bindings, meta };
+    }
+
+    for (const [key, value] of Object.entries(document)) {
+      if (key === 'nodes') {
+        if (isRecord(value)) {
+          for (const [nodeId, binding] of Object.entries(value)) {
+            bindings.set(nodeId, binding);
+          }
+        }
+      } else {
+        meta[key] = value;
+      }
+    }
+  } catch (error) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'JOURNEY_FRONTMATTER_INVALID',
+      message: `frontmatter could not be parsed as YAML: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+
+  return { bindings, meta };
+}
+
+/**
+ * @param {string} body
+ * @returns {string | undefined}
+ */
+function extractMermaid(body) {
+  const match = /```mermaid[ \t]*\r?\n([\s\S]*?)\r?\n```/iu.exec(body);
+  return match?.[1];
+}
+
+/**
+ * @param {string} mermaid
+ * @param {Diagnostic[]} diagnostics
+ * @returns {{ graph: JourneyGraph }}
+ */
+function parseMermaid(mermaid, diagnostics) {
+  /** @type {Map<string, Node>} */
+  const nodes = new Map();
+  /** @type {Edge[]} */
+  const edges = [];
+  /** @type {Set<string>} */
+  const referencedBare = new Set();
+
+  for (const rawLine of mermaid.split(/\r?\n/u)) {
+    const line = rawLine.trim().replace(/;$/u, '');
+    if (!line || line.startsWith('%%')) continue;
+    if (/^(?:graph|flowchart)\s+(?:TD|LR)$/iu.test(line)) continue;
+
+    if (hasUnsupportedEdge(line)) {
+      diagnostics.push({
+        severity: 'warning',
+        code: 'JOURNEY_UNSUPPORTED_EDGE',
+        message: `unsupported edge syntax ignored: ${line}`,
+      });
+      continue;
+    }
+
+    const edge = parseEdge(line);
+    if (edge) {
+      if (edge.from.node) nodes.set(edge.from.node.id, edge.from.node);
+      else referencedBare.add(edge.from.id);
+
+      if (edge.to.node) nodes.set(edge.to.node.id, edge.to.node);
+      else referencedBare.add(edge.to.id);
+
+      edges.push({ from: edge.from.id, to: edge.to.id, ...(edge.label ? { label: edge.label } : {}) });
+      continue;
+    }
+
+    const term = parseTerm(line);
+    if (term?.node) {
+      nodes.set(term.node.id, term.node);
+    }
+  }
+
+  for (const id of referencedBare) {
+    if (!nodes.has(id)) {
+      nodes.set(id, { id, kind: 'process', label: id });
+      diagnostics.push({
+        severity: 'info',
+        code: 'JOURNEY_BARE_NODE',
+        message: `node '${id}' was referenced without a shape and defaulted to process`,
+        node: id,
+      });
+    }
+  }
+
+  return {
+    graph: { nodes, edges, start: '' },
+  };
+}
+
+/**
+ * @param {string} line
+ * @returns {boolean}
+ */
+function hasUnsupportedEdge(line) {
+  return line.includes('-.->') || line.includes('==>') || (line.includes('---') && !line.includes('-->'));
+}
+
+/**
+ * @typedef {{ id: string, node?: Node }} ParsedTerm
+ * @typedef {{ from: ParsedTerm, to: ParsedTerm, label?: string }} ParsedEdge
+ */
+
+/**
+ * @param {string} line
+ * @returns {ParsedEdge | undefined}
+ */
+function parseEdge(line) {
+  const match = /^(.*?)\s*-->\s*(?:\|\s*([^|]+?)\s*\|\s*)?(.*?)$/u.exec(line);
+  if (!match) return undefined;
+
+  const from = parseTerm(match[1].trim());
+  const to = parseTerm(match[3].trim());
+  if (!from || !to) return undefined;
+
+  const label = match[2]?.trim();
+  return { from, to, ...(label ? { label } : {}) };
+}
+
+/**
+ * Parse either a shaped node term or a bare node id.
+ *
+ * @param {string} text
+ * @returns {ParsedTerm | undefined}
+ */
+function parseTerm(text) {
+  const terminal = TERMINAL_RE.exec(text);
+  if (terminal) return termFromMatch(terminal, 'terminal');
+
+  const process = PROCESS_RE.exec(text);
+  if (process) return termFromMatch(process, 'process');
+
+  const decision = DECISION_RE.exec(text);
+  if (decision) return termFromMatch(decision, 'decision');
+
+  if (BARE_RE.test(text)) return { id: text };
+
+  return undefined;
+}
+
+/**
+ * @param {RegExpExecArray} match
+ * @param {NodeKind} kind
+ * @returns {ParsedTerm}
+ */
+function termFromMatch(match, kind) {
+  const id = match[1];
+  const label = match[2] ?? match[3]?.trim() ?? id;
+  return { id, node: { id, kind, label } };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}