@unlaxer/tramli 1.3.0 → 1.5.0

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

@@ -57,7 +57,36 @@ 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;
+    /** Recommended migration order: processors sorted by dependency (fewest first). */
+    migrationOrder(): string[];
+    /** Generate Markdown migration checklist. */
+    toMarkdown(): 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,149 @@ export class DataFlowGraph {
         }
         return lines.join('\n') + '\n';
     }
+    /** Recommended migration order: processors sorted by dependency (fewest first). */
+    migrationOrder() {
+        const nodeReqs = new Map();
+        const nodeProds = new Map();
+        for (const [t, ns] of this._consumers)
+            for (const n of ns) {
+                if (!nodeReqs.has(n.name))
+                    nodeReqs.set(n.name, new Set());
+                nodeReqs.get(n.name).add(t);
+            }
+        for (const [t, ns] of this._producers)
+            for (const n of ns) {
+                if (!nodeProds.has(n.name))
+                    nodeProds.set(n.name, new Set());
+                nodeProds.get(n.name).add(t);
+            }
+        const order = [];
+        const available = new Set();
+        for (const [t, ns] of this._producers) {
+            if (ns.some(n => n.name === 'initial'))
+                available.add(t);
+        }
+        const remaining = new Set([...nodeReqs.keys(), ...nodeProds.keys()]);
+        remaining.delete('initial');
+        while (remaining.size > 0) {
+            let next = null;
+            for (const name of remaining) {
+                const reqs = nodeReqs.get(name) ?? new Set();
+                if ([...reqs].every(r => available.has(r))) {
+                    next = name;
+                    break;
+                }
+            }
+            if (!next) {
+                order.push(...remaining);
+                break;
+            }
+            order.push(next);
+            remaining.delete(next);
+            for (const p of nodeProds.get(next) ?? [])
+                available.add(p);
+        }
+        return order;
+    }
+    /** Generate Markdown migration checklist. */
+    toMarkdown() {
+        const lines = ['# Migration Checklist\n'];
+        const order = this.migrationOrder();
+        for (let i = 0; i < order.length; i++) {
+            const name = order[i];
+            const reqs = [];
+            for (const [t, ns] of this._consumers)
+                if (ns.some(n => n.name === name))
+                    reqs.push(t);
+            const prods = [];
+            for (const [t, ns] of this._producers)
+                if (ns.some(n => n.name === name))
+                    prods.push(t);
+            let line = `- [ ] **${i + 1}. ${name}**`;
+            if (reqs.length)
+                line += `  requires: [${reqs.join(', ')}]`;
+            if (prods.length)
+                line += `  produces: [${prods.join(', ')}]`;
+            lines.push(line);
+        }
+        const dead = this.deadData();
+        if (dead.size > 0) {
+            lines.push('\n## Dead Data\n');
+            for (const d of dead)
+                lines.push(`- ${d}`);
+        }
+        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/index.d.ts

@@ -7,6 +7,8 @@ export { FlowError } from './flow-error.js';
 export { InMemoryFlowStore } from './in-memory-flow-store.js';
 export type { TransitionRecord } from './in-memory-flow-store.js';
 export { MermaidGenerator } from './mermaid-generator.js';
+export { SkeletonGenerator } from './skeleton-generator.js';
+export type { TargetLanguage } from './skeleton-generator.js';
 export { DataFlowGraph } from './data-flow-graph.js';
 export type { NodeInfo } from './data-flow-graph.js';
 export { flowKey } from './flow-key.js';

package/dist/index.js

@@ -6,5 +6,6 @@ export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } f
 export { FlowError } from './flow-error.js';
 export { InMemoryFlowStore } from './in-memory-flow-store.js';
 export { MermaidGenerator } from './mermaid-generator.js';
+export { SkeletonGenerator } from './skeleton-generator.js';
 export { DataFlowGraph } from './data-flow-graph.js';
 export { flowKey } from './flow-key.js';

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/dist/skeleton-generator.d.ts

@@ -0,0 +1,10 @@
+import type { FlowDefinition } from './flow-definition.js';
+export type TargetLanguage = 'java' | 'typescript' | 'rust';
+/**
+ * Generates Processor skeleton code from a FlowDefinition's requires/produces contracts.
+ */
+export declare class SkeletonGenerator {
+    static generate<S extends string>(def: FlowDefinition<S>, lang: TargetLanguage): string;
+    private static genProcessor;
+    private static genGuard;
+}

