@zenithbuild/core 0.6.2 → 0.6.4

package/src/hash.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// hash.js — Zenith Core V0
+// ---------------------------------------------------------------------------
+// Deterministic content hashing. SHA-256, hex output.
+//
+// CRITICAL: This algorithm must match the bundler's hashing exactly.
+// If bundler changes hash algorithm, core must change in lockstep.
+//
+// Input normalization:
+//   - Path separators → /
+//   - Trailing newlines stripped
+// ---------------------------------------------------------------------------
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Hash a string using SHA-256. Returns hex digest.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function hash(content) {
+    const normalized = _normalizeInput(content);
+    return createHash('sha256').update(normalized).digest('hex');
+}
+
+/**
+ * Hash a string and return a truncated hash (first N characters).
+ * Useful for content-hashed filenames.
+ *
+ * @param {string} content
+ * @param {number} [length=8]
+ * @returns {string}
+ */
+export function hashShort(content, length = 8) {
+    return hash(content).slice(0, length);
+}
+
+/**
+ * Normalize input for deterministic hashing.
+ * - Replaces backslashes with forward slashes
+ * - Strips trailing newlines
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function _normalizeInput(content) {
+    let result = content.replace(/\\/g, '/');
+    // Strip trailing newlines
+    result = result.replace(/\n+$/, '');
+    return result;
+}

package/src/index.js

@@ -0,0 +1,26 @@
+// ---------------------------------------------------------------------------
+// index.js — Zenith Core V0
+// ---------------------------------------------------------------------------
+// Public API. Re-exports frozen module namespaces only.
+// ---------------------------------------------------------------------------
+
+export { validateConfig, loadConfig, getDefaults } from './config.js';
+export {
+    normalizeSeparators,
+    fileToRoute,
+    extractParams,
+    isDynamic,
+    validateRouteParams,
+    canonicalize
+} from './path.js';
+export { sortRoutes, sortAlpha, isCorrectOrder } from './order.js';
+export { hash, hashShort } from './hash.js';
+export { createError, formatError, isZenithError, ErrorCodes } from './errors.js';
+export { parseSemver, formatVersion, validateCompatibility } from './version.js';
+export { IR_VERSION, IR_SCHEMA } from './schema.js';
+export { coreModuleSource } from './core-template.js';
+export {
+    containsForbiddenPattern,
+    FORBIDDEN_PATTERNS,
+    BROWSER_GLOBALS
+} from './guards.js';

package/src/ir/index.js

@@ -0,0 +1 @@
+export { IR_VERSION, IR_SCHEMA } from '../schema.js';

package/src/order.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// order.js — Zenith Core V0
+// ---------------------------------------------------------------------------
+// Deterministic ordering utilities. Pure transforms.
+//
+// Sorting contract:
+// 1. Static routes first, dynamic routes second
+// 2. Alphabetical tiebreak within each group
+// 3. Stable across runs
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a route path contains dynamic segments (starts with :).
+ *
+ * @param {string} routePath
+ * @returns {boolean}
+ */
+function _isDynamic(routePath) {
+    return routePath.includes(':');
+}
+
+/**
+ * Sort route entries deterministically.
+ *
+ * Rules:
+ * 1. Static routes before dynamic routes
+ * 2. Alphabetical (lexicographic) within each group
+ *
+ * Entries must have a `path` property.
+ *
+ * @param {{ path: string }[]} entries
+ * @returns {{ path: string }[]}
+ */
+export function sortRoutes(entries) {
+    return [...entries].sort((a, b) => {
+        const aDynamic = _isDynamic(a.path);
+        const bDynamic = _isDynamic(b.path);
+
+        // Static before dynamic
+        if (!aDynamic && bDynamic) return -1;
+        if (aDynamic && !bDynamic) return 1;
+
+        // Alphabetical tiebreak
+        return a.path.localeCompare(b.path);
+    });
+}
+
+/**
+ * Sort an array of strings deterministically.
+ * Simple alphabetical sort with stable ordering.
+ *
+ * @param {string[]} items
+ * @returns {string[]}
+ */
+export function sortAlpha(items) {
+    return [...items].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Check if an array of route entries is in correct deterministic order.
+ * Does not throw — returns boolean.
+ *
+ * @param {{ path: string }[]} entries
+ * @returns {boolean}
+ */
+export function isCorrectOrder(entries) {
+    const sorted = sortRoutes(entries);
+    return entries.every((entry, i) => entry.path === sorted[i].path);
+}

package/src/path.js

@@ -0,0 +1,131 @@
+// ---------------------------------------------------------------------------
+// path.js — Zenith Core V0
+// ---------------------------------------------------------------------------
+// Path normalization utilities. Pure transforms — no filesystem access.
+//
+// - Normalizes separators (\ → /)
+// - Converts [param] → :param
+// - Extracts params from route strings
+// - Validates no repeated param names
+// - Strips file extensions
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize path separators to forward slashes.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function normalizeSeparators(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+
+/**
+ * Convert a file-system path to a route path.
+ *
+ * Rules:
+ * - Normalize separators
+ * - Strip the extension
+ * - Convert [param] → :param
+ * - index files → parent path
+ * - Ensure leading /
+ *
+ * @param {string} filePath  Relative path from pages dir (e.g. "users/[id].zen")
+ * @param {string} [extension='.zen']
+ * @returns {string}
+ */
+export function fileToRoute(filePath, extension = '.zen') {
+    let route = normalizeSeparators(filePath);
+
+    // Strip extension
+    if (route.endsWith(extension)) {
+        route = route.slice(0, -extension.length);
+    }
+
+    // Convert [param] → :param
+    route = route.replace(/\[([^\]]+)\]/g, ':$1');
+
+    // Handle index → parent
+    if (route === 'index') {
+        return '/';
+    }
+    if (route.endsWith('/index')) {
+        route = route.slice(0, -'/index'.length);
+    }
+
+    // Ensure leading /
+    if (!route.startsWith('/')) {
+        route = '/' + route;
+    }
+
+    return route;
+}
+
+/**
+ * Extract parameter names from a route path.
+ *
+ * @param {string} routePath  e.g. "/users/:id/posts/:postId"
+ * @returns {string[]}  e.g. ["id", "postId"]
+ */
+export function extractParams(routePath) {
+    const params = [];
+    const segments = routePath.split('/');
+    for (const segment of segments) {
+        if (segment.startsWith(':')) {
+            params.push(segment.slice(1));
+        }
+    }
+    return params;
+}
+
+/**
+ * Check if a route path contains dynamic segments.
+ *
+ * @param {string} routePath
+ * @returns {boolean}
+ */
+export function isDynamic(routePath) {
+    return routePath.includes(':');
+}
+
+/**
+ * Validate that a route path has no repeated parameter names.
+ * Throws on violation.
+ *
+ * @param {string} routePath
+ */
+export function validateRouteParams(routePath) {
+    const params = extractParams(routePath);
+    const seen = new Set();
+    for (const param of params) {
+        if (seen.has(param)) {
+            throw new Error(
+                `[Zenith:Path] Repeated parameter name ":${param}" in route "${routePath}"`
+            );
+        }
+        seen.add(param);
+    }
+}
+
+/**
+ * Canonicalize a route path.
+ * Strips trailing slashes (except root), normalizes separators.
+ *
+ * @param {string} routePath
+ * @returns {string}
+ */
+export function canonicalize(routePath) {
+    let path = normalizeSeparators(routePath);
+
+    // Remove trailing slash (unless root)
+    if (path.length > 1 && path.endsWith('/')) {
+        path = path.slice(0, -1);
+    }
+
+    // Ensure leading slash
+    if (!path.startsWith('/')) {
+        path = '/' + path;
+    }
+
+    return path;
+}

package/src/schema.js

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// schema.js — Zenith Core IR authority
+// ---------------------------------------------------------------------------
+
+export const IR_VERSION = 1;
+
+export const IR_SCHEMA = Object.freeze({
+    version: IR_VERSION,
+    requiredTopLevelKeys: Object.freeze([
+        'ir_version',
+        'graph_hash',
+        'graph_edges',
+        'graph_nodes',
+        'html',
+        'expressions',
+        'hoisted',
+        'components_scripts',
+        'component_instances',
+        'imports',
+        'modules',
+        'prerender',
+        'signals',
+        'expression_bindings',
+        'marker_bindings',
+        'event_bindings',
+        'style_blocks'
+    ])
+});

package/src/version.js

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// version.js — Zenith Core V0
+// ---------------------------------------------------------------------------
+// SemVer parsing and compatibility validation.
+//
+// Direction of control: Other layers call core's version utility.
+// Core never imports other packages to auto-check.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a SemVer string into components.
+ *
+ * @param {string} version  e.g. "1.2.3"
+ * @returns {{ major: number, minor: number, patch: number }}
+ */
+export function parseSemver(version) {
+    const cleaned = version.replace(/^v/, '');
+    const match = cleaned.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match) {
+        throw new Error(`[Zenith:Version] Invalid semver: "${version}"`);
+    }
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10)
+    };
+}
+
+/**
+ * Format a version object back to a string.
+ *
+ * @param {{ major: number, minor: number, patch: number }} ver
+ * @returns {string}
+ */
+export function formatVersion(ver) {
+    return `${ver.major}.${ver.minor}.${ver.patch}`;
+}
+
+/**
+ * Validate compatibility between two versions.
+ *
+ * Rules:
+ * - Major versions must match (throws if different)
+ * - Minor version difference > 1 produces a warning (returns warning string)
+ * - Otherwise returns null (compatible)
+ *
+ * @param {string} coreVersion
+ * @param {string} otherVersion
+ * @returns {string|null}  Warning message or null if fully compatible
+ */
+export function validateCompatibility(coreVersion, otherVersion) {
+    const core = parseSemver(coreVersion);
+    const other = parseSemver(otherVersion);
+
+    if (core.major !== other.major) {
+        throw new Error(
+            `[Zenith:Version] Incompatible major versions: core=${formatVersion(core)}, other=${formatVersion(other)}`
+        );
+    }
+
+    const minorDiff = Math.abs(core.minor - other.minor);
+    if (minorDiff > 1) {
+        return `[Zenith:Version] Minor version drift: core=${formatVersion(core)}, other=${formatVersion(other)} (diff=${minorDiff})`;
+    }
+
+    return null;
+}

