Add postprocess config file option (useful for applying prettier formatting)

[G-Rath]

This makes it easy to efficiently apply formatters like prettier after docs have been updated but before they're written to disk - this saves having to run such formatters across more files than necessary which on large codebases can be a decent time save.

Since it requires a function, you have to use a js-based config file i.e.:

const prettier = require('prettier');
const { prettier: prettierRC } = require('./package.json');

const config = {
  postprocess: content =>
    prettier.format(content, { ...prettierRC, parser: 'markdown' }),
};

module.exports = config;

The function is expected to return a promise to future-proof, since prettier is making all its public APIs async in v3, and it's all being done in an async function so there's not a strong downside.

This should be fully implemented (its working well locally with eslint-plugin-jest), but I've not had a chance to write any tests (I'm actually having some trouble with the cli tests not completing) so am opening as a draft to get an initial review and check that you're interested in this feature.

Also a possible extension to this could be to support a path to a file that exports a function when being used from the command line, though that might be overkill and should be landable in a followup PR anyway.

[bmish]

Awesome! This is much better / more flexible than the built-in prettier formatting I had implemented in a previous version (removed in #188).

Aside from tests, it will need to be mentioned in the README.md of course.

And do you think the single-word spelling postprocess is more common than postProcess?

Also as a heads up, I'll be releasing v1.0.0 very soon (days). This isn't a breaking change so it doesn't block anything.

[G-Rath]

do you think the single-word spelling postprocess is more common than postProcess?

I favored postprocess because that's what the matching config option is called in ESLint itself, and it seemed fitting to match.

[G-Rath]

@bmish I'd appreciate any pointers you might have on what tests you'd like and where to put them :)

[bmish]

Since this is a new option, you can create option-postprocess-test.ts which passes this option with a trivial post-processing function (perhaps just adding a comment to the file), uses mockFs like most of the other tests, and then ensures the output file has the correct post-processing applied (comparing to a snapshot)

[bmish]

For the README, we can add an example config file using this option to the prettier section. We can mention and link to that section from the Configuration options section.

[G-Rath]

hmm @bmish I'm having some trouble which might be related to #288, where my new test file just hangs indefinitely apparently due to mock-fs i.e.

import mockFs from 'mock-fs';

describe('my test', () => {
  it('is true', () => {
    expect(true).toBe(true);
  });
});

Results in:

eslint-doc-generator on  support-postprocess [!+?] is 📦 v0.26.1 via  v16.15.0 took 7s
❯ nrun test option-postprocess-test
> nrun.js test
> node --max-old-space-size=4096 --experimental-vm-modules node_modules/jest/bin/jest.js --colors --coverage option-postprocess-test
jest-haste-map: Haste module naming collision: eslint-plugin-test
  The following files share their name; please adjust your hasteImpl:
    * <rootDir>/test/fixtures/cjs/package.json
    * <rootDir>/test/fixtures/cjs-config-extends/package.json


 RUNS  test/lib/generate/option-postprocess-test.ts
^C

eslint-doc-generator on  support-postprocess [!+?] is 📦 v0.26.1 via  v16.15.0 took 11m35s

I was having this earlier with the CLI tests but they seemed to have come right - it feels like maybe something is trying to compile or load every single file on disk or in the project (including node_modules), though I can't rule that out easily due to the heavy use of enums which prevents isolatedModules from being used.

I'll try and dig into it a bit further, but would be good to have your eyes on it too.

[bmish]

A few things:

• Avoid using Node 14 locally to avoid Node 14 Windows CI tests failing sometimes #288
• Make sure tsc compiles everything without errors--if there are any type issues, the tests will hang
• Make sure to copy / start from one of the existing tests with mock-fs as there's some setup needed to get it to work correctly

[G-Rath]

if there are any type issues, the tests will hang

hmm right ok looks like this was the issue, thanks.

[bmish]

Thank you! This is great.