juxscript 1.1.0 → 1.1.2

package/machinery/doc-generator.js

@@ -0,0 +1,136 @@
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+
+/**
+ * Generate documentation from TypeScript component files
+ * 
+ * @param {string} juxLibPath - Absolute path to jux/lib directory
+ */
+export async function generateDocs(juxLibPath) {
+  const componentsDir = path.join(juxLibPath, 'components');
+  
+  if (!fs.existsSync(componentsDir)) {
+    throw new Error(`Components directory not found: ${componentsDir}`);
+  }
+  
+  console.log(`  Scanning: ${componentsDir}`);
+  
+  // Find all component TypeScript files
+  const componentFiles = glob.sync('*.ts', {
+    cwd: componentsDir,
+    absolute: true,
+    ignore: ['reactivity.ts', 'error-handler.ts']
+  });
+
+  console.log(`  Found ${componentFiles.length} component files`);
+
+  const components = [];
+
+  for (const filePath of componentFiles) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const componentDoc = parseComponentFile(content, filePath);
+    
+    if (componentDoc) {
+      components.push(componentDoc);
+      console.log(`    ✓ ${componentDoc.name}`);
+    }
+  }
+
+  // Sort by category and name
+  components.sort((a, b) => {
+    const categoryCompare = (a.category || 'ZZZ').localeCompare(b.category || 'ZZZ');
+    if (categoryCompare !== 0) return categoryCompare;
+    return a.name.localeCompare(b.name);
+  });
+
+  // Generate the docs data
+  const docsData = {
+    components,
+    version: '1.0.0',
+    lastUpdated: new Date().toISOString()
+  };
+
+  // Write to JSON file
+  const outputPath = path.join(componentsDir, 'docs-data.json');
+  fs.writeFileSync(outputPath, JSON.stringify(docsData, null, 2));
+  
+  console.log(`  Generated: ${outputPath}`);
+  
+  return docsData;
+}
+
+/**
+ * Parse a single component file
+ */
+function parseComponentFile(content, filePath) {
+  const fileName = path.basename(filePath, '.ts');
+  const className = fileName.charAt(0).toUpperCase() + fileName.slice(1);
+  
+  const category = inferCategory(className, content);
+  const descMatch = content.match(/\/\*\*\s*\n\s*\*\s*([^\n*]+)/);
+  const description = descMatch ? descMatch[1].trim() : `${className} component`;
+  const factoryMatch = content.match(/export function\s+\w+\(([^)]*)\)/);
+  const constructorSig = factoryMatch 
+    ? `jux.${fileName}(${factoryMatch[1]})`
+    : `new ${className}()`;
+  const fluentMethods = extractFluentMethods(content, className);
+  const exampleMatch = content.match(/\*\s+Usage:\s*\n\s*\*\s+(.+?)(?:\n|$)/);
+  let example = exampleMatch 
+    ? exampleMatch[1].trim()
+    : `jux.${fileName}('id').render()`;
+  
+  return {
+    name: className,
+    category,
+    description,
+    constructor: constructorSig,
+    fluentMethods,
+    example
+  };
+}
+
+/**
+ * Extract fluent API methods from class
+ */
+function extractFluentMethods(content, className) {
+  const methods = [];
+  const methodRegex = /^\s*(\w+)\(([^)]*)\):\s*this\s*\{/gm;
+  let match;
+  
+  while ((match = methodRegex.exec(content)) !== null) {
+    const methodName = match[1];
+    const params = match[2];
+    if (methodName.startsWith('_') || methodName === 'constructor') continue;
+    const cleanParams = params.split(',').map(p => p.trim().split(':')[0].trim()).filter(p => p).join(', ');
+    methods.push({
+      name: methodName,
+      params: cleanParams ? `(${cleanParams})` : '()',
+      returns: 'this',
+      description: `Set ${methodName}`
+    });
+  }
+  
+  const renderMatch = content.match(/^\s*render\(([^)]*)\):\s*(\w+)/m);
+  if (renderMatch && !methods.find(m => m.name === 'render')) {
+    methods.push({
+      name: 'render',
+      params: renderMatch[1] ? `(${renderMatch[1]})` : '()',
+      returns: renderMatch[2],
+      description: 'Render component to DOM'
+    });
+  }
+  
+  return methods;
+}
+
+/**
+ * Infer category from component name or content
+ */
+function inferCategory(name, content) {
+  const dataComponents = ['Table', 'List', 'Chart', 'Data'];
+  const coreComponents = ['App', 'Layout', 'Theme', 'Style', 'Script', 'Import'];
+  if (dataComponents.some(dc => name.includes(dc))) return 'Data Components';
+  if (coreComponents.includes(name)) return 'Core';
+  return 'UI Components';
+}

