feat: Add fish shell completion generation

This commit introduces the `gen-completions` command to generate shell completion scripts, with initial support for the `fish` shell.

Key changes include:
- A new `GenCompletionsCommand` class and its integration into the parsing logic in `src/index.ts`, enabling the `gen-completions` subcommand.
- Updates to `src/metadata.ts` to refine argument collection, ensuring compatibility with dynamically generated command structures.
- Comprehensive documentation in `README.md` detailing how to generate and install `fish` shell completions for the application.

This feature enhances usability by providing command-line auto-completion capabilities.

Author: sigmaSd

README.md

@@ -557,8 +557,37 @@ Options:
       Show this help message
 
 Commands:
-  serve    Start development server
-  build    Build the project
+  serve              Start development server
+  build              Start the project
+  gen-completions    Generate shell completions
+```
+
+## Shell Completions
+
+The library includes a built-in `gen-completions` command that generates
+completion scripts for various shells (currently supporting `fish`).
+
+### Generating Completions
+
+To generate completions for your application:
+
+```bash
+# Generate fish completions
+deno run myapp.ts gen-completions fish
+```
+
+### Installing Completions (Fish)
+
+To use the completions immediately in your current fish session:
+
+```fish
+deno run myapp.ts gen-completions fish | source
+```
+
+To make them permanent, save the output to your fish configuration directory:
+
+```fish
+deno run myapp.ts gen-completions fish > ~/.config/fish/completions/myapp.fish
 ```
 
 ## Error Handling

src/completions.ts

@@ -0,0 +1,60 @@
+import type { ArgumentDef, ParsedArg, SubCommand } from "./types.ts";
+import { collectInstanceArgumentDefs } from "./metadata.ts";
+
+/**
+ * Generates fish shell completions for a command.
+ */
+export function generateFishCompletions(
+  appName: string,
+  parsedArgs: ParsedArg[],
+  _argumentDefs: ArgumentDef[],
+  subCommands?: Map<string, SubCommand>,
+): string {
+  const lines: string[] = [];
+
+  // Disable file completion for the command by default
+  lines.push(`complete -c ${appName} -f`);
+
+  // Add completions for global options
+  // These should be available when NO subcommand has been selected yet
+  for (const arg of parsedArgs) {
+    const shortFlag = arg.short ? ` -s ${arg.short}` : "";
+    const desc = arg.description ? ` -d "${arg.description}"` : "";
+    lines.push(
+      `complete -c ${appName} -n "__fish_use_subcommand" -l ${arg.name}${shortFlag}${desc}`,
+    );
+  }
+
+  // Add completions for subcommands
+  if (subCommands && subCommands.size > 0) {
+    for (const [name, subCommand] of subCommands) {
+      const desc = subCommand.description
+        ? ` -d "${subCommand.description}"`
+        : "";
+      // Only suggest subcommand if we haven't seen one yet
+      lines.push(
+        `complete -c ${appName} -n "__fish_use_subcommand" -a "${name}"${desc}`,
+      );
+
+      // Generate completions for the subcommand
+      // We need to instantiate it to get its arguments
+      const instance = new subCommand.commandClass() as Record<string, unknown>;
+      const { parsedArgs: subParsedArgs } = collectInstanceArgumentDefs(
+        instance,
+        { strict: false },
+      );
+
+      // For subcommand options, we check if the subcommand is present in the command line
+      for (const arg of subParsedArgs) {
+        const shortFlag = arg.short ? ` -s ${arg.short}` : "";
+        const desc = arg.description ? ` -d "${arg.description}"` : "";
+        // Condition: __fish_seen_subcommand_from <subcommand>
+        lines.push(
+          `complete -c ${appName} -n "__fish_seen_subcommand_from ${name}" -l ${arg.name}${shortFlag}${desc}`,
+        );
+      }
+    }
+  }
+
+  return lines.join("\n");
+}

src/index.ts

@@ -1,7 +1,16 @@
 import type { ParseOptions, ParseResult, SupportedType } from "./types.ts";
 import { printHelp } from "./help.ts";
 import { handleHelpDisplay, handleParsingError } from "./error-handling.ts";
+import {
+  argument,
+  command,
+  description,
+  required,
+  type,
+  validate,
+} from "./decorators.ts";
 import { collectInstanceArgumentDefs } from "./metadata.ts";
+import { generateFishCompletions } from "./completions.ts";
 
 /**
  * Base class for CLI argument classes.
@@ -38,6 +47,22 @@ export class Args {
   }
 }
 
+/**
+ * Internal command for generating shell completions.
+ */
+@command
+class GenCompletionsCommand {
+  @description("The shell to generate completions for (e.g., 'fish')")
+  @type("string")
+  @argument()
+  @validate(
+    (value: string) => value === "fish",
+    "must be one of: fish (currently only fish is supported)",
+  )
+  @required()
+  shell!: string;
+}
+
 /**
  * CLI decorator to configure a class for command line parsing.
  *
@@ -268,6 +293,15 @@ function parseInstanceBased(
   // Collect subcommands from instance
   const subCommands = collectSubCommandsFromInstance(instance);
 
+  // Inject gen-completions command if not already present and we are at the root
+  if (!commandPath && !subCommands.has("gen-completions")) {
+    subCommands.set("gen-completions", {
+      name: "gen-completions",
+      commandClass: GenCompletionsCommand,
+      description: "Generate shell completions",
+    });
+  }
+
   // Create argument map for parsing
   const argMap = new Map<string, {
     name: string;
@@ -768,6 +802,22 @@ function parseInstanceBased(
         Object.assign(typedResult as Record<string, unknown>, parsedValues);
         result[arg] = typedResult;
       }
+
+      // Handle gen-completions execution
+      if (
+        arg === "gen-completions" &&
+        subCommand.commandClass === GenCompletionsCommand
+      ) {
+        const completions = generateFishCompletions(
+          options?.name || "app",
+          parsedArgs,
+          argumentDefs,
+          subCommands,
+        );
+        console.log(completions);
+        Deno.exit(0);
+      }
+
       break; // Stop processing after subcommand
     } else {
       // Handle positional argument

src/metadata.ts

@@ -45,6 +45,10 @@ function isUserDefinedProperty(descriptor: PropertyDescriptor): boolean {
   return descriptor.writable === true && descriptor.enumerable === true;
 }
 
+interface CollectionOptions {
+  strict?: boolean;
+}
+
 /**
  * Collects argument definitions from an instance.
  *
@@ -53,10 +57,12 @@ function isUserDefinedProperty(descriptor: PropertyDescriptor): boolean {
  * duplicate short flags.
  *
  * @param instance - The class instance to analyze
+ * @param options - Configuration options for metadata collection
  * @returns Object containing parsed options and positional argument definitions
  */
 export function collectInstanceArgumentDefs(
   instance: Record<string, unknown>,
+  options: CollectionOptions = { strict: true },
 ): {
   parsedArgs: ParsedArg[];
   argumentDefs: ArgumentDef[];
@@ -98,11 +104,16 @@ export function collectInstanceArgumentDefs(
     if (propertyMetadata?.argument) {
       // Positional argument
       if (instance[propName] === undefined && !propertyMetadata.type) {
-        throw new Error(
-          `Property '${propName}' has no default value and no @type() decorator. ` +
-            `Use @type("string"), @type("number"), etc. to specify the expected type. ` +
-            `This is required because TypeScript cannot infer the type from undefined values.`,
-        );
+        if (options.strict) {
+          throw new Error(
+            `Property '${propName}' has no default value and no @type() decorator. ` +
+              `Use @type("string"), @type("number"), etc. to specify the expected type. ` +
+              `This is required because TypeScript cannot infer the type from undefined values.`,
+          );
+        } else {
+          // In non-strict mode, skip properties with undetermined types
+          continue;
+        }
       }
 
       argumentDefs.push({
@@ -116,11 +127,16 @@ export function collectInstanceArgumentDefs(
     } else if (propertyMetadata?.rawRest) {
       // Raw rest argument
       if (instance[propName] === undefined && !propertyMetadata.type) {
-        throw new Error(
-          `Property '${propName}' has no default value and no @type() decorator. ` +
-            `Use @type("string[]") or another array type to specify the expected type. ` +
-            `This is required because TypeScript cannot infer the type from undefined values.`,
-        );
+        if (options.strict) {
+          throw new Error(
+            `Property '${propName}' has no default value and no @type() decorator. ` +
+              `Use @type("string[]") or another array type to specify the expected type. ` +
+              `This is required because TypeScript cannot infer the type from undefined values.`,
+          );
+        } else {
+          // In non-strict mode, skip properties with undetermined types
+          continue;
+        }
       }
 
       argumentDefs.push({
@@ -134,11 +150,16 @@ export function collectInstanceArgumentDefs(
     } else {
       // Regular option
       if (instance[propName] === undefined && !propertyMetadata?.type) {
-        throw new Error(
-          `Property '${propName}' has no default value and no @type() decorator. ` +
-            `Use @type("string"), @type("number"), etc. to specify the expected type. ` +
-            `This is required because TypeScript cannot infer the type from undefined values.`,
-        );
+        if (options.strict) {
+          throw new Error(
+            `Property '${propName}' has no default value and no @type() decorator. ` +
+              `Use @type("string"), @type("number"), etc. to specify the expected type. ` +
+              `This is required because TypeScript cannot infer the type from undefined values.`,
+          );
+        } else {
+          // In non-strict mode, skip properties with undetermined types
+          continue;
+        }
       }
 
       parsedArgs.push({

tests/completions.test.ts

@@ -0,0 +1,48 @@
+import { assertEquals, assertStringIncludes } from "@std/assert";
+
+Deno.test("gen-completions fish", async () => {
+  const command = new Deno.Command("deno", {
+    args: ["run", "examples/example.ts", "gen-completions", "fish"],
+    stdout: "piped",
+    stderr: "piped",
+  });
+
+  const { code, stdout, stderr } = await command.output();
+  const output = new TextDecoder().decode(stdout);
+  const error = new TextDecoder().decode(stderr);
+
+  assertEquals(code, 0, `Command failed with code ${code}. Stderr: ${error}`);
+
+  // Check for some expected fish completion lines
+  assertStringIncludes(output, "complete -c myapp -f");
+  assertStringIncludes(
+    output,
+    'complete -c myapp -n "__fish_use_subcommand" -a "serve" -d "Start the development server"',
+  );
+  assertStringIncludes(
+    output,
+    'complete -c myapp -n "__fish_seen_subcommand_from serve" -l port',
+  );
+  assertStringIncludes(
+    output,
+    'complete -c myapp -n "__fish_use_subcommand" -l verbose',
+  );
+});
+
+Deno.test("gen-completions missing shell arg", async () => {
+  const command = new Deno.Command("deno", {
+    args: ["run", "examples/example.ts", "gen-completions"],
+    stdout: "piped",
+    stderr: "piped",
+  });
+
+  const { code, stderr } = await command.output();
+  const error = new TextDecoder().decode(stderr);
+
+  // Should fail because shell is required
+  assertEquals(code, 1);
+  assertStringIncludes(
+    error,
+    "Validation error for argument 'shell': is required",
+  );
+});