docs(#237): add docs to advanced rule

Author: junners

src/main/interfaces/AdvancedSuppression.ts

@@ -1,5 +1,22 @@
-import { RuleResult } from "../internals/internals";
+import { RuleResult } from "../models/RuleResult";
 import { AdvancedConfig } from "./AdvancedRuleConfig";
+
+/**
+ * Interface for implementing advanced suppression logic on rule scan results.
+ *
+ * @remarks
+ * This interface defines a contract for classes or objects that provide suppression capabilities
+ * for rule results, potentially modifying or filtering the results based on custom logic and optional configuration.
+ *
+ * @interface
+ */
 export interface AdvancedSuppression {
+  /**
+   * Suppresses or modifies a given rule scan result based on advanced configuration.
+   *
+   * @param scanResult - The result of a rule scan to be potentially suppressed or altered.
+   * @param ruleConfiguration - Optional advanced configuration that may influence suppression logic.
+   * @returns The (potentially) suppressed or modified rule result.
+   */
   suppress(scanResult: RuleResult, ruleConfiguration?: AdvancedConfig): RuleResult;
 }

src/main/interfaces/AutoFixable.ts

@@ -1,5 +1,11 @@
 import { Flow } from "../internals/internals";
 
+/**
+ * Interface representing an entity capable of automatically fixing a Flow.
+ *
+ * Implementations of this interface provide a `fix` method that takes a {@link Flow}
+ * object as input and returns a new or modified {@link Flow} with applied fixes.
+ */
 export interface AutoFixable {
   fix(flow: Flow): Flow;
 }

src/main/models/AdvancedRule.ts

@@ -7,10 +7,27 @@ import { RuleCommon } from "./RuleCommon";
 import { RuleInfo } from "./RuleInfo";
 import { RuleResult } from "./RuleResult";
 
+/**
+ * Abstract base class for advanced rules, extending {@link RuleCommon} and implementing
+ * {@link AdvancedRuleDefinition} and {@link IRuleDefinition}.
+ *
+ * @remarks
+ * This class provides a structure for advanced rule implementations, including
+ * support for advanced suppression and user-defined suppressions.
+ *
+ * @param info - The rule metadata information.
+ * @param optional - Optional configuration, such as severity.
+ */
 export abstract class AdvancedRule
   extends RuleCommon
   implements AdvancedRuleDefinition, IRuleDefinition
 {
+  /**
+   * Constructs an instance of {@link AdvancedRule}.
+   *
+   * @param info - The rule metadata information.
+   * @param optional - Optional configuration, such as severity.
+   */
   constructor(
     info: RuleInfo,
     optional?: {
@@ -20,7 +37,21 @@ export abstract class AdvancedRule
     super(info, optional);
   }
 
-  abstract execute(flow: Flow, ruleOptions?: object);
+  /**
+   * Your rule
+   * @param flow - The flow to analyze.
+   * @param ruleOptions - Optional rule-specific options.
+   */
+  abstract execute(flow: Flow, ruleOptions?: object): RuleResult;
+
+  /**
+   * Executes the rule with advanced configuration and applies suppressions.
+   *
+   * @param flow - The flow to analyze.
+   * @param ruleConfiguration - Optional advanced rule configuration.
+   * @param userFlowSuppressions - Optional list of user-defined suppressions.
+   * @returns The result of rule execution after applying suppressions.
+   */
   public execute2(
     flow: Flow,
     ruleConfiguration?: AdvancedConfig,
@@ -41,7 +72,13 @@ export abstract class AdvancedRule
     return ruleResult;
   }
 }
-
+/**
+ * Applies user-defined suppressions to the rule result.
+ *
+ * @param ruleResult - The result of rule execution.
+ * @param userFlowRuleSuppressions - Optional list of suppression names to filter out.
+ * @returns The filtered rule result.
+ */
 function generalSuppressions(
   ruleResult: RuleResult,
   userFlowRuleSuppressions?: string[]
@@ -57,13 +94,31 @@ function generalSuppressions(
   return ruleResult;
 }
 
+/**
+ * Type guard to check if a value is a function.
+ *
+ * @param val - The value to check.
+ * @returns True if the value is a function, false otherwise.
+ */
 // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
 const isFunction = (val: unknown): val is Function => typeof val === "function";
 
+/**
+ * Type guard to check if an instance implements {@link AdvancedSuppression}.
+ *
+ * @param instance - The instance to check.
+ * @returns True if the instance has a suppress method, false otherwise.
+ */
 function hasAdvancedSuppression(instance: unknown): instance is AdvancedSuppression {
   return isFunction((instance as AdvancedSuppression).suppress);
 }
 
+/**
+ * Type guard to check if an instance implements {@link IRuleDefinition}.
+ *
+ * @param instance - The instance to check.
+ * @returns True if the instance has an execute method, false otherwise.
+ */
 function hasClassicRuleDefinition(instance: unknown): instance is IRuleDefinition {
   return isFunction((instance as IRuleDefinition).execute);
 }

src/main/models/FlowType.ts

@@ -1,17 +1,37 @@
+/**
+ * Represents the different types of Salesforce Flows and provides utility methods
+ * to categorize and retrieve them.
+ *
+ * @remarks
+ * This class defines static properties for various flow types, including backend,
+ * process builder, survey, visual, and unsupported types. It also provides a method
+ * to retrieve all supported flow types.
+ *
+ * @example
+ * ```typescript
+ * const allFlowTypes = FlowType.allTypes();
+ * ```
+ */
 export class FlowType {
-  public static autolaunchedType = "AutoLaunchedFlow";
+  public static readonly autolaunchedType = "AutoLaunchedFlow";
 
-  public static backEndTypes = [
+  public static readonly backEndTypes = [
     this.autolaunchedType,
     "CustomEvent",
     "InvocableProcess",
     "Orchestrator",
     "EvaluationFlow",
     "ActionCadenceAutolaunchedFlow",
   ];
-  public static processBuilder = ["Workflow"];
-  public static surveyTypes = ["Survey"];
-  public static visualTypes = [
+  public static readonly processBuilder = ["Workflow"];
+  public static readonly surveyTypes = ["Survey"];
+  public static readonly unsupportedTypes = [
+    "CheckoutFlow",
+    "FSCLending",
+    "FSCLending",
+    "LoyaltyManagementFlow",
+  ];
+  public static readonly visualTypes = [
     "Flow",
     "IndividualObjectLinkingFlow",
     "LoginFlow",
@@ -25,14 +45,8 @@ export class FlowType {
     "FieldServiceWeb",
     "SurveyEnrich",
   ];
-  public static unsupportedTypes = [
-    "CheckoutFlow",
-    "FSCLending",
-    "FSCLending",
-    "LoyaltyManagementFlow",
-  ];
 
-  public static allTypes = function () {
+  public static readonly allTypes = function () {
     return [...this.backEndTypes, ...this.visualTypes, ...this.surveyTypes];
   };
 }

src/main/models/RuleInfo.ts

@@ -1,10 +1,60 @@
+export type RuleDefinitionExpression = {
+  options?: {
+    expression?: unknown;
+  };
+};
+
+/**
+ * Represents a rule metadata; this contains properties to describe the rule
+ */
 export class RuleInfo {
+  /**
+   * Indicates whether the rule can be automatically fixed.
+   * When the rule is autofixable, implement @see {AutoFixable}
+   */
   public autoFixable: boolean;
+
+  /**
+   * A human-readable description of the rule.
+   */
   public description: string;
+
+  /**
+   * An array of documentation references related to the rule.
+   */
   public docRefs: Array<{ label: string; path: string }>;
+
+  /**
+   * Specifies if the rule's behavior can be configured.
+   * When configurable, execute should take in a second parameter @see RuleDefinitionExpression
+   * @example
+   * ```typescript
+   * public execute(flow: core.Flow, options?: { expression: string }): core.RuleResult {
+   *   // your rule
+   * }
+   */
   public isConfigurable: boolean;
+
+  /**
+   * The display label for the rule.
+   * This property is being displayed on sf cli and on vsce
+   */
   public label: string;
+
+  /**
+   * The unique name identifier for the rule.
+   */
   public name: string;
+
+  /**
+   * The types supported by this rule (e.g., Flow, Process).
+   * Use defined types in @see FlowType
+   */
   public supportedTypes: string[];
+
+  /**
+   * (Optional) The element that can be used to suppress this rule.
+   * @see AdvancedSuppression
+   */
   public suppressionElement?: string;
 }