melusine 0.1.0

package/src/run.js

@@ -0,0 +1,258 @@
+// @ts-check
+
+import {
+  expectedRole,
+  getCatalogEntry,
+  isGapSignal,
+  missingRequiredInput,
+  normalizeScoreResult,
+  readNodeConfig,
+  storageKeyFor,
+  validateCatalog,
+} from './catalog.js';
+import { parse } from './parse.js';
+import { outgoingByNode } from './validate.js';
+import { selectDecisionEdge } from './walk.js';
+
+/**
+ * @typedef {import('./types.js').Catalog} Catalog
+ * @typedef {import('./types.js').Diagnostic} Diagnostic
+ * @typedef {import('./types.js').ExecutedStep} ExecutedStep
+ * @typedef {import('./types.js').Gap} Gap
+ * @typedef {import('./types.js').GapSignal} GapSignal
+ * @typedef {import('./types.js').Node} Node
+ * @typedef {import('./types.js').ParseResult} ParseResult
+ * @typedef {import('./types.js').RunError} RunError
+ * @typedef {import('./types.js').RunOptions} RunOptions
+ * @typedef {import('./types.js').RunResult} RunResult
+ * @typedef {import('./types.js').ScoreStep} ScoreStep
+ */
+
+/**
+ * Execute a parsed journey directly against a reusable catalog.
+ *
+ * Structural and catalog validation errors short-circuit before catalog
+ * functions run. Programmer errors in catalog definitions or scorer return
+ * shapes throw.
+ *
+ * @param {ParseResult} parsed Parsed journey.
+ * @param {Catalog} catalog Reusable catalog.
+ * @param {RunOptions} [options] Run options.
+ * @returns {Promise<RunResult>}
+ */
+export async function run(parsed, catalog, options = {}) {
+  const structuralDiagnostics = parsed.diagnostics;
+  if (hasErrors(structuralDiagnostics)) {
+    return emptyResult(parsed, structuralDiagnostics);
+  }
+
+  const diagnostics = structuralDiagnostics.concat(validateCatalog(parsed.graph, parsed.bindings, catalog, options));
+  if (hasErrors(diagnostics)) {
+    return emptyResult(parsed, diagnostics);
+  }
+
+  const outgoing = outgoingByNode(parsed.graph);
+  /** @type {Record<string, unknown>} */
+  const context = {};
+  /** @type {ExecutedStep[]} */
+  const steps = [];
+  /** @type {ScoreStep[]} */
+  const scores = [];
+  /** @type {Gap[]} */
+  const gaps = [];
+  /** @type {RunError[]} */
+  const errors = [];
+
+  let current = parsed.graph.start;
+  while (current) {
+    const node = parsed.graph.nodes.get(current);
+    if (!node) break;
+
+    const config = readNodeConfig(parsed.bindings.get(node.id), node.id);
+    const entry = getCatalogEntry(catalog, config.use);
+    const missing = missingRequiredInput(entry, config, node.id);
+    if (missing) {
+      collectGap(node, config.use, missing, gaps, steps);
+      break;
+    }
+
+    const call = {
+      args: config.args,
+      context,
+      meta: parsed.meta,
+      node,
+      previous: steps,
+      config,
+      key: config.use,
+    };
+
+    if (entry.kind === 'task') {
+      try {
+        const output = await entry.run(call);
+        if (isGapSignal(output)) {
+          collectGap(node, config.use, output, gaps, steps);
+          break;
+        }
+
+        const storedAs = storageKeyFor(entry, config, node);
+        context[storedAs] = output;
+        steps.push({
+          type: 'task',
+          node,
+          entryKey: config.use,
+          args: config.args,
+          output,
+          storedAs,
+        });
+        current = (outgoing.get(node.id) ?? [])[0]?.to ?? '';
+      } catch (error) {
+        const runError = {
+          nodeId: node.id,
+          entryKey: config.use,
+          message: error instanceof Error ? error.message : String(error),
+        };
+        errors.push(runError);
+        steps.push({ type: 'error', node, entryKey: config.use, error: runError });
+        break;
+      }
+    } else {
+      let rawScore;
+      try {
+        rawScore = await entry.run(call);
+        if (isGapSignal(rawScore)) {
+          collectGap(node, config.use, rawScore, gaps, steps);
+          break;
+        }
+      } catch (error) {
+        const runError = {
+          nodeId: node.id,
+          entryKey: config.use,
+          message: error instanceof Error ? error.message : String(error),
+        };
+        errors.push(runError);
+        steps.push({ type: 'error', node, entryKey: config.use, error: runError });
+        break;
+      }
+
+      const result = normalizeScoreResult(rawScore, entry.threshold);
+      const role = expectedRole(node, parsed.graph.start) === 'scorer' && node.kind === 'decision' ? 'decision' : 'outcome';
+      /** @type {ScoreStep} */
+      const scoreStep = {
+        type: 'score',
+        node,
+        entryKey: config.use,
+        role,
+        args: config.args,
+        result,
+      };
+
+      if (node.kind === 'decision') {
+        const edge = selectDecisionEdge(outgoing.get(node.id) ?? [], result.pass);
+        if (edge?.label) scoreStep.branch = edge.label;
+        steps.push(scoreStep);
+        scores.push(scoreStep);
+        current = edge?.to ?? '';
+      } else {
+        steps.push(scoreStep);
+        scores.push(scoreStep);
+        current = (outgoing.get(node.id) ?? [])[0]?.to ?? '';
+      }
+    }
+  }
+
+  return {
+    ok: diagnostics.every((diagnostic) => diagnostic.severity !== 'error')
+      && gaps.length === 0
+      && errors.length === 0
+      && scores.filter((score) => score.role === 'outcome').every((score) => score.result.pass),
+    meta: parsed.meta,
+    context,
+    steps,
+    scores,
+    gaps,
+    errors,
+    diagnostics,
+  };
+}
+
+/**
+ * Parse and execute a journey directly against a reusable catalog.
+ *
+ * @param {string} text Markdown journey text.
+ * @param {Catalog} catalog Reusable catalog.
+ * @param {RunOptions} [options] Run options.
+ * @returns {Promise<RunResult>}
+ */
+export function runText(text, catalog, options = {}) {
+  return run(parse(text), catalog, options);
+}
+
+/**
+ * Format diagnostics, gaps, runtime errors, and failed outcome scores for CLI
+ * output and generated node:test assertions.
+ *
+ * @param {RunResult} result Run result.
+ * @returns {string}
+ */
+export function formatRunFailure(result) {
+  /** @type {string[]} */
+  const lines = [];
+
+  for (const diagnostic of result.diagnostics) {
+    if (diagnostic.severity === 'error') {
+      lines.push(`${diagnostic.code}${diagnostic.node ? ` [${diagnostic.node}]` : ''}: ${diagnostic.message}`);
+    }
+  }
+  for (const gap of result.gaps) {
+    lines.push(`gap ${gap.kind} [${gap.nodeId}]: ${gap.reason}`);
+  }
+  for (const error of result.errors) {
+    lines.push(`error [${error.nodeId}]: ${error.message}`);
+  }
+  for (const score of result.scores) {
+    if (score.role === 'outcome' && !score.result.pass) {
+      lines.push(`failed scorer [${score.node.id}]: ${score.result.message ?? 'score did not pass'}`);
+    }
+  }
+
+  return lines.length > 0 ? lines.join('\n') : 'journey did not pass';
+}
+
+/**
+ * @param {ParseResult} parsed
+ * @param {Diagnostic[]} diagnostics
+ * @returns {RunResult}
+ */
+function emptyResult(parsed, diagnostics) {
+  return {
+    ok: false,
+    meta: parsed.meta,
+    context: {},
+    steps: [],
+    scores: [],
+    gaps: [],
+    errors: [],
+    diagnostics,
+  };
+}
+
+/**
+ * @param {Diagnostic[]} diagnostics
+ * @returns {boolean}
+ */
+function hasErrors(diagnostics) {
+  return diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+}
+
+/**
+ * @param {Node} node
+ * @param {string} entryKey
+ * @param {GapSignal} signal
+ * @param {Gap[]} gaps
+ * @param {ExecutedStep[]} steps
+ */
+function collectGap(node, entryKey, signal, gaps, steps) {
+  const gap = { nodeId: node.id, entryKey, kind: signal.kind, reason: signal.reason };
+  gaps.push(gap);
+  steps.push({ type: 'gap', node, entryKey, gap });
+}

