@turing-machine-js/machine 2.0.2 → 3.0.0

package/dist/utilities/equivalence.d.ts

@@ -0,0 +1,31 @@
+import State from '../classes/State';
+import TapeBlock from '../classes/TapeBlock';
+export type Runnable = {
+    state: State;
+    getTapeBlock: () => TapeBlock;
+};
+export type EquivalenceCase = string | {
+    reference: string;
+    candidate: string;
+};
+export type EquivalenceResult = {
+    case: {
+        reference: string;
+        candidate: string;
+    };
+    agree: boolean;
+    referenceOutput: string;
+    candidateOutput: string;
+    referenceSteps: number;
+    candidateSteps: number;
+    firstDivergenceStep: number | null;
+};
+export type EquivalenceReport = {
+    results: EquivalenceResult[];
+    allAgree: boolean;
+};
+export declare function equivalentOn(reference: Runnable, candidate: Runnable, cases: EquivalenceCase[], options?: {
+    compareOutputs?: (refOutput: string, candOutput: string) => boolean;
+    compareSnapshots?: ((refSnap: string, candSnap: string) => boolean) | null;
+    stepsLimit?: number;
+}): EquivalenceReport;

package/dist/utilities/equivalence.js

@@ -0,0 +1,68 @@
+import Tape from '../classes/Tape';
+import TuringMachine from '../classes/TuringMachine';
+const defaultCompare = (a, b) => a === b;
+export function equivalentOn(reference, candidate, cases, options = {}) {
+    const compareOutputs = options.compareOutputs ?? defaultCompare;
+    const compareSnapshots = options.compareSnapshots === undefined
+        ? defaultCompare
+        : options.compareSnapshots;
+    const stepsLimit = options.stepsLimit ?? 1e5;
+    const results = cases.map((c) => {
+        const pair = typeof c === 'string' ? { reference: c, candidate: c } : c;
+        const refRun = runOnce(reference, pair.reference, stepsLimit);
+        const candRun = runOnce(candidate, pair.candidate, stepsLimit);
+        const agree = compareOutputs(refRun.finalOutput, candRun.finalOutput);
+        let firstDivergenceStep = null;
+        if (!agree && compareSnapshots !== null) {
+            const minLen = Math.min(refRun.snapshots.length, candRun.snapshots.length);
+            for (let i = 0; i < minLen; i += 1) {
+                if (!compareSnapshots(refRun.snapshots[i], candRun.snapshots[i])) {
+                    firstDivergenceStep = i;
+                    break;
+                }
+            }
+            if (firstDivergenceStep === null && refRun.snapshots.length !== candRun.snapshots.length) {
+                firstDivergenceStep = minLen;
+            }
+        }
+        return {
+            case: pair,
+            agree,
+            referenceOutput: refRun.finalOutput,
+            candidateOutput: candRun.finalOutput,
+            referenceSteps: refRun.stepCount,
+            candidateSteps: candRun.stepCount,
+            firstDivergenceStep,
+        };
+    });
+    return {
+        results,
+        allAgree: results.every((r) => r.agree),
+    };
+}
+// Single-machine runner: snapshots the tape after each step and returns the
+// final output, the snapshot list, and the step count.
+function runOnce(runnable, input, stepsLimit) {
+    const tapeBlock = runnable.getTapeBlock();
+    const tape = new Tape({
+        alphabet: tapeBlock.tapes[0].alphabet,
+        symbols: input.split(''),
+    });
+    tapeBlock.replaceTape(tape);
+    const machine = new TuringMachine({ tapeBlock });
+    const snapshots = [];
+    let stepCount = 0;
+    // Inside the for-of body, the tape reflects the state BEFORE the current
+    // step's command (i.e. AFTER the previous step's command — or initial for
+    // step 1). After the loop, the tape has had every command applied.
+    for (const _ of machine.runStepByStep({ initialState: runnable.state, stepsLimit })) {
+        snapshots.push(tape.symbols.join(''));
+        stepCount += 1;
+    }
+    snapshots.push(tape.symbols.join(''));
+    return {
+        finalOutput: tape.symbols.join('').trim(),
+        snapshots,
+        stepCount,
+    };
+}

package/dist/utilities/graph.d.ts

@@ -0,0 +1,29 @@
+export type GraphCommand = {
+    symbol: string;
+    movement: string;
+};
+export type GraphTransition = {
+    pattern: string;
+    command: GraphCommand[];
+    nextStateId: number;
+};
+export type GraphNode = {
+    id: number;
+    name: string;
+    isHalt: boolean;
+    transitions: GraphTransition[];
+    overrodeHaltStateId: number | null;
+};
+export type Graph = {
+    initialId: number;
+    alphabets: string[][];
+    nodes: Record<number, GraphNode>;
+};
+export declare function decodePatternDescription(description: string | undefined, alphabets: string[][]): string;
+export declare function decodeMovement(description: string | undefined): string;
+export type ParsedPattern = null | (string | null)[][];
+export declare function splitUnescaped(s: string, sep: string): string[];
+export declare function parsePatternString(s: string, alphabets: string[][]): ParsedPattern;
+export declare function parseMovementLabel(label: string): symbol;
+export declare function parseWriteSymbolLabel(label: string): string | symbol;
+export declare function decodeWriteSymbol(symbol: string | symbol): string;

