melusine 0.1.0

package/README.md

@@ -0,0 +1,249 @@
+# melusine
+
+`melusine` runs Mermaid journey charts as tests.
+
+You write:
+
+1. A Markdown file with YAML frontmatter and a Mermaid flowchart.
+2. A reusable JavaScript catalog with `task(...)` and `scorer(...)` functions.
+
+Melusine parses the chart, validates the graph, runs the catalog functions in graph order, passes task results through context, records gaps, and reports whether the journey passed.
+
+## Install
+
+```sh
+npm install --save-dev melusine
+```
+
+For this repository:
+
+```sh
+npm install
+npm test
+```
+
+## Start a Project
+
+Create starter files in an existing JS/Node project:
+
+```sh
+npx melusine init
+```
+
+This creates:
+
+- `melusine.catalog.js`
+- `journeys/example.journey.md`
+- `melusine:validate` and `melusine:test` package scripts when `package.json` exists
+
+Run the starter:
+
+```sh
+npm run melusine:validate
+npm run melusine:test
+```
+
+## Build a Journey
+
+Save this as `checkout.journey.md`:
+
+````markdown
+---
+journey: checkout-happy-path
+nodes:
+  start:
+    as: checkout
+  addItem:
+    args: ["book", 1]
+  pay:
+    args: ["card"]
+---
+
+# Checkout happy path
+
+```mermaid
+graph TD
+  start(["Customer opens checkout"]) --> addItem
+  addItem["Add item"] --> payable
+  payable{"Cart is payable?"}
+  payable -->|yes| pay
+  payable -->|no| blocked
+  pay["Pay"] --> paid
+  paid(["Order paid"])
+  blocked(["Payment blocked"])
+```
+````
+
+GitHub and GitLab can render Mermaid diagrams in Markdown. Useful Mermaid links:
+
+- [Mermaid docs](https://mermaid.js.org/)
+- [Flowchart syntax](https://mermaid.js.org/syntax/flowchart.html)
+- [Syntax reference](https://mermaid.js.org/intro/syntax-reference.html)
+
+## Write a Catalog
+
+Save this as `checkout.catalog.js`:
+
+```js
+import { scorer, task } from 'melusine';
+import { Checkout } from './checkout.js';
+
+export default {
+  start: task(() => new Checkout(), { as: 'checkout' }),
+
+  addItem: task(({ args, context }) => {
+    context.checkout.addItem(args[0], args[1]);
+  }, { requiredArgs: 2 }),
+
+  payable: scorer(({ context }) => context.checkout.total > 0),
+
+  pay: task(({ args, context }) => {
+    context.checkout.pay(args[0]);
+  }, { requiredArgs: 1 }),
+
+  paid: scorer(({ context }) => ({
+    pass: context.checkout.status === 'paid',
+    actual: context.checkout.status,
+    expected: 'paid',
+    message: 'checkout should be paid',
+  })),
+
+  blocked: scorer(() => ({
+    pass: false,
+    message: 'checkout should have been payable',
+  })),
+};
+```
+
+Catalog entries are reusable. Multiple journey files can reference the same `addItem`, `pay`, and `paid` entries by node id.
+
+## Frontmatter
+
+Frontmatter is the YAML block at the top of the journey file.
+
+```yaml
+---
+journey: checkout-happy-path
+nodes:
+  start:
+    as: checkout
+  addItem:
+    args: ["book", 1]
+  alternateAdd:
+    use: addItem
+    args: ["pen", 2]
+---
+```
+
+`nodes` is keyed by Mermaid node id.
+
+- `args` becomes `input.args` for the catalog function.
+- `as` stores a task result under that context key.
+- `use` points one node at a different catalog key.
+- Extra fields become `input.config.options`.
+
+Everything outside `nodes` becomes `input.meta`.
+
+## Graph Rules
+
+Use a Mermaid `graph` or `flowchart` block:
+
+```mermaid
+graph TD
+  start(["Start"]) --> step
+  step["Do something"] --> decision
+  decision{"Choose?"}
+  decision -->|yes| done
+  decision -->|no| failed
+  done(["Done"])
+  failed(["Failed"])
+```
+
+Supported in v1:
+
+| Shape | Example | Meaning |
+| --- | --- | --- |
+| Terminal | `start(["Start"])` | Start or final outcome |
+| Process | `step["Do something"]` | Task |
+| Decision | `ok{"Ready?"}` | Branch scorer |
+| Edge | `A --> B` | Next node |
+| Labeled edge | `A -->|yes| B` | Decision branch |
+
+Rules:
+
+- There must be one start node: a terminal with no incoming edges.
+- Process nodes must map to tasks.
+- Decision nodes must map to scorers.
+- Final terminal nodes must map to scorers.
+- Every completed path needs an outcome scorer by default.
+- Branches cannot merge back together in v1.
+- Only `-->` edges are supported.
+
+## CLI
+
+```sh
+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]
+```
+
+Common workflow:
+
+```sh
+npx melusine validate checkout.journey.md --catalog checkout.catalog.js
+npx melusine test checkout.journey.md --catalog checkout.catalog.js
+npx melusine compile checkout.journey.md --catalog checkout.catalog.js --out checkout.test.mjs
+node --test checkout.test.mjs
+```
+
+`test` runs the journey directly. `compile` writes a small `node:test` wrapper that reads the journey file, imports the catalog, and calls the same runner.
+
+## Library API
+
+```js
+import { parse, runText, scorer, task } from 'melusine';
+
+const result = await runText(markdown, catalog);
+```
+
+Important exports:
+
+- `task(fn, options)` defines a reusable action.
+- `scorer(fn, options)` defines a reusable check.
+- `runText(text, catalog)` parses and executes a journey.
+- `parse(text)` returns the graph, frontmatter, and diagnostics.
+- `generateTest(options)` creates a generated wrapper string.
+
+Scorers can return:
+
+```js
+true
+false
+{ pass: true, message: 'ok', actual, expected }
+0.8
+{ score: 0.8, threshold: 0.7 }
+```
+
+Numeric scores pass when `score >= threshold`. The default threshold is `1`.
+
+## Examples
+
+The `examples/` directory has complete runnable examples:
+
+- `examples/onboarding/` shows a linear flow.
+- `examples/vending/` shows one decision branch.
+- `examples/order-fulfillment/` shows nested decisions.
+
+Run all examples:
+
+```sh
+npm run generate:examples
+node --test examples/*/generated/*.test.mjs
+```
+
+## Gaps
+
+A catalog entry can return `todo(reason)` or `hole(reason)`. Melusine also creates a `hole` when a required arg or option is missing.
+
+Gaps make the run fail and appear in `result.gaps`. They are never converted into passing assertions.

package/SPEC.md

@@ -0,0 +1,145 @@
+# Melusine Catalog Mode Spec
+
+Melusine is a standalone npm package that runs human-readable Mermaid flowchart journeys as tests. The package owns graph structure: Markdown parsing, Mermaid subset parsing, structural validation, catalog validation, deterministic traversal, branch selection, context passing, scoring, diagnostics, and gap aggregation.
+
+Users own project meaning through reusable ESM JavaScript catalog entries created with `task(...)` and `scorer(...)`.
+
+## Package Rules
+
+- Source is plain ESM JavaScript with `// @ts-check` and JSDoc.
+- Generated `.d.ts` files come from TypeScript as a dev-only declaration generator.
+- Node target is `>=20`.
+- `yaml` is the only runtime dependency.
+- The Mermaid parser is handwritten.
+
+## Journey Input
+
+A journey is Markdown with optional YAML frontmatter and the first Mermaid fence.
+
+````markdown
+---
+journey: vending-purchase
+nodes:
+  start: { as: machine }
+  insert: { args: [150] }
+  dispense: { args: ["cola"] }
+---
+
+```mermaid
+graph TD
+  start(["Start"]) --> insert
+  insert["Insert coins"] --> enough
+  enough{"Enough credit?"}
+  enough -->|yes| dispense
+  enough -->|no| fail
+  dispense["Dispense cola"] --> gotCola
+  gotCola(["Got cola"])
+  fail(["Insufficient credit"])
+```
+````
+
+Frontmatter rules:
+
+- `nodes` is keyed by Mermaid node id.
+- `use` points a node to a different catalog key.
+- `args` becomes the catalog call's positional args.
+- `as` chooses where a task result is stored in execution context.
+- Extra fields become `config.options`.
+- Frontmatter outside `nodes` becomes `meta`.
+
+## Supported Mermaid Subset
+
+- Headers: `graph TD`, `graph LR`, `flowchart TD`, `flowchart LR`.
+- Process nodes: `id["label"]` or `id[label]`.
+- Decision nodes: `id{"label"}` or `id{label}`.
+- Terminal nodes: `id(["label"])` or `id([label])`.
+- Edges: `A --> B` and `A -->|label| B`.
+- Comments beginning with `%%` and blank lines are ignored.
+- Unsupported edge operators produce warnings and are ignored.
+- Bare node references default to process nodes with an info diagnostic.
+
+Structural errors are diagnostics, not thrown exceptions.
+
+## Catalog Semantics
+
+```js
+import { scorer, task } from 'melusine';
+
+export default {
+  start: task(() => new Subject(), { as: 'subject' }),
+  act: task(({ context, args }) => context.subject.act(args[0]), { requiredArgs: 1 }),
+  done: scorer(({ context }) => context.subject.done === true),
+};
+```
+
+Role rules:
+
+- The unique start terminal expects a task.
+- Process nodes expect tasks.
+- Decision nodes expect scorers.
+- Non-start terminal nodes expect scorers.
+- Mermaid shape wins over catalog wrapper role.
+
+Catalog functions receive one object containing:
+
+- `args`
+- `context`
+- `meta`
+- `node`
+- `previous`
+- `config`
+- `key`
+
+Task return values are stored in context under `frontmatter.as`, then task default `as`, then node id.
+
+## Scoring
+
+Scorers are project-owned. Melusine does not infer correctness from labels or shapes.
+
+Accepted scorer returns:
+
+- `boolean`
+- `{ pass, message?, actual?, expected? }`
+- `number`
+- `{ score, threshold?, message?, actual?, expected? }`
+
+Numeric score results pass when `score >= threshold`. The default threshold is `1`.
+
+Decision scorer pass/fail selects a branch. `yes` and `no` labels are preferred; source order is the deterministic fallback. Outcome scorers determine whether the journey passes.
+
+By default, every completed start-to-terminal path must include an outcome scorer. Counting decision scorers for this rule is configurable.
+
+## Gaps
+
+Unresolved work must stay visible.
+
+- `todo(reason)` marks known unfinished project work.
+- `hole(reason)` marks missing human-supplied input.
+- Missing required args or options create holes.
+
+Gaps make a run fail and are returned in `gaps[]`. They must not become passing assertions.
+
+## CLI
+
+- `melusine validate <journey.md> [--catalog <catalog.js>]`
+- `melusine test <journey.md> --catalog <catalog.js>`
+- `melusine compile <journey.md> --catalog <catalog.js> --out <file>`
+- `melusine init`
+
+`test` is the primary command and executes directly. `compile` writes a thin `node:test` wrapper that imports Melusine and the catalog, reads the journey file, and calls the same runner. Generated tests must not inline catalog function source.
+
+## Public API
+
+Core exports:
+
+- `parse`
+- `task`
+- `scorer`
+- `todo`
+- `hole`
+- `run`
+- `runText`
+- `formatRunFailure`
+- `generateTest`
+
+Renderer hooks are not part of the catalog-mode public API.

package/dist/catalog.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Wrap a reusable project action for use by one or more journeys.
+ *
+ * @param {import('./types.js').TaskHandler} handler Function to run.
+ * @param {TaskOptions} [options] Task metadata and requirements.
+ * @returns {import('./types.js').TaskEntry}
+ */
+export function task(handler: import("./types.js").TaskHandler, options?: TaskOptions): import("./types.js").TaskEntry;
+/**
+ * Wrap a reusable project scorer for use by one or more journeys.
+ *
+ * @param {import('./types.js').ScorerHandler} handler Function to score.
+ * @param {ScorerOptions} [options] Scorer metadata and requirements.
+ * @returns {import('./types.js').ScorerEntry}
+ */
+export function scorer(handler: import("./types.js").ScorerHandler, options?: ScorerOptions): import("./types.js").ScorerEntry;
+/**
+ * Create an explicit unresolved task/scorer result.
+ *
+ * @param {string} reason Why the step is pending.
+ * @returns {GapSignal}
+ */
+export function todo(reason: string): GapSignal;
+/**
+ * Create an explicit missing-input result.
+ *
+ * @param {string} reason What input is missing.
+ * @returns {GapSignal}
+ */
+export function hole(reason: string): GapSignal;
+/**
+ * Validate catalog references and graph/catalog role compatibility.
+ *
+ * @param {JourneyGraph} graph Parsed graph.
+ * @param {Map<string, Binding>} bindings Node id to frontmatter config.
+ * @param {Catalog} catalog Catalog object.
+ * @param {RunOptions} [options] Validation options.
+ * @returns {Diagnostic[]}
+ */
+export function validateCatalog(graph: JourneyGraph, bindings: Map<string, Binding>, catalog: Catalog, options?: RunOptions): Diagnostic[];
+/**
+ * Read one node's frontmatter binding into the catalog config model.
+ *
+ * @param {Binding | undefined} binding Raw frontmatter binding.
+ * @param {string} nodeId Source node id.
+ * @param {Diagnostic[]} [diagnostics] Diagnostics sink.
+ * @returns {NodeConfig}
+ */
+export function readNodeConfig(binding: Binding | undefined, nodeId: string, diagnostics?: Diagnostic[]): NodeConfig;
+/**
+ * Resolve one catalog entry and validate its shape.
+ *
+ * @param {Catalog} catalog Catalog object.
+ * @param {string} key Catalog key.
+ * @returns {CatalogEntry}
+ */
+export function getCatalogEntry(catalog: Catalog, key: string): CatalogEntry;
+/**
+ * @param {unknown} value
+ * @returns {value is GapSignal}
+ */
+export function isGapSignal(value: unknown): value is GapSignal;
+/**
+ * Normalize a scorer return value into Melusine's result model.
+ *
+ * @param {unknown} value Raw scorer return.
+ * @param {number | undefined} entryThreshold Default threshold from scorer metadata.
+ * @returns {ScoreResult}
+ */
+export function normalizeScoreResult(value: unknown, entryThreshold: number | undefined): ScoreResult;
+/**
+ * @param {Node} node
+ * @param {string} start
+ * @returns {'task' | 'scorer'}
+ */
+export function expectedRole(node: Node, start: string): "task" | "scorer";
+/**
+ * @param {CatalogEntry} entry
+ * @param {NodeConfig} config
+ * @param {string} nodeId
+ * @returns {GapSignal | undefined}
+ */
+export function missingRequiredInput(entry: CatalogEntry, config: NodeConfig, nodeId: string): GapSignal | undefined;
+/**
+ * @param {CatalogEntry} entry
+ * @param {NodeConfig} config
+ * @param {Node} node
+ * @returns {string}
+ */
+export function storageKeyFor(entry: CatalogEntry, config: NodeConfig, node: Node): string;
+export type Binding = import("./types.js").Binding;
+export type Catalog = import("./types.js").Catalog;
+export type CatalogEntry = import("./types.js").CatalogEntry;
+export type Diagnostic = import("./types.js").Diagnostic;
+export type GapSignal = import("./types.js").GapSignal;
+export type JourneyGraph = import("./types.js").JourneyGraph;
+export type Node = import("./types.js").Node;
+export type NodeConfig = import("./types.js").NodeConfig;
+export type NumericScore = import("./types.js").NumericScore;
+export type RunOptions = import("./types.js").RunOptions;
+export type ScoreResult = import("./types.js").ScoreResult;
+export type ScorerOptions = import("./types.js").ScorerOptions;
+export type StructuredScore = import("./types.js").StructuredScore;
+export type TaskOptions = import("./types.js").TaskOptions;

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * 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 function main(argv?: string[], io?: {
+    cwd?: string;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+}): Promise<number>;
+export type ParsedArgs = {
+    positionals: string[];
+    flags: {
+        catalog?: string;
+        exportName?: string;
+        out?: string;
+        force: boolean;
+        json: boolean;
+    };
+};
+export type Catalog = import("./types.js").Catalog;
+export type Diagnostic = import("./types.js").Diagnostic;
+export type Gap = import("./types.js").Gap;
+export type RunResult = import("./types.js").RunResult;

package/dist/compile.d.ts

@@ -0,0 +1 @@
+export { run as compile, runText as compileText } from "./run.js";

package/dist/generate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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: GenerateOptions): string;
+export type GenerateOptions = import("./types.js").GenerateOptions;

package/dist/index.d.ts

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

package/dist/parse.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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: string): ParseResult;
+export type ParsedTerm = {
+    id: string;
+    node?: Node;
+};
+export type ParsedEdge = {
+    from: ParsedTerm;
+    to: ParsedTerm;
+    label?: string;
+};
+export type Binding = import("./types.js").Binding;
+export type Diagnostic = import("./types.js").Diagnostic;
+export type Edge = import("./types.js").Edge;
+export type JourneyGraph = import("./types.js").JourneyGraph;
+export type Node = import("./types.js").Node;
+export type NodeKind = import("./types.js").NodeKind;
+export type ParseResult = import("./types.js").ParseResult;

package/dist/run.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @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 function run(parsed: ParseResult, catalog: Catalog, options?: RunOptions): Promise<RunResult>;
+/**
+ * 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: string, catalog: Catalog, options?: RunOptions): Promise<RunResult>;
+/**
+ * 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: RunResult): string;
+export type Catalog = import("./types.js").Catalog;
+export type Diagnostic = import("./types.js").Diagnostic;
+export type ExecutedStep = import("./types.js").ExecutedStep;
+export type Gap = import("./types.js").Gap;
+export type GapSignal = import("./types.js").GapSignal;
+export type Node = import("./types.js").Node;
+export type ParseResult = import("./types.js").ParseResult;
+export type RunError = import("./types.js").RunError;
+export type RunOptions = import("./types.js").RunOptions;
+export type RunResult = import("./types.js").RunResult;
+export type ScoreStep = import("./types.js").ScoreStep;

package/dist/scaffold.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 function initProject(cwd: string, options?: InitOptions): Promise<string[]>;
+export type InitOptions = {
+    /**
+     * Overwrite starter files when they already exist.
+     */
+    force?: boolean | undefined;
+};