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

package/README.md

@@ -1,25 +1,22 @@
 <p align="center">
-  <a href="https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/LICENSE.md">
-    <img src="https://img.shields.io/github/license/Flow-Scanner/lightning-flow-scanner?style=flat-square" alt="License">
-  </a>
-  <a href="https://github.com/Flow-Scanner/lightning-flow-scanner/graphs/contributors">
-    <img src="https://img.shields.io/github/contributors/Flow-Scanner/lightning-flow-scanner.svg?style=flat-square" alt="Contributors">
+  <a href="https://github.com/Flow-Scanner/lightning-flow-scanner/stargazers">
+    <img src="https://img.shields.io/github/stars/Flow-Scanner/lightning-flow-scanner?label=Stargazers&style=flat-square" alt="GitHub stars">
   </a>
-  <a href="https://www.npmjs.com/package/@flow-scanner/lightning-flow-scanner-core">
-    <img src="https://img.shields.io/npm/v/@flow-scanner/lightning-flow-scanner-core?label=core&style=flat-square" alt="Core version">
+   <a href="https://www.npmjs.com/package/@flow-scanner/lightning-flow-scanner-core">
+    <img src="https://img.shields.io/npm/v/@flow-scanner/lightning-flow-scanner-core?label=Core&style=flat-square" alt="Core version">
   </a>
   <a href="https://www.npmjs.com/package/lightning-flow-scanner">
-    <img src="https://img.shields.io/npm/v/lightning-flow-scanner?label=cli&style=flat-square" alt="CLI version">
+    <img src="https://img.shields.io/npm/v/lightning-flow-scanner?label=CLI&style=flat-square" alt="CLI version">
   </a>
   <a href="https://open-vsx.org/extension/ForceConfigControl/lightning-flow-scanner-vsx">
-    <img src="https://img.shields.io/open-vsx/v/ForceConfigControl/lightning-flow-scanner-vsx?label=Open%20VSX&style=flat-square" alt="Open VSX">
-  </a>
-  <a href="https://github.com/Flow-Scanner/lightning-flow-scanner/stargazers">
-    <img src="https://img.shields.io/github/stars/Flow-Scanner/lightning-flow-scanner?style=flat-square" alt="GitHub stars">
+    <img src="https://img.shields.io/open-vsx/v/ForceConfigControl/lightning-flow-scanner-vsx?label=VS%20Code&style=flat-square" alt="VS Code version">
   </a>
   <a href="https://www.npmjs.com/package/lightning-flow-scanner-core">
-    <img src="https://img.shields.io/badge/downloads-510k%2B-success?style=flat-square" alt="Total Downloads">
-  </a>
+  <img src="https://img.shields.io/npm/dt/lightning-flow-scanner-core?label=Downloads%3Cv6&style=flat-square" alt="Downloads <v6">
+</a>
+<a href="https://www.npmjs.com/package/@flow-scanner/lightning-flow-scanner-core">
+  <img src="https://img.shields.io/npm/dt/@flow-scanner/lightning-flow-scanner-core?label=Downloads%3Ev6&style=flat-square" alt="Downloads >v6">
+</a>
 </p>
 
 <p align="center">
@@ -355,9 +352,15 @@ Use `lightning-flow-scanner-core` as a Node.js/browser dependency:
 import { parse, scan } from "@flow-scanner/lightning-flow-scanner-core";
 parse("flows/*.xml").then(scan);
 
-// Get SARIF output
+// Get SARIF output (e.g. for GitHub Code Scanning)
 import { parse, scan, exportSarif } from "@flow-scanner/lightning-flow-scanner-core";
-parse("flows/*.xml").then(scan).then(exportSarif);
+parse("flows/**/*.flow-meta.xml").then(scan).then(exportSarif) 
+  // .then(sarif => fs.writeFile("results.sarif", sarif))
+
+// Generate Markdown documentation with Mermaid flow diagrams
+import { parse, exportDiagram } from "@flow-scanner/lightning-flow-scanner-core";
+parse("flows/**/*.flow-meta.xml").then(exportDiagram) 
+  // .then(md => fs.writeFile("FLOW_DOCUMENTATION.md", md))
 
 // Browser Usage (Tooling API)
 const { Flow, scan } = window.lightningflowscanner;

