burgee 0.0.0 → 0.2.0

package/dist/validate.js

@@ -0,0 +1,133 @@
+import { kebab } from './names.js';
+export class UsageError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+    }
+}
+const TYPES = new Set(['string', 'boolean', 'number']);
+export function checkDefinition(name, options) {
+    const shorts = new Map();
+    const flags = new Map();
+    for (const [key, spec] of Object.entries(options)) {
+        if (!TYPES.has(spec.type))
+            throw new Error(`burgee: option "${key}" of "${name}" has unknown type "${String(spec.type)}"`);
+        if (spec.short !== undefined) {
+            const owner = shorts.get(spec.short);
+            if (owner !== undefined)
+                throw new Error(`burgee: options "${owner}" and "${key}" of "${name}" both use -${spec.short}`);
+            shorts.set(spec.short, key);
+        }
+        const flag = kebab(key);
+        const clash = flags.get(flag);
+        if (clash !== undefined)
+            throw new Error(`burgee: options "${clash}" and "${key}" of "${name}" are both --${flag}`);
+        flags.set(flag, key);
+        if ((spec.minimum !== undefined || spec.maximum !== undefined || spec.integer !== undefined) && spec.type !== 'number') {
+            throw new Error(`burgee: option "${key}" of "${name}" declares a numeric bound but is not a number`);
+        }
+    }
+}
+const isSet = (values, key, sources) => values[key] !== undefined && sources[key]?.source !== 'default';
+const flagList = (keys) => keys.map((k) => `--${kebab(k)}`).join(', ');
+function exactlyOne(keys, on) {
+    if (on.length === 1)
+        return;
+    throw new UsageError(`exactly one of ${flagList(keys)} is required`, on.length === 0 ? 'pass one of them' : `drop all but one of ${flagList(on)}`);
+}
+function atLeastOne(keys, on) {
+    if (on.length === 0)
+        throw new UsageError(`at least one of ${flagList(keys)} is required`, 'pass one of them');
+}
+function atMostOne(keys, on) {
+    if (on.length > 1)
+        throw new UsageError(`at most one of ${flagList(keys)} may be given`, `drop all but one of ${flagList(on)}`);
+}
+function noConflict(on) {
+    if (on.length > 1)
+        throw new UsageError(`${flagList(on)} cannot be used together`, 'drop one of them');
+}
+function implied(a, b, values, sources) {
+    if (!isSet(values, a, sources))
+        return;
+    if (typeof b === 'string') {
+        if (!isSet(values, b, sources))
+            throw new UsageError(`--${kebab(a)} requires --${kebab(b)}`, `pass --${kebab(b)}`);
+        return;
+    }
+    if (!b(values))
+        throw new UsageError(`--${kebab(a)} is not allowed with these values`, `check the values --${kebab(a)} is declared to require`);
+}
+function checkRelation(rel, values, sources) {
+    const set = (keys) => keys.filter((k) => isSet(values, k, sources));
+    if ('exactlyOneOf' in rel)
+        exactlyOne(rel.exactlyOneOf, set(rel.exactlyOneOf));
+    else if ('atLeastOneOf' in rel)
+        atLeastOne(rel.atLeastOneOf, set(rel.atLeastOneOf));
+    else if ('atMostOneOf' in rel)
+        atMostOne(rel.atMostOneOf, set(rel.atMostOneOf));
+    else if ('conflicts' in rel)
+        noConflict(set(rel.conflicts));
+    else
+        implied(rel.implies[0], rel.implies[1], values, sources);
+}
+export function checkRelations(relations, values, sources) {
+    for (const rel of relations ?? [])
+        checkRelation(rel, values, sources);
+}
+const isFinite = (n) => Number.isFinite(n);
+const numberOf = (raw) => {
+    if (typeof raw === 'number')
+        return raw;
+    const text = String(raw).trim();
+    return text === '' ? Number.NaN : Number(text);
+};
+export function toNumber(key, spec, raw) {
+    const n = numberOf(raw);
+    const flag = `--${kebab(key)}`;
+    if (!isFinite(n))
+        throw new UsageError(`${flag} expects a number, got "${String(raw)}"`, `pass ${flag} <number>`);
+    if (spec.integer === true && !Number.isInteger(n))
+        throw new UsageError(`${flag} expects an integer, got ${n}`, `pass ${flag} ${Math.round(n)}`);
+    if (spec.minimum !== undefined && n < spec.minimum)
+        throw new UsageError(`${flag} must be at least ${spec.minimum}, got ${n}`, `pass ${flag} ${spec.minimum}`);
+    if (spec.maximum !== undefined && n > spec.maximum)
+        throw new UsageError(`${flag} must be at most ${spec.maximum}, got ${n}`, `pass ${flag} ${spec.maximum}`);
+    return n;
+}
+function checkChoice(key, spec, value) {
+    if (spec.choices === undefined || spec.choices.includes(String(value)))
+        return;
+    throw new UsageError(`--${kebab(key)} must be one of ${spec.choices.join(', ')}, got "${String(value)}"`, `pass --${kebab(key)} ${spec.choices[0] ?? ''}`);
+}
+async function checkSchema(key, spec, value) {
+    if (spec.schema === undefined)
+        return value;
+    const result = await spec.schema['~standard'].validate(value);
+    if (result.issues !== undefined) {
+        throw new UsageError(`--${kebab(key)}: ${result.issues.map((i) => i.message).join('; ')}`, `check --${kebab(key)}`);
+    }
+    return result.value;
+}
+export function splitMultiple(spec, raw) {
+    const sep = spec.separator ?? ',';
+    const parts = Array.isArray(raw) ? raw : [raw];
+    return parts.flatMap((p) => (typeof p === 'string' ? p.split(sep).map((s) => s.trim()).filter((s) => s !== '') : [p]));
+}
+async function coerceOne(key, spec, raw) {
+    const value = spec.type === 'number' ? toNumber(key, spec, raw) : raw;
+    checkChoice(key, spec, value);
+    return await checkSchema(key, spec, value);
+}
+async function coerceValue(key, spec, raw) {
+    if (spec.multiple !== true)
+        return await coerceOne(key, spec, raw);
+    return await Promise.all(splitMultiple(spec, raw).map((item) => coerceOne(key, spec, item)));
+}
+export async function coerce(specs, values) {
+    const present = Object.entries(specs).filter(([key]) => values[key] !== undefined);
+    const coerced = await Promise.all(present.map(async ([key, spec]) => [key, await coerceValue(key, spec, values[key])]));
+    return { ...values, ...Object.fromEntries(coerced) };
+}
+export { camel, kebab } from './names.js';

