refactor(settings): use better serialization methods and types#194
Conversation
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
📝 WalkthroughWalkthroughThe changes refactor the settings documentation and validation system to introduce TOML-based rendering for configuration examples and defaults, add structured deprecation error handling, and expand settings metadata with Example and Deprecated fields for enhanced documentation. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 golangci-lint (2.5.0)level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies" Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. 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. Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
internal/settings/settings.go (1)
177-177:⚠️ Potential issue | 🟡 MinorTypo: "accesss" → "access"
"enter.mount_resolv_conf": { - Short: "Bind-mount host 'resolv.conf' inside chroot for internet accesss", + Short: "Bind-mount host 'resolv.conf' inside chroot for internet access",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@internal/settings/settings.go` at line 177, Fix the typo in the command/flag description: locate the Short string that currently reads "Bind-mount host 'resolv.conf' inside chroot for internet accesss" and change "accesss" to "access" so the Short description reads "Bind-mount host 'resolv.conf' inside chroot for internet access"; update the Short field where it is defined (the command's Short property in settings.go).
🧹 Nitpick comments (2)
internal/settings/settings.go (1)
199-203: Minor inconsistency betweenDeprecatedtext andDeprecatedSettingError.Alternative.Line 202:
Deprecated: "Set \confirmation.always` to `true` instead."Line 333:Alternative: "set `confirmation.always` to `true` instead"`The casing ("Set" vs "set") and trailing period differ. These appear in different contexts (docs vs CLI error), so it may be intentional, but worth normalizing for consistency.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@internal/settings/settings.go` around lines 199 - 203, Normalize the deprecation message for the "no_confirm" setting to match the CLI error alternative: update the Deprecated field in the "no_confirm" entry so it reads exactly like DeprecatedSettingError.Alternative (use "set `confirmation.always` to `true` instead" with the same casing and punctuation), ensuring both the Deprecated string in the map and the Alternative value used by DeprecatedSettingError are identical.internal/settings/errors.go (1)
16-24: Embedded newline inError()may surprise callers that expect single-line errors.Go convention is for
Error()to return a single-line string. The multi-line format with\nhint: ...works well for direct user display, but could produce unexpected output if the error is wrapped withfmt.Errorf("...: %w", err)or logged by a structured logger. If this is only used for user-facing CLI output, it's fine — just worth being intentional about.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@internal/settings/errors.go` around lines 16 - 24, DeprecatedSettingError.Error() currently returns a multi-line string which can surprise callers expecting a single-line error; change Error() to return a single-line representation (e.g., combine e.Field, DeprecatedDocString and e.Alternative into one line separated by punctuation like " - hint: " or parentheses) and add a new method (e.g., DetailedMessage() or UserMessage()) that returns the multi-line, user-facing text for CLI output; update references to use DetailedMessage() where multi-line hints are intended and keep Error() as the concise single-line string to satisfy fmt.Errorf/loggers.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@doc/build.go`:
- Around line 293-296: The early "return" when defaultValue == nil causes the
function to exit before writing deprecated notices; instead, stop returning and
only skip rendering the default value so the deprecated block still runs.
Replace the "return" in the defaultValue == nil check with logic that continues
processing (e.g., "continue" if inside a loop) or otherwise skips outputting the
default value but allows the subsequent deprecated rendering code (the block
that writes the deprecation notice around lines where the deprecated message is
emitted) to execute; reference the defaultValue variable and the surrounding
deprecated-rendering code to find and update the flow.
In `@internal/settings/settings.go`:
- Around line 94-99: The example for ssh.private_key_cmd uses a bare slice
(Example = []string{"sh", "-c", "rbw get $NIXOS_CLI_SSH_HOST"}) which causes
toml.Marshal to panic; update the Example value (the DescriptionEntry.Example
usage) to be a map or struct wrapper (e.g. map[string]any{"command":
[]string{...}}) or a raw string so the TOML encoder won't attempt to emit a
root-level slice, and also correct the typo "internet accesss" to "internet
access" in the corresponding description text.
---
Outside diff comments:
In `@internal/settings/settings.go`:
- Line 177: Fix the typo in the command/flag description: locate the Short
string that currently reads "Bind-mount host 'resolv.conf' inside chroot for
internet accesss" and change "accesss" to "access" so the Short description
reads "Bind-mount host 'resolv.conf' inside chroot for internet access"; update
the Short field where it is defined (the command's Short property in
settings.go).
---
Nitpick comments:
In `@internal/settings/errors.go`:
- Around line 16-24: DeprecatedSettingError.Error() currently returns a
multi-line string which can surprise callers expecting a single-line error;
change Error() to return a single-line representation (e.g., combine e.Field,
DeprecatedDocString and e.Alternative into one line separated by punctuation
like " - hint: " or parentheses) and add a new method (e.g., DetailedMessage()
or UserMessage()) that returns the multi-line, user-facing text for CLI output;
update references to use DetailedMessage() where multi-line hints are intended
and keep Error() as the concise single-line string to satisfy
fmt.Errorf/loggers.
In `@internal/settings/settings.go`:
- Around line 199-203: Normalize the deprecation message for the "no_confirm"
setting to match the CLI error alternative: update the Deprecated field in the
"no_confirm" entry so it reads exactly like DeprecatedSettingError.Alternative
(use "set `confirmation.always` to `true` instead" with the same casing and
punctuation), ensuring both the Deprecated string in the map and the Alternative
value used by DeprecatedSettingError are identical.
a7c4d18 to
01cd54e
Compare
When generation documentation, the metadata was often stringly typed, which made serialization of values rather hard.
This was the case for showing default values for more complex TOML types such as maps and slices, as mentioned in #185, and also for showing examples, since these were often directly embedded as markdown in the description.
Let's not even MENTION the differences between
scdocmanpages and Markdown! That was also a huge problem with this code.This PR solves all those problems and uses actual fields in the settings description entries for any examples and deprecation notices, and formats them depending on if they're in a Markdown page or a man page.
Additionally, it serializes all default values using the underlying
koanfTOML serializer (pelletier/go-toml), so no new dependencies are introduced.Summary by CodeRabbit
Documentation
Refactor