kist 0.0.0 → 0.1.31

package/ts/core/validation/StepValidator.ts

@@ -0,0 +1,203 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { StepInterface } from "../../interface/StepInterface";
+import { StepOptionsInterface } from "../../interface/StepOptionsInterface";
+import { AbstractValidator } from "../abstract/AbstractValidator";
+import { ActionValidator } from "./ActionValidator";
+
+// ============================================================================
+// Class
+// ============================================================================
+
+/**
+ * Validates individual steps within a stage.
+ * Ensures steps conform to the expected structure and all associated
+ * actions are valid.
+ */
+export class StepValidator extends AbstractValidator<StepInterface> {
+    // Parameters
+    // ========================================================================
+
+    private actionValidator: ActionValidator;
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Initializes the StepValidator.
+     * Creates an instance of `ActionValidator` for validating actions.
+     */
+    constructor() {
+        super();
+        this.actionValidator = new ActionValidator();
+        this.logInfo("StepValidator initialized.");
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Validates an entire step object.
+     *
+     * @param step - The step object to validate.
+     * @throws Error if the step or any of its properties are invalid.
+     */
+    public validate(step: StepInterface): void {
+        this.logInfo(`Validating step: "${step.name}"`);
+
+        this.validateProperty("name", step.name);
+        this.validateActions(step.action); // Validate the action object
+        if (step.options) {
+            this.validateProperty("options", step.options);
+        }
+
+        this.logInfo(`Step "${step.name}" validated successfully.`);
+    }
+
+    /**
+     * Validates a specific property of a step.
+     *
+     * @param key - The property key to validate (e.g., "name", "action").
+     * @param value - The property value to validate.
+     * @throws Error if validation fails.
+     */
+    public validateProperty<K extends keyof StepInterface>(
+        key: K,
+        value: StepInterface[K],
+    ): void {
+        switch (key) {
+            case "name":
+                this.validateName(value as string);
+                break;
+            case "options":
+                this.validateOptions(value as Record<string, any>);
+                break;
+            default:
+                this.throwValidationError(
+                    key,
+                    value,
+                    "Unknown key provided for validation.",
+                );
+        }
+
+        this.logValidationSuccess(key, value);
+    }
+
+    /**
+     * Validates the step name.
+     * Ensures it is a non-empty string.
+     *
+     * @param name - The step name to validate.
+     * @throws Error if the name is invalid.
+     */
+    private validateName(name: string): void {
+        if (!name || typeof name !== "string" || name.trim() === "") {
+            this.throwValidationError(
+                "name",
+                name,
+                "Each step must have a valid, non-empty 'name' property.",
+            );
+        }
+    }
+
+    /**
+     * Validates the action object of the step.
+     * Uses `ActionValidator` to validate the action's `name`.
+     *
+     * @param action - The action object to validate.
+     * @throws Error if the action is invalid.
+     */
+    private validateActions(action: StepInterface["action"]): void {
+        if (
+            !action ||
+            typeof action.name !== "string" ||
+            action.name.trim() === ""
+        ) {
+            this.throwValidationError(
+                "action",
+                action,
+                "Each step must have a valid 'action' object with a non-empty 'name' property.",
+            );
+        }
+
+        try {
+            this.actionValidator.validate({ action: action.name }); // Validate the action name
+        } catch (error) {
+            this.throwValidationError(
+                "action",
+                action,
+                (error as Error).message,
+            );
+        }
+    }
+
+    /**
+     * Validates the step options.
+     * Ensures options conform to `StepOptionsInterface`.
+     *
+     * @param options - The options object to validate.
+     * @throws Error if the options are invalid.
+     */
+    private validateOptions(options: StepOptionsInterface | undefined): void {
+        // Ensure options are not null
+        if (options === null) {
+            this.throwValidationError(
+                "options",
+                options,
+                "Step options must be a valid object or undefined, but 'null' was provided.",
+            );
+        }
+
+        if (
+            options &&
+            (typeof options !== "object" || Array.isArray(options))
+        ) {
+            this.throwValidationError(
+                "options",
+                options,
+                "Step options must be a valid object conforming to StepOptionsInterface.",
+            );
+        }
+
+        // Validate individual properties within `options`
+        if (options) {
+            for (const [key, value] of Object.entries(options)) {
+                switch (key) {
+                    case "description":
+                        if (value !== undefined && typeof value !== "string") {
+                            this.throwValidationError(
+                                "options",
+                                value,
+                                `Invalid value for "description": must be a string.`,
+                            );
+                        }
+                        break;
+
+                    case "enabled":
+                        if (
+                            value !== undefined &&
+                            typeof value !== "boolean"
+                        ) {
+                            this.throwValidationError(
+                                "options",
+                                value,
+                                `Invalid value for "enabled": must be a boolean.`,
+                            );
+                        }
+                        break;
+
+                    default:
+                        // For additional custom keys, you can implement further checks
+                        this.logInfo(
+                            `Validating additional key "${key}" with value "${value}".`,
+                        );
+                        break;
+                }
+            }
+        }
+
+        this.logInfo("Step options validated successfully.");
+    }
+}

package/ts/index.ts

@@ -0,0 +1,26 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+
+
+// Core Modules
+// export { Pipeline } from "./core/Pipeline";
+// export { ConfigLoader } from "./core/ConfigLoader";
+// export { PipelineManager } from "./core/PipelineManager";
+
+// Live Modules
+// export { LiveReloadServer } from "./live/LiveReloadServer";
+// export { FileWatcher } from "./live/FileWatcher";
+
+// Actions and Other Utilities
+// export { Action } from "./core/Action";
+
+// Main Function
+export { Kist } from "./kist";
+
+// Additional Types
+export * from "./types";
+
+// CLI Functions (if required programmatically)
+export * from "./cli.js";

package/ts/interface/ActionInterface.ts

@@ -0,0 +1,70 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ActionOptionsType } from "../types/ActionOptionsType";
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * ActionInterface defines the contract for step action classes in pack.gl.
+ * Implementing this interface allows actions to be dynamically integrated into
+ * the pipeline, offering a flexible and extensible system for defining custom
+ * behaviors within different stages.
+ */
+export interface ActionInterface {
+    /**
+     * A unique name identifying the action.
+     * This property is used for logging, registration in the ActionRegistry,
+     * and debugging purposes.
+     */
+    name: string;
+
+    /**
+     * Executes the action with the provided options.
+     * Implementations of this method should perform the main logic of the
+     * action, such as building, testing, linting, packaging, or other
+     * custom-defined processes.
+     *
+     * @param options - A structured set of options specific to the action's
+     * configuration. Implementations are responsible for validating and
+     * applying these options. Example configurations might include:
+     * - For 'build': { minify: boolean, sourceMap: boolean, target: string }
+     * - For 'lint': { fix: boolean, formatter: string }
+     * @returns A Promise that resolves when the action completes successfully,
+     * or rejects with an error if the action fails.
+     */
+    execute(options: ActionOptionsType): Promise<void>;
+
+    /**
+     * Validates the provided options before execution.
+     * This method can be used to check the integrity and correctness of the
+     * options object, ensuring that required fields are present and valid.
+     *
+     * @param options - The options to validate, ensuring they meet the
+     * action's specific requirements.
+     * @returns A boolean indicating whether the options are valid. Throws an
+     * error or returns false if validation fails.
+     */
+    validateOptions?(options: ActionOptionsType): boolean;
+
+    /**
+     * Provides a summary or description of the action.
+     * This can be used for logging, debugging, or documentation purposes to
+     * describe what the action does.
+     *
+     * @returns A string description of the action.
+     */
+    describe?(): string;
+
+    /**
+     * Optional cleanup logic to execute after the main action completes.
+     * Implementations can use this for teardown tasks, like removing
+     * temporary files or restoring the state altered during execution.
+     *
+     * @returns A promise that resolves after cleanup is complete.
+     */
+    cleanup?(): Promise<void>;
+}

