Document fix and output behaviour for Node.js API usage

[jlarmstrongiv]

Describe the documentation issue

I would like to run stylelint to fix styles programmatically with the node api.

To compare, prettier has a node api that will format my code input string and return my prettified code output string:

prettier.format(css, { ...prettierConfig, parser: "css" });

However, with stylelint, I receive many other objects with no clear path to just get my linted code back. I dug around in linted.results[0]._postcssResult, but couldn’t find it. I also tried all the formatters.

What solution would you like to see?

I would love to see documentation on how to pass a css string to the stylelint node api and received my fixed css string back

[jeddy3]

@jlarmstrongiv Thanks for the report and for using the template.

The autofixed code is available as the value of the output property in the returned object, but only when the fix property is set to true (otherwise it's the output from the chosen formatter).

For example, the following code:

import stylelint from "stylelint";

const result = await stylelint.lint({
  code: "a { color: hsl(30 10% 15% / 5%) }",
  config: {
    rules: {
      "hue-degree-notation": "angle",
    },
  },
});

console.log(result);

Gives:

jeddy3@MacBook stylelint-test % node node-api.js
{
  cwd: '/Users/jeddy3/Projects/stylelint-test',
  errored: true,
  results: [
    {
      source: '<input css M42saI>',
      deprecations: [],
      invalidOptionWarnings: [],
      parseErrors: [],
      errored: true,
      warnings: [Array],
      ignored: undefined,
      _postcssResult: [Result]
    }
  ],
  output: '[{"source":"<input css M42saI>","deprecations":[],"invalidOptionWarnings":[],"parseErrors":[],"errored":true,"warnings":[{"line":1,"column":16,"rule":"hue-degree-notation","severity":"error","text":"Expected \\"30\\" to be \\"30deg\\" (hue-degree-notation)"}]}]',
  reportedDisables: []
}

(The default formatter for the Node.js API is JSON.)

Whereas:

import stylelint from "stylelint";

const result = await stylelint.lint({
  code: "a { color: hsl(30 10% 15% / 5%) }",
  config: {
    rules: {
      "hue-degree-notation": "angle",
    },
  },
  fix: true,
});

console.log(result);

Gives:

jeddy3@MacBook stylelint-test % node node-api.js
{
  cwd: '/Users/jeddy3/Projects/stylelint-test',
  errored: false,
  results: [
    {
      source: '<input css 1eb_BR>',
      deprecations: [],
      invalidOptionWarnings: [],
      parseErrors: [],
      errored: false,
      warnings: [],
      ignored: undefined,
      _postcssResult: [Result]
    }
  ],
  output: 'a { color: hsl(30deg 10% 15% / 5%) }',
  reportedDisables: []
}

We need to update this part of the docs to reflect that behaviour.

I've labelled the issue as ready to implement. Please consider contributing the documentation fix if you have time.

[jlarmstrongiv]

Thank you @jeddy3 ! That worked perfectly. I updated the docs accordingly in this PR #5971