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

package/src/main/interfaces/IExceptions.ts

@@ -1,6 +0,0 @@
-export interface IExceptions {
-  [exceptionName: string]: {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [property: string]: any[];
-  };
-}

package/src/main/interfaces/IRuleConfig.ts

@@ -1,6 +0,0 @@
-export interface IRuleConfig {
-  enabled?: boolean;
-  severity?: "error" | "warning" | "note";
-  message?: string; // Custom message to override rule description
-  messageUrl?: string; // Custom URL for documentation (auto-generated if not provided)
-}

package/src/main/interfaces/IRuleDefinition.ts

@@ -1,15 +0,0 @@
-import { Flow, RuleResult } from "../internals/internals";
-
-export interface IRuleDefinition {
-  ruleId: string;
-  description: string;
-  summary: string; // Short summary (5-10 words) shown when no custom message
-  docRefs: Array<{ label: string; path: string }>;
-  execute(flow: Flow, options?: object, suppressions?: string[]): RuleResult;
-  isConfigurable: boolean;
-  label: string;
-  name: string;
-  severity?: string;
-  supportedTypes: string[];
-  uri?: string;
-}

package/src/main/interfaces/IRuleOptions.ts

@@ -1,5 +0,0 @@
-import { IRuleConfig } from "./IRuleConfig";
-
-export interface IRuleOptions {
-  [ruleName: string]: IRuleConfig;
-}

package/src/main/interfaces/IRulesConfig.ts

@@ -1,17 +0,0 @@
-import { IExceptions } from "./IExceptions";
-import { IRuleOptions } from "./IRuleOptions";
-
-export enum DetailLevel {
-  ENRICHED = 'enriched',
-  SIMPLE = 'simple'
-}
-
-export interface IRulesConfig {
-  betaMode?: boolean;  // Toggles beta rules; defaults to false
-  betamode?: boolean;  // Use betaMode instead; to be removed
-  detailLevel?: 'enriched' | 'simple' | DetailLevel;
-  exceptions?: IExceptions;
-  rules?: IRuleOptions;
-  ruleMode?: "merged" | "isolated"; // Defaults to "merged"
-  ignoreFlows?: string[]; // Flow API names to exclude from scanning
-}

package/src/main/internals/internals.ts

@@ -1,35 +0,0 @@
-import type { IRuleDefinition } from "../interfaces/IRuleDefinition";
-import type { IRulesConfig } from "../interfaces/IRulesConfig";
-
-import { Compiler } from "../libs/Compiler";
-import { FlatViolation } from "../models/FlatViolation";
-import { Flow } from "../models/Flow";
-import { FlowAttribute } from "../models/FlowAttribute";
-import { FlowElement } from "../models/FlowElement";
-import { FlowNode } from "../models/FlowNode";
-import { FlowResource } from "../models/FlowResource";
-import { FlowType } from "../models/FlowType";
-import { FlowVariable } from "../models/FlowVariable";
-import { ParsedFlow } from "../models/ParsedFlow";
-import { RuleCommon } from "../models/RuleCommon";
-import { RuleResult } from "../models/RuleResult";
-import { ScanResult } from "../models/ScanResult";
-import { Violation } from "../models/Violation";
-
-// Used to prevent circular dependencies in Common JS
-export {
-  FlowAttribute,
-  FlowElement,
-  FlowNode,
-  FlowType,
-  FlowVariable,
-  FlowResource,
-  Flow,
-  Compiler,
-  ScanResult,
-  RuleResult,
-  Violation,
-  RuleCommon,
-  ParsedFlow,
-};
-export type { IRuleDefinition, IRulesConfig, FlatViolation };

package/src/main/libs/BuildFlow.ts

