@unlaxer/tramli 1.4.0 → 1.5.0

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

@@ -68,6 +68,10 @@ export declare class DataFlowGraph<S extends string> {
     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. */

package/dist/data-flow-graph.js

@@ -223,6 +223,79 @@ 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();

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/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.4.0",
+  "version": "1.5.0",
   "description": "Constrained flow engine — state machines that prevent invalid transitions at build time",
   "type": "module",
   "exports": {