@creact-labs/creact 0.1.0

package/dist/core/StructuralChangeDetector.d.ts

@@ -0,0 +1,140 @@
+/**
+
+ * 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
+
+ */
+import { FiberNode, CloudDOMNode, CReactEvents } from './types';
+/**
+ * Structural change types for CloudDOM topology changes
+ */
+export type StructuralChangeType = 'resource-added' | 'resource-removed' | 'resource-moved' | 'topology-changed';
+/**
+ * Structural change event
+ */
+export interface StructuralChange {
+    type: StructuralChangeType;
+    nodeId: string;
+    path: string[];
+    previousPath?: string[];
+    affectedFibers: FiberNode[];
+    metadata?: Record<string, any>;
+}
+/**
+ * StructuralChangeDetector - Detects CloudDOM topology changes
+ *
+ * Key Features:
+ * - Detect conditional useInstance calls (resources appearing/disappearing)
+ * - Track resource hierarchy changes
+ * - Trigger re-renders for affected components
+ * - Integrate with deployment planning for dynamic updates
+ */
+export declare class StructuralChangeDetector {
+    private previousSnapshot?;
+    private eventHooks?;
+    constructor(eventHooks?: CReactEvents);
+    /**
+     * Detect structural changes between previous and current CloudDOM
+     * This is the main method called after each render to detect topology changes
+     *
+     * @param previousCloudDOM - Previous CloudDOM state
+     * @param currentCloudDOM - Current CloudDOM state
+     * @param currentFiber - Current fiber tree for affected component tracking
+     * @returns Array of structural changes detected
+     */
+    detectStructuralChanges(previousCloudDOM: CloudDOMNode[], currentCloudDOM: CloudDOMNode[], currentFiber: FiberNode): StructuralChange[];
+    /**
+     * Create a topology snapshot of CloudDOM for comparison
+     */
+    private createTopologySnapshot;
+    /**
+     * Detect newly added resources (conditional useInstance calls that became active)
+     */
+    private detectAddedResources;
+    /**
+     * Detect removed resources (conditional useInstance calls that became inactive)
+     */
+    private detectRemovedResources;
+    /**
+     * Detect moved resources (useInstance calls that changed hierarchy position)
+     */
+    private detectMovedResources;
+    /**
+     * Find fiber nodes that correspond to a specific path
+     */
+    private findFibersForPath;
+    /**
+     * Check if a fiber path matches or is related to a target path
+     */
+    private isPathMatch;
+    /**
+     * Check if two paths are equal
+     */
+    private pathsEqual;
+    /**
+     * Find all fibers affected by structural changes
+     */
+    private findAffectedFibers;
+    /**
+     * Generate a simple hash for hierarchy comparison
+     */
+    private generateHash;
+    /**
+     * Emit structural change events for observability
+     */
+    private emitStructuralChangeEvents;
+    /**
+     * Trigger re-renders for components affected by structural changes
+     * This integrates with the RenderScheduler to schedule re-renders
+     *
+     * @param changes - Structural changes detected
+     * @param renderScheduler - RenderScheduler instance to schedule re-renders
+     */
+    triggerStructuralReRenders(changes: StructuralChange[], renderScheduler: any): void;
+    /**
+     * Check if structural changes require deployment plan updates
+     * This helps determine if the deployment needs to be re-planned
+     *
+     * @param changes - Structural changes detected
+     * @returns True if deployment planning should be updated
+     */
+    requiresDeploymentPlanUpdate(changes: StructuralChange[]): boolean;
+    /**
+     * Get statistics about structural changes for monitoring
+     */
+    getChangeStats(changes: StructuralChange[]): {
+        totalChanges: number;
+        addedResources: number;
+        removedResources: number;
+        movedResources: number;
+        topologyChanges: number;
+        affectedFibers: number;
+    };
+    /**
+     * Clear previous snapshot (for testing/cleanup)
+     */
+    clearSnapshot(): void;
+}

package/dist/core/StructuralChangeDetector.js

