@jxsuite/compiler 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -45,15 +45,15 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.5.0",
-    "@jxsuite/create": "^1.0.0",
-    "@jxsuite/runtime": "^1.0.0",
-    "@jxsuite/schema": "^1.0.0",
+    "@jxsuite/create": "^1.1.0",
+    "@jxsuite/runtime": "^1.1.0",
+    "@jxsuite/schema": "^1.1.0",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",
-    "@jxsuite/connector": "^0.2.0",
-    "@jxsuite/parser": "^1.0.0",
+    "@jxsuite/connector": "^0.3.0",
+    "@jxsuite/parser": "^1.1.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/cli.ts

@@ -23,6 +23,8 @@ async function main() {
 
 Commands:
   build [root]     Build a Jx site to dist/
+  dev [root]       Start the dev server (requires @jxsuite/server and Bun)
+  preview [root]   Serve an already-built dist/ directory
   schema [root]    Generate project.schema.json + document.schema.json from project.json#/extensions
   validate [root]  Validate project.json against its generated project.schema.json
   db push [root]   Sync the data section's tables to their connections (additive-only)
@@ -30,6 +32,7 @@ Commands:
 Options:
   --verbose      Print detailed build progress
   --no-clean     Don't clean outDir before building
+  --port <n>     dev/preview: port to listen on (default 3000 / 4173)
   --dry-run      db push: print the statements without executing them
   --connection   db push: restrict to one connection name`);
     process.exit(0);
@@ -42,11 +45,18 @@ Options:
   const flags = new Set<string>();
   const positionals: string[] = [];
   let connectionArg: string | undefined;
+  let portArg: number | undefined;
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index]!;
     if (arg === "--connection") {
       index += 1;
       connectionArg = rest[index];
+    } else if (arg === "--port") {
+      index += 1;
+      const parsed = Math.trunc(Number(rest[index] ?? ""));
+      if (Number.isFinite(parsed) && parsed >= 0) {
+        portArg = parsed;
+      }
     } else if (arg.startsWith("--")) {
       flags.add(arg);
     } else {
@@ -118,6 +128,26 @@ Options:
       console.error(`Build failed: ${err.message}`);
       process.exit(1);
     }
+  } else if (command === "dev") {
+    try {
+      const { runDev } = await import("./site/dev-command.ts");
+      runDev(projectRoot, portArg);
+    } catch (error) {
+      const err = error as Error;
+      console.error(err.message);
+      process.exit(1);
+    }
+  } else if (command === "preview") {
+    const { existsSync } = await import("node:fs");
+    const distDir = resolve(projectRoot, "dist");
+    if (!existsSync(distDir)) {
+      console.error(`No build output at ${distDir} — run \`jx build\` first.`);
+      process.exit(1);
+    }
+    const { startPreviewServer } = await import("./site/preview-server.ts");
+    const port = portArg ?? 4173;
+    startPreviewServer(distDir, port);
+    console.log(`Previewing ${distDir} at http://localhost:${port}`);
   } else if (command === "schema") {
     try {
       const { writeProjectSchemas } = await import("./site/schema-command.ts");

package/src/shared.ts

@@ -8,11 +8,14 @@
 
 import { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
 import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { runStatements } from "@jxsuite/runtime/statements";
 import {
   childrenContainArray,
+  hasStructuredBody,
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
+  isNamedFormulaDef,
   isPrototypeDef,
   isRef,
   isSchemaOnlyDef as isSchemaOnly,
@@ -35,6 +38,28 @@ import type {
 // Re-export runtime utilities used by submodules
 export { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
 export { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+export { compileStatements, runStatements } from "@jxsuite/runtime/statements";
+
+/**
+ * Emit the JS source of a named formula's scope callable: positional arguments are mapped onto the
+ * declared parameter names (honoring CemParameter defaults) as the `_args` object the compiled
+ * body's `$args/` refs read from. Call sites stay positional, matching the interpreter.
+ */
+export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: string): string {
+  const entries: string[] = [];
+  for (const [i, p] of (def.parameters ?? []).entries()) {
+    const name = typeof p === "string" ? p : ((p as { name?: string } | null)?.name ?? "");
+    if (!name) {
+      continue;
+    }
+    const hasDefault = typeof p === "object" && p !== null && "default" in p;
+    const arg = hasDefault
+      ? `_a[${i}] === undefined ? ${JSON.stringify((p as { default?: unknown }).default)} : _a[${i}]`
+      : `_a[${i}]`;
+    entries.push(`${JSON.stringify(name)}: ${arg}`);
+  }
+  return `(..._a) => { const _args = { ${entries.join(", ")} }; return ${compiledBody}; }`;
+}
 export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
 // CDN defaults
@@ -283,7 +308,24 @@ export function buildInitialScope(
     }
     if (isExpressionDef(def)) {
       const node = def.$expression as ExpressionNode;
-      if (isMutating(node.operator)) {
+      if (isNamedFormulaDef(def)) {
+        // Named formula: callable, positional args mapped onto its declared parameters.
+        const params = def.parameters as (string | { name?: string; default?: unknown })[];
+        setOwnScopeValue(scope, key, (...argValues: unknown[]) => {
+          const args: Record<string, unknown> = {};
+          for (const [i, p] of params.entries()) {
+            const name = typeof p === "string" ? p : (p?.name ?? "");
+            if (!name) {
+              continue;
+            }
+            args[name] =
+              argValues[i] === undefined && typeof p === "object" && p !== null && "default" in p
+                ? p.default
+                : argValues[i];
+          }
+          return evaluateExpression(node, scope, null, { args });
+        });
+      } else if (isMutating(node.operator)) {
         setOwnScopeValue(scope, key, (s: Record<string, unknown>, event: Event) =>
           evaluateExpression(node, s, event),
         );
@@ -293,12 +335,19 @@ export function buildInitialScope(
       continue;
     }
     if (isFunctionDef(def)) {
-      if (def.body) {
+      if (hasStructuredBody(def)) {
+        // Structured body (spec §20): a side-effecting handler in the build-time scope.
+        const { body } = def;
+        setOwnScopeValue(scope, key, (s: Record<string, unknown>, event?: Event) => {
+          void runStatements(body, s ?? scope, event ?? null);
+        });
+      } else if (typeof def.body === "string") {
         const names = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
-        const fn = new Function("state", ...names, def.body) as (
+        const { body } = def;
+        const fn = new Function("state", ...names, body) as (
           state: Record<string, unknown>,
         ) => unknown;
-        if (def.body.includes("return")) {
+        if (body.includes("return")) {
           defineLazyScopeValue(scope, key, () => fn(scope));
         } else {
           setOwnScopeValue(scope, key, fn);

package/src/site/dev-command.ts

@@ -0,0 +1,84 @@
+/**
+ * Dev command — `jx dev` resolves the project's @jxsuite/server dev entry and spawns it under Bun.
+ *
+ * The compiler cannot depend on @jxsuite/server (the server already depends on the compiler), and
+ * the dev server is Bun-native while the jx bin runs under Node — so the command is pure resolution
+ * + spawn: the entry module is resolved from the PROJECT's node_modules and executed with Bun.
+ *
+ * @module dev-command
+ */
+
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+
+/**
+ * Resolve the project's `@jxsuite/server/dev` entry module.
+ *
+ * @param {string} projectRoot - Absolute project root
+ * @returns {string} Absolute path to the dev entry module
+ * @throws {Error} With an install hint when the package is not present
+ */
+export function resolveDevEntry(projectRoot: string): string {
+  try {
+    const projectRequire = createRequire(join(projectRoot, "package.json"));
+    return projectRequire.resolve("@jxsuite/server/dev");
+  } catch {
+    throw new Error(
+      `@jxsuite/server is not installed in ${projectRoot}. ` +
+        `Add it to devDependencies (e.g. \`bun add -d @jxsuite/server\`) and retry.`,
+    );
+  }
+}
+
+/** The slice of `process` runDev touches — injectable for tests. */
+export interface ProcessLike {
+  on: (event: string, handler: () => void) => unknown;
+  exitCode?: number | string | undefined;
+}
+
+/**
+ * Spawn the dev server under Bun with inherited stdio.
+ *
+ * @param {string} projectRoot - Absolute project root
+ * @param {number | undefined} port - Optional port override
+ * @param {typeof spawn} [spawnImpl] - Injectable for tests
+ * @param {ProcessLike} [proc] - Injectable for tests
+ * @returns {ChildProcess} The spawned Bun process
+ */
+export function runDev(
+  projectRoot: string,
+  port: number | undefined,
+  spawnImpl: typeof spawn = spawn,
+  proc: ProcessLike = process as unknown as ProcessLike,
+): ChildProcess {
+  const entry = resolveDevEntry(projectRoot);
+  const args = [entry, "--root", projectRoot];
+  if (port !== undefined) {
+    args.push("--port", String(port));
+  }
+  const child = spawnImpl("bun", args, { stdio: "inherit" });
+  child.on("error", (error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") {
+      console.error(
+        "The Jx dev server runs on Bun, which was not found on your PATH. " +
+          "Install it from https://bun.sh and retry.",
+      );
+    } else {
+      console.error(`Failed to start the dev server: ${error.message}`);
+    }
+    proc.exitCode = 1;
+  });
+  // Ctrl+C reaches the child through the shared process group; also mirror explicit kills.
+  proc.on("SIGINT", () => {
+    child.kill("SIGINT");
+  });
+  proc.on("SIGTERM", () => {
+    child.kill("SIGTERM");
+  });
+  child.on("exit", (code) => {
+    proc.exitCode = code ?? 0;
+  });
+  return child;
+}

package/src/site/head-merger.ts

@@ -63,6 +63,19 @@ export function mergeHead(
       attributes: { href: canonical, rel: "canonical" },
       tagName: "link",
     });
+    // Auto OpenGraph identity (site-architecture §8.4) — author-supplied values win.
+    if (!merged.has("meta:og:url")) {
+      merged.set("meta:og:url", {
+        attributes: { content: canonical, property: "og:url" },
+        tagName: "meta",
+      });
+    }
+  }
+  if (context.siteName && !merged.has("meta:og:site_name")) {
+    merged.set("meta:og:site_name", {
+      attributes: { content: context.siteName, property: "og:site_name" },
+      tagName: "meta",
+    });
   }
 
   return [...merged.values()];

package/src/site/image-cache.ts

@@ -6,7 +6,7 @@
  * CI environments (e.g. Cloudflare Pages) can persist it via their npm cache layer.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { execSync } from "node:child_process";
 import { tmpdir } from "node:os";
@@ -23,6 +23,7 @@ interface CacheEntry {
 export interface CacheManifest {
   version: number; // Cache format version
   entries: Record<string, CacheEntry>; // Cached entries keyed by content+config hash
+  touched?: Set<string>; // Keys resolved during this build — runtime only, never serialized
 }
 
 // ─── Cache directory resolution ──────────────────────────────────────────────
@@ -97,25 +98,73 @@ export function cacheKey(srcPath: string, config: ImageConfig) {
 export function loadCache(projectRoot: string): CacheManifest {
   const manifestPath = resolve(getImageCacheDir(projectRoot), "manifest.json");
   if (!existsSync(manifestPath)) {
-    return { entries: {}, version: 1 };
+    return { entries: {}, touched: new Set(), version: 1 };
   }
   try {
-    return JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
+    parsed.touched = new Set();
+    return parsed;
   } catch {
-    return { entries: {}, version: 1 };
+    return { entries: {}, touched: new Set(), version: 1 };
   }
 }
 
 /**
  * Save the cache manifest to disk.
  *
+ * With `prune: true`, entries whose key was never touched during this build (deleted/replaced
+ * sources, superseded configs) are dropped and their variant files deleted first, so a persisted
+ * cache — and the dist copy made from it — stays bounded to images the build actually uses.
+ *
  * @param {string} projectRoot
  * @param {CacheManifest} cache
+ * @param {{ prune?: boolean }} [options]
  */
-export function saveCache(projectRoot: string, cache: CacheManifest) {
+export function saveCache(
+  projectRoot: string,
+  cache: CacheManifest,
+  options: { prune?: boolean } = {},
+) {
+  if (options.prune && cache.touched) {
+    pruneStale(cache, cache.touched);
+  }
   const cacheDir = getImageCacheDir(projectRoot);
   mkdirSync(cacheDir, { recursive: true });
-  writeFileSync(resolve(cacheDir, "manifest.json"), JSON.stringify(cache, null, 2), "utf8");
+  writeFileSync(
+    resolve(cacheDir, "manifest.json"),
+    JSON.stringify({ entries: cache.entries, version: cache.version }, null, 2),
+    "utf8",
+  );
+}
+
+/**
+ * Remove entries (and their variant files) that were not touched during this build. A file shared
+ * with a surviving entry is kept — the same source under an older config produces overlapping
+ * width/format filenames, so deleting blindly would remove files a live entry still references.
+ *
+ * @param {CacheManifest} cache
+ * @param {Set<string>} touched
+ */
+function pruneStale(cache: CacheManifest, touched: Set<string>) {
+  const keep = new Set<string>();
+  for (const [key, entry] of Object.entries(cache.entries)) {
+    if (touched.has(key)) {
+      for (const variant of entry.manifest.variants ?? []) {
+        keep.add(variant.absolutePath);
+      }
+    }
+  }
+  for (const [key, entry] of Object.entries(cache.entries)) {
+    if (touched.has(key)) {
+      continue;
+    }
+    for (const variant of entry.manifest.variants ?? []) {
+      if (!keep.has(variant.absolutePath)) {
+        rmSync(variant.absolutePath, { force: true });
+      }
+    }
+    delete cache.entries[key];
+  }
 }
 
 // ─── Entry access ─────────────────────────────────────────────────────────────
@@ -128,6 +177,7 @@ export function saveCache(projectRoot: string, cache: CacheManifest) {
  * @returns {ImageManifest | null}
  */
 export function getCached(cache: CacheManifest, key: string) {
+  cache.touched?.add(key);
   const entry = cache.entries[key];
   if (!entry) {
     return null;
@@ -149,6 +199,7 @@ export function setCached(
   sourcePath: string,
   manifest: ImageManifest,
 ) {
+  cache.touched?.add(key);
   cache.entries[key] = {
     manifest,
     source: sourcePath,

package/src/site/image-transform.ts

@@ -318,6 +318,7 @@ async function transformImgNode(
   }
 
   let srcset;
+  let dims: { width: number; height: number } | null = null;
 
   if (remote) {
     // Original dimensions are unknown without fetching — emit every configured width and let
@@ -332,6 +333,7 @@ async function transformImgNode(
     if (config.service === "cloudflare") {
       const meta = await resolveCfMeta(absoluteSrc, metaCache);
       srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+      dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : null;
     } else {
       let manifest = imageRefs.get(absoluteSrc);
 
@@ -342,6 +344,10 @@ async function transformImgNode(
 
       const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
+      dims =
+        manifest.original?.width && manifest.original.height
+          ? { height: manifest.original.height, width: manifest.original.width }
+          : null;
     }
   }
 
@@ -350,6 +356,12 @@ async function transformImgNode(
     node.attributes.sizes ??= config.sizes;
   }
 
+  // Intrinsic dimensions prevent layout shift; author-supplied values win.
+  if (dims && node.attributes.width === undefined && node.attributes.height === undefined) {
+    node.attributes.width = String(dims.width);
+    node.attributes.height = String(dims.height);
+  }
+
   if (config.lazyLoad && node.attributes.loading !== "eager") {
     node.attributes.loading = "lazy";
     node.attributes.decoding = "async";
@@ -412,12 +424,14 @@ async function transformInnerHtmlImages(
     }
 
     let srcset;
+    let dims: { width: number; height: number } | null = null;
 
     if (remote) {
       srcset = buildCloudflareSrcset(src, config, Infinity, null);
     } else if (config.service === "cloudflare") {
       const meta = await resolveCfMeta(absoluteSrc as string, metaCache);
       srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+      dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : null;
     } else {
       let manifest = imageRefs.get(absoluteSrc as string);
       if (!manifest) {
@@ -427,12 +441,19 @@ async function transformInnerHtmlImages(
 
       const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
+      dims =
+        manifest.original?.width && manifest.original.height
+          ? { height: manifest.original.height, width: manifest.original.width }
+          : null;
     }
     if (!srcset) {
       continue;
     }
 
     let extra = ` srcset="${srcset}" sizes="${config.sizes}"`;
+    if (dims && !/\bwidth=/.test(attrs) && !/\bheight=/.test(attrs)) {
+      extra += ` width="${dims.width}" height="${dims.height}"`;
+    }
     if (config.lazyLoad && !/\bloading="eager"/.test(attrs)) {
       if (!/\bloading=/.test(attrs)) {
         extra += ` loading="lazy"`;

package/src/site/preview-server.ts

@@ -0,0 +1,93 @@
+/**
+ * Preview server — `jx preview` serves an already-built dist/ directory.
+ *
+ * Dependency-free node:http static server, so the Node-run `jx` bin needs neither Bun nor the
+ * dev-server package. Maps directory URLs to index.html (the build's trailingSlash output) and
+ * falls back to <dist>/404.html when present.
+ *
+ * @module preview-server
+ */
+
+import { createServer } from "node:http";
+import type { Server } from "node:http";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, join, normalize, resolve, sep } from "node:path";
+
+const MIME_TYPES: Record<string, string> = {
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webp": "image/webp",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8",
+};
+
+/**
+ * Resolve a request pathname to a file inside distDir, or null. Directory URLs (with or without a
+ * trailing slash) map to their index.html; traversal outside distDir is rejected.
+ *
+ * @param {string} distDir - Absolute dist directory
+ * @param {string} pathname - Decoded URL pathname
+ * @returns {string | null} Absolute file path to serve, or null
+ */
+export function resolvePreviewFile(distDir: string, pathname: string): string | null {
+  const safe = normalize(pathname).replaceAll("\\", "/");
+  const candidate = resolve(distDir, `.${safe.startsWith("/") ? safe : `/${safe}`}`);
+  if (candidate !== distDir && !candidate.startsWith(distDir + sep)) {
+    return null;
+  }
+  if (existsSync(candidate)) {
+    if (statSync(candidate).isDirectory()) {
+      const index = join(candidate, "index.html");
+      return existsSync(index) ? index : null;
+    }
+    return candidate;
+  }
+  // Extensionless route without trailing slash → its directory index
+  const index = join(candidate, "index.html");
+  return existsSync(index) ? index : null;
+}
+
+/**
+ * Start the preview server on the given port (0 picks a free port).
+ *
+ * @param {string} distDir - Absolute path to the built dist directory
+ * @param {number} port - Port to listen on
+ * @returns {Server} The listening node:http server
+ */
+export function startPreviewServer(distDir: string, port: number): Server {
+  const dist = resolve(distDir);
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const filePath = resolvePreviewFile(dist, decodeURIComponent(url.pathname));
+
+    if (filePath) {
+      res.writeHead(200, {
+        "Content-Type": MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream",
+      });
+      res.end(readFileSync(filePath));
+      return;
+    }
+
+    const notFound = join(dist, "404.html");
+    if (existsSync(notFound)) {
+      res.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(readFileSync(notFound));
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Not found");
+  });
+  server.listen(port);
+  return server;
+}

package/src/site/site-build.ts

@@ -367,7 +367,9 @@ export async function buildSite(
 
   // ── 6b. Save image cache and copy variants to dist ──────────────────────
   if (imageCache && projectConfig.images.optimize) {
-    saveCache(projectRoot, imageCache);
+    // Prune only on fully successful builds — a route that failed to compile never
+    // Touched its images, and pruning would evict their still-valid entries.
+    saveCache(projectRoot, imageCache, { prune: errors.length === 0 });
     const cacheOptimizedDir = resolve(getImageCacheDir(projectRoot), "_optimized");
     if (existsSync(cacheOptimizedDir)) {
       const distOptimizedDir = resolve(outDir, "images/_optimized");
@@ -441,7 +443,8 @@ export async function buildSite(
   // ── 7. Generate redirects ───────────────────────────────────────────────
   if (projectConfig.redirects && Object.keys(projectConfig.redirects).length > 0) {
     log("Generating redirects...");
-    const redirectFiles = generateRedirects(projectConfig.redirects, outDir);
+    const compiledUrls = new Set(routes.map((r) => r.urlPattern));
+    const redirectFiles = generateRedirects(projectConfig.redirects, outDir, compiledUrls);
     fileCount += redirectFiles;
   }
 
@@ -1315,14 +1318,18 @@ function routeToOutputPath(urlPattern: string, outDir: string, trailingSlash: st
  *
  * @param {Record<string, string | { destination: string; status?: number }>} redirects
  * @param {string} outDir
+ * @param {Set<string>} [compiledUrls] - URL patterns of compiled routes, for conflict warnings
  * @returns {number} Number of files written
  */
 function generateRedirects(
   redirects: Record<string, string | { destination: string; status?: number }>,
   outDir: string,
+  compiledUrls = new Set<string>(),
 ) {
   let count = 0;
   const redirectLines: string[] = [];
+  const normalizeUrl = (u: string) => (u.length > 1 && u.endsWith("/") ? u.slice(0, -1) : u);
+  const compiled = new Set([...compiledUrls].map((u) => normalizeUrl(u)));
 
   for (const [source, target] of Object.entries(redirects)) {
     const dest = typeof target === "object" ? target.destination : target;
@@ -1334,6 +1341,13 @@ function generateRedirects(
       continue;
     }
 
+    if (compiled.has(normalizeUrl(source))) {
+      console.warn(
+        `Redirect "${source}" overwrites a compiled page at the same route — ` +
+          `remove the redirect or the page.`,
+      );
+    }
+
     // Static redirect — emit an HTML file with meta refresh
     const htmlPath = routeToOutputPath(source, outDir, "always");
     const html = `<!DOCTYPE html>