ferrovue 0.4.0 → 0.5.0

package/dist/constants.js

@@ -0,0 +1,292 @@
+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 { ctx } from "./context.js";
+import { numberVal } from "./numbers.js";
+import { structLifetime } from "./rust.js";
+const files = new WeakMap();
+const vals = new WeakMap();
+const evaluated = new WeakMap();
+const inProgress = new WeakSet();
+/** Remember the constants and enums a file declares at its top level, to evaluate when one is used. */
+export function declareConsts(home, body) {
+    const found = new Map();
+    for (const st of body) {
+        const exported = st.type === "ExportNamedDeclaration";
+        const d = exported ? st.declaration : st;
+        if (d?.type === "TSEnumDeclaration")
+            found.set(d.id.name, { node: d, home, exported });
+        if (d?.type === "VariableDeclaration" && d.kind === "const") {
+            for (const v of d.declarations)
+                if (v.id.type === "Identifier" && v.init)
+                    found.set(v.id.name, { node: v, home, exported });
+        }
+    }
+    files.set(home, found);
+    return found;
+}
+/** What a declared constant or enum stands for, evaluated once. */
+export function constOfDecl(d) {
+    const done = evaluated.get(d.node);
+    if (done)
+        return done;
+    if (inProgress.has(d.node))
+        fail(d.home, "FV0201", "a constant that refers to itself", d.node);
+    inProgress.add(d.node);
+    try {
+        const c = d.node.type === "TSEnumDeclaration" ? enumConst(d.home, d.node) : evaluate(d.home, d.node.init, d.node.id.name, typedAs(d.node));
+        evaluated.set(d.node, c);
+        return c;
+    }
+    finally {
+        inProgress.delete(d.node);
+    }
+}
+function typedAs(decl) {
+    const names = [decl.id.typeAnnotation?.typeAnnotation];
+    for (let n = decl.init; n?.type === "TSAsExpression" || n?.type === "TSSatisfiesExpression"; n = n.expression)
+        names.push(n.typeAnnotation);
+    for (let t of names) {
+        if (t?.type === "TSTypeOperator")
+            t = t.typeAnnotation;
+        const item = t?.type === "TSArrayType" ? t.elementType : t?.type === "TSTypeReference" && ["Array", "ReadonlyArray"].includes(t.typeName.name) ? t.typeParameters?.params?.[0] : null;
+        if (item?.type === "TSTypeReference" && item.typeName.type === "Identifier" && ctx.typeStructs.has(item.typeName.name))
+            return item.typeName.name;
+    }
+    return null;
+}
+function enumConst(home, d) {
+    const fields = new Map();
+    let next = 0;
+    for (const m of d.members) {
+        const key = m.id.type === "Identifier" ? m.id.name : m.id.value;
+        let value;
+        if (!m.initializer) {
+            if (next === null)
+                fail(home, "FV0202", `enum member \`${key}\` follows a string member, so it needs a value`, m);
+            value = next;
+        }
+        else {
+            const c = evaluate(home, m.initializer, key, null);
+            if (c.k !== "scalar" || typeof c.js === "boolean" || c.js === null)
+                return fail(home, "FV0203", "an enum member's value is a string or a number literal", m.initializer);
+            value = c.js;
+        }
+        fields.set(key, { k: "scalar", js: value });
+        if (typeof value === "number")
+            fields.set(String(value), { k: "scalar", js: key });
+        next = typeof value === "number" ? value + 1 : null;
+    }
+    return { k: "object", fields, node: d, home, name: d.id.name };
+}
+/** The type an enum stands for: the union of its members' literal types. */
+export function enumType(home, d) {
+    const c = enumConst(home, d);
+    const members = c.k === "object" ? d.members.map((m) => c.fields.get(m.id.type === "Identifier" ? m.id.name : m.id.value)) : [];
+    const literal = (js) => typeof js === "string" ? { type: "StringLiteral", value: js } : { type: "NumericLiteral", value: js };
+    return { type: "TSUnionType", types: members.map((m) => ({ type: "TSLiteralType", literal: literal(m.js), loc: d.loc, __fv: d.__fv })), loc: d.loc, __fv: d.__fv };
+}
+function evaluate(home, n, path, typed) {
+    switch (n.type) {
+        case "TSAsExpression":
+        case "TSSatisfiesExpression":
+        case "TSNonNullExpression":
+        case "ParenthesizedExpression":
+            return evaluate(home, n.expression, path, typed);
+        case "StringLiteral":
+        case "NumericLiteral":
+        case "BooleanLiteral":
+            return { k: "scalar", js: n.value };
+        case "NullLiteral":
+            return { k: "scalar", js: null };
+        case "TemplateLiteral":
+            if (n.expressions.length === 0)
+                return { k: "scalar", js: n.quasis[0].value.cooked };
+            break;
+        case "UnaryExpression":
+            if (n.operator === "-" && n.argument.type === "NumericLiteral")
+                return { k: "scalar", js: -n.argument.value };
+            break;
+        case "Identifier": {
+            const d = files.get(home)?.get(n.name);
+            if (d)
+                return constOfDecl(d);
+            break;
+        }
+        case "MemberExpression": {
+            const key = n.computed ? (n.property.type === "StringLiteral" || n.property.type === "NumericLiteral" ? String(n.property.value) : null) : n.property.name;
+            const base = evaluate(home, n.object, path, null);
+            if (base.k === "object" && key !== null) {
+                const f = base.fields.get(key);
+                if (f)
+                    return f;
+                return fail(home, "FV0204", `\`${base.name}\` has no field \`${key}\``, n.property);
+            }
+            break;
+        }
+        case "ArrayExpression":
+            return {
+                k: "list",
+                items: n.elements.map((el) => (el && el.type !== "SpreadElement" ? evaluate(home, el, path, null) : fail(home, "FV0205", "a constant list holds plain values", n))),
+                node: n,
+                home,
+                path,
+                typed,
+            };
+        case "ObjectExpression": {
+            const fields = new Map();
+            for (const p of n.properties) {
+                if (p.type !== "ObjectProperty" || p.computed)
+                    fail(home, "FV0206", "a constant object holds plain keys and values", p);
+                const key = String(p.key.name ?? p.key.value);
+                fields.set(key, evaluate(home, p.value, `${path}_${key}`, null));
+            }
+            return { k: "object", fields, node: n, home, name: path };
+        }
+    }
+    return fail(home, "FV0207", "a constant the compiler evaluates is a literal, a list or an object of literals, or another such constant of the same file", n);
+}
+function scalarVal(js, float = false) {
+    if (js === null)
+        return { code: "None", ty: NULL };
+    if (typeof js === "string")
+        return { code: rustStr(js), ty: STR };
+    if (typeof js === "boolean")
+        return { code: String(js), ty: BOOL, konst: js };
+    return numberVal(js, !float && Number.isSafeInteger(js));
+}
+function scalarTy(js) {
+    if (js === null)
+        return NULL;
+    return typeof js === "string" ? STR : typeof js === "boolean" ? BOOL : Number.isSafeInteger(js) ? INT : FLOAT;
+}
+/** What a constant is as a value in Rust; an object has none, only its fields. */
+export function constVal(c, at) {
+    if (c.k === "scalar")
+        return scalarVal(c.js);
+    if (c.k === "object")
+        return fail(at.comp, "FV0208", `\`${at.what}\` is an object, read one field at a time: \`${at.what}.${[...c.fields.keys()][0] ?? "x"}\``, at.node);
+    const done = vals.get(c);
+    if (done)
+        return done;
+    const val = listVal(c);
+    vals.set(c, val);
+    return val;
+}
+function listVal(c) {
+    if (c.items.length === 0)
+        return { code: "[]", ty: { k: "list", of: UNDEF } };
+    if (c.items.every((i) => i.k === "scalar")) {
+        const js = c.items.map((i) => i.js);
+        if (js.includes(null))
+            fail(c.home, "FV0209", "a constant list of strings, numbers or booleans holds no `null`", c.node);
+        const tys = js.map(scalarTy);
+        const numbers = tys.every((t) => t.k === "int" || t.k === "float");
+        const float = numbers && tys.some((t) => t.k === "float");
+        if (!numbers && tys.some((t) => !sameTy(t, tys[0])))
+            fail(c.home, "FV0210", "a constant list holds strings, numbers or booleans, all of one type", c.node);
+        const values = js.map((v) => scalarVal(v, float));
+        return { code: `[${values.map((v) => v.code).join(", ")}]`, ty: { k: "list", of: values[0].ty } };
+    }
+    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;
+    const st = c.typed !== null ? ctx.typeStructs.get(c.typed) : itemStruct(c, objects);
+    const name = rustConstName(c.path);
+    const owner = ctx.typeConsts.get(name);
+    if (owner && owner.of !== c)
+        fail(c.home, "FV0212", `a constant list called \`${name}\` in Rust comes from ${owner.file} too; rename one`, c.node);
+    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))
+                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(", ")} },`;
+    });
+    ctx.typeConsts.set(name, { of: c, file: c.home.file, text: `/// \`${c.path.replaceAll("_", ".")}\` in \`${c.home.file}\`.\npub const ${name}: &[${st.name}${life}] = &[\n${rows.join("\n")}\n];\n` });
+    return { code: `super::types::${name}`, ty: { k: "list", of: { k: "struct", name: st.name, home: "types" } } };
+}
+function fieldLiteral(c, f, v, node) {
+    const want = f.ty.k === "opt" ? f.ty.of : f.ty;
+    const none = f.ty.k === "opt" ? (f.ty.none ?? "undefined") : null;
+    if (v === undefined)
+        return none === "undefined" || none === "either" ? "None" : fail(c.home, "FV0213", `this object needs \`${f.js}\``, node);
+    if (v.k === "scalar" && v.js === null)
+        return none === "null" || none === "either" ? "None" : fail(c.home, "FV0214", `\`${f.js}\` in a constant list's object is not \`null\``, node);
+    const plain = v.k === "scalar" && (scalarTy(v.js).k === want.k || (want.k === "float" && typeof v.js === "number"));
+    if (!plain || v.k !== "scalar")
+        return fail(c.home, "FV0215", `\`${f.js}\` in a constant list's object is ${describe(want)}`, node);
+    const code = typeof v.js === "string" ? `Cow::Borrowed(${rustStr(v.js)})` : typeof v.js === "number" ? numberVal(v.js, want.k === "int").code.replace(/i64$/, "") : String(v.js);
+    return f.ty.k === "opt" ? `Some(${code})` : code;
+}
+function describe(t) {
+    return t.k === "str" ? "a string" : t.k === "bool" ? "a boolean" : t.k === "int" || t.k === "float" ? "a number" : "a string, a number or a boolean";
+}
+function itemStruct(c, objects) {
+    const name = `${pascal(c.path)}Item`;
+    const keys = [...new Set(objects.flatMap((o) => [...o.fields.keys()]))];
+    const fields = keys.map((key) => {
+        const values = objects.map((o) => o.fields.get(key));
+        const present = values.filter((v) => v !== undefined);
+        if (present.some((v) => v.k !== "scalar"))
+            fail(c.home, "FV0216", `\`${key}\` in a constant list's objects is a string, a number or a boolean`, c.node);
+        const nulls = present.filter((v) => v.js === null).length;
+        const tys = present.filter((v) => v.js !== null).map((v) => scalarTy(v.js));
+        if (!tys.length)
+            fail(c.home, "FV0217", `\`${key}\` in a constant list's objects is only ever \`null\`: declare the list with an interface that gives its type`, c.node);
+        if (nulls && present.length < values.length)
+            fail(c.home, "FV0218", `\`${key}\` in a constant list's objects is \`null\` in some and absent in others: ${ONE_NOTHING}; write \`null\` in each`, c.node);
+        const numbers = tys.every((t) => t.k === "int" || t.k === "float");
+        const ty = numbers && tys.some((t) => t.k === "float") ? FLOAT : tys[0];
+        if (!numbers && tys.some((t) => !sameTy(t, ty)))
+            fail(c.home, "FV0219", `\`${key}\` in a constant list's objects holds values of different types`, c.node);
+        return { js: key, rust: snake(key), ty: withAbsence(ty, nulls ? "null" : present.length < values.length ? "undefined" : null) };
+    });
+    const existing = ctx.typeStructs.get(name);
+    if (existing && ctx.typeFiles.get(name) !== c.home.file)
+        fail(c.home, "FV0220", `\`${name}\`, the type of this list's objects, is declared by ${ctx.typeFiles.get(name)} too`, c.node);
+    if (RUST_PRELUDE.has(name))
+        fail(c.home, "FV0221", `\`${name}\`, the type of this list's objects, would hide Rust's own; rename the constant`, c.node);
+    const st = { name, fields };
+    ctx.typeStructs.set(name, st);
+    ctx.typeFiles.set(name, c.home.file);
+    return st;
+}
+function pascal(path) {
+    return path
+        .split(/_|(?=[A-Z][a-z])/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join("");
+}
+function rustConstName(path) {
+    return path
+        .split("_")
+        .map((w) => (/^[A-Z0-9]+$/.test(w) ? w : snake(w).replace(/^r#/, "").toUpperCase()))
+        .join("_");
+}
+/** The constant an expression names: an imported or enum binding, or a field of one. */
+export function constOf(s, n) {
+    if (n.type === "Identifier") {
+        const c = !s.locals.has(n.name) && !s.setup.has(n.name) ? s.consts.get(n.name) : undefined;
+        return c ? { c, what: n.name } : null;
+    }
+    if (n.type !== "MemberExpression")
+        return null;
+    if (n.object.type === "Identifier" && (n.object.name === "$setup" || n.object.name === "_ctx")) {
+        const name = n.computed ? (n.property.type === "StringLiteral" ? n.property.value : undefined) : n.property.name;
+        const c = name !== undefined ? s.consts.get(name) : undefined;
+        return c && name !== undefined ? { c, what: name } : null;
+    }
+    const base = constOf(s, n.object);
+    if (base?.c.k !== "object")
+        return null;
+    const key = n.computed ? (n.property.type === "StringLiteral" || n.property.type === "NumericLiteral" ? String(n.property.value) : null) : n.property.name;
+    if (key === null) {
+        return fail(s.comp, "FV0222", `\`${base.what}\` read by a key chosen at run time, which may name none of its fields; write the choices out with \`v-if\`, or pass the value as a prop`, n);
+    }
+    const f = base.c.fields.get(key);
+    if (!f)
+        return fail(s.comp, "FV0204", `\`${base.what}\` has no field \`${key}\``, n);
+    return { c: f, what: `${base.what}.${key}` };
+}

package/dist/context.d.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from "./plugin.ts";
+import type { Declared } from "./constants.ts";
 import { type Component, type Struct, type Ty } from "./model.ts";
 /** A type a helper takes or returns, as the configuration spells it. */
 export type TypeName = "string" | "string?" | "int" | "int?" | "float" | "float?" | "bool";
@@ -11,6 +12,16 @@ export interface HelperSpec {
     /** The longest string it returns, which is what a call adds to the buffer reservation. */
     maxLen?: number;
 }
+/** A component ferrovue does not compile, rendered on the server by a Rust function of the
+ * project's: its twin. ferrovue cannot check that the function writes what Vue would. */
+export interface TwinSpec {
+    /** The Rust path the generated parent calls, e.g. `crate::ui::v_btn`. */
+    rust: string;
+    /** Each prop a template may pass it, by its name in Vue, with its type. */
+    props?: Record<string, TypeName>;
+    /** The slots a template may fill, by name: `["default", "prepend"]`. */
+    slots?: string[];
+}
 /** What `ferrovue.config.json` holds. Paths are relative to the project root. */
 export interface Config {
     /** The directory of `.vue` files to compile. */
@@ -22,6 +33,9 @@ export interface Config {
         module: string;
         functions: Record<string, HelperSpec>;
     };
+    /** Components ferrovue does not compile, by the name a template gives them (`VBtn`, which
+     * `<v-btn>` finds too), each rendered by a Rust function of the project's. */
+    twins?: Record<string, TwinSpec>;
     /** The Rust type a `TrustedHtml` prop is, which must implement `ferrovue::TrustedHtml`, e.g.
      * `crate::sanitize::SafeHtml`. A type that borrows names the props' lifetime, `'a`:
      * `crate::render::Trusted<'a>`. Without it, a component cannot use `v-html` at all. */
@@ -40,7 +54,7 @@ export interface Config {
     /** The directory of Pinia stores (`.ts` files), whose state a component may read while it renders
      * on the server. */
     stores?: string;
-    /** Custom directives that render nothing on the server — no `getSSRProps` — by name, without
+    /** Custom directives that render nothing on the server (no `getSSRProps`), by name, without
      * `v-`: `["focus", "click-outside"]`. Any other custom directive is refused, since the server
      * cannot know what its `getSSRProps` would add. */
     clientDirectives?: string[];
@@ -58,6 +72,9 @@ 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 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";
 export declare const CONFIG_FILE = "ferrovue.config.json";
@@ -75,6 +92,7 @@ export declare const ctx: {
     }>;
     helperModule: string | null;
     trustedHtml: string | null;
+    builders: boolean;
     clientDirectives: Set<string>;
     plugins: readonly Plugin[];
     runs: Map<Plugin<unknown, unknown>, unknown>;
@@ -83,6 +101,12 @@ export declare const ctx: {
     typeAliases: Map<string, any>;
     typeFiles: Map<string, string>;
     typeRead: Set<string>;
+    constDecls: Map<string, Map<string, Declared>>;
+    typeConsts: Map<string, {
+        of: unknown;
+        file: string;
+        text: string;
+    }>;
     components: Map<string, Component>;
     narrowCount: number;
     componentsDir: string;

package/dist/context.js

@@ -12,7 +12,7 @@ export function loadConfig(root, configPath) {
     }
     catch (e) {
         if (e.code === "ENOENT") {
-            throw new GenError(`cannot find \`${displayName}\` in ${root}`);
+            throw new GenError("FV1102", `cannot find \`${displayName}\` in ${root}`, { file: displayName });
         }
         throw e;
     }
@@ -21,13 +21,16 @@ export function loadConfig(root, configPath) {
         raw = JSON.parse(text);
     }
     catch (e) {
-        throw new GenError(`failed to parse \`${displayName}\`: ${e.message}`);
+        throw new GenError("FV1103", `failed to parse \`${displayName}\`: ${e.message}`, { file: displayName });
     }
     if (typeof raw.components !== "string" || typeof raw.out !== "string") {
-        throw new GenError(`${displayName} needs \`components\` and \`out\` directories`);
+        throw new GenError("FV1104", `${displayName} needs \`components\` and \`out\` directories`, { file: displayName });
     }
     if (raw.scopeId !== undefined && raw.scopeId !== "filepath" && raw.scopeId !== "filepath-source") {
-        throw new GenError(`\`scopeId\` in ${displayName} is "filepath" or "filepath-source", as \`@vitejs/plugin-vue\` computes it`);
+        throw new GenError("FV1105", `\`scopeId\` in ${displayName} is "filepath" or "filepath-source", as \`@vitejs/plugin-vue\` computes it`, { file: displayName });
+    }
+    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 });
     }
     return raw;
 }
@@ -48,7 +51,7 @@ export function tyOfName(name) {
         case "bool":
             return BOOL;
         default:
-            throw new GenError(`unknown helper type \`${String(name)}\``);
+            throw new GenError("FV1107", `unknown helper type \`${String(name)}\``);
     }
 }
 /** Where `TrustedHtml` comes from. Only that import names the type `v-html` will write raw. */
@@ -57,6 +60,7 @@ export const ctx = {
     helpers: {},
     helperModule: null,
     trustedHtml: null,
+    builders: true,
     clientDirectives: new Set(),
     plugins: [],
     runs: new Map(),
@@ -65,6 +69,8 @@ export const ctx = {
     typeAliases: new Map(),
     typeFiles: new Map(),
     typeRead: new Set(),
+    constDecls: new Map(),
+    typeConsts: new Map(),
     components: new Map(),
     narrowCount: 0,
     componentsDir: "",

package/dist/diagnostics.d.ts

@@ -0,0 +1,23 @@
+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
+ * exclusive, and `null` where it is not known. */
+export interface Diagnostic {
+    file: string | null;
+    line: number | null;
+    column: number | null;
+    endLine: number | null;
+    endColumn: number | null;
+    code: Code;
+    severity: "error";
+    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;
+/** 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;

package/dist/diagnostics.js

@@ -0,0 +1,30 @@
+import { docsUrl, ERRORS } from "./errors.js";
+import { GenError } from "./model.js";
+const UNPARSED = "FV0001";
+/** Whether the compiler raised `e` for its input: a refusal, or a file that does not parse. */
+export function isRefusal(e) {
+    return e instanceof GenError || e instanceof SyntaxError;
+}
+/** The diagnostic for a refusal. */
+export function diagnose(e) {
+    const code = e instanceof GenError ? e.code : UNPARSED;
+    const at = e instanceof GenError ? e.at : null;
+    return {
+        file: at?.file ?? null,
+        line: at?.line ?? null,
+        column: at?.column ?? null,
+        endLine: at?.endLine ?? null,
+        endColumn: at?.endColumn ?? null,
+        code,
+        severity: "error",
+        title: ERRORS[code].title,
+        message: e instanceof GenError ? e.what : e.message.split("\n")[0],
+        docs: docsUrl(code),
+    };
+}
+/** 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 function formatRefusal(e) {
+    const code = e instanceof GenError ? e.code : UNPARSED;
+    return `error[${code}]: ${e.message}\n = docs: ${docsUrl(code)}`;
+}