@valancex/cli 0.13.0 → 0.15.0

package/dist/cli.js

@@ -4,11 +4,13 @@
 //   vlx dev [--port N] [--host H]   serve the project and rebuild it as it changes
 //   vlx build                       write the site to dist/web/
 //   vlx check [--json]              find mistakes in authored files without building
+//   vlx theme check [--json]        the theme: its tokens, recipes, contrast and what each target applies
 //   vlx generate page|component <name>   add a page, or a component registered in src/main.ts (alias: g)
 //   vlx sync                        bring .valance/ (generated types, manifest, entries) up to date; runs by itself after install and generate
 //   vlx help [command]              what a command does
 //
 // In a terminal, `init`, `dev`, `build` and `check` draw an interface (Ink, `ui/`). Anywhere else (a pipe, CI, `--json`, `--plain`) they print the plain text they always have.
+import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { INIT_HELP, parseInit } from "./args.js";
@@ -16,19 +18,26 @@ import { build } from "./build.js";
 import { packageDesktop } from "./package.js";
 import { generateComponent, generatePage, generateTarget, GenerateError, KINDS } from "./add.js";
 import { check } from "./check.js";
+import { themeReport } from "./theme.js";
 import { findRoot } from "./config.js";
 import { localCli } from "./delegate.js";
 import { dev } from "./dev.js";
+import { defaultRecording, replayFile } from "./replay.js";
 import { AppError, format } from "./diagnostics.js";
