fix: normalize BrightScript hex literals in enum/const values

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+-   Enum and const values containing BrightScript hex literals (`&hFF0000FF`) are now normalized to valid JS syntax (`0xFF0000FF`) before being emitted, instead of breaking jsdoc's parser ([#14](https://github.com/markwpearce/brighterscript-jsdocs-plugin/issues/14))
+
 ### Added
 
 -   Support for BrighterScript v1 type syntax in doc comments: union types (`string or integer` → `{(string|integer)}`), typed arrays (`string[]` → `{Array.<string>}`, including arrays of custom class/interface types), and intersection types (`A and B`, which fall back to `{dynamic}` since JSDoc's type grammar has no intersection operator)

examples/source/testEnum.bs

@@ -13,4 +13,11 @@ namespace Alpha
     East = 2
     West = 3
   end enum
-end namespace
+end namespace
+
+' ARGB colors, expressed as BrightScript hex literals
+enum ArgbColors
+  Black = &h000000FF
+  White = &hFFFFFFFF
+  TransparentRed = &hFF000080
+end enum

src/convert-brighterscript-docs.spec.ts

@@ -382,6 +382,24 @@ describe('convertBrighterscriptDocs', () => {
                 };
             `);
         });
+
+        it('normalizes hex literals for enum member values', () => {
+            expectOutput(cbd.convertBrighterscriptDocs(`
+                enum Colors
+                    Black = &h000000FF
+                    White = &hFFFFFFFF
+                end enum
+            `), `
+                /**
+                 * @readonly
+                 * @enum
+                 */
+                var Colors = {
+                Black: 0x000000FF,
+                White: 0xFFFFFFFF,
+                };
+            `);
+        });
     });
 
     describe('interfaces', () => {
@@ -508,6 +526,19 @@ describe('convertBrighterscriptDocs', () => {
                     alpha.MY_CONSTANT = MY_CONSTANT;
             `);
         });
+
+        it('normalizes hex literals for constant values', () => {
+            expectOutput(cbd.convertBrighterscriptDocs(`
+                    const MY_CONSTANT = &hFF0000FF
+                `), `
+                    /**
+                     * @readonly
+                     * @constant
+                     * @default
+                     */
+                    var MY_CONSTANT = 0xFF0000FF;
+            `);
+        });
     });
 
     describe('comment adjacency', () => {

src/convert-brighterscript-docs.ts

@@ -18,6 +18,14 @@ const escapeCharEntities = {
 
 const typeGetOptions: bs.GetTypeOptions = { flags: bs.SymbolTypeFlag.typetime };
 
+/**
+ * Converts BrightScript hex literal tokens (`&hFF`) to valid JS literal syntax (`0xFF`) so
+ * jsdoc's parser doesn't choke on the raw BrightScript source text.
+ */
+function normalizeBrightScriptNumericLiteral(value: string): string {
+    return value.replace(/&([Hh])([0-9A-Fa-f]+)/g, '0x$2');
+}
+
 
 interface PluginOptions {
     addModule?: boolean;
@@ -555,7 +563,7 @@ function processEnum(enumStatement: bs.EnumStatement, moduleName = '', namespace
         if (memberCommentLines.length) {
             output.push(...convertCommentTextToJsDocLines(memberCommentLines), ' */');
         }
-        output.push(`${enumMember.name}: ${enumMember.getValue()},`);
+        output.push(`${enumMember.name}: ${normalizeBrightScriptNumericLiteral(enumMember.getValue())},`);
     }
     output.push('};');
 
@@ -576,7 +584,7 @@ function processConst(constStatement: bs.ConstStatement, moduleName = '', namesp
     output.push(...commentLines);
     let valueOutput = {};
     if (bs.isLiteralExpression(constStatement.value)) {
-        valueOutput = constStatement.value.tokens.value.text;
+        valueOutput = normalizeBrightScriptNumericLiteral(constStatement.value.tokens.value.text);
     }
     output.push(`var ${constStatement.name} = ${valueOutput};`);