feat(plugin): docgen parsing

[unicornware]

Description

✨ Features

• Options?.sourcemap

  Allows users to pass custom sourcemap options (Omit<SourceMapOptions, 'source'>), true to use plugin defaults, or false to disable sourcemap generation. Defaults to true.

• interface PluginReactDocgenTypeScript extends vite.Plugin

  For the developers like me...aka the anal TypeScript developers 😅💙

• Implemented PluginReactDocgenTypeScript.transform

  Parses modules for component docgen info. Build hook transform is called on each module request and can be used to augment individual modules. The hook receives two arguments: the module code to transform (which may already include transforms applied by other plugins), code, and the path to the module, id.

  For successfully parsed and transformed modules, the function will return an updated version of code that includes logic to add a __docgenInfo property to each component exported from id. If options.sourcemap is truthy, the function will also return a version 3 sourcemap.

  If id doesn't meet filtering requirements (set by options.exclude and options.include), the function will return undefined. If id does end up being parsed, but doesn't yield any docgen information, null will be returned instead.

    /**
     * @param {TransformPluginContext} this - Plugin context
     * @param {string} code - Module code being transformed
     * @param {string} id - Path to module being transformed
     * @return {Promise<TransformResult>} Transform result
     */
    transform(
      this: TransformPluginContext,
      code: string,
      id: string
    ): Promise<TransformResult>

♻️ Code Improvements

• Removed Options?.name

  The plugin assumes doc.displayName is the component name when setting __docgenInfo. The name option allows users to generate component names instead (see 🔨 options #1). This option is not needed because the docgen parser already allows users to generate component display names:

      const resolvedComponentName = componentNameResolver(nameSource, source);
      const { description, tags } = this.findDocComment(commentSource);
      const displayName =
        resolvedComponentName ||
        tags.visibleName ||
        computeComponentName(nameSource, source, customComponentTypes);

  parser.ts@2.2.2#L350-L355

  Users exporting multiple components from id should pass options.componentNameResolver, use @visibleName in JSDoc comments, and/or pass options.customComponentTypes. If using @visibleName, eslint-plugin-jsdoc users may need to also update their eslint config:

  /**
   * @file ESLint Configuration
   * @see https://eslint.org/docs/user-guide/configuring
   */
  
  const { Linter } = require('eslint')
  
  /**
   * @type {Linter.Config}
   * @const config - ESLint configuration object
   */
  const config = {
    globals: {
      JSX: 'readonly'
    },
    plugins: ['jsdoc'],
    rules: {
      'jsdoc/check-tag-names': [
        1,
        {
          definedTags: ['visibleName'],
          jsxTags: true
        }
      ]
    },
    settings: {
      jsdoc: {
        structuredTags: {
          visibleName: { required: ['name'] }
        }
    }
  }
  
  module.exports = config

Tests

 RUN  v0.19.1

 ✓ src/__tests__/plugin.spec.ts > unit:plugin > @returns > should return PluginReactDocgenTypeScript
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.apply > should set PluginReactDocgenTypeScript.apply to undefined given [{"apply": undefined}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.apply > should set PluginReactDocgenTypeScript.apply to "build" given [{"apply": "build"}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.apply > should set PluginReactDocgenTypeScript.apply to "serve" given [{"apply": "serve"}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.apply > should set PluginReactDocgenTypeScript.apply to [Function spy] given [{"apply": [Function spy]}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.enforce > should set PluginReactDocgenTypeScript.enforce to "pre" given [{"enforce": undefined}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.enforce > should set PluginReactDocgenTypeScript.enforce to "pre" given [{"enforce": "pre"}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.enforce > should set PluginReactDocgenTypeScript.enforce to "post" given [{"enforce": "post"}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.shouldIncludeExpression > should not throw if ComponentDoc.expression is defined
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.sourcemap > should return Partial<SourceDescription> given [{"sourcemap": undefined}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.sourcemap > should return Partial<SourceDescription> given [{"sourcemap": {"includeContent": true}}]
 ✓ src/__tests__/plugin.spec.ts > unit:plugin > options > options?.sourcemap > should return string given [{"sourcemap": false}]
 ✓ src/__tests__/plugin.functional.spec.ts > functional:plugin > should transform module if id matches include pattern
 ✓ src/__tests__/plugin.functional.spec.ts > functional:plugin > should not transform module if id does not match include pattern
 ✓ src/__tests__/plugin.functional.spec.ts > functional:plugin > should not transform module if id matches exclude pattern
 ✓ src/__tests__/plugin.functional.spec.ts > functional:plugin > should not transform module if docgen info is missing

Test Files  2 passed (2)
     Tests  16 passed (16)
      Time  14.83s (in thread 12.37s, 119.88%)

-----------|---------|----------|---------|---------|-------------------
File       | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
-----------|---------|----------|---------|---------|-------------------
All files  |     100 |      100 |     100 |     100 |                   
 plugin.ts |     100 |      100 |     100 |     100 |                   
-----------|---------|----------|---------|---------|-------------------

Additional context

• Resolve issue with first displayName always being used styleguidist/react-docgen-typescript#441

  This PR will allow users exporting multiple components to forego passing options.componentNameResolver, using @visibleName in JSDoc comments, and/or passing options.customComponentTypes:

  /**
   * Ensure the .displayName is for the currently processing function.
   *
   * This avoids the following situations:
   *
   *  - A file has multiple functions, one has `.displayName`, and all
   *    functions ends up with that same `.displayName` value.
   *
   *  - A file has multiple functions, each with a different
   *    `.displayName`, but the first is applied to all of them.
   */
  const flowNodeNameEscapedText = (statement as any)?.flowNode?.node?.name
    ?.escapedText as false | ts.__String | undefined

  styleguidist/react-docgen-typescript@0dc05e5

Linked issues

closes #2

Submission checklist

• pr title prefixed with PR: (e.g: PR: User authentication)
• pr title describes functionality (not vague title like Update index.md)
• pr targets branch next
• project was run locally to verify that there are no errors
• documentation added or updated

[flexdevelopment]

lgtm 👍🏾