Switch to new enums instead of alias

.github/workflows/release-gluals.yml

@@ -185,7 +185,7 @@ jobs:
         run: |
           npm run generate-lua -- \
             --output ./output \
-            --custom-overrides ./custom
+            -c ./custom
           npm run generate-plugin-index
           npm run generate-plugin-artifacts -- \
             --pluginRoot ./plugin \

.github/workflows/tests.yml

@@ -17,6 +17,8 @@ jobs:
           node-version: "22"
       - name: Install dependencies
         run: npm ci
+      - name: Generate output fixtures
+        run: npm run scrape-wiki
       - name: Run tests
         run: npm run ci:test
       - uses: coverallsapp/github-action@v2

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

@@ -10,6 +10,9 @@ import { markup as varargsFuncMarkup } from '../test-data/offline-sites/gmod-wik
 import { Enum, LibraryFunction, PanelFunction, WikiPage, WikiPageMarkupScraper } from '../../src/scrapers/wiki-page-markup-scraper';
 import { GluaApiWriter } from '../../src/api-writer/glua-api-writer';
 import fetchMock from "jest-fetch-mock";
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
 
 const mockFilePath = '<irrelevant for this test>';
 
@@ -29,6 +32,30 @@ describe('GLua API Writer', () => {
     expect(api).toContain('function GM:PlayerInitialSpawn(player, transition) end');
   });
 
+  it('emits panel hooks as panel-owned callback contracts', () => {
+    const markup = `
+<function name="OnNodeSelected" parent="DTree" type="panelhook">
+  <description>This function is called when a node within a tree is selected.</description>
+  <realm>Client and Menu</realm>
+  <args>
+    <arg name="node" type="Panel">The node that was selected.</arg>
+  </args>
+</function>`;
+    const response = <Response>{
+      url: 'https://wiki.facepunch.com/gmod/DTree:OnNodeSelected?format=text',
+    };
+    const [page] = new WikiPageMarkupScraper(response.url).getScrapeCallback()(response, markup) as WikiPage[];
+    const writer = new GluaApiWriter();
+    writer.writePages([page], mockFilePath);
+    const api = writer.makeApiFromPages(writer.getPages(mockFilePath));
+
+    expect(api).toContain('---@hook OnNodeSelected');
+    expect(api).toContain('---@realm client');
+    expect(api).toContain('---@realm menu');
+    expect(api).toContain('---@param node Panel The node that was selected.');
+    expect(api).toContain('function DTree:OnNodeSelected(node) end');
+  });
+
   it('should emit source and realm annotations when present', () => {
     const writer = new GluaApiWriter();
     const api = writer.writePage(<LibraryFunction>{
@@ -370,6 +397,88 @@ describe('GLua API Writer', () => {
     expect(api).toEqual(`${override}\n\n`);
   });
 
+  it('should replace planned structs with direct page overrides', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gluals-struct-override-'));
+    const outputPath = path.join(tmpDir, 'structures.lua');
+    const override = [
+      '---@class (partial) Custom_Entity_Fields',
+      '---@field custom string',
+      'local Custom_Entity_Fields = {}',
+    ].join('\n');
+    const writer = new GluaApiWriter(tmpDir);
+
+    try {
+      writer.addOverride(structJson.address, override);
+      writer.writePages([<WikiPage>structJson], outputPath);
+      writer.writeToDisk();
+
+      const api = fs.readFileSync(outputPath, 'utf8');
+      expect(api.match(/---@class \(partial\) Custom_Entity_Fields/g)).toHaveLength(1);
+      expect(api).toContain('---@field custom string');
+      expect(api).not.toContain('---@field GetEntityDriveMode function');
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it('should emit distinct direct and class overrides once across output files', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gluals-aliased-overrides-'));
+    const structuresOutputPath = path.join(tmpDir, 'structures.lua');
+    const toolOutputPath = path.join(tmpDir, 'tool.lua');
+    const classOverride = [
+      '---@class ToolObjectSlot',
+      '---@field Ent Entity',
+      '---@class Tool',
+      'Tool = Tool or {}',
+    ].join('\n');
+    const directOverride = [
+      '---@type boolean?',
+      'TOOL.AddToMenu = true',
+    ].join('\n');
+    const toolClass = <WikiPage>{
+      type: 'class',
+      address: 'Tool',
+      name: 'Tool',
+      description: 'Sandbox tool methods.',
+      realm: 'shared',
+      url: 'https://wiki.facepunch.com/gmod/Tool',
+      parent: '',
+    };
+    const toolStruct = <WikiPage>{
+      type: 'struct',
+      address: 'TOOL',
+      name: 'TOOL',
+      description: 'Sandbox tool definition.',
+      realm: 'shared',
+      url: 'https://wiki.facepunch.com/gmod/Structures/TOOL',
+      fields: [{
+        name: 'ScrapedOnly',
+        type: 'string',
+        description: 'A scraped field that the direct override replaces.',
+      }],
+    };
+    const writer = new GluaApiWriter(tmpDir);
+
+    try {
+      writer.addOverride('class.Tool', classOverride);
+      writer.addOverride('TOOL', directOverride);
+      writer.writePages([toolClass], toolOutputPath);
+      writer.writePages([toolStruct], structuresOutputPath);
+      writer.writeToDisk();
+
+      const api = [structuresOutputPath, toolOutputPath]
+        .filter(filePath => fs.existsSync(filePath))
+        .map(filePath => fs.readFileSync(filePath, 'utf8'))
+        .join('\n');
+      expect(api.match(/---@class ToolObjectSlot/g)).toHaveLength(1);
+      expect(api.match(/---@class Tool\n/g)).toHaveLength(1);
+      expect(api.match(/TOOL\.AddToMenu = true/g)).toHaveLength(1);
+      expect(api).not.toContain('ScrapedOnly');
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   it('should allow overriding specific class declarations', () => {
     const writer = new GluaApiWriter();
     const overrideStart = `---@class Custom_Entity_Fields : Parent`;
@@ -383,7 +492,7 @@ describe('GLua API Writer', () => {
     expect(api).toContain('---@field GetEntityDriveMode function');
   });
 
-  it('should create aliasses for global enumerations', () => {
+  it('should create flat enums for global enumerations', () => {
     const writer = new GluaApiWriter();
     const api = writer.writePage(<Enum>{
       type: 'enum',
@@ -418,9 +527,14 @@ describe('GLua API Writer', () => {
     expect(api).toContain('---@readonly\nMATERIAL_FOG_NONE = 0');
     expect(api).toContain('---@readonly\nMATERIAL_FOG_LINEAR = 1');
     expect(api).toContain('---@readonly\nMATERIAL_FOG_LINEAR_BELOW_FOG_Z = -2147483648');
-    expect(api).toContain('---@alias MATERIAL_FOG');
-    expect(api).toContain('---| number # Raw numeric enum value');
-    expect(api).toContain('---| 0 # MATERIAL_FOG_NONE');
+    expect(api).toContain('---@enum MATERIAL_FOG : number');
+    expect(api).toContain('---| MATERIAL_FOG_NONE # No fog');
+    expect(api).toContain('---| MATERIAL_FOG_LINEAR # Linear fog');
+    // A member without a wiki description carries no detail.
+    expect(api).toContain('---| MATERIAL_FOG_LINEAR_BELOW_FOG_Z\n');
+    // TODO values are skipped, and the enum no longer widens to bare `number`.
+    expect(api).not.toContain('MATERIAL_FOG_NEW_FAKE');
+    expect(api).not.toContain('---@alias MATERIAL_FOG');
   });
 
   it('should create enums for table enumerations', () => {