feat(eslint-plugin) new rule: require `@since` annotations

luc122c commented 7 months ago

Hi there! This is work towards resolving https://github.com/nuxt/nuxt/issues/24950. This PR adds a new rule: require-jsdoc-since. The purpose of this rule is to check exported functions and make sure they have a JSDoc with a @since annotation.

Methodology

Filter only ExportNamedDeclaration and ExportDefaultDeclaration
Filter out TSInterfaceDeclaration and TSTypeAliasDeclaration
Get leading comments
- If there are none, then report missing JSDoc
Check for a valid JSDOC with @since annotation
- If there is none then report missing annotation

Issues

Because it is looping over all definitions and checking individually, it is not aware of overloads. This leads to cases where a JSDoc defines a function with overloads, but the new rule reports that the overloads are missing valid JSDoc comments.

Any help would be appreciated 😄

Development

I have made the following modifications to my local copy of Nuxt to test this. If there is a better way to integrate te types, please let me know as I'll need to make a PR to integrate this into Nuxt next :)

// eslint.config.mjs
// ...
  .override('nuxt/rules', {
    files: [
      // Here we define which files get checked
      'packages/*/src/utils.ts',
      'packages/nuxt/src/app/composables/*.ts',
      'packages/nuxt/src/app/utils.ts',
    ],
    rules: {
      // Override removed this default. 
      // Is there a better way to do this?
      'nuxt/prefer-import-meta': 'error',
      'nuxt/require-jsdoc-since': 'error',
    },
  })
// ...

// package.json
{
  // ...
 "resolutions": {
    // ...
    "@nuxt/eslint-plugin": "../eslint/packages/eslint-plugin",
    // ...                           ^ My local copy
  }
  // ...
}

Testing

I have created a test file, but I have absolutely no idea how to run it. I would appreciate it if anyone could help 😃

luc122c commented 5 months ago

@antfu I would really appreciate some pointers, hopefully I'm on the right track.

antfu commented 3 months ago

Thank you, but I am not sure this plugin is useful to general Nuxt apps. If you mean have it for the Nuxt's core repo, it should goes to https://github.com/nuxt/nuxt/blob/main/eslint.config.mjs, but not here. Thanks.

luc122c commented 3 months ago

Oh, I misunderstood. I thought this was the config for the Nuxt core.

nuxt / eslint