Add use_air()

[DavisVaughan]

For posit-dev/air#224

Note that while use_tidy_style() actually invokes styler, use_air() is just about getting your project set up to use Air. The documentation states everything that this does so I won't repeat here.

I can't use jsonlite::write_json() directly due to some fiddly details I documented and talked to @jeroen about, so we have a small shim that mimics it for use with VS Code settings json files.

I've tried to structure these functions with potential future use in mind.

I would not be surprised if writing JSON back to file doesn't result in a perfect roundtrip in terms of formatting, but I think that should be okay, especially if people use version control.

[hadley]

Should this also run air on the whole project?

[DavisVaughan]

Should this also run air on the whole project?

With use_air(), I'm mostly interested in helping people get set up to Format On Save in Positron using recommended best practices (settings.json at the workspace level so its shared among contributors, extensions.json that prompts contributors to install the extension, etc). It does also make air.toml and add to .Rbuildignore, which is also helpful in RStudio.

I think this function is more in line with other one-time-setup helpers than with use_tidy_style() which tries to invoke styler.

---

The current initial workflow for Air in Positron for an existing project looks like:

• Install Air CLI
• Install Air OpenVSX Extension
• usethis::use_air()
• Commit
• air format . one time using the Air CLI to get the whole project in order
• Commit
• Switch to Format on Save using the Air Extension from here on out

The current initial workflow for Air in RStudio for an existing project looks like:

• Install Air CLI
• usethis::use_air()
• Commit
• air format . one time using the Air CLI to get the whole project in order
• Commit
• Switch to Format on Save using Air as an "external formatter" from here on out

I don't think we can improve on RStudio any further unless it bundles Air. But with VS Code / Positron I'd like to remove the CLI from the picture so it looks like:

• Install Air OpenVSX Extension
• usethis::use_air()
• Commit
• Run Air: Format project using the Air Extension
• Commit
• Switch to Format on Save using the Air Extension from here on out

I don't think having use_air() try and invoke Air will be super helpful here, as it will have a pre-req that Air is installed as a command line tool, and in our ideal world that actually won't be the case for Positron users (it'll be bundled in the extension but not available at the command line unless they install it themselves)

[hadley]

Ok, in that case, I'd recommend that you describe that in the docs. Or maybe include a todo bullet to remind the user to also run air format themselves.

[jennybc]

This will be cool! I made a few comments, many of which surface existing patterns in usethis that could be used here.

[jennybc]

There is something of an existing convention where we use can_overwrite() to determine if it's safe to err on the side of making change in a file. If the user has set the usethis.overwrite option to TRUE and we're making changes inside a project that is a Git repo, we just go ahead and do it. I have this set to TRUE in my .Rprofile.

I'm not sure if you'd like to do that here, but just wanted you to know about this pattern.

[DavisVaughan]

I think I'd use that if we were completely overwriting. In this particular case, we want to merge with what the user already has as much as possible, so I think not asking or checking is ok in this case.

I do think I'm going to remove this though

Does nothing if `editor.formatOnSave` was already set.
Does nothing if `editor.defaultFormatter` was already set.

I think we actually should update this, as you've explicitly requested Air with use_air(), so you've opted into these recommended settings already

[jennybc]

Yeah when I first looked at this I thought maybe it was overly cautious / overly respectful of existing settings. Happy to have it just make these changes unconditionally.

[DavisVaughan]

Added a note in the docs about how this does not actually invoke Air, and added this TODO bullet at the end

[jennybc]

The CI failures seem to be related to bad weather at httpbin.org and not related to the content of this PR.

[eitsupi]

I think this operation may fail because settings.json is actually JSONC (JSON with Comments), not JSON.

[DavisVaughan]

Hmm. Darn! jeroen/jsonlite#394