@zvndev/darkmown 2.1.0 → 2.3.0

package/src/compiler/reader.js

@@ -13,13 +13,18 @@
 // ---------------------------------------------------------------------------
 
 import path from "node:path";
+import { normalizeNewlines } from "./context.js";
 
 /**
  * The narrow filesystem surface the compiler needs. Every method takes an
  * ABSOLUTE path (the compiler resolves includes/assets to absolute paths before
  * reading), so a reader only has to map absolute paths to bytes/existence.
  * @typedef {object} Reader
- * @property {(absPath: string) => string} readText Read a UTF-8 text file.
+ * @property {(absPath: string) => string} readText Read a UTF-8 text file. The
+ *   result is ALWAYS LF-normalized: every parser downstream is line-structured
+ *   and LF-shaped, so a CRLF source (Windows, or any `core.autocrlf` checkout)
+ *   would otherwise fail to match delimiters like `---`. A custom reader must
+ *   uphold this.
  * @property {(absPath: string) => Uint8Array} readBinary Read raw bytes (images).
  * @property {(absPath: string) => boolean} exists Whether the path exists.
  * @property {(absPath: string) => string} realpath Canonical path (symlinks
@@ -40,6 +45,11 @@ import path from "node:path";
  */
 export function memoryReader(files, cwd = "/") {
   const map = files instanceof Map ? files : new Map(Object.entries(files));
+  // Resolution deliberately uses the HOST `path`, because `cwd` is frequently a
+  // real OS directory (the fs-parity test compiles the same project from disk
+  // and from memory against one temp root, and a Windows temp root is
+  // `C:\…` — which `path.posix` does not recognize as absolute). Only the
+  // resulting KEY is forced to POSIX, matching the map's documented key shape.
   const keyOf = (/** @type {string} */ absPath) =>
     path.relative(cwd, path.resolve(absPath)).split(path.sep).join("/");
   return {
@@ -49,7 +59,7 @@ export function memoryReader(files, cwd = "/") {
       if (value === undefined) {
         throw new Error(`ENOENT: no in-memory file "${key}" (from ${absPath})`);
       }
-      return value;
+      return normalizeNewlines(value);
     },
     readBinary: () => {
       throw new Error("memoryReader: binary reads are unsupported");

package/src/compiler/state.js

@@ -8,7 +8,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at } from "./context.js";
+import { at, lineOf, wdError } from "./context.js";
 import { astOf, evalAst } from "./expr-ast.js";
 import { escapeHtml, parseStateValue, safeScriptJson } from "./interpolation.js";
 import { compileComputedExpr } from "./predicates.js";
@@ -17,6 +17,13 @@ import { compileComputedExpr } from "./predicates.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable one-liners for the state-family hint tails + the catalog.
+export const STATE_EXAMPLE = ":state count = 0";
+export const STORE_EXAMPLE = ":store cart = []";
+export const COMPUTED_EXAMPLE = ":computed total = items.length * 4";
+export const THEME_EXAMPLE = ":theme";
+const STATE_USE = `Use: :state name = value [persist] — e.g. ${STATE_EXAMPLE}`;
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -25,7 +32,14 @@ import { compileComputedExpr } from "./predicates.js";
  */
 export function handleState(line, ctx, index) {
   const match = line.match(/^:state\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+persist)?$/);
-  if (!match) throw new Error(`Malformed :state in ${at(ctx, index)}: ${line}`);
+  if (!match)
+    throw wdError(`Malformed :state in ${at(ctx, index)}: ${line}. ${STATE_USE}`, {
+      code: "WD201",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: STATE_USE.slice("Use: ".length),
+      example: STATE_EXAMPLE
+    });
   const value = parseStateValue(match[2], at(ctx, index));
   const key = declareState(match[1], value, ctx);
   const persistAttr = match[3] ? ` data-wd-persist="${key}"` : "";
@@ -41,14 +55,26 @@ export function handleState(line, ctx, index) {
  */
 export function declareState(name, value, ctx) {
   if (ctx.loopItem)
-    throw new Error(`State cannot be declared inside a reactive @loop body (${ctx.file})`);
+    throw wdError(`State cannot be declared inside a reactive @loop body (${ctx.file})`, {
+      code: "WD202",
+      file: ctx.file
+    });
   if (ctx.comp.stores.has(name))
-    throw new Error(
-      `State "${name}" collides with a :store of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one.`
+    throw wdError(
+      `State "${name}" collides with a :store of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+      {
+        code: "WD203",
+        file: ctx.file,
+        hint: `:store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   const key = ctx.sections.length ? `${ctx.sections.at(-1)}:${name}` : name;
   if (ctx.comp.state.has(key))
-    throw new Error(`State "${name}" is declared twice in the same scope (${ctx.file})`);
+    throw wdError(`State "${name}" is declared twice in the same scope (${ctx.file})`, {
+      code: "WD204",
+      file: ctx.file
+    });
   ctx.comp.state.set(key, value);
   ctx.comp.assets.runtime = true;
   return key;
@@ -63,8 +89,15 @@ export function declareState(name, value, ctx) {
 export function handleStore(line, ctx, index) {
   const match = line.match(/^:store\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+ephemeral)?$/);
   if (!match)
-    throw new Error(
-      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [ephemeral]`
+    throw wdError(
+      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [ephemeral] — e.g. ${STORE_EXAMPLE}`,
+      {
+        code: "WD205",
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: `:store name = value [ephemeral] — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   const value = parseStateValue(match[2], at(ctx, index));
   const name = declareStore(match[1], value, ctx);
@@ -83,10 +116,24 @@ export function handleStore(line, ctx, index) {
  */
 export function declareStore(name, value, ctx) {
   if (ctx.comp.stores.has(name))
-    throw new Error(`Store "${name}" is declared twice in ${ctx.file}. Use: :store name = value`);
+    throw wdError(
+      `Store "${name}" is declared twice in ${ctx.file}. Use: :store name = value — e.g. ${STORE_EXAMPLE}`,
+      {
+        code: "WD206",
+        file: ctx.file,
+        hint: `:store name = value — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
+    );
   if (ctx.comp.state.has(name))
-    throw new Error(
-      `Store "${name}" collides with a :state of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one.`
+    throw wdError(
+      `Store "${name}" collides with a :state of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+      {
+        code: "WD207",
+        file: ctx.file,
+        hint: `:store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   ctx.comp.stores.add(name);
   ctx.comp.state.set(name, value);
@@ -115,9 +162,13 @@ export function declareErrorState(key, ctx) {
 export function handleComputed(line, ctx, index) {
   const match = line.match(/^:computed\s+([A-Za-z_$][\w$]*)\s*=\s*(.+)$/);
   if (!match)
-    throw new Error(
-      `Malformed :computed in ${at(ctx, index)}: ${line}. Use: :computed total = items.length * 4`
-    );
+    throw wdError(`Malformed :computed in ${at(ctx, index)}: ${line}. Use: ${COMPUTED_EXAMPLE}`, {
+      code: "WD208",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: COMPUTED_EXAMPLE,
+      example: COMPUTED_EXAMPLE
+    });
   const expr = compileComputedExpr(match[2].trim(), ctx);
   // Parse the validated expression to the compact AST the runtime walks. A parse
   // failure means the RHS is syntactically malformed (e.g. `|| <`) — a compile
@@ -127,8 +178,15 @@ export function handleComputed(line, ctx, index) {
   try {
     ast = astOf(expr);
   } catch {
-    throw new Error(
-      `Malformed :computed expression in ${at(ctx, index)}: ${line}. Use: :computed total = items.length * 4`
+    throw wdError(
+      `Malformed :computed expression in ${at(ctx, index)}: ${line}. Use: ${COMPUTED_EXAMPLE}`,
+      {
+        code: "WD209",
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: COMPUTED_EXAMPLE,
+        example: COMPUTED_EXAMPLE
+      }
     );
   }
   // Build-time mirror of the runtime: walk the AST (no eval) so `:computed total =
@@ -155,8 +213,15 @@ export function handleComputed(line, ctx, index) {
 export function handleTheme(line, ctx, index) {
   const match = line.match(/^:theme(?:\s+([A-Za-z_$][\w$]*))?(?:\s*=\s*(.+))?$/);
   if (!match) {
-    throw new Error(
-      `Malformed :theme in ${at(ctx, index)}: ${line}. Use: :theme  (or  :theme name = "auto")`
+    throw wdError(
+      `Malformed :theme in ${at(ctx, index)}: ${line}. Use: :theme  (or  :theme name = "auto") — e.g. ${THEME_EXAMPLE}`,
+      {
+        code: "WD210",
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: `:theme  (or  :theme name = "auto") — e.g. ${THEME_EXAMPLE}`,
+        example: THEME_EXAMPLE
+      }
     );
   }
   const name = match[1] || "theme";

package/src/compiler/structure.js

@@ -11,7 +11,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, createScope, LOOP_META, nestedCtx } from "./context.js";
+import { at, createScope, LOOP_META, lineOf, nestedCtx, wdError } from "./context.js";
 import { astOf, serializeExpr } from "./expr-ast.js";
 import { resolveInclude, scopedSkinFor, stampScope } from "./includes.js";
 import {
@@ -28,6 +28,13 @@ import { compileWhen, evalPredicate } from "./predicates.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable structure examples for the hint tails + the catalog.
+export const INCLUDE_EXAMPLE = "@include /header.wd";
+export const CONTAINER_EXAMPLE = "::: card .featured";
+export const IF_EXAMPLE = ":if count > 0";
+export const CAROUSEL_EXAMPLE = ":carousel autoplay=3000";
+const INCLUDE_USE = `Use: @include /partial.wd [with key="value"] — e.g. ${INCLUDE_EXAMPLE}`;
+
 // Container names that emit their own semantic landmark element instead of a
 // `<div>`, so scaffolds get real `<nav>`/`<main>` landmarks (accessibility: the
 // skip link targets a genuine main-content region and navigation chrome sits in
@@ -44,7 +51,14 @@ const SEMANTIC_CONTAINER_TAGS = new Set(["nav", "main"]);
  */
 export function handleInclude(line, ctx, index) {
   const match = line.match(/^@include\s+(\S+)(?:\s+with\s+(.+))?$/);
-  if (!match) throw new Error(`Malformed @include in ${at(ctx, index)}: ${line}`);
+  if (!match)
+    throw wdError(`Malformed @include in ${at(ctx, index)}: ${line}. ${INCLUDE_USE}`, {
+      code: "WD603",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: INCLUDE_USE.slice("Use: ".length),
+      example: INCLUDE_EXAMPLE
+    });
   const target = resolveInclude(
     match[1],
     ctx.file,
@@ -94,8 +108,9 @@ function parseIncludeArgs(raw, ctx) {
       const expr = value.slice(1, -1).trim();
       const resolved = lookupPath(expr, ctx);
       if (!resolved.found) {
-        throw new Error(
-          `@include argument ${match[1]}={ ${expr} } in ${ctx.file} does not match any value in scope`
+        throw wdError(
+          `@include argument ${match[1]}={ ${expr} } in ${ctx.file} does not match any value in scope`,
+          { code: "WD604", file: ctx.file }
         );
       }
       args[match[1]] = resolved.value;
@@ -152,8 +167,9 @@ export function handleContainer(header, bodyLines, ctx, index) {
     }
     const cm = rest.match(/^\.([A-Za-z_][\w-]*)/);
     if (!cm)
-      throw new Error(
-        `Unexpected token "${rest.split(/\s+/)[0]}" in container "::: ${header}" in ${at(ctx, index)}`
+      throw wdError(
+        `Unexpected token "${rest.split(/\s+/)[0]}" in container "::: ${header}" in ${at(ctx, index)}`,
+        { code: "WD605", file: ctx.file, line: lineOf(ctx, index) }
       );
     const cls = cm[1];
     rest = rest.slice(cm[0].length).trim();
@@ -215,10 +231,16 @@ export function handleCarousel(line, bodyLines, ctx, index) {
   let autoplayAttr = "";
   if (rest) {
     const auto = rest.match(/^autoplay=(\d+)$/);
-    if (!auto)
-      throw new Error(
-        `Malformed :carousel in ${at(ctx, index)}: ${line}. Use: :carousel [autoplay=3000] … :endcarousel`
-      );
+    if (!auto) {
+      const hint = `:carousel [autoplay=3000] … :endcarousel — e.g. ${CAROUSEL_EXAMPLE}`;
+      throw wdError(`Malformed :carousel in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+        code: "WD606",
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint,
+        example: CAROUSEL_EXAMPLE
+      });
+    }
     autoplayAttr = ` data-wd-carousel-autoplay="${auto[1]}"`;
   }
   ctx.comp.assets.behaviors.add("carousel");
@@ -277,8 +299,9 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
     // Per-row meta vars in :if — only valid inside a loop.
     if (LOOP_META[head]) {
       if (!ctx.loopMeta)
-        throw new Error(
-          `":if ${match[1]}" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Use it inside a loop body.`
+        throw wdError(
+          `":if ${match[1]}" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Use it inside a loop body.`,
+          { code: "WD607", file: ctx.file }
         );
       if (ctx.loopItem) {
         const truthy = ctx.compileBody(truthyLines, truthyCtx).trim();
@@ -304,8 +327,9 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
 
     const key = resolveStateKey(head, ctx);
     if (!key) {
-      throw new Error(
-        `:if ${match[1]} in ${ctx.file} does not match a :state or in-scope value. Declare it first.`
+      throw wdError(
+        `:if ${match[1]} in ${ctx.file} does not match a :state or in-scope value. Declare it first.`,
+        { code: "WD608", file: ctx.file }
       );
     }
     ctx.comp.assets.runtime = true;
@@ -323,10 +347,16 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
   // whitelist as `@loop … where` / `.class when` (with `not`), so it folds at
   // build when static, drives a per-row each-if when it reads the loop item, and
   // a global if-region (evaluated each render) when it reads state. No raw eval.
-  if (!condition)
-    throw new Error(
-      `Malformed :if in ${at(ctx, index)}: ${line}. Use ":if name" or ":if a <op> b [and|or|not …]".`
-    );
+  if (!condition) {
+    const hint = `":if name" or ":if a <op> b [and|or|not …]" — e.g. ${IF_EXAMPLE}`;
+    throw wdError(`Malformed :if in ${at(ctx, index)}: ${line}. Use ${hint}`, {
+      code: "WD609",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: IF_EXAMPLE
+    });
+  }
   const compiled = compileWhen(condition, ctx, '":if"');
   if (compiled.static)
     return ctx.compileBody(
@@ -380,13 +410,15 @@ function validateDemoHref(href, ctx) {
   const value = href.trim();
   // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — rejects control characters in URLs/hrefs.
   if (value !== href || /[\u0000-\u001F\u007F]/.test(value)) {
-    throw new Error(
-      `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Use a relative URL starting with /, ./, ../, or #, or an http:, https:, or mailto: URL.`
+    throw wdError(
+      `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Use a relative URL starting with /, ./, ../, or #, or an http:, https:, or mailto: URL.`,
+      { code: "WD610", file: ctx.file }
     );
   }
   if (value.startsWith("//")) {
-    throw new Error(
-      `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Protocol-relative URLs are not allowed; use http: or https: explicitly.`
+    throw wdError(
+      `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Protocol-relative URLs are not allowed; use http: or https: explicitly.`,
+      { code: "WD611", file: ctx.file }
     );
   }
   if (
@@ -401,7 +433,8 @@ function validateDemoHref(href, ctx) {
   if (scheme && ["http", "https", "mailto"].includes(scheme[1].toLowerCase())) {
     return value;
   }
-  throw new Error(
-    `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Use a relative URL starting with /, ./, ../, or #, or an http:, https:, or mailto: URL.`
+  throw wdError(
+    `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Use a relative URL starting with /, ./, ../, or #, or an http:, https:, or mailto: URL.`,
+    { code: "WD610", file: ctx.file }
   );
 }

package/src/deploy.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { buildSite } from "./builder.js";
+import { wdError } from "./compiler/context.js";
 import { BASE_SECURITY_HEADERS, REACTIVE_CSP } from "./headers.js";
 
 /** The platforms `darkmown deploy` knows how to drive. */
@@ -25,7 +26,9 @@ export const DEPLOY_TARGETS = ["vercel", "cloudflare"];
  */
 export async function deploy({ cwd, target, prod = false, log, run = spawnProcess, projectName }) {
   if (!DEPLOY_TARGETS.includes(target)) {
-    throw new Error(`Unknown deploy target "${target}". Use one of: ${DEPLOY_TARGETS.join(", ")}.`);
+    throw wdError(`Unknown deploy target "${target}". Use one of: ${DEPLOY_TARGETS.join(", ")}.`, {
+      code: "WD904"
+    });
   }
 
   ensurePlatformConfig(cwd, target);
@@ -46,11 +49,12 @@ export async function deploy({ cwd, target, prod = false, log, run = spawnProces
         output
       )
     ) {
-      throw new Error(
-        `The ${target} CLI is not signed in. Run \`${plan.loginHint}\` (try \`! ${plan.loginHint}\` in this session), then re-run \`darkmown deploy ${target}\`.`
+      throw wdError(
+        `The ${target} CLI is not signed in. Run \`${plan.loginHint}\` (try \`! ${plan.loginHint}\` in this session), then re-run \`darkmown deploy ${target}\`.`,
+        { code: "WD905" }
       );
     }
-    throw new Error(`${target} deploy failed (exit ${result.code}).`);
+    throw wdError(`${target} deploy failed (exit ${result.code}).`, { code: "WD906" });
   }
 
   const url = plan.parseUrl(output);