azoxjs 0.1.0

package/core/compiler/parser.js

@@ -0,0 +1,317 @@
+// Parses a .azox source file into a small AST. Deliberately not
+// JSX: no React-flavored syntax, just HTML with {expr} interpolation
+// and on:event bindings. This stays simple because the compiler's
+// job is narrow — turn markup + bindings into signal-driven DOM ops.
+
+import { BuildError } from '../buildError.js';
+
+// Extends BuildError so a malformed page is reported as the user's
+// problem, not as an Azox crash.
+export class ParseError extends BuildError {}
+
+const VOID_TAGS = new Set(['br', 'hr', 'img', 'input', 'meta', 'link']);
+
+// A capitalised tag is a component, the way a lowercase one is an
+// HTML element. That keeps the distinction visible in the markup
+// itself, with no separate registration step.
+const isComponentName = (name) => /^[A-Z]/.test(name);
+
+export function parseAzox(source) {
+  const scriptMatch = source.match(/<script>([\s\S]*?)<\/script>/);
+  const script = scriptMatch ? scriptMatch[1].trim() : '';
+  const template = source.replace(/<script>[\s\S]*?<\/script>/, '').trim();
+
+  const tokens = tokenize(template);
+  const { node, rest } = parseNode(tokens);
+  if (rest.length) {
+    throw new ParseError(`Azox parse error: unexpected trailing markup near "${rest[0]?.value ?? ''}"`);
+  }
+
+  return {
+    script,
+    markup: node,
+    components: parseComponentImports(script),
+    props: parsePropNames(script),
+  };
+}
+
+// Component imports are written as ordinary import statements, so an
+// editor treats them like any other module reference:
+//   import Card from '../components/Card.azox';
+function parseComponentImports(script) {
+  const imports = {};
+  const regex = /import\s+([A-Z]\w*)\s+from\s+['"]([^'"]+\.azox)['"]\s*;?/g;
+
+  let match;
+  while ((match = regex.exec(script))) {
+    imports[match[1]] = match[2];
+  }
+
+  return imports;
+}
+
+// `const { title, count } = props();` declares what a component
+// accepts. Declaring them explicitly lets the compiler reject a
+// caller that passes something the component never asked for.
+function parsePropNames(script) {
+  const match = script.match(/const\s*\{([^}]*)\}\s*=\s*props\(\)/);
+  if (!match) return [];
+
+  return match[1]
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
+
+function tokenize(html) {
+  const tokens = [];
+  let i = 0;
+
+  while (i < html.length) {
+    if (html[i] === '<') {
+      const isClose = html[i + 1] === '/';
+      const end = findTagEnd(html, i);
+      const raw = html.slice(i + (isClose ? 2 : 1), end).trim();
+
+      if (isClose) {
+        tokens.push({ type: 'close', name: raw });
+      } else {
+        const selfClosing = raw.endsWith('/');
+        const body = selfClosing ? raw.slice(0, -1).trim() : raw;
+        const [name, ...attrParts] = splitTag(body);
+        tokens.push({
+          type: 'open',
+          name,
+          attrs: parseAttrs(attrParts.join(' ')),
+          selfClosing: selfClosing || VOID_TAGS.has(name),
+        });
+      }
+      i = end + 1;
+    } else {
+      const next = html.indexOf('<', i);
+      const text = html.slice(i, next === -1 ? undefined : next);
+      if (text.trim().length) tokens.push({ type: 'text', value: text.trim() });
+      i = next === -1 ? html.length : next;
+    }
+  }
+
+  return tokens;
+}
+
+// Finds the ">" that actually closes a tag, ignoring any ">" inside
+// a {expr} attribute value (arrow functions) or inside a string.
+function findTagEnd(html, start) {
+  let depth = 0;
+  let quote = null;
+
+  for (let i = start; i < html.length; i++) {
+    const char = html[i];
+
+    if (quote) {
+      if (char === '\\') i++;
+      else if (char === quote) quote = null;
+      continue;
+    }
+
+    if (depth > 0 && (char === '"' || char === "'" || char === '`')) quote = char;
+    else if (char === '{') depth++;
+    else if (char === '}') depth--;
+    else if (char === '>' && depth === 0) return i;
+  }
+
+  throw new ParseError('Azox parse error: unterminated tag');
+}
+
+// Splits a tag body into its name and attribute chunks, keeping any
+// whitespace that falls inside an expression or a quoted value.
+function splitTag(body) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let current = '';
+
+  for (let i = 0; i < body.length; i++) {
+    const char = body[i];
+
+    if (quote) {
+      current += char;
+      if (char === '\\') current += body[++i] ?? '';
+      else if (char === quote) quote = null;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
+      current += char;
+      continue;
+    }
+
+    if (char === '{') depth++;
+    else if (char === '}') depth--;
+
+    if (/\s/.test(char) && depth === 0) {
+      if (current) parts.push(current);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  if (current) parts.push(current);
+  return parts;
+}
+
+// Scanned rather than matched with a regex: an expression can nest
+// braces (an object literal, a template literal), and no regex can
+// pair those. Getting this wrong silently truncates the expression.
+function parseAttrs(attrString) {
+  const attrs = {};
+  let i = 0;
+
+  while (i < attrString.length) {
+    if (/\s/.test(attrString[i])) {
+      i++;
+      continue;
+    }
+
+    const nameEnd = findAttrNameEnd(attrString, i);
+    const name = attrString.slice(i, nameEnd);
+
+    if (!name) {
+      i++;
+      continue;
+    }
+
+    // A bare attribute with no value, e.g. `disabled`.
+    if (attrString[nameEnd] !== '=') {
+      attrs[name] = { kind: 'static', value: '' };
+      i = nameEnd;
+      continue;
+    }
+
+    const valueStart = nameEnd + 1;
+    const quote = attrString[valueStart];
+
+    if (quote === '"' || quote === "'") {
+      const end = attrString.indexOf(quote, valueStart + 1);
+      if (end === -1) {
+        throw new ParseError(`Azox parse error: unterminated value for attribute "${name}"`);
+      }
+      attrs[name] = { kind: 'static', value: attrString.slice(valueStart + 1, end) };
+      i = end + 1;
+      continue;
+    }
+
+    if (quote === '{') {
+      const end = findExpressionEnd(attrString, valueStart, `the {expression} for "${name}"`);
+      attrs[name] = { kind: 'expr', expr: attrString.slice(valueStart + 1, end).trim() };
+      i = end + 1;
+      continue;
+    }
+
+    throw new ParseError(
+      `Azox parse error: attribute "${name}" needs a quoted value or a {expression}`
+    );
+  }
+
+  return attrs;
+}
+
+function findAttrNameEnd(source, start) {
+  let i = start;
+  while (i < source.length && /[\w:.@-]/.test(source[i])) i++;
+  return i;
+}
+
+// Walks from the opening brace to its match, tracking nesting depth
+// and skipping over string and template literals so a brace inside
+// quotes never ends the expression.
+function findExpressionEnd(source, start, describe) {
+  let depth = 0;
+  let quote = null;
+
+  for (let i = start; i < source.length; i++) {
+    const char = source[i];
+
+    if (quote) {
+      if (char === '\\') i++;
+      else if (char === quote) quote = null;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
+    } else if (char === '{') {
+      depth++;
+    } else if (char === '}') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+
+  throw new ParseError(`Azox parse error: ${describe} is never closed`);
+}
+
+function parseNode(tokens) {
+  const [token, ...rest] = tokens;
+
+  if (!token) return { node: null, rest: [] };
+
+  if (token.type === 'text') {
+    return { node: { type: 'text', parts: splitInterpolation(token.value) }, rest };
+  }
+
+  if (token.type === 'open') {
+    const { name, attrs, selfClosing } = token;
+    const type = isComponentName(name) ? 'component' : 'element';
+
+    if (selfClosing) {
+      return { node: { type, name, attrs, children: [] }, rest };
+    }
+
+    const children = [];
+    let remaining = rest;
+    while (remaining.length && !(remaining[0].type === 'close' && remaining[0].name === name)) {
+      const result = parseNode(remaining);
+      if (result.node) children.push(result.node);
+      remaining = result.rest;
+    }
+
+    if (!remaining.length) {
+      throw new ParseError(`Azox parse error: <${name}> is never closed`);
+    }
+
+    remaining = remaining.slice(1); // drop the matching close tag
+
+    return { node: { type, name, attrs, children }, rest: remaining };
+  }
+
+  return { node: null, rest };
+}
+
+// Splits "Clicks: {count()}" into
+// [{kind:'static', value:'Clicks: '}, {kind:'expr', expr:'count()'}]
+//
+// Uses the same brace-depth scan as attributes, so an interpolated
+// expression may contain nested braces and strings.
+function splitInterpolation(text) {
+  const parts = [];
+  let i = 0;
+
+  while (i < text.length) {
+    const start = text.indexOf('{', i);
+
+    if (start === -1) {
+      parts.push({ kind: 'static', value: text.slice(i) });
+      break;
+    }
+
+    if (start > i) parts.push({ kind: 'static', value: text.slice(i, start) });
+
+    const end = findExpressionEnd(text, start, 'an interpolated {expression}');
+    parts.push({ kind: 'expr', expr: text.slice(start + 1, end).trim() });
+    i = end + 1;
+  }
+
+  return parts;
+}

package/core/compiler/resolveComponents.js

@@ -0,0 +1,184 @@
+// Resolves <Component /> usage at build time by inlining each
+// component's markup into its caller.
+//
+// Nothing survives into the runtime: there is no component instance,
+// no lifecycle, no reconciliation. A component is a compile-time unit
+// of reuse, so the emitted code looks the same as if the markup had
+// been written by hand.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import { parseAzox } from './parser.js';
+import { BuildError } from '../buildError.js';
+
+// Extends BuildError so the CLI reports it as a user-facing problem
+// rather than an internal crash with a stack trace.
+export class ComponentError extends BuildError {}
+
+// Returns the AST with every component reference replaced by that
+// component's markup. The caller's script is untouched: components
+// contribute markup only.
+export function resolveComponents(ast, sourcePath, seen = new Set()) {
+  return { ...ast, markup: expand(ast.markup, ast, sourcePath, seen) };
+}
+
+function expand(node, ast, sourcePath, seen) {
+  if (!node || node.type === 'text') return node;
+
+  const children = (node.children ?? []).map((child) => expand(child, ast, sourcePath, seen));
+
+  if (node.type !== 'component') {
+    return { ...node, children };
+  }
+
+  const component = loadComponent(node.name, ast, sourcePath, seen);
+  validateProps(node, component);
+  validateNoLocalState(node.name, component);
+
+  // The component's own body may reference further components, so
+  // expand it in its own directory against its own imports.
+  const inner = resolveComponents(component.ast, component.path, new Set([...seen, component.path]));
+
+  return substituteProps(inner.markup, propValues(node, component.ast.props), children);
+}
+
+function loadComponent(name, ast, sourcePath, seen) {
+  const specifier = ast.components[name];
+
+  if (!specifier) {
+    throw new ComponentError(
+      `<${name}> is used but never imported. Add: import ${name} from './components/${name}.azox';`
+    );
+  }
+
+  const path = resolve(dirname(sourcePath), specifier);
+
+  if (seen.has(path)) {
+    throw new ComponentError(`component cycle detected: ${name} eventually renders itself`);
+  }
+
+  if (!existsSync(path)) {
+    throw new ComponentError(`<${name}> points at ${specifier}, which does not exist`);
+  }
+
+  return { path, ast: parseAzox(readFileSync(path, 'utf8')) };
+}
+
+// Components are presentational in this version: they take props and
+// render markup. Because a component is inlined into its caller,
+// state declared inside one would share the caller's scope and could
+// collide with it — so it is rejected outright rather than producing
+// a subtle bug. Lifting the restriction needs per-component scoping,
+// which is a deliberate design step, not an accident.
+function validateNoLocalState(name, component) {
+  const script = component.ast.script;
+  if (!script) return;
+
+  const withoutImports = script.replace(/^\s*import\s.+?;?\s*$/gm, '');
+  const withoutProps = withoutImports.replace(/const\s*\{[^}]*\}\s*=\s*props\(\)\s*;?/, '');
+
+  if (withoutProps.trim()) {
+    throw new ComponentError(
+      `<${name}> declares logic beyond props(), which this version does not support. ` +
+        'Components take props and render markup; keep state in the page that uses them.'
+    );
+  }
+}
+
+// A caller passing something the component never declared is almost
+// always a typo, and silently dropping it hides the mistake.
+function validateProps(node, component) {
+  const declared = new Set(component.ast.props);
+
+  for (const attr of Object.keys(node.attrs)) {
+    if (attr.startsWith('on:')) continue;
+
+    if (!declared.has(attr)) {
+      const known = component.ast.props.length
+        ? `It accepts: ${component.ast.props.join(', ')}.`
+        : 'It declares no props.';
+      throw new ComponentError(`<${node.name}> was given "${attr}", which it does not declare. ${known}`);
+    }
+  }
+}
+
+// Maps each declared prop to the expression the caller supplied.
+// A static attribute becomes a quoted string; an {expr} attribute is
+// passed through so it keeps its reactivity.
+function propValues(node, declared) {
+  const values = {};
+
+  for (const name of declared) {
+    const attr = node.attrs[name];
+
+    if (!attr) {
+      values[name] = 'undefined';
+    } else if (attr.kind === 'static') {
+      values[name] = JSON.stringify(attr.value);
+    } else {
+      values[name] = attr.expr;
+    }
+  }
+
+  return values;
+}
+
+// Rewrites references to a component's props inside its markup with
+// the caller's expressions, and drops <slot /> in favour of the
+// children the caller nested inside the tag.
+function substituteProps(node, values, slotChildren) {
+  if (!node) return node;
+
+  if (node.type === 'text') {
+    return {
+      ...node,
+      parts: node.parts.map((part) => {
+        if (part.kind !== 'expr') return part;
+
+        const expr = rewrite(part.expr, values);
+
+        // A prop passed as a plain string collapses to a literal, and
+        // static text needs no effect wrapping it at runtime.
+        const literal = asStringLiteral(expr);
+        return literal === null ? { ...part, expr } : { kind: 'static', value: literal };
+      }),
+    };
+  }
+
+  if (node.type === 'element' && node.name === 'slot') {
+    return { type: 'fragment', children: slotChildren };
+  }
+
+  const attrs = {};
+  for (const [key, attr] of Object.entries(node.attrs ?? {})) {
+    attrs[key] = attr.kind === 'expr' ? { ...attr, expr: rewrite(attr.expr, values) } : attr;
+  }
+
+  return {
+    ...node,
+    attrs,
+    children: (node.children ?? []).map((child) => substituteProps(child, values, slotChildren)),
+  };
+}
+
+// Returns the string a wholly-literal expression represents, or null
+// when the expression is anything the compiler must evaluate.
+function asStringLiteral(expr) {
+  const match = expr.trim().match(/^\((("(?:[^"\\]|\\.)*")|('(?:[^'\\]|\\.)*'))\)$/);
+  if (!match) return null;
+
+  try {
+    return JSON.parse(match[2] ?? match[3].replace(/^'|'$/g, '"'));
+  } catch {
+    return null;
+  }
+}
+
+// Replaces whole-word prop identifiers. Property access (obj.title)
+// and string contents are left alone.
+function rewrite(expr, values) {
+  return expr.replace(/(?<![.\w$])([A-Za-z_$][\w$]*)/g, (match) =>
+    Object.hasOwn(values, match) ? `(${values[match]})` : match
+  );
+}

package/core/dev/liveReload.js

@@ -0,0 +1,20 @@
+// The snippet injected into pages served by `azox dev`. It is never
+// written to disk by `azox compile`, so production output stays free
+// of dev machinery.
+
+import { RELOAD_PATH } from './server.js';
+
+const SNIPPET = `<script>
+  (() => {
+    const source = new EventSource('${RELOAD_PATH}');
+    source.addEventListener('reload', () => location.reload());
+    // Losing the connection means the dev server stopped; EventSource
+    // retries on its own, so the page reloads when it comes back.
+  })();
+</script>`;
+
+export function injectLiveReload(html) {
+  return html.includes('</body>')
+    ? html.replace('</body>', `${SNIPPET}\n</body>`)
+    : html + SNIPPET;
+}

package/core/dev/server.js

@@ -0,0 +1,179 @@
+// Static file server for `azox dev`, with a Server-Sent Events
+// channel used to tell connected browsers to reload.
+//
+// SSE rather than WebSockets: reload is a one-way signal, and SSE
+// needs no handshake implementation, which keeps this dependency-free
+// without carrying a protocol implementation.
+
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { join, extname, normalize, resolve, sep } from 'node:path';
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain; charset=utf-8',
+};
+
+export const RELOAD_PATH = '/__azox_reload';
+
+export function createDevServer({ rootDir }) {
+  const clients = new Set();
+
+  // While a build is broken, stale output would look like the edit
+  // simply didn't apply. Serving the error instead makes the actual
+  // problem visible in the browser.
+  let buildError = null;
+
+  const server = createServer(async (req, res) => {
+    if (req.url === RELOAD_PATH) {
+      openReloadStream(req, res, clients);
+      return;
+    }
+
+    if (buildError && isDocumentRequest(req.url)) {
+      send(res, 500, 'text/html; charset=utf-8', errorPage(buildError));
+      return;
+    }
+
+    await serveFile(req, res, rootDir);
+  });
+
+  return {
+    server,
+    listen: (port, host) => new Promise((done) => server.listen(port, host, done)),
+    setBuildError(error) {
+      buildError = error;
+    },
+    reload() {
+      for (const client of clients) client.write('event: reload\ndata: {}\n\n');
+    },
+    close() {
+      for (const client of clients) client.end();
+      clients.clear();
+      return new Promise((done) => server.close(done));
+    },
+    get connections() {
+      return clients.size;
+    },
+  };
+}
+
+// Only pages show the error overlay; assets keep their real status so
+// a failed script doesn't turn into an HTML body.
+function isDocumentRequest(url) {
+  const path = new URL(url, 'http://localhost').pathname;
+  return path.endsWith('/') || path.endsWith('.html') || !extname(path);
+}
+
+function openReloadStream(req, res, clients) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  });
+  res.write('retry: 500\n\n');
+
+  clients.add(res);
+  req.on('close', () => clients.delete(res));
+}
+
+async function serveFile(req, res, rootDir) {
+  const requested = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+  const filePath = resolveWithinRoot(rootDir, requested);
+
+  if (!filePath) {
+    send(res, 403, 'text/plain; charset=utf-8', 'Forbidden');
+    return;
+  }
+
+  try {
+    const target = (await stat(filePath)).isDirectory() ? join(filePath, 'index.html') : filePath;
+    const body = await readFile(target);
+    const type = MIME_TYPES[extname(target).toLowerCase()] ?? 'application/octet-stream';
+
+    // Dev output changes constantly; never let the browser cache it.
+    res.writeHead(200, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+    res.end(body);
+  } catch {
+    send(res, 404, 'text/html; charset=utf-8', notFoundPage(requested));
+  }
+}
+
+// Blocks path traversal: a request for ../../etc/passwd must not
+// escape the served directory.
+function resolveWithinRoot(rootDir, requestedPath) {
+  const root = resolve(rootDir);
+  const candidate = resolve(join(root, normalize(requestedPath)));
+
+  return candidate === root || candidate.startsWith(root + sep) ? candidate : null;
+}
+
+function send(res, status, type, body) {
+  res.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+  res.end(body);
+}
+
+function notFoundPage(path) {
+  return page('404', `<h1>404</h1><p>No file at <code>${escapeHtml(path)}</code></p>`);
+}
+
+function errorPage(error) {
+  return page(
+    'Build failed',
+    `<h1>Build failed</h1><pre>${escapeHtml(error.message)}</pre>`,
+    /* live */ true
+  );
+}
+
+function page(title, body, live = false) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>${title} · Azox</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body {
+      margin: 0; min-height: 100vh;
+      display: grid; place-items: center;
+      font: 15px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace;
+      padding: 2rem;
+    }
+    main { max-width: 60ch; }
+    h1 { font-size: 1.2rem; margin: 0 0 .75rem; }
+    pre {
+      white-space: pre-wrap; margin: 0;
+      padding: 1rem; border-radius: 8px;
+      background: color-mix(in srgb, currentColor 8%, transparent);
+    }
+    code { background: color-mix(in srgb, currentColor 8%, transparent); padding: .1em .35em; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <main>${body}</main>
+  ${live ? `<script>new EventSource('${RELOAD_PATH}').addEventListener('reload', () => location.reload());</script>` : ''}
+</body>
+</html>`;
+}
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}