Export CLI reference as JSON

[Silic0nS0ldier]

The goal of this prototype is to create a better CLI reference. With this extractor prototype completed, work on the UI/UX can now begin.

• For Bazel 5.4.1
• For Bazel 6.2.0
• For Bazel 6.5.0
• For Bazel 7.0.0
• For Bazel 8.0.0-pre.20240108.6

Some notes on the data.

1. Select commands inherit options from an abnormal source. These options will have configuration in their associatedScopes property. Commands which inherit this will have usesConfigurationOptions = true.
2. Commands can inherit options, build being the best known example. coverage and cquery are outliers, inheriting from test.
3. To reduce repetition, all possible options have been consolidated into a single list. As hinted at in (1) associatedScopes indicates what a command belongs to ((command)|startup|common|configuration). Inheritance logic should be applied to this field to determine definitively if an option belongs to a command.
4. Normally hidden fields are included, though properties exist to detect if a field should be hidden.
5. Some fields may not make sense or be inconsistent with the existing Bazel CLI reference. There is business logic applied in other codepaths that this new code may not be applying.

Sample output.

{
    "options": [
        [
            "bazelrc",
            {
                "associatedScopes": [
                    "startup"
                ],
                "helpText": "The location of the user .bazelrc file containing default values of Bazel options. /dev/null indicates that all further `--bazelrc`s will be ignored, which is useful to disable the search for a user rc file, e.g. in release builds.\nThis option can also be specified multiple times.\nE.g. with `--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc`,\n  1) x.rc and y.rc are read.\n  2) z.rc is ignored due to the prior /dev/null.\nIf unspecified, Bazel uses the first .bazelrc file it finds in the following two locations: the workspace directory, then the user's home directory.\nNote: command line options will always supersede any option in bazelrc.",
                "abbreviation": null,
                "allowsMultiple": false,
                "hasNegativeOption": false,
                "isExpansionOption": false,
                "deprecationWarning": "",
                "oldName": "",
                "warnOldName": true,
                "documenationCategory": "bazel_client_options",
                "valueHelp": "<path>",
                "optionExpansions": [],
                "implicitRequirements": [],
                "optionEffectTags": [
                    "changes_inputs"
                ],
                "optionMetadataTags": []
            }
        ],
        ...
    },
    "commands": {
        "analyze-profile": {
            "shortDescription": "Analyzes build profile data.",
            "isHidden": false,
            "triggersBuild": false,
            "mustRunInWorkspace": false,
            "completion": "path",
            "usesConfigurationOptions": false,
            "inherits": []
        },
        ...
    },
    "optionEffectTags": {
        "unknown": {
            "description": "This option has unknown, or undocumented, effect."
        },
        ...
    },
    "optionMetadataTags": {
        "experimental": {
            "description": "This option triggers an experimental feature with no guarantees of functionality.",
            "hidden": false,
            "internal": false
        },
        ...
    }
}

[github-actions]

Thank you for contributing to the Bazel repository! This pull request has been marked as stale since it has not had any activity in the last 1+ years. It will be closed in the next 90 days unless any other activity occurs. If you think this PR is still relevant and should stay open, please post any comment here and the PR will no longer be marked as stale.