Add JSON schema for boards.txt

This schema defines the required data structure of the boards.txt configuration file of Arduino boards platforms.

Author: per1234

etc/schemas/arduino-boards-txt-definitions-schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/arduino/arduino-lint/main/etc/schemas/arduino-boards-txt-permissive-schema.json",
+  "title": "Arduino boards.txt JSON permissive schema",
+  "description": "boards.txt contains the boards definitions of Arduino platforms. See: https://arduino.github.io/arduino-cli/latest/platform-specification/#boardstxt",
+  "$comment": "For information on the boards.txt format, see https://godoc.org/github.com/arduino/go-properties-orderedmap",
+  "type": "object",
+  "properties": {
+    "menu": {
+      "$ref": "arduino-boards-txt-definitions-schema.json#/definitions/propertiesObjects/menu/permissive/object"
+    }
+  },
+  "patternProperties": {
+    "^([^m].*|m([^e].*)?|me([^n].*)?|men([^u].*)?|menu.+)$": {
+      "$ref": "arduino-boards-txt-definitions-schema.json#/definitions/propertiesObjects/boardID/permissive/object"
+    }
+  }
+}

etc/schemas/arduino-boards-txt-permissive-schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/arduino/arduino-lint/main/etc/schemas/arduino-boards-txt-schema.json",
+  "title": "Arduino boards.txt JSON schema",
+  "description": "boards.txt contains the boards definitions of Arduino platforms. See: https://arduino.github.io/arduino-cli/latest/platform-specification/#boardstxt",
+  "$comment": "For information on the boards.txt format, see https://godoc.org/github.com/arduino/go-properties-orderedmap",
+  "type": "object",
+  "properties": {
+    "menu": {
+      "$ref": "arduino-boards-txt-definitions-schema.json#/definitions/propertiesObjects/menu/specification/object"
+    }
+  },
+  "patternProperties": {
+    "^([^m].*|m([^e].*)?|me([^n].*)?|men([^u].*)?|menu.+)$": {
+      "$ref": "arduino-boards-txt-definitions-schema.json#/definitions/propertiesObjects/boardID/specification/object"
+    }
+  }
+}

etc/schemas/arduino-boards-txt-schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/arduino/arduino-lint/main/etc/schemas/arduino-boards-txt-strict-schema.json",
+  "title": "Arduino boards.txt JSON strict schema",
+  "description": "boards.txt contains the boards definitions of Arduino platforms. See: https://arduino.github.io/arduino-cli/latest/platform-specification/#boardstxt",
+  "$comment": "For information on the boards.txt format, see https://godoc.org/github.com/arduino/go-properties-orderedmap",
+  "type": "object",
+  "properties": {
+    "menu": {
+      "$ref": "arduino-boards-txt-definitions-schema.json#/definitions/propertiesObjects/menu/strict/object"
+    }
+  },
+  "patternProperties": {
+    "^([^m].*|m([^e].*)?|me([^n].*)?|men([^u].*)?|menu.+)$": {
+      "$ref": "arduino-boards-txt-definitions-schema.json#/definitions/propertiesObjects/boardID/strict/object"
+    }
+  }
+}

etc/schemas/arduino-boards-txt-strict-schema.json

@@ -20,11 +20,79 @@ See: https://arduino.github.io/arduino-cli/latest/platform-specification/#boards
 package boardstxt
 
 import (
+	"github.com/arduino/arduino-lint/internal/rule/schema"
+	"github.com/arduino/arduino-lint/internal/rule/schema/compliancelevel"
+	"github.com/arduino/arduino-lint/internal/rule/schema/schemadata"
 	"github.com/arduino/go-paths-helper"
 	"github.com/arduino/go-properties-orderedmap"
 )
 
 // Properties parses the boards.txt from the given path and returns the data.
 func Properties(platformPath *paths.Path) (*properties.Map, error) {
-	return properties.SafeLoadFromPath(platformPath.Join("boards.txt"))
+	return properties.LoadFromPath(platformPath.Join("boards.txt"))
+}
+
+var schemaObject = make(map[compliancelevel.Type]schema.Schema)
+
+// Validate validates boards.txt data against the JSON schema and returns a map of the result for each compliance level.
+func Validate(boardsTxt *properties.Map) map[compliancelevel.Type]schema.ValidationResult {
+	referencedSchemaFilenames := []string{
+		"general-definitions-schema.json",
+		"arduino-boards-txt-definitions-schema.json",
+	}
+
+	var validationResults = make(map[compliancelevel.Type]schema.ValidationResult)
+
+	if schemaObject[compliancelevel.Permissive].Compiled == nil { // Only compile the schemas once.
+		schemaObject[compliancelevel.Permissive] = schema.Compile("arduino-boards-txt-permissive-schema.json", referencedSchemaFilenames, schemadata.Asset)
+		schemaObject[compliancelevel.Specification] = schema.Compile("arduino-boards-txt-schema.json", referencedSchemaFilenames, schemadata.Asset)
+		schemaObject[compliancelevel.Strict] = schema.Compile("arduino-boards-txt-strict-schema.json", referencedSchemaFilenames, schemadata.Asset)
+	}
+
+	/*
+		Convert the boards.txt data from the native properties.Map type to the interface type required by the schema
+		validation package.
+		Even though boards.txt has a multi-level nested data structure, the format has the odd characteristic of allowing a
+		key to be both an object and a string simultaneously, which is not compatible with Golang maps or JSON. So the data
+		structure used is a map of the first level keys (necessary to accommodate the board IDs) to the full remainder of
+		the keys (rather than recursing through the key levels individually), to string values.
+	*/
+	boardsTxtInterface := make(map[string]interface{})
+	keys := boardsTxt.FirstLevelKeys()
+	for _, key := range keys {
+		subtreeMap := boardsTxt.SubTree(key).AsMap()
+		// This level also must be converted to map[string]interface{}.
+		subtreeInterface := make(map[string]interface{})
+		for subtreeKey, subtreeValue := range subtreeMap {
+			subtreeInterface[subtreeKey] = subtreeValue
+		}
+		boardsTxtInterface[key] = subtreeInterface
+	}
+
+	validationResults[compliancelevel.Permissive] = schema.Validate(boardsTxtInterface, schemaObject[compliancelevel.Permissive])
+	validationResults[compliancelevel.Specification] = schema.Validate(boardsTxtInterface, schemaObject[compliancelevel.Specification])
+	validationResults[compliancelevel.Strict] = schema.Validate(boardsTxtInterface, schemaObject[compliancelevel.Strict])
+
+	return validationResults
+}
+
+// MenuIDs returns the list of menu IDs from the given boards.txt properties.
+func MenuIDs(boardsTxt *properties.Map) []string {
+	// Each menu must have a property defining its title with the format `menu.MENU_ID=MENU_TITLE`.
+	return boardsTxt.SubTree("menu").FirstLevelKeys()
+}
+
+// BoardIDs returns the list of board IDs from the given boards.txt properties.
+func BoardIDs(boardsTxt *properties.Map) []string {
+	boardIDs := boardsTxt.FirstLevelKeys()
+	boardIDCount := 0
+	for _, boardID := range boardIDs {
+		if boardID != "menu" {
+			// This element is a board ID, retain it in the section of the array that will be returned.
+			boardIDs[boardIDCount] = boardID
+			boardIDCount++
+		}
+	}
+
+	return boardIDs[:boardIDCount]
 }

