azoxjs 0.1.0 → 0.3.0

package/core/build.js

@@ -3,14 +3,27 @@
 // result. `azox compile` runs it once; `azox dev` runs it on every
 // change, so it returns data rather than printing.
 
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  copyFileSync,
+  existsSync,
+  readdirSync,
+  rmSync,
+} from 'node:fs';
+import { resolve, basename, relative, dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
 
 import { parseAzox } from './compiler/parser.js';
 import { resolveComponents } from './compiler/resolveComponents.js';
 import { compileToModule } from './compiler/compileToJs.js';
 import { renderToHtml } from './renderer/renderToHtml.js';
-import { collectRoutes, findRoute } from './routes.js';
+import { parseImports } from './renderer/moduleBindings.js';
+import { evaluateScript } from './renderer/serverScope.js';
+import { escapeHtml } from './compiler/html.js';
+import { collectRoutes, findRoute, resolveRoute, PAGE_EXTENSION } from './routes.js';
+import { createNodeResolver } from './nodeResolver.js';
 import { ROOT_DIR } from './meta.js';
 import { BuildError } from './buildError.js';
 
@@ -20,7 +33,15 @@ import { BuildError } from './buildError.js';
 // host can serve it with no install step.
 const RUNTIME_FILENAME = 'azox-runtime.js';
 
+// The client-side router is opt-in, via `router: true` in the project's
+// package.json. Changing how every link behaves is not something a
+// project should get without asking, and a site of plain documents is
+// perfectly well served by ordinary navigation.
+const ROUTER_FILENAME = 'azox-router.js';
+
 export const PAGES_DIR = 'pages';
+export const COMPONENTS_DIR = 'components';
+export const PUBLIC_DIR = 'public';
 export const BUILD_DIR = '.azox/build';
 
 export { BuildError };
@@ -37,12 +58,21 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
 
   // Components are inlined here, before either output is produced, so
   // the compiler and the renderer both see plain markup.
-  const ast = resolveComponents(parsed, sourcePath);
+  const ast = resolveComponents(parsed, sourcePath, createNodeResolver());
+
+  // Imports the script pulls in are loaded once: server rendering
+  // evaluates against them, and the client module inlines them rather
+  // than importing a path that is never deployed.
+  const inlineModules = loadModules(ast.script, sourcePath, ast.componentImports ?? []);
 
   // SSR pass: render initial markup without touching browser DOM APIs.
   let html;
   try {
-    html = renderToHtml(ast, buildServerScope(ast.script));
+    html = renderToHtml(
+      ast,
+      buildServerScope(ast.script, inlineModules, route.params),
+      inlineModules
+    );
   } catch (error) {
     if (!(error instanceof BuildError)) throw error;
     throw new BuildError(`in ${PAGES_DIR}/${name}.azox: ${error.message}`);
@@ -62,9 +92,16 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
 
   const clientModule = rewriteRuntimeImports(
     compileToModule(ast, {
-      sourcePath,
-      outPath: clientPath,
       runtimeSpecifier,
+      // The user's own relative imports were written next to the
+      // page; the compiled module lives in .azox/build/, so they need
+      // re-expressing from there.
+      // An import hoisted out of a component is relative to that
+      // component's file, which is why the hook takes a path.
+      rewriteImports: (script, from = sourcePath) =>
+        rebaseImports(script, dirname(from), clientPath),
+      inlineModules,
+      routeParams: route.params ?? null,
     }),
     runtimeSpecifier
   );
@@ -76,7 +113,19 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   const runtimePath = resolve(buildRoot, RUNTIME_FILENAME);
   copyFileSync(resolve(ROOT_DIR, 'core/reactivity/signal.js'), runtimePath);
 
-  let document = wrapDocument(html, projectTitle(projectDir));
+  const router = routerEnabled(projectDir);
+  if (router) {
+    copyFileSync(resolve(ROOT_DIR, 'core/router/navigate.js'), resolve(buildRoot, ROUTER_FILENAME));
+  }
+
+  // A component's <head> block is merged in behind the page's own, so
+  // a layout can carry the stylesheet and fonts every page needs while
+  // the page keeps the last word on its title and description.
+  const head = mergeHeads(ast.head, ast.componentHeads ?? []);
+
+  let document = wrapDocument(html, projectTitle(projectDir), head, {
+    routerSrc: router ? `${route.assetPrefix}${ROUTER_FILENAME}` : null,
+  });
   if (transformHtml) document = transformHtml(document);
 
   const htmlPath = resolve(buildRoot, route.htmlPath);
@@ -94,24 +143,270 @@ export function buildAll(projectDir, options) {
     );
   }
 
-  return routes.map((route) => buildRoute(projectDir, route, options));
+  const results = expandTemplates(routes).map((route) =>
+    buildRoute(projectDir, route, options)
+  );
+  const assets = copyPublicAssets(projectDir);
+  removeStaleOutput(projectDir, results, assets);
+
+  return results;
+}
+
+// Turns each template into the concrete routes it declares, leaving
+// ordinary pages as they are. A template stands in for however many
+// pages its routes() call names, and is never written at its own url.
+function expandTemplates(routes) {
+  const expanded = [];
+  const seen = new Map();
+
+  for (const route of routes) {
+    if (!route.isTemplate) {
+      expanded.push(route);
+      continue;
+    }
+
+    for (const values of discoverRoutes(route)) {
+      const resolved = resolveRoute(route, values);
+
+      // Two entries producing the same url would have one silently
+      // overwrite the other, leaving a page missing with no sign of it.
+      const clash = seen.get(resolved.url);
+      if (clash) {
+        throw new BuildError(
+          `${relative(process.cwd(), route.sourcePath)} declares ${resolved.url} twice — ` +
+            `route parameters must be unique`
+        );
+      }
+
+      seen.set(resolved.url, route);
+      expanded.push(resolved);
+    }
+  }
+
+  return expanded;
+}
+
+// Runs a template's <script> with `routes` bound to a collector, so
+// the page declares its own pages from whatever data it imports.
+//
+// The script runs twice per page in total — once here to discover the
+// list, then once per page to render it. That is the cost of letting
+// the declaration be ordinary JavaScript rather than a separate
+// manifest the author has to keep in step.
+function discoverRoutes(route) {
+  const source = readFileSync(route.sourcePath, 'utf8');
+  const parsed = parseAzox(source);
+  const where = `${PAGES_DIR}/${route.name}${PAGE_EXTENSION}`;
+
+  if (!/\broutes\s*\(/.test(parsed.script)) {
+    throw new BuildError(
+      `in ${where}: a page with a [parameter] in its name must declare its pages — ` +
+        `add routes([...]) to its <script> block, for example ` +
+        `routes(posts.map((p) => ({ ${route.paramNames[0]}: p.${route.paramNames[0]} })))`
+    );
+  }
+
+  const collected = [];
+  const body = parsed.script.replace(/^\s*import\s.+?;?\s*$/gm, '');
+
+  try {
+    evaluateScript(
+      body,
+      [],
+      [],
+      loadModules(parsed.script, route.sourcePath),
+      {
+        routes: (list) => {
+          collected.push(...normaliseRouteList(list, where, route.paramNames));
+          return list;
+        },
+        // Discovery happens before any page exists, so params() has
+        // nothing to report yet. Returning an empty object lets a
+        // script that destructures it run without a special case.
+        params: () => ({}),
+      }
+    );
+  } catch (error) {
+    if (error instanceof BuildError) throw error;
+    throw new BuildError(`in ${where}: failed to work out which pages to build: ${error.message}`);
+  }
+
+  if (!collected.length) {
+    throw new BuildError(
+      `in ${where}: routes() was called with nothing, so no pages would be built. ` +
+        `If the list can be empty, that is fine — but the build has nothing to write.`
+    );
+  }
+
+  return collected;
+}
+
+// Each entry must supply every parameter the filename asks for. A
+// missing one would otherwise land in a url as "undefined".
+function normaliseRouteList(list, where, names) {
+  if (!Array.isArray(list)) {
+    throw new BuildError(
+      `in ${where}: routes() needs an array of objects — got ${typeof list}`
+    );
+  }
+
+  return list.map((entry, index) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new BuildError(
+        `in ${where}: routes() entry ${index} must be an object like { ${names[0]}: 'value' }`
+      );
+    }
+
+    for (const name of names) {
+      const value = entry[name];
+
+      if (value === undefined || value === null || value === '') {
+        throw new BuildError(
+          `in ${where}: routes() entry ${index} is missing "${name}", ` +
+            `which the filename asks for`
+        );
+      }
+
+      if (String(value).includes('/')) {
+        throw new BuildError(
+          `in ${where}: routes() entry ${index} has "${name}" set to "${value}", ` +
+            `which contains a "/" — a parameter fills one url segment`
+        );
+      }
+    }
+
+    return entry;
+  });
+}
+
+// Deletes output belonging to pages that no longer exist. Without
+// this, deleting a page leaves its built copy behind and a deployed
+// site keeps serving it.
+//
+// Deliberately narrow: it only ever removes an index.html or a
+// page.client.js that this build did not just write, and only inside
+// the build directory. Anything else found there — a file copied from
+// public/, something a user put there — is left alone.
+function removeStaleOutput(projectDir, results, assets = []) {
+  const buildRoot = resolve(projectDir, BUILD_DIR);
+  if (!existsSync(buildRoot)) return;
+
+  const written = new Set([
+    ...results.flatMap((result) => [result.htmlPath, result.clientPath]),
+    ...assets,
+  ]);
+
+  const generated = new Set(['index.html', 'page.client.js']);
+  const emptied = [];
+
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(full);
+        // A directory left empty held only pages that are now gone.
+        if (readdirSync(full).length === 0) emptied.push(full);
+        continue;
+      }
+
+      if (generated.has(entry.name) && !written.has(full)) rmSync(full);
+    }
+  };
+
+  walk(buildRoot);
+
+  // Innermost first, so a nested route's directories go too.
+  for (const dir of emptied.reverse()) {
+    if (existsSync(dir) && readdirSync(dir).length === 0) rmSync(dir, { recursive: true });
+  }
+}
+
+// Everything in public/ is copied to the build root untouched, so a
+// stylesheet, font or image is referenced by the same path in source
+// and in the built site: public/style.css -> /style.css.
+export function copyPublicAssets(projectDir) {
+  const publicDir = resolve(projectDir, PUBLIC_DIR);
+  if (!existsSync(publicDir)) return [];
+
+  const buildRoot = resolve(projectDir, BUILD_DIR);
+  const copied = [];
+
+  const walk = (dir, relativeDir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+
+      const from = join(dir, entry.name);
+      const to = join(buildRoot, relativeDir, entry.name);
+
+      if (entry.isDirectory()) {
+        mkdirSync(to, { recursive: true });
+        walk(from, join(relativeDir, entry.name));
+      } else {
+        mkdirSync(dirname(to), { recursive: true });
+        copyFileSync(from, to);
+        copied.push(to);
+      }
+    }
+  };
+
+  walk(publicDir, '');
+  return copied;
 }
 
 // Builds a single page by route name or URL.
 export function buildPage(projectDir, pageName, options) {
-  const route = findRoute(listRoutes(projectDir), pageName);
+  const routes = listRoutes(projectDir);
+  const route = findRoute(routes, pageName);
 
-  if (!route) {
-    throw new BuildError(`page "${PAGES_DIR}/${pageName}.azox" not found in ${projectDir}`);
+  // A template cannot be built at its own url, so naming it builds
+  // every page it declares — which is what the author means by
+  // `azox compile --page=blog/[slug]`.
+  if (route?.isTemplate) {
+    return expandTemplates([route]).map((page) => buildRoute(projectDir, page, options));
   }
 
-  return buildRoute(projectDir, route, options);
+  if (route) return buildRoute(projectDir, route, options);
+
+  // Not a file, so it may be one of the pages a template declares.
+  // Expanding them is the only way to know.
+  const generated = findRoute(
+    expandTemplates(routes.filter((candidate) => candidate.isTemplate)),
+    pageName
+  );
+
+  if (generated) return buildRoute(projectDir, generated, options);
+
+  throw new BuildError(`page "${PAGES_DIR}/${pageName}.azox" not found in ${projectDir}`);
 }
 
 // Rewrites the bare specifier a page's own <script> uses to the same
 // path the compiler emitted for the runtime import.
+//
+// Anchored to an import statement on its own line. Matching the bare
+// string anywhere would rewrite data that merely contains it — a JSON
+// import inlined into the module turned `"bin": {"azox": …}` into a
+// path to the runtime.
 function rewriteRuntimeImports(code, runtimeSpecifier) {
-  return code.replace(/(['"])azox(?:\/reactivity)?\1/g, `'${runtimeSpecifier}'`);
+  return code.replace(
+    /^([ \t]*import\s[\s\S]*?from\s+)(['"])azox(?:js)?(?:\/reactivity)?\2/gm,
+    `$1'${runtimeSpecifier}'`
+  );
+}
+
+// Re-expresses the relative imports in a page's <script> so they
+// still resolve from the compiled module's directory. Lives here
+// rather than in the compiler because it is a fact about where files
+// land on disk, which the compiler deliberately knows nothing about.
+function rebaseImports(script, sourceDir, outPath) {
+  return script.replace(
+    /(from\s+|import\s+)(['"])(\.[^'"]*)\2/g,
+    (full, keyword, quote, specifier) => {
+      let rebased = relative(dirname(outPath), resolve(sourceDir, specifier));
+      if (!rebased.startsWith('.')) rebased = `./${rebased}`;
+      return `${keyword}${quote}${rebased}${quote}`;
+    }
+  );
 }
 
 // A compiler must never write output it knows is broken. Parsing the
@@ -159,60 +454,191 @@ function projectTitle(projectDir) {
 // evaluate the expressions the template references. The script is
 // trusted project source, not user input — the same assumption any
 // template engine's SSR step makes.
-function buildServerScope(script) {
-  // Strip imports: the server supplies its own `signal` stub rather
-  // than loading the real reactive runtime.
-  const body = script.replace(/^\s*import\s.+?;\s*$/gm, '');
+function buildServerScope(script, modules = {}, params = null) {
+  // Strip imports: the server supplies its own primitives rather than
+  // loading the real reactive runtime, and anything else a script
+  // imports was resolved by loadModules and is passed in.
+  const body = script.replace(/^\s*import\s.+?;?\s*$/gm, '');
+
+  // A dynamic page reads its own parameters through params(), and its
+  // routes() call has already been answered by discovery — calling it
+  // again here would collect the list a second time to no purpose.
+  const extras = params
+    ? { params: () => params, routes: (list) => list }
+    : {};
 
   try {
-    const fn = new Function('signal', `${body}\nreturn { ${declaredNames(body).join(', ')} };`);
-    return fn(serverSignal);
+    return evaluateScript(body, [], [], modules, extras);
   } catch (error) {
+    if (error instanceof BuildError) throw error;
     throw new BuildError(`failed to evaluate the page's <script> block: ${error.message}`);
   }
 }
 
-// SSR needs only the current value, not reactivity, so `signal()` on
-// the server is a plain boxed value.
-function serverSignal(initial) {
-  let value = initial;
-  const read = () => value;
-  read.set = (next) => {
-    value = typeof next === 'function' ? next(value) : next;
-  };
-  read.peek = () => value;
-  return read;
-}
+// Resolves what a script's imports bring in, so server rendering sees
+// the same values the browser will.
+//
+// Only JSON is loaded. A JSON import is synchronous and has no side
+// effects, which suits a build step that must stay synchronous — and
+// it covers the case this exists for: reading a version or some other
+// constant out of package.json. Importing a .js module would mean
+// executing project code during the build, and `require(esm)` only
+// works from Node 22.12, below the floor this package declares.
+function loadModules(script, sourcePath, componentImports = []) {
+  // A component's hoisted import is relative to the component's own
+  // file, so each is resolved against the path it came with.
+  const imports = [
+    ...parseImports(script).map((entry) => ({ ...entry, from: sourcePath })),
+    ...componentImports.flatMap((entry) =>
+      parseImports(entry.statement).map((parsed) => ({ ...parsed, from: entry.path }))
+    ),
+  ];
+
+  if (!imports.length) return {};
+
+  const bindings = {};
+
+  for (const { specifier, bindings: names, from } of imports) {
+    if (!specifier.endsWith('.json')) {
+      throw new BuildError(
+        `cannot import '${specifier}': a <script> block may import .azox components, ` +
+          `'azox/reactivity', and .json files. Other modules are not available during ` +
+          `server rendering.`
+      );
+    }
 
-function declaredNames(script) {
-  const names = [];
-  const regex = /const\s+(\w+)\s*=/g;
-  let match;
-  while ((match = regex.exec(script))) names.push(match[1]);
-  return names;
+    const require = createRequire(from ? `file://${from}` : import.meta.url);
+
+    let loaded;
+    try {
+      // require caches by resolved path, which is wrong for a build
+      // that runs repeatedly in one process: `azox dev` would keep
+      // serving the data as it was when the server started, so editing
+      // a post changed nothing. Dropping the entry re-reads the file.
+      delete require.cache[require.resolve(specifier)];
+      loaded = require(specifier);
+    } catch (error) {
+      throw new BuildError(`cannot import '${specifier}': ${error.message.split('\n')[0]}`);
+    }
+
+    for (const { local, imported } of names) {
+      if (imported === '*' || imported === 'default') bindings[local] = loaded;
+      else bindings[local] = loaded[imported];
+    }
+  }
+
+  return bindings;
 }
 
 // The client module sits next to the page's index.html, so the src is
 // the same for every route regardless of how deep it is.
-function wrapDocument(bodyHtml, title) {
+// Combines the <head> blocks a page and its components contributed.
+//
+// Components come first so the page can override them: a <title> or a
+// <meta name="description"> set by a layout is a sensible default, and
+// the page that knows its own subject should win. Identical lines are
+// emitted once, so a layout and a page both asking for the same
+// stylesheet do not produce it twice.
+function mergeHeads(pageHead, componentHeads) {
+  const seen = new Set();
+  const lines = [];
+
+  // A page's <title> and description replace a component's rather than
+  // appearing alongside: two titles in one document is invalid.
+  const pageTags = uniqueHeadTags(pageHead);
+
+  for (const block of [...componentHeads, pageHead]) {
+    for (const line of (block ?? '').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      const key = normaliseHeadLine(trimmed);
+      if (seen.has(key)) continue;
+
+      // Dropped in favour of the page's own.
+      const tag = uniqueTagName(trimmed);
+      if (tag && block !== pageHead && pageTags.has(tag)) continue;
+
+      seen.add(key);
+      lines.push(trimmed);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// Tags a document may only hold one of, so a component's must give way
+// to the page's. Keyed by tag name, plus the `name` of a <meta> — two
+// different meta tags are fine, two descriptions are not.
+function uniqueTagName(line) {
+  const title = /^<title[\s>]/i.test(line);
+  if (title) return 'title';
+
+  const meta = line.match(/^<meta\s[^>]*name=["']([^"']+)["']/i);
+  if (meta) return `meta:${meta[1].toLowerCase()}`;
+
+  return null;
+}
+
+function uniqueHeadTags(head) {
+  const names = new Set();
+
+  for (const line of (head ?? '').split('\n')) {
+    const tag = uniqueTagName(line.trim());
+    if (tag) names.add(tag);
+  }
+
+  return names;
+}
+
+// Whitespace inside a tag should not make two identical links differ.
+function normaliseHeadLine(line) {
+  return line.replace(/\s+/g, ' ');
+}
+
+// A page's own <head> block wins over the fallback title, so a page
+// can set its own <title>, stylesheets and meta tags.
+function wrapDocument(bodyHtml, title, head = '', { routerSrc = null } = {}) {
+  const hasOwnTitle = /<title>/i.test(head);
+
+  // The router is loaded after the page's own module, so a page is
+  // interactive before navigation is enhanced.
+  const router = routerSrc
+    ? `\n<script type="module">import { startRouter } from '${routerSrc}'; startRouter();</script>`
+    : '';
+
   return `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>${escapeHtml(title)}</title>
-</head>
+${hasOwnTitle ? '' : `  <title>${escapeHtml(title)}</title>\n`}${head ? indent(head) + '\n' : ''}</head>
 <body>
 <div data-azox-root>${bodyHtml}</div>
-<script type="module" src="./page.client.js"></script>
+<script type="module" src="./page.client.js"></script>${router}
 </body>
 </html>
 `;
 }
 
-function escapeHtml(str) {
-  return String(str)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+// Reads `router` from the project's package.json. A malformed file is
+// not this function's problem to report — the build reads it again for
+// the page title and will surface anything wrong there.
+function routerEnabled(projectDir) {
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) return false;
+
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).router === true;
+  } catch {
+    return false;
+  }
 }
+
+function indent(block) {
+  return block
+    .split('\n')
+    .map((line) => (line.trim() ? `  ${line.trim()}` : line))
+    .join('\n');
+}
+

package/core/cli/router.js

@@ -20,11 +20,13 @@ export const registry = {
     run: devCommand,
     describe: 'Serve the project and rebuild on every change',
     examples: ['azox dev', 'azox dev --port=5000'],
+    flags: ['port', 'host'],
   },
   compile: {
     run: compileCommand,
     describe: 'Compile pages to HTML + hydration modules',
     examples: ['azox compile', 'azox compile --page=about'],
+    flags: ['page'],
   },
   doctor: {
     run: doctorCommand,
@@ -65,9 +67,35 @@ export function runCommand(command, context) {
     return;
   }
 
+  const unknown = unknownFlags(context.flags, entry.flags ?? []);
+
+  if (unknown.length) {
+    const plural = unknown.length === 1 ? 'flag' : 'flags';
+    console.error(
+      `Azox: unknown ${plural} for "${resolved}": ${unknown.map((f) => `--${f}`).join(', ')}`
+    );
+    console.error(
+      entry.flags?.length
+        ? `It accepts: ${entry.flags.map((f) => `--${f}`).join(', ')}.`
+        : 'It accepts no flags.'
+    );
+
+    process.exitCode = 1;
+    return;
+  }
+
   return entry.run({ ...context, registry });
 }
 
+// A mistyped flag used to be ignored, so `azox compile --pge=about`
+// quietly built every page while looking as though it had built one.
+// Command-selecting flags are allowed everywhere, since they are how
+// the command was chosen in the first place.
+function unknownFlags(flags, accepted) {
+  const always = new Set([...Object.keys(FLAG_ALIASES), ...accepted]);
+  return Object.keys(flags).filter((flag) => !always.has(flag));
+}
+
 function aliasFor(flags) {
   for (const [flag, command] of Object.entries(FLAG_ALIASES)) {
     if (flags[flag]) return command;

package/core/commands/compile.js

@@ -15,7 +15,11 @@ export function compileCommand({ flags }) {
   const projectDir = process.cwd();
 
   try {
-    const results = flags.page ? [buildPage(projectDir, flags.page)] : buildAll(projectDir);
+    // Naming a [parameter] template builds every page it declares, so
+    // buildPage may answer with more than one.
+    const results = flags.page
+      ? [buildPage(projectDir, flags.page)].flat()
+      : buildAll(projectDir);
 
     console.log(BANNER);
     console.log('');