@markuplint/cli-utils 4.4.12 → 4.4.14

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.4.14](https://github.com/markuplint/markuplint/compare/@markuplint/cli-utils@4.4.13...@markuplint/cli-utils@4.4.14) (2026-02-10)
+
+**Note:** Version bump only for package @markuplint/cli-utils
+
+## [4.4.13](https://github.com/markuplint/markuplint/compare/@markuplint/cli-utils@4.4.12...@markuplint/cli-utils@4.4.13) (2025-11-05)
+
+**Note:** Version bump only for package @markuplint/cli-utils
+
 ## [4.4.12](https://github.com/markuplint/markuplint/compare/@markuplint/cli-utils@4.4.11...@markuplint/cli-utils@4.4.12) (2025-08-13)
 
 ### Bug Fixes

package/lib/color.d.ts

@@ -1 +1,9 @@
+/**
+ * Creates a curried function that applies an xTerm 256-color foreground color
+ * to the given text using ANSI escape sequences. Falls back to plain text
+ * when color output is not supported.
+ *
+ * @param index - The xTerm 256-color palette index (0-255)
+ * @returns A function that wraps the given text with the specified color escape codes
+ */
 export declare const xterm: (index: number) => (text: string) => string;

package/lib/color.js

@@ -1,4 +1,12 @@
 import c from 'picocolors';
+/**
+ * Creates a curried function that applies an xTerm 256-color foreground color
+ * to the given text using ANSI escape sequences. Falls back to plain text
+ * when color output is not supported.
+ *
+ * @param index - The xTerm 256-color palette index (0-255)
+ * @returns A function that wraps the given text with the specified color escape codes
+ */
 export const xterm = (index) => (text) => {
     // https://github.com/jaywcjlove/colors-cli/blob/d3a3152ec2f087c46655e7d2a663ef637ed5fea5/lib/color.js#L121
     return c.isColorSupported ? '\u001B[38;5;' + index + 'm' + text + '\u001B[0m' : text;

package/lib/get-width.d.ts

@@ -1 +1,8 @@
+/**
+ * Calculates the visual display width of a string, accounting for
+ * East Asian wide characters that occupy two columns in a terminal.
+ *
+ * @param s - The string to measure
+ * @returns The total display width in terminal columns
+ */
 export declare function getWidth(s: string): number;

package/lib/get-width.js

@@ -1,6 +1,13 @@
 // @ts-ignore
 import eastasianwidth from 'eastasianwidth';
 const eaw = eastasianwidth;
+/**
+ * Calculates the visual display width of a string, accounting for
+ * East Asian wide characters that occupy two columns in a terminal.
+ *
+ * @param s - The string to measure
+ * @returns The total display width in terminal columns
+ */
 export function getWidth(s) {
     let width = 0;
     for (const char of s) {

package/lib/header.d.ts

@@ -1 +1,9 @@
+/**
+ * Generates a formatted CLI header box containing the markuplint logo,
+ * name, version, and the given sub-command name.
+ *
+ * @param subCommandName - The name of the sub-command to display in the header
+ * @param noColor - When true, strips ANSI color codes from the output
+ * @returns A multi-line string representing the boxed header
+ */
 export declare const header: (subCommandName: string, noColor?: boolean) => string;

package/lib/header.js

@@ -5,6 +5,14 @@ import { logo } from './logo.js';
 import { name } from './name.js';
 const require = module.createRequire(import.meta.url);
 const version = require('../package.json').version;
+/**
+ * Generates a formatted CLI header box containing the markuplint logo,
+ * name, version, and the given sub-command name.
+ *
+ * @param subCommandName - The name of the sub-command to display in the header
+ * @param noColor - When true, strips ANSI color codes from the output
+ * @returns A multi-line string representing the boxed header
+ */
 export const header = (subCommandName, noColor) => box([
     // Logo and name
     `${logo} ${name}`,

package/lib/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @module @markuplint/cli-utils
+ *
+ * Shared CLI utility functions for the markuplint command-line interface.
+ * Provides terminal color helpers, text formatting, interactive prompts,
+ * module installation, and display utilities used across markuplint CLI commands.
+ */
 export { default as font } from 'picocolors';
 export { xterm } from './color.js';
 export { input, confirm, confirmSequence, select, multiSelect } from './prompt.js';

package/lib/index.js

@@ -1,3 +1,10 @@
+/**
+ * @module @markuplint/cli-utils
+ *
+ * Shared CLI utility functions for the markuplint command-line interface.
+ * Provides terminal color helpers, text formatting, interactive prompts,
+ * module installation, and display utilities used across markuplint CLI commands.
+ */
 export { default as font } from 'picocolors';
 export { xterm } from './color.js';
 export { input, confirm, confirmSequence, select, multiSelect } from './prompt.js';

package/lib/install-module.d.ts

@@ -1,5 +1,16 @@
+/**
+ * Represents the outcome of an {@link installModule} operation.
+ */
 export type InstallModuleResult = {
     success: boolean;
     alreadyExists: boolean;
 };
+/**
+ * Installs one or more npm packages using the detected package manager
+ * (yarn or npm). Skips modules that are already installed locally.
+ *
+ * @param module - An array of module names to install
+ * @param dev - When true, installs as a dev dependency (adds the `-D` flag)
+ * @returns The result indicating success and whether all modules already existed
+ */
 export declare function installModule(module: readonly string[], dev?: boolean): Promise<InstallModuleResult>;

package/lib/install-module.js

@@ -3,6 +3,14 @@ import c from 'picocolors';
 // @ts-ignore
 import detectInstalled from 'detect-installed';
 import hasYarn from 'has-yarn';
+/**
+ * Installs one or more npm packages using the detected package manager
+ * (yarn or npm). Skips modules that are already installed locally.
+ *
+ * @param module - An array of module names to install
+ * @param dev - When true, installs as a dev dependency (adds the `-D` flag)
+ * @returns The result indicating success and whether all modules already existed
+ */
 export async function installModule(module, dev = false) {
     module = module.map(m => m.trim());
     const uninstallMods = [];

package/lib/invisible-space.d.ts

@@ -1,7 +1,9 @@
 /**
- * Convert all characters to space.
+ * Converts all visible characters in a string to spaces, preserving
+ * the visual width. Tabs are expanded to four spaces before conversion.
+ * Useful for generating indentation-preserving blank lines in CLI output.
  *
- * @param str
- * @returns
+ * @param str - The input string whose characters will be replaced with spaces
+ * @returns A string of the same visual length consisting only of space characters
  */
 export declare function invisibleSpace(str: string): string;

package/lib/invisible-space.js

@@ -1,8 +1,10 @@
 /**
- * Convert all characters to space.
+ * Converts all visible characters in a string to spaces, preserving
+ * the visual width. Tabs are expanded to four spaces before conversion.
+ * Useful for generating indentation-preserving blank lines in CLI output.
  *
- * @param str
- * @returns
+ * @param str - The input string whose characters will be replaced with spaces
+ * @returns A string of the same visual length consisting only of space characters
  */
 export function invisibleSpace(str) {
     return (str

package/lib/logo.d.ts

@@ -1 +1,2 @@
+/** The markuplint logo rendered as a styled checkmark for terminal display. */
 export declare const logo: string;

package/lib/logo.js

@@ -1,3 +1,4 @@
 import { xterm } from './color.js';
 import { PRIMARY_COLOR } from './const.js';
+/** The markuplint logo rendered as a styled checkmark for terminal display. */
 export const logo = `/${xterm(PRIMARY_COLOR)('✔')}\\`;

package/lib/message-to-string.d.ts

@@ -1 +1,9 @@
+/**
+ * Combines a lint violation message with an optional reason string.
+ * When a reason is provided, it is appended after a " / " separator.
+ *
+ * @param message - The primary violation message
+ * @param reason - An optional supplementary reason or detail to append
+ * @returns The combined message string
+ */
 export declare function messageToString(message: string, reason?: string): string;

package/lib/message-to-string.js

@@ -1,3 +1,11 @@
+/**
+ * Combines a lint violation message with an optional reason string.
+ * When a reason is provided, it is appended after a " / " separator.
+ *
+ * @param message - The primary violation message
+ * @param reason - An optional supplementary reason or detail to append
+ * @returns The combined message string
+ */
 export function messageToString(message, reason) {
     if (!reason) {
         return message;

package/lib/name.d.ts

@@ -1 +1,2 @@
+/** The styled markuplint product name with the "lint" portion colored in the brand color. */
 export declare const name: string;

package/lib/name.js

@@ -1,3 +1,4 @@
 import { xterm } from './color.js';
 import { PRIMARY_COLOR } from './const.js';
+/** The styled markuplint product name with the "lint" portion colored in the brand color. */
 export const name = `Markup${xterm(PRIMARY_COLOR)('lint')}`;

package/lib/pad.d.ts

@@ -1 +1,10 @@
+/**
+ * Pads a string or number with spaces to reach the specified display width.
+ * Accounts for East Asian wide characters when calculating the current width.
+ *
+ * @param s - The value to pad (converted to string if numeric)
+ * @param pad - The target display width in terminal columns
+ * @param start - When true, prepends spaces (right-aligns); otherwise appends spaces (left-aligns)
+ * @returns The padded string
+ */
 export declare function pad(s: number | string, pad: number, start?: boolean): string;

package/lib/pad.js

@@ -1,4 +1,13 @@
 import { getWidth } from './get-width.js';
+/**
+ * Pads a string or number with spaces to reach the specified display width.
+ * Accounts for East Asian wide characters when calculating the current width.
+ *
+ * @param s - The value to pad (converted to string if numeric)
+ * @param pad - The target display width in terminal columns
+ * @param start - When true, prepends spaces (right-aligns); otherwise appends spaces (left-aligns)
+ * @returns The padded string
+ */
 export function pad(s, pad, start = false) {
     const l = getWidth(`${s}`.trim());
     const d = pad - l;

package/lib/prompt.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Defines a question for single or multi-select prompts.
+ *
+ * @template T - The type of the value associated with each choice
+ */
 type SelectQuestion<T> = {
     readonly message: string;
     readonly choices: readonly {
@@ -5,12 +10,51 @@ type SelectQuestion<T> = {
         readonly value: T;
     }[];
 };
+/**
+ * Displays an interactive single-select prompt and returns the chosen value.
+ *
+ * @template T - The type of the value returned by the selected choice
+ * @param question - The question configuration including message and available choices
+ * @returns The value of the selected choice
+ */
 export declare function select<T>(question: SelectQuestion<T>): Promise<T>;
+/**
+ * Displays an interactive multi-select prompt and returns an array of chosen values.
+ *
+ * @template T - The type of the values returned by the selected choices
+ * @param question - The question configuration including message and available choices
+ * @returns An array of values corresponding to the selected choices
+ */
 export declare function multiSelect<T>(question: SelectQuestion<T>): Promise<T[]>;
+/**
+ * Displays an interactive text input prompt. Re-prompts the user if the
+ * input fails the optional validation pattern.
+ *
+ * @template T - The string subtype returned by the prompt
+ * @param question - The message to display as the prompt question
+ * @param validation - An optional regex pattern the input must match
+ * @returns The validated user input string
+ */
 export declare function input<T extends string = string>(question: string, validation?: Readonly<RegExp>): Promise<T>;
+/**
+ * Displays an interactive yes/no confirmation prompt.
+ *
+ * @param question - The message to display as the confirmation question
+ * @param options - Optional settings for the prompt
+ * @param options.initial - The default answer when the user presses Enter without input
+ * @returns `true` if the user confirmed, `false` otherwise
+ */
 export declare function confirm(question: string, options?: {
     readonly initial?: boolean;
 }): Promise<boolean>;
+/**
+ * Displays a sequence of yes/no confirmation prompts and collects all answers
+ * into a single record keyed by each question's name.
+ *
+ * @template T - The string literal union type of question names
+ * @param questions - An array of question objects, each with a message and a unique name
+ * @returns A record mapping each question name to its boolean answer
+ */
 export declare function confirmSequence<T extends string = string>(questions: readonly {
     readonly message: string;
     readonly name: T;

package/lib/prompt.js

@@ -1,5 +1,12 @@
 import c from 'picocolors';
 import Enquirer from 'enquirer';
+/**
+ * Displays an interactive single-select prompt and returns the chosen value.
+ *
+ * @template T - The type of the value returned by the selected choice
+ * @param question - The question configuration including message and available choices
+ * @returns The value of the selected choice
+ */
 export async function select(question) {
     const res = await Enquirer.prompt({
         ...question,
@@ -13,6 +20,13 @@ export async function select(question) {
     // @ts-ignore
     return res['__Q__'];
 }
+/**
+ * Displays an interactive multi-select prompt and returns an array of chosen values.
+ *
+ * @template T - The type of the values returned by the selected choices
+ * @param question - The question configuration including message and available choices
+ * @returns An array of values corresponding to the selected choices
+ */
 export async function multiSelect(question) {
     const res = await Enquirer.prompt({
         ...question,
@@ -29,6 +43,15 @@ export async function multiSelect(question) {
     // @ts-ignore
     return res['__Q__'];
 }
+/**
+ * Displays an interactive text input prompt. Re-prompts the user if the
+ * input fails the optional validation pattern.
+ *
+ * @template T - The string subtype returned by the prompt
+ * @param question - The message to display as the prompt question
+ * @param validation - An optional regex pattern the input must match
+ * @returns The validated user input string
+ */
 export async function input(question, validation) {
     while (true) {
         const _res = await Enquirer.prompt({
@@ -45,6 +68,14 @@ export async function input(question, validation) {
         return res;
     }
 }
+/**
+ * Displays an interactive yes/no confirmation prompt.
+ *
+ * @param question - The message to display as the confirmation question
+ * @param options - Optional settings for the prompt
+ * @param options.initial - The default answer when the user presses Enter without input
+ * @returns `true` if the user confirmed, `false` otherwise
+ */
 export async function confirm(question, options) {
     const res = await Enquirer.prompt({
         message: question,
@@ -55,6 +86,14 @@ export async function confirm(question, options) {
     // @ts-ignore
     return !!res['__Q__'];
 }
+/**
+ * Displays a sequence of yes/no confirmation prompts and collects all answers
+ * into a single record keyed by each question's name.
+ *
+ * @template T - The string literal union type of question names
+ * @param questions - An array of question objects, each with a message and a unique name
+ * @returns A record mapping each question name to its boolean answer
+ */
 export async function confirmSequence(questions) {
     const res = await Enquirer.prompt(questions.map(question => {
         return {

package/lib/space.d.ts

@@ -1,7 +1,9 @@
 /**
- * Replace space to visible characters.
+ * Replaces whitespace characters with visible symbols for debugging display.
+ * Spaces become middle dots (`\u2022`) and tabs become right arrows (`\u2192`) followed
+ * by three spaces. All whitespace is dimmed using xTerm color 8.
  *
- * @param str
- * @returns
+ * @param str - The input string containing whitespace to visualize
+ * @returns The string with whitespace replaced by visible indicator characters
  */
 export declare function space(str: string): string;

package/lib/space.js

@@ -1,9 +1,11 @@
 import { xterm } from './color.js';
 /**
- * Replace space to visible characters.
+ * Replaces whitespace characters with visible symbols for debugging display.
+ * Spaces become middle dots (`\u2022`) and tabs become right arrows (`\u2192`) followed
+ * by three spaces. All whitespace is dimmed using xTerm color 8.
  *
- * @param str
- * @returns
+ * @param str - The input string containing whitespace to visualize
+ * @returns The string with whitespace replaced by visible indicator characters
  */
 export function space(str) {
     return str

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/cli-utils",
-	"version": "4.4.12",
+	"version": "4.4.14",
 	"description": "Utilities for CLI of Markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -24,9 +24,9 @@
 		"detect-installed": "2.0.4",
 		"eastasianwidth": "0.3.0",
 		"enquirer": "2.4.1",
-		"has-yarn": "3.0.0",
+		"has-yarn": "4.0.0",
 		"picocolors": "1.1.1",
-		"strip-ansi": "7.1.0"
+		"strip-ansi": "7.1.2"
 	},
-	"gitHead": "acbf53f7e30d7a59f850a0f279b617383266dab3"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }