tslaws 0.3.2 → 0.4.0

package/README.md

@@ -159,6 +159,7 @@ See [docs/laws.md](../../docs/laws.md#the-dashboard).
 
 `tslaws mutate [files...] [--max N] [--seed N] [--json]` mutation-tests the laws: it mutates the covered code, re-runs the laws against each mutant, and lists the survivors no law caught. It handles `.tsx`/`.jsx` and projects with a lock, and takes the run flags of `check`. See [docs/laws.md](../../docs/laws.md#mutation-testing).
 
+- **Other source formats:** `tslaws.json` `bundlerPlugins` lists esbuild plugin modules (paths relative to the file) that teach the browser bundler formats like `.tsrx`. See [docs/laws.md](../../docs/laws.md#bundler-plugins).
 - **Settings:** `tslaws.json` `runs`, `bound`, `proofTimeoutMs` and `propertyTimeoutMs` set the run defaults; a command line flag beats them. See [docs/laws.md](../../docs/laws.md#settings).
 
 ## Agents cannot move the goalposts

package/dist/browser.js

@@ -2,8 +2,10 @@
 // each input is sent to a page where the compiled law and the code it checks run against a live DOM.
 import { existsSync } from 'node:fs';
 import { mkdirSync } from 'node:fs';
-import { delimiter, join } from 'node:path';
+import { delimiter, join, relative as pathRelative, resolve, sep } from 'node:path';
 import { build as bundleWith } from 'esbuild';
+import { explainBundleError, loadBundlerPlugins } from "./bundlerPlugins.js";
+import { readConfig } from "./coverage.js";
 import { chromium, firefox, webkit } from 'playwright-core';
 import { toWire } from "./generators.js";
 import { runProperty, summarise } from "./property.js";
@@ -156,21 +158,70 @@ function projectModulesPlugin(cwd) {
         },
     };
 }
+// The compiler writes only what it compiles to .tslaws/out, so a relative import of any other source file (a `.tsrx`
+// template, a stylesheet, an image) would look for it there. Such an import resolves to the file beside the source.
+function sourceFilesPlugin(cwd) {
+    const out = join(cwd, '.tslaws', 'out');
+    return {
+        name: 'tslaws-source-files',
+        setup(build) {
+            build.onResolve({ filter: /^\.\.?\// }, (args) => {
+                if (args.resolveDir !== out && !args.resolveDir.startsWith(out + sep))
+                    return undefined;
+                const inOut = resolve(args.resolveDir, args.path);
+                if (existsSync(inOut))
+                    return undefined;
+                const source = join(cwd, pathRelative(out, inOut));
+                return existsSync(source) && !source.endsWith('.js') ? { path: source } : undefined;
+            });
+        },
+    };
+}
+const assetExtensions = [
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.avif',
+    '.svg',
+    '.ico',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.otf',
+    '.eot',
+];
+/** The project's `bundlerPlugins` from tslaws.json come first, so they can claim a format before the built-in resolver. */
 async function bundleOf(jsFile, cwd) {
-    const result = await bundleWith({
-        plugins: [projectModulesPlugin(cwd)],
-        entryPoints: [jsFile],
-        bundle: true,
-        write: false,
-        format: 'iife',
-        globalName: '__lawModule',
-        platform: 'browser',
-        target: 'es2022',
-        absWorkingDir: cwd,
-        logLevel: 'silent',
-        define: { 'process.env.NODE_ENV': '"development"', global: 'globalThis' },
-    });
-    return result.outputFiles[0].text;
+    const projectPlugins = await loadBundlerPlugins(cwd, readConfig(cwd).bundlerPlugins);
+    try {
+        const result = await bundleWith({
+            plugins: [...projectPlugins, sourceFilesPlugin(cwd), projectModulesPlugin(cwd)],
+            entryPoints: [jsFile],
+            bundle: true,
+            write: false,
+            // Stylesheets a law imports come out as a separate .css file, which needs an output directory to be named.
+            outdir: join(cwd, '.tslaws', 'bundle'),
+            // Images and fonts become data URLs, so a url() in the CSS or an import in the JavaScript needs no file server.
+            loader: Object.fromEntries(assetExtensions.map((extension) => [extension, 'dataurl'])),
+            format: 'iife',
+            globalName: '__lawModule',
+            platform: 'browser',
+            target: 'es2022',
+            absWorkingDir: cwd,
+            logLevel: 'silent',
+            define: { 'process.env.NODE_ENV': '"development"', global: 'globalThis' },
+        });
+        const emitted = (extension) => result.outputFiles
+            .filter((file) => file.path.endsWith(extension))
+            .map((file) => file.text)
+            .join('\n');
+        return { js: emitted('.js'), css: emitted('.css') };
+    }
+    catch (error) {
+        throw explainBundleError(error);
+    }
 }
 /** Runs the counterexample once more, leaves the DOM as it is, and photographs the page. Best effort. */
 async function capture(page, law, args, options) {
@@ -187,7 +238,7 @@ async function capture(page, law, args, options) {
 }
 /** Property-tests one law in a page; `'timeout'` when it does not finish within `options.propertyTimeoutMs`. */
 export async function runBrowserLaw(law, options) {
-    const code = await bundleOf(law.jsFile, options.cwd);
+    const { js: code, css } = await bundleOf(law.jsFile, options.cwd);
     const page = await (await launch(resolveEngine(options.browser))).newPage();
     // A watcher needs only the first few runs to linger; the rest should not eat the time limit.
     let calls = 0;
@@ -216,6 +267,9 @@ export async function runBrowserLaw(law, options) {
         : undefined;
     try {
         await page.setContent('<!doctype html><html><head><meta charset="utf-8"></head><body></body></html>');
+        // The stylesheet goes in before the script runs, as a linked one would.
+        if (css !== '')
+            await page.addStyleTag({ content: css });
         await page.addScriptTag({ content: code });
         await page.addScriptTag({ content: harness });
         const call = async (...args) => {

package/dist/bundlerPlugins.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from 'esbuild';
+/** What a plugin factory receives. */
+export interface BundlerPluginContext {
+    /** The project root: the directory holding tslaws.json. */
+    cwd: string;
+}
+export type BundlerPluginExport = Plugin | ((context: BundlerPluginContext) => Plugin | Promise<Plugin>);
+/** The setting the messages name. */
+export declare const bundlerPluginsSetting = "bundlerPlugins";
+/**
+ * Loads each listed module (paths relative to `cwd`, where tslaws.json lives) with a dynamic import of its file URL.
+ * Throws one error naming the setting and the module when a module is missing, throws while loading or in its
+ * factory, or does not export a plugin, so the law file reports an `error` rather than the run crashing.
+ */
+export declare function loadBundlerPlugins(cwd: string, paths: readonly string[] | undefined): Promise<Plugin[]>;
+/**
+ * Rewrites an esbuild failure into advice when the cause is a source format the bundler has no loader for (the usual
+ * sign that a `bundlerPlugins` entry is missing). Other messages pass through unchanged.
+ */
+export declare function explainBundleError(error: Error): Error;

package/dist/bundlerPlugins.js

@@ -0,0 +1,71 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Bundler plugins: a project teaches the browser bundler a source format (`.tsrx`, `.svelte`, ...) by listing esbuild
+// plugin modules under `bundlerPlugins` in tslaws.json. Each module default-exports an esbuild Plugin, or a function
+// (sync or async) that takes `{ cwd }` and returns one.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** The setting the messages name. */
+export const bundlerPluginsSetting = 'bundlerPlugins';
+/**
+ * Loads each listed module (paths relative to `cwd`, where tslaws.json lives) with a dynamic import of its file URL.
+ * Throws one error naming the setting and the module when a module is missing, throws while loading or in its
+ * factory, or does not export a plugin, so the law file reports an `error` rather than the run crashing.
+ */
+export async function loadBundlerPlugins(cwd, paths) {
+    const plugins = [];
+    for (const path of paths ?? []) {
+        const file = isAbsolute(path) ? path : resolve(cwd, path);
+        const fail = (why) => {
+            throw new Error(`tslaws.json ${bundlerPluginsSetting}: cannot use "${path}" (${file}): ${why}`);
+        };
+        if (!existsSync(file))
+            fail('no such file; paths are relative to the directory of tslaws.json');
+        let exported;
+        try {
+            exported = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href))).default;
+        }
+        catch (error) {
+            return fail(`it failed to load: ${error.message}`);
+        }
+        let plugin = exported;
+        if (typeof exported === 'function') {
+            try {
+                plugin = await exported({ cwd });
+            }
+            catch (error) {
+                return fail(`its plugin function threw: ${error.message}`);
+            }
+        }
+        const candidate = plugin;
+        if (typeof candidate !== 'object' ||
+            candidate === null ||
+            typeof candidate.name !== 'string' ||
+            typeof candidate.setup !== 'function')
+            fail('its default export must be an esbuild plugin ({ name, setup }) or a function returning one');
+        plugins.push(plugin);
+    }
+    return plugins;
+}
+/**
+ * Rewrites an esbuild failure into advice when the cause is a source format the bundler has no loader for (the usual
+ * sign that a `bundlerPlugins` entry is missing). Other messages pass through unchanged.
+ */
+export function explainBundleError(error) {
+    const match = /No loader is configured for "(\.[^"]+)" files/.exec(error.message);
+    if (match === null)
+        return error;
+    const extension = match[1];
+    const advice = `the browser bundler cannot load "${extension}" files. Add a bundler plugin for that extension in tslaws.json ` +
+        `"${bundlerPluginsSetting}", for example { "${bundlerPluginsSetting}": ["./tools/${extension.slice(1)}-plugin.mjs"] }, ` +
+        `where the module default-exports an esbuild plugin whose onLoad({ filter: /\${extension}$/ }) returns the compiled ` +
+        `JavaScript (see "Bundler plugins" in docs/laws.md)`;
+    return new Error(`${advice}. esbuild said: ${error.message.split('\n')[0]}`);
+}

package/dist/coverage.d.ts

@@ -6,6 +6,8 @@ export interface CoverageConfig {
     compilerOptions?: Record<string, unknown>;
     /** End-to-end laws: the app to drive; see `parseE2eConfig`. */
     e2e?: E2eConfig;
+    /** esbuild plugin modules (paths relative to tslaws.json) that teach the browser bundler new source formats. */
+    bundlerPlugins?: string[];
     /** Run settings; a command line flag beats them and they beat the built-in default. */
     runs?: number;
     propertyTimeoutMs?: number;

package/dist/coverage.js

@@ -9,7 +9,7 @@ import { dirname, join, relative, resolve } from 'node:path';
 import ts from 'typescript';
 import { parseE2eConfig } from "./e2e.js";
 const settingKeys = ['runs', 'propertyTimeoutMs', 'proofTimeoutMs', 'bound'];
-const configKeys = ['cover', 'compilerOptions', 'e2e', ...settingKeys];
+const configKeys = ['cover', 'compilerOptions', 'e2e', 'bundlerPlugins', ...settingKeys];
 /** Validates the top level of tslaws.json: known keys only, and the run settings are integers of at least 1. */
 export function parseConfig(raw) {
     const fail = (message) => {
@@ -27,6 +27,10 @@ export function parseConfig(raw) {
         if (value !== undefined && (typeof value !== 'number' || !Number.isInteger(value) || value < 1))
             fail(`"${key}" must be an integer of at least 1, got ${JSON.stringify(value)}`);
     }
+    const plugins = object.bundlerPlugins;
+    if (plugins !== undefined &&
+        (!Array.isArray(plugins) || plugins.some((entry) => typeof entry !== 'string' || entry === '')))
+        fail(`"bundlerPlugins" must be an array of module paths, got ${JSON.stringify(plugins)}`);
     return object;
 }
 export function readConfig(cwd) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tslaws",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Runs and checks `law` declarations compiled by tsc-laws: property tests, SMT proofs, tamper lock.",
   "bin": {
     "tslaws": "bin/tslaws.js"
@@ -58,7 +58,9 @@
     "z3-solver": "^4.15.0"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0"
+    "@tsrx/ripple": "0.2.11",
+    "@types/node": "^24.0.0",
+    "ripple": "0.6.1"
   },
   "peerDependencies": {
     "axe-core": "^4.0.0"
@@ -69,11 +71,11 @@
     }
   },
   "optionalDependencies": {
-    "tslaws-compiler-darwin-arm64": "0.3.2",
-    "tslaws-compiler-darwin-x64": "0.3.2",
-    "tslaws-compiler-linux-arm64-gnu": "0.3.2",
-    "tslaws-compiler-linux-x64-gnu": "0.3.2",
-    "tslaws-compiler-win32-x64-msvc": "0.3.2"
+    "tslaws-compiler-darwin-arm64": "0.4.0",
+    "tslaws-compiler-darwin-x64": "0.4.0",
+    "tslaws-compiler-linux-arm64-gnu": "0.4.0",
+    "tslaws-compiler-linux-x64-gnu": "0.4.0",
+    "tslaws-compiler-win32-x64-msvc": "0.4.0"
   },
   "publishConfig": {
     "access": "public"