Tighten up the `gen_docs.dart` script.

[lrhn]

Move some functionality into helper functions, to make the overall logic easier to read. Extracted constants, added comments.

Make the script work when called from any directory (finds package root relative to Platform.script, instead of assuming current working directory is the root.)

Remove dependency on package:collection which was only used for one function, in code that was restructured.

General functionality should still be the same (the generated output and JSON cache haven't changed).

[lrhn]

(I fell over the script during something else and wanted to change a little thing. Then it snowballed.)

I'm not entirely sure I understand the point of the "validate" mode, which checks that the cached JSON and generated Markdown are in sync, which they should be when both are written in the same runs of the tool.

It would make more sense to check that the cached JSON is up-to-date with the remote source-of-truth, because if not, we should update both local files, or to generate and write the markdown if it's not in sync with the cached JSON, which can happen if modifying the tool itself. Detecting the markdown being out of sync with the local JSON cache, but only being able to update the markdown by fetching the remote JSON first, is a combination I can find no use for.

[devoncarew]

I'm not entirely sure I understand the point of the "validate" mode, which checks that the cached JSON and generated Markdown are in sync, which they should be when both are written in the same runs of the tool.

Yeah, the way I look at it, we want:

• the lints json metadata file to be updated periodically
• whenever the rule sets change (add a rule, remove a rule, ...), we want the markdown file to be updated, and we want to verify that on the bots so the PR author doesn't forget

Probably that means that in the 'verify only' mode, we can skip downloading a new json file and just use what's in the repo.

[lrhn]

I'll consider a separate change to the logic, where the "verify" mode becomes "rebuild without downloading", so it actually saves the new generated documentation. (And tells you if there are any changes.)

Landing this for now.