fix(cli_tools): Enclose option help in quotes

[christerswahn]

In the carapace yaml generator, ensure the option help text is formatted with quotes/escapes to that it is correct yaml format.

Summary by CodeRabbit

• Bug Fixes

  • Consistent escaping and quoting of completion help text so special characters appear correctly in generated YAML, improving reliability of shell completions.

• Tests

  • Updated completion spec tests to expect quoted descriptions where needed, reflecting the improved YAML output.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a private _formatYamlStringValue method to CarapaceYamlGenerator to escape backslashes/quotes and wrap values in quotes, and applies it when emitting option help text; tests updated to expect quoted YAML string values.

Changes

Cohort / File(s)	Summary
YAML string formatter packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart	Adds static String _formatYamlStringValue(String) to escape backslashes and quotes and wrap values in quotes; uses it when writing option help text for standard options and negated flags.
Tests updated for quoted output packages/cli_tools/test/better_command_runner/completion_test.dart	Updates expected YAML output to use quoted strings for persistent flag descriptions and flag option descriptions (target, exec-name, file), preserving content but changing representation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat: Support the carapace CLI completions tool #67 — Modifies the same CarapaceYamlGenerator logic; likely a precursor or related change affecting YAML generation.

Suggested reviewers

• SandPod
• nielsenko

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "fix(cli_tools): Enclose option help in quotes" accurately and clearly describes the main change in the changeset. The PR adds a _formatYamlStringValue helper function to properly format option help text with quotes and escape special characters for valid YAML output, which is reflected in both the source code changes and the test updates. The title is specific, concise, and directly conveys the primary objective of the PR without vague terminology or unnecessary noise.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-completion

---

📜 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 86bcc09 and da2a121.

📒 Files selected for processing (1)

• packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart

---

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

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart (1)

123-132: Consider reusing the outer optionHelp variable.

The optionHelp variable is redeclared on line 125 with the same expression as line 116, both formatting option.helpText. Since the outer optionHelp is already in scope, you can eliminate this duplication.

Apply this diff to reuse the outer variable:

     if (option case final FlagOption flagOption) {
       if (flagOption.negatable && !flagOption.hideNegatedUsage) {
-        final optionHelp = _formatYamlStringValue(option.helpText ?? '');
         _writeWithIndent(
           out,
           '--no-${option.argName}$attributes: $optionHelp',
           indentLevel,
         );
       }
     }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a811a6f and 86bcc09.

📒 Files selected for processing (2)

• packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart (2 hunks)
• packages/cli_tools/test/better_command_runner/completion_test.dart (1 hunks)

🔇 Additional comments (4)

packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart (2)

197-201: LGTM! Correct escaping order.

The implementation properly escapes backslashes before quotes, which is essential to avoid double-escaping issues. The method correctly wraps the result in double quotes to produce valid YAML string values.

---

116-119: LGTM! Proper YAML string formatting applied.

The help text is now correctly formatted as a quoted YAML string value, ensuring valid YAML output even when help text contains special characters.

packages/cli_tools/test/better_command_runner/completion_test.dart (2)

156-157: LGTM! Test expectations correctly updated.

The persistent flag descriptions are now properly quoted, matching the new YAML string formatting behavior from the generator.

---

163-165: LGTM! Flag descriptions correctly updated.

The flag help text is now properly quoted in the test expectations, consistent with the YAML string formatting applied by the generator.

[nielsenko]

I suggest handling \t, \n, and \r as well.

[nielsenko]

LGTM 🚀