Add Prettier formatting script

[jsnajdr]

This PR adds support for wp-prettier, a Prettier fork that follows the WordPress code conventions and inserts extra spaces inside parens:

function fun( param ) {
  foo( [ 1, 2 ], ( val ) => {
    return `key-${ val }`;
  } );
}

I've been maintaining the fork for 2+ years, from version 1.5 to the latest 1.18.2, and it's been super-useful in Automattic projects like Calypso or Jetpack.

Add a format-js script to @wordpress/scripts:
There is a new script that can be used to format a source directory like this:

wp-scripts format-js packages/compose

The arguments are a list of files and directories to be formatted (globs are possible, too), and it will format all matching JS files, while respecting the ignores in the default .eslintignore.

Remove conflicting ESLint rules:
Some ESLint rules that guard formatting are known to conflict with Prettier (difference in opinions about what's the "right" format), so I'm disabling these that check for things that are automatically handled by Prettier. There's also an eslint-config-prettier ESLint plugin for that.

Format packages/compose to get a taste of Prettier:
This PR also includes formatting of one small module to get a taste of how the formatting changes look like.

TODO: incremental adoption
One proven way how to adopt Prettier incrementally in a large codebase is this one:

1. Whenever a file is formatted with Prettier, add a /** @format */ pragma at the beginning. That tells the automated tooling to try keep it formatted.
2. In a pre-commit hook, check for @format pragma in the modified file and reformat it before committing if the pragma is present. Can be done with lint-staged tool that we already use.

The tooling for that is NOT in this PR. Can be added later if there's an interest in Prettier in the first place.

[ntwb]

Suggested change

	hasProjectFile( '.prettierrc.config.js' ) ||
	hasProjectFile( 'prettierrc.config.js' ) ||

No leading . period, Prettier uses cosmiconfig, see https://prettier.io/docs/en/configuration.html

[ntwb]

What functionality does the npm: prefix here perform if you don't mind, I've not seen this?

[swissspidy]

It aliases prettier to wp-prettier, so it will actually use the wp-prettier package under the hood. This was introduced in npm 6.9.

[ntwb]

Neat, thanks, this is pretty cool

[gziolo]

We would need to enforce that check-engines requires npm 6.9 or higher by default.

[swissspidy]

Even cooler would be not having to maintain such a fork, but progress is slow on that front: prettier/prettier#5919

[jsnajdr]

Note that even if prettier/prettier#5919 was fixed and we could ship wp-prettier as a plugin, it wouldn't change much. We'd still need to maintain a fork of the JS formatter, and then ship the forked formatter as a plugin that replaces the original JS formatter. The code and the work is still the same, just shipped in different packaging.

I could fix prettier/prettier#5919 myself if needed, but with package aliasing support shipping both in NPM and Yarn, the aliasing method works equally well.

[jsnajdr]

This was introduced in npm 6.9.

Yes, and it's the main reason why I waited so long before proposing to use the fork. Before package aliases, it could be distributed only as a tarball URL or a GitHub tag ref, which is kind of ugly and doesn't support versioning well. Now, distributing forks of things is much cleaner and easier.

[ntwb]

Should this be defined? Some devs like 4 spaces, some 2, even 8.

Leaving this as a developer preference for them to set in their Editor/IDE is in line with how WordPress Core uses .editorconfig by not defining a tab width

[jsnajdr]

useTabs means that the formatted source will contain tabs and editors can display them freely according to their configuration.

tabWidth is needed only to calculate the line length. If the maximum line length is 80, and the code is indented with tabs, what does the line length number even mean? Nothing. We need to define tabWidth to give the tab a dimension.

[ntwb]

Thanks for the explanation 👍🏼

[ntwb]

Thanks for the PR @jsnajdr I've added a couple of comments for starters...

What I would like to see though is how Prettier has, or if it has since we looked at it in #4628, our conclusion at the time was this (copying here for ease ref) #4628 (comment):

Prettier and WordPress are both pretty opinionated, though there's only a couple of instances where those opinions really opposed each other, thankfully ESLint's --fix was able to bring a satisfactory compromise.

To that end examing whats left after WordPress has applied its ESLint fixes to the changes made by Prettier is relatively minor, primarily these changes relate to line length, where Prettier refactors the code to not exceed x characters in length, it does a pretty good job of that for the most part. As noted in the comments above sometimes it's not ideal where and when it does this it makes for poorly formatted code.

For the remaining instances of stylistic formatting that Prettier made we can look to add ESLint rules to detect these style inconsistencies and update our coding standards to match. Hopefully we can contribute ESLint rules and fixes upstream as much as possible for the benefit of all ESLint users.

I don't think Prettier is the right solution for WordPress Core, we'll continue to enhance and iterate our JavaScript Coding Standards with ESLint.

Thanks to everyone who has tested and explored the world of Prettier with us here, I've had a blast testing this, closing this PR now, thanks again everyone 😄

I would love to see how Prettier fares today with some of the issues we raised as concerns:

• Line Length Build Tools: Try prettier + eslint --fix #4628 (comment)
• Inline docs Build Tools: Try prettier + eslint --fix #4628 (comment)
• Indentation Build Tools: Try prettier + eslint --fix #4628 (comment)
• Removing unnecessary brackets Build Tools: Try prettier + eslint --fix #4628 (comment) Build Tools: Try prettier + eslint --fix #4628 (comment)
• Removing brackets Build Tools: Try prettier + eslint --fix #4628 (comment)

[gziolo]

Noting that this PR addresses #2819 which was closed a long time ago due to the issues listed in the previous comment by @ntwb.

[jsnajdr]

I would love to see how Prettier fares today with some of the issues we raised as concerns:

To be honest, the formatting hasn't changed much 🙂 Looking at the concerns that had been raised, I see two where a fix could be proposed upstream:

Botching up alignment of docblock comments inside JSX

<div>
  { /**
   * i'm a docblock
   */ }
</div>;

This is clearly a Prettier bug, as it happens only when the JSX expression container is otherwise empty. Adding anything to it fixes the comment formatting.

Unpleasant breaking of long curry chains with arrowParens=always

const f = ( a ) => ( b ) => (
  c
) => find( a, b, c );

The arrowParens=avoid version of this code doesn't break the line, even if the curry chain is longer than the maximum line length:

const f = a => b => c => // could continue ad infinitum and never breaks
  find( a, b, c );

I think preventing a break for arrow function with a single simple argument is a reasonable change that shouldn't meet much opposition.

---

But formatting details aside, I think the main reason why this new attempt at Prettier is different is that it removes the need for the eslint --fix step. wp-prettier can insert all the whitespace inside parens correctly, as the WordPress convention requires, and doesn't need any other tool to fix it. There is a new parenSpacing option for that.

Everything else, as I see it, are just subtle differences in opinion about how things should be formatted, they are not specific to the "WordPress culture", if you know what I mean, and don't have a rational resolution that everyone can agree on.

If something seems obviously wrong, as the examples above, we can propose patches upstream. The only WordPress-specific difference seems to be the paren spacing.

[ntwb]

Thanks for the detailed reply @jsnajdr 💯

I think it would great to see how this looks on the entire code base, a gist, a fork maybe, then the Gutenberg and WordPress teams can take a closer look...

I'm thinking once the above is available we can document what changes would be required and acceptable to update the WordPress Coding Standards with, and then create a P2 on make.w.org/core for further feedback

[jsnajdr]

I think it would great to see how this looks on the entire code base, a gist, a fork maybe, then the Gutenberg and WordPress teams can take a closer look...

I can reformat the whole codebase and push the diff to this branch. I originally decided to avoid that in order to keep the PR small.

[gziolo]

I can reformat the whole codebase and push the diff to this branch. I originally decided to avoid that in order to keep the PR small.

It would be fun to see a branch with all files formatted :)