package/dist/utilities/graph.js

@@ -0,0 +1,127 @@
+import { movements, symbolCommands } from '../classes/TapeCommand';
+const movementDescriptionToLabel = {
+    'move caret left command': 'L',
+    'move caret right command': 'R',
+    'do not move carer': 'S',
+};
+const symbolCommandDescriptionToLabel = {
+    'keep symbol command': '·',
+    'erase symbol command': '⌫',
+};
+// Reserved characters in the encoded pattern string:
+//   '*'  per-cell ifOtherSymbol (matches any symbol on that tape)
+//   '-'  the tape's blank symbol
+//   ','  separates per-tape cells inside one pattern
+//   '|'  separates alternative patterns
+//   '\\' escape prefix — to represent any of '*', '-', ',', '|', or '\\' as a
+//        *literal* alphabet symbol, prefix it with '\\' (e.g. '\\*' for literal '*').
+function escapeAlphabetSymbol(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/\*/g, '\\*')
+        .replace(/-/g, '\\-')
+        .replace(/,/g, '\\,')
+        .replace(/\|/g, '\\|');
+}
+export function decodePatternDescription(description, alphabets) {
+    if (!description) {
+        return '?';
+    }
+    if (description === 'other symbol') {
+        return '*';
+    }
+    try {
+        const patternList = JSON.parse(description);
+        return patternList
+            .map((pattern) => pattern
+            .map((s, tapeIx) => {
+            if (s === null) {
+                return '*';
+            }
+            if (s === alphabets[tapeIx]?.[0]) {
+                return '-';
+            }
+            return escapeAlphabetSymbol(s);
+        })
+            .join(','))
+            .join('|');
+    }
+    catch {
+        return description;
+    }
+}
+export function decodeMovement(description) {
+    if (!description) {
+        return '?';
+    }
+    return movementDescriptionToLabel[description] ?? description;
+}
+export function splitUnescaped(s, sep) {
+    const parts = [];
+    let current = '';
+    let i = 0;
+    while (i < s.length) {
+        if (s[i] === '\\' && i + 1 < s.length) {
+            current += s[i + 1];
+            i += 2;
+        }
+        else if (s[i] === sep) {
+            parts.push(current);
+            current = '';
+            i += 1;
+        }
+        else {
+            current += s[i];
+            i += 1;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+export function parsePatternString(s, alphabets) {
+    if (s === '*') {
+        return null;
+    }
+    const alternatives = splitUnescaped(s, '|');
+    return alternatives.map((alt) => {
+        const cells = splitUnescaped(alt, ',');
+        return cells.map((cell, tapeIx) => {
+            if (cell === '*') {
+                return null;
+            }
+            if (cell === '-') {
+                return alphabets[tapeIx]?.[0] ?? cell;
+            }
+            return cell;
+        });
+    });
+}
+const movementLabelToSymbol = {
+    L: movements.left,
+    R: movements.right,
+    S: movements.stay,
+};
+export function parseMovementLabel(label) {
+    const m = movementLabelToSymbol[label];
+    if (!m) {
+        throw new Error(`unknown movement label: ${label}`);
+    }
+    return m;
+}
+export function parseWriteSymbolLabel(label) {
+    if (label === '·') {
+        return symbolCommands.keep;
+    }
+    if (label === '⌫') {
+        return symbolCommands.erase;
+    }
+    return label;
+}
+export function decodeWriteSymbol(symbol) {
+    if (typeof symbol === 'symbol') {
+        const description = symbol.description ?? '?';
+        return symbolCommandDescriptionToLabel[description] ?? description;
+    }
+    return symbol;
+}
+// Format converters (toMermaid / fromMermaid) live in ./graphFormats.

package/dist/utilities/graphFormats.d.ts

@@ -0,0 +1,3 @@
+import { type Graph } from './graph';
+export declare function toMermaid(graph: Graph): string;
+export declare function fromMermaid(text: string): Graph;

package/dist/utilities/graphFormats.js

@@ -0,0 +1,141 @@
+// Format converters between a Graph (the data model produced by State.toGraph
+// and consumed by State.fromGraph) and external string representations.
+//
+// Currently only Mermaid flowchart syntax is supported. Future formats
+// (Graphviz, JSON-LD, custom DSL) belong here too.
+export function toMermaid(graph) {
+    const lines = [
+        'flowchart TD',
+        `%% alphabets: ${JSON.stringify(graph.alphabets)}`,
+    ];
+    for (const node of Object.values(graph.nodes)) {
+        const id = `s${node.id}`;
+        if (node.isHalt) {
+            lines.push(`  ${id}(((halt)))`);
+        }
+        else if (node.id === graph.initialId) {
+            lines.push(`  ${id}(("${node.name}"))`);
+        }
+        else {
+            lines.push(`  ${id}["${node.name}"]`);
+        }
+    }
+    for (const node of Object.values(graph.nodes)) {
+        for (const t of node.transitions) {
+            // Per-tape commands separated with ',' to mirror the pattern syntax.
+            const cmd = t.command.map((c) => `${c.symbol}/${c.movement}`).join(',');
+            const label = `${t.pattern} → ${cmd}`;
+            lines.push(`  s${node.id} -- "${label}" --> s${t.nextStateId}`);
+        }
+        if (node.overrodeHaltStateId !== null) {
+            lines.push(`  s${node.id} -. onHalt .-> s${node.overrodeHaltStateId}`);
+        }
+    }
+    return lines.join('\n');
+}
+// Inverse of toMermaid: parses the Mermaid output produced by toMermaid back
+// into a Graph. The parser is strict to the dialect toMermaid emits — it
+// recognises the specific node/edge shapes and the leading
+// `%% alphabets: [...]` comment. Hand-edited Mermaid that uses different
+// arrow styles or shapes will not parse.
+//
+// Caveats:
+// - Write-symbol cells in commands are split on '/' (last occurrence) and
+//   per-tape segments are split on ','. If your alphabet contains '/' or ','
+//   as literal symbols, the parser cannot disambiguate. Stick to alphabets
+//   without those characters when round-tripping through Mermaid.
+const haltNodeRegex = /^s(\d+)\(\(\(halt\)\)\)$/;
+const initialNodeRegex = /^s(\d+)\(\("([^"]*)"\)\)$/;
+const regularNodeRegex = /^s(\d+)\["([^"]*)"\]$/;
+const transitionRegex = /^s(\d+)\s+--\s+"(.*)"\s+-->\s+s(\d+)$/;
+const onHaltRegex = /^s(\d+)\s+-\.\s+onHalt\s+\.->\s+s(\d+)$/;
+const alphabetsRegex = /^%%\s*alphabets:\s*(.+)$/;
+export function fromMermaid(text) {
+    const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
+    let alphabets = [];
+    let initialId = null;
+    const nodes = {};
+    const ensureNode = (id, opts = {}) => {
+        if (!nodes[id]) {
+            nodes[id] = {
+                id,
+                name: opts.name ?? `s${id}`,
+                isHalt: opts.isHalt ?? false,
+                transitions: [],
+                overrodeHaltStateId: null,
+            };
+        }
+        else {
+            if (opts.name !== undefined) {
+                nodes[id].name = opts.name;
+            }
+            if (opts.isHalt !== undefined) {
+                nodes[id].isHalt = opts.isHalt;
+            }
+        }
+        return nodes[id];
+    };
+    // First pass: alphabets + nodes.
+    for (const line of lines) {
+        if (line === 'flowchart TD') {
+            continue;
+        }
+        const am = line.match(alphabetsRegex);
+        if (am) {
+            alphabets = JSON.parse(am[1]);
+            continue;
+        }
+        const hm = line.match(haltNodeRegex);
+        if (hm) {
+            ensureNode(Number(hm[1]), { name: 'halt', isHalt: true });
+            continue;
+        }
+        const im = line.match(initialNodeRegex);
+        if (im) {
+            const id = Number(im[1]);
+            initialId = id;
+            ensureNode(id, { name: im[2] });
+            continue;
+        }
+        const rm = line.match(regularNodeRegex);
+        if (rm) {
+            ensureNode(Number(rm[1]), { name: rm[2] });
+            continue;
+        }
+    }
+    // Second pass: edges.
+    for (const line of lines) {
+        const om = line.match(onHaltRegex);
+        if (om) {
+            ensureNode(Number(om[1])).overrodeHaltStateId = Number(om[2]);
+            continue;
+        }
+        const tm = line.match(transitionRegex);
+        if (tm) {
+            const fromId = Number(tm[1]);
+            const label = tm[2];
+            const toId = Number(tm[3]);
+            const arrowIx = label.indexOf(' → ');
+            if (arrowIx === -1) {
+                throw new Error(`fromMermaid: malformed edge label: "${label}"`);
+            }
+            const pattern = label.slice(0, arrowIx);
+            const commandStr = label.slice(arrowIx + ' → '.length);
+            const command = commandStr.split(',').map((part) => {
+                const slashIx = part.lastIndexOf('/');
+                if (slashIx === -1) {
+                    throw new Error(`fromMermaid: malformed command part: "${part}"`);
+                }
+                return {
+                    symbol: part.slice(0, slashIx),
+                    movement: part.slice(slashIx + 1),
+                };
+            });
+            ensureNode(fromId).transitions.push({ pattern, command, nextStateId: toId });
+        }
+    }
+    if (initialId === null) {
+        throw new Error('fromMermaid: no initial state (double-paren node) found');
+    }
+    return { initialId, alphabets, nodes };
+}

package/dist/utilities/introspection.d.ts

@@ -0,0 +1,15 @@
+import State from '../classes/State';
+import TapeBlock from '../classes/TapeBlock';
+import { type Graph } from './graph';
+export type GraphSummary = {
+    stateCount: number;
+    transitionCount: number;
+    compositionEdgeCount: number;
+    maxCompositionDepth: number;
+    selfLoopCount: number;
+    hasCycles: boolean;
+    tapeCount: number;
+    alphabetCardinalities: number[];
+};
+export declare function summarizeGraph(graph: Graph): GraphSummary;
+export declare function summarize(state: State, tapeBlock: TapeBlock): GraphSummary;

package/dist/utilities/introspection.js

@@ -0,0 +1,88 @@
+import State from '../classes/State';
+export function summarizeGraph(graph) {
+    const nodes = Object.values(graph.nodes);
+    let transitionCount = 0;
+    let compositionEdgeCount = 0;
+    let selfLoopCount = 0;
+    for (const node of nodes) {
+        transitionCount += node.transitions.length;
+        if (node.overrodeHaltStateId !== null) {
+            compositionEdgeCount += 1;
+        }
+        for (const t of node.transitions) {
+            if (t.nextStateId === node.id) {
+                selfLoopCount += 1;
+            }
+        }
+    }
+    // Longest withOverrodeHaltState chain. Walks node → overrodeHaltState recursively;
+    // a Set guards against cycles in the override graph (which throw at construction
+    // time anyway, but being defensive costs little).
+    const overrideDepthFrom = (id, visited) => {
+        if (visited.has(id)) {
+            return 0;
+        }
+        visited.add(id);
+        const node = graph.nodes[id];
+        if (!node || node.overrodeHaltStateId === null) {
+            return 0;
+        }
+        return 1 + overrideDepthFrom(node.overrodeHaltStateId, visited);
+    };
+    const maxCompositionDepth = nodes.reduce((max, node) => Math.max(max, overrideDepthFrom(node.id, new Set())), 0);
+    // Cycle detection: tri-color DFS over the transition graph.
+    const WHITE = 0;
+    const GREY = 1;
+    const BLACK = 2;
+    const color = new Map();
+    for (const node of nodes) {
+        color.set(node.id, WHITE);
+    }
+    let hasCycles = false;
+    const visit = (id) => {
+        if (hasCycles) {
+            return;
+        }
+        if (color.get(id) === GREY) {
+            hasCycles = true;
+            return;
+        }
+        if (color.get(id) === BLACK) {
+            return;
+        }
+        color.set(id, GREY);
+        const node = graph.nodes[id];
+        if (node) {
+            for (const t of node.transitions) {
+                visit(t.nextStateId);
+                if (hasCycles) {
+                    return;
+                }
+            }
+        }
+        color.set(id, BLACK);
+    };
+    for (const node of nodes) {
+        if (hasCycles) {
+            break;
+        }
+        visit(node.id);
+    }
+    return {
+        stateCount: nodes.length,
+        transitionCount,
+        compositionEdgeCount,
+        maxCompositionDepth,
+        selfLoopCount,
+        hasCycles,
+        tapeCount: graph.alphabets.length,
+        alphabetCardinalities: graph.alphabets.map((a) => a.length),
+    };
+}
+// Convenience: build the graph and summarize in one step.
+export function summarize(state, tapeBlock) {
+    return summarizeGraph(State.toGraph(state, tapeBlock));
+}
+// Behavioral equivalence checking (the testing-tool counterpart to introspection)
+// lives in ./equivalence — kept separate because it runs machines and compares
+// outputs rather than examining structure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "2.0.2",
+  "version": "3.0.0",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
@@ -32,13 +32,7 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs",
       "default": "./dist/index.mjs"
-    },
-    "./src": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs",
-      "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "54da1870a45fd78496c6ba56ce1de728d766470b"
+  "gitHead": "98decf323129d528febafac1bec581a9ee3800ff"
 }

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/index.ts","./src/classes/alphabet.ts","./src/classes/command.ts","./src/classes/lock.ts","./src/classes/reference.ts","./src/classes/state.ts","./src/classes/tape.ts","./src/classes/tapeblock.ts","./src/classes/tapecommand.ts","./src/classes/turingmachine.ts","./src/utilities/functions.ts"],"version":"5.9.3"}