@kaynooo/cli-env 0.15.1 → 0.15.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,383 @@
1
+ import type { Edit, Node as JsonNode, ParseError } from 'jsonc-parser'
2
+ import type { Document, Pair } from 'yaml'
3
+ // Kept out of structured.ts: the editors are bundled into ev's dist, and the modules other packages import from src must not need them.
4
+ import { parse as parseToml, patch as patchToml } from '@decimalturn/toml-patch'
5
+ import { fail } from '@kaynooo/cli-kit'
6
+ import { applyEdits, createScanner, findNodeAtLocation, modify, parseTree } from 'jsonc-parser'
7
+ import { isAlias, isMap, isScalar, isSeq, parseDocument, stringify } from 'yaml'
8
+ import { isRecord, parseStructured, parseStructuredValue, structuredFormat } from './structured'
9
+
10
+ type Path = (string | number)[]
11
+
12
+ interface Located { path: Path, current: unknown }
13
+
14
+ const INDEX = /^\d+$/
15
+ const INDENT = /^([ \t]+)\S/m
16
+ const INDENT_ONLY = /^[ \t]*/
17
+ const BLANK = /^[ \t]*$/
18
+ const CR = /\r$/
19
+ // What may follow a JSON value on its line, so a property added after it goes on the next line and leaves a comment there in place.
20
+ const LINE_TAIL = /^[ \t]*(?:\/\/.*|\/\*.*\*\/[ \t]*)?\r?$/
21
+ const SPACED_COLON = /"[ \t]*:[ \t]/
22
+ const KEY_COLON = /"[ \t]*:/
23
+ const SPACED_COMMA = /,[ \t]/
24
+ // jsonc-parser's SyntaxKind, a const enum its types declare and modules cannot import.
25
+ const LINE_COMMENT = 12
26
+ const BLOCK_COMMENT = 13
27
+ const END = 17
28
+
29
+ // The path of `key` in the parsed file: a key holding dots is matched whole before it is split, and a list takes an item's index. A key not there yet is created under the deepest one that is.
30
+ function locate(name: string, parsed: unknown, key: string): Located {
31
+ const segments = key.split('.')
32
+ const path: Path = []
33
+ let node = parsed
34
+ let at = 0
35
+
36
+ while (at < segments.length) {
37
+ const segment = segments[at]!
38
+
39
+ if (Array.isArray(node)) {
40
+ if (!INDEX.test(segment) || Number(segment) >= node.length)
41
+ fail(`${name}: ${path.join('.') || 'the file'} is a list with no item ${segment}`, 1)
42
+
43
+ path.push(Number(segment))
44
+ node = node[Number(segment)]
45
+ at++
46
+
47
+ continue
48
+ }
49
+
50
+ if (!isRecord(node))
51
+ return fail(`${name}: ${path.join('.')} holds a value, not keys`, 1)
52
+
53
+ const record = node
54
+ let end = segments.length
55
+
56
+ while (end > at && !Object.hasOwn(record, segments.slice(at, end).join('.')))
57
+ end--
58
+
59
+ if (end === at)
60
+ return { path: [...path, ...segments.slice(at)], current: undefined }
61
+
62
+ const own = segments.slice(at, end).join('.')
63
+
64
+ path.push(own)
65
+ node = record[own]
66
+ at = end
67
+ }
68
+
69
+ if (Array.isArray(node) || isRecord(node))
70
+ fail(`${name}: ${key} holds ${Array.isArray(node) ? 'a list' : 'keys'}, not a value`, 1)
71
+
72
+ return { path, current: node }
73
+ }
74
+
75
+ // The value as the type the key holds: a number or a boolean stays one when the text reads back as written, anything else is a string.
76
+ function typed(current: unknown, value: string): unknown {
77
+ if (typeof current === 'number' && value.trim() !== '' && String(Number(value)) === value)
78
+ return Number(value)
79
+
80
+ return typeof current === 'boolean' && (value === 'true' || value === 'false') ? value === 'true' : value
81
+ }
82
+
83
+ function unchanged(name: string, format: string): never {
84
+ return fail(`${name}: the ${format} editor would not give this file back as it is, so nothing was written`, 1, 'edit it by hand')
85
+ }
86
+
87
+ function lineStart(text: string, at: number): number {
88
+ return text.lastIndexOf('\n', at - 1) + 1
89
+ }
90
+
91
+ // The offset after the line holding `at`, its line break included.
92
+ function lineEnd(text: string, at: number): number {
93
+ const end = text.indexOf('\n', at)
94
+
95
+ return end === -1 ? text.length : end + 1
96
+ }
97
+
98
+ function eolOf(text: string): string {
99
+ return text.includes('\r\n') ? '\r\n' : '\n'
100
+ }
101
+
102
+ // The comments of a JSON text, those starting inside `[from, to)` left out.
103
+ function jsonComments(text: string, from = 0, to = 0): string[] {
104
+ const scanner = createScanner(text, false)
105
+ const found: string[] = []
106
+
107
+ for (let token: number = scanner.scan(); token !== END; token = scanner.scan()) {
108
+ const at = scanner.getTokenOffset()
109
+
110
+ if ((token === LINE_COMMENT || token === BLOCK_COMMENT) && (at < from || at >= to))
111
+ found.push(scanner.getTokenValue())
112
+ }
113
+
114
+ return found
115
+ }
116
+
117
+ // A property added to a JSON object as its siblings are written: on a line of its own at their indent in a multi-line object, inline with their spacing in a one-line one, the rest of the file untouched.
118
+ function jsonInsert(text: string, tree: JsonNode, path: Path, value: unknown): Edit[] {
119
+ let depth = path.length - 1
120
+ let parent = findNodeAtLocation(tree, path.slice(0, depth))
121
+
122
+ while (parent?.type !== 'object' && depth > 0)
123
+ parent = findNodeAtLocation(tree, path.slice(0, --depth))
124
+
125
+ if (parent?.type !== 'object')
126
+ return fail(`the file holds no object to add ${path.join('.')} to`, 1)
127
+
128
+ const added = path.slice(depth + 1).reduceRight<unknown>((inner, key) => ({ [key]: inner }), value)
129
+ const own = text.slice(parent.offset, parent.offset + parent.length)
130
+ // The file's own spacing after a key's colon, else a space in a multi-line object and none in a one-line one.
131
+ const colon = SPACED_COLON.test(text) || (!KEY_COLON.test(text) && own.includes('\n')) ? ': ' : ':'
132
+ const last = parent.children?.at(-1)
133
+
134
+ if (!own.includes('\n')) {
135
+ const property = `${JSON.stringify(path[depth])}${colon}${JSON.stringify(added)}`
136
+
137
+ return last === undefined
138
+ ? [{ offset: parent.offset + 1, length: parent.length - 2, content: property }]
139
+ : [{ offset: last.offset + last.length, length: 0, content: `${SPACED_COMMA.test(own) ? ', ' : ','}${property}` }]
140
+ }
141
+
142
+ const eol = eolOf(text)
143
+ const unit = INDENT.exec(text)?.[1] ?? ' '
144
+ const outer = INDENT_ONLY.exec(text.slice(lineStart(text, parent.offset), parent.offset))?.[0] ?? ''
145
+ const indent = last === undefined ? `${outer}${unit}` : INDENT_ONLY.exec(text.slice(lineStart(text, last.offset), last.offset))?.[0] ?? ''
146
+ const property = `${indent}${JSON.stringify(path[depth])}${colon}${JSON.stringify(added, null, unit).replaceAll('\n', `${eol}${indent}`)}`
147
+
148
+ if (last === undefined)
149
+ return [{ offset: parent.offset + 1, length: parent.length - 2, content: `${eol}${property}${eol}${outer}` }]
150
+
151
+ // The comma goes right after the last value, or a trailing one is kept, and the new line goes after a comment ending that line.
152
+ const rest = text.slice(last.offset + last.length)
153
+ const trailing = rest.trimStart().startsWith(',')
154
+ const end = last.offset + last.length + (trailing ? rest.length - rest.trimStart().length + 1 : 0)
155
+ const lineBreak = text.indexOf('\n', end)
156
+ const tail = lineBreak === -1 ? undefined : text.slice(end, lineBreak)
157
+ const after = tail !== undefined && LINE_TAIL.test(tail) ? end + tail.replace(CR, '').length : end
158
+ const comma = trailing ? '' : ','
159
+
160
+ return after === end
161
+ ? [{ offset: end, length: 0, content: `${comma}${eol}${property}` }]
162
+ : [{ offset: end, length: 0, content: comma }, { offset: after, length: 0, content: `${eol}${property}` }]
163
+ }
164
+
165
+ // jsonc-parser replaces or removes the key's span alone when no formatting is asked, as its formatter would redo the lines around it; an added key is written by jsonInsert. Removing one also takes the text up to the previous value, so a comment there would go with it unless refused.
166
+ function editJson(name: string, text: string, path: Path, value: unknown): string {
167
+ const errors: ParseError[] = []
168
+ const tree = parseTree(text, errors, { allowTrailingComma: true })
169
+
170
+ if (errors.length > 0 || tree === undefined)
171
+ return unchanged(name, 'JSON')
172
+
173
+ const existing = findNodeAtLocation(tree, path)
174
+ const edited = applyEdits(text, value === undefined || existing !== undefined ? modify(text, path, value, {}) : jsonInsert(text, tree, path, value))
175
+ const property = value === undefined ? existing?.parent : undefined
176
+ const kept = jsonComments(text, property?.offset, property === undefined ? 0 : property.offset + property.length)
177
+
178
+ if (jsonComments(edited).join('\0') !== kept.join('\0'))
179
+ fail(`${name}: removing ${path.join('.')} would take a comment beside it, so nothing was written`, 1, 'edit it by hand')
180
+
181
+ return edited
182
+ }
183
+
184
+ // A YAML scalar written as the one it replaces was: a quoted one keeps its quotes, and a plain one stays plain when YAML reads it back as the same value. A line break always goes double-quoted, whose escapes are JSON's.
185
+ function yamlScalar(value: unknown, type?: string): string {
186
+ if (typeof value === 'string' && (value.includes('\n') || type === 'QUOTE_DOUBLE'))
187
+ return JSON.stringify(value)
188
+
189
+ if (typeof value === 'string' && type === 'QUOTE_SINGLE')
190
+ return `'${value.replaceAll('\'', '\'\'')}'`
191
+
192
+ return stringify(value, { lineWidth: 0 }).trimEnd()
193
+ }
194
+
195
+ type Range = [number, number, number]
196
+
197
+ // Where `path` leads in the document, keys matched as the text the parsed file reads them as (so `404:` is key '404'): the pair or list item it names, else the deepest map on the way and how many segments lead to it.
198
+ interface YamlSpot { map?: unknown, depth: number, pair?: Pair, item?: unknown }
199
+
200
+ function yamlSpot(document: Document, path: Path): YamlSpot {
201
+ let node: unknown = document.contents
202
+
203
+ for (let depth = 0; depth < path.length; depth++) {
204
+ const segment = path[depth]!
205
+
206
+ if (isSeq(node)) {
207
+ if (depth === path.length - 1)
208
+ return { depth, item: node.items[Number(segment)] }
209
+
210
+ node = node.items[Number(segment)]
211
+
212
+ continue
213
+ }
214
+
215
+ if (!isMap(node))
216
+ return { depth }
217
+
218
+ const pair = node.items.find(each => isScalar(each.key) && String(each.key.value) === String(segment))
219
+
220
+ if (pair === undefined)
221
+ return { map: node, depth }
222
+
223
+ if (depth === path.length - 1)
224
+ return { map: node, depth, pair }
225
+
226
+ node = pair.value
227
+ }
228
+
229
+ return { depth: path.length }
230
+ }
231
+
232
+ // yaml prints a whole document anew, folding lines and respacing comments, so the edit is a splice of the source at the ranges it parsed: the value's own span, a line added after the last of its map, or the key's lines taken out.
233
+ function editYaml(name: string, text: string, path: Path, value: unknown): string {
234
+ const document = parseDocument(text)
235
+
236
+ if (document.errors.length > 0)
237
+ unchanged(name, 'YAML')
238
+
239
+ const refuse = (why: string): never => fail(`${name}: ${path.join('.')} ${why}, which ev does not edit`, 1, 'edit it by hand')
240
+ const spot = yamlSpot(document, path)
241
+ const node = spot.pair === undefined ? spot.item : spot.pair.value
242
+
243
+ if (value !== undefined && (spot.pair !== undefined || spot.item !== undefined)) {
244
+ if (isAlias(node))
245
+ refuse('is an alias')
246
+
247
+ if (!isScalar(node))
248
+ return refuse('holds no plain value')
249
+
250
+ const scalar = node
251
+ const [from, to] = scalar.range!
252
+
253
+ if (scalar.type === 'BLOCK_LITERAL' || scalar.type === 'BLOCK_FOLDED')
254
+ refuse('is a block scalar')
255
+
256
+ // An empty value has an empty range wherever the parser stopped, so the value goes right after the key's colon.
257
+ if (from === to) {
258
+ const key = spot.pair?.key as { range: Range } | undefined
259
+ const colon = key === undefined ? -1 : text.indexOf(':', key.range[1])
260
+
261
+ if (colon === -1)
262
+ refuse('is an empty list item')
263
+
264
+ return `${text.slice(0, colon + 1)} ${yamlScalar(value)}${text.slice(colon + 1)}`
265
+ }
266
+
267
+ return `${text.slice(0, from)}${yamlScalar(value, scalar.type)}${text.slice(to)}`
268
+ }
269
+
270
+ if (value === undefined) {
271
+ const key = spot.pair?.key as { range: Range } | undefined
272
+
273
+ if (key === undefined)
274
+ return text
275
+
276
+ const start = lineStart(text, key.range[0])
277
+ const valueEnd = (node as { range?: Range } | null | undefined)?.range?.[1] ?? 0
278
+
279
+ if (!BLANK.test(text.slice(start, key.range[0])))
280
+ refuse('shares its line with another key')
281
+
282
+ // A block scalar's range ends at the start of the next line, so the removal ends on the line of the value's last character.
283
+ return `${text.slice(0, start)}${text.slice(lineEnd(text, Math.max(key.range[1], valueEnd) - 1))}`
284
+ }
285
+
286
+ const parent = spot.map as { flow?: boolean, items: Pair[], range?: Range } | undefined
287
+
288
+ if (!isMap(parent) || parent.flow === true || parent.items.length === 0)
289
+ return refuse(spot.depth === 0 ? 'is not under a block mapping' : 'sits in a flow mapping or list')
290
+
291
+ const first = parent.items[0]!.key as { range: Range }
292
+ const column = first.range[0] - lineStart(text, first.range[0])
293
+ const unit = INDENT.exec(text)?.[1] ?? ' '
294
+ const eol = eolOf(text)
295
+ const lines = path.slice(spot.depth).map((segment, index, missing) => {
296
+ const indent = ' '.repeat(column + index * unit.length)
297
+ const key = yamlScalar(String(segment))
298
+
299
+ return index === missing.length - 1 ? `${indent}${key}: ${yamlScalar(value)}` : `${indent}${key}:`
300
+ })
301
+ const at = lineEnd(text, parent.range![1] - 1)
302
+ const before = text.slice(0, at)
303
+
304
+ return `${before}${before.endsWith('\n') ? '' : eol}${lines.join(eol)}${eol}${text.slice(at)}`
305
+ }
306
+
307
+ function editToml(name: string, text: string, path: Path, value: unknown): string {
308
+ let parsed: Record<string, unknown>
309
+
310
+ try {
311
+ parsed = parseToml(text) as Record<string, unknown>
312
+ }
313
+ catch {
314
+ return unchanged(name, 'TOML')
315
+ }
316
+
317
+ if (patchToml(text, parsed) !== text)
318
+ unchanged(name, 'TOML')
319
+
320
+ let node: Record<string, unknown> = parsed
321
+
322
+ for (const segment of path.slice(0, -1)) {
323
+ node[segment] ??= {}
324
+ node = node[segment] as Record<string, unknown>
325
+ }
326
+
327
+ const last = path.at(-1)!
328
+
329
+ if (value === undefined)
330
+ delete node[last]
331
+ else
332
+ node[last] = value
333
+
334
+ return patchToml(text, parsed)
335
+ }
336
+
337
+ const EDITORS: Record<string, (name: string, text: string, path: Path, value: unknown) => string> = { JSON: editJson, YAML: editYaml, TOML: editToml }
338
+
339
+ // The edited text, refused unless it reads back as the file did with only `key` changed, so no edit reaches past it.
340
+ function edit(name: string, text: string, key: string, value: string | undefined): string | undefined {
341
+ const format = structuredFormat(name)!
342
+ const editor = EDITORS[format]
343
+
344
+ if (editor === undefined || name.toLowerCase().endsWith('.json5'))
345
+ return fail(`${name}: ev reads JSON5 but does not write it`, 1)
346
+
347
+ const before = parseStructured(name, text)
348
+ const { path, current } = locate(name, parseStructuredValue(name, text), key)
349
+
350
+ if (value === undefined && current === undefined)
351
+ return undefined
352
+
353
+ if (value === undefined && typeof path.at(-1) === 'number')
354
+ fail(`${name}: ${key} is a list item, and removing it would renumber the ones after it`, 1)
355
+
356
+ const written = value === undefined ? undefined : typed(current, value)
357
+ const after = editor(name, text, path, written)
358
+ const expected = new Map(before)
359
+ const flat = path.join('.')
360
+
361
+ if (written === undefined)
362
+ expected.delete(flat)
363
+ else
364
+ expected.set(flat, String(written))
365
+
366
+ // Removing a YAML file's last key leaves nothing but comments, which reads as no value rather than an empty map.
367
+ const read = expected.size === 0 && format === 'YAML' && parseDocument(after).contents === null ? new Map<string, string>() : parseStructured(name, after)
368
+
369
+ if (read.size !== expected.size || [...expected].some(([each, was]) => read.get(each) !== was))
370
+ fail(`${name}: the edit would change more than ${key}, so nothing was written`, 1, 'edit it by hand')
371
+
372
+ return after
373
+ }
374
+
375
+ /** The file's text with `key` set to `value`, a number or boolean key keeping its type, its comments, order and quoting kept. */
376
+ export function setStructured(name: string, text: string, key: string, value: string): string {
377
+ return edit(name, text, key, value)!
378
+ }
379
+
380
+ /** The file's text without `key`, or undefined when it does not set it. */
381
+ export function unsetStructured(name: string, text: string, key: string): string | undefined {
382
+ return edit(name, text, key, undefined)
383
+ }
@@ -0,0 +1,68 @@
1
+ import { extname } from 'node:path'
2
+ import { fail } from '@kaynooo/cli-kit'
3
+
4
+ // The JSON, YAML and TOML files ev reads, by extension, each with the parser Bun has for it; `.json` takes comments too, as tsconfig-style files carry them.
5
+ const PARSERS: Record<string, [format: string, parse: (text: string) => unknown]> = {
6
+ '.json': ['JSON', text => Bun.JSONC.parse(text)],
7
+ '.jsonc': ['JSON', text => Bun.JSONC.parse(text)],
8
+ '.json5': ['JSON', text => Bun.JSON5.parse(text)],
9
+ '.yaml': ['YAML', text => Bun.YAML.parse(text)],
10
+ '.yml': ['YAML', text => Bun.YAML.parse(text)],
11
+ '.toml': ['TOML', text => Bun.TOML.parse(text)],
12
+ }
13
+
14
+ export function structuredFormat(path: string): string | undefined {
15
+ return PARSERS[extname(path).toLowerCase()]?.[0]
16
+ }
17
+
18
+ export function isRecord(value: unknown): value is Record<string, unknown> {
19
+ if (typeof value !== 'object' || value === null)
20
+ return false
21
+
22
+ const prototype = Object.getPrototypeOf(value) as unknown
23
+
24
+ return prototype === Object.prototype || prototype === null
25
+ }
26
+
27
+ // Each leaf under its dotted path (`database.password`, `servers.0.host`); a TOML date prints as written, a null as nothing. An empty object or list leaves no key, a key holding a dot reads like a nested one, and a number prints as JavaScript reads it (`1.0` as `1`).
28
+ function flatten(value: unknown, path: string, into: Map<string, string>): void {
29
+ if (Array.isArray(value) || isRecord(value)) {
30
+ for (const [key, each] of Object.entries(value))
31
+ flatten(each, path === '' ? key : `${path}.${key}`, into)
32
+
33
+ return
34
+ }
35
+
36
+ into.set(path, value === null || value === undefined ? '' : String(value))
37
+ }
38
+
39
+ /** The value a JSON, YAML or TOML file holds, refused unless it holds keys, `name` naming it in a refusal. */
40
+ export function parseStructuredValue(name: string, text: string): unknown {
41
+ const [format, parse] = PARSERS[extname(name).toLowerCase()] ?? []
42
+
43
+ if (format === undefined || parse === undefined)
44
+ fail(`${name} is not JSON, YAML or TOML`)
45
+
46
+ let parsed: unknown
47
+
48
+ try {
49
+ parsed = parse(text)
50
+ }
51
+ catch (error) {
52
+ fail(`${name} is not valid ${format}: ${error instanceof Error ? error.message : String(error)}`)
53
+ }
54
+
55
+ if (!Array.isArray(parsed) && !isRecord(parsed))
56
+ fail(`${name} holds a single ${format} value, no keys`)
57
+
58
+ return parsed
59
+ }
60
+
61
+ // The keys of a JSON, YAML or TOML file as dotted paths to their values.
62
+ export function parseStructured(name: string, text: string): Map<string, string> {
63
+ const into = new Map<string, string>()
64
+
65
+ flatten(parseStructuredValue(name, text), '', into)
66
+
67
+ return into
68
+ }