Publish generated list of rules on documentation website

.github/workflows/check-go-task.yml

@@ -50,10 +50,20 @@ jobs:
           echo "::set-output name=result::$RESULT"
 
   check-errors:
+    name: check-errors (${{ matrix.module.path }})
     needs: run-determination
     if: needs.run-determination.outputs.result == 'true'
     runs-on: ubuntu-latest
 
+    strategy:
+      fail-fast: false
+
+      matrix:
+        module:
+          - path: ./
+          - path: docsgen
+          - path: ruledocsgen
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v2
@@ -70,13 +80,25 @@ jobs:
           version: 3.x
 
       - name: Check for errors
+        env:
+          GO_MODULE_PATH: ${{ matrix.module.path }}
         run: task go:vet
 
   check-outdated:
+    name: check-outdated (${{ matrix.module.path }})
     needs: run-determination
     if: needs.run-determination.outputs.result == 'true'
     runs-on: ubuntu-latest
 
+    strategy:
+      fail-fast: false
+
+      matrix:
+        module:
+          - path: ./
+          - path: docsgen
+          - path: ruledocsgen
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v2
@@ -93,16 +115,28 @@ jobs:
           version: 3.x
 
       - name: Modernize usages of outdated APIs
+        env:
+          GO_MODULE_PATH: ${{ matrix.module.path }}
         run: task go:fix
 
       - name: Check if any fixes were needed
         run: git diff --color --exit-code
 
   check-style:
+    name: check-style (${{ matrix.module.path }})
     needs: run-determination
     if: needs.run-determination.outputs.result == 'true'
     runs-on: ubuntu-latest
 
+    strategy:
+      fail-fast: false
+
+      matrix:
+        module:
+          - path: ./
+          - path: docsgen
+          - path: ruledocsgen
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v2
@@ -122,13 +156,25 @@ jobs:
         run: go install golang.org/x/lint/golint@latest
 
       - name: Check style
+        env:
+          GO_MODULE_PATH: ${{ matrix.module.path }}
         run: task --silent go:lint
 
   check-formatting:
+    name: check-formatting (${{ matrix.module.path }})
     needs: run-determination
     if: needs.run-determination.outputs.result == 'true'
     runs-on: ubuntu-latest
 
+    strategy:
+      fail-fast: false
+
+      matrix:
+        module:
+          - path: ./
+          - path: docsgen
+          - path: ruledocsgen
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v2
@@ -145,6 +191,8 @@ jobs:
           version: 3.x
 
       - name: Format code
+        env:
+          GO_MODULE_PATH: ${{ matrix.module.path }}
         run: task go:format
 
       - name: Check formatting
@@ -163,6 +211,7 @@ jobs:
         module:
           - path: ./
           - path: docsgen
+          - path: ruledocsgen
 
     steps:
       - name: Checkout repository

.github/workflows/check-mkdocs-task.yml

@@ -18,6 +18,7 @@ on:
       - "pyproject.toml"
       - "docs/**"
       - "docsgen/**"
+      - "ruledocsgen/**"
       - "**.go"
   pull_request:
     paths:
@@ -28,6 +29,7 @@ on:
       - "pyproject.toml"
       - "docs/**"
       - "docsgen/**"
+      - "ruledocsgen/**"
       - "**.go"
   workflow_dispatch:
   repository_dispatch:

.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml

@@ -20,6 +20,7 @@ on:
       - "Taskfile.ya?ml"
       - "**.go"
       - "docsgen/**"
+      - "ruledocsgen/**"
       - "mkdocs.ya?ml"
       - "poetry.lock"
       - "pyproject.toml"

.github/workflows/test-go-task.yml

@@ -12,17 +12,17 @@ on:
     paths:
       - ".github/workflows/test-go-task.ya?ml"
       - "codecov.ya?ml"
-      - "go.mod"
-      - "go.sum"
+      - "**/go.mod"
+      - "**/go.sum"
       - "Taskfile.ya?ml"
       - "**.go"
       - "**/testdata/**"
   pull_request:
     paths:
       - ".github/workflows/test-go-task.ya?ml"
       - "codecov.ya?ml"
-      - "go.mod"
-      - "go.sum"
+      - "**/go.mod"
+      - "**/go.sum"
       - "Taskfile.ya?ml"
       - "**.go"
       - "**/testdata/**"