package/ts/interface/ActionPlugin.ts

@@ -0,0 +1,14 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ActionInterface } from "./ActionInterface";
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+// ActionPlugin.ts
+export interface ActionPlugin {
+    registerActions(): Record<string, new () => ActionInterface>;
+}

package/ts/interface/ConfigInterface.ts

@@ -0,0 +1,55 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { MetadataInterface } from "./MetadataInterface";
+import { OptionsInterface } from "./OptionsInterface";
+import { StageInterface } from "./StageInterface";
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * ConfigInterface defines the overall configuration for the packaging
+ * pipeline. This configuration determines the structure, behavior, and
+ * execution flow of the entire pipeline, including stages, global settings,
+ * and optional metadata.
+ */
+export interface ConfigInterface {
+    /**
+     * Optional metadata that provides additional context or descriptive
+     * information about the pipeline configuration. This can include the
+     * pipeline name, version, author, or any other relevant details. Useful
+     * for documentation, tracking, and integration with external systems.
+     */
+    metadata?: MetadataInterface;
+
+    /**
+     * Optional global options that apply universally across the entire
+     * pipeline. These options can control aspects like logging levels, step
+     * timeouts, error handling, concurrency limits, and other settings that
+     * affect the overall pipeline behavior.
+     */
+    options?: OptionsInterface;
+
+    /**
+     * A list of stages to be executed in the pipeline. Stages run in parallel
+     * by default, but dependencies specified in each stage can enforce a
+     * specific execution order. Stages should be defined in the logical
+     * sequence that aligns with the pipeline's objectives.
+     */
+    stages: StageInterface[];
+
+    /**
+     * An optional function or set of rules for validating the configuration
+     * before execution. This can be used to ensure that the pipeline meets
+     * certain criteria or standards before running, catching potential
+     * configuration errors early.
+     *
+     * @param config - The full configuration object to validate.
+     * @returns A boolean indicating whether the configuration is valid, or
+     *      throws an error if validation fails.
+     */
+    validateConfig?(config: ConfigInterface): boolean;
+}

