yargs-file-commands 1.1.1 → 1.2.0

package/README.md

@@ -216,6 +216,29 @@ The `fileCommands` method takes the following options:
 - The verbosity level for the plugin, either `debug` or `info`
 - Default: `"info"`
 
+**validation**
+
+- Whether to validate that positional arguments registered in the builder function match those declared in the command string
+- When enabled, throws an error if positional arguments are registered via `.positional()` but not declared in the command string (e.g., `command: 'create'` should be `command: 'create <arg1> <arg2>'` if positionals are used)
+- This helps catch a common mistake where positional arguments are defined in the builder but missing from the command string, which causes them to be `undefined` at runtime
+- Default: `true`
+
+**Example:**
+
+```ts
+// ❌ This will fail validation if validation: true
+export const command = defineCommand({
+  command: 'create', // Missing positional arguments!
+  builder: (yargs) => yargs.positional('name', { ... }),
+});
+
+// ✅ This passes validation
+export const command = defineCommand({
+  command: 'create <name>', // Positional arguments declared
+  builder: (yargs) => yargs.positional('name', { ... }),
+});
+```
+
 ## Plugin Development (for Contributors only)
 
 If you want to contribute, just check out [this git project](https://github.com/bhouston/yargs-file-commands) and run the following commands to get going:

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,3 +1,3 @@
-export * from './lib/fileCommands.js';
 export * from './lib/defineCommand.js';
+export * from './lib/fileCommands.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC"}

package/dist/lib/fileCommands.d.ts

@@ -7,6 +7,8 @@ import { type ScanDirectoryOptions } from './scanDirectory.js';
 export type FileCommandsOptions = ScanDirectoryOptions & {
     /** Array of directory paths to scan for command files */
     commandDirs: string[];
+    /** Whether to validate that positional arguments in builder match command string */
+    validation?: boolean;
 };
 /**
  * Default configuration options for file-based commands

package/dist/lib/fileCommands.js

@@ -3,6 +3,7 @@ import { buildSegmentTree, createCommand, logCommandTree } from './buildSegmentT
 import { importCommandFromFile } from './importCommand.js';
 import { scanDirectory } from './scanDirectory.js';
 import { segmentPath } from './segmentPath.js';
+import { validatePositionals } from './validatePositionals.js';
 /**
  * Default configuration options for file-based commands
  * @constant
@@ -26,6 +27,8 @@ export const DefaultFileCommandsOptions = {
     logLevel: 'info',
     /** Default log prefix */
     logPrefix: '  ',
+    /** Default validation setting - enabled by default */
+    validation: true,
 };
 /**
  * Generates a command tree structure from files in specified directories
@@ -94,10 +97,15 @@ export const fileCommands = async (options) => {
         if (lastSegment === undefined) {
             throw new Error(`No segments found for file: ${filePath}`);
         }
+        const commandModule = await importCommandFromFile(filePath, lastSegment, fullOptions);
+        // Validate positional arguments if validation is enabled
+        if (fullOptions.validation) {
+            await validatePositionals(commandModule, filePath);
+        }
         return {
             fullPath: filePath,
             segments,
-            commandModule: await importCommandFromFile(filePath, lastSegment, fullOptions),
+            commandModule,
         };
     })));
     commands.push(...fileResults);

package/dist/lib/fileCommands.js.map

@@ -1 +1 @@
-{"version":3,"file":"fileCommands.js","sourceRoot":"","sources":["../../src/lib/fileCommands.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fileCommands.js","sourceRoot":"","sources":["../../src/lib/fileCommands.ts"],"names":[],"mappings":"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"}

package/dist/lib/validatePositionals.d.ts

@@ -0,0 +1,26 @@
+import type { CommandBuilder, CommandModule } from 'yargs';
+/**
+ * Extracts positional argument names from a command string.
+ * Handles patterns like: "create <name>", "create <name> [optional]", etc.
+ *
+ * @param commandString - The command string (e.g., "create <serviceAccount> <token>")
+ * @returns Array of positional argument names found in the command string
+ */
+export declare function extractPositionalsFromCommandString(commandString: string | readonly string[] | undefined): string[];
+/**
+ * Extracts positional argument names from a builder function by executing it
+ * with a mock yargs instance and tracking what positionals are registered.
+ *
+ * @param builder - The command builder function
+ * @returns Array of positional argument names registered in the builder
+ */
+export declare function extractPositionalsFromBuilder(builder: CommandBuilder | undefined): Promise<string[]>;
+/**
+ * Validates that positional arguments registered in the builder match
+ * those declared in the command string.
+ *
+ * @param commandModule - The command module to validate
+ * @param filePath - Path to the command file (for error messages)
+ * @throws Error if validation fails and positionals don't match
+ */
+export declare function validatePositionals(commandModule: CommandModule, filePath: string): Promise<void>;

