Prepare for 13.0.0-0 (#81)

CHANGELOG.md

@@ -9,6 +9,18 @@ The version numbering does not follow semantic versioning but instead aligns wit
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [13.0.0-0] (2024-12-08)
+
+### Added
+
+- strongly type `.optsWithGlobals()` to include inferred globals ([#78])
+- weakly type `.getOptionValueSourceWithGlobals()` to include inferred globals ([#78])
+- infer narrow types for choices, so no longer need to specify as `const` ([#79])
+
+### Changed
+
+- *Breaking:* Typescript 5.0 or higher is required ([#79])
+
 ## [12.1.0] (2024-05-18)
 
 ### Changed
@@ -168,6 +180,7 @@ The version numbering does not follow semantic versioning but instead aligns wit
 - inferred types for `.action()`
 - inferred types for `.opts()`
 
+[13.0.0-0]: https://github.com/commander-js/extra-typings/compare/v12.1.0...v13.0.0-0
 [12.1.0]: https://github.com/commander-js/extra-typings/compare/v12.0.1...v12.1.0
 [12.0.1]: https://github.com/commander-js/extra-typings/compare/v12.0.0...v12.0.1
 [12.0.0]: https://github.com/commander-js/extra-typings/compare/v11.0.0...v12.0.0
@@ -197,7 +210,8 @@ The version numbering does not follow semantic versioning but instead aligns wit
 [#49]: https://github.com/commander-js/extra-typings/pull/49
 [#50]: https://github.com/commander-js/extra-typings/pull/50
 [#59]: https://github.com/commander-js/extra-typings/pull/59
-
 [#65]: https://github.com/commander-js/extra-typings/pull/65
 [#66]: https://github.com/commander-js/extra-typings/pull/66
 [#70]: https://github.com/commander-js/extra-typings/pull/70
+[#78]: https://github.com/commander-js/extra-typings/pull/78
+[#79]: https://github.com/commander-js/extra-typings/pull/79

index.d.ts

@@ -320,8 +320,6 @@ export type CommandUnknownOpts = Command<unknown[], OptionValues, OptionValues>;
 
 // ----- full copy of normal commander typings from here down, with extra type inference -----
 
-// Using method rather than property for method-signature-style, to document method overloads separately. Allow either.
-/* eslint-disable @typescript-eslint/method-signature-style */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 export class CommanderError extends Error {
@@ -532,7 +530,7 @@ export class Option<
 
   /**
    * Return option name, in a camelcase format that can be used
-   * as a object attribute key.
+   * as an object attribute key.
    */
   attributeName(): string;
 
@@ -547,12 +545,25 @@ export class Option<
 export class Help {
   /** output helpWidth, long lines are wrapped to fit */
   helpWidth?: number;
+  minWidthToWrap: number;
   sortSubcommands: boolean;
   sortOptions: boolean;
   showGlobalOptions: boolean;
 
   constructor();
 
+  /*
+   * prepareContext is called by Commander after applying overrides from `Command.configureHelp()`
+   * and just before calling `formatHelp()`.
+   *
+   * Commander just uses the helpWidth and the others are provided for subclasses.
+   */
+  prepareContext(contextOptions: {
+    error?: boolean;
+    helpWidth?: number;
+    outputHasColors?: boolean;
+  }): void;
+
   /** Get the command term to show in the list of subcommands. */
   subcommandTerm(cmd: CommandUnknownOpts): string;
   /** Get the command summary to show in the list of subcommands. */
@@ -588,18 +599,60 @@ export class Help {
   longestGlobalOptionTermLength(cmd: CommandUnknownOpts, helper: Help): number;
   /** Get the longest argument term length. */
   longestArgumentTermLength(cmd: CommandUnknownOpts, helper: Help): number;
+
+  /** Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations. */
+  displayWidth(str: string): number;
+
+  /** Style the titles. Called with 'Usage:', 'Options:', etc. */
+  styleTitle(title: string): string;
+
+  /** Usage: <str> */
+  styleUsage(str: string): string;
+  /** Style for command name in usage string.  */
+  styleCommandText(str: string): string;
+
+  styleCommandDescription(str: string): string;
+  styleOptionDescription(str: string): string;
+  styleSubcommandDescription(str: string): string;
+  styleArgumentDescription(str: string): string;
+  /** Base style used by descriptions. */
+  styleDescriptionText(str: string): string;
+
+  styleOptionTerm(str: string): string;
+  styleSubcommandTerm(str: string): string;
+  styleArgumentTerm(str: string): string;
+
+  /** Base style used in terms and usage for options. */
+  styleOptionText(str: string): string;
+  /** Base style used in terms and usage for subcommands. */
+  styleSubcommandText(str: string): string;
+  /** Base style used in terms and usage for arguments. */
+  styleArgumentText(str: string): string;
+
   /** Calculate the pad width from the maximum term length. */
   padWidth(cmd: CommandUnknownOpts, helper: Help): number;
 
   /**
-   * Wrap the given string to width characters per line, with lines after the first indented.
-   * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted.
+   * Wrap a string at whitespace, preserving existing line breaks.
+   * Wrapping is skipped if the width is less than `minWidthToWrap`.
    */
-  wrap(
-    str: string,
-    width: number,
-    indent: number,
-    minColumnWidth?: number,
+  boxWrap(str: string, width: number): string;
+
+  /** Detect manually wrapped and indented strings by checking for line break followed by whitespace. */
+  preformatted(str: string): boolean;
+
+  /**
+   * Format the "item", which consists of a term and description. Pad the term and wrap the description, indenting the following lines.
+   *
+   * So "TTT", 5, "DDD DDDD DD DDD" might be formatted for this.helpWidth=17 like so:
+   *   TTT    DDD DDDD
+   *          DD DDD
+   */
+  formatItem(
+    term: string,
+    termWidth: number,
+    description: string,
+    helper: Help,
   ): string;
 
   /** Generate the built-in help text. */
@@ -622,9 +675,14 @@ export interface AddHelpTextContext {
 export interface OutputConfiguration {
   writeOut?(str: string): void;
   writeErr?(str: string): void;
+  outputError?(str: string, write: (str: string) => void): void;
+
   getOutHelpWidth?(): number;
   getErrHelpWidth?(): number;
-  outputError?(str: string, write: (str: string) => void): void;
+
+  getOutHasColors?(): boolean;
+  getErrHasColors?(): boolean;
+  stripColor?(str: string): string;
 }
 
 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';