-import { detectPackageManager, directoryFor, directoryProblem, execute, nameProblem, runCommand, titleOf } from "./init.js";
+import { detectPackageManager, directoryFor, directoryProblem, execute, install as installDependencies, nameProblem, PACKAGE_MANAGERS, runCommand, titleOf } from "./init.js";
+import { buildLibrary, checkLibrary, scaffoldLibrary } from "./library.js";
 import { DEFAULT_TARGETS, TARGETS } from "./targets.js";
 import { canAsk, canDraw } from "./tty.js";
 const HELP = `vlx <command>
 
   init [name] [--web]              make a new application
-  dev [--port N] [--host H]        serve it and rebuild as it changes
+  dev [--port N] [--host H]        serve it and rebuild as it changes (--record [file]: write a session log)
+  replay <log> [--route R] [--allow-user-data]  play a session log against this project and find where it differs
   build                            write the site to dist/web/
   check [--json]                   find mistakes in your files without building
+  theme check [--json]             check the theme: tokens, recipes, contrast, and what each target applies
+  init library <name>              make a component library: a workspace with the package and a playground
+  library build|check              build a library's dist/ (JavaScript, declarations, templates, styles); check the package
   generate page|component <name>  add a page, or a component (alias: g)
   generate target web|desktop      add a target to the project
   package --desktop                the desktop target as one executable beside its window (unsigned)
@@ -51,14 +60,40 @@ const GENERATE_HELP = `vlx generate <page|component|target> <name>   (alias: vlx
 
 Nothing is overwritten: a name that is taken is refused.
 `;
+const LIBRARY_HELP = `vlx library <build|check> [--json] [--app <dir>]
+
+Run in a library's package directory (the one with the "valance" export condition; \`vlx init library\` makes one).
+
+  vlx library build    dist/: the TypeScript compiled to JavaScript with declarations (the components' contracts are the
+                       types component() gives them), and every .mprx and .css under src/ copied beside it. Templates ship
+                       as source: the application's build compiles them. Needs typescript installed in the library.
+  vlx library check    the package as a consumer's build needs it: the "valance" condition on exports["."] and the file it
+                       names, no other entry a tool without the condition would load, a peer dependency on
+                       @valancex/common, stylesheets that exist and "sideEffects" that keeps them; then the playground
+                       (--app <dir>, default ../../playground, ./playground or ../playground), an application that depends
+                       on this package: it must build every target the package declares and write every template the
+                       package ships, and its own \`vlx check\` problems are reported with the library's.
+
+Exits 0 when there is nothing to say, 1 when there is. --json prints the diagnostics.
+`;
+const INIT_LIBRARY_HELP = `vlx init library <name> [--pm <npm|pnpm|yarn|bun>] [--no-install] [--cli <spec>]
+
+Make a component library: a workspace with packages/<name> (a sample component, written with the portable core, its contract,
+a tsconfig and a package.json that is marked as a library) and playground/ (an application that depends on it and builds
+the web and the desktop). <name> is the package name (acme-ui, @acme/ui); the directory is the name's last part.
+Then: cd <dir>, install, \`vlx library build\` in packages/<name>, \`vlx library check\`, and the playground's \`vlx dev\`.
+`;
 const COMMAND_HELP = {
-    init: INIT_HELP,
+    init: `${INIT_HELP}\n${INIT_LIBRARY_HELP}`,
+    library: LIBRARY_HELP,
     generate: GENERATE_HELP,
     g: GENERATE_HELP,
-    dev: "vlx dev [--web|--desktop] [--port N] [--host H]\n\nServe the project (the web is served, a desktop project opens its window; a project of more than one target does both, or the one named) and rebuild it as files change. A mistake leaves the last good build serving and shows in the terminal and in the page.\n",
+    replay: "vlx replay <log> [--route changes,update,render] [--json] [--allow-user-data]\n\nPlay a session log (written by vlx dev --record, or one of MESH's conformance logs) against this project's templates by the three routes of the equivalence law, and find the first line where one differs from the log: a tree, an event's outcome, a program or manifest that is not the one recorded. It runs no command and reads no clock. Exits 0 when every route gave what the log recorded, 1 when one did not, 2 when the log cannot be read. A log that holds user data (every recording does: its header says containsUserData) is refused unless you pass --allow-user-data: a divergence prints what was typed and shown.\n",
+    dev: "vlx dev [--web|--desktop] [--port N] [--host H] [--record [file]]\n\nServe the project (the web is served, a desktop project opens its window; a project of more than one target does both, or the one named) and rebuild it as files change. A mistake leaves the last good build serving and shows in the terminal and in the page. --record writes the web page's session as a log (default .valance/sessions/<time>.jsonl) for vlx replay: development only, never uploaded, and it holds what the person typed.\n",
     build: "vlx build [--web] [--desktop]\n\nBuild every target the project has (or the ones named). The web: the site, in dist/web/; any host that serves files can serve it. The desktop: the engine, in dist/desktop/.\n",
     sync: "vlx sync\n\nBring .valance/ up to date: the generated types for your templates (so your editor and tsc agree with them), the manifest and the entries. You rarely run it: a new project does it after install (the `prepare` script), `vlx generate` does it after it writes, and dev, build and check do it as they run. It never fails: mistakes in your files are reported by vlx check.\n",
     package: "vlx package --desktop [--platform linux-x64|win32-x64] [--window <path>] [--node <path>] [--archive]\n\nBuild the desktop target and package it: the engine as one executable (Node's single executable application, with the MESH runtime inside) beside the Desktop PORT's window program, in dist/package/<platform>/. --window is the window program for that platform (default: VLX_WINDOW, else vlx-window on the PATH; build it from the PORT repository). For another platform, --node is a node binary of this version for it. --archive also writes the package as one file, a .tar.gz (Linux) or a .zip (Windows), with its SHA-256 beside it. The result is unsigned.\n",
+    theme: "vlx theme check [--json]\n\nCheck the theme: the project's `theme/theme.json` (its tokens by mode, in the Design Tokens format, and its recipes), or the default theme when it has none. Reports a token that does not resolve, a recipe that names a part, state, variant, property or token that does not exist, a removed focus ring, the contrast of every pair the theme declares (WCAG 2.2), and what the web and the desktop apply of it. --json prints the diagnostics, the contrast and the coverage.\n",
     check: "vlx check [--json]\n\nFind mistakes in your files without building. --json prints them as { file, line, column, code, message } for editors and CI.\n",
 };
 /** Refreshes `.valance/` and says so in a line. Best effort: a mistake in the project is `check`'s to report, and a project with no `valance.json` (the install ran before init finished) is left alone. */
@@ -79,6 +114,16 @@ const option = (args, name) => {
     const at = args.indexOf(name);
     return at < 0 ? undefined : args[at + 1];
 };
+/** `--record` alone, `--record file` or `--record=file`: the file, `""` for the default, nothing when it is not there. A word after it that is another flag is not its file. */
+const recordOption = (args) => {
+    const joined = args.find((each) => each.startsWith("--record="));
+    if (joined !== undefined) {
+        return joined.slice("--record=".length);
+    }
+    const at = args.indexOf("--record");
+    const next = at < 0 ? undefined : args[at + 1];
+    return at < 0 ? undefined : next === undefined || next.startsWith("-") ? "" : next;
+};
 const version = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const runInit = async (args, cwd) => {
     if (args.name !== undefined) {
@@ -124,6 +169,34 @@ const runInit = async (args, cwd) => {
     console.log(`vlx init: next: cd ${answers.dir}${outcome.installed ? "" : ` && ${answers.packageManager} install`} && ${runCommand(answers.packageManager)} dev`);
     return 0;
 };
+const runInitLibrary = async (args, cwd) => {
+    const positional = args.filter((each, index) => !each.startsWith("-") && !["--pm", "--cli"].includes(args[index - 1] ?? ""));
+    const name = positional[0];
+    const manager = option(args, "--pm");
+    if (name === undefined || !/^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(name)) {
+        console.error(`vlx init library: name the package: vlx init library acme-ui (lowercase letters, digits, - . _; or @scope/name)\n\n${INIT_LIBRARY_HELP}`);
+        return 2;
+    }
+    if (manager !== undefined && !PACKAGE_MANAGERS.includes(manager)) {
+        console.error(`vlx init library: --pm is one of ${PACKAGE_MANAGERS.join(", ")}`);
+        return 2;
+    }
+    const dir = directoryFor(name.replace(/^@[^/]+\//, ""), cwd);
+    const problem = directoryProblem(dir);
+    if (problem !== undefined) {
+        console.error(`vlx init library: ${problem}`);
+        return 1;
+    }
+    const answers = { name, dir, packageManager: manager ?? detectPackageManager(), ...(option(args, "--cli") === undefined ? {} : { cli: option(args, "--cli") }) };
+    const files = scaffoldLibrary(answers);
+    console.log(`vlx init library: created ${name} in ${dir} (${files.length} files)`);
+    if (!args.includes("--no-install")) {
+        const ran = await installDependencies(answers);
+        console.log(ran.ok ? "vlx init library: installed" : `vlx init library: the dependencies were not installed (${answers.packageManager} install failed); run it yourself in ${dir}`);
+    }
+    console.log(`vlx init library: next: cd ${dir}/packages/${name.replace(/^@[^/]+\//, "")} && vlx library build && vlx library check`);
+    return 0;
+};
 export const main = async (args, cwd = process.cwd()) => {
     const [command, ...rest] = args;
     // `vlx dev --help` says what dev does and runs nothing (`init` and `generate` answer for themselves below).
@@ -137,7 +210,16 @@ export const main = async (args, cwd = process.cwd()) => {
         return 0;
     }
     // A global `vlx` runs the project's own (see `delegate.ts`).
-    if (command === "dev" || command === "build" || command === "package" || command === "check" || command === "sync" || command === "generate" || command === "g") {
+    if (command === "dev" ||
+        command === "replay" ||
+        command === "build" ||
+        command === "package" ||
+        command === "check" ||
+        command === "theme" ||
+        command === "library" ||
+        command === "sync" ||
+        command === "generate" ||
+        command === "g") {
         const local = localCli(cwd);
         if (local !== undefined) {
             const theirs = (await import(pathToFileURL(local).href));
@@ -152,6 +234,9 @@ export const main = async (args, cwd = process.cwd()) => {
                     console.log(INIT_HELP);
                     return 0;
                 }
+                if (rest[0] === "library") {
+                    return await runInitLibrary(rest.slice(1), cwd);
+                }
                 const parsed = parseInit(rest);
                 if (typeof parsed === "string") {
                     console.error(`vlx init: ${parsed}\n\n${INIT_HELP}`);
@@ -168,9 +253,12 @@ export const main = async (args, cwd = process.cwd()) => {
                     return 2;
                 }
                 const target = picked[0];
+                const asked = recordOption(rest);
+                const record = asked === undefined ? undefined : asked === "" ? defaultRecording(findRoot(cwd)) : resolve(cwd, asked);
                 if (draws) {
                     const { drawDev } = await import("./ui/run.js");
                     await drawDev(findRoot(cwd), {
+                        ...(record === undefined ? {} : { record }),
                         ...(target === undefined ? {} : { target }),
                         ...(port === undefined ? {} : { port: Number(port) }),
                         ...(host === undefined ? {} : { host }),
@@ -178,6 +266,7 @@ export const main = async (args, cwd = process.cwd()) => {
                     return 0;
                 }
                 const running = await dev(findRoot(cwd), {
+                    ...(record === undefined ? {} : { record }),
                     ...(target === undefined ? {} : { target }),
                     ...(port === undefined ? {} : { port: Number(port) }),
                     ...(host === undefined ? {} : { host }),
@@ -192,6 +281,21 @@ export const main = async (args, cwd = process.cwd()) => {
                 await running.close();
                 return 0;
             }
+            case "replay": {
+                const file = rest.find((each, index) => !each.startsWith("-") && rest[index - 1] !== "--route");
+                if (file === undefined) {
+                    console.error("vlx replay: name a log: vlx replay <log> [--route changes,update,render] [--json]");
+                    return 2;
+                }
+                const routes = option(rest, "--route");
+                const replayed = await replayFile(findRoot(cwd), resolve(cwd, file), {
+                    ...(routes === undefined ? {} : { routes: routes.split(",") }),
+                    json: rest.includes("--json"),
+                    allowUserData: rest.includes("--allow-user-data"),
+                });
+                (replayed.code === 0 ? console.log : console.error)(replayed.output);
+                return replayed.code;
+            }
             case "build": {
                 if (draws) {
                     const { drawBuild } = await import("./ui/run.js");
@@ -200,7 +304,7 @@ export const main = async (args, cwd = process.cwd()) => {
                 }
                 const started = Date.now();
                 const flagged = targetFlags(rest);
-                const built = await build(findRoot(cwd), flagged.length === 0 ? {} : { targets: flagged });
+                const built = await build(findRoot(cwd), { ...(flagged.length === 0 ? {} : { targets: flagged }), onReport: (report) => report.forEach((line) => console.log(line)) });
                 console.log(`vlx build: ${built.pages.length} pages, ${built.files.length} files → ${built.dir} (${((Date.now() - started) / 1000).toFixed(1)}s)`);
                 return 0;
             }
@@ -242,6 +346,60 @@ export const main = async (args, cwd = process.cwd()) => {
                 }
                 return result.diagnostics.length === 0 ? 0 : 1;
             }
+            case "library": {
+                const sub = rest[0];
+                if (sub !== "build" && sub !== "check") {
+                    console.error("vlx library: say what: vlx library build | vlx library check [--json] [--app <dir>]");
+                    return 2;
+                }
+                const dir = cwd;
+                const json = rest.includes("--json");
+                const given = option(rest, "--app");
+                const report = (diagnostics) => {
+                    if (json) {
+                        console.log(JSON.stringify({ diagnostics }, null, 2));
+                    }
+                    else {
+                        diagnostics.forEach((each) => console.error(`${each.file}${each.line > 0 ? `:${each.line}` : ""} ${each.code}: ${each.message}`));
+                        console.log(diagnostics.length === 0 ? `vlx library ${sub}: no problems` : `vlx library ${sub}: ${diagnostics.length} problem${diagnostics.length === 1 ? "" : "s"}`);
+                    }
+                    return diagnostics.length === 0 ? 0 : 1;
+                };
+                if (sub === "build") {
+                    const built = buildLibrary(dir);
+                    if (!json && built.diagnostics.length === 0) {
+                        console.log(`vlx library build: dist/ written; ${built.copied.length} template and stylesheet file${built.copied.length === 1 ? "" : "s"} copied as source`);
+                    }
+                    return report(built.diagnostics);
+                }
+                return report(await checkLibrary(dir, given === undefined ? {} : { app: resolve(cwd, given) }));
+            }
+            case "theme": {
+                if (rest[0] !== "check") {
+                    console.error("vlx theme: say what: vlx theme check [--json]");
+                    return 2;
+                }
+                const report = themeReport(findRoot(cwd));
+                if (rest.includes("--json")) {
+                    console.log(JSON.stringify({ theme: report.name, custom: report.custom, diagnostics: report.diagnostics, contrast: report.contrast, coverage: report.coverage }, null, 2));
+                    return report.diagnostics.length === 0 ? 0 : 1;
+                }
+                console.log(`vlx theme check: ${report.custom ? "the project's theme" : "the default theme"} "${report.name}" (modes: ${report.modes.join(", ")})`);
+                for (const each of report.contrast) {
+                    console.log(`  contrast  ${each.mode.padEnd(9)} ${each.text} on ${each.on}  ${each.ratio.toFixed(2)}:1  (min ${each.min})  ${each.passes ? "ok" : "BELOW"}`);
+                }
+                for (const each of report.coverage) {
+                    console.log(`  ${each.target}: ${each.styled.length} of ${each.styled.length + each.unstyled.length} primitives of the portable core styled${each.unstyled.length === 0 ? "" : ` (not styled: ${each.unstyled.join(", ")})`}`);
+                    for (const note of each.notApplied) {
+                        console.log(`    not applied: ${note.primitive} ${note.kind} ${note.name} (${note.support})`);
+                    }
+                }
+                report.diagnostics.forEach((each) => {
+                    console.error(format(each));
+                });
+                console.log(report.diagnostics.length === 0 ? "vlx theme check: no problems" : `vlx theme check: ${report.diagnostics.length} problem${report.diagnostics.length === 1 ? "" : "s"}`);
+                return report.diagnostics.length === 0 ? 0 : 1;
+            }
             case "sync": {
                 const synced = await sync(cwd);
                 console.log(synced);

package/dist/compile.d.ts

@@ -17,8 +17,16 @@ interface Template {
     readonly source: string;
     readonly builtIn: boolean;
 }
+/** A library component left out of a target's program because its library does not support the target (K5): the tag is reported at each use, once, where the application can act. */
+export interface Excluded {
+    readonly id: string;
+    readonly library: string;
+    readonly supports: ReadonlyArray<string>;
+}
 export interface Templates {
     readonly all: ReadonlyArray<Template>;
+    /** The library components this target leaves out, by tag. */
+    readonly excluded: ReadonlyMap<string, Excluded>;
     /** The declared tree, in `src/main.ts`'s own words. */
     readonly tree: ReadonlyArray<Node>;
 }

package/dist/compile.js

@@ -8,12 +8,14 @@ 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 { declarationsOf, declaredOf, linked, nameOf, treeOf } from "./tree.js";
 import { tagsOf } from "./outline.js";
 import { entryOf } from "./contract.js";
+import { idOf, libraryOf, librariesOf } from "./libraries.js";
 import { locateKey } from "./wiring.js";
 import { namesOf, webVocabulary, WHOLE } from "@valancex/common/internal";
-import { ENTRY_FILE } from "./project.js";
+import { checkReferences, checkTemplate } from "./rules.js";
+import { ENTRY_FILE, GENERATED_DIR } from "./project.js";
 export const SOURCE_DIR = "src";
 /** The component the page is drawn by. */
 export const ROOT = "layout";
@@ -47,7 +49,26 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     }
     const layout = author?.layout;
     const overrides = author?.override ?? [];
-    const declared = treeOf(layout, overrides, author?.components ?? []);
+    const { libraries } = librariesOf(root);
+    const resolved = author?.resolve ?? {};
+    const overridden = new Set(overrides.map((each) => nameOf(each.template.mprx)));
+    const excluded = new Map();
+    const idFor = (component) => idOf(libraries, root, component.template.mprx, nameOf(component.template.mprx));
+    // The components of this target's program. A library's component is left out when its library does not support this target (K5: one diagnostic at the use, not several inside the library), when the
+    // application's own template of that name replaces it (`override`), and when `resolve` chose another of that name (K14).
+    const components = (author?.components ?? []).filter((each) => {
+        const name = nameOf(each.template.mprx);
+        const library = libraryOf(libraries, root, each.template.mprx);
+        if (library === undefined) {
+            return true;
+        }
+        if (!library.targets.includes(vocabulary.target)) {
+            excluded.set(name, { id: idFor(each), library: library.name, supports: library.targets });
+            return false;
+        }
+        return !overridden.has(name) && (resolved[name] === undefined || resolved[name] === idFor(each));
+    });
+    const declared = treeOf(layout, overrides, 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. */
@@ -68,17 +89,46 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     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`);
+        if (!builtInNames.has(name) &&
+            name !== ROOT &&
+            !(author?.components ?? []).some((other) => nameOf(other.template.mprx) === name && libraryOf(libraries, root, other.template.mprx) !== undefined)) {
+            problem(at(each.template.mprx), "override-unknown", `<${name}> is not a built-in component and no library component in \`components\` has that name, so there is nothing to override; register it in \`components\` instead`);
+        }
+    }
+    for (const [tag, id] of Object.entries(resolved)) {
+        if (!(author?.components ?? []).some((each) => idFor(each) === id)) {
+            const named = (author?.components ?? []).filter((each) => nameOf(each.template.mprx) === tag).map(idFor);
+            problem({ file: ENTRY_FILE, line: 1, column: 1 }, "resolve-unknown", `\`resolve\` says <${tag}> is ${id}, but no component in \`components\` has that id${named.length === 0 ? ` (nothing named ${tag} is listed)` : ` (listed with that name: ${named.join(", ")})`}`);
+        }
+    }
+    // A name is one component. Two files of one name, from anywhere in the definition (two libraries', or a library's and the application's), are an error: the first listed must not win silently
+    // (decision K14). A component that is not listed in `override` and is named like a built-in is the same collision, with the built-in.
+    // A library's component is named by its qualified id (`acme-ui/disclosure`) in a diagnostic and in `resolve`; the application's own, by the bare name.
+    const listed = declaredOf(layout, overrides, components);
+    const firstOf = new Map();
+    const idOfFile = (file, name) => idOf(libraries, root, file, name);
+    for (const each of listed) {
+        const first = firstOf.get(each.name);
+        const id = idOfFile(each.file, each.name);
+        if (first === undefined) {
+            firstOf.set(each.name, { file: each.file, id });
+            if (each.role === "component" &&
+                builtInNames.has(each.name) &&
+                resolved[each.name] !== id &&
+                !listed.some((other) => other.role !== "component" && other.name === each.name)) {
+                problem(at(each.file), "template-builtin", `${id} is <${each.name}>, which is also a built-in component: list your own template of that name in \`override\` to replace the built-in, or choose this one with \`resolve: { ${each.name}: "${id}" }\``);
+            }
+        }
+        else if (first.file !== each.file) {
+            const libraryMade = id !== each.name || first.id !== each.name;
+            problem(at(each.file), "template-duplicate", libraryMade
+                ? `${id === each.name ? each.file : id} and ${first.id === each.name ? first.file : first.id} are both <${each.name}>: a component is named by its file, so the name must be unique; choose one with \`resolve: { ${each.name}: "${id === each.name ? first.id : id}" }\` in defineApp, or replace both with your own template of that name in \`override\``
+                : `${each.file} is also <${each.name}>, like ${first.file}: a component is named by its file, so the name must be unique; rename one of the files`);
         }
     }
     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 (namesOf(vocabulary).includes(node.name)) {
             problem(place, "template-primitive", `<${node.name}> is already a tag the framework draws as an element; name the file something else`);
             continue;
@@ -98,7 +148,7 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     const claimed = new Set(files.values());
     const whole = (author?.[WHOLE] ?? author);
     for (const parts of [whole, ...Object.values(whole?.targets ?? {})]) {
-        for (const node of treeOf(parts?.layout, parts?.override ?? [], parts?.components ?? [])) {
+        for (const node of declaredOf(parts?.layout, parts?.override ?? [], parts?.components ?? [])) {
             claimed.add(node.file);
         }
     }
@@ -113,7 +163,7 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     if (problems.length > 0) {
         throw new AppError(problems);
     }
-    return { all: [...found.values()], tree };
+    return { all: [...found.values()], tree, excluded };
 };
 /** 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) => {
@@ -143,8 +193,19 @@ export const manifestOf = (author, vocabulary = webVocabulary) => {
     if (!("tags" in vocabulary)) {
         return { ...derived, components: { ...vocabulary.components, ...derived.components } };
     }
-    // The props the vocabulary says a template may leave out.
+    // What the vocabulary declares of a tag's props and events (the specification's) settles what the table alone derived.
     const components = { ...derived.components };
+    for (const [tag, declared] of Object.entries(vocabulary.declared ?? {})) {
+        const entry = components[tag];
+        if (entry !== undefined) {
+            components[tag] = {
+                ...entry,
+                props: Object.fromEntries(Object.entries(entry.props).map(([name, prop]) => [name, declared.props[name] === undefined ? prop : { ...prop, ...declared.props[name] }])),
+                events: Object.fromEntries(Object.entries(entry.events).map(([name, event]) => [name, declared.events[name] === undefined ? event : { ...event, ...declared.events[name] }])),
+            };
+        }
+    }
+    // The props the vocabulary says a template may leave out.
     for (const [tag, names] of Object.entries(vocabulary.optional ?? {})) {
         const entry = components[tag];
         if (entry !== undefined) {
@@ -188,8 +249,10 @@ const modelOf = (root, author, tree, vocabulary) => {
         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));
+            const place = site?.member(each.kind === "unit" ? "props" : each.kind, each.name) ?? site?.call ?? site?.imported ?? { file: ENTRY_FILE, line: 1, column: 1 };
+            problems.push(diagnostic(place.file, place.line, "component-schema", each.message === undefined
+                ? `${node.name}'s ${each.kind === "props" ? "prop" : each.kind === "unit" ? "unit field or command" : "event"} "${each.name}" has no type the model can hold: ${each.reason}`
+                : `${node.name}: ${each.message}`, place.column));
         }
         entries[node.name] = entry;
     }
@@ -198,9 +261,35 @@ const modelOf = (root, author, tree, vocabulary) => {
     }
     return { ...derived, components: { ...derived.components, ...entries } };
 };
+/** The anchors of the content's headings: the ids the built-in views give them (the generated `content.json`, which the content stage wrote before this one). */
+const anchorsOf = (root) => {
+    try {
+        const content = JSON.parse(readFileSync(join(root, GENERATED_DIR, "content.json"), "utf8"));
+        return new Set((content.pages ?? []).flatMap((page) => (page.blocks ?? []).flatMap((block) => (block.anchor === undefined ? [] : [block.anchor]))));
+    }
+    catch {
+        return new Set();
+    }
+};
+/** A tag the web renamed (decision P7: `para` is `paragraph`): said where a template still writes the old one. */
+const renamedHint = (vocabulary, used, at) => {
+    // a prop the web renamed (decision I29: a popover's `kind` is `mode`): the diagnostic names the tag and the prop
+    const prop = /component "([^"]+)" has no prop "([^"]+)"/.exec(at.message ?? "");
+    const renamedProp = prop === null || !("tags" in vocabulary) ? undefined : vocabulary.renamedProps?.[prop[1]]?.[prop[2]];
+    if (renamedProp !== undefined) {
+        return ` (\`${prop[2]}\` on \`${prop[1]}\` is now \`${renamedProp}\`)`;
+    }
+    const renamed = "tags" in vocabulary ? vocabulary.renamed : undefined;
+    const line = used.find((template) => template.path === at.path)?.source.split("\n")[at.span.start.line - 1];
+    if (renamed === undefined || line === undefined) {
+        return "";
+    }
+    const tag = /<\/?([A-Za-z][\w-]*)/.exec(line.slice(Math.max(0, at.span.start.column - 2)))?.[1];
+    return tag !== undefined && Object.hasOwn(renamed, tag) ? ` (\`${tag}\` is now \`${renamed[tag]}\`)` : "";
+};
 /** Compiles the application's templates against a target's vocabulary (the web's by default). Fails with every diagnostic, each pointing into the file it is about. */
 export const compileViews = async (root, author, vocabulary = webVocabulary, views = BUILT_IN) => {
-    const { all, tree } = templatesOf(root, author, vocabulary, views);
+    const { all, tree, excluded } = templatesOf(root, author, vocabulary, views);
     const used = reachable(all);
     const model = modelOf(root, author, tree, vocabulary);
     if (!used.some((template) => template.component === ROOT)) {
@@ -215,12 +304,42 @@ export const compileViews = async (root, author, vocabulary = webVocabulary, vie
         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))),
+                .map((each) => {
+                // a library component this target leaves out (K5): one sentence at the use, in place of the compiler's "unknown component"
+                const left = each.code === "unknown-component" ? excluded.get(/component "([^"]+)"/.exec(each.message)?.[1] ?? "") : undefined;
+                return left === undefined
+                    ? each
+                    : {
+                        ...each,
+                        code: "unsupported-target",
+                        message: `<${each.message.match(/component "([^"]+)"/)[1]}> is ${left.id}, and ${left.library} supports ${left.supports.join(" and ")} only; this project builds for ${vocabulary.target}. Use a component that ${vocabulary.target} has, or build ${left.library} for ${vocabulary.target}`,
+                        suggestions: [],
+                    };
+            })
+                .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 ")}?)` : "") +
+                renamedHint(vocabulary, used, each), 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 rules = "tags" in vocabulary ? vocabulary.rules : undefined;
+    if (rules !== undefined) {
+        const texts = program.templates;
+        const known = new Set(namesOf(vocabulary));
+        const broken = used.flatMap((template, index) => checkTemplate(template.path, template.source, JSON.parse(texts[index] ?? "{}"), rules, known, tree.find((node) => node.name === template.component)?.interface?.name));
+        const compiled = used.map((template, index) => ({
+            file: template.path,
+            source: template.source,
+            template: JSON.parse(texts[index] ?? "{}"),
+            builtIn: template.builtIn,
+        }));
+        broken.push(...checkReferences(compiled, anchorsOf(root)));
+        if (broken.length > 0) {
+            throw new AppError(broken.map((each) => relocate(each, root)));
+        }
+    }
     const enriched = program.model;
     const manifestOfProgram = typeof enriched === "string" ? JSON.parse(enriched) : enriched;
     return {

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { Budget } from "./size.js";
 import type { SiteInfo } from "@valancex/common/internal";
 export declare const PROJECT_FILE = "valance.json";
 export declare const WEB_FILE = "valance.web.json";
@@ -23,6 +24,17 @@ export interface Config {
         readonly base: string;
         readonly proxy: string;
     };
+    /** The size budgets a production build is held to (Tier 2): the project's own, or none, in which case the framework's start-up budgets apply (W14). Never checked by `vlx dev`. */
+    readonly budgets: ReadonlyArray<Budget> | undefined;
+    /** What `vlx dev --record` leaves out of a session log (Tier 2; R9, R14): nothing, unless the project says. */
+    /** The theme package the project uses instead of the default theme (Tier 2; K12): an installed package whose `valance` field is `{ "kind": "theme" }`. Absent: the `theme/` directory, else the default. */
+    readonly theme: string | undefined;
+    readonly record: {
+        readonly redact: {
+            readonly scope: ReadonlyArray<ReadonlyArray<string>>;
+            readonly commands: ReadonlyArray<string>;
+        };
+    };
 }
 /** Reads and validates the project's configuration. Every problem in both files is reported together. */
 export declare const loadConfig: (root: string) => Config;

package/dist/config.js

@@ -3,6 +3,7 @@
 // `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 { budgetProblems } from "./size.js";
 import { AppError, diagnostic, lineOf } from "./diagnostics.js";
 import { DEFAULT_TITLE } from "@valancex/common/internal";
 export const PROJECT_FILE = "valance.json";
@@ -65,6 +66,9 @@ const url = (value) => {
 const title = (value) => typeof value === "string" && value.includes("{page}") && value.length <= 120 && !/[{}]/.test(value.replaceAll("{page}", "").replaceAll("{site}", ""))
     ? undefined
     : 'must contain "{page}" and may use "{site}", for example "{page} · {site}" (at most 120 characters)';
+const themePackage = (value) => typeof value === "string" && /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value)
+    ? undefined
+    : 'must be the name of an installed theme package, such as "acme-theme" or "@acme/theme"';
 const flag = (value) => (typeof value === "boolean" ? undefined : "must be true or false");
 const api = (value) => {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -91,6 +95,32 @@ const api = (value) => {
     }
     return undefined;
 };
+const record = (value) => {
+    const redact = value?.redact;
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        Object.keys(value).some((key) => key !== "redact") ||
+        typeof redact !== "object" ||
+        redact === null ||
+        Array.isArray(redact)) {
+        return 'must be an object such as { "redact": { "scope": [["password"]], "commands": ["login/type"] } }';
+    }
+    const { scope, commands, ...others } = redact;
+    if (Object.keys(others).length > 0) {
+        return `"redact" has unknown settings ${Object.keys(others)
+            .map((key) => `"${key}"`)
+            .join(", ")} (known: scope, commands)`;
+    }
+    if (scope !== undefined &&
+        (!Array.isArray(scope) || scope.some((path) => !Array.isArray(path) || path.length === 0 || path.some((step) => typeof step !== "string" || step === "")))) {
+        return '"redact.scope" must be a list of paths, each a non-empty list of field names ("*" is any list index or field): [["password"], ["people", "*", "pin"]]';
+    }
+    if (commands !== undefined && (!Array.isArray(commands) || commands.some((name) => typeof name !== "string" || !/^[\w-]+\/[\w-]+$/.test(name)))) {
+        return '"redact.commands" must be a list of "component/name" commands whose parameters are not recorded: ["login/type"]';
+    }
+    return undefined;
+};
 /** 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);
@@ -101,7 +131,7 @@ export const loadConfig = (root) => {
     const desktop = read(root, DESKTOP_FILE);
     const problems = [
         ...(desktop === undefined ? [] : check(DESKTOP_FILE, desktop.text, desktop.value, { $schema: schema, version }, [])),
-        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title }, ["name"]),
+        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title, record, budgets: budgetProblems, theme: themePackage }, ["name"]),
         ...(web === undefined ? [] : check(WEB_FILE, web.text, web.value, { $schema: schema, version, base, url, headers: flag, announce: flag, api }, [])),
     ];
     if (problems.length > 0) {
@@ -115,6 +145,9 @@ export const loadConfig = (root) => {
         title: named.title ?? DEFAULT_TITLE,
         web: { base: given.base ?? "/", url: given.url ?? "", headers: given.headers ?? true, announce: given.announce ?? true },
         api: { base: given.api?.base ?? "", proxy: given.api?.proxy ?? "" },
+        budgets: named.budgets,
+        theme: named.theme,
+        record: { redact: { scope: named.record?.redact.scope ?? [], commands: named.record?.redact.commands ?? [] } },
     };
 };
 export const siteInfo = (config) => ({