bug #31 [Stimulus] Report a clear error for a missing or malformed controllers.json (Kocal)

This PR was merged into the main branch.

Discussion
----------

[Stimulus] Report a clear error for a missing or malformed controllers.json

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

When the `stimulus` option pointed at a `controllers.json` that was missing or contained invalid JSON, `generateControllersModule` threw a raw Node error (`ENOENT`, or a bare `SyntaxError`) instead of the clear ``@symfony`/reprise:`-prefixed message the rest of that module already uses for every other failure (package not installed, controller not declared, etc.).

This PR wraps the read and parse so a missing file and malformed JSON each produce an actionable ``@symfony`/reprise:` error naming the file, consistent with the module's other error paths.

Adds tests for both cases, plus a malformed JSON fixture. It's a pure core change, so it covers both bundlers through the shared `generateControllersModule`.

Commits
-------

8690952 [Stimulus] Report a clear error for a missing or malformed controllers.json

Author: Kocal

assets/src/core/stimulus.ts

@@ -48,12 +48,37 @@ 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$/;
 
+// Every other failure in this module reports a `@symfony/reprise:` error; a missing or malformed
+// controllers.json must not slip through as a raw Node ENOENT/SyntaxError.
+function readControllersJson(controllersJson: string): ControllersJson {
+    let raw: string;
+    try {
+        raw = readFileSync(controllersJson, 'utf8');
+    } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+            throw new Error(
+                `@symfony/reprise: cannot read the Stimulus controllers file "${controllersJson}". ` +
+                    'Create it, or point the "stimulus" option at the right path.'
+            );
+        }
+        throw err;
+    }
+    try {
+        return JSON.parse(raw) as ControllersJson;
+    } catch (err) {
+        throw new Error(
+            `@symfony/reprise: the Stimulus controllers file "${controllersJson}" is not valid JSON` +
+                `${err instanceof Error ? ` (${err.message})` : ''}.`
+        );
+    }
+}
+
 export function generateControllersModule(opts: ResolvedStimulusOptions, root: string, isDev: boolean): string {
     // 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'));
-    const json = JSON.parse(readFileSync(opts.controllersJson, 'utf8')) as ControllersJson;
+    const json = readControllersJson(opts.controllersJson);
 
     for (const packageName of Object.keys(json.controllers ?? {})) {
         let pkg: { symfony?: { controllers?: Record<string, PackageControllerConfig> } };

assets/test/core/stimulus.test.ts

@@ -38,6 +38,26 @@ describe('generateControllersModule — third-party', () => {
     });
 });
 
+describe('generateControllersModule — controllers.json errors', () => {
+    it('throws a clear error when the controllers.json file is missing', () => {
+        const missing = {
+            controllersJson: join(root, 'no-such-controllers.json'),
+            controllersDir: opts.controllersDir,
+        };
+        expect(() => generateControllersModule(missing, root, false)).toThrow(
+            /@symfony\/reprise: cannot read the Stimulus controllers file/
+        );
+    });
+
+    it('throws a clear error when the controllers.json file is not valid JSON', () => {
+        const malformed = {
+            controllersJson: join(root, 'malformed-controllers.json'),
+            controllersDir: opts.controllersDir,
+        };
+        expect(() => generateControllersModule(malformed, root, false)).toThrow(/is not valid JSON/);
+    });
+});
+
 describe('generateControllersModule — local', () => {
     const localOpts = { controllersJson: join(root, 'controllers.json'), controllersDir: join(root, 'controllers') };
 

assets/test/fixtures/stimulus/malformed-controllers.json

@@ -0,0 +1 @@
+{ "controllers": { this is not valid json }