fix(eslint): improve JSDoc config for TS #317
Conversation
🦋 Changeset detectedLatest commit: 453737a The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
💡 Enable Vercel Agent with $100 free credit for automated AI reviews |
WalkthroughUpdates the @mheob/eslint-config JSDoc ESLint configuration: adds explicit file globs ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Code Review - PR #317SummaryThis PR improves the JSDoc ESLint configuration for better TypeScript support. The changes are well-motivated and generally sound. Positives✅ TypeScript-specific rules - Switching from ✅ Explicit file targeting - Adding ✅ Proper changeset - The changeset is well-documented with clear descriptions of all changes ✅ Follows conventions - Commit message follows conventional commits pattern as per the project's requirements Issues & Considerations1. JSDoc Comment Requirement Logic (packages/eslint-config/src/configs/jsdoc.ts:31-33)The new configuration requires JSDoc on arrow functions but not on regular function declarations: { require: { ArrowFunctionExpression: true, FunctionDeclaration: false } }Concern: This seems counterintuitive for TypeScript projects because:
Suggestion: Consider reversing this or making both optional, especially since 2. Missing JSDoc Update (packages/eslint-config/src/configs/jsdoc.ts:5-13)The function's JSDoc comment still mentions * including the recommended rules, no-restricted-syntax, reject-any-type,Recommendation: Update the JSDoc to reflect the current rule set. 3. Changeset Message (.changeset/whole-cobras-knock.md)The changeset ends without a newline, which could cause issues with some tools. Minor fix: Add a newline at the end of the file. Security & Performance✅ No security concerns identified VerdictThe PR is approved with minor suggestions. The core changes are solid, but the arrow function requirement deserves reconsideration based on TypeScript best practices. 🤖 Review generated by Claude Code |
mheob
force-pushed
the
fix-jsdoc-react-ts
branch
from
366229c to
99665fc
Compare
Code Review for PR #317: fix(eslint): improve JSDoc config for TSOverviewThis PR improves the JSDoc ESLint configuration by switching to TypeScript-specific recommended rules and adding explicit file targeting. The changes are well-motivated and generally improve the configuration. ✅ Strengths
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.claude/commands/create-commit.md (1)
20-20: Fix grammatical error in instruction."Omit mention Claude" is awkward phrasing. Use "omit mentioning Claude" or simply "omit Claude as author and generator."
Apply this diff:
- Please omit mention Claude as author and generator. + Please omit mentioning Claude as author and generator.
🧹 Nitpick comments (1)
packages/eslint-config/src/configs/jsdoc.ts (1)
5-14: Update JSDoc comment to reflect removed rule.The JSDoc comment mentions
no-restricted-syntax, but according to the PR summary, this rule was removed. Please update the comment to accurately reflect the current configuration./** * Configures the ESLint rules for JSDoc. * * This function sets up the necessary ESLint plugin for JSDoc, * including the `eslint-plugin-jsdoc`. It also configures the rules for JSDoc, - * including the recommended rules, no-restricted-syntax, reject-any-type, + * including the recommended rules, reject-any-type, * reject-function-type, require-jsdoc, require-next-type, and tag-lines rules. * * @returns Promise that resolves once the JSDoc ESLint rules are configured. */
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.changeset/whole-cobras-knock.md(1 hunks).claude/commands/create-commit.md(1 hunks)packages/eslint-config/src/configs/jsdoc.ts(2 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
.changeset/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
Create a changeset for any user-facing change
Files:
.changeset/whole-cobras-knock.md
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/any-inside-generic-functions.mdc)
**/*.{ts,tsx}: When building generic functions in TypeScript, it is acceptable to use 'any' inside the function body if TypeScript cannot match runtime logic to type logic.
Outside of generic functions, use 'any' extremely sparingly in TypeScript code.Unless explicitly required by the framework, do not use default exports in TypeScript files.
**/*.{ts,tsx}: Use TypeScript for all code. Prefer interfaces over types.
Follow the ESLint rules.
Use "function" keyword for pure functions.
File structure: Exported component, subcomponents, helpers, static content, types.
Avoid unnecessary curly braces in conditional statements.
For single-line statements in conditionals, omit curly braces.
Use concise, one-line syntax for simple conditional statements (e.g., if (condition) doSomething()).
Handle errors and edge cases at the beginning of functions.
Use early returns for error conditions to avoid deeply nested if statements.
Place the happy path last in the function for improved readability.
Avoid unnecessary else statements; use if-return pattern instead.
Use guard clauses to handle preconditions and invalid states early.
Implement proper error logging and user-friendly error messages.
Consider using custom error types or error factories for consistent error handling.
Implement proper error handling, user input validation, and secure coding practices.
Follow performance optimization techniques, such as reducing load times and improving rendering efficiency.
Provide clear and concise comments for complex logic.
Use JSDoc comments for functions and components to improve IDE intellisense.
**/*.{ts,tsx}: Proactively use discriminated unions to model data that can be in one of a few different shapes.
Use switch statements to handle the results of discriminated unions.
Use discriminated unions to prevent the 'bag of optionals' problem (i.e., avoid interfaces with multiple optional properties that can represent impossible states).
**/*.{ts,tsx}: Do not introduce new en...
Files:
packages/eslint-config/src/configs/jsdoc.ts
🧠 Learnings (3)
📓 Common learnings
Learnt from: CR
PR: mheob/config#0
File: CLAUDE.md:0-0
Timestamp: 2025-10-09T12:39:52.494Z
Learning: Applies to eslint.config.ts : Maintain the root ESLint configuration in eslint.config.ts
📚 Learning: 2025-10-09T12:39:52.494Z
Learnt from: CR
PR: mheob/config#0
File: CLAUDE.md:0-0
Timestamp: 2025-10-09T12:39:52.494Z
Learning: Applies to commitlint.config.js : Maintain the Commitlint configuration in commitlint.config.js to enforce conventional commits
Applied to files:
.claude/commands/create-commit.md
📚 Learning: 2025-10-09T12:39:52.494Z
Learnt from: CR
PR: mheob/config#0
File: CLAUDE.md:0-0
Timestamp: 2025-10-09T12:39:52.494Z
Learning: Follow the conventional commits specification for all commit messages
Applied to files:
.claude/commands/create-commit.md
🧬 Code graph analysis (1)
packages/eslint-config/src/configs/jsdoc.ts (1)
packages/eslint-config/src/globs.ts (2)
GLOB_JS(4-4)GLOB_TS(7-7)
🔇 Additional comments (2)
packages/eslint-config/src/configs/jsdoc.ts (2)
1-1: LGTM: Explicit file targeting improves clarity.The addition of
GLOB_JSandGLOB_TSimports and their use in thefilesarray makes the configuration more explicit and easier to understand.Also applies to: 21-21
17-17: Config name verified as correct.The "flat/recommended-typescript" config is supported by eslint-plugin-jsdoc, confirming the change at line 17 is valid and properly targets TypeScript-specific JSDoc rules.
- Use flat/recommended-typescript instead of flat/recommended - Add explicit file targeting with GLOB_JS and GLOB_TS - Remove jsdoc/no-restricted-syntax rule - Configure jsdoc/require-jsdoc for arrow functions only
mheob
force-pushed
the
fix-jsdoc-react-ts
branch
from
99665fc to
453737a
Compare
|
PR Review: JSDoc Configuration ImprovementsI've reviewed this pull request and have the following feedback: ✅ Strengths
|
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @mheob/eslint-config@8.14.5 ### Patch Changes - [#317](#317) ([@mheob](https://github.com/mheob)): Updated JSDoc rules: - Added explicit file targeting with GLOB_JS and GLOB_TS - Switched from flat/recommended to flat/recommended-typescript config - Removed jsdoc/no-restricted-syntax rule - Updated jsdoc/require-jsdoc to not require JSDoc on ArrowFunctionExpression or FunctionDeclaration
Summary
Improved JSDoc ESLint configuration to better support TypeScript projects by using TypeScript-specific recommended rules and adding explicit file targeting.
Changes
flat/recommendedtoflat/recommended-typescriptconfigGLOB_JSandGLOB_TSjsdoc/no-restricted-syntaxrulejsdoc/require-jsdocto not require JSDoc on ArrowFunctionExpression or FunctionDeclarationMotivation
The previous configuration used generic JSDoc recommended rules which were not optimized for TypeScript. The TypeScript-specific preset provides better defaults for TypeScript projects. Additionally, requiring JSDoc on arrow functions (which are more commonly used in modern codebases) while making it optional for function declarations provides better documentation coverage without being overly restrictive.
Summary by CodeRabbit
Style
Chores