@gunshi/bone 1.0.0-rc.7 → 1.0.0-rc.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.d.ts CHANGED
@@ -982,7 +982,7 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
982
982
  */
983
983
  cwd: string | undefined;
984
984
  /**
985
- * Command name.
985
+ * The name of the CLI, given to `cli()` as `name`.
986
986
  *
987
987
  * @see {@linkcode CliOptions.name}
988
988
  */
@@ -1144,7 +1144,11 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1144
1144
  */
1145
1145
  cwd?: string;
1146
1146
  /**
1147
- * Command program name.
1147
+ * The name of the CLI, as it is run, such as `todo`.
1148
+ *
1149
+ * The usage line and the help as JSON start with it, and so do the command that the errors point to
1150
+ * for the help and `next` of the errors of `--json`. Without it, the usage line starts with `COMMAND`,
1151
+ * and the others with `<COMMAND>`, a placeholder for how the CLI was run.
1148
1152
  */
1149
1153
  name?: string;
1150
1154
  /**
@@ -1273,11 +1277,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1273
1277
  /**
1274
1278
  * The exit code of the validation errors, such as `2`, the exit code of a usage error in many
1275
1279
  * command-line tools. They are the errors of the arguments: a missing or invalid argument, an unknown
1276
- * command or a command line that cannot be resolved, an unknown option of `strict`, a positional
1277
- * argument that the command does not take of `strictPositionals`, and `--json` given to a command
1278
- * that does not spread `jsonArgs`. With the global options plugin, the exit code is set to it when
1279
- * the errors are printed, as text or as JSON, before {@linkcode CliOptions.onErrorCommand} is called,
1280
- * which can still change it.
1280
+ * command or a command line that cannot be resolved, an unknown option, only with `strict`, a
1281
+ * positional argument that the command does not take, only with `strictPositionals`, and `--json`
1282
+ * given to a command that does not spread `jsonArgs`. Without `strict`, an unknown option is ignored
1283
+ * and the command runs, so to end it with this exit code too, give `strict: true` as well. With the
1284
+ * global options plugin, the exit code is set to it when the errors are printed, as text or as JSON,
1285
+ * before {@linkcode CliOptions.onErrorCommand} is called, which can still change it.
1281
1286
  *
1282
1287
  * It is an integer from `1` to `255`, as the `exitCode` of a `CommandError` is, and any other value is
1283
1288
  * replaced with `1`. It does not change the exit code of a `CommandError`, nor of any other error that a
@@ -1832,11 +1837,90 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
1832
1837
  * @since v0.27.0
1833
1838
  */
1834
1839
  type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
