Added some rudimentary EnumUtil.MakeEnum support

Author: Numynum

README.md

@@ -20,9 +20,10 @@ Generated annotations are limited to
    - Frame Templates
    - Intrinsic Frame Templates
    - Limited support for inheritance, children, and <KeyValues>
- - Globals with a name ending in `Mixin`; some mixins may be missing
+ - Mixins - some mixins, especially local ones, may be missing
    - "methods" for a given mixin
    - inheritance through `CreateFromMixins`
+- Enums created with `EnumUtil.MakeEnum`
 
 Disclaimer: Generated annotations by their very nature are not 100% accurate and may be imprecise or missing altogether.
 

annotation_branch_readme.md

@@ -22,9 +22,10 @@ Generated annotations are limited to
     - Frame Templates
     - Intrinsic Frame Templates
     - Limited support for inheritance, children, and <KeyValues>
-- Globals with a name ending in `Mixin`; some mixins may be missing
+- Mixins - some mixins, especially local ones, may be missing
     - "methods" for a given mixin
     - inheritance through `CreateFromMixins`
+- Enums created with `EnumUtil.MakeEnum`
 
 Disclaimer: Generated annotations by their very nature are not 100% accurate and may be imprecise or missing altogether.
 

bin/annotate

@@ -118,6 +118,7 @@ require_once __DIR__ . '/../vendor/autoload.php';
             $progressBar->advance();
         }
         $xmlFileParser->writeTemplatesFile('_templates.lua', $outputDir);
+        $luaFileParser->writeEnumsFile('_enums.lua', $outputDir);
         $progressBar->finish();
 
         $io->success('Done!');

src/LuaFileParser.php

@@ -4,10 +4,15 @@
 
 namespace App;
 