@@ -0,0 +1,363 @@
+"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.StructuralChangeDetector = void 0;
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('clouddom');
+/**
+ * StructuralChangeDetector - Detects CloudDOM topology changes
+ *
+ * Key Features:
+ * - Detect conditional useInstance calls (resources appearing/disappearing)
+ * - Track resource hierarchy changes
+ * - Trigger re-renders for affected components
+ * - Integrate with deployment planning for dynamic updates
+ */
+class StructuralChangeDetector {
+    constructor(eventHooks) {
+        this.eventHooks = eventHooks;
+    }
+    /**
+     * Detect structural changes between previous and current CloudDOM
+     * This is the main method called after each render to detect topology changes
+     *
+     * @param previousCloudDOM - Previous CloudDOM state
+     * @param currentCloudDOM - Current CloudDOM state
+     * @param currentFiber - Current fiber tree for affected component tracking
+     * @returns Array of structural changes detected
+     */
+    detectStructuralChanges(previousCloudDOM, currentCloudDOM, currentFiber) {
+        const changes = [];
+        // Create snapshots for comparison
+        const previousSnapshot = this.createTopologySnapshot(previousCloudDOM);
+        const currentSnapshot = this.createTopologySnapshot(currentCloudDOM);
+        // Detect added resources
+        const addedChanges = this.detectAddedResources(previousSnapshot, currentSnapshot, currentFiber);
+        changes.push(...addedChanges);
+        // Detect removed resources
+        const removedChanges = this.detectRemovedResources(previousSnapshot, currentSnapshot, currentFiber);
+        changes.push(...removedChanges);
+        // Detect moved resources
+        const movedChanges = this.detectMovedResources(previousSnapshot, currentSnapshot, currentFiber);
+        changes.push(...movedChanges);
+        // Detect overall topology changes
+        if (previousSnapshot.hierarchyHash !== currentSnapshot.hierarchyHash) {
+            const topologyChange = {
+                type: 'topology-changed',
+                nodeId: 'root',
+                path: [],
+                affectedFibers: this.findAffectedFibers(currentFiber, changes),
+                metadata: {
+                    previousHash: previousSnapshot.hierarchyHash,
+                    currentHash: currentSnapshot.hierarchyHash,
+                    totalChanges: changes.length,
+                },
+            };
+            changes.push(topologyChange);
+        }
+        // Store current snapshot for next comparison
+        this.previousSnapshot = currentSnapshot;
+        // Emit events for observability
+        if (changes.length > 0) {
+            this.emitStructuralChangeEvents(changes);
+        }
+        return changes;
+    }
+    /**
+     * Create a topology snapshot of CloudDOM for comparison
+     */
+    createTopologySnapshot(cloudDOM) {
+        const nodeIds = new Set();
+        const nodePaths = new Map();
+        const nodeTypes = new Map();
+        const hierarchyElements = [];
+        const walkNodes = (nodes, depth = 0) => {
+            for (const node of nodes) {
+                nodeIds.add(node.id);
+                nodePaths.set(node.id, [...node.path]);
+                nodeTypes.set(node.id, node.construct);
+                // Add to hierarchy hash elements
+                hierarchyElements.push(`${depth}:${node.id}:${node.construct?.name || 'unknown'}`);
+                if (node.children && node.children.length > 0) {
+                    walkNodes(node.children, depth + 1);
+                }
+            }
+        };
+        walkNodes(cloudDOM);
+        // Create hierarchy hash for quick comparison
+        const hierarchyHash = this.generateHash(hierarchyElements.sort().join('|'));
+        return {
+            nodeIds,
+            nodePaths,
+            nodeTypes,
+            hierarchyHash,
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Detect newly added resources (conditional useInstance calls that became active)
+     */
+    detectAddedResources(previous, current, fiber) {
+        const changes = [];
+        for (const nodeId of current.nodeIds) {
+            if (!previous.nodeIds.has(nodeId)) {
+                const path = current.nodePaths.get(nodeId) || [];
+                const affectedFibers = this.findFibersForPath(fiber, path);
+                changes.push({
+                    type: 'resource-added',
+                    nodeId,
+                    path,
+                    affectedFibers,
+                    metadata: {
+                        construct: current.nodeTypes.get(nodeId)?.name || 'unknown',
+                        timestamp: Date.now(),
+                    },
+                });
+            }
+        }
+        return changes;
+    }
+    /**
+     * Detect removed resources (conditional useInstance calls that became inactive)
+     */
+    detectRemovedResources(previous, current, fiber) {
+        const changes = [];
+        for (const nodeId of previous.nodeIds) {
+            if (!current.nodeIds.has(nodeId)) {
+                const path = previous.nodePaths.get(nodeId) || [];
+                const affectedFibers = this.findFibersForPath(fiber, path);
+                changes.push({
+                    type: 'resource-removed',
+                    nodeId,
+                    path,
+                    affectedFibers,
+                    metadata: {
+                        construct: previous.nodeTypes.get(nodeId)?.name || 'unknown',
+                        timestamp: Date.now(),
+                    },
+                });
+            }
+        }
+        return changes;
+    }
+    /**
+     * Detect moved resources (useInstance calls that changed hierarchy position)
+     */
+    detectMovedResources(previous, current, fiber) {
+        const changes = [];
+        for (const nodeId of current.nodeIds) {
+            if (previous.nodeIds.has(nodeId)) {
+                const previousPath = previous.nodePaths.get(nodeId);
+                const currentPath = current.nodePaths.get(nodeId);
+                if (previousPath && currentPath && !this.pathsEqual(previousPath, currentPath)) {
+                    const affectedFibers = [
+                        ...this.findFibersForPath(fiber, previousPath),
+                        ...this.findFibersForPath(fiber, currentPath),
+                    ];
+                    changes.push({
+                        type: 'resource-moved',
+                        nodeId,
+                        path: currentPath,
+                        previousPath,
+                        affectedFibers,
+                        metadata: {
+                            construct: current.nodeTypes.get(nodeId)?.name || 'unknown',
+                            from: previousPath.join('.'),
+                            to: currentPath.join('.'),
+                            timestamp: Date.now(),
+                        },
+                    });
+                }
+            }
+        }
+        return changes;
+    }
+    /**
+     * Find fiber nodes that correspond to a specific path
+     */
+    findFibersForPath(fiber, targetPath) {
+        const matchingFibers = [];
+        const walkFiber = (currentFiber) => {
+            // Check if this fiber's path matches or is a parent of the target path
+            if (this.isPathMatch(currentFiber.path, targetPath)) {
+                matchingFibers.push(currentFiber);
+            }
+            // Recursively check children
+            if (currentFiber.children && currentFiber.children.length > 0) {
+                for (const child of currentFiber.children) {
+                    walkFiber(child);
+                }
+            }
+        };
+        walkFiber(fiber);
+        return matchingFibers;
+    }
+    /**
+     * Check if a fiber path matches or is related to a target path
+     */
+    isPathMatch(fiberPath, targetPath) {
+        // Exact match
+        if (this.pathsEqual(fiberPath, targetPath)) {
+            return true;
+        }
+        // Fiber is parent of target (target path starts with fiber path)
+        if (targetPath.length > fiberPath.length) {
+            return fiberPath.every((segment, index) => segment === targetPath[index]);
+        }
+        // Fiber is child of target (fiber path starts with target path)
+        if (fiberPath.length > targetPath.length) {
+            return targetPath.every((segment, index) => segment === fiberPath[index]);
+        }
+        return false;
+    }
+    /**
+     * Check if two paths are equal
+     */
+    pathsEqual(path1, path2) {
+        if (path1.length !== path2.length) {
+            return false;
+        }
+        return path1.every((segment, index) => segment === path2[index]);
+    }
+    /**
+     * Find all fibers affected by structural changes
+     */
+    findAffectedFibers(fiber, changes) {
+        const affectedFibers = new Set();
+        for (const change of changes) {
+            change.affectedFibers.forEach((f) => affectedFibers.add(f));
+        }
+        return Array.from(affectedFibers);
+    }
+    /**
+     * Generate a simple hash for hierarchy comparison
+     */
+    generateHash(input) {
+        let hash = 0;
+        for (let i = 0; i < input.length; i++) {
+            const char = input.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        return hash.toString(36);
+    }
+    /**
+     * Emit structural change events for observability
+     */
+    emitStructuralChangeEvents(changes) {
+        if (!this.eventHooks) {
+            return;
+        }
+        for (const change of changes) {
+            // Emit custom event for structural changes
+            if (this.eventHooks.onStructuralChange) {
+                this.eventHooks.onStructuralChange(change);
+            }
+            // Also emit as general events for affected fibers
+            for (const fiber of change.affectedFibers) {
+                this.eventHooks.onFiberReRenderScheduled?.(fiber, 'structural-change');
+            }
+        }
+        logger.debug(`Detected ${changes.length} structural changes:`, changes);
+    }
+    /**
+     * Trigger re-renders for components affected by structural changes
+     * This integrates with the RenderScheduler to schedule re-renders
+     *
+     * @param changes - Structural changes detected
+     * @param renderScheduler - RenderScheduler instance to schedule re-renders
+     */
+    triggerStructuralReRenders(changes, renderScheduler) {
+        const affectedFibers = new Set();
+        // Collect all affected fibers
+        for (const change of changes) {
+            change.affectedFibers.forEach((fiber) => affectedFibers.add(fiber));
+        }
+        // Schedule re-renders for affected fibers
+        for (const fiber of affectedFibers) {
+            renderScheduler.schedule(fiber, 'structural-change');
+        }
+        logger.debug(`Scheduled re-renders for ${affectedFibers.size} fibers due to structural changes`);
+    }
+    /**
+     * Check if structural changes require deployment plan updates
+     * This helps determine if the deployment needs to be re-planned
+     *
+     * @param changes - Structural changes detected
+     * @returns True if deployment planning should be updated
+     */
+    requiresDeploymentPlanUpdate(changes) {
+        // Any resource addition, removal, or move requires deployment plan update
+        return changes.some((change) => change.type === 'resource-added' ||
+            change.type === 'resource-removed' ||
+            change.type === 'resource-moved');
+    }
+    /**
+     * Get statistics about structural changes for monitoring
+     */
+    getChangeStats(changes) {
+        const stats = {
+            totalChanges: changes.length,
+            addedResources: 0,
+            removedResources: 0,
+            movedResources: 0,
+            topologyChanges: 0,
+            affectedFibers: 0,
+        };
+        const allAffectedFibers = new Set();
+        for (const change of changes) {
+            switch (change.type) {
+                case 'resource-added':
+                    stats.addedResources++;
+                    break;
+                case 'resource-removed':
+                    stats.removedResources++;
+                    break;
+                case 'resource-moved':
+                    stats.movedResources++;
+                    break;
+                case 'topology-changed':
+                    stats.topologyChanges++;
+                    break;
+            }
+            change.affectedFibers.forEach((fiber) => allAffectedFibers.add(fiber));
+        }
+        stats.affectedFibers = allAffectedFibers.size;
+        return stats;
+    }
+    /**
+     * Clear previous snapshot (for testing/cleanup)
+     */
+    clearSnapshot() {
+        this.previousSnapshot = undefined;
+    }
+}
+exports.StructuralChangeDetector = StructuralChangeDetector;

package/dist/core/Validator.d.ts

@@ -0,0 +1,127 @@
+/**
+
+ * 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
+
+ */
+import { FiberNode } from './types';
+/**
+ * Validation error with component stack trace
+ * REQ-NF-03.1: Enhanced error messages with file and line trace
+ */
+export declare class ValidationError extends Error {
+    componentStack: string[];
+    filePath?: string | undefined;
+    lineNumber?: number | undefined;
+    constructor(message: string, componentStack: string[], filePath?: string | undefined, lineNumber?: number | undefined);
+    /**
+     * Get a quick summary of the error for dev tools
+     * REQ-NF-03.1: Enhanced error messages
+     */
+    get summary(): string;
+    private formatError;
+}
+/**
+ * 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
+ */
+export declare class Validator {
+    /**
+     * Validate a Fiber tree
+     *
+     * @param fiber - Root Fiber node to validate
+     * @throws ValidationError if validation fails
+     */
+    validate(fiber: FiberNode | null): void;
+    /**
+     * 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
+     */
+    private validateNode;
+    /**
+     * 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
+     */
+    private validateRequiredProps;
+    /**
+     * 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
+     */
+    private validateContextAvailable;
+    /**
+     * 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
+     */
+    private getRequiredProps;
+    /**
+     * Get component name for error reporting
+     *
+     * @param node - Fiber node
+     * @returns Component name
+     */
+    private getComponentName;
+    /**
+     * 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
+     */
+    private getFilePath;
+    /**
+     * Get line number from Fiber node (if available)
+     *
+     * @param node - Fiber node
+     * @returns Line number or undefined
+     */
+    private getLineNumber;
+}