refactor(translator): replace global variable with singleton pattern

- Replace global $translator variable with Translator::getInstance() method
- Add singleton instance management to Translator class
- Update compiler.php to use singleton pattern instead of global variable
- Update gen_stub.php to use getTranslator() helper function
- Add translator instance test to verify singleton behavior
- Remove unnecessary global declarations throughout codebase

phpunit/src/TranslatorInstanceTest.php

@@ -0,0 +1,19 @@
+<?php
+
+use TypePhp\CompilerTest;
+use TypePhp\Translator;
+use function TypePhp\StubGenerator\getTranslator;
+
+final class TranslatorInstanceTest extends BaseTest
+{
+    public function testLatestTranslatorInstanceIsUsedByStubGenerator(): void
+    {
+        $first = CompilerTest::create(TYPEPHP_ROOT_PATH);
+        self::assertSame($first, Translator::getInstance());
+        self::assertSame($first, getTranslator());
+
+        $second = CompilerTest::create(TYPEPHP_ROOT_PATH);
+        self::assertSame($second, Translator::getInstance());
+        self::assertSame($second, getTranslator());
+    }
+}

src/Translator.php

@@ -60,6 +60,9 @@ use function TypePhp\StubGenerator\generateStubFile;
 
 class Translator extends Preprocessor
 {
+    /** Active compiler used by the upstream-derived stub generator. */
+    private static ?Translator $instance = null;
+
     private const string TRAIT_ORIGIN_ATTRIBUTE = 'typephp_trait_origin';
     private const string TRAIT_METHOD_ATTRIBUTE = 'typephp_trait_method';
     use DefaultArgumentGenerator;
@@ -154,6 +157,15 @@ class Translator extends Preprocessor
 
         // Detect the OS, the compiler, and (on Windows) the PHP lib files.
         $this->detectPlatform();
+        self::$instance = $this;
+    }
+
+    public static function getInstance(): Translator
+    {
+        if (self::$instance === null) {
+            self::$instance = new self(TYPEPHP_ROOT_PATH);
+        }
+        return self::$instance;
     }
 
     protected function loadInternalConstants(): array

src/compiler.php

@@ -53,9 +53,7 @@ function main(int $argc, array $argv): void
         return;
     }
 
-    global $translator;
-
-    $translator = new Translator(TYPEPHP_ROOT_PATH);
+    $translator = Translator::getInstance();
     $translator->setIndent('    ');
     // Scan all PHP files and preprocess them.
     $files = $translator->prepare($translator->parseArgv($argv));

src/gen_stub.php

@@ -120,8 +120,7 @@ function processStubFile(string $stubFile, Context $context, bool $includeOnly =
         }
 
         if (!$includeOnly) {
-            global $translator;
-            $stubFilenameWithoutExtension = $translator->getArgInfoStubFilename($stubFile);
+            $stubFilenameWithoutExtension = getTranslator()->getArgInfoStubFilename($stubFile);
             $arginfoFile = $context->objectFile;
             $legacyFile = "{$stubFilenameWithoutExtension}_legacy_arginfo.h";
 
@@ -6817,8 +6816,7 @@ function normalizeConstExprValue(mixed $constValue): mixed
 
 function getTranslator(): Translator
 {
-    global $translator;
-    return $translator;
+    return Translator::getInstance();
 }
 
 /**