bmish / eslint-doc-generator Goto Github PK

Some plugins may only define rules and no configs.

Might need an option to specify this URL.

Example current:

💼 This rule is enabled in the following configs: all, recommended.

Example desired:

💼 This rule is enabled in the following configs: all, recommended.

Option:

• --url-configs https://github.com/ember-cli/eslint-plugin-ember#-configurations

By default, we check for a ## Options or ## Config section that mentions all the named options of a rule.

We could make this configurable through an option like:

Similar to how we have a default emoji of ✅ for the common recommended config.

However, I can't think of a general/universal/all emoji to represent the all config.

Perhaps for other common configs as well:

• stylistic / style
• strict 🔒 (example: https://typescript-eslint.io/rules/)

Will unblock:

• platinumazure/eslint-plugin-qunit#242

Might need a config option to specify the path to these if non-standard:

Standard paths:

• README.md
• docs/rules/[rule-name].md

Override options:

• --path-readme
• --path-rule-doc

Also considered:

• --rule-doc-path for grouping with existing rule doc options
• --rule-list-path for grouping with existing rule list options

Each of our tests sets up a mock filesystem using mock-fs in beforeEach() and then tears it down with mockFs.restore(); in afterEach(). This way, the tests can see the desired files, modify, and test them without affecting the actual filesystem.

For some reason, there seems to be a leak from the tests to the actual filesystem. The doc generator is inserting a rules list into README.md in between the marker comments.

<!-- begin rules list -->
<!-- end rules list -->

It's easy to accidentally check this change in. We need to figure out how to avoid this leak.

The CLI options can get very long.

This has been requested by plugin maintainers.

Options:

• cosmiconfig
• sindresorhus/pkg-conf

Also need option file schema validation:

• https://www.npmjs.com/package/ajv (json schema)

See:

• eslint-doc-generator/lib/generator.ts

  Line 94 in 663344b

  deprecated: false, // TODO: figure out how to access `deprecated` property that can be exported from function-style rules.

• eslint-community/eslint-plugin-eslint-plugin#311

Related:

• #353

We currently only check for an ## Options section. Some users may also want to check for other sections like:

• ## Examples
• ## Rule details

Or even disallow certain sections.

This helps enforce documentation consistency.

We could have an option like:

• --rule-doc-section-include
• --rule-doc-section-exclude

Before:

## Rules

Existing rules section content.

After running tool:

## Rules
<!-- begin rules list -->
...
<!-- end rules list -->

Existing rules section content.

Would like to keep a blank line surrounding comment markers in this case. Follow-up to #48.

Originally posted by @bmish in #48 (comment)

Jest is not indicating why function test coverage is not at 100%. We want all coverage to be 100%.

Follow-up to #87.

module.exports = {
  extends: [require.resolve('./other-config')],
};

This causes a crash right now:

$ eslint-doc-generator
eslint-doc-generator/dist/lib/configs.js:15
        const value = config.rules[`${pluginPrefix}/${ruleName}`];
                                  ^

TypeError: Cannot read properties of undefined (reading 'test/no-foo')
    at getConfigsForRule (eslint-doc-generator/dist/lib/configs.js:15:35)
    at getRuleNoticeLines (eslint-doc-generator/dist/lib/rule-notices.js:47:28)
    at generateRuleHeaderLines (eslint-doc-generator/dist/lib/rule-notices.js:93:12)
    at generate (eslint-doc-generator/dist/lib/generator.js:62:32)
    at async Command.<anonymous> (eslint-doc-generator/dist/lib/cli.js:21:9)
error Command failed with exit code 1.

And the extended config needs to be resolved. Maybe ESLint has an API to do this for us.

Before

# Do not use `foo` (`no-foo`)

After

# Do not use `foo` (`test/no-foo`)

Where the plugin is called eslint-plugin-test.

This avoids a potential hiccup since users will need to use the prefix to refer to the rule in their own codebases.

Automatically generate a table/list of configs in the README ## Configs section.

Not sure about this yet. We have the list of configs but we don't know the config descriptions. We do know the config emojis/badges if the user has specified them.

Optional columns:

• Number of rules enabled, warn, or disabled in each config

Related: #20.

We currently check for an ## Options section in a rule doc when a rule has options. We should allow other common names for that section.

Gracefully handle this.

Node 16 Windows CI is failing attempting to add this tool to an eslint plugin in square/eslint-plugin-square#764.

node:internal/errors:477
    ErrorCaptureStackTrace(err);
    ^

Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in: file, data are supported by the default ESM loader. On Windows, absolute paths must be valid file:// URLs. Received protocol 'd:'
    at new NodeError (node:internal/errors:387:5)
    at throwIfUnsupportedURLScheme (node:internal/modules/esm/resolve:1116:11)
    at defaultResolve (node:internal/modules/esm/resolve:1196:3)
    at nextResolve (node:internal/modules/esm/loader:165:28)
    at ESMLoader.resolve (node:internal/modules/esm/loader:844:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:431:18)
    at ESMLoader.import (node:internal/modules/esm/loader:528:22)
    at importModuleDynamically (node:internal/modules/esm/translators:110:35)
    at importModuleDynamicallyCallback (node:internal/process/esm_loader:35:[14](https://github.com/square/eslint-plugin-square/actions/runs/3170797584/jobs/5163651883#step:5:15))
    at loadPlugin (file:///D:/a/eslint-plugin-square/eslint-plugin-square/node_modules/eslint-doc-generator/dist/lib/package-json.js:[20](https://github.com/square/eslint-plugin-square/actions/runs/3170797584/jobs/5163651883#step:5:21):33) {
  code: 'ERR_UNSUPPORTED_ESM_URL_SCHEME'
}
error Command failed with exit code 1.

https://github.com/square/eslint-plugin-square/actions/runs/3170797584/jobs/5163651883

All our tests our in the massive generate-test.ts test file. Sticking to acceptance tests and avoiding most unit tests has been helpful as it has allowed quicker refactoring of functions without having to update a ton of unit tests. But we should split this giant acceptance test file into multiple files based on category of test.

Example:

• @typescript-eslint/eslint-plugin

Many descriptions begin with a lowercase letter as enforced by this lint rule:

https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/main/docs/rules/require-meta-docs-description.md

Also remove any trailing period so the formatting is more like a title.

So the user doesn't have to do it themselves unless they want to.

If an emoji isn't specified for a config, and we don't see a badge for it in the README, automatically add one to the bottom of the README.

We likely want to consider that a rule is enabled by a config even if it's just enabled in an override from the config (not in the top-level rules of the config).

Example from square/eslint-plugin-square#764 (config line).

--ignore-deprecated-rules

Allow specifying the emoji to represent each config.

Examples of config option:

--config-emoji "recommended,✅" (default)
--config-emoji "stylistic,🎨"

To indicate that we have 100% test coverage.

Throw a helpful error message rather than crash.

Separate issue for creating the missing rule docs: #79

This is more common and it's already in the ## Rules section.

Example of eslint-plugin-unicorn combining the fixable/suggestions notices into one:

🔧💡 This rule is [auto-fixable](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) and provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).

https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-array-push-push.md

Config options:

--rule-list-split-by-category
--rule-list-split-by meta.docs.category

This would help unblock adoption in:

• docs.category - https://github.com/ember-cli/eslint-plugin-ember#-configurations
• type - jest-community/eslint-plugin-jest#1263 (comment)

By default, we ignore all in some places. This should be configurable with a repeatable option.

• --ignore-config all
• --ignore-config foo

--init-rule-docs to create any missing rule docs.

Fail if there are no rule docs to create so this option isn't left in place indefinitely.

This would only be useful for someone who hasn't created any docs for their rules yet. In that scenario, this would help save time in getting started with documentation.

The reason we need an explicit option for this (and we don't want to automatically create missing rule docs by default) is because the rule docs might live at a non-standard path and we just didn't detect them. If the plugin has a non-standard rule doc path, the user just needs to specify --path-rule-doc.

Follow-up to #78.

Apparently the library expects that i installed prettier in my project.

node:internal/errors:465
    ErrorCaptureStackTrace(err);
    ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'prettier' imported from ...\node_modules\.pnpm\[email protected]_ypn2ylkkyfa5i233caldtndbqa\node_modules\eslint-doc-generator\dist\lib\markdown.js
    at new NodeError (node:internal/errors:372:5)
    at packageResolve (node:internal/modules/esm/resolve:954:9)
    at moduleResolve (node:internal/modules/esm/resolve:1003:20)
    at defaultResolve (node:internal/modules/esm/resolve:1218:11)
    at ESMLoader.resolve (node:internal/modules/esm/loader:580:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:294:18)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:80:40)
    at link (node:internal/modules/esm/module_job:78:36) {
  code: 'ERR_MODULE_NOT_FOUND'
}
 ELIFECYCLE  Command failed with exit code 1.

EXPECTED RESULT:
shouldn't crash if prettier isn't my project.

ACTUAL RESULT:
crash if prettier isn't my project.

ENVIROMENT:
Windows 10
Node 16

Used by eslint-plugin-unicorn: https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-array-push-push.md

Currently, we only check for error severity.

Related: #21

Needed to unblock: lo1tuma/eslint-plugin-mocha#330

We can use npm-run-all to avoid this for better compatibility.

Not everyone wants to format their docs with prettier. It also creates a big diff when running this tool. By default, we should only use prettier to format the doc sections this tool manages. We could have an option (default off) to use it to format the entire affected docs.

Currently we detect rules enabled with string/number:

{
  "rules": {
    "test/no-foo": "error"
  },
}

We also need to detect the array-style option config:

{
  "rules": {
    "test/no-foo": ["error", {}]
  },
}

https://eslint.org/docs/latest/user-guide/configuring/rules#configuring-rules

We currently use the following rule doc title format:

# Do not use foo (`test/no-foo`)

We should also support another format with just the rule name without description which is also a common format in plugins:

# no-foo

Not sure which should be the default yet.

• --rule-doc-title-format desc-parens-prefix-name (default): # Do not use foo (test/no-foo)
• --rule-doc-title-format desc-parens-name: # Do not use foo (no-foo)
• --rule-doc-title-format prefix-name: # test/no-foo
• --rule-doc-title-format name: # no-foo

Currently, we only checked when rules are enabled.

Related: #68

Right now, we only detect a ## Rules section when looking for where to insert the rules list into the README when the marker comments are missing. While this is the most common section name, we should detect additional variations:

• ## 🍟 Rules (eslint-plugin-ember)
• ## Custom rules (eslint-plugin-square)
• ## List of supported rules (eslint-plugin-react)