@zvndev/darkmown 1.3.0 → 1.5.0

package/src/compiler/collections.js

@@ -0,0 +1,316 @@
+// ---------------------------------------------------------------------------
+// Typed content collections. ANY `site/pages/<name>/` subdirectory is a
+// queryable collection, referenced by its bare name in `@loop` (no `content/`
+// root, no marker file). The index is built from the router's already-parsed
+// `route.meta` — frontmatter is never re-parsed here — and each entry becomes a
+// row the existing where/sort/format-pipe/`:if`/`:every` machinery consumes
+// UNCHANGED: every frontmatter field plus the derived `url` (entry route),
+// `slug` (filename stem), and an `excerpt` (frontmatter `excerpt:` → first
+// paragraph of a `.md` body).
+//
+// An optional `_schema.wd` at the collection root opts the collection into
+// build-time validation: every entry's frontmatter is checked against a small,
+// closed type DSL (`field: string|number|boolean|date|string[]`, `?` = optional)
+// with `file:line` errors. No `_schema.wd` = no validation (opt-in, like
+// `scoped`/`draft`).
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+import path from "node:path";
+import { firstParagraph } from "../feeds.js";
+import { parseFrontmatter } from "./frontmatter.js";
+
+/**
+ * @typedef {import("./context.js").Paths} Paths
+ * @typedef {import("./context.js").Meta} Meta
+ * @typedef {import("../router.js").Route} Route
+ */
+
+/**
+ * A collection entry row: every frontmatter field, plus derived `url`/`slug`/
+ * `excerpt`. Keyed loosely so authors' custom frontmatter keys pass through to
+ * `{ post.whatever }` and `where`/`sort` without a closed schema here.
+ * @typedef {Record<string, unknown> & { url: string, slug: string, excerpt: string }} CollectionRow
+ */
+
+/** The closed type vocabulary for `_schema.wd`. `?` (optional) is a modifier. */
+const SCHEMA_TYPES = new Set(["string", "number", "boolean", "date", "string[]"]);
+
+/**
+ * Build the collection index from the router's discovered routes: one entry per
+ * `site/pages/<name>/…` route, grouped under the FIRST path segment (the
+ * collection name). The home route, top-level pages, and the synthetic `/404/`
+ * route are not entries. Reuses each route's already-parsed `meta` (no re-parse)
+ * and reads the `.md` body only for the excerpt fallback. When a collection has
+ * a `_schema.wd`, every entry is validated against it here (throwing on the
+ * first violation), so a malformed entry fails the build with a `file:line`.
+ *
+ * @param {Route[]} routes Post-draft-filter routes from `discoverRoutes`.
+ * @param {Paths} paths Resolved project paths (`routesRoot` for `_schema.wd`).
+ * @returns {Map<string, CollectionRow[]>} Collection name → entry rows.
+ */
+export function buildCollections(routes, paths) {
+  /** @type {Map<string, CollectionRow[]>} */
+  const collections = new Map();
+  for (const route of routes) {
+    const name = collectionNameOf(route.route);
+    if (!name) continue;
+    const rows = collections.get(name) || [];
+    rows.push(rowFor(route));
+    collections.set(name, rows);
+  }
+  for (const [name, rows] of collections) {
+    const schema = readSchema(name, paths);
+    if (schema) validateRows(rows, schema, name);
+  }
+  return collections;
+}
+
+/**
+ * The collection name a route belongs to: the first path segment of a nested
+ * route (`/blog/hello/` → `blog`), or null for the home page, a top-level page
+ * (`/about/` → no nesting), or the `/404/` route (never a collection entry).
+ * @param {string} route Public route path (trailing-slashed).
+ * @returns {string | null}
+ */
+function collectionNameOf(route) {
+  if (route === "/" || route === "/404/") return null;
+  const parts = route.replace(/^\/|\/$/g, "").split("/");
+  return parts.length >= 2 ? parts[0] : null;
+}
+
+/**
+ * Build one collection row from a route: spread its frontmatter, then add the
+ * derived `url` (the route path), `slug` (filename stem), and `excerpt`
+ * (frontmatter `excerpt:` wins; else the first paragraph of a `.md` body; `.wd`
+ * bodies are not scanned — directive markup isn't clean prose). The derived keys
+ * are added AFTER the spread so a stray frontmatter `url:`/`slug:` can't shadow
+ * the real route data the loop relies on.
+ * @param {Route} route
+ * @returns {CollectionRow}
+ */
+function rowFor(route) {
+  const slug = path.basename(route.file, path.extname(route.file));
+  /** @type {Record<string, unknown>} */
+  const fields = {};
+  for (const [key, value] of Object.entries(route.meta)) fields[key] = coerceScalar(value);
+  return {
+    ...fields,
+    url: route.route,
+    slug: slug === "index" ? path.basename(path.dirname(route.file)) : slug,
+    excerpt: excerptFor(route)
+  };
+}
+
+/**
+ * Coerce a frontmatter scalar to its natural type for querying. The frontmatter
+ * parser yields scalars as STRINGS (`true`, `42` arrive as `"true"`, `"42"`), but
+ * a collection loop should behave like a JSON loop, where `where p.featured ==
+ * true` and numeric `sort`/comparisons just work. So a bare `true`/`false` becomes
+ * a boolean and a numeric string becomes a number; quoted/other strings and
+ * arrays pass through untouched. This coercion is scoped to collection rows only —
+ * it never touches the global frontmatter parser (a `:state`/`{ meta.x }` value
+ * keeps its existing string form).
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function coerceScalar(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (typeof value === "string" && /^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  return value;
+}
+
+/**
+ * The excerpt for an entry: the frontmatter `excerpt:` string if present, else
+ * (plain `.md` only) the first paragraph of its body, else "". Mirrors the RSS
+ * description fallback so a collection card and the feed read the same snippet.
+ * @param {Route} route
+ * @returns {string}
+ */
+function excerptFor(route) {
+  const fromMeta = route.meta.excerpt;
+  if (typeof fromMeta === "string" && fromMeta.trim()) return fromMeta.trim();
+  if (path.extname(route.file) !== ".md") return "";
+  const { body } = parseFrontmatter(fs.readFileSync(route.file, "utf8"), route.file);
+  return firstParagraph(body);
+}
+
+/**
+ * A parsed `_schema.wd` field rule.
+ * @typedef {object} SchemaField
+ * @property {string} name Field name.
+ * @property {string} type One of {@link SCHEMA_TYPES}.
+ * @property {boolean} optional Whether the field may be absent (`?` modifier).
+ */
+
+/**
+ * Read + parse a collection's `_schema.wd`, or null when the file is absent
+ * (validation is opt-in). The schema is frontmatter-shaped — one `field: type`
+ * line per rule inside the `---` block — so authors write it exactly like the
+ * frontmatter it validates. Each type must be in the closed {@link SCHEMA_TYPES}
+ * vocabulary (`?` suffix = optional); an unknown token is a compile error in the
+ * schema file itself, pointing at the offending line.
+ * @param {string} name Collection name.
+ * @param {Paths} paths
+ * @returns {SchemaField[] | null}
+ */
+export function readSchema(name, paths) {
+  const file = path.join(paths.routesRoot, name, "_schema.wd");
+  if (!fs.existsSync(file)) return null;
+  const raw = fs.readFileSync(file, "utf8");
+  return parseSchema(raw, file);
+}
+
+/**
+ * Parse a `_schema.wd` source into field rules. The schema fields live in the
+ * frontmatter block; the body (if any) is ignored, so a schema file can carry a
+ * prose note after its `---` fence. Each field line is `name: type` where type
+ * is a closed token with an optional trailing `?`.
+ * @param {string} raw `_schema.wd` file contents.
+ * @param {string} file Absolute path, for `file:line` errors.
+ * @returns {SchemaField[]}
+ */
+export function parseSchema(raw, file) {
+  // Use the same `---` extraction as page frontmatter so the schema block is
+  // delimited identically. A schema with no fence is read as bare lines.
+  const lines = raw.replace(/\r\n?/g, "\n").split("\n");
+  /** @type {SchemaField[]} */
+  const fields = [];
+  let fenced = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (trimmed === "---") {
+      // First `---` opens the block; the second closes it and ends the schema.
+      if (!fenced && fields.length === 0) {
+        fenced = true;
+        continue;
+      }
+      if (fenced) break; // closing fence — rest of the file is prose, ignore it
+    }
+    if (!trimmed || trimmed.startsWith("#")) continue; // blank line or comment
+    const match = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.+)$/);
+    if (!match) {
+      throw new Error(
+        `Malformed schema line in ${file}:${i + 1}: "${trimmed}". Use: field: type (e.g. \`title: string\`, \`tags: string[]\`, \`featured: boolean?\`).`
+      );
+    }
+    fields.push(parseSchemaField(match[1], match[2].trim(), file, i + 1));
+  }
+  return fields;
+}
+
+/**
+ * Parse one `name: type` schema rule, validating the type against the closed
+ * vocabulary and peeling the optional `?` modifier.
+ * @param {string} name
+ * @param {string} rawType Type token (may end in `?`).
+ * @param {string} file
+ * @param {number} lineNo 1-based line number for the error.
+ * @returns {SchemaField}
+ */
+function parseSchemaField(name, rawType, file, lineNo) {
+  const optional = rawType.endsWith("?");
+  const type = optional ? rawType.slice(0, -1).trim() : rawType;
+  if (!SCHEMA_TYPES.has(type)) {
+    throw new Error(
+      `Unknown schema type "${rawType}" for field "${name}" in ${file}:${lineNo}. Use one of: ${[...SCHEMA_TYPES].join(", ")} (append "?" to make a field optional).`
+    );
+  }
+  return { name, type, optional };
+}
+
+/**
+ * Validate every collection row against the schema, throwing on the first
+ * violation with a `file:line` (the entry's own path) and the offending field.
+ * A missing required field, a wrong type, or an unknown extra field all fail —
+ * unknown keys are rejected so a typo'd frontmatter key (`titel:`) is caught
+ * rather than silently dropped.
+ * @param {CollectionRow[]} rows
+ * @param {SchemaField[]} schema
+ * @param {string} name Collection name, for the error message.
+ * @returns {void}
+ */
+function validateRows(rows, schema, name) {
+  const allowed = new Set(schema.map((field) => field.name));
+  // Framework-recognized keys never need a schema declaration: `url`/`slug`/
+  // `excerpt` are derived (always present), and `draft` is the routing gate
+  // (present on `--drafts` builds). Allow them implicitly so they don't trip the
+  // unknown-key check.
+  for (const reserved of ["url", "slug", "excerpt", "draft"]) allowed.add(reserved);
+  for (const row of rows) {
+    const where = `${String(row.url)} (collection "${name}")`;
+    for (const field of schema) validateField(row, field, where);
+    for (const key of Object.keys(row)) {
+      if (allowed.has(key)) continue;
+      throw new Error(
+        `Unknown frontmatter field "${key}" in ${where}: it is not declared in _schema.wd. Add \`${key}: <type>\` to the schema, or remove the field.`
+      );
+    }
+  }
+}
+
+/**
+ * Validate one field of one row against its schema rule.
+ * @param {CollectionRow} row
+ * @param {SchemaField} field
+ * @param {string} where Human-readable entry location for the error.
+ * @returns {void}
+ */
+function validateField(row, field, where) {
+  const present = field.name in row && row[field.name] !== null && row[field.name] !== "";
+  if (!present) {
+    if (field.optional) return;
+    throw new Error(
+      `Missing required field "${field.name}" (${field.type}) in ${where}. Add \`${field.name}: …\` to the entry's frontmatter, or mark it optional with "${field.name}: ${field.type}?" in _schema.wd.`
+    );
+  }
+  const value = row[field.name];
+  if (!matchesType(value, field.type)) {
+    throw new Error(
+      `Field "${field.name}" in ${where} should be ${field.type} but is "${describe(value)}". Fix the entry's frontmatter or the schema.`
+    );
+  }
+}
+
+/**
+ * Whether a frontmatter value satisfies a schema type. Frontmatter scalars are
+ * already strings/numbers/booleans/arrays (the parser produces no Date object),
+ * so `date` is "a string that `Date` can parse" and `number` accepts a numeric
+ * string too (frontmatter `42` parses to a number, but a quoted `"42"` stays a
+ * string — both are acceptable for a `number` field). The `type` is always one of
+ * {@link SCHEMA_TYPES} (parseSchemaField rejected anything else), so a missing
+ * checker can't occur — every {@link SCHEMA_TYPES} member has an entry below.
+ * @param {unknown} value
+ * @param {string} type
+ * @returns {boolean}
+ */
+function matchesType(value, type) {
+  return TYPE_CHECKS[type](value);
+}
+
+/**
+ * The per-type value checker for each closed schema type. Keyed exactly by
+ * {@link SCHEMA_TYPES}, so the indexed call in {@link matchesType} always lands on
+ * a real checker (no unreachable fallback branch to cover).
+ * @type {Record<string, (value: unknown) => boolean>}
+ */
+const TYPE_CHECKS = {
+  string: (value) => typeof value === "string",
+  number: (value) =>
+    typeof value === "number" || (typeof value === "string" && /^-?\d+(?:\.\d+)?$/.test(value)),
+  boolean: (value) => typeof value === "boolean" || value === "true" || value === "false",
+  date: (value) => typeof value === "string" && !Number.isNaN(new Date(value).getTime()),
+  "string[]": (value) => Array.isArray(value) && value.every((item) => typeof item === "string")
+};
+
+/**
+ * A short, safe description of a value for a validation error message.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describe(value) {
+  if (Array.isArray(value)) return `[${value.join(", ")}]`;
+  return String(value);
+}

package/src/compiler/context.js

@@ -35,6 +35,21 @@
  * @property {boolean} hasCode Whether the page has a build-time-highlighted code
  *   block, so the framework highlight stylesheet (`/__wd/highlight.css`) is
  *   emitted and linked — pay-for-what-you-use, zero JS.
+ * @property {Set<string>} scopedSkins Source paths of colocated `.skin` files
+ *   that opted into scoping (`scoped` first line). The builder emits these with
+ *   the scope attribute and runs the unused-selector warning against the stamped
+ *   subtree; the HTML stamp uses them to scope the matching page/include subtree.
+ */
+
+/**
+ * The pagination intent a `@loop … paginate N` records during compile, so the
+ * builder can multiply routes (page 1 at the listing route, 2+ at
+ * `/<route>/page/<n>/`). `total` is the post-`where`/`sort` page count for the
+ * collection the loop drew from.
+ * @typedef {object} Pagination
+ * @property {number} perPage Rows per page (the `paginate N` value).
+ * @property {number} total Total page count (≥ 1).
+ * @property {string} collection Collection name the loop paginated.
  */
 
 /**
@@ -45,6 +60,12 @@
  * @property {Set<string>} stores Page-global store names (a subset of state keys).
  * @property {string[]} warnings Non-fatal authoring hints.
  * @property {number} sectionCounter Counter for auto-generated section ids.
+ * @property {Map<string, import("./collections.js").CollectionRow[]>} collections
+ *   Collection name → entry rows, built from the router's routes and threaded in
+ *   so a bare-name `@loop blog into post` resolves to its entries at build time.
+ * @property {import("./context.js").Pagination | null} pagination The pagination
+ *   intent a `@loop … paginate N` recorded this compile, or null. The builder
+ *   reads it to multiply routes; one paginated loop per page is supported.
  */
 
 /**
@@ -76,6 +97,8 @@
  * @property {string} html
  * @property {Assets} assets
  * @property {string[]} warnings
+ * @property {Pagination | null} pagination The pagination intent a paginated
+ *   `@loop` recorded, or null. The builder reads it to multiply routes.
  */
 
 /**
@@ -85,6 +108,8 @@
  * @property {string} html
  * @property {Assets} assets
  * @property {string[]} warnings
+ * @property {Pagination | null} pagination The pagination intent a paginated
+ *   `@loop` recorded, or null. The builder reads it to multiply routes.
  */
 
 /**
@@ -111,6 +136,10 @@
  * @property {boolean} clauseRefsState Whether offset/limit reference state.
  * @property {boolean} sortable Drag-to-reorder the underlying :state/:store list
  *   (the `sortable` clause). Only valid on a plain reactive state-key loop.
+ * @property {number | null} paginate Rows-per-page for a `paginate N` clause, or
+ *   null. Only valid on a collection loop; multiplies the listing into static
+ *   pages (page 1 at the route, 2+ at `/<route>/page/<n>/`) and exposes a `page`
+ *   pager to the template scope.
  */
 
 /**
@@ -144,12 +173,15 @@ export function createCompilation() {
       files: new Map(),
       runtime: false,
       behaviors: new Set(),
-      hasCode: false
+      hasCode: false,
+      scopedSkins: new Set()
     },
     state: new Map(),
     stores: new Set(),
     warnings: [],
-    sectionCounter: 0
+    sectionCounter: 0,
+    collections: new Map(),
+    pagination: null
   };
 }
 

package/src/compiler/directives.js

@@ -12,7 +12,7 @@
 import { compileBody } from "./body.js";
 import { at, createScope, LOOP_META } from "./context.js";
 import { FORMATTERS } from "./format.js";
-import { resolveInclude } from "./includes.js";
+import { resolveInclude, scopedSkinFor } from "./includes.js";
 import {
   escapeHtml,
   getPath,
@@ -26,7 +26,7 @@ import {
   stripQuotes,
   validatePath
 } from "./interpolation.js";
-import { compileFile } from "./page.js";
+import { compileFile, stampScope } from "./page.js";
 import { compileComputedExpr, compileWhen, evalPredicate } from "./predicates.js";
 
 /**
@@ -45,17 +45,23 @@ export function handleInclude(line, ctx, index) {
   if (!match) throw new Error(`Malformed @include in ${at(ctx.file, index)}: ${line}`);
   const target = resolveInclude(match[1], ctx.file, ctx.context);
   const args = parseIncludeArgs(match[2] || "", ctx);
-  const scope = createScope(ctx.scope, args);
+  const childScope = createScope(ctx.scope, args);
   const child = compileFile(
     target,
     ctx.context,
     ctx.stack,
-    scope,
+    childScope,
     ctx.comp,
     ctx.sections,
     ctx.loopItem
   );
-  return child.html;
+  // An include with its OWN scoped colocated skin stamps just its returned
+  // subtree — so a scoped `.card` in the include can't collide with a `.card`
+  // anywhere else on the page, and the scope never leaks to the include's
+  // siblings (only this child HTML is stamped). The CSS rewrite (builder) uses
+  // the same path-derived id, so attribute and stylesheet line up.
+  const scopedSkin = scopedSkinFor(target, ctx.context);
+  return scopedSkin && scopedSkin.scoped ? stampScope(child.html, scopedSkin.scopeId) : child.html;
 }
 
 /**

package/src/compiler/includes.js

@@ -6,6 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { scopeIdFor } from "../skin.js";
 import { pageIncludeExtensions } from "./context.js";
 import { stripQuotes } from "./interpolation.js";
 
@@ -15,6 +16,47 @@ import { stripQuotes } from "./interpolation.js";
  * @typedef {import("./context.js").Compilation} Compilation
  */
 
