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

main
ts 379 lines 12.4 KB
Raw
1 /**
2 * Loads and provides configuration for documentation generation.
3 *
4 * @since 0.6.0
5 */
6
7 import * as Array from "effect/Array"
8 import * as Config from "effect/Config"
9 import * as ConfigProvider from "effect/ConfigProvider"
10 import * as Context from "effect/Context"
11 import * as Effect from "effect/Effect"
12 import * as FileSystem from "effect/FileSystem"
13 import { pipe } from "effect/Function"
14 import * as Layer from "effect/Layer"
15 import * as Option from "effect/Option"
16 import * as Path from "effect/Path"
17 import * as Result from "effect/Result"
18 import * as Schema from "effect/Schema"
19 import * as tsconfck from "tsconfck"
20 import * as Domain from "./Domain.ts"
21 import { DocgenError } from "./Domain.ts"
22
23 /**
24 * Default GitHub Pages theme written to generated configuration.
25 *
26 * @category constants
27 * @since 0.6.0
28 */
29 export const DEFAULT_THEME = "mikearnaldi/just-the-docs"
30
31 const PACKAGE_JSON_FILE_NAME = "package.json"
32 const CONFIG_FILE_NAME = "docgen.json"
33
34 const compilerOptionsSchema = Schema.Union([
35 Schema.String,
36 Schema.Record(Schema.String, Schema.Unknown)
37 ])
38
39 /**
40 * Schema for docgen configuration files.
41 *
42 * @category schemas
43 * @since 0.6.0
44 */
45 export const ConfigurationSchema = Schema.Struct({
46 "$schema": Schema.optional(Schema.String),
47 projectHomepage: Schema.optional(Schema.String.annotate({
48 description: "Will link to the project homepage from the Auxiliary Links of the generated documentation."
49 })),
50 srcLink: Schema.optional(Schema.String.annotate({
51 description: "Will link to the project source code."
52 })),
53 srcDir: Schema.optional(Schema.String.annotate({
54 description: "The directory in which docgen will search for TypeScript files to parse.",
55 default: "src"
56 })),
57 outDir: Schema.optional(Schema.String.annotate({
58 description: "The directory to which docgen will generate its output markdown documents.",
59 default: "docs"
60 })),
61 theme: Schema.optional(Schema.String.annotate({
62 description: "The theme that docgen will specify should be used for GitHub Docs in the generated _config.yml file.",
63 default: DEFAULT_THEME
64 })),
65 enableSearch: Schema.optional(Schema.Boolean.annotate({
66 description: "Whether or not search should be enabled for GitHub Docs in the generated _config.yml file.",
67 default: true
68 })),
69 enforceDescriptions: Schema.optional(Schema.Boolean.annotate({
70 description: "Whether or not descriptions for each module export should be required.",
71 default: false
72 })),
73 enforceExamples: Schema.optional(Schema.Boolean.annotate({
74 description:
75 "Whether or not @example tags for each module export should be required. (Note: examples will not be enforced in module documentation)",
76 default: false
77 })),
78 enforceVersion: Schema.optional(Schema.Boolean.annotate({
79 description: "Whether or not @since tags for each module export should be required.",
80 default: true
81 })),
82 tscExecutable: Schema.optional(Schema.String.annotate({
83 description:
84 "The path to the TypeScript compiler executable that docgen should use when invoking the compiler programmatically.",
85 default: "tsc"
86 })),
87 runExamples: Schema.optional(Schema.Boolean.annotate({
88 description:
89 "Whether or not docgen should attempt to run example code snippets and include the output in the generated documentation.",
90 default: false
91 })),
92 exclude: Schema.optional(
93 Schema.Array(Schema.String).annotate({
94 description: "An array of glob strings specifying files that should be excluded from the documentation.",
95 default: []
96 })
97 ),
98 parseCompilerOptions: Schema.optional(compilerOptionsSchema.annotate({
99 description: "tsconfig for parsing options (or path to a tsconfig)",
100 default: {}
101 })),
102 examplesCompilerOptions: Schema.optional(compilerOptionsSchema.annotate({
103 description: "tsconfig for the examples options (or path to a tsconfig)",
104 default: {}
105 }))
106 }).annotate({ identifier: "ConfigurationSchema" })
107
108 /**
109 * Resolved configuration used by the docgen services.
110 *
111 * @category services
112 * @since 0.6.0
113 */
114 export interface ConfigurationShape {
115 readonly projectName: string
116 readonly projectHomepage: string
117 readonly srcLink: string
118 readonly srcDir: string
119 readonly outDir: string
120 readonly theme: string
121 readonly enableSearch: boolean
122 readonly enforceDescriptions: boolean
123 readonly enforceExamples: boolean
124 readonly enforceVersion: boolean
125 readonly tscExecutable: string
126 readonly runExamples: boolean
127 readonly exclude: ReadonlyArray<string>
128 readonly parseCompilerOptions: Record<string, unknown>
129 readonly examplesCompilerOptions: Record<string, unknown>
130 }
131
132 /**
133 * Service that provides resolved docgen configuration.
134 *
135 * @category services
136 * @since 0.6.0
137 */
138 export class Configuration
139 extends Context.Service<Configuration, ConfigurationShape>()("@effect/docgen/Configuration")
140 {}
141
142 /** @internal */
143 export const defaultCompilerOptions = {
144 noEmit: true,
145 strict: true,
146 skipLibCheck: true,
147 moduleResolution: "Bundler",
148 target: "ES2022",
149 lib: [
150 "ES2022",
151 "DOM"
152 ]
153 }
154
155 const readJsonFile = (
156 path: string
157 ): Effect.Effect<unknown, never, FileSystem.FileSystem> =>
158 Effect.gen(function*() {
159 const fs = yield* FileSystem.FileSystem
160 const content = yield* Effect.orDie(fs.readFileString(path))
161 return yield* pipe(
162 Effect.try({
163 try: () => JSON.parse(content),
164 catch: (error) => `[FileSystem] Unable to read and parse JSON file from '${path}': ${String(error)}`
165 }),
166 Effect.orDie
167 )
168 })
169
170 const validateJsonFile = <A, I>(
171 schema: Schema.Codec<A, I>,
172 path: string
173 ): Effect.Effect<A, never, FileSystem.FileSystem> =>
174 Effect.gen(function*() {
175 const content = yield* readJsonFile(path)
176 return yield* pipe(
177 Schema.decodeUnknownEffect(schema)(content),
178 Effect.mapError((error) =>
179 new DocgenError({
180 message: `[Configuration.validateJsonFile]\n${String(error)}`
181 })
182 ),
183 Effect.orDie
184 )
185 })
186
187 // TODO: this is invoked twice
188 const readDocgenConfig = (
189 path: string
190 ): Effect.Effect<Option.Option<Schema.Schema.Type<typeof ConfigurationSchema>>, never, FileSystem.FileSystem> => {
191 return Effect.gen(function*() {
192 const fs = yield* FileSystem.FileSystem
193 const exists = yield* Effect.orDie(fs.exists(path))
194 if (exists) {
195 const config = yield* validateJsonFile(ConfigurationSchema, path)
196 return Option.some(config)
197 } else {
198 return Option.none()
199 }
200 })
201 }
202
203 const readTSConfig = (fileName: string): Effect.Effect<
204 { readonly [x: string]: unknown },
205 never,
206 Path.Path | Domain.Process
207 > =>
208 Effect.gen(function*() {
209 const path = yield* Path.Path
210 const process = yield* Domain.Process
211 const cwd = yield* process.cwd
212 return yield* pipe(
213 Effect.tryPromise(() => tsconfck.parse(path.resolve(cwd, fileName))).pipe(
214 Effect.map(({ tsconfig }) => tsconfig.compilerOptions ?? defaultCompilerOptions),
215 Effect.mapError((error) =>
216 new DocgenError({
217 message: `[Configuration.readTSConfig] Failed to read TSConfig file\n${String(error)}`
218 })
219 ),
220 Effect.orDie
221 )
222 )
223 })
224
225 const loadCompilerOptions = (configKey: string) =>
226 Config.String(configKey).pipe(
227 Effect.flatMap((config) =>
228 Schema.decodeUnknownEffect(JsonRecordSchema)(config).pipe(Effect.orElseSucceed(() => config))
229 )
230 )
231
232 const resolveCompilerOptions = (
233 configKey: string,
234 fromCLI: Option.Option<string | Record<string, unknown>>,
235 fromDocgenJson: Option.Option<string | Record<string, unknown>>
236 ): Effect.Effect<{ readonly [x: string]: unknown }, never, Path.Path | Domain.Process> => {
237 const fromConfigProvider = loadCompilerOptions(configKey)
238 return Effect.gen(function*() {
239 let config: string | Record<string, unknown>
240 if (Option.isSome(fromCLI)) {
241 config = fromCLI.value
242 } else {
243 const provided = yield* Effect.result(fromConfigProvider)
244 if (Result.isSuccess(provided)) {
245 config = provided.success
246 } else if (Option.isSome(fromDocgenJson)) {
247 config = fromDocgenJson.value
248 } else {
249 config = defaultCompilerOptions
250 }
251 }
252 return typeof config === "string" ? yield* readTSConfig(config) : config
253 })
254 }
255
256 const JsonRecordSchema = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown))
257
258 const PackageJsonSchema = Schema.Struct({
259 name: Schema.String,
260 homepage: Schema.String
261 })
262
263 /** @internal */
264 export const load = Effect.fnUntraced(function*(args: {
265 readonly projectHomepage: Option.Option<string>
266 readonly srcLink: Option.Option<string>
267 readonly srcDir: string
268 readonly outDir: string
269 readonly theme: string
270 readonly enableSearch: boolean
271 readonly enforceDescriptions: boolean
272 readonly enforceExamples: boolean
273 readonly enforceVersion: boolean
274 readonly runExamples: boolean
275 readonly exclude: ReadonlyArray<string>
276 readonly parseCompilerOptions: Option.Option<string | Record<string, unknown>>
277 readonly examplesCompilerOptions: Option.Option<string | Record<string, unknown>>
278 }) {
279 // Extract the requisite services
280 const process = yield* Domain.Process
281 const cwd = yield* process.cwd
282 const path = yield* Path.Path
283
284 // Read and parse the required fields from the `package.json`
285 const packageJsonPath = path.join(cwd, PACKAGE_JSON_FILE_NAME)
286 const packageJson = yield* validateJsonFile(PackageJsonSchema, packageJsonPath)
287 const projectName = packageJson.name
288 const projectHomepage = Option.getOrElse(args.projectHomepage, () => packageJson.homepage)
289 const srcLink = Option.getOrElse(args.srcLink, () => `${projectHomepage}/blob/main/src/`)
290
291 // Read the `docgen.json` configuration file to gain access to the TypeScript
292 // configuration options
293 const configPath = path.join(cwd, CONFIG_FILE_NAME)
294 const config = yield* readDocgenConfig(configPath)
295
296 // Resolve the excluded files
297 const exclude = yield* Array.match(args.exclude, {
298 onEmpty: () =>
299 Effect.result(Config.Array(Schema.String, "exclude")).pipe(
300 Effect.map((configured) =>
301 Result.isSuccess(configured)
302 ? configured.success
303 : Option.match(config, {
304 onNone: () => Array.empty<string>(),
305 onSome: ({ exclude }) => exclude || Array.empty<string>()
306 })
307 )
308 ),
309 onNonEmpty: (exclude) => Effect.succeed(exclude)
310 })
311
312 // Resolve the TypeScript configuration options
313 const examplesCompilerOptions = yield* resolveCompilerOptions(
314 "examplesCompilerOptions",
315 args.examplesCompilerOptions,
316 Option.flatMap(config, (config) => Option.fromNullishOr(config.examplesCompilerOptions))
317 )
318 const parseCompilerOptions = yield* resolveCompilerOptions(
319 "parseCompilerOptions",
320 args.parseCompilerOptions,
321 Option.flatMap(config, (config) => Option.fromNullishOr(config.parseCompilerOptions))
322 )
323
324 const srcDir = config.pipe(
325 Option.flatMapNullishOr((config) => config.srcDir),
326 Option.getOrElse(() => args.srcDir)
327 )
328
329 const outDir = config.pipe(
330 Option.flatMapNullishOr((config) => config.outDir),
331 Option.getOrElse(() => args.outDir)
332 )
333
334 const runExamples = config.pipe(
335 Option.flatMapNullishOr((config) => config.runExamples),
336 Option.getOrElse(() => args.runExamples)
337 )
338
339 const tscExecutable = config.pipe(
340 Option.flatMapNullishOr((config) => config.tscExecutable),
341 Option.getOrElse(() => "tsc")
342 )
343
344 return Configuration.of({
345 ...args,
346 srcDir,
347 outDir,
348 projectName,
349 projectHomepage,
350 srcLink,
351 exclude,
352 examplesCompilerOptions,
353 parseCompilerOptions,
354 runExamples,
355 tscExecutable
356 })
357 })
358
359 /** @internal */
360 export const configProviderLayer = Layer.effect(ConfigProvider.ConfigProvider)(Effect.gen(function*() {
361 // Extract the requisite services
362 const process = yield* Domain.Process
363 const cwd = yield* process.cwd
364 const env = yield* process.env
365 const path = yield* Path.Path
366 // Attempt to load the `docgen.json` configuration file
367 const configPath = path.join(cwd, CONFIG_FILE_NAME)
368 const maybeConfig = yield* readDocgenConfig(configPath)
369 // Construct a config provider for the environment
370 const fromEnv = ConfigProvider.fromEnv({ env }).pipe(
371 ConfigProvider.nested("DOCGEN"),
372 ConfigProvider.constantCase
373 )
374 // Construct a config provider for the `docgen.json` file
375 const fromDocgenJson = ConfigProvider.fromUnknown(Option.getOrElse(maybeConfig, () => ({})))
376 // Prefer the environment over the `docgen.json` file
377 const provider = fromEnv.pipe(ConfigProvider.orElse(fromDocgenJson))
378 return provider
379 }))