@zvndev/darkmown 0.18.0 → 0.20.0

package/src/compiler/frontmatter.js

@@ -0,0 +1,117 @@
+// ---------------------------------------------------------------------------
+// Frontmatter: split a raw file into `meta` + `body`, parse inline scalar/array
+// values, and warn when a file looks like it forgot the opening `---`.
+// ---------------------------------------------------------------------------
+
+import { stripQuotes } from "./interpolation.js";
+
+/**
+ * @typedef {import("./context.js").Meta} Meta
+ * @typedef {import("./context.js").FrontmatterValue} FrontmatterValue
+ * @typedef {import("./context.js").Compilation} Compilation
+ */
+
+/**
+ * Split a raw file into its frontmatter `meta` and `body`.
+ * @param {string} raw Full file contents.
+ * @param {string} [file] Source path, used only for error messages.
+ * @returns {{ meta: Meta, body: string }}
+ */
+export function parseFrontmatter(raw, file) {
+  if (!raw.startsWith("---\n")) return { meta: {}, body: raw };
+  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.`
+    );
+  }
+  const front = raw.slice(4, end).trim();
+  const body = raw.slice(end + 4).replace(/^\n/, "");
+  /** @type {Meta} */
+  const meta = {};
+  for (const line of front.split("\n")) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) meta[match[1]] = parseFrontmatterValue(match[2]);
+  }
+  return { meta, body };
+}
+
+/**
+ * Warn (non-fatal) when a file looks like it MEANT to open frontmatter but forgot
+ * the leading `---`: the first content line is a `key: value` pair and a bare
+ * `---` fence appears within the opening lines. Conservative — a normal markdown
+ * body whose first line happens to contain a colon (with no early `---`) is left
+ * alone, since `---` is also a valid horizontal rule.
+ * @param {string} raw
+ * @param {string} file
+ * @param {Compilation} comp
+ * @returns {void}
+ */
+export function warnLikelyFrontmatter(raw, file, comp) {
+  if (raw.startsWith("---\n")) return; // a real opener: parseFrontmatter handled it
+  const lines = raw.replace(/\r\n?/g, "\n").split("\n");
+  let i = 0;
+  while (i < lines.length && !lines[i].trim()) i++; // skip leading blanks
+  if (i >= lines.length || !/^[A-Za-z][\w-]*:\s*\S/.test(lines[i])) return;
+  // Only warn when the run of lines up to a bare `---` is ALL `key: value` pairs:
+  // a forgotten opener, not prose that merely contains a colon and a later rule.
+  for (let j = i; j < lines.length && j < i + 12; j++) {
+    const t = lines[j].trim();
+    if (t === "---") {
+      comp.warnings.push(
+        `${file}: this looks like frontmatter missing its opening "---". Use: a "---" line before the fields (and another "---" to close) — otherwise the block renders as page text.`
+      );
+      return;
+    }
+    if (t && !/^[A-Za-z][\w-]*:\s*\S/.test(t)) return; // hit prose → not frontmatter
+  }
+}
+
+// Frontmatter values are scalars, except an inline flow array `[a, b, c]`.
+// Block sequences (`- item` on following lines) are intentionally out of scope —
+// the parser stays single-pass and line-based.
+/**
+ * @param {string} raw
+ * @returns {FrontmatterValue}
+ */
+function parseFrontmatterValue(raw) {
+  const value = raw.trim();
+  if (value.startsWith("[") && value.endsWith("]")) return parseInlineArray(value);
+  return stripQuotes(value);
+}
+
+/**
+ * @param {string} raw
+ * @returns {string[]}
+ */
+function parseInlineArray(raw) {
+  const inner = raw.slice(1, -1);
+  if (inner.trim() === "") return [];
+  /** @type {string[]} */
+  const items = [];
+  let buf = "";
+  let quote = null;
+  let quoted = false;
+  const push = () => {
+    items.push(quoted ? buf : buf.trim());
+    buf = "";
+    quoted = false;
+  };
+  for (const char of inner) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else buf += char;
+    } else if ((char === '"' || char === "'") && buf.trim() === "") {
+      quote = char;
+      quoted = true;
+      buf = ""; // drop any whitespace between the comma and the opening quote
+    } else if (char === ",") {
+      push();
+    } else {
+      buf += char;
+    }
+  }
+  push();
+  return items;
+}

package/src/compiler/includes.js

@@ -0,0 +1,116 @@
+// ---------------------------------------------------------------------------
+// Includes / assets: resolve `@include` (and `@loop` data) targets to absolute
+// paths inside `site/pages` or `site/_`, register colocated `.skin`/`.js`
+// siblings, and warn when a plain `.md` file uses `.wd`-only syntax.
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+import path from "node:path";
+import { pageIncludeExtensions } from "./context.js";
+import { stripQuotes } from "./interpolation.js";
+
+/**
+ * @typedef {import("./context.js").Paths} Paths
+ * @typedef {import("./context.js").Assets} Assets
+ * @typedef {import("./context.js").Compilation} Compilation
+ */
+
+/**
+ * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
+ * @param {string} file
+ * @param {Paths} context
+ * @param {Assets} assets
+ * @returns {void}
+ */
+export function collectColocatedAssets(file, context, assets) {
+  const ext = path.extname(file);
+  const stem = file.slice(0, -ext.length);
+  for (const [assetExt, folder] of [
+    [".skin", "styles"],
+    [".js", "scripts"]
+  ]) {
+    const candidate = `${stem}${assetExt}`;
+    if (!fs.existsSync(candidate)) continue;
+    const rel = path.relative(context.cwd, candidate).replaceAll(path.sep, "/");
+    const outputExt = assetExt === ".skin" ? ".css" : ".js";
+    const publicPath = `/__wd/${folder}/${rel.slice(0, -assetExt.length).replace(/[/.]/g, "_")}${outputExt}`;
+    assets.files.set(candidate, publicPath);
+    if (assetExt === ".skin") assets.skins.add(publicPath);
+    if (assetExt === ".js") assets.scripts.add(publicPath);
+  }
+}
+
+/**
+ * Resolve an include spec to an absolute path inside `site/pages` or `site/_`.
+ * @param {string} spec Include target (may be quoted).
+ * @param {string} fromFile File requesting the include.
+ * @param {Paths} context
+ * @param {boolean} [allowAny] Allow non-page extensions (e.g. JSON for `@loop`).
+ * @returns {string}
+ */
+export function resolveInclude(spec, fromFile, context, allowAny = false) {
+  const clean = stripQuotes(spec);
+  const candidates = [];
+  if (clean.startsWith("/")) {
+    candidates.push(path.join(context.shelfRoot, clean.slice(1)));
+  } else {
+    candidates.push(path.resolve(path.dirname(fromFile), clean));
+    candidates.push(path.join(context.shelfRoot, clean));
+  }
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (!isAllowedInclude(resolved, context)) {
+      throw new Error(`Include "${spec}" from ${fromFile} resolves outside site/pages or site/_`);
+    }
+    if (!fs.existsSync(resolved)) continue;
+    if (!allowAny && !pageIncludeExtensions.includes(path.extname(resolved))) continue;
+    return resolved;
+  }
+  throw new Error(`Could not resolve include "${spec}" from ${fromFile}`);
+}
+
+/**
+ * @param {string} file
+ * @param {Paths} context
+ * @returns {boolean}
+ */
+export function isAllowedInclude(file, context) {
+  const roots = [context.routesRoot, context.shelfRoot].map((root) => path.resolve(root));
+  return roots.some((root) => file === root || file.startsWith(`${root}${path.sep}`));
+}
+
+// ---------------------------------------------------------------------------
+// Plain .md hints
+// ---------------------------------------------------------------------------
+
+/**
+ * Warn when a plain `.md` file contains `.wd`-only syntax that stays inert.
+ * @param {string} body
+ * @param {string} file
+ * @param {Compilation} comp
+ * @returns {void}
+ */
+export function scanMarkdownHints(body, file, comp) {
+  let fence = null;
+  for (const line of body.split("\n")) {
+    const fenceMatch = line.match(/^(```+|~~~+)/);
+    if (fence) {
+      if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length)
+        fence = null;
+      continue;
+    }
+    if (fenceMatch) {
+      fence = fenceMatch[1];
+      continue;
+    }
+    const hit = line.match(
+      /^(@include|@loop|@repeat|:state|:button|:if|:for|:try|:note|:sprint|:::)(\s|$)/
+    );
+    if (hit) {
+      comp.warnings.push(
+        `${file}: "${hit[1]}" is .wd syntax and stays plain text in .md — rename the file to .wd to activate it.`
+      );
+      return;
+    }
+  }
+}

