Create tool for linting Arduino projects

README.md

@@ -0,0 +1,6 @@
+# arduino-check
+
+`arduino-check` automatically checks for common problems in your [Arduino](https://www.arduino.cc/) projects:
+
+- Sketches
+- Libraries

arduino-library-properties-schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://github.com/arduino/arduino-check/arduino-library-properties-schema.json",
+  "title": "Arduino library.properties JSON schema",
+  "description": "library.properties is the metadata file for Arduino libraries. See: https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata",
+  "$comment": "For information on the Arduino library.properties format, see https://godoc.org/github.com/arduino/go-properties-orderedmap",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63,
+      "pattern": "^(([a-zA-Z][a-zA-Z0-9 _\\.\\-]*)|([0-9][a-zA-Z0-9 _\\.\\-]*[a-zA-Z][a-zA-Z0-9 _\\.\\-]*))$"
+    },
+    "version": {
+      "type": "string",
+      "$comment": "https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string adjusted to also allow MAJOR.MINOR and with unused non-capturing group syntax removed",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(\\.(0|[1-9]\\d*))?(-((0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(\\.(0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\\+([0-9a-zA-Z-]+(\\.[0-9a-zA-Z-]+)*))?$"
+    },
+    "author": {
+      "type": "string",
+      "minLength": 1
+    },
+    "maintainer": {
+      "type": "string",
+      "minLength": 1
+    },
+    "sentence": {
+      "type": "string",
+      "minLength": 1
+    },
+    "paragraph": {
+      "type": "string"
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "Display",
+        "Communication",
+        "Signal Input/Output",
+        "Sensors",
+        "Device Control",
+        "Timing",
+        "Data Storage",
+        "Data Processing",
+        "Other"
+      ]
+    },
+    "url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "architectures": {
+      "type": "string",
+      "minLength": 1
+    },
+    "depends": {
+      "type": "string",
+      "pattern": "^[a-zA-Z][a-zA-Z\\d _\\.\\-,]*$"
+    },
+    "dot_a_linkage": {
+      "type": "string",
+      "enum": ["true", "false"]
+    },
+    "includes": {
+      "type": "string",
+      "minLength": 1
+    },
+    "precompiled": {
+      "type": "string",
+      "enum": ["true", "full", "false"]
+    },
+    "ldflags": {
+      "type": "string"
+    }
+  },
+  "propertyNames": {
+    "not": {
+      "$comment": "Misspelled optional property names",
+      "pattern": "^((depend)|(D((epends?)|(EPENDS?)))|(dot_a_linkages)|(dot-?a-?linkages?)|(D(((ot)|(OT))[_-]?((a)|(A))[_-]?((linkages?)|(LINKAGES?))))|(include)|(I((ncludes?)|(NCLUDES?)))|(precompile)|(pre[-_]compiled?)|(P((re[-_]?compiled?)|(RE[-_]?COMPILED?)))|(ldflag)|(ld[-_]flags?)|(L((d[-_]?flags?)|(D[-_]?FLAGS?))))$"
+    }
+  },
+  "required": ["name", "version", "author", "maintainer", "sentence", "paragraph", "category", "url", "architectures"]
+}

check/check.go

@@ -0,0 +1,91 @@
+// Package check runs checks on a project.
+package check
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/arduino/arduino-check/check/checkconfigurations"
+	"github.com/arduino/arduino-check/check/checkdata"
+	"github.com/arduino/arduino-check/configuration"
+	"github.com/arduino/arduino-check/configuration/checkmode"
+	"github.com/arduino/arduino-check/project"
+	"github.com/arduino/arduino-check/result"
+	"github.com/arduino/arduino-check/result/feedback"
+	"github.com/arduino/arduino-check/result/outputformat"
+	"github.com/sirupsen/logrus"
+)
+
+// RunChecks runs all checks for the given project and outputs the results.
+func RunChecks(project project.Type) {
+	fmt.Printf("Checking %s in %s\n", project.ProjectType, project.Path)
+
+	checkdata.Initialize(project)
+
+	for _, checkConfiguration := range checkconfigurations.Configurations() {
+		runCheck, err := shouldRun(checkConfiguration, project)
+		if err != nil {
+			feedback.Errorf("Error while determining whether to run check: %v", err)
+			os.Exit(1)
+		}
+
+		if !runCheck {
+			logrus.Infof("Skipping check: %s\n", checkConfiguration.ID)
+			continue
+		}
+
+		// Output will be printed after all checks are finished when configured for "json" output format
+		if configuration.OutputFormat() == outputformat.Text {
+			fmt.Printf("Running check %s: ", checkConfiguration.ID)
+		}
+		checkResult, checkOutput := checkConfiguration.CheckFunction()
+		reportText := result.Results.Record(project, checkConfiguration, checkResult, checkOutput)
+		if configuration.OutputFormat() == outputformat.Text {
+			fmt.Print(reportText)
+		}
+	}
+
+	// Checks are finished for this project, so summarize its check results in the report.
+	result.Results.AddProjectSummary(project)
+
+	if configuration.OutputFormat() == outputformat.Text {
+		// Print the project check results summary.
+		fmt.Print(result.Results.ProjectSummaryText(project))
+	}
+}
+
+// shouldRun returns whether a given check should be run for the given project under the current tool configuration.
+func shouldRun(checkConfiguration checkconfigurations.Type, currentProject project.Type) (bool, error) {
+	configurationCheckModes := configuration.CheckModes(currentProject.SuperprojectType)
+
+	if checkConfiguration.ProjectType != currentProject.ProjectType {
+		return false, nil
+	}
+
+	for _, disableMode := range checkConfiguration.DisableModes {
+		if configurationCheckModes[disableMode] {
+			return false, nil
+		}
+	}
+
+	for _, enableMode := range checkConfiguration.EnableModes {
+		if configurationCheckModes[enableMode] {
+			return true, nil
+		}
+	}
+
+	// Use default
+	for _, disableMode := range checkConfiguration.DisableModes {
+		if disableMode == checkmode.Default {
+			return false, nil
+		}
+	}
+
+	for _, enableMode := range checkConfiguration.EnableModes {
+		if enableMode == checkmode.Default {
+			return true, nil
+		}
+	}
+
+	return false, fmt.Errorf("Check %s is incorrectly configured", checkConfiguration.ID)
+}

