kist 0.0.0 → 0.1.31

package/ts/core/pipeline/Step.ts

@@ -0,0 +1,96 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ActionInterface } from "../../interface/ActionInterface";
+import { StepInterface } from "../../interface/StepInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+import { ActionRegistry } from "./ActionRegistry";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * Represents a single step in a stage, encapsulating its execution logic.
+ * This class manages the resolution and execution of actions associated
+ * with each step.
+ */
+export class Step extends AbstractProcess {
+    // Parameters
+    // ========================================================================
+
+    private name: string;
+    private action: ActionInterface;
+    private options?: Record<string, any>;
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Constructs a Step instance based on the provided step definition.
+     * Dynamically resolves the action class from the registry.
+     *
+     * @param step - The step definition containing the step name, action name,
+     * and options.
+     * @throws Error if the specified action is not registered in the action
+     * registry.
+     */
+    constructor(step: StepInterface) {
+        super();
+        this.name = step.name;
+
+        // Resolve the action class from the registry using the action name
+        const actionRegistry = ActionRegistry.getInstance();
+        // console.log(step.action)
+        // const ActionClass = actionRegistry.getAction(step.action.name);
+        const ActionClass = actionRegistry.getAction(String(step.action));
+        if (!ActionClass) {
+            let msg = `
+                Unknown action "${step.action}" for step "${this.name}".
+                Ensure the action is registered in the registry.
+                `;
+            this.logError(msg);
+            throw new Error(msg);
+        }
+
+        // Initialize the action with the specific class from the registry
+        this.action = new ActionClass();
+        this.options = step.options;
+
+        this.logInfo(
+            `Step "${this.name}" initialized with action "${step.action.constructor.name}".`,
+        );
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Executes the step by invoking its action's execute method.
+     */
+    async execute(): Promise<void> {
+        this.logInfo(`Executing step: ${this.name}`);
+
+        try {
+            // Validate options if the action provides a validation method
+            if (typeof this.action.validateOptions === "function") {
+                const isValid = this.action.validateOptions(
+                    this.options || {},
+                );
+                if (!isValid) {
+                    throw new Error(`Invalid options for step: ${this.name}`);
+                }
+            }
+
+            // Execute the action with the provided options
+            await this.action.execute(this.options || {});
+            this.logInfo(`Step "${this.name}" completed successfully.`);
+        } catch (error) {
+            this.logError(
+                `Error executing step "${this.name}": ${error}`,
+                error,
+            );
+        }
+    }
+}

package/ts/core/validation/ActionValidator.ts

@@ -0,0 +1,97 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { AbstractValidator } from "../abstract/AbstractValidator";
+import { ActionRegistry } from "../pipeline/ActionRegistry";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Type representing the structure of action properties for validation.
+ */
+type ActionValidationKeys = "action";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * Validates actions by ensuring they are registered in the `ActionRegistry`.
+ * Extends `AbstractValidator` for consistent validation and logging.
+ */
+export class ActionValidator extends AbstractValidator<
+    Record<ActionValidationKeys, string>
+> {
+    // Parameters
+    // ========================================================================
+
+    private actionRegistry: ActionRegistry;
+
+    // Constructor
+    // ========================================================================
+
+    constructor() {
+        super();
+        this.actionRegistry = ActionRegistry.getInstance();
+        this.logInfo("ActionValidator initialized.");
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Validates an action object with the structure { action: string }.
+     *
+     * @param target - The action object to validate.
+     * @throws Error if the action is invalid or not registered.
+     */
+    public validate(target: Record<ActionValidationKeys, string>): void {
+        const action = target.action;
+        this.logInfo(`Validating action: "${action}"`);
+
+        if (!action || typeof action !== "string") {
+            this.throwValidationError(
+                "action",
+                action,
+                "Action name must be a non-empty string.",
+            );
+        }
+
+        const registeredAction = this.actionRegistry.getAction(action);
+
+        if (!registeredAction) {
+            this.throwValidationError(
+                "action",
+                action,
+                `Action "${action}" is not registered in the ActionRegistry.`,
+            );
+        }
+
+        this.logValidationSuccess("action", action);
+    }
+
+    /**
+     * Validates a specific property of the action object.
+     * This is required to fulfill the `AbstractValidator` contract.
+     *
+     * @param key - The property key (e.g., "action").
+     * @param value - The value of the property to validate.
+     * @throws Error if the validation fails.
+     */
+    protected validateProperty<
+        K extends keyof Record<ActionValidationKeys, string>,
+    >(key: K, value: Record<ActionValidationKeys, string>[K]): void {
+        if (key === "action") {
+            this.validate({ action: value });
+        } else {
+            this.throwValidationError(
+                key,
+                value,
+                `Unknown property key: "${String(key)}".`,
+            );
+        }
+    }
+}

package/ts/core/validation/ConfigValidator.ts

@@ -0,0 +1,103 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ConfigInterface } from "../../interface/ConfigInterface";
+import { AbstractValidator } from "../abstract/AbstractValidator";
+import { StageValidator } from "./StageValidator";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * Validates the overall configuration, including stages and global options.
+ */
+export class ConfigValidator extends AbstractValidator<ConfigInterface> {
+    // Parameters
+    // ========================================================================
+
+    private stageValidator: StageValidator;
+
+    // Constructor
+    // ========================================================================
+
+    constructor() {
+        super();
+        this.stageValidator = new StageValidator();
+        this.logInfo("ConfigValidator initialized.");
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Validates the entire configuration object.
+     * @param config - The configuration object to validate.
+     * @throws Error if validation fails.
+     */
+    public validate(config: ConfigInterface): void {
+        this.logInfo("Validating configuration.");
+
+        // Validate each property of the configuration
+        for (const key in config) {
+            if (Object.prototype.hasOwnProperty.call(config, key)) {
+                this.validateProperty(
+                    key as keyof ConfigInterface,
+                    config[key as keyof ConfigInterface],
+                );
+            }
+        }
+
+        this.logInfo("Configuration validated successfully.");
+    }
+
+    /**
+     * Validates a specific property of the configuration object.
+     *
+     * @param key - The key of the property to validate.
+     * @param value - The value of the property to validate.
+     * @throws Error if validation fails.
+     */
+    protected validateProperty<K extends keyof ConfigInterface>(
+        key: K,
+        value: ConfigInterface[K],
+    ): void {
+        switch (key) {
+            case "stages":
+                if (Array.isArray(value)) {
+                    this.validateStages(value); // Validate only if it's an array
+                } else {
+                    this.throwValidationError(
+                        key,
+                        value,
+                        "'stages' must be an array.",
+                    );
+                }
+                break;
+
+            default:
+                // Add validation for other properties if needed
+                this.throwValidationError(
+                    key,
+                    value,
+                    `Unknown or unsupported configuration property: "${String(key)}".`,
+                );
+        }
+
+        this.logValidationSuccess(key, value);
+    }
+
+    /**
+     * Validates the stages in the configuration.
+     *
+     * @param stages - The stages to validate.
+     * @throws Error if validation fails.
+     */
+    private validateStages(stages: ConfigInterface["stages"]): void {
+        for (const stage of stages) {
+            // Validate each stage
+            this.stageValidator.validate(stage);
+        }
+    }
+}

package/ts/core/validation/OptionsValidator.ts

@@ -0,0 +1,179 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { OptionsInterface } from "../../interface/OptionsInterface";
+import { AbstractValidator } from "../abstract/AbstractValidator";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * OptionsValidator provides centralized validation logic for pipeline options.
+ * Extends AbstractValidator for consistent validation and logging.
+ */
+export class OptionsValidator extends AbstractValidator<OptionsInterface> {
+    // Parameters
+    // ========================================================================
+
+    /**
+     * A runtime mapping of enumerated options for validation.
+     */
+    private static allowedValues: Partial<
+        Record<keyof OptionsInterface, unknown[]>
+    > = {
+        logLevel: ["debug", "info", "warn", "error"],
+    };
+
+    // Constructor
+    // ========================================================================
+
+    constructor() {
+        super();
+        this.logDebug("OptionsValidator initialized.");
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Validates a specific property of the options object.
+     *
+     * @param key - The key of the option to validate.
+     * @param value - The value of the option to validate.
+     * @throws Error if validation fails.
+     */
+    protected validateProperty<K extends keyof OptionsInterface>(
+        key: K,
+        value: OptionsInterface[K],
+    ): void {
+        if (value === undefined) {
+            this.throwValidationError(
+                key,
+                value,
+                `Option "${String(key)}" cannot be undefined.`,
+            );
+            return;
+        }
+
+        const allowedValues = OptionsValidator.allowedValues[key];
+        if (allowedValues && !allowedValues.includes(value)) {
+            this.throwValidationError(
+                key,
+                value,
+                `Invalid value "${value}" for option "${String(key)}". Allowed values are: ${allowedValues.join(", ")}.`,
+            );
+            return;
+        }
+
+        this.validateByType(key, value);
+        this.logValidationSuccess(key, value);
+    }
+
+    /**
+     * Validates a property based on its type when it does not have predefined
+     * allowed values.
+     *
+     * @param key - The key to validate.
+     * @param value - The value to validate.
+     */
+    private validateByType<K extends keyof OptionsInterface>(
+        key: K,
+        value: OptionsInterface[K],
+    ): void {
+        switch (key) {
+            case "stepTimeout":
+            case "maxConcurrentStages":
+                if (typeof value === "number" && value >= 0) {
+                    this.validateNumber(key, value);
+                } else {
+                    this.throwValidationError(
+                        key,
+                        value,
+                        "Must be a non-negative number.",
+                    );
+                }
+                break;
+
+            case "haltOnFailure":
+            case "tags":
+                if (this.isValidObject(value)) {
+                    this.validateObject(key, value);
+                } else {
+                    this.throwValidationError(
+                        key,
+                        value,
+                        "Must be a valid object.",
+                    );
+                }
+                break;
+
+            case "live":
+                this.validateLiveOptions(value as OptionsInterface["live"]);
+                break;
+
+            default:
+                if (typeof value === "string" && value.trim() !== "") {
+                    this.validateString(key, value);
+                } else {
+                    this.throwValidationError(
+                        key,
+                        value,
+                        "Must be a non-empty string.",
+                    );
+                }
+        }
+    }
+
+    /**
+     * Validates the `live` configuration, ensuring all nested properties
+     * conform to their expected types and ranges.
+     *
+     * @param value - The live reload configuration to validate.
+     */
+    private validateLiveOptions(value: OptionsInterface["live"]): void {
+        if (value?.port && (value.port < 1 || value.port > 65535)) {
+            this.throwValidationError(
+                "live.port",
+                value.port,
+                "Port must be a number between 1 and 65535.",
+            );
+        }
+        if (value?.root && typeof value.root !== "string") {
+            this.throwValidationError(
+                "live.root",
+                value.root,
+                "Root must be a valid string path.",
+            );
+        }
+        if (value?.watchPaths && !Array.isArray(value.watchPaths)) {
+            this.throwValidationError(
+                "live.watchPaths",
+                value.watchPaths,
+                "Must be an array of paths.",
+            );
+        }
+        if (value?.ignoredPaths && !Array.isArray(value.ignoredPaths)) {
+            this.throwValidationError(
+                "live.ignoredPaths",
+                value.ignoredPaths,
+                "Must be an array of paths.",
+            );
+        }
+    }
+
+    /**
+     * Checks if the given value is a valid object.
+     *
+     * @param value - The value to check.
+     * @returns True if the value is an object and not null or an array.
+     */
+    private isValidObject(value: unknown): value is Record<string, unknown> {
+        return (
+            typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value)
+        );
+    }
+}

package/ts/core/validation/StageValidator.ts

@@ -0,0 +1,175 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { StageInterface } from "../../interface/StageInterface";
+import { AbstractValidator } from "../abstract/AbstractValidator";
+import { StepValidator } from "./StepValidator";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * StageValidator ensures that stages within the configuration meet the required criteria.
+ * It validates the stage properties, dependencies, and steps for correctness.
+ */
+export class StageValidator extends AbstractValidator<StageInterface> {
+    // Parameters
+    // ========================================================================
+
+    private stageNames: Set<string>;
+    private stepValidator: StepValidator;
+
+    // Constructor
+    // ========================================================================
+
+    constructor() {
+        super();
+        this.stageNames = new Set();
+        this.stepValidator = new StepValidator();
+        this.logInfo("StageValidator initialized.");
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Validates an entire stage object.
+     *
+     * @param stage - The stage object to validate.
+     * @throws Error if the stage or any of its properties are invalid.
+     */
+    public validate(stage: StageInterface): void {
+        this.logInfo(`Validating stage: "${stage.name}"`);
+
+        try {
+            // Validate individual properties of the stage
+            this.validateProperty("name", stage.name);
+            this.validateProperty("dependsOn", stage.dependsOn);
+            this.validateProperty("steps", stage.steps);
+
+            this.logInfo(`Stage "${stage.name}" validated successfully.`);
+        } catch (error) {
+            this.logError(
+                `Validation failed for stage "${stage.name}": ${(error as Error).message}`,
+            );
+            throw error;
+        }
+    }
+
+    /**
+     * Validates individual properties of the stage.
+     *
+     * @param key - The property name to validate.
+     * @param value - The property value to validate.
+     * @throws Error if the property value is invalid.
+     */
+    public validateProperty<K extends keyof StageInterface>(
+        key: K,
+        value: StageInterface[K],
+    ): void {
+        switch (key) {
+            case "name":
+                this.validateName(value as string);
+                break;
+
+            case "dependsOn":
+                this.validateDependencies(value as string[]);
+                break;
+
+            case "steps":
+                this.validateSteps(value as StageInterface["steps"]);
+                break;
+
+            default:
+                this.throwValidationError(
+                    key,
+                    value,
+                    "Unknown property provided for validation.",
+                );
+        }
+
+        // Log validation success with the property name and value
+        this.logValidationSuccess(key, value);
+    }
+
+    /**
+     * Validates the name of the stage.
+     *
+     * @param name - The name of the stage.
+     * @throws Error if the name is invalid.
+     */
+    private validateName(name: string): void {
+        if (!name || typeof name !== "string") {
+            this.throwValidationError(
+                "name",
+                name,
+                "Stage must have a valid 'name' property.",
+            );
+        }
+
+        if (this.stageNames.has(name)) {
+            this.throwValidationError(
+                "name",
+                name,
+                `Duplicate stage name found: "${name}".`,
+            );
+        }
+
+        this.stageNames.add(name);
+    }
+
+    /**
+     * Validates the stage dependencies.
+     *
+     * @param dependencies - The dependencies to validate.
+     * @throws Error if any dependency is invalid.
+     */
+    private validateDependencies(dependencies: string[] | undefined): void {
+        if (dependencies && !Array.isArray(dependencies)) {
+            throw new Error("Stage dependencies must be an array.");
+        }
+
+        dependencies?.forEach((dependency) => {
+            if (!this.stageNames.has(dependency)) {
+                this.throwValidationError(
+                    "dependsOn",
+                    [dependency], // Wrap dependency in an array to match the expected type
+                    `Undefined dependency: "${dependency}". Ensure it references a valid stage.`,
+                );
+            }
+        });
+    }
+
+    /**
+     * Validates the steps within the stage.
+     *
+     * @param steps - The steps array to validate.
+     * @throws Error if any step is invalid.
+     */
+    private validateSteps(steps: StageInterface["steps"]): void {
+        if (!Array.isArray(steps) || steps.length === 0) {
+            this.throwValidationError(
+                "steps",
+                steps,
+                "Each stage must contain at least one step.",
+            );
+        }
+
+        const stepNames = new Set<string>();
+        steps.forEach((step) => {
+            if (stepNames.has(step.name)) {
+                this.throwValidationError(
+                    "steps",
+                    steps, // Pass the full steps array for context
+                    `Duplicate step name found in stage: "${step.name}".`,
+                );
+            }
+            stepNames.add(step.name);
+
+            // Validate each step using StepValidator
+            this.stepValidator.validate(step);
+        });
+    }
+}