authorgravatar for git@paperclover.netclover caruso <git@paperclover.net> 2025-09-27 17:27:56-07:00
committergravatar for git@paperclover.netclover caruso <git@paperclover.net> 2025-10-14 02:40:47-07:00
logc5236cd3ee2b76999ae6101cd189cdaac23ce0cf
treebf4592314c9bc6f697d0ae25f0a7df3083dc59be
parent293d92bc8ba73bbf125387b927096b2c67a61081
signature Commit is signed but in an unrecognized format.

fix(lib/log/progress): propagate logs for completed nodes

10 files changed, 192 insertions(+), 97 deletions(-)

lib/assert.ts created+47
......@@ -0,0 +1,47 @@
1// This module is intended to be imported as
2
3/** Assert that `condition` is truthy */
4export function ASSERT(condition: boolean, msg?: Message): asserts condition {
5 if (!condition) {
6 throw new Error(msg ? messageToString(msg) : "Assertion Error");
7 }
8}
9
10/** Assert that `nullable` is non-null, returning a non-nullable T */
11export function UNWRAP<T>(nullable: T | null | undefined, msg?: Message) {
12 if (nullable == null) {
13 throw new Error(
14 `Unexpected ${nullable}${msg ? `: ${messageToString(msg)}` : ""}`,
15 );
16 }
17 return nullable;
18}
19
20/** Assert that `number` is not NaN */
21export function FINITE(number: number, msg?: Message) {
22 if (Number.isNaN(number)) {
23 throw new Error(`Unexpected NaN${msg ? `: ${messageToString(msg)}` : ""}`);
24 }
25 return number;
26}
27
28/** Assert that a `default` case in a switch is never reached. */
29export function unreachableCase(value: never): never {
30 throw new Error(`Unexpected value in switch: ${inspect(value as unknown)}`);
31}
32
33/** message called if function; then string printed as is or util inspectified */
34type Message = string | (() => string | unknown) | unknown;
35
36function messageToString(msg: Message) {
37 if (typeof msg === "function") msg = (msg as () => Message)();
38 return typeof msg === "string" ? msg : inspect(msg);
39}
40
41function inspect(object: unknown) {
42 try {
43 return require("node:util").inspect(object);
44 } catch {
45 return typeof object;
46 }
47}
lib/deno.json created+16
......@@ -0,0 +1,16 @@
1{
2 "name": "@clo/lib",
3 "version": "1.0.0",
4 "license": "MIT",
5 "exports": {
6 "./log": "./log.ts",
7 "./log/ansi": "./log/ansi.ts",
8 "./log/headless": "./log/headless.ts",
9 "./queue": "./queue.ts",
10 "./string": "./string.ts",
11 "./ts": "./ts.ts"
12 },
13 "imports": {
14 "lib/": "./"
15 }
16}
lib/jsr.json deleted-13
......@@ -1,13 +0,0 @@
1{
2 "name": "@clo/lib",
3 "version": "1.0.0",
4 "license": "MIT",
5 "exports": {
6 "./log": "./log.ts",
7 "./log/ansi": "./log/ansi.ts",
8 "./log/headless": "./log/headless.ts",
9 "./queue": "./queue.ts",
10 "./string": "./string.ts",
11 "./ts": "./ts.ts"
12 }
13}
lib/log.ts+2-2
......@@ -98,5 +98,5 @@ const globalLog = /* @__PURE__ */ headless.logger({
9898});
9999
100100import process from "node:process";
101import * as headless from "./log/headless.ts";
102import * as ts from "./ts.ts";
101import * as headless from "lib/log/headless.ts";
102import type * as ts from "lib/ts.ts";
lib/log/ansi.ts+2-2
......@@ -49,7 +49,7 @@ export function bgRgb(r: number, g: number, b: number): string {
4949}
5050
5151// cursor management
52export function cursorUp(n: number) {
52export function cursorUp(n: number): string {
5353 return n ? `\x1b[${n}A` : "";
5454}
5555export const startOfLine: string = "\r";
......@@ -77,7 +77,7 @@ export function style(code: string, text: string): string {
7777 * Given a string of multiple style ansi codes, combines all of them.
7878 * Must be used on a string of only ansi style codes.
7979 */
80export function mergeStyles(code: string) {
80export function mergeStyles(code: string): string {
8181 let styles = [];
8282 while (code.length) {
8383 if (!code.startsWith("\x1b[")) {
lib/log/headless.ts+2
......@@ -1,4 +1,6 @@
11// This file is under heavy construction.
2// - I am happy with the overall API, likely no changes.
3// - There are certainly a lot of bugs.
24//
35// Rendering for 'lib/term' is done by specifying all system APIs up front in
46// an interface and creating an instance of the widget host. The main file
lib/log/progress.sample.ts+2
......@@ -25,6 +25,8 @@ for (let i = 0; i < 10; i += 1) {
2525 x = subNodes[2]!.start("other task");
2626 y = x.start("deeply nested");
2727 z = y.start("job");
28 z.log.info("with inline logs");
29 z.log.warn("with inline logs");
2830 }
2931 if (i == 8) z?.end();
3032 if (i === 6) w = y!.start("magic");
lib/log/progress.ts+111-74
......@@ -1,10 +1,15 @@
11// This file is under heavy construction.
2// - I am happy with the overall design
3// - Will rename things
4// - Will be re-working the entire module to have a headless
5// core, but still leaving the top level `start` function.
6// - There are an overwhelming amount of bugs
27//
38// A progress tree based on my past uses with clover console v3 and the Zig
49// Progress API. Pass `Progress` to functions which should track progress,
510// calling `.start()` to create child items. Or, multiple top-level progress
611// bars can be created with the singleton's `start()` function.
7import * as self from "./progress.ts";
12import * as self from "lib/log/progress.ts";
813self satisfies Ref; // prove you can use the namespace import as a `Progress`
914
1015/**
......@@ -12,12 +17,7 @@ self satisfies Ref; // prove you can use the namespace import as a `Progress`
1217 * when given an estimate, a progress bar is rendered.
1318 */
1419export function start(text: string, opts?: StartOptions): Node {
15 const [state, node] = newNode(text, opts);
16 globalState.push(state);
17 state.signal = topLevelSignaler;
18 if (rerender) rerender();
19 else log.startWidget(globalWidget);
20 return node;
20 return global.start(text, opts);
2121}
2222
2323export interface Ref {
......@@ -58,10 +58,6 @@ export interface Node extends Ref {
5858
5959 /** end this Node or RootNode. ending collapses children */
6060 end(): void;
61 // /** signal that there will be a failure without ending the node */
62 // pendingFail(): void;
63 // /** end this node with a failure */
64 // endFail(): void;
6561
6662 [Symbol.dispose](): void;
6763}
......@@ -70,30 +66,18 @@ export interface StartOptions {
7066 estimate?: number | undefined | null;
7167}
7268
73/** a node that satisfies the api */
74const nullNode: Node =
75 (function start(text: string, { estimate }: StartOptions = {}): Node {
76 return {
77 start,
78 text,
79 value: 0,
80 estimate: estimate ?? 0,
81 showEstimate: true,
82 passive: false,
83 maxHeight: null,
84 sortChildren: null,
85 inc() {
86 this.value += 1;
87 },
88 log: log.scoped(""),
89 end() {},
90 [Symbol.dispose]() {},
91 };
69/** a valid `Node` without any output */
70const nullNode: Node = /* @__PURE__ */
71 (function start(text: string, opts?: StartOptions): Node {
72 const node = newNode(text, opts)[1];
73 node.start = start;
74 node.log = log.scoped("");
75 return node;
9276 })("root");
9377
9478export { nullNode as null };
9579
96type SortNode =
80export type SortNode =
9781 & Pick<
9882 Node,
9983 | "text"
......@@ -105,16 +89,23 @@ type SortNode =
10589 >
10690 & { children: SortNode[] };
10791
108type Signal = "draw" | "end" | "endFail" | "pendingFail";
109interface State extends SortNode {
92export interface Internal extends SortNode {
11093 logs: string[];
111 children: State[];
112 parent: State | null;
113 signal(signal: Signal): void;
94 children: Internal[];
95 parent: Internal | null;
96 signal(msg: Signal): void;
11497}
11598
116function newNode(text: string, { estimate }: StartOptions = {}): [State, Node] {
117 const state: State = {
99type Signal =
100 | "draw"
101 | { type: "end"; title: string; logs: string[] }
102 | { type: "line"; line: string };
103
104function newNode(
105 text: string,
106 { estimate }: StartOptions = {},
107): [Internal, Node] {
108 const state: Internal = {
118109 text,
119110 value: 0,
120111 estimate: estimate ?? 0,
......@@ -128,13 +119,20 @@ function newNode(text: string, { estimate }: StartOptions = {}): [State, Node] {
128119 throw new Error("no signaler");
129120 },
130121 };
122 let detached = false;
131123 function end() {
124 if (detached) return;
132125 if (!state.parent) return;
133126 const i = state.parent.children.indexOf(state);
134127 if (i === -1) return;
135 state.signal("draw");
128 let title = state.text;
129 let p: Internal | null = state;
130 while (p = p.parent) title = p.text + " / " + title;
131 state.signal({ type: "end", title, logs: state.logs });
132 state.logs = [];
136133 state.parent.children.splice(i, 1);
137134 state.parent = null;
135 detached = true;
138136 }
139137 function mutate() {
140138 const { parent } = state;
......@@ -144,6 +142,7 @@ function newNode(text: string, { estimate }: StartOptions = {}): [State, Node] {
144142 const scope = headless.logger({
145143 log: {
146144 writeLine(line) {
145 if (detached) return state.signal({ type: "line", line });
147146 state.logs.push(...line.split("\n"));
148147 state.signal("draw");
149148 },
......@@ -226,6 +225,27 @@ function newNode(text: string, { estimate }: StartOptions = {}): [State, Node] {
226225 return [state, binding];
227226}
228227
228function format(now: number, list: Internal[]) {
229 let out = "";
230 for (const top of list) {
231 if (top.passive && top.children.length === 0) continue;
232 out += renderMainLine(top, now, 0) + "\n";
233 out += renderChildren(top, now, []);
234 }
235 return out.trimEnd();
236}
237
238/** These functions are used to test `lib/log/progress` */
239export const internals = {
240 node(text: string, props: Partial<Internal>, children: Internal[]): Internal {
241 const [node] = newNode(text);
242 Object.assign(node, props);
243 node.children.push(...children);
244 return node;
245 },
246 format,
247};
248
229249const spinnerFps = 12.5;
230250
231251const box = {
......@@ -238,31 +258,7 @@ const fullBar = "█";
238258const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
239259 .map((frame) => ansi.style(ansi.fgBlue, frame));
240260
241let rerender: (() => void) | null = null;
242let globalTimer: ts.Interval | null = null;
243const globalWidget: log.Widget = {
244 format(now) {
245 let out = "";
246 for (const top of globalState) {
247 if (top.passive && top.children.length === 0) continue;
248 out += renderMainLine(top, now, 0) + "\n";
249 out += renderChildren(top, now, []);
250 }
251 return out.trimEnd();
252 },
253 onChange(cb) {
254 //const globalTimer = setInterval(cb, 1000 / spinnerFps);
255 //if ("unref" in globalTimer) (globalTimer.unref as () => void)();
256 rerender = cb;
257 return () => {
258 globalTimer != null && clearInterval(globalTimer);
259 rerender = null;
260 };
261 },
262};
263const globalState: State[] = [];
264
265function renderMainLine(state: State, now: number, depth: number) {
261function renderMainLine(state: Internal, now: number, depth: number) {
266262 if (state.estimate && state.showEstimate) {
267263 return ansi.style(
268264 ansi.bgBrightBlack + ansi.fgBlue,
......@@ -278,14 +274,14 @@ function renderMainLine(state: State, now: number, depth: number) {
278274 (state.value > 0 ? `[${state.value}] ` : "") + state.text;
279275}
280276
281function renderChildren(state: State, now: number, depth: boolean[]) {
277function renderChildren(state: Internal, now: number, depth: boolean[]) {
282278 let maxHeight = 25; // TODO:
283279 let truncated = 0;
284280 let out = "";
285281 const { children } = state;
286282 if (children.length === 0) return "";
287283 for (let i = 0, { length } = children; i < length; i += 1) {
288 const child = children[i];
284 const child = UNWRAP(children[i]);
289285 if (child.passive && child.children.length === 0) continue;
290286 let item = "";
291287 const left = depth.map((x) => x ? box.line : " ").join("");
......@@ -333,14 +329,55 @@ export function getUnicodeBar(progress: number, width: number) {
333329 return fill + partChar + empty;
334330}
335331
336function topLevelSignaler(this: State, signal: Signal) {
337 if (signal === "draw") {
338 rerender?.();
332/** Run a progress tree without a dependency on a TTY */
333export class Headless {
334 constructor(
335 /**
336 * `startWidget` is only ever called from `start`
337 * `writeLine` is used for logs from completed nodes
338 */
339 public env: Pick<headless.WidgetHost, "writeLine" | "startWidget">,
340 ) {}
341
342 active: Internal[] = [];
343
344 start(text: string, opts?: StartOptions): Node {
345 const [state, node] = newNode(text, opts);
346 this.active.push(state);
347 state.signal = this.#signal;
348 const rerender = this.#rerender;
349 if (rerender) rerender();
350 else log.startWidget(this.widget);
351 return node;
339352 }
353
354 widget: log.Widget = {
355 format: (now) => format(now, this.active),
356 onChange: (
357 rerender,
358 ) => (this.#rerender = rerender, () => this.#rerender = null),
359 };
360
361 #rerender?: (() => void) | null;
362 #signal = (msg: Signal) => {
363 if (msg === "draw") this.#rerender?.();
364 else if (msg.type === "line") this.env.writeLine(msg.line);
365 else if (msg.type === "end") {
366 if (msg.logs.length === 0) return;
367 const { logs } = msg;
368 const count = `${logs.length} line${logs.length === 1 ? "" : "s"}`;
369 const header = `[${count} from ${msg.title}]`;
370 this.env.writeLine(ansi.style(ansi.fgBrightBlack, header));
371 this.env.writeLine(msg.logs.join("\n"));
372 }
373 };
340374}
341375
342import * as ts from "../ts.ts";
343import * as log from "../log.ts";
344import * as headless from "../log/headless.ts";
345import * as ansi from "./ansi.ts";
346import * as string from "../string.ts";
376const global = /** @__PURE__ */ new Headless(log);
377
378import * as process from "node:process";
379import * as log from "lib/log.ts";
380import * as headless from "lib/log/headless.ts";
381import * as ansi from "lib/log/ansi.ts";
382import * as string from "lib/string.ts";
383import { UNWRAP } from "lib/assert.ts";
lib/queue.ts+3-1
......@@ -136,7 +136,7 @@ export class PriorityQueue {
136136 });
137137 }
138138
139 canRun({ cores }: Internal) {
139 canRun({ cores }: Internal): boolean {
140140 const { coresRemain, concurrency } = this;
141141 return coresRemain >= cores ||
142142 (cores > concurrency && coresRemain === concurrency);
......@@ -166,3 +166,5 @@ function insertSorted<T extends { priority: number }>(arr: T[], item: T) {
166166}
167167
168168const global = new PriorityQueue(navigator.hardwareConcurrency);
169
170import { UNWRAP } from "lib/assert.ts";
lib/string.ts+7-5
......@@ -1,5 +1,5 @@
11// TODO: this function is not benchmarked
2export function countNewlines(str: string) {
2export function countNewlines(str: string): number {
33 let count = 0;
44 for (let i = 0, { length } = str; i < length; i += 1) {
55 if (str[i] === "\n") count += 1;
......@@ -7,7 +7,7 @@ export function countNewlines(str: string) {
77 return count;
88}
99
10export function widthInTerminal(str: string) {
10export function widthInTerminal(str: string): number {
1111 let width = 0;
1212 if (str.includes("\x1b")) str = str.replace(ansiEscapes, "");
1313 for (let i = 0, { length } = str; i < length; i += 1) {
......@@ -32,7 +32,7 @@ export function widthInTerminal(str: string) {
3232 return width;
3333}
3434
35export function trimToWidth(str: string, columns: number) {
35export function trimToWidth(str: string, columns: number): string {
3636 let width = 0;
3737 let ansi = false;
3838 for (let i = 0, { length } = str; i < length; i += 1) {
......@@ -57,7 +57,7 @@ export function trimToWidth(str: string, columns: number) {
5757 str = str.slice(i);
5858 const segments = segmenter.segment(str);
5959 {
60 const { segment } = segments.containing(0);
60 const { segment } = UNWRAP(segments.containing(0));
6161 width += segmentWidth(segment);
6262 if (width > columns) return ansi ? out + "\x1b[0m" : out;
6363 out += segment;
......@@ -73,7 +73,7 @@ export function trimToWidth(str: string, columns: number) {
7373 continue;
7474 }
7575 }
76 const { segment } = segments.containing(i);
76 const { segment } = UNWRAP(segments.containing(i));
7777 width += segmentWidth(segment);
7878 if (width > columns) return ansi ? out + "\x1b[0m" : out;
7979 out += segment;
......@@ -154,3 +154,5 @@ function segmentWidth(segment: string) {
154154 list.includes(x)
155155 );
156156}
157
158import { UNWRAP } from "lib/assert.ts";