feat: remove process.exit(1) (#1231)

Author: davidturnbull

.changeset/compiler-error-handling.md

@@ -0,0 +1,5 @@
+---
+"@lingo.dev/_compiler": patch
+---
+
+Compiler now throws errors instead of abruptly exiting the process, allowing parent applications to handle errors gracefully

packages/compiler/src/index.ts

@@ -79,8 +79,7 @@ const unplugin = createUnplugin<Partial<typeof defaultParams> | undefined>(
           params.targetLocales,
         );
         if (invalidLocales.length > 0) {
-          console.log(dedent`
-            \n
+          throw new Error(dedent`
             ⚠️  Lingo.dev Localization Compiler requires LLM model setup for the following locales: ${invalidLocales.join(
               ", ",
             )}.
@@ -89,10 +88,7 @@ const unplugin = createUnplugin<Partial<typeof defaultParams> | undefined>(
             1. Refer to documentation for help: https://lingo.dev/compiler
             2. If you want to use a different LLM, raise an issue in our open-source repo: https://lingo.dev/go/gh
             3. If you have questions, feature requests, or would like to contribute, join our Discord: https://lingo.dev/go/discord
-
-            ✨
           `);
-          process.exit(1);
         }
       }
     }
@@ -429,16 +425,15 @@ function validateLLMKeyDetails(configuredProviders: string[]): void {
         `);
     }
 
-    console.log(dedent`
+    const errorMessage = dedent`
       \n
       ⭐️ Also:
       1. If you want to use a different LLM, update your configuration. Refer to documentation for help: https://lingo.dev/compiler
       2. If the model/provider you want to use isn't supported yet, raise an issue in our open-source repo: https://lingo.dev/go/gh
       3. If you have questions, feature requests, or would like to contribute, join our Discord: https://lingo.dev/go/discord
-
-      ✨
-    `);
-    process.exit(1);
+    `;
+    console.log(errorMessage);
+    throw new Error("Missing required LLM API keys. See details above.");
   } else if (foundProviders.length > 0) {
     console.log(dedent`
         \n

packages/compiler/src/lib/lcp/api/index.ts

@@ -397,38 +397,33 @@ export class LCPAPI {
    * The message explains why this situation is unusual and how to fix it.
    * @param providerId The ID of the LLM provider whose key is missing.
    */
-  private static _failMissingLLMKeyCi(providerId: string): void {
+  private static _failMissingLLMKeyCi(providerId: string): never {
     let details = providerDetails[providerId];
     if (!details) {
       // Fallback for unsupported provider in failure message logic
-      console.error(
+      throw new Error(
         `Internal Error: Missing details for provider "${providerId}" when reporting missing key in CI/CD. You might be using an unsupported provider.`,
       );
-      process.exit(1);
     }
 
-    console.log(
-      dedent`
-        \n
-        💡 You're using Lingo.dev Localization Compiler, and it detected unlocalized components in your app.
-
-        The compiler needs a ${details.name} API key to translate missing strings, but ${details.apiKeyEnvVar} is not set in the environment.
+    const errorMessage = dedent`
+      💡 You're using Lingo.dev Localization Compiler, and it detected unlocalized components in your app.
 
-        This is unexpected: typically you run a full build locally, commit the generated translation files, and push them to CI/CD.
+      The compiler needs a ${details.name} API key to translate missing strings, but ${details.apiKeyEnvVar} is not set in the environment.
 
-        However, If you want CI/CD to translate the new strings, provide the key with:
-        • Session-wide: export ${details.apiKeyEnvVar}=<your-api-key>
-        • Project-wide / CI: add ${details.apiKeyEnvVar}=<your-api-key> to your pipeline environment variables
+      This is unexpected: typically you run a full build locally, commit the generated translation files, and push them to CI/CD.
 
-        ⭐️ Also:
-        1. If you don't yet have a ${details.name} API key, get one for free at ${details.getKeyLink}
-        2. If you want to use a different LLM, update your configuration. Refer to documentation for help: https://lingo.dev/compiler
-        3. If the model you want to use isn't supported yet, raise an issue in our open-source repo: https://lingo.dev/go/gh
+      However, If you want CI/CD to translate the new strings, provide the key with:
+      • Session-wide: export ${details.apiKeyEnvVar}=<your-api-key>
+      • Project-wide / CI: add ${details.apiKeyEnvVar}=<your-api-key> to your pipeline environment variables
 
-        ✨
-      `,
-    );
-    process.exit(1);
+      ⭐️ Also:
+      1. If you don't yet have a ${details.name} API key, get one for free at ${details.getKeyLink}
+      2. If you want to use a different LLM, update your configuration. Refer to documentation for help: https://lingo.dev/compiler
+      3. If the model you want to use isn't supported yet, raise an issue in our open-source repo: https://lingo.dev/go/gh
+    `;
+    console.log(errorMessage);
+    throw new Error(`Missing ${details.name} API key in CI/CD environment.`);
   }
 
   /**
@@ -442,44 +437,39 @@ export class LCPAPI {
     providerId: string,
     targetLocale: string,
     errorMessage: string,
-  ): void {
+  ): never {
     const details = providerDetails[providerId];
     if (!details) {
       // Fallback
-      console.error(
-        `Internal Error: Missing details for provider "${providerId}" when reporting local failure.`,
+      throw new Error(
+        `Internal Error: Missing details for provider "${providerId}" when reporting local failure. Original Error: ${errorMessage}`,
       );
-      console.error(`Original Error: ${errorMessage}`);
-      process.exit(1);
     }
 
     const isInvalidApiKey = errorMessage.match("Invalid API Key"); // TODO: This may change per-provider, so might update this later
 
     if (isInvalidApiKey) {
-      console.log(dedent`
-          \n
-          ⚠️  Lingo.dev Compiler requires a valid ${details.name} API key to translate your application.
-
-          It looks like you set ${details.name} API key but it is not valid. Please check your API key and try again.
+      const message = dedent`
+        ⚠️  Lingo.dev Compiler requires a valid ${details.name} API key to translate your application.
 
-          Error details from ${details.name} API: ${errorMessage}
+        It looks like you set ${details.name} API key but it is not valid. Please check your API key and try again.
 
-          👉 You can set the API key in one of the following ways:
-          1. User-wide: Run npx lingo.dev@latest config set ${details.apiKeyConfigKey} <your-api-key>
-          2. Project-wide: Add ${details.apiKeyEnvVar}=<your-api-key> to .env file in every project that uses Lingo.dev Localization Compiler
-          3 Session-wide: Run export ${details.apiKeyEnvVar}=<your-api-key> in your terminal before running the compiler to set the API key for the current session
+        Error details from ${details.name} API: ${errorMessage}
 
-          ⭐️ Also:
-          1. If you don't yet have a ${details.name} API key, get one for free at ${details.getKeyLink}
-          2. If you want to use a different LLM, raise an issue in our open-source repo: https://lingo.dev/go/gh
-          3. If you have questions, feature requests, or would like to contribute, join our Discord: https://lingo.dev/go/discord
+        👉 You can set the API key in one of the following ways:
+        1. User-wide: Run npx lingo.dev@latest config set ${details.apiKeyConfigKey} <your-api-key>
+        2. Project-wide: Add ${details.apiKeyEnvVar}=<your-api-key> to .env file in every project that uses Lingo.dev Localization Compiler
+        3 Session-wide: Run export ${details.apiKeyEnvVar}=<your-api-key> in your terminal before running the compiler to set the API key for the current session
 
-          ✨
-        `);
+        ⭐️ Also:
+        1. If you don't yet have a ${details.name} API key, get one for free at ${details.getKeyLink}
+        2. If you want to use a different LLM, raise an issue in our open-source repo: https://lingo.dev/go/gh
+        3. If you have questions, feature requests, or would like to contribute, join our Discord: https://lingo.dev/go/discord
+      `;
+      console.log(message);
+      throw new Error(`Invalid ${details.name} API key.`);
     } else {
-      console.log(
-        dedent`
-        \n
+      const message = dedent`
         ⚠️  Lingo.dev Compiler tried to translate your application to "${targetLocale}" locale via ${
           details.name
         } but it failed.
@@ -502,11 +492,11 @@ export class LCPAPI {
         }?
         2. Did you reach any limits of your ${details.name} account?
         3. If you have questions, feature requests, or would like to contribute, join our Discord: https://lingo.dev/go/discord
-
-        ✨
-      `,
+      `;
+      console.log(message);
+      throw new Error(
+        `Translation failed for locale "${targetLocale}" using ${details.name}: ${errorMessage}`,
       );
     }
-    process.exit(1);
   }
 }

packages/compiler/src/lib/lcp/index.spec.ts

@@ -34,32 +34,20 @@ describe("LCP", () => {
   });
 
   describe("ensureFile", () => {
-    let originalExit: any;
-    beforeEach(() => {
-      // stub exit to avoid existing the actual test process
-      originalExit = process.exit;
-      // @ts-expect-error override for test
-      process.exit = vi.fn();
-    });
-    afterEach(() => {
-      // restore mocked exit behavior
-      (process.exit as any) = originalExit;
-    });
-
-    it("creates meta.json and exists the process", () => {
+    it("creates meta.json and throws an error", () => {
       (fs.existsSync as any).mockReturnValueOnce(false);
-      LCP.ensureFile({ sourceRoot: "src", lingoDir: "lingo" });
+      expect(() => {
+        LCP.ensureFile({ sourceRoot: "src", lingoDir: "lingo" });
+      }).toThrow(/Lingo.dev Compiler detected missing meta.json file/);
       expect(fs.mkdirSync).toHaveBeenCalled();
       expect(fs.writeFileSync).toHaveBeenCalled();
-      expect(process.exit).toHaveBeenCalledWith(1);
     });
 
     it("does not create meta.json if it already exists", () => {
       (fs.existsSync as any).mockReturnValue(true);
       LCP.ensureFile({ sourceRoot: "src", lingoDir: "lingo" });
       expect(fs.mkdirSync).not.toHaveBeenCalled();
       expect(fs.writeFileSync).not.toHaveBeenCalled();
-      expect(process.exit).not.toHaveBeenCalled();
     });
   });
 

packages/compiler/src/lib/lcp/index.ts

@@ -29,19 +29,17 @@ export class LCP {
       }
       fs.writeFileSync(filePath, "{}");
 
-      console.log(dedent`
-          \n
-          ⚠️  Lingo.dev Compiler detected missing meta.json file in lingo directory. 
-          Please restart the build / watch command to regenerate all Lingo.dev Compiler files.
-        `);
       try {
         fs.rmdirSync(path.resolve(process.cwd(), ".next"), {
           recursive: true,
         });
       } catch (error) {
         // Ignore errors if directory doesn't exist
       }
-      process.exit(1);
+      throw new Error(dedent`
+        ⚠️  Lingo.dev Compiler detected missing meta.json file in lingo directory.
+        Please restart the build / watch command to regenerate all Lingo.dev Compiler files.
+      `);
     }
   }