@flow-scanner/lightning-flow-scanner-core 6.17.3 → 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)
@@ -55,221 +55,225 @@
 
 > Want to help improve this project? See our [Contributing Guidelines](https://github.com/Flow-Scanner/lightning-flow-scanner?tab=contributing-ov-file)
 
-<!-- START GENERATED_RULES -->
-
----
-
-### Problems
-
-These rules detect anti-patterns and unsafe practices in your Flows that could break functionality, compromise security, or cause deployment failures.
-
-#### DML Statement In A Loop
-Executing DML operations (insert, update, delete) inside a loop is a high-risk anti-pattern that frequently causes governor limit exceptions. All database operations should be collected and executed once, outside the loop.
-
-**Rule ID:** `dml-in-loop`
-**Class Name:** _[DMLStatementInLoop](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/DMLStatementInLoop.ts)_
-**Severity:** 🔴 *Error*
-
-#### Hardcoded Salesforce Id
-Avoid hard-coding record IDs, as they are unique to a specific org and will not work in other environments. Instead, store IDs in variables—such as merge-field URL parameters or a **Get Records** element—to make the Flow portable, maintainable, and flexible.
-
-**Rule ID:** `hardcoded-id`
-**Class Name:** _[HardcodedId](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/HardcodedId.ts)_
-**Severity:** 🔴 *Error*
-
-#### Hardcoded Salesforce Url
-Avoid hard-coding URLs, as they may change between environments or over time. Instead, store URLs in variables or custom settings to make the Flow adaptable, maintainable, and environment-independent.
-
-**Rule ID:** `hardcoded-url`
-**Class Name:** _[HardcodedUrl](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/HardcodedUrl.ts)_
-**Severity:** 🔴 *Error*
-
-#### Hardcoded Secret ![Beta](https://img.shields.io/badge/status-beta-yellow)
-Avoid hardcoding secrets, API keys, tokens, or credentials in Flows. These should be stored securely in Named Credentials, Custom Settings, Custom Metadata, or external secret management systems.
-
-**Rule ID:** `hardcoded-secret`
-**Class Name:** _[HardcodedSecret](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/HardcodedSecret.ts)_
-**Severity:** 🔴 *Error*
-
-#### Process Builder
-Process Builder is retired. Continuing to use it increases maintenance overhead and risks future compatibility issues. Migrating automation to Flow reduces risk and improves maintainability.
-
-**Rule ID:** `process-builder-usage`
-**Class Name:** _[ProcessBuilder](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/ProcessBuilder.ts)_
-**Severity:** 🔴 *Error*
-
-#### SOQL Query In A Loop
-Running SOQL queries inside a loop can rapidly exceed query limits and severely degrade performance. Queries should be executed once, with results reused throughout the loop.
-
-**Rule ID:** `soql-in-loop`
-**Class Name:** _[SOQLQueryInLoop](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/SOQLQueryInLoop.ts)_
-**Severity:** 🔴 *Error*
-
-#### Unsafe Running Context
-Flows configured to run in System Mode without Sharing grant access to all data, bypassing user permissions. Avoid this setting to prevent security risks and protect sensitive data.
-
-**Rule ID:** `unsafe-running-context`
-**Class Name:** _[UnsafeRunningContext](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/UnsafeRunningContext.ts)_
-**Severity:** 🔴 *Error*
-
-#### Duplicate DML Operation
-When a Flow performs database operations across multiple screens, users navigating backward can cause the same actions to run multiple times. To prevent unintended changes, either restrict backward navigation or redesign the Flow so database operations execute in a single, forward-moving step.
-
-**Rule ID:** `duplicate-dml`
-**Class Name:** _[DuplicateDMLOperation](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/DuplicateDMLOperation.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Missing Fault Path
-Elements that can fail should include a Fault Path to handle errors gracefully. Without it, failures show generic errors to users. Fault Paths improve reliability and user experience.
-
-**Rule ID:** `missing-fault-path`
-**Class Name:** _[MissingFaultPath](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/MissingFaultPath.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Missing Null Handler
-Get Records operations return null when no data is found. Without handling these null values, Flows can fail or produce unintended results. Adding a null check improves reliability and ensures the Flow behaves as expected.
-
-**Rule ID:** `missing-null-handler`
-**Class Name:** _[MissingNullHandler](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/MissingNullHandler.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Recursive After Update
-After-save Flows that update the same record can trigger recursion, causing unintended behavior or performance issues. Avoid updating the triggering record in after-save Flows; use before-save Flows instead to prevent recursion.
-
-**Rule ID:** `recursive-record-update`
-**Class Name:** _[RecursiveAfterUpdate](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/RecursiveAfterUpdate.ts)_
-**Severity:** 🟡 *Warning*
-
----
-
-### Suggestions
-
-These rules highlight areas where Flows can be improved. Following them increases reliability and long-term maintainability.
-
-#### Action Call In A Loop
-Repeatedly invoking Apex actions inside a loop can exhaust governor limits and lead to performance issues. Where possible, bulkify your logic by moving the action call outside the loop and passing a collection variable instead.
-
-**Rule ID:** `action-call-in-loop`
-**Class Name:** _[ActionCallsInLoop](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/ActionCallsInLoop.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Get Record All Fields
-Avoid using Get Records to retrieve all fields unless necessary. This improves performance, reduces processing time, and limits exposure of unnecessary data.
-
-**Rule ID:** `get-record-all-fields`
-**Class Name:** _[GetRecordAllFields](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/GetRecordAllFields.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Inactive Flow
-Inactive Flows should be deleted or archived to reduce risk. Even when inactive, they can cause unintended record changes during testing or be activated as subflows. Keeping only active, relevant Flows improves safety and maintainability.
-
-**Rule ID:** `inactive-flow`
-**Class Name:** _[InactiveFlow](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/InactiveFlow.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Invalid API Version
-Flows running on outdated API versions may behave inconsistently when newer platform features or components are used. From API version 50.0 onward, the API Version attribute explicitly controls Flow runtime behavior. Keeping Flows aligned with a supported API version helps prevent compatibility issues and ensures predictable execution.
-
-**Rule ID:** `invalid-api-version`
-**Class Name:** _[APIVersion](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/APIVersion.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Missing Filter Record Trigger ![Beta](https://img.shields.io/badge/status-beta-yellow)
-Record-triggered Flows without filters on changed fields or entry conditions execute on every record change. Adding filters ensures the Flow runs only when needed, improving performance.
-
-**Rule ID:** `missing-record-trigger-filter`
-**Class Name:** _[MissingFilterRecordTrigger](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/MissingFilterRecordTrigger.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Same Record Field Updates
-Before-save Flows can safely update the triggering record directly via $Record, applying changes efficiently without extra DML operations. Using before-save updates improves performance
-
-**Rule ID:** `same-record-field-updates`
-**Class Name:** _[SameRecordFieldUpdates](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/SameRecordFieldUpdates.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Excessive Cyclomatic Complexity
-High numbers of loops and decision elements increase a Flow's cyclomatic complexity. To maintain simplicity and readability, consider using subflows or splitting a Flow into smaller, ordered Flows.
-
-**Rule ID:** `excessive-cyclomatic-complexity`
-**Class Name:** _[CyclomaticComplexity](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/CyclomaticComplexity.ts)_
-**Severity:** 🔵 *Note*
-
-#### Missing Trigger Order
-Record-triggered Flows without a specified Trigger Order may execute in an unpredictable sequence. Setting a Trigger Order ensures your Flows run in the intended order.
-
-**Rule ID:** `unspecified-trigger-order`
-**Class Name:** _[TriggerOrder](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/TriggerOrder.ts)_
-**Severity:** 🔵 *Note*
-
-#### Record ID as String ![Beta](https://img.shields.io/badge/status-beta-yellow)
-Flows that use a String variable for a record ID instead of receiving the full record introduce unnecessary complexity and additional Get Records queries. Using the complete record simplifies the Flow and improves performance.
-
-**Rule ID:** `record-id-as-string`
-**Class Name:** _[RecordIdAsString](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/RecordIdAsString.ts)_
-**Severity:** 🔵 *Note*
-
-#### Transform Instead of Loop ![Beta](https://img.shields.io/badge/status-beta-yellow)
-Loop elements that perform direct Assignments on each item can slow down Flows. Using Transform elements allows bulk operations on collections, improving performance and reducing complexity.
-
-**Rule ID:** `transform-instead-of-loop`
-**Class Name:** _[TransformInsteadOfLoop](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/TransformInsteadOfLoop.ts)_
-**Severity:** 🔵 *Note*
-
----
-
-### Layout
-
-Focused on naming, documentation, and organization, these rules ensure Flows remain clear, easy to understand, and maintainable as automations grow.
-
-#### Flow Naming Convention
-Using clear and consistent Flow names improves readability, discoverability, and maintainability. A good naming convention helps team members quickly understand a Flow's purpose—for example, including a domain and brief description like Service_OrderFulfillment. Adopt a naming pattern that aligns with your organization's standards.
-
-**Rule ID:** `invalid-naming-convention`
-**Class Name:** _[FlowName](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/FlowName.ts)_
-**Severity:** 🔴 *Error*
-
-#### Missing Flow Description
-Flow descriptions are essential for documentation and maintainability. Include a description for each Flow, explaining its purpose and where it's used.
-
-**Rule ID:** `missing-flow-description`
-**Class Name:** _[FlowDescription](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/FlowDescription.ts)_
-**Severity:** 🔴 *Error*
-
-#### Missing Metadata Description ![Beta](https://img.shields.io/badge/status-beta-yellow)
-Elements and metadata without a description reduce clarity and maintainability. Adding descriptions improves readability and makes your automation easier to understand.
-
-**Rule ID:** `missing-metadata-description`
-**Class Name:** _[MissingMetadataDescription](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/MissingMetadataDescription.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Unclear API Name
-Elements with unclear or duplicated API names, like Copy_X_Of_Element, reduce Flow readability. Make sure to update the API name when copying elements to keep your Flow organized.
-
-**Rule ID:** `unclear-api-naming`
-**Class Name:** _[CopyAPIName](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/CopyAPIName.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Unreachable Element
-Unconnected elements never execute and add unnecessary clutter. Remove or connect unused Flow elements to keep Flows clean and efficient.
-
-**Rule ID:** `unreachable-element`
-**Class Name:** _[UnconnectedElement](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/UnconnectedElement.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Unused Variable
-Unused variables are never referenced and add unnecessary clutter. Remove them to keep Flows efficient and easy to maintain.
-
-**Rule ID:** `unused-variable`
-**Class Name:** _[UnusedVariable](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/UnusedVariable.ts)_
-**Severity:** 🟡 *Warning*
-
-#### Missing Auto Layout
-Auto-Layout automatically arranges and aligns Flow elements, keeping the canvas organized and easier to maintain. Enabling it saves time and improves readability.
-
-**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*
+<!-- START GENERATED_RULES -->
+
+---
+
+### Problems
+
+These rules detect anti-patterns and unsafe practices in your Flows that could break functionality, compromise security, or cause deployment failures.
+
+#### DML Statement In A Loop
+Executing DML operations (insert, update, delete) inside a loop is a high-risk anti-pattern that frequently causes governor limit exceptions. All database operations should be collected and executed once, outside the loop.
+
+**Rule ID:** `dml-in-loop`
+**Class Name:** _[DMLStatementInLoop](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/DMLStatementInLoop.ts)_
+**Severity:** 🔴 *Error*
+
+#### Hardcoded Salesforce Id
+Avoid hard-coding record IDs, as they are unique to a specific org and will not work in other environments. Instead, store IDs in variables—such as merge-field URL parameters or a **Get Records** element—to make the Flow portable, maintainable, and flexible.
+
+**Rule ID:** `hardcoded-id`
+**Class Name:** _[HardcodedId](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/HardcodedId.ts)_
+**Severity:** 🔴 *Error*
+
+#### Hardcoded Salesforce Url
+Avoid hard-coding URLs, as they may change between environments or over time. Instead, store URLs in variables or custom settings to make the Flow adaptable, maintainable, and environment-independent.
+
+**Rule ID:** `hardcoded-url`
+**Class Name:** _[HardcodedUrl](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/HardcodedUrl.ts)_
+**Severity:** 🔴 *Error*
+
+#### Hardcoded Secret ![Beta](https://img.shields.io/badge/status-beta-yellow)
+Avoid hardcoding secrets, API keys, tokens, or credentials in Flows. These should be stored securely in Named Credentials, Custom Settings, Custom Metadata, or external secret management systems.
+
+**Rule ID:** `hardcoded-secret`
+**Class Name:** _[HardcodedSecret](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/HardcodedSecret.ts)_
+**Severity:** 🔴 *Error*
+
+#### Process Builder
+Process Builder is retired. Continuing to use it increases maintenance overhead and risks future compatibility issues. Migrating automation to Flow reduces risk and improves maintainability.
+
+**Rule ID:** `process-builder-usage`
+**Class Name:** _[ProcessBuilder](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/ProcessBuilder.ts)_
+**Severity:** 🔴 *Error*
+
+#### SOQL Query In A Loop
+Running SOQL queries inside a loop can rapidly exceed query limits and severely degrade performance. Queries should be executed once, with results reused throughout the loop.
+
+**Rule ID:** `soql-in-loop`
+**Class Name:** _[SOQLQueryInLoop](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/SOQLQueryInLoop.ts)_
+**Severity:** 🔴 *Error*
+
+#### Unsafe Running Context
+Flows configured to run in System Mode without Sharing grant access to all data, bypassing user permissions. Avoid this setting to prevent security risks and protect sensitive data.
+
+**Rule ID:** `unsafe-running-context`
+**Class Name:** _[UnsafeRunningContext](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/UnsafeRunningContext.ts)_
+**Severity:** 🔴 *Error*
+
+#### Duplicate DML Operation
+When a Flow performs database operations across multiple screens, users navigating backward can cause the same actions to run multiple times. To prevent unintended changes, either restrict backward navigation or redesign the Flow so database operations execute in a single, forward-moving step.
+
+**Rule ID:** `duplicate-dml`
+**Class Name:** _[DuplicateDMLOperation](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/DuplicateDMLOperation.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Missing Fault Path
+Elements that can fail should include a Fault Path to handle errors gracefully. Without it, failures show generic errors to users. Fault Paths improve reliability and user experience.
+
+**Rule ID:** `missing-fault-path`
+**Class Name:** _[MissingFaultPath](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/MissingFaultPath.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Missing Null Handler
+Get Records operations return null when no data is found. Without handling these null values, Flows can fail or produce unintended results. Adding a null check improves reliability and ensures the Flow behaves as expected.
+
+**Rule ID:** `missing-null-handler`
+**Class Name:** _[MissingNullHandler](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/MissingNullHandler.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Recursive After Update
+After-save Flows that update the same record can trigger recursion, causing unintended behavior or performance issues. Avoid updating the triggering record in after-save Flows; use before-save Flows instead to prevent recursion.
+
+**Rule ID:** `recursive-record-update`
+**Class Name:** _[RecursiveAfterUpdate](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/RecursiveAfterUpdate.ts)_
+**Severity:** 🟡 *Warning*
+
+---
+
+### Suggestions
+
+These rules highlight areas where Flows can be improved. Following them increases reliability and long-term maintainability.
+
+#### Action Call In A Loop
+Repeatedly invoking Apex actions inside a loop can exhaust governor limits and lead to performance issues. Where possible, bulkify your logic by moving the action call outside the loop and passing a collection variable instead.
+
+**Rule ID:** `action-call-in-loop`
+**Class Name:** _[ActionCallsInLoop](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/ActionCallsInLoop.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Get Record All Fields
+Avoid using Get Records to retrieve all fields unless necessary. This improves performance, reduces processing time, and limits exposure of unnecessary data.
+
+**Rule ID:** `get-record-all-fields`
+**Class Name:** _[GetRecordAllFields](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/GetRecordAllFields.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Inactive Flow
+Inactive Flows should be deleted or archived to reduce risk. Even when inactive, they can cause unintended record changes during testing or be activated as subflows. Keeping only active, relevant Flows improves safety and maintainability.
+
+**Rule ID:** `inactive-flow`
+**Class Name:** _[InactiveFlow](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/InactiveFlow.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Invalid API Version
+Flows running on outdated API versions may behave inconsistently when newer platform features or components are used. From API version 50.0 onward, the API Version attribute explicitly controls Flow runtime behavior. Keeping Flows aligned with a supported API version helps prevent compatibility issues and ensures predictable execution.
+
+**Rule ID:** `invalid-api-version`
+**Class Name:** _[APIVersion](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/APIVersion.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Missing Filter Record Trigger ![Beta](https://img.shields.io/badge/status-beta-yellow)
+Record-triggered Flows without filters on changed fields or entry conditions execute on every record change. Adding filters ensures the Flow runs only when needed, improving performance.
+
+**Rule ID:** `missing-record-trigger-filter`
+**Class Name:** _[MissingFilterRecordTrigger](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/MissingFilterRecordTrigger.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Same Record Field Updates
+Before-save Flows can safely update the triggering record directly via $Record, applying changes efficiently without extra DML operations. Using before-save updates improves performance
+
+**Rule ID:** `same-record-field-updates`
+**Class Name:** _[SameRecordFieldUpdates](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/SameRecordFieldUpdates.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Excessive Cyclomatic Complexity
+High numbers of loops and decision elements increase a Flow's cyclomatic complexity. To maintain simplicity and readability, consider using subflows or splitting a Flow into smaller, ordered Flows.
+
+**Rule ID:** `excessive-cyclomatic-complexity`
+**Class Name:** _[CyclomaticComplexity](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/CyclomaticComplexity.ts)_
+**Severity:** 🔵 *Note*
+
+#### Missing Trigger Order
+Record-triggered Flows without a specified Trigger Order may execute in an unpredictable sequence. Setting a Trigger Order ensures your Flows run in the intended order.
+
+**Rule ID:** `unspecified-trigger-order`
+**Class Name:** _[TriggerOrder](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/TriggerOrder.ts)_
+**Severity:** 🔵 *Note*
+
+#### Record ID as String ![Beta](https://img.shields.io/badge/status-beta-yellow)
+Flows that use a String variable for a record ID instead of receiving the full record introduce unnecessary complexity and additional Get Records queries. Using the complete record simplifies the Flow and improves performance.
+
+**Rule ID:** `record-id-as-string`
+**Class Name:** _[RecordIdAsString](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/RecordIdAsString.ts)_
+**Severity:** 🔵 *Note*
+
+#### Transform Instead of Loop ![Beta](https://img.shields.io/badge/status-beta-yellow)
+Loop elements that perform direct Assignments on each item can slow down Flows. Using Transform elements allows bulk operations on collections, improving performance and reducing complexity.
+
+**Rule ID:** `transform-instead-of-loop`
+**Class Name:** _[TransformInsteadOfLoop](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/TransformInsteadOfLoop.ts)_
+**Severity:** 🔵 *Note*
+
+---
+
+### Layout
+
+Focused on naming, documentation, and organization, these rules ensure Flows remain clear, easy to understand, and maintainable as automations grow.
+
+#### Flow Naming Convention
+Using clear and consistent Flow names improves readability, discoverability, and maintainability. A good naming convention helps team members quickly understand a Flow's purpose—for example, including a domain and brief description like Service_OrderFulfillment. Adopt a naming pattern that aligns with your organization's standards.
+
+**Rule ID:** `invalid-naming-convention`
+**Class Name:** _[FlowName](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/FlowName.ts)_
+**Severity:** 🔴 *Error*
+
+#### Missing Flow Description
+Flow descriptions are essential for documentation and maintainability. Include a description for each Flow, explaining its purpose and where it's used.
+
+**Rule ID:** `missing-flow-description`
+**Class Name:** _[FlowDescription](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/FlowDescription.ts)_
+**Severity:** 🔴 *Error*
+
+#### Missing Metadata Description ![Beta](https://img.shields.io/badge/status-beta-yellow)
+Elements and metadata without a description reduce clarity and maintainability. Adding descriptions improves readability and makes your automation easier to understand.
+
+**Rule ID:** `missing-metadata-description`
+**Class Name:** _[MissingMetadataDescription](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/MissingMetadataDescription.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Unclear API Name
+Elements with unclear or duplicated API names, like Copy_X_Of_Element, reduce Flow readability. Make sure to update the API name when copying elements to keep your Flow organized.
+
+**Rule ID:** `unclear-api-naming`
+**Class Name:** _[CopyAPIName](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/CopyAPIName.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Unreachable Element
+Unconnected elements never execute and add unnecessary clutter. Remove or connect unused Flow elements to keep Flows clean and efficient.
+
+**Rule ID:** `unreachable-element`
+**Class Name:** _[UnconnectedElement](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/UnconnectedElement.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Unused Variable
+Unused variables are never referenced and add unnecessary clutter. Remove them to keep Flows efficient and easy to maintain.
+
+**Rule ID:** `unused-variable`
+**Class Name:** _[UnusedVariable](https://github.com/Flow-Scanner/lightning-flow-scanner/blob/main/packages/core/src/main/rules/UnusedVariable.ts)_
+**Severity:** 🟡 *Warning*
+
+#### Missing Auto Layout
+Auto-Layout automatically arranges and aligns Flow elements, keeping the canvas organized and easier to maintain. Enabling it saves time and improves readability.
+
+**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).
 

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/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/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.3",
+  "version": "6.18.0",
   "main": "index.js",
   "exports": {
     ".": {