feat(plugin): docgen parsing

.cspell.json

@@ -13,6 +13,7 @@
   "failFast": false,
   "flagWords": [],
   "ignorePaths": [
+    "**/*.snap",
     "**/.gitignore",
     ".cspell.json",
     ".env*",

.dictionary.txt

@@ -17,9 +17,11 @@ esbenp
 esbuild
 fbca
 fpnv
+frec
 gifv
 gpgsign
 iife
+jsxdev
 lcov
 lintstagedrc
 micnncim
@@ -32,9 +34,11 @@ nums
 nvmrc
 ohmyzsh
 pdel
+picomatch
 rcmdnk
 safecrlf
 syncer
+telejson
 tsnode
 tspaths
 vates

.eslintignore

@@ -3,6 +3,7 @@
 
 # DIRECTORIES & FILES
 **/.DS_Store
+**/*.snap
 .eslintcache
 .yarn/*
 CHANGELOG.md

.eslintrc.base.cjs

@@ -53,11 +53,24 @@ const config = {
     node: true
   },
   extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
-  globals: {},
+  globals: {
+    Chai: 'readonly',
+    Console: 'readonly',
+    JSX: 'readonly',
+    LoadHook: 'readonly',
+    LoadHookContext: 'readonly',
+    LoadHookResult: 'readonly',
+    LoaderHookFormat: 'readonly',
+    NodeJS: 'readonly',
+    ResolveFilename: 'readonly',
+    ResolveHook: 'readonly',
+    ResolveHookContext: 'readonly',
+    ResolveHookResult: 'readonly'
+  },
   parser: require.resolve('@typescript-eslint/parser'),
   parserOptions: {
     ecmaFeatures: {
-      jsx: Boolean(tsconfig.compilerOptions.jsx ?? false),
+      jsx: Boolean(tsconfig.compilerOptions.jsx),
       impliedStrict: true
     },
     emitDecoratorMetadata: tsconfig.compilerOptions.emitDecoratorMetadata,
@@ -518,7 +531,7 @@ const config = {
     'jsdoc/check-tag-names': [
       1,
       {
-        definedTags: ['fixme', 'link', 'maximum', 'minimum'],
+        definedTags: ['visibleName'],
         jsxTags: true
       }
     ],
@@ -543,27 +556,7 @@ const config = {
     ],
     'jsdoc/no-restricted-syntax': 0,
     'jsdoc/no-types': 0,
-    'jsdoc/no-undefined-types': [
-      1,
-      {
-        definedTypes: [
-          'Chai',
-          'Console',
-          'JSX',
-          'LoadHook',
-          'LoadHookContext',
-          'LoadHookResult',
-          'LoaderHookFormat',
-          'NodeJS',
-          'ResolveFilename',
-          'ResolveHook',
-          'ResolveHookContext',
-          'ResolveHookResult',
-          'never',
-          'unknown'
-        ]
-      }
-    ],
+    'jsdoc/no-undefined-types': [1, { definedTypes: ['never', 'unknown'] }],
     'jsdoc/require-asterisk-prefix': [1, 'always'],
     'jsdoc/require-description-complete-sentence': 0,
     'jsdoc/require-description': [
@@ -908,6 +901,7 @@ const config = {
         '@typescript-eslint/no-base-to-string': 0,
         '@typescript-eslint/no-unused-expressions': 0,
         '@typescript-eslint/restrict-template-expressions': 0,
+        '@typescript-eslint/unbound-method': 0,
         'chai-expect/missing-assertion': 2,
         'chai-expect/no-inner-compare': 2,
         'chai-expect/no-inner-literal': 2,
@@ -1233,10 +1227,17 @@ const config = {
           name: 'namepath-defining',
           required: ['type']
         },
+        type: {
+          name: 'namepath-defining',
+          required: ['type']
+        },
         var: {
           name: 'namepath-defining',
           required: ['name']
         },
+        visibleName: {
+          required: ['name']
+        },
         yield: {
           name: 'namepath-defining',
           required: ['type']

.eslintrc.cjs

@@ -15,6 +15,12 @@ const config = {
   extends: ['./.eslintrc.base.cjs', './.eslintrc.react.cjs'],
   overrides: [
     ...base.overrides,
+    {
+      files: ['__fixtures__/**'],
+      rules: {
+        'unicorn/filename-case': 0
+      }
+    },
     {
       files: ['build.config.ts'],
       rules: {

.github/dependabot.yml

@@ -20,7 +20,6 @@ updates:
       separator: '-'
     rebase-strategy: auto
     target-branch: next
-    versioning-strategy: increase
   - package-ecosystem: npm
     directory: /
     schedule:
@@ -29,7 +28,10 @@ updates:
       prefix: build
       include: scope
     ignore:
+      - dependency-name: '@storybook/react'
       - dependency-name: '@types/node'
+      - dependency-name: '@types/styled-components'
+      - dependency-name: styled-components
     labels:
       - type:build
     open-pull-requests-limit: 5

.husky/pre-push

@@ -6,4 +6,4 @@
 #
 # - https://vitest.dev/guide/cli.html#changed
 
-yarn test --changed
+yarn test --changed HEAD^

.prettierignore

@@ -4,6 +4,7 @@
 # DIRECTORIES & FILES
 **/.gitignore
 **/.gitkeep
+**/*.snap
 .eslintcache
 .eslintignore
 .husky/_/*

.vscode/settings.json

@@ -5,6 +5,12 @@
   "[javascript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
+  "[jest-snapshot]": {
+    "editor.rulers": [120],
+    "editor.wordWrap": "wordWrapColumn",
+    "editor.wordWrapColumn": 120,
+    "rewrap.wrappingColumn": 120
+  },
   "[json]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
@@ -39,6 +45,7 @@
     "typescriptreact"
   ],
   "files.associations": {
+    "*.snap": "jest-snapshot",
     ".env.zsh": "shellscript",
     ".markdownlintignore": "ignore",
     "commit-msg": "shellscript",
@@ -79,6 +86,11 @@
       "format": "svg",
       "icon": "tsconfig"
     },
+    {
+      "extensions": ["snap"],
+      "format": "svg",
+      "icon": "vitest"
+    },
     {
       "extensions": ["yarnrc.yml"],
       "format": "svg",
@@ -91,6 +103,11 @@
       "format": "svg",
       "icon": "data"
     },
+    {
+      "extensions": ["__snapshots__"],
+      "format": "svg",
+      "icon": "temp"
+    },
     {
       "extensions": ["setup"],
       "format": "svg",

README.md

@@ -49,15 +49,15 @@ npmScopes:
 
 ## Built With
 
-- [magic-string][1]
-- [micromatch][2]
+- [@rollup/pluginutils][1]
+- [magic-string][2]
 - [react-docgen-typescript][3]
-- [ts-dedent][4]
+- [telejson][4]
 
-[1]: https://github.com/Rich-Harris/magic-string
-[2]: https://github.com/micromatch/micromatch
+[1]: https://github.com/rollup/plugins/tree/master/packages/pluginutils
+[2]: https://github.com/Rich-Harris/magic-string
 [3]: https://github.com/styleguidist/react-docgen-typescript
-[4]: https://github.com/tamino-martinius/node-ts-dedent
+[4]: https://github.com/storybookjs/telejson
 [5]: https://vitejs.dev
 [6]:
   https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries

__fixtures__/Button.stories.tsx

@@ -0,0 +1,20 @@
+/**
+ * @file Fixtures - Button Stories
+ * @module fixtures/Button.stories
+ */
+
+import type { Meta, Story } from '@storybook/react'
+import Button, { CounterButton, type CounterButtonProps } from './Button'
+
+export default {
+  args: Button.defaultProps,
+  component: Button,
+  parameters: {},
+  title: 'Button'
+} as Meta<CounterButtonProps>
+
+export const Counter: Story<CounterButtonProps> = (
+  args: CounterButtonProps
+) => {
+  return <CounterButton {...args} />
+}

__fixtures__/Button.tsx

@@ -0,0 +1,113 @@
+/**
+ * @file Fixtures - Button
+ * @module fixtures/Button
+ */
+
+import {
+  forwardRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type ForwardedRef
+} from 'react'
+import s, { css } from 'styled-components'
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * Button background color.
+   *
+   * @default 'black'
+   */
+  $bg?: ButtonHTMLAttributes<HTMLButtonElement>['color']
+
+  /**
+   * Button text color.
+   *
+   * @default 'white'
+   */
+  $color?: ButtonHTMLAttributes<HTMLButtonElement>['color']
+
+  /**
+   * Button font size.
+   *
+   * @default '1.25rem'
+   */
+  $fontsize?: number | string
+
+  /**
+   * Mark button as disabled.
+   */
+  disabled?: boolean
+}
+
+interface CounterButtonProps extends ButtonProps {
+  /**
+   * Initial click count.
+   *
+   * @default 0
+   */
+  count?: number
+}
+
+/**
+ * Renders an HTML `<button>` element.
+ *
+ * @see https://developer.mozilla.org/docs/Web/HTML/Element/button
+ * @see https://developer.mozilla.org/docs/Web/API/HTMLButtonElement
+ *
+ * @visibleName Button
+ */
+const Button = s.button.attrs<ButtonProps>(p => ({
+  'aria-disabled': p.disabled ?? undefined,
+  'aria-hidden': p.hidden ?? undefined
+}))<ButtonProps>(p => {
+  return css`
+    background-color: ${p.$bg};
+    color: ${p.$color};
+  `
+})
+
+Button.defaultProps = {
+  $bg: 'black',
+  $color: 'white',
+  $fontsize: '1.25rem',
+  type: 'button'
+}
+
+/**
+ * Renders a button that displays how many times it has been clicked.
+ *
+ * @param {CounterButtonProps} [props={}] - Component props
+ * @param {ForwardedRef<HTMLButtonElement>} [ref] - `<button>` reference
+ * @return {JSX.Element} Counter button markup
+ */
+const CounterButton = forwardRef(function (
+  props: CounterButtonProps = {},
+  ref?: ForwardedRef<HTMLButtonElement>
+): JSX.Element {
+  const { count, ...rest } = props
+
+  const [clicks, setclicks] = useState<number>(count!)
+
+  /**
+   * Increases {@link clicks}.
+   *
+   * @return {void} Nothing when complete
+   */
+  const increment = (): void => setclicks(prev => prev + 1)
+
+  return (
+    <Button {...rest} onClick={increment} ref={ref}>
+      {clicks}
+    </Button>
+  )
+})
+
+CounterButton.displayName = 'CounterButton'
+CounterButton.defaultProps = {}
+
+export {
+  Button as default,
+  CounterButton,
+  type ButtonProps,
+  type CounterButtonProps
+}