package/dist/lib/validatePositionals.js

@@ -0,0 +1,104 @@
+import yargs from 'yargs';
+/**
+ * Extracts positional argument names from a command string.
+ * Handles patterns like: "create <name>", "create <name> [optional]", etc.
+ *
+ * @param commandString - The command string (e.g., "create <serviceAccount> <token>")
+ * @returns Array of positional argument names found in the command string
+ */
+export function extractPositionalsFromCommandString(commandString) {
+    if (!commandString) {
+        return [];
+    }
+    // Handle array of command strings (take the first one)
+    const cmd = Array.isArray(commandString) ? commandString[0] : commandString;
+    if (!cmd || typeof cmd !== 'string') {
+        return [];
+    }
+    // Match patterns like <name> or [name] in the command string
+    // Examples:
+    // - "create <serviceAccount> <token>" -> ["serviceAccount", "token"]
+    // - "create <name> [optional]" -> ["name", "optional"]
+    // - "create" -> []
+    const positionalPattern = /[<[]([^>\]]+)[>\]]/g;
+    const positionals = [];
+    let match = positionalPattern.exec(cmd);
+    while (match !== null) {
+        if (match[1]) {
+            positionals.push(match[1]);
+        }
+        match = positionalPattern.exec(cmd);
+    }
+    return positionals;
+}
+/**
+ * Extracts positional argument names from a builder function by executing it
+ * with a mock yargs instance and tracking what positionals are registered.
+ *
+ * @param builder - The command builder function
+ * @returns Array of positional argument names registered in the builder
+ */
+export async function extractPositionalsFromBuilder(builder) {
+    if (!builder) {
+        return [];
+    }
+    // CommandBuilder can be a function or an object - we only validate function builders
+    if (typeof builder !== 'function') {
+        // Object builders don't use .positional() calls, so no positionals to extract
+        return [];
+    }
+    // Track positional arguments by creating a wrapper around yargs
+    const positionals = [];
+    const mockYargs = yargs([]);
+    // Wrap the positional method to track calls
+    const originalPositional = mockYargs.positional.bind(mockYargs);
+    // biome-ignore lint/suspicious/noExplicitAny: Need to override yargs positional method to track calls
+    mockYargs.positional = (name, config) => {
+        positionals.push(name);
+        return originalPositional(name, config);
+    };
+    // Execute the builder function
+    try {
+        const result = builder(mockYargs);
+        // Handle both sync and async builders
+        await (result instanceof Promise ? result : Promise.resolve(result));
+    }
+    catch {
+        // If builder throws, we can't validate - this is okay, yargs will catch it later
+        // We'll just return what we've collected so far
+    }
+    return positionals;
+}
+/**
+ * Validates that positional arguments registered in the builder match
+ * those declared in the command string.
+ *
+ * @param commandModule - The command module to validate
+ * @param filePath - Path to the command file (for error messages)
+ * @throws Error if validation fails and positionals don't match
+ */
+export async function validatePositionals(commandModule, filePath) {
+    const commandString = commandModule.command;
+    const builder = commandModule.builder;
+    // Extract positionals from command string
+    const commandStringPositionals = extractPositionalsFromCommandString(commandString);
+    // Extract positionals from builder
+    const builderPositionals = await extractPositionalsFromBuilder(builder);
+    // If builder has positionals but command string doesn't, that's an error
+    if (builderPositionals.length > 0 && commandStringPositionals.length === 0) {
+        throw new Error(`Command in ${filePath} has ${builderPositionals.length} positional argument(s) registered in builder ` +
+            `(${builderPositionals.join(', ')}) but none declared in command string "${commandString}". ` +
+            `Positional arguments must be declared in the command string (e.g., "create <arg1> <arg2>").`);
+    }
+    // Check if all builder positionals are in command string
+    const missingInCommandString = builderPositionals.filter((pos) => !commandStringPositionals.includes(pos));
+    if (missingInCommandString.length > 0) {
+        throw new Error(`Command in ${filePath} has positional argument(s) registered in builder ` +
+            `(${missingInCommandString.join(', ')}) that are not declared in command string "${commandString}". ` +
+            `All positional arguments must be declared in the command string (e.g., "create <arg1> <arg2>").`);
+    }
+    // Check if command string has positionals not in builder (warning case, but not an error)
+    // This is allowed - you can declare positionals in command string without registering them
+    // But we'll still validate the reverse (builder positionals must be in command string)
+}
+//# sourceMappingURL=validatePositionals.js.map