@@ -1,14 +0,0 @@
-export function BuildFlow(nodesToMerge) {
-  let res = {};
-  for (const nodeToMerge of nodesToMerge) {
-    const subtype = nodeToMerge.subtype;
-    const nodesOfType = nodesToMerge.filter((node) => subtype === node.subtype);
-    res = convertFlowNodes(res, nodesOfType, subtype);
-  }
-  return res;
-}
-
-function convertFlowNodes(obj, nodes, key) {
-  obj[key] = nodes.map((node) => node.element);
-  return obj;
-}

package/src/main/libs/Compiler.ts

@@ -1,53 +0,0 @@
-import { FlowNode } from "../models/FlowNode";
-
-export class Compiler {
-  public visitedElements: Set<string>;
-  constructor() {
-    this.visitedElements = new Set<string>();
-  }
-  traverseFlow(
-    startElementName: string,
-    visitCallback: (element: FlowNode) => void,
-    nodeMap: Map<string, FlowNode>,
-    allConnectors: Map<string, Set<string>>,
-    endElementName?: string
-  ) {
-    // Iterative Deepening Depth-First Search (IDDFS)
-    let elementsToVisit = [startElementName];
-    while (elementsToVisit.length > 0) {
-      const nextElements: string[] = [];
-      for (const elementName of elementsToVisit) {
-        if (!this.visitedElements.has(elementName)) {
-          const currentElement = nodeMap.get(elementName);
-          if (currentElement) {
-            visitCallback(currentElement);
-            this.visitedElements.add(elementName);
-            nextElements.push(...this.findNextElements(elementName, allConnectors, nodeMap, endElementName));
-          }
-        }
-      }
-      if (nextElements.length === 0) {
-        // If no more next elements
-        break; // Terminate the traversal
-      }
-      elementsToVisit = nextElements;
-    }
-  }
-  private findNextElements(
-    elementName: string,
-    allConnectors: Map<string, Set<string>>,
-    nodeMap: Map<string, FlowNode>,
-    endElementName?: string
-  ): string[] {
-    const nextElements: string[] = [];
-    const targets = allConnectors.get(elementName);
-    if (targets) {
-      for (const targetReference of targets) {
-        if (targetReference !== endElementName && nodeMap.has(targetReference)) { // Safety check for existence
-          nextElements.push(targetReference);
-        }
-      }
-    }
-    return nextElements;
-  }
-}

package/src/main/libs/ExportDetails.ts

@@ -1,58 +0,0 @@
-import { FlatViolation } from "../models/FlatViolation";
-import { ScanResult } from "../models/ScanResult";
-
-export function exportDetails(results: ScanResult[], includeDetails = false): FlatViolation[] {
-  return results.flatMap(result => {
-    const flow = result.flow;
-    const flowName = flow.name || flow.label;
-    // Prefer fsPath (resolved absolute path), fallback to uri (input path), or construct from name
-    const flowFile = flow.fsPath 
-      ? flow.fsPath.replace(/\\/g, "/") 
-      : flow.uri 
-        ? flow.uri.replace(/\\/g, "/")
-        : `${flow.name}.flow-meta.xml`;
-    
-    return result.ruleResults
-      .filter(rule => rule.occurs && rule.details?.length)
-      .flatMap(rule => rule.details.map(detail => {
-        // Base violation without details
-        const { details, ...base } = detail;
-        
-        // Build the flat violation with conditionally flattened details
-        const exported: FlatViolation = {
-          ...base,
-          flowFile,
-          flowName,
-          ruleId: rule.ruleId,
-          ruleName: rule.ruleName,
-          severity: rule.severity ?? "warning",
-          message: rule.message || rule.ruleDefinition.description,
-          messageUrl: rule.messageUrl,
-        };
-
-        // Flatten details object into top-level properties if includeDetails is true
-        if (includeDetails && details) {
-          if ('dataType' in details) {
-            exported.dataType = details.dataType as string;
-          }
-          if ('locationX' in details) {
-            exported.locationX = String(details.locationX);
-          }
-          if ('locationY' in details) {
-            exported.locationY = String(details.locationY);
-          }
-          if ('connectsTo' in details) {
-            // Join array into comma-separated string
-            exported.connectsTo = Array.isArray(details.connectsTo) 
-              ? details.connectsTo.join(', ') 
-              : String(details.connectsTo);
-          }
-          if ('expression' in details) {
-            exported.expression = details.expression as string;
-          }
-        }
-
-        return exported;
-      }));
-  });
-}

