@jxsuite/compiler 0.0.1

package/src/site/content-loader.js

@@ -0,0 +1,452 @@
+/**
+ * Content-loader.js — Content collection loader
+ *
+ * Loads content collections defined in project.json's `collections` key. Supports Markdown (.md),
+ * JSON (.json), and CSV (.csv) source files.
+ *
+ * Phase 2 implementation of site-architecture spec §6.
+ *
+ * @module content-loader
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, basename, extname } from "node:path";
+import { globSync } from "glob";
+
+// ─── CSV Parser (minimal, spec-compliant) ─────────────────────────────────────
+
+/**
+ * Parse a CSV string into an array of objects using the first row as headers. Handles quoted fields
+ * with commas and newlines.
+ *
+ * @param {string} csv - Raw CSV text
+ * @returns {Record<string, any>[]} Array of row objects
+ */
+function parseCSV(csv) {
+  /** @type {Record<string, any>[]} */
+  const rows = [];
+  let current = "";
+  let inQuotes = false;
+  /** @type {string[]} */
+  const lines = [];
+
+  // Split into rows respecting quoted newlines
+  for (let i = 0; i < csv.length; i++) {
+    const ch = csv[i];
+    if (ch === '"') {
+      if (inQuotes && csv[i + 1] === '"') {
+        current += '"';
+        i++;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if ((ch === "\n" || (ch === "\r" && csv[i + 1] === "\n")) && !inQuotes) {
+      lines.push(current);
+      current = "";
+      if (ch === "\r") i++;
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) lines.push(current);
+
+  if (lines.length === 0) return [];
+
+  /** @param {string} line */
+  const parseRow = (line) => {
+    /** @type {string[]} */
+    const fields = [];
+    let field = "";
+    let q = false;
+    for (let i = 0; i < line.length; i++) {
+      const ch = line[i];
+      if (ch === '"') {
+        if (q && line[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          q = !q;
+        }
+      } else if (ch === "," && !q) {
+        fields.push(field);
+        field = "";
+      } else {
+        field += ch;
+      }
+    }
+    fields.push(field);
+    return fields;
+  };
+
+  const headers = parseRow(lines[0]);
+  for (let i = 1; i < lines.length; i++) {
+    const fields = parseRow(lines[i]);
+    /** @type {Record<string, any>} */
+    const obj = {};
+    for (let j = 0; j < headers.length; j++) {
+      obj[headers[j].trim()] = fields[j]?.trim() ?? "";
+    }
+    rows.push(obj);
+  }
+  return rows;
+}
+
+// ─── Markdown loader ──────────────────────────────────────────────────────────
+
+/** @type {any} */
+let _mdModule = null;
+
+/**
+ * Lazily import @jxplatform/parser for Markdown support. This avoids hard dependency — only loads
+ * when MD collections exist.
+ *
+ * @returns {Promise<any>}
+ */
+async function getMarkdownModule() {
+  if (!_mdModule) {
+    _mdModule = await import("@jxplatform/parser");
+  }
+  return _mdModule;
+}
+
+/**
+ * Load a single markdown file into a ContentEntry.
+ *
+ * @param {string} filePath - Absolute path to .md file
+ * @returns {Promise<object>} ContentEntry shape
+ */
+/**
+ * Load a markdown file into a ContentEntry. If directiveOptions are provided, they control which
+ * custom element directives are available in the markdown.
+ *
+ * @param {string} filePath - Absolute path to .md file
+ * @param {any} [directiveOptions] - Options for the MarkdownDirective plugin
+ * @returns {Promise<object>} ContentEntry shape
+ */
+async function loadMarkdownEntry(filePath, directiveOptions) {
+  const { MarkdownFile } = await getMarkdownModule();
+  const file = new MarkdownFile({ src: filePath, directiveOptions });
+  const result = await file.resolve();
+  return {
+    id: result.slug,
+    data: result.frontmatter,
+    body: readFileSync(filePath, "utf-8"),
+    rendered: result.$body,
+    _meta: {
+      excerpt: result.$excerpt,
+      toc: result.$toc,
+      readingTime: result.$readingTime,
+      wordCount: result.$wordCount,
+    },
+  };
+}
+
+/**
+ * Load a JSON file into ContentEntry(s). If the file is an array, each element is an entry. If it's
+ * an object with an `id` field, it's a single entry.
+ *
+ * @param {string} filePath - Absolute path to .json file
+ * @returns {object[]} Array of ContentEntry shapes
+ */
+function loadJSONEntries(filePath) {
+  const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+  if (Array.isArray(raw)) {
+    return raw.map((/** @type {any} */ item, /** @type {number} */ i) => ({
+      id: item.id ?? basename(filePath, ".json") + "-" + i,
+      data: item,
+      body: null,
+      rendered: null,
+    }));
+  }
+  // Single object file — filename is the id
+  return [
+    {
+      id: raw.id ?? basename(filePath, ".json"),
+      data: raw,
+      body: null,
+      rendered: null,
+    },
+  ];
+}
+
+/**
+ * Load a CSV file into ContentEntry(s).
+ *
+ * @param {string} filePath - Absolute path to .csv file
+ * @param {any} [schema] - Collection schema (for type coercion)
+ * @returns {object[]} Array of ContentEntry shapes
+ */
+function loadCSVEntries(filePath, schema) {
+  const csv = readFileSync(filePath, "utf-8");
+  const rows = parseCSV(csv);
+  return rows.map((/** @type {Record<string, any>} */ row, /** @type {number} */ i) => {
+    // Apply type coercion based on schema if available
+    if (schema?.properties) {
+      for (const [key, def] of Object.entries(schema.properties)) {
+        const d = /** @type {any} */ (def);
+        if (key in row) {
+          if (d.type === "number") row[key] = Number(row[key]);
+          else if (d.type === "boolean") row[key] = row[key] === "true";
+        }
+      }
+    }
+    // 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 };
+  });
+}
+
+// ─── Content Config ───────────────────────────────────────────────────────────
+
+/**
+ * Load and parse content collections config from project.json.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {Record<string, any>} [projectConfig] - Already-loaded project config with `collections`
+ *   key
+ * @returns {{ config: any; contentDir: string } | null} Parsed config or null if no content dir
+ */
+export function loadContentConfig(projectRoot, projectConfig = undefined) {
+  const contentDir = resolve(projectRoot, "content");
+
+  /** @type {any} */
+  const config = { collections: projectConfig?.collections ?? {} };
+
+  return { config, contentDir };
+}
+
+// ─── Collection Loading ───────────────────────────────────────────────────────
+
+/**
+ * Load all content collections 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
+ */
+export async function loadCollections(projectRoot, projectConfig = undefined) {
+  const result = loadContentConfig(projectRoot, projectConfig);
+  if (!result) return new Map();
+
+  const { config } = result;
+  /** @type {Map<string, any[]>} */
+  const collections = new Map();
+
+  for (const [name, collectionDef] of Object.entries(config.collections)) {
+    const entries = await loadCollection(name, /** @type {any} */ (collectionDef), projectRoot);
+    collections.set(name, entries);
+  }
+
+  return collections;
+}
+
+/**
+ * Get the $elements array for a specific collection, if defined in project.json collections.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {string} collectionName - Name of the collection
+ * @param {Record<string, any>} [projectConfig] - Already-loaded project config
+ * @returns {any[] | undefined}
+ */
+export function getCollectionElements(projectRoot, collectionName, projectConfig = undefined) {
+  const result = loadContentConfig(projectRoot, projectConfig);
+  if (!result) return undefined;
+  const def = result.config.collections?.[collectionName];
+  return def?.$elements;
+}
+
+/**
+ * Load a single collection by its definition.
+ *
+ * @param {string} name - Collection name
+ * @param {any} collectionDef - Collection 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;
+
+  // Derive directive allowedNames from collection $elements (tag names from npm packages)
+  /** @type {any} */
+  const directiveOptions = collectionDef.$elements?.length
+    ? {
+        allowedNames: collectionDef.$elements
+          .filter((/** @type {any} */ e) => typeof e === "string" || e?.$ref)
+          .map((/** @type {any} */ e) => (typeof e === "string" ? e : e.$ref)),
+      }
+    : undefined;
+
+  // Resolve the glob pattern relative to project root
+  const pattern = resolve(projectRoot, source).split("\\").join("/");
+  const files = globSync(pattern, { absolute: true });
+
+  /** @type {any[]} */
+  const entries = [];
+
+  for (const filePath of files) {
+    const ext = extname(filePath).toLowerCase();
+
+    if (ext === ".md") {
+      entries.push(await loadMarkdownEntry(filePath, directiveOptions));
+    } else if (ext === ".json") {
+      entries.push(...loadJSONEntries(filePath));
+    } else if (ext === ".csv") {
+      entries.push(...loadCSVEntries(filePath, schema));
+    }
+  }
+
+  // Validate entries against schema if present
+  if (schema) {
+    validateEntries(entries, schema, name);
+  }
+
+  return entries;
+}
+
+// ─── Schema Validation ────────────────────────────────────────────────────────
+
+/**
+ * Validate content entries against their collection 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
+ */
+function validateEntries(entries, schema, collectionName) {
+  const required = schema.required ?? [];
+  const properties = schema.properties ?? {};
+
+  for (const entry of entries) {
+    // Check required fields
+    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}"`,
+        );
+      }
+    }
+
+    // Check types
+    for (const [field, def] of Object.entries(properties)) {
+      const d = /** @type {any} */ (def);
+      const value = entry.data[field];
+      if (value == null) continue;
+
+      if (d.type === "string" && typeof value !== "string") {
+        console.warn(
+          `Content validation: "${collectionName}/${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}`,
+        );
+      } else if (d.type === "boolean" && typeof value !== "boolean") {
+        console.warn(
+          `Content validation: "${collectionName}/${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}`,
+        );
+      }
+    }
+  }
+}
+
+// ─── Collection Querying ──────────────────────────────────────────────────────
+
+/**
+ * Query a loaded collection with filter, sort, and limit. Implements the ContentCollection
+ * $prototype resolution.
+ *
+ * @param {any[]} entries - Full collection entries
+ * @param {any} [query] - Query options
+ * @returns {any[]} Filtered, sorted, limited entries
+ */
+export function queryCollection(entries, query = {}) {
+  let result = [...entries];
+
+  // Filter
+  if (query.filter && typeof query.filter === "object") {
+    result = result.filter((/** @type {any} */ entry) => {
+      for (const [key, expected] of Object.entries(
+        /** @type {Record<string, any>} */ (query.filter),
+      )) {
+        const actual = entry.data[key];
+        if (actual !== expected) return false;
+      }
+      return true;
+    });
+  }
+
+  // Sort
+  if (query.sort) {
+    const { field, order = "asc" } = query.sort;
+    result.sort((/** @type {any} */ a, /** @type {any} */ b) => {
+      const aVal = a.data[field] ?? "";
+      const bVal = b.data[field] ?? "";
+      if (aVal < bVal) return order === "asc" ? -1 : 1;
+      if (aVal > bVal) return order === "asc" ? 1 : -1;
+      return 0;
+    });
+  }
+
+  // Limit
+  if (query.limit && query.limit > 0) {
+    result = result.slice(0, query.limit);
+  }
+
+  return result;
+}
+
+/**
+ * Find a single entry by ID in a collection. Implements the ContentEntry $prototype resolution.
+ *
+ * @param {any[]} entries - Full collection entries
+ * @param {string} id - Entry ID to find
+ * @returns {any | null} The matching entry or null
+ */
+export function findEntry(entries, id) {
+  return entries.find((/** @type {any} */ e) => e.id === id) ?? null;
+}
+
+// ─── Collection 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
+ * entry.
+ *
+ * @param {Map<string, any[]>} collections - All loaded collections @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);
+    const schema = cd.schema;
+    if (!schema?.properties) continue;
+
+    const entries = collections.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 (!refEntries) continue;
+
+      for (const entry of entries) {
+        const refId = entry.data[field];
+        if (typeof refId === "string") {
+          const resolved = refEntries.find((/** @type {any} */ e) => e.id === refId);
+          if (resolved) {
+            entry.data[field] = resolved;
+          }
+        }
+      }
+    }
+  }
+}

