@trazum/cli 1.73.1 → 1.75.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.
package/src/style.ts ADDED
@@ -0,0 +1,108 @@
1
+ /**
2
+ * The CLI's presentation layer — the 1.75 arc.
3
+ *
4
+ * Six painters, one measurer, one table renderer, one proportion bar, one
5
+ * heading rule. Everything here decorates figures the prose already states;
6
+ * the chapter-four guard strips the paint and asserts nothing was lost and
7
+ * nothing was hiding in it.
8
+ *
9
+ * Colour is on for a TTY unless `NO_COLOR` says otherwise, and on anywhere
10
+ * when `FORCE_COLOR=1` — the door the guard itself walks through, since a
11
+ * test that wants to see what colour does runs under a pipe. A plain pipe
12
+ * stays plain: every `trazum ... | grep` in somebody's script is owed the
13
+ * bytes their script was written against.
14
+ */
15
+
16
+ const forced = process.env.FORCE_COLOR === '1';
17
+ export const useColor = forced || (process.stdout.isTTY === true && process.env.NO_COLOR === undefined);
18
+
19
+ export const c = {
20
+ bold: (s: string) => (useColor ? `\u001b[1m${s}\u001b[22m` : s),
21
+ dim: (s: string) => (useColor ? `\u001b[2m${s}\u001b[22m` : s),
22
+ green: (s: string) => (useColor ? `\u001b[32m${s}\u001b[39m` : s),
23
+ red: (s: string) => (useColor ? `\u001b[31m${s}\u001b[39m` : s),
24
+ yellow: (s: string) => (useColor ? `\u001b[33m${s}\u001b[39m` : s),
25
+ cyan: (s: string) => (useColor ? `\u001b[36m${s}\u001b[39m` : s),
26
+ };
27
+
28
+ /** The report's text column. Headings rule out to it; nothing else needs it. */
29
+ export const REPORT_WIDTH = 74;
30
+
31
+ const ANSI = /\u001b\[[0-9;]*m/g;
32
+
33
+ /**
34
+ * A string's width as a terminal draws it — the ANSI codes not counted.
35
+ *
36
+ * Every hand-rolled `padStart` in the CLI miscounted the moment a painted
37
+ * cell reached it, which is why nothing painted ever sat in a column. All
38
+ * padding below measures through this.
39
+ */
40
+ export function visibleWidth(s: string): number {
41
+ return s.replace(ANSI, '').length;
42
+ }
43
+
44
+ export function padCell(s: string, width: number, align: 'left' | 'right'): string {
45
+ const gap = Math.max(0, width - visibleWidth(s));
46
+ return align === 'right' ? ' '.repeat(gap) + s : s + ' '.repeat(gap);
47
+ }
48
+
49
+ export interface TableColumn {
50
+ /** The header cell, already localized. Empty string for a headerless column. */
51
+ header: string;
52
+ align: 'left' | 'right';
53
+ }
54
+
55
+ /**
56
+ * The one table renderer, for the eleven layouts that each rebuilt it.
57
+ *
58
+ * Widths come from the content, headers print dimmed, and cells may arrive
59
+ * painted — the measurement ignores the paint. Returns lines; the caller
60
+ * owns the `console.log` and the indent, because some tables live inside a
61
+ * bullet and some at the margin.
62
+ */
63
+ export function table(columns: TableColumn[], rows: string[][], indent = ' '): string[] {
64
+ const widths = columns.map((col, i) =>
65
+ Math.max(visibleWidth(col.header), ...rows.map((row) => visibleWidth(row[i] ?? ''))),
66
+ );
67
+ const lines: string[] = [];
68
+ if (columns.some((col) => col.header !== '')) {
69
+ lines.push(
70
+ indent +
71
+ columns.map((col, i) => padCell(c.dim(col.header), widths[i] ?? 0, col.align)).join(' ').trimEnd(),
72
+ );
73
+ }
74
+ for (const row of rows) {
75
+ lines.push(
76
+ indent + columns.map((col, i) => padCell(row[i] ?? '', widths[i] ?? 0, col.align)).join(' ').trimEnd(),
77
+ );
78
+ }
79
+ return lines;
80
+ }
81
+
82
+ /**
83
+ * A share the line already states, readable from further away: `███░░░░░░░`.
84
+ *
85
+ * The bar is content, not paint — it prints in a pipe too, so the stripped
86
+ * and plain outputs stay byte-identical. It never carries information the
87
+ * text does not: the percentage beside it is the number, the bar is the
88
+ * glance. Clamped, because a share over 1 is the caller's bug and a bar
89
+ * wider than asked would make it the layout's.
90
+ */
91
+ export function bar(share: number, width = 10): string {
92
+ const clamped = Math.max(0, Math.min(1, share));
93
+ const filled = Math.round(clamped * width);
94
+ return c.cyan('█'.repeat(filled)) + c.dim('░'.repeat(width - filled));
95
+ }
96
+
97
+ /**
98
+ * A section heading an eye can stop on: the text bold, the line completed
99
+ * with a dim rule out to the report's width.
100
+ *
101
+ * Adónde fue el dinero ─────────────────────────────────────────────
102
+ *
103
+ * The rule is content (it survives the strip); the weight is paint.
104
+ */
105
+ export function sectionHeading(text: string, width = REPORT_WIDTH): string {
106
+ const room = Math.max(0, width - visibleWidth(text) - 1);
107
+ return `${c.bold(text)} ${c.dim('─'.repeat(room))}`.trimEnd();
108
+ }