burgee 0.6.0 → 0.6.1

package/dist/yargs/cliui.d.ts

@@ -1,21 +1,17 @@
+import { type WrapOptions } from "linegauge";
 /**
- * cliui 9 — the column layout yargs' usage renders through — with the string-width,
- * strip-ansi and wrap-ansi it depends on, ported for `burgee/yargs`. The wrapping
+ * cliui 9 — the column layout yargs' usage renders through — with the wrap-ansi it depends
+ * on, ported for `burgee/yargs`. Width and escape-stripping come from linegauge. The wrapping
  * arithmetic is byte-for-byte the upstream's: yargs' usage tests compare whole help
  * screens.
  */
-export declare function stripAnsi(str: string): string;
-export declare function stringWidth(input: string): number;
-interface WrapOptions {
-    hard?: boolean;
-    wordWrap?: boolean;
-    trim?: boolean;
-}
+export declare const stripAnsi: (str: string) => string;
+export declare const stringWidth: (input: string) => number;
 export declare function wrapAnsi(string: string, columns: number, options?: WrapOptions): string;
 export interface Column {
     text: string;
     width?: number | undefined;
-    align?: 'right' | 'left' | 'center';
+    align?: "right" | "left" | "center";
     padding: number[];
     border?: boolean;
 }

package/dist/yargs/cliui.js

@@ -1,221 +1,36 @@
+import { strip, width, wrap } from "linegauge";
 /**
- * cliui 9 — the column layout yargs' usage renders through — with the string-width,
- * strip-ansi and wrap-ansi it depends on, ported for `burgee/yargs`. The wrapping
+ * cliui 9 — the column layout yargs' usage renders through — with the wrap-ansi it depends
+ * on, ported for `burgee/yargs`. Width and escape-stripping come from linegauge. The wrapping
  * arithmetic is byte-for-byte the upstream's: yargs' usage tests compare whole help
  * screens.
  */
