go-tools
go-tools copied to clipboard
dominikh
website: automate publishing of documentation
Right now, I have to manually deploy the docs at staticcheck.dev – and it's a common occurrence that we add a new check but forget to deploy to staticcheck.dev. New documentation should be pushed automatically from the master branch when pushing to GitHub.
Related to this, it would be useful to have a standardized way to document the checks in a standard format, maybe with a name, tag (or category) and description. Ideally, the list of checks would be standardized across linters that support multiple checks. For example, if we had a common data structure or JSON format for listing the checks, then it would be possible to consume the list across linters. That would make it possible to search linters checks.
https://github.com/golangci/golangci-lint/issues/1767 https://github.com/golangci/golangci-lint/issues/1685
That common format should probably be SARIF: https://docs.oasis-open.org/sarif/sarif/v2.0/csprd02/sarif-v2.0-csprd02.html#_Toc10127747
Though I don't see how this relates to golangci-lint specifically, which uses go/analysis and can access this information directly from Go. Emitting this information in JSON would be interesting to tools that consume diagnostics, such as frontends, not so much to Go software that itself produces diagnostics.
Though I don't see how this relates to golangci-lint specifically, which uses
go/analysisand can access this information directly from Go. Emitting this information in JSON would be interesting to tools that consume diagnostics, such as frontends, not so much to Go software that itself produces diagnostics.
Right, that's why I wrote data struct or JSON. The first thing to do would be to come up with a common format, then figure out the implementation. Yes for golangci-lint ideally this would be consumed as go structs.
golangci/golangci-lint#1685 can be implemented right now, via go/analysis.Analyzer.Name and go/analysis.Diagnostic.Category. golangci/golangci-lint#1767 might indeed need some additional work, as there is nothing to encode "tags". Of course coming up with an agreed upon set of tags is difficult, and kind of up to the consumer, not the producer.
golangci/golangci-lint#1685 can be implemented right now, via go/analysis.Analyzer.Name and go/analysis.Diagnostic.Category. golangci/golangci-lint#1767 might indeed need some additional work, as there is nothing to encode "tags". Of course coming up with an agreed upon set of tags is difficult, and kind of up to the consumer, not the producer.
IMO, for the purpose of static analysis documentation, "category" is semantically equivalent to "tag". I used both terms because I see some linters use the word "tag", others use the word "category", others don't have any categorization. Even the diagnostic documentation uses Category and Tag.
AFAIK, linters generate Diagnostics dynamically at a source position whenever they create an issue. So I'm not sure it's possible to ask the linter "what is the list of diagnostics you can produce?"
IMO, for the purpose of static analysis documentation, "category" is semantically equivalent to "tag".
In the context of go/analysis, they are not. A diagnostic's category acts as a sort of sub-identifier, namespaced under the check's name. For example, the nilness analysis in x/tools has the categories nilderef, nilpanic and others.
This is different from what's suggested in https://github.com/golangci/golangci-lint/issues/1767, which has tags such as "security" and "stylistic issue".
Even the diagnostic documentation uses Category and Tag.
The only reference to "tag" I could find in the documentation was diagnostics being "tagged" with a value. That has a meaning different from tags as suggested in https://github.com/golangci/golangci-lint/issues/1767.
AFAIK, linters generate Diagnostics dynamically at a source position whenever they create an issue. So I'm not sure it's possible to ask the linter "what is the list of diagnostics you can produce?"
That is correct.