@loomcli/core 0.6.0 → 0.8.0

package/dist/style-width.js

@@ -0,0 +1,170 @@
+/*!
+Ported from the grapheme width iterator of @rockorager/uucode 2.2.1, src/width.ts.
+Copyright (c) 2026 Tim Culverhouse. Licensed under the MIT License,
+in licenses/uucode-LICENSE.md of @loomcli/core.
+*/
+import { graphemeTable, widthTable } from './unicode.generated.js';
+/** The break state after a regional indicator, which pairs with the next one into a flag. */
+const regionalIndicatorState = 1;
+/** The break state inside an extended pictographic sequence, which a ZWJ continues. */
+const pictographicState = 2;
+// The table members, read once, so each lookup indexes the arrays directly.
+const { stage1, stage1Shift, stage2, stage2Mask, stage3, widthMask, zeroWidthFlag, emojiVSFlag } = widthTable;
+const { breakTable, graphemeBreakPropertyCount } = graphemeTable;
+/** A code point's packed row: its grapheme break property, width, and emoji flags. */
+function lookup(codePoint) {
+    const offset = stage1[codePoint >> stage1Shift] ?? 0;
+    return stage3[stage2[offset + (codePoint & stage2Mask)] ?? 0] ?? 0;
+}
+/** The row an empty string starts from: the Other break property at width one. */
+const defaultRow = 1 << 5;
+const graphemeBreak = (row) => row & 0x1f;
+const rowWidth = (row) => (row >> 5) & widthMask;
+const zeroInGrapheme = (row) => ((row >> 5) & zeroWidthFlag) !== 0;
+const emojiSelectorBase = (row) => ((row >> 8) & emojiVSFlag) !== 0;
+/** The next break state shifted left once, with whether a cluster boundary falls between. */
+function transition(before, after, state) {
+    const count = graphemeBreakPropertyCount;
+    return breakTable[(state * count + before) * count + after] ?? 0;
+}
+/** A cursor at the start of a run, with the run's first code point read ahead. */
+function cursor(text, start) {
+    const hasNext = start < text.length;
+    const codePoint = hasNext ? (text.codePointAt(start) ?? 0) : 0;
+    return {
+        codePoint: 0,
+        hasNext,
+        index: start,
+        isBreak: false,
+        nextCodePoint: codePoint,
+        nextIndex: hasNext ? start + (codePoint > 0xff_ff ? 2 : 1) : start,
+        nextRow: hasNext ? lookup(codePoint) : defaultRow,
+        row: defaultRow,
+        state: 0,
+        text,
+    };
+}
+/** Moves to the next code point and reads whether a cluster boundary follows it. */
+function advance(at) {
+    if (!at.hasNext) {
+        return false;
+    }
+    at.codePoint = at.nextCodePoint;
+    at.row = at.nextRow;
+    const index = at.nextIndex;
+    at.index = index;
+    if (index >= at.text.length) {
+        at.hasNext = false;
+        at.isBreak = true;
+        return true;
+    }
+    const first = at.text.charCodeAt(index);
+    let codePoint = first;
+    let nextIndex = index + 1;
+    if (first >= 0xd8_00 && first <= 0xdb_ff && nextIndex < at.text.length) {
+        const second = at.text.charCodeAt(nextIndex);
+        if (second >= 0xdc_00 && second <= 0xdf_ff) {
+            codePoint = ((first - 0xd8_00) << 10) + second - 0xdc_00 + 0x1_00_00;
+            nextIndex += 1;
+        }
+    }
+    const row = lookup(codePoint);
+    const packed = transition(graphemeBreak(at.row), graphemeBreak(row), at.state);
+    at.state = packed >> 1;
+    at.nextCodePoint = codePoint;
+    at.nextIndex = nextIndex;
+    at.nextRow = row;
+    at.isBreak = (packed & 1) !== 0;
+    return true;
+}
+/** The width of the next grapheme cluster, leaving the cursor at its end. */
+function clusterWidth(at) {
+    if (!advance(at)) {
+        return 0;
+    }
+    const standalone = rowWidth(at.row);
+    if (at.isBreak) {
+        return standalone;
+    }
+    let width = zeroInGrapheme(at.row) ? 0 : standalone;
+    let previousRow = at.row;
+    let previousState = at.state;
+    for (;;) {
+        if (!advance(at)) {
+            break;
+        }
+        switch (at.codePoint) {
+            case 0xfe_0f: {
+                if (emojiSelectorBase(previousRow)) {
+                    width = 2;
+                }
+                break;
+            }
+            case 0xfe_0e: {
+                if (emojiSelectorBase(previousRow)) {
+                    width = 1;
+                }
+                break;
+            }
+            case 0x20_0d: {
+                if (previousState === pictographicState && !at.isBreak) {
+                    if (!advance(at) || at.isBreak) {
+                        return width;
+                    }
+                    previousRow = at.row;
+                    previousState = at.state;
+                    continue;
+                }
+                break;
+            }
+            case 0x1_f3_fb:
+            case 0x1_f3_fc:
+            case 0x1_f3_fd:
+            case 0x1_f3_fe:
+            case 0x1_f3_ff: {
+                width = 2;
+                break;
+            }
+            default: {
+                if (previousState === regionalIndicatorState) {
+                    width = 2;
+                }
+                else if (!zeroInGrapheme(at.row)) {
+                    width += rowWidth(at.row);
+                }
+            }
+        }
+        if (at.isBreak) {
+            break;
+        }
+        previousRow = at.row;
+        previousState = at.state;
+    }
+    return width;
+}
+/** Whether the character at an index is printable ASCII that no non-ASCII character follows. */
+function asciiAlone(text, index) {
+    const code = text.charCodeAt(index);
+    return (code >= 0x20 && code < 0x7f && (index + 1 >= text.length || text.charCodeAt(index + 1) < 0x80));
+}
+/**
+ * Each grapheme cluster of a string with the terminal columns it occupies. Printable ASCII that no
+ * non-ASCII character follows is its own one-column cluster. Any other run of clusters is read by
+ * one cursor, which starts at the run and carries the break state from cluster to cluster.
+ */
+export function* graphemeWidths(text) {
+    let start = 0;
+    while (start < text.length) {
+        if (asciiAlone(text, start)) {
+            yield { end: start + 1, start, width: 1 };
+            start += 1;
+            continue;
+        }
+        const at = cursor(text, start);
+        do {
+            const width = clusterWidth(at);
+            yield { end: at.index, start, width };
+            start = at.index;
+        } while (start < text.length && !asciiAlone(text, start));
+    }
+}

package/dist/types.d.ts

@@ -8,12 +8,18 @@ import type { RenderingPolicy } from './rendering.js';
 import type { ContextualStyle } from './style.js';
 type LowercaseLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
 type ShortAlias = LowercaseLetter | Uppercase<LowercaseLetter>;
+/**
+ * The spellings an option declares beyond its long form. `aliases` adds a long spelling for each
+ * name, so `shortOnly`, which removes every long spelling, never declares one.
+ */
 type OptionSpelling = {
     short?: ShortAlias;
     shortOnly?: false;
+    aliases?: readonly string[];
 } | {
     short: ShortAlias;
     shortOnly: true;
+    aliases?: never;
 };
 type Presence = {
     required: true;
@@ -48,6 +54,24 @@ type Omission = {
 } | {
     validateOmitted?: false;
 };
+/**
+ * The presence rules a global option never declares, because its validation runs on every Command.
+ * `GlobalOptionConfig` and `GlobalOmissionConstraint` both read the rule from here.
+ */
+type PresenceRuleKey = 'required' | 'validateOmitted';
+/** The fault each presence rule names when a global option declares it. */
+interface PresenceRuleFaults {
+    required: {
+        'A global option declares no required; the Commands that read it check for it': never;
+    };
+    validateOmitted: {
+        'A global option declares no validateOmitted; its omission is plain absence': never;
+    };
+}
+/** The first presence rule a config declares, in the order the faults name them. */
+type DeclaredPresenceRule<Config> = {
+    [Key in PresenceRuleKey]: [Extract<Config, Record<Key, unknown>>] extends [never] ? never : Key;
+}[PresenceRuleKey];
 /**
  * The one-line summary every projection reads. It is a core fact: optional, and a string that holds
  * a character other than whitespace and no line terminator.
@@ -156,8 +180,11 @@ export interface InputIdentity {
 export interface SuppliedInputs {
     /** Raw positional values of the routed Command: one string, or the tokens of a variadic. */
     args: Readonly<Record<string, string | readonly string[] | undefined>>;
-    /** Raw option values, globals and locals: a string, every occurrence, or a Boolean presence. */
-    options: Readonly<Record<string, string | readonly string[] | boolean | undefined>>;
+    /**
+     * Raw option values, globals and locals: a string, every occurrence, a Boolean presence, or the
+     * number of times a counted option was supplied.
+     */
+    options: Readonly<Record<string, string | readonly string[] | boolean | number | undefined>>;
 }
 /**
  * What core knows when it calls one schema. A default validates before any token is read, so its
@@ -185,7 +212,7 @@ export interface ViewContext {
 export interface View<Data> {
     render: (data: Readonly<Data>, context: ViewContext) => string;
     /** A view has one shape; the row view of Results is the other. */
-    row?: never;
+    row?: undefined;
 }
 /**
  * A row view renders a sequence one row at a time.
@@ -197,7 +224,7 @@ export interface RowView<Row> {
     head?: (context: ViewContext) => string;
     tail?: (count: number, context: ViewContext) => string;
     /** A row view has one shape; the whole view of Rendered output is the other. */
-    render?: never;
+    render?: undefined;
 }
 /** The views record of a value result: every entry renders the whole value. */
 export type ResultViews<Value> = Readonly<Record<string, View<Value>>>;
@@ -317,7 +344,7 @@ export interface ResultBinding {
 /**
  * The routed Command's invocation after parsing and validation, which every middleware reads. The
  * values are what the action receives, the output of each declaration's schema, for that Command's
- * own arguments and local options; global and plugin option values are not here. The records are
+ * own arguments and local options; global option values are not here. The records are
  * untyped and frozen, because a middleware runs ahead of every action and the graph carries no
  * type for a value.
  */
@@ -341,6 +368,8 @@ export type StringOption = OptionSpelling & Presence & Multiplicity & Omission &
     type: 'string';
     polarity?: never;
     validate?: StandardSchemaV1;
+    /** The value a bare spelling supplies, so an explicit value is attached to the spelling. */
+    implied?: string;
 };
 /** A variadic argument collects the remaining tokens, so it follows the multiple option rules. */
 export type VariadicArgument = Presence & Described & ArgumentExtensions & {
@@ -357,6 +386,19 @@ export type ValidatedValue<Config, Raw> = Config extends unknown ? 'validate' ex
 export type DefaultConstraint<Config> = Config extends unknown ? Config & {
     default?: 'validate' extends keyof Config ? PerValue<Config, SchemaInput<Config['validate']>> : RawValue<Config>;
 } : never;
+/**
+ * An implied value is the string an operator would otherwise attach, so it must be a string the
+ * validator's input type accepts, as a default must be. A multiple option's validator reads one
+ * value, so the implied value meets that one value's input type. A validator that declares no types
+ * infers `never`, so it states nothing to check against. The key names the fault, the way the
+ * other declaration constraints do, because an intersection with the literal would reduce the whole
+ * config to `never` and report every key.
+ */
+export type ImpliedConstraint<Config> = Config extends {
+    implied: infer Implied;
+} ? 'validate' extends keyof Config ? [SchemaInput<Config['validate']>] extends [never] ? unknown : Implied extends SchemaInput<Config['validate']> ? unknown : {
+    'An implied value must be in the validator input type': Config['validate'];
+} : unknown : unknown;
 /**
  * A multiple option or a variadic argument passes each value to its validator alone, so the
  * declared validator must accept one `string`. The key names the fault, the way the other
@@ -404,19 +446,9 @@ export type ValidateOmittedConstraint<Config> = Config extends {
 /**
  * A global option declares no presence rule, so its omission is always plain absence. A union
  * config fails when any member declares the key, and a wide `OptionConfig` passes, because its
- * members only allow the key.
+ * members only allow the key. `required` is named first when a config declares both.
  */
-export type GlobalOmissionConstraint<Config> = [Extract<Config, {
-    required: unknown;
-}>] extends [
-    never
-] ? [Extract<Config, {
-    validateOmitted: unknown;
-}>] extends [never] ? unknown : {
-    'A global option declares no validateOmitted; its omission is plain absence': never;
-} : {
-    'A global option declares no required; the Commands that read it check for it': never;
-};
+export type GlobalOmissionConstraint<Config> = [DeclaredPresenceRule<Config>] extends [never] ? unknown : PresenceRuleFaults['required' extends DeclaredPresenceRule<Config> ? 'required' : 'validateOmitted'];
 export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
     variadic: true;
 } ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
@@ -433,6 +465,7 @@ export type BooleanOption = (OptionSpelling & Described & Listed & EnvBinding &
     multiple?: never;
     required?: never;
     validateOmitted?: never;
+    implied?: never;
     polarity?: 'positive' | 'negative';
 }) | (Described & Listed & EnvBinding & OptionExtensions & {
     type: 'boolean';
@@ -441,27 +474,34 @@ export type BooleanOption = (OptionSpelling & Described & Listed & EnvBinding &
     multiple?: never;
     required?: never;
     validateOmitted?: never;
+    implied?: never;
     polarity: 'both';
     short?: ShortAlias;
     shortOnly?: false;
+    aliases?: readonly string[];
 });
-export type OptionConfig = StringOption | BooleanOption;
 /**
- * The parsing part of a string option config, which is all a plugin option declares. A plugin
- * option carries no schema and no presence rule, because the pre-scan consumes it ahead of routing,
- * where the validation context every schema is promised cannot exist. Its middleware interprets
- * the value.
- * A Boolean plugin option is an ordinary `BooleanOption`, which already declares none of them.
+ * A counted option takes no value and reads how many times it was supplied, across every spelling,
+ * so it declares no validator, default, presence rule, collection, polarity, or implied value.
  */
-export type PluginStringOption = OptionSpelling & Multiplicity & Described & Listed & OptionExtensions & {
-    type: 'string';
-    default?: string | string[];
-    polarity?: never;
-    required?: never;
+export type CountOption = OptionSpelling & Described & Listed & EnvBinding & OptionExtensions & {
+    type: 'count';
     validate?: never;
+    default?: never;
+    multiple?: never;
+    required?: never;
     validateOmitted?: never;
+    polarity?: never;
+    implied?: never;
 };
-export type PluginOptionConfig = PluginStringOption | BooleanOption;
+export type OptionConfig = StringOption | BooleanOption | CountOption;
+/**
+ * The configuration of a global option a plugin declares: everything `option()` takes except the
+ * presence rules, which a global option never declares, because its validation runs on every
+ * Command. `globalOption()` states the same rule through `GlobalOmissionConstraint`, which also
+ * accepts a config typed as the wide `OptionConfig`.
+ */
+export type GlobalOptionConfig = OptionConfig & Readonly<Partial<Record<PresenceRuleKey, never>>>;
 export type OptionValue<Config extends OptionConfig> = Config extends StringOption ? Config extends {
     multiple: true;
 } ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
@@ -470,7 +510,7 @@ export type OptionValue<Config extends OptionConfig> = Config extends StringOpti
     default: unknown;
 } | {
     validateOmitted: true;
-} ? never : undefined) : boolean;
+} ? never : undefined) : Config extends CountOption ? number : boolean;
 /**
  * What an action receives. `graph` is the frozen graph `inspect()` returns for this run, and
  * `command` is the routed node inside it: the same two values the run's middleware receive.

package/dist/unicode.generated.d.ts

@@ -0,0 +1,27 @@
+/*!
+The tables derive from the Unicode Character Database.
+Copyright © 1991-2025 Unicode, Inc. Licensed under the Unicode License v3,
+in licenses/unicode-LICENSE.txt of @loomcli/core.
+
+They are generated from the tables of @rockorager/uucode.
+Copyright (c) 2026 Tim Culverhouse. Licensed under the MIT License,
+in licenses/uucode-LICENSE.md of @loomcli/core.
+*/
+/** The grapheme break state machine, indexed by state and two break properties. */
+export declare const graphemeTable: {
+    breakStateCount: number;
+    breakTable: Uint8Array<ArrayBuffer>;
+    graphemeBreakPropertyCount: number;
+};
+/** Each code point's width and grapheme break property, in a three-stage lookup. */
+export declare const widthTable: {
+    emojiVSFlag: number;
+    maxCodePoint: number;
+    stage1: Uint16Array<ArrayBuffer>;
+    stage1Shift: number;
+    stage2: Uint8Array<ArrayBuffer>;
+    stage2Mask: number;
+    stage3: Uint16Array<ArrayBuffer>;
+    widthMask: number;
+    zeroWidthFlag: number;
+};