package/src/compiler/index.js

@@ -0,0 +1,22 @@
+// ---------------------------------------------------------------------------
+// Compiler module wiring. The compiler is split across cohesive seams:
+//
+//   context.js        shared typedefs + tiny helpers (createCompilation, at, …)
+//   interpolation.js  path/value resolution, state-key lookup, escapeHtml, literals
+//   frontmatter.js    `---` block → meta + body, inline scalar/array parsing
+//   includes.js       @include / @loop-data resolution, colocated assets, .md hints
+//   predicates.js     where / when / :if / :computed expression compilers
+//   markdown.js       markdown-it instances + plugins + prose interpolation
+//   loops.js          @loop pipeline + row-template initial-paint fill
+//   directives.js     the handle* family + :button action parser + demo directives
+//   body.js           the line-based directive dispatcher (compileBody)
+//   page.js           HTML page shell, image hardening, per-file compile
+//
+// This barrel re-exports the public API; `src/compiler.js` re-exports from here
+// so every existing `import … from "./compiler.js"` keeps working unchanged.
+// ---------------------------------------------------------------------------
+
+export { parseFrontmatter } from "./frontmatter.js";
+export { escapeHtml } from "./interpolation.js";
+export { loopKeyOf } from "./loops.js";
+export { compileDocument, compilePage, enhanceImages } from "./page.js";

