bug #10 [Stimulus] Detect preserved /*! ... */ lazy comments and lock deterministic ordering (Kocal)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Stimulus] Detect preserved `/*! ... */` lazy comments and lock deterministic ordering

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | no
| Deprecations? | no
| Issues        | -
| License       | MIT

Reprise's Stimulus virtual module (`assets/src/core/stimulus.ts`) reimplements StimulusBundle's `ControllersMapGenerator` for bundlers, since the webpack loader Encore relied on doesn't exist outside webpack. StimulusBundle just merged two small fixes to that PHP generator, so this PR ports both to the TS side. Two commits, one per upstream PR.

**1. Detect the preserved `/*! stimulusFetch: 'lazy' */` comment form** (port of symfony/ux#3702)

A controller opts into lazy loading by adding a `stimulusFetch: 'lazy'` comment above its class. The problem: tsc and esbuild strip regular block comments during minification, but keep "preserved" ones written as `/*! ... */`. Reprise's lazy-detection regex only matched the plain `/* ... */` form, so the marker was lost as soon as the controller went through a minifying build. This adds the optional `!` to the block-comment branch so both forms are detected. New fixture controller + test included.

**2. Sort local controllers for a deterministic loader output** (port of symfony/ux#3703)

Upstream, controllers were iterated in filesystem order, so the generated loader (and its content hash) could shift between builds even with no actual change, breaking cache busting. Reprise already sorts its local controllers (`listLocalControllers` ends with `.sort()`), so there's no behavior change here. This commit just adds a regression test that pins the exact emission order, plus a comment explaining why the sort matters.

All tests pass (`assets/test`), and `oxlint`/`oxfmt` are clean. Added a short docs note in `doc/index.rst` for the preserved-comment form.

Commits
-------

16caeb7 [Stimulus] Detect preserved `/*! ... */` lazy comments and lock deterministic ordering

Author: Kocal

assets/src/core/stimulus.ts

@@ -54,8 +54,10 @@ interface ResolvedController {
 // 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;
+    /(?:\/\*!?\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 {
@@ -173,10 +175,14 @@ function listLocalControllers(dir: string): string[] {
     } catch {
         return []; // dir absent -> no local controllers
     }
-    return entries
-        .map((e) => String(e).replace(/\\/g, '/'))
-        .filter((e) => LOCAL_CONTROLLER_RE.test(e))
-        .sort();
+    return (
+        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()
+    );
 }
 
 function localIdentifier(rel: string): string {

assets/test/core/stimulus.test.ts

@@ -59,6 +59,13 @@ describe('generateControllersModule — local', () => {
         expect(src).toContain(posix(join(root, 'controllers/single_line_controller.js')));
     });
 
+    it('detects the lazy marker inside a preserved /*! ... */ comment', () => {
+        const src = generateControllersModule(localOpts, root, false);
+        // tsc/esbuild keep `/*! ... */` comments through minification, so the marker survives.
+        expect(src).toContain(`"preserved-comment": () => import(`);
+        expect(src).toContain(posix(join(root, 'controllers/preserved_comment_controller.js')));
+    });
+
     it('ignores a lazy marker that sits above the imports (it must be directly above the class)', () => {
         const src = generateControllersModule(localOpts, root, false);
         // The marker in `above_imports_controller.js` precedes the imports, not the class,
@@ -78,6 +85,26 @@ describe('generateControllersModule — local', () => {
         expect(src).toContain('export const eagerControllers = {}');
         expect(src).toContain('export const lazyControllers = {}');
     });
+
+    it('emits controllers in a stable, name-sorted order (deterministic output/hash)', () => {
+        // Local controllers are sorted by filename so the generated module -- and thus its
+        // content hash -- stays stable regardless of the order the filesystem returns the files
+        // in (symfony/ux#3703). Assert the exact identifier order the module is rendered in.
+        const src = generateControllersModule(localOpts, root, false);
+        const identifiers = [...src.matchAll(/^ {2}"([^"]+)":/gm)].map((m) => m[1]);
+        expect(identifiers).toEqual([
+            // eagerControllers: third-party first, then local controllers sorted by filename
+            'acme--ux-hello--hello',
+            'above-imports',
+            'admin--user',
+            'greet',
+            // lazyControllers: third-party first, then local controllers sorted by filename
+            'acme--ux-map--map',
+            'heavy',
+            'preserved-comment',
+            'single-line',
+        ]);
+    });
 });
 
 describe('generateControllersModule — identifier collision', () => {

assets/test/fixtures/stimulus/controllers/preserved_comment_controller.js

@@ -0,0 +1,2 @@
+/*! stimulusFetch: 'lazy' */
+export default class {}

doc/index.rst

@@ -119,7 +119,9 @@ imports) — a block or a single-line comment both work:
     /* stimulusFetch: 'lazy' */
     export default class extends Controller {}
 
-(``// stimulusFetch: 'lazy'`` on the line above the class works too.)
+(``// stimulusFetch: 'lazy'`` on the line above the class works too, as does a
+preserved ``/*! stimulusFetch: 'lazy' */`` comment — the form tsc and esbuild keep
+through minification.)
 
 **Third-party UX packages.** Controllers declared in ``controllers.json`` are
 resolved from ``node_modules``, so install them with your package manager, the