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

main
ts 1,624 lines 41.1 KB
Raw
1 import { computeJSDocInputHash, extractJSDocsSync, loadJSDocConfig, parseJSDoc } from "@effect/jsdocs"
2 import { assert, describe, it } from "@effect/vitest"
3 import * as fs from "node:fs"
4 import * as os from "node:os"
5 import * as path from "node:path"
6 import * as ts from "typescript"
7
8 interface SourceFileWithParseDiagnostics extends ts.SourceFile {
9 readonly parseDiagnostics: ReadonlyArray<ts.Diagnostic>
10 }
11
12 const stabilityResult = (tag: string) => {
13 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-stability-"))
14 try {
15 fs.mkdirSync(path.join(cwd, "src"))
16 fs.writeFileSync(
17 path.join(cwd, "tsconfig.json"),
18 JSON.stringify({
19 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
20 include: ["src/**/*.ts"]
21 })
22 )
23 fs.writeFileSync(
24 path.join(cwd, "package.json"),
25 JSON.stringify({
26 name: "@effect/sample",
27 type: "module",
28 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
29 })
30 )
31 fs.writeFileSync(
32 path.join(cwd, "src/index.ts"),
33 `/**
34 * @stability stable
35 * @since 1.0.0
36 */
37 export * as Foo from "./Foo.ts"\n`
38 )
39 fs.writeFileSync(
40 path.join(cwd, "src/Foo.ts"),
41 `/**
42 * Creates a value.
43 *
44 * ${tag}
45 * @category constructors
46 * @since 1.0.0
47 */
48 export const makeValue = () => 1
49 `
50 )
51 const model = extractJSDocsSync({
52 cwd,
53 tsconfig: "tsconfig.json",
54 include: ["src/**/*.ts"],
55 output: ".data/jsdocs.json"
56 })
57 return {
58 diagnostics: model.files.flatMap((file) => file.diagnostics.map((diagnostic) => diagnostic.code)),
59 stability: model.apis.find((api) => api.apiFqn === "@effect/sample/Foo.makeValue")?.tags.stability
60 }
61 } finally {
62 fs.rmSync(cwd, { recursive: true, force: true })
63 }
64 }
65
66 const missingStabilityDiagnostics = (files: Record<string, string>, moduleStability = "@stability stable") => {
67 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-require-stability-"))
68 try {
69 fs.mkdirSync(path.join(cwd, "src"))
70 fs.writeFileSync(
71 path.join(cwd, "tsconfig.json"),
72 JSON.stringify({
73 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
74 include: ["src/**/*.ts"]
75 })
76 )
77 fs.writeFileSync(
78 path.join(cwd, "package.json"),
79 JSON.stringify({ name: "@effect/sample", type: "module", exports: { "./*": "./src/*.ts" } })
80 )
81 for (const [file, source] of Object.entries(files)) {
82 fs.writeFileSync(
83 path.join(cwd, "src", file),
84 `/**
85 * Module.
86 *
87 * ${moduleStability}
88 * @since 1.0.0
89 */
90 import type {} from "node:fs"
91
92 ${source}`
93 )
94 }
95 const model = extractJSDocsSync({ cwd, tsconfig: "tsconfig.json", include: ["src/**/*.ts"], output: "out.json" })
96 return Object.fromEntries(
97 Object.keys(files).map((file) => [
98 file,
99 model.files.find((modelFile) => modelFile.file === `src/${file}`)?.diagnostics.map((item) => item.message) ??
100 []
101 ])
102 )
103 } finally {
104 fs.rmSync(cwd, { recursive: true, force: true })
105 }
106 }
107
108 const signatureParseDiagnostics = (signature: string): ReadonlyArray<string> =>
109 (ts.createSourceFile(
110 "signature.ts",
111 signature,
112 ts.ScriptTarget.Latest,
113 true,
114 ts.ScriptKind.TS
115 ) as SourceFileWithParseDiagnostics)
116 .parseDiagnostics.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"))
117
118 describe("jsdocs", () => {
119 it("parses a raw JSDoc block", () => {
120 const result = parseJSDoc(`/**
121 * Creates a value.
122 *
123 * @category constructors
124 * @since 1.0.0
125 */`)
126 assert.strictEqual(result._tag, "Success")
127 if (result._tag === "Success") {
128 assert.strictEqual(result.value.description.short, "Creates a value.")
129 }
130 })
131
132 it("accepts unstable declarations", () => {
133 const result = parseJSDoc(`/**
134 * Creates an unstable value.
135 *
136 * @stability unstable
137 * @category constructors
138 * @since 1.0.0
139 */`)
140 assert.strictEqual(result._tag, "Success")
141 })
142
143 it("accepts experimental declarations", () => {
144 assert.deepStrictEqual(stabilityResult("@stability experimental"), {
145 diagnostics: [],
146 stability: "experimental"
147 })
148 })
149
150 it("accepts explicit stable declarations", () => {
151 assert.deepStrictEqual(stabilityResult("@stability stable"), {
152 diagnostics: [],
153 stability: "stable"
154 })
155 })
156
157 it("rejects unknown stability values", () => {
158 assert.deepStrictEqual(stabilityResult("@stability bogus").diagnostics, ["invalid-stability"])
159 })
160
161 it("requires @stability on directly importable declarations", () => {
162 assert.deepStrictEqual(
163 missingStabilityDiagnostics({
164 "Declaration.ts": `/**
165 * A value.
166 *
167 * @category constructors
168 * @since 1.0.0
169 */
170 export const value = 1
171 `,
172 "Specifier.ts": `const value = 1
173
174 export {
175 /**
176 * A value.
177 *
178 * @category constructors
179 * @since 1.0.0
180 */
181 value
182 }
183 `,
184 "Namespace.ts": `/**
185 * A group.
186 *
187 * @category models
188 * @since 1.0.0
189 */
190 export declare namespace Group {}
191 `,
192 "Nested.ts": `/**
193 * A group.
194 *
195 * @stability stable
196 * @category models
197 * @since 1.0.0
198 */
199 export declare namespace Group {
200 /**
201 * Declarations inside a namespace do not require a stability tag.
202 *
203 * @category models
204 * @since 1.0.0
205 */
206 export interface Item {
207 /**
208 * Members do not require a stability tag.
209 */
210 readonly id: string
211 }
212 }
213 `
214 }),
215 {
216 "Declaration.ts": ["Public JSDoc must include @stability"],
217 "Specifier.ts": ["Public JSDoc must include @stability"],
218 "Namespace.ts": ["Public JSDoc must include @stability"],
219 "Nested.ts": []
220 }
221 )
222 })
223
224 it("requires @stability on module JSDoc", () => {
225 assert.deepStrictEqual(missingStabilityDiagnostics({ "Module.ts": "" }, "Has no stability tag."), {
226 "Module.ts": ["Module JSDoc must include @stability"]
227 })
228 })
229
230 it("requires @stability on namespace re-exports", () => {
231 assert.deepStrictEqual(
232 missingStabilityDiagnostics({
233 "Missing.ts": `/**
234 * Re-exports a module.
235 *
236 * @category exports
237 * @since 1.0.0
238 */
239 export * as Target from "./Target.ts"
240 `,
241 "Tagged.ts": `/**
242 * Re-exports a module.
243 *
244 * @stability stable
245 * @category exports
246 * @since 1.0.0
247 */
248 export * as Target from "./Target.ts"
249 `,
250 "Target.ts": `/**
251 * A value.
252 *
253 * @stability stable
254 * @category constructors
255 * @since 1.0.0
256 */
257 export const value = 1
258 `
259 }),
260 {
261 "Missing.ts": ["Public JSDoc must include @stability"],
262 "Tagged.ts": [],
263 "Target.ts": []
264 }
265 )
266 })
267
268 it("checks hand-maintained public index exports with the repository JSDoc config", () => {
269 const config = loadJSDocConfig(path.resolve(import.meta.dirname, "../../../.."))
270 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-public-index-"))
271 try {
272 const packageRoot = path.join(cwd, "packages/atom/vue")
273 fs.mkdirSync(path.join(packageRoot, "src"), { recursive: true })
274 fs.writeFileSync(
275 path.join(cwd, config.tsconfig),
276 JSON.stringify({
277 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
278 include: ["packages/**/src/**/*.ts"]
279 })
280 )
281 fs.writeFileSync(
282 path.join(packageRoot, "package.json"),
283 JSON.stringify({ name: "@effect/atom-vue", type: "module", exports: { ".": "./src/index.ts" } })
284 )
285 fs.writeFileSync(
286 path.join(packageRoot, "src/index.ts"),
287 `/**
288 * Public entry point.
289 *
290 * @stability unstable
291 * @since 1.0.0
292 */
293 import type {} from "node:fs"
294
295 /**
296 * A directly importable value.
297 *
298 * @category constructors
299 * @since 1.0.0
300 */
301 export const value = 1
302 `
303 )
304 const model = extractJSDocsSync({ ...config, cwd })
305 assert.deepStrictEqual(
306 model.files.find((file) => file.file === "packages/atom/vue/src/index.ts")?.diagnostics
307 .filter((diagnostic) => diagnostic.code === "missing-tag")
308 .map((diagnostic) => diagnostic.message),
309 ["Public JSDoc must include @stability"]
310 )
311 } finally {
312 fs.rmSync(cwd, { recursive: true, force: true })
313 }
314 })
315
316 it("rejects duplicate stability tags", () => {
317 assert.deepStrictEqual(stabilityResult("@stability unstable\n * @stability unstable").diagnostics, [
318 "duplicate-tag"
319 ])
320 })
321
322 it("rejects legacy unstable tags", () => {
323 assert.deepStrictEqual(stabilityResult("@unstable").diagnostics, ["forbidden-tag", "missing-tag"])
324 })
325
326 it("accepts doctest metadata on TypeScript fences", () => {
327 const result = parseJSDoc(`/**
328 * Creates a value.
329 *
330 * **Example** (Creating a value)
331 *
332 * \`\`\`ts import.meta.vitest name="creates a value"
333 * const value = 1
334 * \`\`\`
335 *
336 * @category constructors
337 * @since 1.0.0
338 */`)
339 assert.strictEqual(result._tag, "Success")
340 })
341
342 it("accepts practical When to use forms", () => {
343 const result = parseJSDoc(`/**
344 * Creates a value.
345 *
346 * **When to use**
347 *
348 * Use to create a value when construction should be explicit.
349 *
350 * @category constructors
351 * @since 1.0.0
352 */`)
353 assert.strictEqual(result._tag, "Success")
354 if (result._tag === "Success") {
355 assert.strictEqual(
356 result.value.description.whenToUse,
357 "Use to create a value when construction should be explicit."
358 )
359 }
360 })
361
362 it("flags unsupported When to use forms", () => {
363 const result = parseJSDoc(`/**
364 * Creates a value.
365 *
366 * **When to use**
367 *
368 * - Creating a value when construction should be explicit.
369 *
370 * @category constructors
371 * @since 1.0.0
372 */`)
373 assert.strictEqual(result._tag, "Failure")
374 if (result._tag === "Failure") {
375 assert.deepStrictEqual(
376 result.error.diagnostics.map((diagnostic) => diagnostic.code),
377 ["when-to-use-format"]
378 )
379 }
380 })
381
382 it("refreshes extracted docs after a source change", () => {
383 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
384 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
385 fs.writeFileSync(
386 path.join(cwd, "tsconfig.json"),
387 JSON.stringify({
388 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
389 include: ["src/**/*.ts"]
390 })
391 )
392 fs.writeFileSync(
393 path.join(cwd, "package.json"),
394 JSON.stringify({
395 name: "@effect/sample",
396 type: "module",
397 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
398 })
399 )
400 fs.writeFileSync(
401 path.join(cwd, "src/index.ts"),
402 `/**
403 * @stability stable
404 * @since 1.0.0
405 */
406 export * as Foo from "./Foo.ts"\n`
407 )
408 fs.writeFileSync(
409 path.join(cwd, "src/Foo.ts"),
410 `/**
411 * Creates a value.
412 *
413 * @stability stable
414 * @category constructors
415 * @since 1.0.0
416 */
417 export const makeValue = () => 1
418 `
419 )
420 const options = {
421 cwd,
422 tsconfig: "tsconfig.json",
423 include: ["src/**/*.ts"],
424 output: ".data/jsdocs.json"
425 }
426 const model = extractJSDocsSync(options)
427 assert.strictEqual(model.version, 3)
428 assert.deepStrictEqual(model.files.map((file) => file.file), ["src/Foo.ts", "src/index.ts"])
429 const index = model.files.find((file) => file.file === "src/index.ts")
430 assert.deepStrictEqual(index?.diagnostics, [])
431 assert.strictEqual(index?.namespaces[0]?.name, "Foo")
432 assert.strictEqual(model.apis.some((api) => api.apiFqn === "@effect/sample.Foo"), true)
433 assert.strictEqual(model.files[0]?.declarations[0]?.name, "makeValue")
434 assert.strictEqual(model.apis[0]?.apiFqn, "@effect/sample/Foo.makeValue")
435 assert.deepStrictEqual(model.apis[0]?.importGuidance, {
436 style: "namespace-barrel",
437 importDeclaration: "import { Foo } from \"@effect/sample\"",
438 usage: "Foo.makeValue"
439 })
440
441 const sourcePath = path.join(cwd, "src/Foo.ts")
442 fs.writeFileSync(sourcePath, fs.readFileSync(sourcePath, "utf8").replaceAll("makeValue", "makeUpdatedValue"))
443 const updated = extractJSDocsSync(options)
444 assert.strictEqual(updated.files[0]?.declarations[0]?.name, "makeUpdatedValue")
445 })
446
447 it("stores a stable input hash for cache checks", () => {
448 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
449 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
450 fs.writeFileSync(
451 path.join(cwd, "tsconfig.json"),
452 JSON.stringify({
453 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
454 include: ["src/**/*.ts"]
455 })
456 )
457 fs.writeFileSync(
458 path.join(cwd, "jsdocs.config.json"),
459 JSON.stringify({
460 tsconfig: "tsconfig.json",
461 include: ["src/**/*.ts"],
462 output: ".data/jsdocs.json"
463 })
464 )
465 fs.writeFileSync(
466 path.join(cwd, "package.json"),
467 JSON.stringify({
468 name: "@effect/sample",
469 type: "module",
470 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
471 })
472 )
473 fs.writeFileSync(
474 path.join(cwd, "src/index.ts"),
475 `/**
476 * @stability stable
477 * @since 1.0.0
478 */
479 export * as Foo from "./Foo.ts"\n`
480 )
481 fs.writeFileSync(
482 path.join(cwd, "src/Foo.ts"),
483 `/**
484 * Creates a value.
485 *
486 * @stability stable
487 * @category constructors
488 * @since 1.0.0
489 */
490 export const makeValue = () => 1
491 `
492 )
493 const options = {
494 cwd,
495 tsconfig: "tsconfig.json",
496 include: ["src/**/*.ts"],
497 output: ".data/jsdocs.json"
498 }
499 const inputHash = computeJSDocInputHash(options)
500 const model = extractJSDocsSync(options)
501 assert.strictEqual(model.inputHash, inputHash)
502 assert.strictEqual(computeJSDocInputHash(options), inputHash)
503
504 fs.appendFileSync(path.join(cwd, "src/Foo.ts"), "\n")
505 assert.notStrictEqual(computeJSDocInputHash(options), inputHash)
506 })
507
508 it("extracts typechecker signatures for top-level functions", () => {
509 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
510 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
511 fs.writeFileSync(
512 path.join(cwd, "tsconfig.json"),
513 JSON.stringify({
514 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
515 include: ["src/**/*.ts"]
516 })
517 )
518 fs.writeFileSync(
519 path.join(cwd, "package.json"),
520 JSON.stringify({
521 name: "@effect/sample",
522 type: "module",
523 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
524 })
525 )
526 fs.writeFileSync(
527 path.join(cwd, "src/index.ts"),
528 `/**
529 * @stability stable
530 * @since 1.0.0
531 */
532 export * as Foo from "./Foo.ts"\n`
533 )
534 fs.writeFileSync(
535 path.join(cwd, "src/External.ts"),
536 `/**
537 * External value type.
538 *
539 * @stability stable
540 * @category models
541 * @since 1.0.0
542 */
543 export interface External {
544 readonly value: string
545 }
546
547 /**
548 * Makes an external value.
549 *
550 * @stability stable
551 * @category constructors
552 * @since 1.0.0
553 */
554 export const makeExternal = (value: string): External => ({ value })
555 `
556 )
557 fs.writeFileSync(
558 path.join(cwd, "src/Foo.ts"),
559 `/**
560 * Parses a value.
561 *
562 * @stability stable
563 * @category parsing
564 * @since 1.0.0
565 */
566 export function parse(value: string): string
567 export function parse(value: number): number
568 export function parse(value: string | number) {
569 return value
570 }
571
572 /**
573 * Converts a value.
574 *
575 * @stability stable
576 * @category constructors
577 * @since 1.0.0
578 */
579 export const inferred = (value: number) => String(value)
580
581 const aliased = (value: boolean) => !value
582
583 export {
584 /**
585 * Negates a value.
586 *
587 * @stability stable
588 * @category constructors
589 * @since 1.0.0
590 */
591 aliased as renamed
592 }
593
594 export {
595 /**
596 * Makes an external value.
597 *
598 * @stability stable
599 * @category constructors
600 * @since 1.0.0
601 */
602 makeExternal as external
603 } from "./External.ts"
604
605 const attempt = (value: string) => value.length
606
607 export {
608 /**
609 * Attempts a value.
610 *
611 * @stability stable
612 * @category constructors
613 * @since 1.0.0
614 */
615 attempt as try
616 }
617
618 /**
619 * Handles many overloads.
620 *
621 * @stability stable
622 * @category constructors
623 * @since 1.0.0
624 */
625 export function many(value: 1): 1
626 export function many(value: 2): 2
627 export function many(value: 3): 3
628 export function many(value: 4): 4
629 export function many(value: 5): 5
630 export function many(value: 6): 6
631 export function many(value: 7): 7
632 export function many(value: 8): 8
633 export function many(value: 9): 9
634 export function many(value: 10): 10
635 export function many(value: 11): 11
636 export function many(value: 12): 12
637 export function many(value: 13): 13
638 export function many(value: number) {
639 return value
640 }
641
642 /**
643 * Runs a value through a transform chain.
644 *
645 * @stability stable
646 * @category constructors
647 * @since 1.0.0
648 */
649 export function pipeline<A>(a: A): A
650 export function pipeline<A, B>(a: A, ab: (a: A) => B): B
651 export function pipeline<A, B, C>(a: A, ab: (a: A) => B, bc: (b: B) => C): C
652 export function pipeline<A, B, C, D>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D
653 export function pipeline<A, B, C, D, E>(
654 a: A,
655 ab: (a: A) => B,
656 bc: (b: B) => C,
657 cd: (c: C) => D,
658 de: (d: D) => E
659 ): E
660 export function pipeline<A, B, C, D, E, F>(
661 a: A,
662 ab: (a: A) => B,
663 bc: (b: B) => C,
664 cd: (c: C) => D,
665 de: (d: D) => E,
666 ef: (e: E) => F
667 ): F
668 export function pipeline<A, B, C, D, E, F, G>(
669 a: A,
670 ab: (a: A) => B,
671 bc: (b: B) => C,
672 cd: (c: C) => D,
673 de: (d: D) => E,
674 ef: (e: E) => F,
675 fg: (f: F) => G
676 ): G
677 export function pipeline<A, B, C, D, E, F, G, H>(
678 a: A,
679 ab: (a: A) => B,
680 bc: (b: B) => C,
681 cd: (c: C) => D,
682 de: (d: D) => E,
683 ef: (e: E) => F,
684 fg: (f: F) => G,
685 gh: (g: G) => H
686 ): H
687 export function pipeline<A, B, C, D, E, F, G, H, I>(
688 a: A,
689 ab: (a: A) => B,
690 bc: (b: B) => C,
691 cd: (c: C) => D,
692 de: (d: D) => E,
693 ef: (e: E) => F,
694 fg: (f: F) => G,
695 gh: (g: G) => H,
696 hi: (h: H) => I
697 ): I
698 export function pipeline(...args: Array<any>) {
699 return args.length === 1 ? args[0] : args.slice(1).reduce((value, f) => f(value), args[0])
700 }
701
702 interface Box<in out A> {}
703
704 declare namespace Box {
705 export type Inner<A extends Box<any>> = A extends Box<infer T> ? T : never
706 }
707
708 interface Check<A> {}
709
710 interface Ctor<A extends Box<any>> {
711 (value: Box.Inner<A>): A
712 }
713
714 /**
715 * Builds a boxed constructor.
716 *
717 * @stability stable
718 * @category constructors
719 * @since 1.0.0
720 */
721 export function boxed<A extends Box<any>>(
722 ...value: readonly [Check<Box.Inner<A>>, ...Array<Check<Box.Inner<A>>>]
723 ): Ctor<A> {
724 return null as any
725 }
726
727 /**
728 * Handles distinct overload modes.
729 *
730 * @stability stable
731 * @category constructors
732 * @since 1.0.0
733 */
734 export function modes(body: () => string): string
735 export function modes(body: (value: number) => string): string
736 export function modes(body: (this: string) => string): string
737 export function modes(body: () => string, map: (value: string) => number): number
738 export function modes(body: () => string, map: (value: string) => number, next: (value: number) => boolean): boolean
739 export function modes(options: { readonly self: string }, body: (this: string) => string): string
740 export function modes(name: string): (body: () => string) => string
741 export function modes(self: string, body: () => string): string
742 export function modes(predicate: (value: number) => boolean, body: () => number): number
743 export function modes(refinement: (value: string | number) => value is string, body: () => string): string
744 export function modes(...args: Array<any>) {
745 return args[0]
746 }
747
748 /**
749 * Service for sample values.
750 *
751 * @stability stable
752 * @category services
753 * @since 1.0.0
754 */
755 export class Service {
756 readonly value: string
757 /**
758 * Runs the service.
759 */
760 run(input: number): string {
761 return \`\${this.value}:\${input}\`
762 }
763 }
764
765 /**
766 * Default count.
767 *
768 * @stability stable
769 * @category constants
770 * @since 1.0.0
771 */
772 export const count = 1
773
774 /**
775 * Sample value type.
776 *
777 * @stability stable
778 * @category models
779 * @since 1.0.0
780 */
781 export interface Sample {
782 readonly value: string
783 }
784 `
785 )
786 const model = extractJSDocsSync({
787 cwd,
788 tsconfig: "tsconfig.json",
789 include: ["src/**/*.ts"],
790 output: ".data/jsdocs.json"
791 })
792 const signatureByName = new Map(model.apis.map((api) => [api.apiName, api.signature]))
793 assert.deepStrictEqual(model.files.flatMap((file) => file.diagnostics), [])
794 for (const api of model.apis) {
795 if (api.signature !== null) {
796 const diagnostics = signatureParseDiagnostics(api.signature)
797 if (diagnostics.length > 0) {
798 assert.fail(`${api.apiName}: ${diagnostics.join(", ")}`)
799 }
800 }
801 }
802 assert.strictEqual(
803 signatureByName.get("parse"),
804 "declare function parse(value: string): string\ndeclare function parse(value: number): number"
805 )
806 assert.strictEqual(signatureByName.get("inferred"), "declare function inferred(value: number): string")
807 assert.strictEqual(signatureByName.get("renamed"), "declare function renamed(value: boolean): boolean")
808 assert.strictEqual(
809 signatureByName.get("try"),
810 `declare const _try: {
811 (value: string): number;
812 }
813 export { _try as try }`
814 )
815 assert.strictEqual(signatureByName.get("external"), "declare function external(value: string): External")
816 const manyLines = signatureByName.get("many")?.split("\n")
817 assert.strictEqual(manyLines?.length, 1)
818 assert.strictEqual(manyLines?.[0], "declare function many(value: 1): 1")
819 const pipelineLines = signatureByName.get("pipeline")?.split("\n") ?? []
820 assert.strictEqual(pipelineLines.length, 6)
821 assert.deepStrictEqual(pipelineLines.map((line) => line.match(/=>/g)?.length ?? 0), [0, 1, 2, 3, 4, 8])
822 const boxedSignature = signatureByName.get("boxed")
823 assert.strictEqual(
824 boxedSignature,
825 "declare const boxed: <A extends Box<any>>(value_0: Check<Box.Inner<A>>, ...value: Check<Box.Inner<A>>[]) => Ctor<A>"
826 )
827 const modeLines = signatureByName.get("modes")?.split("\n")
828 assert.deepStrictEqual(modeLines, [
829 "declare function modes(body: () => string): string",
830 "declare function modes(body: (this: string) => string): string",
831 "declare function modes(body: () => string, map: (value: string) => number): number",
832 "declare function modes(options: { readonly self: string; }, body: (this: string) => string): string",
833 "declare function modes(name: string): (body: () => string) => string",
834 "declare function modes(self: string, body: () => string): string",
835 "declare function modes(predicate: (value: number) => boolean, body: () => number): number",
836 "declare function modes(refinement: (value: string | number) => value is string, body: () => string): string"
837 ])
838 assert.strictEqual(signatureByName.get("Service"), null)
839 assert.strictEqual(signatureByName.get("Service.run"), null)
840 assert.strictEqual(signatureByName.get("count"), null)
841 assert.strictEqual(signatureByName.get("Sample"), null)
842 })
843
844 it("stores valid top-of-file module JSDoc", () => {
845 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
846 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
847 fs.writeFileSync(
848 path.join(cwd, "tsconfig.json"),
849 JSON.stringify({
850 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
851 include: ["src/**/*.ts"]
852 })
853 )
854 fs.writeFileSync(
855 path.join(cwd, "package.json"),
856 JSON.stringify({
857 name: "@effect/sample",
858 type: "module",
859 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
860 })
861 )
862 fs.writeFileSync(
863 path.join(cwd, "src/index.ts"),
864 `/**
865 * @stability stable
866 * @since 1.0.0
867 */
868 export * as Foo from "./Foo.ts"\n`
869 )
870 fs.writeFileSync(
871 path.join(cwd, "src/Foo.ts"),
872 `/**
873 * The Foo module provides helpers for sample values. Use {@link makeValue} to
874 * create the default value.
875 *
876 * **Example** (Using the module)
877 *
878 * \`\`\`ts
879 * import { Foo } from "@effect/sample"
880 *
881 * Foo.makeValue()
882 * \`\`\`
883 *
884 * @see {@link makeValue}
885 * @stability stable
886 * @since 1.0.0
887 */
888 import type { Buffer } from "node:buffer"
889
890 /**
891 * Creates a value.
892 *
893 * @stability stable
894 * @category constructors
895 * @since 1.0.0
896 */
897 export const makeValue = () => 1
898 `
899 )
900 const model = extractJSDocsSync({
901 cwd,
902 tsconfig: "tsconfig.json",
903 include: ["src/**/*.ts"],
904 output: ".data/jsdocs.json"
905 })
906 assert.strictEqual(model.files[0]?.moduleJSDoc?.raw.includes("The Foo module provides helpers"), true)
907 assert.deepStrictEqual(model.files[0]?.diagnostics, [])
908 })
909
910 it("does not treat the first exported declaration JSDoc as module JSDoc", () => {
911 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
912 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
913 fs.writeFileSync(
914 path.join(cwd, "tsconfig.json"),
915 JSON.stringify({
916 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
917 include: ["src/**/*.ts"]
918 })
919 )
920 fs.writeFileSync(
921 path.join(cwd, "package.json"),
922 JSON.stringify({
923 name: "@effect/sample",
924 type: "module",
925 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
926 })
927 )
928 fs.writeFileSync(
929 path.join(cwd, "src/index.ts"),
930 `/**
931 * @stability stable
932 * @since 1.0.0
933 */
934 export * as Foo from "./Foo.ts"\n`
935 )
936 fs.writeFileSync(
937 path.join(cwd, "src/Foo.ts"),
938 `/**
939 * Creates a value.
940 *
941 * @stability stable
942 * @category constructors
943 * @since 1.0.0
944 */
945 export const makeValue = () => 1
946 `
947 )
948 const model = extractJSDocsSync({
949 cwd,
950 tsconfig: "tsconfig.json",
951 include: ["src/**/*.ts"],
952 output: ".data/jsdocs.json"
953 })
954 assert.strictEqual(model.files[0]?.moduleJSDoc, undefined)
955 assert.deepStrictEqual(model.files[0]?.diagnostics, [])
956 })
957
958 it("flags inline links that TypeScript does not bind", () => {
959 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
960 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
961 fs.writeFileSync(
962 path.join(cwd, "tsconfig.json"),
963 JSON.stringify({
964 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
965 include: ["src/**/*.ts"]
966 })
967 )
968 fs.writeFileSync(
969 path.join(cwd, "package.json"),
970 JSON.stringify({
971 name: "@effect/sample",
972 type: "module",
973 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
974 })
975 )
976 fs.writeFileSync(
977 path.join(cwd, "src/index.ts"),
978 `/**
979 * @stability stable
980 * @since 1.0.0
981 */
982 export * as Foo from "./Foo.ts"\n`
983 )
984 fs.writeFileSync(path.join(cwd, "src/Schema.ts"), `export {}\n`)
985 fs.writeFileSync(
986 path.join(cwd, "src/Foo.ts"),
987 `/**
988 * Creates a value with the {@link Schema} module.
989 *
990 * @stability stable
991 * @category constructors
992 * @since 1.0.0
993 */
994 export const makeValue = () => 1
995 `
996 )
997 const model = extractJSDocsSync({
998 cwd,
999 tsconfig: "tsconfig.json",
1000 include: ["src/**/*.ts"],
1001 output: ".data/jsdocs.json"
1002 })
1003 assert.deepStrictEqual(
1004 model.files[0]?.diagnostics.map((diagnostic) => diagnostic.code),
1005 ["unresolved-link"]
1006 )
1007 assert.deepStrictEqual(
1008 model.files[0]?.diagnostics.map((diagnostic) => diagnostic.message),
1009 ["Unresolved JSDoc inline link: {@link Schema}"]
1010 )
1011 })
1012
1013 it("flags module JSDoc tag, example, and public @see diagnostics", () => {
1014 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
1015 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
1016 fs.writeFileSync(
1017 path.join(cwd, "tsconfig.json"),
1018 JSON.stringify({
1019 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
1020 include: ["src/**/*.ts"]
1021 })
1022 )
1023 fs.writeFileSync(
1024 path.join(cwd, "package.json"),
1025 JSON.stringify({
1026 name: "@effect/sample",
1027 type: "module",
1028 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
1029 })
1030 )
1031 fs.writeFileSync(
1032 path.join(cwd, "src/index.ts"),
1033 `/**
1034 * @stability stable
1035 * @since 1.0.0
1036 */
1037 export * as Foo from "./Foo.ts"\n`
1038 )
1039 fs.writeFileSync(
1040 path.join(cwd, "src/Foo.ts"),
1041 `/**
1042 * The Foo module provides helpers.
1043 *
1044 * \`\`\`ts
1045 * const value = 1
1046 * \`\`\`
1047 *
1048 * @see {@link Hidden}
1049 * @stability stable
1050 */
1051 import type { Buffer } from "node:buffer"
1052
1053 class Hidden {}
1054
1055 /**
1056 * Creates a value.
1057 *
1058 * @stability stable
1059 * @category constructors
1060 * @since 1.0.0
1061 */
1062 export const makeValue = () => 1
1063 `
1064 )
1065 const model = extractJSDocsSync({
1066 cwd,
1067 tsconfig: "tsconfig.json",
1068 include: ["src/**/*.ts"],
1069 output: ".data/jsdocs.json"
1070 })
1071 assert.deepStrictEqual(
1072 model.files[0]?.diagnostics.map((diagnostic) => diagnostic.code).sort(),
1073 ["loose-ts-fence", "missing-tag", "public-see-target"].sort()
1074 )
1075 assert.strictEqual(model.files[0]?.moduleJSDoc?.raw.includes("The Foo module provides helpers"), true)
1076 })
1077
1078 it("flags @see links to targets without public JSDoc", () => {
1079 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
1080 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
1081 fs.writeFileSync(
1082 path.join(cwd, "tsconfig.json"),
1083 JSON.stringify({
1084 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
1085 include: ["src/**/*.ts"]
1086 })
1087 )
1088 fs.writeFileSync(
1089 path.join(cwd, "package.json"),
1090 JSON.stringify({
1091 name: "@effect/sample",
1092 type: "module",
1093 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
1094 })
1095 )
1096 fs.writeFileSync(
1097 path.join(cwd, "src/index.ts"),
1098 `/**
1099 * @stability stable
1100 * @since 1.0.0
1101 */
1102 export * as Foo from "./Foo.ts"\n`
1103 )
1104 fs.writeFileSync(
1105 path.join(cwd, "src/Foo.ts"),
1106 `/**
1107 * A documented container.
1108 *
1109 * @stability stable
1110 * @category models
1111 * @since 1.0.0
1112 */
1113 export interface Box {
1114 documented: string
1115 hidden: string
1116 }
1117
1118 /**
1119 * Uses the hidden member.
1120 *
1121 * @see {@link Box.hidden}
1122 * @stability stable
1123 * @category constructors
1124 * @since 1.0.0
1125 */
1126 export const useHidden = () => undefined
1127 `
1128 )
1129 const model = extractJSDocsSync({
1130 cwd,
1131 tsconfig: "tsconfig.json",
1132 include: ["src/**/*.ts"],
1133 output: ".data/jsdocs.json"
1134 })
1135 assert.deepStrictEqual(
1136 model.files[0]?.diagnostics.map((diagnostic) => diagnostic.code),
1137 ["undocumented-see-target"]
1138 )
1139 assert.deepStrictEqual(model.files[0]?.imports?.barrel, {
1140 type: "namespace",
1141 module: "@effect/sample",
1142 name: "Foo"
1143 })
1144 })
1145
1146 it("resolves @see links through TypeScript symbols before local-name lookup", () => {
1147 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
1148 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
1149 fs.writeFileSync(
1150 path.join(cwd, "tsconfig.json"),
1151 JSON.stringify({
1152 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
1153 include: ["src/**/*.ts"]
1154 })
1155 )
1156 fs.writeFileSync(
1157 path.join(cwd, "package.json"),
1158 JSON.stringify({
1159 name: "@effect/sample",
1160 type: "module",
1161 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
1162 })
1163 )
1164 fs.writeFileSync(
1165 path.join(cwd, "src/index.ts"),
1166 `/**
1167 * @stability stable
1168 * @since 1.0.0
1169 */
1170 export * as Eq from "./Eq.ts"\n/**
1171 * @stability stable
1172 * @since 1.0.0
1173 */
1174 export * as Ordering from "./Ordering.ts"\n/**
1175 * @stability stable
1176 * @since 1.0.0
1177 */
1178 export * as Reducer from "./Reducer.ts"\n`
1179 )
1180 fs.writeFileSync(
1181 path.join(cwd, "src/Reducer.ts"),
1182 `/**
1183 * A reusable reducer.
1184 *
1185 * @stability stable
1186 * @category models
1187 * @since 1.0.0
1188 */
1189 export interface Reducer {
1190 /**
1191 * Combines two values.
1192 */
1193 combine: string
1194 }
1195 `
1196 )
1197 fs.writeFileSync(
1198 path.join(cwd, "src/Ordering.ts"),
1199 `/**
1200 * Ordering reducer value.
1201 *
1202 * @stability stable
1203 * @category constants
1204 * @since 1.0.0
1205 */
1206 export const Reducer = "ordering"
1207 `
1208 )
1209 fs.writeFileSync(
1210 path.join(cwd, "src/Eq.ts"),
1211 `import * as Reducer from "./Reducer.ts"
1212
1213 /**
1214 * Creates an equivalence reducer.
1215 *
1216 * @see {@link Reducer}
1217 * @stability stable
1218 * @category constructors
1219 * @since 1.0.0
1220 */
1221 export const makeReducer = () => Reducer
1222 `
1223 )
1224 const model = extractJSDocsSync({
1225 cwd,
1226 tsconfig: "tsconfig.json",
1227 include: ["src/**/*.ts"],
1228 output: ".data/jsdocs.json"
1229 })
1230 const makeReducer = model.apis.find((api) => api.apiFqn === "@effect/sample/Eq.makeReducer")
1231 const link = makeReducer?.see[0]?.links[0]
1232 assert.deepStrictEqual(model.files.flatMap((file) => file.diagnostics), [])
1233 assert.deepStrictEqual(link?.resolution, {
1234 _tag: "Resolved",
1235 apiId: "root-declaration:type:@effect/sample/Reducer.Reducer",
1236 apiFqn: "@effect/sample/Reducer.Reducer"
1237 })
1238 })
1239
1240 it("flags @see links to targets outside the public JSDoc API model", () => {
1241 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
1242 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
1243 fs.writeFileSync(
1244 path.join(cwd, "tsconfig.json"),
1245 JSON.stringify({
1246 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
1247 include: ["src/**/*.ts"]
1248 })
1249 )
1250 fs.writeFileSync(
1251 path.join(cwd, "package.json"),
1252 JSON.stringify({
1253 name: "@effect/sample",
1254 type: "module",
1255 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
1256 })
1257 )
1258 fs.writeFileSync(
1259 path.join(cwd, "src/index.ts"),
1260 `/**
1261 * @stability stable
1262 * @since 1.0.0
1263 */
1264 export * as Foo from "./Foo.ts"\n`
1265 )
1266 fs.writeFileSync(
1267 path.join(cwd, "src/Foo.ts"),
1268 `/**
1269 * Private helper.
1270 *
1271 * @stability stable
1272 * @category models
1273 * @since 1.0.0
1274 */
1275 class Hidden {}
1276
1277 /**
1278 * Uses a hidden helper.
1279 *
1280 * @see {@link Hidden}
1281 * @stability stable
1282 * @category constructors
1283 * @since 1.0.0
1284 */
1285 export const useHidden = () => Hidden
1286 `
1287 )
1288 const model = extractJSDocsSync({
1289 cwd,
1290 tsconfig: "tsconfig.json",
1291 include: ["src/**/*.ts"],
1292 output: ".data/jsdocs.json"
1293 })
1294 assert.deepStrictEqual(
1295 model.files[0]?.diagnostics.map((diagnostic) => diagnostic.code),
1296 ["public-see-target"]
1297 )
1298 assert.deepStrictEqual(
1299 model.files[0]?.diagnostics.map((diagnostic) => diagnostic.message),
1300 [
1301 "@see link {@link Hidden} does not resolve to a public JSDoc API. Check that the target is exported and has valid public JSDoc."
1302 ]
1303 )
1304 })
1305
1306 it("keeps valid APIs from files with diagnostics for @see resolution", () => {
1307 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
1308 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
1309 fs.writeFileSync(
1310 path.join(cwd, "tsconfig.json"),
1311 JSON.stringify({
1312 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
1313 include: ["src/**/*.ts"]
1314 })
1315 )
1316 fs.writeFileSync(
1317 path.join(cwd, "package.json"),
1318 JSON.stringify({
1319 name: "@effect/sample",
1320 type: "module",
1321 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
1322 })
1323 )
1324 fs.writeFileSync(
1325 path.join(cwd, "src/index.ts"),
1326 `/**
1327 * @stability stable
1328 * @since 1.0.0
1329 */
1330 export * as Bar from "./Bar.ts"\n/**
1331 * @stability stable
1332 * @since 1.0.0
1333 */
1334 export * as Foo from "./Foo.ts"\n`
1335 )
1336 fs.writeFileSync(
1337 path.join(cwd, "src/Foo.ts"),
1338 `/**
1339 * Target value.
1340 *
1341 * @stability stable
1342 * @category constants
1343 * @since 1.0.0
1344 */
1345 export const Target = "target"
1346
1347 /**
1348 * Broken value.
1349 *
1350 * **Example**
1351 *
1352 * \`\`\`ts
1353 * const value = "broken"
1354 * \`\`\`
1355 *
1356 * @stability stable
1357 * @category constants
1358 * @since 1.0.0
1359 */
1360 export const Broken = "broken"
1361 `
1362 )
1363 fs.writeFileSync(
1364 path.join(cwd, "src/Bar.ts"),
1365 `import * as Foo from "./Foo.ts"
1366
1367 /**
1368 * Uses the target value.
1369 *
1370 * @see {@link Foo.Target} for the target value
1371 * @stability stable
1372 * @category constants
1373 * @since 1.0.0
1374 */
1375 export const useTarget = () => Foo.Target
1376 `
1377 )
1378 const model = extractJSDocsSync({
1379 cwd,
1380 tsconfig: "tsconfig.json",
1381 include: ["src/**/*.ts"],
1382 output: ".data/jsdocs.json"
1383 })
1384 const foo = model.files.find((file) => file.file === "src/Foo.ts")
1385 const bar = model.files.find((file) => file.file === "src/Bar.ts")
1386 assert.deepStrictEqual(
1387 foo?.diagnostics.map((diagnostic) => diagnostic.code),
1388 ["malformed-example"]
1389 )
1390 assert.deepStrictEqual(bar?.diagnostics, [])
1391 assert.strictEqual(
1392 model.apis.some((api) => api.apiFqn === "@effect/sample/Foo.Target"),
1393 true
1394 )
1395 })
1396
1397 it("resolves @see links to aliased export specifiers", () => {
1398 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
1399 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
1400 fs.writeFileSync(
1401 path.join(cwd, "tsconfig.json"),
1402 JSON.stringify({
1403 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
1404 include: ["src/**/*.ts"]
1405 })
1406 )
1407 fs.writeFileSync(
1408 path.join(cwd, "package.json"),
1409 JSON.stringify({
1410 name: "@effect/sample",
1411 type: "module",
1412 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
1413 })
1414 )
1415 fs.writeFileSync(
1416 path.join(cwd, "src/index.ts"),
1417 `/**
1418 * @stability stable
1419 * @since 1.0.0
1420 */
1421 export * as Foo from "./Foo.ts"\n`
1422 )
1423 fs.writeFileSync(
1424 path.join(cwd, "src/Foo.ts"),
1425 `/**
1426 * @stability stable
1427 * @since 1.0.0
1428 */
1429 const Array_ = "array"
1430
1431 export {
1432 /**
1433 * Public array helper.
1434 *
1435 * @stability stable
1436 * @category constructors
1437 * @since 1.0.0
1438 */
1439 Array_ as Array
1440 }
1441
1442 /**
1443 * Public tuple helper.
1444 *
1445 * @see {@link Array_}
1446 * @see {@link Array}
1447 * @stability stable
1448 * @category constructors
1449 * @since 1.0.0
1450 */
1451 export const Tuple = Array
1452 `
1453 )
1454 const model = extractJSDocsSync({
1455 cwd,
1456 tsconfig: "tsconfig.json",
1457 include: ["src/**/*.ts"],
1458 output: ".data/jsdocs.json"
1459 })
1460 const tuple = model.apis.find((api) => api.apiFqn === "@effect/sample/Foo.Tuple")
1461 const links = tuple?.see.flatMap((tag) => tag.links) ?? []
1462 assert.deepStrictEqual(model.files.flatMap((file) => file.diagnostics), [])
1463 assert.deepStrictEqual(links.map((link) => link.resolution), [{
1464 _tag: "Resolved",
1465 apiId: "root-declaration:value:@effect/sample/Foo.Array",
1466 apiFqn: "@effect/sample/Foo.Array"
1467 }, {
1468 _tag: "Resolved",
1469 apiId: "root-declaration:value:@effect/sample/Foo.Array",
1470 apiFqn: "@effect/sample/Foo.Array"
1471 }])
1472 })
1473
1474 it("accepts @stability unstable on module, member, and namespace docs", () => {
1475 const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "jsdocs-"))
1476 fs.mkdirSync(path.join(cwd, "src"), { recursive: true })
1477 fs.writeFileSync(
1478 path.join(cwd, "tsconfig.json"),
1479 JSON.stringify({
1480 compilerOptions: { module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022" },
1481 include: ["src/**/*.ts"]
1482 })
1483 )
1484 fs.writeFileSync(
1485 path.join(cwd, "package.json"),
1486 JSON.stringify({
1487 name: "@effect/sample",
1488 type: "module",
1489 exports: { ".": "./src/index.ts", "./*": "./src/*.ts" }
1490 })
1491 )
1492 fs.writeFileSync(
1493 path.join(cwd, "src/index.ts"),
1494 `/**
1495 * @stability stable
1496 * @since 1.0.0
1497 */
1498 export * as Foo from "./Foo.ts"\n`
1499 )
1500 fs.writeFileSync(
1501 path.join(cwd, "src/Imported.ts"),
1502 `/**
1503 * Imported marker.
1504 *
1505 * @stability stable
1506 * @category models
1507 * @since 1.0.0
1508 */
1509 export interface Marker {
1510 readonly id: string
1511 }
1512 `
1513 )
1514 fs.writeFileSync(
1515 path.join(cwd, "src/Foo.ts"),
1516 `/**
1517 * Sample module.
1518 *
1519 * @stability unstable
1520 * @since 1.0.0
1521 */
1522 import type { Marker } from "./Imported.ts"
1523
1524 /**
1525 * A boxed value.
1526 *
1527 * @stability stable
1528 * @category models
1529 * @since 1.0.0
1530 */
1531 export interface Box {
1532 /**
1533 * The boxed text.
1534 *
1535 * @stability unstable
1536 * @since 1.0.0
1537 */
1538 readonly value: Marker["id"]
1539
1540 /**
1541 * The stable label.
1542 *
1543 * @since 1.0.0
1544 */
1545 readonly label: string
1546 }
1547
1548 /**
1549 * Groups boxed types.
1550 *
1551 * @stability unstable
1552 * @category models
1553 * @since 1.0.0
1554 */
1555 export declare namespace Group {
1556 /**
1557 * A grouped item.
1558 *
1559 * @stability unstable
1560 * @category models
1561 * @since 1.0.0
1562 */
1563 export interface Item {
1564 readonly id: string
1565 }
1566
1567 /**
1568 * A stable grouped item.
1569 *
1570 * @category models
1571 * @since 1.0.0
1572 */
1573 export interface StableItem {
1574 readonly id: string
1575 }
1576 }
1577
1578 /**
1579 * Groups stable types.
1580 *
1581 * @stability stable
1582 * @category models
1583 * @since 1.0.0
1584 */
1585 export declare namespace StableGroup {
1586 /**
1587 * A stable nested item.
1588 *
1589 * @category models
1590 * @since 1.0.0
1591 */
1592 export interface Item {
1593 readonly id: string
1594 }
1595 }
1596 `
1597 )
1598 const model = extractJSDocsSync({
1599 cwd,
1600 tsconfig: "tsconfig.json",
1601 include: ["src/**/*.ts"],
1602 output: ".data/jsdocs.json"
1603 })
1604 const foo = model.files.find((file) => file.file.endsWith("src/Foo.ts"))
1605 const stabilityByName = Object.fromEntries(
1606 model.apis
1607 .filter((api) => api.moduleName === "@effect/sample/Foo")
1608 .map((api) => [api.apiFqn, api.tags.stability])
1609 )
1610
1611 assert.deepStrictEqual(foo?.diagnostics ?? [], [])
1612 assert.match(foo?.moduleJSDoc?.raw ?? "", /@stability unstable/)
1613 assert.deepStrictEqual(stabilityByName, {
1614 "@effect/sample/Foo.Box": "stable",
1615 "@effect/sample/Foo.Box.value": "unstable",
1616 "@effect/sample/Foo.Box.label": "stable",
1617 "@effect/sample/Foo.Group": "unstable",
1618 "@effect/sample/Foo.Group.Item": "unstable",
1619 "@effect/sample/Foo.Group.StableItem": "stable",
1620 "@effect/sample/Foo.StableGroup": "stable",
1621 "@effect/sample/Foo.StableGroup.Item": "stable"
1622 })
1623 })
1624 })