docs(guide): use define function - #424
Conversation
Updated code examples in the getting-started guide to use the define() helper function for command definitions instead of plain object literals. This change: - Adds define import from gunshi - Wraps command object with define() call - Maintains consistency with recommended best practices The example now demonstrates the proper way to define commands from the start, helping new users adopt the correct pattern immediately.
Updated all code examples in the declarative configuration guide to use the define() helper function instead of plain object literals. This comprehensive update covers: - Basic command structure examples - Complete working examples - Positional argument definitions - Custom type argument examples - Kebab-case conversion examples - Conflicting options examples - Examples with dynamic/async features - Explicit argument tracking examples Each example now demonstrates the recommended pattern of wrapping command definitions with define(), ensuring consistency across all documentation and helping users understand the proper command definition approach.
Updated the command hooks guide to use define() helper for command definition instead of inline object literal. This change: - Extracts command definition from cli() call - Uses define() to wrap command object - Improves code clarity by separating command definition from hook setup The refactored example better demonstrates separation of concerns, showing hooks configuration distinct from command definition.
Updated the internationalization guide's built-in resources example to use the define() helper function for command definition. This change: - Adds define import to the example - Wraps command object with define() - Maintains consistency with other documentation examples The example now shows the proper pattern for defining commands when using built-in translation resources from @gunshi/resources package.
Updated the plugin usage template in guidelines to use define() helper for command definition instead of plain object literal. This change: - Adds define import to the template code - Wraps command object with define() - Provides correct pattern for plugin usage examples Plugin developers using this template will now see the recommended approach for defining commands when integrating their plugins.
Updated all plugin testing examples to use define() helper for creating mock command objects instead of plain object literals. This change: - Adds define import to test file examples - Wraps all mock command objects with define() - Maintains consistency with production code patterns Changes cover multiple testing scenarios: - Basic plugin initialization tests - Configuration validation tests - Extension factory tests - Extension method interaction tests - Async extension tests - Plugin dependency tests - Plugin interaction tests Using define() in tests ensures test code follows the same patterns as production code, making tests more representative and maintainable.
WalkthroughThe PR updates documentation examples across multiple guide sections to adopt the new Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
@gunshi/bone
@gunshi/definition
@gunshi/docs
gunshi
@gunshi/plugin
@gunshi/plugin-completion
@gunshi/plugin-dryrun
@gunshi/plugin-global
@gunshi/plugin-i18n
@gunshi/plugin-renderer
@gunshi/resources
@gunshi/shared
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
packages/docs/src/guide/advanced/command-hooks.md(1 hunks)packages/docs/src/guide/advanced/internationalization.md(1 hunks)packages/docs/src/guide/essentials/declarative.md(24 hunks)packages/docs/src/guide/essentials/getting-started.md(2 hunks)packages/docs/src/guide/plugin/guidelines.md(1 hunks)packages/docs/src/guide/plugin/testing.md(12 hunks)
🧰 Additional context used
🧠 Learnings (5)
📓 Common learnings
Learnt from: CR
Repo: kazupon/gunshi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-05T09:55:04.596Z
Learning: Update documentation at gunshi.dev when adding new features or changing APIs
📚 Learning: 2025-12-05T09:55:04.596Z
Learnt from: CR
Repo: kazupon/gunshi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-05T09:55:04.596Z
Learning: Applies to packages/plugin-*/src/**/*.ts : Implement plugins using gunshi/plugin package for minimal dependencies following the plugin API in packages/plugin/src/
Applied to files:
packages/docs/src/guide/plugin/guidelines.mdpackages/docs/src/guide/plugin/testing.mdpackages/docs/src/guide/advanced/internationalization.md
📚 Learning: 2025-12-05T09:55:04.596Z
Learnt from: CR
Repo: kazupon/gunshi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-05T09:55:04.596Z
Learning: Update documentation at gunshi.dev when adding new features or changing APIs
Applied to files:
packages/docs/src/guide/plugin/guidelines.mdpackages/docs/src/guide/advanced/command-hooks.mdpackages/docs/src/guide/plugin/testing.mdpackages/docs/src/guide/essentials/getting-started.mdpackages/docs/src/guide/advanced/internationalization.mdpackages/docs/src/guide/essentials/declarative.md
📚 Learning: 2025-12-05T09:55:04.596Z
Learnt from: CR
Repo: kazupon/gunshi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-05T09:55:04.596Z
Learning: Applies to packages/plugin/src/**/*.ts : Provide type helpers for plugin developers such as GunshiParams, CommandContext, etc.
Applied to files:
packages/docs/src/guide/plugin/guidelines.mdpackages/docs/src/guide/advanced/command-hooks.mdpackages/docs/src/guide/plugin/testing.mdpackages/docs/src/guide/advanced/internationalization.mdpackages/docs/src/guide/essentials/declarative.md
📚 Learning: 2025-12-05T09:55:04.596Z
Learnt from: CR
Repo: kazupon/gunshi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-05T09:55:04.596Z
Learning: Applies to packages/gunshi/src/**/*.ts : Test changes across all supported runtimes (Node.js, Deno, Bun) when modifying core functionality
Applied to files:
packages/docs/src/guide/plugin/testing.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Test on Node.js 20
🔇 Additional comments (9)
packages/docs/src/guide/plugin/testing.md (2)
54-73: define() import and usage correctly applied.The import of
definefrom gunshi and its usage to wrap command objects is consistent with the pattern shown throughout this PR. The mock command construction usingdefine()is correct.
156-165: Consistent define() usage across test examples.All test examples that create mock commands correctly use
define({ ... })pattern. The integration withcreateCommandContextandvi.fn()mocks is properly maintained. This provides clear, idiomatic test examples for readers.Also applies to: 219-234, 295-320
packages/docs/src/guide/essentials/getting-started.md (1)
89-118: Clear introduction of define() with logical progression.The guide demonstrates a natural progression from inline functions to declarative command definition with
define(). The import addition and usage are consistent with other documentation files, and the example clearly shows the benefits of declarative configuration. This is a pedagogically sound introduction to the API.packages/docs/src/guide/plugin/guidelines.md (1)
839-847: README template correctly demonstrates define() usage.The provided README template is a helpful reference for plugin authors. It correctly shows the updated API pattern with
define()wrapper and serves as a clear guide for documentation authoring. The imports and usage are consistent with updated guidelines across the documentation.packages/docs/src/guide/advanced/command-hooks.md (1)
55-80: define() integrates correctly with lifecycle hooks.The examples demonstrate proper integration of
define()with CLI lifecycle hooks (onBeforeCommand,onAfterCommand,onErrorCommand). The pattern correctly separates command definition from CLI configuration, with hooks remaining in the options object. The usage is consistent and clear.packages/docs/src/guide/advanced/internationalization.md (1)
156-178: define() correctly shown alongside i18n helper functions.The examples demonstrate proper usage of
define()for basic commands and showcase how specialized i18n helpers likedefineI18nWithTypesextend the basedefine()functionality. The pattern is clear and provides good context for understanding the API hierarchy.packages/docs/src/guide/essentials/declarative.md (3)
16-35: Declarative structure clearly presented with define().The guide provides an excellent introduction to the command structure with clear comments explaining each section. The define() wrapper is presented naturally as the primary way to create commands, making it the idiomatic pattern for new users.
47-110: Complete example demonstrates full declarative capabilities.The comprehensive example shows how
define()brings together metadata, arguments, examples, and execution logic in an organized structure. The progression through different configuration options is pedagogically sound and provides excellent guidance for users building CLIs of increasing complexity.
183-340: Advanced features (positional args, custom types, options) correctly demonstrated.All advanced examples—positional arguments, custom type parsing, kebab-case conversion, negatable options, and conflicting options—consistently use
define()and maintain proper patterns. The examples effectively teach both syntax and best practices.
| const command = define({ name: 'deploy', description: 'Deploy', run: vi.fn() }) | ||
| const ctx = await createCommandContext({ command }) | ||
| const extension = await plugin.extension.factory(ctx, command) | ||
| await plugin.extension.onFactory?.(ctx, command) |
There was a problem hiding this comment.
Fix incorrect API call in test example.
Line 471 calls plugin.extension.onFactory?.(), but based on the plugin structure defined in this guide, onExtension is a top-level callback on the plugin object, not a property of plugin.extension. The correct call should be plugin.onExtension?.().
- await plugin.extension.onFactory?.(ctx, command)
+ await plugin.onExtension?.(ctx, command)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| await plugin.extension.onFactory?.(ctx, command) | |
| await plugin.onExtension?.(ctx, command) |
🤖 Prompt for AI Agents
In packages/docs/src/guide/plugin/testing.md around line 471, the example
incorrectly calls plugin.extension.onFactory?.(ctx, command); change this to
call the top-level callback plugin.onExtension?.(ctx, command) instead (pass the
same ctx and command arguments) so the example matches the plugin structure
described in the guide.
2 participants
Description
use
definefunction for defining CLI command every time.this force llms to use
definefunctionLinked Issues
Additional context
Summary by CodeRabbit
Release Notes
New Features
definefunction for declaratively creating commands with improved type safety and structured syntax.Documentation
define()command definition pattern.✏️ Tip: You can customize this high-level summary in your review settings.