@synergenius/flow-weaver 0.2.0

package/dist/diff/impact.js

@@ -0,0 +1,119 @@
+/**
+ * Impact assessment utilities for workflow diffs.
+ */
+/** Impact level descriptions */
+export const IMPACT_DESCRIPTIONS = {
+    CRITICAL: 'Workflow API changed - consumers must update',
+    BREAKING: 'Internal structure changed - may break dependent workflows',
+    MINOR: 'Additions or non-breaking modifications',
+    COSMETIC: 'No semantic changes',
+};
+/** Impact level colors for CLI/UI */
+export const IMPACT_COLORS = {
+    CRITICAL: 'red',
+    BREAKING: 'yellow',
+    MINOR: 'blue',
+    COSMETIC: 'gray',
+};
+/**
+ * Get detailed impact reasons from a diff
+ */
+export function getImpactReasons(diff) {
+    const reasons = [];
+    if (diff.identical) {
+        reasons.push('Workflows are semantically identical');
+        return reasons;
+    }
+    // CRITICAL reasons
+    if (diff.startPorts.removed.length > 0) {
+        reasons.push(`Removed ${diff.startPorts.removed.length} workflow input port(s): ${diff.startPorts.removed.map(p => p.name).join(', ')}`);
+    }
+    if (diff.exitPorts.removed.length > 0) {
+        reasons.push(`Removed ${diff.exitPorts.removed.length} workflow output port(s): ${diff.exitPorts.removed.map(p => p.name).join(', ')}`);
+    }
+    // BREAKING reasons
+    if (diff.summary.nodeTypesRemoved > 0) {
+        const removed = diff.nodeTypes.filter(nt => nt.changeType === 'REMOVED');
+        reasons.push(`Removed ${removed.length} node type(s): ${removed.map(nt => nt.name).join(', ')}`);
+    }
+    if (diff.summary.instancesRemoved > 0) {
+        const removed = diff.instances.filter(i => i.changeType === 'REMOVED');
+        reasons.push(`Removed ${removed.length} instance(s): ${removed.map(i => i.id).join(', ')}`);
+    }
+    if (diff.summary.connectionsRemoved > 0) {
+        reasons.push(`Removed ${diff.summary.connectionsRemoved} connection(s)`);
+    }
+    // Check for breaking port changes
+    for (const nt of diff.nodeTypes) {
+        const removedInputs = nt.changes.inputs?.filter(p => p.type === 'REMOVED') ?? [];
+        const removedOutputs = nt.changes.outputs?.filter(p => p.type === 'REMOVED') ?? [];
+        if (removedInputs.length > 0) {
+            reasons.push(`Node type '${nt.name}' removed input port(s): ${removedInputs.map(p => p.portName).join(', ')}`);
+        }
+        if (removedOutputs.length > 0) {
+            reasons.push(`Node type '${nt.name}' removed output port(s): ${removedOutputs.map(p => p.portName).join(', ')}`);
+        }
+    }
+    // MINOR reasons
+    if (diff.summary.nodeTypesAdded > 0) {
+        const added = diff.nodeTypes.filter(nt => nt.changeType === 'ADDED');
+        reasons.push(`Added ${added.length} node type(s): ${added.map(nt => nt.name).join(', ')}`);
+    }
+    if (diff.summary.instancesAdded > 0) {
+        const added = diff.instances.filter(i => i.changeType === 'ADDED');
+        reasons.push(`Added ${added.length} instance(s): ${added.map(i => i.id).join(', ')}`);
+    }
+    if (diff.summary.connectionsAdded > 0) {
+        reasons.push(`Added ${diff.summary.connectionsAdded} connection(s)`);
+    }
+    if (diff.startPorts.added.length > 0) {
+        reasons.push(`Added workflow input port(s): ${diff.startPorts.added.map(p => p.name).join(', ')}`);
+    }
+    if (diff.exitPorts.added.length > 0) {
+        reasons.push(`Added workflow output port(s): ${diff.exitPorts.added.map(p => p.name).join(', ')}`);
+    }
+    // Modified reasons
+    if (diff.summary.nodeTypesModified > 0) {
+        const modified = diff.nodeTypes.filter(nt => nt.changeType === 'MODIFIED');
+        reasons.push(`Modified ${modified.length} node type(s): ${modified.map(nt => nt.name).join(', ')}`);
+    }
+    if (diff.summary.instancesModified > 0) {
+        const modified = diff.instances.filter(i => i.changeType === 'MODIFIED');
+        reasons.push(`Modified ${modified.length} instance(s): ${modified.map(i => i.id).join(', ')}`);
+    }
+    if (diff.scopes.length > 0) {
+        const added = diff.scopes.filter(s => s.changeType === 'ADDED').map(s => s.name);
+        const removed = diff.scopes.filter(s => s.changeType === 'REMOVED').map(s => s.name);
+        const modified = diff.scopes.filter(s => s.changeType === 'MODIFIED').map(s => s.name);
+        if (added.length > 0)
+            reasons.push(`Added scope(s): ${added.join(', ')}`);
+        if (removed.length > 0)
+            reasons.push(`Removed scope(s): ${removed.join(', ')}`);
+        if (modified.length > 0)
+            reasons.push(`Modified scope(s): ${modified.join(', ')}`);
+    }
+    return reasons;
+}
+/**
+ * Check if a diff has breaking changes
+ */
+export function hasBreakingChanges(diff) {
+    return diff.impact === 'CRITICAL' || diff.impact === 'BREAKING';
+}
+/**
+ * Get changed node types grouped by change type
+ */
+export function getNodeTypeChanges(diff) {
+    return {
+        added: diff.nodeTypes.filter(nt => nt.changeType === 'ADDED'),
+        removed: diff.nodeTypes.filter(nt => nt.changeType === 'REMOVED'),
+        modified: diff.nodeTypes.filter(nt => nt.changeType === 'MODIFIED'),
+    };
+}
+/**
+ * Get critical connections (to/from Start/Exit)
+ */
+export function getCriticalConnections(diff) {
+    return diff.connections.filter(c => c.from.node === 'Start' || c.to.node === 'Exit');
+}
+//# sourceMappingURL=impact.js.map