internal/project/platform/boardstxt/boardstxt.go

@@ -0,0 +1,94 @@
+// This file is part of arduino-lint.
+//
+// Copyright 2020 ARDUINO SA (http://www.arduino.cc/)
+//
+// This software is released under the GNU General Public License version 3,
+// which covers the main part of arduino-lint.
+// The terms of this license can be found at:
+// https://www.gnu.org/licenses/gpl-3.0.en.html
+//
+// You can be released from the requirements of the above licenses by purchasing
+// a commercial license. Buying such a license is mandatory if you want to
+// modify or otherwise use the software for commercial activities involving the
+// Arduino software without disclosing the source code of your own applications.
+// To purchase a commercial license, send an email to [email protected].
+
+package boardstxt
+
+import (
+	"testing"
+
+	"github.com/arduino/arduino-lint/internal/rule/schema/compliancelevel"
+	"github.com/arduino/go-paths-helper"
+	"github.com/arduino/go-properties-orderedmap"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+var testDataPath *paths.Path
+
+var validBoardsTxtMap map[string]string
+
+func init() {
+	workingDirectory, err := paths.Getwd()
+	if err != nil {
+		panic(err)
+	}
+	testDataPath = workingDirectory.Join("testdata")
+
+	validBoardsTxtMap = map[string]string{
+		"uno.name":                     "Arduino Uno",
+		"uno.build.board":              "AVR_UNO",
+		"uno.build.core":               "arduino",
+		"uno.upload.tool":              "avrdude",
+		"uno.upload.maximum_size":      "123",
+		"uno.upload.maximum_data_size": "123",
+	}
+}
+
+func TestProperties(t *testing.T) {
+	propertiesOutput, err := Properties(testDataPath.Join("valid"))
+	require.Nil(t, err)
+
+	assert.True(t, properties.NewFromHashmap(validBoardsTxtMap).Equals(propertiesOutput))
+}
+
+func TestValidate(t *testing.T) {
+	boardsTxt := properties.NewFromHashmap(validBoardsTxtMap)
+	validationResult := Validate(boardsTxt)
+
+	assert.Nil(t, validationResult[compliancelevel.Permissive].Result)
+	assert.Nil(t, validationResult[compliancelevel.Specification].Result)
+	assert.Nil(t, validationResult[compliancelevel.Strict].Result)
+
+	boardsTxt.Remove("uno.name") // Remove required property.
+	validationResult = Validate(boardsTxt)
+	assert.NotNil(t, validationResult[compliancelevel.Permissive].Result)
+	assert.NotNil(t, validationResult[compliancelevel.Specification].Result)
+	assert.NotNil(t, validationResult[compliancelevel.Strict].Result)
+}
+
+func TestMenuIDs(t *testing.T) {
+	boardsTxt := properties.NewFromHashmap(validBoardsTxtMap)
+
+	assert.ElementsMatch(t, []string{}, MenuIDs(boardsTxt), "No menu IDs")
+
+	boardsTxt.Set("menu", "noooo")
+	assert.ElementsMatch(t, []string{}, MenuIDs(boardsTxt), "Some silly defined a menu property without a subproperty")
+
+	boardsTxt.Set("menu.foo", "asdf")
+	boardsTxt.Set("menu.bar", "zxcv")
+	boardsTxt.Set("baz.name", "qwer")
+	assert.ElementsMatch(t, []string{"foo", "bar"}, MenuIDs(boardsTxt), "Has menu IDs")
+}
+
+func TestBoardIDs(t *testing.T) {
+	boardsTxt := properties.NewFromHashmap(validBoardsTxtMap)
+
+	assert.ElementsMatch(t, []string{"uno"}, BoardIDs(boardsTxt))
+
+	boardsTxt.Set("menu.foo", "asdf")
+	boardsTxt.Set("menu.bar", "zxcv")
+	boardsTxt.Set("baz.name", "qwer")
+	assert.ElementsMatch(t, []string{"uno", "baz"}, BoardIDs(boardsTxt))
+}