ROX-28263: Custom `roxctl` command usage formatting by parametalol · Pull Request #14376 · stackrox/stackrox

parametalol · 2025-02-21T22:22:09Z

Description

This PR adds implementation of a custom formatter, that indents and wraps flag descriptions:

Options:
    --ca:
        Path to a custom CA certificate to use (PEM format). Alternatively pass 
        the file path using the ROX_CA_CERT_FILE environment variable

    --direct-grpc=false:
        Use direct gRPC (advanced; only use if you encounter connection issues).
        Alternately, enable by setting the ROX_DIRECT_GRPC_CLIENT environment 
        variable to true

    -e, --endpoint='localhost:8443':
        Endpoint for service to contact. Alternatively, set the endpoint via the
        ROX_ENDPOINT environment variable

Instead of the current unreadable nonsense:

Flags:
      --ca string                  Path to a custom CA certificate to use (PEM format). Alternatively pass the file pa
th using the ROX_CA_CERT_FILE environment variable
      --direct-grpc                Use direct gRPC (advanced; only use if you encounter connection issues). Alternately
, enable by setting the ROX_DIRECT_GRPC_CLIENT environment variable to true (default false)
  -e, --endpoint string            Endpoint for service to contact. Alternatively, set the endpoint via the ROX_ENDPOIN
T environment variable (default "localhost:8443")

It also removes the annoying "(default false)" from boolean flags descriptions.

⚠️ The declarative-config commands override the formatter for reasons. This will be addressed in the follow-up PR #14377.

See the new output:
https://github.com/stackrox/stackrox/pull/14376/files#diff-c01d393b2fd1c2f1621101007552a73c3958050590c941c2c6272e26a8efef76

User-facing documentation

CHANGELOG is updated OR update is not needed
documentation PR is created and is linked above OR is not needed

Testing and quality

the change is production ready: the change is GA or otherwise the functionality is gated by a feature flag
CI results are inspected

Automated testing

How I validated my change

Unit tests, bats tests.

Current dependencies on/for this PR:

master
- PR chore(roxctl): Test roxctl command tree #14387
  - PR ROX-28263: Custom roxctl command usage formatting #14376 👈
  - PR ROX-28262: Refactor roxctl command flag inheritance #14377

rhacs-bot · 2025-02-21T22:51:36Z

Images are ready for the commit at 5558939.

To use with deploy scripts, first export MAIN_IMAGE_TAG=4.8.x-195-g5558939b6f.

codecov · 2025-02-21T23:30:20Z

Codecov Report

Attention: Patch coverage is 96.86099% with 7 lines in your changes missing coverage. Please review.

Project coverage is 49.17%. Comparing base (e13fdf0) to head (5558939).
Report is 26 commits behind head on master.

Files with missing lines	Patch %	Lines
roxctl/utils/help_formatter.go	97.34%	2 Missing and 1 partial ⚠️
roxctl/utils/help_writer.go	92.00%	2 Missing ⚠️
roxctl/central/db/restore/v2.go	0.00%	1 Missing ⚠️
roxctl/main.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #14376      +/-   ##
==========================================
+ Coverage   49.11%   49.17%   +0.05%     
==========================================
  Files        2522     2525       +3     
  Lines      184268   184462     +194     
==========================================
+ Hits        90506    90706     +200     
+ Misses      86559    86551       -8     
- Partials     7203     7205       +2

Flag	Coverage Δ
go-unit-tests	`49.17% <96.86%> (+0.05%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

parametalol · 2025-02-23T16:58:29Z

/retest

janisz · 2025-02-24T09:00:23Z

What's the reason behind this change?

parametalol · 2025-02-24T10:03:31Z

What's the reason behind this change?

The reason is to get rid of this embarrassment:

Flags:
      --ca string                  Path to a custom CA certificate to use (PEM format). Alternatively pass the file pa
th using the ROX_CA_CERT_FILE environment variable
      --direct-grpc                Use direct gRPC (advanced; only use if you encounter connection issues). Alternately
, enable by setting the ROX_DIRECT_GRPC_CLIENT environment variable to true (default false)
  -e, --endpoint string            Endpoint for service to contact. Alternatively, set the endpoint via the ROX_ENDPOIN
T environment variable (default "localhost:8443")

janisz · 2025-02-24T12:08:58Z

Could you add a link to kubectl and how it's done there?

Beautify kubectl help flag commands kubernetes/kubernetes#104736

roxctl/maincommand/commands_tree.yaml

tests/roxctl/bats-tests/helpers.bash

roxctl/utils/utils.go

roxctl/utils/help_formatter.go

roxctl/maincommand/command_test.go

roxctl/maincommand/command.go

roxctl/central/db/restore/v2.go

roxctl/central/db/backup/backup.go

janisz

LGTM if you can extract unrelated changes and use term size

parametalol requested a review from a team as a code owner February 21, 2025 22:22

github-actions bot added the area/roxctl label Feb 21, 2025

parametalol mentioned this pull request Feb 21, 2025

ROX-28262: Refactor roxctl command flag inheritance #14377

Draft

9 tasks

parametalol changed the title ~~michael/roxctl-format-usage~~ chore(roxctl): Custom command usage formatting Feb 22, 2025

janisz reviewed Feb 24, 2025

View reviewed changes

roxctl/maincommand/commands_tree.yaml Show resolved Hide resolved

parametalol mentioned this pull request Feb 24, 2025

chore(roxctl): Test roxctl command tree #14387

Merged

9 tasks

parametalol force-pushed the michael/roxctl-format-usage branch 4 times, most recently from 9e9d6af to 52a4a0c Compare February 24, 2025 17:15

parametalol changed the base branch from master to michael/roxctl-command-tree-test February 24, 2025 17:34

parametalol force-pushed the michael/roxctl-format-usage branch from dfc30a4 to 3f832f4 Compare February 24, 2025 17:39

parametalol requested a review from janisz February 24, 2025 17:44