fix: Fixes and updates based on learnings from serverpod cli

[christerswahn]

Some fixes and updates based on learnings from migrating the serverpod command to cli_tools 0.5.0-beta.1:

• New Logger.log method with dynamically specified log level
• Downgrades collection dependency to 1.18 to be compatible with serverpod
• Fixes some usage help composition
• Minor API improvements

Summary by CodeRabbit

• Documentation

  • Improved and extended documentation for configuration options, enums, and constructors, including usage examples and clearer parameter explanations.

• New Features

  • Added the ability to externally set the global configuration before running commands.

• Bug Fixes

  • Improved formatting and help string generation for enum and multi-value options.

• Refactor

  • Simplified parser and option constructors for easier usage and consistency.
  • Shifted configuration resolution to parsing phase for streamlined command execution.

• Chores

  • Updated dependency constraints for better compatibility.
  • Updated tests to match constructor changes without altering test logic.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request primarily introduces documentation improvements and refactoring for configuration handling in a command-line utility library. It adds detailed documentation to constructors and classes, clarifies usage of custom validators, and updates help string logic for enum options. The configuration resolution process is refactored so that it occurs during argument parsing rather than command execution. There are also minor API changes, such as altering the constructor signature for MultiParser, and a dependency version downgrade for the collection package. Additionally, a new generic log method was added to the logging interface and implemented in concrete loggers, with corresponding tests added. No functional logic is changed in the tests.

Changes

File(s)	Change Summary
lib/src/better_command_runner/better_command.dart	Added comprehensive documentation to the BetterCommand constructor, explaining parameters and usage with examples. No code logic changes.
lib/src/better_command_runner/better_command_runner.dart	Refactored configuration resolution to occur in the parse method instead of runCommand. Added a setter for globalConfiguration, updated error messages, and clarified comments.
lib/src/config/configuration.dart	Expanded documentation for ConfigOptionBase regarding customValidator. Changed defaultValueString to use valueParser.format. Modified MultiParser constructor to require the parser as a positional parameter.
lib/src/config/options.dart	Updated MultiStringOption constructors to use the new MultiParser constructor signature. Added format override in EnumParser. Improved documentation and logic for EnumOption.valueHelpString. Removed defaultValueString override from DurationOption.
pubspec.yaml	Downgraded collection dependency version constraint from ^1.19.1 to ^1.18.0.
test/config/configuration_type_test.dart	Updated test instantiations of MultiParser to use the new positional constructor argument. No test logic changes.
lib/src/logger/logger.dart	Added a new abstract method log to the Logger interface to support dynamic log levels.
lib/src/logger/loggers/std_out_logger.dart	Refactored to centralize logging logic in the new log method; level-specific methods delegate to it. Added prefix method and adjusted error method to include stack traces.
lib/src/logger/loggers/void_logger.dart	Added override of the new log method with an empty implementation.
test/std_out_logger_test.dart	Added tests verifying the new generic log method produces expected output for different log levels.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant BetterCommandRunner
    participant ConfigResolver
    participant Configuration

    User->>BetterCommandRunner: parse(args)
    BetterCommandRunner->>BetterCommandRunner: super.parse(args)
    BetterCommandRunner->>ConfigResolver: resolve configuration
    ConfigResolver-->>BetterCommandRunner: Configuration
    BetterCommandRunner->>BetterCommandRunner: set globalConfiguration
    BetterCommandRunner-->>User: ArgResults

    User->>BetterCommandRunner: runCommand()
    BetterCommandRunner->>BetterCommandRunner: use globalConfiguration

Loading

Possibly related PRs

• refactor!: Clarified BetterCommandRunner output/logger setup #29: Refactors BetterCommandRunner and BetterCommand to replace separate logging callbacks with a unified MessageOutput class for output handling; related to output/logging but focuses on interface refactoring rather than documentation and configuration changes.
• fix!: Previously missed renaming of messageOutput #31: Modifies the BetterCommand constructor parameter from passOutput to messageOutput, related to the same class whose constructor documentation is updated in this PR.

Suggested reviewers

• SandPod

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8889aa7 and 56742cf.

📒 Files selected for processing (4)

• lib/src/logger/logger.dart (1 hunks)
• lib/src/logger/loggers/std_out_logger.dart (5 hunks)
• lib/src/logger/loggers/void_logger.dart (1 hunks)
• test/std_out_logger_test.dart (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• lib/src/logger/loggers/void_logger.dart

🔇 Additional comments (6)

test/std_out_logger_test.dart (1)

40-78: Tests are well-implemented for the new log method

The tests validate that the new generic log method correctly forwards logs to the appropriate output streams with the expected formatting for each log level. The test approach is consistent with the existing testing pattern, ensuring parity between level-specific methods and the new flexible log method.

lib/src/logger/logger.dart (1)

38-46: Good API improvement with the generic log method

The addition of the log method provides flexibility for dynamically selecting log levels at runtime, which is a valuable enhancement to the logging interface. The method signature is consistent with existing level-specific methods and includes appropriate documentation.

lib/src/logger/loggers/std_out_logger.dart (4)

15-23: Useful utility method for log level prefixes

The _levelPrefix static method efficiently centralizes the prefix formatting logic using Dart's modern switch expression syntax. This makes the code more maintainable by avoiding duplicate prefix strings.

---

54-54: Good refactoring to reduce code duplication

Updating the level-specific methods to delegate to the new log method reduces code duplication and improves maintainability. This is good software engineering practice following the DRY principle.

Also applies to: 63-63, 72-72

---

76-86: Improved error logging to include stack traces

The error method now properly handles stack traces by appending them to the message before delegating to the log method. This ensures that stack traces are consistently formatted and displayed.

---

88-110: Well-implemented centralized logging method

The implementation of the log method effectively centralizes styling and prefixing logic based on log levels, improving maintainability. The code handles both ANSI-capable and non-ANSI terminals appropriately.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[Isakdl]

LGTM