@nikkory/vibe-engine 4.0.0

package/dist/utils/factor-resolver.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Factor Resolver - Dynamic Factor Resolution for Granularity Levels
+ *
+ * This module provides functions to dynamically resolve which factors
+ * apply at each granularity level based on factor definitions with
+ * `level` and `cascadeDown` fields.
+ *
+ * Key Functions:
+ * - `getFactorsForLevel()` - Get all applicable factors for a level
+ * - `getFactorDefinition()` - Get a single factor by ID
+ * - `resolveFactorValue()` - Resolve a factor's value with cascade logic
+ *
+ * @packageDocumentation
+ * @module utils/factor-resolver
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { DesignSystem } from '../types';
+import type { GranularityFactorCategory, GranularityFactorDefinition, GranularityFactorValues, GranularityLevel } from '../types/granularity';
+/**
+ * Get all factors applicable at a given granularity level
+ *
+ * This function dynamically resolves which factors apply at a level by:
+ * 1. Including factors defined at the exact level
+ * 2. Including factors from higher levels that have `cascadeDown: true`
+ *
+ * This REPLACES hardcoded 8/13/24 factor arrays with dynamic resolution.
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level to query
+ * @returns Array of factor definitions applicable at this level
+ *
+ * @example
+ * ```typescript
+ * // Template level gets 8 factors (defined at template level)
+ * const templateFactors = getFactorsForLevel('template');
+ * console.log(templateFactors.length); // 8
+ *
+ * // Page level gets template factors + page-specific = 13
+ * const pageFactors = getFactorsForLevel('page');
+ * console.log(pageFactors.length); // 13
+ *
+ * // Section level gets cascading + section-specific = 18
+ * const sectionFactors = getFactorsForLevel('section');
+ * console.log(sectionFactors.length); // 18
+ *
+ * // Component level gets all 24 factors
+ * const componentFactors = getFactorsForLevel('component');
+ * console.log(componentFactors.length); // 24
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getFactorsForLevel(level: GranularityLevel): readonly GranularityFactorDefinition[];
+/**
+ * Get factor IDs applicable at a given granularity level
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level to query
+ * @returns Array of factor IDs applicable at this level
+ *
+ * @example
+ * ```typescript
+ * const pageFactorIds = getFactorIdsForLevel('page');
+ * console.log(pageFactorIds); // ['colorPrimary', 'spacing', ...]
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getFactorIdsForLevel(level: GranularityLevel): readonly string[];
+/**
+ * Get a factor definition by ID
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param factorId - The factor ID to look up
+ * @returns The factor definition
+ * @throws Error if factor not found
+ *
+ * @example
+ * ```typescript
+ * const factor = getFactorDefinition('spacing');
+ * console.log(factor.level); // 'template'
+ * console.log(factor.cascadeDown); // true
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getFactorDefinition(factorId: string): GranularityFactorDefinition;
+/**
+ * Safely get a factor definition by ID (returns undefined if not found)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param factorId - The factor ID to look up
+ * @returns The factor definition or undefined
+ *
+ * @example
+ * ```typescript
+ * const factor = tryGetFactorDefinition('spacing');
+ * if (factor) {
+ *   console.log(factor.name);
+ * }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function tryGetFactorDefinition(factorId: string): GranularityFactorDefinition | undefined;
+/**
+ * Get all factor IDs in the registry
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @returns Array of all registered factor IDs
+ *
+ * Powered by Nikkory
+ */
+export declare function getAllFactorIds(): readonly string[];
+/**
+ * Options for resolving factor values
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface ResolveFactorOptions {
+    /** Design system for default values */
+    readonly designSystem: DesignSystem;
+    /** Parent factor values (for cascade) */
+    readonly parentFactors?: GranularityFactorValues;
+    /** Explicit overrides (highest priority) */
+    readonly overrides?: GranularityFactorValues;
+}
+/**
+ * Resolve a single factor's value with cascade priority
+ *
+ * Priority order (highest to lowest):
+ * 1. Explicit overrides
+ * 2. Parent cascaded values
+ * 3. Design system defaults
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param factorId - The factor ID to resolve
+ * @param options - Resolution options
+ * @returns The resolved value
+ *
+ * @example
+ * ```typescript
+ * const value = resolveFactorValue('spacing', {
+ *   designSystem: 'material-design',
+ *   parentFactors: { spacing: 'lg' },
+ *   overrides: { spacing: 'xl' }
+ * });
+ * console.log(value); // 'xl' (override wins)
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function resolveFactorValue(factorId: string, options: ResolveFactorOptions): unknown;
+/**
+ * Resolve all factors for a level with cascade
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level
+ * @param options - Resolution options
+ * @returns Object with all resolved factor values
+ *
+ * @example
+ * ```typescript
+ * const values = resolveAllFactors('section', {
+ *   designSystem: 'material-design',
+ *   parentFactors: { spacing: 'lg', theme: 'dark' }
+ * });
+ * console.log(values.spacing); // 'lg' (cascaded from parent)
+ * console.log(values.gridColumns); // 12 (default)
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function resolveAllFactors(level: GranularityLevel, options: ResolveFactorOptions): GranularityFactorValues;
+/**
+ * Filter factors by category for a given level
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level
+ * @param categories - Categories to include
+ * @returns Filtered factors
+ *
+ * @example
+ * ```typescript
+ * const visualFactors = filterFactorsByCategory('section', ['visual']);
+ * console.log(visualFactors.length); // Visual factors applicable at section level
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function filterFactorsByCategory(level: GranularityLevel, categories: readonly GranularityFactorCategory[]): readonly GranularityFactorDefinition[];
+/**
+ * Filter factors that cascade down
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level
+ * @returns Only factors that cascade to child levels
+ *
+ * @example
+ * ```typescript
+ * const cascading = getCascadingFactors('page');
+ * // Returns page-level factors that will cascade to sections
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getCascadingFactors(level: GranularityLevel): readonly GranularityFactorDefinition[];
+/**
+ * Filter factors that do NOT cascade down
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level
+ * @returns Only factors that are local to this level
+ *
+ * @example
+ * ```typescript
+ * const local = getLocalFactors('section');
+ * // Returns section-specific factors that don't cascade
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getLocalFactors(level: GranularityLevel): readonly GranularityFactorDefinition[];
+/**
+ * Get factor count for a level (for debugging/display)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level
+ * @returns Number of applicable factors
+ *
+ * @example
+ * ```typescript
+ * getFactorCountForLevel('template'); // 8
+ * getFactorCountForLevel('page');     // 13
+ * getFactorCountForLevel('section');  // 18
+ * getFactorCountForLevel('component'); // 24
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getFactorCountForLevel(level: GranularityLevel): number;
+/**
+ * Get factor count breakdown by level
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @returns Object with factor counts per level
+ *
+ * @example
+ * ```typescript
+ * const counts = getFactorCountsByLevel();
+ * console.log(counts);
+ * // {
+ * //   template: 8,
+ * //   layout: 8,
+ * //   page: 13,
+ * //   section: 18,
+ * //   component: 24,
+ * //   atom: 24
+ * // }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getFactorCountsByLevel(): Record<GranularityLevel, number>;
+//# sourceMappingURL=factor-resolver.d.ts.map

package/dist/utils/granularity-helpers.d.ts

@@ -0,0 +1,359 @@
+/**
+ * Granularity Helpers - Utility Functions for Granularity Level Operations
+ *
+ * This module provides helper functions for working with the 6-level
+ * granularity hierarchy:
+ * - Comparing levels (isHigherGranularity, isLowerGranularity)
+ * - Finding child/parent levels (getChildGranularities, getParentGranularity)
+ * - Level validation and lookup
+ *
+ * @packageDocumentation
+ * @module utils/granularity-helpers
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { GranularityLevel } from '../types/granularity';
+/**
+ * Check if level A is higher than level B in the hierarchy
+ *
+ * Template (6) > Layout (5) > Page (4) > Section (3) > Component (2) > Atom (1)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param levelA - First granularity level
+ * @param levelB - Second granularity level
+ * @returns True if levelA is higher than levelB
+ *
+ * @example
+ * ```typescript
+ * isHigherGranularity('template', 'page'); // true
+ * isHigherGranularity('section', 'page');  // false
+ * isHigherGranularity('page', 'page');     // false
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function isHigherGranularity(levelA: GranularityLevel, levelB: GranularityLevel): boolean;
+/**
+ * Check if level A is lower than level B in the hierarchy
+ *
+ * Atom (1) < Component (2) < Section (3) < Page (4) < Layout (5) < Template (6)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param levelA - First granularity level
+ * @param levelB - Second granularity level
+ * @returns True if levelA is lower than levelB
+ *
+ * @example
+ * ```typescript
+ * isLowerGranularity('atom', 'component'); // true
+ * isLowerGranularity('page', 'section');   // false
+ * isLowerGranularity('page', 'page');      // false
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function isLowerGranularity(levelA: GranularityLevel, levelB: GranularityLevel): boolean;
+/**
+ * Check if two levels are at the same rank
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param levelA - First granularity level
+ * @param levelB - Second granularity level
+ * @returns True if levels are the same
+ *
+ * @example
+ * ```typescript
+ * isSameGranularity('page', 'page');     // true
+ * isSameGranularity('page', 'section');  // false
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function isSameGranularity(levelA: GranularityLevel, levelB: GranularityLevel): boolean;
+/**
+ * Check if level A is higher than or equal to level B
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param levelA - First granularity level
+ * @param levelB - Second granularity level
+ * @returns True if levelA is >= levelB
+ *
+ * @example
+ * ```typescript
+ * isHigherOrEqualGranularity('page', 'section'); // true
+ * isHigherOrEqualGranularity('page', 'page');    // true
+ * isHigherOrEqualGranularity('section', 'page'); // false
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function isHigherOrEqualGranularity(levelA: GranularityLevel, levelB: GranularityLevel): boolean;
+/**
+ * Check if level A is lower than or equal to level B
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param levelA - First granularity level
+ * @param levelB - Second granularity level
+ * @returns True if levelA is <= levelB
+ *
+ * @example
+ * ```typescript
+ * isLowerOrEqualGranularity('section', 'page'); // true
+ * isLowerOrEqualGranularity('page', 'page');    // true
+ * isLowerOrEqualGranularity('page', 'section'); // false
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function isLowerOrEqualGranularity(levelA: GranularityLevel, levelB: GranularityLevel): boolean;
+/**
+ * Get all granularity levels that can be children of a given level
+ *
+ * Children are all levels LOWER than the parent level.
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param parentLevel - The parent granularity level
+ * @returns Array of child granularity levels (lower levels)
+ *
+ * @example
+ * ```typescript
+ * getChildGranularities('page');
+ * // ['section', 'component', 'atom']
+ *
+ * getChildGranularities('section');
+ * // ['component', 'atom']
+ *
+ * getChildGranularities('atom');
+ * // [] (atom has no children)
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getChildGranularities(parentLevel: GranularityLevel): readonly GranularityLevel[];
+/**
+ * Get the immediate child level (one level down)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The current granularity level
+ * @returns The immediate child level, or undefined if at lowest level
+ *
+ * @example
+ * ```typescript
+ * getImmediateChildLevel('page');     // 'section'
+ * getImmediateChildLevel('section');  // 'component'
+ * getImmediateChildLevel('atom');     // undefined
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getImmediateChildLevel(level: GranularityLevel): GranularityLevel | undefined;
+/**
+ * Get the parent level (one level up)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The current granularity level
+ * @returns The parent level, or undefined if at highest level
+ *
+ * @example
+ * ```typescript
+ * getParentGranularity('section');  // 'page'
+ * getParentGranularity('page');     // 'layout'
+ * getParentGranularity('template'); // undefined
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getParentGranularity(level: GranularityLevel): GranularityLevel | undefined;
+/**
+ * Get all ancestor levels (all levels higher than the given level)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The current granularity level
+ * @returns Array of ancestor levels (higher levels)
+ *
+ * @example
+ * ```typescript
+ * getAncestorGranularities('section');
+ * // ['template', 'layout', 'page']
+ *
+ * getAncestorGranularities('template');
+ * // [] (template has no ancestors)
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getAncestorGranularities(level: GranularityLevel): readonly GranularityLevel[];
+/**
+ * Check if a string is a valid granularity level
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid GranularityLevel
+ *
+ * @example
+ * ```typescript
+ * isValidGranularityLevel('page');    // true
+ * isValidGranularityLevel('invalid'); // false
+ * isValidGranularityLevel(123);       // false
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function isValidGranularityLevel(value: unknown): value is GranularityLevel;
+/**
+ * Assert that a value is a valid granularity level
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param value - The value to check
+ * @throws Error if not a valid granularity level
+ *
+ * @example
+ * ```typescript
+ * assertGranularityLevel('page'); // OK
+ * assertGranularityLevel('invalid'); // throws Error
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function assertGranularityLevel(value: unknown): asserts value is GranularityLevel;
+/**
+ * Get all granularity levels
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @returns All 6 granularity levels in hierarchy order (highest to lowest)
+ *
+ * @example
+ * ```typescript
+ * getAllGranularityLevels();
+ * // ['template', 'layout', 'page', 'section', 'component', 'atom']
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getAllGranularityLevels(): readonly GranularityLevel[];
+/**
+ * Get the distance between two levels in the hierarchy
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param levelA - First granularity level
+ * @param levelB - Second granularity level
+ * @returns Number of levels between (positive if A > B, negative if A < B)
+ *
+ * @example
+ * ```typescript
+ * getLevelDistance('page', 'section');    // 1
+ * getLevelDistance('template', 'atom');   // 5
+ * getLevelDistance('section', 'page');    // -1
+ * getLevelDistance('page', 'page');       // 0
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getLevelDistance(levelA: GranularityLevel, levelB: GranularityLevel): number;
+/**
+ * Check if a child level can be placed in a parent level
+ *
+ * A child can be placed in a parent if the child is at a LOWER level.
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param parentLevel - The parent granularity level
+ * @param childLevel - The child granularity level
+ * @returns True if child can be placed in parent
+ *
+ * @example
+ * ```typescript
+ * canContain('page', 'section');    // true
+ * canContain('section', 'page');    // false
+ * canContain('section', 'section'); // false
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function canContain(parentLevel: GranularityLevel, childLevel: GranularityLevel): boolean;
+/**
+ * Get the highest level in the hierarchy
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @returns The highest granularity level ('template')
+ *
+ * @example
+ * ```typescript
+ * getHighestLevel(); // 'template'
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getHighestLevel(): GranularityLevel;
+/**
+ * Get the lowest level in the hierarchy
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @returns The lowest granularity level ('atom')
+ *
+ * @example
+ * ```typescript
+ * getLowestLevel(); // 'atom'
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getLowestLevel(): GranularityLevel;
+/**
+ * Get levels between two levels (exclusive)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param higherLevel - The higher level
+ * @param lowerLevel - The lower level
+ * @returns Levels between (not including the endpoints)
+ *
+ * @example
+ * ```typescript
+ * getLevelsBetween('template', 'section');
+ * // ['layout', 'page']
+ *
+ * getLevelsBetween('page', 'component');
+ * // ['section']
+ *
+ * getLevelsBetween('page', 'section');
+ * // [] (adjacent levels)
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getLevelsBetween(higherLevel: GranularityLevel, lowerLevel: GranularityLevel): readonly GranularityLevel[];
+//# sourceMappingURL=granularity-helpers.d.ts.map

package/dist/utils/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared Utilities
+ *
+ * @packageDocumentation
+ * @module utils
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export * from './StringUtils';
+export * from './CodeUtils';
+export * from './ValidationUtils';
+export * from './Logger';
+export * from './GenerateComponentValidator';
+export * from './performance';
+export * from './stringify';
+export { getFactorsForLevel, getFactorIdsForLevel, getFactorDefinition as getGranularityFactorDefinition, tryGetFactorDefinition, getAllFactorIds as getAllResolverFactorIds, resolveFactorValue, resolveAllFactors, filterFactorsByCategory, getCascadingFactors, getLocalFactors, getFactorCountForLevel, getFactorCountsByLevel, } from './factor-resolver';
+export type { ResolveFactorOptions } from './factor-resolver';
+export { isHigherGranularity, isLowerGranularity, isSameGranularity, isHigherOrEqualGranularity, isLowerOrEqualGranularity, getChildGranularities, getImmediateChildLevel, getParentGranularity, getAncestorGranularities, isValidGranularityLevel, assertGranularityLevel, getAllGranularityLevels, getLevelDistance, canContain, getHighestLevel, getLowestLevel, getLevelsBetween, } from './granularity-helpers';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/performance.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Performance Utilities
+ *
+ * Cross-platform performance measurement utilities.
+ *
+ * @packageDocumentation
+ * @module utils/performance
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+/**
+ * Get high-resolution timestamp.
+ * Uses performance.now() in browsers, Date.now() in Node.js.
+ *
+ * @returns Timestamp in milliseconds
+ *
+ * @example
+ * ```typescript
+ * const start = now();
+ * // ... operations ...
+ * const duration = now() - start;
+ * ```
+ */
+export declare function now(): number;
+//# sourceMappingURL=performance.d.ts.map