package/src/site/context-injection.js

@@ -0,0 +1,152 @@
+/**
+ * Context-injection.js — $page and $site context injection
+ *
+ * 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).
+ *
+ * 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 { resolve, dirname, relative } from "node:path";
+
+/**
+ * Inject $site and $page context into a page document's state.
+ *
+ * @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 {string | null} [projectRoot] - Absolute path to the project root (for import rebasing)
+ * @returns {any} The mutated document
+ */
+export function injectContext(
+  doc,
+  projectConfig,
+  route,
+  collections = new Map(),
+  projectRoot = null,
+) {
+  if (!doc.state) doc.state = {};
+
+  // $site context — read-only project-level data
+  doc.state.$site = {
+    name: projectConfig.name ?? "Jx Site",
+    url: projectConfig.url ?? "",
+    ...projectConfig.state,
+  };
+
+  // $page context — read-only page-level data
+  doc.state.$page = {
+    url: route.urlPattern,
+    title: doc.title ?? doc._pageTitle ?? projectConfig.name ?? "",
+    params: route._pathParams ?? {},
+  };
+
+  // Resolve ContentCollection and ContentEntry $prototype entries
+  if (collections.size > 0) {
+    resolveContentPrototypes(doc.state, collections, route._pathParams ?? {});
+  }
+
+  // Merge project-level state into page state (page wins on conflicts)
+  if (projectConfig.state) {
+    for (const [key, value] of Object.entries(projectConfig.state)) {
+      if (key !== "$site" && key !== "$page" && !(key in doc.state)) {
+        doc.state[key] = value;
+      }
+    }
+  }
+
+  // Merge project-level $media into page $media
+  if (projectConfig.$media) {
+    doc.$media = { ...projectConfig.$media, ...doc.$media };
+  }
+
+  // Merge project-level imports into page imports (page wins on collision)
+  if (projectConfig.imports && Object.keys(projectConfig.imports).length > 0) {
+    if (!doc.imports) doc.imports = {};
+    for (const [name, srcPath] of Object.entries(projectConfig.imports)) {
+      if (!(name in doc.imports)) {
+        const src = /** @type {string} */ (srcPath);
+        // Only rebase relative paths — bare/npm specifiers pass through unmodified
+        if (projectRoot && route.sourcePath && (src.startsWith("./") || src.startsWith("../"))) {
+          const abs = resolve(projectRoot, src);
+          doc.imports[name] = "./" + relative(dirname(route.sourcePath), abs);
+        } else {
+          doc.imports[name] = src;
+        }
+      }
+    }
+  }
+
+  // Merge project-level $elements into page $elements (union, dedup)
+  if (projectConfig.$elements?.length) {
+    if (!doc.$elements?.length) {
+      doc.$elements = [...projectConfig.$elements];
+    } else {
+      /** @type {Set<string>} */
+      const seen = new Set();
+      /** @type {any[]} */
+      const merged = [];
+      for (const entry of [...projectConfig.$elements, ...doc.$elements]) {
+        const key = typeof entry === "string" ? entry : entry?.$ref;
+        if (key && !seen.has(key)) {
+          seen.add(key);
+          merged.push(entry);
+        }
+      }
+      doc.$elements = merged;
+    }
+  }
+
+  return doc;
+}
+
+/**
+ * Resolve ContentCollection and ContentEntry $prototype state entries.
+ *
+ * Replaces state entries like: { "$prototype": "ContentCollection", "collection": "blog", ... }
+ * with the actual resolved collection data.
+ *
+ * @param {Record<string, any>} state - Page state (mutated)
+ * @param {Map<string, any[]>} collections - Loaded collections
+ * @param {Record<string, any>} params - Route parameters for $ref resolution
+ */
+function resolveContentPrototypes(state, collections, 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);
+      if (!entries) {
+        console.warn(`ContentCollection: collection "${value.collection}" not found`);
+        state[key] = [];
+        continue;
+      }
+      state[key] = queryCollection(entries, {
+        filter: value.filter,
+        sort: value.sort,
+        limit: value.limit,
+      });
+    } else if (value.$prototype === "ContentEntry") {
+      const entries = collections.get(value.collection);
+      if (!entries) {
+        console.warn(`ContentEntry: collection "${value.collection}" not found`);
+        state[key] = null;
+        continue;
+      }
+      // Resolve the ID — may reference $params
+      let id = value.id;
+      if (id && typeof id === "object" && id.$ref?.startsWith("#/$params/")) {
+        const paramName = id.$ref.replace("#/$params/", "");
+        id = params[paramName];
+      }
+      state[key] = findEntry(entries, id);
+    }
+  }
+}