package/index.d.ts

@@ -19,5 +19,8 @@ import { ParsedFlow } from "./main/models/ParsedFlow";
 import { RuleResult } from "./main/models/RuleResult";
 import { ScanResult } from "./main/models/ScanResult";
 import { Violation } from "./main/models/Violation";
-export { Compiler, exportDetails, exportSarif, fix, Flow, FlowAttribute, FlowElement, FlowNode, FlowResource, FlowType, FlowVariable, getRules, parse, ParsedFlow, Violation, RuleResult, scan, ScanResult, };
-export type { FlatViolation, IRuleDefinition, IRulesConfig };
+import { DEFAULT_ICONS, ASCII_ICONS, type NodeIconConfig } from "./main/config/NodeIcons";
+import { DEFAULT_VARIABLE_ICONS, ASCII_VARIABLE_ICONS, type VariableIconConfig } from "./main/config/VariableIcons";
+import { exportDiagram, type DiagramOptions } from "./main/libs/ExportDiagram";
+export { Compiler, exportDetails, exportDiagram, exportSarif, fix, Flow, FlowAttribute, FlowElement, FlowNode, FlowResource, FlowType, FlowVariable, getRules, parse, ParsedFlow, Violation, RuleResult, scan, ScanResult, DEFAULT_ICONS, ASCII_ICONS, DEFAULT_VARIABLE_ICONS, ASCII_VARIABLE_ICONS, };
+export type { FlatViolation, IRuleDefinition, IRulesConfig, NodeIconConfig, DiagramOptions, VariableIconConfig };

package/index.js

