@jxsuite/compiler 0.9.0 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "0.9.0",
+  "version": "0.10.2",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.3.5",
-    "@jxsuite/parser": "^0.7.0",
-    "@jxsuite/runtime": "^0.7.0",
+    "@jxsuite/parser": "^0.10.1",
+    "@jxsuite/runtime": "^0.10.1",
     "remark-gfm": "^4.0.1",
     "remark-stringify": "^11.0.0",
     "sharp": "^0.34.5",

package/src/compile-cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from "./compiler.js";
+
+const [, , src, out] = process.argv;
+if (src) {
+  runCli(src, out).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/src/compiler.js

@@ -10,7 +10,7 @@
  *   - Server               → compile-server.js   (Hono server handler)
  *
  * Usage (CLI):
- *   bun packages/compiler/compiler.js <source.json> [output.html]
+ *   bun packages/compiler/src/compile-cli.js <source.json> [output.html]
  */
 
 import { readFileSync } from "node:fs";
@@ -132,35 +132,30 @@ export async function compile(sourcePath, opts = {}) {
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
-const isMainModule = process.argv[1]?.endsWith("compiler.js");
-if (isMainModule && process.argv[2]) {
-  const [, , src, out] = process.argv;
-
-  Promise.all([compile(src), compileServer(src)])
-    .then(async ([result, server]) => {
-      const { writeFileSync, mkdirSync } = await import("node:fs");
-      const { dirname, join } = await import("node:path");
-      if (out) {
-        writeFileSync(out, result.html, "utf8");
-        console.error(`Written to ${out}`);
-        const outDir = dirname(out);
-        for (const f of result.files) {
-          const filePath = join(outDir, f.path);
-          mkdirSync(dirname(filePath), { recursive: true });
-          writeFileSync(filePath, f.content, "utf8");
-          console.error(`Written to ${filePath}`);
-        }
-      } else {
-        process.stdout.write(result.html);
-      }
-      if (server && out) {
-        const serverOut = out.replace(/(\.[^.]+)?$/, "-server.js");
-        writeFileSync(serverOut, /** @type {string} */ (server), "utf8");
-        console.error(`Server handler written to ${serverOut}`);
-      }
-    })
-    .catch((/** @type {any} */ err) => {
-      console.error(err);
-      process.exit(1);
-    });
+/**
+ * @param {string} src
+ * @param {string} [out]
+ */
+export async function runCli(src, out) {
+  const [result, server] = await Promise.all([compile(src), compileServer(src)]);
+  const { writeFileSync, mkdirSync } = await import("node:fs");
+  const { dirname, join } = await import("node:path");
+  if (out) {
+    writeFileSync(out, result.html, "utf8");
+    console.error(`Written to ${out}`);
+    const outDir = dirname(out);
+    for (const f of result.files) {
+      const filePath = join(outDir, f.path);
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, f.content, "utf8");
+      console.error(`Written to ${filePath}`);
+    }
+  } else {
+    process.stdout.write(result.html);
+  }
+  if (server && out) {
+    const serverOut = out.replace(/(\.[^.]+)?$/, "-server.js");
+    writeFileSync(serverOut, /** @type {string} */ (server), "utf8");
+    console.error(`Server handler written to ${serverOut}`);
+  }
 }

package/src/site/content-loader.js

@@ -1,8 +1,8 @@
 /**
- * Content-loader.js — Content collection loader
+ * Content-loader.js — Content type loader
  *
- * Loads content collections defined in project.json's `collections` key. Supports Markdown (.md),
- * JSON (.json), and CSV (.csv) source files.
+ * Loads content types defined in project.json's `contentTypes` key. Supports Markdown (.md), JSON
+ * (.json), and CSV (.csv) source files.
  *
  * Phase 2 implementation of site-architecture spec §6.
  *
@@ -30,12 +30,13 @@ function parseCSV(csv) {
   /** @type {string[]} */
   const lines = [];
 
-  // Split into rows respecting quoted newlines
+  // Split into rows respecting quoted newlines (preserve raw characters)
   for (let i = 0; i < csv.length; i++) {
     const ch = csv[i];
     if (ch === '"') {
+      current += ch;
       if (inQuotes && csv[i + 1] === '"') {
-        current += '"';
+        current += csv[i + 1];
         i++;
       } else {
         inQuotes = !inQuotes;
@@ -98,7 +99,7 @@ let _mdModule = null;
 
 /**
  * Lazily import @jxsuite/parser for Markdown support. This avoids hard dependency — only loads when
- * MD collections exist.
+ * MD content types exist.
  *
  * @returns {Promise<any>}
  */
@@ -155,7 +156,6 @@ function loadJSONEntries(filePath) {
       id: item.id ?? basename(filePath, ".json") + "-" + i,
       data: item,
       body: null,
-      rendered: null,
     }));
   }
   // Single object file — filename is the id
@@ -164,7 +164,6 @@ function loadJSONEntries(filePath) {
       id: raw.id ?? basename(filePath, ".json"),
       data: raw,
       body: null,
-      rendered: null,
     },
   ];
 }
