From f73cd675ebf4d55388e73ebbc4d3483ad1d23ab6 Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Sat, 25 Feb 2023 03:59:16 +1300 Subject: [PATCH 01/13] feat: set up initial behavior --- .gitignore | 1 + package.json | 4 ++ pnpm-lock.yaml | 41 ++++++++++++++++++++ src/index.ts | 101 +++++++++++++++++++++++++++++++++++++++++++++++-- 4 files changed, 144 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 501cab1..63cb2a5 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,6 @@ node_modules/ /coverage/ /dist/ +/docs/ *.log diff --git a/package.json b/package.json index ee7b899..18ac5de 100644 --- a/package.json +++ b/package.json @@ -98,7 +98,11 @@ "rollup-plugin-dts": "5.2.0", "semantic-release": "20.1.0", "ts-node": "10.9.1", + "typedoc": "^0.23.25", "typescript": "4.9.5" }, + "peerDependencies": { + "typedoc": "^0.23.25" + }, "packageManager": "pnpm@7.27.0" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 3b42d7a..d997a07 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -48,6 +48,7 @@ specifiers: rollup-plugin-dts: 5.2.0 semantic-release: 20.1.0 ts-node: 10.9.1 + typedoc: ^0.23.25 typescript: 4.9.5 devDependencies: @@ -98,6 +99,7 @@ devDependencies: rollup-plugin-dts: 5.2.0_vi3xdhr63abcxdtwtptol35g5u semantic-release: 20.1.0 ts-node: 10.9.1_5lyanyhwyggrikgtn7dsw3wuei + typedoc: 0.23.25_typescript@4.9.5 typescript: 4.9.5 packages: @@ -1585,6 +1587,10 @@ packages: engines: {node: '>=12'} dev: true + /ansi-sequence-parser/1.1.0: + resolution: {integrity: sha512-lEm8mt52to2fT8GhciPCGeCXACSz2UwIN4X2e2LJSnZ5uAbn2/dsYdOmUXq0AtWS5cpAupysIneExOgH0Vd2TQ==} + dev: true + /ansi-styles/3.2.1: resolution: {integrity: sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==} engines: {node: '>=4'} @@ -4787,6 +4793,10 @@ packages: engines: {node: '>=12'} dev: true + /lunr/2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + dev: true + /magic-string/0.16.0: resolution: {integrity: sha512-c4BEos3y6G2qO0B9X7K0FVLOPT9uGrjYwYRLFmDqyl5YMboUviyecnXWp94fJTSMwPw2/sf+CEYt5AGpmklkkQ==} dependencies: @@ -6174,6 +6184,15 @@ packages: resolution: {integrity: sha512-lT297f1WLAdq0A4O+AknIFRP6kkiI3s8C913eJ0XqBxJbZPGWUNkRQk2u8zk4bEAjUJ5i+fSLwB6z1HzeT+DEg==} dev: true + /shiki/0.14.1: + resolution: {integrity: sha512-+Jz4nBkCBe0mEDqo1eKRcCdjRtrCjozmcbTUjbPTX7OOJfEbTZzlUWlZtGe3Gb5oV1/jnojhG//YZc3rs9zSEw==} + dependencies: + ansi-sequence-parser: 1.1.0 + jsonc-parser: 3.2.0 + vscode-oniguruma: 1.7.0 + vscode-textmate: 8.0.0 + dev: true + /side-channel/1.0.4: resolution: {integrity: sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==} dependencies: @@ -6745,6 +6764,20 @@ packages: is-typedarray: 1.0.0 dev: true + /typedoc/0.23.25_typescript@4.9.5: + resolution: {integrity: sha512-O1he153qVyoCgJYSvIyY3bPP1wAJTegZfa6tL3APinSZhJOf8CSd8F/21M6ex8pUY/fuY6n0jAsT4fIuMGA6sA==} + engines: {node: '>= 14.14'} + hasBin: true + peerDependencies: + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x + dependencies: + lunr: 2.3.9 + marked: 4.2.12 + minimatch: 6.2.0 + shiki: 0.14.1 + typescript: 4.9.5 + dev: true + /typescript/4.9.5: resolution: {integrity: sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g==} engines: {node: '>=4.2.0'} @@ -6842,6 +6875,14 @@ packages: resolution: {integrity: sha512-1bonkGqQs5/fxGT5UchTgjGVnfysL0O8v1AYMBjqTbWQTFn721zaPGDYFkOKtfDgFiSgXM3KwaG3FMGfW4Ed9Q==} dev: true + /vscode-oniguruma/1.7.0: + resolution: {integrity: sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==} + dev: true + + /vscode-textmate/8.0.0: + resolution: {integrity: sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==} + dev: true + /vscode-uri/3.0.7: resolution: {integrity: sha512-eOpPHogvorZRobNqJGhapa0JdwaxpjVvyBp0QIUMRMSf8ZAlqOdEquKuRmw9Qwu0qXtJIWqFtMkmvJjUZmMjVA==} dev: true diff --git a/src/index.ts b/src/index.ts index d4a9007..40c3afc 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,4 +1,99 @@ -/* eslint-disable eslint-comments/disable-enable-pair */ -/* eslint-disable unicorn/no-empty-file */ +import type { Application, ProjectReflection, Reflection } from "typedoc"; +import { ParameterType, Validator, ReflectionKind } from "typedoc"; -// Write me +/** + * Extend typedoc's options with the plugin's option using declaration merging. + */ +declare module "typedoc" { + // eslint-disable-next-line @typescript-eslint/consistent-type-definitions, jsdoc/require-jsdoc + export interface TypeDocOptionMap { + requireTags: { + byKind: ByKindEntry[]; + }; + } +} + +export type ByKindEntry = { + kind: keyof typeof ReflectionKind; + tags: string[]; +}; + +export function load(app: Readonly) { + // @ts-expect-error -- FIXME: ??? + app.options.addDeclaration({ + name: "requireTags", + help: "The configuration object of the require-tags plugin.", + type: ParameterType.Object, + }); + + app.validator.on( + Validator.EVENT_RUN, + (project: Readonly) => { + const requireTagsOptions = app.options.getValue( + "requireTags" + ) as unknown as { + byKind: ByKindEntry[]; + }; + + let m_kinds = requireTagsOptions.byKind.reduce( + (prev, cur) => prev | ReflectionKind[cur.kind], + 0 + ); + + const reflectionKindReplacements: Array< + [oldKind: number, newKind: number] + > = [ + [ReflectionKind.FunctionOrMethod, ReflectionKind.CallSignature], + [ReflectionKind.Constructor, ReflectionKind.ConstructorSignature], + [ + ReflectionKind.Accessor, + ReflectionKind.GetSignature | ReflectionKind.SetSignature, + ], + ]; + + for (const [oldKind, newKind] of reflectionKindReplacements) { + m_kinds = (m_kinds | newKind) & ~oldKind; + } + + const requireTagsByKind = new Map( + requireTagsOptions.byKind.map( + ({ kind: kindString, tags }): [number, string[]] => { + const kind = ReflectionKind[kindString]; + const realKind = + reflectionKindReplacements.find( + ([oldKind]) => (oldKind & kind) !== 0 + )?.[1] ?? kind; + return [realKind, tags]; + } + ) + ); + + const reflections = project.getReflectionsByKind(m_kinds); + const seen = new Set(); + + for (const reflection of reflections) { + if (seen.has(reflection)) { + continue; + } + + seen.add(reflection); + + if (!reflection.hasComment()) { + app.logger.warn( + `${reflection.getFriendlyFullName()} does not have any documentation.` + ); + continue; + } + + for (const tagName of requireTagsByKind.get(reflection.kind)!) { + const tag = `@${tagName}` as const; + if (reflection.comment!.getTags(tag).length === 0) { + app.logger.warn( + `${reflection.getFriendlyFullName()} does not have any ${tag} tags.` + ); + } + } + } + } + ); +} From ed36500a37e51b56b2992479762e1c82fbc11daf Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Sat, 25 Feb 2023 16:44:37 +1300 Subject: [PATCH 02/13] fix: update for upstream PR changes --- src/index.ts | 118 +++++++++++++++++++++++++-------------------------- 1 file changed, 59 insertions(+), 59 deletions(-) diff --git a/src/index.ts b/src/index.ts index 40c3afc..a5b8a49 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,5 +1,5 @@ -import type { Application, ProjectReflection, Reflection } from "typedoc"; -import { ParameterType, Validator, ReflectionKind } from "typedoc"; +import type { Reflection } from "typedoc"; +import { Application, ParameterType, ReflectionKind } from "typedoc"; /** * Extend typedoc's options with the plugin's option using declaration merging. @@ -26,74 +26,74 @@ export function load(app: Readonly) { type: ParameterType.Object, }); - app.validator.on( - Validator.EVENT_RUN, - (project: Readonly) => { - const requireTagsOptions = app.options.getValue( - "requireTags" - ) as unknown as { - byKind: ByKindEntry[]; - }; + app.on(Application.EVENT_VALIDATION_RUN, (project) => { + const requireTagsOptions = app.options.getValue( + "requireTags" + ) as unknown as { + byKind: ByKindEntry[]; + }; - let m_kinds = requireTagsOptions.byKind.reduce( - (prev, cur) => prev | ReflectionKind[cur.kind], - 0 - ); + let m_kinds = requireTagsOptions.byKind.reduce( + (prev, cur) => prev | ReflectionKind[cur.kind], + 0 + ); - const reflectionKindReplacements: Array< - [oldKind: number, newKind: number] - > = [ - [ReflectionKind.FunctionOrMethod, ReflectionKind.CallSignature], - [ReflectionKind.Constructor, ReflectionKind.ConstructorSignature], - [ - ReflectionKind.Accessor, - ReflectionKind.GetSignature | ReflectionKind.SetSignature, - ], - ]; + const reflectionKindReplacements: Array< + [oldKind: number, newKind: number] + > = [ + [ReflectionKind.FunctionOrMethod, ReflectionKind.CallSignature], + [ReflectionKind.Constructor, ReflectionKind.ConstructorSignature], + [ + ReflectionKind.Accessor, + ReflectionKind.GetSignature | ReflectionKind.SetSignature, + ], + ]; - for (const [oldKind, newKind] of reflectionKindReplacements) { - m_kinds = (m_kinds | newKind) & ~oldKind; - } + for (const [oldKind, newKind] of reflectionKindReplacements) { + m_kinds = (m_kinds | newKind) & ~oldKind; + } - const requireTagsByKind = new Map( - requireTagsOptions.byKind.map( - ({ kind: kindString, tags }): [number, string[]] => { - const kind = ReflectionKind[kindString]; - const realKind = - reflectionKindReplacements.find( - ([oldKind]) => (oldKind & kind) !== 0 - )?.[1] ?? kind; - return [realKind, tags]; - } - ) - ); + const requireTagsByKind = new Map( + requireTagsOptions.byKind.map( + ({ kind: kindString, tags }): [number, string[]] => { + const kind = ReflectionKind[kindString]; + const realKind = + reflectionKindReplacements.find( + ([oldKind]) => (oldKind & kind) !== 0 + )?.[1] ?? kind; + return [realKind, tags]; + } + ) + ); - const reflections = project.getReflectionsByKind(m_kinds); - const seen = new Set(); + const reflections = project.getReflectionsByKind(m_kinds); + const seen = new Set(); - for (const reflection of reflections) { - if (seen.has(reflection)) { - continue; - } + for (const reflection of reflections) { + if (seen.has(reflection)) { + continue; + } - seen.add(reflection); + seen.add(reflection); - if (!reflection.hasComment()) { + if (!reflection.hasComment()) { + app.logger.warn( + `${reflection.getFriendlyFullName()} does not have any documentation.` + ); + continue; + } + + for (const tagName of requireTagsByKind.get(reflection.kind)!) { + const tag: `@${string}` = tagName.startsWith("@") + ? (tagName as `@${string}`) + : `@${tagName}`; + + if (reflection.comment!.getTags(tag).length === 0) { app.logger.warn( - `${reflection.getFriendlyFullName()} does not have any documentation.` + `${reflection.getFriendlyFullName()} does not have any ${tag} tags.` ); - continue; - } - - for (const tagName of requireTagsByKind.get(reflection.kind)!) { - const tag = `@${tagName}` as const; - if (reflection.comment!.getTags(tag).length === 0) { - app.logger.warn( - `${reflection.getFriendlyFullName()} does not have any ${tag} tags.` - ); - } } } } - ); + }); } From 612f0de6d5047a33ab1bcabe7ac29b47eb66ee38 Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Sat, 25 Feb 2023 16:58:21 +1300 Subject: [PATCH 03/13] refactor: improve setting of options type --- src/index.ts | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/index.ts b/src/index.ts index a5b8a49..9d7a536 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,4 +1,4 @@ -import type { Reflection } from "typedoc"; +import type { Reflection, TypeDocOptionMap } from "typedoc"; import { Application, ParameterType, ReflectionKind } from "typedoc"; /** @@ -29,9 +29,7 @@ export function load(app: Readonly) { app.on(Application.EVENT_VALIDATION_RUN, (project) => { const requireTagsOptions = app.options.getValue( "requireTags" - ) as unknown as { - byKind: ByKindEntry[]; - }; + ) as unknown as TypeDocOptionMap["requireTags"]; let m_kinds = requireTagsOptions.byKind.reduce( (prev, cur) => prev | ReflectionKind[cur.kind], From 13942d1c283e956c164e33f63abbe45abf55eaba Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Sun, 26 Feb 2023 19:07:12 +1300 Subject: [PATCH 04/13] fix: update for upstream PR changes --- src/index.ts | 115 ++++++++++++++++++++++++++------------------------- 1 file changed, 59 insertions(+), 56 deletions(-) diff --git a/src/index.ts b/src/index.ts index 9d7a536..e04472c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,4 +1,4 @@ -import type { Reflection, TypeDocOptionMap } from "typedoc"; +import type { ProjectReflection, Reflection, TypeDocOptionMap } from "typedoc"; import { Application, ParameterType, ReflectionKind } from "typedoc"; /** @@ -26,72 +26,75 @@ export function load(app: Readonly) { type: ParameterType.Object, }); - app.on(Application.EVENT_VALIDATION_RUN, (project) => { - const requireTagsOptions = app.options.getValue( - "requireTags" - ) as unknown as TypeDocOptionMap["requireTags"]; + app.on( + Application.EVENT_VALIDATE_PROJECT, + (project: Readonly) => { + const requireTagsOptions = app.options.getValue( + "requireTags" + ) as unknown as TypeDocOptionMap["requireTags"]; - let m_kinds = requireTagsOptions.byKind.reduce( - (prev, cur) => prev | ReflectionKind[cur.kind], - 0 - ); + let m_kinds = requireTagsOptions.byKind.reduce( + (prev, cur) => prev | ReflectionKind[cur.kind], + 0 + ); - const reflectionKindReplacements: Array< - [oldKind: number, newKind: number] - > = [ - [ReflectionKind.FunctionOrMethod, ReflectionKind.CallSignature], - [ReflectionKind.Constructor, ReflectionKind.ConstructorSignature], - [ - ReflectionKind.Accessor, - ReflectionKind.GetSignature | ReflectionKind.SetSignature, - ], - ]; + const reflectionKindReplacements: Array< + [oldKind: number, newKind: number] + > = [ + [ReflectionKind.FunctionOrMethod, ReflectionKind.CallSignature], + [ReflectionKind.Constructor, ReflectionKind.ConstructorSignature], + [ + ReflectionKind.Accessor, + ReflectionKind.GetSignature | ReflectionKind.SetSignature, + ], + ]; - for (const [oldKind, newKind] of reflectionKindReplacements) { - m_kinds = (m_kinds | newKind) & ~oldKind; - } - - const requireTagsByKind = new Map( - requireTagsOptions.byKind.map( - ({ kind: kindString, tags }): [number, string[]] => { - const kind = ReflectionKind[kindString]; - const realKind = - reflectionKindReplacements.find( - ([oldKind]) => (oldKind & kind) !== 0 - )?.[1] ?? kind; - return [realKind, tags]; - } - ) - ); - - const reflections = project.getReflectionsByKind(m_kinds); - const seen = new Set(); - - for (const reflection of reflections) { - if (seen.has(reflection)) { - continue; + for (const [oldKind, newKind] of reflectionKindReplacements) { + m_kinds = (m_kinds | newKind) & ~oldKind; } - seen.add(reflection); + const requireTagsByKind = new Map( + requireTagsOptions.byKind.map( + ({ kind: kindString, tags }): [number, string[]] => { + const kind = ReflectionKind[kindString]; + const realKind = + reflectionKindReplacements.find( + ([oldKind]) => (oldKind & kind) !== 0 + )?.[1] ?? kind; + return [realKind, tags]; + } + ) + ); - if (!reflection.hasComment()) { - app.logger.warn( - `${reflection.getFriendlyFullName()} does not have any documentation.` - ); - continue; - } + const reflections = project.getReflectionsByKind(m_kinds); + const seen = new Set(); - for (const tagName of requireTagsByKind.get(reflection.kind)!) { - const tag: `@${string}` = tagName.startsWith("@") - ? (tagName as `@${string}`) - : `@${tagName}`; + for (const reflection of reflections) { + if (seen.has(reflection)) { + continue; + } + + seen.add(reflection); - if (reflection.comment!.getTags(tag).length === 0) { + if (!reflection.hasComment()) { app.logger.warn( - `${reflection.getFriendlyFullName()} does not have any ${tag} tags.` + `${reflection.getFriendlyFullName()} does not have any documentation.` ); + continue; + } + + for (const tagName of requireTagsByKind.get(reflection.kind)!) { + const tag: `@${string}` = tagName.startsWith("@") + ? (tagName as `@${string}`) + : `@${tagName}`; + + if (reflection.comment!.getTags(tag).length === 0) { + app.logger.warn( + `${reflection.getFriendlyFullName()} does not have any ${tag} tags.` + ); + } } } } - }); + ); } From 5a92d07b4ad4889cba88e64e89b843c1a4b078e5 Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 02:25:10 +1300 Subject: [PATCH 05/13] build: require typedoc >=0.23.26 --- package.json | 4 ++-- pnpm-lock.yaml | 17 ++++++++++++----- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/package.json b/package.json index 18ac5de..0db1664 100644 --- a/package.json +++ b/package.json @@ -98,11 +98,11 @@ "rollup-plugin-dts": "5.2.0", "semantic-release": "20.1.0", "ts-node": "10.9.1", - "typedoc": "^0.23.25", + "typedoc": "0.23.26", "typescript": "4.9.5" }, "peerDependencies": { - "typedoc": "^0.23.25" + "typedoc": "^0.23.26" }, "packageManager": "pnpm@7.27.0" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d997a07..a5542d7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -48,7 +48,7 @@ specifiers: rollup-plugin-dts: 5.2.0 semantic-release: 20.1.0 ts-node: 10.9.1 - typedoc: ^0.23.25 + typedoc: 0.23.26 typescript: 4.9.5 devDependencies: @@ -99,7 +99,7 @@ devDependencies: rollup-plugin-dts: 5.2.0_vi3xdhr63abcxdtwtptol35g5u semantic-release: 20.1.0 ts-node: 10.9.1_5lyanyhwyggrikgtn7dsw3wuei - typedoc: 0.23.25_typescript@4.9.5 + typedoc: 0.23.26_typescript@4.9.5 typescript: 4.9.5 packages: @@ -5040,6 +5040,13 @@ packages: brace-expansion: 2.0.1 dev: true + /minimatch/7.4.2: + resolution: {integrity: sha512-xy4q7wou3vUoC9k1xGTXc+awNdGaGVHtFUaey8tiX4H1QRc04DZ/rmDFwNm2EBsuYEhAZ6SgMmYf3InGY6OauA==} + engines: {node: '>=10'} + dependencies: + brace-expansion: 2.0.1 + dev: true + /minimist-options/4.1.0: resolution: {integrity: sha512-Q4r8ghd80yhO/0j1O3B2BjweX3fiHg9cdOwjJd2J76Q135c+NDxGCqdYKQ1SKBuFfgWbAUzBfvYjPUEeNgqN1A==} engines: {node: '>= 6'} @@ -6764,8 +6771,8 @@ packages: is-typedarray: 1.0.0 dev: true - /typedoc/0.23.25_typescript@4.9.5: - resolution: {integrity: sha512-O1he153qVyoCgJYSvIyY3bPP1wAJTegZfa6tL3APinSZhJOf8CSd8F/21M6ex8pUY/fuY6n0jAsT4fIuMGA6sA==} + /typedoc/0.23.26_typescript@4.9.5: + resolution: {integrity: sha512-5m4KwR5tOLnk0OtMaRn9IdbeRM32uPemN9kur7YK9wFqx8U0CYrvO9aVq6ysdZSV1c824BTm+BuQl2Ze/k1HtA==} engines: {node: '>= 14.14'} hasBin: true peerDependencies: @@ -6773,7 +6780,7 @@ packages: dependencies: lunr: 2.3.9 marked: 4.2.12 - minimatch: 6.2.0 + minimatch: 7.4.2 shiki: 0.14.1 typescript: 4.9.5 dev: true From 046f1e1bd83156ec68521edc6a21bb054a187edd Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 02:27:45 +1300 Subject: [PATCH 06/13] chore: remove now fixed ts-expect-error --- src/index.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/index.ts b/src/index.ts index e04472c..2bee1c7 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,7 +19,6 @@ export type ByKindEntry = { }; export function load(app: Readonly) { - // @ts-expect-error -- FIXME: ??? app.options.addDeclaration({ name: "requireTags", help: "The configuration object of the require-tags plugin.", From 8126fd38f669493c826da25b77f412d401ca3390 Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 02:29:40 +1300 Subject: [PATCH 07/13] ci: fix name of script --- .github/workflows/build-node.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-node.yml b/.github/workflows/build-node.yml index f7d44ee..d699ad3 100644 --- a/.github/workflows/build-node.yml +++ b/.github/workflows/build-node.yml @@ -11,4 +11,4 @@ jobs: steps: - uses: actions/checkout@v3 - uses: ./.github/actions/prepare - - run: pnpm run build-node + - run: pnpm run build:node From 17669ac0e60e9de8fb692520b451eb6a3fd0ab9d Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 02:33:58 +1300 Subject: [PATCH 08/13] build: add typedoc-plugin keyword --- package.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 0db1664..b043b7a 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,9 @@ "version": "0.0.0-development", "private": true, "description": "", - "keywords": [], + "keywords": [ + "typedoc-plugin" + ], "homepage": "https://github.com/RebeccaStevens/typedoc-plugin-require-tags#readme", "bugs": { "url": "https://github.com/RebeccaStevens/typedoc-plugin-require-tags/issues" From 5884a3856000eb7a563b8636cdfd6e3a1a7ee1d8 Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 02:41:10 +1300 Subject: [PATCH 09/13] ci: enable cd --- .github/workflows/release.yml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index af4a8c4..edded09 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -49,8 +49,7 @@ jobs: run: pnpm run build - name: Release - run: echo "Do Release Here" - # run: pnpm run semantic-release - # env: - # GITHUB_TOKEN: ${{ github.token }} - # NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + run: pnpm run semantic-release + env: + GITHUB_TOKEN: ${{ github.token }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} From 09f3dd3cfb3027c536032ca4218b20920a8fa8b7 Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 02:48:30 +1300 Subject: [PATCH 10/13] refactor: dont't extend TypeDocOptionMap --- src/index.ts | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/src/index.ts b/src/index.ts index 2bee1c7..fe3b205 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,17 +1,9 @@ -import type { ProjectReflection, Reflection, TypeDocOptionMap } from "typedoc"; +import type { ProjectReflection, Reflection } from "typedoc"; import { Application, ParameterType, ReflectionKind } from "typedoc"; -/** - * Extend typedoc's options with the plugin's option using declaration merging. - */ -declare module "typedoc" { - // eslint-disable-next-line @typescript-eslint/consistent-type-definitions, jsdoc/require-jsdoc - export interface TypeDocOptionMap { - requireTags: { - byKind: ByKindEntry[]; - }; - } -} +export type RequireTagsOptions = { + byKind: ByKindEntry[]; +}; export type ByKindEntry = { kind: keyof typeof ReflectionKind; @@ -30,7 +22,7 @@ export function load(app: Readonly) { (project: Readonly) => { const requireTagsOptions = app.options.getValue( "requireTags" - ) as unknown as TypeDocOptionMap["requireTags"]; + ) as RequireTagsOptions; let m_kinds = requireTagsOptions.byKind.reduce( (prev, cur) => prev | ReflectionKind[cur.kind], From 3f54df5b63496d2c091035581fb71107f4ce10f4 Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 03:55:17 +1300 Subject: [PATCH 11/13] feat: add ability to require summaries --- src/index.ts | 88 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 58 insertions(+), 30 deletions(-) diff --git a/src/index.ts b/src/index.ts index fe3b205..fee229c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,18 +1,19 @@ import type { ProjectReflection, Reflection } from "typedoc"; import { Application, ParameterType, ReflectionKind } from "typedoc"; -export type RequireTagsOptions = { +export type CustomValidationOptions = { byKind: ByKindEntry[]; }; export type ByKindEntry = { - kind: keyof typeof ReflectionKind; - tags: string[]; + kinds: keyof typeof ReflectionKind | Array; + tags?: string | string[]; + summary?: boolean; }; export function load(app: Readonly) { app.options.addDeclaration({ - name: "requireTags", + name: "customValidation", help: "The configuration object of the require-tags plugin.", type: ParameterType.Object, }); @@ -20,14 +21,14 @@ export function load(app: Readonly) { app.on( Application.EVENT_VALIDATE_PROJECT, (project: Readonly) => { - const requireTagsOptions = app.options.getValue( - "requireTags" - ) as RequireTagsOptions; + const customValidationOptions = app.options.getValue( + "customValidation" + ) as CustomValidationOptions; - let m_kinds = requireTagsOptions.byKind.reduce( - (prev, cur) => prev | ReflectionKind[cur.kind], - 0 - ); + let m_kinds = customValidationOptions.byKind + .flatMap((by) => by.kinds) + .map((kind) => ReflectionKind[kind]) + .reduce((p, c) => p | c); const reflectionKindReplacements: Array< [oldKind: number, newKind: number] @@ -44,16 +45,32 @@ export function load(app: Readonly) { m_kinds = (m_kinds | newKind) & ~oldKind; } - const requireTagsByKind = new Map( - requireTagsOptions.byKind.map( - ({ kind: kindString, tags }): [number, string[]] => { - const kind = ReflectionKind[kindString]; - const realKind = - reflectionKindReplacements.find( - ([oldKind]) => (oldKind & kind) !== 0 - )?.[1] ?? kind; - return [realKind, tags]; - } + type Requirements = { tags: string[]; summary: boolean }; + + const requirementsByKind = new Map( + customValidationOptions.byKind.flatMap(({ kinds, tags, summary }) => + (Array.isArray(kinds) ? kinds : [kinds]).map( + (kindString): [number, Requirements] => { + const kind = ReflectionKind[kindString]; + const realKind = + reflectionKindReplacements.find( + ([oldKind]) => (oldKind & kind) !== 0 + )?.[1] ?? kind; + + return [ + realKind, + { + tags: + tags === undefined + ? [] + : Array.isArray(tags) + ? tags + : [tags], + summary: summary ?? false, + }, + ]; + } + ) ) ); @@ -64,26 +81,37 @@ export function load(app: Readonly) { if (seen.has(reflection)) { continue; } - seen.add(reflection); - if (!reflection.hasComment()) { + if (!reflection.hasComment() || reflection.comment!.isEmpty()) { app.logger.warn( `${reflection.getFriendlyFullName()} does not have any documentation.` ); continue; } - for (const tagName of requireTagsByKind.get(reflection.kind)!) { - const tag: `@${string}` = tagName.startsWith("@") - ? (tagName as `@${string}`) - : `@${tagName}`; - - if (reflection.comment!.getTags(tag).length === 0) { + const requirements = requirementsByKind.get(reflection.kind); + if (requirements !== undefined) { + if ( + requirements.summary && + reflection.comment!.summary.length === 0 + ) { app.logger.warn( - `${reflection.getFriendlyFullName()} does not have any ${tag} tags.` + `${reflection.getFriendlyFullName()} does not have a summary.` ); } + + for (const tagName of requirements.tags) { + const tag: `@${string}` = tagName.startsWith("@") + ? (tagName as `@${string}`) + : `@${tagName}`; + + if (reflection.comment!.getTags(tag).length === 0) { + app.logger.warn( + `${reflection.getFriendlyFullName()} does not have any ${tag} tags.` + ); + } + } } } } From f2351cc08ce672b79a0bf0ccac0e2a0037b1bbec Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 04:09:06 +1300 Subject: [PATCH 12/13] docs: add usage docs --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/README.md b/README.md index 58ca137..987b49d 100644 --- a/README.md +++ b/README.md @@ -29,3 +29,49 @@ pnpm add -D typedoc-plugin-require-tags # Install with yarn yarn add -D typedoc-plugin-require-tags ``` + +## Usage + +All options are configured in the `customValidation` option. + +### `byKind` + +This option is for specifying requirements for each kind of node. + +Example: Require all functions to have a summary and have an `@example` tag. + +```json +{ + "plugin": ["typedoc-plugin-require-tags"], + "customValidation": { + "byKind": [ + { + "kinds": "Function", + "summary": true, + "tags": ["example"] + } + ] + } +} +``` + +### My Tags Don't Exists? + +Due to the way typedoc works, some tags may be move to other nodes than the one they were defined on. + +For example, `@param` tags are removed from the `Function` node they are defined on and its content is put onto the corresponding `Parameter` node. +You can require parameters to be documented with: + +```json +{ + "plugin": ["typedoc-plugin-require-tags"], + "customValidation": { + "byKind": [ + { + "kinds": "Parameter", + "summary": true + } + ] + } +} +``` From 89b949d7343a373a85d430bb1d742110f332517b Mon Sep 17 00:00:00 2001 From: Rebecca Stevens Date: Fri, 3 Mar 2023 04:10:35 +1300 Subject: [PATCH 13/13] chore: rename plugin --- .github/FUNDING.yml | 4 ++-- README.md | 22 +++++++++++----------- package.json | 8 ++++---- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 607c82f..60787aa 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,3 +1,3 @@ -issuehunt: RebeccaStevens/typedoc-plugin-require-tags +issuehunt: RebeccaStevens/typedoc-plugin-custom-validation ko_fi: rebeccastevens -custom: https://github.com/RebeccaStevens/typedoc-plugin-require-tags/blob/main/DONATIONS.md +custom: https://github.com/RebeccaStevens/typedoc-plugin-custom-validation/blob/main/DONATIONS.md diff --git a/README.md b/README.md index 987b49d..2d83d24 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@
-# typedoc-plugin-require-tags +# typedoc-plugin-custom-validation -[![npm version](https://img.shields.io/npm/v/typedoc-plugin-require-tags.svg)](https://www.npmjs.com/package/typedoc-plugin-require-tags) -[![CI](https://github.com/RebeccaStevens/typedoc-plugin-require-tags/actions/workflows/release.yml/badge.svg)](https://github.com/RebeccaStevens/typedoc-plugin-require-tags/actions/workflows/release.yml) -[![Coverage Status](https://codecov.io/gh/RebeccaStevens/typedoc-plugin-require-tags/branch/main/graph/badge.svg?token=MVpR1oAbIT)](https://codecov.io/gh/RebeccaStevens/typedoc-plugin-require-tags)\ +[![npm version](https://img.shields.io/npm/v/typedoc-plugin-custom-validation.svg)](https://www.npmjs.com/package/typedoc-plugin-custom-validation) +[![CI](https://github.com/RebeccaStevens/typedoc-plugin-custom-validation/actions/workflows/release.yml/badge.svg)](https://github.com/RebeccaStevens/typedoc-plugin-custom-validation/actions/workflows/release.yml) +[![Coverage Status](https://codecov.io/gh/RebeccaStevens/typedoc-plugin-custom-validation/branch/main/graph/badge.svg?token=MVpR1oAbIT)](https://codecov.io/gh/RebeccaStevens/typedoc-plugin-custom-validation)\ [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier) -[![GitHub Discussions](https://img.shields.io/github/discussions/RebeccaStevens/typedoc-plugin-require-tags?style=flat-square)](https://github.com/RebeccaStevens/typedoc-plugin-require-tags/discussions) -[![BSD 3 Clause license](https://img.shields.io/github/license/RebeccaStevens/typedoc-plugin-require-tags.svg?style=flat-square)](https://opensource.org/licenses/BSD-3-Clause) +[![GitHub Discussions](https://img.shields.io/github/discussions/RebeccaStevens/typedoc-plugin-custom-validation?style=flat-square)](https://github.com/RebeccaStevens/typedoc-plugin-custom-validation/discussions) +[![BSD 3 Clause license](https://img.shields.io/github/license/RebeccaStevens/typedoc-plugin-custom-validation.svg?style=flat-square)](https://opensource.org/licenses/BSD-3-Clause) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)](https://commitizen.github.io/cz-cli/) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/semantic-release/semantic-release) @@ -21,13 +21,13 @@ ```sh # Install with npm -npm install -D typedoc-plugin-require-tags +npm install -D typedoc-plugin-custom-validation # Install with pnpm -pnpm add -D typedoc-plugin-require-tags +pnpm add -D typedoc-plugin-custom-validation # Install with yarn -yarn add -D typedoc-plugin-require-tags +yarn add -D typedoc-plugin-custom-validation ``` ## Usage @@ -42,7 +42,7 @@ Example: Require all functions to have a summary and have an `@example` tag. ```json { - "plugin": ["typedoc-plugin-require-tags"], + "plugin": ["typedoc-plugin-custom-validation"], "customValidation": { "byKind": [ { @@ -64,7 +64,7 @@ You can require parameters to be documented with: ```json { - "plugin": ["typedoc-plugin-require-tags"], + "plugin": ["typedoc-plugin-custom-validation"], "customValidation": { "byKind": [ { diff --git a/package.json b/package.json index b043b7a..930512b 100644 --- a/package.json +++ b/package.json @@ -1,18 +1,18 @@ { - "name": "typedoc-plugin-require-tags", + "name": "typedoc-plugin-custom-validation", "version": "0.0.0-development", "private": true, "description": "", "keywords": [ "typedoc-plugin" ], - "homepage": "https://github.com/RebeccaStevens/typedoc-plugin-require-tags#readme", + "homepage": "https://github.com/RebeccaStevens/typedoc-plugin-custom-validation#readme", "bugs": { - "url": "https://github.com/RebeccaStevens/typedoc-plugin-require-tags/issues" + "url": "https://github.com/RebeccaStevens/typedoc-plugin-custom-validation/issues" }, "repository": { "type": "git", - "url": "git+https://github.com/RebeccaStevens/typedoc-plugin-require-tags" + "url": "git+https://github.com/RebeccaStevens/typedoc-plugin-custom-validation" }, "license": "BSD-3-Clause", "author": {