package/bin/zen-build.ts

@@ -1,2 +0,0 @@
-import { runCLI } from '../cli/main'
-runCLI({ defaultCommand: 'build' })

package/bin/zen-dev.ts

@@ -1,2 +0,0 @@
-import { runCLI } from '../cli/main'
-runCLI({ defaultCommand: 'dev' })

package/bin/zen-preview.ts

@@ -1,2 +0,0 @@
-import { runCLI } from '../cli/main'
-runCLI({ defaultCommand: 'preview' })

package/bin/zenith.ts

@@ -1,2 +0,0 @@
-import { runCLI } from '../cli/main'
-runCLI()

package/cli/commands/add.ts

@@ -1,37 +0,0 @@
-/**
- * @zenith/cli - Add Command
- * 
- * Registers a plugin in the project
- */
-
-import { requireProject } from '../utils/project'
-import { addPlugin, hasPlugin } from '../utils/plugin-manager'
-import * as logger from '../utils/logger'
-
-export interface AddOptions {
-    options?: Record<string, unknown>
-}
-
-export async function add(pluginName: string, options: AddOptions = {}): Promise<void> {
-    requireProject()
-
-    logger.header('Add Plugin')
-
-    if (!pluginName) {
-        logger.error('Plugin name required. Usage: zenith add <plugin>')
-        process.exit(1)
-    }
-
-    if (hasPlugin(pluginName)) {
-        logger.warn(`Plugin "${pluginName}" is already registered`)
-        return
-    }
-
-    const success = addPlugin(pluginName, options.options)
-
-    if (success) {
-        logger.info(`Plugin "${pluginName}" has been registered.`)
-        logger.info('Note: You may need to install the package manually:')
-        logger.log(`  bun add @zenith/plugin-${pluginName}`)
-    }
-}

package/cli/commands/build.ts

@@ -1,37 +0,0 @@
-/**
- * @zenith/cli - Build Command
- * 
- * Builds the application for production using SSG.
- */
-
-import path from 'path'
-import { requireProject } from '../utils/project'
-import * as logger from '../utils/logger'
-import { buildSSG } from '../../compiler/ssg-build'
-
-export interface BuildOptions {
-    outDir?: string
-}
-
-export async function build(options: BuildOptions = {}): Promise<void> {
-    const project = requireProject()
-    const outDir = options.outDir || project.distDir
-
-    logger.header('Zenith Build')
-    logger.log(`Source: ${project.pagesDir}`)
-    logger.log(`Output: ${outDir}`)
-
-    try {
-        buildSSG({
-            pagesDir: project.pagesDir,
-            outDir: outDir,
-            baseDir: project.root
-        })
-        logger.success('Build complete!')
-
-    } catch (err: unknown) {
-        const message = err instanceof Error ? err.message : String(err)
-        logger.error(`Build failed: ${message}`)
-        process.exit(1)
-    }
-}