1840
+ /**
1841
+ * The keys that people write in an argument, from another library or by a typo, with the key of Gunshi to use
1842
+ * instead
1843
+ *
1844
+ * NOTE(kazupon): keep it short. A key is here when people write it, as the apps that use Gunshi did with `alias`
1845
+ * and `array` (#930). The i18n plugin keeps a copy of it (`packages/plugin-i18n/src/helpers.ts`): change both.
1846
+ *
1847
+ * @internal
1848
+ */
1849
+ type ArgKeyHints = {
1850
+ alias: 'short';
1851
+ array: 'multiple';
1852
+ desc: 'description';
1853
+ require: 'required';
1854
+ };
1855
+ /**
1856
+ * The message for a key that an argument does not have, with the key to use instead when {@link ArgKeyHints} has
1857
+ * one
1858
+ *
1859
+ * @internal
1860
+ */
1861
+ type UnknownArgKeyMessage<P> = `'${P & string}' is not a key of an argument${P extends keyof ArgKeyHints ? `: use '${ArgKeyHints[P]}'` : ''}`;
1862
+ /**
1863
+ * The keys of all the members of a union of schemas, such as a schema typed as
1864
+ * `{ type: 'string'; require: true } | { type: 'number' }`: `keyof` of a union has only the keys that every member
1865
+ * has
1866
+ *
1867
+ * @internal
1868
+ */
1869
+ type KeysOfEach<S> = S extends unknown ? keyof S : never;
1870
+ /**
1871
+ * The keys of each argument that {@link ArgSchema} does not have, mapped to a type that names the key
1872
+ *
1873
+ * NOTE(kazupon): the definition helpers infer the arguments, so a key that an argument does not have, such as
1874
+ * `positional: true` or a misspelled `require`, would type-check and be ignored at run time (#930). A value does not
1875
+ * fit the type, so the error is reported at the key, and says which key an argument does not have, and the key to
1876
+ * use instead for the keys of {@link ArgKeyHints}:
1877
+ * `Type 'true' is not assignable to type 'boolean & { "'require' is not a key of an argument: use 'required'": never; }'`.
1878
+ * The marks of Gunshi, such as the one of `jsonArgs`, are keys that start with `~gunshi.`.
1879
+ *
1880
+ * @internal
1881
+ */
1882
+ type UnknownArgKeys<A> = { [K in keyof A]: { [P in Exclude<KeysOfEach<A[K]>, keyof ArgSchema | `~gunshi.${string}`>]: { [M in UnknownArgKeyMessage<P>]: never; }; }; };
1883
+ /**
1884
+ * `G`, which a call does not infer from: an indexed access that waits for `G`, as `NoInfer` of TypeScript 5.4 does
1885
+ *
1886
+ * NOTE(kazupon): the first overload of `cli()` infers the arguments of the entry command from its `args`, and takes
1887
+ * `G` as `{ args: A; extensions: {} }` (#931). If `G` were inferred, a command of `define()` would give it from the
1888
+ * keys that the definition does not write, which `define()` types with the default parameters, such as `examples`, and
1889
+ * a command that spreads `jsonArgs` would not fit. Nor is the entry typed as `Command<{ args: A; extensions: {} }>`:
1890
+ * as the first overload, that breaks the inference of `define()` written in the call (#452).
1891
+ *
1892
+ * @typeParam G - The type of the parameters of a command
1893
+ *
1894
+ * @internal
1895
+ */
1896
+ type NoInferParams<G> = [G][G extends unknown ? 0 : never];
1897
+ /**
1898
+ * A command that the other overloads of `cli()` do not take, such as a command of another copy of the types of gunshi:
1899
+ * its arguments are `Args`, and its runner returns what a runner returns
1900
+ *
1901
+ * NOTE(kazupon): `gunshi` and `@gunshi/definition` bundle their own copies of the types. A command of `define()` types
1902
+ * its `run` with the context of its arguments, and the keys that the definition does not write with the default
1903
+ * parameters. Within one copy, TypeScript compares them by the variance of `CommandContext`, and the command fits;
1904
+ * across the copies, TypeScript compares the structures, and the command fits no other overload. So the runner takes
1905
+ * any arguments here. The arguments are `Args`, and the runner returns what a runner returns, so that an object written
1906
+ * in the call with an argument that is not valid, such as `type: 'numbr'`, is a type error, rather than taken with a
1907
+ * `ctx` of `any` (#931).
1908
+ *
1909
+ * @internal
1910
+ */
1911
+ type EntryCommandable = Omit<SubCommandable, 'args' | 'run'> & {
1912
+ args?: Args;
1913
+ run?: (...args: any[]) => Awaitable<string | void | JsonResult>;
1914
+ };
1835
1915
  /**
1836
1916
  * Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
1837
1917
  * To have them, use `cli` from `gunshi`.
1838
1918
  *
1839
- * @typeParam A - The type of {@linkcode Args | arguments} defined in the command and cli options.
1919
+ * An object written as the entry command is typed by its `args`, as with `define`: `ctx.values` of its `run` are
1920
+ * inferred from them, and a key that an argument does not have is an error.
1921
+ *
1922
+ * @typeParam A - The type of {@linkcode Args | arguments} of the entry command, inferred from its `args`.
1923
+ * @typeParam G - A type extending {@linkcode GunshiParams}, which is not inferred: `{ args: A; extensions: {} }`.
1840
1924
  *
1841
1925
  * @param args - Command line arguments
1842
1926
  * @param entry - A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
@@ -1846,7 +1930,9 @@ type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiP
1846
1930
  export declare function cli<A extends Args = Args, G extends GunshiParams = {
1847
1931
  args: A;
1848
1932
  extensions: {};
1849
- }>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
1933
+ }>(args: string[], entry: (Command<NoInferParams<G>> & {
1934
+ args?: A & UnknownArgKeys<A>;
1935
+ }) | CommandRunner<NoInferParams<G>> | LazyCommand<NoInferParams<G>>, options?: CliOptions<NoInferParams<G>>): Promise<string | undefined>;
1850
1936
  /**
1851
1937
  * Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
1852
1938
  * To have them, use `cli` from `gunshi`.
@@ -1874,4 +1960,19 @@ export declare function cli<E extends ExtendContext = ExtendContext, G extends G
1874
1960
  * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
1875
1961
  */
1876
1962
  export declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
1963
+ /**
1964
+ * Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
1965
+ * To have them, use `cli` from `gunshi`.
1966
+ *
1967
+ * This overload takes a command of another copy of the types of gunshi, such as a command of `@gunshi/definition`,
1968
+ * whose types the overloads above cannot compare. `@gunshi/bone` exports no `define`, so a CLI on it defines its
1969
+ * commands with another package. Its arguments are checked as `Args`, and its runner returns what a runner returns. It
1970
+ * must be the last of the overloads.
1971
+ *
1972
+ * @param args - Command line arguments
1973
+ * @param entry - A command-like object (command, command runner, or lazy command)
1974
+ * @param options - A {@link CliOptions | CLI options}
1975
+ * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
1976
+ */
1977
+ export declare function cli(args: string[], entry: EntryCommandable, options?: CliOptions): Promise<string | undefined>;
1877
1978
  export type { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, CommandRunnerResult, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, HasJsonArgs, JsonResult, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator };
