@zvndev/darkmown 2.2.0 → 2.3.1-next.1.g3a4a8dc

package/types/src/builder.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Compile the whole site under `cwd` into `dist`, returning the route manifest.
+ *
+ * The build is always 100% static, CDN-cacheable HTML. Backend `api/*.js`
+ * functions are NOT compiled — they are the host's concern. `target` only
+ * decides the small amount of host glue Darkmown emits alongside the static
+ * output: the default (`vercel`/anything) leaves `api/` for the platform to pick
+ * up natively; `cloudflare` emits a `dist/_worker.js/` module that routes
+ * `/api/*` to those same functions and serves everything else as a static asset.
+ *
+ * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
+ * @param {{ target?: string, includeDrafts?: boolean, depMap?: boolean, changed?: string[], quietFeedHints?: boolean }} [options]
+ *   `target: "cloudflare"` emits the Pages worker. `includeDrafts: true` keeps
+ *   `draft: true` pages in the build + feeds (dev / `build --drafts`); default
+ *   excludes them at route discovery so feeds never see a draft. `depMap: true`
+ *   (dev builds) writes the per-route dependency map to `dist/.wd-dev-deps.json`.
+ *   `changed` (project-relative paths, dev only; implies `depMap`) attempts an
+ *   incremental rebuild of just the affected routes, falling back to a full
+ *   rebuild on ANY uncertainty — a stale page is worse than a slow rebuild.
+ * @returns {BuildResult}
+ */
+export function buildSite(cwd?: string, options?: {
+    target?: string;
+    includeDrafts?: boolean;
+    depMap?: boolean;
+    changed?: string[];
+    quietFeedHints?: boolean;
+}): BuildResult;
+/**
+ * Strip developer comments from the runtime before it ships. The source keeps
+ * full JSDoc type annotations (for `checkJs` + `.d.ts`) and explanatory comments
+ * so it stays readable; the browser downloads neither. This keeps the shipped
+ * runtime lean and the gzip budget honest (measured against what users receive),
+ * WITHOUT minifying — identifiers, structure, and whitespace are all preserved.
+ *
+ * Two passes, each conservative: `/** ... *\/` JSDoc blocks, then whole-line
+ * `//` comments (a line that is nothing but a comment). Trailing `//` after code
+ * and `//` inside strings/URLs are deliberately left untouched, so no string
+ * literal is ever harmed.
+ * @param {string} source
+ * @returns {string}
+ */
+export function stripRuntimeComments(source: string): string;
+/**
+ * Render the Cloudflare Pages `_headers` file from the route manifest.
+ *
+ * Cloudflare applies every matching block in order; when blocks set the same
+ * header, the later block wins. So we emit the catch-all `/*` first (baseline
+ * security headers + the reactive CSP, which since 2.1 is eval-free and satisfies
+ * every page), then one block per static route that re-states the same eval-free
+ * CSP as defense-in-depth. Reactive routes need no override — the catch-all
+ * already carries the eval-free CSP.
+ *
+ * Clean URLs mean a route like `/docs/` is served at both `/docs` and `/docs/`,
+ * so each static route emits a path glob (`/docs`, `/docs/*`) that covers both.
+ * @param {RouteManifestEntry[]} manifest
+ * @returns {string}
+ */
+export function renderCloudflareHeaders(manifest: RouteManifestEntry[]): string;
+/**
+ * @typedef {import("./config.js").Paths} Paths
+ * @typedef {import("./compiler.js").Assets} Assets
+ * @typedef {import("./compiler.js").Meta} Meta
+ * @typedef {import("./router.js").Route} Route
+ */
+/**
+ * A built route entry written to `dist/routes.json`.
+ * @typedef {object} RouteManifestEntry
+ * @property {string} route Public route path.
+ * @property {string} file Source file path, relative to cwd, POSIX-separated.
+ * @property {{ skins: string[], scripts: string[], runtime: boolean }} assets
+ */
+/**
+ * One source route's record in the dev dependency map (`dist/.wd-dev-deps.json`),
+ * written by dev builds so a later `--changed` build can rebuild only the routes
+ * whose dependency graph contains the changed file.
+ * @typedef {object} DepMapEntry
+ * @property {string} file Source file, project-relative, POSIX-separated.
+ * @property {string[]} deps Every source file this route's compile read (the page
+ *   itself, includes, loop JSON data files, colocated `.skin`/`.js`) —
+ *   project-relative, POSIX-separated, sorted.
+ * @property {string[]} collections Collection names the route loops, so a change
+ *   to any entry of the collection rebuilds this route.
+ * @property {RouteManifestEntry[]} pages The manifest entries this route emitted
+ *   (one, or one per pagination page), so `routes.json`/`_headers`/the sitemap
+ *   can be reassembled globally without recompiling untouched routes.
+ */
+/** The dev dependency map's filename under `dist/`. */
+export const DEP_MAP_FILE: ".wd-dev-deps.json";
+/**
+ * The value `buildSite` returns. `incremental` is present only when a `changed`
+ * build actually rebuilt a subset of routes (absent on every full rebuild).
+ */
+export type BuildResult = {
+    routes: RouteManifestEntry[];
+    distRoot: string;
+    feeds: {
+        sitemap: number | null;
+        rss: number | null;
+    };
+    incremental?: {
+        changed: string[];
+        rebuilt: string[];
+        total: number;
+    } | undefined;
+};
+/**
+ * A compiled page bound for a concrete output route. Mirrors `CompiledPage` plus
+ * the public `route` it's written to — for a paginated listing, page 1 keeps the
+ * listing route and pages 2+ get `/<route>/page/<n>/`.
+ */
+export type EmittedPage = {
+    /**
+     * Public route path this page is written to.
+     */
+    route: string;
+    html: string;
+    assets: import("./compiler.js").Assets;
+    warnings: string[];
+};
+export type Paths = import("./config.js").Paths;
+export type Assets = import("./compiler.js").Assets;
+export type Meta = import("./compiler.js").Meta;
+export type Route = import("./router.js").Route;
+/**
+ * A built route entry written to `dist/routes.json`.
+ */
+export type RouteManifestEntry = {
+    /**
+     * Public route path.
+     */
+    route: string;
+    /**
+     * Source file path, relative to cwd, POSIX-separated.
+     */
+    file: string;
+    assets: {
+        skins: string[];
+        scripts: string[];
+        runtime: boolean;
+    };
+};
+/**
+ * One source route's record in the dev dependency map (`dist/.wd-dev-deps.json`),
+ * written by dev builds so a later `--changed` build can rebuild only the routes
+ * whose dependency graph contains the changed file.
+ */
+export type DepMapEntry = {
+    /**
+     * Source file, project-relative, POSIX-separated.
+     */
+    file: string;
+    /**
+     * Every source file this route's compile read (the page
+     * itself, includes, loop JSON data files, colocated `.skin`/`.js`) —
+     * project-relative, POSIX-separated, sorted.
+     */
+    deps: string[];
+    /**
+     * Collection names the route loops, so a change
+     * to any entry of the collection rebuilds this route.
+     */
+    collections: string[];
+    /**
+     * The manifest entries this route emitted
+     * (one, or one per pagination page), so `routes.json`/`_headers`/the sitemap
+     * can be reassembled globally without recompiling untouched routes.
+     */
+    pages: RouteManifestEntry[];
+};

