The best way to control Claude Code, Codex and more from any computer or phone

main
ts 1,827 lines 38 KB
Raw
1 import * as Configuration from "@effect/docgen/Configuration"
2 import * as Domain from "@effect/docgen/Domain"
3 import * as Parser from "@effect/docgen/Parser"
4 import * as Printer from "@effect/docgen/Printer"
5 import { assert, describe, it } from "@effect/vitest"
6 import { Effect, Exit, Predicate } from "effect"
7 import * as Path from "effect/Path"
8 import * as ast from "ts-morph"
9
10 let testCounter = 0
11
12 const project = new ast.Project({
13 compilerOptions: { strict: true },
14 useInMemoryFileSystem: true
15 })
16
17 const defaultConfig: Configuration.ConfigurationShape = {
18 projectName: "docgen",
19 projectHomepage: "https://github.com/effect-ts/docgen",
20 srcLink: "https://github.com/effect-ts/docgen/blob/main/src/",
21 srcDir: "src",
22 outDir: "docs",
23 theme: "mikearnaldi/just-the-docs",
24 enableSearch: true,
25 enforceDescriptions: false,
26 enforceExamples: false,
27 enforceVersion: true,
28 runExamples: false,
29 tscExecutable: "tsc",
30 exclude: [],
31 parseCompilerOptions: {},
32 examplesCompilerOptions: {}
33 }
34
35 const makeSourcefile = (source: string | ast.SourceFile) => {
36 if (Predicate.isString(source)) {
37 const filename = `test.ts`
38 const existing = project.getSourceFile(filename)
39 if (existing) {
40 project.removeSourceFile(existing)
41 }
42 return project.createSourceFile(filename, source)
43 }
44 return source
45 }
46
47 const makeSource = (source: string | ast.SourceFile) => {
48 const sourceFile = makeSourcefile(source)
49 const filename = sourceFile.getBaseName()
50 return Parser.Source.of({
51 path: [filename],
52 sourceFile
53 })
54 }
55
56 const print = Effect.fnUntraced(function*(printables: ReadonlyArray<Printer.Printable>) {
57 const strings = yield* Effect.forEach(printables, (printable) => Printer.print(printable))
58 return strings.join("\n")
59 })
60
61 const isModule = (printableOr: ReadonlyArray<Printer.Printable> | Domain.Module): printableOr is Domain.Module => {
62 return !Array.isArray(printableOr)
63 }
64
65 const expectMarkdown = Effect.fnUntraced(function*<E>(
66 eff: Effect.Effect<
67 ReadonlyArray<Printer.Printable> | Domain.Module,
68 E,
69 Parser.Source | Configuration.Configuration | Path.Path
70 >,
71 sourceText: string,
72 expected: string,
73 config?: Partial<Configuration.ConfigurationShape>
74 ) {
75 const exit = yield* Effect.exit(eff.pipe(
76 Effect.flatMap((printableOr) => {
77 if (isModule(printableOr)) {
78 return Printer.printModule(printableOr)
79 }
80 return print(printableOr)
81 }),
82 Effect.provideService(Parser.Source, makeSource(sourceText)),
83 Effect.provideService(Configuration.Configuration, { ...defaultConfig, ...config }),
84 Effect.provide(Path.layer)
85 ))
86 assert.ok(exit._tag === "Success")
87 if (exit.value !== expected) {
88 console.log(exit.value)
89 }
90 assert.strictEqual(exit.value, expected)
91 })
92
93 describe("Parser", () => {
94 describe("parseModule", () => {
95 it.effect("should not require an example for modules when `enforceExamples` is set to true", () =>
96 Effect.gen(function*() {
97 yield* expectMarkdown(
98 Parser.parseModule,
99 `/**
100 * This is the assert module.
101 *
102 * @since 1.0.0
103 */
104 import * as assert from 'assert'
105
106 /**
107 * This is the foo export.
108 *
109 * @example
110 * import { foo } from 'test'
111 *
112 * console.log(foo)
113 *
114 * @category category
115 * @since 1.0.0
116 */
117 export const foo = 'foo'`,
118 `## test.ts overview
119
120 This is the assert module.
121
122 Since v1.0.0
123
124 <!-- toc -->
125
126 # category
127
128 ## foo
129
130 This is the foo export.
131
132 **Example**
133
134 \`\`\`ts
135 import { foo } from 'test'
136
137 console.log(foo)
138 \`\`\`
139
140 **Signature**
141
142 \`\`\`ts
143 declare const foo: "foo"
144 \`\`\`
145
146 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L19)
147
148 Since v1.0.0`
149 )
150 }))
151
152 it.effect("should ignore non-JSDoc comments above JSDoc comments", () =>
153 Effect.gen(function*() {
154 yield* expectMarkdown(
155 Parser.parseModule,
156 `/**
157 * This is the assert module.
158 *
159 * @since 1.0.0
160 */
161 import * as assert from 'assert'
162
163 // This comment should be ignored
164
165 /**
166 * This is the foo export.
167 *
168 * @example
169 * import { foo } from 'test'
170 *
171 * console.log(foo)
172 *
173 * @category category
174 * @since 1.0.0
175 */
176 export const foo = 'foo'`,
177 `## test.ts overview
178
179 This is the assert module.
180
181 Since v1.0.0
182
183 <!-- toc -->
184
185 # category
186
187 ## foo
188
189 This is the foo export.
190
191 **Example**
192
193 \`\`\`ts
194 import { foo } from 'test'
195
196 console.log(foo)
197 \`\`\`
198
199 **Signature**
200
201 \`\`\`ts
202 declare const foo: "foo"
203 \`\`\`
204
205 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L21)
206
207 Since v1.0.0`
208 )
209 }))
210 })
211
212 describe("parseFunctions", () => {
213 it.effect("omits internal properties from signatures", () =>
214 Effect.gen(function*() {
215 yield* expectMarkdown(
216 Parser.parseFunctions,
217 `/**
218 * @since 1.0.0
219 */
220 export const myfunc: (options: {
221 readonly visible?: string
222 /** @internal */
223 readonly internal?: boolean
224 }) => void = () => {}`,
225 `## myfunc
226
227 **Signature**
228
229 \`\`\`ts
230 declare const myfunc: (options: { readonly visible?: string; }) => void
231 \`\`\`
232
233 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L4)
234
235 Since v1.0.0`
236 )
237 }))
238
239 it.effect(`should remove all metadata from typedcript code blocks when the theme is ${Configuration.DEFAULT_THEME}`, () =>
240 Effect.gen(function*() {
241 yield* expectMarkdown(
242 Parser.parseFunctions,
243 `/**
244 * \`\`\`ts skip-type-checking a=1 showLineNumbers=true
245 * const a: string = 1
246 * \`\`\`
247 *
248 * @since 1.0.0
249 */
250 export function myfunc<A>() {}`,
251 `## myfunc
252
253 \`\`\`ts
254 const a: string = 1
255 \`\`\`
256
257 **Signature**
258
259 \`\`\`ts
260 declare const myfunc: <A>() => void
261 \`\`\`
262
263 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L8)
264
265 Since v1.0.0`
266 )
267 }))
268 it.effect("generics", () =>
269 Effect.gen(function*() {
270 yield* expectMarkdown(
271 Parser.parseFunctions,
272 `/**
273 * This is a description containing two links to {@link foo} and {@link bar}.
274 *
275 * @since 1.2.0
276 */
277 export function myfunc<A>() {}`,
278 `## myfunc
279
280 This is a description containing two links to \`foo\` and \`bar\`.
281
282 **Signature**
283
284 \`\`\`ts
285 declare const myfunc: <A>() => void
286 \`\`\`
287
288 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L6)
289
290 Since v1.2.0`
291 )
292 }))
293
294 it.effect("description", () =>
295 Effect.gen(function*() {
296 yield* expectMarkdown(
297 Parser.parseFunctions,
298 `/**
299 * This is a description containing two links to {@link foo} and {@link bar}.
300 *
301 * @since 1.2.0
302 */
303 export function myfunc() {}`,
304 `## myfunc
305
306 This is a description containing two links to \`foo\` and \`bar\`.
307
308 **Signature**
309
310 \`\`\`ts
311 declare const myfunc: () => void
312 \`\`\`
313
314 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L6)
315
316 Since v1.2.0`
317 )
318 }))
319
320 it.effect("throws", () =>
321 Effect.gen(function*() {
322 yield* expectMarkdown(
323 Parser.parseFunctions,
324 `/**
325 * description...
326 * @throws \`Error1\` - Description 1
327 * @throws \`Error2\` - Description 2
328 * @since 1.2.0
329 */
330 export function myfunc() {}`,
331 `## myfunc
332
333 description...
334
335 **Throws**
336
337 \`Error1\` - Description 1
338 \`Error2\` - Description 2
339
340 **Signature**
341
342 \`\`\`ts
343 declare const myfunc: () => void
344 \`\`\`
345
346 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L7)
347
348 Since v1.2.0`
349 )
350 }))
351
352 it.effect("sees", () =>
353 Effect.gen(function*() {
354 yield* expectMarkdown(
355 Parser.parseFunctions,
356 `/**
357 * description...
358 * @see \`foo\` Description 1
359 * @see {@link bar} Description 2
360 * @see {@link baz quux} Description 2
361 * @since 1.2.0
362 */
363 export function myfunc() {}`,
364 `## myfunc
365
366 description...
367
368 **See**
369
370 - \`foo\` Description 1
371 - \`bar\` Description 2
372 - \`quux\` Description 2
373
374 **Signature**
375
376 \`\`\`ts
377 declare const myfunc: () => void
378 \`\`\`
379
380 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L8)
381
382 Since v1.2.0`
383 )
384 }))
385
386 it.effect("example without fence", () =>
387 Effect.gen(function*() {
388 yield* expectMarkdown(
389 Parser.parseFunctions,
390 `/**
391 * description...
392 * @example
393 * const x = 1
394 * @since 1.0.0
395 */
396 export function myfunc() {}`,
397 `## myfunc
398
399 description...
400
401 **Example**
402
403 \`\`\`ts
404 const x = 1
405 \`\`\`
406
407 **Signature**
408
409 \`\`\`ts
410 declare const myfunc: () => void
411 \`\`\`
412
413 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L7)
414
415 Since v1.0.0`
416 )
417 }))
418
419 it.effect("example with backtick fence", () =>
420 Effect.gen(function*() {
421 yield* expectMarkdown(
422 Parser.parseFunctions,
423 `/**
424 * description...
425 * @example
426 * \`\`\`ts
427 * const x = 1
428 * \`\`\`
429 * @since 1.0.0
430 */
431 export function myfunc() {}`,
432 `## myfunc
433
434 description...
435
436 **Example**
437
438 \`\`\`ts
439 const x = 1
440 \`\`\`
441
442 **Signature**
443
444 \`\`\`ts
445 declare const myfunc: () => void
446 \`\`\`
447
448 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L9)
449
450 Since v1.0.0`
451 )
452 }))
453
454 it.effect("2 examples", () =>
455 Effect.gen(function*() {
456 yield* expectMarkdown(
457 Parser.parseFunctions,
458 `/**
459 * description...
460 * @example
461 * \`\`\`ts
462 * const x = 1
463 * \`\`\`
464 * @example
465 * \`\`\`ts
466 * const x = 2
467 * \`\`\`
468 * @since 1.0.0
469 */
470 export function myfunc() {}`,
471 `## myfunc
472
473 description...
474
475 **Example**
476
477 \`\`\`ts
478 const x = 1
479 \`\`\`
480
481 **Example**
482
483 \`\`\`ts
484 const x = 2
485 \`\`\`
486
487 **Signature**
488
489 \`\`\`ts
490 declare const myfunc: () => void
491 \`\`\`
492
493 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L13)
494
495 Since v1.0.0`
496 )
497 }))
498
499 it.effect("example with metas", () =>
500 Effect.gen(function*() {
501 yield* expectMarkdown(
502 Parser.parseFunctions,
503 `/**
504 * description...
505 * @example
506 * \`\`\`ts a=1
507 * const x = 1
508 * \`\`\`
509 * @since 1.0.0
510 */
511 export function myfunc() {}`,
512 `## myfunc
513
514 description...
515
516 **Example**
517
518 \`\`\`ts a=1
519 const x = 1
520 \`\`\`
521
522 **Signature**
523
524 \`\`\`ts
525 declare const myfunc: () => void
526 \`\`\`
527
528 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L9)
529
530 Since v1.0.0`
531 )
532 }))
533
534 it.effect("example with titde fence", () =>
535 Effect.gen(function*() {
536 yield* expectMarkdown(
537 Parser.parseFunctions,
538 `/**
539 * description...
540 * @example
541 * ~~~ts
542 * const x = 1
543 * ~~~
544 * @since 1.0.0
545 */
546 export function myfunc() {}`,
547 `## myfunc
548
549 description...
550
551 **Example**
552
553 ~~~ts
554 const x = 1
555 ~~~
556
557 **Signature**
558
559 \`\`\`ts
560 declare const myfunc: () => void
561 \`\`\`
562
563 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L9)
564
565 Since v1.0.0`
566 )
567 }))
568
569 it.effect("should not return private function declarations", () =>
570 Effect.gen(function*() {
571 yield* expectMarkdown(
572 Parser.parseFunctions,
573 `/**
574 * description...
575 */
576 function myfunc() {}`,
577 ""
578 )
579 }))
580
581 it.effect("should not return ignored function declarations", () =>
582 Effect.gen(function*() {
583 yield* expectMarkdown(
584 Parser.parseFunctions,
585 `/**
586 * @ignore
587 */
588 export function myfunc() {}`,
589 ""
590 )
591 }))
592
593 it.effect("should not return ignored function declarations with overloads", () =>
594 Effect.gen(function*() {
595 yield* expectMarkdown(
596 Parser.parseFunctions,
597 `/**
598 * @ignore
599 */
600 export function sum(a: number, b: number)
601 export function sum(a: number, b: number): number { return a + b }`,
602 ""
603 )
604 }))
605
606 it.effect("should not return internal function declarations", () =>
607 Effect.gen(function*() {
608 yield* expectMarkdown(
609 Parser.parseFunctions,
610 `/**
611 * @internal
612 */
613 export function sum(a: number, b: number): number { return a + b }`,
614 ""
615 )
616 }))
617
618 it.effect("should not return internal function declarations even with overloads", () =>
619 Effect.gen(function*() {
620 yield* expectMarkdown(
621 Parser.parseFunctions,
622 `/**
623 * @internal
624 */
625 export function sum(a: number, b: number)
626 export function sum(a: number, b: number): number { return a + b }`,
627 ""
628 )
629 }))
630
631 it.effect("should not return private const function declarations", () =>
632 Effect.gen(function*() {
633 yield* expectMarkdown(
634 Parser.parseFunctions,
635 `const sum = (a: number, b: number): number => a + b `,
636 ""
637 )
638 }))
639
640 it.effect("should not return internal const function declarations", () =>
641 Effect.gen(function*() {
642 yield* expectMarkdown(
643 Parser.parseFunctions,
644 `/**
645 * @internal
646 */
647 export const sum = (a: number, b: number): number => a + b `,
648 ""
649 )
650 }))
651
652 it.effect("should account for nullable polymorphic return types", () =>
653 Effect.gen(function*() {
654 yield* expectMarkdown(
655 Parser.parseFunctions,
656 `/**
657 * @since 1.0.0
658 */
659 export const toNullable = <A>(ma: A | null): A | null => ma`,
660 `## toNullable
661
662 **Signature**
663
664 \`\`\`ts
665 declare const toNullable: <A>(ma: A | null) => A | null
666 \`\`\`
667
668 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L4)
669
670 Since v1.0.0`
671 )
672 }))
673
674 it.effect("should handle a const function declaration", () =>
675 Effect.gen(function*() {
676 yield* expectMarkdown(
677 Parser.parseFunctions,
678 `/**
679 * a description...
680 * @since 1.0.0
681 * @example
682 * assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })
683 * @example
684 * assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })
685 * @deprecated
686 */
687 export const f = (a: number, b: number): { [key: string]: number } => ({ a, b })`,
688 `## ~~f~~
689
690 a description...
691
692 **Example**
693
694 \`\`\`ts
695 assert.deepStrictEqual(f(1, 2), { a: 1, b: 2 })
696 \`\`\`
697
698 **Example**
699
700 \`\`\`ts
701 assert.deepStrictEqual(f(3, 4), { a: 3, b: 4 })
702 \`\`\`
703
704 **Signature**
705
706 \`\`\`ts
707 declare const f: (a: number, b: number) => { [key: string]: number; }
708 \`\`\`
709
710 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L10)
711
712 Since v1.0.0`
713 )
714 }))
715
716 it.effect("should handle a function declaration", () =>
717 Effect.gen(function*() {
718 yield* expectMarkdown(
719 Parser.parseFunctions,
720 `/**
721 * @since 1.0.0
722 */
723 export function f(a: number, b: number): { [key: string]: number } { return { a, b } }`,
724 `## f
725
726 **Signature**
727
728 \`\`\`ts
729 declare const f: (a: number, b: number) => { [key: string]: number; }
730 \`\`\`
731
732 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L4)
733
734 Since v1.0.0`
735 )
736 }))
737
738 it.effect("should handle overloadings", () =>
739 Effect.gen(function*() {
740 yield* expectMarkdown(
741 Parser.parseFunctions,
742 `/**
743 * a description...
744 * @since 1.0.0
745 * @deprecated
746 */
747 export function f(a: Int, b: Int): { [key: string]: number }
748 export function f(a: number, b: number): { [key: string]: number }
749 export function f(a: any, b: any): { [key: string]: number } { return { a, b } }`,
750 `## ~~f~~
751
752 a description...
753
754 **Signature**
755
756 \`\`\`ts
757 declare const f: { (a: Int, b: Int): { [key: string]: number; }; (a: number, b: number): { [key: string]: number; }; }
758 \`\`\`
759
760 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L8)
761
762 Since v1.0.0`
763 )
764 }))
765 })
766
767 describe("parseConstants", () => {
768 it.effect("should handle a constant value", () =>
769 Effect.gen(function*() {
770 yield* expectMarkdown(
771 Parser.parseConstants,
772 `/**
773 * a description...
774 * @since 1.0.0
775 * @deprecated
776 */
777 export const s: string = ''`,
778 `## ~~s~~
779
780 a description...
781
782 **Signature**
783
784 \`\`\`ts
785 declare const s: string
786 \`\`\`
787
788 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L6)
789
790 Since v1.0.0`
791 )
792 }))
793
794 it.effect("should support constants with default type parameters", () =>
795 Effect.gen(function*() {
796 yield* expectMarkdown(
797 Parser.parseConstants,
798 `/**
799 * @since 1.0.0
800 */
801 export const left: <E = never, A = never>(l: E) => string = T.left`,
802 `## left
803
804 **Signature**
805
806 \`\`\`ts
807 declare const left: <E = never, A = never>(l: E) => string
808 \`\`\`
809
810 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L4)
811
812 Since v1.0.0`
813 )
814 }))
815
816 it.effect("should support untyped constants", () =>
817 Effect.gen(function*() {
818 yield* expectMarkdown(
819 Parser.parseConstants,
820 `
821 class A {}
822 /**
823 * @since 1.0.0
824 */
825 export const empty = new A()`,
826 `## empty
827
828 **Signature**
829
830 \`\`\`ts
831 declare const empty: A
832 \`\`\`
833
834 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L6)
835
836 Since v1.0.0`
837 )
838 }))
839
840 it.effect("should handle constants with typeof annotations", () =>
841 Effect.gen(function*() {
842 yield* expectMarkdown(
843 Parser.parseConstants,
844 ` const task: { a: number } = {
845 a: 1
846 }
847 /**
848 * @since 1.0.0
849 */
850 export const taskSeq: typeof task = {
851 ...task,
852 ap: (mab, ma) => () => mab().then(f => ma().then(a => f(a)))
853 }`,
854 `## taskSeq
855
856 **Signature**
857
858 \`\`\`ts
859 declare const taskSeq: { a: number; }
860 \`\`\`
861
862 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L7)
863
864 Since v1.0.0`
865 )
866 }))
867
868 it.effect("should not include variables declared in for loops", () =>
869 Effect.gen(function*() {
870 yield* expectMarkdown(
871 Parser.parseConstants,
872 ` const object = { a: 1, b: 2, c: 3 };
873
874 for (const property in object) {
875 console.log(property);
876 }`,
877 ""
878 )
879 }))
880 })
881
882 describe("parseTypeAliases", () => {
883 it.effect("should return a type alias", () =>
884 Effect.gen(function*() {
885 yield* expectMarkdown(
886 Parser.parseTypeAliases,
887 `
888 type None<A> = { readonly _tag: "None" }
889 type Some<A> = { readonly _tag: "Some"; readonly value: A }
890 /**
891 * a description...
892 * @since 1.0.0
893 * @deprecated
894 */
895 export type Option<A> = None<A> | Some<A>`,
896 `## ~~Option~~ (type alias)
897
898 a description...
899
900 **Signature**
901
902 \`\`\`ts
903 type Option<A> = None<A> | Some<A>
904 \`\`\`
905
906 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L9)
907
908 Since v1.0.0`
909 )
910 }))
911 })
912
913 describe("parseExports", () => {
914 it.effect("should return no exports if the file is empty", () =>
915 Effect.gen(function*() {
916 yield* expectMarkdown(
917 Parser.parseExports,
918 "",
919 ""
920 )
921 }))
922
923 it.effect("should return an `Export`", () =>
924 Effect.gen(function*() {
925 yield* expectMarkdown(
926 Parser.parseExports,
927 `
928 const a = 1;
929 const b = 2;
930 export {
931 /**
932 * description_of_a
933 * \`\`\`ts
934 * const a: string = 1
935 * \`\`\`
936 *
937 * @since 1.0.0
938 */
939 a,
940 /**
941 * description_of_b
942 * @since 2.0.0
943 */
944 b
945 }`,
946 `## a
947
948 description_of_a
949 \`\`\`ts
950 const a: string = 1
951 \`\`\`
952
953 **Signature**
954
955 \`\`\`ts
956 declare const a: 1
957 \`\`\`
958
959 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L13)
960
961 Since v1.0.0
962 ## b
963
964 description_of_b
965
966 **Signature**
967
968 \`\`\`ts
969 declare const b: 2
970 \`\`\`
971
972 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L18)
973
974 Since v2.0.0`
975 )
976 }))
977
978 it.effect("should handle renamimg", () =>
979 Effect.gen(function*() {
980 yield* expectMarkdown(
981 Parser.parseExports,
982 `const a = 1;
983 export {
984 /**
985 * @since 1.0.0
986 */
987 a as b
988 }`,
989 `## b
990
991 **Signature**
992
993 \`\`\`ts
994 declare const b: 1
995 \`\`\`
996
997 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L6)
998
999 Since v1.0.0`
1000 )
1001 }))
1002
1003 it.effect("should handle a single re-export", () =>
1004 Effect.gen(function*() {
1005 project.createSourceFile("a.ts", `export const a = 1`)
1006 const sourceFile = project.createSourceFile(
1007 "b.ts",
1008 `import { a } from './a'
1009 const b = a
1010 export {
1011 /**
1012 * @since 1.0.0
1013 */
1014 b
1015 }`
1016 )
1017 const actual = yield* Effect.exit(Parser.parseExports.pipe(
1018 Effect.provideService(Parser.Source, makeSource(sourceFile)),
1019 Effect.provideService(Configuration.Configuration, defaultConfig)
1020 ))
1021 assert.deepStrictEqual(
1022 actual,
1023 Exit.succeed([
1024 new Domain.Export(
1025 "b",
1026 new Domain.Doc(
1027 undefined,
1028 ["1.0.0"],
1029 [],
1030 [],
1031 [],
1032 [],
1033 [],
1034 {
1035 "since": ["1.0.0"]
1036 }
1037 ),
1038 "declare const b: 1",
1039 {
1040 "column": 11,
1041 "line": 7
1042 },
1043 false
1044 )
1045 ])
1046 )
1047 }))
1048
1049 it.effect("should handle `export * from ...`", () =>
1050 Effect.gen(function*() {
1051 project.createSourceFile("example.ts", `export const a = 1`, { overwrite: true })
1052
1053 const sourceFile = project.createSourceFile(
1054 "export-all.ts",
1055 `
1056 /**
1057 * @since 1.0.0
1058 */
1059 export * from './example'
1060 `
1061 )
1062
1063 const actual = yield* Effect.exit(Parser.parseExports.pipe(
1064 Effect.provideService(Parser.Source, makeSource(sourceFile)),
1065 Effect.provideService(Configuration.Configuration, defaultConfig)
1066 ))
1067
1068 assert.deepStrictEqual(
1069 actual,
1070 Exit.succeed([
1071 new Domain.Export(
1072 "'./example'",
1073 new Domain.Doc(
1074 "Re-exports all named exports from the './example' module.",
1075 ["1.0.0"],
1076 [],
1077 [],
1078 [],
1079 [],
1080 [],
1081 {
1082 "since": ["1.0.0"]
1083 }
1084 ),
1085 "export * from './example'",
1086 {
1087 "column": 10,
1088 "line": 5
1089 },
1090 true
1091 )
1092 ])
1093 )
1094 }))
1095
1096 it.effect("should handle `export * as ... from ...`", () =>
1097 Effect.gen(function*() {
1098 project.createSourceFile("example.ts", `export const a = 1`, { overwrite: true })
1099
1100 const sourceFile = project.createSourceFile(
1101 "export-all-namespace.ts",
1102 `
1103 /**
1104 * @since 1.0.0
1105 */
1106 export * as example from './example'
1107 `
1108 )
1109
1110 const actual = yield* Effect.exit(Parser.parseExports.pipe(
1111 Effect.provideService(Parser.Source, makeSource(sourceFile)),
1112 Effect.provideService(Configuration.Configuration, defaultConfig)
1113 ))
1114
1115 assert.deepStrictEqual(
1116 actual,
1117 Exit.succeed([
1118 new Domain.Export(
1119 "example",
1120 new Domain.Doc(
1121 "Re-exports all named exports from the './example' module as `example`.",
1122 ["1.0.0"],
1123 [],
1124 [],
1125 [],
1126 [],
1127 [],
1128 {
1129 "since": ["1.0.0"]
1130 }
1131 ),
1132 "export * as example from './example'",
1133 {
1134 "column": 11,
1135 "line": 5
1136 },
1137 true
1138 )
1139 ])
1140 )
1141 }))
1142 })
1143
1144 describe("parseInterfaces", () => {
1145 it.effect("should return no interfaces if the file is empty", () =>
1146 Effect.gen(function*() {
1147 yield* expectMarkdown(
1148 Parser.parseInterfaces,
1149 "",
1150 ""
1151 )
1152 }))
1153
1154 it.effect("should return no interfaces if there are no exported interfaces", () =>
1155 Effect.gen(function*() {
1156 yield* expectMarkdown(
1157 Parser.parseInterfaces,
1158 "interface A {}",
1159 ""
1160 )
1161 }))
1162
1163 it.effect("should return an interface", () =>
1164 Effect.gen(function*() {
1165 yield* expectMarkdown(
1166 Parser.parseInterfaces,
1167 `/**
1168 * a description...
1169 * @since 1.0.0
1170 * @deprecated
1171 */
1172 export interface A {}`,
1173 `## ~~A~~ (interface)
1174
1175 a description...
1176
1177 **Signature**
1178
1179 \`\`\`ts
1180 export interface A {}
1181 \`\`\`
1182
1183 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L6)
1184
1185 Since v1.0.0`
1186 )
1187 }))
1188 })
1189
1190 describe("parseNamespaces", () => {
1191 it.effect("should return no namespaces if the file is empty", () =>
1192 Effect.gen(function*() {
1193 yield* expectMarkdown(
1194 Parser.parseNamespaces,
1195 "",
1196 ""
1197 )
1198 }))
1199
1200 it.effect("should return no namespaces if there are no exported namespaces", () =>
1201 Effect.gen(function*() {
1202 yield* expectMarkdown(
1203 Parser.parseNamespaces,
1204 "namespace A {}",
1205 ""
1206 )
1207 }))
1208
1209 it.effect("should parse an empty Namespace", () =>
1210 Effect.gen(function*() {
1211 yield* expectMarkdown(
1212 Parser.parseNamespaces,
1213 `
1214 /**
1215 * @since 1.0.0
1216 */
1217 export namespace A {}
1218 `,
1219 `## A (namespace)
1220
1221 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1222
1223 Since v1.0.0`
1224 )
1225 }))
1226
1227 describe("namespace > interfaces", () => {
1228 it.effect("should ignore not exported interfaces", () =>
1229 Effect.gen(function*() {
1230 yield* expectMarkdown(
1231 Parser.parseNamespaces,
1232 `
1233 /**
1234 * @since 1.0.0
1235 */
1236 export namespace A {
1237 interface C {}
1238 }
1239 `,
1240 `## A (namespace)
1241
1242 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1243
1244 Since v1.0.0`
1245 )
1246 }))
1247
1248 it.effect("should parse an interface", () =>
1249 Effect.gen(function*() {
1250 yield* expectMarkdown(
1251 Parser.parseNamespaces,
1252 `
1253 /**
1254 * @since 1.0.0
1255 */
1256 export namespace A {
1257 /**
1258 * @since 1.0.1
1259 */
1260 export interface B {
1261 readonly d: boolean
1262 }
1263 }
1264 `,
1265 `## A (namespace)
1266
1267 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1268
1269 Since v1.0.0
1270
1271 ### B (interface)
1272
1273 **Signature**
1274
1275 \`\`\`ts
1276 export interface B {
1277 readonly d: boolean
1278 }
1279 \`\`\`
1280
1281 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L9)
1282
1283 Since v1.0.1`
1284 )
1285 }))
1286 })
1287
1288 describe("namespace > type aliases", () => {
1289 it.effect("should ignore not exported type aliases", () =>
1290 Effect.gen(function*() {
1291 yield* expectMarkdown(
1292 Parser.parseNamespaces,
1293 `
1294 /**
1295 * @since 1.0.0
1296 */
1297 export namespace A {
1298 type C = number
1299 }
1300 `,
1301 `## A (namespace)
1302
1303 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1304
1305 Since v1.0.0`
1306 )
1307 }))
1308
1309 it.effect("should parse a type alias", () =>
1310 Effect.gen(function*() {
1311 yield* expectMarkdown(
1312 Parser.parseNamespaces,
1313 `
1314 /**
1315 * @since 1.0.0
1316 */
1317 export namespace A {
1318 /**
1319 * @since 1.0.1
1320 */
1321 export type B = string
1322 }
1323 `,
1324 `## A (namespace)
1325
1326 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1327
1328 Since v1.0.0
1329
1330 ### B (type alias)
1331
1332 **Signature**
1333
1334 \`\`\`ts
1335 type B = string
1336 \`\`\`
1337
1338 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L9)
1339
1340 Since v1.0.1`
1341 )
1342 }))
1343 })
1344
1345 describe("namespace > nested namespaces", () => {
1346 it.effect("should ignore not exported namespaces", () =>
1347 Effect.gen(function*() {
1348 yield* expectMarkdown(
1349 Parser.parseNamespaces,
1350 `
1351 /**
1352 * @since 1.0.0
1353 */
1354 export namespace A {
1355 namespace B {}
1356 }
1357 `,
1358 `## A (namespace)
1359
1360 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1361
1362 Since v1.0.0`
1363 )
1364 }))
1365
1366 it.effect("should parse a namespace", () =>
1367 Effect.gen(function*() {
1368 yield* expectMarkdown(
1369 Parser.parseNamespaces,
1370 `
1371 /**
1372 * @since 1.0.0
1373 */
1374 export namespace A {
1375 /**
1376 * @since 1.0.1
1377 */
1378 export namespace B {
1379 /**
1380 * @since 1.0.2
1381 */
1382 export type C = string
1383 }
1384 }
1385 `,
1386 `## A (namespace)
1387
1388 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1389
1390 Since v1.0.0
1391
1392 ### B (namespace)
1393
1394 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L9)
1395
1396 Since v1.0.1
1397
1398 #### C (type alias)
1399
1400 **Signature**
1401
1402 \`\`\`ts
1403 type C = string
1404 \`\`\`
1405
1406 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L13)
1407
1408 Since v1.0.2`
1409 )
1410 }))
1411 })
1412 })
1413
1414 describe("parseClasses", () => {
1415 it.effect("should ignore `@internal` classes", () =>
1416 Effect.gen(function*() {
1417 yield* expectMarkdown(
1418 Parser.parseClasses,
1419 `/** @internal */export class MyClass {}`,
1420 ""
1421 )
1422 }))
1423
1424 it.effect("should ignore `@ignore` classes", () =>
1425 Effect.gen(function*() {
1426 yield* expectMarkdown(
1427 Parser.parseClasses,
1428 `
1429 /** @ignore */
1430 export class MyClass {}
1431 `,
1432 ""
1433 )
1434 }))
1435
1436 it.effect("should ignore not exported classes", () =>
1437 Effect.gen(function*() {
1438 yield* expectMarkdown(
1439 Parser.parseClasses,
1440 `
1441 class MyClass {}
1442 `,
1443 ""
1444 )
1445 }))
1446
1447 it.effect("should skip ignored properties", () =>
1448 Effect.gen(function*() {
1449 yield* expectMarkdown(
1450 Parser.parseClasses,
1451 `/**
1452 * @since 1.0.0
1453 */
1454 export class MyClass<A> {
1455 /**
1456 * @ignore
1457 */
1458 readonly _A!: A
1459 }`,
1460 `## MyClass (class)
1461
1462 **Signature**
1463
1464 \`\`\`ts
1465 declare class MyClass<A>
1466 \`\`\`
1467
1468 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L4)
1469
1470 Since v1.0.0`
1471 )
1472 }))
1473
1474 it.effect("should skip the constructor body", () =>
1475 Effect.gen(function*() {
1476 yield* expectMarkdown(
1477 Parser.parseClasses,
1478 `/**
1479 * description
1480 * @since 1.0.0
1481 */
1482 export class C { constructor() {} }`,
1483 `## C (class)
1484
1485 description
1486
1487 **Signature**
1488
1489 \`\`\`ts
1490 declare class C { constructor() }
1491 \`\`\`
1492
1493 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1494
1495 Since v1.0.0`
1496 )
1497 }))
1498
1499 it("should get a constructor declaration signature", () => {
1500 const sourceFile = project.createSourceFile(
1501 `test-${testCounter++}.ts`,
1502 `
1503 /**
1504 * @since 1.0.0
1505 */
1506 declare class A {
1507 constructor()
1508 }
1509 `
1510 )
1511
1512 const constructorDeclaration = sourceFile
1513 .getClass("A")!
1514 .getConstructors()[0]
1515
1516 assert.deepStrictEqual(
1517 Parser.getConstructorDeclarationSignature(constructorDeclaration),
1518 "constructor()"
1519 )
1520 })
1521
1522 it.effect("should handle non-readonly properties", () =>
1523 Effect.gen(function*() {
1524 yield* expectMarkdown(
1525 Parser.parseClasses,
1526 `/**
1527 * description
1528 * @since 1.0.0
1529 */
1530 export class C {
1531 /**
1532 * @since 1.0.0
1533 */
1534 a: string
1535 }`,
1536 `## C (class)
1537
1538 description
1539
1540 **Signature**
1541
1542 \`\`\`ts
1543 declare class C
1544 \`\`\`
1545
1546 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1547
1548 Since v1.0.0
1549
1550 ### a (property)
1551
1552 **Signature**
1553
1554 \`\`\`ts
1555 a: string
1556 \`\`\`
1557
1558 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L9)
1559
1560 Since v1.0.0`
1561 )
1562 }))
1563
1564 it.effect("should return a `Class`", () =>
1565 Effect.gen(function*() {
1566 yield* expectMarkdown(
1567 Parser.parseClasses,
1568 `/**
1569 * a class description...
1570 * @since 1.0.0
1571 * @deprecated
1572 */
1573 export class Test {
1574 /**
1575 * a property...
1576 * @since 1.1.0
1577 * @deprecated
1578 */
1579 readonly a: string
1580 private readonly b: number
1581 /**
1582 * a static method description...
1583 * @since 1.1.0
1584 * @deprecated
1585 */
1586 static f(): void {}
1587 constructor(readonly value: string) { }
1588 /**
1589 * a method description...
1590 * @since 1.1.0
1591 * @deprecated
1592 */
1593 g(a: number, b: number): { [key: string]: number } {
1594 return { a, b }
1595 }
1596 }`,
1597 `## ~~Test~~ (class)
1598
1599 a class description...
1600
1601 **Signature**
1602
1603 \`\`\`ts
1604 declare class Test { constructor(readonly value: string) }
1605 \`\`\`
1606
1607 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L6)
1608
1609 Since v1.0.0
1610
1611 ### ~~f~~ (static method)
1612
1613 a static method description...
1614
1615 **Signature**
1616
1617 \`\`\`ts
1618 declare const f: () => void
1619 \`\`\`
1620
1621 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L19)
1622
1623 Since v1.1.0
1624
1625 ### ~~g~~ (method)
1626
1627 a method description...
1628
1629 **Signature**
1630
1631 \`\`\`ts
1632 declare const g: (a: number, b: number) => { [key: string]: number; }
1633 \`\`\`
1634
1635 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L26)
1636
1637 Since v1.1.0
1638
1639 ### ~~a~~ (property)
1640
1641 a property...
1642
1643 **Signature**
1644
1645 \`\`\`ts
1646 readonly a: string
1647 \`\`\`
1648
1649 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L12)
1650
1651 Since v1.1.0`
1652 )
1653 }))
1654
1655 it.effect("should handle method overloadings", () =>
1656 Effect.gen(function*() {
1657 yield* expectMarkdown(
1658 Parser.parseClasses,
1659 `/**
1660 * a class description...
1661 * @since 1.0.0
1662 * @deprecated
1663 */
1664 export class Test<A> {
1665 /**
1666 * a static method description...
1667 * @since 1.1.0
1668 * @deprecated
1669 */
1670 static f(x: number): number
1671 static f(x: string): string
1672 static f(x: any): any {}
1673 constructor(readonly value: A) { }
1674 /**
1675 * a method description...
1676 * @since 1.1.0
1677 * @deprecated
1678 */
1679 map(f: (a: number) => number): Test
1680 map(f: (a: string) => string): Test
1681 map(f: (a: any) => any): any {
1682 return new Test(f(this.value))
1683 }
1684 }`,
1685 `## ~~Test~~ (class)
1686
1687 a class description...
1688
1689 **Signature**
1690
1691 \`\`\`ts
1692 declare class Test<A> { constructor(readonly value: A) }
1693 \`\`\`
1694
1695 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L6)
1696
1697 Since v1.0.0
1698
1699 ### ~~f~~ (static method)
1700
1701 a static method description...
1702
1703 **Signature**
1704
1705 \`\`\`ts
1706 declare const f: { (x: number): number; (x: string): string; }
1707 \`\`\`
1708
1709 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L14)
1710
1711 Since v1.1.0
1712
1713 ### ~~map~~ (method)
1714
1715 a method description...
1716
1717 **Signature**
1718
1719 \`\`\`ts
1720 declare const map: { (f: (a: number) => number): Test; (f: (a: string) => string): Test; }
1721 \`\`\`
1722
1723 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L23)
1724
1725 Since v1.1.0`
1726 )
1727 }))
1728
1729 it.effect("should ignore internal/ignored methods (#42)", () =>
1730 Effect.gen(function*() {
1731 yield* expectMarkdown(
1732 Parser.parseClasses,
1733 `/**
1734 * a class description...
1735 * @since 1.0.0
1736 */
1737 export class Test<A> {
1738 /**
1739 * @since 0.0.1
1740 * @internal
1741 **/
1742 private foo(): void {}
1743 /**
1744 * @since 0.0.1
1745 * @ignore
1746 **/
1747 private bar(): void {}
1748 }`,
1749 `## Test (class)
1750
1751 a class description...
1752
1753 **Signature**
1754
1755 \`\`\`ts
1756 declare class Test<A>
1757 \`\`\`
1758
1759 [Source](https://github.com/effect-ts/docgen/blob/main/src/test.ts#L5)
1760
1761 Since v1.0.0`
1762 )
1763 }))
1764 })
1765
1766 describe("parseFile", () => {
1767 it.effect("should not parse a non-existent file", () =>
1768 Effect.gen(function*() {
1769 const file = new Domain.File("non-existent.ts", "")
1770 const project = new ast.Project({ useInMemoryFileSystem: true })
1771
1772 assert.deepStrictEqual(
1773 yield* Effect.exit(
1774 Parser.parseFile(project)(file).pipe(
1775 Effect.provideService(Configuration.Configuration, defaultConfig),
1776 Effect.provide(Path.layer)
1777 )
1778 ),
1779 Exit.fail(["Unable to locate file: non-existent.ts"])
1780 )
1781 }))
1782 })
1783
1784 describe("utils", () => {
1785 it("parseComment", () => {
1786 assert.deepStrictEqual(Parser.parseComment(""), {
1787 description: undefined,
1788 tags: {}
1789 })
1790
1791 assert.deepStrictEqual(Parser.parseComment("/** description */"), {
1792 description: "description",
1793 tags: {}
1794 })
1795
1796 assert.deepStrictEqual(
1797 Parser.parseComment("/** description\n * @since 1.0.0\n */"),
1798 {
1799 description: "description",
1800 tags: {
1801 since: ["1.0.0"]
1802 }
1803 }
1804 )
1805
1806 assert.deepStrictEqual(
1807 Parser.parseComment("/** description\n * @deprecated\n */"),
1808 {
1809 description: "description",
1810 tags: {
1811 deprecated: [""]
1812 }
1813 }
1814 )
1815
1816 assert.deepStrictEqual(
1817 Parser.parseComment("/** description\n * @category instance\n */"),
1818 {
1819 description: "description",
1820 tags: {
1821 category: ["instance"]
1822 }
1823 }
1824 )
1825 })
1826 })
1827 })