check/checkconfigurations/checkconfigurations.go

@@ -0,0 +1,119 @@
+/*
+Package checkconfigurations defines the configuration of each check:
+- metadata
+- output template
+- under which conditions it's enabled
+- the level of a failure
+- which function implements it
+*/
+package checkconfigurations
+
+import (
+	"github.com/arduino/arduino-check/check/checkfunctions"
+	"github.com/arduino/arduino-check/configuration/checkmode"
+	"github.com/arduino/arduino-check/project/projecttype"
+)
+
+// Type is the type for check configurations.
+type Type struct {
+	ProjectType projecttype.Type // The project type the check applies to.
+	// The following fields provide arbitrary text for the tool output associated with each check:
+	Category        string
+	Subcategory     string
+	ID              string // Unique check identifier: <project type identifier (L|S|P|I)><category identifier><number>
+	Brief           string // Short description of the check.
+	Description     string // Supplemental information about the check.
+	MessageTemplate string // The warning/error message template displayed when the check fails. Will be filled by check function output.
+	// The following fields define under which tool configuration modes the check will run:
+	DisableModes []checkmode.Type // Check is disabled when tool is in any of these modes.
+	EnableModes  []checkmode.Type // Check is only enabled when tool is in one of these modes.
+	// The following fields define the check level in each configuration mode:
+	InfoModes     []checkmode.Type    // Failure of the check only results in an informational message.
+	WarningModes  []checkmode.Type    // Failure of the check is considered a warning.
+	ErrorModes    []checkmode.Type    // Failure of the check is considered an error.
+	CheckFunction checkfunctions.Type // The function that implements the check.
+}
+
+// Configurations returns the slice of check configurations.
+func Configurations() []Type {
+	return configurations
+}
+
+// configurations is an array of structs that define the configuration of each check.
+var configurations = []Type{
+	{
+		ProjectType:     projecttype.Library,
+		Category:        "library.properties",
+		Subcategory:     "general",
+		ID:              "LP001",
+		Brief:           "invalid format",
+		Description:     "",
+		MessageTemplate: "library.properties has an invalid format: {{.}}",
+		DisableModes:    nil,
+		EnableModes:     []checkmode.Type{checkmode.All},
+		InfoModes:       nil,
+		WarningModes:    nil,
+		ErrorModes:      []checkmode.Type{checkmode.All},
+		CheckFunction:   checkfunctions.LibraryPropertiesFormat,
+	},
+	{
+		ProjectType:     projecttype.Library,
+		Category:        "library.properties",
+		Subcategory:     "name field",
+		ID:              "LP002",
+		Brief:           "missing name field",
+		Description:     "",
+		MessageTemplate: "missing name field in library.properties",
+		DisableModes:    nil,
+		EnableModes:     []checkmode.Type{checkmode.All},
+		InfoModes:       nil,
+		WarningModes:    nil,
+		ErrorModes:      []checkmode.Type{checkmode.All},
+		CheckFunction:   checkfunctions.LibraryPropertiesNameFieldMissing,
+	},
+	{
+		ProjectType:     projecttype.Library,
+		Category:        "library.properties",
+		Subcategory:     "name field",
+		ID:              "LP003",
+		Brief:           "disallowed characters",
+		Description:     "",
+		MessageTemplate: "disallowed characters in library.properties name field. See: https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format",
+		DisableModes:    nil,
+		EnableModes:     []checkmode.Type{checkmode.All},
+		InfoModes:       nil,
+		WarningModes:    nil,
+		ErrorModes:      []checkmode.Type{checkmode.All},
+		CheckFunction:   checkfunctions.LibraryPropertiesNameFieldDisallowedCharacters,
+	},
+	{
+		ProjectType:     projecttype.Library,
+		Category:        "library.properties",
+		Subcategory:     "version field",
+		ID:              "LP004",
+		Brief:           "missing version field",
+		Description:     "",
+		MessageTemplate: "missing version field in library.properties",
+		DisableModes:    nil,
+		EnableModes:     []checkmode.Type{checkmode.All},
+		InfoModes:       nil,
+		WarningModes:    nil,
+		ErrorModes:      []checkmode.Type{checkmode.All},
+		CheckFunction:   checkfunctions.LibraryPropertiesVersionFieldMissing,
+	},
+	{
+		ProjectType:     projecttype.Sketch,
+		Category:        "structure",
+		Subcategory:     "",
+		ID:              "SS001",
+		Brief:           ".pde extension",
+		Description:     "The .pde extension is used by both Processing sketches and Arduino sketches. Processing sketches should either be in the \"data\" subfolder of the sketch or in the \"extras\" folder of the library. Arduino sketches should use the modern .ino extension",
+		MessageTemplate: "{{.}} uses deprecated .pde file extension. Use .ino for Arduino sketches",
+		DisableModes:    nil,
+		EnableModes:     []checkmode.Type{checkmode.All},
+		InfoModes:       nil,
+		WarningModes:    []checkmode.Type{checkmode.Permissive},
+		ErrorModes:      []checkmode.Type{checkmode.Default},
+		CheckFunction:   checkfunctions.PdeSketchExtension,
+	},
+}

