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

main
ts 284 lines 10.8 KB
Raw
1 import * as Configuration from "@effect/docgen/Configuration"
2 import * as Core from "@effect/docgen/Core"
3 import * as Domain from "@effect/docgen/Domain"
4 import * as Parser from "@effect/docgen/Parser"
5 import * as NodeServices from "@effect/platform-node/NodeServices"
6 import { assert, describe, it } from "@effect/vitest"
7 import * as Effect from "effect/Effect"
8 import * as FileSystem from "effect/FileSystem"
9 import * as Path from "effect/Path"
10 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner"
11 import * as Sink from "effect/Sink"
12 import * as Stream from "effect/Stream"
13 import * as path from "node:path"
14 import * as ast from "ts-morph"
15
16 const assertFencedCode = (
17 markdown: string,
18 expectedExamples: ReadonlyArray<string>,
19 expectedWarnings: ReadonlyArray<string>
20 ) => {
21 assert.deepStrictEqual(Core.extractFencedCode(markdown), [expectedExamples, expectedWarnings])
22 }
23
24 const assertExampleFiles = Effect.fnUntraced(
25 function*(source: string, expected: ReadonlyArray<string>, runExamples = true) {
26 const fs = yield* FileSystem.FileSystem
27 const path = yield* Path.Path
28 const cwd = yield* fs.makeTempDirectoryScoped()
29 const config: Configuration.ConfigurationShape = {
30 projectName: "docgen",
31 projectHomepage: "https://example.test",
32 srcLink: "https://example.test",
33 srcDir: path.relative(process.cwd(), path.join(cwd, "src")),
34 outDir: path.relative(process.cwd(), path.join(cwd, "docs")),
35 theme: Configuration.DEFAULT_THEME,
36 enableSearch: true,
37 enforceDescriptions: false,
38 enforceExamples: false,
39 enforceVersion: false,
40 tscExecutable: "tsc",
41 runExamples,
42 exclude: [],
43 parseCompilerOptions: {},
44 examplesCompilerOptions: Configuration.defaultCompilerOptions
45 }
46 yield* fs.makeDirectory(config.srcDir)
47 yield* fs.writeFileString(path.join(config.srcDir, "Box.ts"), source)
48
49 const commands: Array<string> = []
50 // Inspect the generated inputs without invoking a compiler or executing examples.
51 const spawner = ChildProcessSpawner.make((command) =>
52 Effect.gen(function*() {
53 if (command._tag !== "StandardCommand") return yield* Effect.die("Unexpected pipeline")
54 commands.push(command.command)
55 const directory = path.join(config.outDir, "examples")
56 const names = (yield* fs.readDirectory(directory))
57 .filter((name) => name.endsWith(".ts") && name !== "index.ts").sort()
58 const contents = yield* Effect.forEach(names, (name) => fs.readFileString(path.join(directory, name)))
59 assert.deepStrictEqual(contents.sort(), [...expected].sort())
60 const index = yield* fs.readFileString(path.join(directory, "index.ts"))
61 assert.deepStrictEqual(index.trim().split("\n").sort(), names.map((name) => `import './${name.slice(0, -3)}'`))
62 return ChildProcessSpawner.makeHandle({
63 pid: ChildProcessSpawner.ProcessId(1),
64 exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
65 isRunning: Effect.succeed(false),
66 kill: () => Effect.void,
67 stdin: Sink.drain,
68 stdout: Stream.empty,
69 stderr: Stream.empty,
70 all: Stream.empty,
71 getInputFd: () => Sink.drain,
72 getOutputFd: () => Stream.empty,
73 unref: Effect.succeed(Effect.void)
74 })
75 })
76 )
77 yield* Core.program.pipe(
78 Effect.provideService(Configuration.Configuration, config),
79 Effect.provideService(Domain.Process, {
80 cwd: Effect.succeed(process.cwd()),
81 platform: Effect.succeed(process.platform),
82 argv: Effect.succeed([]),
83 env: Effect.succeed({})
84 }),
85 Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner)
86 )
87 const executables = expected.length === 0 ? [] : runExamples ? ["tsc", "tsx"] : ["tsc"]
88 assert.deepStrictEqual(commands, executables.map((name) => process.platform === "win32" ? `${name}.cmd` : name))
89 },
90 Effect.provide(NodeServices.layer)
91 )
92
93 describe("Core", () => {
94 describe("class property examples", { timeout: 20_000 }, () => {
95 // These tests run the full docgen program (including ts-morph and Prettier) in parallel.
96 // Under Bun with other CI projects running, that can exceed Vitest's 5s default.
97 for (const runExamples of [true, false]) {
98 it.effect(`collects property-only examples with runExamples: ${runExamples}`, () =>
99 assertExampleFiles(
100 `export class Box {
101 /**
102 * @example
103 * ~~~ts
104 * const value = 1
105 * ~~~
106 */
107 readonly value = 1
108 }`,
109 ["const value = 1"],
110 runExamples
111 ))
112 }
113
114 it.effect("collects property descriptions and example tags alongside methods, excluding skipped fences", () =>
115 assertExampleFiles(
116 `export class Box {
117 /**
118 * ~~~ts
119 * const description = 1
120 * ~~~
121 * @example
122 * ~~~ts
123 * const first = 1
124 * ~~~
125 * @example
126 * ~~~ts
127 * const second = 2
128 * ~~~
129 * @example
130 * ~~~ts skip-type-checking
131 * const skipped: string = 1
132 * ~~~
133 */
134 readonly value = 1
135 /**
136 * @example
137 * ~~~ts
138 * const method = 3
139 * ~~~
140 */
141 read() { return this.value }
142 }`,
143 ["const description = 1", "const first = 1", "const second = 2", "const method = 3"]
144 ))
145
146 it.effect("does not request validation when all property examples are skipped", () =>
147 assertExampleFiles(
148 `export class Box {
149 /**
150 * @example
151 * ~~~ts skip-type-checking
152 * const skipped: string = 1
153 * ~~~
154 */
155 readonly value = 1
156 }`,
157 []
158 ))
159 })
160
161 // The first case initializes ts-morph and renders Markdown for three modules.
162 // Concurrent Bun CI projects can push that cold start beyond the 5s default.
163 describe("[internal] getModuleMarkdownFiles", { timeout: 20_000 }, () => {
164 for (const srcDir of [".", "src", "source/lib", path.resolve("source/lib"), process.cwd()]) {
165 it.effect(`generates distinct source-relative pages for ${srcDir}`, () =>
166 Effect.gen(function*() {
167 const project = new ast.Project({ useInMemoryFileSystem: true })
168 const sources = [
169 ["left/Shared.ts", "leftMarker"],
170 ["right/Shared.ts", "rightMarker"],
171 ["Flat.ts", "flatMarker"]
172 ] as const
173 const modules = yield* Effect.forEach(sources, ([relativePath, marker]) => {
174 const filePath = path.join(srcDir, relativePath)
175 const content = `/** @since 1.0.0 */\nexport const ${marker} = "${marker}"\n`
176 project.createSourceFile(filePath, content)
177 return Parser.parseFile(project)(new Domain.File(filePath, content))
178 })
179 const files = yield* Core.getModuleMarkdownFiles(modules)
180
181 assert.deepStrictEqual(files.map((file) => file.path), [
182 path.join("docs", "modules", "left", "Shared.ts.md"),
183 path.join("docs", "modules", "right", "Shared.ts.md"),
184 path.join("docs", "modules", "Flat.ts.md")
185 ])
186 for (const [index, file] of files.entries()) {
187 assert.deepStrictEqual(
188 sources.map(([, marker]) => marker).filter((marker) => file.content.includes(marker)),
189 [sources[index][1]]
190 )
191 assert.isTrue(file.isOverwriteable)
192 }
193 }).pipe(
194 Effect.provideService(Configuration.Configuration, {
195 projectName: "docgen",
196 projectHomepage: "https://example.com",
197 srcLink: "https://example.com/src",
198 srcDir,
199 outDir: "docs",
200 theme: Configuration.DEFAULT_THEME,
201 enableSearch: true,
202 enforceDescriptions: false,
203 enforceExamples: false,
204 enforceVersion: true,
205 runExamples: false,
206 tscExecutable: "tsc",
207 exclude: [],
208 parseCompilerOptions: {},
209 examplesCompilerOptions: {}
210 }),
211 Effect.provide(NodeServices.layer)
212 ))
213 }
214 })
215
216 it.effect("preserves a type alias name and declared type parameters", () => {
217 const sourceFile = new ast.Project({ useInMemoryFileSystem: true }).createSourceFile(
218 "Identity.ts",
219 `/**
220 * A boxed value.
221 *
222 * @since 1.0.0
223 */
224 export type Identity<A extends string = string> = A`
225 )
226
227 return Parser.parseTypeAliases.pipe(
228 Effect.provideService(Parser.Source, { path: ["Identity.ts"], sourceFile }),
229 Effect.map(([alias]) => assert.strictEqual(alias?.signature, "type Identity<A extends string = string> = A"))
230 )
231 })
232
233 describe("[internal] extractFencedCode", () => {
234 it("should extract fenced code blocks from markdown (backticks)", () => {
235 assertFencedCode("a\n\n```ts\nconst a = 1\n```\n\nb", ["const a = 1"], [])
236 })
237
238 it("should extract fenced code blocks from markdown (tildes)", () => {
239 assertFencedCode("a\n\n~~~ts\nconst a = 1\n~~~~\n\nb", ["const a = 1"], [])
240 })
241
242 it("should skip-type-checking (backticks)", () => {
243 assertFencedCode("a\n\n```ts skip-type-checking a=1\nconst a = 1\n```\n\nb", [], [])
244 })
245
246 it("should skip-type-checking (tildes)", () => {
247 assertFencedCode("a\n\n~~~ts skip-type-checking a=1\nconst a = 1\n~~~~\n\nb", [], [])
248 })
249
250 it("should handle metadata (backticks)", () => {
251 assertFencedCode("a\n\n```ts a=1\nconst a = 1\n```\n\nb", ["const a = 1"], [])
252 })
253
254 it("should handle metadata (tildes)", () => {
255 assertFencedCode("a\n\n~~~ts a=1\nconst a = 1\n~~~~\n\nb", ["const a = 1"], [])
256 })
257
258 it("should handle non closing fences (backticks)", () => {
259 assertFencedCode("a\n\n```ts\nconst a = 1", ["const a = 1"], [
260 "Code block does not have a matching closing fence:\na\n\n```ts\nconst a = 1"
261 ])
262 })
263
264 it("should handle non closing fences (tildes)", () => {
265 assertFencedCode("a\n\n~~~ts\nconst a = 1", ["const a = 1"], [
266 "Code block does not have a matching closing fence:\na\n\n~~~ts\nconst a = 1"
267 ])
268 })
269 })
270
271 describe("[internal] runCommand", () => {
272 it.effect("streams output without a maxBuffer limit", () =>
273 Effect.gen(function*() {
274 const size = 1024 * 1024 + 1
275 const result = yield* Core.runCommand("node", [
276 "-e",
277 `process.stdout.write("x".repeat(${size})); process.stderr.write("problem"); process.exitCode = 2`
278 ], false)
279 assert.strictEqual(result.stdout.length, size)
280 assert.strictEqual(result.stderr, "problem")
281 assert.strictEqual(result.exitCode, 2)
282 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)))
283 })
284 })