ferrovue 0.5.0 → 0.7.0

package/dist/compiler.js

@@ -1,23 +1,33 @@
 import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, resolve } from "node:path";
+import { relativePath } from "./paths.js";
 import { ctx, loadConfig, tyOfName } from "./context.js";
-import { importsOf, readComponent } from "./component.js";
+import { failIn, snake } from "./model.js";
+import { readComponent, refuseOptionsApi } from "./component.js";
+import { listDir } from "./files.js";
 import { scopeFor } from "./script.js";
 import { attrsFlow } from "./fallthrough.js";
-import { componentSource, isIsland, modSource } from "./rust.js";
+import { prepareDynamic } from "./dynamic.js";
+import { componentSource, GENERATED, isIsland, modSource } from "./rust.js";
+import { requireWhole } from "./typescript.js";
 import { renderParams } from "./plugin.js";
 import { PLUGINS } from "./plugins/index.js";
-/** Every generated file, keyed by its name in the output directory. */
-export function generate(root, config = loadConfig(root)) {
+/** Every generated file, keyed by its name in the output directory. `sources` holds the text of
+ * components by path, read in place of their files, as an editor's unsaved buffers. */
+export function generate(root, config = loadConfig(root), sources = new Map()) {
+    ctx.sources = new Map([...sources].map(([file, text]) => [resolve(root, file), text]));
     ctx.componentsDir = config.components.replace(/\/?$/, "/");
     ctx.helperModule = config.helpers?.module ?? null;
     ctx.trustedHtml = config.trustedHtml ?? null;
     ctx.builders = config.builders ?? true;
     ctx.clientDirectives = new Set(config.clientDirectives ?? []);
     ctx.rootDir = root;
+    ctx.vnodeTag = null;
     ctx.typeStructs = new Map();
     ctx.typeAliases = new Map();
     ctx.typeFiles = new Map();
+    ctx.typeDecls = new Map();
+    ctx.typeReached = new Set();
     ctx.typeRead = new Set();
     ctx.constDecls = new Map();
     ctx.typeConsts = new Map();
@@ -32,16 +42,41 @@ export function generate(root, config = loadConfig(root)) {
         { rust: h.rust, params: h.params.map(tyOfName), ret: tyOfName(h.returns), maxLen: h.maxLen ?? 0 },
     ]));
     const dir = join(root, config.components);
-    const files = readdirSync(dir)
-        .filter((f) => f.endsWith(".vue"))
-        .toSorted()
-        .map((f) => join(dir, f));
-    const children = new Set(files.flatMap((f) => importsOf(readFileSync(f, "utf8")).filter((c) => c !== basename(f, ".vue"))));
-    const read = files.map((f) => readComponent(f, root, children.has(basename(f, ".vue"))));
+    const files = [
+        ...listDir(root, config.components, "components")
+            .filter((f) => f.endsWith(".vue"))
+            .toSorted()
+            .map((f) => ({ file: join(dir, f), name: basename(f, ".vue") })),
+        ...PLUGINS.flatMap((p) => p.components?.() ?? []).map((c) => ({ file: join(root, c.file), name: c.name })),
+    ];
+    const modulesOf = new Map();
+    for (const f of files) {
+        const rel = relativePath(root, f.file);
+        if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(f.name)) {
+            failIn(rel, "FV0007", `the component is called \`${f.name}\` after its file, which is not a Rust name: name the file in PascalCase, letters and digits (\`UserCard.vue\`)`);
+        }
+        const file = moduleFile(snake(f.name));
+        if (file === "mod.rs")
+            failIn(rel, "FV0007", `the component's module would be \`mod.rs\`, which holds the generated modules: rename the file`);
+        const taken = modulesOf.get(file);
+        if (taken)
+            failIn(rel, "FV0007", `the component's module would be \`${file}\`, as ${taken}'s is: rename one of them`);
+        modulesOf.set(file, rel);
+    }
+    const read = files.map((f) => readComponent(f.file, root, f.name));
+    const children = new Set(read.flatMap((r) => [...r.comp.imports, ...r.comp.childProps.values()].filter((c) => c !== r.comp.name)));
+    for (const r of read)
+        if (r.optionsApi)
+            refuseOptionsApi(r.comp, r.optionsApi, children.has(r.comp.name));
+    const byName = new Map(read.map((r) => [r.comp.name, r]));
     const components = new Map(read.map((r) => [r.comp.name, r.comp]));
     ctx.components = components;
