@blotch/angular-lynx-build 0.0.0-stage → 22.2.2

package/builders/dev-server/schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "AngularLynxDevServerBuilder",
+  "title": "AngularLynx dev-server builder",
+  "description": "Runs the rspeedy dev server, which Lynx Explorer and the web preview load the app from.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "buildTarget": {
+      "type": "string",
+      "description": "The build target to serve, as `project:target[:configuration]`, e.g. `my-app:build:development`. Its options (the Angular compiler options, `config`) configure the build, and its `optimization` picks a production or development build. Defaults to the project's build target with its development configuration, as Angular's own dev server does.",
+      "pattern": "^[^:\\s]*:[^:\\s]*(:[^\\s]+)?$"
+    },
+    "port": {
+      "type": "number",
+      "description": "The port to serve on. Overrides `server.port` in lynx.config.ts."
+    },
+    "host": {
+      "type": "string",
+      "description": "The host to listen on. Overrides `server.host` in lynx.config.ts."
+    },
+    "environment": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Only build these rspeedy environments (e.g. lynx). Defaults to the build target's `environment`, or all of them."
+    }
+  }
+}

package/builders/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/builders/project-import.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importFromProject = void 0;
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+/**
+ * Imports a package installed in the user's project (rspeedy), not one this
+ * package depends on. The project pins its own rspeedy version in
+ * package.json, and that is the version `ng build` must run, just as
+ * `rspeedy build` would.
+ *
+ * rspeedy is ESM-only, and its `exports` have no `require` condition, so
+ * `require.resolve` can't find its entry point. Its package.json is exported,
+ * though: resolve that and read the `import` entry from it.
+ */
+const importFromProject = async (packageName, projectRoot, installHint) => {
+    const require = (0, node_module_1.createRequire)(node_path_1.default.join(projectRoot, 'package.json'));
+    let packageJsonPath;
+    try {
+        packageJsonPath = require.resolve(`${packageName}/package.json`);
+    }
+    catch {
+        throw new Error(`${packageName} is not installed. ${installHint}`);
+    }
+    const packageJson = JSON.parse((0, node_fs_1.readFileSync)(packageJsonPath, 'utf8'));
+    const entry = resolveImportEntry(packageJson);
+    if (!entry) {
+        throw new Error(`${packageName} has no ESM entry point.`);
+    }
+    return (await import((0, node_url_1.pathToFileURL)(node_path_1.default.join(node_path_1.default.dirname(packageJsonPath), entry)).href));
+};
+exports.importFromProject = importFromProject;
+const resolveImportEntry = (packageJson) => {
+    const exports = packageJson.exports;
+    const root = exports && typeof exports === 'object' && '.' in exports
+        ? exports['.']
+        : exports;
+    return pick(root ?? null) ?? packageJson.module ?? packageJson.main;
+};
+/**
+ * Follows `import` (then `default`) conditions down to a file path.
+ */
+const pick = (value) => {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (!value) {
+        return undefined;
+    }
+    for (const condition of ['import', 'node', 'default']) {
+        if (condition in value) {
+            const found = pick(value[condition]);
+            if (found) {
+                return found;
+            }
+        }
+    }
+    return undefined;
+};

package/builders/rspeedy.js