@@ -54,15 +54,23 @@ jobs:
           echo "::set-output name=result::$RESULT"
 
   test:
+    name: test (${{ matrix.module.path }} - ${{ matrix.operating-system }})
     needs: run-determination
     if: needs.run-determination.outputs.result == 'true'
 
     strategy:
+      fail-fast: false
+
       matrix:
         operating-system:
           - ubuntu-latest
           - windows-latest
           - macos-latest
+        module:
+          - path: ./
+            codecov-flags: unit
+          - path: ruledocsgen/
+            codecov-flags: unit
 
     runs-on: ${{ matrix.operating-system }}
 
@@ -82,12 +90,14 @@ jobs:
           version: 3.x
 
       - name: Run tests
+        env:
+          GO_MODULE_PATH: ${{ matrix.module.path }}
         run: task go:test
 
       - name: Send unit tests coverage to Codecov
-        if: matrix.operating-system == 'ubuntu-latest'
+        if: runner.os == 'Linux'
         uses: codecov/codecov-action@v2
         with:
-          file: ./coverage_unit.txt
-          flags: unit
+          file: ${{ matrix.module.path }}coverage_unit.txt
+          flags: ${{ matrix.module.codecov-flags }}
           fail_ci_if_error: ${{ github.repository == 'arduino/arduino-lint' }}

.gitignore

