yargs-file-commands 0.0.10 → 0.0.12

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# yargs-file-commands
+
+## 0.0.12
+
+### Patch Changes
+
+- More explicit exceptions when bad parameters are passed in
+- More robust parameter checking and logging
+- Improved debugging logging
+- More robust debug messages
+
+## 0.0.11
+
+### Patch Changes
+
+- More explicit exceptions when bad parameters are passed in
+- Improved debugging logging
+- More robust debug messages
+
+## 0.0.10
+
+### Patch Changes
+
+- Improved debugging logging
+- More robust debug messages
+
+## 0.0.9
+
+### Patch Changes
+
+- Improved debugging logging
+- More robust debug messages

package/dist/lib/fileCommands.js

@@ -60,9 +60,14 @@ export const fileCommands = async (options) => {
         const fullPath = path.resolve(commandDir);
         console.debug(`Scanning directory for commands: ${fullPath}`);
         const filePaths = await scanDirectory(commandDir, commandDir, fullOptions);
+        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,

package/dist/lib/importCommand.js

@@ -1,3 +1,4 @@
+import fs from 'fs';
 import {} from 'yargs';
 /**
  * Imports a command module from a file
@@ -11,6 +12,10 @@ import {} from 'yargs';
  * If no handler is provided, creates a null implementation.
  */
 export const importCommandFromFile = async (filePath, name, options) => {
+    // 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 handlerModule = (await import(filePath));
     const { logLevel = 'info' } = options;
     const command = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yargs-file-commands",
   "description": "A yargs helper function that lets you define your commands structure via directory and file naming conventions.",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,9 +29,11 @@
   },
   "files": [
     "dist",
+    "src",
     "package.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
     "yargs": "^17"
@@ -53,6 +55,7 @@
     "typecheck": "tsc --noEmit",
     "test": "tsc && node --test dist/**/*.test.js --test-concurrency=1",
     "lint": "eslint --fix \"src/**/*.{ts,tsx}\"",
-    "format": "prettier \"src/**/*.{js,jsx,css,md,html,ts,tsx,json,yaml}\" --check"
+    "format": "prettier \"src/**/*.{js,jsx,css,md,html,ts,tsx,json,yaml}\" --check",
+    "prePublishOnly": "pnpm build && pnpm test"
   }
 }

package/src/index.ts

@@ -0,0 +1 @@
+export * from './lib/fileCommands.js';

package/src/lib/Command.ts

@@ -0,0 +1,14 @@
+import type { CommandModule } from 'yargs';
+
+/**
+ * Represents a command structure with its file path and module information
+ * @interface Command
+ */
+export interface Command {
+  /** Full file system path to the command file */
+  fullPath: string;
+  /** Array of path segments representing the command hierarchy */
+  segments: string[];
+  /** The Yargs command module implementation */
+  commandModule: CommandModule;
+}

package/src/lib/buildSegmentTree.test.ts

@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { buildSegmentTree } from './buildSegmentTree.js';
+import type { Command } from './Command.js';
+
+describe('buildSegmentTree', async () => {
+  it('should build correct tree structure', () => {
+    const commands: Command[] = [
+      {
+        fullPath: '/commands/db/migration/command.js',
+        segments: ['db', 'migration'],
+        commandModule: {
+          command: 'migration',
+          describe: 'Migration command',
+          handler: async () => {
+            // Test handler
+          }
+        }
+      },
+      {
+        fullPath: '/commands/db/health.js',
+        segments: ['db', 'health'],
+        commandModule: {
+          command: 'health',
+          describe: 'Health command',
+          handler: async () => {
+            // Test handler
+          }
+        }
+      }
+    ];
+
+    const tree = buildSegmentTree(commands);
+
+    assert.equal(tree.length, 1, 'Should have one root node');
+    const rootNode = tree[0];
+    assert(rootNode, 'Root node should exist');
+    assert.equal(rootNode.segmentName, 'db', 'Root node should be "db"');
+    assert.equal(
+      rootNode.type,
+      'internal',
+      'Root node should be internal type'
+    );
+
+    if (rootNode.type !== 'internal') {
+      throw new Error('Expected internal node');
+    }
+
+    assert.equal(rootNode.children.length, 2, 'Should have two child nodes');
+
+    const childSegments = rootNode.children
+      .map((child) => child.segmentName)
+      .sort();
+    assert.deepEqual(
+      childSegments,
+      ['health', 'migration'],
+      'Should have "health" and "migration" sub-commands'
+    );
+  });
+
+  it('should handle empty input', () => {
+    const tree = buildSegmentTree([]);
+    assert.equal(tree.length, 0, 'Should return empty array for empty input');
+  });
+
+  it('should handle single command', () => {
+    const commands: Command[] = [
+      {
+        fullPath: '/commands/test.ts',
+        segments: ['test'],
+        commandModule: {
+          command: 'test',
+          describe: 'Test command',
+          handler: async () => {
+            // Test handler
+          }
+        }
+      }
+    ];
+
+    const tree = buildSegmentTree(commands);
+
+    assert.equal(tree.length, 1, 'Should have one node');
+    const node = tree[0];
+    assert(node, 'Node should exist');
+    assert.equal(node.segmentName, 'test', 'Should have correct segment');
+    assert.equal(node.type, 'leaf', 'Should be a leaf node');
+  });
+});

