[Rsbuild][Docs] Read rspack off the compiler, condense comments

Author: Kocal

assets/src/collectors/vite.ts

@@ -10,11 +10,8 @@ type ViteOutputChunk = Rollup.OutputChunk & { viteMetadata?: ViteChunkMetadata }
 export function bundleToGraph(bundle: Rollup.OutputBundle, root: string): NormalizedGraph {
     const entryPoints: Record<string, EntryFiles> = {};
     const assets: AssetEntry[] = [];
-    // Entry CSS stays in the manifest, keyed by its logical name (e.g. `app.css`, matching Rsbuild's
-    // chunk-name keying). Async (non-entry) chunk CSS does not: it loads at runtime with its lazily
-    // imported chunk, never via `asset()`, so a manifest entry would only be a byproduct that diverges
-    // from Rsbuild and collides when two chunks share a name. Both kinds report `originalFileNames` as
-    // the importing JS, so neither must reach the source-path branch (that is for imported images/fonts).
+    // Entry CSS is kept in the manifest (keyed by logical name like `app.css`); async chunk CSS isn't
+    // (it loads with its chunk, never via `asset()`, and would collide across same-named chunks).
     const entryCss = new Set<string>();
     const asyncCss = new Set<string>();
 
@@ -47,9 +44,8 @@ export function bundleToGraph(bundle: Rollup.OutputBundle, root: string): Normal
 }
 
 function assetLogicalName(file: Rollup.OutputAsset, root: string, entryCss: Set<string>): string {
-    // Imported assets (images, fonts) get their source path relative to the project root, so the
-    // manifest key matches Rsbuild's `sourceFilename` and same-basename files in different folders
-    // stay distinct. Entry CSS and assets with no source path fall back to the basename.
+    // Imported assets key by source path relative to root (matches Rsbuild's `sourceFilename`, keeps
+    // same-basename files distinct); entry CSS and path-less assets fall back to the basename.
     const original = entryCss.has(file.fileName) ? undefined : file.originalFileNames[0];
     if (original) return slash(relative(root, resolve(root, original)));
     return file.names[0] ?? file.fileName;

assets/src/core/format.ts

@@ -5,8 +5,7 @@ export function joinUrl(prefix: string, name: string): string {
 }
 
 function toReference(prefix: string, name: string): string {
-    // Docroot-relative reference (ADR 0001): a build URL like `/build/app-<hash>.js` becomes
-    // `build/app-<hash>.js`; an absolute dev-server URL has no leading slash and is unchanged.
+    // Docroot-relative reference (ADR 0001): strips the leading slash (dev-server URLs have none).
     return joinUrl(prefix, name).replace(/^\//, '');
 }
 
@@ -27,8 +26,7 @@ export function buildEntrypoints(graph: NormalizedGraph, ctx: BuildContext): Ent
         entryPoints,
     };
     if (graph.integrity) {
-        // Re-key the per-file-name hashes by the same references that appear in the entry lists,
-        // so the Symfony side can look each one up by asset reference.
+        // Re-key hashes by the same references used in the entry lists, for lookup by reference.
         out.integrity = Object.fromEntries(
             Object.entries(graph.integrity).map(([fileName, sri]) => [toReference(ctx.urlPrefix, fileName), sri])
         );

assets/src/core/integrity.ts

@@ -3,20 +3,12 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-/**
- * Build a Subresource Integrity string for `content`: one `<algorithm>-<base64 digest>`
- * token per algorithm, joined by spaces (the format browsers expect in an `integrity`
- * attribute, and the one Webpack Encore writes into `entrypoints.json`).
- */
+/** SRI string for `content`: space-joined `<algo>-<base64 digest>` tokens, one per algorithm. */
 export function computeIntegrity(content: string | Uint8Array, algorithms: string[]): string {
     return algorithms.map((algo) => `${algo}-${createHash(algo).update(content).digest('base64')}`).join(' ');
 }
 
-/**
- * The distinct file names referenced by every entry, across all four buckets
- * (js/css/preload/dynamic), in first-seen order. This is the set of emitted files
- * that get an integrity hash.
- */
+/** Distinct file names across every entry's four buckets (first-seen order) — the SRI set. */
 export function referencedFileNames(entryPoints: Record<string, EntryFiles>): string[] {
     const seen = new Set<string>();
     for (const files of Object.values(entryPoints)) {
@@ -27,11 +19,7 @@ export function referencedFileNames(entryPoints: Record<string, EntryFiles>): st
     return [...seen];
 }
 
-/**
- * Compute the integrity of each file read from `outputPath` on disk, keyed by file name.
- * Used by the Rspack path, whose `done` hook fires after the assets are emitted (like
- * Encore, which reads the emitted files back). Bytes are hashed raw, so binary assets work.
- */
+/** Integrity of each file read back from disk (Rspack path; raw bytes, so binary assets work). */
 export function integrityFromDisk(
     fileNames: string[],
     outputPath: string,

assets/src/core/options.ts

@@ -7,9 +7,8 @@ function normalizeIntegrity(integrity: Options['integrity']): ResolvedOptions['i
 }
 
 function normalizeCopyTo(to: string): string {
-    // Collapse "." segments and redundant slashes, then drop any leading "./" or "/" and trailing
-    // "/". A leading "./" or "/" would corrupt the manifest key ("build/./to-copy/…") and, in the
-    // Vite path, make Rollup reject the emitted asset fileName (it forbids relative-looking paths).
+    // Drop leading `./`|`/` and trailing `/`: they corrupt the manifest key and make Rollup reject
+    // a relative-looking emitted fileName.
     const normalized = path.posix.normalize(to.replace(/\\/g, '/'));
     return normalized
         .replace(/^\.?\/+/, '')

assets/src/core/stimulus.ts

@@ -22,11 +22,7 @@ interface ControllersJson {
 /** The virtual module the runtime helper imports; provided by each bundler adapter. */
 export const VIRTUAL_CONTROLLERS_ID = 'virtual:symfony/controllers';
 
-/**
- * Shown when `virtual:symfony/controllers` is imported (typically via `startStimulusApp()`)
- * while the `stimulus` option is unset — instead of the bundler's cryptic
- * "failed to resolve" / "Unhandled scheme" error.
- */
+/** Shown when the virtual module is imported while the `stimulus` option is unset. */
 export const STIMULUS_NOT_ENABLED_MESSAGE =
     `[@symfony/reprise] "${VIRTUAL_CONTROLLERS_ID}" was imported (this is what startStimulusApp() ` +
     `from "@symfony/reprise/stimulus" pulls in), but the Stimulus integration is not enabled. ` +
@@ -42,29 +38,18 @@ interface ResolvedController {
     autoimports: string[];
 }
 
-// A controller opts into lazy loading with a `stimulusFetch: 'lazy'` comment placed *directly
-// above the class declaration* — after the imports, like a decorator:
-//
-//   import { Controller } from '@hotwired/stimulus'
+// A controller opts into lazy loading with a `stimulusFetch: 'lazy'` comment directly above the
+// class (line/block comment, either quotes, `/*!...*/` survives minification) — recognised only
+// when the class is the very next code, so a stray marker elsewhere doesn't count:
 //
 //   /* stimulusFetch: 'lazy' */
 //   export default class extends Controller {}
-//
-// The marker is recognised only when the very next code is the class (`[export [default]] class`),
-// which is why a stray `stimulusFetch: 'lazy'` sitting above the imports (or anywhere else) does
-// NOT flip the controller to lazy. It may be a block comment or a single-line one, single or
-// double quotes; a block comment may sit on the class's own line, a line comment must precede it.
-// A preserved block comment (`/*! ... */`, the form tsc/esbuild keep so the marker survives
-// minification) is recognised too.
 const LAZY_COMMENT_RE =
     /(?:\/\*!?\s*stimulusFetch:\s*['"]lazy['"]\s*\*\/|\/\/\s*stimulusFetch:\s*['"]lazy['"])\s*(?:export\s+(?:default\s+)?)?(?:abstract\s+)?class\b/i;
 const LOCAL_CONTROLLER_RE = /[-_]controller\.[jt]s$/;
 
 export function generateControllersModule(opts: ResolvedStimulusOptions, root: string, isDev: boolean): string {
-    // Collect controllers keyed by identifier. Third-party controllers are added first, local
-    // ones second, so a local controller sharing an identifier with a third-party one overrides
-    // it (last write wins) and each identifier ends up in exactly one of the two maps — never
-    // emitted twice, never registered twice.
+    // Keyed by identifier; local added after third-party so a local override wins (last write wins).
     const controllers = new Map<string, ResolvedController>();
 
     const require = createRequire(path.join(root, 'noop.js'));
@@ -108,8 +93,7 @@ export function generateControllersModule(opts: ResolvedStimulusOptions, root: s
         controllers.set(identifier, {
             identifier,
             fetch: LAZY_COMMENT_RE.test(readFileSync(abs, 'utf8')) ? 'lazy' : 'eager',
-            // Emit a forward-slash path: a valid ESM import specifier on every OS (a Windows
-            // backslash path would be escaped in the generated string and is not a portable specifier).
+            // Forward slashes: a portable ESM specifier (a Windows backslash path isn't).
             main: abs.replace(/\\/g, '/'),
             autoimports: [],
         });
@@ -179,8 +163,7 @@ function listLocalControllers(dir: string): string[] {
         entries
             .map((e) => String(e).replace(/\\/g, '/'))
             .filter((e) => LOCAL_CONTROLLER_RE.test(e))
-            // Sort so the generated module -- and therefore its content hash -- stays stable
-            // regardless of the filesystem's iteration order. See symfony/ux#3703.
+            // Sort so the module (and its content hash) is stable across FS order. See symfony/ux#3703.
             .sort()
     );
 }