+    for (const c of components.values())
+        for (const f of c.props.fields)
+            requireWhole(c, f.ty);
     const scopes = read.map((r) => scopeFor(r.comp, r.ast, components).scope);
-    const all = read.map((r, i) => ({ comp: r.comp, ssr: r.ssr, children: scopes[i].children, attrsBindings: scopes[i].attrsBindings }));
+    const analysed = prepareDynamic(read.map((r, i) => ({ ...r, scope: scopes[i] })));
+    const all = read.map((r, i) => ({ comp: r.comp, ssr: analysed[i], children: scopes[i].children, attrsBindings: scopes[i].attrsBindings }));
     for (const p of PLUGINS)
         p.analyse?.(all);
     attrsFlow(all);
@@ -66,23 +101,49 @@ export function generate(root, config = loadConfig(root)) {
             return;
         placed.add(r.comp.name);
         for (const i of r.comp.imports) {
-            const dep = read.find((x) => x.comp.name === i);
+            const dep = byName.get(i);
             if (dep)
                 place(dep);
         }
         ordered.push(r);
     };
     read.forEach(place);
-    for (const r of ordered) {
+    const built = ordered.map((r) => {
         ctx.narrowCount = 0;
-        out.set(`${r.comp.module}.rs`, componentSource(r.comp, r.ast, r.ssr, components));
+        const file = moduleFile(r.comp.module);
+        out.set(file, "");
+        return { file, source: componentSource(r.comp, r.ast, r.ssr, components) };
+    });
+    const reached = () => ctx.typeReached.size + [...components.values()].reduce((n, c) => n + c.reached.size, 0);
+    let modules = [];
+    for (let before = -1; before !== reached();) {
+        before = reached();
+        for (const { file, source } of built)
+            out.set(file, source());
+        modules = PLUGINS.flatMap((p) => p.modules?.() ?? []);
     }
-    const modules = PLUGINS.flatMap((p) => p.modules?.() ?? []);
     out.set("mod.rs", modSource(read.map((r) => r.comp), modules.map(([file]) => file)));
-    for (const [file, text] of modules)
+    for (const [file, text] of modules) {
+        const taken = modulesOf.get(file);
+        if (taken)
+            failIn(taken, "FV0007", `the component's module would be \`${file}\`, which ferrovue writes for the project's ${file.replace(/\.rs$/, "").replaceAll("_", " ")}: rename the file`);
         out.set(file, text);
+    }
     return out;
 }
+/** Whether a file starts with the header ferrovue writes, so `write` removes only what an earlier
+ * run wrote and never a module of the app's own put in the output directory by mistake. */
+export function isGenerated(file) {
+    try {
+        return readFileSync(file, "utf8").startsWith(GENERATED);
+    }
+    catch {
+        return false;
+    }
+}
+function moduleFile(module) {
+    return `${module.replace(/^r#/, "")}.rs`;
+}
 /** Write what \`generate\` produces to the configured directory: only the files whose text changed,
  * so a Rust build that watches them rebuilds no more than it must, and removing what no component
  * produces any more. */
@@ -103,7 +164,7 @@ export function write(root, config = loadConfig(root)) {
             changed.push(name);
         }
     }
