@flow-scanner/lightning-flow-scanner-core 6.17.1 → 6.17.3

package/src/main/libs/FixFlows.ts

@@ -1,61 +0,0 @@
-import * as core from "../internals/internals";
-import { BuildFlow } from "./BuildFlow";
-
-export function fix(results: core.ScanResult[]): core.ScanResult[] {
-  const newResults: core.ScanResult[] = [];
-
-  for (const result of results) {
-    if (!result.ruleResults || result.ruleResults.length === 0) continue;
-
-    const fixables: core.RuleResult[] = result.ruleResults.filter(
-      (r) =>
-        (r.ruleName === "UnusedVariable" && r.occurs) ||
-        (r.ruleName === "UnconnectedElement" && r.occurs)
-    );
-
-    if (fixables.length === 0) continue;
-
-    const newFlow = FixFlows(result.flow, fixables);
-
-    const hasRemainingElements = newFlow.elements && newFlow.elements.length > 0;
-    if (hasRemainingElements) {
-      result.flow = newFlow;
-      newResults.push(result);
-    }
-  }
-
-  return newResults;
-}
-
-export function FixFlows(flow: core.Flow, ruleResults: core.RuleResult[]): core.Flow {
-  const unusedVariableRes = ruleResults.find((r) => r.ruleName === "UnusedVariable");
-  const unusedVariableNames = new Set(
-    unusedVariableRes?.details?.map((d) => d.name) ?? []
-  );
-
-  const unconnectedElementsRes = ruleResults.find((r) => r.ruleName === "UnconnectedElement");
-  const unconnectedElementNames = new Set(
-    unconnectedElementsRes?.details?.map((d) => d.name) ?? []
-  );
-
-  const nodesToKeep = flow.elements?.filter((node) => {
-    switch (node.metaType) {
-      case "attribute":
-      case "resource":
-        return true;
-      case "node": {
-        const nodeElement = node as core.FlowNode;
-        return !unconnectedElementNames.has(nodeElement.name);
-      }
-      case "variable": {
-        const nodeVar = node as core.FlowVariable;
-        return !unusedVariableNames.has(nodeVar.name);
-      }
-      default:
-        return false;
-    }
-  }) ?? [];
-
-  const xmldata = BuildFlow(nodesToKeep);
-  return new core.Flow(flow.fsPath, xmldata);
-}

package/src/main/libs/GetRuleDefinitions.ts

@@ -1,64 +0,0 @@
-import { IRuleConfig } from "../interfaces/IRuleConfig";
-import { IRuleDefinition } from "../interfaces/IRuleDefinition";
-import { IRulesConfig } from "../interfaces/IRulesConfig";
-import { ruleRegistry } from "../config/RuleRegistry";
-
-export function GetRuleDefinitions(
-  ruleConfig?: Map<string, unknown>,
-  options?: IRulesConfig
-): IRuleDefinition[] {
-  const includeBeta = options?.betaMode === true || options?.betamode === true;
-  const rulesMode = options?.ruleMode || "merged";
-  const selectedRules: IRuleDefinition[] = [];
-
-  const ruleIds = ruleRegistry.getAllRuleIds(includeBeta);
-
-  // ISOLATED MODE
-  if (rulesMode === "isolated" && ruleConfig && ruleConfig.size > 0) {
-    for (const key of ruleConfig.keys()) {
-      // key can now be either ruleId (new) or legacyName (old config compatibility)
-      const entry = ruleRegistry.get(key);
-      if (!entry) continue;
-
-      const config = ruleConfig.get(key) as IRuleConfig | undefined;
-      if (config?.enabled === false) continue;
-
-      const rule = ruleRegistry.createInstance(entry.ruleId);  // Always use ruleId to instantiate
-
-      if (config?.severity) {
-        rule.severity = config.severity;
-      }
-
-      selectedRules.push(rule);
-    }
-    return selectedRules;
-  }
-
-  // MERGED MODE (default)
-  for (const ruleId of ruleIds) {
-    const rule = ruleRegistry.createInstance(ruleId);
-
-    // Try to find config by ruleId first, then fall back to legacy name
-    const config = (
-      ruleConfig?.get(rule.ruleId) ??
-      ruleConfig?.get(rule.name)  // rule.name is the legacy camelCase name (e.g. "ActionCallsInLoop")
-    ) as IRuleConfig | undefined;
-
-    if (config?.enabled === false) continue;
-
-    if (config?.severity) {
-      rule.severity = config.severity;
-    }
-
-    selectedRules.push(rule);
-  }
-
-  return selectedRules;
-}
-
-export function getRules(
-  ruleNames?: string[],
-  options?: IRulesConfig
-): IRuleDefinition[] {
-  return ruleRegistry.getRulesByNames(ruleNames, options);
-}

