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

package/README.md

@@ -39,7 +39,7 @@
   - [Configure Rules](#configure-rules)
   - [Define Exceptions](#define-exceptions)
   - [Exclude Flows](#exclude-flows)
-  - [Scan Modes](#scan-modes)
+  - [Scan Options](#scan-options)
 - **[Installation](#installation)**
   - [Distributions](#distributions)
   - [CICD Templates](#cicd-templates)
@@ -270,6 +270,10 @@ Auto-Layout automatically arranges and aligns Flow elements, keeping the canvas
 **Rule ID:** `missing-auto-layout`
 **Class Name:** _[AutoLayout](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/AutoLayout.ts)_
 **Severity:** 🔵 *Note*
+
+#### System (subcategory)
+
+System rules are a subset of Layout rules that detect structural issues normally prevented by the Flow Builder UI. See [System Rules Documentation](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/docs/system-rules.md) for the full list.
 <!-- END GENERATED_RULES -->
 
 ---
@@ -281,20 +285,26 @@ It is recommend to configure and define:
 - The severity of violating any specific rule.
 - Expressions used for rules, such as REGEX patterns and comparison operators.
 - Any known exceptions that should be ignored during scanning.
+- (Optional) Implement filters based on a severity **threshold** or **rule categories**.
+
+Most distributions automatically load configuration from: 
+- `.flow-scanner.yml`  
+- `.flow-scanner.json`  
+- `package.json` → `"flowScanner"` key
 
 ```json
 {
   "rules": {
-    // Your rule configurations
+    // rule customizations (severity, expression, enabled, ...)
   },
   "exceptions": {
-    // Your defined exceptions
-  }
+    // flow → rule → result suppressions
+  },
+  "threshold": "error",                    // only consider errors
+  "categories": ["problem", "layout"]  // only run rules from these categories
 }
 ```
 
-Most Lightning Flow Scanner distributions automatically resolve configurations from `.flow-scanner.yml`, `.flow-scanner.json`, or `package.json` → `flowScanner`.
-
 ### Configure Rules
 
 By default, all default rules are executed. You can customize individual rules and override the rules to be executed without having to specify every rule. Below is a breakdown of the available attributes of rule configuration:
@@ -315,7 +325,7 @@ By default, all default rules are executed. You can customize individual rules a
 
 #### Configure Severity
 
-When the severity is not provided it will be `warning` by default. Other available values for severity are `error` and `note`. Configure the severity per rule as demonstrated below:
+Available values for severity are `error`, `warning` and `note`. If no severity is provided, a default value is applied. Configure the severity per rule as demonstrated below:
 
 ```json
 {
@@ -444,7 +454,19 @@ Exclude specific flows by their unique API names, regardless of their location.
 
 **Environment compatibility**: works in **all environments** including Node.js and browser/web distributions, as it operates on parsed flow data rather than file system paths.
 
-### Scan Modes
+### Scan Options
+
+#### Severity Threshold
+Only report on violations at or above a chosen severity level:
+```json
+{ "threshold": "error" }
+```
+
+#### Filter by category
+Restrict the scan to specific categories of rules:
+```json
+{ "categories": ["problem", "layout"] }
+```
 
 #### Beta Mode
 
@@ -469,9 +491,10 @@ By default, Lightning Flow Scanner runs **all** default rules and merges any cus
 |----------------------------------------------------------------|-----------------------------------------------|---------------------------------------------------------------------------------------------------------|
 | **[Salesforce CLI Plugin](https://www.npmjs.com/package/lightning-flow-scanner)** | Local development, scratch orgs, CI/CD        | `sf plugins install lightning-flow-scanner`                                                             |
 | **[VS Code Extension](https://open-vsx.org/extension/ForceConfigControl/lightning-flow-scanner-vsx)** | Real-time scanning inside VS Code             | `code --install-extension ForceConfigControl.lightning-flow-scanner-vsx`                               |
-| **[Salesforce App (Managed Package)](https://github.com/Flow-Scanner/lightning-flow-scanner-app)** | Run scans directly inside a Salesforce org  | `sf package install --package 04tgK0000008CLlQAM` |
+| **[Salesforce App](https://github.com/Flow-Scanner/lightning-flow-scanner-app)** | Run scans directly inside a Salesforce org  | `sf package install --package 04tgK0000008CLlQAM` |
 | **[GitHub Action](https://github.com/marketplace/actions/lightning-flow-scan)** | Native PR checks        | `uses: Flow-Scanner/lightning-flow-scanner@main` |
 | **[Core Library](https://www.npmjs.com/package/@flow-scanner/lightning-flow-scanner-core)** (Node.js + Browser) | Custom tools, scripts, extensions, web apps   | `npm install -g @flow-scanner/lightning-flow-scanner-core`                                                 |
+| **[Regex Scanner](https://www.npmjs.com/package/@flow-scanner/regex-scanner)** |  Regex-based scanning   | `npm install -g @flow-scanner/regex-scanner`   
 
 **Privacy:** Zero user data collected. All processing is client-side. → See our [Security Policy](https://github.com/Flow-Scanner/lightning-flow-scanner?tab=security-ov-file).
 
@@ -628,7 +651,7 @@ For more on Programmatic API, types, and advanced usage of `@flow-scanner/lightn
 6. Deploy Demo Flows (Optional):
 
    ```bash
-   cd example-flows && sf project deploy start
+   sf project deploy start
    ```
 
    Navigate to the [Demo Readme](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/example-flows/README.md) for full details

package/index.d.ts

@@ -1,5 +1,6 @@
 import type { IRuleDefinition } from "./main/interfaces/IRuleDefinition";
-import type { IRulesConfig } from "./main/interfaces/IRulesConfig";
+import type { IRulesConfig, RuleCategory, Severity, Threshold } from "./main/interfaces/IRulesConfig";
+import { SEVERITY_ORDER, meetsThreshold, countThresholdViolations, filterByThreshold } from "./main/interfaces/IRulesConfig";
 import type { FlatViolation } from "./main/models/FlatViolation";
 import { Compiler } from "./main/libs/Compiler";
 import { exportDetails } from "./main/libs/ExportDetails";
@@ -22,5 +23,5 @@ import { Violation } from "./main/models/Violation";
 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 };
+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, SEVERITY_ORDER, meetsThreshold, countThresholdViolations, filterByThreshold, };
+export type { FlatViolation, IRuleDefinition, IRulesConfig, RuleCategory, Severity, Threshold, NodeIconConfig, DiagramOptions, VariableIconConfig };

package/index.js

@@ -52,12 +52,19 @@ _export(exports, {
     get RuleResult () {
         return _RuleResult.RuleResult;
     },
+    get // Threshold utilities
+    SEVERITY_ORDER () {
+        return _IRulesConfig.SEVERITY_ORDER;
+    },
     get ScanResult () {
         return _ScanResult.ScanResult;
     },
     get Violation () {
         return _Violation.Violation;
     },
+    get countThresholdViolations () {
+        return _IRulesConfig.countThresholdViolations;
+    },
     get exportDetails () {
         return _ExportDetails.exportDetails;
     },
@@ -67,12 +74,18 @@ _export(exports, {
     get exportSarif () {
         return _ExportSarif.exportSarif;
     },
+    get filterByThreshold () {
+        return _IRulesConfig.filterByThreshold;
+    },
     get fix () {
         return _FixFlows.fix;
     },
     get getRules () {
         return _GetRuleDefinitions.getRules;
     },
+    get meetsThreshold () {
+        return _IRulesConfig.meetsThreshold;
+    },
     get parse () {
         return _ParseFlows.parse;
     },
@@ -80,6 +93,7 @@ _export(exports, {
         return _ScanFlows.scan;
     }
 });
+const _IRulesConfig = require("./main/interfaces/IRulesConfig");
 const _Compiler = require("./main/libs/Compiler");
 const _ExportDetails = require("./main/libs/ExportDetails");
 const _ExportSarif = require("./main/libs/ExportSarif");

package/main/config/RuleRegistry.js

@@ -34,6 +34,7 @@ const _UnsafeRunningContext = require("../rules/UnsafeRunningContext");
 const _UnusedVariable = require("../rules/UnusedVariable");
 const _MissingMetadataDescription = require("../rules/MissingMetadataDescription");
 const _MissingRecordTriggerFilter = require("../rules/MissingRecordTriggerFilter");
+const _MissingStartReference = require("../rules/MissingStartReference");
 const _TransformInsteadOfLoop = require("../rules/TransformInsteadOfLoop");
 const _RecordIdAsString = require("../rules/RecordIdAsString");
 function _define_property(obj, key, value) {
@@ -201,6 +202,7 @@ registry.register("unsafe-running-context", _UnsafeRunningContext.UnsafeRunningC
 registry.register("unused-variable", _UnusedVariable.UnusedVariable, "UnusedVariable");
 registry.register("missing-metadata-description", _MissingMetadataDescription.MissingMetadataDescription, "MissingMetadataDescription", true);
 registry.register("missing-record-trigger-filter", _MissingRecordTriggerFilter.MissingRecordTriggerFilter, "MissingFilterRecordTrigger", true);
+registry.register("missing-start-reference", _MissingStartReference.MissingStartReference, "MissingStartReference", true);
 registry.register("transform-instead-of-loop", _TransformInsteadOfLoop.TransformInsteadOfLoop, "TransformInsteadOfLoop", true);
 registry.register("record-id-as-string", _RecordIdAsString.RecordIdAsString, "RecordIdAsString", true);
 registry.register("hardcoded-secret", _HardcodedSecret.HardcodedSecret, "HardcodedSecret", true);

package/main/interfaces/IRuleDefinition.d.ts

@@ -1,6 +1,7 @@
 import { Flow, RuleResult } from "../internals/internals";
 export interface IRuleDefinition {
     ruleId: string;
+    category?: 'problem' | 'suggestion' | 'layout' | 'system';
     description: string;
     summary: string;
     docRefs: Array<{

package/main/interfaces/IRulesConfig.d.ts

@@ -4,12 +4,45 @@ export declare enum DetailLevel {
     ENRICHED = "enriched",
     SIMPLE = "simple"
 }
+export type RuleCategory = 'problem' | 'suggestion' | 'layout';
+export type Severity = 'error' | 'warning' | 'note';
+export type Threshold = Severity | 'never';
+/** Severity levels ordered from most to least severe */
+export declare const SEVERITY_ORDER: Severity[];
 export interface IRulesConfig {
     betaMode?: boolean;
     betamode?: boolean;
+    systemRules?: boolean;
+    categories?: RuleCategory[];
+    threshold?: Threshold;
     detailLevel?: 'enriched' | 'simple' | DetailLevel;
     exceptions?: IExceptions;
     rules?: IRuleOptions;
     ruleMode?: "merged" | "isolated";
     ignoreFlows?: string[];
 }
+/**
+ * Check if a severity meets or exceeds the threshold.
+ * @param severity - The severity to check
+ * @param threshold - The threshold to compare against
+ * @returns true if severity >= threshold (more severe or equal)
+ */
+export declare function meetsThreshold(severity: string | undefined, threshold: Threshold): boolean;
+/**
+ * Count violations that meet or exceed the threshold.
+ * @param results - Array of results with severity property
+ * @param threshold - The threshold to compare against
+ * @returns Number of violations meeting the threshold
+ */
+export declare function countThresholdViolations(results: Array<{
+    severity?: string;
+}>, threshold: Threshold): number;
+/**
+ * Filter results to only include those meeting the threshold.
+ * @param results - Array of results with severity property
+ * @param threshold - The threshold to filter by
+ * @returns Filtered array of results meeting the threshold ('never' returns all)
+ */
+export declare function filterByThreshold<T extends {
+    severity?: string;
+}>(results: T[], threshold: Threshold): T[];

package/main/interfaces/IRulesConfig.js

@@ -2,10 +2,27 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
-Object.defineProperty(exports, "DetailLevel", {
-    enumerable: true,
-    get: function() {
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get DetailLevel () {
         return DetailLevel;
+    },
+    get SEVERITY_ORDER () {
+        return SEVERITY_ORDER;
+    },
+    get countThresholdViolations () {
+        return countThresholdViolations;
+    },
+    get filterByThreshold () {
+        return filterByThreshold;
+    },
+    get meetsThreshold () {
+        return meetsThreshold;
     }
 });
 var DetailLevel = /*#__PURE__*/ function(DetailLevel) {
@@ -13,3 +30,24 @@ var DetailLevel = /*#__PURE__*/ function(DetailLevel) {
     DetailLevel["SIMPLE"] = "simple";
     return DetailLevel;
 }({});
+const SEVERITY_ORDER = [
+    'error',
+    'warning',
+    'note'
+];
+function meetsThreshold(severity, threshold) {
+    if (threshold === 'never') return false;
+    const sev = severity || 'warning';
+    const sevIndex = SEVERITY_ORDER.indexOf(sev);
+    const thresholdIndex = SEVERITY_ORDER.indexOf(threshold);
+    // Lower index = more severe, so severity meets threshold if sevIndex <= thresholdIndex
+    return sevIndex >= 0 && sevIndex <= thresholdIndex;
+}
+function countThresholdViolations(results, threshold) {
+    if (threshold === 'never') return 0;
+    return results.filter((r)=>meetsThreshold(r.severity, threshold)).length;
+}
+function filterByThreshold(results, threshold) {
+    if (threshold === 'never') return results;
+    return results.filter((r)=>meetsThreshold(r.severity, threshold));
+}

package/main/libs/FixFlows.d.ts

@@ -1,3 +1,7 @@
 import * as core from "../internals/internals";
 export declare function fix(results: core.ScanResult[]): core.ScanResult[];
+/**
+ * @deprecated Use fix() instead which modifies flows in place.
+ * Kept for backward compatibility.
+ */
 export declare function FixFlows(flow: core.Flow, ruleResults: core.RuleResult[]): core.Flow;

package/main/libs/FixFlows.js

@@ -17,7 +17,6 @@ _export(exports, {
     }
 });
 const _internals = /*#__PURE__*/ _interop_require_wildcard(require("../internals/internals"));
-const _BuildFlow = require("./BuildFlow");
 function _getRequireWildcardCache(nodeInterop) {
     if (typeof WeakMap !== "function") return null;
     var cacheBabelInterop = new WeakMap();
@@ -63,45 +62,105 @@ function fix(results) {
     const newResults = [];
     for (const result of results){
         if (!result.ruleResults || result.ruleResults.length === 0) continue;
-        const fixables = result.ruleResults.filter((r)=>r.ruleName === "UnusedVariable" && r.occurs || r.ruleName === "UnconnectedElement" && r.occurs);
+        const fixables = result.ruleResults.filter((r)=>r.ruleName === "UnusedVariable" && r.occurs || r.ruleName === "UnconnectedElement" && r.occurs || r.ruleName === "AutoLayout" && 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);
+        // Handle AutoLayout fix separately (modifies metadata, not elements)
+        const autoLayoutFix = fixables.find((r)=>r.ruleName === "AutoLayout");
+        if (autoLayoutFix) {
+            applyAutoLayoutFix(result.flow);
         }
+        // Handle element-based fixes (UnusedVariable, UnconnectedElement)
+        // These modify xmldata in place to preserve element order and formatting
+        const elementFixables = fixables.filter((r)=>r.ruleName !== "AutoLayout");
+        if (elementFixables.length > 0) {
+            applyElementFixes(result.flow, elementFixables);
+        }
+        newResults.push(result);
     }
     return newResults;
 }
-function FixFlows(flow, ruleResults) {
-    var _unusedVariableRes_details, _unconnectedElementsRes_details, _flow_elements;
+function applyAutoLayoutFix(flow) {
+    if (!flow.xmldata) return;
+    // Ensure processMetadataValues is an array
+    if (!flow.xmldata.processMetadataValues) {
+        flow.xmldata.processMetadataValues = [];
+    } else if (!Array.isArray(flow.xmldata.processMetadataValues)) {
+        flow.xmldata.processMetadataValues = [
+            flow.xmldata.processMetadataValues
+        ];
+    }
+    // Find existing CanvasMode entry
+    const canvasModeIndex = flow.xmldata.processMetadataValues.findIndex((mdv)=>mdv.name === "CanvasMode");
+    const autoLayoutValue = {
+        name: "CanvasMode",
+        value: {
+            stringValue: "AUTO_LAYOUT_CANVAS"
+        }
+    };
+    if (canvasModeIndex >= 0) {
+        // Update existing entry
+        flow.xmldata.processMetadataValues[canvasModeIndex] = autoLayoutValue;
+    } else {
+        // Add new entry
+        flow.xmldata.processMetadataValues.push(autoLayoutValue);
+    }
+    // Update the flow's processMetadataValues property
+    flow.processMetadataValues = flow.xmldata.processMetadataValues;
+}
+/**
+ * Apply element-based fixes (UnusedVariable, UnconnectedElement) by modifying xmldata in place.
+ * This preserves element order and formatting from the original file.
+ */ function applyElementFixes(flow, ruleResults) {
+    var _unusedVariableRes_details, _unconnectedElementsRes_details;
+    if (!flow.xmldata) return;
     const unusedVariableRes = ruleResults.find((r)=>r.ruleName === "UnusedVariable");
     var _unusedVariableRes_details_map;
     const unusedVariableNames = new Set((_unusedVariableRes_details_map = unusedVariableRes === null || unusedVariableRes === void 0 ? void 0 : (_unusedVariableRes_details = unusedVariableRes.details) === null || _unusedVariableRes_details === void 0 ? void 0 : _unusedVariableRes_details.map((d)=>d.name)) !== null && _unusedVariableRes_details_map !== void 0 ? _unusedVariableRes_details_map : []);
     const unconnectedElementsRes = ruleResults.find((r)=>r.ruleName === "UnconnectedElement");
     var _unconnectedElementsRes_details_map;
     const unconnectedElementNames = new Set((_unconnectedElementsRes_details_map = unconnectedElementsRes === null || unconnectedElementsRes === void 0 ? void 0 : (_unconnectedElementsRes_details = unconnectedElementsRes.details) === null || _unconnectedElementsRes_details === void 0 ? void 0 : _unconnectedElementsRes_details.map((d)=>d.name)) !== null && _unconnectedElementsRes_details_map !== void 0 ? _unconnectedElementsRes_details_map : []);
-    var _flow_elements_filter;
-    const nodesToKeep = (_flow_elements_filter = (_flow_elements = flow.elements) === null || _flow_elements === void 0 ? void 0 : _flow_elements.filter((node)=>{
-        switch(node.metaType){
-            case "attribute":
-            case "resource":
-                return true;
-            case "node":
-                {
-                    const nodeElement = node;
-                    return !unconnectedElementNames.has(nodeElement.name);
-                }
-            case "variable":
-                {
-                    const nodeVar = node;
-                    return !unusedVariableNames.has(nodeVar.name);
-                }
-            default:
-                return false;
+    // Remove unused variables from xmldata
+    if (unusedVariableNames.size > 0) {
+        for (const varTag of _internals.Flow.VARIABLE_TAGS){
+            removeElementsByName(flow.xmldata, varTag, unusedVariableNames);
+        }
+    }
+    // Remove unconnected elements from xmldata
+    if (unconnectedElementNames.size > 0) {
+        for (const nodeTag of _internals.Flow.NODE_TAGS){
+            removeElementsByName(flow.xmldata, nodeTag, unconnectedElementNames);
+        }
+    }
+    // Update the flow's elements array to match the modified xmldata
+    flow.preProcessNodes();
+}
+/**
+ * Remove elements from xmldata by name.
+ * Handles both single element and array cases.
+ */ function removeElementsByName(xmldata, tagName, namesToRemove) {
+    const elements = xmldata[tagName];
+    if (!elements) return;
+    if (Array.isArray(elements)) {
+        const filtered = elements.filter((el)=>!namesToRemove.has(el === null || el === void 0 ? void 0 : el.name));
+        if (filtered.length === 0) {
+            delete xmldata[tagName];
+        } else if (filtered.length === 1) {
+            // Keep as single element if only one remains (matches original format)
+            xmldata[tagName] = filtered[0];
+        } else {
+            xmldata[tagName] = filtered;
         }
-    })) !== null && _flow_elements_filter !== void 0 ? _flow_elements_filter : [];
-    const xmldata = (0, _BuildFlow.BuildFlow)(nodesToKeep);
-    return new _internals.Flow(flow.fsPath, xmldata);
+    } else if (typeof elements === 'object' && elements !== null) {
+        // Single element case
+        if (namesToRemove.has(elements.name)) {
+            delete xmldata[tagName];
+        }
+    }
+}
+function FixFlows(flow, ruleResults) {
+    // Create a shallow clone of xmldata to avoid modifying the original
+    const clonedXmldata = JSON.parse(JSON.stringify(flow.xmldata));
+    const clonedFlow = new _internals.Flow(flow.fsPath, clonedXmldata);
+    applyElementFixes(clonedFlow, ruleResults);
+    return clonedFlow;
 }

package/main/libs/GetRuleDefinitions.js

@@ -19,6 +19,8 @@ _export(exports, {
 const _RuleRegistry = require("../config/RuleRegistry");
 function GetRuleDefinitions(ruleConfig, options) {
     const includeBeta = (options === null || options === void 0 ? void 0 : options.betaMode) === true || (options === null || options === void 0 ? void 0 : options.betamode) === true;
+    const includeSystem = (options === null || options === void 0 ? void 0 : options.systemRules) !== false; // defaults to true
+    const categories = options === null || options === void 0 ? void 0 : options.categories; // undefined means all categories
     const rulesMode = (options === null || options === void 0 ? void 0 : options.ruleMode) || "merged";
     const selectedRules = [];
     const ruleIds = _RuleRegistry.ruleRegistry.getAllRuleIds(includeBeta);
@@ -31,6 +33,10 @@ function GetRuleDefinitions(ruleConfig, options) {
             const config = ruleConfig.get(key);
             if ((config === null || config === void 0 ? void 0 : config.enabled) === false) continue;
             const rule = _RuleRegistry.ruleRegistry.createInstance(entry.ruleId); // Always use ruleId to instantiate
+            // Skip system rules if disabled
+            if (rule.category === 'system' && !includeSystem) continue;
+            // Skip rules not in selected categories (if categories filter is specified)
+            if (!isCategoryIncluded(rule.category, categories, includeSystem)) continue;
             if (config === null || config === void 0 ? void 0 : config.severity) {
                 rule.severity = config.severity;
             }
@@ -41,6 +47,10 @@ function GetRuleDefinitions(ruleConfig, options) {
     // MERGED MODE (default)
     for (const ruleId of ruleIds){
         const rule = _RuleRegistry.ruleRegistry.createInstance(ruleId);
+        // Skip system rules if disabled
+        if (rule.category === 'system' && !includeSystem) continue;
+        // Skip rules not in selected categories (if categories filter is specified)
+        if (!isCategoryIncluded(rule.category, categories, includeSystem)) continue;
         var _ruleConfig_get;
         // Try to find config by ruleId first, then fall back to legacy name
         const config = (_ruleConfig_get = ruleConfig === null || ruleConfig === void 0 ? void 0 : ruleConfig.get(rule.ruleId)) !== null && _ruleConfig_get !== void 0 ? _ruleConfig_get : ruleConfig === null || ruleConfig === void 0 ? void 0 : ruleConfig.get(rule.name) // rule.name is the legacy camelCase name (e.g. "ActionCallsInLoop")
@@ -53,6 +63,26 @@ function GetRuleDefinitions(ruleConfig, options) {
     }
     return selectedRules;
 }
+/**
+ * Check if a rule's category should be included based on the categories filter.
+ * - If no categories filter is specified, all categories are included
+ * - System rules are handled separately via includeSystem flag
+ * - Rules with matching category are included
+ * - Category matching is case-insensitive
+ */ function isCategoryIncluded(ruleCategory, categories, includeSystem) {
+    // System category is controlled by systemRules flag, not categories filter
+    if (ruleCategory === 'system') {
+        return includeSystem;
+    }
+    // If no categories filter specified, include all non-system categories
+    if (!categories || categories.length === 0) {
+        return true;
+    }
+    // Normalize categories to lowercase for case-insensitive matching
+    const normalizedCategories = categories.map((c)=>c.toLowerCase());
+    // Check if rule's category is in the allowed list (case-insensitive)
+    return normalizedCategories.includes(ruleCategory === null || ruleCategory === void 0 ? void 0 : ruleCategory.toLowerCase());
+}
 function getRules(ruleNames, options) {
     return _RuleRegistry.ruleRegistry.getRulesByNames(ruleNames, options);
 }

package/main/models/Flow.d.ts

@@ -66,4 +66,5 @@ export declare class Flow {
     private findStart;
     toXMLString(): string;
     private generateDoc;
+    private hasXsiAttributes;
 }

package/main/models/Flow.js

@@ -259,16 +259,42 @@ let Flow = class Flow {
         };
         const builder = new _fastxmlparser.XMLBuilder(builderOptions);
         const xmldataWithNs = _object_spread({}, this.xmldata);
+        // Always ensure the base xmlns is present
         if (!xmldataWithNs["@_xmlns"]) {
             xmldataWithNs["@_xmlns"] = flowXmlNamespace;
         }
-        if (!xmldataWithNs["@_xmlns:xsi"]) {
+        // Only add xmlns:xsi if the content actually uses xsi: attributes
+        // Don't add it unconditionally to avoid unnecessary diffs
+        if (!xmldataWithNs["@_xmlns:xsi"] && this.hasXsiAttributes(xmldataWithNs)) {
             xmldataWithNs["@_xmlns:xsi"] = "http://www.w3.org/2001/XMLSchema-instance";
         }
         const rootObj = {
             Flow: xmldataWithNs
         };
-        return builder.build(rootObj);
+        const xmlContent = builder.build(rootObj);
+        // Add XML declaration if not present
+        const xmlDeclaration = '<?xml version="1.0" encoding="UTF-8"?>\n';
+        if (!xmlContent.startsWith('<?xml')) {
+            return xmlDeclaration + xmlContent;
+        }
+        return xmlContent;
+    }
+    hasXsiAttributes(obj) {
+        if (obj === null || obj === undefined) {
+            return false;
+        }
+        if (typeof obj !== 'object') {
+            return false;
+        }
+        for (const key of Object.keys(obj)){
+            if (key.includes(':xsi') || key.includes('xsi:')) {
+                return true;
+            }
+            if (this.hasXsiAttributes(obj[key])) {
+                return true;
+            }
+        }
+        return false;
     }
     constructor(path, data){
         // Flow elements (excludes legacy start nodes)

package/main/models/FlowGraph.d.ts

@@ -8,6 +8,7 @@ import { FlowNode } from "./FlowNode";
 export declare class FlowGraph {
     private nodeMap;
     private reachableFromStart;
+    private normalReachableFromStart;
     private elementsInLoop;
     private faultConnectors;
     private normalConnectors;
@@ -35,6 +36,11 @@ export declare class FlowGraph {
      * This reuses the existing IDDFS traversal logic!
      */
     private computeReachability;
+    /**
+     * Compute which elements are reachable from start using ONLY normal connectors (not fault connectors).
+     * Elements that are reachable overall but NOT reachable via normal connectors are part of fault handling.
+     */
+    private computeNormalReachability;
     /**
      * Use Compiler to compute which elements are inside loops.
      * Calls Compiler.traverseFlow() for each loop with endElementName.
@@ -51,6 +57,11 @@ export declare class FlowGraph {
     getAllNextElements(elementName: string): string[];
     getPreviousElements(elementName: string): string[];
     getNode(elementName: string): FlowNode | undefined;
+    /**
+     * Check if an element is part of fault handling flow.
+     * An element is part of fault handling if it's only reachable through fault paths
+     * (i.e., reachable overall but NOT reachable via normal connectors from START).
+     */
     isPartOfFaultHandling(elementName: string): boolean;
     getLoopNodes(): FlowNode[];
     forEachReachable(callback: (node: FlowNode) => void): void;

package/main/models/FlowGraph.js

@@ -110,6 +110,15 @@ let FlowGraph = class FlowGraph {
         }, this.nodeMap, this.allConnectors);
     }
     /**
+   * Compute which elements are reachable from start using ONLY normal connectors (not fault connectors).
+   * Elements that are reachable overall but NOT reachable via normal connectors are part of fault handling.
+   */ computeNormalReachability(startReference) {
+        const compiler = new _Compiler.Compiler();
+        compiler.traverseFlow(startReference, (element)=>{
+            this.normalReachableFromStart.add(element.name);
+        }, this.nodeMap, this.normalConnectors);
+    }
+    /**
    * Use Compiler to compute which elements are inside loops.
    * Calls Compiler.traverseFlow() for each loop with endElementName.
    */ computeLoopBoundaries() {
@@ -167,13 +176,13 @@ let FlowGraph = class FlowGraph {
     getNode(elementName) {
         return this.nodeMap.get(elementName);
     }
-    isPartOfFaultHandling(elementName) {
-        const previous = this.getPreviousElements(elementName);
-        return previous.some((prev)=>{
-            const faultTargets = this.faultConnectors.get(prev);
-            var _faultTargets_has;
-            return (_faultTargets_has = faultTargets === null || faultTargets === void 0 ? void 0 : faultTargets.has(elementName)) !== null && _faultTargets_has !== void 0 ? _faultTargets_has : false;
-        });
+    /**
+   * Check if an element is part of fault handling flow.
+   * An element is part of fault handling if it's only reachable through fault paths
+   * (i.e., reachable overall but NOT reachable via normal connectors from START).
+   */ isPartOfFaultHandling(elementName) {
+        // Element is part of fault handling if it's reachable but NOT reachable via normal paths
+        return this.reachableFromStart.has(elementName) && !this.normalReachableFromStart.has(elementName);
     }
     getLoopNodes() {
         return Array.from(this.nodeMap.values()).filter((n)=>n.subtype === "loops");
@@ -508,6 +517,7 @@ let FlowGraph = class FlowGraph {
         _define_property(this, "nodeMap", new Map());
         // Pre-computed sets for common queries (built using Compiler)
         _define_property(this, "reachableFromStart", new Set());
+        _define_property(this, "normalReachableFromStart", new Set()); // Elements reachable via normal (non-fault) connectors only
         _define_property(this, "elementsInLoop", new Map()); // element -> loop name
         // Connector metadata (extracted during node processing)
         _define_property(this, "faultConnectors", new Map());
@@ -527,6 +537,7 @@ let FlowGraph = class FlowGraph {
         this.computeLoopBoundaries();
         if (startReference) {
             this.computeReachability(startReference);
+            this.computeNormalReachability(startReference);
         }
     }
 };

package/main/models/RuleCommon.d.ts

@@ -1,7 +1,7 @@
 import { RuleInfo } from "./RuleInfo";
 import * as core from "../internals/internals";
 export declare abstract class RuleCommon {
-    category?: 'problem' | 'suggestion' | 'layout';
+    category?: 'problem' | 'suggestion' | 'layout' | 'system';
     description: string;
     summary: string;
     docRefs: Array<{

package/main/models/RuleInfo.d.ts

@@ -29,9 +29,8 @@ export declare class RuleInfo {
     label: string;
     /**
      * The category for the rule.
-     * 'problem' | 'suggestion' | 'layout'
      */
-    category: 'problem' | 'suggestion' | 'layout';
+    category: 'problem' | 'suggestion' | 'layout' | 'system';
     /**
      * Stable public identifier used for config, suppression, and reporting.
      */

package/main/models/RuleInfo.js

@@ -38,7 +38,6 @@ let RuleInfo = class RuleInfo {
    */ _define_property(this, "label", void 0);
         /**
    * The category for the rule.
-   * 'problem' | 'suggestion' | 'layout'
    */ _define_property(this, "category", void 0);
         /**
    * Stable public identifier used for config, suppression, and reporting.

package/main/rules/MissingRecordTriggerFilter.js

@@ -66,11 +66,13 @@ let MissingRecordTriggerFilter = class MissingRecordTriggerFilter extends _RuleC
         }
         // Check if the flow has filters or entry conditions at the flow level
         const filters = this.getStartProperty(flow, 'filters');
+        const filterFormula = this.getStartProperty(flow, 'filterFormula');
         const hasFilters = !!filters;
+        const hasFilterFormula = !!filterFormula;
         const scheduledPaths = (_flow_xmldata = flow.xmldata) === null || _flow_xmldata === void 0 ? void 0 : (_flow_xmldata_start = _flow_xmldata.start) === null || _flow_xmldata_start === void 0 ? void 0 : _flow_xmldata_start.scheduledPaths;
         const hasScheduledPaths = !!scheduledPaths;
-        // If no filters or scheduled paths (which have their own conditions), flag as violation
-        if (!hasFilters && !hasScheduledPaths) {
+        // If no filters, formula conditions, or scheduled paths (which have their own conditions), flag as violation
+        if (!hasFilters && !hasFilterFormula && !hasScheduledPaths) {
             violations.push(new _internals.Violation(new _internals.FlowAttribute(triggerType, "triggerType", "autolaunched && triggerType")));
         }
         return violations;

package/main/rules/MissingStartReference.d.ts

@@ -0,0 +1,7 @@
+import * as core from "../internals/internals";
+import { RuleCommon } from "../models/RuleCommon";
+import { IRuleDefinition } from "../internals/internals";
+export declare class MissingStartReference extends RuleCommon implements IRuleDefinition {
+    constructor();
+    protected check(flow: core.Flow, _options: object | undefined, _suppressions: Set<string>): core.Violation[];
+}

package/main/rules/MissingStartReference.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "MissingStartReference", {
+    enumerable: true,
+    get: function() {
+        return MissingStartReference;
+    }
+});
+const _internals = /*#__PURE__*/ _interop_require_wildcard(require("../internals/internals"));
+const _RuleCommon = require("../models/RuleCommon");
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+let MissingStartReference = class MissingStartReference extends _RuleCommon.RuleCommon {
+    check(flow, _options, _suppressions) {
+        const violations = [];
+        if (!flow.startNode) {
+            violations.push(new _internals.Violation(new _internals.FlowAttribute("undefined", "startNode", "startNode")));
+        }
+        return violations;
+    }
+    constructor(){
+        super({
+            ruleId: "missing-start-reference",
+            category: "system",
+            name: "MissingStartReference",
+            label: "Missing Start Reference",
+            description: "When a flow has no start reference.",
+            summary: "Ensure flow has a start reference node",
+            supportedTypes: _internals.FlowType.allTypes(),
+            docRefs: []
+        }, {
+            severity: "error"
+        });
+    }
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flow-scanner/lightning-flow-scanner-core",
   "description": "A lightweight engine for Flow metadata in Node.js, and browser environments. Assess and enhance Salesforce Flow automations for best practices, security, governor limits, and performance issues.",
-  "version": "6.17.2",
+  "version": "6.18.0",
   "main": "index.js",
   "exports": {
     ".": {