Add tool to filter Vale JSON output using rule precedence (#942)

.github/workflows/validate-documentation-inverse.yml

@@ -19,3 +19,7 @@ jobs:
     runs-on: "ubuntu-latest"
     steps:
       - run: echo 'No build required'
+  test:
+    runs-on: "ubuntu-latest"
+    steps:
+      - run: echo 'No build required'

.github/workflows/validate-documentation.yml

@@ -1,4 +1,4 @@
-name: Validate documentation
+name: Documentation CI
 on:
   pull_request:
     paths: ["docs/sources/**", "vale/**"]
@@ -47,7 +47,7 @@ jobs:
       - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
         with:
           node-version: 20
-      - run: npm install prettier
+      - run: npm install --no-save prettier
       - run: >
           reviewdog
           --filter-mode=nofilter
@@ -82,22 +82,9 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           persist-credentials: false
-      - name: Sync packages
-        run: vale sync
-      - name: Run linter
-        run: >
-          vale
-          '--glob=*.md'
-          --minAlertLevel=warning
-          --output=/etc/vale/rdjsonl.tmpl
-          docs/sources
-          | reviewdog
-          -f=rdjsonl
-          --fail-on-error
-          --name=vale
-          --reporter=github-pr-review
-        env:
-          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: ./vale-action
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
 
   report-readability:
     if: ${{ github.repository == 'grafana/writers-toolkit' }}

.gitignore

@@ -7,3 +7,4 @@
 build.conf
 /dist
 /vale/Grafana.zip
+vale/tools/inhibit-rules

vale-action/action.yml

@@ -0,0 +1,39 @@
+name: Run Vale
+description: |
+  Lints documentation with Vale.
+
+  Note that the action assumes you are running the steps using the grafana/vale container image.
+inputs:
+  directory:
+    default: docs/sources
+    description: Directory containing documentation for linting.
+    required: false
+  filter:
+    default: ""
+    description: |
+      Vale filter that allows you to report an arbitrary subset of the Grafana style.
+
+      For more information, refer to https://vale.sh/docs/filters.
+  token:
+    default: ${{ github.token }}
+    description: Used by reviewdog to comment on pull requests.
+    required: false
+runs:
+  using: composite
+  steps:
+    - name: Vale
+      env:
+        DIRECTORY: ${{ inputs.directory }}
+        FILTER: --filter=${{ inputs.filter }}
+        REVIEWDOG_GITHUB_API_TOKEN: ${{ inputs.token }}
+      run: |
+          (cd /etc/vale && vale sync)
+          vale ${FILTER} --output=/etc/vale/rdjsonl.tmpl ${DIRECTORY} | \
+            inhibit-rules | \
+            /bin/reviewdog \
+            --conf=/etc/vale/.reviewdog.yml \
+            --fail-on-error \
+            --f=rdjsonl \
+            --name=vale \
+            --reporter=github-pr-review
+      shell: sh

vale/Dockerfile

@@ -18,10 +18,22 @@ WORKDIR "/src/reviewdog-${REVIEWDOG_VERSION}"
 RUN GOOS="${TARGETOS}" GOARCH="${TARGETARCH}" go build -o reviewdog ./cmd/reviewdog
 RUN mv reviewdog /out
 
+################################################################################
+FROM --platform=${BUILDPLATFORM} golang:alpine AS inhibit-rules
+ARG TARGETOS TARGETARCH
+
+RUN mkdir /src /out
+COPY /tools /src
+
+WORKDIR /src
+RUN GOOS="${TARGETOS}" GOARCH="${TARGETARCH}" go build -o inhibit-rules ./cmd/inhibit-rules
+RUN mv inhibit-rules /out
+
 ################################################################################
 FROM jdkato/vale:v3.8.0
 
 COPY --from=reviewdog /out/reviewdog /bin
+COPY --from=inhibit-rules /out/inhibit-rules /bin
 
 # Git is useful for reporting with reviewdog.
 RUN apk add --no-cache git

vale/Makefile

@@ -28,9 +28,11 @@ $(DOCUMENTATION): $(wildcard Grafana/styles/Grafana/*) $(wildcard ../tools/cmd/g
 Grafana/styles/config/dictionaries/en_US-grafana.%: dictionary.libsonnet
 	$(MAKE) -C $(@D) $(@F)
 
+IMAGE_PREREQUISITES := Grafana/styles/config/dictionaries/en_US-grafana.aff Grafana/styles/config/dictionaries/en_US-grafana.dic Grafana/styles/Grafana/Google .vale.ini
+
 .PHONY: grafana/vale
 grafana/vale: ## Builds a container image for Vale with the Grafana style loaded.
-grafana/vale: Grafana/styles/config/dictionaries/en_US-grafana.aff Grafana/styles/config/dictionaries/en_US-grafana.dic Grafana/styles/Grafana/Google .vale.ini
+grafana/vale: $(IMAGE_PREREQUISITES)
 	docker buildx build \
 		--platform linux/x86_64,linux/arm64 \
 		--progress=plain \
@@ -40,7 +42,7 @@ grafana/vale: Grafana/styles/config/dictionaries/en_US-grafana.aff Grafana/style
 
 .PHONY: grafana/vale/push
 grafana/vale/push: ## Builds and pushes container image for Vale with the Grafana style loaded.
-grafana/vale/push:
+grafana/vale/push: $(IMAGE_PREREQUISITES)
 	docker buildx build \
 		--platform linux/x86_64,linux/arm64 \
 		--progress=plain \

vale/tools/cmd/inhibit-rules/main.go

@@ -0,0 +1,122 @@
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/grafana/writers-toolkit/tools/exit"
+)
+
+const command = "inhibit-rules"
+
+func usage(w io.Writer, fs *flag.FlagSet) {
+	fmt.Fprintf(w, "Usage of %s:\n", command)
+	fs.SetOutput(w)
+	fs.PrintDefaults()
+
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintln(w, "Reads JSON formatted error messages from standard input and filters them based on rule precedence.")
+}
+
+func main() {
+	fs := flag.NewFlagSet(command, flag.ExitOnError)
+	flag.Parse()
+
+	if flag.NArg() > 0 {
+		usage(os.Stderr, fs)
+		os.Exit(exit.UsageError)
+	}
+
+	r := bufio.NewReader(os.Stdin)
+	scanner := bufio.NewScanner(r)
+	diags := make([]diagnostic, 0)
+
+	var errs bool
+	for scanner.Scan() {
+		diag := diagnostic{}
+		if err := json.Unmarshal(scanner.Bytes(), &diag); err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+			errs = true
+		}
+
+		diags = append(diags, diag)
+	}
+
+	if err := scanner.Err(); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		errs = true
+	}
+
+	diags = inhibit(diags)
+	for _, d := range diags {
+		if err := json.NewEncoder(os.Stdout).Encode(d); err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+			errs = true
+		}
+	}
+
+	if errs {
+		os.Exit(exit.RuntimeError)
+	}
+}
+
+// {"message": "[{{ $check }}] {{ $message | jsonEscape }}", "location": {"path": "{{ $path }}", "range": {"start": {"line": {{ $line }}, "column": {{ $col }}}}}, "severity": "{{ $error }}"}
+type diagnostic struct {
+	Message  string `json:"message"`
+	Location struct {
+		Path  string `json:"path"`
+		Range struct {
+			Start struct {
+				Line   int `json:"line"`
+				Column int `json:"column"`
+			} `json:"start"`
+		} `json:"range"`
+	} `json:"location"`
+	Severity string `json:"severity"`
+}
+
+// Each error has the rule name in square brackets at the beginning of the message.
+// For example: {"message": "[Grafana.Spelling] ..." ...}
+func (d diagnostic) Rule() string {
+	if len(d.Message) == 0 || d.Message[0] != '[' {
+		return ""
+	}
+
+	end := strings.Index(d.Message, "]")
+	if end == -1 {
+		return ""
+	}
+
+	return d.Message[1:end]
+}
+
+func (d diagnostic) LocationKey() string {
+	return fmt.Sprintf("%s:%d:%d", d.Location.Path, d.Location.Range.Start.Line, d.Location.Range.Start.Column)
+}
+
+func inhibit(in []diagnostic) []diagnostic {
+	filtered := make(map[string]diagnostic)
+	precedence := map[string]int{
+		"Grafana.ProductPossessives": 0,
+		"Grafana.WordList":           1,
+		"Grafana.Spelling":           2,
+	}
+
+	for _, d := range in {
+		if _, ok := filtered[d.LocationKey()]; !ok || precedence[d.Rule()] < precedence[filtered[d.LocationKey()].Rule()] {
+			filtered[d.LocationKey()] = d
+		}
+	}
+
+	out := make([]diagnostic, 0, len(filtered))
+	for _, d := range filtered {
+		out = append(out, d)
+	}
+
+	return out
+}

vale/tools/go.mod

@@ -0,0 +1,5 @@
+module github.com/grafana/writers-toolkit/vale/tools
+
+go 1.23.3
+
+require github.com/grafana/writers-toolkit/tools v0.0.0-20250108111324-7ed051741521 // indirect

vale/tools/go.sum

@@ -0,0 +1,2 @@
+github.com/grafana/writers-toolkit/tools v0.0.0-20250108111324-7ed051741521 h1:sJw5cYvUHjysFlOEN5MLaJC9XR0Is3S1rLlUuv3L83s=
+github.com/grafana/writers-toolkit/tools v0.0.0-20250108111324-7ed051741521/go.mod h1:f8r529z0g/keWOXl33WHJr4uYcv2bp7iwzFKeG+AukA=