package/machinery/imports.js

@@ -0,0 +1,155 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REGISTRY_PATH = path.join(__dirname, '../lib/registry/packages.json');
+
+/**
+ * Load package registry
+ */
+function loadRegistry() {
+  if (!fs.existsSync(REGISTRY_PATH)) {
+    return {};
+  }
+  return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf-8'));
+}
+
+/**
+ * Parse @import directives from Jux code
+ */
+export function parseImports(juxCode) {
+  const imports = [];
+  const lines = juxCode.split('\n');
+  
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    
+    // Stop parsing when we hit actual code (non-directive, non-comment)
+    if (line && !line.startsWith('@') && !line.startsWith('//') && !line.startsWith('/*')) {
+      break;
+    }
+    
+    // Match @import directive
+    const importMatch = line.match(/^@import\s+(.+)$/);
+    if (importMatch) {
+      const importSpec = importMatch[1].trim();
+      imports.push({
+        line: i + 1,
+        raw: importSpec,
+        resolved: resolveImport(importSpec)
+      });
+      
+      if (process.env.JUX_VERBOSE) {
+        console.log(`  [Line ${i + 1}] Found @import: ${importSpec}`);
+      }
+    }
+  }
+  
+  return imports;
+}
+
+/**
+ * Resolve import specification to URL/path
+ */
+export function resolveImport(importSpec) {
+  // Remove quotes if present
+  const cleaned = importSpec.replace(/^['"]|['"]$/g, '');
+  
+  // Direct URL (starts with http:// or https://)
+  if (cleaned.startsWith('http://') || cleaned.startsWith('https://')) {
+    return {
+      type: 'cdn',
+      url: cleaned,
+      source: 'direct'
+    };
+  }
+  
+  // Local file (starts with ./ or ../ or /)
+  if (cleaned.startsWith('./') || cleaned.startsWith('../') || cleaned.startsWith('/')) {
+    return {
+      type: 'local',
+      path: cleaned,
+      source: 'file'
+    };
+  }
+  
+  // Unknown/unsupported
+  return {
+    type: 'unknown',
+    name: cleaned,
+    error: `Import "${cleaned}" must be a URL (https://...) or relative path (./...)`
+  };
+}
+
+/**
+ * Auto-detect component dependencies
+ */
+function detectComponentDependencies(usedComponents) {
+  const componentDeps = {
+    'chart': 'chart.js'
+    // Add more mappings as needed
+  };
+  
+  const deps = new Set();
+  
+  usedComponents.forEach(comp => {
+    if (componentDeps[comp]) {
+      deps.add(componentDeps[comp]);
+    }
+  });
+  
+  return Array.from(deps).map(pkg => ({
+    auto: true,
+    resolved: resolveImport(pkg)
+  }));
+}
+
+/**
+ * Generate HTML script tags from resolved imports
+ */
+export function generateImportTags(imports) {
+  const tags = [];
+  const seen = new Set();
+  
+  for (const imp of imports) {
+    const resolved = imp.resolved;
+    
+    if (resolved.type === 'unknown') {
+      tags.push(`<!-- ERROR: ${resolved.error} -->`);
+      continue;
+    }
+    
+    const key = resolved.url || resolved.path;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    
+    if (resolved.type === 'cdn') {
+      tags.push(`  <script src="${resolved.url}"></script>`);
+    } else if (resolved.type === 'local') {
+      tags.push(`  <script type="module" src="${resolved.path}"></script>`);
+    }
+  }
+  
+  return tags.join('\n');
+}
+
+/**
+ * Validate all imports are resolvable
+ */
+export function validateImports(imports) {
+  const errors = [];
+  
+  imports.forEach(imp => {
+    if (imp.resolved.type === 'unknown') {
+      errors.push({
+        line: imp.line,
+        message: imp.resolved.error,
+        raw: imp.raw
+      });
+    }
+  });
+  
+  return errors;
+}

package/machinery/server.js

@@ -0,0 +1,166 @@
+import express from 'express';
+import http from 'http';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { startWatcher } from './watcher.js';
+import { WebSocketServer } from 'ws';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Try to start a server on a port, with fallback to next port if busy
+ * Returns the actual port that was successfully allocated
+ */
+async function tryPort(startPort, maxAttempts = 5, reservedPorts = []) {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const port = startPort + attempt;
+
+    // Skip if this port is already reserved
+    if (reservedPorts.includes(port)) {
+      continue;
+    }
+
+    try {
+      // Test if port is available
+      await new Promise((resolve, reject) => {
+        const testServer = http.createServer();
+        testServer.once('error', reject);
+        testServer.once('listening', () => {
+          testServer.close();
+          resolve(port);
+        });
+        testServer.listen(port);
+      });
+      return port;
+    } catch (err) {
+      if (err.code === 'EADDRINUSE') {
+        if (attempt < maxAttempts - 1) {
+          console.log(`   Port ${port} in use, trying ${port + 1}...`);
+        }
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error(`Could not find available port after ${maxAttempts} attempts starting from ${startPort}`);
+}
+
+async function serve(httpPort = 3000, wsPort = 3001, distDir = './.jux-dist') {
+  const app = express();
+  const absoluteDistDir = path.resolve(distDir);
+  const projectRoot = path.resolve('.');
+
+  app.use(express.json());
+
+  if (!fs.existsSync(absoluteDistDir)) {
+    console.error(`❌ Error: ${path.basename(distDir)}/ directory not found at ${absoluteDistDir}`);
+    console.error('   Run: npx jux build\n');
+    process.exit(1);
+  }
+
+  // Strong cache prevention
+  app.use((req, res, next) => {
+    res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0');
+    res.setHeader('Pragma', 'no-cache');
+    res.setHeader('Expires', '0');
+    res.setHeader('ETag', 'W/"' + Date.now() + '"');
+    next();
+  });
+
+  // ✅ ADD: Explicit MIME type for JavaScript files
+  app.use((req, res, next) => {
+    if (req.path.endsWith('.js')) {
+      res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+    }
+    next();
+  });
+
+  // Serve static files
+  app.use(express.static(absoluteDistDir));
+
+  // ✅ FIX: Only apply SPA fallback to routes, not static files
+  app.use((req, res, next) => {
+    // Skip SPA fallback for file extensions (static assets)
+    if (/\.[a-zA-Z0-9]+$/.test(req.path)) {
+      return res.status(404).send('File not found');
+    }
+
+    // SPA fallback for routes only
+    if (req.accepts('html')) {
+      const indexPath = path.join(absoluteDistDir, 'index.html');
+      if (fs.existsSync(indexPath)) {
+        res.sendFile(indexPath);
+      } else {
+        res.status(404).send('index.html not found. Run `npx jux build` first.');
+      }
+    } else {
+      res.status(404).send('Not found');
+    }
+  });
+
+  // Find available ports sequentially to avoid collision
+  console.log('🔍 Finding available ports...');
+
+  // First, find HTTP port
+  const availableHttpPort = await tryPort(httpPort);
+
+  // Then find WS port, excluding the HTTP port we just allocated
+  const availableWsPort = await tryPort(wsPort, 5, [availableHttpPort]);
+
+  // Create HTTP server
+  const server = http.createServer(app);
+
+  // WebSocket server for hot reload
+  const wss = new WebSocketServer({ port: availableWsPort });
+  const clients = [];
+
+  wss.on('connection', (ws) => {
+    clients.push(ws);
+    console.log('🔌 WebSocket client connected');
+
+    ws.on('close', () => {
+      console.log('🔌 WebSocket client disconnected');
+      const index = clients.indexOf(ws);
+      if (index > -1) clients.splice(index, 1);
+    });
+
+    ws.on('error', (error) => {
+      console.error('WebSocket error:', error);
+    });
+  });
+
+  console.log(`🔌 WebSocket server running at ws://localhost:${availableWsPort}`);
+
+  // Start HTTP server
+  server.listen(availableHttpPort, () => {
+    console.log(`🚀 JUX dev server running at http://localhost:${availableHttpPort}`);
+    console.log(`   Serving: ${absoluteDistDir}`);
+    console.log(`   Press Ctrl+C to stop\n`);
+  });
+
+  // Start file watcher
+  const juxSource = path.join(projectRoot, 'jux');
+  if (fs.existsSync(juxSource)) {
+    console.log(`👀 Watching: ${juxSource}\n`);
+    startWatcher(juxSource, absoluteDistDir, clients);
+  }
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.log('\n\n👋 Shutting down server...');
+    wss.close();
+    server.close();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  return { server, httpPort: availableHttpPort, wsPort: availableWsPort };
+}
+
+export async function start(httpPort = 3000, wsPort = 3001, distDir = './.jux-dist') {
+  return serve(httpPort, wsPort, distDir);
+}

package/machinery/ts-shim.js

@@ -0,0 +1,46 @@
+import esbuild from 'esbuild';
+
+/**
+ * TypeScript Shim - Strips type annotations using esbuild
+ * This is rock-solid and handles ALL TypeScript syntax correctly
+ */
+
+/**
+ * Strip TypeScript type annotations from code using esbuild
+ * 
+ * @param {string} code - TypeScript source code
+ * @returns {string} - JavaScript code with types removed
+ */
+export function stripTypes(code) {
+    try {
+        // ✅ Use esbuild to transform TypeScript → JavaScript
+        const result = esbuild.transformSync(code, {
+            loader: 'ts',
+            format: 'esm',
+            target: 'es2020'
+        });
+
+        return result.code;
+    } catch (err) {
+        console.error('❌ Failed to strip TypeScript:', err.message);
+        // Return original code if transformation fails
+        return code;
+    }
+}
+
+/**
+ * Check if a file is TypeScript based on extension
+ */
+export function isTypeScript(filePath) {
+    return filePath.endsWith('.ts') || filePath.endsWith('.tsx');
+}
+
+/**
+ * Load and parse a file, automatically stripping types if it's TypeScript
+ */
+export function loadAndStripTypes(filePath, fileContent) {
+    if (isTypeScript(filePath)) {
+        return stripTypes(fileContent);
+    }
+    return fileContent;
+}

package/machinery/validators/file-validator.js

@@ -0,0 +1,123 @@
+/**
+ * File validation utilities for Jux compiler
+ * Validates file types and content security
+ */
+export class FileValidator {
+  constructor() {
+    this.cssExtensions = /\.(css|scss|sass|less)$/i;
+    this.jsExtensions = /\.(js|mjs|ts|tsx|jsx)$/i;
+    this.imageExtensions = /\.(png|jpg|jpeg|gif|svg|webp|ico|bmp)$/i;
+  }
+
+  /**
+   * Check if file is a CSS file
+   */
+  isCSSFile(filepath) {
+    return this.cssExtensions.test(filepath);
+  }
+
+  /**
+   * Check if file is a JavaScript file
+   */
+  isJavaScriptFile(filepath) {
+    return this.jsExtensions.test(filepath);
+  }
+
+  /**
+   * Check if file is an image file
+   */
+  isImageFile(filepath) {
+    return this.imageExtensions.test(filepath);
+  }
+
+  /**
+   * Validate CSS content for security issues
+   * Detects <script> tags that could be injected
+   */
+  validateStyleContent(content, source = 'unknown') {
+    if (/<script/i.test(content)) {
+      throw new Error(
+        `🚨 Security Error: <script> tag detected in ${source}\n` +
+        `CSS content must not contain script tags.`
+      );
+    }
+    
+    if (/<\/script/i.test(content)) {
+      throw new Error(
+        `🚨 Security Error: </script> tag detected in ${source}\n` +
+        `CSS content must not contain script tags.`
+      );
+    }
+    
+    return content;
+  }
+
+  /**
+   * Determine import type based on file extension
+   * Returns: 'css' | 'js' | 'image' | 'unknown'
+   */
+  validateImportPath(importPath) {
+    // Handle URLs
+    if (importPath.startsWith('http://') || importPath.startsWith('https://')) {
+      // Try to infer from URL
+      if (this.isCSSFile(importPath)) return { type: 'css', path: importPath };
+      if (this.isJavaScriptFile(importPath)) return { type: 'js', path: importPath };
+      if (this.isImageFile(importPath)) return { type: 'image', path: importPath };
+      
+      // Default to unknown for CDN URLs without clear extensions
+      return { type: 'unknown', path: importPath };
+    }
+
+    // Local files
+    if (this.isCSSFile(importPath)) {
+      return { type: 'css', path: importPath };
+    }
+    
+    if (this.isJavaScriptFile(importPath)) {
+      return { type: 'js', path: importPath };
+    }
+    
+    if (this.isImageFile(importPath)) {
+      return { type: 'image', path: importPath };
+    }
+
+    return { type: 'unknown', path: importPath };
+  }
+
+  /**
+   * Validate array of imports and categorize them
+   * Returns categorized imports with warnings
+   */
+  categorizeImports(imports) {
+    const categorized = {
+      css: [],
+      js: [],
+      images: [],
+      unknown: []
+    };
+
+    const warnings = [];
+
+    for (const importPath of imports) {
+      const result = this.validateImportPath(importPath);
+      
+      if (result.type === 'unknown') {
+        warnings.push(
+          `⚠️  Unknown import type: ${importPath}\n` +
+          `   Supported: .css/.scss/.sass, .js/.ts, .png/.jpg/.svg`
+        );
+      }
+      
+      categorized[result.type === 'unknown' ? 'unknown' : result.type].push(result.path);
+    }
+
+    return { categorized, warnings };
+  }
+
+  /**
+   * Check if inline style content is empty or whitespace-only
+   */
+  isEmptyStyle(styleContent) {
+    return !styleContent || styleContent.trim().length === 0;
+  }
+}