linegauge 0.3.3 → 0.4.0

package/README.md

@@ -154,10 +154,10 @@ its own suite — which this package passes. The runner reports that as a failur
 to the incumbent an unexpected pass means a stale annotation; it is counted here as the
 pass it is, and marked rather than left to look like the ones beside it.
 
-Weight, installed and tree-inclusive: **83,536 bytes** against **170,342** for the incumbents it replaces — a ratio of **0.4904**.
+Weight, installed and tree-inclusive: **77,124 bytes** against **170,342** for the incumbents it replaces — a ratio of **0.4528**.
 ## Where it sits
 
-It hosts no plugin key of its own.
+Plugins register under the `widths` key, against the one schema the whole family shares.
 
 `burgee`, `caique`, `flagstaff` build on it, and it builds on nothing in this family.
 ## Licence

package/dist/check.d.ts

@@ -0,0 +1,14 @@
+/**
+ * E1, restated rather than imported: linegauge is an independent product and depends on nobody in
+ * the family for its exit contract. `scripts/exit-code-lock.test.ts` keeps the restatements in
+ * step.
+ */
+export declare const EXIT_OK = 0;
+export declare const EXIT_RUNTIME = 1;
+export declare const EXIT_USAGE = 2;
+/**
+ * Every refusal leaves through here, wherever it was raised: `register()`, or a plugin file that
+ * registers itself on import — which throws inside the `import()`, before any line of `inspect`
+ * could catch it, and used to reach the bin as a bare message with no code and no fix (R8).
+ */
+export declare function check(argv: readonly string[], write: (s: string) => void): Promise<number>;

package/dist/check.js

@@ -0,0 +1,57 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { overrides, PluginError, register, setOverrides, validate } from './plugin.js';
+import { width } from './width.js';
+export const EXIT_OK = 0;
+export const EXIT_RUNTIME = 1;
+export const EXIT_USAGE = 2;
+function refuse(code, message, fix, write) {
+    write(`${code}: ${message}\n  fix: ${fix}\n`);
+    return EXIT_RUNTIME;
+}
+const HEX = 16;
+const MIN_DIGITS = 4;
+const codePoint = (n) => `U+${n.toString(HEX).toUpperCase().padStart(MIN_DIGITS, '0')}`;
+const overridesOf = (plugin) => {
+    const widths = plugin?.widths;
+    return typeof widths === 'object' && widths !== null ? Object.entries(widths) : [];
+};
+const firstOf = (plugin) => overridesOf(plugin).flatMap(([, o]) => (o.ranges ?? []).map(([low]) => low));
+const shadows = (names) => (names.length === 0 ? '' : ` (replaces ${names.join(', ')})`);
+export async function check(argv, write) {
+    try {
+        return await inspect(argv, write);
+    }
+    catch (error) {
+        if (!(error instanceof PluginError))
+            throw error;
+        return refuse(error.code, error.message, error.fix, write);
+    }
+}
+async function inspect(argv, write) {
+    const file = argv[0];
+    if (file === undefined) {
+        write('usage: linegauge check <plugin-file>\n');
+        return EXIT_USAGE;
+    }
+    const loaded = (await import(pathToFileURL(resolve(file)).href));
+    const plugin = loaded.default ?? loaded;
+    for (const registered of [...overrides().keys()])
+        setOverrides(registered, {});
+    const builtIn = new Map(firstOf(plugin).map((code) => [code, width(String.fromCodePoint(code))]));
+    validate(plugin);
+    register(plugin);
+    const name = plugin.name;
+    const rows = overridesOf(plugin).flatMap(([label, o]) => (o.ranges ?? []).map(([low, high]) => {
+        const span = low === high ? codePoint(low) : `${codePoint(low)}..${codePoint(high)}`;
+        return `${label}  ${span}  built-in ${String(builtIn.get(low) ?? '?')} → ${String(width(String.fromCodePoint(low)))}  — ${o.why}`;
+    }));
+    write(`${name} — ${String(rows.length)} widths\n`);
+    if (rows.length === 0) {
+        return refuse('E_NO_CONTRIBUTION', `${name} registers, but contributes nothing linegauge reads`, 'add a `widths` section — a key another package in the family reads is allowed in the same object, but `linegauge check` cannot show it', write);
+    }
+    for (const row of rows)
+        write(`  ${row}\n`);
+    write(`${name}: ok\n`);
+    return EXIT_OK;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { check, EXIT_RUNTIME } from './check.js';
+const [, , command, ...rest] = process.argv;
+check(command === 'check' ? rest : [command, ...rest].filter((a) => a !== undefined), (s) => void process.stdout.write(s)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = EXIT_RUNTIME;
+});