package/src/lib/buildSegmentTree.ts

@@ -0,0 +1,145 @@
+import type { Argv, CommandModule } from 'yargs';
+
+import type { Command } from './Command';
+
+/**
+ * Represents a node in the command tree structure
+ * @type {CommandTreeNode}
+ */
+type CommandTreeNode = {
+  /** Name of the command segment */
+  segmentName: string;
+} & (
+  | {
+      /** Internal node type with children */
+      type: 'internal';
+      /** Child command nodes */
+      children: CommandTreeNode[];
+    }
+  | {
+      /** Leaf node type with command implementation */
+      type: 'leaf';
+      /** The command implementation */
+      command: Command;
+    }
+);
+
+/**
+ * Builds a tree structure from command definitions
+ * @param {Command[]} commands - Array of command definitions
+ * @returns {CommandTreeNode[]} Root nodes of the command tree
+ *
+ * @description
+ * Constructs a hierarchical tree structure from flat command definitions,
+ * preserving the command hierarchy defined by the file system structure.
+ */
+export const buildSegmentTree = (commands: Command[]): CommandTreeNode[] => {
+  const rootTreeNodes: CommandTreeNode[] = [];
+
+  for (const command of commands) {
+    insertIntoTree(rootTreeNodes, command, 0);
+  }
+
+  return rootTreeNodes;
+};
+
+/**
+ * Inserts a command into the tree structure at the specified depth
+ * @param {CommandTreeNode[]} treeNodes - Current level tree nodes
+ * @param {Command} command - Command to insert
+ * @param {number} depth - Current depth in the segment tree
+ * @throws {Error} When there's a conflict between directory and command names
+ */
+function insertIntoTree(
+  treeNodes: CommandTreeNode[],
+  command: Command,
+  depth: number
+): void {
+  // If we've processed all segments, we shouldn't be here
+  if (depth >= command.segments.length) {
+    return;
+  }
+
+  const currentSegmentName = command.segments[depth]!;
+  let currentSegment = treeNodes.find(
+    (s) => s.segmentName === currentSegmentName
+  );
+
+  // If this is the last segment, create a leaf node
+  if (depth === command.segments.length - 1) {
+    if (currentSegment == null) {
+      treeNodes.push({
+        type: 'leaf',
+        segmentName: currentSegmentName,
+        command
+      });
+    } else if (currentSegment.type === 'internal') {
+      throw new Error(
+        `Conflict: ${currentSegmentName} is both a directory and a command`
+      );
+    }
+    return;
+  }
+
+  // Creating or ensuring we have an internal node
+  if (currentSegment == null) {
+    currentSegment = {
+      type: 'internal',
+      segmentName: currentSegmentName,
+      children: []
+    };
+    treeNodes.push(currentSegment);
+  } else if (currentSegment.type === 'leaf') {
+    throw new Error(
+      `Conflict: ${currentSegmentName} is both a directory and a command`
+    );
+  }
+
+  // Recurse into children
+  insertIntoTree(currentSegment.children, command, depth + 1);
+}
+
+/**
+ * Creates a Yargs command module from a tree node
+ * @param {CommandTreeNode} treeNode - The tree node to convert
+ * @returns {CommandModule} Yargs command module
+ *
+ * @description
+ * Recursively converts a tree node into a Yargs command module.
+ * For leaf nodes, returns the actual command implementation.
+ * For internal nodes, creates a parent command that manages subcommands.
+ */
+export const createCommand = (treeNode: CommandTreeNode): CommandModule => {
+  if (treeNode.type === 'leaf') {
+    return treeNode.command.commandModule;
+  }
+
+  const name = treeNode.segmentName;
+  // For internal nodes, create a command that registers all children
+  const command: CommandModule = {
+    command: name,
+    describe: `${name} commands`,
+    builder: (yargs: Argv): Argv => {
+      // Register all child segments as subcommands
+      yargs.command(treeNode.children.map((child) => createCommand(child)));
+      // Demand a subcommand unless we're at the root
+      yargs.demandCommand(1, `You must specify a ${name} subcommand`);
+
+      return yargs;
+    },
+    handler: async () => {
+      // Internal nodes don't need handlers as they'll demand subcommands
+    }
+  };
+
+  return command;
+};
+
+export const logCommandTree = (commands: CommandTreeNode[], level = 0) => {
+  commands.forEach((command) => {
+    console.debug(`${'  '.repeat(level) + command.segmentName}`);
+    if (command.type === 'internal') {
+      logCommandTree(command.children, level + 1);
+    }
+  });
+};

