yargs-file-commands 0.0.19 → 1.0.1

package/src/lib/fileCommands.ts

@@ -1,149 +0,0 @@
-import path from 'path';
-
-import {
-  buildSegmentTree,
-  createCommand,
-  logCommandTree
-} from './buildSegmentTree.js';
-import type { Command } from './Command.js';
-import { importCommandFromFile } from './importCommand.js';
-import { scanDirectory, type ScanDirectoryOptions } from './scanDirectory.js';
-import { segmentPath } from './segmentPath.js';
-
-/**
- * Configuration options for file-based command generation
- * @interface FileCommandsOptions
- */
-export type FileCommandsOptions = ScanDirectoryOptions & {
-  /** Array of directory paths to scan for command files */
-  commandDirs: string[];
-};
-
-/**
- * Default configuration options for file-based commands
- * @constant
- * @type {Partial<FileCommandsOptions>}
- */
-export const DefaultFileCommandsOptions: Required<FileCommandsOptions> = {
-  /** Default directories to scan for command files */
-  commandDirs: [],
-
-  /** Default file extensions to process */
-  extensions: ['.js', '.ts'],
-
-  /** Default patterns to ignore when scanning directories */
-  ignorePatterns: [
-    /^[.|_].*/, // Hidden files and underscore files
-    /\.(?:test|spec)\.[jt]s$/, // Test files
-    /__(?:test|spec)__/, // Test directories
-    /\.d\.ts$/ // TypeScript declaration files
-  ],
-
-  /** Default logging level */
-  logLevel: 'info',
-
-  /** Default log prefix */
-  logPrefix: '  '
-};
-
-/**
- * Generates a command tree structure from files in specified directories
- * @async
- * @param {FileCommandsOptions} options - Configuration options for command generation
- * @returns {Promise<Command[]>} Array of root-level commands with their nested subcommands
- *
- * @description
- * This function scans the specified directories for command files and builds a hierarchical
- * command structure based on the file system layout. It processes files in parallel for better
- * performance and supports nested commands through directory structure.
- *
- * The function will:
- * 1. Scan all specified command directories
- * 2. Process found files to extract command information
- * 3. Build a tree structure based on file paths
- * 4. Convert the tree into a command hierarchy
- */
-export const fileCommands = async (options: FileCommandsOptions) => {
-  const fullOptions: Required<FileCommandsOptions> = {
-    ...DefaultFileCommandsOptions,
-    ...options
-  };
-
-  // validate extensions have dots in them
-  if (fullOptions.extensions.some((ext) => !ext.startsWith('.'))) {
-    throw new Error(
-      `Invalid extensions provided, must start with a dot: ${fullOptions.extensions.join(
-        ', '
-      )}`
-    );
-  }
-  // check for empty list of directories to scan
-  if (fullOptions.commandDirs.length === 0) {
-    throw new Error('No command directories provided');
-  }
-
-  // throw if some command directories are not absolute, first filter to find non-absolute an then throw, listing those that are not absolute
-  const nonAbsoluteDirs = fullOptions.commandDirs.filter(
-    (dir) => !path.isAbsolute(dir)
-  );
-  if (nonAbsoluteDirs.length > 0) {
-    throw new Error(
-      `Command directories must be absolute paths: ${nonAbsoluteDirs.join(
-        ', '
-      )}`
-    );
-  }
-
-  const commands: Command[] = [];
-
-  for (const commandDir of fullOptions.commandDirs) {
-    const fullPath = path.resolve(commandDir);
-    if (fullOptions.logLevel === 'debug') {
-      console.debug(`Scanning directory for commands: ${fullPath}`);
-    }
-
-    const filePaths = await scanDirectory(commandDir, commandDir, fullOptions);
-
-    if (fullOptions.logLevel === 'debug') {
-      console.debug(`Importing found commands:`);
-    }
-    for (const filePath of filePaths) {
-      const localPath = path.relative(commandDir, filePath);
-      const segments = segmentPath(filePath, commandDir);
-      segments.pop(); // remove extension.
-
-      if (fullOptions.logLevel === 'debug') {
-        console.debug(`  ${localPath} - importing command module`);
-      }
-      commands.push({
-        fullPath: filePath,
-        segments,
-        commandModule: await importCommandFromFile(
-          filePath,
-          segments[segments.length - 1]!,
-          fullOptions
-        )
-      });
-    }
-  }
-
-  // check if no commands were found
-  if (commands.length === 0) {
-    throw new Error(
-      `No commands found in specified directories: ${fullOptions.commandDirs.join(
-        ', '
-      )}`
-    );
-  }
-
-  const commandRootNodes = buildSegmentTree(commands);
-
-  if (fullOptions.logLevel === 'debug') {
-    console.debug('Command tree structure:');
-    logCommandTree(commandRootNodes, 1);
-  }
-
-  const rootCommands = commandRootNodes.map((node) => createCommand(node));
-
-  return rootCommands;
-};