package/ts/interface/File.ts

@@ -0,0 +1,24 @@
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * Interface for representing a file within the system.
+ * This interface is used to define the structure of file data objects
+ * that include both the file path and its source content.
+ */
+export interface File {
+    /**
+     * The full path to the file.
+     * This should include the complete directory path and the file name with
+     * its extension.
+     */
+    filepath: string;
+
+    /**
+     * The source content of the file.
+     * This could be any form of text, such as code, configuration, or plain
+     * text.
+     */
+    source: string;
+}

package/ts/interface/LiveOptionsInterface.ts

@@ -0,0 +1,46 @@
+/**
+ * LiveOptionsInterface defines the configuration settings for live reload
+ * functionality, which enables dynamic updates to the application during
+ * development.
+ */
+export interface LiveOptionsInterface {
+    /**
+     * Enables or disables the live reload feature.
+     * - `true`: Live reload is enabled, and the server will listen for changes.
+     * - `false`: Live reload is disabled.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+
+    /**
+     * The port number on which the live reload server will listen.
+     * If not specified, a default port (e.g., 3000) may be used.
+     *
+     * @example 3000
+     * @default 3000
+     */
+    port?: number;
+
+    /**
+     * The root directory for serving static files during live reload.
+     * This path is relative to the project root and is used to serve public
+     * assets.
+     *
+     * @example "public"
+     * @default "public"
+     */
+    root?: string;
+
+    /**
+     * An array of paths to monitor for file changes. These paths can use glob
+     * patterns for flexibility
+     */
+    watchPaths?: string[];
+
+    /**
+     * An array of paths or patterns to exclude from monitoring. Use this to
+     * ignore directories or files that do not need to trigger reloads
+     */
+    ignoredPaths?: string[];
+}

package/ts/interface/MetadataInterface.ts

