ferrovue 0.5.0 → 0.7.0

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) {
@@ -54,6 +214,8 @@ export function tyOfName(name) {
             throw new GenError("FV1107", `unknown helper type \`${String(name)}\``);
     }
 }
+/** The Rust type of an `InlineHtml` prop, and of a `TrustedHtml` one when `trustedHtml` names it. */
+export const INLINE_HTML = "ferrovue::InlineHtml";
 /** Where `TrustedHtml` comes from. Only that import names the type `v-html` will write raw. */
 export const TYPES_MODULE = "ferrovue/types";
 export const ctx = {
@@ -68,10 +230,19 @@ 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(),
     components: new Map(),
     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/dynamic.d.ts

@@ -0,0 +1,18 @@
+import { type Component, type N, type Scope } from "./model.ts";
+import { Emitter } from "./emitter.ts";
+/** Whether the content a parent gives `slot` of `child` is rendered as virtual nodes, as it is
+ * inside an element a `<component :is>` chooses. */
+export declare function slotAsVnodes(child: Component, slot: string): boolean;
+/** Whether a statement of a compiled template renders a `<component :is>`. */
+export declare function isDynamicComponent(st: N): boolean;
+/** Render `_ssrRenderVNode` of a `<component :is>`, or return false for a statement that is not one. */
+export declare function dynamicComponent(s: Scope, e: Emitter, st: N): boolean;
+/** Resolve every `<component :is>` of the components before any is generated: the slots whose
+ * content renders as virtual nodes, and the compiled templates as the analyses read them, with
+ * each `<component :is>` written out as its choices. */
+export declare function prepareDynamic(read: {
+    comp: Component;
+    ast: N[];
+    ssr: string;
+    scope: Scope;
+}[]): string[];