package/src/lib/fileCommands.test.ts

@@ -0,0 +1,57 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import type { CommandModule } from 'yargs';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+import { fileCommands } from '../lib/fileCommands.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+describe('fileCommands', async () => {
+  await it('should load commands from directory structure', async () => {
+    const commandsDir = path.join(__dirname, 'fixtures', 'commands');
+    const commands = await fileCommands({
+      commandDirs: [commandsDir],
+      extensions: ['.js'],
+      logLevel: 'debug'
+    });
+
+    assert.equal(commands.length, 1, 'Should have one root command');
+    const rootCommand = commands[0] as CommandModule;
+    assert(rootCommand, 'Root command should exist');
+    assert.equal(rootCommand.command, 'db', 'Root command should be "db"');
+
+    // Create a new yargs instance
+    const yargsInstance = yargs(hideBin(process.argv));
+
+    if (typeof rootCommand.builder === 'function') {
+      rootCommand.builder(yargsInstance);
+    }
+
+    // Check that the command has subcommands by checking its description
+    const description = rootCommand.describe;
+    assert(
+      typeof description === 'string' && description.includes('db'),
+      'Command should have correct description'
+    );
+  });
+
+  await it('should respect ignore patterns', async () => {
+    const commandsDir = path.join(__dirname, 'fixtures', 'commands');
+    const commands = await fileCommands({
+      commandDirs: [commandsDir],
+      extensions: ['.js'],
+      ignorePatterns: [/health/],
+      logLevel: 'debug'
+    });
+
+    assert.equal(commands.length, 1, 'Should have one root command');
+    const rootCommand = commands[0] as CommandModule;
+    assert(rootCommand, 'Root command should exist');
+    assert.equal(rootCommand.command, 'db', 'Root command should be "db"');
+  });
+});

package/src/lib/fileCommands.ts

@@ -0,0 +1,133 @@
+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');
+  }
+
+  const commands: Command[] = [];
+
+  for (const commandDir of fullOptions.commandDirs) {
+    const fullPath = path.resolve(commandDir);
+    console.debug(`Scanning directory for commands: ${fullPath}`);
+
+    const filePaths = await scanDirectory(commandDir, commandDir, fullOptions);
+
+    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/db/health.ts

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { importCommandFromFile } from '../lib/importCommand.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+describe('importCommandFromFile', async () => {
+  await it('should import command module correctly', async () => {
+    const commandPath = path.join(
+      __dirname,
+      'fixtures',
+      'commands',
+      'db',
+      'health.js'
+    );
+    const command = await importCommandFromFile(commandPath, 'health', {});
+
+    assert(command.describe, 'Should have describe property');
+    assert(
+      typeof command.builder === 'function',
+      'Should have builder function'
+    );
+    assert(
+      typeof command.handler === 'function',
+      'Should have handler function'
+    );
+  });
+
+  await it('should handle non-existent files', async () => {
+    const nonExistentPath = path.join(
+      __dirname,
+      'fixtures',
+      'commands',
+      'non-existent.ts'
+    );
+
+    await assert.rejects(
+      async () => {
+        await importCommandFromFile(nonExistentPath, 'non-existent', {});
+      },
+      Error,
+      'Should throw error for non-existent file'
+    );
+  });
+});

package/src/lib/importCommand.ts

@@ -0,0 +1,122 @@
+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 handlerModule = (await import(filePath)) as CommandImportModule;
+  const { logLevel = 'info' } = options;
+
+  const command = {
+    command: name,
+    describe: handlerModule.describe,
+    alias: handlerModule.alias,
+    builder: handlerModule.builder,
+    deprecated: handlerModule.deprecated,
+    handler:
+      handlerModule.handler ??
+      (async (args: ArgumentsCamelCase<any>) => {
+        // null implementation
+      })
+  } as CommandModule;
+
+  if (logLevel === 'debug') {
+    console.debug(
+      'Importing command from',
+      filePath,
+      'as',
+      name,
+      'with description',
+      command.describe
+    );
+  }
+  return command;
+};

package/src/lib/scanDirectory.test.ts

@@ -0,0 +1,75 @@
+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,
+      2,
+      `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/],
+      logLevel: 'debug'
+    });
+
+    assert.equal(
+      files.length,
+      1,
+      `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

@@ -0,0 +1,109 @@
+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

@@ -0,0 +1,71 @@
+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

@@ -0,0 +1,38 @@
+/**
+ * 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;
+};