@@ -0,0 +1,105 @@
+/**
+ * MetadataInterface provides contextual information about the pipeline
+ * configuration. This metadata is useful for tracking changes, documentation,
+ * and integration with external systems.
+ */
+export interface MetadataInterface {
+    /**
+     * A human-readable name for the pipeline.
+     * Used for identification and reporting purposes.
+     *
+     * @example "Data Processing Pipeline"
+     */
+    name?: string;
+
+    /**
+     * The semantic version of the pipeline configuration.
+     * Helps in tracking changes, maintaining compatibility, and managing
+     * different setups.
+     *
+     * @example "1.0.0"
+     */
+    version?: string;
+
+    /**
+     * A detailed description outlining the pipeline's purpose, objectives,
+     * or key features.
+     * Useful for providing context to users and maintainers.
+     *
+     * @example "A pipeline for processing and analyzing large datasets,
+     * including ETL operations."
+     */
+    description?: string;
+
+    /**
+     * The author or owner of the pipeline configuration.
+     * Can include details such as name, email, or organization.
+     *
+     * @example "John Doe <john.doe@example.com>"
+     */
+    author?: string;
+
+    /**
+     * A collection of arbitrary key-value pairs to further describe the
+     * pipeline configuration. This can be used for categorization or
+     * custom metadata.
+     *
+     * @example { category: "ETL", team: "Data Engineering" }
+     */
+    tags?: Record<string, string>;
+
+    /**
+     * A timestamp indicating when the configuration was created or last
+     * updated. Should follow the ISO 8601 format (e.g.,
+     * "2024-01-01T12:00:00Z").
+     *
+     * @example "2024-01-01T12:00:00Z"
+     */
+    timestamp?: string;
+
+    /**
+     * The license under which the pipeline configuration is shared or used.
+     * This defines the terms and conditions for using the configuration.
+     *
+     * @example "MIT"
+     * @example "GPL-3.0"
+     */
+    license?: string;
+
+    /**
+     * A URL pointing to documentation or additional resources related to
+     * the pipeline.
+     * Can include links to GitHub repos, wikis, or help pages.
+     *
+     * @example "https://github.com/username/repo"
+     */
+    documentation?: string;
+
+    /**
+     * Contact information for questions or support regarding the pipeline
+     * configuration.
+     * This can include an email address, a support page URL, or a
+     * team/organization name.
+     *
+     * @example "support@example.com"
+     * @example "https://example.com/support"
+     */
+    contact?: string;
+
+    /**
+     * Dependencies or related systems required by the pipeline configuration.
+     * Useful for tracking external systems or tools that interact with this
+     * pipeline.
+     *
+     * @example ["Node.js >=14.0", "Docker >=20.10"]
+     */
+    dependencies?: string[];
+
+    /**
+     * A list of intended runtime environment(s) for the pipeline.
+     * This helps clarify where the pipeline is designed to be executed.
+     *
+     * @example ["local", "CI/CD", "staging", "production"]
+     */
+    environments?: string[];
+}

package/ts/interface/OptionsInterface.ts

@@ -0,0 +1,58 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { LiveOptionsInterface } from "./LiveOptionsInterface";
+import { PipelineOptionsInterface } from "./PipelineOptionsInterface";
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * OptionsInterface represents the global configuration options that
+ * apply to the entire pipeline. These settings provide overarching controls
+ * that affect how all stages and steps within the pipeline operate.
+ */
+export interface OptionsInterface {
+    /**
+     * Configuration settings for live reload functionality, enabling
+     * real-time updates during development.
+     */
+    live?: LiveOptionsInterface;
+
+    /**
+     * Pipeline-specific configuration options.
+     */
+    pipeline?: PipelineOptionsInterface;
+
+    /**
+     * Path to the configuration file. This can be used to override default
+     * or automatically located configuration files.
+     *
+     * @example "./config/pack.yaml"
+     */
+    configPath?: string;
+
+    /**
+     * Specifies the level of logging to be used throughout the pipeline.
+     *
+     * The available levels are:
+     * - "debug": Provides detailed logging, useful for debugging and
+     *      tracing execution flow.
+     * - "info": Standard logging level, providing key information about
+     *      pipeline progress and outcomes.
+     * - "warn": Logs only warnings and errors, useful for highlighting
+     *      potential issues without excessive details.
+     * - "error": Logs only errors, minimizing output to essential problem
+     *      notifications. Default is "info".
+     *
+     * @default "info"
+     */
+    logLevel?: "debug" | "info" | "warn" | "error";
+
+    /**
+     * Additional properties can be included dynamically.
+     */
+    [key: string]: unknown;
+}