@amritk/nish-aarch64-darwin 0.35.0 → 0.36.0

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.
Files changed (119) hide show
  1. package/INSTALL.md +6 -1
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +9 -2
  4. package/package.json +1 -1
  5. package/runtime/nish.d.ts +4612 -430
  6. package/runtime/vite.d.ts +30 -0
  7. package/runtime/vite.mjs +150 -0
  8. package/scripts/build.sh +108 -13
  9. package/std/base64.ts +34 -5
  10. package/std/bytes.ts +256 -40
  11. package/std/cli-args.ts +296 -70
  12. package/std/cli-flags.ts +184 -19
  13. package/std/cli.ts +475 -54
  14. package/std/collections.ts +121 -23
  15. package/std/compress/checksum.ts +44 -14
  16. package/std/compress/deflate.ts +224 -111
  17. package/std/compress/gzip.ts +217 -53
  18. package/std/compress/zlib.ts +63 -7
  19. package/std/crypto/aes.ts +80 -9
  20. package/std/crypto/base64url.ts +22 -0
  21. package/std/crypto/bcrypt-batch.ts +88 -21
  22. package/std/crypto/bcrypt.ts +60 -0
  23. package/std/crypto/chacha20poly1305.ts +53 -0
  24. package/std/crypto/ct.ts +32 -13
  25. package/std/crypto/ed25519.ts +47 -0
  26. package/std/crypto/hkdf.ts +198 -13
  27. package/std/crypto/hmac.ts +235 -31
  28. package/std/crypto/jwt.ts +192 -63
  29. package/std/crypto/p256.ts +159 -16
  30. package/std/crypto/p384.ts +28 -3
  31. package/std/crypto/pki-roots.ts +32 -2
  32. package/std/crypto/pki.ts +81 -15
  33. package/std/crypto/rsa.ts +33 -3
  34. package/std/crypto/sha1.ts +3 -0
  35. package/std/crypto/sha256.ts +24 -1
  36. package/std/crypto/sha512.ts +99 -14
  37. package/std/crypto/x25519.ts +152 -14
  38. package/std/crypto/x509-random.ts +10 -0
  39. package/std/crypto/x509.ts +67 -7
  40. package/std/json-equal.ts +19 -0
  41. package/std/json-format.ts +112 -13
  42. package/std/json-number.ts +64 -14
  43. package/std/json-pointer.ts +23 -1
  44. package/std/json-tokenizer.ts +100 -29
  45. package/std/json-typed.ts +713 -66
  46. package/std/json-value.ts +400 -124
  47. package/std/json.ts +138 -10
  48. package/std/map.ts +25 -7
  49. package/std/math.ts +36 -4
  50. package/std/net/buffer-pool.ts +42 -11
  51. package/std/net/dns-config.ts +109 -23
  52. package/std/net/dns-message.ts +62 -7
  53. package/std/net/dns-resolver.ts +247 -53
  54. package/std/net/dns.ts +203 -35
  55. package/std/net/fetch.ts +151 -61
  56. package/std/net/handler.ts +278 -80
  57. package/std/net/hpack.ts +262 -52
  58. package/std/net/http-compress.ts +125 -15
  59. package/std/net/http-fields.ts +85 -9
  60. package/std/net/http1-client-codec.ts +100 -19
  61. package/std/net/http1-codec.ts +235 -27
  62. package/std/net/http1-server.ts +343 -85
  63. package/std/net/http2-frame.ts +272 -35
  64. package/std/net/http2-tls.ts +135 -34
  65. package/std/net/http2.ts +247 -106
  66. package/std/net/http3-frame.ts +154 -17
  67. package/std/net/http3-server.ts +246 -96
  68. package/std/net/http3.ts +307 -115
  69. package/std/net/outbound.ts +37 -3
  70. package/std/net/postgres-carrier.ts +144 -8
  71. package/std/net/postgres.ts +723 -103
  72. package/std/net/prefork.ts +164 -31
  73. package/std/net/qpack.ts +105 -18
  74. package/std/net/quic-conn-ack.ts +59 -12
  75. package/std/net/quic-conn-cid.ts +124 -27
  76. package/std/net/quic-conn-params.ts +70 -10
  77. package/std/net/quic-datagram.ts +43 -3
  78. package/std/net/quic-frame.ts +286 -12
  79. package/std/net/quic-listener.ts +101 -32
  80. package/std/net/quic-packet.ts +302 -21
  81. package/std/net/quic-recovery.ts +228 -44
  82. package/std/net/quic-stream.ts +353 -91
  83. package/std/net/quic.ts +489 -171
  84. package/std/net/router.ts +87 -40
  85. package/std/net/tls/client.ts +166 -51
  86. package/std/net/tls/codec.ts +413 -56
  87. package/std/net/tls/record-client.ts +110 -55
  88. package/std/net/tls/record-server.ts +159 -59
  89. package/std/net/tls/record.ts +109 -12
  90. package/std/net/tls/schedule.ts +235 -26
  91. package/std/net/tls/ticket.ts +159 -40
  92. package/std/net/tls/verify.ts +49 -3
  93. package/std/net/tls-tcp.ts +250 -45
  94. package/std/net/tls.ts +221 -59
  95. package/std/net/upstream.ts +81 -45
  96. package/std/net/url.ts +97 -13
  97. package/std/net/websocket.ts +122 -12
  98. package/std/net/webtransport.ts +220 -89
  99. package/std/pair.ts +10 -2
  100. package/std/random.ts +34 -9
  101. package/std/regex.ts +352 -198
  102. package/std/region.ts +70 -15
  103. package/std/secret.ts +52 -11
  104. package/std/sort.ts +17 -2
  105. package/std/sqlite.ts +256 -35
  106. package/std/sync/ring.ts +205 -35
  107. package/std/sync/shm.ts +194 -16
  108. package/std/term-io.ts +137 -64
  109. package/std/term-pixels.ts +144 -19
  110. package/std/term-probe.ts +66 -25
  111. package/std/term-rate.ts +128 -57
  112. package/std/term.ts +332 -121
  113. package/std/testing.ts +130 -32
  114. package/std/text.ts +73 -7
  115. package/std/threads.ts +229 -41
  116. package/std/yaml-json.ts +94 -82
  117. package/std/yaml-lines.ts +47 -15
  118. package/std/yaml-write.ts +24 -16
  119. package/std/yaml.ts +764 -384