package/src/scaffold.js

@@ -0,0 +1,142 @@
+// @ts-check
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/**
+ * @typedef {object} InitOptions
+ * @property {boolean} [force] Overwrite starter files when they already exist.
+ */
+
+/**
+ * Create a project-local Melusine starter.
+ *
+ * @param {string} cwd Target project directory.
+ * @param {InitOptions} [options] Init options.
+ * @returns {Promise<string[]>} Files written or updated.
+ */
+export async function initProject(cwd, options = {}) {
+  const catalogPath = join(cwd, 'melusine.catalog.js');
+  const journeyPath = join(cwd, 'journeys', 'example.journey.md');
+  const packagePath = join(cwd, 'package.json');
+  const packageJson = await readPackageJson(packagePath);
+  const force = options.force === true;
+  /** @type {string[]} */
+  const written = [];
+
+  if (!force) {
+    await assertMissing(catalogPath);
+    await assertMissing(journeyPath);
+  }
+
+  await writeNewFile(catalogPath, STARTER_CATALOG);
+  written.push(catalogPath);
+  await writeNewFile(journeyPath, STARTER_JOURNEY);
+  written.push(journeyPath);
+
+  if (packageJson) {
+    /** @type {Record<string, string>} */
+    const scripts = typeof packageJson.scripts === 'object'
+      && packageJson.scripts !== null
+      && !Array.isArray(packageJson.scripts)
+      ? /** @type {Record<string, string>} */ (packageJson.scripts)
+      : {};
+    scripts['melusine:validate'] = 'melusine validate journeys/example.journey.md --catalog melusine.catalog.js';
+    scripts['melusine:test'] = 'melusine test journeys/example.journey.md --catalog melusine.catalog.js';
+    packageJson.scripts = scripts;
+    await writeFile(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8');
+    written.push(packagePath);
+  }
+
+  return written;
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<Record<string, unknown> | undefined>}
+ */
+async function readPackageJson(path) {
+  try {
+    const pkg = JSON.parse(await readFile(path, 'utf8'));
+    if (typeof pkg !== 'object' || pkg === null || Array.isArray(pkg)) {
+      throw new Error('package.json must contain an object');
+    }
+    return pkg;
+  } catch (error) {
+    if (error && typeof error === 'object' && Reflect.get(error, 'code') === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {string} path
+ */
+async function assertMissing(path) {
+  try {
+    await readFile(path, 'utf8');
+    throw new Error(`refusing to overwrite existing file: ${path}`);
+  } catch (error) {
+    if (!(error && typeof error === 'object' && Reflect.get(error, 'code') === 'ENOENT')) {
+      throw error;
+    }
+  }
+}
+
+/**
+ * @param {string} path
+ * @param {string} text
+ */
+async function writeNewFile(path, text) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, text, 'utf8');
+}
+
+const STARTER_CATALOG = `// @ts-check
+
+import { scorer, task } from 'melusine';
+
+export default {
+  createSubject: task(({ args }) => {
+    return { name: args[0], completed: false };
+  }, { as: 'subject', requiredArgs: 1 }),
+
+  completeSubject: task(({ context }) => {
+    const subject = context.subject;
+    if (!subject || typeof subject !== 'object') {
+      throw new Error('subject missing from context');
+    }
+    subject.completed = true;
+    return subject;
+  }),
+
+  subjectCompleted: scorer(({ context }) => {
+    return {
+      pass: context.subject?.completed === true,
+      actual: context.subject?.completed,
+      expected: true,
+      message: 'subject should be completed',
+    };
+  }),
+};
+`;
+
+const STARTER_JOURNEY = `---
+journey: melusine-starter
+nodes:
+  createSubject:
+    args: ["starter"]
+    as: subject
+---
+
+# Melusine starter journey
+
+\`\`\`mermaid
+graph TD
+  start(["Start"]) --> createSubject
+  createSubject["Create subject"] --> completeSubject
+  completeSubject["Complete subject"] --> subjectCompleted
+  subjectCompleted(["Subject completed"])
+\`\`\`
+`;