@@ -173,7 +172,7 @@ function loadJSONEntries(filePath) {
  * Load a CSV file into ContentEntry(s).
  *
  * @param {string} filePath - Absolute path to .csv file
- * @param {any} [schema] - Collection schema (for type coercion)
+ * @param {any} [schema] - Content type schema (for type coercion)
  * @returns {object[]} Array of ContentEntry shapes
  */
 function loadCSVEntries(filePath, schema) {
@@ -192,17 +191,17 @@ function loadCSVEntries(filePath, schema) {
     }
     // Use `id` column, `sku` column, or row index as the entry ID
     const id = row.id ?? row.sku ?? String(i);
-    return { id, data: row, body: null, rendered: null };
+    return { id, data: row, body: null };
   });
 }
 
 // ─── Content Config ───────────────────────────────────────────────────────────
 
 /**
- * Load and parse content collections config from project.json.
+ * Load and parse content types config from project.json.
  *
  * @param {string} projectRoot - Project root directory
- * @param {Record<string, any>} [projectConfig] - Already-loaded project config with `collections`
+ * @param {Record<string, any>} [projectConfig] - Already-loaded project config with `contentTypes`
  *   key
  * @returns {{ config: any; contentDir: string } | null} Parsed config or null if no content dir
  */
@@ -210,68 +209,68 @@ export function loadContentConfig(projectRoot, projectConfig = undefined) {
   const contentDir = resolve(projectRoot, "content");
 
   /** @type {any} */
-  const config = { collections: projectConfig?.collections ?? {} };
+  const config = { contentTypes: projectConfig?.contentTypes ?? {} };
 
   return { config, contentDir };
 }
 
-// ─── Collection Loading ───────────────────────────────────────────────────────
+// ─── Content Type Loading ────────────────────────────────────────────────────
 
 /**
- * Load all content collections defined in project.json.
+ * Load all content types defined in project.json.
  *
  * @param {string} projectRoot - Project root directory
  * @param {Record<string, any>} [projectConfig] - Already-loaded project config
- * @returns {Promise<Map<string, any[]>>} Map of collection name → array of ContentEntry
+ * @returns {Promise<Map<string, any[]>>} Map of content type name → array of ContentEntry
  */
-export async function loadCollections(projectRoot, projectConfig = undefined) {
+export async function loadContentTypes(projectRoot, projectConfig = undefined) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) return new Map();
 
   const { config } = result;
   /** @type {Map<string, any[]>} */
-  const collections = new Map();
+  const contentTypes = new Map();
 
-  for (const [name, collectionDef] of Object.entries(config.collections)) {
-    const entries = await loadCollection(name, /** @type {any} */ (collectionDef), projectRoot);
-    collections.set(name, entries);
+  for (const [name, contentTypeDef] of Object.entries(config.contentTypes)) {
+    const entries = await loadContentType(name, /** @type {any} */ (contentTypeDef), projectRoot);
+    contentTypes.set(name, entries);
   }
 
-  return collections;
+  return contentTypes;
 }
 
 /**
- * Get the $elements array for a specific collection, if defined in project.json collections.
+ * Get the $elements array for a specific content type, if defined in project.json contentTypes.
  *
  * @param {string} projectRoot - Project root directory
- * @param {string} collectionName - Name of the collection
+ * @param {string} contentTypeName - Name of the content type
  * @param {Record<string, any>} [projectConfig] - Already-loaded project config
  * @returns {any[] | undefined}
  */
-export function getCollectionElements(projectRoot, collectionName, projectConfig = undefined) {
+export function getContentTypeElements(projectRoot, contentTypeName, projectConfig = undefined) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) return undefined;
-  const def = result.config.collections?.[collectionName];
+  const def = result.config.contentTypes?.[contentTypeName];
   return def?.$elements;
 }
 
 /**
- * Load a single collection by its definition.
+ * Load a single content type by its definition.
  *
- * @param {string} name - Collection name
- * @param {any} collectionDef - Collection definition from project.json
+ * @param {string} name - Content type name
+ * @param {any} contentTypeDef - Content type definition from project.json
  * @param {string} projectRoot - Absolute path to project root directory
  * @returns {Promise<any[]>} Array of ContentEntry
  */