package/dist/diff/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Semantic diff module for workflow comparison.
+ * @module diff
+ */
+export * from './types.js';
+export { WorkflowDiffer } from './WorkflowDiffer.js';
+export { IMPACT_DESCRIPTIONS, IMPACT_COLORS, getImpactReasons, hasBreakingChanges, getNodeTypeChanges, getCriticalConnections, } from './impact.js';
+export { formatDiff } from './formatDiff.js';
+export type { TDiffFormat } from './formatDiff.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/diff/index.js

@@ -0,0 +1,9 @@
+/**
+ * Semantic diff module for workflow comparison.
+ * @module diff
+ */
+export * from './types.js';
+export { WorkflowDiffer } from './WorkflowDiffer.js';
+export { IMPACT_DESCRIPTIONS, IMPACT_COLORS, getImpactReasons, hasBreakingChanges, getNodeTypeChanges, getCriticalConnections, } from './impact.js';
+export { formatDiff } from './formatDiff.js';
+//# sourceMappingURL=index.js.map

package/dist/diff/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Semantic diff types for workflow comparison.
+ * Compares semantic fields, ignores visual/metadata fields.
+ */
+import type { TPortDefinition, TPortConfig, TExecuteWhen, TBranchingStrategy } from '../ast/types.js';
+/** Impact level of a change */
+export type TImpactLevel = 'CRITICAL' | 'BREAKING' | 'MINOR' | 'COSMETIC';
+/** Change operation type */
+export type TChangeType = 'ADDED' | 'REMOVED' | 'MODIFIED';
+/** Base change record */
+export interface TChange<T = unknown> {
+    type: TChangeType;
+    before?: T;
+    after?: T;
+}
+/** Port definition change */
+export interface TPortChange extends TChange<TPortDefinition> {
+    portName: string;
+    direction: 'INPUT' | 'OUTPUT';
+}
+/** Node type semantic diff */
+export interface TNodeTypeDiff {
+    name: string;
+    changeType: TChangeType;
+    changes: {
+        functionName?: TChange<string>;
+        inputs?: TPortChange[];
+        outputs?: TPortChange[];
+        executeWhen?: TChange<TExecuteWhen>;
+        branchingStrategy?: TChange<TBranchingStrategy>;
+        isAsync?: TChange<boolean>;
+        scope?: TChange<string | undefined>;
+        variant?: TChange<string | undefined>;
+    };
+}
+/** Instance config change */
+export interface TInstanceConfigChange {
+    pullExecution?: TChange<{
+        triggerPort: string;
+    } | undefined>;
+    portConfigs?: TChange<TPortConfig[] | undefined>;
+}
+/** Instance UI change (position, label, etc.) */
+export interface TInstanceUIChange {
+    label?: TChange<string>;
+    position?: TChange<{
+        x: number;
+        y: number;
+    }>;
+    size?: TChange<{
+        width: number;
+        height: number;
+    }>;
+    minimized?: TChange<boolean>;
+}
+/** Node instance semantic diff */
+export interface TInstanceDiff {
+    id: string;
+    changeType: TChangeType;
+    changes: {
+        nodeType?: TChange<string>;
+        config?: TInstanceConfigChange;
+        parent?: TChange<{
+            id: string;
+            scope: string;
+        } | null | undefined>;
+        ui?: TInstanceUIChange;
+    };
+}
+/** Port reference for connections */
+export interface TPortRef {
+    node: string;
+    port: string;
+    scope?: string;
+}
+/** Connection semantic diff */
+export interface TConnectionDiff {
+    changeType: TChangeType;
+    from: TPortRef;
+    to: TPortRef;
+}
+/** Start/Exit port diff */
+export interface TWorkflowPortsDiff {
+    added: Array<{
+        name: string;
+        definition: TPortDefinition;
+    }>;
+    removed: Array<{
+        name: string;
+        definition: TPortDefinition;
+    }>;
+    modified: Array<{
+        name: string;
+        before: TPortDefinition;
+        after: TPortDefinition;
+    }>;
+}
+/** Scope diff */
+export interface TScopeDiff {
+    name: string;
+    changeType: TChangeType;
+    before?: string[];
+    after?: string[];
+}
+/** Complete workflow diff */
+export interface TWorkflowDiff {
+    /** Whether workflows are semantically identical */
+    identical: boolean;
+    /** Overall impact level */
+    impact: TImpactLevel;
+    /** Summary counts */
+    summary: {
+        nodeTypesAdded: number;
+        nodeTypesRemoved: number;
+        nodeTypesModified: number;
+        instancesAdded: number;
+        instancesRemoved: number;
+        instancesModified: number;
+        instancesUIModified: number;
+        connectionsAdded: number;
+        connectionsRemoved: number;
+    };
+    /** Detailed changes */
+    nodeTypes: TNodeTypeDiff[];
+    instances: TInstanceDiff[];
+    connections: TConnectionDiff[];
+    startPorts: TWorkflowPortsDiff;
+    exitPorts: TWorkflowPortsDiff;
+    scopes: TScopeDiff[];
+}
+/**
+ * Fields to compare for semantic diff.
+ * Everything else is ignored (visual, metadata, computed).
+ */
+export declare const SEMANTIC_NODE_TYPE_FIELDS: readonly ["name", "functionName", "inputs", "outputs", "executeWhen", "branchingStrategy", "isAsync", "scope", "variant"];
+export declare const SEMANTIC_INSTANCE_FIELDS: readonly ["id", "nodeType", "config.pullExecution", "config.portConfigs", "parent"];
+export declare const SEMANTIC_CONNECTION_FIELDS: readonly ["from.node", "from.port", "from.scope", "to.node", "to.port", "to.scope"];
+//# sourceMappingURL=types.d.ts.map

