@zvndev/darkmown 2.1.0 → 2.3.0

package/src/compiler/forms.js

@@ -9,7 +9,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, nestedCtx } from "./context.js";
+import { at, lineOf, nestedCtx, wdError } from "./context.js";
 import { validateFetchUrl } from "./fetch.js";
 import {
   escapeHtml,
@@ -25,6 +25,20 @@ import { declareErrorState, declareState } from "./state.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable one-liners for the form-family hint tails + the catalog.
+// (Field openers like :select/:checkbox expect following `- Label` lines; the
+// example is the opener, which the catalog/grammar pair with option lines.)
+export const FORM_EXAMPLE = ":form into contact";
+export const INPUT_EXAMPLE = ":input email type=email required";
+export const TEXTAREA_EXAMPLE = ':textarea message placeholder="Your message" rows=4';
+export const SELECT_EXAMPLE = ":select topic";
+export const CHECKBOX_EXAMPLE = ":checkbox toppings";
+export const RADIO_EXAMPLE = ":radio size";
+export const SUBMIT_EXAMPLE = ':submit "Send"';
+export const BIND_EXAMPLE = ':bind query placeholder="Search"';
+export const SLIDER_EXAMPLE = ":slider volume = 50 min=0 max=100 step=1";
+const INPUT_USE = `Use: :input name [type=…] [placeholder="…"] [required] — e.g. ${INPUT_EXAMPLE}`;
+
 /**
  * @param {string} line
  * @param {string[]} bodyLines
@@ -43,9 +57,14 @@ export function handleForm(line, bodyLines, ctx, index) {
     .replace(/(?:^|\s)into\s+[A-Za-z_$][\w$]*/, "")
     .trim();
   if ((!rawAction && !into) || leftover) {
-    throw new Error(
-      `Malformed :form in ${at(ctx, index)}: ${line}. Use ':form into name' (client state), ':form action="/url"' (native post), or both (fetch round-trip into state).`
-    );
+    const hint = `':form into name' (client state), ':form action="/url"' (native post), or both (fetch round-trip into state) — e.g. ${FORM_EXAMPLE}`;
+    throw wdError(`Malformed :form in ${at(ctx, index)}: ${line}. Use ${hint}`, {
+      code: "WD401",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: FORM_EXAMPLE
+    });
   }
   const action = rawAction ? validateFetchUrl(rawAction, ctx, ":form action") : undefined;
   const inner = ctx.compileBody(bodyLines, nestedCtx(ctx, index + 1)).trim();
