kist 0.0.0 → 0.1.31

package/js/core/pipeline/Stage.js

@@ -0,0 +1,110 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stage = void 0;
+const AbstractProcess_1 = require("../abstract/AbstractProcess");
+const Step_1 = require("./Step");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * Represents a stage in the pipeline, encapsulating its execution logic and
+ * dependencies. Each stage consists of multiple steps that are executed
+ * consecutively, and stages can have dependencies on other stages which are
+ * managed before execution.
+ */
+class Stage extends AbstractProcess_1.AbstractProcess {
+    // Constructor
+    // ========================================================================
+    /**
+     * Constructs a Stage instance with the given stage definition.
+     * @param stage - The stage definition containing name, steps, and
+     * dependencies.
+     */
+    constructor(stage) {
+        super(); // Initialize logging
+        this.name = stage.name;
+        this.steps = stage.steps.map((step) => new Step_1.Step(step));
+        this.dependsOn = stage.dependsOn;
+        this.logInfo(`Stage "${this.name}" initialized with ${this.steps.length} steps.`);
+    }
+    // Methods
+    // ========================================================================
+    // Methods
+    // ========================================================================
+    /**
+     * Executes the stage by running its steps consecutively.
+     * Manages dependencies by waiting for dependent stages to complete
+     * before execution.
+     * @param completedStages - A set of completed stage names used for
+     * dependency tracking.
+     * @throws Error if any step within the stage fails.
+     */
+    execute(completedStages) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Handle dependencies before executing the stage
+            if (this.dependsOn) {
+                yield this.resolveDependencies(completedStages);
+            }
+            this.logInfo(`Executing stage: ${this.name}`);
+            // Execute all steps within the stage consecutively
+            try {
+                for (const step of this.steps) {
+                    yield step.execute();
+                }
+                this.logInfo(`Stage "${this.name}" completed successfully.`);
+                completedStages.add(this.name);
+            }
+            catch (error) {
+                this.logError(`Error executing stage "${this.name}": ${error}`, error);
+                // Propagate the error to halt pipeline or manage based on
+                // global settings
+                throw error;
+            }
+        });
+    }
+    /**
+     * Resolves dependencies by ensuring all required stages have completed.
+     * @param completedStages - A set of completed stage names used for
+     * dependency tracking.
+     * @returns A promise that resolves once all dependencies are met.
+     */
+    resolveDependencies(completedStages) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.dependsOn)
+                return;
+            this.logInfo(`Stage "${this.name}" is waiting for
+            dependencies:${this.dependsOn.join(", ")}`);
+            yield Promise.all(this.dependsOn.map((dep) => this.waitForStageCompletion(dep, completedStages)));
+            this.logInfo(`All dependencies resolved for stage: "${this.name}"`);
+        });
+    }
+    /**
+     * Waits for a specified stage to complete by monitoring the completed
+     * stages set.
+     * @param stageName - The name of the stage to wait for.
+     * @param completedStages - A set of completed stage names used for
+     * dependency tracking.
+     * @returns A promise that resolves when the specified stage is marked
+     * as completed.
+     */
+    waitForStageCompletion(stageName, completedStages) {
+        return __awaiter(this, void 0, void 0, function* () {
+            while (!completedStages.has(stageName)) {
+                yield new Promise((resolve) => setTimeout(resolve, 100));
+            }
+        });
+    }
+}
+exports.Stage = Stage;

package/js/core/pipeline/Step.d.ts

@@ -0,0 +1,26 @@
+import { StepInterface } from "../../interface/StepInterface";
+import { AbstractProcess } from "../abstract/AbstractProcess";
+/**
+ * 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 declare class Step extends AbstractProcess {
+    private name;
+    private action;
+    private options?;
+    /**
+     * 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);
+    /**
+     * Executes the step by invoking its action's execute method.
+     */
+    execute(): Promise<void>;
+}

package/js/core/pipeline/Step.js

