refactor(types): simplify definition helpers

[kazupon]

Description

Linked Issues

Additional context

Summary by CodeRabbit

• Refactor

  • Streamlined TypeScript typings for command definitions, lazy commands, plugins, and plugin decorators to improve type inference and IDE autocomplete.
  • Renamed and clarified the extension-extraction utility and adjusted command-context return typing for more consistent consumer types.
  • Reworked internal normalization approach for parameter/extension shapes.

• Exports

  • Re-exported the merge-extensions utility for consumer use.

• Tests

  • Added type-level tests validating parameter normalization and extension merging.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e3b16123-e42c-4c02-84f6-ff4e590fc8d5

📥 Commits

Reviewing files that changed from the base of the PR and between 45830cc and 8709a15.

📒 Files selected for processing (1)

• packages/gunshi/src/types.ts

---

📝 Walkthrough

Walkthrough

This PR refactors the Gunshi type system by introducing NormalizeToGunshiParams as a foundational normalization helper, creating new command and plugin type helpers, and updating public APIs (define, defineWithTypes, lazyWithTypes, plugin) and decorator/context typings to consume these helpers.

Changes

Type System Refactoring

Layer / File(s)	Summary
NormalizeToGunshiParams normalization foundation packages/gunshi/src/types.ts	NormalizeToGunshiParams conditional type now explicitly branches on whether input G includes args and/or extensions, mapping to normalized GunshiParams shapes with defaults ({} for missing extensions, Args for missing args).
Definition API refactoring with CommandDefinition helpers packages/gunshi/src/definition.ts	Defines CommandDefinitionResult and CommandDefinition, updates define and defineWithTypes to accept CommandDefinition<...> shapes, and changes lazyWithTypes to use imported NormalizeToGunshiParams for computing FullGunshiParams.
Plugin core refactor: dependency & merged params helpers packages/gunshi/src/plugin/core.ts	Adds DependencyExtensions, DependencyParams, MergedPluginExtensions, and MergedPluginParams; updates PluginOptions defaults and both plugin overloads to compute resolved dependency extensions and merged extensions via these helpers.
Context and decorator typing updates packages/gunshi/src/context.ts, packages/gunshi/src/plugin/context.ts, packages/gunshi/src/plugin.ts	Renames extension extractor to ExtractExtensionValues, introduces CommandContextResult for createCommandContext return typing, updates PluginContext decorator callback types to use MergeGunshiExtensions<G, L>, updates createPluginContext decorator registrations, and re-exports MergeGunshiExtensions from plugin.ts.
Type validation for NormalizeToGunshiParams packages/gunshi/src/type.test-d.ts	Adds imports and vitest type-level assertions verifying NormalizeToGunshiParams normalization for args-only, extensions-only, and combined inputs, and tests MergeGunshiExtensions merging behavior.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• kazupon/gunshi#259: Related plugin/core typing changes around dependency/extension merging and PluginContext typing.
• kazupon/gunshi#262: Prior work on plugin dependency-extension inference and merge helpers; overlaps the same type-system area.
• kazupon/gunshi#330: Updates consumer/test usages of defineWithTypes that align with the define/defineWithTypes typing changes here.

Suggested labels

refactoring

Poem

🐰 A tiny rabbit hops through types so neat,

Lines aligned and conditionals meet,
Helpers born to normalize the land,
Plugins and commands now hold hands,
A soft thump — the types are complete.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor(types): simplify definition helpers' is partially related to the changeset, focusing on type simplification but not capturing the broader scope of changes across multiple modules and the introduction of new helper types.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/types

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying gunshi with    Cloudflare Pages

Latest commit:	8709a15
Status:	✅  Deploy successful!
Preview URL:	https://42c4d8e5.gunshi.pages.dev
Branch Preview URL:	https://refactor-types.gunshi.pages.dev

View logs

[pkg-pr-new]

Open in StackBlitz

@gunshi/bone

npm i https://pkg.pr.new/@gunshi/bone@566

@gunshi/combinators

npm i https://pkg.pr.new/@gunshi/combinators@566

@gunshi/definition

npm i https://pkg.pr.new/@gunshi/definition@566