package/src/main/libs/ParseFlows.ts

@@ -1,34 +0,0 @@
-import { XMLParser } from "fast-xml-parser";
-import { promises as fs } from "fs";
-import * as p from "path";
-
-import { Flow } from "../models/Flow";
-import { ParsedFlow } from "../models/ParsedFlow";
-
-
-export async function parse(selectedUris: string[]): Promise<ParsedFlow[]> {
-  const parseResults: ParsedFlow[] = [];
-  const parser = new XMLParser({
-    attributeNamePrefix: "@_",
-    ignoreAttributes: false,
-    // @ts-expect-error type issue
-    ignoreNameSpace: false,
-    parseTagValue: false,
-    textNodeName: "#text"
-  });
-
-  for (const uri of selectedUris) {
-    try {
-      const normalizedURI = p.normalize(uri);
-      const content = await fs.readFile(normalizedURI, "utf8");
-      const parsed = parser.parse(content);
-      const flowObj = parsed.Flow;
-      parseResults.push(new ParsedFlow(uri, new Flow(uri, flowObj)));
-    } catch (e: any) {
-      parseResults.push(
-        new ParsedFlow(uri, undefined, e.message ?? e.toString())
-      );
-    }
-  }
-  return parseResults;
-}

package/src/main/libs/RuleDocumentation.ts

@@ -1,35 +0,0 @@
-/**
- * Converts a rule label to a documentation URL anchor.
- *
- * Rules:
- * - Lowercase
- * - Spaces → hyphens
- * - Remove special characters and badges
- *
- * @param label - The rule display label (e.g., "DML Statement In A Loop")
- * @returns The anchor slug (e.g., "dml-statement-in-a-loop")
- */
-export function labelToAnchor(label: string): string {
-  return label
-    .toLowerCase()
-    .replace(/\s+/g, '-')           // Replace spaces with hyphens
-    .replace(/[^a-z0-9-]/g, '')     // Remove non-alphanumeric except hyphens
-    .replace(/-+/g, '-')            // Collapse multiple hyphens
-    .replace(/^-|-$/g, '');         // Trim leading/trailing hyphens
-}
-
-/**
- * Generates a documentation URL for a rule.
- *
- * @param label - The rule display label
- * @param customUrl - Optional custom URL override
- * @returns The documentation URL
- */
-export function getRuleDocumentationUrl(label: string, customUrl?: string): string {
-  if (customUrl) {
-    return customUrl;
-  }
-
-  const anchor = labelToAnchor(label);
-  return `https://flow-scanner.github.io/lightning-flow-scanner/#${anchor}`;
-}

package/src/main/libs/ScanFlows.ts

@@ -1,142 +0,0 @@
-import type { IRuleDefinition } from "../interfaces/IRuleDefinition";
-import {
-  Flow,
-  IRulesConfig,
-  RuleResult,
-  ScanResult,
-} from "../../main/internals/internals";
-import { DetailLevel } from "../interfaces/IRulesConfig";
-import { ParsedFlow } from "../models/ParsedFlow";
-import { enrichViolationsWithLineNumbers } from "../models/Violation";
-import { GetRuleDefinitions } from "./GetRuleDefinitions";
-import { getRuleDocumentationUrl } from "./RuleDocumentation";
-
-function getRuleConfigByIdOrName(
-  rule: IRuleDefinition,
-  rulesConfig?: Record<string, any>
-): any | undefined {
-  if (!rulesConfig) return undefined;
-  // Try ruleId first, then fall back to name
-  return rulesConfig[rule.ruleId] || rulesConfig[rule.name];
-}
-
-function getSuppressionsForRule(
-  rule: IRuleDefinition,
-  flowName: string,
-  exceptions?: Record<string, Record<string, string[]>>
-): string[] {
-  if (!exceptions?.[flowName]) return [];
-  const flowExceptions = exceptions[flowName];
-  // Try ruleId first, then fall back to name
-  const rawSuppressions = flowExceptions[rule.ruleId] || flowExceptions[rule.name];
-  // If wildcard exists, return only wildcard; otherwise return array or empty
-  return rawSuppressions?.includes("*") ? ["*"] : (rawSuppressions ?? []);
-}
-
-export function scan(parsedFlows: ParsedFlow[], ruleOptions?: IRulesConfig): ScanResult[] {
-  const flows: Flow[] = [];
-  const ignoreFlows = ruleOptions?.ignoreFlows || [];
-
-  for (const flow of parsedFlows) {
-    if (!flow.errorMessage && flow.flow) {
-      // Filter out flows whose names are in the ignore list
-      if (ignoreFlows.length > 0 && ignoreFlows.includes(flow.flow.name)) {
-        continue;
-      }
-      flows.push(flow.flow);
-    }
-  }
-  const scanResults = ScanFlows(flows, ruleOptions);
-  return scanResults;
-}
-
-export function ScanFlows(flows: Flow[], ruleOptions?: IRulesConfig): ScanResult[] {
-  const flowResults: ScanResult[] = [];
-  const rawMode = ruleOptions?.detailLevel;
-  const detailLevel =
-    typeof rawMode === 'string' && rawMode.toLowerCase() === 'simple'
-      ? DetailLevel.SIMPLE
-      : DetailLevel.ENRICHED;
-
-  let ruleMap: Map<string, object> | undefined = undefined;
-  if (ruleOptions?.rules && Object.keys(ruleOptions.rules).length > 0) {
-    ruleMap = new Map<string, object>();
-    for (const [ruleName, config] of Object.entries(ruleOptions.rules)) {
-      ruleMap.set(ruleName, config);
-    }
-  }
-
-  // This ensures default rules are loaded and merged with any custom configs
-  const selectedRules = GetRuleDefinitions(ruleMap, ruleOptions);
-
-  const flowXmlCache = new Map<string, string>();
-
-  for (const flowInput of flows) {
-    const flow = flowInput instanceof Flow ? flowInput : Flow.from(flowInput);
-    const ruleResults: RuleResult[] = [];
-
-    for (const rule of selectedRules) {
-      try {
-        if (!rule.supportedTypes.includes(flow.type)) {
-          ruleResults.push(new RuleResult(rule, []));
-          continue;
-        }
-
-        const config = getRuleConfigByIdOrName(rule, ruleOptions?.rules);
-        const suppressions = getSuppressionsForRule(rule, flow.name, ruleOptions?.exceptions);
-
-        const result =
-          config && Object.keys(config).length > 0
-            ? rule.execute(flow, config, suppressions)
-            : rule.execute(flow, undefined, suppressions);
-
-        // Apply custom message if provided in config, otherwise use summary
-        if (config && typeof config === 'object' && 'message' in config && typeof config.message === 'string') {
-          result.message = config.message;
-        } else {
-          // Use summary if available, otherwise fallback to description
-          result.message = result.ruleDefinition.summary || result.ruleDefinition.description;
-        }
-
-        // Apply custom messageUrl if provided in config, otherwise auto-generate from rule label
-        const customUrl = config && typeof config === 'object' && 'messageUrl' in config && typeof config.messageUrl === 'string'
-          ? config.messageUrl
-          : undefined;
-        result.messageUrl = getRuleDocumentationUrl(result.ruleDefinition.label, customUrl);
-
-        if (result.details.length > 0) {
-          let flowXml = flowXmlCache.get(flow.name);
-          if (!flowXml) {
-            flowXml = flow.toXMLString();
-            flowXmlCache.set(flow.name, flowXml);
-          }
-          if (flowXml) {
-            enrichViolationsWithLineNumbers(result.details, flowXml);
-          }
-        }
-
-        ruleResults.push(result);
-      } catch (error) {
-        const message = `Something went wrong while executing ${rule.name} in the Flow: ${flow.name} with error ${error}`;
-        ruleResults.push(new RuleResult(rule, [], message));
-      }
-    }
-
-    flowResults.push(new ScanResult(flow, ruleResults));
-    flowXmlCache.delete(flow.name);
-  }
-
-  flowXmlCache.clear();
-
-  if (detailLevel === DetailLevel.SIMPLE) {
-    flowResults.forEach(scanResult => {
-      scanResult.ruleResults.forEach(ruleResult => {
-        ruleResult.details.forEach(violation => {
-          delete violation.details;
-        });
-      });
-    });
-  }
-
-  return flowResults;
-}

