doc: plugin development guide #527
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds a v3-doc-plugin Git submodule, updates multiple submodule commit pointers, adds a comprehensive plugin development doc while removing a placeholder, and replaces StackBlitz SDK embedding with direct StackBlitz URLs plus removal of the StackBlitzEmbed component. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Repository UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
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 |
![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
🧹 Nitpick comments (2)
versioned_docs/version-3.x/recipe/plugin-dev.md (2)
44-44: Refine language: capitalize "Markdown" and replace "very simple".Two style improvements for clarity and consistency:
- "markdown" should be "Markdown" (proper noun referring to the markup language)
- Consider replacing "very simple" with a more expressive term per documentation style guidelines
🔎 View suggested refinement:
-...let's create a very simple CLI plugin that generates a markdown document listing... +...let's create a straightforward CLI plugin that generates a Markdown document listing...Alternatively, consider "minimal", "uncomplicated", or "basic" instead of "simple".
15-15: Optional refactoring: more expressive phrasing for "source tree".The phrase "create a folder in your source tree" could be more direct and accessible to different audiences.
🔎 View suggested refinement:
-...create a folder in your source tree with a `plugin.zmodel` file... +...create a folder in your project with a `plugin.zmodel` file...Or alternatively: "in your source code directory" or "in your application's source code".
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.gitmodules(1 hunks)code-repos/zenstackhq/v3-doc-plugin(1 hunks)versioned_docs/version-3.x/modeling/plugin.md(1 hunks)versioned_docs/version-3.x/orm/cli.md(1 hunks)versioned_docs/version-3.x/orm/plugins/index.md(1 hunks)versioned_docs/version-3.x/recipe/plugin-dev.md(1 hunks)versioned_docs/version-3.x/reference/plugin-dev.md(0 hunks)
💤 Files with no reviewable changes (1)
- versioned_docs/version-3.x/reference/plugin-dev.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/recipe/plugin-dev.md
[style] ~15-~15: Consider a more expressive alternative.
Context: ... extend the data modeling semantics. To do that, create a folder in your source tr...
(DO_ACHIEVE)
[style] ~44-~44: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...inue the previous example, let's create a very simple CLI plugin that generates a markdown do...
(EN_WEAK_ADJECTIVE)
[uncategorized] ~44-~44: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...very simple CLI plugin that generates a markdown document listing all model fields marke...
(MARKDOWN_NNP)
🔇 Additional comments (6)
code-repos/zenstackhq/v3-doc-plugin (1)
1-1: Submodule and documentation structure verified as properly configured.The v3-doc-plugin submodule is correctly added to
.gitmoduleswith the pathcode-repos/zenstackhq/v3-doc-pluginand URLhttps://github.com/zenstackhq/v3-doc-plugin. The commit reference (7740cdf8d9a38db9085ff55563cd0834a1b8621a) is valid and properly tracked by Git.Documentation files referenced in this change exist and are accessible:
versioned_docs/version-3.x/recipe/plugin-dev.mdis presentversioned_docs/version-3.x/recipe/directory existsversioned_docs/version-3.x/reference/directory existsThe submodule setup follows the established pattern of other v3-doc-* submodules in the repository. No issues identified.
.gitmodules (1)
31-33: ✓ Submodule addition looks good.The new submodule entry follows the established format and is placed appropriately at the end of the file.
versioned_docs/version-3.x/orm/plugins/index.md (1)
44-46: ✓ Clear cross-reference to comprehensive plugin development guide.The info admonition appropriately directs users to the new plugin development documentation for schema extension and runtime integration details.
versioned_docs/version-3.x/orm/cli.md (1)
20-22: ✓ CLI extensibility admonition placement and content are appropriate.Positioning the admonition after the core CLI explanation helps readers understand the extensibility option at the right moment in their reading flow.
versioned_docs/version-3.x/modeling/plugin.md (1)
51-53: ✓ Admonition effectively consolidates plugin behavior documentation.This update properly directs users to the comprehensive plugin development guide while removing fragmentation across multiple pages.
versioned_docs/version-3.x/recipe/plugin-dev.md (1)
1-107: ✓ Comprehensive plugin development guide with clear sections and examples.The documentation provides excellent coverage of:
- Schema language extension via plugin.zmodel
- CLI plugin generation with the SDK
- ORM runtime integration with concrete examples
The structure is logical, examples reference the new v3-doc-plugin repository appropriately, and the three main extension points are well-explained. The developer's transparency about the "vibe-coded" warning on line 100 is appreciated—just ensure that example is reviewed before considering it production-ready.
Please verify that the StackBlitzGithub components can resolve the v3-doc-plugin repository correctly (lines 23, 58, 103) and that the referenced file paths within that repository exist and are accessible.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
src/components/StackBlitzGithub.tsx (1)
22-24: Simplify redundant array check.Since
openFilesis always an array (initialized on line 17), theopenFiles &&check is redundant.🔎 Proposed simplification
- if (openFiles && openFiles.length > 0) { + if (openFiles.length > 0) { openFiles.forEach((f) => url.searchParams.append('file', f)); }versioned_docs/version-3.x/recipe/plugin-dev.md (1)
44-44: Consider capitalizing "Markdown" as a proper noun.The term "markdown" on this line should be capitalized as "Markdown" since it refers to the markup language by name.
🔎 Proposed fix
-The `zen` CLI is extensible via plugins and allows you to generate custom artifacts from the ZModel schema. To continue the previous example, let's create a very simple CLI plugin that generates a markdown document listing all model fields marked as passwords. +The `zen` CLI is extensible via plugins and allows you to generate custom artifacts from the ZModel schema. To continue the previous example, let's create a very simple CLI plugin that generates a Markdown document listing all model fields marked as passwords.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
package.jsonis excluded by!**/*.jsonpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml,!**/*.yaml
📒 Files selected for processing (14)
code-repos/zenstackhq/v3-doc-orm(1 hunks)code-repos/zenstackhq/v3-doc-orm-computed-fields(1 hunks)code-repos/zenstackhq/v3-doc-orm-policy(1 hunks)code-repos/zenstackhq/v3-doc-orm-polymorphism(1 hunks)code-repos/zenstackhq/v3-doc-orm-typed-json(1 hunks)code-repos/zenstackhq/v3-doc-orm-validation(1 hunks)code-repos/zenstackhq/v3-doc-plugin(1 hunks)code-repos/zenstackhq/v3-doc-quick-start(1 hunks)code-repos/zenstackhq/v3-doc-server-adapter(1 hunks)code-repos/zenstackhq/v3-doc-tanstack-query(1 hunks)src/components/StackBlitzEmbed.tsx(0 hunks)src/components/StackBlitzGithub.tsx(1 hunks)versioned_docs/version-3.x/modeling/plugin.md(2 hunks)versioned_docs/version-3.x/recipe/plugin-dev.md(1 hunks)
💤 Files with no reviewable changes (1)
- src/components/StackBlitzEmbed.tsx
✅ Files skipped from review due to trivial changes (10)
- code-repos/zenstackhq/v3-doc-orm-validation
- code-repos/zenstackhq/v3-doc-orm-polymorphism
- code-repos/zenstackhq/v3-doc-quick-start
- code-repos/zenstackhq/v3-doc-orm
- code-repos/zenstackhq/v3-doc-orm-typed-json
- code-repos/zenstackhq/v3-doc-server-adapter
- code-repos/zenstackhq/v3-doc-tanstack-query
- code-repos/zenstackhq/v3-doc-orm-policy
- code-repos/zenstackhq/v3-doc-orm-computed-fields
- code-repos/zenstackhq/v3-doc-plugin
🚧 Files skipped from review as they are similar to previous changes (1)
- versioned_docs/version-3.x/modeling/plugin.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/recipe/plugin-dev.md
[style] ~15-~15: Consider a more expressive alternative.
Context: ... extend the data modeling semantics. To do that, create a folder in your source tr...
(DO_ACHIEVE)
[style] ~44-~44: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...inue the previous example, let's create a very simple CLI plugin that generates a markdown do...
(EN_WEAK_ADJECTIVE)
[uncategorized] ~44-~44: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...very simple CLI plugin that generates a markdown document listing all model fields marke...
(MARKDOWN_NNP)
🔇 Additional comments (1)
versioned_docs/version-3.x/recipe/plugin-dev.md (1)
90-90: Past issue already resolved.The URL typo flagged in the previous review (gi.thub.com) has been corrected to github.com. The link now properly references the jiti repository.
Summary by CodeRabbit
Documentation
Chores
Behavior
✏️ Tip: You can customize this high-level summary in your review settings.