Fake enums should not be exposed as globals (fixes #76)

Author: luttje

__tests__/api-writer/glua-api-writer.spec.ts

@@ -3,6 +3,7 @@ import { apiDefinition as hookApiDefinition, json as hookJson } from '../test-da
 // import { apiDefinition as libraryFunctionApiDefinition, json as libraryFunctionJson } from '../test-data/offline-sites/gmod-wiki/library-function-ai-getscheduleid';
 import { apiDefinition as structApiDefinition, markup as structMarkup, json as structJson } from '../test-data/offline-sites/gmod-wiki/struct-custom-entity-fields';
 // import { apiDefinition as enumApiDefinition, json as enumJson } from '../test-data/offline-sites/gmod-wiki/enums-use';
+import { apiDefinition as enumNavCornerApiDefinition, markup as enumNavCornerMarkup } from '../test-data/offline-sites/gmod-wiki/enums-navcorner';
 import { markup as panelMarkup, apiDefinition as panelApiDefinition } from '../test-data/offline-sites/gmod-wiki/panel-slider';
 import { markup as multiReturnFuncMarkup, apiDefinition as multiReturnFuncApiDefinition } from '../test-data/offline-sites/gmod-wiki/library-function-concommand-gettable';
 import { markup as varargsFuncMarkup, apiDefinition as varargsFuncApiDefinition } from '../test-data/offline-sites/gmod-wiki/library-function-coroutine-resume';
@@ -42,6 +43,23 @@ describe('GLua API Writer', () => {
     expect(api).toEqual(structApiDefinition);
   });
 
+  it('should be able to write Lua API definitions directly from wiki json data for a fake enum', async () => {
+    const writer = new GluaApiWriter();
+
+    fetchMock.mockResponseOnce(enumNavCornerMarkup);
+
+    const responseMock = <Response>{
+      url: 'https://wiki.facepunch.com/gmod/Enums/NavCorner?format=text',
+    };
+
+    const scrapeCallback = new WikiPageMarkupScraper(responseMock.url).getScrapeCallback();
+    const enums = await scrapeCallback(responseMock, enumNavCornerMarkup);
+    expect(enums).toHaveLength(1);
+    writer.writePages(enums, mockFilePath);
+    const api = writer.makeApiFromPages(writer.getPages(mockFilePath));
+    expect(api).toEqual(enumNavCornerApiDefinition);
+  });
+
   it('should handle deprecated in description', async () => {
     const writer = new GluaApiWriter();
 

__tests__/test-data/offline-sites/gmod-wiki/enums-navcorner.ts

@@ -0,0 +1,69 @@
+export const markup = `<enum>
+	<realm>Server</realm>
+	<description>
+Enumerations used by <page>CNavArea</page> methods.
+These Enums correspond to each corner of a <page>CNavArea</page>
+
+<warning>These enumerations do not exist in game and are listed here only for reference</warning>
+	</description>
+	<items>
+<item key="NORTH_WEST" value="0">North West Corner</item>
+<item key="NORTH_EAST" value="1">North East Corner</item>
+<item key="SOUTH_EAST" value="2">South East Corner</item>
+<item key="SOUTH_WEST" value="3">South West Corner</item>
+<item key="NUM_CORNERS" value="4">Represents all corners, only applicable to certain functions, such as <page>CNavArea:PlaceOnGround</page>.</item>
+	</items>
+
+</enum>`;
+
+export const json = {
+  url: 'https://wiki.facepunch.com/gmod/Enums/NavCorner',
+  type: 'enum',
+  name: 'NavCorner',
+  address: 'NavCorner',
+  description: `\nEnumerations used by <page>CNavArea</page> methods.\nThese Enums correspond to each corner of a <page>CNavArea</page>\n\n<warning>These enumerations do not exist in game and are listed here only for reference</warning>\n`,
+  realm: 'server',
+  items: [
+    {
+      key: 'NORTH_WEST',
+      value: '0',
+      description: 'North West Corner',
+    },
+    {
+      key: 'NORTH_EAST',
+      value: '1',
+      description: 'North East Corner',
+    },
+    {
+      key: 'SOUTH_EAST',
+      value: '2',
+      description: 'South East Corner',
+    },
+    {
+      key: 'SOUTH_WEST',
+      value: '3',
+      description: 'South West Corner',
+    },
+    {
+      key: 'NUM_CORNERS',
+      value: '4',
+      description: 'Represents all corners, only applicable to certain functions, such as CNavArea:PlaceOnGround.',
+    },
+  ],
+};
+
+export const apiDefinition = `---![(Server)](https://github.com/user-attachments/assets/d8fbe13a-6305-4e16-8698-5be874721ca1) Enumerations used by [CNavArea](https://wiki.facepunch.com/gmod/CNavArea) methods.
+--- These Enums correspond to each corner of a [CNavArea](https://wiki.facepunch.com/gmod/CNavArea)
+---
+--- **WARNING**: These enumerations do not exist in game and are listed here only for reference
+--- * \`NORTH_WEST\` = \`0\`
+--- * \`NORTH_EAST\` = \`1\`
+--- * \`SOUTH_EAST\` = \`2\`
+--- * \`SOUTH_WEST\` = \`3\`
+--- * \`NUM_CORNERS\` = \`4\`
+---
+--- [View wiki](https://wiki.facepunch.com/gmod/Enums/NavCorner)
+--- @alias NavCorner 0 | 1 | 2 | 3 | 4
+
+
+`;

src/api-writer/glua-api-writer.ts

@@ -78,6 +78,11 @@ export class GluaApiWriter {
     this.pageOverrides.set(safeFileName(pageAddress, '.'), override);
   }
 
+  private isFakeEnum(_enum: Enum) {
+    // TODO: Kindly ask Rubat to add a <isFake> marker of sorts to the wiki
+    return _enum.description.includes('**WARNING**: These enumerations do not exist in game and are listed here only for reference');
+  }
+
   public writePage(page: WikiPage) {
     const fileSafeAddress = safeFileName(page.address, '.');
     if (this.pageOverrides.has(fileSafeAddress)) {
@@ -280,22 +285,46 @@ export class GluaApiWriter {
       }
     };
 
-    for (const item of _enum.items)
-      writeItem(item.key, item);
+    if (!this.isFakeEnum(_enum)) {
+      for (const item of _enum.items)
+        writeItem(item.key, item);
+    }
 
     if (isContainedInTable) {
       api += '}';
     } else {
       // TODO: Clean up this workaround when LuaLS supports global enumerations.
       // Until LuaLS supports global enumerations (https://github.com/LuaLS/lua-language-server/issues/2721) we
       // will use @alias as a workaround.
-      // LuaLS doesn't nicely display annotations for aliasses, hence this is commented
-      //api += `\n---${this.formatRealm(_enum.realm)} ${_enum.description ? `${wrapInComment(_enum.description)}` : ''}\n`;
-      api += `\n---@alias ${_enum.name}\n`;
 
-      for (const item of _enum.items) {
-        if (item.key !== '' && !isNaN(Number(item.value.trim()))) {
-          api += `---| \`${item.key}\`\n`;
+      // Some enums like SNDLVL are fake in the wiki and only listed for reference, so we render those such that the enums
+      // are explained in the annotation
+      if (this.isFakeEnum(_enum)) {
+        // First output the description
+        api += `---${this.formatRealm(_enum.realm)} ${_enum.description ? `${wrapInComment(_enum.description)}` : ''}\n`;
+        let enumValues = '';
+
+        for (const item of _enum.items) {
+          if (item.key !== '' && !isNaN(Number(item.value.trim()))) {
+            api += `--- * \`${item.key}\` = \`${item.value}\`\n`;
+            enumValues += `${item.value} | `;
+          }
+        }
+
+        enumValues = enumValues.slice(0, -3); // Remove trailing " | "
+
+        // Add wikilink
+        api += `---\n--- [View wiki](${_enum.url})\n`;
+        api += `--- @alias ${_enum.name} ${enumValues}\n`;
+      } else {
+        // LuaLS doesn't nicely display annotations for aliasses, hence this is commented
+        //api += `\n---${this.formatRealm(_enum.realm)} ${_enum.description ? `${wrapInComment(_enum.description)}` : ''}\n`;
+        api += `\n---@alias ${_enum.name}\n`;
+
+        for (const item of _enum.items) {
+          if (item.key !== '' && !isNaN(Number(item.value.trim()))) {
+            api += `---| \`${item.key}\`\n`;
+          }
         }
       }
     }

src/utils/metadata.ts

@@ -12,7 +12,7 @@ export type Metadata = {
 }
 
 export async function writeMetadata(url: string, outputDirectory: string): Promise<Metadata> {
-  const results = await scrapeAndCollect(new WikiHistoryPageScraper(path.join(url, '~recentchanges')));
+  const results = await scrapeAndCollect(new WikiHistoryPageScraper(url + '/~recentchanges'));
   const exists = promisify(fs.exists);
   const lastUpdate = results[0].history[0].dateTime;
 
@@ -29,7 +29,7 @@ export async function writeMetadata(url: string, outputDirectory: string): Promi
   return metadata;
 }
 
-export async function readMetadata(outputDirectory: string) : Promise<Metadata | undefined> {
+export async function readMetadata(outputDirectory: string): Promise<Metadata | undefined> {
   const metadataPath = path.join(outputDirectory, metadataFilename);
   const exists = promisify(fs.exists);