@blotch/rsbuild-plugin-angular-lynx 22.2.0 → 22.2.2

package/README.md

@@ -4,12 +4,14 @@ Rsbuild plugin that compiles Angular apps for the [Lynx](https://lynxjs.org/) na
 
 ## Installation
 
+> **Using the Angular CLI?** You don't need this package directly. `ng add @blotch/angular-lynx` installs [`@blotch/angular-lynx-build`](../build), whose `ng build` and `ng serve` builders depend on this plugin and add it to rspeedy's config. To pass it options, import it from there: `import { pluginAngularLynx } from '@blotch/angular-lynx-build'`.
+
+To run rspeedy directly:
+
 ```bash
 npm install @blotch/rsbuild-plugin-angular-lynx
 ```
 
-> Starting a new project? `ng add @blotch/angular-lynx` sets this up automatically.
-
 ## Usage
 
 Add the plugin to your `lynx.config.ts`:
@@ -32,6 +34,21 @@ export default defineConfig({
 - Splits each entry into **main-thread** and **background-thread** bundles for Lynx's dual-thread model
 - Bundles component stylesheets and processes CSS
 - Registers `CUSTOM_ELEMENTS_SCHEMA` so Angular accepts Lynx elements (`<view>`, `<text>`, etc.)
+- Enforces the build target's `budgets` with `ng build`'s units and messages: a warning is printed, an error fails the build
+
+## Budgets
+
+Budgets in angular.json are checked against the `lynx` environment, the bundles devices load. The `web` preview isn't checked. A Lynx app ships `.bundle` files rather than separate scripts and stylesheets, so each budget type measures:
+
+| Type                | Measures                                                           |
+| ------------------- | ------------------------------------------------------------------ |
+| `initial`           | Each entry's bundle on its own, since a Lynx page loads one bundle |
+| `bundle`            | The bundle of the entry named by `name`                            |
+| `all` / `allScript` | All bundles and scripts together (scripts ship inside the bundles) |
+| `any` / `anyScript` | Each bundle and script                                             |
+| `anyComponentStyle` | Each component stylesheet, compiled                                |
+
+Media and fonts aren't counted. Under plain `rspeedy dev` budgets are skipped: the plugin then reads angular.json's default configuration, usually production, whose budgets don't fit a development build. `ng serve` checks them when the configuration it serves has them, as Angular's dev server does.
 
 ## Documentation
 

package/dist/angular-cli-context.d.ts

@@ -0,0 +1,34 @@
+import type { RsbuildPlugin, RsbuildPluginAPI } from '@lynx-js/rspeedy';
+/**
+ * What Angular CLI knows about the build that a plain rspeedy run doesn't:
+ * which project it is for, and its build target's options as Angular CLI
+ * resolved them. `ng build` and `ng serve` (@blotch/angular-lynx-build) hand
+ * it to the plugin through {@link pluginAngularCliContext}.
+ */
+export type AngularCliContext = {
+    /** The workspace root, where angular.json is. */
+    readonly workspaceRoot: string;
+    /** The angular.json project being built. */
+    readonly project: string;
+    /**
+     * The project's build target options: its base options, then each
+     * configuration selected with `-c` (or the default one), then command-line
+     * overrides, merged by Angular CLI.
+     */
+    readonly buildOptions: Readonly<Record<string, unknown>>;
+};
+export declare const ANGULAR_CLI_CONTEXT_PLUGIN_NAME = "lynx:angular-cli-context";
+/**
+ * Hands the Angular CLI context to `pluginAngularLynx()` through Rsbuild's
+ * plugin-to-plugin API (`api.expose` / `api.useExposed`). The builders add it
+ * to rspeedy's config; lynx.config.ts never lists it.
+ *
+ * It works whether the builders added `pluginAngularLynx()` themselves or
+ * lynx.config.ts lists it with options, which a constructor argument couldn't.
+ */
+export declare const pluginAngularCliContext: (context: AngularCliContext) => RsbuildPlugin;
+/**
+ * The Angular CLI context, or undefined when rspeedy runs on its own (then
+ * the plugin reads angular.json itself).
+ */
+export declare const getAngularCliContext: (api: Pick<RsbuildPluginAPI, "useExposed">) => AngularCliContext | undefined;

package/dist/angular-cli-context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/angular-diagnostics.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Where an Angular diagnostic points. Mirrors the esbuild `Location` shape that
+ * `@angular/build` converts TypeScript and Angular compiler diagnostics into:
+ * `line` is 1-based and `column` 0-based.
+ */
+export type AngularDiagnosticLocation = {
+    readonly file?: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly length?: number;
+    readonly lineText?: string;
+};
+/**
+ * One diagnostic from `compilation.diagnoseFiles()`: an esbuild
+ * `PartialMessage`, whose `text` starts with the code (`TS2307: ...`,
+ * `NG8001: ...`).
+ */
+export type AngularDiagnosticMessage = {
+    readonly text?: string;
+    readonly location?: AngularDiagnosticLocation | null;
+    readonly notes?: readonly {
+        readonly text?: string;
+        readonly location?: AngularDiagnosticLocation | null;
+    }[];
+};
+/**
+ * The diagnostics of one Angular compile, normalized so callers don't have to
+ * handle `diagnoseFiles()` leaving either list out.
+ */
+export type AngularDiagnostics = {
+    readonly errors: readonly AngularDiagnosticMessage[];
+    readonly warnings: readonly AngularDiagnosticMessage[];
+};
+/**
+ * The shape rspack accepts in `compilation.errors` and `compilation.warnings`.
+ * rsbuild prints `file` as the error's `File:` line, so a `path:line:column`
+ * value makes it clickable in terminals and editors.
+ */
+export type AngularDiagnosticError = Error & {
+    file?: string;
+    hideStack: boolean;
+};
+/**
+ * Keeps only the diagnostics a user can act on. Angular's template checker
+ * doesn't know Lynx's native elements and their attributes, so it reports
+ * them as unknown even though the renderer supports them.
+ */
+export declare const filterAngularDiagnostics: (diagnostics: {
+    errors?: readonly AngularDiagnosticMessage[];
+    warnings?: readonly AngularDiagnosticMessage[];
+}) => AngularDiagnostics;
+/**
+ * Converts an Angular diagnostic into an error rspack can report. Pushing it
+ * into `compilation.errors` is what makes `rspeedy build` exit non-zero (and
+ * the dev server show it) the way `ng build` and `ng serve` do; printing it
+ * with `console.log` let builds with type errors succeed and ship.
+ */
+export declare const toAngularDiagnosticError: (message: AngularDiagnosticMessage, severity: "error" | "warning") => AngularDiagnosticError;

package/dist/angular-diagnostics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/angular.d.ts

@@ -21,7 +21,8 @@ import type { PluginAngularLynxOptions } from './utils/options.js';
  *     → compilation.update (rebuilds only: invalidate the changed files)
  *     → compilation.initialize (Angular AOT walk + transformStylesheet callback)
  *     → emitAffectedFiles (refreshes typeScriptFileCache)
- *     → diagnoseFiles (filtered to suppress Lynx-element false positives)
+ *     → diagnoseFiles (filtered to suppress Lynx-element false positives, then
+ *       reported as rspack errors/warnings so type errors fail the build)
  *     → rspack rebuilds the changed files plus any whose compiled output changed
  *
  * Then for each module request the `api.transform` hook delegates the per-module

package/dist/budgets-plugin.d.ts

@@ -0,0 +1,64 @@
+import type { RsbuildPluginAPI, Rspack } from '@lynx-js/rspeedy';
+import { type BudgetAsset, type BudgetFailure, type ComponentStyleSize } from './utils/angular/budgets.js';
+import type { Budget } from './utils/angular/options.js';
+/** The shape rspack accepts in `compilation.errors` and `compilation.warnings`. */
+export type BudgetError = Error & {
+    hideStack: boolean;
+};
+/**
+ * Turns a budget failure into an rspack error or warning. As an error it
+ * fails `ng build` / `rspeedy build`, like a budget error fails `ng build`
+ * for a web app; as a warning it's printed and the build succeeds.
+ */
+export declare const toBudgetError: (failure: BudgetFailure) => BudgetError;
+/**
+ * The entry (page) a Lynx template was built from, or undefined for a lazy
+ * bundle. A template covers an entry and its main-thread twin; lazy bundles
+ * cover async chunk groups, which aren't entry points.
+ */
+export declare const bundleEntryName: (chunkGroups: readonly {
+    readonly name?: string | null;
+}[], entrypoints: {
+    has: (name: string) => boolean;
+}) => string | undefined;
+/**
+ * The emitted files budgets count: the bundles and any scripts left outside
+ * them. Leaves out source maps and hot updates (as Angular does), media and
+ * fonts, and the build's intermediate directory, where the Lynx template
+ * plugin writes debug copies of what it encoded into the bundles.
+ */
+export declare const collectBudgetAssets: (assets: readonly {
+    readonly name: string;
+    readonly source: {
+        size: () => number;
+    };
+    readonly info: {
+        readonly hotModuleReplacement?: boolean;
+    };
+}[], entryBundles: ReadonlyMap<string, string>, intermediateDir: string | undefined) => BudgetAsset[];
+export type AngularBudgetsPluginOptions = {
+    readonly budgets: readonly Budget[];
+    /** Kept current by the Angular compile, which runs before each compilation. */
+    readonly componentStyleSizes: ReadonlyMap<string, ComponentStyleSize>;
+    readonly intermediateDir: string | undefined;
+};
+/**
+ * Checks the budgets after every compilation of the `lynx` environment,
+ * including watch rebuilds, once its bundles are final.
+ */
+export declare class AngularBudgetsPlugin {
+    #private;
+    constructor(options: AngularBudgetsPluginOptions);
+    apply(compiler: Rspack.Compiler): void;
+}
+/**
+ * Enforces angular.json's `budgets` on the `lynx` environment, the bundles
+ * devices load. The `web` environment only builds a browser preview, so its
+ * sizes say nothing about the app.
+ */
+export declare const applyBudgets: (api: Pick<RsbuildPluginAPI, "context" | "modifyBundlerChain" | "useExposed">, { budgets, componentStyleSizes, underAngularCli, }: {
+    readonly budgets: readonly Budget[];
+    readonly componentStyleSizes: ReadonlyMap<string, ComponentStyleSize>;
+    /** Whether `ng build` / `ng serve` resolved the build options. */
+    readonly underAngularCli: boolean;
+}) => void;

package/dist/budgets-plugin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/component-styles-cache.d.ts

@@ -1,3 +1,4 @@
+import type { ComponentStyleSize } from './utils/angular/budgets.js';
 /**
  * Per-component stylesheet bookkeeping. `imports` lists the on-disk scoped CSS
  * paths the loader will prepend as `import` statements; `inlineStyles` mirrors
@@ -14,6 +15,11 @@ export type ComponentScopeInfo = {
     className: string;
     scopeId: string;
 };
+/**
+ * Drops the recorded stylesheet sizes of a component whose file was deleted,
+ * so `anyComponentStyle` budgets stop reporting styles that no longer ship.
+ */
+export declare const forgetComponentStyleSizes: (componentStyleSizes: Map<string, ComponentStyleSize>, containingFile: string) => void;
 /**
  * Builds the `transformStylesheet` callback that Angular's AOT compiler invokes
  * for every component stylesheet (inline `styles: []` and external `styleUrls`).
@@ -40,4 +46,10 @@ export declare const createTransformStylesheet: (params: {
      * following rebuild.
      */
     onStylesheetWritten?: (filePath: string) => void;
+    /**
+     * The compiled size of every component stylesheet, for `anyComponentStyle`
+     * budgets. Overwritten each time Angular compiles a stylesheet, so watch
+     * rebuilds check the current sizes.
+     */
+    componentStyleSizes?: Map<string, ComponentStyleSize>;
 }) => ((data: string, containingFile: string, stylesheetFile: string | undefined, order: number, className: string | undefined) => Promise<string>);

package/dist/entry.d.ts

@@ -1,6 +1,11 @@
 import type { RsbuildPluginAPI, Rspack } from '@lynx-js/rspeedy';
 import type { UndefinedOnPartialDeep } from 'type-fest';
 import type { PluginAngularLynxOptions } from './utils/options.js';
+/**
+ * The key `pluginLynx` (the Lynx build engine, which Rspeedy registers) exposes
+ * its resolved config under. Mirrors `S_LYNX_CONFIG` in React Lynx's plugin.
+ */
+export declare const S_LYNX_CONFIG: unique symbol;
 export declare const applyEntry: (api: RsbuildPluginAPI, options: Required<PluginAngularLynxOptions>) => void;
 /**
  * This is copied from https://github.com/web-infra-dev/rsbuild/blob/037da7b9d92e20c7136c8b2efa21eef539fa2f88/packages/core/src/plugins/html.ts#L168

package/dist/index.d.ts

@@ -1 +1,3 @@
-export { pluginAngularLynx } from './plugin-angular-lynx';
+export { pluginAngularLynx } from './plugin-angular-lynx.js';
+export type { PluginAngularLynxOptions } from './utils/options.js';
+export { type AngularCliContext, pluginAngularCliContext, } from './angular-cli-context.js';