@songtonyli/dsh-cli 0.1.85 → 0.1.86

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.
@@ -17,17 +17,21 @@
17
17
  * [Install](#install)
18
18
  * [Use](#use)
19
19
  * [API](#api)
20
- * [`visitParents(tree[, test], visitor[, reverse])`](#visitparentstree-test-visitor-reverse)
20
+ * [`visitParents(tree[, test], enter|visitors[, reverse])`](#visitparentstree-test-entervisitors-reverse)
21
21
  * [`CONTINUE`](#continue)
22
22
  * [`EXIT`](#exit)
23
23
  * [`SKIP`](#skip)
24
24
  * [`Action`](#action)
25
25
  * [`ActionTuple`](#actiontuple)
26
26
  * [`BuildVisitor`](#buildvisitor)
27
+ * [`BuildVisitors`](#buildvisitors)
27
28
  * [`Index`](#index)
28
29
  * [`Test`](#test)
29
30
  * [`Visitor`](#visitor)
31
+ * [`VisitorExit`](#visitorexit)
30
32
  * [`VisitorResult`](#visitorresult)
33
+ * [`VisitorResultExit`](#visitorresultexit)
34
+ * [`Visitors`](#visitors)
31
35
  * [Types](#types)
32
36
  * [Compatibility](#compatibility)
33
37
  * [Related](#related)
@@ -94,16 +98,18 @@ This package exports the identifiers [`CONTINUE`][api-continue],
94
98
  [`EXIT`][api-exit], [`SKIP`][api-skip], and [`visitParents`][api-visitparents].
95
99
  There is no default export.
96
100
 
97
- ### `visitParents(tree[, test], visitor[, reverse])`
101
+ ### `visitParents(tree[, test], enter|visitors[, reverse])`
98
102
 
99
103
  Visit nodes, with ancestral information.
100
104
 
101
105
  This algorithm performs *[depth-first][]* *[tree traversal][tree-traversal]*
102
- in *[preorder][]* (**NLR**) or if `reverse` is given, in *reverse preorder*
103
- (**NRL**).
106
+ in *[preorder][]* (**NLR**) or if `reverse` is given,
107
+ in *reverse preorder* (**NRL**).
108
+ An [`exit`][api-visitors] visitor is called in *[postorder][]* (**LRN**)
109
+ or if `reverse` is given, in *reverse postorder* (**RLN**).
104
110
 
105
- You can choose for which nodes `visitor` is called by passing a `test`.
106
- For complex tests, you should test yourself in `visitor`, as it will be
111
+ You can choose which nodes are visited by passing a `test`.
112
+ For complex tests, you should test yourself in a visitor, as it will be
107
113
  faster and will have improved type information.
108
114
 
109
115
  Walking the tree is an intensive task.
@@ -113,7 +119,15 @@ Instead of walking a tree multiple times, walk it once, use
113
119
  different operations.
114
120
 
115
121
  You can change the tree.
116
- See [`Visitor`][api-visitor] for more info.
122
+ Changes inside a node made when entering it are walked,
123
+ changes made when exiting it are not.
124
+ See [`Visitor`][api-visitor] and [`VisitorExit`][api-visitorexit] for more
125
+ info.
126
+
127
+ ###### Signatures
128
+
129
+ * `visitParents(tree[, test], enter[, reverse])`
130
+ * `visitParents(tree[, test], visitors[, reverse])`
117
131
 
118
132
  ###### Parameters
119
133
 
@@ -121,10 +135,15 @@ See [`Visitor`][api-visitor] for more info.
121
135
  — tree to traverse
122
136
  * `test` ([`Test`][api-test], optional)
123
137
  — [`unist-util-is`][unist-util-is]-compatible test
124
- * `visitor` ([`Visitor`][api-visitor])
125
- — handle each node
138
+ * `enter` ([`Visitor`][api-visitor])
139
+ — handle each node when entering it
140
+ * `visitors` ([`Visitors`][api-visitors])
141
+ — handle each node when exiting it,
142
+ and optionally when entering it
126
143
  * `reverse` (`boolean`, default: `false`)
127
- — traverse in reverse preorder (NRL) instead of the default preorder (NLR)
144
+ — walk children from last to first;
145
+ for `enter`, reverse preorder (NRL) instead of preorder (NLR);
146
+ for `exit`, reverse postorder (RLN) instead of postorder (LRN)
128
147
 
129
148
  ###### Returns
130
149
 
@@ -141,6 +160,7 @@ Stop traversing immediately (`false`).
141
160
  ### `SKIP`
142
161
 
143
162
  Do not traverse this node’s children (`'skip'`).
163
+ Only works when entering a node.
144
164
 
145
165
  ### `Action`
146
166
 
@@ -183,6 +203,24 @@ It will infer which values are passed as `node` and which as `parents`.
183
203
 
184
204
  [`Visitor`][api-visitor].
185
205
 
206
+ ### `BuildVisitors`
207
+
208
+ Build typed [`Visitors`][api-visitors] from a tree and a test (TypeScript
209
+ type).
210
+
211
+ It will infer which values are passed as `node` and which as `parents`.
212
+
213
+ ###### Type parameters
214
+
215
+ * `Tree` ([`Node`][node], default: `Node`)
216
+ — tree type
217
+ * `Check` ([`Test`][api-test], default: `Test`)
218
+ — test type
219
+
220
+ ###### Returns
221
+
222
+ [`Visitors`][api-visitors].
223
+
186
224
  ### `Index`
187
225
 
188
226
  Move to the sibling at `index` next (after node itself is completely
@@ -205,22 +243,45 @@ type Index = number
205
243
 
206
244
  ### `Visitor`
207
245
 
208
- Handle a node (matching `test`, if given) (TypeScript type).
246
+ Handle a node (matching `test`, if given) before its children (TypeScript
247
+ type).
209
248
 
210
- Visitors are free to transform `node`.
211
- They can also transform the parent of node (the last of `ancestors`).
249
+ Changes inside `node` are walked next.
250
+ Replacing or removing it is easier in `exit`.
251
+ When replacing or removing it here,
252
+ return `SKIP` (as otherwise its old children are walked),
253
+ or `[SKIP, index]` to continue with the node now at `index`.
254
+ Changing next siblings (in walk order) is fine;
255
+ changing previous siblings needs a new `Index`.
256
+ Removing an ancestor or changing its previous siblings is not supported.
212
257
 
213
- Replacing `node` itself, if `SKIP` is not returned, still causes its
214
- descendants to be walked (which is a bug).
258
+ ###### Parameters
259
+
260
+ * `node` ([`Node`][node])
261
+ — found node
262
+ * `parents` ([`Array<Node>`][node])
263
+ — ancestors of `node`
264
+ * `index` (`number` or `undefined`)
265
+ — index of `node` in its parent (the last of `parents`),
266
+ or `undefined` for the tree itself
267
+
268
+ ###### Returns
215
269
 
216
- When adding or removing previous siblings of `node` (or next siblings, in
217
- case of reverse), the `Visitor` should return a new `Index` to specify the
218
- sibling to traverse after `node` is traversed.
219
- Adding or removing next siblings of `node` (or previous siblings, in case
220
- of reverse) is handled as expected without needing to return a new `Index`.
270
+ What to do next ([`VisitorResult`][api-visitorresult]).
221
271
 
222
- Removing the children property of an ancestor still results in them being
223
- traversed.
272
+ Passing a tuple back ([`ActionTuple`][api-actiontuple]) only makes sense as
273
+ `[SKIP, Index]`.
274
+
275
+ ### `VisitorExit`
276
+
277
+ Handle a node (matching `test`, if given) after its children (TypeScript type).
278
+
279
+ Changes inside `node` are not walked,
280
+ which makes this a good place to change `node` based on its children,
281
+ or to replace or remove it.
282
+ When removing `node` or changing previous siblings (in walk order),
283
+ return a new `Index`.
284
+ Removing an ancestor or changing its previous siblings is not supported.
224
285
 
225
286
  ###### Parameters
226
287
 
@@ -228,21 +289,26 @@ traversed.
228
289
  — found node
229
290
  * `parents` ([`Array<Node>`][node])
230
291
  — ancestors of `node`
292
+ * `index` (`number` or `undefined`)
293
+ — index of `node` in its parent (the last of `parents`),
294
+ or `undefined` for the tree itself
231
295
 
232
296
  ###### Returns
233
297
 
234
- What to do next.
235
-
236
- An `Index` is treated as a tuple of `[CONTINUE, Index]`.
237
- An `Action` is treated as a tuple of `[Action]`.
298
+ What to do next ([`VisitorResultExit`][api-visitorresultexit]).
238
299
 
239
- Passing a tuple back only makes sense if the `Action` is `SKIP`.
240
- When the `Action` is `EXIT`, that action can be returned.
241
- When the `Action` is `CONTINUE`, `Index` can be returned.
300
+ `CONTINUE` (`true`, nothing) continues as normal,
301
+ `EXIT` (`false`) stops traversing,
302
+ and `Index` continues at that sibling.
242
303
 
243
304
  ### `VisitorResult`
244
305
 
245
- Any value that can be returned from a visitor (TypeScript type).
306
+ Any value that can be returned from an enter visitor (TypeScript type).
307
+
308
+ Like [`VisitorResultExit`][api-visitorresultexit] but `SKIP` can be returned to
309
+ not walk children of the node,
310
+ and [`ActionTuple`][api-actiontuple] can be used to combine an action with an
311
+ index.
246
312
 
247
313
  ###### Type
248
314
 
@@ -256,13 +322,48 @@ type VisitorResult =
256
322
  | void
257
323
  ```
258
324
 
325
+ ### `VisitorResultExit`
326
+
327
+ Any value that can be returned from an exit visitor (TypeScript type).
328
+
329
+ ###### Type
330
+
331
+ ```ts
332
+ type VisitorResultExit = Index | boolean | null | undefined | void
333
+ ```
334
+
335
+ ### `Visitors`
336
+
337
+ Handle nodes when entering and exiting them (TypeScript type).
338
+ The `enter` visitor is optional while `exit` is required.
339
+
340
+ Pass an `enter` visitor directly to only handle nodes when entering them.
341
+
342
+ `enter` is called before children (if any) are walked and `exit` after that.
343
+ `exit` is still called when `enter` returns `SKIP`.
344
+ Both `enter` and `exit` are only called for nodes that match an optional `test`.
345
+
346
+ ###### Fields
347
+
348
+ * `enter` ([`Visitor`][api-visitor], optional)
349
+ — handle a node before its children
350
+ * `exit` ([`VisitorExit`][api-visitorexit])
351
+ — handle a node after its children
352
+
259
353
  ## Types
260
354
 
261
355
  This package is fully typed with [TypeScript][].
262
356
  It exports the additional types [`Action`][api-action],
263
- [`ActionTuple`][api-actiontuple], [`BuildVisitor`][api-buildvisitor],
264
- [`Index`][api-index], [`Test`][api-test], [`Visitor`][api-visitor], and
265
- [`VisitorResult`][api-visitorresult].
357
+ [`ActionTuple`][api-actiontuple],
358
+ [`BuildVisitor`][api-buildvisitor],
359
+ [`BuildVisitors`][api-buildvisitors],
360
+ [`Index`][api-index],
361
+ [`Test`][api-test],
362
+ [`Visitor`][api-visitor],
363
+ [`VisitorExit`][api-visitorexit],
364
+ [`VisitorResult`][api-visitorresult],
365
+ [`VisitorResultExit`][api-visitorresultexit], and
366
+ [`Visitors`][api-visitors].
266
367
 
267
368
  ## Compatibility
268
369
 
@@ -276,7 +377,7 @@ This means we try to keep the current release line,
276
377
 
277
378
  ## Related
278
379
 
279
- * [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
380
+ * [`unist-util-visit`][unist-util-visit]
280
381
  — walk the tree with one parent
281
382
  * [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter)
282
383
  — create a new tree with all nodes that pass a test
@@ -305,84 +406,94 @@ abide by its terms.
305
406
 
306
407
  <!-- Definition -->
307
408
 
308
- [build-badge]: https://github.com/syntax-tree/unist-util-visit-parents/workflows/main/badge.svg
409
+ [api-action]: #action
309
410
 
310
- [build]: https://github.com/syntax-tree/unist-util-visit-parents/actions
411
+ [api-actiontuple]: #actiontuple
311
412
 
312
- [coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-visit-parents.svg
413
+ [api-buildvisitor]: #buildvisitor
313
414
 
314
- [coverage]: https://codecov.io/github/syntax-tree/unist-util-visit-parents
415
+ [api-buildvisitors]: #buildvisitors
315
416
 
316
- [downloads-badge]: https://img.shields.io/npm/dm/unist-util-visit-parents.svg
417
+ [api-continue]: #continue
317
418
 
318
- [downloads]: https://www.npmjs.com/package/unist-util-visit-parents
419
+ [api-exit]: #exit
319
420
 
320
- [size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-visit-parents
421
+ [api-index]: #index
321
422
 
322
- [size]: https://bundlejs.com/?q=unist-util-visit-parents
423
+ [api-skip]: #skip
323
424
 
324
- [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
425
+ [api-test]: #test
325
426
 
326
- [backers-badge]: https://opencollective.com/unified/backers/badge.svg
427
+ [api-visitor]: #visitor
327
428
 
328
- [collective]: https://opencollective.com/unified
429
+ [api-visitorexit]: #visitorexit
329
430
 
330
- [chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
331
-
332
- [chat]: https://github.com/syntax-tree/unist/discussions
431
+ [api-visitorresult]: #visitorresult
333
432
 
334
- [npm]: https://docs.npmjs.com/cli/install
433
+ [api-visitorresultexit]: #visitorresultexit
335
434
 
336
- [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
435
+ [api-visitors]: #visitors
337
436
 
338
- [esmsh]: https://esm.sh
437
+ [api-visitparents]: #visitparentstree-test-entervisitors-reverse
339
438
 
340
- [typescript]: https://www.typescriptlang.org
439
+ [author]: https://wooorm.com
341
440
 
342
- [license]: license
441
+ [backers-badge]: https://opencollective.com/unified/backers/badge.svg
343
442
 
344
- [author]: https://wooorm.com
443
+ [build]: https://github.com/syntax-tree/unist-util-visit-parents/actions
345
444
 
346
- [health]: https://github.com/syntax-tree/.github
445
+ [build-badge]: https://github.com/syntax-tree/unist-util-visit-parents/workflows/main/badge.svg
347
446
 
348
- [contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
447
+ [chat]: https://github.com/syntax-tree/unist/discussions
349
448
 
350
- [support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
449
+ [chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
351
450
 
352
451
  [coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
353
452
 
354
- [unist]: https://github.com/syntax-tree/unist
453
+ [collective]: https://opencollective.com/unified
355
454
 
356
- [node]: https://github.com/syntax-tree/unist#node
455
+ [contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
456
+
457
+ [coverage]: https://codecov.io/github/syntax-tree/unist-util-visit-parents
458
+
459
+ [coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-visit-parents.svg
357
460
 
358
461
  [depth-first]: https://github.com/syntax-tree/unist#depth-first-traversal
359
462
 
360
- [tree-traversal]: https://github.com/syntax-tree/unist#tree-traversal
463
+ [downloads]: https://www.npmjs.com/package/unist-util-visit-parents
361
464
 
362
- [preorder]: https://github.com/syntax-tree/unist#preorder
465
+ [downloads-badge]: https://img.shields.io/npm/dm/unist-util-visit-parents.svg
363
466
 
364
- [unist-util-visit]: https://github.com/syntax-tree/unist-util-visit
467
+ [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
365
468
 
366
- [unist-util-is]: https://github.com/syntax-tree/unist-util-is
469
+ [esmsh]: https://esm.sh
367
470
 
368
- [api-visitparents]: #visitparentstree-test-visitor-reverse
471
+ [health]: https://github.com/syntax-tree/.github
369
472
 
370
- [api-continue]: #continue
473
+ [license]: license
371
474
 
372
- [api-exit]: #exit
475
+ [node]: https://github.com/syntax-tree/unist#node
373
476
 
374
- [api-skip]: #skip
477
+ [npm]: https://docs.npmjs.com/cli/install
375
478
 
376
- [api-action]: #action
479
+ [postorder]: https://github.com/syntax-tree/unist#postorder
377
480
 
378
- [api-actiontuple]: #actiontuple
481
+ [preorder]: https://github.com/syntax-tree/unist#preorder
379
482
 
380
- [api-buildvisitor]: #buildvisitor
483
+ [size]: https://bundlejs.com/?q=unist-util-visit-parents
381
484
 
382
- [api-index]: #index
485
+ [size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-visit-parents
383
486
 
384
- [api-test]: #test
487
+ [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
385
488
 
386
- [api-visitor]: #visitor
489
+ [support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
387
490
 
388
- [api-visitorresult]: #visitorresult
491
+ [tree-traversal]: https://github.com/syntax-tree/unist#tree-traversal
492
+
493
+ [typescript]: https://www.typescriptlang.org
494
+
495
+ [unist]: https://github.com/syntax-tree/unist
496
+
497
+ [unist-util-is]: https://github.com/syntax-tree/unist-util-is
498
+
499
+ [unist-util-visit]: https://github.com/syntax-tree/unist-util-visit
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@songtonyli/dsh-cli",
3
- "version": "0.1.85",
3
+ "version": "0.1.86",
4
4
  "description": "The dsh terminal agent: an interactive TUI over the DeepSeek Harness, with its whole Node runtime bundled in one install.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -476,7 +476,7 @@
476
476
  "etag": "1.8.1",
477
477
  "eventsource": "3.0.7",
478
478
  "eventsource-parser": "3.1.1",
479
- "execa": "10.2.0",
479
+ "execa": "10.2.1",
480
480
  "extend": "3.0.2",
481
481
  "fast-deep-equal": "3.1.3",
482
482
  "fast-sha256": "1.3.0",
@@ -618,8 +618,8 @@
618
618
  "unist-util-is": "6.0.1",
619
619
  "unist-util-position": "5.0.0",
620
620
  "unist-util-stringify-position": "4.0.0",
621
- "unist-util-visit": "5.1.0",
622
- "unist-util-visit-parents": "6.0.2",
621
+ "unist-util-visit": "5.2.0",
622
+ "unist-util-visit-parents": "6.1.0",
623
623
  "vary": "1.1.2",
624
624
  "vfile": "6.0.3",
625
625
  "vfile-message": "4.0.3",