check/checkdata/checkdata.go

@@ -0,0 +1,38 @@
+/*
+Package checkdata handles the collection of data specific to a project before running the checks on it.
+This is for data required by multiple checks.
+*/
+package checkdata
+
+import (
+	"github.com/arduino/arduino-check/project"
+	"github.com/arduino/arduino-check/project/projecttype"
+	"github.com/arduino/go-paths-helper"
+)
+
+// Initialize gathers the check data for the specified project.
+func Initialize(project project.Type) {
+	projectType = project.ProjectType
+	projectPath = project.Path
+	switch project.ProjectType {
+	case projecttype.Sketch:
+	case projecttype.Library:
+		InitializeForLibrary(project)
+	case projecttype.Platform:
+	case projecttype.PackageIndex:
+	}
+}
+
+var projectType projecttype.Type
+
+// ProjectType returns the type of the project being checked.
+func ProjectType() projecttype.Type {
+	return projectType
+}
+
+var projectPath *paths.Path
+
+// ProjectPath returns the path to the project being checked.
+func ProjectPath() *paths.Path {
+	return projectPath
+}

check/checkdata/library.go

@@ -0,0 +1,41 @@
+package checkdata
+
+import (
+	"github.com/arduino/arduino-check/project"
+	"github.com/arduino/arduino-check/project/library/libraryproperties"
+	"github.com/arduino/go-properties-orderedmap"
+	"github.com/xeipuuv/gojsonschema"
+)
+
+// Initialize gathers the library check data for the specified project.
+func InitializeForLibrary(project project.Type) {
+	libraryProperties, libraryPropertiesLoadError = libraryproperties.Properties(project.Path)
+	if libraryPropertiesLoadError != nil {
+		// TODO: can I even do this?
+		libraryPropertiesSchemaValidationResult = nil
+	} else {
+		libraryPropertiesSchemaValidationResult = libraryproperties.Validate(libraryProperties)
+	}
+}
+
+var libraryPropertiesLoadError error
+
+// LibraryPropertiesLoadError returns the error output from loading the library.properties metadata file.
+func LibraryPropertiesLoadError() error {
+	return libraryPropertiesLoadError
+}
+
+var libraryProperties *properties.Map
+
+// LibraryProperties returns the data from the library.properties metadata file.
+func LibraryProperties() *properties.Map {
+	return libraryProperties
+}
+
+var libraryPropertiesSchemaValidationResult *gojsonschema.Result
+
+// LibraryPropertiesSchemaValidationResult returns the result of validating library.properties against the JSON schema.
+// See: https://github.com/xeipuuv/gojsonschema
+func LibraryPropertiesSchemaValidationResult() *gojsonschema.Result {
+	return libraryPropertiesSchemaValidationResult
+}

check/checkfunctions/checkfunctions.go

@@ -0,0 +1,10 @@
+// Package checkfunctions contains the functions that implement each check.
+package checkfunctions
+
+import (
+	"github.com/arduino/arduino-check/check/checkresult"
+)
+
+// Type is the function signature for the check functions.
+// The `output` result is the contextual information that will be inserted into the check's message template.
+type Type func() (result checkresult.Type, output string)