-const ANSI_PATTERN = '[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))';
-export function stripAnsi(str) {
-    return typeof str === 'string' ? str.replace(new RegExp(ANSI_PATTERN, 'g'), '') : str;
-}
-const segmenter = new Intl.Segmenter();
-const EMOJI = new RegExp('^\\p{RGI_Emoji}$', 'v');
-function isWide(code) {
-    return ((code >= 0x1100 && code <= 0x115f) ||
-        code === 0x2329 ||
-        code === 0x232a ||
-        (code >= 0x2e80 && code <= 0x303e) ||
-        (code >= 0x3041 && code <= 0x33ff) ||
-        (code >= 0x3400 && code <= 0x4dbf) ||
-        (code >= 0x4e00 && code <= 0x9fff) ||
-        (code >= 0xa000 && code <= 0xa4cf) ||
-        (code >= 0xa960 && code <= 0xa97f) ||
-        (code >= 0xac00 && code <= 0xd7a3) ||
-        (code >= 0xf900 && code <= 0xfaff) ||
-        (code >= 0xfe10 && code <= 0xfe19) ||
-        (code >= 0xfe30 && code <= 0xfe6f) ||
-        (code >= 0xff00 && code <= 0xff60) ||
-        (code >= 0xffe0 && code <= 0xffe6) ||
-        (code >= 0x1f300 && code <= 0x1f64f) ||
-        (code >= 0x1f900 && code <= 0x1f9ff) ||
-        (code >= 0x20000 && code <= 0x3fffd));
-}
-export function stringWidth(input) {
-    if (typeof input !== 'string' || input.length === 0)
-        return 0;
-    const string = stripAnsi(input);
-    if (string.length === 0)
-        return 0;
-    let width = 0;
-    for (const { segment } of segmenter.segment(string)) {
-        const code = segment.codePointAt(0);
-        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
-            continue;
-        if ((code >= 0x200b && code <= 0x200f) || code === 0xfeff)
-            continue;
-        if (code >= 0x300 && code <= 0x36f)
-            continue;
-        if (EMOJI.test(segment)) {
-            width += 2;
-            continue;
-        }
-        width += isWide(code) ? 2 : 1;
-    }
-    return width;
-}
-/** ansi-styles' open→close map, the part wrap-ansi reads. */
-function closeCode(code) {
-    if (code === 1 || code === 2)
-        return 22;
-    if (code === 3)
-        return 23;
-    if (code === 4)
-        return 24;
-    if (code === 7)
-        return 27;
-    if (code === 8)
-        return 28;
-    if (code === 9)
-        return 29;
-    if ((code >= 30 && code <= 37) || (code >= 90 && code <= 97))
-        return 39;
-    if ((code >= 40 && code <= 47) || (code >= 100 && code <= 107))
-        return 49;
-    return undefined;
-}
-const ESC = '\u001B';
-const ESCAPES = new Set([ESC, '\u009B']);
-const END_CODE = 39;
-const ANSI_ESCAPE_BELL = '\u0007';
-const ANSI_CSI = '[';
-const ANSI_OSC = ']';
-const ANSI_SGR_TERMINATOR = 'm';
-const ANSI_ESCAPE_LINK = `${ANSI_OSC}8;;`;
-const wrapAnsiCode = (code) => `${ESC}${ANSI_CSI}${code}${ANSI_SGR_TERMINATOR}`;
-const wrapAnsiHyperlink = (uri) => `${ESC}${ANSI_ESCAPE_LINK}${uri}${ANSI_ESCAPE_BELL}`;
-const wordLengths = (string) => string.split(' ').map((character) => stringWidth(character));
-function wrapWord(rows, word, columns) {
-    const characters = [...word];
-    let isInsideEscape = false;
-    let isInsideLinkEscape = false;
-    let visible = stringWidth(stripAnsi(rows.at(-1)));
-    for (const [index, character] of characters.entries()) {
-        const characterLength = stringWidth(character);
-        if (visible + characterLength <= columns)
-            rows[rows.length - 1] += character;
-        else {
-            rows.push(character);
-            visible = 0;
-        }
-        if (ESCAPES.has(character)) {
-            isInsideEscape = true;
-            isInsideLinkEscape = characters.slice(index + 1).join('').startsWith(ANSI_ESCAPE_LINK);
-        }
-        if (isInsideEscape) {
-            if (isInsideLinkEscape) {
-                if (character === ANSI_ESCAPE_BELL) {
-                    isInsideEscape = false;
-                    isInsideLinkEscape = false;
-                }
-            }
-            else if (character === ANSI_SGR_TERMINATOR)
-                isInsideEscape = false;
-            continue;
-        }
-        visible += characterLength;
-        if (visible === columns && index < characters.length - 1) {
-            rows.push('');
-            visible = 0;
-        }
-    }
-    if (!visible && rows.at(-1).length > 0 && rows.length > 1)
-        rows[rows.length - 2] += rows.pop();
-}
-function stringVisibleTrimSpacesRight(string) {
-    const words = string.split(' ');
-    let last = words.length;
-    while (last > 0) {
-        if (stringWidth(words[last - 1]) > 0)
-            break;
-        last--;
-    }
-    if (last === words.length)
-        return string;
-    return words.slice(0, last).join(' ') + words.slice(last).join('');
-}
-function execWrap(string, columns, options = {}) {
-    if (options.trim !== false && string.trim() === '')
-        return '';
-    let returnValue = '';
-    let escapeCode;
-    let escapeUrl;
-    const lengths = wordLengths(string);
-    let rows = [''];
-    for (const [index, word] of string.split(' ').entries()) {
-        if (options.trim !== false)
-            rows[rows.length - 1] = rows.at(-1).trimStart();
-        let rowLength = stringWidth(rows.at(-1));
-        if (index !== 0) {
-            if (rowLength >= columns && (options.wordWrap === false || options.trim === false)) {
-                rows.push('');
-                rowLength = 0;
-            }
-            if (rowLength > 0 || options.trim === false) {
-                rows[rows.length - 1] += ' ';
-                rowLength++;
-            }
-        }
-        const length = lengths[index];
-        if (options.hard && length > columns) {
-            const remainingColumns = columns - rowLength;
-            const breaksStartingThisLine = 1 + Math.floor((length - remainingColumns - 1) / columns);
-            const breaksStartingNextLine = Math.floor((length - 1) / columns);
-            if (breaksStartingNextLine < breaksStartingThisLine)
-                rows.push('');
-            wrapWord(rows, word, columns);
-            continue;
-        }
-        if (rowLength + length > columns && rowLength > 0 && length > 0) {
-            if (options.wordWrap === false && rowLength < columns) {
-                wrapWord(rows, word, columns);
-                continue;
-            }
-            rows.push('');
-        }
-        if (rowLength + length > columns && options.wordWrap === false) {
-            wrapWord(rows, word, columns);
-            continue;
-        }
-        rows[rows.length - 1] += word;
-    }
-    if (options.trim !== false)
-        rows = rows.map(stringVisibleTrimSpacesRight);
-    const pre = [...rows.join('\n')];
-    for (const [index, character] of pre.entries()) {
-        returnValue += character;
-        if (ESCAPES.has(character)) {
-            const found = new RegExp(`(?:\\${ANSI_CSI}(?<code>\\d+)m|\\${ANSI_ESCAPE_LINK}(?<uri>.*)${ANSI_ESCAPE_BELL})`).exec(pre.slice(index).join(''));
-            const groups = found?.groups ?? {};
-            if (groups.code !== undefined) {
-                const code = Number.parseFloat(groups.code);
-                escapeCode = code === END_CODE ? undefined : code;
-            }
-            else if (groups.uri !== undefined)
-                escapeUrl = groups.uri.length === 0 ? undefined : groups.uri;
-        }
-        const code = closeCode(Number(escapeCode));
-        if (pre[index + 1] === '\n') {
-            if (escapeUrl)
-                returnValue += wrapAnsiHyperlink('');
-            if (escapeCode && code)
-                returnValue += wrapAnsiCode(code);
-        }
-        else if (character === '\n') {
-            if (escapeCode && code)
-                returnValue += wrapAnsiCode(escapeCode);
-            if (escapeUrl)
-                returnValue += wrapAnsiHyperlink(escapeUrl);
-        }
-    }
-    return returnValue;
-}
+/*
+ * `width` and `strip` are linegauge's — measuring text and removing escapes is the layer
+ * below this one, and this file had its own copies of both. They were not merely duplicated,
+ * they were wrong: the ITU T.416 sub-parameter form `ESC[38:2::255:0:0m`, which chalk emits
+ * for truecolor, left `:2::255:0:0m` behind and measured a 13-column string as 25. linegauge
+ * fixed that in its own `strip`; burgee inherited nothing because it was not asking.
+ *
+ * The names stay, because `usage.ts` and `shim.ts` import them and the upstream port reads
+ * the way cliui reads.
+ */
+export const stripAnsi = (str) => typeof str === "string" ? strip(str) : str;
+export const stringWidth = (input) => typeof input === "string" ? width(input) : 0;
+/*
+ * The wrap is linegauge's too. This file carried a wrap-ansi port — ansi-styles' open→close
+ * map, an escape-state machine over every character, hyperlink re-opening — to wrap a line
+ * without breaking the styling across it. That is the same job `linegauge/wrap` exists for
+ * and grades against wrap-ansi, so burgee kept a second implementation of a thing the layer
+ * below already owned.
+ *
+ * Checked before swapping, because yargs' usage tests compare whole help screens: the two
+ * agreed on all ten shapes probed — plain prose at several widths, an unbreakable word,
+ * SGR-coloured text, single characters, CJK, an embedded newline, leading and trailing
+ * spaces, empty, and a string exactly the column width.
+ */
 export function wrapAnsi(string, columns, options) {
-    return String(string)
-        .normalize()
-        .replace(/\r\n/g, '\n')
-        .split('\n')
-        .map((line) => execWrap(line, columns, options))
-        .join('\n');
+    return wrap(String(string).normalize().replace(/\r\n/g, "\n"), columns, options);
 }
 const align = { right: alignRight, center: alignCenter };
 const top = 0;
@@ -240,21 +55,24 @@ export class UI {
     }
     div(...args) {
         if (args.length === 0)
-            this.div('');
-        if (this.wrap && this.shouldApplyLayoutDSL(...args) && typeof args[0] === 'string')
+            this.div("");
+        if (this.wrap &&
+            this.shouldApplyLayoutDSL(...args) &&
+            typeof args[0] === "string")
             return this.applyLayoutDSL(args[0]);
-        const cols = args.map((arg) => (typeof arg === 'string' ? this.colFromString(arg) : arg));
+        const cols = args.map((arg) => typeof arg === "string" ? this.colFromString(arg) : arg);
         this.rows.push(cols);
         return cols;
     }
     shouldApplyLayoutDSL(...args) {
-        return args.length === 1 && typeof args[0] === 'string' && /[\t\n]/.test(args[0]);
+        return (args.length === 1 && typeof args[0] === "string" && /[\t\n]/.test(args[0]));
     }
     applyLayoutDSL(str) {
-        const rows = str.split('\n').map((row) => row.split('\t'));
+        const rows = str.split("\n").map((row) => row.split("\t"));
         let leftColumnWidth = 0;
         rows.forEach((columns) => {
-            if (columns.length > 1 && stringWidth(columns[0]) > leftColumnWidth) {
+            if (columns.length > 1 &&
+                stringWidth(columns[0]) > leftColumnWidth) {
                 leftColumnWidth = Math.min(Math.floor(this.width * 0.5), stringWidth(columns[0]));
             }
         });
@@ -271,8 +89,20 @@ export class UI {
         return { text, padding: this.measurePadding(text) };
     }
     measurePadding(str) {
+        // An unanchored `\s*$` was the upstream spelling, and it is quadratic: the engine
+        // retries at every position, so a cell of 50,000 spaces then an `x` costs 1,346 ms
+        // here — CodeQL alert 35, "polynomial regular expression used on uncontrolled data",
+        // raised once `stripAnsi` became library input. Spaces, not the tabs the alert names:
+        // a tab routes into `applyLayoutDSL`, which splits on it long before this runs.
+        // `trim{Start,End}` remove exactly the set `\s` matches (WhiteSpace + LineTerminator)
+        // and are linear, so this is the same measurement without the backtracking.
         const noAnsi = stripAnsi(str);
-        return [0, /\s*$/.exec(noAnsi)[0].length, 0, /^\s*/.exec(noAnsi)[0].length];
+        return [
+            0,
+            noAnsi.length - noAnsi.trimEnd().length,
+            0,
+            noAnsi.length - noAnsi.trimStart().length,
+        ];
     }
     toString() {
         const lines = [];
@@ -282,36 +112,36 @@ export class UI {
         return lines
             .filter((line) => !line.hidden)
             .map((line) => line.text)
-            .join('\n');
+            .join("\n");
     }
     rowToString(row, lines) {
         this.rasterize(row).forEach((rrow, r) => {
-            let str = '';
+            let str = "";
             rrow.forEach((col, c) => {
                 const column = row[c];
                 const { width } = column;
                 const wrapWidth = this.negatePadding(column);
                 let ts = col;
                 if (wrapWidth > stringWidth(col))
-                    ts += ' '.repeat(wrapWidth - stringWidth(col));
-                if (column.align && column.align !== 'left' && this.wrap) {
+                    ts += " ".repeat(wrapWidth - stringWidth(col));
+                if (column.align && column.align !== "left" && this.wrap) {
                     const fn = align[column.align];
                     ts = fn(ts, wrapWidth);
                     if (stringWidth(ts) < wrapWidth)
-                        ts += ' '.repeat((width || 0) - stringWidth(ts) - 1);
+                        ts += " ".repeat((width || 0) - stringWidth(ts) - 1);
                 }
                 const padding = column.padding || [0, 0, 0, 0];
                 if (padding[left])
-                    str += ' '.repeat(padding[left]);
-                str += addBorder(column, ts, '| ');
+                    str += " ".repeat(padding[left]);
+                str += addBorder(column, ts, "| ");
                 str += ts;
-                str += addBorder(column, ts, ' |');
+                str += addBorder(column, ts, " |");
                 if (padding[right])
-                    str += ' '.repeat(padding[right]);
+                    str += " ".repeat(padding[right]);
                 if (r === 0 && lines.length > 0)
                     str = this.renderInline(str, lines.at(-1));
             });
-            lines.push({ text: str.replace(/ +$/, ''), span: row.span });
+            lines.push({ text: str.replace(/ +$/, ""), span: row.span });
         });
         return lines;
     }
@@ -329,7 +159,9 @@ export class UI {
         if (leadingWhitespace < targetTextWidth)
             return source;
         previousLine.hidden = true;
-        return target.trimEnd() + ' '.repeat(leadingWhitespace - targetTextWidth) + source.trimStart();
+        return (target.trimEnd() +
+            " ".repeat(leadingWhitespace - targetTextWidth) +
+            source.trimStart());
     }
     rasterize(row) {
         const rrows = [];
@@ -338,16 +170,18 @@ export class UI {
         row.forEach((col, c) => {
             col.width = widths[c];
             if (this.wrap)
-                wrapped = wrapAnsi(col.text, this.negatePadding(col), { hard: true }).split('\n');
+                wrapped = wrapAnsi(col.text, this.negatePadding(col), {
+                    hard: true,
+                }).split("\n");
             else
-                wrapped = col.text.split('\n');
+                wrapped = col.text.split("\n");
             if (col.border) {
-                wrapped.unshift(`.${'-'.repeat(this.negatePadding(col) + 2)}.`);
-                wrapped.push(`'${'-'.repeat(this.negatePadding(col) + 2)}'`);
+                wrapped.unshift(`.${"-".repeat(this.negatePadding(col) + 2)}.`);
+                wrapped.push(`'${"-".repeat(this.negatePadding(col) + 2)}'`);
             }
             if (col.padding) {
-                wrapped.unshift(...new Array(col.padding[top] || 0).fill(''));
-                wrapped.push(...new Array(col.padding[bottom] || 0).fill(''));
+                wrapped.unshift(...new Array(col.padding[top] || 0).fill(""));
+                wrapped.push(...new Array(col.padding[bottom] || 0).fill(""));
             }
             wrapped.forEach((str, r) => {
                 if (!rrows[r])
@@ -355,7 +189,7 @@ export class UI {
                 const rrow = rrows[r];
                 for (let i = 0; i < c; i++) {
                     if (rrow[i] === undefined)
-                        rrow.push('');
+                        rrow.push("");
                 }
                 rrow.push(str);
             });
@@ -384,18 +218,18 @@ export class UI {
             return undefined;
         });
         const unsetWidth = unset ? Math.floor(remainingWidth / unset) : 0;
-        return widths.map((w, i) => (w === undefined ? Math.max(unsetWidth, minWidth(row[i])) : w));
+        return widths.map((w, i) => w === undefined ? Math.max(unsetWidth, minWidth(row[i])) : w);
     }
 }
 function addBorder(col, ts, style) {
     if (col.border) {
         if (/[.']-+[.']/.test(ts))
-            return '';
+            return "";
         if (ts.trim().length !== 0)
             return style;
-        return '  ';
+        return "  ";
     }
-    return '';
+    return "";
 }
 function minWidth(col) {
     const padding = col.padding || [];
@@ -405,7 +239,7 @@ function minWidth(col) {
     return min;
 }
 function getWindowWidth() {
-    if (typeof process === 'object' && process.stdout && process.stdout.columns)
+    if (typeof process === "object" && process.stdout && process.stdout.columns)
         return process.stdout.columns;
     return 80;
 }
@@ -413,7 +247,7 @@ function alignRight(str, width) {
     str = str.trim();
     const strWidth = stringWidth(str);
     if (strWidth < width)
-        return ' '.repeat(width - strWidth) + str;
+        return " ".repeat(width - strWidth) + str;
     return str;
 }
 function alignCenter(str, width) {
@@ -421,7 +255,7 @@ function alignCenter(str, width) {
     const strWidth = stringWidth(str);
     if (strWidth >= width)
         return str;
-    return ' '.repeat((width - strWidth) >> 1) + str;
+    return " ".repeat((width - strWidth) >> 1) + str;
 }
 export function cliui(opts) {
     return new UI({ width: opts?.width || getWindowWidth(), wrap: opts?.wrap });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burgee",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "An agent-native CLI framework, drop-in compatible with commander and yargs. One declaration; help, --json, --schema, --mcp and completions all projected from it.",
   "license": "MIT",
   "type": "module",
@@ -96,6 +96,7 @@
     "provenance": true
   },
   "dependencies": {
+    "linegauge": "^0.2.0",
     "roundel": "^0.3.0",
     "seniority": "^0.1.0"
   },