@gunshi/bone 1.0.0-rc.1 → 1.0.0-rc.2

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
@@ -1134,6 +1134,9 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1134
1134
  * Output that must still appear — machine-readable results for an agent, warnings for the
1135
1135
  * CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
1136
1136
  *
1137
+ * The validation errors are not printed either, so `cli()` rejects with them, for the caller to
1138
+ * report them (see {@linkcode CliOptions.renderValidationErrors}).
1139
+ *
1137
1140
  * @default false
1138
1141
  */
1139
1142
  usageSilent?: boolean;
@@ -1157,6 +1160,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1157
1160
  renderHeader?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
1158
1161
  /**
1159
1162
  * Render function the validation errors.
1163
+ *
1164
+ * With the global options plugin, the rendered message is printed to stderr, the exit code is set
1165
+ * to `1`, {@linkcode CliOptions.onErrorCommand} is called, and `cli()` resolves with `undefined`.
1166
+ * Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
1167
+ * with the `AggregateError`. A renderer that returns an empty message, and
1168
+ * {@linkcode CliOptions.usageSilent}, also leave them to the caller.
1160
1169
  */
1161
1170
  renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
1162
1171
  /**
@@ -1188,10 +1197,14 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1188
1197
  */
1189
1198
  onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
1190
1199
  /**
1191
- * Hook that runs when a command throws an error
1200
+ * Hook that runs when a command throws an error, or when the arguments fail validation
1201
+ *
1202
+ * For the validation errors that the global options plugin has printed, the exit code is already `1`
1203
+ * when the hook runs, so the hook can set another one, and `cli()` resolves after it. Any other
1204
+ * error rejects `cli()` after the hook.
1192
1205
  *
1193
1206
  * @param ctx - The command context
1194
- * @param error - The error thrown during execution
1207
+ * @param error - The error thrown during execution, or the `AggregateError` of the validation errors
1195
1208
  * @since v0.27.0
1196
1209
  */
1197
1210
  onErrorCommand?: (ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>;
@@ -1360,9 +1373,11 @@ interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParam
1360
1373
  usage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
1361
1374
  /**
1362
1375
  * Validation errors rendering configuration
1363
- * - `null`: Disable rendering
1376
+ * - `null`: Disable rendering. `cli()` rejects with the validation errors, for the caller to report them
1364
1377
  * - `function`: Use custom renderer
1365
1378
  * - `undefined` (when omitted): Use default renderer
1379
+ *
1380
+ * See {@linkcode CliOptions.renderValidationErrors} for where the rendered message goes.
1366
1381
  */
1367
1382
  validationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
1368
1383
  }
package/lib/index.js CHANGED
@@ -1892,7 +1892,7 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
1892
1892
  skipPositional
1893
1893
  });
1894
1894
  const validationError = mergeValidationErrors(error, [...additionalValidationErrors, ...cliOptions.strict && !diagnostic ? createUnknownOptionErrors(findUnknownOptions(args, tokens, { toKebab: resolvedCommand.toKebab })) : []]);
1895
- return await executeCommand(resolvedCommand, await createCommandContext({
1895
+ const commandContext = await createCommandContext({
1896
1896
  args,
1897
1897
  explicit,
1898
1898
  values,
@@ -1907,7 +1907,41 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
1907
1907
  extensions: getPluginExtensions(resolvedPlugins),
1908
1908
  validationError,
1909
1909
  cliOptions
1910
- }), decorators.commandDecorators);
1910
+ });
1911
+ const reported = trackReported(commandContext);
1912
+ try {
1913
+ return await executeCommand(resolvedCommand, commandContext, decorators.commandDecorators);
1914
+ } catch (error) {
1915
+ /**
1916
+ * NOTE(kazupon): a plugin that has reported the validation errors to the user marks them, as the
1917
+ * global options plugin does after it prints them to stderr and sets the exit code. They have been
1918
+ * dealt with, and `onErrorCommand` has seen them in `executeCommand`, so `cli()` ends without
1919
+ * rejecting. Errors that nobody reported, such as when the app renders the validation errors itself
1920
+ * or an error thrown by a command, reject as before.
1921
+ */
1922
+ if (error != null && typeof error === "object" && reported.has(error)) return;
1923
+ throw error;
1924
+ }
1925
+ }
1926
+ /**
1927
+ * The key of the registry that maps the command context of a run to the set of the errors that a plugin
1928
+ * has reported to the user during the run. The global options plugin uses the same registered symbol,
1929
+ * since `gunshi` and the plugins bundle their own copies.
1930
+ */
1931
+ const REPORTED = Symbol.for("gunshi.reported");
1932
+ /**
1933
+ * Prepare the set of the errors that a plugin reports to the user during a run. The set belongs to the
1934
+ * command context of the run, so a report counts for this run only: not for a nested `cli()` in a hook,
1935
+ * nor for a later run in which the same error is thrown again.
1936
+ *
1937
+ * @param ctx - The command context of the run
1938
+ * @returns The set of the errors that have been reported during the run
1939
+ */
1940
+ function trackReported(ctx) {
1941
+ const registry = globalThis;
1942
+ const reported = /* @__PURE__ */ new WeakSet();
1943
+ (registry[REPORTED] ??= /* @__PURE__ */ new WeakMap()).set(ctx, reported);
1944
+ return reported;
1911
1945
  }
1912
1946
  /**
1913
1947
  * Create the decorator that renders the usage of the command instead of running it.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@gunshi/bone",
3
3
  "description": "gunshi minimum",
4
- "version": "1.0.0-rc.1",
4
+ "version": "1.0.0-rc.2",
5
5
  "author": {
6
6
  "name": "kazuya kawaguchi",
7
7
  "email": "kawakazu80@gmail.com"
@@ -51,11 +51,11 @@
51
51
  }
52
52
  },
53
53
  "devDependencies": {
54
- "@gunshi/definition": "1.0.0-rc.1",
55
- "@gunshi/plugin-global": "1.0.0-rc.1",
56
- "@gunshi/plugin-renderer": "1.0.0-rc.1",
54
+ "@gunshi/definition": "1.0.0-rc.2",
55
+ "@gunshi/plugin-global": "1.0.0-rc.2",
56
+ "@gunshi/plugin-renderer": "1.0.0-rc.2",
57
57
  "deno": "^2.7.14",
58
- "gunshi": "1.0.0-rc.1",
58
+ "gunshi": "1.0.0-rc.2",
59
59
  "jsr": "^0.14.3",
60
60
  "jsr-exports-lint": "^0.4.2",
61
61
  "publint": "^0.3.20",