package/types/src/catalog.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The structured, machine-readable catalog of the whole `.wd` authoring surface.
+ * @returns {DirectiveCatalog}
+ */
+export function directiveCatalog(): DirectiveCatalog;
+/**
+ * Render the catalog as a compact llms.txt-style markdown cheatsheet — the
+ * artifact an app pastes into a small model's system prompt. Generated entirely
+ * from {@link directiveCatalog}, so it can never disagree with what compiles.
+ * @returns {string}
+ */
+export function llmsText(): string;
+/** The action tokens the catalog exposes — used by the drift guard. */
+export const CATALOG_ACTION_TOKENS: string[];
+/**
+ * Whether the directive
+ *   ships zero JS (static), needs the reactive runtime (reactive), or can be
+ *   either depending on whether it reads `:state`/`:store` (either).
+ */
+export type Reactivity = "static" | "reactive" | "either";
+export type DirectiveEntry = {
+    /**
+     * The directive token (`@loop`, `:state`, `:::`, …).
+     */
+    name: string;
+    /**
+     * A single line, or an opener with a closer.
+     */
+    kind: "line" | "block";
+    /**
+     * One-line schematic (`[…]` = optional, `<…>` = slot).
+     */
+    syntax: string;
+    /**
+     * One-line, plain-language summary.
+     */
+    description: string;
+    /**
+     * One concrete, compilable line.
+     */
+    example: string;
+    reactive: Reactivity;
+};
+/**
+ * A clause / action-op / pipe / operator entry.
+ */
+export type CatalogEntry = {
+    name: string;
+    syntax?: string | undefined;
+    description: string;
+    example?: string | undefined;
+};
+export type DirectiveCatalog = {
+    /**
+     * The installed Darkmown version.
+     */
+    version: string;
+    /**
+     * Always `.wd` — the file extension that gates directives.
+     */
+    format: string;
+    directives: DirectiveEntry[];
+    /**
+     * Clauses of the `@loop` header (fixed order).
+     */
+    loopClauses: CatalogEntry[];
+    /**
+     * Per-row meta variables valid in a loop body.
+     */
+    loopVariables: CatalogEntry[];
+    /**
+     * The `:button`/`:effect`/`:every` action vocabulary.
+     */
+    actionOps: CatalogEntry[];
+    /**
+     * The `{ value | pipe }` formatter whitelist.
+     */
+    formatPipes: CatalogEntry[];
+    /**
+     * Comparison operators for `where`/`:if`/`when`.
+     */
+    predicateOps: CatalogEntry[];
+    /**
+     * Logical joiners (`and`/`or`/`not`).
+     */
+    predicateJoiners: string[];
+    /**
+     * The `WDxxx` code blocks.
+     */
+    errorAreas: import("./errors.js").ErrorArea[];
+    /**
+     * Every stable compile-error
+     * code, with its cause and fix. A thrown error's message starts with its code
+     * (`[WD201] …`) and mirrors it on `err.wd.code`.
+     */
+    errors: import("./errors.js").ErrorEntry[];
+};