@@ -0,0 +1,162 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRspeedy = exports.modeFromOptimization = exports.importQRCodePlugin = exports.importPlugin = exports.importRspeedy = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Like the rsbuild plugin, rspeedy is this package's own dependency, so the
+ * builders always run the rspeedy version they were released and tested with,
+ * and an app needs no build tool in its package.json besides this package
+ * (as one from `ng new` needs only `@angular/build`).
+ */
+const importRspeedy = () => import('@lynx-js/rspeedy');
+exports.importRspeedy = importRspeedy;
+/**
+ * Unlike rspeedy, the plugin is this package's own dependency, so it is
+ * resolved from here rather than from the project: the builders always run
+ * the plugin version they were released with.
+ */
+const importPlugin = () => import('@blotch/rsbuild-plugin-angular-lynx');
+exports.importPlugin = importPlugin;
+const importQRCodePlugin = () => import('@lynx-js/qrcode-rsbuild-plugin');
+exports.importQRCodePlugin = importQRCodePlugin;
+/** The name `pluginAngularLynx()` registers itself under. */
+const ANGULAR_PLUGIN_NAME = 'lynx:angular';
+/** The name `pluginQRCode()` registers itself under. */
+const QR_CODE_PLUGIN_NAME = 'lynx:rsbuild:qrcode';
+/**
+ * The files rspeedy looks for when no `config` option names one, in its order
+ * (`resolveConfigPath` in @lynx-js/rspeedy).
+ */
+const DEFAULT_CONFIG_FILES = [
+    'lynx.config.ts',
+    'lynx.config.js',
+    'lynx.config.mts',
+    'lynx.config.mjs',
+];
+/**
+ * Whether an rspeedy `plugins` list holds the plugin named `name`. The list
+ * takes Rsbuild's shapes: plugins, falsy entries (from `cond && plugin()`),
+ * promises of either, and nested lists.
+ */
+const hasPlugin = async (plugins, name) => {
+    const plugin = await plugins;
+    if (Array.isArray(plugin)) {
+        for (const item of plugin) {
+            if (await hasPlugin(item, name)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    return plugin?.name === name;
+};
+/**
+ * The rspeedy mode for a build target's options. Angular has no mode option:
+ * its `optimization` decides, and a build that doesn't optimize scripts runs
+ * in dev mode (`ngDevMode` on). The same switch picks rspeedy's mode, so
+ * `ng build -c development` (`optimization: false`) is a development build
+ * and `ng serve -c production` a production one.
+ */
+const modeFromOptimization = (optimization) => {
+    // Angular's own reading of the option (normalizeOptimization in
+    // @angular/build): on by default, and in object form `scripts` decides.
+    const scripts = typeof optimization === 'object' && optimization !== null
+        ? !!optimization.scripts
+        : optimization !== false;
+    return scripts ? 'production' : 'development';
+};
+exports.modeFromOptimization = modeFromOptimization;
+/**
+ * Loads lynx.config.ts as `rspeedy build` and `rspeedy dev` would. Unlike
+ * them, a project without one builds too, from the defaults
+ * {@link createRspeedy} fills in: angular.json holds what the config would
+ * repeat, as it does for any Angular app. A `config` option must name a file
+ * that exists.
+ */
+const loadProjectConfig = async (rspeedy, projectRoot, config) => {
+    if (!config &&
+        !DEFAULT_CONFIG_FILES.some((file) => (0, node_fs_1.existsSync)(node_path_1.default.join(projectRoot, file)))) {
+        return { content: {} };
+    }
+    return rspeedy.loadConfig({ cwd: projectRoot, configPath: config });
+};
+/**
+ * Creates an rspeedy instance the way `rspeedy build` and `rspeedy dev` do:
+ * load lynx.config.ts, then apply the command-line overrides, which here come
+ * from the builder options.
+ *
+ * What lynx.config.ts leaves out comes from angular.json and the defaults an
+ * AngularLynx app needs, so most apps don't need the file at all:
+ *
+ * - `source.entry` is the build target's `browser` option.
+ * - `environments` are `lynx` (the native bundle) and `web` (the browser
+ *   preview).
+ * - The mode follows the build target's `optimization` (see
+ *   {@link modeFromOptimization}).
+ *
+ * It also adds plugins, each unless lynx.config.ts lists it itself (to pass
+ * it options): the AngularLynx plugin, which compiles Angular, and for the
+ * dev server the QR code plugin, which prints the link Lynx Explorer opens.
+ * And the Angular CLI context plugin hands the AngularLynx plugin the project
+ * and its build options as Angular CLI resolved them (`-c` and command-line
+ * overrides included), which it would otherwise read from angular.json under
+ * the default configuration.
+ */
+const createRspeedy = async ({ rspeedy, plugin, qrCode, projectRoot, angularCli, config, environment, server, }) => {
+    const mode = (0, exports.modeFromOptimization)(angularCli.buildOptions['optimization']);
+    // As the rspeedy CLI does before anything else, so plugins (Tailwind,
+    // PostCSS) that read NODE_ENV agree with the mode. The CLI derives it from
+    // the command; here the mode decides, as `optimization` does for Angular.
+    if (!process.env['NODE_ENV']) {
+        process.env['NODE_ENV'] = mode;
+    }
+    const { content, configPath } = await loadProjectConfig(rspeedy, projectRoot, config);
+    // As `rspeedy build` does: a persistent build cache must be invalidated
+    // when lynx.config.ts itself changes.
+    const performance = content['performance'];
+    if (configPath) {
+        if (performance?.buildCache === true) {
+            performance.buildCache = { buildDependencies: [configPath] };
+        }
+        else if (performance?.buildCache) {
+            (performance.buildCache.buildDependencies ??= []).push(configPath);
+        }
+    }
+    content.mode = mode;
+    content['environments'] ??= { lynx: {}, web: {} };
+    const browser = angularCli.buildOptions['browser'];
+    const source = (content['source'] ??= {});
+    if (source.entry === undefined && typeof browser === 'string') {
+        source.entry = node_path_1.default.join(angularCli.workspaceRoot, browser);
+    }
+    if (server?.port !== undefined || server?.host !== undefined) {
+        content['server'] = {
+            ...content['server'],
+            ...(server.port !== undefined && { port: server.port }),
+            ...(server.host !== undefined && { host: server.host }),
+        };
+    }
+    const plugins = Array.isArray(content['plugins']) ? content['plugins'] : [];
+    content['plugins'] = [
+        plugin.pluginAngularCliContext(angularCli),
+        ...plugins,
+        ...((await hasPlugin(plugins, ANGULAR_PLUGIN_NAME))
+            ? []
+            : [plugin.pluginAngularLynx()]),
+        // `fullscreen` opens the app in Lynx Explorer without its navigation
+        // bar, as the rspeedy project template does.
+        ...(qrCode && !(await hasPlugin(plugins, QR_CODE_PLUGIN_NAME))
+            ? [qrCode.pluginQRCode({ fullscreen: true })]
+            : []),
+    ];
+    return rspeedy.createRspeedy({
+        cwd: projectRoot,
+        rspeedyConfig: content,
+        environment: environment ?? [],
+    });
+};
+exports.createRspeedy = createRspeedy;

package/builders/unit-test/index.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runUnitTest = exports.ASSET_LOADERS = exports.ANGULAR_BUILD_OPTIONS = exports.hasTestingLibrary = void 0;
+const architect_1 = require("@angular-devkit/architect");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const project_import_1 = require("../project-import");
+/**
+ * @angular/build comes from the project, like Angular's own builders: its
+ * version must match the project's Angular version, which `ng new` installs
+ * it for.
+ */
+const importAngularBuild = (projectRoot) => (0, project_import_1.importFromProject)('@angular/build', projectRoot, 'Run `npm install --save-dev @angular/build` (`ng new` adds it).');
+/**
+ * Whether the project has @blotch/angular-lynx-testing-library. Its package.json
+ * isn't in its `exports` in every version, and Node then refuses to resolve
+ * it, but only when the package is there.
+ */
+const hasTestingLibrary = (projectRoot) => {
+    try {
+        (0, node_module_1.createRequire)(node_path_1.default.join(projectRoot, 'package.json')).resolve('@blotch/angular-lynx-testing-library/package.json');
+        return true;
+    }
+    catch (error) {
+        return (error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED');
+    }
+};
+exports.hasTestingLibrary = hasTestingLibrary;
+const defaultDeps = {
+    importAngularBuild,
+    hasTestingLibrary: exports.hasTestingLibrary,
+};
+const LYNX_APPLICATION_BUILDER = '@blotch/angular-lynx-build:application';
+const ANGULAR_APPLICATION_BUILDER = '@angular/build:application';
+/**
+ * The options of the Lynx application builder that are Angular's application
+ * builder's too, and mean the same. The rest (native app settings, rspeedy's
+ * `config` and `environment`) are Lynx-only; Angular's schema rejects them.
+ */
+exports.ANGULAR_BUILD_OPTIONS = [
+    'browser',
+    'tsConfig',
+    'polyfills',
+    'styles',
+    'assets',
+    'scripts',
+    'inlineStyleLanguage',
+    'fileReplacements',
+    'aot',
+    'optimization',
+    'sourceMap',
+    'outputHashing',
+    'i18nMissingTranslation',
+    'budgets',
+    'extractLicenses',
+    'outputPath',
+    'index',
+    'watch',
+];
+/**
+ * How Angular's test build loads imported assets (`import logo from
+ * './logo.png'`): as files, so the import is the file's URL, as rspeedy
+ * makes it in the app. Angular's build has no loader for them by default and
+ * fails on the import.
+ */
+exports.ASSET_LOADERS = Object.fromEntries([
+    // Images
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'webp',
+    'avif',
+    'bmp',
+    'ico',
+    'svg',
+    // Fonts
+    'woff',
+    'woff2',
+    'ttf',
+    'otf',
+    'eot',
+    // Audio and video
+    'mp4',
+    'webm',
+    'mov',
+    'mp3',
+    'wav',
+    'ogg',
+    'm4a',
+    'aac',
+].map((extension) => [`.${extension}`, 'file']));
+/**
+ * The builder context Angular's unit-test builder gets. It reads the
+ * compiler options (tsconfig, polyfills, styles, file replacements) from the
+ * build target, and only knows Angular's own application builder: for any
+ * other it warns that "unexpected behavior or build failures may occur" and
+ * validates the options against that builder's schema. A Lynx build target
+ * therefore reaches it as an Angular one, with the options both builders
+ * share, which Angular's schema validates and completes with its defaults,
+ * the asset loaders rspeedy's defaults correspond to, and `lynxPolyfills`
+ * after the app's own polyfills.
+ *
+ * The Lynx setup goes in as polyfills rather than `setupFiles` because
+ * Angular compiles setup files with the tests, and TypeScript rejects one
+ * outside the tsconfig's folder when the tsconfig sets an `outDir`, as
+ * `ng new`'s tsconfig.spec.json does: a package in the workspace's
+ * node_modules is outside a project in `projects/`. Polyfills are bundled as
+ * modules, and run first.
+ */
+const asAngularBuildTargets = (context, lynxPolyfills) => {
+    const isLynxApplication = async (target) => (await context.getBuilderNameForTarget(target)) ===
+        LYNX_APPLICATION_BUILDER;
+    const overrides = {
+        getBuilderNameForTarget: async (target) => (await isLynxApplication(target))
+            ? ANGULAR_APPLICATION_BUILDER
+            : context.getBuilderNameForTarget(target),
+        getTargetOptions: async (target) => {
+            const options = await context.getTargetOptions(target);
+            if (!(await isLynxApplication(target))) {
+                return options;
+            }
+            const polyfills = options['polyfills'];
+            return {
+                ...Object.fromEntries(Object.entries(options).filter(([key]) => exports.ANGULAR_BUILD_OPTIONS.includes(key))),
+                loader: exports.ASSET_LOADERS,
+                polyfills: [
+                    ...(Array.isArray(polyfills)
+                        ? polyfills
+                        : typeof polyfills === 'string'
+                            ? [polyfills]
+                            : []),
+                    ...lynxPolyfills,
+                ],
+            };
+        },
+    };
+    return new Proxy(context, {
+        get: (target, property) => property in overrides
+            ? overrides[property]
+            : Reflect.get(target, property),
+    });
+};
+/**
+ * The options as Angular CLI hands them to Angular's own builders. For a
+ * builder outside `@angular/build`, it sets every array option the user left
+ * out to `[]` (and nested ones too, e.g. `coverageWatermarks.lines`), which
+ * Angular's unit-test builder reads as set: `reporters: []` runs Vitest with
+ * no reporter, so `ng test` printed nothing. An empty list never means more
+ * than an absent one here, so empty lists are dropped.
+ */
+const withoutEmptyLists = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, item]) => !(Array.isArray(item) && item.length === 0))
+        .map(([key, item]) => [key, withoutEmptyLists(item)]));
+};
+/**
+ * `ng test`: Angular's unit-test builder (`@angular/build:unit-test`), so the
+ * options, test discovery (`*.spec.ts` and `*.test.ts`), TestBed, watch mode
+ * and coverage are the ones Angular developers know, and the tests compile
+ * ahead of time like the app. Two modules load first: one defines the
+ * compile-time flags the AngularLynx runtime reads, and, when the project has
+ * @blotch/angular-lynx-testing-library, its setup prepares the Lynx
+ * environment its `render()` needs.
+ *
+ * Tests render through Angular's DOM renderer under TestBed and through the
+ * Lynx renderer under the testing library's `render()`. Either way the test
+ * compile checks templates strictly, as the Angular Language Service does:
+ * a component that uses Lynx elements imports LYNX_ELEMENTS (as generated
+ * ones do). The app build is laxer, because it adds CUSTOM_ELEMENTS_SCHEMA to
+ * every component, which Angular's test build has no hook for.
+ */
+const runUnitTest = async function* (options, context, deps = defaultDeps) {
+    const projectName = context.target?.project;
+    if (!projectName) {
+        yield { success: false, error: 'The builder needs a project target.' };
+        return;
+    }
+    const metadata = await context.getProjectMetadata(projectName);
+    const projectRoot = node_path_1.default.join(context.workspaceRoot, metadata['root'] ?? '');
+    let angularBuild;
+    try {
+        angularBuild = await deps.importAngularBuild(projectRoot);
+    }
+    catch (error) {
+        yield {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+        return;
+    }
+    const lynxPolyfills = [
+        '@blotch/angular-lynx-build/unit-test/lynx-globals',
+        ...(deps.hasTestingLibrary(projectRoot)
+            ? ['@blotch/angular-lynx-testing-library/setup']
+            : []),
+    ];
+    yield* angularBuild.executeUnitTestBuilder(withoutEmptyLists(options), asAngularBuildTargets(context, lynxPolyfills));
+};
+exports.runUnitTest = runUnitTest;
+exports.default = (0, architect_1.createBuilder)((options, context) => (0, exports.runUnitTest)(options, context));

package/builders/unit-test/lynx-globals.d.mts

@@ -0,0 +1,3 @@
+// lynx-globals.mjs only sets globals: `ng test` loads it for its side
+// effects, as a polyfill. Declared so type checkers (and attw) see the module.
+export {};

package/builders/unit-test/lynx-globals.mjs

@@ -0,0 +1,18 @@
+// The first module `ng test` loads, as a polyfill: before Angular's TestBed,
+// the testing library's setup, and any test that imports @blotch/angular-lynx.
+//
+// The runtime reads these compile-time flags, which the rsbuild plugin
+// defines for each thread when it bundles the app. Angular's unit-test build
+// leaves packages unbundled, so a `define` couldn't reach the runtime's code;
+// globals do. Tests run the way the native main thread does: in development,
+// not on the web, without profiling or SSR.
+//
+// Plain JavaScript, so it isn't compiled to CommonJS with the builders:
+// Angular bundles polyfills as ES modules.
+Object.assign(globalThis, {
+  __DEV__: true,
+  __MAIN_THREAD__: true,
+  __WEB__: false,
+  __PROFILE__: false,
+  __ENABLE_SSR__: false,
+});

package/builders/unit-test/schema.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });