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

main
ts 244 lines 6.71 KB
Raw
1 /**
2 * Validates parsed documentation against the configured requirements.
3 *
4 * @since 0.6.0
5 */
6 import { codeFrameColumns } from "@babel/code-frame"
7 import * as Array from "effect/Array"
8 import * as Effect from "effect/Effect"
9 import * as Configuration from "./Configuration.ts"
10 import type * as Domain from "./Domain.ts"
11 import * as Parser from "./Parser.ts"
12
13 const makeError = (
14 source: Parser.SourceShape,
15 position: Domain.Position,
16 message: (filePath: string, frame: string) => string
17 ) => {
18 const location = { start: position }
19 const frame = codeFrameColumns(source.sourceFile.getFullText(), location)
20 return [message(source.sourceFile.getFilePath(), frame)]
21 }
22
23 type Entry = {
24 readonly doc: Domain.Doc
25 readonly position: Domain.Position
26 }
27
28 const checkEntry = Effect.fnUntraced(function*(model: Entry, options: {
29 readonly enforceVersion: boolean
30 }) {
31 const source = yield* Parser.Source
32 const config = yield* Configuration.Configuration
33
34 let errors: Array<string> = []
35
36 // description
37 if (config.enforceDescriptions) {
38 if (model.doc.description === undefined) {
39 errors = errors.concat(makeError(
40 source,
41 model.position,
42 (filePath, frame) => `Missing description in file ${filePath}:\n\n${frame}`
43 ))
44 }
45 }
46
47 // @example tags
48 if (config.enforceExamples) {
49 if (model.doc.examples.length === 0) {
50 errors = errors.concat(makeError(
51 source,
52 model.position,
53 (filePath, frame) => `Missing examples in file ${filePath}:\n\n${frame}`
54 ))
55 }
56 }
57
58 // @since tags
59 if (config.enforceVersion && options.enforceVersion !== false) {
60 const since = model.doc.since
61 if (since.length === 0) {
62 errors = errors.concat(makeError(
63 source,
64 model.position,
65 (filePath, frame) => `Missing \`@since\` tag in file ${filePath}:\n\n${frame}`
66 ))
67 }
68 }
69
70 return errors
71 })
72
73 function checkEntries(models: ReadonlyArray<Entry>, options: {
74 readonly enforceVersion: boolean
75 }) {
76 return Effect.forEach(models, (model) => checkEntry(model, options)).pipe(Effect.map(Array.flatten))
77 }
78
79 function checkFunction(model: Domain.Function) {
80 return checkEntry(model, {
81 enforceVersion: true
82 })
83 }
84
85 /**
86 * Validates documentation for function declarations.
87 *
88 * @category validation
89 * @since 0.6.0
90 */
91 export function checkFunctions(models: ReadonlyArray<Domain.Function>) {
92 return Effect.forEach(models, checkFunction).pipe(Effect.map(Array.flatten))
93 }
94
95 const checkClass = Effect.fnUntraced(function*(model: Domain.Class) {
96 const docErrors = yield* checkEntry(model, {
97 enforceVersion: true
98 })
99 const staticMethodsErrors = yield* checkEntries(model.staticMethods, {
100 enforceVersion: false
101 })
102 const methodsErrors = yield* checkEntries(model.methods, {
103 enforceVersion: false
104 })
105 const propertiesErrors = yield* checkEntries(model.properties, {
106 enforceVersion: false
107 })
108 return Array.flatten([docErrors, staticMethodsErrors, methodsErrors, propertiesErrors])
109 })
110
111 /**
112 * Validates documentation for class declarations and their documented members.
113 *
114 * @category validation
115 * @since 0.6.0
116 */
117 export function checkClasses(models: ReadonlyArray<Domain.Class>) {
118 return Effect.forEach(models, checkClass).pipe(Effect.map(Array.flatten))
119 }
120
121 function checkConstant(model: Domain.Constant) {
122 return checkEntry(model, {
123 enforceVersion: true
124 })
125 }
126
127 /**
128 * Validates documentation for constant declarations.
129 *
130 * @category validation
131 * @since 0.6.0
132 */
133 export function checkConstants(models: ReadonlyArray<Domain.Constant>) {
134 return Effect.forEach(models, checkConstant).pipe(Effect.map(Array.flatten))
135 }
136
137 function checkInterface(model: Domain.Interface) {
138 return checkEntry(model, {
139 enforceVersion: true
140 })
141 }
142
143 /**
144 * Validates documentation for interface declarations.
145 *
146 * @category validation
147 * @since 0.6.0
148 */
149 export function checkInterfaces(models: ReadonlyArray<Domain.Interface>) {
150 return Effect.forEach(models, checkInterface).pipe(Effect.map(Array.flatten))
151 }
152
153 function checkTypeAlias(model: Domain.TypeAlias) {
154 return checkEntry(model, {
155 enforceVersion: true
156 })
157 }
158
159 /**
160 * Validates documentation for type alias declarations.
161 *
162 * @category validation
163 * @since 0.6.0
164 */
165 export function checkTypeAliases(models: ReadonlyArray<Domain.TypeAlias>) {
166 return Effect.forEach(models, checkTypeAlias).pipe(Effect.map(Array.flatten))
167 }
168
169 function checkNamespace(
170 model: Domain.Namespace
171 ): Effect.Effect<Array<string>, never, Parser.Source | Configuration.Configuration> {
172 return Effect.gen(function*() {
173 const docErrors = yield* checkEntry(model, {
174 enforceVersion: true
175 })
176 const interfacesErrors = yield* checkInterfaces(model.interfaces)
177 const typeAliasesErrors = yield* checkTypeAliases(model.typeAliases)
178 const namespacesErrors = yield* checkNamespaces(model.namespaces)
179 return Array.flatten([docErrors, interfacesErrors, typeAliasesErrors, namespacesErrors])
180 })
181 }
182
183 /**
184 * Validates documentation for namespaces and their nested declarations.
185 *
186 * @category validation
187 * @since 0.6.0
188 */
189 export function checkNamespaces(models: ReadonlyArray<Domain.Namespace>) {
190 return Effect.forEach(models, checkNamespace).pipe(Effect.map(Array.flatten))
191 }
192
193 function checkExport(model: Domain.Export) {
194 return checkEntry(model, {
195 enforceVersion: true
196 })
197 }
198
199 /**
200 * Validates documentation for explicit export declarations.
201 *
202 * @category validation
203 * @since 0.6.0
204 */
205 export function checkExports(models: ReadonlyArray<Domain.Export>) {
206 return Effect.forEach(models, checkExport).pipe(Effect.map(Array.flatten))
207 }
208
209 /**
210 * Validates every documented declaration in a parsed module.
211 *
212 * @category validation
213 * @since 0.6.0
214 */
215 export function checkModule(module: Domain.Module) {
216 return Effect.gen(function*() {
217 const functionsErrors = yield* checkFunctions(module.functions)
218 const classesErrors = yield* checkClasses(module.classes)
219 const constantsErrors = yield* checkConstants(module.constants)
220 const interfacesErrors = yield* checkInterfaces(module.interfaces)
221 const typeAliasesErrors = yield* checkTypeAliases(module.typeAliases)
222 const namespacesErrors = yield* checkNamespaces(module.namespaces)
223 const exportsErrors = yield* checkExports(module.exports)
224 return Array.flatten([
225 functionsErrors,
226 classesErrors,
227 constantsErrors,
228 interfacesErrors,
229 typeAliasesErrors,
230 namespacesErrors,
231 exportsErrors
232 ])
233 }).pipe(Effect.provideService(Parser.Source, module.source))
234 }
235
236 /**
237 * Validates every documented declaration in a collection of parsed modules.
238 *
239 * @category validation
240 * @since 0.6.0
241 */
242 export function checkModules(modules: ReadonlyArray<Domain.Module>) {
243 return Effect.forEach(modules, checkModule).pipe(Effect.map(Array.flatten))
244 }