-async function loadCollection(name, collectionDef, projectRoot) {
-  const source = collectionDef.source;
-  const schema = collectionDef.schema;
+async function loadContentType(name, contentTypeDef, projectRoot) {
+  const source = contentTypeDef.source;
+  const schema = contentTypeDef.schema;
 
-  // Derive directive allowedNames from collection $elements (tag names from npm packages)
+  // Derive directive allowedNames from content type $elements (tag names from npm packages)
   /** @type {any} */
-  const directiveOptions = collectionDef.$elements?.length
+  const directiveOptions = contentTypeDef.$elements?.length
     ? {
-        allowedNames: collectionDef.$elements
+        allowedNames: contentTypeDef.$elements
           .filter((/** @type {any} */ e) => typeof e === "string" || e?.$ref)
           .map((/** @type {any} */ e) => (typeof e === "string" ? e : e.$ref)),
       }
@@ -307,14 +306,14 @@ async function loadCollection(name, collectionDef, projectRoot) {
 // ─── Schema Validation ────────────────────────────────────────────────────────
 
 /**
- * Validate content entries against their collection schema. Logs warnings for missing required
+ * Validate content entries against their content type schema. Logs warnings for missing required
  * fields and type mismatches.
  *
  * @param {any[]} entries - Array of ContentEntry
- * @param {any} schema - JSON Schema for the collection
- * @param {string} collectionName - For error messages
+ * @param {any} schema - JSON Schema for the content type
+ * @param {string} contentTypeName - For error messages
  */
-function validateEntries(entries, schema, collectionName) {
+function validateEntries(entries, schema, contentTypeName) {
   const required = schema.required ?? [];
   const properties = schema.properties ?? {};
 
@@ -323,7 +322,7 @@ function validateEntries(entries, schema, collectionName) {
     for (const field of required) {
       if (!(field in entry.data) || entry.data[field] == null) {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" missing required field "${field}"`,
+          `Content validation: "${contentTypeName}/${entry.id}" missing required field "${field}"`,
         );
       }
     }
@@ -336,36 +335,36 @@ function validateEntries(entries, schema, collectionName) {
 
       if (d.type === "string" && typeof value !== "string") {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" field "${field}" expected string, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected string, got ${typeof value}`,
         );
       } else if (d.type === "number" && typeof value !== "number") {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" field "${field}" expected number, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected number, got ${typeof value}`,
         );
       } else if (d.type === "boolean" && typeof value !== "boolean") {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" field "${field}" expected boolean, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected boolean, got ${typeof value}`,
         );
       } else if (d.type === "array" && !Array.isArray(value)) {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" field "${field}" expected array, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected array, got ${typeof value}`,
         );
       }
     }
   }
 }
 
-// ─── Collection Querying ──────────────────────────────────────────────────────
+// ─── Content Type Querying ───────────────────────────────────────────────────
 
 /**
- * Query a loaded collection with filter, sort, and limit. Implements the ContentCollection
+ * Query a loaded content type with filter, sort, and limit. Implements the ContentCollection
  * $prototype resolution.
  *
- * @param {any[]} entries - Full collection entries
+ * @param {any[]} entries - Full content type entries
  * @param {any} [query] - Query options
  * @returns {any[]} Filtered, sorted, limited entries
  */