package/types/src/compiler/actions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleButton(line: string, ctx: Ctx, index: number): string;
+/**
+ * Parse `:effect <watched> -> <actions>` into a zero-output marker the runtime
+ * watches: when `<watched>` state changes, it runs `<actions>` (the same `:button`
+ * action vocabulary, `;`-chained). For arbitrary side effects beyond `:computed`
+ * (derive state) and fetch deps (auto-refetch).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleEffect(line: string, ctx: Ctx, index: number): string;
+/**
+ * Parse `:every <duration> -> <actions>` into a marker the runtime drives on a
+ * timer: every `<duration>` it runs `<actions>` (the same `:button` vocabulary,
+ * `;`-chained), and the interval auto-pauses while the tab is hidden. The one time
+ * primitive — behind live polling (`:every 5s -> board refetch`), clocks and
+ * countdowns (`:every 1s -> seconds++`), and slideshow autoplay (`:every 4s -> slide++`).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleEvery(line: string, ctx: Ctx, index: number): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {import("./context.js").Action} Action
+ */
+export const BUTTON_EXAMPLE: ":button \"Add one\" -> count++";
+export const EFFECT_EXAMPLE: ":effect query -> searches++";
+export const EVERY_EXAMPLE: ":every 5s -> seconds++";
+export const ACTION_EXAMPLE: "count++";
+export const ACTION_USE: "Use: name++, name--, n += k, n -= k, name = v, flag toggle, list append/prepend v, list toggle v, list remove v, x clear, obj merge other, obj delete key, name reset — chain with \";\" — e.g. count++";
+export type Ctx = import("./context.js").Ctx;
+export type Action = import("./context.js").Action;

package/types/src/compiler/body.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+/**
+ * Parse a `.wd` body line-by-line into HTML, mixing directives and prose.
+ * @param {string[]} lines
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function compileBody(lines: string[], ctx: Ctx): string;
+export type Ctx = import("./context.js").Ctx;

package/types/src/compiler/collections.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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`).
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed by
+ *   default; pass an in-memory reader to build collections without a filesystem).
+ * @returns {Map<string, CollectionRow[]>} Collection name → entry rows.
+ */
+export function buildCollections(routes: Route[], paths: Paths, reader?: import("./reader.js").Reader): Map<string, CollectionRow[]>;
+/**
+ * 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
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed by default).
+ * @returns {SchemaField[] | null}
+ */
+export function readSchema(name: string, paths: Paths, reader?: import("./reader.js").Reader): SchemaField[] | null;
+/**
+ * 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: string, file: string): SchemaField[];
+/**
+ * A parsed `_schema.wd` field rule.
+ */
+export type SchemaField = {
+    /**
+     * Field name.
+     */
+    name: string;
+    /**
+     * One of {@link SCHEMA_TYPES}.
+     */
+    type: string;
+    /**
+     * Whether the field may be absent (`?` modifier).
+     */
+    optional: boolean;
+};
+export type Paths = import("./context.js").Paths;
+export type Meta = import("./context.js").Meta;
+export type Route = import("../router.js").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.
+ */
+export type CollectionRow = Record<string, unknown> & {
+    url: string;
+    slug: string;
+    excerpt: string;
+};