@zenithbuild/core 0.6.2 → 0.6.4

package/CORE_CONTRACT.md

@@ -0,0 +1,145 @@
+# CORE_CONTRACT.md — Deterministic Utility Substrate
+
+Canonical public docs: `../zenith-docs/documentation/contracts/core-contract.md`
+
+> **This document is a legal boundary.**
+> Core is a shared utility layer. It contains no business logic,
+> no routing, no DOM, no framework behavior. Pure helper substrate only.
+>
+> **Standalone test:** If `zenith-core` were published alone on npm,
+> it must make sense as a generic deterministic utility library.
+
+## Status: FROZEN (V0)
+
+---
+
+## 1. Core Identity
+
+Core provides deterministic **transforms**, **formatting**, and **schema validation**.
+
+**Core provides:**
+- Deterministic transforms: `hash`, `normalizePath`, `sortRoutes`, `parseConfig`, `parseSemver`
+- Deterministic formatting: `formatError`
+- Deterministic schema validation: `validateConfigSchema`, `validateRouteParams`
+
+**Core does NOT:**
+- Scan repositories
+- Enforce cross-layer behavior
+- Know about router semantics
+- Know about bundler internals
+- Police other layers' architecture
+
+---
+
+## 2. Allowed Modules
+
+| Module | Purpose |
+|---|---|
+| `config.js` | Load + validate config schema |
+| `path.js` | Normalize paths + `[param]` → `:param` |
+| `order.js` | Static-first stable sort |
+| `hash.js` | SHA-256 content hashing |
+| `errors.js` | Error factory + prefixing |
+| `version.js` | SemVer parsing + major compatibility |
+| `guards.js` | Small pure validation helpers |
+| `index.js` | Re-exports |
+
+---
+
+## 3. Determinism Guarantees
+
+| Rule | Guarantee |
+|---|---|
+| Hashing | Same input → same hash, cross-platform |
+| Ordering | Stable sort: static first, dynamic after, alpha tiebreak |
+| Paths | Normalized separators (`/`), consistent param format |
+| Config | Missing keys → explicit defaults, unknown keys → throw |
+| Errors | Consistent format: `[Zenith:MODULE] message` |
+
+---
+
+## 4. Explicit Prohibitions
+
+Core source **must never**:
+
+1. Import from `@zenithbuild/compiler`, `@zenithbuild/bundler`, `@zenithbuild/runtime`, or `@zenithbuild/router`
+2. Reference `window`, `document`, `navigator`, or any browser API
+3. Use `eval()`, `new Function()`, or `document.write()`
+4. Perform build orchestration of any kind
+5. Access the filesystem **except when explicitly loading `zenith.config.js`**
+6. Mutate global state
+7. Contain preset/mode logic (`basic`, `router`, `fullstack` belong in `create-zenith`)
+8. Initiate version checks against other packages (other layers call core's utility)
+
+---
+
+## 5. Hash Contract
+
+- Algorithm: **SHA-256** via `node:crypto`
+- Output: **hex string**
+- Input normalization: path separators → `/`, trailing newlines stripped
+
+> **Critical rule:** Hash algorithm must match bundler's algorithm exactly.
+> If bundler changes hash algorithm, core must change in lockstep.
+
+---
+
+## 6. Config Schema (V0)
+
+```js
+// zenith.config.js
+export default {
+  router: false,    // boolean — opt-in client router
+  outDir: 'dist',   // string — output directory
+  pagesDir: 'pages' // string — pages directory
+}
+```
+
+| Key | Type | Default | Validation |
+|---|---|---|---|
+| `router` | `boolean` | `false` | Must be boolean |
+| `outDir` | `string` | `'dist'` | Non-empty string |
+| `pagesDir` | `string` | `'pages'` | Non-empty string |
+
+Unknown keys → throw `[Zenith:Config] Unknown key: "foo"`.
+
+**No other keys for V0.** No `mode`, `target`, `presets`, `experimental`, `base`, `assetsDir`.
+
+---
+
+## 7. Version Compatibility API
+
+```js
+validateCompatibility(coreVersion, otherVersion)
+// Throws if major versions differ
+// Warns if minor versions differ by > 1
+```
+
+**Direction of control:** Other layers call this function.
+Core never imports other packages to auto-check.
+
+---
+
+## 8. Guard Helpers
+
+Guards are **small pure validation helpers**:
+
+```js
+containsForbiddenPattern(source, patterns)  // returns boolean
+validateRouteParams(routePath)              // throws on repeated params
+validateConfigSchema(config)                // throws on unknown keys / wrong types
+```
+
+Guards do NOT:
+- Scan entire repositories
+- Enforce architectural decisions
+- Assert that other layers used sorting correctly
+
+---
+
+## 9. Dependency Rules
+
+- **Zero dependencies on other Zenith packages**
+- Zero runtime npm dependencies
+- Dev dependencies: Jest only
+- Pure ESM, Node.js built-ins only

package/README.md

@@ -1,39 +1,24 @@
-# @zenithbuild/core ⚡
+# `@zenithbuild/core`
 
-The heart of the Zenith framework. High-performance reactive runtime, compiler, and build primitives.
+This is the **sole public entrypoint** for the Zenith framework. 
 
-## Overview
+## Canonical Docs
 
-Zenith is a modern reactive web framework designed for maximum performance and developer experience. The core package contains the essential building blocks:
-- **Compiler**: Transforms `.zen` files into optimized JavaScript.
-- **Runtime**: A lightweight, efficient reactive system for the browser.
-- **Router**: Lightweight client-side routing.
-- **Build Primitives**: Tools for dev servers and production builds.
+- Core contract: `../zenith-docs/documentation/contracts/core-contract.md`
+- Zenith contract: `../zenith-docs/documentation/zenith-contract.md`
 
-## Key Components
+Use this package directly in your projects to run Zenith utilities and access the official APIs.
 
-### 1. Compiler (`/compiler`)
-The Zenith compiler handles parsing and transforming Single File Components (`.zen`). It leverages `parse5` for robust HTML parsing and generates highly optimized render functions.
+## Installation
 
-### 2. Runtime (`/runtime`)
-Our runtime is designed to be minimal. It manages the reactive cycle, efficient DOM updates, and lifecycle management (like `zenOnMount`).
-
-### 3. Server (`/bin/zen-dev`, `/bin/zen-build`)
-Low-level binaries for orchestrating development and production environments.
-
-## Architecture
-
-Zenith follows a "Compiler-First" philosophy. We shift as much work as possible to build time, keeping the client-side bundle lean and fast.
-
-## Usage (Internal)
+```bash
+npm install @zenithbuild/core
+```
 
-This package is typically consumed by the Zenith CLI and other ecosystem tools.
+## Running the CLI
 
-```typescript
-import { compile } from '@zenithbuild/core/compiler';
-// ... compile logic
-```
+The `.bin` wrapper is exposed as `zenith`. Running `npx zenith dev` or `npx zenith build` executes the corresponding framework command.
 
-## License
+## Internal Dependencies
 
-MIT
+For developers: DO NOT import any other `@zenithbuild/*` packages directly (e.g. `@zenithbuild/compiler`, `@zenithbuild/runtime`, `@zenithbuild/cli`). All needed features are either opaque implementation details or safely exposed through exports here. Direct access of inner implementation details is strictly forbidden.

package/bin/zenith.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+const cwdRequire = createRequire(join(process.cwd(), 'package.json'));
+
+function resolveInternal(specifier) {
+    try {
+        return cwdRequire.resolve(specifier);
+    } catch {
+        return require.resolve(specifier);
+    }
+}
+
+// Version mismatch check
+const corePkgPath = join(__dirname, '../package.json');
+const corePkg = JSON.parse(readFileSync(corePkgPath, 'utf-8'));
+const args = process.argv.slice(2);
+
+if (args.includes('--version') || args.includes('-v')) {
+    console.log(`zenith ${corePkg.version}`);
+    process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h')) {
+    const { cli } = await import(pathToFileURL(resolveInternal('@zenithbuild/cli')).href);
+    await cli(args);
+    process.exit(0);
+}
+
+const expectedInternals = [
+    '@zenithbuild/cli',
+    '@zenithbuild/compiler',
+    '@zenithbuild/runtime',
+    '@zenithbuild/router',
+    '@zenithbuild/bundler'
+];
+
+let hasMismatch = false;
+
+for (const internal of expectedInternals) {
+    const expectedVersion = corePkg.dependencies[internal];
+    if (!expectedVersion) continue;
+
+    try {
+        const entryPath = resolveInternal(internal);
+
+        // Walk up to find the package's package.json
+        let currentDir = dirname(entryPath);
+        let pkgVersion = null;
+
+        while (currentDir !== '/' && currentDir !== '.') {
+            try {
+                const pkgTxt = readFileSync(join(currentDir, 'package.json'), 'utf-8');
+                const pkg = JSON.parse(pkgTxt);
+                if (pkg.name === internal) {
+                    pkgVersion = pkg.version;
+                    break;
+                }
+            } catch (e) {
+                // Ignored, continue walking up
+            }
+            currentDir = dirname(currentDir);
+        }
+
+        if (pkgVersion && pkgVersion !== expectedVersion) {
+            console.error(`Version mismatch: ${internal} is version ${pkgVersion} but @zenithbuild/core expects exactly ${expectedVersion}`);
+            hasMismatch = true;
+        } else if (!pkgVersion) {
+            // In a strict mode, failing to find package.json might be treated as a failure.
+        }
+    } catch (err) {
+        console.error(`Version mismatch check failed: Could not resolve internal dependency ${internal}`);
+        hasMismatch = true;
+    }
+}
+
+if (hasMismatch) {
+    process.exit(1);
+}
+
+// Proceed to hand off execution to the underlying CLI implementation
+import(pathToFileURL(resolveInternal('@zenithbuild/cli')).href);

package/package.json

@@ -1,72 +1,55 @@
 {
   "name": "@zenithbuild/core",
-  "version": "0.6.2",
-  "description": "Core library for the Zenith framework",
+  "version": "0.6.4",
+  "description": "Deterministic utility substrate for the Zenith framework",
   "license": "MIT",
   "type": "module",
-  "main": "./index.ts",
+  "main": "./src/index.js",
   "bin": {
-    "zenith": "./dist/zenith.js",
-    "zenith-dev": "./dist/zen-dev.js",
-    "zen-dev": "./dist/zen-dev.js",
-    "zen-build": "./dist/zen-build.js",
-    "zen-preview": "./dist/zen-preview.js"
+    "zenith": "bin/zenith.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./config": "./src/config.js",
+    "./path": "./src/path.js",
+    "./order": "./src/order.js",
+    "./hash": "./src/hash.js",
+    "./errors": "./src/errors.js",
+    "./version": "./src/version.js",
+    "./guards": "./src/guards.js",
+    "./schema": "./src/schema.js",
+    "./core-template": "./src/core-template.js",
+    "./ir": "./src/ir/index.js"
   },
   "files": [
+    "src",
     "bin",
-    "cli",
-    "compiler",
-    "core",
-    "router",
-    "runtime",
-    "dist",
-    "index.ts",
-    "tsconfig.json"
+    "CORE_CONTRACT.md",
+    "README.md",
+    "contracts"
   ],
-  "exports": {
-    ".": "./index.ts",
-    "./compiler": "./compiler/index.ts",
-    "./config": "./core/config/index.ts",
-    "./core": "./core/index.ts",
-    "./router": "./router/index.ts",
-    "./runtime": "./runtime/index.ts"
+  "publishConfig": {
+    "access": "public"
   },
-  "keywords": [
-    "zenith",
-    "core",
-    "framework"
-  ],
-  "author": "Zenith Team",
-  "repository": {
-    "type": "git",
-    "url": "git@github.com:zenithbuild/zenith-core.git"
+  "dependencies": {
+    "@zenithbuild/cli": "0.6.4",
+    "@zenithbuild/compiler": "0.6.4",
+    "@zenithbuild/runtime": "0.6.4",
+    "@zenithbuild/router": "0.6.4",
+    "@zenithbuild/bundler": "0.6.4"
   },
   "scripts": {
-    "dev": "bun dev",
-    "build": "bun build",
-    "start": "bun run build && bun run dev",
-    "build:cli": "bun build bin/zenith.ts bin/zen-dev.ts bin/zen-build.ts bin/zen-preview.ts --outdir dist --target bun --bundle && for f in dist/*.js; do echo '#!/usr/bin/env bun' | cat - \"$f\" > \"$f.tmp\" && mv \"$f.tmp\" \"$f\" && chmod +x \"$f\"; done",
-    "format": "prettier --write \"**/*.ts\"",
-    "format:check": "prettier --check \"**/*.ts\""
+    "test": "npm run contract:deps && npm run contract:scan && npm run contract:api && npm run contract:template && npm run contract:golden",
+    "test:legacy": "NODE_OPTIONS=--experimental-vm-modules jest --config jest.config.js",
+    "contract:deps": "node dependency_contract.spec.js",
+    "contract:scan": "node contract-scan.mjs",
+    "contract:api": "node core_api_lock.spec.js",
+    "contract:template": "node template-contract.spec.js",
+    "contract:golden": "node golden-contract.spec.js"
   },
-  "private": false,
   "devDependencies": {
-    "@types/bun": "latest",
-    "@types/node": "latest",
-    "prettier": "^3.7.4"
-  },
-  "peerDependencies": {
-    "typescript": "^5"
+    "@jest/globals": "^30.2.0",
+    "jest": "^30.2.0"
   },
-  "dependencies": {
-    "@zenithbuild/router": "latest",
-    "@types/acorn": "^6.0.4",
-    "@types/marked": "^6.0.0",
-    "@types/parse5": "^7.0.0",
-    "acorn": "^8.15.0",
-    "es-module-lexer": "^2.0.0",
-    "marked": "^17.0.1",
-    "parse5": "^8.0.0",
-    "picocolors": "^1.1.1"
-  }
+  "private": false
 }

package/src/config.js

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// config.js — Zenith Core V0
+// ---------------------------------------------------------------------------
+// Load and validate zenith.config.js. This is the ONLY module in core
+// that touches the filesystem (via dynamic import).
+//
+// V0 Schema: { router, outDir, pagesDir }
+// Unknown keys → throw.
+// ---------------------------------------------------------------------------
+
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** V0 config defaults */
+const DEFAULTS = {
+    router: false,
+    embeddedMarkupExpressions: false,
+    types: true,
+    typescriptDefault: true,
+    outDir: 'dist',
+    pagesDir: 'pages',
+    experimental: {},
+    strictDomLints: false
+};
+
+/** Allowed keys and their expected types */
+const SCHEMA = {
+    router: 'boolean',
+    embeddedMarkupExpressions: 'boolean',
+    types: 'boolean',
+    typescriptDefault: 'boolean',
+    outDir: 'string',
+    pagesDir: 'string',
+    experimental: 'object',
+    strictDomLints: 'boolean'
+};
+
+/**
+ * Validate a config object against the V0 schema.
+ * Throws on unknown keys or wrong types.
+ *
+ * @param {object} config
+ * @returns {object} Normalized config with defaults applied
+ */
+export function validateConfig(config) {
+    if (config === null || config === undefined) {
+        return { ...DEFAULTS };
+    }
+
+    if (typeof config !== 'object' || Array.isArray(config)) {
+        throw new Error('[Zenith:Config] Config must be a plain object');
+    }
+
+    // Check for unknown keys
+    for (const key of Object.keys(config)) {
+        if (!(key in SCHEMA)) {
+            throw new Error(`[Zenith:Config] Unknown key: "${key}"`);
+        }
+    }
+
+    // Validate types and apply defaults
+    const result = { ...DEFAULTS };
+
+    for (const [key, expectedType] of Object.entries(SCHEMA)) {
+        if (key in config) {
+            const value = config[key];
+            if (typeof value !== expectedType) {
+                throw new Error(
+                    `[Zenith:Config] Key "${key}" must be ${expectedType}, got ${typeof value}`
+                );
+            }
+            if (expectedType === 'string' && value.trim() === '') {
+                throw new Error(
+                    `[Zenith:Config] Key "${key}" must be a non-empty string`
+                );
+            }
+            if (key === 'experimental' && value) {
+                if (typeof value !== 'object' || Array.isArray(value)) {
+                    throw new Error(`[Zenith:Config] Key "experimental" must be a plain object`);
+                }
+                const expDefaults = { ...DEFAULTS.experimental };
+                for (const expKey of Object.keys(value)) {
+                    if (!(expKey in expDefaults)) {
+                        throw new Error(`[Zenith:Config] Unknown experimental key: "${expKey}"`);
+                    }
+                    if (typeof value[expKey] !== typeof expDefaults[expKey]) {
+                        throw new Error(`[Zenith:Config] Experimental key "${expKey}" must be ${typeof expDefaults[expKey]}`);
+                    }
+                    expDefaults[expKey] = value[expKey];
+                }
+                result[key] = expDefaults;
+                continue;
+            }
+            result[key] = value;
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Load zenith.config.js from a project root.
+ * Returns validated config with defaults applied.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<object>}
+ */
+export async function loadConfig(projectRoot) {
+    const configPath = join(projectRoot, 'zenith.config.js');
+
+    try {
+        const url = pathToFileURL(configPath).href;
+        const mod = await import(url);
+        const raw = mod.default || mod;
+        return validateConfig(raw);
+    } catch (err) {
+        // File not found — return defaults
+        if (
+            err.code === 'ERR_MODULE_NOT_FOUND' ||
+            err.code === 'ENOENT' ||
+            err.message?.includes('Cannot find module') ||
+            err.message?.includes('ENOENT')
+        ) {
+            return { ...DEFAULTS };
+        }
+        throw err;
+    }
+}
+
+/**
+ * Return the default config.
+ * @returns {object}
+ */
+export function getDefaults() {
+    return { ...DEFAULTS };
+}

package/src/core-template.js

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// core-template.js — source template for emitted core asset
+// ---------------------------------------------------------------------------
+
+function assertRuntimeImport(runtimeImport) {
+    if (typeof runtimeImport !== 'string' || runtimeImport.trim().length === 0) {
+        throw new Error('[Zenith Core] coreModuleSource(runtimeImport) requires non-empty runtimeImport');
+    }
+}
+
+export function coreModuleSource(runtimeImport) {
+    assertRuntimeImport(runtimeImport);
+    const runtimeImportLiteral = JSON.stringify(runtimeImport);
+
+    return [
+        `import { signal, state, zeneffect, zenEffect as __zenithZenEffect, zenMount as __zenithZenMount } from ${runtimeImportLiteral};`,
+        '',
+        'export const zenSignal = signal;',
+        'export const zenState = state;',
+        'export const zenEffect = __zenithZenEffect;',
+        'export const zenMount = __zenithZenMount;',
+        '',
+        'export function zenOnMount(callback) {',
+        '  return __zenithZenMount(callback);',
+        '}',
+        '',
+        'export { signal, state, zeneffect };',
+        ''
+    ].join('\n');
+}

package/src/errors.js

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// errors.js — Zenith Core V0
+// ---------------------------------------------------------------------------
+// Shared error formatting. All Zenith errors use the format:
+//   [Zenith:MODULE] message
+//
+// Pure factory functions. No side effects.
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Zenith error with standard formatting.
+ *
+ * @param {string} module  Module name (e.g. 'Config', 'Path', 'Build')
+ * @param {string} message  Error message
+ * @returns {Error}
+ */
+export function createError(module, message) {
+    const err = new Error(`[Zenith:${module}] ${message}`);
+    err.zenithModule = module;
+    return err;
+}
+
+/**
+ * Format an error message with the Zenith prefix.
+ *
+ * @param {string} module
+ * @param {string} message
+ * @returns {string}
+ */
+export function formatError(module, message) {
+    return `[Zenith:${module}] ${message}`;
+}
+
+/**
+ * Check if an error is a Zenith error.
+ *
+ * @param {Error} err
+ * @returns {boolean}
+ */
+export function isZenithError(err) {
+    return err instanceof Error && typeof err.zenithModule === 'string';
+}
+
+/**
+ * Predefined error codes for common situations.
+ */
+export const ErrorCodes = {
+    CONFIG_UNKNOWN_KEY: 'CONFIG_UNKNOWN_KEY',
+    CONFIG_INVALID_TYPE: 'CONFIG_INVALID_TYPE',
+    CONFIG_EMPTY_VALUE: 'CONFIG_EMPTY_VALUE',
+    PATH_REPEATED_PARAM: 'PATH_REPEATED_PARAM',
+    VERSION_INCOMPATIBLE: 'VERSION_INCOMPATIBLE',
+    GUARD_VIOLATION: 'GUARD_VIOLATION'
+};

package/src/guards.js

@@ -0,0 +1,61 @@
+// ---------------------------------------------------------------------------
+// guards.js — Zenith Core V0
+// ---------------------------------------------------------------------------
+// Small pure validation helpers. These provide primitives —
+// they do NOT scan repos, enforce architecture, or police other layers.
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if source contains any of the given forbidden patterns.
+ *
+ * @param {string} source  Source code text
+ * @param {string[]} patterns  Patterns to check for
+ * @returns {string[]}  Array of matched patterns (empty if none)
+ */
+export function containsForbiddenPattern(source, patterns) {
+    const found = [];
+    for (const pattern of patterns) {
+        if (source.includes(pattern)) {
+            found.push(pattern);
+        }
+    }
+    return found;
+}
+
+/**
+ * Validate that a route path has no repeated parameter names.
+ * Re-exported from path.js for convenience.
+ *
+ * @param {string} routePath
+ */
+export { validateRouteParams } from './path.js';
+
+/**
+ * Validate a config object against the V0 schema.
+ * Re-exported from config.js for convenience.
+ *
+ * @param {object} config
+ * @returns {object}
+ */
+export { validateConfig as validateConfigSchema } from './config.js';
+
+/**
+ * Default forbidden patterns for Zenith source code.
+ */
+export const FORBIDDEN_PATTERNS = [
+    'eval(',
+    'new Function(',
+    'new Function (',
+    'document.write('
+];
+
+/**
+ * Default browser globals that should not appear in Node-only code.
+ */
+export const BROWSER_GLOBALS = [
+    'window',
+    'document',
+    'navigator',
+    'localStorage',
+    'sessionStorage'
+];