Improve CLI error logs (#774)

This PR introduces a `CliError` class that displays better error messages (with sub-item support).

Author: lorisleiva

packages/cli/README.md

@@ -28,7 +28,7 @@ pnpm codama init --gill
 
 ## `codama run`
 
-Once you have your codama config file, you can run your Codama scripts using the `codama run` command as follows:
+Once you have your codama configuration file, you can run your Codama scripts using the `codama run` command as follows:
 
 ```sh
 pnpm codama run         # Only runs your before visitors.
@@ -38,7 +38,7 @@ pnpm codama run --all   # Runs your before visitors followed by all your scripts
 
 ## The configuration file
 
-The codama config file defines an object containing the following fields:
+The codama configuration file defines an object containing the following fields:
 
 - `idl` (string): The path to the IDL file. This can be a Codama IDL or an Anchor IDL which will be automatically converted to a Codama IDL.
 - `before` (array): An array of visitors that will run before every script.

packages/cli/src/cli/index.ts

@@ -1,3 +1,5 @@
+import pico from 'picocolors';
+
 import { createProgram } from '../program';
 import { logDebug, logError } from '../utils';
 
@@ -7,10 +9,11 @@ export async function run(argv: readonly string[]) {
     try {
         await program.parseAsync(argv);
     } catch (err) {
+        const error = err as { message: string; stack?: string; items?: string[] };
         if (program.opts().debug) {
-            logDebug(`${(err as { stack: string }).stack}`);
+            logDebug(`${error.stack}`);
         }
-        logError((err as { message: string }).message);
+        logError(pico.bold(error.message), error.items ?? []);
         process.exitCode = 1;
     }
 }

packages/cli/src/commands/init.ts

@@ -5,6 +5,7 @@ import prompts, { PromptType } from 'prompts';
 import { Config, ScriptConfig, ScriptName } from '../config';
 import {
     canRead,
+    CliError,
     importModuleItem,
     installMissingDependencies,
     isRootNode,
@@ -36,14 +37,26 @@ async function doInit(explicitOutput: string | undefined, options: InitOptions)
     const configFileType = getConfigFileType(output, options);
 
     if (await canRead(output)) {
-        throw new Error(`Configuration file already exists at "${output}".`);
+        throw new CliError(`Configuration file already exists.`, [`${pico.bold('Path')}: ${output}`]);
     }
 
+    // Start prompts.
     logBanner();
     const result = await getPromptResult(options, configFileType);
+
+    // Check dependencies.
+    const isAnchor = await isAnchorIdl(result.idlPath);
+    await installMissingDependencies(`Your configuration requires additional dependencies.`, [
+        ...(isAnchor ? ['@codama/nodes-from-anchor'] : []),
+        ...(result.scripts.includes('js') ? ['@codama/renderers-js'] : []),
+        ...(result.scripts.includes('rust') ? ['@codama/renderers-rust'] : []),
+    ]);
+
+    // Write configuration file.
     const content = getContentFromPromptResult(result, configFileType);
     await writeFile(output, content);
-    logSuccess(`Configuration file created at "${output}".`);
+    console.log();
+    logSuccess(pico.bold('Configuration file created.'), [`${pico.bold('Path')}: ${output}`]);
 }
 
 function getOutputPath(explicitOutput: string | undefined, options: Pick<InitOptions, 'gill' | 'js'>): string {
@@ -74,7 +87,7 @@ async function getPromptResult(
         (script: string, type: PromptType = 'text') =>
         (_: unknown, values: { scripts: string[] }) =>
             values.scripts.includes(script) ? type : null;
-    const result: PromptResult = await prompts(
+    return await prompts(
         [
             {
                 initial: defaults.idlPath,
@@ -121,15 +134,6 @@ async function getPromptResult(
         ],
         PROMPT_OPTIONS,
     );
-
-    const isAnchor = await isAnchorIdl(result.idlPath);
-    await installMissingDependencies(`Your configuration requires additional dependencies.`, [
-        ...(isAnchor ? ['@codama/nodes-from-anchor'] : []),
-        ...(result.scripts.includes('js') ? ['@codama/renderers-js'] : []),
-        ...(result.scripts.includes('rust') ? ['@codama/renderers-rust'] : []),
-    ]);
-
-    return result;
 }
 
 function getDefaultPromptResult(): PromptResult {

packages/cli/src/commands/run.ts

@@ -1,16 +1,17 @@
 import type { RootNode } from '@codama/nodes';
 import { visit, type Visitor } from '@codama/visitors-core';
 import { Command } from 'commander';
+import pico from 'picocolors';
 
 import { ScriptName } from '../config';
 import { getParsedConfigFromCommand, ParsedConfig } from '../parsedConfig';
-import { getRootNodeVisitors, logInfo, logSuccess, logWarning } from '../utils';
+import { CliError, getRootNodeVisitors, logInfo, logSuccess, logWarning } from '../utils';
 
 export function setRunCommand(program: Command): void {
     program
         .command('run')
         .argument('[scripts...]', 'The scripts to execute')
-        .option('-a, --all', 'Run all scripts in the config file')
+        .option('-a, --all', 'Run all scripts in the configuration file')
         .action(doRun);
 }
 
@@ -39,17 +40,20 @@ async function getPlans(
 ): Promise<RunPlan[]> {
     const plans: RunPlan[] = [];
     if (scripts.length === 0 && parsedConfig.before.length === 0) {
-        throw new Error('There are no scripts or before visitors to run.');
+        throw new CliError('There are no scripts or before visitors to run.');
     }
 
     const missingScripts = scripts.filter(script => !parsedConfig.scripts[script]);
     if (missingScripts.length > 0) {
         const scriptPluralized = missingScripts.length === 1 ? 'Script' : 'Scripts';
-        const missingScriptsIdentifier = `${scriptPluralized} "${missingScripts.join(', ')}"`;
         const message = parsedConfig.configPath
-            ? `${missingScriptsIdentifier} not found in config file "${parsedConfig.configPath}"`
-            : `${missingScriptsIdentifier} not found because no config file was found`;
-        throw new Error(message);
+            ? `${scriptPluralized} not found in configuration file.`
+            : `${scriptPluralized} not found because no configuration file was found.`;
+        const items = [
+            `${pico.bold(scriptPluralized)}: ${missingScripts.join(', ')}`,
+            ...(parsedConfig.configPath ? [`${pico.bold('Path')}: ${parsedConfig.configPath}`] : []),
+        ];
+        throw new CliError(message, items);
     }
 
     if (parsedConfig.before.length > 0) {

packages/cli/src/config.ts

@@ -1,7 +1,9 @@
 import path from 'node:path';
 
+import pico from 'picocolors';
+
 import { ProgramOptions } from './programOptions';
-import { canRead, importModuleItem, logWarning } from './utils';
+import { canRead, CliError, importModuleItem, logWarning } from './utils';
 
 export type Config = Readonly<{
     idl?: string;
@@ -24,13 +26,13 @@ export async function getConfig(options: Pick<ProgramOptions, 'config'>): Promis
     const configPath = options.config != null ? path.resolve(options.config) : await getDefaultConfigPath();
 
     if (!configPath) {
-        logWarning('No config file found. Using empty configs. Make sure you provide the `--idl` option.');
+        logWarning('No configuration file found. Using empty configs. Make sure you provide the `--idl` option.');
         return [{}, configPath];
     }
 
-    const configFile = await importModuleItem({ identifier: 'config file', from: configPath });
+    const configFile = await importModuleItem({ identifier: 'configuration file', from: configPath });
     if (!configFile || typeof configFile !== 'object') {
-        throw new Error(`Invalid config file at "${configPath}"`);
+        throw new CliError(`Invalid configuration file.`, [`${pico.bold('Path')}: ${configPath}`]);
     }
 
     return [configFile, configPath];

packages/cli/src/parsedConfig.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import { Config, getConfig, ScriptName, ScriptsConfig, VisitorConfig, VisitorPath } from './config';
 import { ProgramOptions } from './programOptions';
 import {
+    CliError,
     getRootNodeFromIdl,
     importModuleItem,
     isLocalModulePath,
@@ -63,7 +64,7 @@ function parseIdlPath(
     if (config.idl) {
         return resolveConfigPath(config.idl, configPath);
     }
-    throw new Error('No IDL identified. Please provide the `--idl` option or set it in the config file.');
+    throw new CliError('No IDL identified. Please provide the `--idl` option or set it in the configuration file.');
 }
 
 function parseScripts(scripts: ScriptsConfig, configPath: string | null): ParsedScriptsConfig {

packages/cli/src/utils/errors.ts

@@ -0,0 +1,10 @@
+export class CliError extends Error {
+    constructor(
+        message: string,
+        public items: string[] = [],
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+        this.name = 'CliError';
+    }
+}

packages/cli/src/utils/import.ts

@@ -1,5 +1,8 @@
 import { createRequire } from 'node:module';
 
+import pico from 'picocolors';
+
+import { CliError } from './errors';
 import { canRead, isLocalModulePath, resolveRelativePath } from './fs';
 
 type ImportModuleItemOptions = {
@@ -12,8 +15,8 @@ export async function importModuleItem<T = unknown>(options: ImportModuleItemOpt
     const module = await importModule(options);
     const moduleItem = pickModuleItem(module, options.item) as T | undefined;
     if (moduleItem === undefined) {
-        const moduleInfo = getModuleInfo(options);
-        throw new Error(`Failed to ${moduleInfo}.`);
+        const items = getErrorItems(options);
+        throw new CliError(`Failed to load ${options.identifier ?? 'module'}.`, items);
     }
     return moduleItem;
 }
@@ -43,9 +46,10 @@ async function importModule<T extends object>(options: ImportModuleItemOptions):
 }
 
 async function importLocalModule<T extends object>(options: ImportModuleItemOptions): Promise<T> {
-    const { identifier, from } = options;
+    const { from, identifier } = options;
     if (!(await canRead(from))) {
-        throw new Error(`Cannot access ${identifier ?? 'module'} at "${from}"`);
+        const items = getErrorItems(options);
+        throw new CliError(`Cannot access ${identifier ?? 'module'}.`, items);
     }
 
     const dotIndex = from.lastIndexOf('.');
@@ -71,20 +75,23 @@ async function handleImportPromise<T extends object>(
 ): Promise<T> {
     try {
         return (await importPromise) as T;
-    } catch (error) {
-        const moduleInfo = getModuleInfo(options);
-        let causeMessage =
-            !!error && typeof error === 'object' && 'message' in error && typeof error.message === 'string'
-                ? (error as { message: string }).message
-                : undefined;
-        causeMessage = causeMessage ? `\n(caused by: ${causeMessage})` : '';
-        throw new Error(`Failed to ${moduleInfo}.${causeMessage}`, { cause: error });
+    } catch (cause) {
+        const items = getErrorItems(options, cause);
+        throw new CliError(`Failed to load ${options.identifier ?? 'module'}.`, items, { cause });
     }
 }
 
-function getModuleInfo(options: ImportModuleItemOptions): string {
-    const { identifier, from, item } = options;
-    const importStatement = item ? `import { ${item} } from '${from}'` : `import default from '${from}'`;
-    if (!identifier) return importStatement;
-    return `import ${identifier} [${importStatement}]`;
+function getErrorItems(options: ImportModuleItemOptions, cause?: unknown): string[] {
+    const { from, item } = options;
+    const items = [`${pico.bold('Module')}: ${from}`];
+    if (item) {
+        items.push(`${pico.bold('Item')}: ${item}`);
+    }
+
+    const hasCause = !!cause && typeof cause === 'object' && 'message' in cause && typeof cause.message === 'string';
+    if (hasCause) {
+        items.push(`${pico.bold('Caused by')}: ${(cause as { message: string }).message}`);
+    }
+
+    return items;
 }

packages/cli/src/utils/index.ts

@@ -1,4 +1,5 @@
 export * from './childCommands';
+export * from './errors';
 export * from './fs';
 export * from './import';
 export * from './logs';

packages/cli/src/utils/logs.ts

@@ -1,41 +1,46 @@
 import pico from 'picocolors';
 
-export function logSuccess(message: string, items?: string[]): void {
-    console.log(pico.green('✔'), message);
+type LogLevel = 'debug' | 'error' | 'info' | 'success' | 'warning';
+
+type LogOptions = {
+    level: LogLevel;
+    message: string;
+    items?: string[];
+};
+
+function getLogLevelInfo(logLevel: LogLevel) {
+    const identity = (text: string) => text;
+    const infos: Record<LogLevel, [string, (text: string) => string, (text: string) => string]> = {
+        success: ['✔', pico.green, pico.green],
+        info: ['→', pico.blueBright, identity],
+        warning: ['▲', pico.yellow, pico.yellow],
+        error: ['✖', pico.red, pico.red],
+        debug: ['✱', pico.magenta, pico.magenta],
+    };
+
+    return {
+        icon: infos[logLevel][0],
+        color: infos[logLevel][1],
+        messageColor: infos[logLevel][2],
+    };
+}
+
+const logWrapper = (level: LogLevel) => (message: string, items?: string[]) => log({ level, message, items });
+export const logSuccess = logWrapper('success');
+export const logError = logWrapper('error');
+export const logInfo = logWrapper('info');
+export const logWarning = logWrapper('warning');
+export const logDebug = logWrapper('debug');
+
+function log({ level, message, items }: LogOptions): void {
+    const { icon, color, messageColor } = getLogLevelInfo(level);
+    console.log(color(icon), messageColor(message));
     if (items) {
-        logItems(items, pico.green);
+        logItems(items, color);
     }
 }
 
-export function logInfo(message: string, items?: string[]): void {
-    console.log(pico.blueBright('→'), message);
-    if (items) {
-        logItems(items, pico.blueBright);
-    }
-}
-
-export function logWarning(message: string, items?: string[]): void {
-    console.log(pico.yellow('▲'), message);
-    if (items) {
-        logItems(items, pico.yellow);
-    }
-}
-
-export function logError(message: string, items?: string[]): void {
-    console.log(pico.red('✖'), message);
-    if (items) {
-        logItems(items, pico.red);
-    }
-}
-
-export function logDebug(message: string, items?: string[]): void {
-    console.log(pico.magenta('✱'), message);
-    if (items) {
-        logItems(items, pico.magenta);
-    }
-}
-
-export function logItems(items: string[], color?: (text: string) => string): void {
+function logItems(items: string[], color?: (text: string) => string): void {
     const colorFn = color ?? (text => text);
     items.forEach((item, index) => {
         const prefix = index === items.length - 1 ? '└─' : '├─';