fix: align implementation with most recent specs (#9)

Upstream: arduino/arduino-cli#2460
Upstream: arduino/arduino-cli#2509

Closes: #8

Signed-off-by: dankeboy36 <[email protected]>

Author: dankeboy36

.vscode/settings.json

@@ -8,6 +8,6 @@
   "typescript.tsc.autoDetect": "off",
   "typescript.tsdk": "./node_modules/typescript/lib",
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": true
+    "source.fixAll.eslint": "explicit"
   }
 }

README.md

@@ -2,13 +2,9 @@
 
 Arduino FQBN (fully qualified board name)
 
-```
-VENDOR:ARCHITECTURE:BOARD_ID[:MENU_ID=OPTION_ID[,MENU2_ID=OPTION_ID ...]]
-```
-
-> ℹ️ [What's the FQBN string?](https://arduino.github.io/arduino-cli/latest/FAQ/#whats-the-fqbn-string)
+> ℹ️ [What's the FQBN string?](https://arduino.github.io/arduino-cli/dev/FAQ/#whats-the-fqbn-string)
 
-> ℹ️ Check the `{build.fqbn}` entry in the Arduino [Platform specification](https://arduino.github.io/arduino-cli/latest/platform-specification/#global-predefined-properties) for more details.
+> FQBN stands for Fully Qualified Board Name. It has the following format: `VENDOR:ARCHITECTURE:BOARD_ID[:MENU_ID=OPTION_ID[,MENU2_ID=OPTION_ID ...]]`, with each `MENU_ID=OPTION_ID` being an optional key-value pair configuration. Each field accepts letters (`A-Z` or `a-z`), numbers (`0-9`), underscores (`_`), dashes(`-`) and dots(`.`). The special character `=` is accepted in the configuration value. For a deeper understanding of how FQBN works, you should understand the [Arduino platform specification](https://arduino.github.io/arduino-cli/dev/platform-specification/).
 
 ## Install
 

src/__tests__/index.spec.ts

@@ -11,15 +11,35 @@ describe('fqbn', () => {
       assert.ok(valid('a:b:c:o1=v1'));
     });
 
+    it('should be OK with config option value is empty', () => {
+      assert.ok(valid('a:b:c:o1='));
+    });
+
     it('should be OK with multiple config options', () => {
       assert.ok(valid('a:b:c:o1=v1,o2=v2'));
     });
 
+    it("should be OK with multiple equal ('=') signs in the value part", () => {
+      assert.ok(valid('a:b:c:o1=v1='));
+    });
+
+    it('should be OK with empty vendor', () => {
+      assert.ok(valid(':avr:uno'));
+    });
+
+    it('should be OK with empty arch', () => {
+      assert.ok(valid('arduino::uno'));
+    });
+
+    it('should be OK with empty vendor and arch', () => {
+      assert.ok(valid('::uno'));
+    });
+
     it('should fail when invalid', () => {
       assert.strictEqual(valid('invalid'), undefined);
     });
 
-    it('should fail when has trailing comma', () => {
+    it('should fail when config key value is empty', () => {
       assert.strictEqual(valid('a:b:c:'), undefined);
     });
 
@@ -32,13 +52,21 @@ describe('fqbn', () => {
     });
 
     it('should fail when invalid config options syntax', () => {
-      assert.strictEqual(valid('a:b:c:o1=v1='), undefined);
+      assert.strictEqual(valid('a:b:c:o1=v1*'), undefined);
     });
 
     it('should fail when contains duplicate config options', () => {
       assert.strictEqual(valid('a:b:c:o1=v1,o1=v2'), undefined);
     });
 
+    it('should fail when has trailing comma (no config options)', () => {
+      assert.strictEqual(valid('a:b:c,'), undefined);
+    });
+
+    it('should fail when has trailing comma (with config options)', () => {
+      assert.strictEqual(valid('a:b:c:o1=v1,'), undefined);
+    });
+
     it('should fail when config options has trailing comma', () => {
       assert.strictEqual(valid('a:b:c:o1=v1,o2=v2,'), undefined);
     });
@@ -47,6 +75,10 @@ describe('fqbn', () => {
       assert.strictEqual(valid('a:b:c:o1=v1,,o2=v2'), undefined);
     });
 
+    it('should fail when config option key is empty', () => {
+      assert.strictEqual(valid('a:b:c:=v1'), undefined);
+    });
+
     it('should rethrow unhandled errors', () => {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const invalid: any = undefined;
@@ -64,6 +96,22 @@ describe('fqbn', () => {
         assert.strictEqual(fqbn.options, undefined);
       });
 
+      [
+        'ardui_no:av_r:un_o',
+        'arduin.o:av.r:un.o',
+        'arduin-o:av-r:un-o',
+        'arduin-o:av-r:un-o:a=b=c=d',
+      ].map((fqbn) =>
+        it(`should create: ${fqbn}`, () =>
+          assert.doesNotThrow(() => new FQBN(fqbn)))
+      );
+
+      ['arduin-o:av-r:un=o', 'arduin?o:av-r:uno', 'arduino:av*r:uno'].map(
+        (fqbn) =>
+          it(`should not create: ${fqbn}`, () =>
+            assert.throws(() => new FQBN(fqbn)))
+      );
+
       it('should create with a config option', () => {
         const fqbn = new FQBN('a:b:c:o1=v1');
         assert.strictEqual(fqbn.vendor, 'a');
@@ -88,7 +136,7 @@ describe('fqbn', () => {
       });
 
       it('should error when invalid config options syntax', () => {
-        assert.throws(() => new FQBN('a:b:c:o1='), /ConfigOptionError: .*/);
+        assert.throws(() => new FQBN('a:b:c:=v1'), /ConfigOptionError: .*/);
       });
 
       it('should error when has duplicate config options', () => {

src/index.ts

@@ -26,20 +26,42 @@ export class FQBN {
   readonly options?: Readonly<ConfigOptions>;
 
   constructor(fqbn: string) {
-    const [vendor, arch, boardId, rest] = fqbn.split(':');
-    if (!vendor || !arch || !boardId) {
+    const fqbnSegments = fqbn.split(':');
+    if (fqbnSegments.length < 3 || fqbnSegments.length > 4) {
+      throw new InvalidFQBNError(fqbn);
+    }
+    for (let i = 0; i < 3; i++) {
+      if (!/^[a-zA-Z0-9_.-]*$/.test(fqbnSegments[i])) {
+        throw new InvalidFQBNError(fqbn);
+      }
+    }
+    const [vendor, arch, boardId, rest] = fqbnSegments;
+    if (!boardId) {
       throw new InvalidFQBNError(fqbn);
     }
 
     const options: Record<string, string> = {};
     if (typeof rest === 'string') {
       const tuples = rest.split(',');
       for (const tuple of tuples) {
-        const [key, value, unexpected] = tuple.split('=');
-        if (!key || !value || typeof unexpected === 'string') {
+        const configSegments = tuple.split('=', 2);
+        if (configSegments.length !== 2) {
+          throw new ConfigOptionError(
+            fqbn,
+            `Invalid config option: '${tuple}'`
+          );
+        }
+        const [key, value] = configSegments;
+        if (!/^[a-zA-Z0-9_.-]+$/.test(key)) {
+          throw new ConfigOptionError(
+            fqbn,
+            `Invalid config option key: '${key}' (${tuple})`
+          );
+        }
+        if (!/^[a-zA-Z0-9=_.-]*$/.test(value)) {
           throw new ConfigOptionError(
             fqbn,
-            `Invalid config option syntax: '${tuple}'`
+            `Invalid config option value: '${value}' (${tuple})`
           );
         }
         const existingValue = options[key];