@@ -0,0 +1,85 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Step = void 0;
+const AbstractProcess_1 = require("../abstract/AbstractProcess");
+const ActionRegistry_1 = require("./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.
+ */
+class Step extends AbstractProcess_1.AbstractProcess {
+    // 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) {
+        super();
+        this.name = step.name;
+        // Resolve the action class from the registry using the action name
+        const actionRegistry = ActionRegistry_1.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.
+     */
+    execute() {
+        return __awaiter(this, void 0, void 0, function* () {
+            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
+                yield this.action.execute(this.options || {});
+                this.logInfo(`Step "${this.name}" completed successfully.`);
+            }
+            catch (error) {
+                this.logError(`Error executing step "${this.name}": ${error}`, error);
+            }
+        });
+    }
+}
+exports.Step = Step;

package/js/core/validation/OptionsValidator.d.ts

@@ -0,0 +1,43 @@
+import { OptionsInterface } from "../../interface/OptionsInterface";
+import { AbstractValidator } from "../abstract/AbstractValidator";
+/**
+ * OptionsValidator provides centralized validation logic for pipeline options.
+ * Extends AbstractValidator for consistent validation and logging.
+ */
+export declare class OptionsValidator extends AbstractValidator<OptionsInterface> {
+    /**
+     * A runtime mapping of enumerated options for validation.
+     */
+    private static allowedValues;
+    constructor();
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/js/core/validation/OptionsValidator.js

@@ -0,0 +1,123 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OptionsValidator = void 0;
+const AbstractValidator_1 = require("../abstract/AbstractValidator");
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * OptionsValidator provides centralized validation logic for pipeline options.
+ * Extends AbstractValidator for consistent validation and logging.
+ */
+class OptionsValidator extends AbstractValidator_1.AbstractValidator {
+    // 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.
+     */
+    validateProperty(key, value) {
+        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.
+     */
+    validateByType(key, value) {
+        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);
+                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.
+     */
+    validateLiveOptions(value) {
+        if ((value === null || value === void 0 ? void 0 : 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 === null || value === void 0 ? void 0 : value.root) && typeof value.root !== "string") {
+            this.throwValidationError("live.root", value.root, "Root must be a valid string path.");
+        }
+        if ((value === null || value === void 0 ? void 0 : value.watchPaths) && !Array.isArray(value.watchPaths)) {
+            this.throwValidationError("live.watchPaths", value.watchPaths, "Must be an array of paths.");
+        }
+        if ((value === null || value === void 0 ? void 0 : 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.
+     */
+    isValidObject(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value));
+    }
+}
+exports.OptionsValidator = OptionsValidator;
+// Parameters
+// ========================================================================
+/**
+ * A runtime mapping of enumerated options for validation.
+ */
+OptionsValidator.allowedValues = {
+    logLevel: ["debug", "info", "warn", "error"],
+};

package/js/index.d.ts

@@ -0,0 +1,3 @@
+export { Kist } from "./kist";
+export * from "./types";
+export * from "./cli.js";

package/js/index.js

@@ -0,0 +1,36 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Kist = void 0;
+// 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
+var kist_1 = require("./kist");
+Object.defineProperty(exports, "Kist", { enumerable: true, get: function () { return kist_1.Kist; } });
+// Additional Types
+__exportStar(require("./types"), exports);
+// CLI Functions (if required programmatically)
+__exportStar(require("./cli.js"), exports);

package/js/interface/ActionInterface.d.ts

@@ -0,0 +1,57 @@
+import { ActionOptionsType } from "../types/ActionOptionsType";
+/**
+ * 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/js/interface/ActionInterface.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/interface/ActionPlugin.d.ts

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

package/js/interface/ActionPlugin.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/interface/ConfigInterface.d.ts

@@ -0,0 +1,43 @@
+import { MetadataInterface } from "./MetadataInterface";
+import { OptionsInterface } from "./OptionsInterface";
+import { StageInterface } from "./StageInterface";
+/**
+ * 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/js/interface/ConfigInterface.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// Import
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/js/interface/LiveOptionsInterface.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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/js/interface/LiveOptionsInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });