documentationjs / gulp-documentation Goto Github PK

• ❌ ci/circleci Your tests failed on CircleCI Details

This is the release I've been waiting for a very long time: one that has only minimal changes to JavaScript!

For the past 6 months, we kept doing changes to various aspects of printing JavaScript, with the hope that one day we would get to a stable place. No automated tool is going to print perfect code for all the possible edge cases. The goal is to find a good place where when people report code that is printed in a funny way, we can't make it better without making other pieces of code look worse, introduce behavior that's very hard to understand for humans and doesn't introduce some disproportionate complexity to the codebase.

We're not 100% there yet, but we're closer than ever!

Now that JavaScript needs for support is trending down, it's an opportunity to support other languages that front-end developers are working on and want formatted. We've introduced TypeScript and CSS in the last release and are doing a batch of fixes for them in this release. We're also adding support for new languages: GraphQL queries, embedding CSS-in-JS and JSON are now available in prettier!

Blog Post: Adding a new layout strategy to Prettier by @karl

Prettier is not only a useful tool but it's also a really cool piece of technology. @karl spent a bunch of time improving JSX support and in the process implemented a new primitive to prettier: fill. He wrote a very interesting blog post Adding a new layout strategy to Prettier that I highly recommend reading if you're interested in how prettier is working behind the scenes.

GraphQL

Thanks to @stubailo, @jnwng, @tgriesser and @azz, prettier now supports printing GraphQL queries!

It works for .graphql files and within JavaScipt templates that start with graphql, graphql.experimental and gql in order to work with Relay and Apollo.

ReactDOM.render(
  <QueryRenderer
    query={graphql`
      query appQuery {
        viewer {
          ...TodoApp_viewer
        }
      }
    `}
    // ...
  />,
  mountNode
);

Note that it only supports the open source syntax of GraphQL, therefore doesn't work with Relay Classic, it only works with Relay Modern.

CSS-in-JS

If you are using styled-components or styled-jsx, prettier will now reformat the CSS inside of your template expressions.

const EqualDivider = styled.div`
  margin: 0.5rem;
  padding: 1rem;
  background: papayawhip;
  > * {
    flex: 1;
    &:not(:first-child) {
      ${props => (props.vertical ? "margin-top" : "margin-left")}: 1rem;
    }
  }
`;

JSON

This was pretty straightforward to implement but nonetheless very useful. Thanks to @josephfrazier for doing it :)

{
  "name": "prettier",
  "version": "1.5.0",
  "description": "Prettier is an opinionated JavaScript formatter",
  "bin": {
    "prettier": "./bin/prettier.js"
  }
}

CSS

I'm really excited because we only put a few days to build the initial CSS support and it has worked surprisingly well. This release brings a handful of important improvements to CSS but nothing that required big changes.

CSS: Every selector is now printed in its own line (#2047) by @yuchi

The biggest unknown when printing CSS was how to deal with multiple selectors. The initial approach we took was to use the 80 columns rule where we would only split if it was bigger than that. Many people reported that they were using another strategy for this: always break after a ,. It turns out that many popular codebases are using this approach and it feels good as you can see the structure of the selectors when layed out on-top of each others.

// Before
.clusterPlannerDialog input[type="text"], .clusterPlannerDialog .uiTypeahead {
// After

.clusterPlannerDialog input[type="text"],

.clusterPlannerDialog .uiTypeahead {

CSS: lowercase hex colors (#2203) by @azz

The concept of code formatting has blurry boundaries. The core aspect of it is around whitespaces but some things like single vs double quotes and semi-colons are usually bundled with it. With prettier on JavaScript, we also lightly reformat strings by removing extra \ and normalize numbers. For CSS, we need to do a similar interpretation of where the boundary ends. For colors, we decided to turn all the letters into lowercase and stop there. Turning rgb() into hex or 6 hex into 3 hex is out of scope.

// Before
.foo {
  color: #AAA;
  -o-color: #fabcd3;
  -ms-color: #AABBCC;
}
// After

.foo {

color: #aa;

-o-color: #fabcd3;

-ms-color: #aabbcc;

}

CSS: Use fill for CSS values (#2224)

The new fill primitive turned out to be very useful for CSS. For long values, instead of breaking and putting a \n before every element, we can instead only put a \n when it goes over the limit. It leads to much better looking code.

// Before
border-left:
  1px
  solid
  mix($warningBackgroundColors, $warningBorderColors, 50%);
// After

border-left: 1px solid

mix($warningBackgroundColors, $warningBorderColors, 50%);

CSS: Allow long media rules to break (#2219)

This is another small fix in the journey of properly supporting a new language. We now encode the ability to break on long @media rules.

// Before
@media all and (-webkit-min-device-pixel-ratio: 1.5), all and (-o-min-device-pixel-ratio: 3/2), all and (min--moz-device-pixel-ratio: 1.5), all and (min-device-pixel-ratio: 1.5) {
}
// After

@media all and (-webkit-min-device-pixel-ratio: 1.5),

all and (-o-min-device-pixel-ratio: 3/2),

all and (min--moz-device-pixel-ratio: 1.5),

all and (min-device-pixel-ratio: 1.5) {

}

CSS: Print @else on same line as } (#2088) by @azz

Less and Scss are turning into real programming languages :) Step by step, we're starting to print all their constructs in the same way as JavaScript. This time, it's the else placement.

// Before
@if $media == phonePortrait {
  $k: .15625;
}
@else if $media == tabletPortrait {
  $k: .065106;
}
// After

@if $media == phonePortrait {

$k: .15625;

} @else if $media == tabletPortrait {

$k: .065106;

}

CSS: implement prettier-ignore (#2089) by @azz

While we want prettier to format the entire codebase, there are times where we "know better" and want an escape hatch. This is where the prettier-ignore comment comes in. It wasn't working for CSS but that was an oversight, now it is implemented :)

// Before
foo {
  /* prettier-ignore */
  thing: foo;
  -ms-thing: foo;
}
// After

foo {

/* prettier-ignore */

thing:     foo;

-ms-thing: foo;

}

CSS: Fix css-modules composes breaking with long line width (#2190) by @tdeekens

In order to be fast, many "packagers" do not parse files in order to extract dependencies but instead use a crude regex. This is a reason why we don't break long require() calls and it happens to also affect CSS Modules. If you add new lines in the composes field, it doesn't recognize it anymore. So we're no longer breaking it there, even if it goes over 80 columns.

// Before
.reference {
  composes: 
    selector 
    from
    "a/long/file/path/exceeding/the/maximum/length/forcing/a/line-wrap/file.css";
}
// After

.reference {

composes: selector from "a/long/file/path/exceeding/the/maximum/length/forcing/a/line-wrap/file.css";

}

CSS: First try scss when there's an @import with comma (#2225)

We made a decision to have only a single high level "parser" for CSS, SCSS and Less even though we are using postcss-less and postcss-scss under the hood. We use a regex to figure out which parser to try first and fallback to the other one if a syntax error is thrown. Unfortunately, for certain features, the first (incorrect) parser doesn't throw and instead skips some elements. So, we need to beef up the regex to make sure we are right for the early detection.

Thankfully, this hack is working well in practice. If we find a lot more edge cases, we'll likely want to do the right thing(tm) and split them into two parsers.

// Before
@import "text-shadow";
// After

@import "rounded-corners", "text-shadow";

TypeScript

TypeScript support is now solid, all the changes for this release are small edge cases.

TypeScript: print arrow function type params on same line as params (#2101) by @azz

The core algorithm of prettier is to expand a group if all the elements do not fit. It works really well in practice for most of JavaScript but there's one case it doesn't handle very well is when there are two groups side by side, in this case: <Generics>(Arguments). We have to carefully create groups such that arguments expand first as this is generally what people expect.

// Before
export const forwardS = R.curry(<
  V,
  T
>(prop: string, reducer: ReducerFunction<V, T>, value: V, state: {[name: string]: T}) =>
  R.assoc(prop, reducer(value, state[prop]), state)
);
// After

export const forwardS = R.curry(

<V, T>(

prop: string,

reducer: ReducerFunction<V, T>,

value: V,

state: { [name: string]: T }

) => R.assoc(prop, reducer(value, state[prop]), state)

);

TypeScript: keep parens around with yield/await non-null assertion (#2149) by @azz

For better or worse, we decided to manually handle adding parenthesis. So when a new operator is introduced, we need to make sure that we add correct parenthesis when nested with any other combination of operators. In this case, we missed await inside of TypeScript !.

// Before
const bar = await foo(false)!;
// After

const bar = (await foo(false))!;

TypeScript: Print {} in import if it's in the source (#2150) by @azz

We use typescript-eslint-parser project that translates TypeScript AST into estree AST in order for prettier to print it. From time to time we're going to find edge cases that it doesn't handle yet. In this case, it didn't give a way to tell that there's an empty {}, which apparently is important for TypeScript. Thankfully, the team is very responsive and they fixed it after we put a workaround inside of prettier.

// Before
import from "@types/googlemaps";
// After

import {} from "@types/googlemaps";

TypeScript: Always break interfaces onto multiple lines (#2161) by @azz

The code that implements interface is shared with the code that prints objects, which contains a rule to keep them expanded if there's a \n inside. But, this is not the intended behavior for interfaces. We always want to expand, like we do for classes, even if it fits 80 columns.

// Before
interface FooBar { [id: string]: number; }
// After

interface FooBar {

[id: string]: number;

}

TypeScript: Fix extra semicolon in ambient typescript declaration emit (#2167) by @azz

no-semi and semi are often requested but on the prettier team we're one step ahead and implemented two-semi for you! Just kidding, it was a bug and is now fixed ;)

// Before
declare module "classnames" {
  export default function classnames(
    ...inputs: (string | number | false | object | undefined)[]
  ): string;;
}
// After

declare module "classnames" {

export default function classnames(

...inputs: (string | number | false | object | undefined)[]

): string;

}

TypeScript: group function params in call/construct signatures (#2169) by @azz

Adding a comment before a method used to take into account the comment length and would often expand the method when it wasn't expected. Thankfully, it was a simple fix, just wrap the output in a group.

// Before
interface TimerConstructor {
  // Line-splitting comment
  new (
    interval: number,
    callback: (handler: Timer) => void
  ): Timer;
}
interface TimerConstructor {

// Line-splitting comment

new (interval: number, callback: (handler: Timer) => void): Timer;

}

TypeScript: Upgrade tsep (#2183) by @azz

This bug was very annoying if you ran into it: anytime you formatted the code, it would add one more _ to the object key!

// Before
obj = {                                                                               
  __: 42
  ___: 42
};
// After

obj = {

_: 42

__: 42

};

TypeScript: break on multiple interface extends (#2085) by @azz

Unlike in JavaScript, TypeScript lets you extend multiple classes at once. It turns out that people use this feature and prettier now does a better job at printing it.

// Before
export interface ThirdVeryLongAndBoringInterfaceName extends AVeryLongAndBoringInterfaceName, AnotherVeryLongAndBoringInterfaceName, AThirdVeryLongAndBoringInterfaceName {}
// After

export interface ThirdVeryLongAndBoringInterfaceName

extends AVeryLongAndBoringInterfaceName,

AnotherVeryLongAndBoringInterfaceName,

AThirdVeryLongAndBoringInterfaceName {}

TypeScript: handle ObjectPattern instead of ObjectExpression inside BinaryExpression (#2238) by @azz

This one isn't very interesting, it's an edge case that's not properly handled in the TypeScript -> estree conversion.

// Before
call(c => { bla: 1 }) || [];
// After

call(c => ({ bla: 1 })) || [];

Preserve lines after directives (#2070)

By supporting TypeScript, prettier is now being used in a lot of Angular codebases which exercises edge cases that were not properly handled. In this case, we didn't preserve empty lines after directives inside of a function.

// Before
export default class {
  constructor($log, $uibModal) {
    "ngInject";
    Object.assign(this, { $log, $uibModal });
// After

export default class {

constructor($log, $uibModal) {

"ngInject";
<span class="pl-c1">Object</span>.<span class="pl-en">assign</span>(<span class="pl-c1">this</span>, { $log, $uibModal });</pre></div>

JavaScript
This release is very light in terms of JavaScript changes, which is awesome. We're starting to see the light at the end of the tunnel and get towards a great pretty printer. We're never going to get to a 100% perfect automatic pretty printer. The goal is that for every issue we get, there are no clear ways to improve the way it is printed without regressing other pieces.
Allow JSX lines to be recombined (#1831) by @karl
The goal of prettier is to have a consistent way to format your code: given an AST, we always print the same way. In two places we had to compromise and read the original format: JSX and Objects. With this change, we're no longer relying on the original input for JSX with text inside. This lets us reflow
// Before
const Abc = () => {
  return (
    <div>
      Please state your
      {" "}
      <b>name</b>
      {" "}
      and
      {" "}
      <b>occupation</b>
      {" "}
      for the board of directors.
    </div>
  );
};
// After

const Abc = () => {

return (

<div>

Please state your <b>name</b> and <b>occupation</b> for the board of

directors.

</div>

);

}

Break on non-literal computed member expression (#2087) by @azz
Printing member chains is the most complicated piece of prettier and we keep finding small tweaks we can do to make it a better experience.
// Before
nock(/test/)
  .matchHeader("Accept", "application/json")[httpMethodNock(method)]("/foo")
  .reply(200, {
    foo: "bar",
  });
// After

nock(/test/)

.matchHeader("Accept", "application/json")

[httpMethodNock(method)]("/foo")

.reply(200, {

foo: "bar",

});

Indent first variable in one-var scenario (#2095) by @azz
Up until recently we haven't done much to support printing multiple variables in a single declaration as the most common practice is to do one variable declaration per variable. For single declarations, we don't want to indent it, but it turns out that we do when there are other ones afterwards, otherwise it looks weird.
// Before
var templateTagsMapping = {
 '%{itemIndex}': 'index',
 '%{itemContentMetaTextViews}': 'views'
},
  separator = '<span class="item__content__meta__separator">•</span>';
// After

var templateTagsMapping = {

'%{itemIndex}': 'index',

'%{itemContentMetaTextViews}': 'views'

},

separator = '<span class="item__content__meta__separator">•</span>';

Allow break with both default named import (#2096) by @azz
This one is an unfortunate regression from 1.4 where we inlined import that only contained a single element. Turns out the definition of a single element allowed a single type and a single element. This is now corrected!
// Before
import transformRouterContext, { type TransformedContextRouter } from '../../helpers/transformRouterContext';
// After

import transformRouterContext, {

type TransformedContextRouter

} from '../../helpers/transformRouterContext';

Turn allowImportExportEverywhere on (#2207) by @zimme
The goal of prettier is to format code people write in practice, so we enable loose/experimental modes for all the parsers we support. Babylon allows you to write import within a function, which is not part of the standard, but it doesn't cost us much to allow it.
// Before
ParseError
// After

function f() {

import x from 'x';

}

Support inline template for new calls (#2222)
We keep adding features for function calls and have to backport them to new calls as they have a different AST node type but in practice we want to treat them the same. This fix refactored the two so that they are going through the same call site, so hopefully should prevent more from sneaking in.
// Before
new Error(
  formatErrorMessage`
    This a really bad error.
    Which has more than one line.
  `
);
// After

new Error(formatErrorMessage</span></span> <span class="pl-s">  This a really bad error.</span> <span class="pl-s">  Which has more than one line.</span> <span class="pl-s"><span class="pl-pds">);

Don't indent + in object value (#2227)
When we switched to using the same heuristic for assignment (a = b) for objects ({a: b}), we forgot to fix the indentation. Now it's fixed.
// Before
var abc = {
  thing:
    "asdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdf" +
      "asdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdf" +
      "asdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdf",
}
// After

var abc = {

thing:

"asdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdf" +

"asdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdf" +

"asdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdf",

}

Handle conditions inside of a ternary (#2228)
Prettier already had a special case when the expression was a conditional but it didn't apply when the conditional was the left part of a ternary. Now it does.
// Before
room = room.map((row, rowIndex) =>
  row.map(
    (col, colIndex) =>
      rowIndex === 0 ||
        colIndex === 0 ||
        rowIndex === height ||
        colIndex === width
        ? 1
        : 0
  )
);
// After

room = room.map((row, rowIndex) =>

row.map(

(col, colIndex) =>

rowIndex === 0 ||

colIndex === 0 ||

rowIndex === height ||

colIndex === width

? 1

: 0

)

);

Add caching for printing (#2259)
With the 1.0 release, we fixed a bug in the printing that introduced an exponential behavior. We've been able to mitigate the biggest issue such that reasonable code didn't time out, but it wasn't completely fixed it. By adding a caching layer at the right spot, we should now be in the clear.
This should make printing the IR of prettier using prettier in debug mode no longer time out.
// Before
...times out...
// After

someObject.someFunction().then(function () {

return someObject.someFunction().then(function () {

return someObject.someFunction().then(function () {

return someObject.someFunction().then(function () {

return someObject.someFunction().then(function () {

return someObject.someFunction().then(function () {

return someObject.someFunction().then(function () {

return someObject.someFunction().then(function () {

return someObject.someFunction().then(function () {

anotherFunction();

});

});

});

});

});

});

});

});

});

Fix variance location (#2261)
We refactored the code that prints modifiers when we introduced TypeScript support and accidentally moved around the variance (+) part before static which is not valid in Flow. This is now fixed.
// Before
class Route {
  +static param: T;
}
// After

class Route {

static +param: T;

}

Miscellaneous
Various fixes for range and cursor tracking (#2266, #2248, #2250, #2136) by @CiGit and @josephfrazier
Both those features were introduced in the last release and we discovered a bunch of issues when actually using them in production. A bunch of them got fixed, if you see more, please report them!

There is a collection of frequently asked questions and of course you may always ask my humans.

• ❌ ci/circleci No test commands were found Details

The new version differs by 2 commits.

• 2790e08 chore(release): 4.2.0
• bc0fc53 feat: add support for package-lock.json (#190)

See the full diff

There is a collection of frequently asked questions and of course you may always ask my humans.

• ❌ ci/circleci No test commands were found Details

The new version differs by 9 commits.

• 5c6d1e6 0.13.4
• b330a22 Add .npmignore (#127)
• b500d3c Update README.md
• 2885443 index.js: minor reformat (#118)
• 0bd9db0 minor: update number of dependent projects (#122)
• 9d027eb Log Node version
• 803e841 Refactor
• df86893 Update CHANGELOG.md
• 41f40b1 Update README.md

See the full diff

There is a collection of frequently asked questions and of course you may always ask my humans.

• ✅ ci/circleci Your tests passed on CircleCI! Details
• ❌ continuous-integration/travis-ci/push The Travis CI build could not complete due to an error Details

The new version differs by 2 commits.

• 008d391 1.6.2
• b198e8d Replace Buffer constructor with buffer-from (#59)

See the full diff

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

<a name"3.4.1">

3.4.1 (2017-04-28)

Bug Fixes

• package: update listr to version 0.12.0 (#155) (21df53ec, closes #142)

The new version differs by 3 commits0.

• 21df53e fix(package): update listr to version 0.12.0 (#155)
• 9f0257f docs: Simplify installation instructions copy (#153)
• f2fbdd4 docs: Remove unnecessary dashes (#154)

false

See the full diff

There is a collection of frequently asked questions and of course you may always ask my humans.

• ❌ ci/circleci No test commands were found Details

Fix

• Proxy cwd if base is set to same value (07e4093) - Closes #129

The new version differs by 2 commits .

• e014ed1 Release: 2.0.2
• 07e4093 Fix: Proxy cwd if base is set to same value (fixes #129)

See the full diff.

There is a collection of frequently asked questions and of course you may always ask my humans.

Greenkeeper has checked the engines key in any package.json file, the .nvmrc file, and the .travis.yml file, if present.

• engines was only updated if it defined a single version, not a range.
• .nvmrc was updated to Node.js 10
• .travis.yml was only changed if there was a root-level node_js that didn’t already include Node.js 10, such as node or lts/*. In this case, the new version was appended to the list. We didn’t touch job or matrix configurations because these tend to be quite specific and complex, and it’s difficult to infer what the intentions were.

For many simpler .travis.yml configurations, this PR should suffice as-is, but depending on what you’re doing it may require additional work or may not be applicable at all. We’re also aware that you may have good reasons to not update to Node.js 10, which is why this was sent as an issue and not a pull request. Feel free to delete it without comment, I’m a humble robot and won’t feel rejected 🤖

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.