ferrovue 0.6.0 → 0.7.0

package/dist/conformance.d.ts

@@ -19,7 +19,18 @@ export interface ConformanceOptions extends Pick<RouterOptions, "pinia" | "vueRo
     fixtures?: string;
     /** Write each fixture's `.html` from Vue's render instead of comparing it: when
      * `FERROVUE_FIXTURES_WRITE=1` is set, if not given. */
-    record?: boolean;
+    record?: boolean | undefined;
+    /** Check that a fresh client render of each fixture shows its recorded HTML, which an
+     * application that navigates between pages relies on: on when `clientDiffers` is given. */
+    clientRender?: boolean;
+    /** The fixtures (`Component/case.json`) whose fresh client render Vue itself makes differ from
+     * its server render, which the check of client renders then expects to differ: a `v-model`
+     * `<select>` whose value matches no option, which the client leaves with none selected; an
+     * attribute such as `disabled` bound on an element with no such property, which the client
+     * writes as `"true"`; a `<TransitionGroup>`'s `name`, which only the server writes; a slot's scope
+     * ids; and an async component beside a `<ClientOnly>`, whose content shows by the time the
+     * component has loaded. */
+    clientDiffers?: string[];
 }
 interface TestApi {
     describe(name: string, body: () => void): void;
@@ -53,12 +64,22 @@ export declare function fixtureOptions(root: string, config: Config): {
     routes: RouteEntry[] | null;
     options: RouterOptions;
 };
+/** Render a fixture's app on the client from scratch, with `createApp` (`fixtureApp`'s `client`
+ * option), into a document laid out as `hydrationBody` lays out its recorded render, and say where
+ * the client's DOM differs from the main HTML the browser parsed, as `renderedShape` compares
+ * them: as mounting leaves it, where `<ClientOnly>` still shows its fallback, and, where that
+ * differs while async components are loading, once they have loaded. What is teleported and the
+ * head are not compared. `null` where they agree. */
+export declare function clientRenderDifference(app: App, html: string): Promise<string | null>;
 /** Register the conformance suite with the given `describe` and `it`. */
 export declare function registerConformance(api: TestApi, options: ConformanceOptions): void;
 /** Register vitest tests holding a project's components to Vue, as ferrovue's own suite does:
  * every component has fixtures and every fixture a component, the generated Rust is what the
  * generator writes now, Vue renders each fixture to its recorded `.html` (or records it, with
- * `FERROVUE_FIXTURES_WRITE=1`), and each recorded `.html` hydrates with no warning and the server's
- * nodes kept. Await it at the top of a test file run in a DOM environment such as happy-dom. */
+ * `FERROVUE_FIXTURES_WRITE=1`), each recorded `.html` hydrates with no warning and the server's
+ * nodes kept. With `clientRender` or `clientDiffers`, a fresh client render of each fixture shows
+ * its recorded `.html`, as `clientRenderDifference` compares them, except the fixtures listed in
+ * `clientDiffers`: what an application that navigates between pages relies on when it renders the
+ * next page from its record. Await it at the top of a test file run in a DOM environment such as happy-dom. */
 export declare function conformanceSuite(options: ConformanceOptions): Promise<void>;
 export {};

package/dist/conformance.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
+import { relativePath } from "./paths.js";
 import { renderToString } from "vue/server-renderer";
 import { generate, loadConfig } from "./compiler.js";
 import { unifiedDiff } from "./diff.js";
@@ -7,6 +8,7 @@ import { allPages, fileRoutes, pagesFolder, routeEntries } from "./file-routes.j
 import { fixtureApp, peer, readFixture } from "./fixture.js";
 import { headRendered, settled } from "./settle.js";
 import { attachSsrRender } from "./ssr.js";
+import { applyCssVars, renderDifference, renderedShape } from "./client-render.js";
 export const TELEPORTS = "<!--fv-teleports-->";
 export const HEAD = "<!--fv-head-->";
 /** The head a recorded render wrote after its body, if it wrote one. */