package/src/compiler/interpolation.js

@@ -0,0 +1,189 @@
+// ---------------------------------------------------------------------------
+// Interpolation primitives: path/value resolution, state-key lookup, scalar
+// parsing, and HTML escaping. These are the leaf utilities the directive
+// handlers, loops, predicates, and markdown layer all build on — this module
+// imports only the shared typedefs, so it sits near the root of the DAG.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {import("./context.js").Scope} Scope
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+
+/**
+ * Walk the scope chain for a top-level variable.
+ * @param {Scope} scope
+ * @param {string} name
+ * @returns {{ found: true, value: unknown } | { found: false }}
+ */
+export function lookupVar(scope, name) {
+  /** @type {Scope | null} */
+  let current = scope;
+  for (; current; current = current.parent) {
+    if (name in current.vars) return { found: true, value: current.vars[name] };
+  }
+  return { found: false };
+}
+
+/**
+ * Resolve a dotted path against the static scope chain.
+ * @param {string} expr
+ * @param {Ctx} ctx
+ * @returns {{ found: true, value: unknown } | { found: false }}
+ */
+export function lookupPath(expr, ctx) {
+  const segs = expr.split(".");
+  const head = lookupVar(ctx.scope, segs[0]);
+  if (!head.found) return { found: false };
+  return { found: true, value: getPath(head.value, segs.slice(1)) };
+}
+
+/**
+ * Safely read a dotted path off a value, rejecting prototype-pollution segments.
+ * @param {unknown} value
+ * @param {string[]} segments
+ * @returns {unknown}
+ */
+export function getPath(value, segments) {
+  /** @type {any} */
+  let current = value;
+  for (const segment of segments) {
+    if (current == null) return undefined;
+    if (["constructor", "prototype", "__proto__"].includes(segment)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+/**
+ * Validate a dotted path shape, rejecting prototype-pollution segments at every
+ * level. Shared by actions/loops/fetch. Throws with a corrective `Use:` hint.
+ * @param {string} path Dotted path, e.g. `cart.items`.
+ * @param {Ctx} ctx
+ * @param {string} use Corrective suggestion for the error message.
+ * @returns {string[]} The validated segments.
+ */
+export function validatePath(path, ctx, use) {
+  const segs = path.split(".");
+  if (segs.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg))) {
+    throw new Error(`Path segment in "${path}" is not allowed in ${ctx.file}. Use: ${use}`);
+  }
+  return segs;
+}
+
+/**
+ * Resolve a bare state name to its fully-qualified key, walking section scopes.
+ * @param {string} name
+ * @param {Ctx} ctx
+ * @returns {string | null}
+ */
+export function resolveStateKey(name, ctx) {
+  for (let i = ctx.sections.length - 1; i >= 0; i--) {
+    const key = `${ctx.sections[i]}:${name}`;
+    if (ctx.comp.state.has(key)) return key;
+  }
+  return ctx.comp.state.has(name) ? name : null;
+}
+
+/**
+ * Render an interpolated value as text. Arrays join with ", " (matching the
+ * documented `{ meta.tags }` behavior); a bare object is a mistake — fail
+ * loudly with a fix rather than emitting "[object Object]".
+ * @param {unknown} value
+ * @param {string} expr
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function interpolateLeaf(value, expr, ctx) {
+  if (value === null || value === undefined) return "";
+  if (Array.isArray(value)) return value.join(", ");
+  if (typeof value === "object") {
+    throw new Error(
+      `Cannot interpolate the object value "{ ${expr} }" in ${ctx.file}. Interpolate a field instead — e.g. { ${expr}.title } — or iterate it with @loop ${expr} into item.`
+    );
+  }
+  return String(value);
+}
+
+// ---------------------------------------------------------------------------
+// Literals
+// ---------------------------------------------------------------------------
+
+/**
+ * JSON-encode a value for an inline `<script>`, escaping `<` to stay HTML-safe.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function safeScriptJson(value) {
+  return JSON.stringify(value).replaceAll("<", "\\u003c");
+}
+
+/**
+ * @param {string} raw
+ * @returns {unknown}
+ */
+export function parseStateValue(raw) {
+  const value = raw.trim();
+  if (/^["'].*["']$/.test(value)) return stripQuotes(value);
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * @param {string} raw
+ * @returns {string | number | boolean}
+ */
+export function parseScalar(raw) {
+  const trimmed = raw.trim();
+  if (/^["']/.test(trimmed)) return stripQuotes(trimmed);
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  return trimmed;
+}
+
+/**
+ * @param {string} [value]
+ * @returns {string}
+ */
+export function stripQuotes(value) {
+  return value?.replace(/^["']|["']$/g, "") ?? "";
+}
+
+/**
+ * Turn a field name / state key into a human-readable accessible name, e.g.
+ * `quest` → "Quest", `user-name` → "User name", `firstName` → "First name".
+ * Hyphens, underscores, and camelCase boundaries become spaces; the first letter
+ * is capitalized. Used to auto-derive aria-label on generated form inputs.
+ * @param {string} name
+ * @returns {string}
+ */
+export function humanizeName(name) {
+  const words = name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2") // split camelCase
+    .replace(/[-_]+/g, " ") // hyphens/underscores → spaces
+    .trim()
+    .toLowerCase();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : name;
+}
+
+/**
+ * Escape a value for safe inclusion in HTML text and attribute contexts.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}