package/dist/skeleton-generator.js

@@ -0,0 +1,44 @@
+/**
+ * Generates Processor skeleton code from a FlowDefinition's requires/produces contracts.
+ */
+export class SkeletonGenerator {
+    static generate(def, lang) {
+        const lines = [
+            `// Skeleton generated from flow: ${def.name}`,
+            `// Language: ${lang}`,
+            '',
+        ];
+        const seen = new Set();
+        for (const t of def.transitions) {
+            if (t.processor && !seen.has(t.processor.name)) {
+                seen.add(t.processor.name);
+                lines.push(this.genProcessor(t.processor.name, t.processor.requires, t.processor.produces, lang));
+            }
+            if (t.guard && !seen.has(t.guard.name)) {
+                seen.add(t.guard.name);
+                lines.push(this.genGuard(t.guard.name, t.guard.requires, t.guard.produces, lang));
+            }
+        }
+        return lines.join('\n');
+    }
+    static genProcessor(name, reqs, prods, lang) {
+        if (lang === 'typescript') {
+            return `const ${lcFirst(name)}: StateProcessor<S> = {\n  name: '${name}',\n  requires: [${reqs.join(', ')}],\n  produces: [${prods.join(', ')}],\n  process(ctx: FlowContext) {\n${reqs.map(r => `    const ${lcFirst(r)} = ctx.get(${r});`).join('\n')}\n    // TODO: implement\n${prods.map(p => `    // ctx.put(${p}, { ... });`).join('\n')}\n  },\n};\n`;
+        }
+        if (lang === 'java') {
+            return `static final StateProcessor ${name.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase()} = new StateProcessor() {\n    @Override public String name() { return "${name}"; }\n    @Override public Set<Class<?>> requires() { return Set.of(${reqs.map(r => r + '.class').join(', ')}); }\n    @Override public Set<Class<?>> produces() { return Set.of(${prods.map(p => p + '.class').join(', ')}); }\n    @Override public void process(FlowContext ctx) {\n        // TODO: implement\n    }\n};\n`;
+        }
+        // rust
+        return `struct ${name};\nimpl StateProcessor<S> for ${name} {\n    fn name(&self) -> &str { "${name}" }\n    fn requires(&self) -> Vec<TypeId> { requires![${reqs.join(', ')}] }\n    fn produces(&self) -> Vec<TypeId> { requires![${prods.join(', ')}] }\n    fn process(&self, ctx: &mut FlowContext) -> Result<(), FlowError> {\n        todo!()\n    }\n}\n`;
+    }
+    static genGuard(name, reqs, prods, lang) {
+        if (lang === 'typescript') {
+            return `const ${lcFirst(name)}: TransitionGuard<S> = {\n  name: '${name}',\n  requires: [${reqs.join(', ')}],\n  produces: [${prods.join(', ')}],\n  maxRetries: 3,\n  validate(ctx: FlowContext): GuardOutput {\n    // TODO: implement\n    return { type: 'accepted' };\n  },\n};\n`;
+        }
+        if (lang === 'java') {
+            return `static final TransitionGuard ${name.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase()} = new TransitionGuard() {\n    @Override public String name() { return "${name}"; }\n    @Override public Set<Class<?>> requires() { return Set.of(${reqs.map(r => r + '.class').join(', ')}); }\n    @Override public Set<Class<?>> produces() { return Set.of(${prods.map(p => p + '.class').join(', ')}); }\n    @Override public int maxRetries() { return 3; }\n    @Override public GuardOutput validate(FlowContext ctx) {\n        return new GuardOutput.Accepted();\n    }\n};\n`;
+        }
+        return `struct ${name};\nimpl TransitionGuard<S> for ${name} {\n    fn name(&self) -> &str { "${name}" }\n    fn requires(&self) -> Vec<TypeId> { requires![${reqs.join(', ')}] }\n    fn produces(&self) -> Vec<TypeId> { requires![${prods.join(', ')}] }\n    fn validate(&self, ctx: &FlowContext) -> GuardOutput {\n        GuardOutput::Accepted { data: HashMap::new() }\n    }\n}\n`;
+    }
+}
+function lcFirst(s) { return s.charAt(0).toLowerCase() + s.slice(1); }

package/package.json

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