package/dist/diff/types.js

@@ -0,0 +1,35 @@
+/**
+ * Semantic diff types for workflow comparison.
+ * Compares semantic fields, ignores visual/metadata fields.
+ */
+/**
+ * Fields to compare for semantic diff.
+ * Everything else is ignored (visual, metadata, computed).
+ */
+export const SEMANTIC_NODE_TYPE_FIELDS = [
+    'name',
+    'functionName',
+    'inputs',
+    'outputs',
+    'executeWhen',
+    'branchingStrategy',
+    'isAsync',
+    'scope',
+    'variant',
+];
+export const SEMANTIC_INSTANCE_FIELDS = [
+    'id',
+    'nodeType',
+    'config.pullExecution',
+    'config.portConfigs',
+    'parent',
+];
+export const SEMANTIC_CONNECTION_FIELDS = [
+    'from.node',
+    'from.port',
+    'from.scope',
+    'to.node',
+    'to.port',
+    'to.scope',
+];
+//# sourceMappingURL=types.js.map

package/dist/doc-metadata/extractors/annotations.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Extractor for JSDoc annotation documentation
+ *
+ * This defines all Flow Weaver JSDoc annotations with their syntax and descriptions.
+ * The annotation names correspond to tokens defined in chevrotain-parser/tokens.ts.
+ */
+import type { TAnnotationDoc, TAnnotationModifierDoc } from '../types.js';
+/**
+ * Core Flow Weaver annotations - the primary JSDoc tags
+ */
+export declare const CORE_ANNOTATIONS: TAnnotationDoc[];
+/**
+ * Port-related annotations
+ */
+export declare const PORT_ANNOTATIONS: TAnnotationDoc[];
+/**
+ * Workflow structure annotations
+ */
+export declare const WORKFLOW_ANNOTATIONS: TAnnotationDoc[];
+/**
+ * Node type metadata annotations
+ */
+export declare const METADATA_ANNOTATIONS: TAnnotationDoc[];
+/**
+ * Standard JSDoc annotations (for completeness in IDE)
+ */
+export declare const STANDARD_ANNOTATIONS: TAnnotationDoc[];
+/**
+ * Pattern-specific annotations
+ */
+export declare const PATTERN_ANNOTATIONS: TAnnotationDoc[];
+/**
+ * Port modifiers - attributes in square brackets after port name
+ */
+export declare const PORT_MODIFIERS: TAnnotationModifierDoc[];
+/**
+ * Node instance modifiers - attributes in @node declarations
+ */
+export declare const NODE_MODIFIERS: TAnnotationModifierDoc[];
+/**
+ * All annotations combined
+ */
+export declare const ALL_ANNOTATIONS: TAnnotationDoc[];
+/**
+ * Extract all annotation documentation
+ */
+export declare function extractAnnotations(): TAnnotationDoc[];
+/**
+ * Extract port modifier documentation
+ */
+export declare function extractPortModifiers(): TAnnotationModifierDoc[];
+/**
+ * Extract node modifier documentation
+ */
+export declare function extractNodeModifiers(): TAnnotationModifierDoc[];
+//# sourceMappingURL=annotations.d.ts.map