valid-types: Add more type checks #308

l1bbcsg · 2019-07-04T12:41:05Z

Fixes #305 .

All of the problems mentioned in the issue are solved, but I'm not entirely sure the solution's perfect.

Namely, there's a lot of complexity because there are tags that may have a name, a type or a description and tags must have a name, a type or a description and each of this sets intersect with every other.

The changes introduced in this PR:

The rule became stricter as it now checks more and reports more errors as a result. Some previously overlooked errors may now be reported as well.
Some error messages changed, namely Syntax error in type: (note the empty string) now became more specific Tag @tag must have a type or Tag @tag must have a namepath
Parsing of @see tag has changed. Previously @see {@link http://foo.bar} was parsed as having type @link http://foo.bar which definitely not something that should happen. I made {@link http://foo.bar} a description.

The following became unintentionally valid:

/**
 * @typedef {number|string}
 */

I think it's fine, at least as far as this rule is concerned. The type is valid, so is jsdoc itself.
The fact that it's missing typedef name via variable declaration could probably be handled by another rule. This was done to allow GCC syntax.

Also, this is valid with previous and current checks, but shouldn't be (Array<string> is not a valid identifier). This happens because both type and namepath are checked the same way via jsdoctypeparser.

/**
 * @typedef {StringArray} Array<string>
 */

test/rules/assertions/validTypes.js

brettz9

Some useful contributions, thank you. There are a number of questions/concerns, in part due to jsdoc not being a strict validation spec.

test/rules/assertions/validTypes.js

src/jsdocUtils.js

src/iterateJsdoc.js

src/jsdocUtils.js

test/rules/assertions/validTypes.js

* master: feat(require-description-complete-sentence): validate explicit `description` tags fix(check-types): remove template substitution variables, `badType`, `preferredType`, and `replacement` (gajus#310) feat: remove `preferredTypesDefined` option in favor of making it apply automatically feat(check-tag-names): auto-allow tags in `tagNamePreference` setting to be defined; add `definedTags` option to replace `additionalTagNames.customTags` setting feat(check-tag-names): allow rejecting normally valid tag names and/or providing custom error messages when suggesting tags to reject or replace (fixes gajus#108) Allow rejecting normally valid tag names and/or providing custom error messages when suggesting tags to reject or replace (gajus#302) docs: indicate option defaults (fixes part of gajus#256) and ensure optioins all listed in docs chore: update Babel devDeps. feat(no-undefined-types): handle GCC generic functions docs: generate docs Add an invalid test case for incorrect @template type fix: reverse jsdoctypeparser update until traversal issue with "external:..." can be fixed feat: bump jsdoctypeparser to 5.0.0 docs: generate docs Add support for generic functions in addition to classes

* master: feat(match-description): allow `description` and `desc` tags to be matched for validation refactor: use template string when appropriate

* master: docs: correct docs refactor: change option extraction codes refactor: leverage `settings` property from `iterateJsdoc.js` for consistent settings access docs: update docs feat(`require-example`): move settings to options feat(`require-jsdoc`): move settings to options feat(`valid-types`): move settings to options feat(`require-returns`): move settings to options fix(`check-examples`): make `escape-regex-string` a dependency, as it should have been (fixes gajus#314) # Conflicts: # README.md # src/rules/validTypes.js # test/rules/assertions/validTypes.js

* master: refactor: fix code comment docs(require-description, require-example, require-param, require-returns): add reference to potentially applicable settings, removing reference to deprecated items docs: make explicit default for setting `ignorePrivate` and clarify setting

…-type-checks-to-valid-types * commit 'f44b25ed4cb521116a682a0d8d10406f3440cec7': refactor: simplify iterateJsdoc

* master: feat(`require-param`): remove deprecated settings `allowOverrideWithoutParam`, `allowImplementsWithoutParam`, `allowAugmentsExtendsWithoutParam` feat(`check-examples`): move settings to options (fixes gajus#216)

* master: feat(`require-description`): add `descriptionStyle` option to accept implicit descriptions as satisfying the rule by default (fixes gajus#301) feat(`match-description`): allow arbitrary tags; also fixes `returns`/`return` to avoid skipping matching of an initial "name" and space

* master: (46 commits) feat(require-description-complete-sentence): limit checking to certain default tags likely to have descriptions or by `tags` array for additional choices; fixes gajus#337 docs(newline-after-description): indicate applies on doc block docs(match-description): add alias `desc` to separate column docs(match-description): indicate application by default to `description`/`desc` and allowance for `property`/`prop`; clarify fix(match-description): ensure `prop` and `property` matching excludes name testing(require-param): fix test source (part of gajus#332) testing(require-param): fix test expectation (part of gajus#332) docs: generate docs chore: update devDeps (eslint-config-canonical, gitdown) fix(no-undefined-types): ensure working in all contexts; fixes gajus#324 refactor(iterateJsdoc): reduce retrieval calls docs(check-examples): allow for whitespace at end feat(check-examples): add `paddedIndent` option fix(check-examples): preserve whitespace so as to report issues with whitespace-related rules such as `indent` (fixes gajus#211) chore(travis): fix Travis to use older unicorn version that supports Node 6 (and the canonical config that requires the earlier unicorn version) docs(require-returns, require-returns-check): indicate that these will report if multiple `returns` tags are present refactor: use `String.prototype.repeat` over lodash `repeat` refactor: apply (jsdoc-related) eslint rule fixes chore: add `lint-fix` script fix(newline-after-description): avoid matching duplicate or partial matches within tag descriptions after the block description; fixes gajus#328 ...

* master: fix(match-description, require-description-complete-sentence): do not report blocking of tag by user for `description` tag (the tag is not required by these rules) fix(require-description): only report blocking of description tag by user if "tag" option is set fix(require-description, implements-on-classes, check-param-names, check-tag-names, require-param, require-returns, require-returns-check, require-hyphen-before-param-description, require-param-description, require-param-name, require-param-type, require-returns-description, require-returns-type): only report blocking of tag by user if problematic tag is present; fixes gajus#332

* master: chore: change the process for generatng readme fix: Fix wrong alignment docs: generate docs fix: Exclude line slicing by zero. chore: update comment-parser and gitdown deps. fix: Fix trim bug in trimCode docs: generate docs fix: Remove unformatted space

* master: feat: add fixer for no-types (gajus#350) fix(check-param-names): ensure polyfilling `Object.entries` for Node 6 fix(check-param-names): provide fixer duplicate param names (remove extra); partial fix for gajus#47 chore(npm): update deps (comment-parser, lodash) and devDep (husky, mocha) fix(require-param): reporting all missing jsdoc params (gajus#348) docs(check-examples): fix heading level docs(readme): remove section "Reference to jscs-jsdoc" chore: update Babel devDeps

…o nothing with missing description); fixes part of gajus#336

… need to handle gajus#11 )

feat(*): have doc block retrieval allow or require additional preceding empty lines via min/max line setting API

…ents

…ajus#360)

l1bbcsg · 2019-08-08T14:32:52Z

Apologizes for dying on this PR, both work and vacation happened.

I updated it and addressed all comments I believe.

* master: chore: update devDeps (llinting, husky)

test/rules/assertions/validTypes.js

src/jsdocUtils.js

test/rules/assertions/validTypes.js

src/jsdocUtils.js

test/rules/assertions/validTypes.js

* master: chore: report unused disable directives in eslint refactor: remove unused disable directives fix(require-jsdoc): avoid exported functions possessing jsdoc blocks causing other non-public functions to be treated as exported; fixes gajus#358 refactor(require-jsdoc): remove redundant check docs(require-returns): Fix typo chore: update devDeps; avoid `lint-staged` Add type "symbol" to noUndefinedTypes chore: update `lint-staged` for husky issue: typicode/husky#247 chore(CI): stop running broken npm script `check-readme` fix(no-undefined-types): avoid `flat-map-polyfill` entirely; further further fix for gajus#366 fix(check-tag-names): ensure `replacement` field overrides a default tag name preference; fixes gajus#367 chore: update comment-parser dep. and devDeps; avoid buggy eslint6.2 and for eslint 6 tests, avoid breaking typescript-eslint/parser update fix(`no-undefined-types`): import flat-map polyfill directly to avoid renamed `flatten` method from polluting prototype (gajus#366)

…nd query both

…sForNamepaths` option on

brettz9

Looks good now (note, I did make a few subsequent minor additions/changes). I've added some of the GCC-specific to-dos to #356.

gajus · 2019-09-01T05:15:35Z

🎉 This PR is included in version 15.9.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

feat(valid-types): Add more type checks

f5c485d

l1bbcsg commented Jul 4, 2019

View reviewed changes

test/rules/assertions/validTypes.js Outdated Show resolved Hide resolved

l1bbcsg commented Jul 4, 2019

View reviewed changes

test/rules/assertions/validTypes.js Outdated Show resolved Hide resolved

brettz9 requested changes Jul 5, 2019

View reviewed changes

l1bbcsg and others added 26 commits July 5, 2019 16:34

Fix reported line numbers

4f71560

docs: generate docs

4549593

Merge branch 'master' into add-more-type-checks-to-valid-types

efa0e68

* master: feat(match-description): allow `description` and `desc` tags to be matched for validation refactor: use template string when appropriate

Merge commit 'f44b25ed4cb521116a682a0d8d10406f3440cec7' into add-more…

47472d0

…-type-checks-to-valid-types * commit 'f44b25ed4cb521116a682a0d8d10406f3440cec7': refactor: simplify iterateJsdoc

Merge branch 'master' into add-more-type-checks-to-valid-types

89cd7f9

* master: feat(`require-param`): remove deprecated settings `allowOverrideWithoutParam`, `allowImplementsWithoutParam`, `allowAugmentsExtendsWithoutParam` feat(`check-examples`): move settings to options (fixes gajus#216)

fix(require-example): add fixer for missing declaration (though can d…

ea3e057

…o nothing with missing description); fixes part of gajus#336

fix(require-param): skip destructuring; fixes gajus#352 (though still…

c8d0611

… need to handle gajus#11 )

feat: allow empty line between jsdoc and jscode (gajus#353)

19a6590

feat(*): have doc block retrieval allow or require additional preceding empty lines via min/max line setting API

fix(require-returns-check): check WithStatement for return statem…

37e8300

…ents

fix(require-jsdoc): add fixer to add empty jsdoc block

b48cf1d

docs(require-returns-check): update docs

e456c50

refactor(require-returns): simplify util.hasReturnValue

c3b56c6

feat(check-types): Add symbol and bigint to native types (fixes g…

23846fc

…ajus#360)

chore: update devDeps and apply comma-dangle linting rule

982debb

Cleanup after merging

2bfe7d8

docs(valid-types) Update readme

44f98a4

Merge branch 'master' into feature/add-more-type-checks-to-valid-types

403c9db

Completely ignore @see {@link ...} tag in parser

5e0f9a5

l1bbcsg added 2 commits August 8, 2019 21:14

Refactor utils naming

b897250

Add couple more tests and reuse some utilites to fix coverage

668ea89

l1bbcsg and others added 2 commits August 8, 2019 21:56

Call namepaths namepath instead of types in error messages

bccfebe

Merge branch 'master' into add-more-type-checks-to-valid-types

cb02b85

* master: chore: update devDeps (llinting, husky)

brettz9 reviewed Aug 10, 2019

View reviewed changes

test/rules/assertions/validTypes.js Show resolved Hide resolved

brettz9 reviewed Aug 10, 2019

View reviewed changes

src/jsdocUtils.js Show resolved Hide resolved

brettz9 reviewed Aug 10, 2019

View reviewed changes

test/rules/assertions/validTypes.js Show resolved Hide resolved

brettz9 reviewed Aug 10, 2019

View reviewed changes

src/jsdocUtils.js Outdated Show resolved Hide resolved

brettz9 reviewed Aug 10, 2019

View reviewed changes

src/jsdocUtils.js Show resolved Hide resolved

brettz9 reviewed Aug 10, 2019

View reviewed changes

test/rules/assertions/validTypes.js Show resolved Hide resolved

brettz9 added 4 commits September 1, 2019 08:12

refactor: remove mandatory type items from optional type items list a…

6b7ab34

…nd query both

docs: add todo comment to ensure handling gcc when mode added

24e8a57

refactor: rename variable without redundant "either"

439fd99

brettz9 mentioned this pull request Sep 1, 2019

JSDoc/GCC/TypeScript mode #356

Closed

13 tasks

brettz9 added 2 commits September 1, 2019 12:31

testing: remove namepath in test checking for empty namepath

6081ff2

testing: ensure we don't report see with link even with `checkSee…

902fac0

…sForNamepaths` option on

brettz9 approved these changes Sep 1, 2019

View reviewed changes

This was referenced Sep 1, 2019

Support parsing namepaths without allowing types jsdoctypeparser/jsdoctypeparser#86

Closed

Have namepath checks in valid-types only allow strict namepaths #374

Open

brettz9 merged commit 12ae7c6 into gajus:master Sep 1, 2019

gajus added the released label Sep 1, 2019

teppeis mentioned this pull request Sep 19, 2019

fix(deps): update eslint and prettier (minor) teppeis/eslint-config-teppeis#331

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

valid-types: Add more type checks #308

valid-types: Add more type checks #308

l1bbcsg commented Jul 4, 2019 •

edited by brettz9

Loading

brettz9 left a comment

l1bbcsg commented Aug 8, 2019

brettz9 left a comment

gajus commented Sep 1, 2019

valid-types: Add more type checks #308

valid-types: Add more type checks #308

Conversation

l1bbcsg commented Jul 4, 2019 • edited by brettz9 Loading

brettz9 left a comment

Choose a reason for hiding this comment

l1bbcsg commented Aug 8, 2019

brettz9 left a comment

Choose a reason for hiding this comment

gajus commented Sep 1, 2019

l1bbcsg commented Jul 4, 2019 •

edited by brettz9

Loading