package/src/lib/fixtures/commands/$default.ts

@@ -1,5 +0,0 @@
-export const describe = 'Default command';
-
-export const handler = async () => {
-  // Default command implementation
-};

package/src/lib/fixtures/commands/create.ts

@@ -1,6 +0,0 @@
-export const command = 'create [name]';
-export const describe = 'Create something with a name';
-
-export const handler = async () => {
-  // Create command implementation
-};

package/src/lib/fixtures/commands/db/health.ts

@@ -1,9 +0,0 @@
-export const describe = 'Database health check';
-
-export const builder = (yargs: any) => {
-  return yargs;
-};
-
-export const handler = async () => {
-  console.log('Health check handler called');
-};

package/src/lib/fixtures/commands/db/migration/command.ts

@@ -1,12 +0,0 @@
-export const describe = 'Database migration command';
-
-export const builder = (yargs: any) => {
-  return yargs.option('force', {
-    type: 'boolean',
-    describe: 'Force migration'
-  });
-};
-
-export const handler = async (argv: any) => {
-  console.log('Migration handler called');
-};

package/src/lib/importCommand.test.ts

@@ -1,65 +0,0 @@
-import path from 'path';
-import { test } from 'node:test';
-import assert from 'node:assert';
-
-import { importCommandFromFile } from './importCommand.js';
-
-// get __dirname in ESM style
-const __dirname = path.dirname(new URL(import.meta.url).pathname);
-
-test('should import command module correctly', async () => {
-  const filePath = path.join(
-    __dirname,
-    'fixtures',
-    'commands',
-    'db',
-    'health.js'
-  );
-  const command = await importCommandFromFile(filePath, 'health', {
-    logLevel: 'info'
-  });
-
-  assert.equal(command.describe, 'Database health check');
-});
-
-test('should handle non-existent files', async () => {
-  const filePath = path.join(
-    __dirname,
-    'fixtures',
-    'commands',
-    'non-existent.js'
-  );
-  try {
-    await importCommandFromFile(filePath, 'non-existent', {
-      logLevel: 'info'
-    });
-    assert.fail('Should have thrown an error');
-  } catch (error) {
-    assert.ok(error instanceof Error);
-    assert.ok(
-      (error as Error).message.includes(
-        'Can not import command from non-existence'
-      )
-    );
-  }
-});
-
-test('should handle explicit command names', async () => {
-  const filePath = path.join(__dirname, 'fixtures', 'commands', 'create.js');
-  const command = await importCommandFromFile(filePath, 'create', {
-    logLevel: 'info'
-  });
-
-  assert.equal(command.command, 'create [name]');
-  assert.equal(command.describe, 'Create something with a name');
-});
-
-test('should handle default commands', async () => {
-  const filePath = path.join(__dirname, 'fixtures', 'commands', '$default.js');
-  const command = await importCommandFromFile(filePath, '$default', {
-    logLevel: 'info'
-  });
-
-  assert.equal(command.command, '$0');
-  assert.equal(command.describe, 'Default command');
-});

package/src/lib/importCommand.ts

@@ -1,148 +0,0 @@
-import fs from 'fs';
-import {
-  type ArgumentsCamelCase,
-  type CommandBuilder,
-  type CommandModule
-} from 'yargs';
-
-/**
- * Represents command alias configuration
- * @type {readonly string[] | string | undefined}
- */
-export type CommandAlias = readonly string[] | string | undefined;
-
-/**
- * Represents command name configuration
- * @type {readonly string[] | string | undefined}
- */
-export type CommandName = readonly string[] | string | undefined;
-
-/**
- * Represents command deprecation configuration
- * @type {boolean | string | undefined}
- */
-export type CommandDeprecated = boolean | string | undefined;
-
-/**
- * Represents command description configuration
- * @type {string | false | undefined}
- */
-export type CommandDescribe = string | false | undefined;
-
-/**
- * Command handler function type
- * @type {Function}
- */
-export type CommandHandler = (
-  args: ArgumentsCamelCase<any>
-) => void | Promise<any>;
-
-/**
- * Parameters for file commands configuration
- * @interface FileCommandsParams
- */
-export interface FileCommandsParams {
-  /** Root directory for command files */
-  rootDir: string;
-}
-
-/**
- * Structure of a command module import
- * @interface CommandImportModule
- */
-export interface CommandImportModule {
-  /** Command aliases */
-  alias?: CommandAlias;
-  /** Command builder function */
-  builder?: CommandBuilder;
-  /** Command name */
-  command?: CommandName;
-  /** Deprecation status */
-  deprecated?: CommandDeprecated;
-  /** Command description */
-  describe?: CommandDescribe;
-  /** Command handler function */
-  handler?: CommandHandler;
-}
-
-export interface ImportCommandOptions {
-  logLevel?: 'info' | 'debug';
-}
-
-/**
- * Imports a command module from a file
- * @async
- * @param {string} filePath - Path to the command file
- * @param {string} name - Command name
- * @returns {Promise<CommandModule>} Imported command module
- *
- * @description
- * Dynamically imports a command file and constructs a Yargs command module.
- * If no handler is provided, creates a null implementation.
- */
-export const importCommandFromFile = async (
-  filePath: string,
-  name: string,
-  options: ImportCommandOptions
-) => {
-  // ensure file exists using fs node library
-  if (fs.existsSync(filePath) === false) {
-    throw new Error(
-      `Can not import command from non-existence file path: ${filePath}`
-    );
-  }
-
-  const url = 'file://' + filePath;
-
-  const handlerModule = (await import(url)) as CommandImportModule;
-  const { logLevel = 'info' } = options;
-
-  // Check if this is the default command
-  const isDefault = name === '$default';
-
-  const command = {
-    command: handlerModule.command ?? (isDefault ? '$0' : name),
-    describe: handlerModule.describe,
-    alias: handlerModule.alias,
-    builder: handlerModule.builder,
-    deprecated: handlerModule.deprecated,
-    handler:
-      handlerModule.handler ??
-      (async (args: ArgumentsCamelCase<any>) => {
-        // null implementation
-      })
-  } as CommandModule;
-
-  const supportedNames = [
-    'command',
-    'describe',
-    'alias',
-    'builder',
-    'deprecated',
-    'handler'
-  ];
-  const module = handlerModule as Record<string, any>;
-  const unsupportedExports = Object.keys(module).filter(
-    (key) => !supportedNames.includes(key)
-  );
-  if (unsupportedExports.length > 0) {
-    throw new Error(
-      `Command module ${name} in ${filePath} has some unsupported exports, probably a misspelling: ${unsupportedExports.join(
-        ', '
-      )}`
-    );
-  }
-
-  if (logLevel === 'debug') {
-    console.debug(
-      'Importing command from',
-      filePath,
-      'as',
-      name,
-      'with description',
-      command.describe
-    );
-  }
-
-  return command;
-};

package/src/lib/scanDirectory.test.ts