package/lib/index.js CHANGED
@@ -1,4 +1,4 @@
1
- // ../../node_modules/.pnpm/args-tokens@1.2.0/node_modules/args-tokens/lib/parser.js
1
+ // ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/parser.js
2
2
  /**
3
3
  * forked from `nodejs/node` (`pkgjs/parseargs`)
4
4
  * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
@@ -200,7 +200,7 @@ function isLongOptionAndValue(arg) {
200
200
  function hasLongOptionPrefix(arg) {
201
201
  return arg.startsWith(LONG_OPTION_PREFIX) && arg.length > 2;
202
202
  }
203
- // ../../node_modules/.pnpm/args-tokens@1.2.0/node_modules/args-tokens/lib/utils.js
203
+ // ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/utils.js
204
204
  /**
205
205
  * Entry point of utils.
206
206
  *
@@ -230,7 +230,7 @@ function kebabnize(str) {
230
230
  function formatChoices(choices) {
231
231
  return choices.map((value) => JSON.stringify(value)).join(", ");
232
232
  }
233
- // ../../node_modules/.pnpm/args-tokens@1.2.0/node_modules/args-tokens/lib/resolver-DT0CiD5Y.js
233
+ // ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/resolver-DWmHKGSL.js
234
234
  /**
235
235
  * Internal definitions shared by the modules of `args-tokens`.
236
236
  *
@@ -266,6 +266,11 @@ const PURE_PARSE = Symbol.for("args-tokens.pureParse");
266
266
  * Each code identifies a validation failure category and is also suitable as an
267
267
  * i18n resource key for localized rendering.
268
268
  *
269
+ * A value that breaks a constraint of the options of a combinator is reported with a code of its
270
+ * own: `tooSmall` and `tooLarge` for `min` and `max` of `number()`, `integer()` and `float()`,
271
+ * `tooShort` and `tooLong` for `minLength` and `maxLength` of `string()`, and `patternMismatch` for
272
+ * its `pattern`. What a `parse` function of your own throws is reported as `customParse`.
273
+ *
269
274
  * {@link resolveArgs} and `parse()` do not report `unknownOption` or `unexpectedPositional`: a caller
270
275
  * that knows what a command takes, such as a CLI framework, reports them. An option that is not in the
271
276
  * schema takes the argument after it as its value, unless that argument is an option, and the value
@@ -283,7 +288,12 @@ const ArgsValidationErrorKeys = {
283
288
  missingValue: "err:arg:missing-value",
284
289
  conflict: "err:arg:conflict",
285
290
  invalidDefault: "err:arg:invalid-default",
286
- unexpectedPositional: "err:arg:unexpected-positional"
291
+ unexpectedPositional: "err:arg:unexpected-positional",
292
+ tooSmall: "err:arg:too-small",
293
+ tooLarge: "err:arg:too-large",
294
+ tooShort: "err:arg:too-short",
295
+ tooLong: "err:arg:too-long",
296
+ patternMismatch: "err:arg:pattern-mismatch"
287
297
  };
288
298
  /**
289
299
  * Brand that marks {@link ArgsValidationError} instances.
@@ -1144,7 +1154,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
1144
1154
  }
1145
1155
  return [];
1146
1156
  }
1147
- // ../../node_modules/.pnpm/args-tokens@1.2.0/node_modules/args-tokens/lib/index.js
1157
+ // ../../node_modules/.pnpm/args-tokens@1.3.0/node_modules/args-tokens/lib/index.js
1148
1158
  /**
1149
1159
  * @author kazuya kawaguchi (a.k.a. kazupon)
1150
1160
  * @license MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gunshi/bone",
3
- "version": "1.0.0-rc.7",
3
+ "version": "1.0.0-rc.8",
4
4
  "description": "gunshi minimum",
5
5
  "keywords": [
6
6
  "cli",
@@ -48,10 +48,10 @@
48
48
  "access": "public"
49
49
  },
50
50
  "devDependencies": {
51
- "@gunshi/definition": "1.0.0-rc.7",
52
- "@gunshi/plugin-global": "1.0.0-rc.7",
53
- "@gunshi/plugin-renderer": "1.0.0-rc.7",
54
- "gunshi": "1.0.0-rc.7",
51
+ "@gunshi/definition": "1.0.0-rc.8",
52
+ "@gunshi/plugin-global": "1.0.0-rc.8",
53
+ "@gunshi/plugin-renderer": "1.0.0-rc.8",
54
+ "gunshi": "1.0.0-rc.8",
55
55
  "publint": "^0.3.20"
56
56
  },
57
57
  "engines": {