@turing-machine-js/builder 5.0.0 → 6.0.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.0.0] - 2026-05-09
+
+### Changed (BREAKING)
+
+- **`peerDependencies."@turing-machine-js/machine"` widened from `^5.0.0` to `^6.0.0`** to match the v6 lockstep. Consumers pinned to `@turing-machine-js/machine@5` will see an unmet-peer warning when installing this version. The v6 dispatch-order change in the engine ([#119](https://github.com/mellonis/turing-machine-js/issues/119)) doesn't affect this package directly (the builder doesn't call `run()`).
+
+Released in lockstep with `@turing-machine-js/machine` 6.0.0. No source or behavior changes in this package beyond the peer-dep widening.
+
 ## [5.0.0] - 2026-05-09
 
 ### Added

package/README.md

@@ -12,31 +12,30 @@ Constructs a Turing machine from a declarative state-table object. Every transit
 import { Tape } from '@turing-machine-js/machine';
 import buildMachine from '@turing-machine-js/builder';
 
+// Flip every bit on the tape; halt when the head reaches a blank.
 const [machine, initialState] = buildMachine({
-  alphabetString: '_01XY#',
-  initialState: 'Q8',
-  finalStateList: ['Q5'],
+  alphabetString: ' 01',
+  initialState: 'flip',
+  finalStateList: ['DONE'],
   states: {
-    Q8: { '#': { state: 'Q6', symbol: '#', movement: 'R' } },
-    Q6: {
-      '0': { state: 'Q0', symbol: 'X', movement: 'R' },
-      '1': { state: 'Q1', symbol: 'Y', movement: 'R' },
-      '#': { state: 'Q2', symbol: '#', movement: 'R' },
+    flip: {
+      '0': { state: 'flip', symbol: '1', movement: 'R' },
+      '1': { state: 'flip', symbol: '0', movement: 'R' },
+      ' ': { state: 'DONE', symbol: ' ', movement: 'S' },
     },
-    // ... more states ...
   },
 });
 
 machine.tapeBlock.replaceTape(new Tape({
   alphabet: machine.tapeBlock.alphabets[0],
-  symbols: '#011#'.split(''),
+  symbols: '0101'.split(''),
 }));
 
 await machine.run({ initialState, stepsLimit: 100 });
-// tape now contains: #011#011#  (the input duplicated)
+console.log(machine.tapeBlock.tapes[0].symbols.join('').trim()); // "1010"
 ```
 
-See [`builder.spec.ts`](src/builder.spec.ts) for a complete worked example, including a small parser that reads the `(state,symbol)→(state,symbol,movement);` textual notation often used in textbooks.
+See [`builder.spec.ts`](src/builder.spec.ts) for a longer worked example — a 27-state binary-string-duplicator (input `#011#` → output `#011#011#`) — including a small parser that reads the textbook `(state,symbol)→(state,symbol,movement);` notation.
 
 ## Limitations
 

package/dist/index.cjs

@@ -9,7 +9,7 @@ const movementsMap = {
 };
 const referenceKey = Symbol('reference');
 const stateKey = Symbol('state');
-function buildMachine({ alphabetString, initialState, finalStateList, states: stateNameToStateDeclarationMap, }) {
+function buildMachine({ alphabetString, initialState, finalStateList, states: stateNameToStateDeclarationMap, debug, }) {
     const alphabet = new machine.Alphabet(alphabetString.split(''));
     const machine$1 = new machine.TuringMachine({
         tapeBlock: machine.TapeBlock.fromAlphabets([alphabet]),
@@ -66,6 +66,40 @@ function buildMachine({ alphabetString, initialState, finalStateList, states: st
         ...result,
         [stateName]: stateOrReference[stateKey],
     }), {});
+    // #101: apply per-state debug config. Filter values are raw alphabet
+    // characters; translate each via tapeBlock.symbol([char]) so they match
+    // the same interned Symbol used in transitions. `true` passes through
+    // as-is (wildcard). final-state names are rejected — they alias to
+    // haltState which is out of scope per the issue spec.
+    if (debug) {
+        Object.entries(debug).forEach(([stateName, config]) => {
+            if (finalStateList.includes(stateName)) {
+                throw new Error(`debug cannot be set on final state '${stateName}': finalStateList `
+                    + 'entries map to haltState, which is out of scope for the builder. '
+                    + 'Set haltState.debug directly on the imported singleton if needed.');
+            }
+            const state = resultStates[stateName];
+            if (!state) {
+                throw new Error(`debug references unknown state '${stateName}'`);
+            }
+            const translateFilter = (f) => {
+                if (f === undefined)
+                    return undefined;
+                if (f === true)
+                    return true;
+                return f.map((c) => {
+                    if (!alphabet.has(c)) {
+                        throw new Error(`debug filter symbol '${c}' for state '${stateName}' is not in the alphabet`);
+                    }
+                    return getSymbol([c]);
+                });
+            };
+            state.debug = {
+                before: translateFilter(config.before),
+                after: translateFilter(config.after),
+            };
+        });
+    }
     return [
         machine$1,
         resultStates[initialState],

package/dist/index.d.ts

@@ -5,10 +5,25 @@ export type States = Record<string, Record<string, {
     movement: keyof typeof movementsMap;
     state: string;
 }>>;
-export default function buildMachine({ alphabetString, initialState, finalStateList, states: stateNameToStateDeclarationMap, }: {
+/**
+ * Per-state breakpoint config for the declarative builder. Filter values are
+ * raw alphabet characters (matching the input-symbol notation in `states`);
+ * the builder translates each to a `tapeBlock.symbol([char])`-interned
+ * Symbol at construction time. `true` is the wildcard.
+ *
+ * Out of scope (#101): final-state entries — `finalStateList` names map to
+ * `haltState`, which is not a state in the table. Pass `before` / `after`
+ * directly on `haltState.debug` if you need to pause on halt entry.
+ */
+export type DebugConfigByState = Record<string, {
+    before?: true | string[];
+    after?: true | string[];
+}>;
+export default function buildMachine({ alphabetString, initialState, finalStateList, states: stateNameToStateDeclarationMap, debug, }: {
     alphabetString: string;
     initialState: string;
     finalStateList: string[];
     states: States;
+    debug?: DebugConfigByState;
 }): readonly [TuringMachine, State, Record<string, State>];
 export {};

package/dist/index.mjs

@@ -7,7 +7,7 @@ const movementsMap = {
 };
 const referenceKey = Symbol('reference');
 const stateKey = Symbol('state');
-function buildMachine({ alphabetString, initialState, finalStateList, states: stateNameToStateDeclarationMap, }) {
+function buildMachine({ alphabetString, initialState, finalStateList, states: stateNameToStateDeclarationMap, debug, }) {
     const alphabet = new Alphabet(alphabetString.split(''));
     const machine = new TuringMachine({
         tapeBlock: TapeBlock.fromAlphabets([alphabet]),
@@ -64,6 +64,40 @@ function buildMachine({ alphabetString, initialState, finalStateList, states: st
         ...result,
         [stateName]: stateOrReference[stateKey],
     }), {});
+    // #101: apply per-state debug config. Filter values are raw alphabet
+    // characters; translate each via tapeBlock.symbol([char]) so they match
+    // the same interned Symbol used in transitions. `true` passes through
+    // as-is (wildcard). final-state names are rejected — they alias to
+    // haltState which is out of scope per the issue spec.
+    if (debug) {
+        Object.entries(debug).forEach(([stateName, config]) => {
+            if (finalStateList.includes(stateName)) {
+                throw new Error(`debug cannot be set on final state '${stateName}': finalStateList `
+                    + 'entries map to haltState, which is out of scope for the builder. '
+                    + 'Set haltState.debug directly on the imported singleton if needed.');
+            }
+            const state = resultStates[stateName];
+            if (!state) {
+                throw new Error(`debug references unknown state '${stateName}'`);
+            }
+            const translateFilter = (f) => {
+                if (f === undefined)
+                    return undefined;
+                if (f === true)
+                    return true;
+                return f.map((c) => {
+                    if (!alphabet.has(c)) {
+                        throw new Error(`debug filter symbol '${c}' for state '${stateName}' is not in the alphabet`);
+                    }
+                    return getSymbol([c]);
+                });
+            };
+            state.debug = {
+                before: translateFilter(config.before),
+                after: translateFilter(config.after),
+            };
+        });
+    }
     return [
         machine,
         resultStates[initialState],

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@turing-machine-js/builder",
-  "version": "5.0.0",
+  "version": "6.0.1",
   "description": "A turing machine builder — declarative state-table construction. Not actively developed by the author; the same state-table pattern is also shown as an inline example in @turing-machine-js/machine's README. Contributions welcome.",
   "engines": {
     "npm": ">=7.0.0"
   },
-  "author": "Ruslan Gilmullin <mellonis14@gmain.com>",
+  "author": "Ruslan Gilmullin <mellonis@yandex.ru>",
   "homepage": "https://github.com/mellonis/turing-machine-js#readme",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -25,7 +25,7 @@
     "builder"
   ],
   "peerDependencies": {
-    "@turing-machine-js/machine": "^5.0.0"
+    "@turing-machine-js/machine": "^6.0.0"
   },
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -38,5 +38,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "ccf9a4743965c2a4ea6340ce1de8f6596e094251"
+  "gitHead": "d7ebca4e8379a548e3ca97eb83e96387de2cda32"
 }