Read config from file

[molawson]

While I love that there are very few configuration options, since there are some, what do you think about having the CLI read a configuration file in addition to the arguments that are passed in?

In most cases, it's not too much effort to make sure you're passing in the options you want (and I particularly like the ability to dynamically define rake tasks with the options already specified!), but that becomes a bit unwieldy with multiple projects that use different options. E.g., the VS Code extension lets you specify those options, but they're applied globally. Switching projects means I need to remember to update my editor to match the options for syntax_tree. Having a per-project config file would let that (and other) editor integrations "do the right thing" in each repo.

If you're open to it, I'd be happy to make a pass at implementing the necessary changes.

[xeger]

Just a quick note that the VS Code extension lets you define a custom wrapper script for the stree command, which lets you customize the CLI options, ensure a specific Ruby interpreter version, or apply other tweaks. (There are some limitations e.g, only one instance of stree per editor window, which can be an issue in monorepos that use many ruby versions or have many gem files.)

I'd love to know more about your use case for the VS Code plug-in, as I am working on adapting it for larger repos myself.

Independently of that, I'd love to hear specifics on your request for config files. Which flags would you put into a config file? Or, would you put the list of files to operate on into the config? (There is a Unix convention for the latter that might be very palatable, even without a config file as such.)

[molawson]

@xeger Great questions! I haven't dug much into the particulars of the VS Code extension (I'm usually in vim, but I'm doing some work to make sure we're setup well with a range of editors). And really, the VS Code extension was just an example of the sort of thing that could be improved with a config file.

But going with that example, while you can set syntax_tree options in the VS Code extension (even on a per-workspace basis), those options are now local to your dev environment. In a team environment, if any of those options change for a repo, we've got to make sure that everyone updates their extension settings to match. That's painful and error-prone. And that pain is amplified by the number of tools you may have to run syntax_tree commands (rake task, CI step, etc.).

What I'm aiming for generally is the ability to store the config options alongside the code itself (I'm not really even thinking about large monorepos that may want differing configs in the same repo). That would help keep the code in-sync with the options being used by syntax_tree, and if it's baked into SyntaxTree::CLI, it'll work for any tool that calls stree. I imagine this is why so many projects like this end up with a config of some sort (e.g. RuboCop, ESLint, prettier & its plugins, etc.).

Which flags would you put into a config file? Or, would you put the list of files to operate on into the config?

Ideally, we could put anything in that config file that we can pass to the CLI: plugins, print width, paths, etc. Especially since there aren't many options to begin with, supporting all of those seems reasonable.

[xeger]

At my org, we commit VS Code workspace settings files to our Git repo, and those settings override developers' user-level settings for a few specific items, such as Syntax Tree. This keeps everyone consistent w/r/t Ruby formatting (and JS linting, and debugger configuration, etc).

When you widen the scope to use of other tools (e.g. Rake tasks) that involve a deeper process tree, then I can certainly see your point. I'm reminded of Bundler and Rubocop, which both support configuration files, but Rubocop does it extremely poorly and Bundler does it exceptionally well.

The Bundler model:

• traverse all the way up to $HOME until you find a Gemfile (since cwd may be a subdir of the project)
• merge Gemfile-level settings and user-level settings
• allow overrides of those settings via env vars

The Rubocop model:

• look in cwd for a .rubocop, or in the dir you tell me with -c

The full Bundler model is probably overkill for stree, but it has the lovely usability benefit that no tool (or human) ever needs to specify any options when invoking the tool -- it finds its own config using a flexible convention.

Stree's Rake tasks do something lovely for me: determine which source files to pass to the CLI automatically. They also halfway solve the config-specification problem, though I notice we haven't added all of the new options to them.

I've directed my developers to those Rake tasks, if they need to double-check that everything is formatted well and that their editor has been correctly formatting as they go. We also use the Rake tasks in CI.

There's also the issue that the config needs to be duplicated between them, and of course not all of the tools we work with are prepared to run Rake instead of stree ... still: perhaps those Rake tasks could contribute to a solution for your org if they were flexible enough to capture all of the relevant options in a DRY manner?

[molawson]

Committing VS Code workspace settings in a repo is handy, but we're not all using VS Code. And the tool we've got to share some of these configs across repos does use the rake tasks (or our own version of them until #123 or something like it is ready). The rake tasks handy for a "format all the things" sort of task, but they're not as helpful for editor integrations since they take a static list of source files.

I've tried a number of different routes for using the gem as-is to integrate well with a range of editors and other tools. We started to go down the road of using the rake tasks but we pretty quickly hit the issue of the added overhead that rake brings with it (about an extra second compared to running stree directly). That isn't a big deal when formatting multiple files, but it becomes painful and sluggish in an editor "write on save" setup.

I currently have a setup where we have a custom executable that calls SyntaxTree::CLI directly, passing in our particular options. And that works ok but still has shortcomings with certain integrations because we're now further away from the standard stree executable.

Each step in this process has left me feeling like the ideal solution to the shortcomings in these other approaches would be support for a SyntaxTree config file.

Is there a general reticence to add config file support to SyntaxTree::CLI?

As you mentioned with RuboCop and Bundler, there are a variety of ways this could be implemented (I'd also add standardrb and Sorbet as further examples in Ruby). And some are certainly more complicated than others. I'm all for starting with the simplest solution that works and building additional features if/when they feel necessary.

There's something really nice to me in the simplicity of Sorbet's config that's a text file with the command line arguments separated onto separate lines. There's no YAML parsing and there's a fairly simple path to letting explicit options passed from the command line interact with what's in the config file.

Most other Ruby projects like this tend to reach for YAML, which would be fine too. But I'm struggling to find a project like this that doesn't have support for a config file. It seems to be a reasonable, well-paved path for a number of the issues we've talked through here.

Is there an appetite to do the same in SyntaxTree? If so, I'm happy to take a swing at the implementation with as much or as little guidance and input from the maintainers as they'd like. How would you feel about me working up a PR at least as a starting place to have more concrete discussions about approach and usability?

[kddnewton]

Merged in #125. That'll be out in the next release.

[xeger]

Sorry for the late reply @molawson - but I see you JFDI'd, and that our conversation persuaded the primary maintainer. Thanks for the contribution!

[molawson]

@xeger You weren't late at all! And I really appreciate you working through this with me. You helped clarify a lot and whittle away the unimportant bit. Thanks!

[kddnewton]

This is now released in version v3.3.0.