melusine 0.1.0

package/dist/types.d.ts

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

package/dist/validate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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: JourneyGraph): Diagnostic[];
+/**
+ * @param {JourneyGraph} graph
+ * @returns {Map<string, Edge[]>}
+ */
+export function incomingByNode(graph: JourneyGraph): Map<string, Edge[]>;
+/**
+ * @param {JourneyGraph} graph
+ * @returns {Map<string, Edge[]>}
+ */
+export function outgoingByNode(graph: JourneyGraph): Map<string, Edge[]>;
+export type JourneyGraph = import("./types.js").JourneyGraph;
+export type Diagnostic = import("./types.js").Diagnostic;
+export type Node = import("./types.js").Node;
+export type Edge = import("./types.js").Edge;

package/dist/walk.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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: JourneyGraph): string[][];
+/**
+ * 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: Edge[], pass: boolean): Edge | undefined;
+export type Edge = import("./types.js").Edge;
+export type JourneyGraph = import("./types.js").JourneyGraph;

package/examples/README.md

@@ -0,0 +1,21 @@
+# Examples
+
+Each example shows a different journey shape using the same catalog-mode API.
+
+- `onboarding/` is a linear flow.
+- `vending/` has one decision branch.
+- `order-fulfillment/` has nested decisions.
+
+Every folder includes:
+
+- `journey.md` with YAML frontmatter and Mermaid.
+- `catalog.js` with reusable `task(...)` and `scorer(...)` entries.
+- A small toy system under test.
+- `generated/*.test.mjs`, a committed wrapper generated by `melusine compile`.
+
+Run all generated examples:
+
+```sh
+npm run generate:examples
+node --test examples/*/generated/*.test.mjs
+```

package/examples/onboarding/README.md

@@ -0,0 +1,16 @@
+# Onboarding Example
+
+This is the simplest example: one start task, three process tasks, and one outcome scorer.
+
+Files:
+
+- `journey.md` defines the Mermaid flow.
+- `catalog.js` creates and reuses an `OnboardingSession`.
+- `onboarding-session.mjs` is the toy system under test.
+- `generated/onboarding.test.mjs` is the generated wrapper.
+
+Run it:
+
+```sh
+node src/cli.js test examples/onboarding/journey.md --catalog examples/onboarding/catalog.js
+```

package/examples/onboarding/catalog.js

@@ -0,0 +1,29 @@
+// @ts-check
+
+import { scorer, task } from 'melusine';
+import { OnboardingSession } from './onboarding-session.mjs';
+
+export const catalog = {
+  start: task(() => new OnboardingSession(), { as: 'session' }),
+
+  collect: task(({ args, context }) => {
+    context.session.collectEmail(args[0]);
+  }, { requiredArgs: 1 }),
+
+  verify: task(({ context }) => {
+    context.session.verifyEmail();
+  }),
+
+  create: task(({ args, context }) => {
+    context.session.createWorkspace(args[0]);
+  }, { requiredArgs: 1 }),
+
+  ready: scorer(({ context }) => ({
+    pass: context.session.workspace === 'Analytical Engine' && context.session.verified === true,
+    actual: { workspace: context.session.workspace, verified: context.session.verified },
+    expected: { workspace: 'Analytical Engine', verified: true },
+    message: 'workspace should be ready after verified onboarding',
+  })),
+};
+
+export default catalog;

package/examples/onboarding/generated/onboarding.test.mjs

@@ -0,0 +1,15 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { formatRunFailure, runText } from "melusine";
+import * as catalogModule from "../catalog.js";
+
+const catalog = (catalogModule.default ?? catalogModule.catalog);
+const journeyUrl = new URL("../journey.md", import.meta.url);
+
+test("journey: onboarding-linear", 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));
+});

package/examples/onboarding/journey.md

@@ -0,0 +1,18 @@
+---
+journey: onboarding-linear
+nodes:
+  start:   { as: session }
+  collect: { args: ["ada@example.com"] }
+  create:  { args: ["Analytical Engine"] }
+---
+
+# Onboarding journey
+
+```mermaid
+graph LR
+  start(["Visitor opens signup"]) --> collect
+  collect["Enter email"] --> verify
+  verify["Verify email"] --> create
+  create["Create workspace"] --> ready
+  ready(["Workspace ready"])
+```

package/examples/onboarding/onboarding-session.mjs

@@ -0,0 +1,21 @@
+export class OnboardingSession {
+  constructor() {
+    this.email = null;
+    this.verified = false;
+    this.workspace = null;
+  }
+
+  collectEmail(email) {
+    this.email = email;
+  }
+
+  verifyEmail() {
+    if (!this.email) throw new Error('email required');
+    this.verified = true;
+  }
+
+  createWorkspace(name) {
+    if (!this.verified) throw new Error('email must be verified');
+    this.workspace = name;
+  }
+}