src/pipeline/step.js

/**
 * Pipeline phase interface; subclass name "StepNSuffix" drives index/id/name.
 * @interface
 * @example
 * const step = new Step2Chords();
 * step.index; // 2
 * step.id;    // "step2"
 * step.name;  // "Step 2 (Chords)"
 */
export class Step {
  /** @type {string} Step id "step{index}". */
  get id() {
    return `step${this.index}`;
  }
  /** @type {number} Step index from class name. */
  get index() {
    return Number(this.constructor.name.match(/^Step(\d+)/)[1]);
  }
  /** @type {string} Display name "Step {index} ({Suffix})". */
  get name() {
    const m = this.constructor.name.match(/^Step(\d+)([A-Z][a-zA-Z]*)$/);
    return `Step ${m[1]} (${m[2]})`;
  }
  /**
   * @abstract
   * @return {Object[]} UI parameter descriptors.
   * @throws {Error} When called on a Step subclass that did not override schema().
   */
  schema() {
    throw new Error("Not implemented: schema()");
  }
}
/**
 * Trait: adds abstract solve(parameters, solver) to a Step subclass.
 * Non-solvable steps (e.g. pure form definitions) just extend Step directly.
 * @typedef {Step} Solvable
 * @example
 * class Step9Foo extends Solvable(Step) {
 *   schema() { return SCHEMA; }
 *   async solve(parameters, solver) {
 *     const { model } = modelFoo(parameters);
 *     const solution = await solver(model);
 *     return { textOutput: solution ? "ok" : "no solution", solution };
 *   }
 * }
 */
export const Solvable = (Base) =>
  class extends Base {
    /**
     * @abstract
     * Build a model from parameters, hand it to the solver, render a result.
     * @param {Object} parameters - Per-step form values; see the concrete step's schema().
     * @param {function(model: string): Promise<Object>} solver - Pre-bound solver callback.
     * @return {Promise<Object|null>} Per-step result containing the CSP solution (sigma); null reserved for skip cases.
     * @throws {Error} When called on a Solvable subclass that did not override solve().
     */
    solve(parameters, solver) {
      throw new Error(
        `Not implemented: solve(parameters=${typeof parameters}, solver=${typeof solver})`,
      );
    }
  };