@valancex/cli 0.0.0-stage → 0.11.0

package/dist/compile.js

@@ -0,0 +1,217 @@
+// Build time, in Node: the templates → one MESH program. Templates are found, never listed: every `.mprx` file under `src/` is a component named by its file (`src/callout.mprx` is
+// `<callout>`), and the framework's own (`views/` in this package) fill in what the author did not write. A template with the same name as a built-in replaces it. The manifest MESH checks
+// the templates against is derived (Valance's `manifest`) from the tag table, the layout's scope and the command table, so there is no manifest file to keep in step.
+import { compileProgram } from "@valancex/mesh-compiler";
+import { manifest } from "@valancex/valance/web/build";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { commandTable, scopeSchema } from "@valancex/common/internal";
+import { AppError, diagnostic } from "./diagnostics.js";
+import { declarationsOf, linked, nameOf, treeOf } from "./tree.js";
+import { tagsOf } from "./outline.js";
+import { entryOf } from "./contract.js";
+import { locateKey } from "./wiring.js";
+import { primitives } from "@valancex/common/internal";
+import { ENTRY_FILE } from "./project.js";
+export const SOURCE_DIR = "src";
+/** The component the page is drawn by. */
+export const ROOT = "layout";
+export const BUILT_IN = fileURLToPath(new URL("../views/", import.meta.url));
+/** The package directory: where its README, which documents the framework's own names, is. */
+export const PACKAGE_DIR = fileURLToPath(new URL("../", import.meta.url));
+const mprxIn = (dir) => existsSync(dir)
+    ? readdirSync(dir, { recursive: true, encoding: "utf8" })
+        .filter((file) => file.endsWith(".mprx"))
+        .sort()
+    : [];
+const entryText = (root) => {
+    try {
+        return readFileSync(join(root, ENTRY_FILE), "utf8");
+    }
+    catch {
+        return "";
+    }
+};
+/**
+ * Built-in templates, then the author's. The author's are exactly the ones `src/main.ts` declares: `layout`, `components` and `override`. A file under `src/` that is not declared is an error, not
+ * a guess; a registered component that no template writes is allowed (it is not part of the program until one does). Which components a template uses is read from the template. A name that is a built-in's replaces it only through `override`.
+ */
+export const templatesOf = (root, author) => {
+    const found = new Map();
+    for (const file of mprxIn(BUILT_IN)) {
+        const component = basename(file, ".mprx");
+        found.set(component, { component, path: `@valancex/cli/views/${file}`, source: readFileSync(join(BUILT_IN, file), "utf8"), builtIn: true });
+    }
+    const layout = author?.layout;
+    const overrides = author?.override ?? [];
+    const declared = treeOf(layout, overrides, author?.components ?? []);
+    const declarations = declarationsOf(root);
+    const problems = [];
+    /** Where a template's component is defined: its `component(…)` call, else where it is imported, else the top of the entry file. */
+    const at = (file) => {
+        const site = declarations.get(file);
+        return site?.call ?? site?.imported ?? { file: ENTRY_FILE, line: 1, column: 1 };
+    };
+    const problem = (place, code, message) => {
+        problems.push(diagnostic(place.file, place.line, code, message, place.column));
+    };
+    // The layout's inputs are the state and the commands, so it has no props or events of its own to declare.
+    if (layout !== undefined && (layout.props !== undefined || layout.events !== undefined)) {
+        problem(at(layout.template.mprx), "layout-contract", "the layout takes no props and raises no events: its inputs are the state and the commands. Declare state fields and commands in defineApp instead");
+    }
+    if (layout !== undefined && nameOf(layout.template.mprx) !== ROOT) {
+        problem(at(layout.template.mprx), "layout-name", `the layout's template must be named ${ROOT}.mprx, not ${basename(layout.template.mprx)}`);
+    }
+    const builtInNames = new Set(found.keys());
+    for (const each of overrides) {
+        const name = nameOf(each.template.mprx);
+        if (!builtInNames.has(name) && name !== ROOT) {
+            problem(at(each.template.mprx), "override-unknown", `<${name}> is not a built-in component, so there is nothing to override; list it in the \`uses\` of the component that uses it`);
+        }
+    }
+    const files = new Map();
+    for (const node of declared) {
+        const place = at(node.file);
+        if (files.has(node.name) && files.get(node.name) !== node.file) {
+            problem(place, "template-duplicate", `${files.get(node.name)} is also <${node.name}>: a component is named by its file, so the name must be unique`);
+            continue;
+        }
+        if (node.name in primitives) {
+            problem(place, "template-primitive", `<${node.name}> is already a tag the framework draws as an element; name the file something else`);
+            continue;
+        }
+        if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(node.name)) {
+            problem(place, "template-name", `"${node.name}" cannot be a tag: use lowercase words joined by - (for example callout or post-card)`);
+            continue;
+        }
+        if (!existsSync(join(root, node.file))) {
+            problem(place, "template-missing", `${node.file} does not exist`);
+            continue;
+        }
+        files.set(node.name, node.file);
+        found.set(node.name, { component: node.name, path: node.file, source: readFileSync(join(root, node.file), "utf8"), builtIn: false });
+    }
+    // Every template under src/ must be somewhere in the tree.
+    for (const file of mprxIn(join(root, SOURCE_DIR))) {
+        const path = `${SOURCE_DIR}/${file}`;
+        if (![...files.values()].includes(path)) {
+            problems.push(diagnostic(path, 0, "template-unused", `${path} is not in the component tree: import it in ${ENTRY_FILE} and ${basename(file) === `${ROOT}.mprx` ? "pass it as `layout`" : "list it in `components`"}`));
+        }
+    }
+    // Who uses whom is what the templates write: a component's uses are the declared components whose tags its template has.
+    const tree = linked(declared, layout, overrides, (name) => [...tagsOf(found.get(name)?.source ?? "").keys()]);
+    if (problems.length > 0) {
+        throw new AppError(problems);
+    }
+    return { all: [...found.values()], tree };
+};
+/** The templates the root reaches, following the tags each uses. A template nothing uses is not part of the program (the compiler refuses one). */
+const reachable = (all) => {
+    const byName = new Map(all.map((template) => [template.component, template]));
+    const seen = new Set();
+    const queue = [ROOT];
+    while (queue.length > 0) {
+        const name = queue.pop();
+        const template = byName.get(name);
+        if (template === undefined || seen.has(name)) {
+            continue;
+        }
+        seen.add(name);
+        for (const tag of tagsOf(template.source).keys()) {
+            queue.push(tag);
+        }
+    }
+    return all.filter((template) => seen.has(template.component));
+};
+export const manifestOf = (author) => manifest({
+    primitives,
+    scopes: { [ROOT]: scopeSchema(author) },
+    commands: commandTable(author),
+});
+const isManifestError = (error) => error instanceof Error && error._tag === "ManifestError";
+/**
+ * The model the templates are checked against: the derived one (the tags, the layout's scope, the commands), and an entry for each component that declares its interface. A declared interface is
+ * exactly what was written, an omitted side being none, and it overrides inference; a component that declares neither props nor events keeps the contract MESH infers from its template and its
+ * uses. MESH checks every use against it (an undeclared prop, a missing one, a wrong type, an undeclared event in a handler), at the use or in the template. A schema with no model type is a
+ * diagnostic at the declaration, not a crash.
+ */
+const modelOf = (root, author, tree) => {
+    const problems = [];
+    const mainText = entryText(root);
+    let derived;
+    try {
+        derived = manifestOf(author);
+    }
+    catch (error) {
+        if (!isManifestError(error)) {
+            throw error;
+        }
+        // `layout.theme.deep`: a state field (the layout's scope) names where; anything else is the commands.
+        const field = /^layout\.([^.[]+)/.exec(error.path)?.[1];
+        const place = field === undefined ? { file: ENTRY_FILE, line: 1, column: 1 } : locateKey(mainText, field);
+        problems.push(diagnostic(place.file, place.line, "state-type", `${field === undefined ? error.path : `the state field "${field}"`} has no type the model can hold: ${error.message.replace(/^[\w.[\]]+: /, "")}`, place.column));
+    }
+    const declarations = declarationsOf(root);
+    const entries = {};
+    for (const node of tree) {
+        if (node.interface === undefined || node.name === ROOT) {
+            continue;
+        }
+        const { entry, problems: bad } = entryOf(node.interface);
+        const site = declarations.get(node.file);
+        for (const each of bad) {
+            const place = site?.member(each.kind, each.name) ?? site?.call ?? site?.imported ?? { file: ENTRY_FILE, line: 1, column: 1 };
+            problems.push(diagnostic(place.file, place.line, "component-schema", `${node.name}'s ${each.kind === "props" ? "prop" : "event"} "${each.name}" has no type the model can hold: ${each.reason}`, place.column));
+        }
+        entries[node.name] = entry;
+    }
+    if (problems.length > 0 || derived === undefined) {
+        throw new AppError(problems);
+    }
+    return { ...derived, components: { ...derived.components, ...entries } };
+};
+/** Compiles the application's templates. Fails with every diagnostic, each pointing into the file it is about. */
+export const compileViews = async (root, author) => {
+    const { all, tree } = templatesOf(root, author);
+    const used = reachable(all);
+    const model = modelOf(root, author, tree);
+    if (!used.some((template) => template.component === ROOT)) {
+        throw new AppError([diagnostic(`${SOURCE_DIR}/${ROOT}.mprx`, 0, "layout-missing", "there is no layout")]);
+    }
+    const result = await compileProgram({
+        model: { manifest: JSON.stringify(model), path: ".valance/manifest.json" },
+        root: ROOT,
+        components: used.map((template) => ({ component: template.component, source: template.source, path: template.path })),
+    });
+    if (result.program === undefined) {
+        const found = [
+            ...(result.components ?? []).flatMap((entry) => entry.diagnostics.diagnostics
+                .filter((each) => each.severity === "error")
+                .map((each) => diagnostic(each.path, each.span.start.line, each.code, each.message + (each.suggestions.length > 0 ? ` (did you mean ${each.suggestions.map((suggestion) => `"${suggestion.replacement}"`).join(" or ")}?)` : ""), each.span.start.column))),
+            ...(result.assembly?.diagnostics ?? []).map((each) => diagnostic(each.path ?? "program", each.span?.start.line ?? 0, each.code, each.message, each.span?.start.column ?? 0)),
+        ];
+        throw new AppError(found.map((each) => relocate(each, root)));
+    }
+    const program = result.program;
+    const enriched = program.model;
+    const manifestOfProgram = typeof enriched === "string" ? JSON.parse(enriched) : enriched;
+    return {
+        program,
+        manifest: manifestOfProgram,
+        tree,
+        files: Object.fromEntries(used.filter((template) => !template.builtIn).map((template) => [template.path, template.component])),
+        components: used.map((template) => template.component),
+        templates: used.map((template) => ({
+            component: template.component,
+            file: template.builtIn
+                ? relative(root, join(BUILT_IN, `${template.component}.mprx`))
+                    .split(sep)
+                    .join("/")
+                : template.path,
+            source: template.source,
+            builtIn: template.builtIn,
+        })),
+    };
+};
+const relocate = (each, root) => ({ ...each, file: each.file.startsWith(root) ? relative(root, each.file) : each.file });

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+import type { SiteInfo } from "@valancex/common/internal";
+export declare const PROJECT_FILE = "valance.json";
+export declare const WEB_FILE = "valance.web.json";
+/** The only version of both files there is. */
+export declare const CONFIG_VERSION = 1;
+export interface Config {
+    readonly name: string;
+    readonly web: {
+        readonly base: string;
+        readonly url: string;
+    };
+}
+/** Reads and validates the project's configuration. Every problem in both files is reported together. */
+export declare const loadConfig: (root: string) => Config;
+export declare const siteInfo: (config: Config) => SiteInfo;
+/**
+ * The nearest directory at or above `from` that holds a `valance.json`, as its real path. The bundler names a file by its real path, so a project reached through a symlink, or by a short
+ * Windows name (`RUNNER~1`), must be called the same thing here or a file is not the file the bundler means.
+ */
+export declare const findRoot: (from: string) => string;

package/dist/config.js

@@ -0,0 +1,99 @@
+// Project configuration. `valance.json` is the project's (what it is called); `valance.web.json` is the web target's (where it is served). Nothing else is configurable, on purpose: a setting
+// is added when something needs it. Unknown keys are errors with the line, because a misspelt key that is ignored is a setting the author thinks they have. The JSON Schemas in
+// `schemas/` describe the same files for editors; this is the check the tools make.
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AppError, diagnostic, lineOf } from "./diagnostics.js";
+export const PROJECT_FILE = "valance.json";
+export const WEB_FILE = "valance.web.json";
+/** The only version of both files there is. */
+export const CONFIG_VERSION = 1;
+const read = (root, file) => {
+    const path = join(root, file);
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    const text = readFileSync(path, "utf8");
+    try {
+        return { text, value: JSON.parse(text) };
+    }
+    catch (error) {
+        throw new AppError([diagnostic(file, 1, "config-syntax", `not valid JSON: ${error instanceof Error ? error.message : String(error)}`)]);
+    }
+};
+const check = (file, text, value, keys, required) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return [diagnostic(file, 1, "config-shape", "must be a JSON object")];
+    }
+    const found = [];
+    const record = value;
+    for (const key of required) {
+        if (!(key in record)) {
+            found.push(diagnostic(file, 1, "config-missing", `"${key}" is required`));
+        }
+    }
+    for (const [key, given] of Object.entries(record)) {
+        const rule = keys[key];
+        if (rule === undefined) {
+            found.push(diagnostic(file, lineOf(text, `"${key}"`), "config-unknown", `unknown setting "${key}" (known: ${Object.keys(keys).join(", ")})`));
+            continue;
+        }
+        const problem = rule(given);
+        if (problem !== undefined) {
+            found.push(diagnostic(file, lineOf(text, `"${key}"`), "config-value", `"${key}" ${problem}`));
+        }
+    }
+    return found;
+};
+const text = (value) => (typeof value === "string" && value.trim() !== "" ? undefined : "must be a non-empty string");
+const version = (value) => (value === CONFIG_VERSION ? undefined : `must be ${CONFIG_VERSION} (the only version there is)`);
+const schema = (value) => (typeof value === "string" ? undefined : "must be a string");
+const base = (value) => typeof value === "string" && /^\/([\w.~-]+\/)*$/.test(value) ? undefined : 'must start and end with "/" (for example "/" or "/docs/")';
+const url = (value) => {
+    if (typeof value !== "string") {
+        return "must be a string";
+    }
+    try {
+        return new URL(value).protocol.startsWith("http") && !value.endsWith("/") ? undefined : 'must be an http(s) address without a trailing "/"';
+    }
+    catch {
+        return "must be an absolute address such as https://example.com";
+    }
+};
+/** Reads and validates the project's configuration. Every problem in both files is reported together. */
+export const loadConfig = (root) => {
+    const project = read(root, PROJECT_FILE);
+    if (project === undefined) {
+        throw new AppError([diagnostic(PROJECT_FILE, 0, "config-missing", `there is no ${PROJECT_FILE} in ${root}`)]);
+    }
+    const web = read(root, WEB_FILE);
+    const problems = [
+        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text }, ["name"]),
+        ...(web === undefined ? [] : check(WEB_FILE, web.text, web.value, { $schema: schema, version, base, url }, [])),
+    ];
+    if (problems.length > 0) {
+        throw new AppError(problems);
+    }
+    const given = (web?.value ?? {});
+    return { name: project.value.name, web: { base: given.base ?? "/", url: given.url ?? "" } };
+};
+export const siteInfo = (config) => ({ name: config.name, base: config.web.base, url: config.web.url });
+/**
+ * The nearest directory at or above `from` that holds a `valance.json`, as its real path. The bundler names a file by its real path, so a project reached through a symlink, or by a short
+ * Windows name (`RUNNER~1`), must be called the same thing here or a file is not the file the bundler means.
+ */
+export const findRoot = (from) => {
+    let at = from;
+    for (;;) {
+        if (existsSync(join(at, PROJECT_FILE))) {
+            return realpathSync.native(at);
+        }
+        const parent = dirname(at);
+        if (parent === at) {
+            throw new AppError([
+                diagnostic(PROJECT_FILE, 0, "no-project", `no ${PROJECT_FILE} in ${from} or any directory above it. Run this from your project, or create one with {"name": "…"}`),
+            ]);
+        }
+        at = parent;
+    }
+};

