melusine 0.1.0

package/src/catalog.js

@@ -0,0 +1,485 @@
+// @ts-check
+
+import { enumeratePaths } from './walk.js';
+
+/**
+ * @typedef {import('./types.js').Binding} Binding
+ * @typedef {import('./types.js').Catalog} Catalog
+ * @typedef {import('./types.js').CatalogEntry} CatalogEntry
+ * @typedef {import('./types.js').Diagnostic} Diagnostic
+ * @typedef {import('./types.js').GapSignal} GapSignal
+ * @typedef {import('./types.js').JourneyGraph} JourneyGraph
+ * @typedef {import('./types.js').Node} Node
+ * @typedef {import('./types.js').NodeConfig} NodeConfig
+ * @typedef {import('./types.js').NumericScore} NumericScore
+ * @typedef {import('./types.js').RunOptions} RunOptions
+ * @typedef {import('./types.js').ScoreResult} ScoreResult
+ * @typedef {import('./types.js').ScorerOptions} ScorerOptions
+ * @typedef {import('./types.js').StructuredScore} StructuredScore
+ * @typedef {import('./types.js').TaskOptions} TaskOptions
+ */
+
+const ENTRY_BRAND = Symbol('melusine.catalogEntry');
+const RESERVED_CONFIG_KEYS = new Set(['use', 'args', 'as', 'options']);
+
+/**
+ * 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, options = {}) {
+  if (typeof handler !== 'function') {
+    throw new TypeError('task() requires a function');
+  }
+  if (options.as !== undefined && typeof options.as !== 'string') {
+    throw new TypeError('task() option `as` must be a string when provided');
+  }
+
+  return brandEntry({
+    kind: 'task',
+    run: handler,
+    as: options.as,
+    requiredArgs: normalizeRequiredArgs(options.requiredArgs),
+    requiredOptions: normalizeRequiredOptions(options.requiredOptions),
+    meta: normalizeMeta(options.meta),
+  });
+}
+
+/**
+ * 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, options = {}) {
+  if (typeof handler !== 'function') {
+    throw new TypeError('scorer() requires a function');
+  }
+  if (options.threshold !== undefined && !isFiniteNumber(options.threshold)) {
+    throw new TypeError('scorer() option `threshold` must be a finite number when provided');
+  }
+
+  return brandEntry({
+    kind: 'scorer',
+    run: handler,
+    threshold: options.threshold,
+    requiredArgs: normalizeRequiredArgs(options.requiredArgs),
+    requiredOptions: normalizeRequiredOptions(options.requiredOptions),
+    meta: normalizeMeta(options.meta),
+  });
+}
+
+/**
+ * Create an explicit unresolved task/scorer result.
+ *
+ * @param {string} reason Why the step is pending.
+ * @returns {GapSignal}
+ */
+export function todo(reason) {
+  if (typeof reason !== 'string' || reason.length === 0) {
+    throw new TypeError('todo() requires a non-empty reason');
+  }
+  return { kind: 'todo', reason };
+}
+
+/**
+ * Create an explicit missing-input result.
+ *
+ * @param {string} reason What input is missing.
+ * @returns {GapSignal}
+ */
+export function hole(reason) {
+  if (typeof reason !== 'string' || reason.length === 0) {
+    throw new TypeError('hole() requires a non-empty reason');
+  }
+  return { kind: 'hole', reason };
+}
+
+/**
+ * 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, bindings, catalog, options = {}) {
+  assertCatalog(catalog);
+  /** @type {Diagnostic[]} */
+  const diagnostics = [];
+
+  for (const node of graph.nodes.values()) {
+    const config = readNodeConfig(bindings.get(node.id), node.id, diagnostics);
+    const entry = Reflect.get(catalog, config.use);
+
+    if (entry === undefined) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_CATALOG_MISSING',
+        message: `node '${node.id}' references missing catalog entry '${config.use}'`,
+        node: node.id,
+      });
+      continue;
+    }
+
+    assertCatalogEntry(entry, config.use);
+    const expected = expectedRole(node, graph.start);
+    if (entry.kind !== expected) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_CATALOG_ROLE',
+        message: `node '${node.id}' is a ${node.kind} and expects a ${expected}, but catalog entry '${config.use}' is a ${entry.kind}`,
+        node: node.id,
+      });
+    }
+  }
+
+  for (const path of enumeratePaths(graph)) {
+    if (!pathHasRequiredScorer(path, graph, bindings, catalog, options)) {
+      const last = path.at(-1);
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_PATH_WITHOUT_SCORER',
+        message: `path ending at '${last ?? graph.start}' does not include a required outcome scorer`,
+        ...(last ? { node: last } : {}),
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+/**
+ * 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, nodeId, diagnostics = []) {
+  /** @type {NodeConfig} */
+  const config = {
+    use: nodeId,
+    args: [],
+    as: undefined,
+    options: {},
+    raw: binding,
+  };
+
+  if (binding === undefined) return config;
+
+  if (!isRecord(binding)) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'JOURNEY_NODE_CONFIG_INVALID',
+      message: `node '${nodeId}' frontmatter config must be an object`,
+      node: nodeId,
+    });
+    return config;
+  }
+
+  if (binding.use !== undefined) {
+    if (typeof binding.use === 'string' && binding.use.length > 0) {
+      config.use = binding.use;
+    } else {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_NODE_CONFIG_INVALID',
+        message: `node '${nodeId}' frontmatter field 'use' must be a non-empty string`,
+        node: nodeId,
+      });
+    }
+  }
+
+  if (binding.args !== undefined) {
+    if (Array.isArray(binding.args)) {
+      config.args = binding.args;
+    } else {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_NODE_CONFIG_INVALID',
+        message: `node '${nodeId}' frontmatter field 'args' must be an array`,
+        node: nodeId,
+      });
+    }
+  }
+
+  if (binding.as !== undefined) {
+    if (typeof binding.as === 'string' && binding.as.length > 0) {
+      config.as = binding.as;
+    } else {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_NODE_CONFIG_INVALID',
+        message: `node '${nodeId}' frontmatter field 'as' must be a non-empty string`,
+        node: nodeId,
+      });
+    }
+  }
+
+  if (binding.options !== undefined) {
+    if (isRecord(binding.options)) {
+      config.options = { ...binding.options };
+    } else {
+      diagnostics.push({
+        severity: 'error',
+        code: 'JOURNEY_NODE_CONFIG_INVALID',
+        message: `node '${nodeId}' frontmatter field 'options' must be an object`,
+        node: nodeId,
+      });
+    }
+  }
+
+  for (const [key, value] of Object.entries(binding)) {
+    if (!RESERVED_CONFIG_KEYS.has(key)) {
+      config.options[key] = value;
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Resolve one catalog entry and validate its shape.
+ *
+ * @param {Catalog} catalog Catalog object.
+ * @param {string} key Catalog key.
+ * @returns {CatalogEntry}
+ */
+export function getCatalogEntry(catalog, key) {
+  assertCatalog(catalog);
+  const entry = Reflect.get(catalog, key);
+  assertCatalogEntry(entry, key);
+  return entry;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is GapSignal}
+ */
+export function isGapSignal(value) {
+  return isRecord(value)
+    && (value.kind === 'todo' || value.kind === 'hole')
+    && typeof value.reason === 'string';
+}
+
+/**
+ * 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, entryThreshold) {
+  if (typeof value === 'boolean') {
+    return { pass: value };
+  }
+
+  if (typeof value === 'number') {
+    assertFiniteScore(value);
+    const threshold = entryThreshold ?? 1;
+    return { pass: value >= threshold, score: value, threshold };
+  }
+
+  if (!isRecord(value)) {
+    throw new TypeError('scorer returned an invalid result');
+  }
+
+  if (typeof value.pass === 'boolean') {
+    return withScoreDetails({ pass: value.pass }, value);
+  }
+
+  if (typeof value.score === 'number') {
+    assertFiniteScore(value.score);
+    const threshold = value.threshold === undefined ? (entryThreshold ?? 1) : value.threshold;
+    if (!isFiniteNumber(threshold)) {
+      throw new TypeError('scorer returned an invalid numeric threshold');
+    }
+    return withScoreDetails({ pass: value.score >= threshold, score: value.score, threshold }, value);
+  }
+
+  throw new TypeError('scorer returned an invalid result');
+}
+
+/**
+ * @param {Node} node
+ * @param {string} start
+ * @returns {'task' | 'scorer'}
+ */
+export function expectedRole(node, start) {
+  if (node.kind === 'process') return 'task';
+  if (node.kind === 'decision') return 'scorer';
+  return node.id === start ? 'task' : 'scorer';
+}
+
+/**
+ * @param {CatalogEntry} entry
+ * @param {NodeConfig} config
+ * @param {string} nodeId
+ * @returns {GapSignal | undefined}
+ */
+export function missingRequiredInput(entry, config, nodeId) {
+  if (entry.requiredArgs !== undefined && config.args.length < entry.requiredArgs) {
+    return hole(`node '${nodeId}' requires at least ${entry.requiredArgs} arg(s)`);
+  }
+
+  for (const key of entry.requiredOptions) {
+    if (!Object.hasOwn(config.options, key)) {
+      return hole(`node '${nodeId}' requires option '${key}'`);
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * @param {CatalogEntry} entry
+ * @param {NodeConfig} config
+ * @param {Node} node
+ * @returns {string}
+ */
+export function storageKeyFor(entry, config, node) {
+  return config.as ?? (entry.kind === 'task' ? entry.as : undefined) ?? node.id;
+}
+
+/**
+ * @param {unknown} catalog
+ * @returns {asserts catalog is Catalog}
+ */
+function assertCatalog(catalog) {
+  if (!isRecord(catalog)) {
+    throw new TypeError('catalog must be an object');
+  }
+}
+
+/**
+ * @param {unknown} entry
+ * @param {string} key
+ * @returns {asserts entry is CatalogEntry}
+ */
+function assertCatalogEntry(entry, key) {
+  if (!isCatalogEntry(entry)) {
+    throw new TypeError(`catalog entry '${key}' must be created with task() or scorer()`);
+  }
+}
+
+/**
+ * @template {CatalogEntry} T
+ * @param {T} entry
+ * @returns {T}
+ */
+function brandEntry(entry) {
+  Object.defineProperty(entry, ENTRY_BRAND, { value: true });
+  return Object.freeze(entry);
+}
+
+/**
+ * @param {number | undefined} value
+ * @returns {number | undefined}
+ */
+function normalizeRequiredArgs(value) {
+  if (value === undefined) return undefined;
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TypeError('requiredArgs must be a non-negative integer');
+  }
+  return value;
+}
+
+/**
+ * @param {string[] | undefined} value
+ * @returns {string[]}
+ */
+function normalizeRequiredOptions(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    throw new TypeError('requiredOptions must be an array of non-empty strings');
+  }
+  return [...value];
+}
+
+/**
+ * @param {Record<string, unknown> | undefined} value
+ * @returns {Record<string, unknown>}
+ */
+function normalizeMeta(value) {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new TypeError('meta must be an object');
+  return { ...value };
+}
+
+/**
+ * @param {string[]} path
+ * @param {JourneyGraph} graph
+ * @param {Map<string, Binding>} bindings
+ * @param {Catalog} catalog
+ * @param {RunOptions} options
+ * @returns {boolean}
+ */
+function pathHasRequiredScorer(path, graph, bindings, catalog, options) {
+  for (const nodeId of path) {
+    const node = graph.nodes.get(nodeId);
+    if (!node) continue;
+    const config = readNodeConfig(bindings.get(node.id), node.id);
+    const entry = Reflect.get(catalog, config.use);
+    if (!isCatalogEntry(entry) || entry.kind !== 'scorer') continue;
+
+    if (node.kind === 'terminal' && node.id !== graph.start) return true;
+    if (options.countDecisionScorers === true && node.kind === 'decision') return true;
+  }
+  return false;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is CatalogEntry}
+ */
+function isCatalogEntry(value) {
+  return isRecord(value)
+    && value[ENTRY_BRAND] === true
+    && (value.kind === 'task' || value.kind === 'scorer')
+    && typeof value.run === 'function';
+}
+
+/**
+ * @param {ScoreResult} base
+ * @param {Record<string, unknown>} source
+ * @returns {ScoreResult}
+ */
+function withScoreDetails(base, source) {
+  return {
+    ...base,
+    ...(typeof source.message === 'string' ? { message: source.message } : {}),
+    ...(Object.hasOwn(source, 'actual') ? { actual: source.actual } : {}),
+    ...(Object.hasOwn(source, 'expected') ? { expected: source.expected } : {}),
+  };
+}
+
+/**
+ * @param {number} score
+ */
+function assertFiniteScore(score) {
+  if (!isFiniteNumber(score)) {
+    throw new TypeError('scorer returned a non-finite score');
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string | symbol, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}