@unlaxer/tramli 1.3.0 → 1.4.0

package/dist/data-flow-graph.d.ts

@@ -57,7 +57,32 @@ export declare class DataFlowGraph<S extends string> {
      * Returns list of missing type keys (empty = OK).
      */
     assertDataFlow(ctx: FlowContext, currentState: S): string[];
+    /** Impact analysis: all producers and consumers of a given type. */
+    impactOf(key: FlowKey<unknown>): {
+        producers: NodeInfo<S>[];
+        consumers: NodeInfo<S>[];
+    };
+    /** Parallelism hints: pairs of processors with no data dependency. */
+    parallelismHints(): [string, string][];
+    /** Structured JSON representation. */
+    toJson(): string;
     /** Generate Mermaid data-flow diagram. */
     toMermaid(): string;
+    /** Test scaffold: for each processor, list required type names. */
+    testScaffold(): Map<string, string[]>;
+    /** Generate data-flow invariant assertions as strings. */
+    generateInvariantAssertions(): string[];
+    /** Cross-flow map: types that one flow produces and another requires. */
+    static crossFlowMap(...graphs: DataFlowGraph<any>[]): string[];
+    /** Diff two data-flow graphs. */
+    static diff(before: DataFlowGraph<any>, after: DataFlowGraph<any>): {
+        addedTypes: Set<string>;
+        removedTypes: Set<string>;
+        addedEdges: Set<string>;
+        removedEdges: Set<string>;
+    };
+    private static collectEdges;
+    /** Version compatibility: check if v1 instances can resume on v2 definition. */
+    static versionCompatibility<S extends string>(before: DataFlowGraph<S>, after: DataFlowGraph<S>): string[];
     static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[]): DataFlowGraph<S>;
 }

package/dist/data-flow-graph.js

@@ -142,6 +142,63 @@ export class DataFlowGraph {
         }
         return missing;
     }
+    /** Impact analysis: all producers and consumers of a given type. */
+    impactOf(key) {
+        return { producers: this.producersOf(key), consumers: this.consumersOf(key) };
+    }
+    /** Parallelism hints: pairs of processors with no data dependency. */
+    parallelismHints() {
+        const allNodes = new Set();
+        for (const nodes of this._producers.values())
+            for (const n of nodes)
+                allNodes.add(n.name);
+        for (const nodes of this._consumers.values())
+            for (const n of nodes)
+                allNodes.add(n.name);
+        const list = [...allNodes];
+        const hints = [];
+        for (let i = 0; i < list.length; i++) {
+            for (let j = i + 1; j < list.length; j++) {
+                const aProds = new Set(), bReqs = new Set();
+                const bProds = new Set(), aReqs = new Set();
+                for (const [t, ns] of this._producers) {
+                    for (const n of ns) {
+                        if (n.name === list[i])
+                            aProds.add(t);
+                        if (n.name === list[j])
+                            bProds.add(t);
+                    }
+                }
+                for (const [t, ns] of this._consumers) {
+                    for (const n of ns) {
+                        if (n.name === list[i])
+                            aReqs.add(t);
+                        if (n.name === list[j])
+                            bReqs.add(t);
+                    }
+                }
+                const aDepB = [...aReqs].some(r => bProds.has(r));
+                const bDepA = [...bReqs].some(r => aProds.has(r));
+                if (!aDepB && !bDepA)
+                    hints.push([list[i], list[j]]);
+            }
+        }
+        return hints;
+    }
+    /** Structured JSON representation. */
+    toJson() {
+        const types = [...this.allTypes()].map(t => {
+            const entry = { name: t };
+            const prods = this.producersOf(t);
+            if (prods.length)
+                entry.producers = prods.map(p => p.name);
+            const cons = this.consumersOf(t);
+            if (cons.length)
+                entry.consumers = cons.map(c => c.name);
+            return entry;
+        });
+        return JSON.stringify({ types, deadData: [...this.deadData()] }, null, 2);
+    }
     /** Generate Mermaid data-flow diagram. */
     toMermaid() {
         const lines = ['flowchart LR'];
@@ -166,6 +223,76 @@ export class DataFlowGraph {
         }
         return lines.join('\n') + '\n';
     }