package/dist/content.d.ts

@@ -0,0 +1,12 @@
+import type { Config } from "./config.js";
+import type { Content } from "@valancex/common/internal";
+export declare const CONTENT_DIR = "content";
+export declare const PUBLIC_DIR = "public";
+/** `guide/getting-started.md` → `/guide/getting-started`; `index.md` → `/`; `guide/index.md` → `/guide`. */
+export declare const pathOfFile: (relative: string) => string;
+/** An address under the site's base: `/guide/x#y` with base `/docs/` is `/docs/guide/x#y`. */
+export declare const underBase: (base: string, address: string) => string;
+export declare const publicFiles: (root: string) => ReadonlySet<string>;
+/** Reads `content/` under `root`. Every mistake in every file is reported together, not the first only. */
+export declare const readContent: (root: string, config: Config) => Content;
+export declare const sectionTitle: (value: string) => string;

package/dist/content.js

@@ -0,0 +1,193 @@
+// Build time, in Node: `content/` → the content model. One Markdown file is one page; its path is its address. This is the whole of the content pipeline for an ordinary application:
+// discovery, front matter, Markdown, navigation order, and a check of every link and image against the pages and `public/` that exist.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, posix } from "node:path";
+import { AppError, diagnostic } from "./diagnostics.js";
+import { parseMarkdown, plain } from "./markdown.js";
+export const CONTENT_DIR = "content";
+export const PUBLIC_DIR = "public";
+const FRONT_KEYS = ["title", "description", "order"];
+const frontMatter = (source, file, problems) => {
+    const lines = source.split("\n");
+    if (lines[0]?.trim() !== "---") {
+        return { values: {}, lines: 0, body: source };
+    }
+    const end = lines.findIndex((line, at) => at > 0 && line.trim() === "---");
+    if (end < 0) {
+        problems.push(diagnostic(file, 1, "front-unclosed", 'the front matter starts with "---" and is never closed'));
+        return { values: {}, lines: 0, body: source };
+    }
+    const values = {};
+    lines.slice(1, end).forEach((line, at) => {
+        if (line.trim() === "" || line.trim().startsWith("#")) {
+            return;
+        }
+        const found = /^([A-Za-z][\w-]*):\s*(.*?)\s*$/.exec(line);
+        if (found === null) {
+            problems.push(diagnostic(file, at + 2, "front-syntax", `expected "key: value", found "${line.trim()}"`));
+            return;
+        }
+        if (!FRONT_KEYS.includes(found[1])) {
+            problems.push(diagnostic(file, at + 2, "front-unknown", `unknown front matter key "${found[1]}" (known: ${FRONT_KEYS.join(", ")})`));
+            return;
+        }
+        values[found[1]] = found[2].replace(/^(["'])(.*)\1$/, "$2");
+    });
+    return { values, lines: end + 1, body: lines.slice(end + 1).join("\n") };
+};
+const filesUnder = (dir, prefix = "") => !existsSync(dir)
+    ? []
+    : readdirSync(dir)
+        .sort()
+        .flatMap((name) => (statSync(join(dir, name)).isDirectory() ? filesUnder(join(dir, name), `${prefix}${name}/`) : [`${prefix}${name}`]));
+/** `guide/getting-started.md` → `/guide/getting-started`; `index.md` → `/`; `guide/index.md` → `/guide`. */
+export const pathOfFile = (relative) => {
+    const without = relative.replace(/\.md$/, "");
+    const path = `/${without}`.replace(/\/index$/, "");
+    return path === "" ? "/" : path;
+};
+const titleCase = (value) => value.replace(/[-_]+/g, " ").replace(/^./, (first) => first.toUpperCase());
+/** `/a/b#x` → `["/a/b", "x"]`; a trailing slash is not part of the path. */
+const splitAddress = (href) => {
+    const hash = href.indexOf("#");
+    const path = (hash < 0 ? href : href.slice(0, hash)).replace(/(.)\/$/, "$1");
+    return [path, hash < 0 ? "" : href.slice(hash + 1)];
+};
+/** An address under the site's base: `/guide/x#y` with base `/docs/` is `/docs/guide/x#y`. */
+export const underBase = (base, address) => `${base}${address.replace(/^\//, "")}`;
+export const publicFiles = (root) => new Set(filesUnder(join(root, PUBLIC_DIR)).map((file) => `/${file}`));
+/** Reads `content/` under `root`. Every mistake in every file is reported together, not the first only. */
+export const readContent = (root, config) => {
+    const problems = [];
+    const dir = join(root, CONTENT_DIR);
+    if (!existsSync(dir)) {
+        throw new AppError([diagnostic(CONTENT_DIR, 0, "content-missing", `there is no ${CONTENT_DIR}/ directory: each Markdown file in it becomes a page`)]);
+    }
+    const base = config.web.base;
+    const assets = publicFiles(root);
+    const raw = new Map();
+    let notFound;
+    for (const relative of filesUnder(dir)) {
+        const file = `${CONTENT_DIR}/${relative}`;
+        if (!relative.endsWith(".md")) {
+            problems.push(diagnostic(file, 0, "content-file", "only .md files belong in content/; put other files in public/"));
+            continue;
+        }
+        if (!/^[\w.\-/]+$/.test(relative)) {
+            problems.push(diagnostic(file, 0, "content-name", "a file name becomes an address: use letters, digits, - _ and ."));
+            continue;
+        }
+        const here = [];
+        const front = frontMatter(readFileSync(join(dir, relative), "utf8"), file, here);
+        let parsed;
+        try {
+            parsed = parseMarkdown(front.body, file, front.lines);
+        }
+        catch (error) {
+            if (error instanceof AppError) {
+                here.push(...error.diagnostics);
+            }
+            else {
+                throw error;
+            }
+        }
+        problems.push(...here);
+        if (parsed === undefined || here.length > 0) {
+            continue;
+        }
+        const heading = parsed.blocks.find((block) => block.kind === "heading" && block.level === 1);
+        const title = front.values["title"] ?? (heading === undefined ? "" : plain(heading.spans));
+        const order = front.values["order"];
+        if (title === "") {
+            problems.push(diagnostic(file, 1, "page-title", 'a page needs a title: add "title: …" to its front matter, or start it with a # heading'));
+            continue;
+        }
+        if (order !== undefined && !/^-?\d+$/.test(order)) {
+            problems.push(diagnostic(file, 1, "front-order", `"order" must be a whole number, found "${order}"`));
+            continue;
+        }
+        const path = pathOfFile(relative);
+        const entry = {
+            page: {
+                path,
+                file,
+                title,
+                description: front.values["description"] ?? "",
+                order: order === undefined ? 1000 : Number(order),
+                section: relative.includes("/") ? relative.split("/")[0] : "",
+                blocks: parsed.blocks,
+                outline: parsed.outline,
+            },
+            links: parsed.links,
+            anchors: parsed.anchors,
+            front,
+        };
+        if (path === "/404") {
+            notFound = entry;
+            continue;
+        }
+        if (raw.has(path)) {
+            problems.push(diagnostic(file, 0, "content-duplicate", `${path} is also the address of ${raw.get(path).page.file}`));
+            continue;
+        }
+        raw.set(path, entry);
+    }
+    if (!raw.has("/") && problems.length === 0) {
+        problems.push(diagnostic(CONTENT_DIR, 0, "content-home", "there is no content/index.md: it is the page at the site's address"));
+    }
+    const resolve = (entry, link) => {
+        const from = entry.page.file;
+        const href = link.href;
+        const bad = (code, message) => {
+            problems.push(diagnostic(from, link.line, code, message));
+            return href;
+        };
+        if (/^[a-z][a-z0-9+.-]*:/i.test(href)) {
+            return /^(https?:|mailto:)/i.test(href) ? href : bad("link-scheme", `"${href}" is not an address a page may link to (http, https and mailto are)`);
+        }
+        if (link.image) {
+            if (!href.startsWith("/")) {
+                return bad("image-path", `an image address starts with "/" and names a file in ${PUBLIC_DIR}/ (found "${href}")`);
+            }
+            return assets.has(href) ? underBase(base, href) : bad("image-missing", `${PUBLIC_DIR}${href} does not exist`);
+        }
+        // A relative address is relative to the file it is written in, and names another .md file.
+        const absolute = href.startsWith("#") || href.startsWith("/")
+            ? href
+            : `${pathOfFile(posix.join(posix.dirname(from.slice(CONTENT_DIR.length + 1)), href.replace(/#.*$/, "")))}${href.includes("#") ? href.slice(href.indexOf("#")) : ""}`;
+        const [target, fragment] = absolute.startsWith("#") ? [entry.page.path, absolute.slice(1)] : splitAddress(absolute);
+        const page = target === entry.page.path ? entry : raw.get(target);
+        if (page === undefined) {
+            return assets.has(target) && fragment === "" ? underBase(base, target) : bad("link-broken", `${href} leads to no page (and no file in ${PUBLIC_DIR}/)`);
+        }
+        if (fragment !== "" && !page.anchors.has(fragment)) {
+            return bad("link-fragment", `${page.page.file} has no heading with the address #${fragment} (it has ${[...page.anchors].map((anchor) => `#${anchor}`).join(", ") || "none"})`);
+        }
+        return underBase(base, target) + (fragment === "" ? "" : `#${fragment}`);
+    };
+    // The parser recorded the links in document order, and a page's blocks hold them in that same order.
+    const rewrite = (entry) => {
+        const resolved = entry.links.map((link) => resolve(entry, link));
+        let n = 0;
+        const take = () => resolved[n++];
+        const spansOf = (spans) => spans.map((span) => (span.kind === "link" ? { ...span, href: take() } : span));
+        const blocks = entry.page.blocks.map((block) => ({
+            ...block,
+            ...(block.kind === "image" ? { src: take() } : {}),
+            spans: spansOf(block.spans),
+            items: block.items.map((item) => ({ ...item, spans: spansOf(item.spans) })),
+        }));
+        if (n !== resolved.length) {
+            throw new Error(`internal: ${entry.page.file} has ${resolved.length} links and the model holds ${n}`);
+        }
+        return { ...entry.page, blocks };
+    };
+    const pages = [...raw.values()].map(rewrite);
+    const fallback = notFound === undefined ? undefined : rewrite(notFound);
+    if (problems.length > 0) {
+        throw new AppError(problems);
+    }
+    const ordered = [...pages].sort((a, b) => (a.section === "" ? 0 : 1) - (b.section === "" ? 0 : 1) || a.section.localeCompare(b.section) || a.order - b.order || a.path.localeCompare(b.path));
+    return { site: { name: config.name, base: config.web.base, url: config.web.url }, pages: ordered, ...(fallback === undefined ? {} : { notFound: fallback }) };
+};
+export const sectionTitle = titleCase;

package/dist/contract.d.ts

@@ -0,0 +1,31 @@
+import type { MeshType } from "@valancex/valance/web/build";
+import { Schema } from "effect";
+import type { Node } from "./tree.js";
+type SchemaOf = Schema.Schema<any, any, never>;
+/** The model's entry for a component: exactly the interface it declares. */
+export interface Entry {
+    readonly props: Readonly<Record<string, {
+        readonly type: MeshType;
+        readonly required: boolean;
+    }>>;
+    readonly events: Readonly<Record<string, {
+        readonly payload?: MeshType;
+    }>>;
+    readonly commands: Readonly<Record<string, never>>;
+    /** Every prop is a name the template reads: the same name and type, absent when the prop may be. */
+    readonly scope: Readonly<Record<string, MeshType>>;
+}
+/** A schema with no model type, said at the declaration. */
+export interface Problem {
+    readonly kind: "props" | "events";
+    readonly name: string;
+    readonly reason: string;
+}
+/** What a schema is in the model: put in a struct, so the rules are state's. A field that may be `undefined` comes back optional. */
+export declare const typeOf: (schema: SchemaOf) => MeshType;
+/** The entry a declared interface makes, and every schema in it that has no model type. */
+export declare const entryOf: (declared: NonNullable<Node["interface"]>) => {
+    readonly entry: Entry;
+    readonly problems: ReadonlyArray<Problem>;
+};
+export {};

package/dist/contract.js

@@ -0,0 +1,45 @@
+import { manifest } from "@valancex/valance/web/build";
+import { Schema } from "effect";
+/** What a schema is in the model: put in a struct, so the rules are state's. A field that may be `undefined` comes back optional. */
+export const typeOf = (schema) => {
+    const derived = manifest({ primitives: {}, scopes: { contract: Schema.Struct({ value: schema }) }, commands: () => ({}) });
+    return derived.components["contract"].scope["value"];
+};
+const reasonOf = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.replace(/^[\w.]+: /, "");
+};
+/** No payload: the schema of nothing. */
+const isEmpty = (schema) => ["VoidKeyword", "UndefinedKeyword"].includes(schema.ast._tag);
+/** The entry a declared interface makes, and every schema in it that has no model type. */
+export const entryOf = (declared) => {
+    const problems = [];
+    const props = {};
+    const scope = {};
+    const events = {};
+    for (const [name, schema] of Object.entries(declared.props)) {
+        try {
+            const type = typeOf(schema);
+            const optional = type.kind === "optional";
+            props[name] = { type: optional ? type.type : type, required: !optional };
+            scope[name] = type;
+        }
+        catch (error) {
+            problems.push({ kind: "props", name, reason: reasonOf(error) });
+        }
+    }
+    for (const [name, schema] of Object.entries(declared.events)) {
+        try {
+            if (isEmpty(schema)) {
+                events[name] = {};
+                continue;
+            }
+            const type = typeOf(schema);
+            events[name] = { payload: type.kind === "optional" ? type.type : type };
+        }
+        catch (error) {
+            problems.push({ kind: "events", name, reason: reasonOf(error) });
+        }
+    }
+    return { entry: { props, events, commands: {}, scope }, problems };
+};

package/dist/delegate.d.ts

@@ -0,0 +1,2 @@
+/** The `dist/cli.js` of the `@valancex/cli` installed in the project that contains `cwd`, if it is not this package. */
+export declare const localCli: (cwd: string) => string | undefined;

package/dist/delegate.js

@@ -0,0 +1,23 @@
+// The command on your PATH is not the version your project uses. Like `ng`, a global `vlx` hands `dev`, `build` and `check` to the `@valancex/cli` installed in the project (the one its
+// package.json names, with the MESH compiler, runtime and VALANCE that go with it), so a project builds the same wherever it is run from. `init` and `--help` need no project and are the
+// global command's own. With no local install (or the local one is this one) it runs as it is.
+import { existsSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findRoot } from "./config.js";
+const SELF = realpathSync(fileURLToPath(new URL("../", import.meta.url)));
+/** The `dist/cli.js` of the `@valancex/cli` installed in the project that contains `cwd`, if it is not this package. */
+export const localCli = (cwd) => {
+    try {
+        const root = findRoot(cwd);
+        const manifest = createRequire(join(root, "package.json")).resolve("@valancex/cli/package.json");
+        const dir = realpathSync(manifest.replace(/[\\/]package\.json$/, ""));
+        const entry = join(dir, "dist", "cli.js");
+        return dir !== SELF && existsSync(entry) ? entry : undefined;
+    }
+    catch {
+        // No project here, or nothing installed in it: the command runs as it is.
+        return undefined;
+    }
+};