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
| 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 | } |