package/dist/yargs-burgee.d.ts

@@ -0,0 +1,50 @@
+/**
+ * burgee's additions on yargs syntax — the pure half. `yargs-factory.ts` snapshots what
+ * a program registered (options, descriptions, commands and their builders' results) and
+ * this module projects that snapshot into the manifest every surface reads (J7, J8).
+ * Nothing here runs at parse time unless a burgee surface was asked for.
+ */
+import { type Effects, type Manifest, type OptionSpec } from './manifest.js';
+import type { Positional } from './yargs-utils.js';
+/** What one yargs instance (the root, or a command's builder run on a scratch) registered. */
+export interface Snapshot {
+    name: string;
+    version?: string | undefined;
+    description?: string | undefined;
+    effects?: Effects | undefined;
+    hasHandler: boolean;
+    keys: string[];
+    aliases: Record<string, string[]>;
+    boolean: string[];
+    number: string[];
+    string: string[];
+    count: string[];
+    array: string[];
+    hiddenOptions: string[];
+    demanded: Record<string, string | undefined>;
+    deprecated: Record<string, string | boolean | undefined>;
+    choices: Record<string, any[]>;
+    defaults: Record<string, any>;
+    descriptions: Record<string, string | undefined>;
+    /** yargs' own `help`, `version` and `show-hidden` keys: burgee serves those itself. */
+    skip: readonly string[];
+    positionals: {
+        demanded: Positional[];
+        optional: Positional[];
+    };
+    commands: {
+        name: string;
+        description: string | false | undefined;
+        deprecated: boolean | string | undefined;
+        child: Snapshot;
+    }[];
+}
+/** Options as the manifest describes them, on a null-prototype record keyed by the canonical camelCase name. */
+export declare function optionSpecs(s: Snapshot): Record<string, OptionSpec>;
+/**
+ * Project a snapshot into the manifest: the root, then every command as a child path.
+ * Plugin-contributed nodes survive re-projection, exactly as on the commander façade.
+ */
+export declare function projectManifest(manifest: Manifest, root: Snapshot): void;
+/** What a run prints for a handler's return value when the streams are injected. */
+export declare function render(value: unknown): string;

package/dist/yargs-burgee.js

@@ -0,0 +1,104 @@
+import { camelCase } from './yargs-parser.js';
+const DEFER_PREFIX = '__yargsString__:';
+function describe(descriptions, key) {
+    const raw = descriptions[key];
+    if (raw === undefined || raw === '')
+        return undefined;
+    return raw.startsWith(DEFER_PREFIX) ? raw.slice(DEFER_PREFIX.length) : raw;
+}
+function typeOf(s, key) {
+    const any = (list) => list.includes(key) || (s.aliases[key] ?? []).some((a) => list.includes(a));
+    if (any(s.boolean))
+        return 'boolean';
+    if (any(s.number) || any(s.count))
+        return 'number';
+    return 'string';
+}
+export function optionSpecs(s) {
+    const specs = Object.create(null);
+    const aliasOf = new Set();
+    for (const [key, list] of Object.entries(s.aliases)) {
+        if (s.keys.includes(key))
+            for (const a of list)
+                aliasOf.add(a);
+    }
+    const positional = new Set([...s.positionals.demanded, ...s.positionals.optional].flatMap((p) => p.cmd));
+    for (const key of s.keys) {
+        if (s.skip.includes(key) || aliasOf.has(key) || positional.has(key) || key.includes('.'))
+            continue;
+        const spec = { type: typeOf(s, key) };
+        const aliases = s.aliases[key] ?? [];
+        const short = aliases.find((a) => a.length === 1 && !/^[0-9]$/.test(a));
+        if (short !== undefined)
+            spec.short = short;
+        const desc = describe(s.descriptions, key) ?? aliases.map((a) => describe(s.descriptions, a)).find((d) => d !== undefined);
+        if (desc !== undefined)
+            spec.description = desc;
+        if (key in s.demanded || aliases.some((a) => a in s.demanded))
+            spec.required = true;
+        if (s.array.includes(key) || aliases.some((a) => s.array.includes(a)))
+            spec.multiple = true;
+        const choices = s.choices[key] ?? aliases.map((a) => s.choices[a]).find((c) => c !== undefined);
+        if (choices !== undefined)
+            spec.choices = choices.map(String);
+        const def = s.defaults[key];
+        if (typeof def === 'string' || typeof def === 'boolean' || typeof def === 'number')
+            spec.default = def;
+        else if (Array.isArray(def) && def.every((d) => typeof d === 'string'))
+            spec.default = def;
+        if (s.hiddenOptions.includes(key))
+            spec.hidden = true;
+        const deprecated = s.deprecated[key];
+        if (deprecated !== undefined && deprecated !== false)
+            spec.deprecated = deprecated;
+        Object.defineProperty(specs, camelCase(key), { value: spec, enumerable: true, writable: true, configurable: true });
+    }
+    return specs;
+}
+function argumentsOf(s) {
+    const out = [];
+    const push = (p, required) => {
+        const name = p.cmd[0];
+        const desc = describe(s.descriptions, name);
+        out.push({ name, required, variadic: p.variadic, ...(desc === undefined ? {} : { description: desc }) });
+    };
+    for (const p of s.positionals.demanded)
+        push(p, true);
+    for (const p of s.positionals.optional)
+        push(p, false);
+    return out;
+}
+export function projectManifest(manifest, root) {
+    const contributed = manifest.commands.filter((c) => c.plugin !== undefined);
+    manifest.commands.splice(0, manifest.commands.length, ...contributed);
+    manifest.rootPath = [root.name];
+    if (root.version !== undefined)
+        manifest.version = root.version;
+    const visit = (s, at, description, deprecated) => {
+        const args = argumentsOf(s);
+        manifest.add({
+            path: at,
+            ...(description === undefined ? {} : { description }),
+            ...(s.effects === undefined ? {} : { effects: s.effects }),
+            ...(deprecated === undefined || deprecated === false ? {} : { deprecated }),
+            options: optionSpecs(s),
+            ...(args.length === 0 ? {} : { arguments: args }),
+            ...(s.hasHandler ? { run: () => undefined } : {}),
+        });
+        for (const c of s.commands)
+            visit(c.child, [...at, c.name], c.description === false ? undefined : c.description, c.deprecated);
+    };
+    visit(root, [root.name], root.description, undefined);
+}
+export function render(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string')
+        return `${value}\n`;
+    if (typeof value === 'object' && !Array.isArray(value)) {
+        return Object.entries(value)
+            .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}\n`)
+            .join('');
+    }
+    return `${JSON.stringify(value)}\n`;
+}

package/dist/yargs-cliui.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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
+ * 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 function wrapAnsi(string: string, columns: number, options?: WrapOptions): string;
+export interface Column {
+    text: string;
+    width?: number | undefined;
+    align?: 'right' | 'left' | 'center';
+    padding: number[];
+    border?: boolean;
+}
+interface ColumnArray extends Array<Column> {
+    span?: boolean;
+}
+interface Line {
+    hidden?: boolean;
+    text: string;
+    span?: boolean | undefined;
+}
+export declare class UI {
+    width: number;
+    wrap: boolean;
+    rows: ColumnArray[];
+    constructor(opts: {
+        width: number;
+        wrap?: boolean | undefined;
+    });
+    span(...args: (Column | string)[]): void;
+    resetOutput(): void;
+    div(...args: (Column | string)[]): ColumnArray;
+    private shouldApplyLayoutDSL;
+    private applyLayoutDSL;
+    private colFromString;
+    private measurePadding;
+    toString(): string;
+    rowToString(row: ColumnArray, lines: Line[]): Line[];
+    private renderInline;
+    private rasterize;
+    private negatePadding;
+    private columnWidths;
+}
+export declare function cliui(opts?: {
+    width?: number | null | undefined;
+    wrap?: boolean | undefined;
+}): UI;
+export {};