package/dist/plugin.d.ts

@@ -0,0 +1,66 @@
+/**
+ * One plugin-supplied width override: the column count a set of code-point ranges occupies.
+ */
+export interface WidthOverride {
+    /** Inclusive `[low, high]` code-point pairs. */
+    ranges: readonly (readonly [number, number])[];
+    /** 0 for a zero-width mark, 1 narrow, 2 wide. */
+    columns: number;
+    /** Which terminal or font disagrees, and how it was measured. Required; see the file comment. */
+    why: string;
+}
+/**
+ * Later registrations win, which is the point: the user is the authority on their terminal.
+ *
+ * An empty table **removes** the plugin rather than recording that it contributes nothing.
+ * `overrides()` is what `linegauge check` prints and what a caller inspects, and a name in it
+ * with no ranges under it reads as *this plugin is active* when the truth is the opposite.
+ *
+ * The seam in `width.ts` is installed only while something is registered, so the last plugin
+ * leaving puts `measure` back on the path with no call in it at all.
+ */
+export declare function setOverrides(name: string, widths: Record<string, WidthOverride>): void;
+/** Every override currently registered, by plugin name — what `linegauge check` prints. */
+export declare function overrides(): ReadonlyMap<string, Record<string, WidthOverride>>;
+/**
+ * The plugin contract version. One number for the family — the same `1` flagstaff, caique,
+ * closeout and paratext declare, written out rather than imported for the reason above.
+ */
+export declare const CONTRACT = 1;
+/**
+ * The keys linegauge reads. Declared structurally: any object with these fields is a plugin
+ * here, whatever else it carries.
+ */
+export interface Plugin {
+    name: string;
+    contract?: number;
+    /** Width overrides by name. The key is the author's label; see {@link validate}. */
+    widths?: Record<string, WidthOverride>;
+}
+/**
+ * Two codes, both already in the family's vocabulary
+ * (`scripts/plugin-error-vocabulary-lock.test.ts`).
+ */
+export type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_CONTRIBUTION';
+/** A refused plugin says what is wrong and what to do about it — the family's one vocabulary. */
+export declare class PluginError extends Error {
+    readonly code: PluginErrorCode;
+    readonly fix: string;
+    constructor(code: PluginErrorCode, message: string, fix: string);
+}
+type Problem = {
+    code: PluginErrorCode;
+    line: string;
+    fix: string;
+};
+/** Everything wrong with a plugin document, in the family's vocabulary. Empty means it registers. */
+export declare function problems(plugin: unknown): Problem[];
+/** Throws on the first problem, in the family's vocabulary. */
+export declare function validate(plugin: unknown): asserts plugin is Plugin;
+/**
+ * Register a plugin's width overrides. Later registrations win over earlier ones, and over the
+ * built-in tables — which is the point: the built-in answer is right for most terminals and the
+ * user is the authority on theirs.
+ */
+export declare function register(plugin: unknown): void;
+export {};

package/dist/plugin.js

@@ -0,0 +1,125 @@
+import { setClaim } from './width.js';
+let flattened = [];
+const byPlugin = new Map();
+function overridden(code) {
+    let found;
+    for (let i = 0; i < flattened.length; i += 3) {
+        if (code >= flattened[i] && code <= flattened[i + 1])
+            found = flattened[i + 2];
+    }
+    return found;
+}
+export function setOverrides(name, widths) {
+    if (Object.keys(widths).length === 0)
+        byPlugin.delete(name);
+    else
+        byPlugin.set(name, widths);
+    const rows = [];
+    for (const table of byPlugin.values()) {
+        for (const { ranges, columns } of Object.values(table)) {
+            for (const [low, high] of ranges)
+                rows.push(low, high, columns);
+        }
+    }
+    flattened = rows;
+    setClaim(rows.length === 0 ? undefined : overridden);
+}
+export function overrides() {
+    return byPlugin;
+}
+export const CONTRACT = 1;
+export class PluginError extends Error {
+    code;
+    fix;
+    constructor(code, message, fix) {
+        super(message);
+        this.code = code;
+        this.fix = fix;
+        this.name = 'PluginError';
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const MAX_CODE_POINT = 0x10_ff_ff;
+const MAX_COLUMNS = 2;
+function rangeProblem(label, range) {
+    if (!Array.isArray(range) || range.length !== 2)
+        return `${label} is not a [low, high] pair`;
+    const [low, high] = range;
+    if (!Number.isInteger(low) || !Number.isInteger(high))
+        return `${label} has a non-integer bound`;
+    const lo = low;
+    const hi = high;
+    if (lo < 0 || hi > MAX_CODE_POINT)
+        return `${label} is outside U+0000..U+10FFFF`;
+    if (lo > hi)
+        return `${label} runs backwards: [${String(lo)}, ${String(hi)}]`;
+    return undefined;
+}
+function headerProblems(plugin) {
+    const out = [];
+    if (typeof plugin['name'] !== 'string' || plugin['name'] === '') {
+        out.push({ code: 'E_PLUGIN_SCHEMA', line: 'a plugin needs a non-empty `name`', fix: 'add `name: "my-widths"` — it is what `linegauge check` and a later registration call it' });
+    }
+    const contract = plugin['contract'];
+    if (contract !== undefined && contract !== CONTRACT) {
+        out.push({
+            code: 'E_PLUGIN_CONTRACT',
+            line: `contract ${String(contract)} is not ${String(CONTRACT)}`,
+            fix: `set \`contract: ${String(CONTRACT)}\`, or drop the field — the family is on one version`,
+        });
+    }
+    return out;
+}
+function overrideProblems(name, value) {
+    if (!isRecord(value))
+        return [{ code: 'E_PLUGIN_SCHEMA', line: `widths.${name} is not an object`, fix: 'each override is { ranges, columns, why }' }];
+    const out = [];
+    const ranges = value['ranges'];
+    if (!Array.isArray(ranges) || ranges.length === 0) {
+        out.push({ code: 'E_PLUGIN_SCHEMA', line: `widths.${name}.ranges is a non-empty array of [low, high] pairs`, fix: 'ranges: [[0xE000, 0xF8FF]]' });
+    }
+    else {
+        for (const [i, range] of ranges.entries()) {
+            const problem = rangeProblem(`widths.${name}.ranges[${String(i)}]`, range);
+            if (problem !== undefined)
+                out.push({ code: 'E_PLUGIN_SCHEMA', line: problem, fix: 'each range is [low, high], both integers in U+0000..U+10FFFF, low first' });
+        }
+    }
+    const columns = value['columns'];
+    if (!Number.isInteger(columns) || columns < 0 || columns > MAX_COLUMNS) {
+        out.push({ code: 'E_PLUGIN_SCHEMA', line: `widths.${name}.columns is 0, 1 or 2`, fix: '0 for a zero-width mark, 1 narrow, 2 wide' });
+    }
+    if (typeof value['why'] !== 'string' || value['why'] === '') {
+        out.push({
+            code: 'E_PLUGIN_SCHEMA',
+            line: `widths.${name}.why is required`,
+            fix: 'say which terminal or font disagrees, and how you measured it — ambiguous width is wrong often enough that the next reader needs the provenance',
+        });
+    }
+    return out;
+}
+export function problems(plugin) {
+    if (!isRecord(plugin)) {
+        return [{ code: 'E_PLUGIN_SCHEMA', line: 'a plugin is an object', fix: 'export default { name: "my-widths", widths: { … } }' }];
+    }
+    const out = headerProblems(plugin);
+    const widths = plugin['widths'];
+    if (widths === undefined)
+        return out;
+    if (!isRecord(widths)) {
+        out.push({ code: 'E_PLUGIN_SCHEMA', line: '`widths` is an object keyed by name', fix: 'widths: { "nerd-font-icons": { ranges: [[0xE000, 0xF8FF]], columns: 2, why: "…" } }' });
+        return out;
+    }
+    for (const [name, value] of Object.entries(widths))
+        out.push(...overrideProblems(name, value));
+    return out;
+}
+export function validate(plugin) {
+    const [first] = problems(plugin);
+    if (first !== undefined)
+        throw new PluginError(first.code, first.line, first.fix);
+}
+export function register(plugin) {
+    validate(plugin);
+    setOverrides(plugin.name, plugin.widths ?? {});
+}

package/dist/schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"propertyNames":{"enum":["error","warn","ok","hint","muted","command","flag","value","heading","ground"],"description":"roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}},"capabilities":{"$ref":"#/$defs/capabilities"},"widths":{"$ref":"#/$defs/widths"}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}},"capability":{"type":"object","required":["name","osc","when","encode","fallback"],"additionalProperties":false,"description":"One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.","properties":{"name":{"type":"string","minLength":1,"description":"How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."},"osc":{"description":"The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.","oneOf":[{"type":"integer","minimum":0},{"const":"BEL"}]},"when":{"type":"object","description":"When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.","additionalProperties":false,"properties":{"tty":{"type":"boolean","description":"Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."},"termProgram":{"type":"array","items":{"type":"string"},"description":"Any one of these TERM_PROGRAM values."},"envAny":{"type":"array","items":{"type":"string"},"description":"Any one of these environment variables merely being set, as VTE announces itself."},"term":{"type":"string","description":"An exact TERM — Kitty is xterm-kitty."}}},"encode":{"type":"string","minLength":1,"description":"The bytes, as a template, for a terminal that does understand."},"fallback":{"type":"string","description":"What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."}},"examples":[{"name":"kitty-image","osc":"BEL","when":{"tty":true,"term":"xterm-kitty"},"encode":"\u001b_Ga=T,f=100;{base64}\u001b\\","fallback":"{caption}"}]},"capabilities":{"type":"object","description":"paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/capability"}},"capabilityDocument":{"description":"What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.","oneOf":[{"description":"The family shape: a plugin carrying its capabilities under `capabilities`.","type":"object","required":["name","capabilities"],"properties":{"name":{"type":"string","minLength":1},"contract":{"type":"integer","minimum":1},"capabilities":{"$ref":"#/$defs/capabilities"}}},{"deprecated":true,"description":"Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.","$ref":"#/$defs/capability"}]},"widthRange":{"type":"array","description":"One inclusive code-point range, as [low, high]. A single code point is written [n, n].","items":{"type":"integer","minimum":0,"maximum":1114111},"minItems":2,"maxItems":2},"widthOverride":{"type":"object","description":"A linegauge width override: the column count a named set of code-point ranges occupies, for a terminal that disagrees with the Unicode tables. Data only — no function, so it can be written in a config file, diffed, and printed by `linegauge check` without running anyone code.","required":["ranges","columns","why"],"additionalProperties":false,"properties":{"ranges":{"type":"array","description":"The code points this override applies to.","items":{"$ref":"#/$defs/widthRange"},"minItems":1},"columns":{"type":"integer","description":"Columns each cluster in those ranges occupies: 0 for a zero-width mark, 1 narrow, 2 wide.","minimum":0,"maximum":2},"why":{"type":"string","description":"The terminal or the reason. Required, because a width table with no provenance is one nobody can audit when it turns out to be wrong — which is the normal outcome for ambiguous width.","minLength":1}}},"widths":{"type":"object","description":"linegauge width overrides by name — the measurement section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/widthOverride"}}}}

package/dist/width.d.ts

@@ -1,3 +1,5 @@
+/** Installed by `plugin.ts` when the first override registers, and cleared when the last one goes. */
+export declare function setClaim(fn: ((code: number) => number | undefined) | undefined): void;
 /**
  * Columns a string of *plain* text occupies — no escape scan. The wrapper below has
  * already split its input into text runs and complete sequences, so rescanning would only

package/dist/width.js

@@ -178,9 +178,18 @@ function hangulColumns(visible, ambiguousIsWide) {
     }
     return columns;
 }
+let claim;
+export function setClaim(fn) {
+    claim = fn;
+}
 export function measure(text, ambiguousIsWide = false) {
     let columns = 0;
     for (const { segment } of segmenter().segment(text)) {
+        const claimed = claim?.(segment.codePointAt(0) ?? 0);
+        if (claimed !== undefined) {
+            columns += claimed;
+            continue;
+        }
         if (ZERO_WIDTH_CLUSTER().test(segment))
             continue;
         if (RGI_EMOJI().test(segment) || isUnqualifiedEmojiSequence(segment)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linegauge",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "A printer's line gauge \u2014 the steel rule marked in picas and points. Measuring, wrapping, truncating and slicing styled terminal text without the edge fraying \u2014 grapheme-correct over Intl.Segmenter. Drop-in paths for string-width, wrap-ansi, strip-ansi and slice-ansi. Zero dependencies.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,13 @@
       "types": "./dist/strip.d.ts",
       "import": "./dist/strip.js",
       "default": "./dist/strip.js"
-    }
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./schema.json": "./dist/schema.json"
   },
   "files": [
     "dist",
@@ -45,7 +51,7 @@
     "!dist/**/*.test.*"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node ../../scripts/strip-comments.mjs dist",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/schema-to-dist.mjs && node ../../scripts/strip-comments.mjs dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
     "coverage": "vitest run --coverage.enabled",
@@ -76,5 +82,8 @@
   ],
   "devDependencies": {
     "vitest": "^5.0.1"
+  },
+  "bin": {
+    "linegauge": "./dist/cli.js"
   }
 }