@flow-scanner/lightning-flow-scanner-core 6.10.5 → 6.11.0

package/main/models/Flow.js

@@ -14,6 +14,7 @@ const _FlowMetadata = require("./FlowMetadata");
 const _FlowNode = require("./FlowNode");
 const _FlowResource = require("./FlowResource");
 const _FlowVariable = require("./FlowVariable");
+const _FlowGraph = require("./FlowGraph");
 function _define_property(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -83,7 +84,39 @@ function _object_spread(target) {
     }
     return target;
 }
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        if (enumerableOnly) {
+            symbols = symbols.filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(object, sym).enumerable;
+            });
+        }
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
 let Flow = class Flow {
+    get graph() {
+        if (!this._graph) {
+            const flowNodes = this.elements.filter((e)=>e instanceof _FlowNode.FlowNode);
+            this.startReference || (this.startReference = this.findStart());
+            this._graph = new _FlowGraph.FlowGraph(flowNodes, this.startReference, this.startNode);
+        }
+        return this._graph;
+    }
     static from(obj) {
         if (obj instanceof Flow) {
             return obj;
@@ -96,14 +129,17 @@ let Flow = class Flow {
         return flow;
     }
     preProcessNodes() {
-        this.label = this.xmldata.label;
+        if (!this.xmldata) {
+            return;
+        }
+        // Extract top-level attributes
+        this.label = this.xmldata.label || "";
         this.interviewLabel = this.xmldata.interviewLabel;
-        this.processType = this.xmldata.processType;
+        this.processType = this.xmldata.processType || "AutoLaunchedFlow";
+        this.type = this.processType;
         this.processMetadataValues = this.xmldata.processMetadataValues;
         this.startElementReference = this.xmldata.startElementReference;
-        this.start = this.xmldata.start;
-        this.status = this.xmldata.status;
-        this.type = this.xmldata.processType;
+        this.status = this.xmldata.status || "Draft";
         this.triggerOrder = this.xmldata.triggerOrder;
         const allNodes = [];
         for(const nodeType in this.xmldata){
@@ -112,129 +148,182 @@ let Flow = class Flow {
                 continue;
             }
             const data = this.xmldata[nodeType];
-            if (Flow.ATTRIBUTE_TAGS.includes(nodeType)) {
-                if (Array.isArray(data)) {
-                    for (const node of data){
-                        allNodes.push(new _FlowMetadata.FlowMetadata(node.name, nodeType, node));
-                    }
-                } else {
-                    allNodes.push(new _FlowMetadata.FlowMetadata(data.name, nodeType, data));
+            // Handle start nodes separately - store in startNode property
+            if (nodeType === "start") {
+                if (Array.isArray(data) && data.length > 0) {
+                    this.startNode = new _FlowNode.FlowNode(data[0].name || "start", "start", data[0]);
+                } else if (!Array.isArray(data)) {
+                    this.startNode = new _FlowNode.FlowNode(data.name || "start", "start", data);
                 }
+                continue;
+            }
+            // Process other node types
+            if (Flow.ATTRIBUTE_TAGS.includes(nodeType)) {
+                this.processNodeType(data, nodeType, allNodes, _FlowMetadata.FlowMetadata);
             } else if (Flow.VARIABLE_TAGS.includes(nodeType)) {
-                if (Array.isArray(data)) {
-                    for (const node of data){
-                        allNodes.push(new _FlowVariable.FlowVariable(node.name, nodeType, node));
-                    }
-                } else {
-                    allNodes.push(new _FlowVariable.FlowVariable(data.name, nodeType, data));
-                }
+                this.processNodeType(data, nodeType, allNodes, _FlowVariable.FlowVariable);
             } else if (Flow.NODE_TAGS.includes(nodeType)) {
-                if (Array.isArray(data)) {
-                    for (const node of data){
-                        allNodes.push(new _FlowNode.FlowNode(node.name, nodeType, node));
-                    }
-                } else {
-                    allNodes.push(new _FlowNode.FlowNode(data.name, nodeType, data));
-                }
+                this.processNodeType(data, nodeType, allNodes, _FlowNode.FlowNode);
             } else if (Flow.RESOURCE_TAGS.includes(nodeType)) {
-                if (Array.isArray(data)) {
-                    for (const node of data){
-                        allNodes.push(new _FlowResource.FlowResource(node.name, nodeType, node));
-                    }
-                } else {
-                    allNodes.push(new _FlowResource.FlowResource(data.name, nodeType, data));
-                }
+                this.processNodeType(data, nodeType, allNodes, _FlowResource.FlowResource);
             }
         }
         this.elements = allNodes;
         this.startReference = this.findStart();
+        // Build the connectivity graph
+        const flowNodes = allNodes.filter((e)=>e instanceof _FlowNode.FlowNode);
+        this._graph = new _FlowGraph.FlowGraph(flowNodes, this.startReference, this.startNode);
+    }
+    visualize(format = 'mermaid', options = {}) {
+        if (format === 'mermaid') {
+            var _this_xmldata, _this_startNode_element, _this_startNode, _this_startNode_element1, _this_startNode1;
+            return this.graph.toMermaid(_object_spread_props(_object_spread({}, options), {
+                flowMetadata: {
+                    label: this.label,
+                    processType: this.processType,
+                    status: this.status,
+                    description: (_this_xmldata = this.xmldata) === null || _this_xmldata === void 0 ? void 0 : _this_xmldata.description,
+                    triggerType: (_this_startNode = this.startNode) === null || _this_startNode === void 0 ? void 0 : (_this_startNode_element = _this_startNode.element) === null || _this_startNode_element === void 0 ? void 0 : _this_startNode_element['triggerType'],
+                    object: (_this_startNode1 = this.startNode) === null || _this_startNode1 === void 0 ? void 0 : (_this_startNode_element1 = _this_startNode1.element) === null || _this_startNode_element1 === void 0 ? void 0 : _this_startNode_element1['object']
+                }
+            }));
+        } else if (format === 'plantuml') {
+            return this.graph.toPlantUML();
+        }
+        throw new Error('Unsupported format');
+    }
+    processNodeType(data, nodeType, allNodes, NodeClass) {
+        if (Array.isArray(data)) {
+            for (const node of data){
+                allNodes.push(new NodeClass(node.name, nodeType, node));
+            }
+        } else {
+            allNodes.push(new NodeClass(data.name, nodeType, data));
+        }
+    }
+    /**
+   * Find the name of the first element to execute.
+   * Priority order:
+   * 1. startElementReference (newer flows, direct XML attribute)
+   * 2. Start node connector (older flows, points to first element)
+   * 3. Start node scheduledPaths (async flows)
+   */ findStart() {
+        var _this_startNode;
+        // Priority 1: Explicit startElementReference
+        if (this.startElementReference) {
+            return this.startElementReference;
+        }
+        // Priority 2: Start node with regular connector
+        if (this.startNode && this.startNode.connectors && this.startNode.connectors.length > 0) {
+            const connector = this.startNode.connectors[0];
+            if (connector.reference) {
+                return connector.reference;
+            }
+        }
+        // Priority 3: Start node with scheduledPaths (async flows)
+        if ((_this_startNode = this.startNode) === null || _this_startNode === void 0 ? void 0 : _this_startNode.element) {
+            const scheduledPaths = this.startNode.element['scheduledPaths'];
+            if (scheduledPaths) {
+                var _paths_;
+                const paths = Array.isArray(scheduledPaths) ? scheduledPaths : [
+                    scheduledPaths
+                ];
+                if (paths.length > 0 && ((_paths_ = paths[0]) === null || _paths_ === void 0 ? void 0 : _paths_.connector)) {
+                    const targetRef = paths[0].connector.targetReference;
+                    if (targetRef) {
+                        return targetRef;
+                    }
+                }
+            }
+        }
+        // No valid start found
+        return "";
     }
     toXMLString() {
         try {
             return this.generateDoc();
         } catch (exception) {
-            console.warn(`Unable to write xml, caught an error ${exception.toString()}`);
+            const errorMsg = exception instanceof Error ? exception.message : String(exception);
+            console.warn(`Unable to write xml, caught an error: ${errorMsg}`);
             return "";
         }
     }
-    findStart() {
-        let start = "";
-        const flowElements = this.elements.filter((node)=>node instanceof _FlowNode.FlowNode);
-        if (this.startElementReference) {
-            start = this.startElementReference;
-        } else if (flowElements.find((n)=>{
-            return n.subtype === "start";
-        })) {
-            const startElement = flowElements.find((n)=>{
-                return n.subtype === "start";
-            });
-            start = startElement.connectors[0]["reference"];
-        }
-        return start;
-    }
     generateDoc() {
-        // eslint-disable-next-line sonarjs/no-clear-text-protocols
         const flowXmlNamespace = "http://soap.sforce.com/2006/04/metadata";
         const builderOptions = {
             attributeNamePrefix: "@_",
             format: true,
             ignoreAttributes: false,
             suppressBooleanAttributes: false,
-            suppressEmptyNode: false // Keep empty tags (but doesn't force self-closing in pretty)
+            suppressEmptyNode: false
         };
         const builder = new _fastxmlparser.XMLBuilder(builderOptions);
-        // Fallback: Inject xmlns as attribute if missing
         const xmldataWithNs = _object_spread({}, this.xmldata);
         if (!xmldataWithNs["@_xmlns"]) {
             xmldataWithNs["@_xmlns"] = flowXmlNamespace;
         }
-        // Optional: Add xsi if needed (often in parsed data; test has it in root)
         if (!xmldataWithNs["@_xmlns:xsi"]) {
             xmldataWithNs["@_xmlns:xsi"] = "http://www.w3.org/2001/XMLSchema-instance";
         }
-        // Build: Wrap in { Flow: ... }
         const rootObj = {
             Flow: xmldataWithNs
         };
         return builder.build(rootObj);
     }
     constructor(path, data){
-        _define_property(this, "elements", void 0);
-        _define_property(this, "fsPath", void 0); //  This is only set in Node.js environments and is the resolved absolute path. In browser environments, it stays undefined.
-        _define_property(this, "uri", void 0); // This is always set from the constructor's path parameter and represents the input path (could be relative, absolute, or virtual)
+        // Flow elements (excludes legacy start nodes)
+        _define_property(this, "elements", []);
+        // Path properties
+        _define_property(this, "fsPath", void 0); // Resolved absolute path (Node.js only)
+        _define_property(this, "uri", void 0); // Input path (could be relative, absolute, or virtual)
+        // Flow metadata
+        _define_property(this, "label", "");
         _define_property(this, "interviewLabel", void 0);
-        _define_property(this, "label", void 0);
-        _define_property(this, "name", void 0);
+        _define_property(this, "name", "unnamed");
         _define_property(this, "processMetadataValues", void 0);
-        _define_property(this, "processType", void 0);
-        _define_property(this, "root", void 0);
-        _define_property(this, "start", void 0);
-        _define_property(this, "startElementReference", void 0);
-        _define_property(this, "startReference", void 0);
-        _define_property(this, "status", void 0);
+        _define_property(this, "processType", "AutoLaunchedFlow");
+        _define_property(this, "type", ""); // Alias for processType (backward compatibility)
+        _define_property(this, "status", "");
         _define_property(this, "triggerOrder", void 0);
-        _define_property(this, "type", void 0);
+        // Start-related properties
         /**
-   * XML to JSON conversion in raw format
-   */ _define_property(this, "xmldata", void 0);
+   * @deprecated Use startNode.element instead. Kept for backward compatibility.
+   */ _define_property(this, "start", void 0);
+        /**
+   * Direct reference to first element (from XML attribute).
+   * Used in newer flows as an alternative to the start element.
+   */ _define_property(this, "startElementReference", void 0);
+        /**
+   * Computed reference to the first element to execute.
+   * This is what rules should use for traversal.
+   */ _define_property(this, "startReference", void 0);
+        /**
+   * Parsed FlowNode object of the start element.
+   * Contains trigger information and connectors.
+   * Access start element data via startNode.element
+   */ _define_property(this, "startNode", void 0);
+        _define_property(this, "_graph", void 0);
+        // Legacy/internal
+        _define_property(this, "root", void 0);
+        _define_property(this, "xmldata", void 0);
         if (path) {
-            this.uri = path; // Always set general URI from input (file path or virtual)
-            // Only resolve fsPath in Node.js environments
-            // In browser with polyfills, fsPath stays undefined
-            if (typeof process !== 'undefined' && process.cwd) {
+            this.uri = path;
+            if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
                 this.fsPath = _path.resolve(path);
             }
             let flowName = _path.basename(_path.basename(path), _path.extname(path));
             if (flowName.includes(".")) {
                 flowName = flowName.split(".")[0];
             }
-            this.name = flowName;
+            this.name = flowName || "unnamed";
         }
         if (data) {
-            const hasFlowElement = typeof data === "object" && "Flow" in data;
+            const hasFlowElement = typeof data === "object" && data !== null && "Flow" in data;
             if (hasFlowElement) {
                 this.xmldata = data.Flow;
-            } else this.xmldata = data;
+            } else {
+                this.xmldata = data;
+            }
             this.preProcessNodes();
         }
     }
@@ -276,7 +365,6 @@ let Flow = class Flow {
     "recordUpdates",
     "recordRollbacks",
     "screens",
-    "start",
     "steps",
     "subflows",
     "waits",

package/main/models/FlowGraph.d.ts

@@ -0,0 +1,85 @@
+import { FlowNode } from "./FlowNode";
+/**
+ * FlowGraph: Pre-computed connectivity cache built using Compiler.
+ * Built once during Flow.preProcessNodes() to avoid repeated traversals.
+ *
+ * Uses the existing Compiler to build the graph - no duplicate logic!
+ */
+export declare class FlowGraph {
+    private nodeMap;
+    private reachableFromStart;
+    private elementsInLoop;
+    private faultConnectors;
+    private normalConnectors;
+    private allConnectors;
+    private reverseConnectors;
+    constructor(nodes: FlowNode[], startReference?: string, startNode?: FlowNode);
+    /**
+     * Add START node connectors to the connector maps (for flows with explicit <start> element)
+     */
+    private addStartNodeConnectors;
+    /**
+     * Add START edge for newer flows that use startElementReference (no explicit <start> node)
+     */
+    private addStartEdgeFromReference;
+    /**
+     * Build node map for O(1) lookups
+     */
+    private buildNodeMaps;
+    /**
+     * Build connector maps by inspecting node connectors
+     */
+    private buildConnectorMaps;
+    /**
+     * Use Compiler to compute which elements are reachable from start.
+     * This reuses the existing IDDFS traversal logic!
+     */
+    private computeReachability;
+    /**
+     * Use Compiler to compute which elements are inside loops.
+     * Calls Compiler.traverseFlow() for each loop with endElementName.
+     */
+    private computeLoopBoundaries;
+    isReachable(elementName: string): boolean;
+    getReachableElements(): Set<string>;
+    isInLoop(elementName: string): boolean;
+    getContainingLoop(elementName: string): string | undefined;
+    getLoopElements(loopName: string): Set<string>;
+    hasFaultConnector(elementName: string): boolean;
+    getFaultTargets(elementName: string): string[];
+    getNextElements(elementName: string): string[];
+    getAllNextElements(elementName: string): string[];
+    getPreviousElements(elementName: string): string[];
+    getNode(elementName: string): FlowNode | undefined;
+    isPartOfFaultHandling(elementName: string): boolean;
+    getLoopNodes(): FlowNode[];
+    forEachReachable(callback: (node: FlowNode) => void): void;
+    /**
+     * Export the graph to Mermaid flowchart syntax with rich documentation.
+     */
+    toMermaid(options?: {
+        includeDetails?: boolean;
+        includeMarkdownDocs?: boolean;
+        collapsedDetails?: boolean;
+        flowMetadata?: any;
+    }): string;
+    private generateMermaidDiagram;
+    private generateStartNode;
+    private getNodeShape;
+    private generateEdges;
+    private findEndNodes;
+    private generateLoopSubgraphs;
+    private generateMermaidStyles;
+    private generateNodeDetailsMarkdown;
+    private nodeToMarkdownTable;
+    private prettifyValue;
+    /**
+     * Generate full markdown documentation with diagram and node details
+     */
+    private generateFullMarkdownDoc;
+    /**
+     * Export the graph to PlantUML syntax for UML-style diagrams.
+     * @returns PlantUML string.
+     */
+    toPlantUML(): string;
+}