+    /** Test scaffold: for each processor, list required type names. */
+    testScaffold() {
+        const scaffold = new Map();
+        for (const [typeName, nodes] of this._consumers) {
+            for (const node of nodes) {
+                if (!scaffold.has(node.name))
+                    scaffold.set(node.name, []);
+                scaffold.get(node.name).push(typeName);
+            }
+        }
+        return scaffold;
+    }
+    /** Generate data-flow invariant assertions as strings. */
+    generateInvariantAssertions() {
+        const assertions = [];
+        for (const [state, types] of this._availableAtState) {
+            assertions.push(`At state ${state}: context must contain [${[...types].sort().join(', ')}]`);
+        }
+        return assertions;
+    }
+    // ─── Cross-flow / Versioning utilities ─────────────────────
+    /** Cross-flow map: types that one flow produces and another requires. */
+    static crossFlowMap(...graphs) {
+        const results = [];
+        for (let i = 0; i < graphs.length; i++) {
+            for (let j = 0; j < graphs.length; j++) {
+                if (i === j)
+                    continue;
+                for (const produced of graphs[i]._allProduced) {
+                    if (graphs[j]._allConsumed.has(produced)) {
+                        results.push(`${produced}: flow ${i} produces → flow ${j} consumes`);
+                    }
+                }
+            }
+        }
+        return results;
+    }
+    /** Diff two data-flow graphs. */
+    static diff(before, after) {
+        const beforeTypes = before.allTypes(), afterTypes = after.allTypes();
+        const addedTypes = new Set([...afterTypes].filter(t => !beforeTypes.has(t)));
+        const removedTypes = new Set([...beforeTypes].filter(t => !afterTypes.has(t)));
+        const beforeEdges = DataFlowGraph.collectEdges(before), afterEdges = DataFlowGraph.collectEdges(after);
+        const addedEdges = new Set([...afterEdges].filter(e => !beforeEdges.has(e)));
+        const removedEdges = new Set([...beforeEdges].filter(e => !afterEdges.has(e)));
+        return { addedTypes, removedTypes, addedEdges, removedEdges };
+    }
+    static collectEdges(graph) {
+        const edges = new Set();
+        for (const [t, ns] of graph._producers)
+            for (const n of ns)
+                edges.add(`${n.name} --produces--> ${t}`);
+        for (const [t, ns] of graph._consumers)
+            for (const n of ns)
+                edges.add(`${t} --requires--> ${n.name}`);
+        return edges;
+    }
+    /** Version compatibility: check if v1 instances can resume on v2 definition. */
+    static versionCompatibility(before, after) {
+        const issues = [];
+        for (const [state, beforeAvail] of before._availableAtState) {
+            const afterAvail = after._availableAtState.get(state) ?? new Set();
+            for (const type of afterAvail) {
+                if (!beforeAvail.has(type)) {
+                    issues.push(`State ${state}: v2 expects ${type} but v1 instances may not have it`);
+                }
+            }
+        }
+        return issues;
+    }
     // ─── Builder ─────────────────────────────────────────────
     static build(def, initiallyAvailable) {
         const stateAvail = new Map();

package/dist/flow-definition.d.ts

@@ -15,6 +15,10 @@ export declare class FlowDefinition<S extends string> {
     transitionsFrom(state: S): Transition<S>[];
     externalFrom(state: S): Transition<S> | undefined;
     allStates(): S[];
+    /**
+     * Create a new FlowDefinition with a sub-flow inserted before a specific transition.
+     */
+    withPlugin(from: S, to: S, pluginFlow: FlowDefinition<any>): FlowDefinition<S>;
     static builder<S extends string>(name: string, stateConfig: Record<S, StateConfig>): Builder<S>;
 }
 export declare class Builder<S extends string> {

package/dist/flow-definition.js

@@ -37,6 +37,42 @@ export class FlowDefinition {
     allStates() {
         return Object.keys(this.stateConfig);
     }
+    /**
+     * Create a new FlowDefinition with a sub-flow inserted before a specific transition.
+     */
+    withPlugin(from, to, pluginFlow) {
+        const newTransitions = [];
+        let replaced = false;
+        for (const t of this.transitions) {
+            if (t.from === from && t.to === to && !replaced) {
+                const exitMap = new Map();
+                for (const terminal of pluginFlow.terminalStates)
+                    exitMap.set(terminal, to);
+                newTransitions.push({
+                    from, to: from, type: 'sub_flow',
+                    processor: t.processor, guard: undefined, branch: undefined,
+                    branchTargets: new Map(),
+                    subFlowDefinition: pluginFlow, exitMappings: exitMap,
+                });
+                replaced = true;
+            }
+            else {
+                newTransitions.push(t);
+            }
+        }
+        const result = Object.create(FlowDefinition.prototype);
+        Object.assign(result, {
+            name: this.name + '+plugin:' + pluginFlow.name,
+            stateConfig: this.stateConfig, ttl: this.ttl,
+            maxGuardRetries: this.maxGuardRetries,
+            transitions: newTransitions,
+            errorTransitions: new Map(this.errorTransitions),
+            initialState: this.initialState,
+            terminalStates: this.terminalStates,
+            dataFlowGraph: null, // will be rebuilt if needed
+        });
+        return result;
+    }
     // ─── Builder ─────────────────────────────────────────────
     static builder(name, stateConfig) {
         return new Builder(name, stateConfig);

package/dist/flow-instance.d.ts

@@ -28,6 +28,10 @@ export declare class FlowInstance<S extends string> {
     statePath(): string[];
     /** State path as slash-separated string. */
     statePathString(): string;
+    /** Data types available in context at current state (from data-flow graph). */
+    availableData(): Set<string>;
+    /** Data types that the next transition requires but are not yet in context. */
+    missingFor(): string[];
     /** Types required by the next external transition (including in active sub-flows). */
     waitingFor(): string[];
     /** Return a copy with the given version. For FlowStore optimistic locking. */

package/dist/flow-instance.js

@@ -56,6 +56,27 @@ export class FlowInstance {
     }
     /** State path as slash-separated string. */
     statePathString() { return this.statePath().join('/'); }
+    /** Data types available in context at current state (from data-flow graph). */
+    availableData() {
+        return this.definition.dataFlowGraph?.availableAt(this._currentState) ?? new Set();
+    }
+    /** Data types that the next transition requires but are not yet in context. */
+    missingFor() {
+        const missing = [];
+        for (const t of this.definition.transitionsFrom(this._currentState)) {
+            if (t.guard)
+                for (const r of t.guard.requires) {
+                    if (!this.context.has(r))
+                        missing.push(r);
+                }
+            if (t.processor)
+                for (const r of t.processor.requires) {
+                    if (!this.context.has(r))
+                        missing.push(r);
+                }
+        }
+        return [...new Set(missing)];
+    }
     /** Types required by the next external transition (including in active sub-flows). */
     waitingFor() {
         if (this._activeSubFlow)

package/dist/mermaid-generator.d.ts

@@ -1,6 +1,8 @@
 import type { FlowDefinition } from './flow-definition.js';
 export declare class MermaidGenerator {
     static generate<S extends string>(def: FlowDefinition<S>): string;
+    /** Generate Mermaid diagram highlighting external transitions and their data contracts. */
+    static generateExternalContract<S extends string>(def: FlowDefinition<S>): string;
     /** Generate Mermaid data-flow diagram from requires/produces declarations. */
     static generateDataFlow<S extends string>(def: FlowDefinition<S>): string;
     private static transitionLabel;

package/dist/mermaid-generator.js

@@ -43,6 +43,23 @@ export class MermaidGenerator {
         }
         return lines.join('\n') + '\n';
     }
+    /** Generate Mermaid diagram highlighting external transitions and their data contracts. */
+    static generateExternalContract(def) {
+        const lines = ['flowchart LR'];
+        for (const t of def.transitions) {
+            if (t.type !== 'external' || !t.guard)
+                continue;
+            lines.push(`    subgraph ${t.from}_to_${t.to}`);
+            lines.push('        direction TB');
+            lines.push(`        ${t.guard.name}{"[${t.guard.name}]"}`);
+            for (const req of t.guard.requires)
+                lines.push(`        ${req} -->|client sends| ${t.guard.name}`);
+            for (const prod of t.guard.produces)
+                lines.push(`        ${t.guard.name} -->|returns| ${prod}`);
+            lines.push('    end');
+        }
+        return lines.join('\n') + '\n';
+    }
     /** Generate Mermaid data-flow diagram from requires/produces declarations. */
     static generateDataFlow(def) {
         return def.dataFlowGraph?.toMermaid() ?? '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlaxer/tramli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Constrained flow engine — state machines that prevent invalid transitions at build time",
   "type": "module",
   "exports": {