-    const removed = readdirSync(target).filter((f) => f.endsWith(".rs") && !files.has(f));
+    const removed = readdirSync(target).filter((f) => f.endsWith(".rs") && !files.has(f) && isGenerated(join(target, f)));
     for (const f of removed)
         rmSync(join(target, f));
     const islands = Object.fromEntries([...ctx.components.values()].filter(isIsland).map((c) => [c.name, c.file]));
@@ -111,6 +172,7 @@ export function write(root, config = loadConfig(root)) {
 }
 export { CONFIG_FILE, loadConfig, TYPES_MODULE } from "./context.js";
 export { GenError } from "./model.js";
+export { docsUrl, ERRORS } from "./errors.js";
 export const VERSION = (() => {
     try {
         const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

package/dist/component.d.ts

@@ -1,8 +1,12 @@
 import { type Component, type N } from "./model.ts";
-/** The `.vue` files a component imports, by name. */
-export declare function importsOf(source: string): string[];
-export declare function readComponent(file: string, root: string, isChild: boolean): {
+/** Refuse a component written with the Options API, which `readComponent` read no further: as a
+ * child when another component imports it, as an island otherwise. */
+export declare function refuseOptionsApi(comp: Component, script: N, isChild: boolean): never;
+/** A component, read and its template compiled. One written with the Options API is read no
+ * further than its `<script>`, `optionsApi`, for `refuseOptionsApi` once every component is read. */
+export declare function readComponent(file: string, root: string, name?: string): {
     comp: Component;
     ast: N[];
     ssr: string;
+    optionsApi?: N;
 };

package/dist/component.js

@@ -1,11 +1,11 @@
 import { parse as parseJs } from "@babel/parser";
 import { compileScript, compileTemplate, parse as parseSfc } from "@vue/compiler-sfc";
-import { readFileSync } from "node:fs";
 import { SourceMapConsumer } from "source-map-js";
-import { basename, relative } from "node:path";
+import { basename } from "node:path";
+import { relativePath } from "./paths.js";
 import { absence, blankComponent, fail, GenError, opt, snake, sourceAt, tagAst } from "./model.js";
-import { ctx } from "./context.js";
-import { typesImports, declareTypes, defaultValue, definePropsType, ONE_NOTHING, readTypeFile, resolveImport, runtimeDefaults, structOf, tyOfTs } from "./typescript.js";
+import { ctx, readSource } from "./context.js";
+import { typesImports, declareTypes, defaultValue, definePropsType, ONE_NOTHING, reachLocal, readTypeFile, resolveImport, runtimeDefaults, structOf, tyOfTs } from "./typescript.js";
 import { claim } from "./plugin.js";
 import { asyncChildren } from "./script.js";
 function vueErrorNode(err, within) {
@@ -59,9 +59,17 @@ function sourceDefault(ast, key) {
 function blockAt(source, block) {
     return sourceAt(source, source.lastIndexOf(`<${block.type}`, block.loc.start.offset));
 }
-/** The `.vue` files a component imports, by name. */
-export function importsOf(source) {
-    return [...source.matchAll(/\bfrom\s*["'](?:[^"']*\/)?([^"'/]+)\.vue["']/g)].map((m) => m[1]);
+function cssVarsAt(source, descriptor) {
+    const at = new Map();
+    for (const st of descriptor.styles) {
+        for (const m of st.content.matchAll(/v-bind\s*\(\s*(?:'([^']*)'|"([^"]*)"|([^)'"]*))/g)) {
+            const raw = m[1] ?? m[2] ?? m[3].trim();
+            if (!at.has(raw))
+                at.set(raw, sourceAt(source, st.loc.start.offset + m.index));
+        }
+    }
+    const block = descriptor.styles.find((st) => /\bv-bind\s*\(/.test(st.content));
+    return descriptor.cssVars.map((v) => at.get(v) ?? (block ? blockAt(source, block) : sourceAt(source, 0)));
 }
 function generics(comp, source, block) {
     const text = block.attrs.generic;
@@ -114,28 +122,27 @@ function scriptOf(comp, descriptor) {
         throw new GenError("FV0001", e.message, { file: comp.file, ...where }, e.message.split("\n")[0]);
     }
 }
-export function readComponent(file, root, isChild) {
-    const name = basename(file, ".vue");
-    const source = readFileSync(file, "utf8");
+/** Refuse a component written with the Options API, which `readComponent` read no further: as a
+ * child when another component imports it, as an island otherwise. */
+export function refuseOptionsApi(comp, script, isChild) {
+    const needs = isChild ? "a child component must have" : "an island needs";
+    return fail(comp, "FV0003", `${needs} \`<script setup lang="ts">\`, or no script at all: a \`<script>\` without \`setup\` (the Options API, \`defineComponent\`) is not translated`, script);
+}
+/** A component, read and its template compiled. One written with the Options API is read no
+ * further than its `<script>`, `optionsApi`, for `refuseOptionsApi` once every component is read. */
+export function readComponent(file, root, name = basename(file, ".vue")) {
+    const source = readSource(file);
     const { descriptor, errors } = parseSfc(source, { filename: file });
-    const rel = relative(root, file);
+    const rel = relativePath(root, file);
     const comp = blankComponent(name, snake(name), rel);
     comp.source = source;
     if (errors.length)
-        fail(comp, "FV0002", String(errors[0]), vueErrorNode(errors[0]));
-    if (descriptor.script && !descriptor.scriptSetup) {
-        const needs = isChild ? "a child component must have" : "an island needs";
-        fail(comp, "FV0003", `${needs} \`<script setup lang="ts">\`, or no script at all: a \`<script>\` without \`setup\` (the Options API, \`defineComponent\`) is not translated`, blockAt(source, descriptor.script));
-    }
+        fail(comp, "FV0002", String(errors[0]).replaceAll(file, rel), vueErrorNode(errors[0]) ?? sourceAt(source, 0));
+    if (descriptor.script && !descriptor.scriptSetup)
+        return { comp, ast: [], ssr: "", optionsApi: blockAt(source, descriptor.script) };
     if (!descriptor.template)
         fail(comp, "FV0004", "a component needs a `<template>`: a render function is not translated", sourceAt(source, 0));
-    for (const st of descriptor.styles) {
-        if (st.module)
-            fail(comp, "FV1005", "`<style module>` renames classes in the bundler; use a global or scoped `<style>`, or a stylesheet", blockAt(source, st));
-    }
-    const cssVar = descriptor.styles.find((st) => /\bv-bind\s*\(/.test(st.content));
-    if (descriptor.cssVars.length)
-        fail(comp, "FV1006", "`v-bind()` in `<style>` sets variables the server does not render; bind `:style` instead", cssVar ? blockAt(source, cssVar) : undefined);
+    comp.cssVarsAt = cssVarsAt(source, descriptor);
     for (const p of ctx.plugins)
         p.sfc?.(comp, descriptor, file, source);
     const script = descriptor.scriptSetup ? scriptOf(comp, descriptor) : null;
@@ -191,7 +198,7 @@ export function readComponent(file, root, isChild) {
         generics(comp, source, descriptor.scriptSetup);
     const decls = declareTypes(comp, [...plainAst, ...ast], comp.structs, comp.aliases);
     for (const d of decls)
-        comp.structs.set(d.name, structOf(comp, d.name, d.members, comp.structs));
+        comp.typeDecls.set(d.name, { members: d.members, node: d.node });
     let propsTy = null;
     for (const s of ast) {
         const call = s.type === "ExpressionStatement" ? s.expression : s.type === "VariableDeclaration" ? s.declarations[0]?.init : null;
@@ -209,7 +216,12 @@ export function readComponent(file, root, isChild) {
         comp.props = structOf(comp, "Props", propsTy.members, comp.structs);
     }
     else if (propsTy.type === "TSTypeReference" && comp.structs.has(propsTy.typeName.name)) {
-        comp.props = { name: "Props", fields: comp.structs.get(propsTy.typeName.name).fields };
+        reachLocal(comp, propsTy.typeName.name);
+        const st = comp.structs.get(propsTy.typeName.name);
+        const refused = st.refused?.values().next().value;
+        if (refused !== undefined)
+            throw refused;
+        comp.props = { name: "Props", fields: st.fields };
     }
     else {
         fail(comp, "FV0304", "`defineProps` takes a type literal or an interface declared in the same block", propsTy);
@@ -252,9 +264,8 @@ export function readComponent(file, root, isChild) {
     const compiled = compileTemplate({
         source: descriptor.template.content,
         filename: file,
-        ...(claim((p) => p.templateOptions?.(comp)) ?? { id: name, scoped: false, slotted: false }),
+        ...(claim((p) => p.templateOptions?.(comp)) ?? { id: name, scoped: false, slotted: false, ssrCssVars: [], isProd: true }),
         ssr: true,
-        ssrCssVars: [],
         compilerOptions: { ...(script ? { bindingMetadata: script.bindings } : {}), sourceMap: true },
     });
     const kids = (n) => n.children.filter((c) => c.type !== 3 && !(c.type === 2 && !c.content.trim()));

package/dist/conformance.d.ts

@@ -0,0 +1,85 @@
+import type { App, Component } from "vue";
+import { type Config } from "./compiler.ts";
+import { type RouteEntry, type RouterOptions } from "./fixture.ts";
+/** What `conformanceSuite` checks: the project, its components and its fixtures. `pinia`,
+ * `vueRouter` and `vueI18n` are the application's own modules (`pinia: await import("pinia")`),
+ * which the fixtures install so that its stores and composables find them. */
+export interface ConformanceOptions extends Pick<RouterOptions, "pinia" | "vueRouter" | "vueI18n"> {
+    /** The project's `ferrovue.config.json`. */
+    config: string;
+    /** Every component in the configured `components` directory, by file name or by the path
+     * `import.meta.glob` gives it: `import.meta.glob("../components/*.vue", { eager: true })`; and
+     * with a folder of pages, every page, by the path `import.meta.glob("../pages/**\/*.vue")` gives
+     * it or by its component name (`BooksId`). */
+    components: Record<string, Component | {
+        default: Component;
+    }>;
+    /** The fixtures, one directory per component holding `<case>.json` and `<case>.html`:
+     * `fixtures` beside the configuration when not given. */
+    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 | 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;
+    it(name: string, body: () => Promise<void> | void): void;
+}
+export declare const TELEPORTS = "<!--fv-teleports-->";
+export declare const HEAD = "<!--fv-head-->";
+/** What unhead's server renderer wrote for a recorded render's head, as `renderSSRHead` gives it. */
+export interface RecordedHead {
+    headTags: string;
+    bodyTags: string;
+    bodyTagsOpen: string;
+    htmlAttrs: string;
+    bodyAttrs: string;
+}
+/** The head a recorded render wrote after its body, if it wrote one. */
+export declare function recordedHead(html: string): RecordedHead | null;
+/** Render a fixture's app as the conformance suite records it: Vue's HTML, then what was teleported
+ * and what `useHead` asked for, each after its marker. */
+export declare function renderFixture(app: App): Promise<string>;
+/** Put a recorded render's head into the document, as a page would write it: its tags in `<head>`,
+ * and its attributes on `<html>` and `<body>`. */
+export declare function placeHead(head: RecordedHead | null, doc?: Document): void;
+/** A recorded render as a page body to hydrate: the main HTML in `<div id="root">`, what was
+ * teleported in each target, and the tags the head puts at the start and end of `<body>`. */
+export declare function hydrationBody(html: string): string;
+/** Where two renders first differ, with the text around it in each. */
+export declare function firstDifference(recorded: string, rendered: string): string;
+/** The routes and the router and vue-i18n options a project's fixtures render with, from its configuration. */
+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`), 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 {};