[gziolo]

I added prettier as a dependency here as well. I hope it is a good idea.

[ntwb]

Untested, but I "think" this is correct

[gziolo]

@jsnajdr, I regenerated package-lock.json using the latest master version in
d19a844. I think we also need to define prettier as a dependency of @wordpress/scripts to make it work smoothly. Feel free to merge if you agree with the changes applied.

I tested locally with:

npm run lint-js
npm run format-js
npm run lint-js

There were 9 errors reported but they are caused by the next line disable comments no longer working as intended after file reformating.

[jsnajdr]

I think we also need to define prettier as a dependency of @wordpress/scripts to make it work smoothly. Feel free to merge if you agree with the changes applied.

Thanks @gziolo! I think that Prettier doesn't necessarily need to be a dependency of @wordpress/scripts, but let's resolve this in followup discussions about the IDE integration and config files.

Now, let's merge this PR before it gets stale again! 🙂

[gziolo]

Awesome work @jsnajdr, thanks for bringing Prettier to the WordPress community 🎉

[ntwb]

Woot 🥳

Thanks to everyone who contributed along the way, your feedback and patience is greatly appreciated 💯

Special shoutout and thanks @jsnajdr for maintaining, persisting, and persevering for the longest time to bring this to the WordPress project 🙇🏼‍♂️

[gziolo]

I opened #19946 that document this new script added to @wordpress/scripts. @jsnajdr, can you double-check the proposal? Feel free to add your own commits if you feel like it needs more details. I omitted the part about IDEs as it feels like we need to experiment with it a bit first.

[epiqueras]

We need to run prettier on lint if we are not going to enforce the formatting rules through eslint anymore.