@@ -1,75 +0,0 @@
-import assert from 'node:assert/strict';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-import { fileURLToPath } from 'node:url';
-
-import { scanDirectory } from '../lib/scanDirectory.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-describe('scanDirectory', async () => {
-  await it('should find all command files in directory', async () => {
-    const commandsDir = path.join(__dirname, 'fixtures', 'commands');
-    console.log('Scan Directory: ', commandsDir);
-    const files = await scanDirectory(commandsDir, commandsDir, {
-      extensions: ['.js'],
-      logLevel: 'debug'
-    });
-
-    assert.equal(
-      files.length,
-      4,
-      `Should find two command files, instead found: ${files.join(', ')}`
-    );
-    assert(
-      files.some((f) => f.includes('health.js')),
-      `Should find health.js, instead found: ${files.join(', ')}`
-    );
-    assert(
-      files.some((f) => f.includes('command.js')),
-      `Should find command.js, instead found: ${files.join(', ')}`
-    );
-  });
-
-  await it('should respect ignore patterns', async () => {
-    const commandsDir = path.join(__dirname, 'fixtures', 'commands');
-    console.log('Scan Directory: ', commandsDir);
-    const files = await scanDirectory(commandsDir, commandsDir, {
-      extensions: ['.js'],
-      ignorePatterns: [/health/, /.d.ts/],
-      logLevel: 'debug'
-    });
-
-    assert.equal(
-      files.length,
-      3,
-      `Should find one command file, instead found: ${files.join(', ')}`
-    );
-    assert(
-      files.some((f) => f.includes('command.js')),
-      `Should find command.js, instead found: ${files.join(', ')}`
-    );
-    assert(
-      !files.some((f) => f.includes('health.js')),
-      `Should not find health.js, instead found: ${files.join(', ')}`
-    );
-  });
-
-  await it('should handle non-existent directories', async () => {
-    const nonExistentDir = path.join(__dirname, 'fixtures', 'non-existent');
-    try {
-      console.log('Scan Directory: ', nonExistentDir);
-      await scanDirectory(nonExistentDir, nonExistentDir, {
-        extensions: ['.js'],
-        logLevel: 'debug'
-      });
-      assert.fail('Should have thrown an error');
-    } catch (error) {
-      assert(error instanceof Error);
-      assert(
-        error.message.includes('ENOENT'),
-        'Error should indicate directory not found'
-      );
-    }
-  });
-});

package/src/lib/scanDirectory.ts

@@ -1,109 +0,0 @@
-import { readdir, stat } from 'fs/promises';
-import path, { join } from 'path';
-
-/**
- * Options for directory scanning
- * @interface ScanDirectoryOptions
- */
-export interface ScanDirectoryOptions {
-  /** File extensions to consider when scanning for command files */
-  extensions?: string[];
-  /** Regular expressions for patterns to ignore when scanning directories */
-  ignorePatterns?: RegExp[];
-  /** Logging verbosity level */
-  logLevel?: 'info' | 'debug';
-  /** Prefix for log messages */
-  logPrefix?: string;
-}
-
-/**
- * Recursively scans a directory for command files
- * @async
- * @param {string} dirPath - The directory path to scan
- * @param {ScanDirectoryOptions} options - Scanning configuration options
- * @returns {Promise<string[]>} Array of full paths to command files
- *
- * @description
- * Performs a recursive directory scan, filtering files based on:
- * - Ignore patterns (skips matching files/directories)
- * - File extensions (only includes matching files)
- * The scan is performed in parallel for better performance.
- */
-export const scanDirectory = async (
-  dirPath: string,
-  commandDir: string,
-  options: ScanDirectoryOptions = {}
-): Promise<string[]> => {
-  const {
-    ignorePatterns = [],
-    extensions = ['.js', '.ts'],
-    logLevel = 'info',
-    logPrefix = ''
-  } = options;
-
-  try {
-    const entries = await readdir(dirPath);
-
-    const commandPaths: string[] = [];
-    for (const entry of entries) {
-      const fullPath = join(dirPath, entry);
-
-      const localPath = fullPath.replace(commandDir, '');
-
-      // apply ignore pattern and early return if matched
-      const shouldIgnore = ignorePatterns.some((pattern) =>
-        pattern.test(localPath)
-      );
-      if (shouldIgnore) {
-        if (logLevel === 'debug') {
-          console.debug(
-            `${logPrefix}${localPath} - ignoring because it matches ignorePattern: ${ignorePatterns
-              .filter((pattern) => pattern.test(localPath))
-              .join(', ')}`
-          );
-        }
-        continue;
-      }
-
-      const stats = await stat(fullPath);
-
-      if (stats.isDirectory()) {
-        if (logLevel === 'debug') {
-          console.debug(
-            `${logPrefix}${localPath} - directory, scanning for commands:`
-          );
-        }
-        commandPaths.push(
-          ...(await scanDirectory(fullPath, commandDir, {
-            ...options,
-            logPrefix: `${logPrefix}  `
-          }))
-        );
-        continue;
-      }
-      const extension = path.extname(fullPath);
-      if (!extensions.includes(extension)) {
-        if (logLevel === 'debug') {
-          console.debug(
-            `${logPrefix}${localPath} - ignoring as its extension, ${extension}, doesn't match required extension: ${extensions.join(
-              ', '
-            )}`
-          );
-        }
-        continue;
-      }
-
-      if (logLevel === 'debug') {
-        console.debug(`${logPrefix}${localPath} - possible command file`);
-      }
-
-      commandPaths.push(fullPath);
-    }
-
-    return commandPaths;
-  } catch (error) {
-    throw new Error(
-      `${logPrefix}Failed to scan directory ${dirPath}: ${error}`
-    );
-  }
-};

