|
| 1 | +// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * The refusal a config load raises when a `define*` helper's `Schema.parse` |
| 5 | + * throws a raw `ZodError` while the config MODULE evaluates. |
| 6 | + * |
| 7 | + * ## The defect this closes |
| 8 | + * |
| 9 | + * `defineView`, `defineAction` and the other strict helpers call |
| 10 | + * `Schema.parse` and let the `ZodError` out as is. Nothing on the normal load |
| 11 | + * path wrapped it, and every command's catch-all printed `error.message` — |
| 12 | + * which for a `ZodError` is its issues as a JSON array. Measured on this tree |
| 13 | + * with a `defineView` mixing string and object `list.columns`: `os validate`, |
| 14 | + * `os build`, `os lint`, `os dev` and `os serve` all printed `✗ [` and 40-odd |
| 15 | + * lines of JSON, naming no file, no helper and no remedy. |
| 16 | + * |
| 17 | + * ## What it renders, and with what |
| 18 | + * |
| 19 | + * The issues go through the project's own `formatZodError` — the formatter the |
| 20 | + * `os migrate meta` shim's `__refusal` and the loader's own `defineStack |
| 21 | + * validation failed` block already use, union branch expansion included. There |
| 22 | + * is no second formatter here: this file only works out WHERE the refused call |
| 23 | + * is, and puts that in front of the block. |
| 24 | + * |
| 25 | + * ## How the location is read, and when it is not |
| 26 | + * |
| 27 | + * bundle-require evaluates one esbuild bundle of the config and every module |
| 28 | + * it imports (an `@objectstack/*` package or a `node_modules` dependency stays |
| 29 | + * external), with an inline source map. The innermost stack frame inside that |
| 30 | + * bundle is therefore the authored call that threw, and the map turns it back |
| 31 | + * into the authored file, line and column. The frame directly above it is the |
| 32 | + * function that call entered: the helper, named only when it is a `define*` |
| 33 | + * function whose name the authored line actually spells. |
| 34 | + * |
| 35 | + * ⛔ Never a guessed file. When the stack holds no frame in the bundle (a |
| 36 | + * truncated stack, an error rethrown from a promise), when the map has no |
| 37 | + * entry on that generated line, or when the mapped file is not on disk, |
| 38 | + * {@link locateConfigLoadZodError} answers `undefined` and the refusal names |
| 39 | + * the config entry it was loading, saying the module that threw is unknown. |
| 40 | + */ |
| 41 | + |
| 42 | +import fs from 'fs'; |
| 43 | +import path from 'path'; |
| 44 | +import { SourceMap } from 'node:module'; |
| 45 | +import { fileURLToPath } from 'node:url'; |
| 46 | +import { formatZodError } from '@objectstack/spec'; |
| 47 | + |
| 48 | +/** The bundle bundle-require evaluated: its path on disk and its text. */ |
| 49 | +export interface EvaluatedConfigBundle { |
| 50 | + readonly file: string; |
| 51 | + readonly text: string; |
| 52 | +} |
| 53 | + |
| 54 | +/** Where the refused call is in the authored source. */ |
| 55 | +export interface ConfigLoadZodLocation { |
| 56 | + /** Absolute path of the authored module that made the refused call. */ |
| 57 | + readonly file: string; |
| 58 | + /** 1-based. */ |
| 59 | + readonly line: number; |
| 60 | + /** 1-based. */ |
| 61 | + readonly column: number; |
| 62 | + /** The `define*` helper the call entered, when the stack and the line agree on it. */ |
| 63 | + readonly helper?: string; |
| 64 | +} |
| 65 | + |
| 66 | +/** A `ZodError` as `Schema.parse` throws it: by shape, not `instanceof` (two zod copies can be live). */ |
| 67 | +export function isRawZodError(error: unknown): error is Error & { issues: unknown[] } { |
| 68 | + return ( |
| 69 | + error instanceof Error |
| 70 | + && error.name === 'ZodError' |
| 71 | + && Array.isArray((error as { issues?: unknown }).issues) |
| 72 | + ); |
| 73 | +} |
| 74 | + |
| 75 | +const DEFINE_HELPER_NAME_RE = /^define[A-Z][A-Za-z0-9]*$/; |
| 76 | +const INLINE_SOURCE_MAP_RE = /\/\/# sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)\s*$/; |
| 77 | +const STACK_FRAME_RE = /^\s*at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?$/; |
| 78 | + |
| 79 | +interface StackFrame { |
| 80 | + readonly fn?: string; |
| 81 | + readonly file: string; |
| 82 | + readonly line: number; |
| 83 | + readonly column: number; |
| 84 | +} |
| 85 | + |
| 86 | +function stackFramesOf(stack: string): StackFrame[] { |
| 87 | + const frames: StackFrame[] = []; |
| 88 | + for (const raw of stack.split('\n')) { |
| 89 | + const match = STACK_FRAME_RE.exec(raw); |
| 90 | + if (!match) continue; |
| 91 | + const [, fn, location, line, column] = match; |
| 92 | + let file = location; |
| 93 | + if (file.startsWith('async ')) file = file.slice('async '.length); |
| 94 | + if (file.startsWith('file://')) { |
| 95 | + try { |
| 96 | + file = fileURLToPath(file); |
| 97 | + } catch { |
| 98 | + continue; |
| 99 | + } |
| 100 | + } |
| 101 | + frames.push({ fn: fn?.replace(/^async /, ''), file, line: Number(line), column: Number(column) }); |
| 102 | + } |
| 103 | + return frames; |
| 104 | +} |
| 105 | + |
| 106 | +function sourceMapOf(bundle: EvaluatedConfigBundle): { map: SourceMap; sources: Set<string> } | undefined { |
| 107 | + const match = INLINE_SOURCE_MAP_RE.exec(bundle.text); |
| 108 | + if (!match) return undefined; |
| 109 | + try { |
| 110 | + const payload = JSON.parse(Buffer.from(match[1], 'base64').toString('utf8')); |
| 111 | + return { |
| 112 | + map: new SourceMap(payload), |
| 113 | + sources: new Set<string>(Array.isArray(payload.sources) ? payload.sources : []), |
| 114 | + }; |
| 115 | + } catch { |
| 116 | + return undefined; |
| 117 | + } |
| 118 | +} |
| 119 | + |
| 120 | +/** A map `sources` entry as an absolute path: esbuild writes them relative to its working directory. */ |
| 121 | +function absoluteSource(source: string, cwd: string): string | undefined { |
| 122 | + if (source.startsWith('file://')) { |
| 123 | + try { |
| 124 | + return fileURLToPath(source); |
| 125 | + } catch { |
| 126 | + return undefined; |
| 127 | + } |
| 128 | + } |
| 129 | + return path.resolve(cwd, source); |
| 130 | +} |
| 131 | + |
| 132 | +/** The helper the frame names, when it is a `define*` function and the authored line spells that name. */ |
| 133 | +function helperOf(frame: StackFrame | undefined, file: string, line: number): string | undefined { |
| 134 | + const name = frame?.fn?.split('.').pop(); |
| 135 | + if (!name || !DEFINE_HELPER_NAME_RE.test(name)) return undefined; |
| 136 | + let text: string | undefined; |
| 137 | + try { |
| 138 | + text = fs.readFileSync(file, 'utf8').split(/\r?\n/)[line - 1]; |
| 139 | + } catch { |
| 140 | + return undefined; |
| 141 | + } |
| 142 | + return text !== undefined && new RegExp(`\\b${name}\\b`).test(text) ? name : undefined; |
| 143 | +} |
| 144 | + |
| 145 | +/** |
| 146 | + * The authored file, line, column and helper of the call that threw `stack` |
| 147 | + * while `bundle` evaluated, or `undefined` when the stack cannot tell. |
| 148 | + * |
| 149 | + * @param stack the thrown error's `stack` |
| 150 | + * @param bundle the bundle bundle-require evaluated, read before it was deleted |
| 151 | + * @param cwd the working directory esbuild resolved the map's `sources` against |
| 152 | + */ |
| 153 | +export function locateConfigLoadZodError( |
| 154 | + stack: string | undefined, |
| 155 | + bundle: EvaluatedConfigBundle | undefined, |
| 156 | + cwd: string, |
| 157 | +): ConfigLoadZodLocation | undefined { |
| 158 | + if (!stack || !bundle) return undefined; |
| 159 | + const mapped = sourceMapOf(bundle); |
| 160 | + if (!mapped) return undefined; |
| 161 | + const authored = new Set<string>(); |
| 162 | + for (const source of mapped.sources) { |
| 163 | + const absolute = absoluteSource(source, cwd); |
| 164 | + if (absolute) authored.add(absolute); |
| 165 | + } |
| 166 | + |
| 167 | + const frames = stackFramesOf(stack); |
| 168 | + for (let i = 0; i < frames.length; i++) { |
| 169 | + const frame = frames[i]; |
| 170 | + let located: { file: string; line: number; column: number } | undefined; |
| 171 | + if (frame.file === bundle.file) { |
| 172 | + // V8 frames are 1-based; the map is 0-based. The entry must sit on the |
| 173 | + // frame's own generated line — `findEntry` otherwise answers the nearest |
| 174 | + // earlier mapping, which can be another module's code. |
| 175 | + const entry = mapped.map.findEntry(frame.line - 1, frame.column - 1) as { |
| 176 | + generatedLine?: number; |
| 177 | + originalSource?: string; |
| 178 | + originalLine?: number; |
| 179 | + originalColumn?: number; |
| 180 | + }; |
| 181 | + if ( |
| 182 | + entry.generatedLine !== frame.line - 1 |
| 183 | + || typeof entry.originalSource !== 'string' |
| 184 | + || typeof entry.originalLine !== 'number' |
| 185 | + || typeof entry.originalColumn !== 'number' |
| 186 | + ) { |
| 187 | + return undefined; |
| 188 | + } |
| 189 | + const file = absoluteSource(entry.originalSource, cwd); |
| 190 | + if (!file) return undefined; |
| 191 | + located = { file, line: entry.originalLine + 1, column: entry.originalColumn + 1 }; |
| 192 | + } else if (authored.has(frame.file)) { |
| 193 | + // `--enable-source-maps`: V8 already mapped the frame to the authored file. |
| 194 | + located = { file: frame.file, line: frame.line, column: frame.column }; |
| 195 | + } |
| 196 | + if (!located) continue; |
| 197 | + if (!fs.existsSync(located.file)) return undefined; |
| 198 | + const helper = helperOf(frames[i - 1], located.file, located.line); |
| 199 | + return helper ? { ...located, helper } : located; |
| 200 | + } |
| 201 | + return undefined; |
| 202 | +} |
| 203 | + |
| 204 | +/** A path as the author reads it: relative to the working directory when it is under it. */ |
| 205 | +function displayPath(file: string, cwd: string): string { |
| 206 | + const relative = path.relative(cwd, file); |
| 207 | + return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file; |
| 208 | +} |
| 209 | + |
| 210 | +/** |
| 211 | + * The readable refusal for a raw `ZodError` a config load threw. |
| 212 | + * |
| 213 | + * A plain `Error`, so every command's catch-all prints it exactly where it |
| 214 | + * printed the JSON array before — `--json` copies `message` into its |
| 215 | + * envelope's `error` — and no catch-all changes. The `ZodError` rides as |
| 216 | + * `cause`. |
| 217 | + */ |
| 218 | +export class ConfigLoadRefusalError extends Error { |
| 219 | + constructor(message: string, cause: Error) { |
| 220 | + super(message, { cause }); |
| 221 | + this.name = 'ConfigLoadRefusalError'; |
| 222 | + } |
| 223 | +} |
| 224 | + |
| 225 | +/** |
| 226 | + * Turn a raw `ZodError` thrown while `configPath` loaded into |
| 227 | + * {@link ConfigLoadRefusalError}: |
| 228 | + * |
| 229 | + * ```text |
| 230 | + * src/views/ticket.view.ts:5:28 · defineView validation failed (1 issue): |
| 231 | + * |
| 232 | + * ✗ list.columns: Invalid input |
| 233 | + * ✗ list.columns.0: Invalid input: expected string, received object |
| 234 | + * ``` |
| 235 | + */ |
| 236 | +export function configLoadRefusal( |
| 237 | + error: Error & { issues: unknown[] }, |
| 238 | + configPath: string, |
| 239 | + bundle: EvaluatedConfigBundle | undefined, |
| 240 | + cwd: string, |
| 241 | +): ConfigLoadRefusalError { |
| 242 | + const location = locateConfigLoadZodError(error.stack, bundle, cwd); |
| 243 | + const where = location |
| 244 | + ? `${displayPath(location.file, cwd)}:${location.line}:${location.column}` |
| 245 | + : `${displayPath(configPath, cwd)} (loading it threw; the stack does not say which module)`; |
| 246 | + const label = location?.helper ? `${location.helper} validation failed` : undefined; |
| 247 | + const block = formatZodError(error as unknown as Parameters<typeof formatZodError>[0], label); |
| 248 | + return new ConfigLoadRefusalError(`${where} · ${block}`, error); |
| 249 | +} |
![objectstack-fleet[bot]](https://avatars.githubusercontent.com/u/254823548?v=4&size=40){kind=avatar}
0 commit comments