@unlaxer/tramli-plugins 3.1.0 → 3.3.0

package/dist/cjs/api/types.d.ts

@@ -36,16 +36,35 @@ export interface GenerationPlugin<I, O> extends FlowPlugin {
 /** Documentation plugin — generates string documentation. */
 export interface DocumentationPlugin<I> extends GenerationPlugin<I, string> {
 }
+/** Describes where in a flow definition a finding is located. */
+export type FindingLocation = {
+    type: 'transition';
+    fromState: string;
+    toState: string;
+} | {
+    type: 'state';
+    state: string;
+} | {
+    type: 'data';
+    dataKey: string;
+} | {
+    type: 'flow';
+};
+/** A single analysis finding. */
+export interface FindingEntry {
+    pluginId: string;
+    severity: string;
+    message: string;
+    location?: FindingLocation;
+}
 /** Plugin report — collects analysis findings. */
 export declare class PluginReport {
     private entries;
     add(pluginId: string, severity: string, message: string): void;
     warn(pluginId: string, message: string): void;
     error(pluginId: string, message: string): void;
+    warnAt(pluginId: string, message: string, location: FindingLocation): void;
+    errorAt(pluginId: string, message: string, location: FindingLocation): void;
     asText(): string;
-    findings(): {
-        pluginId: string;
-        severity: string;
-        message: string;
-    }[];
+    findings(): FindingEntry[];
 }

package/dist/cjs/api/types.js

@@ -13,11 +13,30 @@ class PluginReport {
     error(pluginId, message) {
         this.add(pluginId, 'ERROR', message);
     }
+    warnAt(pluginId, message, location) {
+        this.entries.push({ pluginId, severity: 'WARN', message, location });
+    }
+    errorAt(pluginId, message, location) {
+        this.entries.push({ pluginId, severity: 'ERROR', message, location });
+    }
     asText() {
         if (this.entries.length === 0)
             return 'No findings.';
-        return this.entries.map(e => `[${e.severity}] ${e.pluginId}: ${e.message}`).join('\n');
+        return this.entries.map(e => {
+            let text = `[${e.severity}] ${e.pluginId}: ${e.message}`;
+            if (e.location)
+                text += ` @ ${formatLocation(e.location)}`;
+            return text;
+        }).join('\n');
     }
     findings() { return [...this.entries]; }
 }
 exports.PluginReport = PluginReport;
+function formatLocation(loc) {
+    switch (loc.type) {
+        case 'transition': return `transition(${loc.fromState} -> ${loc.toState})`;
+        case 'state': return `state(${loc.state})`;
+        case 'data': return `data(${loc.dataKey})`;
+        case 'flow': return 'flow';
+    }
+}

package/dist/cjs/index.d.ts

@@ -1,5 +1,5 @@
 export { PluginReport } from './api/types.js';
-export type { PluginKind, PluginDescriptor, FlowPlugin, AnalysisPlugin, StorePlugin, EnginePlugin, RuntimeAdapterPlugin, GenerationPlugin, DocumentationPlugin as DocumentationPluginSPI, } from './api/types.js';
+export type { FindingLocation, FindingEntry, PluginKind, PluginDescriptor, FlowPlugin, AnalysisPlugin, StorePlugin, EnginePlugin, RuntimeAdapterPlugin, GenerationPlugin, DocumentationPlugin as DocumentationPluginSPI, } from './api/types.js';
 export { PluginRegistry } from './api/plugin-registry.js';
 export { AuditStorePlugin } from './audit/audit-store-plugin.js';
 export { AuditingFlowStore } from './audit/auditing-flow-store.js';
@@ -32,5 +32,5 @@ export { allDefaultPolicies } from './lint/default-flow-policies.js';
 export type { FlowPolicy } from './lint/types.js';
 export { ScenarioTestPlugin } from './testing/scenario-test-plugin.js';
 export { ScenarioGenerationPlugin } from './testing/scenario-generation-plugin.js';
-export type { FlowScenario, FlowTestPlan } from './testing/types.js';
+export type { FlowScenario, FlowTestPlan, ScenarioKind } from './testing/types.js';
 export { GuaranteedSubflowValidator } from './subflow/guaranteed-subflow-validator.js';

package/dist/cjs/lint/default-flow-policies.js

@@ -4,7 +4,7 @@ exports.allDefaultPolicies = allDefaultPolicies;
 function warnTerminalWithOutgoing(def, report) {
     for (const state of def.terminalStates) {
         if (def.transitionsFrom(state).length > 0) {
-            report.warn('policy/terminal-outgoing', `terminal state ${state} has outgoing transitions`);
+            report.warnAt('policy/terminal-outgoing', `terminal state ${state} has outgoing transitions`, { type: 'state', state });
         }
     }
 }
@@ -12,7 +12,7 @@ function warnTooManyExternals(def, report) {
     for (const state of def.allStates()) {
         const externals = def.transitionsFrom(state).filter(t => t.type === 'external');
         if (externals.length > 3) {
-            report.warn('policy/external-count', `state ${state} has ${externals.length} external transitions`);
+            report.warnAt('policy/external-count', `state ${state} has ${externals.length} external transitions`, { type: 'state', state });
         }
     }
 }
@@ -21,13 +21,13 @@ function warnDeadProducedData(def, report) {
         return;
     const dead = def.dataFlowGraph.deadData();
     for (const key of dead) {
-        report.warn('policy/dead-data', `produced but never consumed: ${key}`);
+        report.warnAt('policy/dead-data', `produced but never consumed: ${key}`, { type: 'data', dataKey: key });
     }
 }
 function warnOverwideProcessors(def, report) {
     for (const t of def.transitions) {
         if (t.processor && t.processor.produces.length > 3) {
-            report.warn('policy/overwide-processor', `${t.processor.name} produces ${t.processor.produces.length} types; consider splitting it`);
+            report.warnAt('policy/overwide-processor', `${t.processor.name} produces ${t.processor.produces.length} types; consider splitting it`, { type: 'transition', fromState: t.from, toState: t.to });
         }
     }
 }

package/dist/cjs/testing/scenario-test-plugin.d.ts

@@ -2,6 +2,7 @@ import type { FlowDefinition } from '@unlaxer/tramli';
 import type { FlowTestPlan } from './types.js';
 /**
  * Generates BDD-style test scenarios from a flow definition.
+ * Covers happy paths, error transitions, guard rejections, and timeout expiry.
  */
 export declare class ScenarioTestPlugin {
     generate<S extends string>(definition: FlowDefinition<S>): FlowTestPlan;

package/dist/cjs/testing/scenario-test-plugin.js

@@ -3,10 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ScenarioTestPlugin = void 0;
 /**
  * Generates BDD-style test scenarios from a flow definition.
+ * Covers happy paths, error transitions, guard rejections, and timeout expiry.
  */
 class ScenarioTestPlugin {
     generate(definition) {
         const scenarios = [];
+        // Happy path scenarios from transitions
         for (const t of definition.transitions) {
             const steps = [];
             steps.push(`given flow in ${t.from}`);
@@ -20,7 +22,67 @@ class ScenarioTestPlugin {
                 steps.push(`when branch ${t.branch.name} selects a route`);
             }
             steps.push(`then flow reaches ${t.to}`);
-            scenarios.push({ name: `${t.from}_to_${t.to}`, steps });
+            scenarios.push({ name: `${t.from}_to_${t.to}`, kind: 'happy', steps });
+        }
+        // Error path scenarios from errorTransitions
+        for (const [from, to] of definition.errorTransitions) {
+            scenarios.push({
+                name: `error_${from}_to_${to}`,
+                kind: 'error',
+                steps: [
+                    `given flow in ${from}`,
+                    `when processor throws an error`,
+                    `then flow transitions to ${to} via on_error`,
+                ],
+            });
+        }
+        // Exception route scenarios
+        if (definition.exceptionRoutes) {
+            for (const [from, routes] of definition.exceptionRoutes) {
+                for (const route of routes) {
+                    const label = route.errorClass?.name ?? 'error';
+                    scenarios.push({
+                        name: `step_error_${from}_${label}_to_${route.target}`,
+                        kind: 'error',
+                        steps: [
+                            `given flow in ${from}`,
+                            `when error matching ${label} is thrown`,
+                            `then flow transitions to ${route.target} via on_step_error`,
+                        ],
+                    });
+                }
+            }
+        }
+        // Guard rejection scenarios
+        for (const t of definition.transitions) {
+            if (t.type === 'external' && t.guard) {
+                const errorTarget = definition.errorTransitions.get(t.from);
+                scenarios.push({
+                    name: `guard_reject_${t.from}_${t.guard.name}`,
+                    kind: 'guard_rejection',
+                    steps: [
+                        `given flow in ${t.from}`,
+                        `when guard ${t.guard.name} rejects ${definition.maxGuardRetries} times`,
+                        errorTarget
+                            ? `then flow transitions to ${errorTarget} via error`
+                            : `then flow enters TERMINAL_ERROR`,
+                    ],
+                });
+            }
+        }
+        // Timeout scenarios
+        for (const t of definition.transitions) {
+            if (t.timeout != null) {
+                scenarios.push({
+                    name: `timeout_${t.from}`,
+                    kind: 'timeout',
+                    steps: [
+                        `given flow in ${t.from}`,
+                        `when per-state timeout of ${t.timeout}ms expires`,
+                        `then flow completes as EXPIRED`,
+                    ],
+                });
+            }
         }
         return { scenarios };
     }

package/dist/cjs/testing/types.d.ts

@@ -1,5 +1,7 @@
+export type ScenarioKind = 'happy' | 'error' | 'guard_rejection' | 'timeout';
 export interface FlowScenario {
     name: string;
+    kind: ScenarioKind;
     steps: string[];
 }
 export interface FlowTestPlan {

package/dist/esm/api/types.d.ts

@@ -36,16 +36,35 @@ export interface GenerationPlugin<I, O> extends FlowPlugin {
 /** Documentation plugin — generates string documentation. */
 export interface DocumentationPlugin<I> extends GenerationPlugin<I, string> {
 }
+/** Describes where in a flow definition a finding is located. */
+export type FindingLocation = {
+    type: 'transition';
+    fromState: string;
+    toState: string;
+} | {
+    type: 'state';
+    state: string;
+} | {
+    type: 'data';
+    dataKey: string;
+} | {
+    type: 'flow';
+};
+/** A single analysis finding. */
+export interface FindingEntry {
+    pluginId: string;
+    severity: string;
+    message: string;
+    location?: FindingLocation;
+}
 /** Plugin report — collects analysis findings. */
 export declare class PluginReport {
     private entries;
     add(pluginId: string, severity: string, message: string): void;
     warn(pluginId: string, message: string): void;
     error(pluginId: string, message: string): void;
+    warnAt(pluginId: string, message: string, location: FindingLocation): void;
+    errorAt(pluginId: string, message: string, location: FindingLocation): void;
     asText(): string;
-    findings(): {
-        pluginId: string;
-        severity: string;
-        message: string;
-    }[];
+    findings(): FindingEntry[];
 }

package/dist/esm/api/types.js

@@ -10,10 +10,29 @@ export class PluginReport {
     error(pluginId, message) {
         this.add(pluginId, 'ERROR', message);
     }
+    warnAt(pluginId, message, location) {
+        this.entries.push({ pluginId, severity: 'WARN', message, location });
+    }
+    errorAt(pluginId, message, location) {
+        this.entries.push({ pluginId, severity: 'ERROR', message, location });
+    }
     asText() {
         if (this.entries.length === 0)
             return 'No findings.';
-        return this.entries.map(e => `[${e.severity}] ${e.pluginId}: ${e.message}`).join('\n');
+        return this.entries.map(e => {
+            let text = `[${e.severity}] ${e.pluginId}: ${e.message}`;
+            if (e.location)
+                text += ` @ ${formatLocation(e.location)}`;
+            return text;
+        }).join('\n');
     }
     findings() { return [...this.entries]; }
 }
+function formatLocation(loc) {
+    switch (loc.type) {
+        case 'transition': return `transition(${loc.fromState} -> ${loc.toState})`;
+        case 'state': return `state(${loc.state})`;
+        case 'data': return `data(${loc.dataKey})`;
+        case 'flow': return 'flow';
+    }
+}

package/dist/esm/index.d.ts

@@ -1,5 +1,5 @@
 export { PluginReport } from './api/types.js';
-export type { PluginKind, PluginDescriptor, FlowPlugin, AnalysisPlugin, StorePlugin, EnginePlugin, RuntimeAdapterPlugin, GenerationPlugin, DocumentationPlugin as DocumentationPluginSPI, } from './api/types.js';
+export type { FindingLocation, FindingEntry, PluginKind, PluginDescriptor, FlowPlugin, AnalysisPlugin, StorePlugin, EnginePlugin, RuntimeAdapterPlugin, GenerationPlugin, DocumentationPlugin as DocumentationPluginSPI, } from './api/types.js';
 export { PluginRegistry } from './api/plugin-registry.js';
 export { AuditStorePlugin } from './audit/audit-store-plugin.js';
 export { AuditingFlowStore } from './audit/auditing-flow-store.js';
@@ -32,5 +32,5 @@ export { allDefaultPolicies } from './lint/default-flow-policies.js';
 export type { FlowPolicy } from './lint/types.js';
 export { ScenarioTestPlugin } from './testing/scenario-test-plugin.js';
 export { ScenarioGenerationPlugin } from './testing/scenario-generation-plugin.js';
-export type { FlowScenario, FlowTestPlan } from './testing/types.js';
+export type { FlowScenario, FlowTestPlan, ScenarioKind } from './testing/types.js';
 export { GuaranteedSubflowValidator } from './subflow/guaranteed-subflow-validator.js';

package/dist/esm/lint/default-flow-policies.js

@@ -1,7 +1,7 @@
 function warnTerminalWithOutgoing(def, report) {
     for (const state of def.terminalStates) {
         if (def.transitionsFrom(state).length > 0) {
-            report.warn('policy/terminal-outgoing', `terminal state ${state} has outgoing transitions`);
+            report.warnAt('policy/terminal-outgoing', `terminal state ${state} has outgoing transitions`, { type: 'state', state });
         }
     }
 }
@@ -9,7 +9,7 @@ function warnTooManyExternals(def, report) {
     for (const state of def.allStates()) {
         const externals = def.transitionsFrom(state).filter(t => t.type === 'external');
         if (externals.length > 3) {
-            report.warn('policy/external-count', `state ${state} has ${externals.length} external transitions`);
+            report.warnAt('policy/external-count', `state ${state} has ${externals.length} external transitions`, { type: 'state', state });
         }
     }
 }
@@ -18,13 +18,13 @@ function warnDeadProducedData(def, report) {
         return;
     const dead = def.dataFlowGraph.deadData();
     for (const key of dead) {
-        report.warn('policy/dead-data', `produced but never consumed: ${key}`);
+        report.warnAt('policy/dead-data', `produced but never consumed: ${key}`, { type: 'data', dataKey: key });
     }
 }
 function warnOverwideProcessors(def, report) {
     for (const t of def.transitions) {
         if (t.processor && t.processor.produces.length > 3) {
-            report.warn('policy/overwide-processor', `${t.processor.name} produces ${t.processor.produces.length} types; consider splitting it`);
+            report.warnAt('policy/overwide-processor', `${t.processor.name} produces ${t.processor.produces.length} types; consider splitting it`, { type: 'transition', fromState: t.from, toState: t.to });
         }
     }
 }

package/dist/esm/testing/scenario-test-plugin.d.ts

@@ -2,6 +2,7 @@ import type { FlowDefinition } from '@unlaxer/tramli';
 import type { FlowTestPlan } from './types.js';
 /**
  * Generates BDD-style test scenarios from a flow definition.
+ * Covers happy paths, error transitions, guard rejections, and timeout expiry.
  */
 export declare class ScenarioTestPlugin {
     generate<S extends string>(definition: FlowDefinition<S>): FlowTestPlan;

package/dist/esm/testing/scenario-test-plugin.js

@@ -1,9 +1,11 @@
 /**
  * Generates BDD-style test scenarios from a flow definition.
+ * Covers happy paths, error transitions, guard rejections, and timeout expiry.
  */
 export class ScenarioTestPlugin {
     generate(definition) {
         const scenarios = [];
+        // Happy path scenarios from transitions
         for (const t of definition.transitions) {
             const steps = [];
             steps.push(`given flow in ${t.from}`);
@@ -17,7 +19,67 @@ export class ScenarioTestPlugin {
                 steps.push(`when branch ${t.branch.name} selects a route`);
             }
             steps.push(`then flow reaches ${t.to}`);
-            scenarios.push({ name: `${t.from}_to_${t.to}`, steps });
+            scenarios.push({ name: `${t.from}_to_${t.to}`, kind: 'happy', steps });
+        }
+        // Error path scenarios from errorTransitions
+        for (const [from, to] of definition.errorTransitions) {
+            scenarios.push({
+                name: `error_${from}_to_${to}`,
+                kind: 'error',
+                steps: [
+                    `given flow in ${from}`,
+                    `when processor throws an error`,
+                    `then flow transitions to ${to} via on_error`,
+                ],
+            });
+        }
+        // Exception route scenarios
+        if (definition.exceptionRoutes) {
+            for (const [from, routes] of definition.exceptionRoutes) {
+                for (const route of routes) {
+                    const label = route.errorClass?.name ?? 'error';
+                    scenarios.push({
+                        name: `step_error_${from}_${label}_to_${route.target}`,
+                        kind: 'error',
+                        steps: [
+                            `given flow in ${from}`,
+                            `when error matching ${label} is thrown`,
+                            `then flow transitions to ${route.target} via on_step_error`,
+                        ],
+                    });
+                }
+            }
+        }
+        // Guard rejection scenarios
+        for (const t of definition.transitions) {
+            if (t.type === 'external' && t.guard) {
+                const errorTarget = definition.errorTransitions.get(t.from);
+                scenarios.push({
+                    name: `guard_reject_${t.from}_${t.guard.name}`,
+                    kind: 'guard_rejection',
+                    steps: [
+                        `given flow in ${t.from}`,
+                        `when guard ${t.guard.name} rejects ${definition.maxGuardRetries} times`,
+                        errorTarget
+                            ? `then flow transitions to ${errorTarget} via error`
+                            : `then flow enters TERMINAL_ERROR`,
+                    ],
+                });
+            }
+        }
+        // Timeout scenarios
+        for (const t of definition.transitions) {
+            if (t.timeout != null) {
+                scenarios.push({
+                    name: `timeout_${t.from}`,
+                    kind: 'timeout',
+                    steps: [
+                        `given flow in ${t.from}`,
+                        `when per-state timeout of ${t.timeout}ms expires`,
+                        `then flow completes as EXPIRED`,
+                    ],
+                });
+            }
         }
         return { scenarios };
     }

package/dist/esm/testing/types.d.ts

@@ -1,5 +1,7 @@
+export type ScenarioKind = 'happy' | 'error' | 'guard_rejection' | 'timeout';
 export interface FlowScenario {
     name: string;
+    kind: ScenarioKind;
     steps: string[];
 }
 export interface FlowTestPlan {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlaxer/tramli-plugins",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Plugin pack for tramli — audit, eventstore, observability, resume, idempotency, hierarchy, diagram, docs, lint, testing, subflow",
   "type": "module",
   "exports": {