melusine 0.1.0

package/src/types.js

@@ -0,0 +1,330 @@
+// @ts-check
+
+/**
+ * Structural kind inferred from a supported Mermaid node shape.
+ *
+ * @typedef {'terminal' | 'process' | 'decision'} NodeKind
+ */
+
+/**
+ * A node in the parsed journey graph.
+ *
+ * @typedef {object} Node
+ * @property {string} id Stable Mermaid node id.
+ * @property {NodeKind} kind Structural kind inferred from shape.
+ * @property {string} label Human-readable label from the diagram.
+ */
+
+/**
+ * A directed edge in source order.
+ *
+ * @typedef {object} Edge
+ * @property {string} from Source node id.
+ * @property {string} to Destination node id.
+ * @property {string} [label] Branch label, such as "yes" or "no".
+ */
+
+/**
+ * Parsed journey graph. `start` is populated when validation finds exactly one
+ * zero-incoming terminal.
+ *
+ * @typedef {object} JourneyGraph
+ * @property {Map<string, Node>} nodes Node id to node.
+ * @property {Edge[]} edges Edges in Mermaid source order.
+ * @property {string} start Unique start node id, or an empty string when invalid.
+ */
+
+/**
+ * Opaque per-node frontmatter value.
+ *
+ * @typedef {unknown} Binding
+ */
+
+/**
+ * A stable diagnostic for author-input issues or parser notes.
+ *
+ * @typedef {object} Diagnostic
+ * @property {'error' | 'warning' | 'info'} severity Diagnostic severity.
+ * @property {string} code Stable screaming-snake diagnostic code.
+ * @property {string} message Human-readable explanation.
+ * @property {string} [node] Node id when the diagnostic is node-scoped.
+ */
+
+/**
+ * Result returned by `parse()`.
+ *
+ * @typedef {object} ParseResult
+ * @property {JourneyGraph} graph Parsed graph.
+ * @property {Map<string, Binding>} bindings Node id to opaque frontmatter config.
+ * @property {Record<string, unknown>} meta Frontmatter minus `nodes`.
+ * @property {Diagnostic[]} diagnostics Parser and structural validation diagnostics.
+ */
+
+/**
+ * Per-node catalog configuration read from frontmatter.
+ *
+ * `use` chooses a reusable catalog key for this graph. `as` chooses where a
+ * task output is stored in execution context. Extra fields are passed to the
+ * catalog function in `options`.
+ *
+ * @typedef {object} NodeConfig
+ * @property {string} use Catalog key. Defaults to node id.
+ * @property {unknown[]} args Positional arguments for this node.
+ * @property {string | undefined} as Context key override for task output.
+ * @property {Record<string, unknown>} options Extra per-journey options.
+ * @property {Binding | undefined} raw Original binding value.
+ */
+
+/**
+ * Previous execution state supplied to catalog functions.
+ *
+ * @typedef {TaskStep | ScoreStep | GapStep | ErrorStep} ExecutedStep
+ */
+
+/**
+ * Object passed to every task and scorer function.
+ *
+ * @typedef {object} CatalogCall
+ * @property {unknown[]} args Node-specific args from frontmatter.
+ * @property {Record<string, unknown>} context Mutable execution context.
+ * @property {Record<string, unknown>} meta Journey frontmatter minus `nodes`.
+ * @property {Node} node Source graph node.
+ * @property {ExecutedStep[]} previous Steps that have run before this node.
+ * @property {NodeConfig} config Normalized node config.
+ * @property {string} key Resolved catalog key.
+ */
+
+/**
+ * Pending fragment for a known unresolved step.
+ *
+ * @typedef {object} TodoGap
+ * @property {'todo'} kind
+ * @property {string} reason Why the step is unresolved.
+ */
+
+/**
+ * Pending fragment for missing human-supplied input.
+ *
+ * @typedef {object} HoleGap
+ * @property {'hole'} kind
+ * @property {string} reason What input is missing.
+ */
+
+/**
+ * A catalog function may return one of these to stop execution honestly.
+ *
+ * @typedef {TodoGap | HoleGap} GapSignal
+ */
+
+/**
+ * Function wrapped by `task(...)`.
+ *
+ * @callback TaskHandler
+ * @param {CatalogCall} input
+ * @returns {unknown | GapSignal | Promise<unknown | GapSignal>}
+ */
+
+/**
+ * Raw values accepted from scorer functions before normalization.
+ *
+ * @typedef {boolean | number | StructuredScore | NumericScore | GapSignal} ScorerReturn
+ */
+
+/**
+ * Structured pass/fail scorer result.
+ *
+ * @typedef {object} StructuredScore
+ * @property {boolean} pass
+ * @property {string} [message]
+ * @property {unknown} [actual]
+ * @property {unknown} [expected]
+ */
+
+/**
+ * Numeric scorer result. The result passes when `score >= threshold`.
+ *
+ * @typedef {object} NumericScore
+ * @property {number} score
+ * @property {number} [threshold]
+ * @property {string} [message]
+ * @property {unknown} [actual]
+ * @property {unknown} [expected]
+ */
+
+/**
+ * Normalized scorer result returned by Melusine.
+ *
+ * @typedef {object} ScoreResult
+ * @property {boolean} pass Whether the score passed.
+ * @property {number} [score] Numeric score when one was returned.
+ * @property {number} [threshold] Numeric threshold when one was used.
+ * @property {string} [message] Optional failure or detail message.
+ * @property {unknown} [actual] Optional actual value.
+ * @property {unknown} [expected] Optional expected value.
+ */
+
+/**
+ * Function wrapped by `scorer(...)`.
+ *
+ * @callback ScorerHandler
+ * @param {CatalogCall} input
+ * @returns {ScorerReturn | Promise<ScorerReturn>}
+ */
+
+/**
+ * Shared catalog entry options.
+ *
+ * @typedef {object} CatalogEntryOptions
+ * @property {number} [requiredArgs] Minimum number of args required before running.
+ * @property {string[]} [requiredOptions] Option keys required before running.
+ * @property {Record<string, unknown>} [meta] Entry-owned metadata.
+ */
+
+/**
+ * Options for `task(...)`.
+ *
+ * @typedef {CatalogEntryOptions & { as?: string }} TaskOptions
+ */
+
+/**
+ * Options for `scorer(...)`.
+ *
+ * @typedef {CatalogEntryOptions & { threshold?: number }} ScorerOptions
+ */
+
+/**
+ * Reusable catalog task entry.
+ *
+ * @typedef {object} TaskEntry
+ * @property {'task'} kind
+ * @property {TaskHandler} run
+ * @property {string | undefined} as Default context storage key.
+ * @property {number | undefined} requiredArgs Minimum required args.
+ * @property {string[]} requiredOptions Required option keys.
+ * @property {Record<string, unknown>} meta Entry-owned metadata.
+ */
+
+/**
+ * Reusable catalog scorer entry.
+ *
+ * @typedef {object} ScorerEntry
+ * @property {'scorer'} kind
+ * @property {ScorerHandler} run
+ * @property {number | undefined} threshold Default numeric score threshold.
+ * @property {number | undefined} requiredArgs Minimum required args.
+ * @property {string[]} requiredOptions Required option keys.
+ * @property {Record<string, unknown>} meta Entry-owned metadata.
+ */
+
+/**
+ * A reusable catalog entry.
+ *
+ * @typedef {TaskEntry | ScorerEntry} CatalogEntry
+ */
+
+/**
+ * ESM catalog object keyed by Mermaid node id or frontmatter `use`.
+ *
+ * @typedef {Record<string, CatalogEntry>} Catalog
+ */
+
+/**
+ * Run/validation options for catalog execution.
+ *
+ * @typedef {object} RunOptions
+ * @property {boolean} [countDecisionScorers] Count decision scorers toward the
+ * per-path scorer coverage rule. Defaults to false.
+ */
+
+/**
+ * A collected unresolved node.
+ *
+ * @typedef {object} Gap
+ * @property {string} nodeId Node that produced the gap.
+ * @property {'todo' | 'hole'} kind Gap kind.
+ * @property {string} reason Gap reason.
+ * @property {string} [entryKey] Catalog key involved in the gap.
+ */
+
+/**
+ * Runtime error produced while executing a catalog entry.
+ *
+ * @typedef {object} RunError
+ * @property {string} nodeId Node that failed.
+ * @property {string} entryKey Catalog key that failed.
+ * @property {string} message Error message.
+ */
+
+/**
+ * Task execution step.
+ *
+ * @typedef {object} TaskStep
+ * @property {'task'} type
+ * @property {Node} node Source node.
+ * @property {string} entryKey Catalog key.
+ * @property {unknown[]} args Args supplied to the task.
+ * @property {unknown} output Task return value.
+ * @property {string} storedAs Context key used for the task output.
+ */
+
+/**
+ * Scorer execution step.
+ *
+ * @typedef {object} ScoreStep
+ * @property {'score'} type
+ * @property {Node} node Source node.
+ * @property {string} entryKey Catalog key.
+ * @property {'decision' | 'outcome'} role How the score was used.
+ * @property {unknown[]} args Args supplied to the scorer.
+ * @property {ScoreResult} result Normalized score result.
+ * @property {string} [branch] Branch label selected by a decision scorer.
+ */
+
+/**
+ * Gap execution step.
+ *
+ * @typedef {object} GapStep
+ * @property {'gap'} type
+ * @property {Node} node Source node.
+ * @property {string} entryKey Catalog key.
+ * @property {Gap} gap Gap collected for the node.
+ */
+
+/**
+ * Error execution step.
+ *
+ * @typedef {object} ErrorStep
+ * @property {'error'} type
+ * @property {Node} node Source node.
+ * @property {string} entryKey Catalog key.
+ * @property {RunError} error Runtime error collected for the node.
+ */
+
+/**
+ * Result returned by `run()` and `runText()`.
+ *
+ * @typedef {object} RunResult
+ * @property {boolean} ok True when diagnostics, gaps, runtime errors, and
+ * outcome scorers all pass.
+ * @property {Record<string, unknown>} meta Journey frontmatter minus `nodes`.
+ * @property {Record<string, unknown>} context Final execution context.
+ * @property {ExecutedStep[]} steps Executed steps in deterministic order.
+ * @property {ScoreStep[]} scores Executed scorer steps.
+ * @property {Gap[]} gaps Reachable unresolved nodes in execution order.
+ * @property {RunError[]} errors Runtime errors in execution order.
+ * @property {Diagnostic[]} diagnostics Parser, structural, and catalog diagnostics.
+ */
+
+/**
+ * Options used when generating a node:test wrapper.
+ *
+ * @typedef {object} GenerateOptions
+ * @property {string} journeyPath Path imported by the generated wrapper.
+ * @property {string} catalogPath Path imported by the generated wrapper.
+ * @property {string} [outPath] Output path, used to make relative imports.
+ * @property {string} [exportName] Named catalog export to use.
+ * @property {string} [testName] Test name. Defaults to journey metadata or file name.
+ * @property {string} [packageName] Package import name. Defaults to `melusine`.
+ */
+
+export {};