@@ -68,7 +87,14 @@ export function handleForm(line, bodyLines, ctx, index) {
  */
 export function handleInput(line, ctx, index) {
   const match = line.match(/^:input\s+([A-Za-z_][\w-]*)\s*(.*)$/);
-  if (!match) throw new Error(`Malformed :input in ${at(ctx, index)}: ${line}`);
+  if (!match)
+    throw wdError(`Malformed :input in ${at(ctx, index)}: ${line}. ${INPUT_USE}`, {
+      code: "WD402",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: INPUT_USE.slice("Use: ".length),
+      example: INPUT_EXAMPLE
+    });
   const attrs = [`name="${escapeHtml(match[1])}"`];
   let type = "text";
   let placeholder;
@@ -77,7 +103,11 @@ export function handleInput(line, ctx, index) {
   for (const token of (match[2] || "").matchAll(re)) {
     if (token[3]) {
       if (!["required", "autofocus", "disabled", "readonly"].includes(token[3])) {
-        throw new Error(`Unknown :input flag "${token[3]}" in ${at(ctx, index)}`);
+        throw wdError(`Unknown :input flag "${token[3]}" in ${at(ctx, index)}`, {
+          code: "WD403",
+          file: ctx.file,
+          line: lineOf(ctx, index)
+        });
       }
       attrs.push(token[3]);
       continue;
@@ -100,7 +130,11 @@ export function handleInput(line, ctx, index) {
         "aria-describedby"
       ].includes(token[1])
     ) {
-      throw new Error(`Unknown :input attribute "${token[1]}" in ${at(ctx, index)}`);
+      throw wdError(`Unknown :input attribute "${token[1]}" in ${at(ctx, index)}`, {
+        code: "WD404",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
     }
     if (token[1] === "placeholder") placeholder = value;
     if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
@@ -127,13 +161,18 @@ export function handleInput(line, ctx, index) {
 export function handleBind(line, ctx, index) {
   const match = line.match(/^:bind\s+([A-Za-z_$][\w$]*)\s*(.*)$/);
   if (!match)
-    throw new Error(
-      `Malformed :bind in ${at(ctx, index)}: ${line}. Use: :bind query placeholder="Search"`
-    );
+    throw wdError(`Malformed :bind in ${at(ctx, index)}: ${line}. Use: ${BIND_EXAMPLE}`, {
+      code: "WD405",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: BIND_EXAMPLE,
+      example: BIND_EXAMPLE
+    });
   const key = resolveStateKey(match[1], ctx);
   if (!key) {
-    throw new Error(
-      `:bind ${match[1]} in ${ctx.file} has no matching state. Declare it first: :state ${match[1]} = ""`
+    throw wdError(
+      `:bind ${match[1]} in ${ctx.file} has no matching state. Declare it first: :state ${match[1]} = ""`,
+      { code: "WD406", file: ctx.file }
     );
   }
   ctx.comp.assets.runtime = true;
@@ -145,7 +184,11 @@ export function handleBind(line, ctx, index) {
   for (const token of (match[2] || "").matchAll(re)) {
     if (token[3]) {
       if (!["required", "autofocus"].includes(token[3]))
-        throw new Error(`Unknown :bind flag "${token[3]}" in ${at(ctx, index)}`);
+        throw wdError(`Unknown :bind flag "${token[3]}" in ${at(ctx, index)}`, {
+          code: "WD407",
+          file: ctx.file,
+          line: lineOf(ctx, index)
+        });
       attrs.push(token[3]);
       continue;
     }
@@ -155,7 +198,11 @@ export function handleBind(line, ctx, index) {
       continue;
     }
     if (!["placeholder", "autocomplete", "aria-label", "aria-describedby"].includes(token[1])) {
-      throw new Error(`Unknown :bind attribute "${token[1]}" in ${at(ctx, index)}`);
+      throw wdError(`Unknown :bind attribute "${token[1]}" in ${at(ctx, index)}`, {
+        code: "WD408",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
     }
     if (token[1] === "placeholder") placeholder = value;
     if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
@@ -187,9 +234,13 @@ export function handleBind(line, ctx, index) {
 export function handleSlider(line, ctx, index) {
   const head = line.match(/^:slider\s+([A-Za-z_$][\w$]*)\s*(.*)$/);
   if (!head)
-    throw new Error(
-      `Malformed :slider in ${at(ctx, index)}: ${line}. Use: :slider volume = 50 min=0 max=100 step=1`
-    );
+    throw wdError(`Malformed :slider in ${at(ctx, index)}: ${line}. Use: ${SLIDER_EXAMPLE}`, {
+      code: "WD409",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: SLIDER_EXAMPLE,
+      example: SLIDER_EXAMPLE
+    });
   const name = head[1];
   let rest = head[2].trim();
 
@@ -198,8 +249,9 @@ export function handleSlider(line, ctx, index) {
   if (rest.startsWith("=")) {
     const valueMatch = rest.match(/^=\s*(\S+)\s*(.*)$/);
     if (!valueMatch)
-      throw new Error(
-        `Malformed :slider initial value in ${at(ctx, index)}: ${line}. Use: :slider ${name} = 50`
+      throw wdError(
+        `Malformed :slider initial value in ${at(ctx, index)}: ${line}. Use: :slider ${name} = 50`,
+        { code: "WD410", file: ctx.file, line: lineOf(ctx, index) }
       );
     initialRaw = valueMatch[1];
     rest = valueMatch[2].trim();
@@ -221,7 +273,12 @@ export function handleSlider(line, ctx, index) {
     else if (token[1] === "max") max = value;
     else if (token[1] === "step") step = value;
     else if (token[1] === "aria-label") ariaLabel = value;
-    else throw new Error(`Unknown :slider attribute "${token[1]}" in ${at(ctx, index)}`);
+    else
+      throw wdError(`Unknown :slider attribute "${token[1]}" in ${at(ctx, index)}`, {
+        code: "WD411",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
   }
   for (const [label, raw] of [
     ["min", min],
@@ -229,7 +286,11 @@ export function handleSlider(line, ctx, index) {
     ["step", step]
   ]) {
     if (!/^-?\d+(?:\.\d+)?$/.test(raw))
-      throw new Error(`:slider ${label} must be a number in ${at(ctx, index)}: ${raw}`);
+      throw wdError(`:slider ${label} must be a number in ${at(ctx, index)}: ${raw}`, {
+        code: "WD412",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
   }
 
   ctx.comp.assets.runtime = true;
@@ -239,21 +300,24 @@ export function handleSlider(line, ctx, index) {
   if (initialRaw !== undefined) {
     const value = parseStateValue(initialRaw, at(ctx, index));
     if (typeof value !== "number")
-      throw new Error(
-        `:slider ${name} initial value must be a number in ${at(ctx, index)}: ${initialRaw}`
+      throw wdError(
+        `:slider ${name} initial value must be a number in ${at(ctx, index)}: ${initialRaw}`,
+        { code: "WD413", file: ctx.file, line: lineOf(ctx, index) }
       );
     key = declareState(name, value, ctx);
     const persistAttr = persist ? ` data-wd-persist="${key}"` : "";
     seed = `<script type="application/json" data-wd-state${persistAttr}>${safeScriptJson({ [key]: value })}</script>`;
   } else {
     if (persist)
-      throw new Error(
-        `:slider persist only applies when declaring state inline (:slider ${name} = 0 … persist) in ${at(ctx, index)}`
+      throw wdError(
+        `:slider persist only applies when declaring state inline (:slider ${name} = 0 … persist) in ${at(ctx, index)}`,
+        { code: "WD414", file: ctx.file, line: lineOf(ctx, index) }
       );
     const resolved = resolveStateKey(name, ctx);
     if (!resolved)
-      throw new Error(
-        `:slider ${name} in ${ctx.file} has no matching state. Declare it: :slider ${name} = 0 min=0 max=100`
+      throw wdError(
+        `:slider ${name} in ${ctx.file} has no matching state. Declare it: :slider ${name} = 0 min=0 max=100`,
+        { code: "WD415", file: ctx.file }
       );
     key = resolved;
   }
@@ -274,7 +338,16 @@ export function handleSlider(line, ctx, index) {
 export function handleSubmit(line, ctx, index) {
   const match = line.match(/^:submit\s+"([^"]+)"\s*$/);
   if (!match)
-    throw new Error(`Malformed :submit in ${at(ctx, index)}: ${line}. Use: :submit "Label"`);
+    throw wdError(
+      `Malformed :submit in ${at(ctx, index)}: ${line}. Use: :submit "Label" — e.g. ${SUBMIT_EXAMPLE}`,
+      {
+        code: "WD416",
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: `:submit "Label" — e.g. ${SUBMIT_EXAMPLE}`,
+        example: SUBMIT_EXAMPLE
+      }
+    );
   return `<button type="submit">${escapeHtml(match[1])}</button>`;
 }
 
@@ -290,10 +363,16 @@ export function handleSubmit(line, ctx, index) {
  */
 export function handleTextarea(line, ctx, index) {
   const match = line.match(/^:textarea\s+([A-Za-z_][\w-]*)\s*(.*)$/);
-  if (!match)
-    throw new Error(
-      `Malformed :textarea in ${at(ctx, index)}: ${line}. Use: :textarea name [placeholder="…"] [rows=N] [required]`
-    );
+  if (!match) {
+    const hint = `:textarea name [placeholder="…"] [rows=N] [required] — e.g. ${TEXTAREA_EXAMPLE}`;
+    throw wdError(`Malformed :textarea in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      code: "WD417",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: TEXTAREA_EXAMPLE
+    });
+  }
   const attrs = [`name="${escapeHtml(match[1])}"`];
   let placeholder;
   let hasAria = false;
@@ -301,7 +380,11 @@ export function handleTextarea(line, ctx, index) {
   for (const token of (match[2] || "").matchAll(re)) {
     if (token[3]) {
       if (!["required", "autofocus", "disabled", "readonly"].includes(token[3])) {
-        throw new Error(`Unknown :textarea flag "${token[3]}" in ${at(ctx, index)}`);
+        throw wdError(`Unknown :textarea flag "${token[3]}" in ${at(ctx, index)}`, {
+          code: "WD418",
+          file: ctx.file,
+          line: lineOf(ctx, index)
+        });
       }
       attrs.push(token[3]);
       continue;
@@ -319,7 +402,11 @@ export function handleTextarea(line, ctx, index) {
         "aria-describedby"
       ].includes(token[1])
     ) {
-      throw new Error(`Unknown :textarea attribute "${token[1]}" in ${at(ctx, index)}`);
+      throw wdError(`Unknown :textarea attribute "${token[1]}" in ${at(ctx, index)}`, {
+        code: "WD419",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
     }
     if (token[1] === "placeholder") placeholder = value;
     if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
@@ -343,24 +430,38 @@ export function handleTextarea(line, ctx, index) {
  */
 export function handleSelect(line, optionLines, ctx, index) {
   const match = line.match(/^:select\s+([A-Za-z_][\w-]*)\s*(.*)$/);
-  if (!match)
-    throw new Error(
-      `Malformed :select in ${at(ctx, index)}: ${line}. Use: :select name [required] then "- Label" lines`
-    );
+  if (!match) {
+    const hint = `:select name [required] then "- Label" lines — e.g. ${SELECT_EXAMPLE}`;
+    throw wdError(`Malformed :select in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      code: "WD420",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: SELECT_EXAMPLE
+    });
+  }
   const attrs = [`name="${escapeHtml(match[1])}"`];
   let hasAria = false;
   const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
   for (const token of (match[2] || "").matchAll(re)) {
     if (token[3]) {
       if (!["required", "disabled", "autofocus"].includes(token[3])) {
-        throw new Error(`Unknown :select flag "${token[3]}" in ${at(ctx, index)}`);
+        throw wdError(`Unknown :select flag "${token[3]}" in ${at(ctx, index)}`, {
+          code: "WD421",
+          file: ctx.file,
+          line: lineOf(ctx, index)
+        });
       }
       attrs.push(token[3]);
       continue;
     }
     const value = stripQuotes(token[2]);
     if (!["autocomplete", "aria-label", "aria-describedby"].includes(token[1])) {
-      throw new Error(`Unknown :select attribute "${token[1]}" in ${at(ctx, index)}`);
+      throw wdError(`Unknown :select attribute "${token[1]}" in ${at(ctx, index)}`, {
+        code: "WD422",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
     }
     if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
     attrs.push(`${token[1]}="${escapeHtml(value)}"`);
@@ -370,8 +471,9 @@ export function handleSelect(line, optionLines, ctx, index) {
   }
   const options = optionLines.map((l) => l.replace(/^\s*-\s+/, "").trim()).filter(Boolean);
   if (!options.length) {
-    throw new Error(
-      `:select "${match[1]}" in ${at(ctx, index)} has no options. Add "- Label" lines beneath it.`
+    throw wdError(
+      `:select "${match[1]}" in ${at(ctx, index)} has no options. Add "- Label" lines beneath it.`,
+      { code: "WD423", file: ctx.file, line: lineOf(ctx, index) }
     );
   }
   const opts = options
@@ -404,10 +506,17 @@ export function handleChoiceGroup(line, optionLines, ctx, kind, index) {
       ? /^:checkbox\s+([A-Za-z_][\w-]*)\s*(.*)$/
       : /^:radio\s+([A-Za-z_][\w-]*)\s*(.*)$/
   );
-  if (!match)
-    throw new Error(
-      `Malformed ${directive} in ${at(ctx, index)}: ${line}. Use: ${directive} name [required] then "- Label" lines`
-    );
+  if (!match) {
+    const example = kind === "checkbox" ? CHECKBOX_EXAMPLE : RADIO_EXAMPLE;
+    const hint = `${directive} name [required] then "- Label" lines — e.g. ${example}`;
+    throw wdError(`Malformed ${directive} in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      code: "WD424",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example
+    });
+  }
   const name = match[1];
   const flags = [];
   let ariaLabel = null;
@@ -416,7 +525,11 @@ export function handleChoiceGroup(line, optionLines, ctx, kind, index) {
   for (const token of (match[2] || "").matchAll(re)) {
     if (token[3]) {
       if (!["required", "disabled", "autofocus"].includes(token[3])) {
-        throw new Error(`Unknown ${directive} flag "${token[3]}" in ${at(ctx, index)}`);
+        throw wdError(`Unknown ${directive} flag "${token[3]}" in ${at(ctx, index)}`, {
+          code: "WD425",
+          file: ctx.file,
+          line: lineOf(ctx, index)
+        });
       }
       flags.push(token[3]);
       continue;
@@ -424,12 +537,18 @@ export function handleChoiceGroup(line, optionLines, ctx, kind, index) {
     const value = stripQuotes(token[2]);
     if (token[1] === "aria-label") ariaLabel = value;
     else if (token[1] === "aria-describedby") ariaDescribedby = value;
-    else throw new Error(`Unknown ${directive} attribute "${token[1]}" in ${at(ctx, index)}`);
+    else
+      throw wdError(`Unknown ${directive} attribute "${token[1]}" in ${at(ctx, index)}`, {
+        code: "WD426",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
   }
   const options = optionLines.map((l) => l.replace(/^\s*-\s+/, "").trim()).filter(Boolean);
   if (!options.length) {
-    throw new Error(
-      `${directive} "${name}" in ${at(ctx, index)} has no options. Add "- Label" lines beneath it.`
+    throw wdError(
+      `${directive} "${name}" in ${at(ctx, index)} has no options. Add "- Label" lines beneath it.`,
+      { code: "WD427", file: ctx.file, line: lineOf(ctx, index) }
     );
   }
   const isCheckbox = kind === "checkbox";

package/src/compiler/frontmatter.js

@@ -3,6 +3,7 @@
 // values, and warn when a file looks like it forgot the opening `---`.
 // ---------------------------------------------------------------------------
 
+import { normalizeNewlines, wdError } from "./context.js";
 import { stripQuotes } from "./interpolation.js";
 
 /**
@@ -20,12 +21,20 @@ import { stripQuotes } from "./interpolation.js";
  * @returns {{ meta: Meta, body: string, bodyLine: number }}
  */
 export function parseFrontmatter(raw, file) {
+  // A file authored on Windows (or checked out with git's autocrlf) arrives
+  // CRLF-terminated, and every delimiter/line test below is LF-shaped — so
+  // without this the opening `---\r\n` never matches and the whole frontmatter
+  // block is silently treated as body text. Normalizing here rather than only
+  // in the reader keeps the direct callers (builder.js reads route frontmatter
+  // straight off disk for feeds) on the same footing. Idempotent on LF input.
+  raw = normalizeNewlines(raw);
   if (!raw.startsWith("---\n")) return { meta: {}, body: raw, bodyLine: 0 };
   const end = raw.indexOf("\n---", 3);
   if (end === -1) {
     const where = file ? ` in ${file}` : "";
-    throw new Error(
-      `Unterminated frontmatter${where}: opening "---" has no closing "---". Use: --- on its own line to open and another --- to close, then the page body.`
+    throw wdError(
+      `Unterminated frontmatter${where}: opening "---" has no closing "---". Use: --- on its own line to open and another --- to close, then the page body.`,
+      { code: "WD001", file }
     );
   }
   const front = raw.slice(4, end).trim();

package/src/compiler/fs-reader.js

@@ -8,6 +8,7 @@
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
+import { normalizeNewlines } from "./context.js";
 
 /**
  * A {@link import("./reader.js").Reader} backed by `node:fs`. Each method is a
@@ -17,7 +18,7 @@ import fs from "node:fs";
  */
 export function fsReader() {
   return {
-    readText: (absPath) => fs.readFileSync(absPath, "utf8"),
+    readText: (absPath) => normalizeNewlines(fs.readFileSync(absPath, "utf8")),
     readBinary: (absPath) => fs.readFileSync(absPath),
     exists: (absPath) => fs.existsSync(absPath),
     realpath: (absPath) => fs.realpathSync(absPath)