Document every option in the generated .solargraph.yml - #1350
Open
apiology wants to merge 4 commits into
Open
Conversation
solargraph config generates a .solargraph.yml, but the file explains nothing about what any option does or accepts - you have to read source or find solargraph.org to make sense of it. type_checker.rules is a good example: it lets you override an individual typecheck rule level (098b067), but nothing in the generated file said so. Adds a CONFIG_DOCS table and Config.commented_yaml, so solargraph config now writes a doc comment above every top-level key, including type_checker.rules. Also fixes a crash in that same command: conf['extensions'] was pushed to when a solargraph-*-ext gem was installed, but the key never existed in the defaults. And two unrelated latent bugs found in passing: Rules#level always returned nil (a wrong hash lookup; nothing in production code reads it, which is why it went unnoticed), and Workspace#rules ignored its level argument after the first call (memoized on the first level requested, regardless of what was asked for later). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UtuMwbDhKyt9bAPC19T5xF
Compress two comments PR 70 added in
lib/solargraph/workspace/config.rb to fit the repo's comment-length
budget.
The CONFIG_DOCS constant docstring dropped from 4 prose lines to 2,
keeping only what a reader can't get from the code: what generates
the comment, and that a missing key renders with none.
The @sg-ignore above the Psych.dump call in commented_yaml was five
lines; the convention here (see lib/solargraph/type_checker/rules.rb)
is a single-line reason. Full diagnostic for anyone re-verifying this
suppression: Psych.dump's RBS signature declares optional kwargs
(indentation:, line_width:, ...) in addition to its positional args,
so `YAML.dump({ key => value })` - a single positional Hash built
with `=>` - gets misread by the type checker as an attempt to pass
those kwargs, producing "Unrecognized keyword argument key to
Psych.dump". Worth filing upstream against castwide/solargraph as a
Psych.dump RBS/kwarg-vs-positional-Hash false positive; not filed as
part of this pass.
A typo in the type_checker rules block of .solargraph.yml took down the whole typecheck run with "comparison of Integer with nil failed". Config#type_checker_rules converts each value with a bare to_sym and never checks it against LEVELS, so report? looked the value up, got nil, and compared an Integer against it. Drop unrecognized overrides at construction and warn, mirroring what the constructor already does for an unrecognized primary level. The rule then falls back to its own default level rather than crashing.
apiology
marked this pull request as ready for review
September 8, 2026 21:15
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR was written by Claude Code on behalf of @apiology.
Problem:
solargraph configwrites a file that says nothing about what any setting does or what values it accepts.type_checker.rulesis the sharpest case: it takes a level name per rule, and nothing in the generated file or an error message says so, while a misspelled level took down the whole typecheck run withcomparison of Integer with nil failed.Solution: Emit a documented comment above each key, and drop rule overrides naming a level that does not exist so a typo warns and falls back instead of raising.