package/src/validate.js

@@ -0,0 +1,171 @@
+// @ts-check
+
+/**
+ * @typedef {import('./types.js').JourneyGraph} JourneyGraph
+ * @typedef {import('./types.js').Diagnostic} Diagnostic
+ * @typedef {import('./types.js').Node} Node
+ * @typedef {import('./types.js').Edge} Edge
+ */
+
+/**
+ * Validate the structural rules that are independent of any target.
+ *
+ * @param {JourneyGraph} graph Parsed graph to validate. `graph.start` is updated
+ * when the unique start terminal can be identified.
+ * @returns {Diagnostic[]} Structural diagnostics in deterministic order.
+ */
+export function validate(graph) {
+  /** @type {Diagnostic[]} */
+  const diagnostics = [];
+  graph.start = '';
+
+  for (const edge of graph.edges) {
+    if (!graph.nodes.has(edge.from)) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_UNKNOWN_NODE',
+        message: `edge references unknown source node '${edge.from}'`,
+        node: edge.from,
+      });
+    }
+    if (!graph.nodes.has(edge.to)) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_UNKNOWN_NODE',
+        message: `edge references unknown destination node '${edge.to}'`,
+        node: edge.to,
+      });
+    }
+  }
+
+  const incoming = incomingByNode(graph);
+  const outgoing = outgoingByNode(graph);
+  const zeroIncoming = [...graph.nodes.values()].filter((node) => (incoming.get(node.id) ?? []).length === 0);
+  const terminalStarts = zeroIncoming.filter((node) => node.kind === 'terminal');
+
+  if (terminalStarts.length === 1 && zeroIncoming.length === 1) {
+    graph.start = terminalStarts[0].id;
+  } else if (zeroIncoming.length === 0 || terminalStarts.length === 0) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'JOURNEY_NO_START',
+      message: 'journey must have exactly one zero-incoming terminal start',
+    });
+  } else {
+    diagnostics.push({
+      severity: 'error',
+      code: 'JOURNEY_MULTIPLE_STARTS',
+      message: `journey has multiple zero-incoming start candidates: ${zeroIncoming.map((node) => node.id).join(', ')}`,
+    });
+  }
+
+  for (const node of graph.nodes.values()) {
+    const incomingEdges = incoming.get(node.id) ?? [];
+    if (incomingEdges.length > 1) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_MERGE_UNSUPPORTED',
+        message: `node '${node.id}' has multiple incoming edges; merges are not supported in v1`,
+        node: node.id,
+      });
+    }
+  }
+
+  for (const node of graph.nodes.values()) {
+    const outgoingEdges = outgoing.get(node.id) ?? [];
+    if (outgoingEdges.length > 1 && node.kind !== 'decision') {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_BRANCH_SHAPE',
+        message: `node '${node.id}' has multiple outgoing edges but is not a decision`,
+        node: node.id,
+      });
+    }
+    if (node.kind === 'decision') {
+      for (const edge of outgoingEdges) {
+        if (!edge.label) {
+          diagnostics.push({
+            severity: 'error',
+            code: 'JOURNEY_UNLABELED_BRANCH',
+            message: `decision node '${node.id}' has an unlabeled outgoing edge`,
+            node: node.id,
+          });
+        }
+      }
+    }
+  }
+
+  if (hasCycle(graph)) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'JOURNEY_CYCLE',
+      message: 'journey graph must be acyclic',
+    });
+  }
+
+  return diagnostics;
+}
+
+/**
+ * @param {JourneyGraph} graph
+ * @returns {Map<string, Edge[]>}
+ */
+export function incomingByNode(graph) {
+  /** @type {Map<string, Edge[]>} */
+  const incoming = new Map();
+  for (const id of graph.nodes.keys()) incoming.set(id, []);
+  for (const edge of graph.edges) {
+    const edges = incoming.get(edge.to);
+    if (edges) edges.push(edge);
+  }
+  return incoming;
+}
+
+/**
+ * @param {JourneyGraph} graph
+ * @returns {Map<string, Edge[]>}
+ */
+export function outgoingByNode(graph) {
+  /** @type {Map<string, Edge[]>} */
+  const outgoing = new Map();
+  for (const id of graph.nodes.keys()) outgoing.set(id, []);
+  for (const edge of graph.edges) {
+    const edges = outgoing.get(edge.from);
+    if (edges) edges.push(edge);
+  }
+  return outgoing;
+}
+
+/**
+ * @param {JourneyGraph} graph
+ * @returns {boolean}
+ */
+function hasCycle(graph) {
+  /** @type {Set<string>} */
+  const visiting = new Set();
+  /** @type {Set<string>} */
+  const visited = new Set();
+  const outgoing = outgoingByNode(graph);
+
+  /**
+   * @param {string} id
+   * @returns {boolean}
+   */
+  function visit(id) {
+    if (visiting.has(id)) return true;
+    if (visited.has(id)) return false;
+    visiting.add(id);
+    for (const edge of outgoing.get(id) ?? []) {
+      if (!graph.nodes.has(edge.to)) continue;
+      if (visit(edge.to)) return true;
+    }
+    visiting.delete(id);
+    visited.add(id);
+    return false;
+  }
+
+  for (const id of graph.nodes.keys()) {
+    if (visit(id)) return true;
+  }
+  return false;
+}

