visualifyjs 2.5.3 → 3.0.0

package/src/cli/utils/config.js

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview Configuration utilities for Visualify CLI
+ * @module cli/utils/config
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const logger = require('./logger');
+
+/**
+ * Configuration file names to search for
+ * @readonly
+ * @type {string[]}
+ */
+const CONFIG_FILES = ['visualify.json', '.visualify.json'];
+
+/**
+ * Default configuration values
+ * @readonly
+ * @type {Object}
+ */
+const DEFAULT_CONFIG = {
+	mode: 'auto',
+	port: 3000,
+	host: 'localhost',
+};
+
+/**
+ * Check if a file exists
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>} Whether the file exists
+ */
+async function fileExists(filePath) {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Find the configuration file in the current directory
+ * @returns {Promise<string|null>} Path to config file or null
+ */
+async function findConfigFile() {
+	const cwd = process.cwd();
+
+	for (const configFile of CONFIG_FILES) {
+		const configPath = path.join(cwd, configFile);
+		if (await fileExists(configPath)) {
+			logger.debug(`Found config file: ${configPath}`);
+			return configPath;
+		}
+	}
+
+	logger.debug('No config file found');
+	return null;
+}
+
+/**
+ * Load and parse the configuration file
+ * @param {string} [configPath] - Path to config file (optional)
+ * @returns {Promise<Object>} Merged configuration object
+ */
+async function loadConfig(configPath) {
+	const targetPath = configPath || (await findConfigFile());
+
+	if (!targetPath) {
+		logger.debug('Using default configuration');
+		return { ...DEFAULT_CONFIG };
+	}
+
+	try {
+		const content = await fs.readFile(targetPath, 'utf-8');
+		const parsed = JSON.parse(content);
+		logger.debug(`Loaded config from ${targetPath}`);
+
+		return {
+			...DEFAULT_CONFIG,
+			...parsed,
+		};
+	} catch (err) {
+		if (err instanceof SyntaxError) {
+			logger.error(`Invalid JSON in config file: ${targetPath}`);
+			throw new Error(`Failed to parse config file: ${err.message}`);
+		}
+		logger.error(`Failed to read config file: ${targetPath}`);
+		throw err;
+	}
+}
+
+/**
+ * Detect the project mode based on file structure
+ * @returns {Promise<string>} Detected mode ('docs' or 'portal')
+ */
+async function detectMode() {
+	const cwd = process.cwd();
+	logger.debug('Detecting mode from file structure...');
+
+	// Check for docs directory with markdown files
+	const docsPath = path.join(cwd, 'docs');
+	if (await fileExists(docsPath)) {
+		try {
+			const files = await fs.readdir(docsPath);
+			const hasMarkdown = files.some(
+				(file) => file.endsWith('.md') || file.endsWith('.mdx')
+			);
+			if (hasMarkdown) {
+				logger.debug('Found docs directory with markdown files');
+				return 'docs';
+			}
+		} catch (err) {
+			logger.debug('Error reading docs directory:', err.message);
+		}
+	}
+
+	// Check for portal indicators
+	const portalIndicators = [
+		'src/pages',
+		'src/routes',
+		'visualify.config.js',
+		'src/App.jsx',
+		'src/App.tsx',
+	];
+
+	for (const indicator of portalIndicators) {
+		const indicatorPath = path.join(cwd, indicator);
+		if (await fileExists(indicatorPath)) {
+			logger.debug(`Found portal indicator: ${indicator}`);
+			return 'portal';
+		}
+	}
+
+	// Default to docs if we can't determine
+	logger.debug('Could not detect mode, defaulting to docs');
+	logger.warn('Could not auto-detect project mode, defaulting to docs');
+	logger.tip('Create a visualify.json file to specify mode explicitly');
+	return 'docs';
+}
+
+/**
+ * Get the configured mode from config or auto-detect
+ * @returns {Promise<string>} The mode to use
+ */
+async function getMode() {
+	const config = await loadConfig();
+
+	if (config.mode && config.mode !== 'auto') {
+		logger.debug(`Using configured mode: ${config.mode}`);
+		return config.mode;
+	}
+
+	return detectMode();
+}
+
+/**
+ * Save configuration to file
+ * @param {Object} config - Configuration object to save
+ * @param {string} [configPath] - Path to save to (defaults to visualify.json)
+ * @returns {Promise<void>}
+ */
+async function saveConfig(config, configPath = 'visualify.json') {
+	try {
+		const content = JSON.stringify(config, null, 2);
+		await fs.writeFile(configPath, content, 'utf-8');
+		logger.debug(`Saved config to ${configPath}`);
+	} catch (err) {
+		logger.error(`Failed to save config to ${configPath}:`, err.message);
+		throw err;
+	}
+}
+
+/**
+ * Validate configuration object
+ * @param {Object} config - Configuration to validate
+ * @returns {Object} Validation result with isValid and errors
+ */
+function validateConfig(config) {
+	const errors = [];
+	const validModes = ['auto', 'docs', 'portal'];
+
+	if (config.mode && !validModes.includes(config.mode)) {
+		errors.push(`Invalid mode: "${config.mode}". Must be one of: ${validModes.join(', ')}`);
+	}
+
+	if (config.port && (typeof config.port !== 'number' || config.port < 1 || config.port > 65535)) {
+		errors.push('Invalid port: must be a number between 1 and 65535');
+	}
+
+	return {
+		isValid: errors.length === 0,
+		errors,
+	};
+}
+
+module.exports = {
+	CONFIG_FILES,
+	DEFAULT_CONFIG,
+	fileExists,
+	findConfigFile,
+	loadConfig,
+	detectMode,
+	getMode,
+	saveConfig,
+	validateConfig,
+};

package/src/cli/utils/logger.js

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview Colored logging utility for Visualify CLI with i18n support
+ * @module cli/utils/logger
+ */
+
+const chalk = require('chalk');
+
+// Simple i18n for CLI (Node.js compatible)
+let currentLocale = 'en';
+const translations = {};
+
+/**
+ * Load translations for a locale
+ * @param {string} locale - Locale code
+ * @param {Object} messages - Translation messages
+ */
+function loadTranslations(locale, messages) {
+  translations[locale] = { ...translations[locale], ...messages };
+}
+
+/**
+ * Set the current locale for CLI messages
+ * @param {string} locale - Locale code
+ */
+function setLocale(locale) {
+  currentLocale = locale;
+}
+
+/**
+ * Get the current locale
+ * @returns {string} Current locale code
+ */
+function getLocale() {
+  return currentLocale;
+}
+
+/**
+ * Translate a key with optional interpolation
+ * @param {string} key - Translation key
+ * @param {Object} params - Interpolation parameters
+ * @returns {string} Translated string
+ */
+function t(key, params = {}) {
+  const messages = translations[currentLocale] || translations['en'] || {};
+  let message = key.split('.').reduce((obj, k) => obj?.[k], messages) || key;
+
+  // Simple interpolation: {key} -> value
+  Object.keys(params).forEach((param) => {
+    message = message.replace(new RegExp(`{${param}}`, 'g'), params[param]);
+  });
+
+  return message;
+}
+
+// Load default English translations
+loadTranslations('en', {
+  cli: {
+    debug: 'debug',
+    info: 'info',
+    warn: 'warn',
+    error: 'error',
+    success: 'success',
+    tip: 'tip',
+  },
+});
+
+loadTranslations('zh', {
+  cli: {
+    debug: '调试',
+    info: '信息',
+    warn: '警告',
+    error: '错误',
+    success: '成功',
+    tip: '提示',
+  },
+});
+
+loadTranslations('es', {
+  cli: {
+    debug: 'depurar',
+    info: 'info',
+    warn: 'advertencia',
+    error: 'error',
+    success: 'éxito',
+    tip: 'consejo',
+  },
+});
+
+loadTranslations('de', {
+  cli: {
+    debug: 'debug',
+    info: 'info',
+    warn: 'warnung',
+    error: 'fehler',
+    success: 'erfolg',
+    tip: 'tipp',
+  },
+});
+
+/**
+ * Log level constants
+ * @readonly
+ * @enum {number}
+ */
+const LOG_LEVELS = {
+	DEBUG: 0,
+	INFO: 1,
+	WARN: 2,
+	ERROR: 3,
+	SUCCESS: 4,
+};
+
+/**
+ * Current log level (can be overridden by --verbose flag)
+ * @type {number}
+ */
+let currentLogLevel = LOG_LEVELS.INFO;
+
+/**
+ * Set the minimum log level for output
+ * @param {number} level - The log level to set
+ */
+function setLogLevel(level) {
+	currentLogLevel = level;
+}
+
+/**
+ * Enable verbose/debug mode
+ */
+function enableVerbose() {
+	currentLogLevel = LOG_LEVELS.DEBUG;
+}
+
+/**
+ * Check if a message should be logged based on current level
+ * @param {number} level - The level of the message
+ * @returns {boolean} Whether the message should be logged
+ */
+function shouldLog(level) {
+	return level >= currentLogLevel;
+}
+
+/**
+ * Print a debug message (gray)
+ * @param {...any} args - Messages to log
+ */
+function debug(...args) {
+	if (!shouldLog(LOG_LEVELS.DEBUG)) return;
+	console.log(chalk.gray(`[${t('cli.debug')}]`), ...args);
+}
+
+/**
+ * Print an info message (cyan)
+ * @param {...any} args - Messages to log
+ */
+function info(...args) {
+	if (!shouldLog(LOG_LEVELS.INFO)) return;
+	console.log(chalk.cyan(`[${t('cli.info')}]`), ...args);
+}
+
+/**
+ * Print a warning message (yellow)
+ * @param {...any} args - Messages to log
+ */
+function warn(...args) {
+	if (!shouldLog(LOG_LEVELS.WARN)) return;
+	console.warn(chalk.yellow(`[${t('cli.warn')}]`), ...args);
+}
+
+/**
+ * Print an error message (red)
+ * @param {...any} args - Messages to log
+ */
+function error(...args) {
+	if (!shouldLog(LOG_LEVELS.ERROR)) return;
+	console.error(chalk.red(`[${t('cli.error')}]`), ...args);
+}
+
+/**
+ * Print a success message (green)
+ * @param {...any} args - Messages to log
+ */
+function success(...args) {
+	if (!shouldLog(LOG_LEVELS.SUCCESS)) return;
+	console.log(chalk.green(`[${t('cli.success')}]`), ...args);
+}
+
+/**
+ * Print a newline
+ */
+function newline() {
+	console.log();
+}
+
+/**
+ * Print a section header (bold white)
+ * @param {string} title - The section title
+ */
+function header(title) {
+	console.log(chalk.bold.white(`\n${title}\n`));
+}
+
+/**
+ * Print a command example (dim)
+ * @param {string} command - The command to display
+ * @param {string} [description] - Optional description
+ */
+function example(command, description) {
+	if (description) {
+		console.log(chalk.dim(`  $ ${command}`), chalk.gray(`- ${description}`));
+	} else {
+		console.log(chalk.dim(`  $ ${command}`));
+	}
+}
+
+/**
+ * Print a tip/suggestion (magenta)
+ * @param {string} message - The tip message
+ */
+function tip(message) {
+	console.log(chalk.magenta(`[${t('cli.tip')}]`), message);
+}
+
+module.exports = {
+	LOG_LEVELS,
+	setLogLevel,
+	enableVerbose,
+	debug,
+	info,
+	warn,
+	error,
+	success,
+	newline,
+	header,
+	example,
+	tip,
+	setLocale,
+	getLocale,
+	loadTranslations,
+	t,
+};

package/src/config/defaults.ts

@@ -0,0 +1,122 @@
+/**
+ * Default configuration values for Visualify.js
+ * @module defaults
+ */
+
+import { VisualifyConfig } from '../../types';
+
+/**
+ * Complete default configuration object for Visualify.js
+ * These values are used when not specified in visualify.json or overrides
+ *
+ * @example
+ * ```typescript
+ * import defaults from './defaults';
+ *
+ * const config = {
+ *   ...defaults,
+ *   mode: 'portal' // Override specific values
+ * };
+ * ```
+ */
+const defaults: VisualifyConfig = {
+	/**
+	 * Schema version - must match the expected version for compatibility
+	 */
+	version: '3.0.0',
+
+	/**
+	 * Application mode - determines how Visualify operates
+	 * - 'docs': Documentation mode with markdown rendering
+	 * - 'portal': Full portal mode with navigation
+	 * - 'hybrid': Combined docs and portal
+	 * - 'auto': Automatically detect based on content
+	 */
+	mode: 'auto',
+
+	/**
+	 * Documentation configuration
+	 */
+	docs: {
+		/**
+		 * Base path for documentation files
+		 */
+		basePath: './docs',
+
+		/**
+		 * Documentation theme
+		 */
+		theme: 'vue',
+
+		/**
+		 * List of plugin modules to load
+		 */
+		plugins: [],
+	},
+
+	/**
+	 * Portal configuration
+	 */
+	portal: {
+		/**
+		 * Homepage configuration file
+		 */
+		homepage: 'home.json',
+
+		/**
+		 * Portal theme
+		 */
+		theme: 'modern',
+
+		/**
+		 * Data sources for the portal
+		 */
+		dataSources: [],
+	},
+
+	/**
+	 * Visualization configuration
+	 */
+	visualization: {
+		/**
+		 * Default charting library
+		 * - 'echarts': Apache ECharts (default)
+		 * - 'plotly': Plotly.js
+		 */
+		defaultLibrary: 'echarts',
+
+		/**
+		 * Enable 3D visualization capabilities
+		 */
+		enable3D: false,
+
+		/**
+		 * Use Web Workers for rendering (improves performance)
+		 */
+		webWorkers: false,
+	},
+
+	/**
+	 * Internationalization (i18n) configuration
+	 */
+	i18n: {
+		/**
+		 * Locale setting
+		 * - 'auto': Automatically detect from browser
+		 * - 'en', 'zh', 'es', 'de', 'ar', 'he': Specific language
+		 */
+		locale: 'auto',
+
+		/**
+		 * Fallback locale when translation is missing
+		 */
+		fallbackLocale: 'en',
+
+		/**
+		 * Enable RTL (Right-to-Left) layout support
+		 */
+		enableRTL: true,
+	},
+};
+
+export default defaults;

package/src/config/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Visualify.js Configuration System
+ *
+ * This module provides configuration management for Visualify.js applications.
+ * It supports loading from files, environment variables, and CLI arguments with
+ * proper validation using JSON Schema.
+ *
+ * @module config
+ * @example
+ * ```typescript
+ * import { loadConfig, validateConfig, defaults } from './config';
+ *
+ * // Load and validate configuration
+ * const config = await loadConfig(process.cwd(), cliArgs);
+ *
+ * // Validate custom configuration
+ * const result = validateConfig(myConfig);
+ * if (!result.valid) {
+ *   console.error(result.errors);
+ * }
+ * ```
+ */
+
+// Export defaults
+export { default as defaults } from './defaults';
+
+// Export schema
+export { default as schema } from './schema';
+export type { SchemaType } from './schema';
+
+// Export validation functions
+export {
+	validateConfig,
+	validateProperty,
+	isVersionCompatible,
+	isValidConfig,
+	ERROR_TEMPLATES,
+	SUGGESTED_FIXES,
+} from './validator';
+
+// Export loading functions and constants
+export {
+	loadConfig,
+	watchConfig,
+	findConfigFile,
+	loadConfigFile,
+	loadEnvironmentConfig,
+	clearCache,
+	getCacheStats,
+	deepMerge,
+	ConfigLoadError,
+	CONFIG_FILES,
+	ENV_PREFIX,
+} from './loader';
+
+// Re-export types
+export type {
+	VisualifyConfig,
+	DocsConfig,
+	PortalConfig,
+	VisualizationConfig,
+	DataSource,
+	AppMode,
+	ChartLibrary,
+	DataSourceType,
+	LoadConfigOptions,
+	ConfigCacheEntry,
+	CacheStats,
+	ConfigWatcher,
+	ConfigReloadCallback,
+	PartialConfig,
+} from '../../types';