package/std/cli-args.ts CHANGED
@@ -165,10 +165,15 @@ const closest = (typed: string, names: string[]): string => {
165
165
 
166
166
  /** A flag spec taken apart: `-r, --raw-output`, `--limit <n>`, `--no-color`. */
167
167
  class FlagSpec {
168
+ /** @internal Used by `Cli`. */
168
169
  short: string
170
+ /** @internal Used by `Cli`. */
169
171
  long: string
172
+ /** @internal Used by `Cli`. */
170
173
  meta: string
174
+ /** @internal Used by `Cli`. */
171
175
  value: i32
176
+ /** @internal Used by `Cli`. */
172
177
  negated: boolean
173
178
 
174
179
  constructor(call: string, spec: string) {
@@ -219,53 +224,80 @@ class FlagSpec {
219
224
  * declaration answers a handle (an `i32`) that `parse`'s answer is read by.
220
225
  */
221
226
  export class Cli {
227
+ /** @internal Used by `ParseResult`. */
222
228
  name: string
229
+ /** @internal Used by `ParseResult`. */
223
230
  version: string
224
- description: string
231
+ private description: string
225
232
 
226
- cmdName: string[]
227
- cmdParent: i32[]
233
+ private cmdName: string[]
234
+ private cmdParent: i32[]
235
+ /** @internal Used by `ParseResult`. */
228
236
  cmdId: i32[]
229
- cmdDesc: string[]
237
+ private cmdDesc: string[]
238
+ /** @internal Used by `ParseResult`. */
230
239
  cmdGroup: boolean[]
231
- cmdPath: string[]
232
- cmdAliases: string[]
233
- aliasOwner: i32[]
234
- aliasName: string[]
235
- cmdEpilog: string[]
240
+ private cmdPath: string[]
241
+ private cmdAliases: string[]
242
+ private aliasOwner: i32[]
243
+ private aliasName: string[]
244
+ private cmdEpilog: string[]
245
+ /** @internal Used by `ParseResult`. */
236
246
  cmdFirstArg: i32[]
237
- cmdLastArg: i32[]
238
- cmdVariadic: boolean[]
239
- cmdOptionalArg: boolean[]
240
- children: Map<string, i32>
241
-
242
- flagOwner: i32[]
243
- flagShort: string[]
244
- flagLong: string[]
245
- flagMeta: string[]
247
+ private cmdLastArg: i32[]
248
+ private cmdVariadic: boolean[]
249
+ private cmdOptionalArg: boolean[]
250
+ private children: Map<string, i32>
251
+
252
+ private flagOwner: i32[]
253
+ private flagShort: string[]
254
+ private flagLong: string[]
255
+ private flagMeta: string[]
256
+ /** @internal Used by `ParseResult`. */
246
257
  flagValue: i32[]
258
+ /** @internal Used by `ParseResult`. */
247
259
  flagNegated: boolean[]
248
- flagNegatable: boolean[]
249
- flagDesc: string[]
260
+ private flagNegatable: boolean[]
261
+ private flagDesc: string[]
262
+ /** @internal Used by `ParseResult`. */
250
263
  flagDefault: string[]
264
+ /** @internal Used by `ParseResult`. */
251
265
  flagHasDefault: boolean[]
252
- flagRequired: boolean[]
266
+ private flagRequired: boolean[]
267
+ /** @internal Used by `ParseResult`. */
253
268
  flagRepeatable: boolean[]
254
- flags: Map<string, i32>
255
- negations: Map<string, i32>
269
+ private flags: Map<string, i32>
270
+ private negations: Map<string, i32>
271
+ /** @internal Used by `ParseResult`. */
256
272
  cmdRequired: i32[][]
273
+ /** @internal Used by `ParseResult`. */
257
274
  globalRequired: i32[]
258
- ids: Map<string, i32>
275
+ private ids: Map<string, i32>
259
276
 
277
+ /** @internal Used by `ParseResult`. */
260
278
  argOwner: i32[]
279
+ /** @internal Used by `ParseResult`. */
261
280
  argName: string[]
281
+ /** @internal Used by `ParseResult`. */
262
282
  argRequired: boolean[]
283
+ /** @internal Used by `ParseResult`. */
263
284
  argVariadic: boolean[]
264
- argDesc: string[]
285
+ private argDesc: string[]
286
+ /** @internal Used by `ParseResult`. */
265
287
  argIndex: i32[]
288
+ /** @internal Used by `ParseResult`. */
266
289
  argNext: i32[]
267
290
 
268
- /** A tree with only its root, the program `name` at `version`, for `description`. */
291
+ /**
292
+ * A tree with only its root, the program `name` at `version`, for
293
+ * `description`.
294
+ *
295
+ * @param name the program's name, which starts every command path, usage
296
+ * line and error line, such as `"api"`
297
+ * @param version what `--version` prints after the name, such as `"1.4.0"`
298
+ * @param description the one-line summary every help page's header shows
299
+ * after the version
300
+ */
269
301
  constructor(name: string, version: string, description: string) {
270
302
  this.name = name
271
303
  this.version = version
@@ -312,14 +344,14 @@ export class Cli {
312
344
  }
313
345
 
314
346
  /** The command `handle`, or a panic naming `call` when there is none. */
315
- checkCommand(call: string, handle: i32): i32 {
347
+ private checkCommand(call: string, handle: i32): i32 {
316
348
  if (!(handle >= 0 && handle < toI32(this.cmdName.length))) {
317
349
  panic(`cli-args: ${call}: ${handle} is not a command handle`)
318
350
  }
319
351
  return handle
320
352
  }
321
353
 
322
- /** The flag `handle`, or a panic naming `call` when there is none. */
354
+ /** @internal Called by `ParseResult`. The flag `handle`, or a panic naming `call` when there is none. */
323
355
  checkFlag(call: string, handle: i32): i32 {
324
356
  if (!(handle >= 0 && handle < toI32(this.flagLong.length))) {
325
357
  panic(`cli-args: ${call}: ${handle} is not a flag handle`)
@@ -327,7 +359,7 @@ export class Cli {
327
359
  return handle
328
360
  }
329
361
 
330
- /** The argument `handle`, or a panic naming `call` when there is none. */
362
+ /** @internal Called by `ParseResult`. The argument `handle`, or a panic naming `call` when there is none. */
331
363
  checkArgument(call: string, handle: i32): i32 {
332
364
  if (!(handle >= 0 && handle < toI32(this.argName.length))) {
333
365
  panic(`cli-args: ${call}: ${handle} is not an argument handle`)
@@ -335,19 +367,26 @@ export class Cli {
335
367
  return handle
336
368
  }
337
369
 
338
- /** The command line that names `handle`: the program, then each command down to it. */
370
+ /** @internal Called by `ParseResult`. The command line that names `handle`: the program, then each command down to it. */
339
371
  pathOf(handle: i32): string {
340
372
  return this.cmdPath[this.checkCommand("path", handle)]
341
373
  }
342
374
 
343
- /** Whether `handle` holds commands rather than running: a group, or a root given children. */
375
+ /** @internal Called by nothing. Whether `handle` holds commands rather than running: a group, or a root given children. */
344
376
  isGroup(handle: i32): boolean {
345
377
  const h = this.checkCommand("isGroup", handle)
346
378
  return this.cmdGroup[h]
347
379
  }
348
380
 
349
381
  /** A new child of `parent`; `call` names the declaration in a panic. */
350
- addCommand(call: string, parent: i32, name: string, id: i32, description: string, group: boolean): i32 {
382
+ private addCommand(
383
+ call: string,
384
+ parent: i32,
385
+ name: string,
386
+ id: i32,
387
+ description: string,
388
+ group: boolean
389
+ ): i32 {
351
390
  const p = this.checkCommand(call, parent)
352
391
  if (!isWord(name)) {
353
392
  panic(`cli-args: ${call}: '${name}' is not a command name`)
@@ -384,7 +423,19 @@ export class Cli {
384
423
  return handle
385
424
  }
386
425
 
387
- /** A group under `parent`: it holds commands, and naming it without one is an error. */
426
+ /**
427
+ * A group under `parent`: it holds commands, and naming it without one is
428
+ * an error.
429
+ *
430
+ * @param parent the handle of the group (or `ROOT`) the group goes in;
431
+ * panics on a command, or on one that takes arguments or a required flag
432
+ * @param name the word that names the group on the command line; panics
433
+ * when it is empty, has a space or `=`, starts with `-`, or is already a
434
+ * name in `parent`
435
+ * @param description the group's line in its parent's help, and in its own
436
+ * @returns the group's handle, for `command`, `group`, `flag`, `alias` and
437
+ * `epilog`
438
+ */
388
439
  group(parent: i32, name: string, description: string): i32 {
389
440
  return this.addCommand(`group(${name})`, parent, name, NONE, description, true)
390
441
  }
@@ -392,6 +443,19 @@ export class Cli {
392
443
  /**
393
444
  * A command under `parent` that the program runs, answered by `id` in
394
445
  * `ParseResult.id`: not negative, which is a group's, and no other command's.
446
+ *
447
+ * @param parent the handle of the group (or `ROOT`) the command goes in;
448
+ * panics on a command, or on one that takes arguments or a required flag
449
+ * @param name the word that names the command on the command line; panics
450
+ * when it is empty, has a space or `=`, starts with `-`, or is already a
451
+ * name in `parent`
452
+ * @param id what `ParseResult.id` answers when the arguments name this
453
+ * command, so the program can switch on it; panics when negative or
454
+ * already another command's
455
+ * @param description the command's line in its parent's help, and in its
456
+ * own usage line
457
+ * @returns the command's handle, for `flag`, `argument`, `alias` and
458
+ * `epilog`
395
459
  */
396
460
  command(parent: i32, name: string, id: i32, description: string): i32 {
397
461
  const call = `command(${name})`
@@ -408,7 +472,15 @@ export class Cli {
408
472
  return handle
409
473
  }
410
474
 
411
- /** Another name for the command or group `handle`, in the same scope. */
475
+ /**
476
+ * Another name for the command or group `handle`, in the same scope.
477
+ *
478
+ * @param handle the command or group the alias names; panics on `ROOT`
479
+ * or a handle no declaration answered
480
+ * @param name the other word, which the parent's help lists beside the
481
+ * first; panics when it is not a command name or is already a name in
482
+ * that scope
483
+ */
412
484
  alias(handle: i32, name: string): void {
413
485
  const call = `alias(${name})`
414
486
  const h = this.checkCommand(call, handle)
@@ -429,13 +501,13 @@ export class Cli {
429
501
  }
430
502
 
431
503
  /** Whether a flag of `scope` (a command, or `GLOBAL`) answers to `key`, as itself or as a negation. */
432
- taken(scope: i32, key: string): boolean {
504
+ private taken(scope: i32, key: string): boolean {
433
505
  const k = scopeKey(scope, key)
434
506
  return this.flags.has(k) || this.negations.has(k)
435
507
  }
436
508
 
437
509
  /** Whether `scope` already answers to any of `--long`, its negation (for `--no-x`), or `-short`. */
438
- scopeHas(scope: i32, spec: FlagSpec): boolean {
510
+ private scopeHas(scope: i32, spec: FlagSpec): boolean {
439
511
  if (this.taken(scope, `--${spec.long}`) || (spec.negated && this.taken(scope, `--no-${spec.long}`))) {
440
512
  return true
441
513
  }
@@ -443,12 +515,12 @@ export class Cli {
443
515
  }
444
516
 
445
517
  /** Whether flag `f` answers to `--name`, as itself or, negatable, as its negation. */
446
- answersTo(f: i32, name: string): boolean {
518
+ private answersTo(f: i32, name: string): boolean {
447
519
  return this.flagLong[f] === name || (this.flagNegatable[f] && `no-${this.flagLong[f]}` === name)
448
520
  }
449
521
 
450
522
  /** A new flag in `scope` from `spec`; `call` names the declaration in a panic. */
451
- addFlag(call: string, scope: i32, spec: string, description: string): i32 {
523
+ private addFlag(call: string, scope: i32, spec: string, description: string): i32 {
452
524
  const s = new FlagSpec(call, spec)
453
525
  if (s.long === "help" || s.long === "version" || s.short === "h" || s.short === "v") {
454
526
  panic(`cli-args: ${call}: -h, --help, -v and --version are taken`)
@@ -497,18 +569,50 @@ export class Cli {
497
569
  return handle
498
570
  }
499
571
 
500
- /** A flag every command takes, before, between or after the command names. */
572
+ /**
573
+ * A flag every command takes, before, between or after the command names.
574
+ *
575
+ * @param spec the flag as the help writes it: `--name`, optionally after
576
+ * `-x, ` for a one-letter short form, optionally followed by ` <value>`
577
+ * (required) or ` [value]` (optional); `--no-x` with no value is a flag
578
+ * that is on until given. Panics on a malformed spec, on `-h`, `--help`,
579
+ * `-v` or `--version`, and on a name any flag already answers to
580
+ * @param description the flag's line in the `Global flags` help section
581
+ * @returns the flag's handle, for `ParseResult.flag`, `value`, `values`
582
+ * and `source`, and for `defaultValue`, `required`, `repeatable` and
583
+ * `negatable`
584
+ */
501
585
  globalFlag(spec: string, description: string): i32 {
502
586
  return this.addFlag(`globalFlag("${spec}")`, GLOBAL, spec, description)
503
587
  }
504
588
 
505
- /** A flag the command or group `cmd` takes, and no other. */
589
+ /**
590
+ * A flag the command or group `cmd` takes, and no other.
591
+ *
592
+ * @param cmd the handle of the command or group (or `ROOT`) that owns the
593
+ * flag; the flag is unknown everywhere else in the tree
594
+ * @param spec the flag as the help writes it, in `globalFlag`'s syntax;
595
+ * panics on a malformed spec, on `-h`, `--help`, `-v` or `--version`,
596
+ * and on a name `cmd` or a global flag already answers to
597
+ * @param description the flag's line in `cmd`'s `Flags` help section
598
+ * @returns the flag's handle, for `ParseResult.flag`, `value`, `values`
599
+ * and `source`, and for `defaultValue`, `required`, `repeatable` and
600
+ * `negatable`
601
+ */
506
602
  flag(cmd: i32, spec: string, description: string): i32 {
507
603
  const call = `flag("${spec}")`
508
604
  return this.addFlag(call, this.checkCommand(call, cmd), spec, description)
509
605
  }
510
606
 
511
- /** The value flag `f` answers when it is not given. */
607
+ /**
608
+ * The value flag `f` answers when it is not given.
609
+ *
610
+ * @param f the handle of a flag that takes a value; panics on one that
611
+ * takes none or is required
612
+ * @param value what `value` and `values` answer when the arguments do not
613
+ * give the flag, and what its help row shows as `(default: …)`; a later
614
+ * call replaces an earlier one
615
+ */
512
616
  defaultValue(f: i32, value: string): void {
513
617
  const call = `defaultValue(${value})`
514
618
  const h = this.checkFlag(call, f)
@@ -525,6 +629,9 @@ export class Cli {
525
629
  /**
526
630
  * Makes `f` an error to leave out, for the command that owns it (every
527
631
  * command, for a global); a group's flag cannot be, as no parse ends at one.
632
+ *
633
+ * @param f the handle of the flag; panics on a group's flag or one with a
634
+ * default. Calling it twice is the same as once
528
635
  */
529
636
  required(f: i32): void {
530
637
  const h = this.checkFlag("required", f)
@@ -547,7 +654,13 @@ export class Cli {
547
654
  }
548
655
  }
549
656
 
550
- /** Makes `f` gather every value it is given, in order, for `ParseResult.values`. */
657
+ /**
658
+ * Makes `f` gather every value it is given, in order, for
659
+ * `ParseResult.values`.
660
+ *
661
+ * @param f the handle of a flag that takes a value; panics on one that
662
+ * takes none
663
+ */
551
664
  repeatable(f: i32): void {
552
665
  const h = this.checkFlag("repeatable", f)
553
666
  if (this.flagValue[h] === VALUE_NONE) {
@@ -556,7 +669,13 @@ export class Cli {
556
669
  this.flagRepeatable[h] = true
557
670
  }
558
671
 
559
- /** Adds `--no-x` to the boolean flag `--x`, which turns it back off. */
672
+ /**
673
+ * Adds `--no-x` to the boolean flag `--x`, which turns it back off.
674
+ *
675
+ * @param f the handle of a flag declared `--x` with no value; panics on a
676
+ * flag that takes a value, one declared `--no-x`, or when `--no-x` is
677
+ * already a name a flag in its reach answers to
678
+ */
560
679
  negatable(f: i32): void {
561
680
  const h = this.checkFlag("negatable", f)
562
681
  const call = `negatable(--${this.flagLong[h]})`
@@ -579,6 +698,16 @@ export class Cli {
579
698
  /**
580
699
  * A positional argument of the command `cmd`: `<name>` required, `[name]`
581
700
  * optional, `<name...>` or `[name...]` taking every one left, last only.
701
+ *
702
+ * @param cmd the handle of the command that takes the argument; panics on
703
+ * a group, or on the root once it holds commands
704
+ * @param spec the argument as the help writes it, one of the four forms
705
+ * above; panics on a malformed one, on any argument after a variadic one,
706
+ * and on a required one after an optional one
707
+ * @param description the argument's line in `cmd`'s `Arguments` help
708
+ * section
709
+ * @returns the argument's handle, for `ParseResult.positional` and
710
+ * `positionals`
582
711
  */
583
712
  argument(cmd: i32, spec: string, description: string): i32 {
584
713
  const call = `argument("${spec}")`
@@ -626,7 +755,14 @@ export class Cli {
626
755
  return handle
627
756
  }
628
757
 
629
- /** Text shown at the end of the help of `handle` (a command or group), as given. */
758
+ /**
759
+ * Text shown at the end of the help of `handle` (a command or group), as
760
+ * given.
761
+ *
762
+ * @param handle the command or group (or `ROOT`) whose help ends with it
763
+ * @param text what follows a blank line after the last row; empty for
764
+ * none, and a later call replaces an earlier one
765
+ */
630
766
  epilog(handle: i32, text: string): void {
631
767
  const h = this.checkCommand("epilog", handle)
632
768
  this.cmdEpilog[h] = text
@@ -636,19 +772,19 @@ export class Cli {
636
772
  * The flag `name` (dashes included) names in `table` at `cmd`: its own, then
637
773
  * a global; -1 for none. `table` is `flags`, or `negations` for `--no-x`.
638
774
  */
639
- lookup(table: Map<string, i32>, cmd: i32, name: string): i32 {
775
+ private lookup(table: Map<string, i32>, cmd: i32, name: string): i32 {
640
776
  const own = table.get(scopeKey(cmd, name)) ?? -1
641
777
  return own >= 0 ? own : (table.get(scopeKey(GLOBAL, name)) ?? -1)
642
778
  }
643
779
 
644
- /** How `f` is spelled on the command line: its long name, or `--no-x` for one declared that way. */
780
+ /** @internal Called by `ParseResult`. How `f` is spelled on the command line: its long name, or `--no-x` for one declared that way. */
645
781
  spelling(f: i32): string {
646
782
  const h = this.checkFlag("spelling", f)
647
783
  return this.flagNegated[h] ? `--no-${this.flagLong[h]}` : `--${this.flagLong[h]}`
648
784
  }
649
785
 
650
786
  /** Every long flag `cmd` answers to, for a did-you-mean. */
651
- longNames(cmd: i32): string[] {
787
+ private longNames(cmd: i32): string[] {
652
788
  const names: string[] = []
653
789
  for (let f: i32 = 0; f < toI32(this.flagLong.length); f++) {
654
790
  if (this.flagOwner[f] === cmd || this.flagOwner[f] === GLOBAL) {
@@ -665,7 +801,7 @@ export class Cli {
665
801
  return names
666
802
  }
667
803
 
668
- /** The names `cmd`'s children answer to, in declaration order, then their aliases when `withAliases`. */
804
+ /** @internal Called by `ParseResult`. The names `cmd`'s children answer to, in declaration order, then their aliases when `withAliases`. */
669
805
  childNames(cmd: i32, withAliases: boolean): string[] {
670
806
  const names: string[] = []
671
807
  for (let c: i32 = 0; c < toI32(this.cmdName.length); c++) {
@@ -689,6 +825,14 @@ export class Cli {
689
825
  /**
690
826
  * Parses `argv` from index `start` (1 for `process.argv`, past the
691
827
  * program's path) in one walk over it.
828
+ *
829
+ * @param argv the command line's words, which are only read
830
+ * @param start how many leading words of `argv` to skip; a negative one
831
+ * skips none, and one at or past the end reads nothing, which at a root
832
+ * with commands is a missing-command error
833
+ * @returns a fresh answer the caller owns, holding this tree to read its
834
+ * values by handle; a usage error is its `PARSE_ERROR` kind, never a
835
+ * panic
692
836
  */
693
837
  parse(argv: string[], start: i32): ParseResult {
694
838
  const r = new ParseResult(this)
@@ -723,7 +867,7 @@ export class Cli {
723
867
  }
724
868
 
725
869
  /** Records `token` as no command `r`'s group holds, with the nearest one that it does. */
726
- unknownCommand(r: ParseResult, token: string): void {
870
+ private unknownCommand(r: ParseResult, token: string): void {
727
871
  const near = closest(token, this.childNames(r.command, true))
728
872
  r.badCommand = true
729
873
  r.fail(
@@ -733,7 +877,7 @@ export class Cli {
733
877
  }
734
878
 
735
879
  /** Records `--name`, `--name=value`, `--name value` or `--no-name` from `token`; answers the next index. */
736
- longFlag(r: ParseResult, argv: string[], next: i32, token: string): i32 {
880
+ private longFlag(r: ParseResult, argv: string[], next: i32, token: string): i32 {
737
881
  const eq: i32 = toI32(token.indexOf("="))
738
882
  const name = eq < 0 ? token : token.substring(0, eq)
739
883
  if (name === "--help") {
@@ -774,7 +918,7 @@ export class Cli {
774
918
  }
775
919
 
776
920
  /** Records the cluster `-abc` (or `-l5`, `-l=5`, `-l 5`) from `token`; answers the next index. */
777
- shortFlags(r: ParseResult, argv: string[], next: i32, token: string): i32 {
921
+ private shortFlags(r: ParseResult, argv: string[], next: i32, token: string): i32 {
778
922
  for (let k: i32 = 1; k < toI32(token.length); k++) {
779
923
  const letter = token.substring(k, k + 1)
780
924
  if (letter === "h") {
@@ -810,7 +954,7 @@ export class Cli {
810
954
  * not empty, or else the token at `next` when the flag's value takes it;
811
955
  * answers the index after whatever it took.
812
956
  */
813
- takeValue(r: ParseResult, argv: string[], next: i32, f: i32, attached: string): i32 {
957
+ private takeValue(r: ParseResult, argv: string[], next: i32, f: i32, attached: string): i32 {
814
958
  const kind: i32 = this.flagValue[f]
815
959
  if (kind === VALUE_NONE) {
816
960
  r.set(f, "true")
@@ -838,13 +982,13 @@ export class Cli {
838
982
  }
839
983
 
840
984
  /** A help row's flag column for `f`: `-s, --long`, with `--[no-]x` for a negatable one. */
841
- flagLabel(f: i32): string {
985
+ private flagLabel(f: i32): string {
842
986
  const long = this.flagNegatable[f] ? `--[no-]${this.flagLong[f]}` : this.spelling(f)
843
987
  return this.flagShort[f].length > 0 ? `-${this.flagShort[f]}, ${long}` : long
844
988
  }
845
989
 
846
990
  /** A help row's description for `f`, with what it is: repeatable, its default, required. */
847
- flagText(f: i32): string {
991
+ private flagText(f: i32): string {
848
992
  let text = this.flagDesc[f]
849
993
  if (this.flagRepeatable[f]) {
850
994
  text = `${text} (repeatable)`
@@ -859,7 +1003,7 @@ export class Cli {
859
1003
  }
860
1004
 
861
1005
  /** Adds a `section` row to `rows` for every flag `owner` (a command, or `GLOBAL`) declares. */
862
- flagRows(rows: HelpRow[], section: string, owner: i32): void {
1006
+ private flagRows(rows: HelpRow[], section: string, owner: i32): void {
863
1007
  for (let f: i32 = 0; f < toI32(this.flagLong.length); f++) {
864
1008
  if (this.flagOwner[f] === owner) {
865
1009
  rows.push(new HelpRow(section, this.flagLabel(f), this.flagMeta[f], this.flagText(f)))
@@ -867,7 +1011,15 @@ export class Cli {
867
1011
  }
868
1012
  }
869
1013
 
870
- /** The help of the command or group `handle`, painted with `style`. */
1014
+ /**
1015
+ * The help of the command or group `handle`, painted with `style`.
1016
+ *
1017
+ * @param handle the command or group (or `ROOT`) whose help it is; panics
1018
+ * on a handle no declaration answered
1019
+ * @param style how the help's names and headings are painted; a style
1020
+ * that is off gives plain text
1021
+ * @returns a fresh string, the whole page, built on each call
1022
+ */
871
1023
  helpText(handle: i32, style: Style): string {
872
1024
  const cmd = this.checkCommand("help", handle)
873
1025
  const rows: HelpRow[] = []
@@ -931,9 +1083,13 @@ export class Cli {
931
1083
 
932
1084
  /** One row of a help page, kept until the widest row sets the column. */
933
1085
  class HelpRow {
1086
+ /** @internal Used by `Cli`. */
934
1087
  section: string
1088
+ /** @internal Used by `Cli`. */
935
1089
  label: string
1090
+ /** @internal Used by `Cli`. */
936
1091
  meta: string
1092
+ /** @internal Used by `Cli`. */
937
1093
  text: string
938
1094
 
939
1095
  constructor(section: string, label: string, meta: string, text: string) {
@@ -950,7 +1106,7 @@ class HelpRow {
950
1106
  * them. Values are read by the handles the tree was declared with.
951
1107
  */
952
1108
  export class ParseResult {
953
- cli: Cli
1109
+ private cli: Cli
954
1110
  /** The command line that names it: `api users keys list`. */
955
1111
  path: string
956
1112
  /** The error line for `PARSE_ERROR`, the version line for `PARSE_VERSION`, else empty. */
@@ -959,9 +1115,11 @@ export class ParseResult {
959
1115
  hint: string
960
1116
  /** The command line of the command an error was found at; empty without one. */
961
1117
  errorPath: string
962
- setFlags: i32[]
963
- setValues: string[]
1118
+ private setFlags: i32[]
1119
+ private setValues: string[]
1120
+ /** @internal Used by `Cli`. */
964
1121
  positionalValues: string[]
1122
+ /** @internal Used by `Cli`. */
965
1123
  restValues: string[]
966
1124
  /** `PARSE_OK`, `PARSE_HELP`, `PARSE_VERSION` or `PARSE_ERROR`. */
967
1125
  kind: i32
@@ -971,13 +1129,23 @@ export class ParseResult {
971
1129
  id: i32
972
1130
  /** The status to exit with: 2 for an error, 0 otherwise. */
973
1131
  exitCode: i32
1132
+ /** @internal Used by `Cli`. */
974
1133
  wantHelp: boolean
975
- /** Whether help was asked for by the word `help`, which a path follows. */
1134
+ /** @internal Used by `Cli`. Whether help was asked for by the word `help`, which a path follows. */
976
1135
  helpWord: boolean
977
- /** Whether a word named no command, which `help <path>` does not forgive. */
1136
+ /** @internal Used by `Cli`. Whether a word named no command, which `help <path>` does not forgive. */
978
1137
  badCommand: boolean
1138
+ /** @internal Used by `Cli`. */
979
1139
  wantVersion: boolean
980
1140
 
1141
+ /**
1142
+ * An answer that has read nothing: kind `PARSE_OK` at `ROOT` with no
1143
+ * values. `Cli.parse` makes one and fills it in; a program gets its
1144
+ * answer from there rather than building one.
1145
+ *
1146
+ * @param cli the tree the answer's handles belong to; it is kept, not
1147
+ * copied
1148
+ */
981
1149
  constructor(cli: Cli) {
982
1150
  this.cli = cli
983
1151
  this.kind = PARSE_OK
@@ -999,7 +1167,7 @@ export class ParseResult {
999
1167
  this.restValues = []
1000
1168
  }
1001
1169
 
1002
- /** Records `text` as the error found at `cmd`, unless one is already recorded: the first wins. */
1170
+ /** @internal Called by `Cli`. Records `text` as the error found at `cmd`, unless one is already recorded: the first wins. */
1003
1171
  fail(cmd: i32, text: string): void {
1004
1172
  if (this.message.length === 0) {
1005
1173
  this.errorPath = this.cli.pathOf(cmd)
@@ -1008,13 +1176,14 @@ export class ParseResult {
1008
1176
  }
1009
1177
  }
1010
1178
 
1011
- /** Records flag `f` as given `value`. */
1179
+ /** @internal Called by `Cli`. Records flag `f` as given `value`. */
1012
1180
  set(f: i32, value: string): void {
1013
1181
  this.setFlags.push(f)
1014
1182
  this.setValues.push(value)
1015
1183
  }
1016
1184
 
1017
1185
  /**
1186
+ * @internal Called by `Cli`.
1018
1187
  * Settles the kind once the walk is over: help (unless `help <path>` named
1019
1188
  * no command), then the version, then an error, then the checks only a
1020
1189
  * whole command line can fail.
@@ -1070,7 +1239,7 @@ export class ParseResult {
1070
1239
  }
1071
1240
 
1072
1241
  /** The first of the `required` flags the arguments did not set, else -1. */
1073
- firstMissing(required: i32[]): i32 {
1242
+ private firstMissing(required: i32[]): i32 {
1074
1243
  for (let i: i32 = 0; i < toI32(required.length); i++) {
1075
1244
  if (this.lastSet(required[i]) < 0) {
1076
1245
  return required[i]
@@ -1083,7 +1252,7 @@ export class ParseResult {
1083
1252
  * Where the last value of flag `f` is in `setValues`, or -1 when it was not
1084
1253
  * given: a scan of the flags the arguments set, so bounded by their count.
1085
1254
  */
1086
- lastSet(f: i32): i32 {
1255
+ private lastSet(f: i32): i32 {
1087
1256
  for (let i: i32 = toI32(this.setFlags.length) - 1; i >= 0 && i < toI32(this.setFlags.length); i--) {
1088
1257
  if (this.setFlags[i] === f) {
1089
1258
  return i
@@ -1095,6 +1264,11 @@ export class ParseResult {
1095
1264
  /**
1096
1265
  * Whether flag `f` is on: a boolean's value (true by default for one
1097
1266
  * declared `--no-x`), or for a flag with a value, whether it was given.
1267
+ *
1268
+ * @param f the handle of a flag anywhere in the tree; panics on a handle
1269
+ * no declaration answered
1270
+ * @returns the last of the arguments' settings for a boolean, so
1271
+ * `--x --no-x` is off
1098
1272
  */
1099
1273
  flag(f: i32): boolean {
1100
1274
  const h = this.cli.checkFlag("flag", f)
@@ -1111,6 +1285,11 @@ export class ParseResult {
1111
1285
  /**
1112
1286
  * The value of flag `f`: the last one given (empty for `[value]` given
1113
1287
  * none), else its default, else null.
1288
+ *
1289
+ * @param f the handle of a flag anywhere in the tree; panics on a handle
1290
+ * no declaration answered
1291
+ * @returns the value as written, or `"true"` or `"false"` for a boolean
1292
+ * that was given; null tells a flag never given and with no default
1114
1293
  */
1115
1294
  value(f: i32): string | null {
1116
1295
  const h = this.cli.checkFlag("value", f)
@@ -1124,6 +1303,10 @@ export class ParseResult {
1124
1303
  /**
1125
1304
  * Every value of flag `f` in order for a repeatable one, the last alone
1126
1305
  * for any other, else its default alone, else none.
1306
+ *
1307
+ * @param f the handle of a flag anywhere in the tree; panics on a handle
1308
+ * no declaration answered
1309
+ * @returns a fresh array the caller owns
1127
1310
  */
1128
1311
  values(f: i32): string[] {
1129
1312
  const h = this.cli.checkFlag("values", f)
@@ -1146,7 +1329,16 @@ export class ParseResult {
1146
1329
  return out
1147
1330
  }
1148
1331
 
1149
- /** Where flag `f`'s value came from: `SOURCE_ARGV`, `SOURCE_DEFAULT` or `SOURCE_UNSET`. */
1332
+ /**
1333
+ * Where flag `f`'s value came from: `SOURCE_ARGV`, `SOURCE_DEFAULT` or
1334
+ * `SOURCE_UNSET`.
1335
+ *
1336
+ * @param f the handle of a flag anywhere in the tree; panics on a handle
1337
+ * no declaration answered
1338
+ * @returns `SOURCE_ARGV` when the arguments gave it, `SOURCE_DEFAULT` when
1339
+ * it has a default or is declared `--no-x` (on by default), else
1340
+ * `SOURCE_UNSET`
1341
+ */
1150
1342
  source(f: i32): i32 {
1151
1343
  const h = this.cli.checkFlag("source", f)
1152
1344
  if (this.lastSet(h) >= 0) {
@@ -1155,7 +1347,15 @@ export class ParseResult {
1155
1347
  return this.cli.flagHasDefault[h] || this.cli.flagNegated[h] ? SOURCE_DEFAULT : SOURCE_UNSET
1156
1348
  }
1157
1349
 
1158
- /** The argument `a`'s value, or null when it was not given or belongs to another command. */
1350
+ /**
1351
+ * The argument `a`'s value, or null when it was not given or belongs to
1352
+ * another command.
1353
+ *
1354
+ * @param a the handle of an argument; panics on a handle no `argument`
1355
+ * call answered
1356
+ * @returns the word at the argument's place among the positionals, which
1357
+ * for a variadic one is the first it took
1358
+ */
1159
1359
  positional(a: i32): string | null {
1160
1360
  const h = this.cli.checkArgument("positional", a)
1161
1361
  const k: i32 = this.cli.argIndex[h]
@@ -1165,7 +1365,15 @@ export class ParseResult {
1165
1365
  return this.positionalValues[k]
1166
1366
  }
1167
1367
 
1168
- /** Every value from argument `a` on: all a variadic one took, or the one value of any other. */
1368
+ /**
1369
+ * Every value from argument `a` on: all a variadic one took, or the one
1370
+ * value of any other.
1371
+ *
1372
+ * @param a the handle of an argument; panics on a handle no `argument`
1373
+ * call answered
1374
+ * @returns a fresh array the caller owns; empty when the argument was not
1375
+ * given or belongs to another command
1376
+ */
1169
1377
  positionals(a: i32): string[] {
1170
1378
  const h = this.cli.checkArgument("positionals", a)
1171
1379
  const out: string[] = []
@@ -1180,12 +1388,24 @@ export class ParseResult {
1180
1388
  return out
1181
1389
  }
1182
1390
 
1183
- /** The tokens after `--`, in order. */
1391
+ /**
1392
+ * The tokens after `--`, in order. They are positionals too, so an
1393
+ * argument may also have taken them.
1394
+ *
1395
+ * @returns the answer's own array, not a copy: a change to it is seen by
1396
+ * every later `rest` call
1397
+ */
1184
1398
  rest(): string[] {
1185
1399
  return this.restValues
1186
1400
  }
1187
1401
 
1188
- /** The help of the command the arguments reached, painted with `style`. */
1402
+ /**
1403
+ * The help of the command the arguments reached, painted with `style`.
1404
+ *
1405
+ * @param style how the help's names and headings are painted; a style
1406
+ * that is off gives plain text
1407
+ * @returns a fresh string, the whole page, built on each call
1408
+ */
1189
1409
  help(style: Style): string {
1190
1410
  return this.cli.helpText(this.command, style)
1191
1411
  }
@@ -1199,6 +1419,12 @@ const usageHint = (command: string): string => `Run '${command}' for usage.`
1199
1419
  * standard output and exit 0; an error line and the hint on standard error
1200
1420
  * and exit 2, the hint's command painted with `errStyle`, the error never;
1201
1421
  * answers 0 for `PARSE_OK`, which the program goes on to run.
1422
+ *
1423
+ * @param r the answer of `Cli.parse`
1424
+ * @param outStyle how help on standard output is painted
1425
+ * @param errStyle how the hint's `<path> --help` on standard error is
1426
+ * painted
1427
+ * @returns 0, and only for `PARSE_OK`: every other kind exits instead
1202
1428
  */
1203
1429
  export const finish = (r: ParseResult, outStyle: Style, errStyle: Style): i32 => {
1204
1430
  if (r.kind === PARSE_HELP) {