+/**
+ * Read a `.skin` file's first meaningful line (skipping `//` line comments,
+ * `/* … *\/` block comments, blanks, and decorative dividers — the same skip
+ * rules `compileSkin` applies) to decide whether it opts into scoping. A skin
+ * scopes its selectors ONLY when that first line is exactly `scoped`; otherwise
+ * it is global and untouched. This is the single source for "is this skin
+ * scoped + what is its id", so the CSS rewrite (builder) and the HTML stamp
+ * (page/include) always agree on both.
+ * @param {string} skinPath Absolute path to the colocated `.skin` file.
+ * @param {string} cwd Project root, for the path-based scope id.
+ * @returns {{ scoped: boolean, scopeId: string }}
+ */
+export function scopeInfoForSkin(skinPath, cwd) {
+  const rel = path.relative(cwd, skinPath).replaceAll(path.sep, "/");
+  const scopeId = scopeIdFor(rel);
+  const src = fs.readFileSync(skinPath, "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+  for (const raw of src.split("\n")) {
+    const t = raw.trim();
+    if (!t || t.startsWith("//") || !/[A-Za-z0-9]/.test(t)) continue;
+    return { scoped: t === "scoped", scopeId };
+  }
+  return { scoped: false, scopeId };
+}
+
+/**
+ * The scope info for a page/include's OWN colocated `.skin` sibling, or null
+ * when there is no sibling skin. Used by the HTML stamp sites: a route's own
+ * scoped skin → stamp the page body; an include's scoped skin → stamp the
+ * returned subtree. Resolution mirrors `collectColocatedAssets` (same stem,
+ * `.skin` extension).
+ * @param {string} file Absolute path to the page/include source file.
+ * @param {Paths} context
+ * @returns {{ scoped: boolean, scopeId: string } | null}
+ */
+export function scopedSkinFor(file, context) {
+  const ext = path.extname(file);
+  const candidate = `${file.slice(0, -ext.length)}.skin`;
+  if (!fs.existsSync(candidate)) return null;
+  return scopeInfoForSkin(candidate, context.cwd);
+}
+
 /**
  * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
  * @param {string} file
@@ -35,7 +77,12 @@ export function collectColocatedAssets(file, context, assets) {
     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 === ".skin") {
+      assets.skins.add(publicPath);
+      // Surface "this skin is scoped" so the warning pass (builder) and the HTML
+      // stamp can find the scoped skins among all colocated ones by source path.
+      if (scopeInfoForSkin(candidate, context.cwd).scoped) assets.scopedSkins.add(candidate);
+    }
     if (assetExt === ".js") assets.scripts.add(publicPath);
   }
 }

package/src/compiler/index.js

@@ -20,4 +20,4 @@
 export { parseFrontmatter } from "./frontmatter.js";
 export { escapeHtml } from "./interpolation.js";
 export { loopKeyOf } from "./loops.js";
-export { compileDocument, compilePage, enhanceImages } from "./page.js";
+export { compileDocument, compilePage, enhanceImages, stampScope } from "./page.js";