Skip to content

Add Vale JSON template compatible with the Code Quality spec

Achilleas Pipinellis requested to merge axil-docs-vale-json-code-quality into master

What does this MR do and why?

Adds a Vale template that outputs code-quality-compatible JSON to be used with https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html#implementing-a-custom-tool

For gitlab-docs#1088 (moved)

Caveats

In many suggestions, we have double quotes which makes the JSON file not valid. We should change " with ' or backticks.

How to set up and validate locally

vale --output=doc/.vale/vale-json.tmpl .vale.ini doc/index.md

The output will be:

[{
    "description": "Grade level (12.76) is high. To lower the score, use shorter sentences and words.",
    "fingerprint": "doc/index.md-1",
    "severity": "suggestion",
    "location": {
      "path": "doc/index.md",
      "lines": {
        "begin": 1
      }
    }
  },
{
    "description": "Consider "documentation" instead of "docs".",
    "fingerprint": "doc/index.md-10",
    "severity": "suggestion",
    "location": {
      "path": "doc/index.md",
      "lines": {
        "begin": 10
      }
    }
  },
{
    "description": "Consider "documentation" instead of "Docs".",
    "fingerprint": "doc/index.md-15",
    "severity": "suggestion",
    "location": {
      "path": "doc/index.md",
      "lines": {
        "begin": 15
      }
    }
  },
{
    "description": "If possible, use "must" instead of "need to".",
    "fingerprint": "doc/index.md-28",
    "severity": "warning",
    "location": {
      "path": "doc/index.md",
      "lines": {
        "begin": 28
      }
    }
  },
{
    "description": "Avoid words like "useful" that imply ease of use, because the user may find this action hard.",
    "fingerprint": "doc/index.md-98",
    "severity": "suggestion",
    "location": {
      "path": "doc/index.md",
      "lines": {
        "begin": 98
      }
    }
  },
{
    "description": "'There are' is not precise. Try rewriting with a specific subject and verb.",
    "fingerprint": "doc/index.md-107",
    "severity": "suggestion",
    "location": {
      "path": "doc/index.md",
      "lines": {
        "begin": 107
      }
    }
  },
{
    "description": "Consider "documentation" instead of "Docs".",
    "fingerprint": "doc/index.md-126",
    "severity": "suggestion",
    "location": {
      "path": "doc/index.md",
      "lines": {
        "begin": 126
      }
    }
  },
]

Lint the JSON output https://jsonlint.com/.

Edited by Achilleas Pipinellis

Merge request reports