@astralarium/repo-config-vitest 0.1.0 → 0.2.0

package/README.md

@@ -33,3 +33,19 @@ export default defineConfig({
   },
 });
 ```
+
+```ts
+testPages(pages, [
+  expectHead(
+    { title: "About - App", property: { "og:url": "/about" } },
+    { origin },
+  ),
+]);
+```
+
+```ts
+// ./start: client-bundle view of a Start module graph
+const { code, modules, imports } = await libraryBuild(entry, {
+  plugins: startClientCompiler(),
+});
+```

package/dist/pages/head.d.ts

@@ -0,0 +1,38 @@
+import type { PageCheck } from "./types.ts";
+/** A page's head metadata, character references decoded. */
+export interface PageHead {
+    /** First `<title>` in `<head>`. */
+    title?: string;
+    /** `<meta name>` contents in `<head>` by lowercase name (HTML matches
+     *  names case-insensitively); the first tag wins. */
+    name: Record<string, string>;
+    /** `<meta property>` contents in `<head>` by lowercase property
+     *  (OpenGraph); the first tag wins. */
+    property: Record<string, string>;
+    /** Target of the first `<meta http-equiv="refresh">`, anywhere in the
+     *  document. */
+    refresh?: string;
+}
+/** The head fields an `expectHead` check asserts; each named field must
+ *  match, `undefined` asserting absence. */
+export interface HeadExpectation {
+    title?: string;
+    /** `<meta name>` contents by name, any case. */
+    name?: Record<string, string | undefined>;
+    /** `<meta property>` contents by property, any case. */
+    property?: Record<string, string | undefined>;
+    refresh?: string;
+}
+/** `headOf` settings. */
+export interface HeadOptions {
+    /** Origin the page serves from: same-origin absolute URLs in `property`
+     *  contents and the `refresh` target read origin-relative. */
+    origin?: string;
+}
+/** `html`'s head metadata (`PageHead`). */
+export declare function headOf(html: string, { origin }?: HeadOptions): PageHead;
+/** The page's head carries each field `expected` names (`headOf`). */
+export declare function expectHead(expected: HeadExpectation, options?: HeadOptions): PageCheck;
+/** `url` resolved against `origin`: its path, query and hash when it
+ *  shares `origin`, else absolute. */
+export declare function originRelative(origin: string, url: string): string;

package/dist/pages/head.js

@@ -0,0 +1,111 @@
+import { expect } from "vitest";
+/** Every `<meta>` start tag of `html`, as attributes; a `>` inside a
+ *  quoted value stays in the tag. */
+function metaTags(html) {
+    return Array.from(html.matchAll(/<meta\b((?:[^>"']|"[^"]*"|'[^']*')*)>/gi), ([, attrs]) => attributes(attrs ?? ""));
+}
+/** `html`'s head metadata (`PageHead`). */
+export function headOf(html, { origin } = {}) {
+    const head = html.split(/<\/head>/i)[0] ?? html;
+    const name = {};
+    const property = {};
+    for (const attrs of metaTags(head)) {
+        if (attrs.content === undefined)
+            continue;
+        const content = decodeEntities(attrs.content);
+        if (attrs.name !== undefined)
+            name[attrs.name.toLowerCase()] ??= content;
+        if (attrs.property !== undefined)
+            property[attrs.property.toLowerCase()] ??=
+                origin && /^https?:\/\//i.test(content)
+                    ? originRelative(origin, content)
+                    : content;
+    }
+    const result = { name, property };
+    const title = /<title\b[^>]*>([\s\S]*?)<\/title>/i.exec(head)?.[1];
+    if (title !== undefined)
+        result.title = decodeEntities(title);
+    const refresh = metaTags(html).find((attrs) => attrs["http-equiv"]?.toLowerCase() === "refresh")?.content;
+    const target = refresh === undefined ? undefined : refreshUrl(decodeEntities(refresh));
+    if (target)
+        result.refresh = origin ? originRelative(origin, target) : target;
+    return result;
+}
+/** The page's head carries each field `expected` names (`headOf`). */
+export function expectHead(expected, options = {}) {
+    return {
+        name: "carries the expected head metadata",
+        check: ({ html }) => {
+            const head = headOf(html, options);
+            const actual = {};
+            if ("title" in expected)
+                actual.title = head.title;
+            if ("refresh" in expected)
+                actual.refresh = head.refresh;
+            if (expected.name)
+                actual.name = Object.fromEntries(Object.keys(expected.name).map((key) => [
+                    key,
+                    head.name[key.toLowerCase()],
+                ]));
+            if (expected.property)
+                actual.property = Object.fromEntries(Object.keys(expected.property).map((key) => [
+                    key,
+                    head.property[key.toLowerCase()],
+                ]));
+            expect(actual).toEqual(expected);
+        },
+    };
+}
+/** `url` resolved against `origin`: its path, query and hash when it
+ *  shares `origin`, else absolute. */
+export function originRelative(origin, url) {
+    const resolved = new URL(url, origin);
+    return resolved.origin === new URL(origin).origin
+        ? `${resolved.pathname}${resolved.search}${resolved.hash}`
+        : resolved.href;
+}
+/** The URL of a refresh `content` (`0; url=…`), its quotes stripped. */
+function refreshUrl(content) {
+    const url = /url\s*=\s*(.*)$/i.exec(content)?.[1]?.trim();
+    const quote = url?.[0];
+    if (url === undefined || (quote !== '"' && quote !== "'"))
+        return url;
+    const end = url.indexOf(quote, 1);
+    return url.slice(1, end === -1 ? undefined : end);
+}
+/** One attribute of a start tag: name, then a double-quoted,
+ *  single-quoted or unquoted value, or none. */
+const ATTRIBUTE = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+/** Attributes of a start tag's attribute text, by lowercase name; the first
+ *  of a name wins, and a valueless attribute reads `""`. */
+function attributes(text) {
+    const attrs = {};
+    for (const [, name, double, single, unquoted] of text.matchAll(ATTRIBUTE))
+        attrs[name.toLowerCase()] ??= double ?? single ?? unquoted ?? "";
+    return attrs;
+}
+/** Named character references `decodeEntities` resolves. */
+const NAMED_ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+};
+/** Highest Unicode code point. */
+const MAX_CODE_POINT = 0x10ffff;
+/** One pass of HTML character reference decoding: numeric references to
+ *  code points and `NAMED_ENTITIES`; others stay as written. */
+function decodeEntities(text) {
+    return text.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (reference, body) => {
+        if (!body.startsWith("#"))
+            return NAMED_ENTITIES[body.toLowerCase()] ?? reference;
+        const codePoint = /^#x/i.test(body)
+            ? parseInt(body.slice(2), 16)
+            : parseInt(body.slice(1), 10);
+        return codePoint <= MAX_CODE_POINT
+            ? String.fromCodePoint(codePoint)
+            : reference;
+    });
+}

package/dist/pages/index.d.ts

@@ -1,7 +1,9 @@
-/** Served-page invariants: the runner, and checks of server rendering. */
+/** Served-page invariants: the runner, and checks of server rendering
+ *  and head metadata. */
 export * from "./checks.ts";
 export * from "./classes.ts";
 export { dehydratedContext, type DehydratedContextOptions, type DehydratedMatch, type DehydratedRouter, dehydratedRouter, } from "./dehydrated.ts";
+export * from "./head.ts";
 export * from "./runner.ts";
 export * from "./types.ts";
 export * from "./viewer.ts";

package/dist/pages/index.js

@@ -1,7 +1,9 @@
-/** Served-page invariants: the runner, and checks of server rendering. */
+/** Served-page invariants: the runner, and checks of server rendering
+ *  and head metadata. */
 export * from "./checks.js";
 export * from "./classes.js";
 export { dehydratedContext, dehydratedRouter, } from "./dehydrated.js";
+export * from "./head.js";
 export * from "./runner.js";
 export * from "./types.js";
 export * from "./viewer.js";

package/dist/start/client-compiler.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "vite";
+/** Start's compiler for the client environment, as an app's
+ *  `tanstackStart()` configures it. */
+export declare function startClientCompiler(): Plugin[];

package/dist/start/client-compiler.js

@@ -0,0 +1,16 @@
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+/** Names of the client environment's compiler plugins in `tanstackStart()`. */
+const CLIENT_COMPILER = new Set([
+    "tanstack-start-core::server-fn:client",
+    "tanstack-start-core:compiler-virtual-module",
+]);
+/** Start's compiler for the client environment, as an app's
+ *  `tanstackStart()` configures it. */
+export function startClientCompiler() {
+    return tanstackStart()
+        .flat(Infinity)
+        .filter((plugin) => typeof plugin === "object" &&
+        plugin !== null &&
+        "name" in plugin &&
+        CLIENT_COMPILER.has(plugin.name));
+}

package/dist/start/index.d.ts

@@ -0,0 +1,3 @@
+/** Vite builds of a module graph, as a Start app's client bundle takes it. */
+export * from "./client-compiler.ts";
+export * from "./library-build.ts";

package/dist/start/index.js

@@ -0,0 +1,3 @@
+/** Vite builds of a module graph, as a Start app's client bundle takes it. */
+export * from "./client-compiler.js";
+export * from "./library-build.js";

package/dist/start/library-build.d.ts

@@ -0,0 +1,20 @@
+import { type Plugin } from "vite";
+/** What `libraryBuild` builds with. */
+export interface LibraryBuildOptions {
+    /** Plugins the build runs, as an app's config adds them. */
+    plugins?: Plugin[];
+    /** Compile-time replacements, e.g. the dev build flag. */
+    define?: Record<string, string>;
+}
+/** A library build's output. */
+export interface LibraryBuild {
+    /** The chunks' code, joined. */
+    code: string;
+    /** Files the chunks bundle. */
+    modules: string[];
+    /** Bare specifiers the chunks import. */
+    imports: string[];
+}
+/** The ES build of the module at `entry`, a file path: unminified,
+ *  comment-free, bare imports external. */
+export declare function libraryBuild(entry: string, { plugins, define }?: LibraryBuildOptions): Promise<LibraryBuild>;

package/dist/start/library-build.js

@@ -0,0 +1,26 @@
+import { build } from "vite";
+/** The ES build of the module at `entry`, a file path: unminified,
+ *  comment-free, bare imports external. */
+export async function libraryBuild(entry, { plugins = [], define } = {}) {
+    const [output] = (await build({
+        configFile: false,
+        logLevel: "silent",
+        plugins,
+        define,
+        build: {
+            write: false,
+            minify: false,
+            lib: { entry, formats: ["es"] },
+            rolldownOptions: {
+                external: (id) => !id.startsWith(".") && !id.startsWith("/"),
+                output: { comments: false },
+            },
+        },
+    }));
+    const chunks = output.output.flatMap((chunk) => chunk.type === "chunk" ? [chunk] : []);
+    return {
+        code: chunks.map((chunk) => chunk.code).join("\n"),
+        modules: chunks.flatMap((chunk) => chunk.moduleIds),
+        imports: chunks.flatMap((chunk) => chunk.imports),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astralarium/repo-config-vitest",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "homepage": "https://github.com/astralarium/repo/tree/main/packages/repo-config-vitest#readme",
   "repository": {
@@ -21,7 +21,8 @@
     "./harness/app-process": "./dist/harness/app-process.js",
     "./harness/worker-process": "./dist/harness/worker-process.js",
     "./pages": "./dist/pages/index.js",
-    "./react": "./dist/react.js"
+    "./react": "./dist/react.js",
+    "./start": "./dist/start/index.js"
   },
   "publishConfig": {
     "access": "public"
@@ -38,10 +39,11 @@
     "seroval": "^1.7.2",
     "undici": "^7.29.0",
     "zod": "^4.6.7",
-    "@astralarium/repo-telemetry": "^0.1.0",
-    "@astralarium/repo-dev": "^0.1.0"
+    "@astralarium/repo-dev": "^0.1.1",
+    "@astralarium/repo-telemetry": "^0.2.0"
   },
   "devDependencies": {
+    "@tanstack/react-start": "^1.169.4",
     "@types/node": "^24.2.0",
     "eslint": "^10.2.1",
     "jsdom": "^29.1.1",
@@ -49,17 +51,21 @@
     "vite": "^8.3.4",
     "vitest": "^5.0.3",
     "wrangler": "^4.132.0",
-    "@astralarium/repo-package-files": "^0.1.0",
-    "@astralarium/repo-config-eslint": "^0.1.0",
-    "@astralarium/repo-config-typescript": "^0.1.0"
+    "@astralarium/repo-config-typescript": "^0.1.0",
+    "@astralarium/repo-config-eslint": "^0.3.0",
+    "@astralarium/repo-package-files": "^0.1.0"
   },
   "peerDependencies": {
+    "@tanstack/react-start": "^1.169.4",
     "jsdom": "^29.1.1",
     "vite": "^8.3.4",
     "vitest": "^5.0.3",
     "wrangler": "^4.132.0"
   },
   "peerDependenciesMeta": {
+    "@tanstack/react-start": {
+      "optional": true
+    },
     "jsdom": {
       "optional": true
     },