Feature request: Provide a way to link detected issues to their documentation

[radomirbosak]

The checks.md document is a very useful resource to find more about each issue types reported by actionlint.

However, currently there's no straightforward way to find out which documentation section corresponds to which issue. The kind key (in the actionlint json formatting) is not usable for this purpose, since both issues

• https://github.com/rhysd/actionlint/blob/main/docs/checks.md#unexpected-keys
• https://github.com/rhysd/actionlint/blob/main/docs/checks.md#missing-required-keys-or-key-duplicates have kind value syntax-check (it's not 1-to-1 correspondence)

I'm not sure what is the best/easiest way to address this, but maybe a new docs key with either link to https://github.com/rhysd/actionlint/blob/main/docs/checks.md#XYZ or just the section name XYZ would help.

Example:

[
  {
    "message": "pyflakes reported issue in this script: 1:7 undefined name 'hello'",
    "filepath": "myworkflow.yml",
    "line": 9,
    "column": 9,
    "kind": "pyflakes",
    "snippet": "      - run: print(hello)\n        ^~~~",
    "docs": "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#check-pyflakes-integ"
  }
]

Alternatively, the checks.md section names could be named after the kind parameter values, however then it may be useful for the kind values to be more detailed - to distinguish between different types of syntax-check.

What do you think?

[rhysd]

Thank you for suggesting this.

Yes, that's what I thought. When I started to make this tool, the kind field was enough to identify errors. However, the number of checks growing, it was no longer enough.

I think giving IDs to each errors and describing them in the list of checks would be nice like shellcheck. Users can search the page with the ID and easily find the description.

As you know actionlint now has many checks so giving IDs for each error is not so easy and would it take time. So this would not be solved soon.

[radomirbosak]

Thank you for your reply!

I think giving IDs to each errors and describing them in the list of checks would be nice like shellcheck. [...]

[...] So this would not be solved soon.

Nice! If you are not against this idea, then as the first step, let me create an issue for the task of assigning unique IDs to errors. It may take time, but at least the feature request will be tracked and also, somebody can possibly pick it up.

[radomirbosak]

Issue for creating unique IDs is here: https://github.com/rhysd/actionlint/issues/75