package/src/lib/segmentPath.test.ts

@@ -1,71 +0,0 @@
-import { describe, it } from 'node:test';
-
-import assert from 'assert';
-
-import { segmentPath } from './segmentPath.js';
-
-describe('segmentPath', () => {
-  it('should segment a path correctly', () => {
-    const fullPath =
-      '/Users/username/Coding/Personal/yargs-file-commands/packages/yargs-file-commands/src/lib/segmentPath.ts';
-    const baseDir = '/Users/username/Coding/Personal/yargs-file-commands/';
-    const expected = [
-      'packages',
-      'yargs-file-commands',
-      'src',
-      'lib',
-      'segmentPath',
-      'ts'
-    ];
-    const result = segmentPath(fullPath, baseDir);
-    assert.deepStrictEqual(result, expected);
-  });
-
-  it('should handle paths with periods correctly', () => {
-    const fullPath =
-      '/Users/username/Coding/Personal/yargs-file-commands/packages/yargs-file-commands/src/lib/segmentPath.test.ts';
-    const baseDir = '/Users/username/Coding/Personal/yargs-file-commands/';
-    const expected = [
-      'packages',
-      'yargs-file-commands',
-      'src',
-      'lib',
-      'segmentPath',
-      'test',
-      'ts'
-    ];
-    const result = segmentPath(fullPath, baseDir);
-    assert.deepStrictEqual(result, expected);
-  });
-
-  it('should filter out "command" segments', () => {
-    const fullPath =
-      '/Users/username/Coding/Personal/yargs-file-commands/packages/yargs-file-commands/src/lib/commandPath.ts';
-    const baseDir = '/Users/username/Coding/Personal/yargs-file-commands/';
-    const expected = [
-      'packages',
-      'yargs-file-commands',
-      'src',
-      'lib',
-      'commandPath',
-      'ts'
-    ];
-    const result = segmentPath(fullPath, baseDir);
-    assert.deepStrictEqual(result, expected);
-  });
-
-  it('should handle empty segments correctly', () => {
-    const fullPath =
-      '/Users/username/Coding/Personal/yargs-file-commands/packages/yargs-file-commands/src/lib/.hiddenFile';
-    const baseDir = '/Users/username/Coding/Personal/yargs-file-commands/';
-    const expected = [
-      'packages',
-      'yargs-file-commands',
-      'src',
-      'lib',
-      'hiddenFile'
-    ];
-    const result = segmentPath(fullPath, baseDir);
-    assert.deepStrictEqual(result, expected);
-  });
-});

package/src/lib/segmentPath.ts

@@ -1,38 +0,0 @@
-/**
- * Converts a file path into an array of command segments
- * @param {string} fullPath - The complete file system path to the command file
- * @param {string} baseDir - The base directory to make the path relative to
- * @returns {string[]} Array of segments representing the command hierarchy
- *
- * @description
- * This function processes a file path into command segments by:
- * 1. Making the path relative to the base directory
- * 2. Splitting on directory separators
- * 3. Removing file extensions
- * 4. Splitting on dots for nested commands
- * 5. Filtering out empty segments and 'command' keyword
- *
- * @example
- * segmentPath('/base/dir/hello/world.command.ts', '/base/dir')
- * // Returns: ['hello', 'world']
- */
-export const segmentPath = (fullPath: string, baseDir: string): string[] => {
-  // Remove base directory and normalize slashes
-  const relativePath = fullPath.replace(baseDir, '').replace(/^[/\\\\]+/, '');
-
-  // Split into path segments and filename
-  const allSegments = relativePath.split(/[/\\\\]/);
-
-  // Process all segments including filename (without extension)
-  const processedSegments = allSegments
-    // Remove extension from the last segment (filename)
-    .map((segment, index, array) =>
-      index === array.length - 1 ? segment.replace(/\\.[^/.]+$/, '') : segment
-    )
-    // Split segments containing periods
-    .flatMap((segment) => segment.split('.'))
-    // Filter out empty segments and 'command'
-    .filter((segment) => segment !== '' && segment !== 'command');
-
-  return processedSegments;
-};