package/src/main/models/FlatViolation.ts

@@ -1,16 +0,0 @@
-import { Violation } from "./Violation";
-
-export interface FlatViolation extends Omit<Violation, 'details'> {
-  flowFile: string;
-  flowName: string;
-  ruleId: string; // Canonical rule ID (e.g., "dml-in-loop")
-  ruleName: string; // Legacy class name (e.g., "DMLStatementInLoop")
-  severity: string;
-  message?: string; // Custom message overriding the default rule description
-  messageUrl?: string; // URL to custom documentation
-  dataType?: string;
-  locationX?: string;
-  locationY?: string;
-  connectsTo?: string;
-  expression?: string;
-}

package/src/main/models/Flow.ts

@@ -1,325 +0,0 @@
-import { XMLBuilder } from "fast-xml-parser";
-import * as p from "path";
-import { FlowElement } from "./FlowElement";
-import { FlowMetadata } from "./FlowMetadata";
-import { FlowNode } from "./FlowNode";
-import { FlowResource } from "./FlowResource";
-import { FlowVariable } from "./FlowVariable";
-import { FlowGraph } from "./FlowGraph";
-
-export class Flow {
-  /**
-   * Metadata Tags of Salesforce Flow Attributes
-   */
-  public static readonly ATTRIBUTE_TAGS = [
-    "apiVersion",
-    "areMetricsLoggedToDataCloud",
-    "description",
-    "environments",
-    "fullName",
-    "interviewLabel",
-    "isAdditionalPermissionRequiredToRun",
-    "isTemplate",
-    "label",
-    "migratedFromWorkflowRuleName",
-    "processMetadataValues",
-    "processType",
-    "runInMode",
-    "segment",
-    "startElementReference",
-    "status",
-    "timeZoneSidKey",
-    "triggerOrder"
-  ] as const;
-
-  /**
-   * Metadata Tags of Salesforce Flow Nodes
-   */
-  public static readonly NODE_TAGS = [
-    "actionCalls",
-    "apexPluginCalls",
-    "assignments",
-    "collectionProcessors",
-    "decisions",
-    "loops",
-    "orchestratedStages",
-    "recordCreates",
-    "recordDeletes",
-    "recordLookups",
-    "recordUpdates",
-    "recordRollbacks",
-    "screens",
-    "steps",
-    "subflows",
-    "waits",
-    "transforms",
-    "customErrors",
-  ] as const;
-
-  public static readonly RESOURCE_TAGS = ["textTemplates", "stages"] as const;
-  public static readonly VARIABLE_TAGS = ["choices", "constants", "dynamicChoiceSets", "formulas", "variables"] as const;
-
-  // Flow elements (excludes legacy start nodes)
-  public elements: FlowElement[] = [];
-
-  // Path properties
-  public fsPath?: string; // Resolved absolute path (Node.js only)
-  public uri?: string;    // Input path (could be relative, absolute, or virtual)
-
-  // Flow metadata
-  public label: string = "";
-  public interviewLabel?: string;
-  public name: string = "unnamed";
-  public processMetadataValues?: any;
-  public processType: string = "AutoLaunchedFlow";
-  public type: string = ""; // Alias for processType (backward compatibility)
-  public status: string = "";
-  public triggerOrder?: number;
-
-  // Start-related properties
-  /**
-   * @deprecated Use startNode.element instead. Kept for backward compatibility.
-   */
-  public start?: any;
-  
-  /**
-   * Direct reference to first element (from XML attribute).
-   * Used in newer flows as an alternative to the start element.
-   */
-  public startElementReference?: string;
-  
-  /**
-   * Computed reference to the first element to execute.
-   * This is what rules should use for traversal.
-   */
-  public startReference?: string;
-  
-  /**
-   * Parsed FlowNode object of the start element.
-   * Contains trigger information and connectors.
-   * Access start element data via startNode.element
-   */
-  public startNode?: FlowNode;
-
-  private _graph?: FlowGraph;
-
-  public get graph(): FlowGraph {
-    if (!this._graph) {
-      const flowNodes = this.elements.filter((e): e is FlowNode => e instanceof FlowNode);
-      this.startReference ||= this.findStart();
-      this._graph = new FlowGraph(flowNodes, this.startReference, this.startNode);
-    }
-    return this._graph;
-  }
-
-    // Legacy/internal
-  public root?: any;
-  public xmldata: any;
-
-  constructor(path?: string, data?: unknown) {
-    if (path) {
-      this.uri = path;
-      
-      if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
-        this.fsPath = p.resolve(path);
-      }
-      
-      let flowName = p.basename(p.basename(path), p.extname(path));
-      if (flowName.includes(".")) {
-        flowName = flowName.split(".")[0];
-      }
-      this.name = flowName || "unnamed";
-    }
-
-    if (data) {
-      const hasFlowElement = typeof data === "object" && data !== null && "Flow" in data;
-      if (hasFlowElement) {
-        this.xmldata = (data as any).Flow;
-      } else {
-        this.xmldata = data;
-      }
-      this.preProcessNodes();
-    }
-  }
-
-  public static from(obj: Partial<Flow>): Flow {
-    if (obj instanceof Flow) {
-      return obj;
-    }
-    const flow = Object.create(Flow.prototype);
-    Object.assign(flow, obj);
-    if (!flow.toXMLString) {
-      flow.toXMLString = () => '';
-    }
-    return flow;
-  }
-
-  public preProcessNodes() {
-    if (!this.xmldata) {
-      return;
-    }
-
-    // Extract top-level attributes
-    this.label = this.xmldata.label || "";
-    this.interviewLabel = this.xmldata.interviewLabel;
-    this.processType = this.xmldata.processType || "AutoLaunchedFlow";
-    this.type = this.processType;
-    this.processMetadataValues = this.xmldata.processMetadataValues;
-    this.startElementReference = this.xmldata.startElementReference;
-    this.status = this.xmldata.status || "Draft";
-    this.triggerOrder = this.xmldata.triggerOrder;
-
-    const allNodes: Array<FlowMetadata | FlowNode | FlowVariable | FlowResource> = [];
-
-    for (const nodeType in this.xmldata) {
-      // Skip xmlns and attributes
-      if (nodeType.startsWith("@_") || nodeType === "@xmlns") {
-        continue;
-      }
-
-      const data = this.xmldata[nodeType];
-
-      // Handle start nodes separately - store in startNode property
-      if (nodeType === "start") {
-        if (Array.isArray(data) && data.length > 0) {
-          this.startNode = new FlowNode(data[0].name || "start", "start", data[0]);
-        } else if (!Array.isArray(data)) {
-          this.startNode = new FlowNode(data.name || "start", "start", data);
-        }
-        continue;
-      }
-
-      // Process other node types
-      if (Flow.ATTRIBUTE_TAGS.includes(nodeType as any)) {
-        this.processNodeType(data, nodeType, allNodes, FlowMetadata);
-      } else if (Flow.VARIABLE_TAGS.includes(nodeType as any)) {
-        this.processNodeType(data, nodeType, allNodes, FlowVariable);
-      } else if (Flow.NODE_TAGS.includes(nodeType as any)) {
-        this.processNodeType(data, nodeType, allNodes, FlowNode);
-      } else if (Flow.RESOURCE_TAGS.includes(nodeType as any)) {
-        this.processNodeType(data, nodeType, allNodes, FlowResource);
-      }
-    }
-
-    this.elements = allNodes;
-    this.startReference = this.findStart();
-
-    // Build the connectivity graph
-    const flowNodes = allNodes.filter((e): e is FlowNode => e instanceof FlowNode);
-    this._graph = new FlowGraph(flowNodes, this.startReference, this.startNode);
-  }
-
-  public visualize(
-  format: 'mermaid' | 'plantuml' = 'mermaid',
-  options: {
-    includeDetails?: boolean;
-    includeMarkdownDocs?: boolean;
-    collapsedDetails?: boolean;
-  } = {}
-): string {
-  if (format === 'mermaid') {
-    return this.graph.toMermaid({
-      ...options,
-      flowMetadata: {
-        label: this.label,
-        processType: this.processType,
-        status: this.status,
-        description: this.xmldata?.description,
-        triggerType: this.startNode?.element?.['triggerType'],
-        object: this.startNode?.element?.['object'],
-      }
-    });
-  } else if (format === 'plantuml') {
-    return this.graph.toPlantUML();
-  }
-  throw new Error('Unsupported format');
-}
-  private processNodeType<T extends FlowElement>(
-    data: any,
-    nodeType: string,
-    allNodes: FlowElement[],
-    NodeClass: new (name: string, subtype: string, data: any) => T
-  ) {
-    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)
-   */
-  private findStart(): string {
-    // 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?.element) {
-      const scheduledPaths = this.startNode.element['scheduledPaths'];
-      if (scheduledPaths) {
-        const paths = Array.isArray(scheduledPaths) ? scheduledPaths : [scheduledPaths];
-        if (paths.length > 0 && paths[0]?.connector) {
-          const targetRef = paths[0].connector.targetReference;
-          if (targetRef) {
-            return targetRef;
-          }
-        }
-      }
-    }
-
-    // No valid start found
-    return "";
-  }
-
-  public toXMLString(): string {
-    try {
-      return this.generateDoc();
-    } catch (exception) {
-      const errorMsg = exception instanceof Error ? exception.message : String(exception);
-      console.warn(`Unable to write xml, caught an error: ${errorMsg}`);
-      return "";
-    }
-  }
-
-  private generateDoc(): string {
-    const flowXmlNamespace = "http://soap.sforce.com/2006/04/metadata";
-    const builderOptions = {
-      attributeNamePrefix: "@_",
-      format: true,
-      ignoreAttributes: false,
-      suppressBooleanAttributes: false,
-      suppressEmptyNode: false
-    };
-
-    const builder = new XMLBuilder(builderOptions);
-    const xmldataWithNs = { ...this.xmldata };
-
-    if (!xmldataWithNs["@_xmlns"]) {
-      xmldataWithNs["@_xmlns"] = flowXmlNamespace;
-    }
-
-    if (!xmldataWithNs["@_xmlns:xsi"]) {
-      xmldataWithNs["@_xmlns:xsi"] = "http://www.w3.org/2001/XMLSchema-instance";
-    }
-
-    const rootObj = { Flow: xmldataWithNs };
-    return builder.build(rootObj);
-  }
-}

package/src/main/models/FlowAttribute.ts

@@ -1,11 +0,0 @@
-import { MetaType } from "../enums/MetadataTypes";
-import { FlowElement } from "./FlowElement";
-
-export class FlowAttribute extends FlowElement {
-  public expression?: string;
-
-  constructor(name: string, subtype: string, expression?: string) {
-    super(MetaType.ATTRIBUTE, subtype, name);  // No element passed, or pass {} if needed
-    this.expression = expression;
-  }
-}