package/src/main/libs/ExportDiagram.ts

@@ -1,83 +0,0 @@
-import { Flow } from "../models/Flow";
-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 function exportDiagram(
-  parsedFlows: ParsedFlow[],
-  options: DiagramOptions = {
-    includeDetails: true,
-    includeMarkdownDocs: true,
-    collapsedDetails: true
-  }
-): string {
-  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/src/main/libs/ExportSarif.ts

@@ -1,92 +0,0 @@
-import { Flow } from "../models/Flow";
-import { ScanResult } from "../models/ScanResult";
-import { Violation } from "../models/Violation";
-
-export function exportSarif(results: ScanResult[]): string {
-  const runs = results.map((result) => {
-    const flow = result.flow;
-    const uri = getUri(flow);
-    return {
-      artifacts: [{ location: { uri }, sourceLanguage: "xml" }],
-      results: result.ruleResults
-        .filter(r => r.occurs)
-        .flatMap(r => r.details.map(d => ({
-          level: mapSeverity(r.severity),
-          locations: [{
-            physicalLocation: {
-              artifactLocation: { index: 0, uri },
-              region: mapRegion(d)
-            },
-          }],
-          message: {
-            text: r.errorMessage || (r.message || r.ruleDefinition.description
-              ? `${r.message || r.ruleDefinition.description} (${d.name})`
-              : `${r.ruleId} in ${d.name}`)
-          },
-          properties: {
-            element: d.name,
-            flow: flow.name,
-            type: d.type,
-            ...d.details,
-          },
-          ruleId: r.ruleId,
-        }))),
-      tool: {
-        driver: {
-          informationUri: "https://github.com/Flow-Scanner/lightning-flow-scanner",
-          name: "Lightning Flow Scanner",
-          rules: result.ruleResults
-            .filter(r => r.occurs)
-            .map(r => ({
-              defaultConfiguration: { level: mapSeverity(r.severity) },
-              fullDescription: { text: r.message || r.ruleDefinition.description || "" },
-              id: r.ruleId,
-              shortDescription: { text: r.message || r.ruleDefinition.description || r.ruleId },
-            })),
-          version: "1.0.0",
-        },
-      },
-    };
-  });
-  return JSON.stringify({
-    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
-    runs,
-    version: "2.1.0",
-  }, null, 2);
-}
-
-function getUri(flow: Flow): string {
-  // Prefer uri (works in both browser and Node)
-  if (flow.uri) {
-    return flow.uri.replace(/\\/g, "/");
-  }
-  
-  // Node only: fsPath is only set in Node environments
-  if (flow.fsPath) {
-    const match = flow.fsPath.match(/(?:force-app|src)\/.+$/);
-    if (match) {
-      return match[0].replace(/\\/g, "/");
-    }
-    return flow.fsPath.replace(/\\/g, "/");
-  }
-  
-  return `flows/${flow.name}.flow-meta.xml`;
-}
-
-function mapRegion(detail: Violation): any {
-  // Use pre-enriched line/column from Violation (added by enrichViolationsWithLineNumbers)
-  // Fallback if somehow missing (e.g., unenriched legacy data)
-  return {
-    startColumn: detail.columnNumber ?? 1,
-    startLine: detail.lineNumber ?? 1,
-  };
-}
-
-function mapSeverity(sev: string): "error" | "note" | "warning" {
-  switch (sev?.toLowerCase()) {
-    case "info":
-    case "note": return "note";
-    case "warning": return "warning";
-    default: return "warning";
-  }
-}

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}`;
-}