+/**
+ * @phpstan-type AnnotationData array{lineNr: int, classAnnotation: string, annotated: string}
+ */
 class LuaFileParser
 {
     /** @var array<string, array<string, array{lineNr: int, classAnnotation: string, annotated: string}> [filename => [mixin name => mixin data]] */
     private array $mixins = [];
+    /** @var array<string, list<array{lineNr: int, enumAnnotation: null|string, typeAnnotation: string}>> [filename => list of enum data] */
+    private array $enums = [];
     /** @var array<string, array<string, string> [filename => [function name => function data]] */
     private array $functions = [];
 
@@ -21,7 +26,9 @@ public function parse(string $filename, string $prefixToStrip, ?string $linkPref
         $fileContents = file_get_contents($filename);
         if (str_starts_with($filename, $prefixToStrip)) {
             $linkFilename = substr($filename, strlen($prefixToStrip));
-            $linkPrefix = $linkPrefix ? str_replace('//', '/', $linkPrefix . '/' . $linkFilename) : null;
+            $linkPrefix = $linkPrefix
+                ? sprintf('%s/%s', rtrim($linkPrefix, '/'), ltrim($linkFilename, '/'))
+                : null;
         }
 
         $mixins = $this->extractMixins($fileContents, $linkPrefix);
@@ -30,6 +37,8 @@ public function parse(string $filename, string $prefixToStrip, ?string $linkPref
         if (!$this->mixAnnotationsIntoSource) {
             $functions = $this->extractFunctions($fileContents, $mixins, $linkPrefix);
             $this->functions[$filename] = $functions;
+        } else {
+            $this->enums[$filename] = $this->extractEnums($fileContents, $linkPrefix);
         }
     }
 
@@ -41,6 +50,9 @@ public function writeAnnotationsToFile(string $filename, string $outDir, string
             foreach ($this->mixins[$filename] ?? [] as $funcInfo) {
                 $byLine[$funcInfo['lineNr'] - 1] .= $funcInfo['classAnnotation'];
             }
+            foreach ($this->enums[$filename] ?? [] as $enumInfo) {
+                $byLine[$enumInfo['lineNr'] - 1] .= $enumInfo['typeAnnotation'];
+            }
             $data = implode("\n", $byLine);
         } else {
             if (empty($this->mixins[$filename]) && empty($this->functions[$filename])) {
@@ -62,6 +74,25 @@ public function writeAnnotationsToFile(string $filename, string $outDir, string
         file_put_contents($targetFile, $data);
     }
 
+    public function writeEnumsFile(string $filename, string $outDir): void
+    {
+        $targetFile = $outDir . '/' . $filename . '.annotated.lua';
+        if (!is_dir(dirname($targetFile))) {
+            mkdir($outDir . '/' . dirname($filename), recursive: true);
+        }
+
+        $data = "--- @meta _\n\n";
+        foreach ($this->enums as $enums) {
+            foreach ($enums as $enumInfo) {
+                if ($enumInfo['enumAnnotation']) {
+                    $data .= $enumInfo['enumAnnotation'] . "\n\n";
+                }
+            }
+        }
+
+        file_put_contents($targetFile, $data);
+    }
+
     private function extractMixins(string $fileContents, ?string $linkPrefix): array
     {
         $mixins = [];
@@ -194,6 +225,88 @@ private function extractFunctions(string $fileContents, array $mixins, ?string $
         return $functions;
     }
 
+    private function extractEnums(string $fileContents, ?string $linkPrefix): array
+    {
+        $enums = [];
+        // e.g. `local foo = EnumUtil.MakeEnum("firstValue", "secondValue", "Value3")`
+        // e.g. `foo = EnumUtil.MakeEnum("firstValue", "secondValue", "Value3")`
+        // e.g. `Something.Foo = EnumUtil.MakeEnum("firstValue", "secondValue", "Value3")`
+        $regex = '/^(?<local>local )?(?<name>\S+) = EnumUtil\.MakeEnum\((?<values>(?:\s*"[^",]+?",?\s*(?:--\s*(?<comment>[^\n]+\n))?)+)\)/m';
+        $valueRegex = '/(?<value>"[^",]+?"),?\s*(?:--\s*(?<comment>[^\n]+))?/m';
+        $matches = [];
+        preg_match_all(
+            $regex,
+            $fileContents,
+            $matches,
+            PREG_SET_ORDER | PREG_OFFSET_CAPTURE,
+        );
+        foreach ($matches as $match) {
+            $isLocal = $match['local'][1] !== -1;
+            $enumName = $match['name'][0];
+            $enumValuesRaw = $match['values'][0];
+            $enumValues = [];
+            $valueComments = [];
+            $valueMatches = [];
+            preg_match_all($valueRegex, $enumValuesRaw, $valueMatches, PREG_SET_ORDER | PREG_OFFSET_CAPTURE);
+            foreach ($valueMatches as $valueMatch) {
+                $value = $valueMatch['value'][0];
+                if (isset($valueMatch['comment']) && $valueMatch['comment'][1] !== -1) {
+                    $valueComments[] = ' -- ' . $valueMatch['comment'][0];
+                } else {
+                    $valueComments[] = '';
+                }
+                $enumValues[] = $value;
+            }
+
+            // --- @type {["firstValue"] = 1, ["secondValue"] = 2, ["value3"] = 3}
+            $typeAnnotation = sprintf(
+                '--- @type {%s}',
+                implode(
+                    ', ',
+                    array_map(
+                        fn (string $v, int $i) => sprintf(
+                            '[%s]: %d',
+                            str_replace("\n", ' ', $v),
+                            $i + 1,
+                        ),
+                        $enumValues,
+                        array_keys($enumValues),
+                    ),
+                ),
+            );
+            $lineNr = $this->getLineNrFromOffset($fileContents, $match['name'][1]);
+            if ($isLocal) {
+                $enumAnnotation = null;
+            } else {
+                $typeAnnotation .= sprintf(' See [%s](lua://%s)', $enumName, $enumName);
+                $enumAnnotation = sprintf(
+                    "--- @enum %s\nlocal %s = {\n    %s\n}",
+                    $enumName,
+                    str_replace('.', '_', $enumName),
+                    implode(
+                        "\n    ",
+                        array_map(
+                            fn (string $v, int $i, string $comment) => sprintf('[%s] = %d,%s', $v, $i + 1, $comment),
+                            $enumValues,
+                            array_keys($enumValues),
+                            $valueComments,
+                        ),
+                    ),
+                );
+                if ($linkPrefix) {
+                    $enumAnnotation = "--- [Source]($linkPrefix#L$lineNr)\n$enumAnnotation";
+                }
+            }
+            $enums[] = [
+                'lineNr' => $lineNr,
+                'enumAnnotation' => $enumAnnotation,
+                'typeAnnotation' => $typeAnnotation,
+            ];
+        }
+
+        return $enums;
+    }
+
     private function getLineNrFromOffset(string $file, int $offset): int
     {
         return substr_count($file, "\n", 0, $offset) + 1;

src/XmlFileParser.php

@@ -173,7 +173,9 @@ public function writeAnnotationsToFile(string $filename, string $outDir, string
 
         if (str_starts_with($filename, $prefixToStrip)) {
             $filename = substr($filename, strlen($prefixToStrip));
-            $linkPrefix = $linkPrefix ? str_replace('//', '/', $linkPrefix . '/' . $filename) : null;
+            $linkPrefix = $linkPrefix
+                ? sprintf('%s/%s', rtrim($linkPrefix, '/'), ltrim($filename, '/'))
+                : null;
         }
         $targetFile = $outDir . '/' . $filename . '.annotated.lua';
         if (!is_dir(dirname($targetFile))) {