-export function queryCollection(entries, query = {}) {
+export function queryContentType(entries, query = {}) {
   let result = [...entries];
 
   // Filter
@@ -402,9 +401,9 @@ export function queryCollection(entries, query = {}) {
 }
 
 /**
- * Find a single entry by ID in a collection. Implements the ContentEntry $prototype resolution.
+ * Find a single entry by ID in a content type. Implements the ContentEntry $prototype resolution.
  *
- * @param {any[]} entries - Full collection entries
+ * @param {any[]} entries - Full content type entries
  * @param {string} id - Entry ID to find
  * @returns {any | null} The matching entry or null
  */
@@ -412,30 +411,30 @@ export function findEntry(entries, id) {
   return entries.find((/** @type {any} */ e) => e.id === id) ?? null;
 }
 
-// ─── Collection Reference Resolution ─────────────────────────────────────────
+// ─── Content Type Reference Resolution ──────────────────────────────────────
 
 /**
- * Resolve cross-collection $ref references in entry data. For example, a blog post's `author:
- * "jane-doe"` with a schema `$ref` to the authors collection gets resolved to the full author
+ * Resolve cross-content-type $ref references in entry data. For example, a blog post's `author:
+ * "jane-doe"` with a schema `$ref` to the authors content type gets resolved to the full author
  * entry.
  *
- * @param {Map<string, any[]>} collections - All loaded collections @param {any} config -
+ * @param {Map<string, any[]>} contentTypes - All loaded content types @param {any} config -
  * Content.config.json
  */
-export function resolveCollectionRefs(collections, config) {
-  for (const [name, collectionDef] of Object.entries(config.collections)) {
-    const cd = /** @type {any} */ (collectionDef);
+export function resolveContentTypeRefs(contentTypes, config) {
+  for (const [name, contentTypeDef] of Object.entries(config.contentTypes)) {
+    const cd = /** @type {any} */ (contentTypeDef);
     const schema = cd.schema;
     if (!schema?.properties) continue;
 
-    const entries = collections.get(name);
+    const entries = contentTypes.get(name);
     if (!entries) continue;
 
     for (const [field, def] of Object.entries(schema.properties)) {
       const d = /** @type {any} */ (def);
-      if (!d.$ref?.startsWith("#/collections/")) continue;
-      const refCollection = d.$ref.replace("#/collections/", "");
-      const refEntries = collections.get(refCollection);
+      if (!d.$ref?.startsWith("#/contentTypes/")) continue;
+      const refContentType = d.$ref.replace("#/contentTypes/", "");
+      const refEntries = contentTypes.get(refContentType);
       if (!refEntries) continue;
 
       for (const entry of entries) {

package/src/site/context-injection.js

@@ -4,15 +4,15 @@
  * Injects project-level and page-level context variables into a page's state before compilation.
  * These are available as $site.* and $page.* in template expressions.
  *
- * Also resolves ContentCollection and ContentEntry $prototype entries against loaded content
- * collections (Phase 2, spec §6.4).
+ * Also resolves ContentCollection and ContentEntry $prototype entries against loaded content types
+ * (Phase 2, spec §6.4).
  *
  * Per site-architecture spec §10: $site.name — from project.json name $site.url — from project.json
  * url $site.state.* — site-wide reactive state $page.url — current page URL path $page.title — page
  * title $page.params — dynamic route parameters (if any)
  */
 
-import { queryCollection, findEntry } from "./content-loader.js";
+import { queryContentType, findEntry } from "./content-loader.js";
 import { resolve, dirname, relative } from "node:path";
 
 /**
@@ -21,7 +21,7 @@ import { resolve, dirname, relative } from "node:path";
  * @param {any} doc - The page document (mutated)
  * @param {any} projectConfig - Loaded project configuration
  * @param {any} route - The resolved route for this page
- * @param {Map<string, any[]>} [collections] - Loaded content collections
+ * @param {Map<string, any[]>} [contentTypes] - Loaded content types
  * @param {string | null} [projectRoot] - Absolute path to the project root (for import rebasing)
  * @returns {any} The mutated document
  */
@@ -29,7 +29,7 @@ export function injectContext(
   doc,
   projectConfig,
   route,
-  collections = new Map(),
+  contentTypes = new Map(),
   projectRoot = null,
 ) {
   if (!doc.state) doc.state = {};
@@ -49,8 +49,8 @@ export function injectContext(
   };
 
   // Resolve ContentCollection and ContentEntry $prototype entries
-  if (collections.size > 0) {
-    resolveContentPrototypes(doc.state, collections, route._pathParams ?? {});
+  if (contentTypes.size > 0) {
+    resolveContentPrototypes(doc.state, contentTypes, route._pathParams ?? {});
   }
 
   // Merge project-level state into page state (page wins on conflicts)
@@ -110,33 +110,33 @@ export function injectContext(
 /**
  * Resolve ContentCollection and ContentEntry $prototype state entries.
  *
- * Replaces state entries like: { "$prototype": "ContentCollection", "collection": "blog", ... }
- * with the actual resolved collection data.
+ * Replaces state entries like: { "$prototype": "ContentCollection", "contentType": "blog", ... }
+ * with the actual resolved content type data.
  *
  * @param {Record<string, any>} state - Page state (mutated)
- * @param {Map<string, any[]>} collections - Loaded collections
+ * @param {Map<string, any[]>} contentTypes - Loaded content types
  * @param {Record<string, any>} params - Route parameters for $ref resolution
  */
-function resolveContentPrototypes(state, collections, params) {
+function resolveContentPrototypes(state, contentTypes, params) {
   for (const [key, value] of Object.entries(state)) {
     if (!value || typeof value !== "object" || !value.$prototype) continue;
 
     if (value.$prototype === "ContentCollection") {
-      const entries = collections.get(value.collection);
+      const entries = contentTypes.get(value.contentType);
       if (!entries) {
-        console.warn(`ContentCollection: collection "${value.collection}" not found`);
+        console.warn(`ContentCollection: content type "${value.contentType}" not found`);
         state[key] = [];
         continue;
       }
-      state[key] = queryCollection(entries, {
+      state[key] = queryContentType(entries, {
         filter: value.filter,
         sort: value.sort,
         limit: value.limit,
       });
     } else if (value.$prototype === "ContentEntry") {
-      const entries = collections.get(value.collection);
+      const entries = contentTypes.get(value.contentType);
       if (!entries) {
-        console.warn(`ContentEntry: collection "${value.collection}" not found`);
+        console.warn(`ContentEntry: content type "${value.contentType}" not found`);
         state[key] = null;
         continue;
       }

package/src/site/pages-discovery.js

@@ -162,17 +162,17 @@ function fileToRoute(relativePath, absolutePath) {
 /**
  * Expand dynamic routes by resolving $paths from each dynamic page.
  *
- * Supports three $paths shapes (per spec §4.3): 1. Collection-based: { collection: "blog", param:
- * "slug", field: "id" } 2. Explicit values: { values: ["en", "fr"], param: "lang" } 3. Data file
- * ref: { "$ref": "./data/products.json", param: "id", field: "sku" } 4. Legacy array: [{ slug:
+ * Supports three $paths shapes (per spec §4.3): 1. Content type-based: { contentType: "blog",
+ * param: "slug", field: "id" } 2. Explicit values: { values: ["en", "fr"], param: "lang" } 3. Data
+ * file ref: { "$ref": "./data/products.json", param: "id", field: "sku" } 4. Legacy array: [{ slug:
  * "hello" }, { slug: "world" }]
  *
  * @param {Route[]} routes - Discovered route table
  * @param {string} projectRoot - Project root for resolving $ref paths
- * @param {Map<string, any[]>} [collections] - Loaded content collections (from content-loader)
+ * @param {Map<string, any[]>} [contentTypes] - Loaded content types (from content-loader)
  * @returns {Promise<Route[]>} Expanded routes with concrete paths
  */
-export async function expandDynamicRoutes(routes, projectRoot, collections = new Map()) {
+export async function expandDynamicRoutes(routes, projectRoot, contentTypes = new Map()) {
   /** @type {Route[]} */
   const expanded = [];
 
@@ -197,7 +197,7 @@ export async function expandDynamicRoutes(routes, projectRoot, collections = new
       continue;
     }
 
-    const pathEntries = resolvePathEntries(raw.$paths, projectRoot, collections);
+    const pathEntries = resolvePathEntries(raw.$paths, projectRoot, contentTypes);
 
     for (const pathEntry of pathEntries) {
       let concreteUrl = route.urlPattern;
@@ -225,21 +225,21 @@ export async function expandDynamicRoutes(routes, projectRoot, collections = new
  *
  * @param {any} $paths - The $paths declaration
  * @param {string} projectRoot
- * @param {Map<string, any[]>} collections
+ * @param {Map<string, any[]>} contentTypes
  * @returns {Record<string, any>[]} Array of { paramName: value } objects
  */
-function resolvePathEntries($paths, projectRoot, collections) {
+function resolvePathEntries($paths, projectRoot, contentTypes) {
   // Legacy: array of param objects
   if (Array.isArray($paths)) {
     return $paths;
   }
 
-  // Collection-based: { collection: "blog", param: "slug", field: "id" }
-  if ($paths.collection) {
-    const entries = collections.get($paths.collection);
+  // Content type-based: { contentType: "blog", param: "slug", field: "id" }
+  if ($paths.contentType) {
+    const entries = contentTypes.get($paths.contentType);
     if (!entries || entries.length === 0) {
       console.warn(
-        `Warning: $paths references collection "${$paths.collection}" but it has no entries`,
+        `Warning: $paths references content type "${$paths.contentType}" but it has no entries`,
       );
       return [];
     }