@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 734 lines 20.5 KB
Raw
1 /**
2 * Parses TypeScript declarations and JSDoc into docgen models.
3 *
4 * @since 0.6.0
5 */
6 import * as doctrine from "doctrine"
7 import * as Array from "effect/Array"
8 import * as Context from "effect/Context"
9 import * as Effect from "effect/Effect"
10 import { pipe } from "effect/Function"
11 import * as Option from "effect/Option"
12 import * as Path from "effect/Path"
13 import * as Record from "effect/Record"
14 import * as String from "effect/String"
15 import * as ast from "ts-morph"
16 import * as Configuration from "./Configuration.ts"
17 import * as Domain from "./Domain.ts"
18
19 /**
20 * Source file and path currently being parsed.
21 *
22 * @category services
23 * @since 0.6.0
24 */
25 export interface SourceShape {
26 readonly path: Array.NonEmptyReadonlyArray<string>
27 readonly sourceFile: ast.SourceFile
28 }
29
30 /** @internal */
31 export class Source extends Context.Service<Source, SourceShape>()("@effect/docgen/Source") {}
32
33 const sortModulesByPath: <A extends Domain.Module>(self: Iterable<A>) => Array<A> = Array
34 .sort(Domain.ByPath)
35
36 const getJSDocText: (jsdocs: ReadonlyArray<ast.JSDoc>) => string = Array.matchRight({
37 onEmpty: () => "",
38 onNonEmpty: (_, last) => last.getText()
39 })
40
41 const getDocComment = (ranges: ReadonlyArray<ast.CommentRange>): Option.Option<ast.CommentRange> =>
42 pipe(
43 ranges,
44 Array.filter((range) => range.getText().startsWith("/**")),
45 Array.last
46 )
47
48 class Comment {
49 readonly description: string | undefined
50 readonly tags: Record<string, ReadonlyArray<string> | undefined>
51 constructor(
52 description: string | undefined,
53 tags: Record<string, ReadonlyArray<string> | undefined>
54 ) {
55 this.description = description
56 this.tags = tags
57 }
58 }
59
60 /**
61 * @internal
62 */
63 export const parseComment = (text: string): Comment => {
64 const annotation: doctrine.Annotation = doctrine.parse(text, {
65 unwrap: true
66 })
67
68 const description = pipe(
69 Option.fromNullishOr(annotation.description),
70 Option.map((s) => s.trim()),
71 Option.filter(String.isNonEmpty),
72 Option.getOrUndefined
73 )
74
75 const tags = pipe(
76 annotation.tags,
77 Array.groupBy((tag) => tag.title),
78 Record.map((values) =>
79 Array.map(values, (tag) =>
80 pipe(
81 Option.fromNullishOr(tag.description),
82 Option.map(String.trim),
83 Option.getOrElse(() => "")
84 ))
85 )
86 )
87
88 return { description, tags }
89 }
90
91 const isVariableDeclarationList = (
92 u: ast.VariableDeclarationList | ast.CatchClause
93 ): u is ast.VariableDeclarationList => u.getKind() === ast.ts.SyntaxKind.VariableDeclarationList
94
95 const isVariableStatement = (
96 u:
97 | ast.VariableStatement
98 | ast.ForStatement
99 | ast.ForOfStatement
100 | ast.ForInStatement
101 ): u is ast.VariableStatement => u.getKind() === ast.ts.SyntaxKind.VariableStatement
102
103 const parseDoc = (text: string) => {
104 const comment = parseComment(text)
105 return new Domain.Doc(
106 comment.description,
107 comment.tags["since"] ?? [],
108 comment.tags["deprecated"] ?? [],
109 comment.tags["example"] ?? [],
110 comment.tags["category"] ?? [],
111 comment.tags["throws"] ?? [],
112 comment.tags["see"] ?? [],
113 comment.tags
114 )
115 }
116
117 const shouldIgnore = (doc: Domain.Doc): boolean => {
118 return Record.has(doc.tags, "internal") || Record.has(doc.tags, "ignore")
119 }
120
121 const parseInterfaceDeclaration = Effect.fnUntraced(function*(id: ast.InterfaceDeclaration) {
122 const doc = parseDoc(getJSDocText(id.getJsDocs()))
123 if (shouldIgnore(doc)) {
124 return []
125 }
126 const name = id.getName()
127 const signature = id.getText()
128 const position = yield* parsePosition(id)
129 return [
130 new Domain.Interface(
131 name,
132 doc,
133 signature,
134 position
135 )
136 ]
137 })
138
139 const parseInterfaceDeclarations = (interfaces: ReadonlyArray<ast.InterfaceDeclaration>) => {
140 const exportedInterfaces = Array.filter(
141 interfaces,
142 (id) => id.isExported()
143 )
144 return Effect.forEach(exportedInterfaces, parseInterfaceDeclaration).pipe(Effect.map(Array.flatten))
145 }
146
147 /**
148 * Parses exported interfaces from the current source file.
149 *
150 * @category parsing
151 * @since 0.6.0
152 */
153 export const parseInterfaces = Effect.flatMap(
154 Source,
155 (source) => parseInterfaceDeclarations(source.sourceFile.getInterfaces())
156 )
157
158 const getTypeText = (node: ast.Node) =>
159 node.getType().getText(
160 node,
161 ast.ts.TypeFormatFlags.NoTruncation
162 | ast.ts.TypeFormatFlags.WriteArrayAsGenericType
163 | ast.ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope
164 | ast.ts.TypeFormatFlags.NoTypeReduction
165 | ast.ts.TypeFormatFlags.AllowUniqueESSymbolType
166 | ast.ts.TypeFormatFlags.WriteArrowStyleSignature
167 )
168
169 const parseType = (node: ast.Node) => {
170 let text = getTypeText(node)
171 for (const property of node.getDescendantsOfKind(ast.ts.SyntaxKind.PropertySignature)) {
172 if (!shouldIgnore(parseDoc(getJSDocText(property.getJsDocs())))) continue
173 const readonly = property.getFirstModifierByKind(ast.ts.SyntaxKind.ReadonlyKeyword) ? "readonly " : ""
174 const optional = property.hasQuestionToken() ? "?" : ""
175 const type = property.getTypeNode()?.getText() ?? getTypeText(property)
176 const signature = `${readonly}${property.getName()}${optional}: ${type}`
177 text = text
178 .replaceAll(`; ${signature}`, "")
179 .replaceAll(`${signature}; `, "")
180 .replaceAll(signature, "")
181 }
182 return text
183 }
184
185 const getFunctionDeclarationJSDocs = (fd: ast.FunctionDeclaration): Array<ast.JSDoc> =>
186 Array.matchLeft(fd.getOverloads(), {
187 onEmpty: () => fd.getJsDocs(),
188 onNonEmpty: (firstOverload) => firstOverload.getJsDocs()
189 })
190
191 const parsePosition = (node: ast.Node): Effect.Effect<Domain.Position, never, Source> => {
192 return Effect.gen(function*() {
193 const source = yield* Source
194 const startPos = node.getStart()
195 const position = source.sourceFile.getLineAndColumnAtPos(startPos)
196 return position
197 })
198 }
199
200 const parseFunctionDeclaration = Effect.fnUntraced(function*(fd: ast.FunctionDeclaration) {
201 const doc = parseDoc(getJSDocText(getFunctionDeclarationJSDocs(fd)))
202 if (shouldIgnore(doc)) {
203 return []
204 }
205 const name = fd.getName()
206 const type = parseType(fd)
207 const signature = `declare const ${name}: ${type}`
208 const position = yield* parsePosition(fd)
209 return [
210 new Domain.Function(
211 name ?? "",
212 doc,
213 signature,
214 position
215 )
216 ]
217 })
218
219 const parseFunctionVariableDeclaration = Effect.fnUntraced(function*(vd: ast.VariableDeclaration) {
220 const vs: any = vd.getParent().getParent()
221 const doc = parseDoc(getJSDocText(vs.getJsDocs()))
222 if (shouldIgnore(doc)) {
223 return []
224 }
225 const name = vd.getName()
226 const type = parseType(vd)
227 const signature = `declare const ${name}: ${type}`
228 const startPos = vd.getStart()
229 const source = yield* Source
230 const position = source.sourceFile.getLineAndColumnAtPos(startPos)
231 return [
232 new Domain.Function(
233 name ?? "",
234 doc,
235 signature,
236 position
237 )
238 ]
239 })
240
241 const getFunctionDeclarations = Effect.gen(function*() {
242 const source = yield* Source
243 const functions = Array.filter(
244 source.sourceFile.getFunctions(),
245 (fd) => fd.isExported()
246 )
247 const arrows = pipe(
248 Array.filter(
249 source.sourceFile.getVariableDeclarations(),
250 (vd) => {
251 if (isVariableDeclarationList(vd.getParent())) {
252 const vs: any = vd.getParent().getParent()
253 if (isVariableStatement(vs)) {
254 return vs.isExported() &&
255 Option.fromNullishOr(vd.getInitializer()).pipe(
256 Option.filter((expr) => ast.Node.isFunctionLikeDeclaration(expr)),
257 Option.isSome
258 )
259 }
260 }
261 return false
262 }
263 )
264 )
265 return { functions, arrows }
266 })
267
268 /**
269 * Parses exported function declarations and function-valued variables.
270 *
271 * @category parsing
272 * @since 0.6.0
273 */
274 export const parseFunctions = Effect.gen(function*() {
275 const { arrows, functions } = yield* getFunctionDeclarations
276 const functionDeclarations = yield* Effect.forEach(functions, parseFunctionDeclaration).pipe(
277 Effect.map(Array.flatten)
278 )
279 const functionVariableDeclarations = yield* Effect.forEach(arrows, parseFunctionVariableDeclaration).pipe(
280 Effect.map(Array.flatten)
281 )
282 return [...functionDeclarations, ...functionVariableDeclarations]
283 })
284
285 const parseTypeAliasDeclaration = Effect.fnUntraced(function*(ta: ast.TypeAliasDeclaration) {
286 const doc = parseDoc(getJSDocText(ta.getJsDocs()))
287 if (shouldIgnore(doc)) {
288 return []
289 }
290 const name = ta.getName()
291 const typeParameters = ta.getTypeParameters().map((parameter) => parameter.getText()).join(", ")
292 const definition = ta.getTypeNode()?.getText()
293 const signature = `type ${name}${typeParameters.length > 0 ? `<${typeParameters}>` : ""} = ${definition}`
294 const position = yield* parsePosition(ta)
295 return [
296 new Domain.TypeAlias(
297 name,
298 doc,
299 signature,
300 position
301 )
302 ]
303 })
304
305 const parseTypeAliasDeclarations = (typeAliases: ReadonlyArray<ast.TypeAliasDeclaration>) => {
306 const exportedTypeAliases = Array.filter(
307 typeAliases,
308 (tad) => tad.isExported()
309 )
310 return Effect.forEach(exportedTypeAliases, parseTypeAliasDeclaration).pipe(Effect.map(Array.flatten))
311 }
312
313 /**
314 * Parses exported type aliases from the current source file.
315 *
316 * @category parsing
317 * @since 0.6.0
318 */
319 export const parseTypeAliases = Effect.flatMap(
320 Source,
321 (source) => parseTypeAliasDeclarations(source.sourceFile.getTypeAliases())
322 )
323
324 const parseConstantVariableDeclaration = Effect.fnUntraced(function*(vd: ast.VariableDeclaration) {
325 const vs: any = vd.getParent().getParent()
326 const doc = parseDoc(getJSDocText(vs.getJsDocs()))
327 if (shouldIgnore(doc)) {
328 return []
329 }
330 const name = vd.getName()
331 const type = parseType(vd)
332 const signature = `declare const ${name}: ${type}`
333 const position = yield* parsePosition(vd)
334 return [
335 new Domain.Constant(
336 name,
337 doc,
338 signature,
339 position
340 )
341 ]
342 })
343
344 /**
345 * Parses exported non-function constants from the current source file.
346 *
347 * @category parsing
348 * @since 0.6.0
349 */
350 export const parseConstants = Effect.gen(function*() {
351 const source = yield* Source
352 const variableDeclarations = pipe(
353 Array.filter(
354 source.sourceFile.getVariableDeclarations(),
355 (vd) => {
356 if (isVariableDeclarationList(vd.getParent())) {
357 const vs: any = vd.getParent().getParent()
358 if (isVariableStatement(vs)) {
359 return vs.isExported() &&
360 Option.fromNullishOr(vd.getInitializer()).pipe(
361 Option.filter((expr) => !ast.Node.isFunctionLikeDeclaration(expr)),
362 Option.isSome
363 )
364 }
365 }
366 return false
367 }
368 )
369 )
370 return yield* Effect.forEach(variableDeclarations, parseConstantVariableDeclaration).pipe(
371 Effect.map(Array.flatten)
372 )
373 })
374
375 const parseExportSpecifier = Effect.fnUntraced(function*(es: ast.ExportSpecifier) {
376 const name = es.compilerNode.name.text
377 const type = parseType(es)
378 const oDocComment = getDocComment(es.getLeadingCommentRanges())
379 const doc = Option.isSome(oDocComment) ? parseDoc(oDocComment.value.getText()) : parseDoc("")
380 const signature = `declare const ${name}: ${type}`
381 const position = yield* parsePosition(es)
382 return new Domain.Export(
383 name,
384 doc,
385 signature,
386 position,
387 false
388 )
389 })
390
391 const parseExportStar = Effect.fnUntraced(function*(ed: ast.ExportDeclaration) {
392 const es = ed.getModuleSpecifier()!
393 const name = es.getText()
394 const namespace = ed.getNamespaceExport()?.getName()
395 const signature = `export *${namespace === undefined ? "" : ` as ${namespace}`} from ${name}`
396 const oDocComment = getDocComment(ed.getLeadingCommentRanges())
397 const doc = Option.isSome(oDocComment) ? parseDoc(oDocComment.value.getText()) : parseDoc("")
398 const position = yield* parsePosition(ed)
399 return new Domain.Export(
400 namespace ?? name,
401 doc.modifyDescription(
402 `Re-exports all named exports from the ${name} module${namespace === undefined ? "" : ` as \`${namespace}\``}.`
403 ),
404 signature,
405 position,
406 true
407 )
408 })
409
410 const parseNamedExports = (ed: ast.ExportDeclaration) => {
411 const namedExports = ed.getNamedExports()
412 if (namedExports.length === 0) {
413 if (ed.getModuleSpecifier() !== undefined) {
414 return parseExportStar(ed).pipe(Effect.map(Array.of))
415 }
416 return Effect.succeed([])
417 }
418 return Effect.forEach(namedExports, parseExportSpecifier)
419 }
420
421 /**
422 * Parses explicit export declarations from the current source file.
423 *
424 * @category parsing
425 * @since 0.6.0
426 */
427 export const parseExports = pipe(
428 Effect.map(Source, (source) => source.sourceFile.getExportDeclarations()),
429 Effect.flatMap((exportDeclarations) => Effect.forEach(exportDeclarations, parseNamedExports)),
430 Effect.map(Array.flatten)
431 )
432
433 const parseModuleDeclaration = (
434 ed: ast.ModuleDeclaration
435 ): Effect.Effect<Array<Domain.Namespace>, never, Source | Configuration.Configuration> => {
436 const doc = parseDoc(getJSDocText(ed.getJsDocs()))
437 if (shouldIgnore(doc)) {
438 return Effect.succeed([])
439 }
440 const name = ed.getName()
441 const getInterfaces = parseInterfaceDeclarations(ed.getInterfaces())
442 const getTypeAliases = parseTypeAliasDeclarations(ed.getTypeAliases())
443 const getNamespaces = parseModuleDeclarations(ed.getModules())
444 return Effect.gen(function*() {
445 const interfaces = yield* getInterfaces
446 const typeAliases = yield* getTypeAliases
447 const namespaces = yield* getNamespaces
448 const position = yield* parsePosition(ed)
449 return [
450 new Domain.Namespace(
451 name,
452 doc,
453 position,
454 interfaces,
455 typeAliases,
456 namespaces
457 )
458 ]
459 })
460 }
461
462 const parseModuleDeclarations = (namespaces: ReadonlyArray<ast.ModuleDeclaration>) => {
463 return Effect.forEach(
464 namespaces.filter((md) => md.isExported()),
465 parseModuleDeclaration
466 ).pipe(Effect.map(Array.flatten))
467 }
468
469 /**
470 * Parses exported namespaces from the current source file.
471 *
472 * @category parsing
473 * @since 0.6.0
474 */
475 export const parseNamespaces = Effect.gen(function*() {
476 const source = yield* Source
477 return yield* parseModuleDeclarations(source.sourceFile.getModules())
478 })
479
480 const getTypeParameters = (tps: ReadonlyArray<ast.TypeParameterDeclaration>): string =>
481 tps.length === 0 ? "" : `<${tps.map((p) => p.getName()).join(", ")}>`
482
483 const parseMethod = Effect.fnUntraced(function*(md: ast.MethodDeclaration) {
484 const name = md.getName()
485 const jsdocs = Array.matchLeft(md.getOverloads(), {
486 onEmpty: () => md.getJsDocs(),
487 onNonEmpty: (head) => head.getJsDocs()
488 })
489 const doc = parseDoc(getJSDocText(jsdocs))
490 if (shouldIgnore(doc)) {
491 return Option.none()
492 }
493 const type = parseType(md)
494 const signature = `declare const ${name}: ${type}`
495 const position = yield* parsePosition(md)
496 return Option.some(
497 new Domain.DocEntry(
498 name,
499 doc,
500 signature,
501 position
502 )
503 )
504 })
505
506 const parseProperty = Effect.fnUntraced(function*(pd: ast.PropertyDeclaration) {
507 const doc = parseDoc(getJSDocText(pd.getJsDocs()))
508 if (shouldIgnore(doc)) {
509 return []
510 }
511 const name = pd.getName()
512 const type = parseType(pd)
513 const readonly = pipe(
514 Option.fromNullishOr(pd.getFirstModifierByKind(ast.ts.SyntaxKind.ReadonlyKeyword)),
515 Option.match({
516 onNone: () => "",
517 onSome: () => "readonly "
518 })
519 )
520 const signature = `${readonly}${name}: ${type}`
521 const position = yield* parsePosition(pd)
522 return [
523 new Domain.DocEntry(
524 name,
525 doc,
526 signature,
527 position
528 )
529 ]
530 })
531
532 const parseProperties = (c: ast.ClassDeclaration) => {
533 const properties = Array.filter(
534 c.getProperties(),
535 (pd) =>
536 !pd.isStatic() && pipe(
537 pd.getFirstModifierByKind(ast.ts.SyntaxKind.PrivateKeyword),
538 Option.fromNullishOr,
539 Option.isNone
540 )
541 )
542 return Effect.forEach(properties, parseProperty).pipe(Effect.map(Array.flatten))
543 }
544
545 /**
546 * @internal
547 */
548 export const getConstructorDeclarationSignature = (
549 c: ast.ConstructorDeclaration
550 ): string =>
551 pipe(
552 Option.fromNullishOr(c.compilerNode.body),
553 Option.match({
554 onNone: () => c.getText(),
555 onSome: (body) => {
556 const end = body.getStart() - c.getStart() - 1
557 return c.getText().substring(0, end)
558 }
559 })
560 )
561
562 const getClassDeclarationSignature = (c: ast.ClassDeclaration) => {
563 const name = c.getName() ?? ""
564 return pipe(
565 Effect.succeed(getTypeParameters(c.getTypeParameters())),
566 Effect.map((typeParameters) =>
567 pipe(
568 c.getConstructors(),
569 Array.matchLeft({
570 onEmpty: () => `declare class ${name}${typeParameters}`,
571 onNonEmpty: (head) =>
572 `declare class ${name}${typeParameters} { ${
573 getConstructorDeclarationSignature(
574 head
575 )
576 } }`
577 })
578 )
579 )
580 )
581 }
582
583 const parseClass = Effect.fnUntraced(function*(c: ast.ClassDeclaration) {
584 const doc = parseDoc(getJSDocText(c.getJsDocs()))
585 if (shouldIgnore(doc)) {
586 return []
587 }
588 const name = c.getName() ?? ""
589 const signature = yield* getClassDeclarationSignature(c)
590 const methods = yield* pipe(
591 c.getInstanceMethods(),
592 Effect.forEach(parseMethod),
593 Effect.map(Array.getSomes)
594 )
595 const staticMethods = yield* pipe(
596 c.getStaticMethods(),
597 Effect.forEach(parseMethod),
598 Effect.map(Array.getSomes)
599 )
600 const properties = yield* parseProperties(c)
601 const position = yield* parsePosition(c)
602 return [
603 new Domain.Class(
604 name,
605 doc,
606 signature,
607 position,
608 methods,
609 staticMethods,
610 properties
611 )
612 ]
613 })
614
615 /**
616 * Parses exported classes and their documented members from the current source file.
617 *
618 * @category parsing
619 * @since 0.6.0
620 */
621 export const parseClasses = Effect.gen(function*() {
622 const source = yield* Source
623 const exportedClasses = source.sourceFile.getClasses().filter((cd) => cd.isExported())
624 return yield* Effect.forEach(exportedClasses, parseClass).pipe(Effect.map(Array.flatten))
625 })
626
627 /**
628 * @internal
629 */
630 export const parseModuleDocumentation = Effect.gen(function*() {
631 const source = yield* Source
632 const statements = source.sourceFile.getStatements()
633 const ofirstStatement = Array.head(statements)
634 if (Option.isSome(ofirstStatement)) {
635 const oDocComment = getDocComment(ofirstStatement.value.getLeadingCommentRanges())
636 if (Option.isSome(oDocComment)) {
637 return parseDoc(oDocComment.value.getText())
638 }
639 }
640 return parseDoc("")
641 })
642
643 /**
644 * Parses the current source file into a module documentation model.
645 *
646 * @category parsing
647 * @since 0.6.0
648 */
649 export const parseModule = Effect.gen(function*() {
650 const source = yield* Source
651 const doc = yield* parseModuleDocumentation
652 const interfaces = yield* parseInterfaces
653 const functions = yield* parseFunctions
654 const typeAliases = yield* parseTypeAliases
655 const classes = yield* parseClasses
656 const constants = yield* parseConstants
657 const exports = yield* parseExports
658 const namespaces = yield* parseNamespaces
659 const name = source.sourceFile.getBaseName()
660 return new Domain.Module(
661 source,
662 name,
663 doc,
664 source.path,
665 classes,
666 interfaces,
667 functions,
668 typeAliases,
669 constants,
670 exports,
671 namespaces
672 )
673 })
674
675 /**
676 * @internal
677 */
678 export const parseFile =
679 (project: ast.Project) =>
680 (file: Domain.File): Effect.Effect<Domain.Module, Array<string>, Configuration.Configuration | Path.Path> => {
681 return Effect.gen(function*() {
682 const path = yield* Path.Path
683 const sourceFile = project.getSourceFile(file.path)
684 const filePath = file.path.split(path.sep)
685 if (sourceFile !== undefined && Array.isArrayNonEmpty(filePath)) {
686 return yield* Effect.provideService(parseModule, Source, { sourceFile, path: filePath })
687 }
688 return yield* Effect.fail([`Unable to locate file: ${file.path}`])
689 })
690 }
691
692 const createProject = Effect.fnUntraced(function*(files: ReadonlyArray<Domain.File>) {
693 const config = yield* Configuration.Configuration
694 const process = yield* Domain.Process
695 const cwd = yield* process.cwd
696 // Convert the raw config into a format that TS/TS-Morph expects
697 const parsed = ast.ts.parseJsonConfigFileContent(
698 {
699 compilerOptions: {
700 strict: true,
701 moduleResolution: "node",
702 ...config.parseCompilerOptions
703 }
704 },
705 ast.ts.sys,
706 cwd
707 )
708
709 const options: ast.ProjectOptions = {
710 compilerOptions: parsed.options
711 }
712 const project = new ast.Project(options)
713 for (const file of files) {
714 project.addSourceFileAtPath(file.path)
715 }
716 return project
717 })
718
719 /**
720 * Parses source files into module documentation models sorted by path.
721 *
722 * @category parsing
723 * @since 0.6.0
724 */
725 export const parseFiles = (files: ReadonlyArray<Domain.File>) =>
726 createProject(files).pipe(
727 Effect.flatMap((project) =>
728 pipe(
729 files,
730 Effect.validate(parseFile(project)),
731 Effect.map(sortModulesByPath)
732 )
733 )
734 )