@@ -154,7 +156,7 @@ function driftProblems(root, config) {
         else {
             const committed = readFileSync(path, "utf8");
             if (committed !== text)
-                problems.push(unifiedDiff(relative(root, path), committed, text).trimEnd());
+                problems.push(unifiedDiff(relativePath(root, path), committed, text).trimEnd());
         }
     }
     const stale = existsSync(out) ? readdirSync(out).filter((f) => f.endsWith(".rs") && !files.has(f)) : [];
@@ -191,6 +193,37 @@ async function hydrateFixture(app, html) {
     placeHead(null);
     return problems;
 }
+/** Render a fixture's app on the client from scratch, with `createApp` (`fixtureApp`'s `client`
+ * option), into a document laid out as `hydrationBody` lays out its recorded render, and say where
+ * the client's DOM differs from the main HTML the browser parsed, as `renderedShape` compares
+ * them: as mounting leaves it, where `<ClientOnly>` still shows its fallback, and, where that
+ * differs while async components are loading, once they have loaded. What is teleported and the
+ * head are not compared. `null` where they agree. */
+export async function clientRenderDifference(app, html) {
+    if (typeof document === "undefined")
+        throw new Error("rendering a fixture on the client needs a DOM: run the suite with `environment: \"happy-dom\"` (or jsdom)");
+    document.body.innerHTML = hydrationBody(html);
+    const root = document.getElementById("root");
+    const expected = renderedShape(root);
+    root.replaceChildren();
+    app.config.warnHandler = () => { };
+    const { warn } = console;
+    console.warn = () => { };
+    let difference;
+    try {
+        app.mount(root);
+        applyCssVars(app);
+        difference = await renderDifference(app, root, renderedShape(root), expected);
+        app.unmount();
+        await headRendered();
+    }
+    finally {
+        console.warn = warn;
+    }
+    document.body.innerHTML = "";
+    placeHead(null);
+    return difference;
+}
 /** Register the conformance suite with the given `describe` and `it`. */
 export function registerConformance(api, options) {
     const configFile = resolve(options.config);
@@ -217,12 +250,12 @@ export function registerConformance(api, options) {
     const cases = casesIn(fixtures);
     const { routes, options: configured } = fixtureOptions(root, config);
     const appOptions = { ...configured, pinia: options.pinia, vueRouter: options.vueRouter, vueI18n: options.vueI18n };
-    const app = async (c, hydrate = false) => {
+    const app = async (c, mode = {}) => {
         const component = given.get(c.component);
         if (!component)
             throw new Error(`the fixtures in ${c.component}/ name no component in \`components\``);
         const json = JSON.parse(readFileSync(`${c.base}.json`, "utf8"));
-        return fixtureApp(component, readFixture(json), routes, { ...appOptions, hydrate });
+        return fixtureApp(component, readFixture(json), routes, { ...appOptions, ...mode });
     };
     api.describe("conformance", () => {
         api.it("has fixtures for every component, and a component for every fixture", () => {
@@ -257,19 +290,37 @@ export function registerConformance(api, options) {
         api.describe("the recorded HTML hydrates without a mismatch", () => {
             for (const c of cases) {
                 api.it(`${c.component}/${c.name}`, async () => {
-                    const problems = await hydrateFixture(await app(c, true), recordedHtml(c));
+                    const problems = await hydrateFixture(await app(c, { hydrate: true }), recordedHtml(c));
                     if (problems.length)
                         throw new Error(`${c.component}/${c.name} did not hydrate exactly:\n${problems.join("\n")}`);
                 });
             }
         });
+        if (!(options.clientRender ?? options.clientDiffers !== undefined))
+            return;
+        const differs = new Set(options.clientDiffers ?? []);
+        api.describe("a fresh client render shows the recorded HTML", () => {
+            for (const c of cases) {
+                const key = `${c.component}/${c.name}`;
+                api.it(key, async () => {
+                    const difference = await clientRenderDifference(await app(c, { client: true }), recordedHtml(c));
+                    if (difference && !differs.has(key))
+                        throw new Error(`${key}: ${difference}\n(list it in \`clientDiffers\` where Vue's own client render differs from its server render)`);
+                    if (!difference && differs.has(key))
+                        throw new Error(`${key} is in \`clientDiffers\`, but the client renders it as the server did: take it out`);
+                });
+            }
+        });
     });
 }
 /** Register vitest tests holding a project's components to Vue, as ferrovue's own suite does:
  * every component has fixtures and every fixture a component, the generated Rust is what the
  * generator writes now, Vue renders each fixture to its recorded `.html` (or records it, with
- * `FERROVUE_FIXTURES_WRITE=1`), and each recorded `.html` hydrates with no warning and the server's
- * nodes kept. Await it at the top of a test file run in a DOM environment such as happy-dom. */
+ * `FERROVUE_FIXTURES_WRITE=1`), each recorded `.html` hydrates with no warning and the server's
+ * nodes kept. With `clientRender` or `clientDiffers`, a fresh client render of each fixture shows
+ * its recorded `.html`, as `clientRenderDifference` compares them, except the fixtures listed in
+ * `clientDiffers`: what an application that navigates between pages relies on when it renders the
+ * next page from its record. Await it at the top of a test file run in a DOM environment such as happy-dom. */
 export async function conformanceSuite(options) {
     const vitest = await peer("vitest", "`conformanceSuite` registers vitest tests", () => import("vitest"));
     registerConformance(vitest, options);

package/dist/constants.js

@@ -1,5 +1,5 @@
 import { blankComponent, BOOL, fail, FLOAT, INT, NULL, RUST_PRELUDE, rustStr, sameTy, snake, STR, UNDEF, withAbsence } from "./model.js";
-import { ONE_NOTHING } from "./typescript.js";
+import { ONE_NOTHING, reachType } from "./typescript.js";
 import { ctx } from "./context.js";
 import { numberVal } from "./numbers.js";
 import { structLifetime } from "./rust.js";
@@ -190,6 +190,8 @@ function listVal(c) {
     if (!c.items.every((i) => i.k === "object"))
         fail(c.home, "FV0211", "a constant list holds plain values of one kind, or objects", c.node);
     const objects = c.items;
+    if (c.typed !== null)
+        reachType(c.typed);
     const st = c.typed !== null ? ctx.typeStructs.get(c.typed) : itemStruct(c, objects);
     const name = rustConstName(c.path);
     const owner = ctx.typeConsts.get(name);
@@ -198,7 +200,7 @@ function listVal(c) {
     const life = structLifetime(st, blankComponent("types", "types", "types", ctx.typeStructs)) ? "<'static>" : "";
     const rows = objects.map((o, i) => {
         for (const key of o.fields.keys())
-            if (!st.fields.some((f) => f.js === key))
+            if (!st.fields.some((f) => f.js === key) && !st.refused?.has(key))
                 fail(c.home, "FV0204", `\`${st.name}\` has no field \`${key}\``, o.node);
         const inits = st.fields.map((f) => `${f.rust}: ${fieldLiteral(c, f, o.fields.get(f.js), objects[i].node)}`);
         return `    ${st.name} { ${inits.join(", ")} },`;

package/dist/context.d.ts

@@ -1,13 +1,16 @@
 import type { Plugin } from "./plugin.ts";
 import type { Declared } from "./constants.ts";
-import { type Component, type Struct, type Ty } from "./model.ts";
+import { type Component, type N, type Struct, type Ty, GenError } from "./model.ts";
+import { type Schema } from "./schema.ts";
 /** A type a helper takes or returns, as the configuration spells it. */
 export type TypeName = "string" | "string?" | "int" | "int?" | "float" | "float?" | "bool";
 /** A function a template may call, and the Rust function that is its twin. */
 export interface HelperSpec {
     /** The Rust path the generated code calls, e.g. `crate::helpers::format_count`. */
     rust: string;
+    /** The type of each argument, in order. */
     params: TypeName[];
+    /** The type it returns. */
     returns: TypeName;
     /** The longest string it returns, which is what a call adds to the buffer reservation. */
     maxLen?: number;
@@ -24,13 +27,18 @@ export interface TwinSpec {
 }
 /** What `ferrovue.config.json` holds. Paths are relative to the project root. */
 export interface Config {
+    /** The JSON Schema an editor checks the file against. ferrovue does not read it. */
+    $schema?: string;
     /** The directory of `.vue` files to compile. */
     components: string;
-    /** The directory the Rust modules are written to. Everything in it is replaced. */
+    /** The directory the Rust modules are written to. A module ferrovue wrote there is replaced or
+     * removed; any other file is left alone. */
     out: string;
     /** The module components import their helpers from, and the Rust twin of each export. */
     helpers?: {
+        /** The module a component imports the helpers from, as its imports name it: `./helpers`. */
         module: string;
+        /** Each function a template may call, by its name in that module. */
         functions: Record<string, HelperSpec>;
     };
     /** Components ferrovue does not compile, by the name a template gives them (`VBtn`, which
@@ -48,9 +56,13 @@ export interface Config {
     /** The router, in full: its routes, the history's base, and the class names `createRouter`
      * gives active links. `routes` alone is shorthand for `{ routes }`. */
     router?: {
+        /** Where the routes come from, as `routes` takes them. */
         routes: RoutesSource;
+        /** The base `createWebHistory` is given, which every link starts with. */
         base?: string;
+        /** The class of a link to the current route or one of its parents. */
         linkActiveClass?: string;
+        /** The class of a link to exactly the current route. */
         linkExactActiveClass?: string;
     };
     /** The directory of Pinia stores (`.ts` files), whose state a component may read while it renders
@@ -63,8 +75,11 @@ export interface Config {
     /** vue-i18n: the directory of locale files (`en.json`, `nl.json`), the locale a page renders in
      * when it names none, and the locales a missing message falls back to. */
     i18n?: {
+        /** The directory of locale files, one per locale: `en.json`, `nl.json`. */
         messages: string;
+        /** The locale a page renders in when it names none. */
         locale?: string;
+        /** The locale or locales, in order, a message missing from the page's locale is looked up in. */
         fallbackLocale?: string | string[];
     };
     /** How a `<style scoped>` component's `data-v-` id is computed, which must be how
@@ -74,18 +89,40 @@ export interface Config {
     scopeId?: ScopeIdMode;
     /** Vite's root, from which a scope id hashes a component's path: the project root by default. */
     viteRoot?: string;
+    /** Whether `@vitejs/plugin-vue` compiles for production, as Vite's `isProduction`: `true` (the
+     * default) for `vite build`, `false` for the dev server. It decides the names of the CSS
+     * variables `v-bind()` in `<style>` sets: a hash in production, the expression in development. */
+    isProduction?: boolean;
+    /** CSS modules (`<style module>`): how Vite's `css.modules` names their classes, which ferrovue
+     * computes as postcss-modules does. Without it, `<style module>` is refused. */
+    cssModules?: {
+        /** The pattern of a class's name, as Vite's `css.modules.generateScopedName`:
+         * `"[local]_[hash:base64:5]"`. */
+        generateScopedName: string;
+        /** Vite's `css.modules.hashPrefix`, hashed before a module's path. */
+        hashPrefix?: string;
+        /** The directory Vite runs in, its working directory, from which a hash takes a module's path,
+         * relative to this file's directory: `viteRoot` by default. */
+        context?: string;
+    };
     /** Whether each props struct and shared type gets `new()` and a chainable setter per optional
      * field: `true` by default. With `false`, props are built as struct literals. */
     builders?: boolean;
 }
 export type ScopeIdMode = "filepath" | "filepath-source";
+/** The options of Vite's `css.modules` that decide a class's name, as postcss-modules reads them. */
+export type CssModulesConfig = NonNullable<Config["cssModules"]>;
 /** Where the routes come from: a JSON file of routes, or a folder of pages. */
 export type RoutesSource = string | {
+    /** The folder of pages, each a component, whose file names give the routes. */
     pages: string;
 };
 export declare const CONFIG_FILE = "ferrovue.config.json";
-/** Read the project's configuration. */
-export declare function loadConfig(root: string, configPath?: string): Config;
+/** Read the project's configuration, handing `warn` a warning for each deprecated key it holds. */
+export declare function loadConfig(root: string, configPath?: string, warn?: (warning: GenError) => void): Config;
+/** Check what a configuration file holds against `schema`, naming the first key that is unknown or
+ * of the wrong shape, and handing `warn` a warning for each deprecated key. */
+export declare function checkConfig(raw: unknown, file: string, warn: (warning: GenError) => void, schema?: Schema): Config;
 export declare function tyOfName(name: TypeName): Ty;
 /** The Rust type of an `InlineHtml` prop, and of a `TrustedHtml` one when `trustedHtml` names it. */
 export declare const INLINE_HTML = "ferrovue::InlineHtml";
@@ -108,6 +145,12 @@ export declare const ctx: {
     typeStructs: Map<string, Struct>;
     typeAliases: Map<string, any>;
     typeFiles: Map<string, string>;
+    typeDecls: Map<string, {
+        home: Component;
+        members: N[];
+        node: N;
+    }[]>;
+    typeReached: Set<string>;
     typeRead: Set<string>;
     constDecls: Map<string, Map<string, Declared>>;
     typeConsts: Map<string, {
@@ -119,4 +162,8 @@ export declare const ctx: {
     narrowCount: number;
     componentsDir: string;
     vnodeTag: string | null;
+    sources: Map<string, string>;
 };
+/** A component's text: what the run was given for its path, as an editor's unsaved buffer, or the
+ * file on disk. */
+export declare function readSource(file: string): string;

package/dist/context.js

@@ -1,9 +1,12 @@
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { BOOL, FLOAT, GenError, INT, opt, STR } from "./model.js";
+import { formatWarning } from "./diagnostics.js";
+import { CONFIG_SCHEMA, TYPE_NAMES } from "./schema.js";
 export const CONFIG_FILE = "ferrovue.config.json";
-/** Read the project's configuration. */
-export function loadConfig(root, configPath) {
+const warnOnConsole = (warning) => console.warn(formatWarning(warning));
+/** Read the project's configuration, handing `warn` a warning for each deprecated key it holds. */
+export function loadConfig(root, configPath, warn = warnOnConsole) {
     const filePath = configPath ? resolve(root, configPath) : join(root, CONFIG_FILE);
     const displayName = configPath ?? CONFIG_FILE;
     let text = "";
@@ -23,15 +26,172 @@ export function loadConfig(root, configPath) {
     catch (e) {
         throw new GenError("FV1103", `failed to parse \`${displayName}\`: ${e.message}`, { file: displayName });
     }
+    return checkConfig(raw, displayName, warn);
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isStrings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+function distance(a, b) {
+    let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j++)
+            next.push(Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)));
+        row = next;
+    }
+    return row[b.length];
+}
+/** The known key a misspelt one most likely means: the same but for case, or one or two edits
+ * away (one for a short key). */
+function closest(key, known) {
+    let best = null;
+    let least = Math.min(2, Math.floor(key.length / 3)) + 1;
+    for (const k of known) {
+        const d = k.toLowerCase() === key.toLowerCase() ? 0 : distance(key, k);
+        if (d < least)
+            [best, least] = [k, d];
+    }
+    return best;
+}
+/** Check what a configuration file holds against `schema`, naming the first key that is unknown or
+ * of the wrong shape, and handing `warn` a warning for each deprecated key. */
+export function checkConfig(raw, file, warn, schema = CONFIG_SCHEMA) {
+    const refuse = (code, what) => {
+        throw new GenError(code, what, { file });
+    };
+    const wrong = (key, shape) => refuse("FV1115", `\`${key}\` in ${file} is ${shape}`);
+    const keys = (o, path, node) => {
+        const props = (node && node.properties) || {};
+        for (const k of Object.keys(o)) {
+            if (props[k])
+                continue;
+            const known = Object.keys(props).filter((x) => !x.startsWith("$") && !props[x].deprecated);
+            const near = closest(k, known);
+            const hint = near ? `did you mean \`${near}\`?` : `it takes ${known.map((x) => `\`${x}\``).join(", ")}`;
+            refuse("FV1114", `${path ? `\`${path}\` in ${file}` : file} has no key \`${k}\`: ${hint}`);
+        }
+    };
+    const string = (o, key, path, required = false) => {
+        if (o[key] === undefined ? required : typeof o[key] !== "string")
+            wrong(path, "a string");
+    };
+    const typeName = (v, path) => {
+        if (typeof v !== "string" || !TYPE_NAMES.includes(v)) {
+            refuse("FV1107", `\`${path}\` in ${file} is ${JSON.stringify(v) ?? "missing"}, not a type a helper or twin takes: ${TYPE_NAMES.map((t) => `"${t}"`).join(", ")}`);
+        }
+    };
+    const routesSource = (v, path) => {
+        if (typeof v === "string" || (isObject(v) && typeof v.pages === "string" && Object.keys(v).length === 1))
+            return;
+        refuse("FV1238", `\`${path}\` in ${file} is a JSON file of routes, or \`{ "pages": "…" }\`: the folder of pages vue-router's file-based routing reads`);
+    };
+    if (!isObject(raw)) {
+        const what = Array.isArray(raw) ? "an array" : raw === null ? "`null`" : `a ${typeof raw}`;
+        return refuse("FV1113", `${file} holds ${what}, where it holds an object: \`{ "components": "components", "out": "src/generated" }\``);
+    }
+    const shape = schema.properties ?? {};
+    const entry = (node) => node?.additionalProperties || undefined;
+    keys(raw, "", schema);
     if (typeof raw.components !== "string" || typeof raw.out !== "string") {
-        throw new GenError("FV1104", `${displayName} needs \`components\` and \`out\` directories`, { file: displayName });
+        throw new GenError("FV1104", `${file} needs \`components\` and \`out\` directories`, { file });
     }
     if (raw.scopeId !== undefined && raw.scopeId !== "filepath" && raw.scopeId !== "filepath-source") {
-        throw new GenError("FV1105", `\`scopeId\` in ${displayName} is "filepath" or "filepath-source", as \`@vitejs/plugin-vue\` computes it`, { file: displayName });
+        throw new GenError("FV1105", `\`scopeId\` in ${file} is "filepath" or "filepath-source", as \`@vitejs/plugin-vue\` computes it`, { file });
     }
     if (raw.builders !== undefined && typeof raw.builders !== "boolean") {
-        throw new GenError("FV1106", `\`builders\` in ${displayName} is \`true\` or \`false\`: whether each props struct gets \`new()\` and a setter per optional field`, { file: displayName });
+        throw new GenError("FV1106", `\`builders\` in ${file} is \`true\` or \`false\`: whether each props struct gets \`new()\` and a setter per optional field`, { file });
+    }
+    for (const key of ["$schema", "stores", "trustedHtml", "viteRoot"])
+        string(raw, key, key);
+    if (raw.isProduction !== undefined && typeof raw.isProduction !== "boolean")
+        wrong("isProduction", "`true` or `false`: whether `@vitejs/plugin-vue` compiles for production");
+    if (raw.cssModules !== undefined) {
+        const m = raw.cssModules;
+        if (!isObject(m))
+            return wrong("cssModules", "an object: `{ generateScopedName, hashPrefix?, context? }`");
+        keys(m, "cssModules", shape.cssModules);
+        string(m, "generateScopedName", "cssModules.generateScopedName", true);
+        string(m, "hashPrefix", "cssModules.hashPrefix");
+        string(m, "context", "cssModules.context");
     }
+    if (raw.clientDirectives !== undefined && !isStrings(raw.clientDirectives))
+        wrong("clientDirectives", 'a list of directive names, as `["focus"]`');
+    if (raw.routes !== undefined)
+        routesSource(raw.routes, "routes");
+    if (raw.router !== undefined) {
+        const r = raw.router;
+        if (!isObject(r))
+            return wrong("router", "an object: `{ routes, base?, linkActiveClass?, linkExactActiveClass? }`");
+        keys(r, "router", shape.router);
+        routesSource(r.routes, "router.routes");
+        for (const key of ["base", "linkActiveClass", "linkExactActiveClass"])
+            string(r, key, `router.${key}`);
+    }
+    if (raw.i18n !== undefined) {
+        const i = raw.i18n;
+        if (!isObject(i))
+            return wrong("i18n", "an object: `{ messages, locale?, fallbackLocale? }`");
+        keys(i, "i18n", shape.i18n);
+        string(i, "messages", "i18n.messages", true);
+        string(i, "locale", "i18n.locale");
+        if (i.fallbackLocale !== undefined && typeof i.fallbackLocale !== "string" && !isStrings(i.fallbackLocale))
+            wrong("i18n.fallbackLocale", "a locale or a list of them");
+    }
+    if (raw.helpers !== undefined) {
+        const h = raw.helpers;
+        if (!isObject(h))
+            return wrong("helpers", "an object: `{ module, functions }`");
+        keys(h, "helpers", shape.helpers);
+        string(h, "module", "helpers.module", true);
+        if (!isObject(h.functions))
+            return wrong("helpers.functions", "an object of functions by name, each `{ rust, params, returns, maxLen? }`");
+        for (const [name, spec] of Object.entries(h.functions)) {
+            const path = `helpers.functions.${name}`;
+            if (!isObject(spec))
+                return wrong(path, "an object: `{ rust, params, returns, maxLen? }`");
+            keys(spec, path, entry(shape.helpers?.properties?.functions));
+            string(spec, "rust", `${path}.rust`, true);
+            if (!Array.isArray(spec.params))
+                return wrong(`${path}.params`, 'the list of types the function takes, as `["int"]`');
+            spec.params.forEach((t, i) => typeName(t, `${path}.params[${i}]`));
+            typeName(spec.returns, `${path}.returns`);
+            if (spec.maxLen !== undefined && !(Number.isSafeInteger(spec.maxLen) && spec.maxLen >= 0))
+                wrong(`${path}.maxLen`, "a whole number, 0 or more");
+        }
+    }
+    if (raw.twins !== undefined) {
+        if (!isObject(raw.twins))
+            return wrong("twins", "an object of twins by component name, each `{ rust, props?, slots? }`");
+        for (const [name, spec] of Object.entries(raw.twins)) {
+            const path = `twins.${name}`;
+            if (!isObject(spec))
+                return wrong(path, "an object: `{ rust, props?, slots? }`");
+            keys(spec, path, entry(shape.twins));
+            if (typeof spec.rust !== "string")
+                refuse("FV1110", `\`${path}\` in ${file} needs \`rust\`, the path of the function that renders it, as \`crate::ui::v_btn\``);
+            if (spec.props !== undefined) {
+                if (!isObject(spec.props))
+                    return wrong(`${path}.props`, 'an object of prop types by name, as `{ "label": "string" }`');
+                for (const [prop, t] of Object.entries(spec.props))
+                    typeName(t, `${path}.props.${prop}`);
+            }
+            if (spec.slots !== undefined && !isStrings(spec.slots))
+                wrong(`${path}.slots`, 'a list of slot names, as `["default"]`');
+        }
+    }
+    const deprecated = (o, node, path) => {
+        if (!isObject(o))
+            return;
+        for (const [k, v] of Object.entries(o)) {
+            const at = path ? `${path}.${k}` : k;
+            const prop = node.properties?.[k] ?? (node.additionalProperties || undefined);
+            if (!prop)
+                continue;
+            if (prop.deprecated)
+                warn(new GenError("FV1117", `\`${at}\` in ${file} is deprecated since ${prop.deprecated.since}, and goes in the next major release: use ${prop.deprecated.use}`, { file }));
+            deprecated(v, prop, at);
+        }
+    };
+    deprecated(raw, schema, "");
     return raw;
 }
 export function tyOfName(name) {
@@ -70,6 +230,8 @@ export const ctx = {
     typeStructs: new Map(),
     typeAliases: new Map(),
     typeFiles: new Map(),
+    typeDecls: new Map(),
+    typeReached: new Set(),
     typeRead: new Set(),
     constDecls: new Map(),
     typeConsts: new Map(),
@@ -77,4 +239,10 @@ export const ctx = {
     narrowCount: 0,
     componentsDir: "",
     vnodeTag: null,
+    sources: new Map(),
 };
+/** A component's text: what the run was given for its path, as an editor's unsaved buffer, or the
+ * file on disk. */
+export function readSource(file) {
+    return ctx.sources.get(resolve(file)) ?? readFileSync(file, "utf8");
+}

package/dist/diagnostics.d.ts

@@ -1,6 +1,6 @@
 import { type Code } from "./errors.ts";
 import { GenError } from "./model.ts";
-/** One refusal, as `ferrovue --format json` writes it. Lines and columns count from 1; the end is
+/** One refusal or warning, as `ferrovue --format json` writes it. Lines and columns count from 1; the end is
  * exclusive, and `null` where it is not known. */
 export interface Diagnostic {
     file: string | null;
@@ -9,15 +9,17 @@ export interface Diagnostic {
     endLine: number | null;
     endColumn: number | null;
     code: Code;
-    severity: "error";
+    severity: "error" | "warning";
     title: string;
     message: string;
     docs: string;
 }
 /** Whether the compiler raised `e` for its input: a refusal, or a file that does not parse. */
 export declare function isRefusal(e: unknown): e is GenError | SyntaxError;
-/** The diagnostic for a refusal. */
-export declare function diagnose(e: GenError | SyntaxError): Diagnostic;
+/** The diagnostic for a refusal, or for a warning raised as a `GenError` and not thrown. */
+export declare function diagnose(e: GenError | SyntaxError, severity?: Diagnostic["severity"]): Diagnostic;
 /** A refusal as the CLI and the Vite plugin show it: `error[FV0604]: `, the message with its
  * location and quoted line, and where the code is documented. */
 export declare function formatRefusal(e: GenError | SyntaxError): string;
+/** A warning as the CLI shows it: `warning[FV1117]: `, the message, and where the code is documented. */
+export declare function formatWarning(e: GenError): string;

package/dist/diagnostics.js

@@ -5,8 +5,8 @@ const UNPARSED = "FV0001";
 export function isRefusal(e) {
     return e instanceof GenError || e instanceof SyntaxError;
 }
-/** The diagnostic for a refusal. */
-export function diagnose(e) {
+/** The diagnostic for a refusal, or for a warning raised as a `GenError` and not thrown. */
+export function diagnose(e, severity = "error") {
     const code = e instanceof GenError ? e.code : UNPARSED;
     const at = e instanceof GenError ? e.at : null;
     return {
@@ -16,7 +16,7 @@ export function diagnose(e) {
         endLine: at?.endLine ?? null,
         endColumn: at?.endColumn ?? null,
         code,
-        severity: "error",
+        severity,
         title: ERRORS[code].title,
         message: e instanceof GenError ? e.what : e.message.split("\n")[0],
         docs: docsUrl(code),
@@ -28,3 +28,7 @@ export function formatRefusal(e) {
     const code = e instanceof GenError ? e.code : UNPARSED;
     return `error[${code}]: ${e.message}\n = docs: ${docsUrl(code)}`;
 }
+/** A warning as the CLI shows it: `warning[FV1117]: `, the message, and where the code is documented. */
+export function formatWarning(e) {
+    return `warning[${e.code}]: ${e.message}\n = docs: ${docsUrl(e.code)}`;
+}

package/dist/editor.d.ts

@@ -0,0 +1,18 @@
+import { type Diagnostic } from "./diagnostics.ts";
+/** A refusal in the file an editor holds, with its range as offsets into the text it was given. The
+ * end is exclusive, and `null` where the compiler does not know it. */
+export interface Located extends Diagnostic {
+    start: number;
+    end: number | null;
+}
+/** Where an editor's checks find the project: the configuration file's path from the project root. */
+export interface EditorOptions {
+    config?: string;
+}
+/** The directory holding `config` that is `dir` or the nearest above it. */
+export declare function projectRoot(dir: string, config?: string): string | null;
+/** The refusals in a component of a ferrovue project, compiling the project with `text` in place of
+ * the file. A project is the nearest directory above the file holding the configuration; a file in
+ * none has no refusals. The compiler stops at the first refusal, so a refusal in another file hides
+ * those in this one. */
+export declare function refusalsIn(file: string, text: string, options?: EditorOptions): Located[];