@creact-labs/creact 0.1.0

package/dist/core/Validator.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+
+ * you may not use this file except in compliance with the License.
+
+ * You may obtain a copy of the License at
+
+ *
+
+ *     http://www.apache.org/licenses/LICENSE-2.0
+
+ *
+
+ * Unless required by applicable law or agreed to in writing, software
+
+ * distributed under the License is distributed on an "AS IS" BASIS,
+
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+ * See the License for the specific language governing permissions and
+
+ * limitations under the License.
+
+ *
+
+ * Copyright 2025 Daniel Coutinho Ribeiro
+
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Validator = exports.ValidationError = void 0;
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('validator');
+/**
+ * Validation error with component stack trace
+ * REQ-NF-03.1: Enhanced error messages with file and line trace
+ */
+class ValidationError extends Error {
+    constructor(message, componentStack, filePath, lineNumber) {
+        super(message);
+        this.componentStack = componentStack;
+        this.filePath = filePath;
+        this.lineNumber = lineNumber;
+        this.name = 'ValidationError';
+        // Enhance error message with stack trace
+        this.message = this.formatError(message, componentStack, filePath, lineNumber);
+    }
+    /**
+     * Get a quick summary of the error for dev tools
+     * REQ-NF-03.1: Enhanced error messages
+     */
+    get summary() {
+        return `${this.message.split('\n')[0]} (${this.filePath || 'unknown'})`;
+    }
+    formatError(message, componentStack, filePath, lineNumber) {
+        let formatted = message;
+        // Add file location if available
+        if (filePath) {
+            formatted += `\n  at ${filePath}`;
+            if (lineNumber) {
+                formatted += `:${lineNumber}`;
+            }
+        }
+        // Add component stack trace
+        if (componentStack.length > 0) {
+            formatted += '\n\nComponent stack:';
+            componentStack.forEach((component, index) => {
+                const indent = '  '.repeat(index + 1);
+                formatted += `\n${indent}in ${component}`;
+            });
+        }
+        return formatted;
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Validator validates Fiber tree before committing to CloudDOM
+ *
+ * Validation checks:
+ * - Required props are present
+ * - Context is available when useStackContext is called
+ * - Resource IDs are unique
+ * - No circular dependencies
+ *
+ * No dependencies injected - pure validation logic
+ */
+class Validator {
+    /**
+     * Validate a Fiber tree
+     *
+     * @param fiber - Root Fiber node to validate
+     * @throws ValidationError if validation fails
+     */
+    validate(fiber) {
+        if (!fiber) {
+            throw new Error('Cannot validate null Fiber tree');
+        }
+        // Track resource IDs for uniqueness check
+        const resourceIds = new Set();
+        // Track visited nodes for circular dependency check
+        const visitedPaths = new Set();
+        // Validate recursively
+        this.validateNode(fiber, [], resourceIds, visitedPaths);
+    }
+    /**
+     * Validate a single Fiber node and its children
+     *
+     * @param node - Fiber node to validate
+     * @param componentStack - Stack of component names for error reporting
+     * @param resourceIds - Set of resource IDs seen so far
+     * @param visitedPaths - Set of visited paths for circular dependency detection
+     */
+    validateNode(node, componentStack, resourceIds, visitedPaths) {
+        // Defensive: Handle corrupted nodes
+        if (!node) {
+            return;
+        }
+        // Get component name for stack trace
+        const componentName = this.getComponentName(node);
+        const currentStack = [...componentStack, componentName];
+        // Optional debug trace for development introspection
+        const pathStr = node.path ? node.path.join('.') : 'unknown';
+        logger.debug('Validating', pathStr);
+        // REQ-07.4: Circular dependency detection
+        const pathKey = node.path ? node.path.join('.') : '';
+        if (pathKey && visitedPaths.has(pathKey)) {
+            throw new ValidationError(`Circular dependency detected: ${pathKey}`, currentStack, this.getFilePath(node), this.getLineNumber(node));
+        }
+        if (pathKey) {
+            visitedPaths.add(pathKey);
+        }
+        // REQ-07.1: Required props validation
+        this.validateRequiredProps(node, currentStack);
+        // REQ-07.3: Unique resource IDs - check cloudDOMNodes array
+        if (node.cloudDOMNodes && node.cloudDOMNodes.length > 0) {
+            for (const cloudNode of node.cloudDOMNodes) {
+                const resourceId = cloudNode.id;
+                if (resourceIds.has(resourceId)) {
+                    throw new ValidationError(`Duplicate resource ID: '${resourceId}'. Resource IDs must be unique.`, currentStack, this.getFilePath(node), this.getLineNumber(node));
+                }
+                resourceIds.add(resourceId);
+            }
+        }
+        // REQ-07.2: Context validation
+        // Note: This will be implemented when hooks are added
+        // For now, we check if the node has a marker indicating context usage
+        if (node.props && node.props.__usesStackContext) {
+            this.validateContextAvailable(node, currentStack);
+        }
+        // Recursively validate children
+        // Clone visitedPaths for each child to ensure isolation per branch
+        // This prevents false circular dependency warnings for sibling nodes
+        if (node.children && Array.isArray(node.children)) {
+            for (const child of node.children) {
+                this.validateNode(child, currentStack, resourceIds, new Set(visitedPaths));
+            }
+        }
+    }
+    /**
+     * Validate that required props are present
+     * REQ-07.1: Required props validation
+     *
+     * @param node - Fiber node to validate
+     * @param componentStack - Component stack for error reporting
+     */
+    validateRequiredProps(node, componentStack) {
+        // Get required props from component type
+        const requiredProps = this.getRequiredProps(node.type);
+        // Check each required prop
+        for (const propName of requiredProps) {
+            if (!(propName in node.props) || node.props[propName] === undefined) {
+                const componentName = this.getComponentName(node);
+                throw new ValidationError(`Missing required prop '${propName}' in ${componentName} component`, componentStack, this.getFilePath(node), this.getLineNumber(node));
+            }
+        }
+    }
+    /**
+     * Validate that context is available when useStackContext is called
+     * REQ-07.2: Context validation
+     *
+     * @param node - Fiber node that uses context
+     * @param componentStack - Component stack for error reporting
+     */
+    validateContextAvailable(node, componentStack) {
+        // Note: In a real implementation, we would traverse the parent chain
+        // For now, we check if there's a provider marker in the tree
+        // This will be properly implemented when StackContext is added
+        // Check if any ancestor has a provider
+        // (This is a simplified check - full implementation will traverse parent references)
+        if (node.props.__hasContextProvider === false) {
+            const componentName = this.getComponentName(node);
+            throw new ValidationError(`useStackContext() called in ${componentName} but no StackContext.Provider found in ancestor tree`, componentStack, this.getFilePath(node), this.getLineNumber(node));
+        }
+    }
+    /**
+     * Get required props for a component type
+     *
+     * Checks for:
+     * - Static requiredProps property
+     * - PropTypes (if available)
+     * - TypeScript metadata (future enhancement)
+     *
+     * @param type - Component type
+     * @returns Array of required prop names
+     */
+    getRequiredProps(type) {
+        // Check for static requiredProps property
+        if (type && type.requiredProps && Array.isArray(type.requiredProps)) {
+            return type.requiredProps;
+        }
+        // Check for PropTypes (React-style)
+        if (type && type.propTypes) {
+            const required = [];
+            for (const [propName, propType] of Object.entries(type.propTypes)) {
+                // Check if prop is marked as required
+                if (propType && typeof propType === 'object' && propType.isRequired) {
+                    required.push(propName);
+                }
+            }
+            return required;
+        }
+        // No required props found
+        return [];
+    }
+    /**
+     * Get component name for error reporting
+     *
+     * @param node - Fiber node
+     * @returns Component name
+     */
+    getComponentName(node) {
+        if (typeof node.type === 'function') {
+            return node.type.displayName || node.type.name || 'Anonymous';
+        }
+        if (typeof node.type === 'string') {
+            return node.type;
+        }
+        return 'Unknown';
+    }
+    /**
+     * Get file path from Fiber node (if available)
+     *
+     * In a real implementation, this would use source maps or
+     * stack trace analysis to determine the file path.
+     *
+     * @param node - Fiber node
+     * @returns File path or undefined
+     */
+    getFilePath(node) {
+        // Check if component has __source metadata (added by Babel/TypeScript)
+        if (node.type && node.type.__source) {
+            return node.type.__source.fileName;
+        }
+        // Check props for source metadata
+        if (node.props && node.props.__source) {
+            return node.props.__source.fileName;
+        }
+        return undefined;
+    }
+    /**
+     * Get line number from Fiber node (if available)
+     *
+     * @param node - Fiber node
+     * @returns Line number or undefined
+     */
+    getLineNumber(node) {
+        // Check if component has __source metadata
+        if (node.type && node.type.__source) {
+            return node.type.__source.lineNumber;
+        }
+        // Check props for source metadata
+        if (node.props && node.props.__source) {
+            return node.props.__source.lineNumber;
+        }
+        return undefined;
+    }
+}
+exports.Validator = Validator;

package/dist/core/errors.d.ts

@@ -0,0 +1,153 @@
+/**
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+
+ * you may not use this file except in compliance with the License.
+
+ * You may obtain a copy of the License at
+
+ *
+
+ *     http://www.apache.org/licenses/LICENSE-2.0
+
+ *
+
+ * Unless required by applicable law or agreed to in writing, software
+
+ * distributed under the License is distributed on an "AS IS" BASIS,
+
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+ * See the License for the specific language governing permissions and
+
+ * limitations under the License.
+
+ *
+
+ * Copyright 2025 Daniel Coutinho Ribeiro
+
+ */
+/**
+ * Base error class for all CReact errors
+ */
+export declare class CReactError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Validation error - thrown when CloudDOM validation fails
+ *
+ * Used for:
+ * - Circular dependencies
+ * - Invalid node structure
+ * - Schema validation failures
+ */
+export declare class ValidationError extends CReactError {
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, details?: Record<string, any> | undefined);
+}
+/**
+ * Reconciliation error - thrown when diff computation fails
+ *
+ * Used for:
+ * - Circular dependencies in dependency graph
+ * - Invalid change detection
+ */
+export declare class ReconciliationError extends CReactError {
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, details?: Record<string, any> | undefined);
+}
+/**
+ * Deployment error data structure
+ *
+ * Provides structured error information for audit logs and debugging.
+ */
+export interface DeploymentErrorData {
+    /** Error code for categorization */
+    code?: string;
+    /** Error message */
+    message: string;
+    /** Stack trace */
+    stack?: string;
+    /** Root cause description */
+    cause?: string;
+    /** Additional context */
+    details?: Record<string, any>;
+}
+/**
+ * Deployment error - thrown when deployment fails
+ *
+ * Used for:
+ * - Provider failures
+ * - Resource creation failures
+ * - State persistence failures
+ * - State machine transition errors
+ *
+ * Provides structured error data for audit logs and telemetry.
+ */
+export declare class DeploymentError extends CReactError {
+    readonly data: DeploymentErrorData;
+    constructor(message: string, data?: DeploymentErrorData);
+}
+/**
+ * Provider error - thrown when provider operations fail
+ *
+ * Used for:
+ * - Provider initialization failures
+ * - Materialization failures
+ * - Backend state operations
+ */
+export declare class ProviderError extends CReactError {
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, details?: Record<string, any> | undefined);
+}
+/**
+ * Reactive system error - thrown when reactive operations fail
+ *
+ * Used for:
+ * - Re-render failures
+ * - Circular dependency detection
+ * - State update failures
+ * - Context propagation failures
+ */
+export declare class ReactiveError extends CReactError {
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, details?: Record<string, any> | undefined);
+}
+/**
+ * Circular dependency error - thrown when circular dependencies are detected
+ */
+export declare class CircularDependencyError extends ReactiveError {
+    readonly cyclePath: string[];
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, cyclePath: string[], details?: Record<string, any> | undefined);
+}
+/**
+ * Re-render error - thrown when component re-rendering fails
+ */
+export declare class ReRenderError extends ReactiveError {
+    readonly fiberPath: string[];
+    readonly cause?: Error | undefined;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, fiberPath: string[], cause?: Error | undefined, details?: Record<string, any> | undefined);
+}
+/**
+ * State update error - thrown when state updates fail
+ */
+export declare class StateUpdateError extends ReactiveError {
+    readonly fiberPath: string[];
+    readonly hookIndex: number;
+    readonly cause?: Error | undefined;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, fiberPath: string[], hookIndex: number, cause?: Error | undefined, details?: Record<string, any> | undefined);
+}
+/**
+ * Context propagation error - thrown when context updates fail
+ */
+export declare class ContextPropagationError extends ReactiveError {
+    readonly contextId: symbol;
+    readonly affectedFibers: string[][];
+    readonly cause?: Error | undefined;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, contextId: symbol, affectedFibers: string[][], cause?: Error | undefined, details?: Record<string, any> | undefined);
+}

package/dist/core/errors.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+
+ * you may not use this file except in compliance with the License.
+
+ * You may obtain a copy of the License at
+
+ *
+
+ *     http://www.apache.org/licenses/LICENSE-2.0
+
+ *
+
+ * Unless required by applicable law or agreed to in writing, software
+
+ * distributed under the License is distributed on an "AS IS" BASIS,
+
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+ * See the License for the specific language governing permissions and
+
+ * limitations under the License.
+
+ *
+
+ * Copyright 2025 Daniel Coutinho Ribeiro
+
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextPropagationError = exports.StateUpdateError = exports.ReRenderError = exports.CircularDependencyError = exports.ReactiveError = exports.ProviderError = exports.DeploymentError = exports.ReconciliationError = exports.ValidationError = exports.CReactError = void 0;
+// Custom error classes for CReact
+// Provides typed errors for better error handling and debugging
+/**
+ * Base error class for all CReact errors
+ */
+class CReactError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'CReactError';
+        // Maintain proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+exports.CReactError = CReactError;
+/**
+ * Validation error - thrown when CloudDOM validation fails
+ *
+ * Used for:
+ * - Circular dependencies
+ * - Invalid node structure
+ * - Schema validation failures
+ */
+class ValidationError extends CReactError {
+    constructor(message, details) {
+        super(message, 'VALIDATION_ERROR');
+        this.details = details;
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Reconciliation error - thrown when diff computation fails
+ *
+ * Used for:
+ * - Circular dependencies in dependency graph
+ * - Invalid change detection
+ */
+class ReconciliationError extends CReactError {
+    constructor(message, details) {
+        super(message, 'RECONCILIATION_ERROR');
+        this.details = details;
+        this.name = 'ReconciliationError';
+        // Maintain proper stack trace (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ReconciliationError);
+        }
+    }
+}
+exports.ReconciliationError = ReconciliationError;
+/**
+ * Deployment error - thrown when deployment fails
+ *
+ * Used for:
+ * - Provider failures
+ * - Resource creation failures
+ * - State persistence failures
+ * - State machine transition errors
+ *
+ * Provides structured error data for audit logs and telemetry.
+ */
+class DeploymentError extends CReactError {
+    constructor(message, data = { message }) {
+        super(message, data.code || 'DEPLOYMENT_ERROR');
+        this.data = data;
+        this.name = 'DeploymentError';
+        // Ensure message is in data
+        if (!this.data.message) {
+            this.data.message = message;
+        }
+        // Maintain proper stack trace (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, DeploymentError);
+        }
+    }
+}
+exports.DeploymentError = DeploymentError;
+/**
+ * Provider error - thrown when provider operations fail
+ *
+ * Used for:
+ * - Provider initialization failures
+ * - Materialization failures
+ * - Backend state operations
+ */
+class ProviderError extends CReactError {
+    constructor(message, details) {
+        super(message, 'PROVIDER_ERROR');
+        this.details = details;
+        this.name = 'ProviderError';
+    }
+}
+exports.ProviderError = ProviderError;
+/**
+ * Reactive system error - thrown when reactive operations fail
+ *
+ * Used for:
+ * - Re-render failures
+ * - Circular dependency detection
+ * - State update failures
+ * - Context propagation failures
+ */
+class ReactiveError extends CReactError {
+    constructor(message, details) {
+        super(message, 'REACTIVE_ERROR');
+        this.details = details;
+        this.name = 'ReactiveError';
+    }
+}
+exports.ReactiveError = ReactiveError;
+/**
+ * Circular dependency error - thrown when circular dependencies are detected
+ */
+class CircularDependencyError extends ReactiveError {
+    constructor(message, cyclePath, details) {
+        super(message, { ...details, cyclePath });
+        this.cyclePath = cyclePath;
+        this.details = details;
+        this.name = 'CircularDependencyError';
+    }
+}
+exports.CircularDependencyError = CircularDependencyError;
+/**
+ * Re-render error - thrown when component re-rendering fails
+ */
+class ReRenderError extends ReactiveError {
+    constructor(message, fiberPath, cause, details) {
+        super(message, { ...details, fiberPath, cause: cause?.message });
+        this.fiberPath = fiberPath;
+        this.cause = cause;
+        this.details = details;
+        this.name = 'ReRenderError';
+    }
+}
+exports.ReRenderError = ReRenderError;
+/**
+ * State update error - thrown when state updates fail
+ */
+class StateUpdateError extends ReactiveError {
+    constructor(message, fiberPath, hookIndex, cause, details) {
+        super(message, { ...details, fiberPath, hookIndex, cause: cause?.message });
+        this.fiberPath = fiberPath;
+        this.hookIndex = hookIndex;
+        this.cause = cause;
+        this.details = details;
+        this.name = 'StateUpdateError';
+    }
+}
+exports.StateUpdateError = StateUpdateError;
+/**
+ * Context propagation error - thrown when context updates fail
+ */
+class ContextPropagationError extends ReactiveError {
+    constructor(message, contextId, affectedFibers, cause, details) {
+        super(message, {
+            ...details,
+            contextId: String(contextId),
+            affectedFibers,
+            cause: cause?.message,
+        });
+        this.contextId = contextId;
+        this.affectedFibers = affectedFibers;
+        this.cause = cause;
+        this.details = details;
+        this.name = 'ContextPropagationError';
+    }
+}
+exports.ContextPropagationError = ContextPropagationError;

package/dist/core/index.d.ts

@@ -0,0 +1,38 @@
+/**
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+
+ * you may not use this file except in compliance with the License.
+
+ * You may obtain a copy of the License at
+
+ *
+
+ *     http://www.apache.org/licenses/LICENSE-2.0
+
+ *
+
+ * Unless required by applicable law or agreed to in writing, software
+
+ * distributed under the License is distributed on an "AS IS" BASIS,
+
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+ * See the License for the specific language governing permissions and
+
+ * limitations under the License.
+
+ *
+
+ * Copyright 2025 Daniel Coutinho Ribeiro
+
+ */
+export * from './types';
+export * from './Renderer';
+export * from './Validator';
+export * from './CloudDOMBuilder';
+export * from './CReact';
+export { CloudDOMEventBus } from './EventBus';
+export { Reconciler } from './Reconciler';
+export { ReconciliationError, DeploymentError, DeploymentErrorData, ValidationError, ProviderError, } from './errors';
+export { StateMachine, DeploymentStatus, DeploymentState, StateMachineEvent, StateMachineEventPayload, AuditLogEntry, } from './StateMachine';