@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/dist/io/logger.d.ts

@@ -0,0 +1,11 @@
+import type { KtxCliIo } from '../cli-runtime.js';
+import type { KtxOutputMode } from './mode.js';
+export interface KtxOperationalLogger {
+    log(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug?(message: string): void;
+}
+export type KtxOperationalOutputMode = KtxOutputMode | 'viz';
+export declare function createNoopOperationalLogger(): KtxOperationalLogger;
+export declare function createCliOperationalLogger(io: KtxCliIo, mode: KtxOperationalOutputMode): KtxOperationalLogger;

package/dist/io/logger.js

@@ -0,0 +1,22 @@
+function writeLine(io, message) {
+    io.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
+}
+export function createNoopOperationalLogger() {
+    return {
+        log: () => undefined,
+        warn: () => undefined,
+        error: () => undefined,
+        debug: () => undefined,
+    };
+}
+export function createCliOperationalLogger(io, mode) {
+    if (mode === 'json') {
+        return createNoopOperationalLogger();
+    }
+    return {
+        log: (message) => writeLine(io, message),
+        warn: (message) => writeLine(io, message),
+        error: (message) => writeLine(io, message),
+        debug: (message) => writeLine(io, message),
+    };
+}

package/dist/io/logger.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/io/logger.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createCliOperationalLogger, createNoopOperationalLogger } from './logger.js';
+function makeIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: {
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+describe('createCliOperationalLogger', () => {
+    it('routes operational messages to stderr outside JSON mode', () => {
+        const io = makeIo();
+        const logger = createCliOperationalLogger(io.io, 'plain');
+        logger.log('progress');
+        logger.warn('warning');
+        logger.error('failure');
+        logger.debug?.('debug');
+        expect(io.stdout()).toBe('');
+        expect(io.stderr()).toBe('progress\nwarning\nfailure\ndebug\n');
+    });
+    it('suppresses operational messages in JSON mode by default', () => {
+        const io = makeIo();
+        const logger = createCliOperationalLogger(io.io, 'json');
+        logger.log('progress');
+        logger.warn('warning');
+        logger.error('failure');
+        logger.debug?.('debug');
+        expect(io.stdout()).toBe('');
+        expect(io.stderr()).toBe('');
+    });
+});
+describe('createNoopOperationalLogger', () => {
+    it('never writes', () => {
+        const logger = createNoopOperationalLogger();
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        logger.log('progress');
+        logger.warn('warning');
+        logger.error('failure');
+        logger.debug?.('debug');
+        expect(warn).not.toHaveBeenCalled();
+    });
+});

package/dist/io/mode.d.ts

@@ -0,0 +1,9 @@
+import type { KtxCliIo } from '../cli-runtime.js';
+export type KtxOutputMode = 'pretty' | 'plain' | 'json';
+export interface ResolveOutputModeArgs {
+    explicit?: string;
+    json?: boolean;
+    io: KtxCliIo;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function resolveOutputMode(args: ResolveOutputModeArgs): KtxOutputMode;

package/dist/io/mode.js

@@ -0,0 +1,28 @@
+const MODES = new Set(['pretty', 'plain', 'json']);
+export function resolveOutputMode(args) {
+    if (args.json === true) {
+        return 'json';
+    }
+    if (args.explicit !== undefined) {
+        if (!MODES.has(args.explicit)) {
+            throw new Error(`Invalid --output value: ${args.explicit}. Expected one of pretty, plain, json.`);
+        }
+        return args.explicit;
+    }
+    const env = args.env ?? process.env;
+    const envMode = env.KTX_OUTPUT;
+    if (envMode !== undefined && envMode !== '') {
+        if (!MODES.has(envMode)) {
+            throw new Error(`Invalid KTX_OUTPUT value: ${envMode}. Expected one of pretty, plain, json.`);
+        }
+        return envMode;
+    }
+    const ci = env.CI;
+    if (ci !== undefined && ci !== '' && ci !== '0' && ci !== 'false') {
+        return 'plain';
+    }
+    if (args.io.stdout.isTTY === true) {
+        return 'pretty';
+    }
+    return 'plain';
+}

package/dist/io/mode.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/io/mode.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { resolveOutputMode } from './mode.js';
+function ioWith(isTTY) {
+    return {
+        stdout: { isTTY, write: () => { } },
+        stderr: { write: () => { } },
+    };
+}
+describe('resolveOutputMode', () => {
+    it('uses explicit value when provided', () => {
+        expect(resolveOutputMode({ explicit: 'pretty', io: ioWith(false), env: {} })).toBe('pretty');
+        expect(resolveOutputMode({ explicit: 'plain', io: ioWith(true), env: {} })).toBe('plain');
+        expect(resolveOutputMode({ explicit: 'json', io: ioWith(true), env: {} })).toBe('json');
+    });
+    it('json:true takes precedence over explicit value', () => {
+        expect(resolveOutputMode({ explicit: 'pretty', json: true, io: ioWith(true), env: {} })).toBe('json');
+    });
+    it('throws on unknown explicit value', () => {
+        expect(() => resolveOutputMode({ explicit: 'fancy', io: ioWith(true), env: {} })).toThrow(/Invalid --output/);
+    });
+    it('honors KTX_OUTPUT env var when no explicit value', () => {
+        expect(resolveOutputMode({ io: ioWith(true), env: { KTX_OUTPUT: 'plain' } })).toBe('plain');
+        expect(resolveOutputMode({ io: ioWith(false), env: { KTX_OUTPUT: 'pretty' } })).toBe('pretty');
+        expect(resolveOutputMode({ io: ioWith(false), env: { KTX_OUTPUT: 'json' } })).toBe('json');
+    });
+    it('throws on unknown KTX_OUTPUT', () => {
+        expect(() => resolveOutputMode({ io: ioWith(true), env: { KTX_OUTPUT: 'fancy' } })).toThrow(/Invalid KTX_OUTPUT/);
+    });
+    it('returns plain when CI is set to a truthy value', () => {
+        expect(resolveOutputMode({ io: ioWith(true), env: { CI: 'true' } })).toBe('plain');
+        expect(resolveOutputMode({ io: ioWith(true), env: { CI: '1' } })).toBe('plain');
+    });
+    it('ignores CI when set to a falsy value', () => {
+        expect(resolveOutputMode({ io: ioWith(true), env: { CI: '' } })).toBe('pretty');
+        expect(resolveOutputMode({ io: ioWith(true), env: { CI: '0' } })).toBe('pretty');
+        expect(resolveOutputMode({ io: ioWith(true), env: { CI: 'false' } })).toBe('pretty');
+    });
+    it('returns pretty when stdout is a TTY and CI is not set', () => {
+        expect(resolveOutputMode({ io: ioWith(true), env: {} })).toBe('pretty');
+    });
+    it('returns plain when stdout is not a TTY', () => {
+        expect(resolveOutputMode({ io: ioWith(false), env: {} })).toBe('plain');
+        expect(resolveOutputMode({ io: ioWith(undefined), env: {} })).toBe('plain');
+    });
+    it('explicit value beats KTX_OUTPUT env var', () => {
+        expect(resolveOutputMode({ explicit: 'json', io: ioWith(true), env: { KTX_OUTPUT: 'plain' } })).toBe('json');
+    });
+});

package/dist/io/print-list.d.ts

@@ -0,0 +1,42 @@
+import type { KtxCliIo } from '../cli-runtime.js';
+import type { KtxOutputMode } from './mode.js';
+export interface PrintListColumn<Row> {
+    key: keyof Row & string;
+    label?: string;
+    /**
+     * Plain-mode rendering control.
+     * - `string` (including `''`): emit `${plain}${value}` as a tab-separated cell.
+     * - `false`: omit this column entirely in plain mode.
+     * - `undefined`: same as `''`.
+     */
+    plain?: string | false;
+    /** Skip this column when the row's value is null / undefined / empty string. */
+    optional?: boolean;
+    /** Pretty-mode hint: render this column dim. */
+    dim?: boolean;
+    /**
+     * Pretty-mode role override. When omitted, role is auto-detected:
+     * - `'badge'`  — leading cell before the name column (right-padded across rows).
+     * - `'name'`   — name column. Default: first non-grouped, non-metric, non-optional column.
+     * - `'metric'` — `"N word"` cell. Default: any column with a non-empty `plain` prefix.
+     * - `'suffix'` — trailing em-dash optional value. Default: any column with `optional: true`.
+     */
+    role?: 'name' | 'metric' | 'badge' | 'suffix';
+    /** Custom pretty-mode value formatter (e.g. score → "87%"). Plain/JSON unaffected. */
+    prettyFormat?: (value: Row[keyof Row & string], row: Row) => string;
+}
+export interface PrintListArgs<Row> {
+    rows: ReadonlyArray<Row>;
+    columns: ReadonlyArray<PrintListColumn<Row>>;
+    groupBy?: keyof Row & string;
+    emptyMessage: string;
+    /** Optional second-line hint shown on empty results.
+     *  Plain mode: written to stderr. Pretty mode: dimmed line inside the box. JSON mode: ignored. */
+    emptyHint?: string;
+    /** Singular noun used in counts (`N {unit}s`, `(N {unit}s)`). Defaults to `'result'`. */
+    unit?: string;
+    command: string;
+    mode: KtxOutputMode;
+    io: KtxCliIo;
+}
+export declare function printList<Row extends object>(args: PrintListArgs<Row>): void;

package/dist/io/print-list.js

@@ -0,0 +1,192 @@
+import { bold, dim, SYMBOLS } from './symbols.js';
+function writeJsonResult(io, envelope) {
+    io.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+}
+export function printList(args) {
+    switch (args.mode) {
+        case 'json':
+            printListJson(args);
+            return;
+        case 'plain':
+            printListPlain(args);
+            return;
+        case 'pretty':
+            printListPretty(args);
+            return;
+    }
+}
+function isEmpty(value) {
+    return value === undefined || value === null || value === '';
+}
+function printListPlain(args) {
+    if (args.rows.length === 0) {
+        if (args.emptyHint !== undefined && args.emptyHint !== '') {
+            // Plain mode keeps stdout pipe-safe. Send the human-readable empty
+            // state to stderr as two lines (message, then hint).
+            args.io.stderr.write(`${args.emptyMessage}\n`);
+            args.io.stderr.write(`${args.emptyHint}\n`);
+        }
+        return;
+    }
+    for (const row of args.rows) {
+        const cells = [];
+        for (const col of args.columns) {
+            if (col.plain === false)
+                continue;
+            const value = row[col.key];
+            if (col.optional && isEmpty(value))
+                continue;
+            const prefix = col.plain ?? '';
+            cells.push(`${prefix}${value === undefined || value === null ? '' : String(value)}`);
+        }
+        args.io.stdout.write(`${cells.join('\t')}\n`);
+    }
+}
+function printListJson(args) {
+    writeJsonResult(args.io, {
+        kind: 'list',
+        data: { items: args.rows },
+        meta: { command: args.command },
+    });
+}
+function pluralize(count, singular) {
+    return `${count} ${count === 1 ? singular : `${singular}s`}`;
+}
+function metricCell(label, count) {
+    // "5 cols", "3 measures", "1 join" / "2 joins"
+    // The label in PrintListColumn is uppercase; pretty mode lowercases it.
+    const word = label.toLowerCase();
+    return `${count} ${count === 1 ? singularize(word) : word}`;
+}
+function singularize(word) {
+    if (word === 'joins')
+        return 'join';
+    if (word === 'measures')
+        return 'measure';
+    if (word === 'cols')
+        return 'col';
+    if (word.endsWith('s'))
+        return word.slice(0, -1);
+    return word;
+}
+function groupRows(rows, key) {
+    const groups = new Map();
+    for (const row of rows) {
+        const value = String(row[key] ?? '');
+        const bucket = groups.get(value);
+        if (bucket) {
+            bucket.push(row);
+        }
+        else {
+            groups.set(value, [row]);
+        }
+    }
+    return groups;
+}
+function resolveColumns(columns, groupBy) {
+    const badge = [];
+    const metric = [];
+    const suffix = [];
+    let name;
+    for (const col of columns) {
+        if (col.role === 'badge') {
+            badge.push(col);
+            continue;
+        }
+        if (col.role === 'name') {
+            name ??= col;
+            continue;
+        }
+        if (col.role === 'metric') {
+            metric.push(col);
+            continue;
+        }
+        if (col.role === 'suffix') {
+            suffix.push(col);
+            continue;
+        }
+        // Auto-detect when no explicit role.
+        if (col.key === groupBy)
+            continue;
+        if (col.optional === true) {
+            suffix.push(col);
+            continue;
+        }
+        if (typeof col.plain === 'string' && col.plain.length > 0) {
+            metric.push(col);
+            continue;
+        }
+        if (!name && !col.plain && col.plain !== false) {
+            name = col;
+        }
+    }
+    return { badge, name, metric, suffix };
+}
+function formatCellValue(col, row) {
+    const value = row[col.key];
+    if (col.prettyFormat) {
+        return col.prettyFormat(value, row);
+    }
+    if (value === undefined || value === null)
+        return '';
+    return String(value);
+}
+function printListPretty(args) {
+    const { io, command, rows, columns, groupBy, emptyMessage, emptyHint } = args;
+    const unit = args.unit ?? 'result';
+    io.stdout.write(`${bold(command)}\n`);
+    if (rows.length === 0) {
+        io.stdout.write(`\n  ${emptyMessage}\n`);
+        if (emptyHint !== undefined && emptyHint !== '') {
+            io.stdout.write(`  ${dim(emptyHint)}\n`);
+        }
+        io.stdout.write('\n');
+        return;
+    }
+    io.stdout.write('\n');
+    const resolved = resolveColumns(columns, groupBy);
+    const buckets = groupBy ? groupRows(rows, groupBy) : new Map([['', [...rows]]]);
+    const nameWidth = resolved.name
+        ? Math.max(...rows.map((r) => String(r[resolved.name.key] ?? '').length))
+        : 0;
+    const badgeWidths = resolved.badge.map((col) => Math.max(0, ...rows.map((r) => formatCellValue(col, r).length)));
+    for (const [groupValue, groupRowList] of buckets) {
+        if (groupBy) {
+            io.stdout.write(`  ${bold(groupValue)} ${dim(`(${pluralize(groupRowList.length, unit)})`)}\n`);
+        }
+        for (const row of groupRowList) {
+            const segments = [];
+            resolved.badge.forEach((col, idx) => {
+                segments.push(formatCellValue(col, row).padStart(badgeWidths[idx] ?? 0));
+            });
+            if (resolved.name) {
+                segments.push(String(row[resolved.name.key] ?? '').padEnd(nameWidth));
+            }
+            const metrics = resolved.metric
+                .map((col) => {
+                if (col.prettyFormat)
+                    return formatCellValue(col, row);
+                return metricCell(col.label ?? col.key, Number(row[col.key] ?? 0));
+            })
+                .join(` ${SYMBOLS.middot} `);
+            if (metrics.length > 0)
+                segments.push(dim(metrics));
+            const optionalSuffix = resolved.suffix
+                .map((col) => {
+                const value = row[col.key];
+                if (isEmpty(value))
+                    return null;
+                const formatted = col.prettyFormat ? formatCellValue(col, row) : String(value);
+                return `${SYMBOLS.emDash} ${dim(formatted)}`;
+            })
+                .filter((s) => s !== null)
+                .join(' ');
+            if (optionalSuffix.length > 0)
+                segments.push(optionalSuffix);
+            const indent = groupBy ? '    ' : '  ';
+            io.stdout.write(`${indent}${segments.join('  ')}\n`);
+        }
+        io.stdout.write('\n');
+    }
+    io.stdout.write(`${pluralize(rows.length, unit)}\n`);
+}

package/dist/io/print-list.test.d.ts

@@ -0,0 +1 @@
+export {};