package/src/walk.js

@@ -0,0 +1,57 @@
+// @ts-check
+
+import { outgoingByNode } from './validate.js';
+
+/**
+ * @typedef {import('./types.js').Edge} Edge
+ * @typedef {import('./types.js').JourneyGraph} JourneyGraph
+ */
+
+/**
+ * Enumerate all start-to-terminal graph paths in deterministic source order.
+ *
+ * @param {JourneyGraph} graph Validated acyclic graph.
+ * @returns {string[][]}
+ */
+export function enumeratePaths(graph) {
+  if (!graph.start) return [];
+  const outgoing = outgoingByNode(graph);
+  /** @type {string[][]} */
+  const paths = [];
+
+  /**
+   * @param {string} nodeId
+   * @param {string[]} path
+   */
+  function visit(nodeId, path) {
+    const nextPath = [...path, nodeId];
+    const edges = outgoing.get(nodeId) ?? [];
+    if (edges.length === 0) {
+      paths.push(nextPath);
+      return;
+    }
+    for (const edge of edges) {
+      visit(edge.to, nextPath);
+    }
+  }
+
+  visit(graph.start, []);
+  return paths;
+}
+
+/**
+ * Select the outgoing decision branch for a normalized scorer result.
+ *
+ * `yes` and `no` labels are preferred. If the expected label is absent, source
+ * order keeps branch selection deterministic.
+ *
+ * @param {Edge[]} edges Outgoing decision edges in source order.
+ * @param {boolean} pass Decision scorer pass value.
+ * @returns {Edge | undefined}
+ */
+export function selectDecisionEdge(edges, pass) {
+  const preferred = pass ? 'yes' : 'no';
+  const byLabel = edges.find((edge) => (edge.label ?? '').toLowerCase() === preferred);
+  if (byLabel) return byLabel;
+  return pass ? edges[0] : (edges[1] ?? edges[0]);
+}