@@ -18,5 +18,8 @@ coverage_unit.txt
 /docsgen/arduino-cli
 /docsgen/arduino-cli.exe
 /docs/commands/*.md
+/ruledocsgen/ruledocsgen
+/ruledocsgen/ruledocsgen.exe
+/docs/rules/
 
 /dist

.prettierignore

@@ -9,3 +9,4 @@
 /internal/project/projectdata/testdata/packageindexes/invalid-JSON/package_foo_index.json
 /internal/rule/rulefunction/testdata/packageindexes/invalid-JSON/package_foo_index.json
 /internal/rule/rulefunction/testdata/sketches/InvalidJSONMetadataFile/sketch.json
+/ruledocsgen/testdata/golden

Taskfile.yml

@@ -8,8 +8,19 @@ vars:
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/release-go-task/Taskfile.yml
   PROJECT_NAME: "arduino-lint"
   DIST_DIR: "dist"
+  # Path of the project's primary Go module:
+  DEFAULT_GO_MODULE_PATH: ./
   DEFAULT_GO_PACKAGES:
-    sh: echo $(go list ./... | grep --invert-match 'github.com/arduino/arduino-lint/internal/rule/schema/schemadata' | tr '\n' ' ')
+    sh: |
+      echo $( \
+        cd {{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}} \
+        && \
+        go list ./... | \
+          grep --invert-match 'github.com/arduino/arduino-lint/internal/rule/schema/schemadata' | \
+            tr '\n' ' ' \
+        || \
+        echo '"ERROR: Unable to discover Go packages"' \
+      )
   # build vars
   COMMIT:
     sh: echo "$(git log --no-show-signature -n 1 --format=%h)"
@@ -95,6 +106,7 @@ tasks:
     desc: Create all generated documentation content
     deps:
       - task: go:cli-docs
+      - task: go:rule-docs
       # Make the formatting consistent with the non-generated Markdown
       - task: general:format-prettier
 
@@ -134,6 +146,7 @@ tasks:
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/go-task/Taskfile.yml
   go:build:
     desc: Build the Go code
+    dir: "{{.DEFAULT_GO_MODULE_PATH}}"
     cmds:
       - go build -v {{.LDFLAGS}}
 
@@ -150,12 +163,14 @@ tasks:
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:fix:
     desc: Modernize usages of outdated APIs
+    dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
     cmds:
       - go fix {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
 
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:format:
     desc: Format Go code
+    dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
     cmds:
       - go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
 
@@ -172,6 +187,7 @@ tasks:
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:lint:
     desc: Lint Go code
+    dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
     cmds:
       - |
         if ! which golint &>/dev/null; then
@@ -183,9 +199,24 @@ tasks:
           {{default "-min_confidence 0.8 -set_exit_status" .GO_LINT_FLAGS}} \
           {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
 
+  go:rule-docs:
+    desc: Generate rules documentation
+    dir: ./ruledocsgen
+    deps:
+      - task: go:rule-docs:build
+    cmds:
+      - ./ruledocsgen ../docs/rules
+
+  go:rule-docs:build:
+    desc: Generate rules documentation
+    dir: ./ruledocsgen
+    cmds:
+      - go build
+
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-go-task/Taskfile.yml
   go:test:
     desc: Run unit tests
+    dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
     cmds:
       - |
         go test \
@@ -201,13 +232,16 @@ tasks:
     desc: Run integration tests
     deps:
       - task: go:build
+      - task: go:rule-docs:build
       - task: poetry:install-deps
     cmds:
       - poetry run pytest tests
+      - poetry run pytest ruledocsgen/tests
 
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:vet:
     desc: Check for errors in Go code
+    dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
     cmds:
       - go vet {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
 

docs/index.md

@@ -1,8 +1,8 @@
 **Arduino Lint** is a command line tool that checks for common problems with [Arduino](https://www.arduino.cc/)
 projects.
 
-Its focus is on the structure, metadata, and configuration of Arduino projects, rather than the code. Rules cover
-specification compliance, Library Manager submission requirements, and best practices.
+Its focus is on the structure, metadata, and configuration of Arduino projects, rather than the code. [Rules](rules.md)
+cover specification compliance, Library Manager submission requirements, and best practices.
 
 ## Installation
 

docs/rules.md

@@ -0,0 +1,47 @@
+**Arduino Lint** inspects Arduino projects for common problems. This is done by checking the project against a series of
+"rules", each of which is targeted to detecting a specific potential issue. Only the rules of relevance to the project
+being linted are applied.
+
+## Rule documentation
+
+Additional information is available for each of the **Arduino Lint** rules, organized by project type:
+
+- [Sketch](rules/sketch.md)
+- [Library](rules/library.md)
+- [Boards platform](rules/platform.md)
+- [Package index](rules/package-index.md)
+
+## Rule ID
+
+In order to allow particular rules to be referenced unequivocally, each has been assigned a permanent unique
+identification code (e.g., `SS001`).
+
+## Rule level
+
+In addition to checking for critical flaws, **Arduino Lint** also advocates for best practices in Arduino projects. For
+this reason, not all rule violations are treated as fatal linting errors.
+
+A violation of a rule is assigned a level according to its severity. In cases where a rule violation indicates a serious
+problem with the project, the violation is treated as an error, and will result in a non-zero exit status from the
+`arduino-lint` command. In cases where the violation indicates a possible problem, or where the rule is a recommendation
+for an optional improvement to enhance the project user's experience, the violation is treated as a warning. It is hoped
+that these warning-level violations will be given consideration by the user, but they do not affect the `arduino-lint`
+exit status.
+
+Of the hundreds of rules provided by **Arduino Lint**, only the ones relevant to the current target project are applied,
+with the rest disabled.
+
+The rule levels and enabled subset of rules is dependent on the target project type and how the user has configured
+Arduino Lint via the [command line flags](commands/arduino-lint.md) and
+[environment variables](index.md#environment-variables).
+
+## Projects and "superprojects"
+
+Arduino projects may contain other Arduino projects as subprojects. For example, the libraries
+[bundled](https://arduino.github.io/arduino-cli/latest/platform-specification/#platform-bundled-libraries) with an
+Arduino boards platform. These subprojects may, in turn, contain their own subprojects, such as the example sketches
+included with a platform bundled library.
+
+**Arduino Lint** also lints any subprojects the target project might contain. The type of the top level "superproject"
+is a factor in the configuration of some rules. For example, there is no need to take Library Manager requirements into
+consideration in the case of a platform bundled library, since it will never be distributed via that system.

internal/result/result.go

@@ -109,6 +109,9 @@ func (results *Type) Record(lintedProject project.Type, ruleConfiguration ruleco
 	ruleMessage := ""
 	if ruleResult == ruleresult.Fail {
 		ruleMessage = message(ruleConfiguration.MessageTemplate, ruleOutput)
+		if ruleConfiguration.Reference != "" {
+			ruleMessage = fmt.Sprintf("%s\nSee: %s", ruleMessage, ruleConfiguration.Reference)
+		}
 	} else {
 		// Rules may provide an explanation for their non-fail result.
 		// The message template should not be used in this case, since it is written for a failure result.