package/dist/lib/validatePositionals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatePositionals.js","sourceRoot":"","sources":["../../src/lib/validatePositionals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,UAAU,mCAAmC,CAAC,aAAqD,EAAY;IACnH,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,uDAAuD;IACvD,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;IAC5E,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,6DAA6D;IAC7D,YAAY;IACZ,qEAAqE;IACrE,uDAAuD;IACvD,mBAAmB;IACnB,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;IAChD,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,KAAK,GAA2B,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEhE,OAAO,KAAK,KAAK,IAAI,EAAE,CAAC;QACtB,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACb,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,WAAW,CAAC;AAAA,CACpB;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAAC,OAAmC,EAAqB;IAC1G,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,qFAAqF;IACrF,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,8EAA8E;QAC9E,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,gEAAgE;IAChE,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,MAAM,SAAS,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;IAE5B,4CAA4C;IAC5C,MAAM,kBAAkB,GAAG,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAChE,sGAAsG;IACrG,SAAiB,CAAC,UAAU,GAAG,CAAC,IAAY,EAAE,MAAyB,EAAE,EAAE,CAAC;QAC3E,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAAA,CACzC,CAAC;IAEF,+BAA+B;IAC/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,SAA0B,CAAC,CAAC;QACnD,sCAAsC;QACtC,MAAM,CAAC,MAAM,YAAY,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,iFAAiF;QACjF,gDAAgD;IAClD,CAAC;IAED,OAAO,WAAW,CAAC;AAAA,CACpB;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,aAA4B,EAAE,QAAgB,EAAiB;IACvG,MAAM,aAAa,GAAG,aAAa,CAAC,OAAO,CAAC;IAC5C,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;IAEtC,0CAA0C;IAC1C,MAAM,wBAAwB,GAAG,mCAAmC,CAAC,aAAa,CAAC,CAAC;IAEpF,mCAAmC;IACnC,MAAM,kBAAkB,GAAG,MAAM,6BAA6B,CAAC,OAAO,CAAC,CAAC;IAExE,yEAAyE;IACzE,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,IAAI,wBAAwB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CACb,cAAc,QAAQ,QAAQ,kBAAkB,CAAC,MAAM,gDAAgD;YACrG,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,0CAA0C,aAAa,KAAK;YAC7F,6FAA6F,CAChG,CAAC;IACJ,CAAC;IAED,yDAAyD;IACzD,MAAM,sBAAsB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,wBAAwB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAE3G,IAAI,sBAAsB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,cAAc,QAAQ,oDAAoD;YACxE,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,8CAA8C,aAAa,KAAK;YACrG,iGAAiG,CACpG,CAAC;IACJ,CAAC;IAED,0FAA0F;IAC1F,2FAA2F;IAC3F,uFAAuF;AAJtF,CAKF"}