chore: improve linting, docs, and export structure #280
Conversation
- Enhanced ESLint configuration by adding new rules and plugins, including `eslint-plugin-import-x` and `eslint-plugin-tsdoc`, to improve code quality and documentation. - Updated `package.json` to reflect the addition of new dependencies and removed obsolete entries. - Refactored the project structure by deleting the `src/1.ts` file and reorganizing exports to streamline the codebase. - Introduced a new `markProcessor` and `parser` module to improve parsing capabilities and maintainability.
|
Warning This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
This stack of pull requests is managed by Graphite. Learn more about stacking. |
|
New dependencies detected. Learn more about Socket for GitHub ↗︎
|
- Removed the 'ae-missing-release-tag' rule from the ESLint configuration. - Added detailed JSDoc comments to various types and interfaces in `nodeTypes.ts`, `types.ts`, `evaluator/types.ts`, `parser/parser.ts`, `typeEvaluator/types.ts`, and `values/types.ts` to improve clarity and public API documentation. - Updated the `parse` function in `parser.ts` to include a public annotation for better visibility in generated documentation.
ricokahler
changed the title
ricokahler
changed the title
judofyr
left a comment
judofyr
left a comment
There was a problem hiding this comment.
This now needs a rebase. It would also be good to split it into separate PRs and not change everything at once.
| "type": "commonjs", | ||
| "exports": { | ||
| ".": { | ||
| "source": "./src/1.ts", |
There was a problem hiding this comment.
Any specific reason why you removed this? The intention of this was to be compatible with new breaking changes of GROQ (the language). In that case we would implement a new export (e.g. "groq-js/2" so that groq-js can still implement version 1 of GROQ through a separate export. The intention of using exports here was in case we would do more drastic changes to e.g. the parser and we would like to keep completely separate versions (and thus improve the possibility of tree shaking).
That said, it's probably not to critical to not have this now. Once we break GROQ we can always release a new minor of groq-js which introduces groq-js/2 and groq-js/1 (but keeps groq-js defaulting to groq-js/1).
2 participants
Motivation
This PR introduces several tooling and structural improvements to enhance code quality, enforce documentation standards, and simplify the package's export configuration. These changes serve as preparatory work for the upcoming refactoring related to the synchronous evaluator, aiming for a cleaner and more maintainable codebase.
Key Changes:
Enhanced Linting:
eslint-plugin-import-xand configured rules to enforce consistent import ordering, style, and prevent duplicates (import-x/order,import-x/consistent-type-specifier-style,import-x/no-duplicates, etc.).eslint-plugin-tsdocand enabled thetsdoc/syntaxrule to validate TSDoc comment syntax, promoting better inline documentation.no-consoleandno-warning-comments.Simplified Export Structure:
src/1.ts.src/_exports/index.ts.package.jsonexportsfield:"."entry point now correctly points tosrc/_exports/index.ts(source) and its correspondingdistfiles."./1"export entry.typesVersionsfield frompackage.jsonas it's no longer needed after removing the specific./1export.API Extractor Configuration:
ae-missing-release-tagrule inpackage.config.ts. TSDoc validation (@public,@internalwithin comments) will be the primary mechanism for controlling API surface visibility going forward.Dependency Updates:
eslint-plugin-import-xandeslint-plugin-tsdoctodevDependencies.pnpm-lock.yamlaccordingly.Impact
./1subpath export.This PR primarily affects the developer experience and internal structure and should not introduce breaking changes for consumers using the main package entry point (
import {...} from 'groq-js').