@gunshi/docs

npm i https://pkg.pr.new/@gunshi/docs@566

gunshi

npm i https://pkg.pr.new/gunshi@566

@gunshi/plugin

npm i https://pkg.pr.new/@gunshi/plugin@566

@gunshi/plugin-completion

npm i https://pkg.pr.new/@gunshi/plugin-completion@566

@gunshi/plugin-dryrun

npm i https://pkg.pr.new/@gunshi/plugin-dryrun@566

@gunshi/plugin-global

npm i https://pkg.pr.new/@gunshi/plugin-global@566

@gunshi/plugin-i18n

npm i https://pkg.pr.new/@gunshi/plugin-i18n@566

@gunshi/plugin-renderer

npm i https://pkg.pr.new/@gunshi/plugin-renderer@566

@gunshi/resources

npm i https://pkg.pr.new/@gunshi/resources@566

@gunshi/shared

npm i https://pkg.pr.new/@gunshi/shared@566

commit: 8709a15

[coderabbitai]

🧹 Nitpick comments (1)

packages/gunshi/src/type.test-d.ts (1)

63-75: ⚡ Quick win

Add branch-complete coverage for NormalizeToGunshiParams.

This block validates 3 branches well; add explicit cases for GunshiParams passthrough and default fallback to lock all conditional paths.

Proposed test additions

 test('NormalizeToGunshiParams', () => {
   expectTypeOf<NormalizeToGunshiParams<{ args: typeof _args1 }>>().toEqualTypeOf<
     GunshiParams<{ args: typeof _args1; extensions: {} }>
   >()

   expectTypeOf<NormalizeToGunshiParams<{ extensions: { foo: Extension1 } }>>().toEqualTypeOf<
     GunshiParams<{ args: Args; extensions: { foo: Extension1 } }>
   >()

   expectTypeOf<
     NormalizeToGunshiParams<{ args: typeof _args1; extensions: { foo: Extension2 } }>
   >().toEqualTypeOf<GunshiParams<{ args: typeof _args1; extensions: { foo: Extension2 } }>>()
+
+  expectTypeOf<
+    NormalizeToGunshiParams<GunshiParams<{ args: typeof _args1; extensions: { foo: Extension1 } }>>
+  >().toEqualTypeOf<GunshiParams<{ args: typeof _args1; extensions: { foo: Extension1 } }>>()
+
+  expectTypeOf<NormalizeToGunshiParams<{}>>().toEqualTypeOf<DefaultGunshiParams>()
 })

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/gunshi/src/type.test-d.ts` around lines 63 - 75, Add two additional
type-level test cases to fully cover NormalizeToGunshiParams branches: one
asserting that NormalizeToGunshiParams<GunshiParams<{ args: typeof _args1;
extensions: { foo: Extension2 } }>>() equals the same GunshiParams type
(passthrough branch), and one asserting that NormalizeToGunshiParams<{}>()
equals GunshiParams<{ args: Args; extensions: {} }> (default fallback branch);
place these new expectTypeOf checks alongside the existing tests so all
conditional paths of NormalizeToGunshiParams are exercised.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/gunshi/src/type.test-d.ts`:
- Around line 63-75: Add two additional type-level test cases to fully cover
NormalizeToGunshiParams branches: one asserting that
NormalizeToGunshiParams<GunshiParams<{ args: typeof _args1; extensions: { foo:
Extension2 } }>>() equals the same GunshiParams type (passthrough branch), and
one asserting that NormalizeToGunshiParams<{}>() equals GunshiParams<{ args:
Args; extensions: {} }> (default fallback branch); place these new expectTypeOf
checks alongside the existing tests so all conditional paths of
NormalizeToGunshiParams are exercised.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6c898005-cf57-41a7-a6a8-01976bfd47a3

📥 Commits

Reviewing files that changed from the base of the PR and between 2bda6e3 and d2c4055.

📒 Files selected for processing (4)

• packages/gunshi/src/definition.ts
• packages/gunshi/src/plugin/core.ts
• packages/gunshi/src/type.test-d.ts
• packages/gunshi/src/types.ts