nitpick init: Identify styles that are relevant for your project and programming language

[andreoliwa]

Problem

While setting up Nitpick with nitpick init, I want to select only the styles that are relevant for the specific programming languages used in the project.

The default style is opinionated, made for Python only, and probably not a fit for everyone (it's not a fit for my own projects anymore).

Adding only the styles that match the file types present on the project is way more flexible and still auto-configurable.

Possible solution

Each style file should (optionally) have information about the file types it relates to.

• This is done since docs(readme): add a table with the style library (presets) #448; the built-in style files:

1. ...are separated into directories that represent file types (actually, identify tags).
2. ...have a [nitpick.meta] section that can be expanded if needed.

• Add a flag to nitpick init to trigger this auto-detection, e.g. nitpick init --identify
• During nitpick init --identify, scan the files on the project root recursively, and collect a set of identify tags from each file.
  E.g.: {"ini", "text", "python", "json", "rst", "yaml"}
• On the list of styles suggested by nitpick init, display only styles:
  • which match the collected tags above, or
  • styles without any identify_tags (in the any directory)
• Add the identified styles to the [tool.nitpick]style key in Nitpick's config (pyproject.toml or .nitpick.toml)
• Create an empty [tool.nitpick]ignore_on_init_identify key (or some better name) and a comment: "Add here the full path of the styles you want --identify to ignore"
• nitpick init --identify can be configured as a pre-commit hook. Every time a new built-in style is added to nitpick, your projects will have this style (if they have any file with a matching type AKA identify tag)
• nitpick init --identify should be idempotent. It shouldn't duplicate styles if they already exist in any of the lists ([tool.nitpick]style or [tool.nitpick]ignore_on_init_identify)
• The identified styles are loaded as styles relative to the [tools.nitpick]identified_styles_prefix URL (defaults to py://nitpick/resources/...) -> CLI option --library to accept the path to the custom library
  • How do we deal with styles that are not built-in and live in another directory? Think about it
• This feature should play nicely with nitpick init: Specify style url(s) in the command line #458
  • The styles specified in the CLI have precedence and should be added first to [tool.nitpick]style
  • Only then the styles detected by --identify should be appended

---

These ideas below are not needed anymore, because the directory under resources/ already specifies the file type for the style.

One possible use case: a style that can be used only by multiple specific file types and not any.
Right now, I can't think of a real case.
The any directory works.
If someone needs to specify precise tags for the styles in any, this can be done in a separate issue.

• Each style file should have an optional key [nitpick]identify_tags
• This key should accept a list of pre-commit/identify tags
• This list means that the style is related to that identify tag/type. E.g.:
  • black.toml should have [nitpick]identify_tags = ["python"]
  • package-json.toml should have [nitpick]identify_tags = ["javascript"]
  • bash.toml should have [nitpick]identify_tags = ["shell"]
  • commitlint.toml shouldn't have any identify_tags
    • Or maybe an empty list, meaning explicitly "this style has no identify tags on purpose": [nitpick]identify_tags = []
• nitpick init: Interactively select styles to add to the config file #330 should be done before this issue -> Not necessarily

[mjpieters]

I like the idea of using file tags as a mapping to style presets.

Can we make the prefix configurable? So, where you state:

The identified styles should be added as py:// URLs as usual, since they are resources built-in into Nitpick

I'd prefer that to say:

The identified styles are loaded as styles relative to the [tools.nitpick]identified_styles_prefix URL (defaults to py://nitpick/resources/...).

That way we can swap out the styles by providing our own. I guess we'll have to handle missing tags from that (e.g. what to do if there is no {identified_styles_prefix}/kotlin.toml style resource).

[andreoliwa]

Can we make the prefix configurable?

Yeah, this works.

I guess we'll have to handle missing tags from that (e.g. what to do if there is no {identified_styles_prefix}/kotlin.toml style resource).

This implies that you have styles stored somewhere (e.g. in a private repo) that mimics (most of) the directory tree of Nitpick built-ins, right?

---

I'd like somehow to create a "shared Nitpick library" where people could contribute.
Encourage people and projects to add their styles to be shipped as Nitpick built-ins.
Either in individual .toml files or as a "preset".

Right now I'm the only one adding these built-in styles for my own use.
I'd like to also cherry-pick and reuse styles from other people/projects.

---

But maybe I digress, and this whole "managing style files" is getting out of hand and it deserves to be a separate package, as I mentioned in #469.

If only there was some Python package that can handle merging config files like Renovate does with the "extends" keyword, or like ESLint mentioned in #445:

Nitpick reminds me of ESLint configs (like AirBnB's) where there can be a single source that projects can pull from, and any changes can be reflected throughout.

[mjpieters]

This implies that you have styles stored somewhere (e.g. in a private repo) that mimics (most of) the directory tree of Nitpick built-ins, right?

Yes, exactly.

The whole reason I’ve been providing PRs is so we can handle the styles entirely independently ;-) Specifically, because your current Python style is rather far removed from current community best practices (line length 80 with bugbear extensions to 88, as encoded by black), and because I need to guarantee stability for our engineers, I created an internal repository that replaces all of the defaults.

Apart from the exact contents of the default styles, you should definitely consider moving the default styles to a separate repository, just so you can decouple the nitpick release cycle from the default styles.

I’d personally then recommend the styles are then updated to reflect community best practices and consensus a bit more closely, as that would help adoption better.

[andreoliwa]

I will try to keep this ticket shorter because it's already a bit ambitious as it is.

While working on the detection of styles, I'll think about how to deal with styles that are not built-in ones (I added it to the description).

I'll answer your comments above but in #482. 🙂

[mjpieters]

The more I talk with stakeholders in our org about nitpick, the clearer it is to me that this feature would be amazing and of huge value. So, consider this my second thumb-up on the ticket, if it helps increase its priority. 😃

[github-actions]

🎉 This issue has been resolved in version 0.35.0 🎉

The release is available on:

• v0.35.0
• GitHub release

Your semantic-release bot 📦🚀