@@ -1,3 +1,4 @@
+// Updated exports in index.ts
 "use strict";
 Object.defineProperty(exports, "__esModule", {
     value: true
@@ -9,9 +10,21 @@ function _export(target, all) {
     });
 }
 _export(exports, {
+    get ASCII_ICONS () {
+        return _NodeIcons.ASCII_ICONS;
+    },
+    get ASCII_VARIABLE_ICONS () {
+        return _VariableIcons.ASCII_VARIABLE_ICONS;
+    },
     get Compiler () {
         return _Compiler.Compiler;
     },
+    get DEFAULT_ICONS () {
+        return _NodeIcons.DEFAULT_ICONS;
+    },
+    get DEFAULT_VARIABLE_ICONS () {
+        return _VariableIcons.DEFAULT_VARIABLE_ICONS;
+    },
     get Flow () {
         return _Flow.Flow;
     },
@@ -48,6 +61,9 @@ _export(exports, {
     get exportDetails () {
         return _ExportDetails.exportDetails;
     },
+    get exportDiagram () {
+        return _ExportDiagram.exportDiagram;
+    },
     get exportSarif () {
         return _ExportSarif.exportSarif;
     },
@@ -82,3 +98,6 @@ const _ParsedFlow = require("./main/models/ParsedFlow");
 const _RuleResult = require("./main/models/RuleResult");
 const _ScanResult = require("./main/models/ScanResult");
 const _Violation = require("./main/models/Violation");
+const _NodeIcons = require("./main/config/NodeIcons");
+const _VariableIcons = require("./main/config/VariableIcons");
+const _ExportDiagram = require("./main/libs/ExportDiagram");

package/main/config/NodeIcons.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Icon configuration for flow node types.
+ * Emoji are safe in UTF-8 encoded source files and will work in all modern builds.
+ * If you need ASCII fallback, use FlowNode.setIconConfig(ASCII_ICONS)
+ */
+export interface NodeIconConfig {
+    [nodeType: string]: {
+        [subtype: string]: string;
+    } | {
+        default: string;
+    };
+}
+/**
+ * Default icons using emoji (recommended for modern environments)
+ */
+export declare const DEFAULT_ICONS: NodeIconConfig;
+/**
+ * ASCII fallback icons (for environments without emoji support)
+ */
+export declare const ASCII_ICONS: NodeIconConfig;
+/**
+ * Get default icon config (can be overridden at runtime)
+ */
+export declare function getDefaultIconConfig(): NodeIconConfig;

package/main/config/NodeIcons.js

@@ -0,0 +1,122 @@
+/**
+ * Icon configuration for flow node types.
+ * Emoji are safe in UTF-8 encoded source files and will work in all modern builds.
+ * If you need ASCII fallback, use FlowNode.setIconConfig(ASCII_ICONS)
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ASCII_ICONS () {
+        return ASCII_ICONS;
+    },
+    get DEFAULT_ICONS () {
+        return DEFAULT_ICONS;
+    },
+    get getDefaultIconConfig () {
+        return getDefaultIconConfig;
+    }
+});
+const DEFAULT_ICONS = {
+    actionCalls: {
+        apex: '\u2699\uFE0F',
+        emailAlert: '\uD83D\uDCE7',
+        emailSimple: '\uD83D\uDCE7',
+        submit: '\u26A1',
+        default: '\u26A1' // HIGH VOLTAGE
+    },
+    assignments: {
+        default: '\uD83D\uDFF0' // 🟰 HEAVY EQUALS SIGN
+    },
+    collectionProcessors: {
+        FilterCollectionProcessor: '\uD83D\uDD3D',
+        SortCollectionProcessor: '\uD83D\uDD03',
+        default: '\uD83D\uDCE6' // PACKAGE
+    },
+    customErrors: {
+        default: '\uD83D\uDEAB' // PROHIBITED
+    },
+    decisions: {
+        default: '\uD83D\uDD00' // TWISTED ARROWS
+    },
+    loops: {
+        default: '\uD83D\uDD01' // REPEAT BUTTON
+    },
+    recordCreates: {
+        default: '\u2795' // PLUS
+    },
+    recordDeletes: {
+        default: '\uD83D\uDDD1\uFE0F' // WASTEBASKET
+    },
+    recordLookups: {
+        default: '\uD83D\uDD0D' // MAGNIFYING GLASS
+    },
+    recordUpdates: {
+        default: '\uD83D\uDEE0\uFE0F' // HAMMER AND WRENCH
+    },
+    screens: {
+        default: '\uD83D\uDCBB' // LAPTOP
+    },
+    subflows: {
+        default: '\uD83D\uDD17' // LINK
+    },
+    transforms: {
+        default: '\u267B\uFE0F'
+    }
+};
+const ASCII_ICONS = {
+    actionCalls: {
+        apex: '[A]',
+        emailAlert: '[E]',
+        emailSimple: '[E]',
+        submit: '[!]',
+        default: '[!]'
+    },
+    assignments: {
+        default: '[=]'
+    },
+    collectionProcessors: {
+        FilterCollectionProcessor: '[F]',
+        SortCollectionProcessor: '[S]',
+        default: '[C]'
+    },
+    customErrors: {
+        default: '[X]'
+    },
+    decisions: {
+        default: '[?]'
+    },
+    loops: {
+        default: '[L]'
+    },
+    recordCreates: {
+        default: '[+]'
+    },
+    recordDeletes: {
+        default: '[-]'
+    },
+    recordLookups: {
+        default: '[S]'
+    },
+    recordUpdates: {
+        default: '[U]'
+    },
+    screens: {
+        default: '[#]'
+    },
+    subflows: {
+        default: '[>]'
+    },
+    transforms: {
+        default: '[T]'
+    }
+};
+function getDefaultIconConfig() {
+    return DEFAULT_ICONS;
+}

package/main/config/VariableIcons.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Icon configuration for flow variable types.
+ * Includes icons for variable subtypes and boolean states.
+ */
+export interface VariableIconConfig {
+    subtypes: {
+        [subtype: string]: string;
+    };
+    boolean: {
+        true: string;
+        false: string;
+    };
+}
+/**
+ * Default icons using emoji (recommended for modern environments)
+ */
+export declare const DEFAULT_VARIABLE_ICONS: VariableIconConfig;
+/**
+ * ASCII fallback icons (for environments without emoji support)
+ */
+export declare const ASCII_VARIABLE_ICONS: VariableIconConfig;
+/**
+ * Get default variable icon config
+ */
+export declare function getDefaultVariableIconConfig(): VariableIconConfig;

package/main/config/VariableIcons.js

@@ -0,0 +1,53 @@
+/**
+ * Icon configuration for flow variable types.
+ * Includes icons for variable subtypes and boolean states.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ASCII_VARIABLE_ICONS () {
+        return ASCII_VARIABLE_ICONS;
+    },
+    get DEFAULT_VARIABLE_ICONS () {
+        return DEFAULT_VARIABLE_ICONS;
+    },
+    get getDefaultVariableIconConfig () {
+        return getDefaultVariableIconConfig;
+    }
+});
+const DEFAULT_VARIABLE_ICONS = {
+    subtypes: {
+        variables: '\uD83D\uDCCA',
+        constants: '\uD83D\uDD12',
+        formulas: '\uD83E\uDDEE',
+        choices: '\uD83D\uDCCB',
+        dynamicChoiceSets: '\uD83D\uDD04'
+    },
+    boolean: {
+        true: '\u2705',
+        false: '\u2B1C'
+    }
+};
+const ASCII_VARIABLE_ICONS = {
+    subtypes: {
+        variables: '[V]',
+        constants: '[C]',
+        formulas: '[F]',
+        choices: '[CH]',
+        dynamicChoiceSets: '[D]'
+    },
+    boolean: {
+        true: '[X]',
+        false: '[ ]'
+    }
+};
+function getDefaultVariableIconConfig() {
+    return DEFAULT_VARIABLE_ICONS;
+}

package/main/libs/Compiler.d.ts

@@ -1,8 +1,7 @@
-import { Flow } from "../models/Flow";
 import { FlowNode } from "../models/FlowNode";
 export declare class Compiler {
     visitedElements: Set<string>;
     constructor();
-    traverseFlow(flow: Flow, startElementName: string, visitCallback: (element: FlowNode) => void, endElementName?: string): void;
+    traverseFlow(startElementName: string, visitCallback: (element: FlowNode) => void, nodeMap: Map<string, FlowNode>, allConnectors: Map<string, Set<string>>, endElementName?: string): void;
     private findNextElements;
 }

package/main/libs/Compiler.js

@@ -22,7 +22,7 @@ function _define_property(obj, key, value) {
     return obj;
 }
 let Compiler = class Compiler {
-    traverseFlow(flow, startElementName, visitCallback, endElementName) {
+    traverseFlow(startElementName, visitCallback, nodeMap, allConnectors, endElementName) {
         // Iterative Deepening Depth-First Search (IDDFS)
         let elementsToVisit = [
             startElementName
@@ -31,12 +31,11 @@ let Compiler = class Compiler {
             const nextElements = [];
             for (const elementName of elementsToVisit){
                 if (!this.visitedElements.has(elementName)) {
-                    var _flow_elements;
-                    const currentElement = (_flow_elements = flow.elements) === null || _flow_elements === void 0 ? void 0 : _flow_elements.find((element)=>element.name === elementName);
+                    const currentElement = nodeMap.get(elementName);
                     if (currentElement) {
                         visitCallback(currentElement);
                         this.visitedElements.add(elementName);
-                        nextElements.push(...this.findNextElements(flow, currentElement, endElementName));
+                        nextElements.push(...this.findNextElements(elementName, allConnectors, nodeMap, endElementName));
                     }
                 }
             }
@@ -46,19 +45,14 @@ let Compiler = class Compiler {
             elementsToVisit = nextElements;
         }
     }
-    findNextElements(flow, currentElement, endElementName) {
+    findNextElements(elementName, allConnectors, nodeMap, endElementName) {
         const nextElements = [];
-        if (!currentElement.connectors || currentElement.connectors.length === 0) {
-            return nextElements;
-        }
-        for (const connector of currentElement.connectors){
-            var _connector_connectorTargetReference, _flow_elements;
-            var _connector_connectorTargetReference_targetReference;
-            const targetReference = (_connector_connectorTargetReference_targetReference = connector === null || connector === void 0 ? void 0 : (_connector_connectorTargetReference = connector.connectorTargetReference) === null || _connector_connectorTargetReference === void 0 ? void 0 : _connector_connectorTargetReference.targetReference) !== null && _connector_connectorTargetReference_targetReference !== void 0 ? _connector_connectorTargetReference_targetReference : connector.reference;
-            // Check if the reference exists in the flow elements
-            const nextElement = (_flow_elements = flow.elements) === null || _flow_elements === void 0 ? void 0 : _flow_elements.find((element)=>element.metaType === "node" && element.name === targetReference);
-            if (nextElement && nextElement.metaType === "node" && nextElement.name !== endElementName) {
-                nextElements.push(nextElement.name);
+        const targets = allConnectors.get(elementName);
+        if (targets) {
+            for (const targetReference of targets){
+                if (targetReference !== endElementName && nodeMap.has(targetReference)) {
+                    nextElements.push(targetReference);
+                }
             }
         }
         return nextElements;

package/main/libs/ExportDiagram.d.ts

@@ -0,0 +1,41 @@
+import { ParsedFlow } from "../models/ParsedFlow";
+export interface DiagramOptions {
+    includeDetails?: boolean;
+    includeMarkdownDocs?: boolean;
+    collapsedDetails?: boolean;
+}
+/**
+ * Generate Markdown documentation for parsed flows, including Mermaid diagrams for valid flows.
+ *
+ * This function can be chained after parse() to generate documentation.
+ * It filters out errored parses and only documents valid flows.
+ *
+ * @param parsedFlows Array of ParsedFlow objects from parse()
+ * @param options Visualization options for Mermaid diagrams
+ *
+ * @returns Markdown string with documentation
+ *
+ * @example
+ * ```typescript
+ * // Node.js usage
+ * import { parse, exportFlowMarkdown } from "@flow-scanner/lightning-flow-scanner-core";
+ * import fs from "fs/promises";
+ *
+ * const parsed = await parse(["flows/*.xml"]);
+ * const md = exportFlowMarkdown(parsed, {
+ *   includeDetails: true,
+ *   includeMarkdownDocs: true,
+ *   collapsedDetails: true
+ * });
+ * await fs.writeFile("flow-doc.md", md);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Chained (async/await)
+ * const md = await parse(["flows/*.xml"]).then(parsed =>
+ *   exportFlowMarkdown(parsed, { includeDetails: true })
+ * );
+ * ```
+ */
+export declare function exportDiagram(parsedFlows: ParsedFlow[], options?: DiagramOptions): string;

package/main/libs/ExportDiagram.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "exportDiagram", {
+    enumerable: true,
+    get: function() {
+        return exportDiagram;
+    }
+});
+function exportDiagram(parsedFlows, options = {
+    includeDetails: true,
+    includeMarkdownDocs: true,
+    collapsedDetails: true
+}) {
+    const validFlows = parsedFlows.filter((p)=>p.flow).map((p)=>p.flow);
+    let markdown = "# Flow Documentation\n\n";
+    if (validFlows.length === 0) {
+        markdown += "No valid flows found.\n\n";
+    }
+    for (const flow of validFlows){
+        markdown += `## ${flow.name}\n\n`;
+        const vizOptions = {
+            includeDetails: options.includeDetails,
+            includeMarkdownDocs: options.includeMarkdownDocs,
+            collapsedDetails: options.collapsedDetails
+        };
+        markdown += flow.visualize("mermaid", vizOptions) + "\n\n";
+    }
+    // Optionally add errors section if any
+    const errors = parsedFlows.filter((p)=>p.errorMessage);
+    if (errors.length > 0) {
+        markdown += "## Parse Errors\n\n";
+        for (const err of errors){
+            markdown += `- ${err.uri}: ${err.errorMessage}\n`;
+        }
+        markdown += "\n";
+    }
+    return markdown;
+}

package/main/libs/ExportSarif.js

@@ -74,7 +74,7 @@ function exportSarif(results) {
                     }))),
             tool: {
                 driver: {
-                    informationUri: "https://github.com/Flow-Scanner/lightning-flow-scanner-core",
+                    informationUri: "https://github.com/Flow-Scanner/lightning-flow-scanner",
                     name: "Lightning Flow Scanner",
                     rules: result.ruleResults.filter((r)=>r.occurs).map((r)=>({
                             defaultConfiguration: {

package/main/models/Flow.d.ts

@@ -1,4 +1,6 @@
 import { FlowElement } from "./FlowElement";
+import { FlowNode } from "./FlowNode";
+import { FlowGraph } from "./FlowGraph";
 export declare class Flow {
     /**
      * Metadata Tags of Salesforce Flow Attributes
@@ -7,32 +9,61 @@ export declare class Flow {
     /**
      * Metadata Tags of Salesforce Flow Nodes
      */
-    static readonly NODE_TAGS: readonly ["actionCalls", "apexPluginCalls", "assignments", "collectionProcessors", "decisions", "loops", "orchestratedStages", "recordCreates", "recordDeletes", "recordLookups", "recordUpdates", "recordRollbacks", "screens", "start", "steps", "subflows", "waits", "transforms", "customErrors"];
+    static readonly NODE_TAGS: readonly ["actionCalls", "apexPluginCalls", "assignments", "collectionProcessors", "decisions", "loops", "orchestratedStages", "recordCreates", "recordDeletes", "recordLookups", "recordUpdates", "recordRollbacks", "screens", "steps", "subflows", "waits", "transforms", "customErrors"];
     static readonly RESOURCE_TAGS: readonly ["textTemplates", "stages"];
     static readonly VARIABLE_TAGS: readonly ["choices", "constants", "dynamicChoiceSets", "formulas", "variables"];
-    elements?: FlowElement[];
+    elements: FlowElement[];
     fsPath?: string;
     uri?: string;
-    interviewLabel?: string;
     label: string;
-    name?: string;
+    interviewLabel?: string;
+    name: string;
     processMetadataValues?: any;
-    processType?: string;
-    root?: any;
+    processType: string;
+    type: string;
+    status: string;
+    triggerOrder?: number;
+    /**
+     * @deprecated Use startNode.element instead. Kept for backward compatibility.
+     */
     start?: any;
+    /**
+     * Direct reference to first element (from XML attribute).
+     * Used in newer flows as an alternative to the start element.
+     */
     startElementReference?: string;
+    /**
+     * Computed reference to the first element to execute.
+     * This is what rules should use for traversal.
+     */
     startReference?: string;
-    status?: string;
-    triggerOrder?: number;
-    type?: string;
     /**
-     * XML to JSON conversion in raw format
+     * Parsed FlowNode object of the start element.
+     * Contains trigger information and connectors.
+     * Access start element data via startNode.element
      */
+    startNode?: FlowNode;
+    private _graph?;
+    get graph(): FlowGraph;
+    root?: any;
     xmldata: any;
     constructor(path?: string, data?: unknown);
     static from(obj: Partial<Flow>): Flow;
     preProcessNodes(): void;
-    toXMLString(): string;
+    visualize(format?: 'mermaid' | 'plantuml', options?: {
+        includeDetails?: boolean;
+        includeMarkdownDocs?: boolean;
+        collapsedDetails?: boolean;
+    }): string;
+    private processNodeType;
+    /**
+     * 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)
+     */
     private findStart;
+    toXMLString(): string;
     private generateDoc;
 }