docs: migrate api references generation with ox-content tooling#569
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughMigrate docs generation from Typedoc to OxContent/VitePress: add a repo-level API generator and clean step, update workspace catalog and package scripts, wrap VitePress config for API extraction, and regenerate/move API docs across plugin packages. ChangesDocs generation migration
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer/CI
participant PackageScripts as package.json scripts
participant CleanScript as packages/docs/scripts/clean-api.ts
participant ApiScript as scripts/api-references.ts
participant OxContent as generateOxContentApiDocs
participant VitePress as VitePress build
Dev->>PackageScripts: pnpm workspace run build:docs
PackageScripts->>CleanScript: run clean-api.ts -> rm old generated api
PackageScripts->>ApiScript: run tsx scripts/api-references.ts
ApiScript->>OxContent: generateOxContentApiDocs(inputs, externalPackageSources)
OxContent->>PackageScripts: emit Markdown under package `docs`
PackageScripts->>VitePress: build site including generated API pages
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
✨ Finishing Touches🧪 Generate unit tests (beta)
|
Deploying gunshi with
|
| Latest commit: |
d3efa45
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://fa422177.gunshi.pages.dev |
| Branch Preview URL: | https://feat-vitepress-api-reference.gunshi.pages.dev |
@gunshi/bone
@gunshi/combinators
@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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 15
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/docs/src/api/combinators/type-aliases/CombinatorSchema.md (1)
1-20:⚠️ Potential issue | 🔴 CriticalFix docs API generation to run after plugin
.d.tsbuilds
packages/docsrunsbuild:vitepressat the end ofbuild(build:api && build:readme && build:vitepress), and VitePress API generation is configured inpackages/docs/src/.vitepress/config.tsto readpackages/plugin-i18n/lib/index.d.ts(viaexternalPackageSources). Since@gunshi/plugin-i18nonly provides that file after itsbuild(tsdown) runs, the docs build fails when the plugins haven’t been compiled yet.Ensure the monorepo build order (or workspace dependency graph) builds
@gunshi/plugin-i18n(and any other referenced external packages like@gunshi/plugin-renderer) before@gunshi/docssolib/index.d.tsexists whenwithOxContentApiDocsruns.🤖 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/docs/src/api/combinators/type-aliases/CombinatorSchema.md` around lines 1 - 20, The docs build fails because VitePress API generation (configured in packages/docs/src/.vitepress/config.ts via externalPackageSources and used by withOxContentApiDocs) reads plugin .d.ts files that only exist after those plugins are built; update the build ordering so `@gunshi/plugin-i18n` (and any other external packages like `@gunshi/plugin-renderer`) are built before `@gunshi/docs`: either add those plugins as workspace dependencies in packages/docs package.json (so install/build respects the graph) or change the root/monorepo build script (the sequence that runs build:api && build:readme && build:vitepress / build:vitepress) to invoke the plugins' build (tsdown) first, ensuring lib/index.d.ts exists when withOxContentApiDocs runs.Source: Pipeline failures
🧹 Nitpick comments (9)
scripts/api-references.ts (2)
21-57: ⚡ Quick winAdd error handling for the main API generation call.
The
generateOxContentApiDocscall has no try-catch wrapper. If generation fails (as shown in the pipeline failures), the script will crash without providing context-specific error information.🛡️ Proposed error handling
+try { const result = await generateOxContentApiDocs({ root: repoRoot, tsconfig: 'tsconfig.json', entryPoints: [{ path: path.join(packageDirectory, 'src/index.ts'), name: 'default' }], outDir, basePath: `/${packageDirectory}/docs`, extraction: { private: false, internal: false, externalDocs: true, typeParameters: true, externalPackageSources }, markdown: { groupBy: 'file', pathStrategy: 'typedoc', singleEntryRoot: 'flatten', renderStyle: 'markdown', linkStyle: 'markdown', indexFormat: 'table', parametersFormat: 'table', interfacePropertiesFormat: 'table', classPropertiesFormat: 'table', propertyMembersFormat: 'table', typeAliasPropertiesFormat: 'table', enumMembersFormat: 'table', typeDeclarationFormat: 'none', renderStats: false, renderGeneratedBy: false, groupOrder: ['Variables', 'Functions', 'Class'], sort: ['alphabetical'], sortEntryPoints: true }, nav: { enabled: false }, docsJson: false, escapeHeadingAngleBrackets: true }) console.log(`Generated ${result.generatedFiles.length} API reference files for ${packageJson.name}`) +} catch (error) { + console.error(`Failed to generate API docs for ${packageJson.name}:`, error) + console.error(`External package sources: ${JSON.stringify(externalPackageSources, null, 2)}`) + process.exit(1) +}🤖 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 `@scripts/api-references.ts` around lines 21 - 57, Wrap the generateOxContentApiDocs invocation in a try-catch block so failures surface with context: call generateOxContentApiDocs inside try, catch any error, log a clear message that includes the package/entry info (e.g., packageDirectory and outDir) and the caught error, and then exit non-zero or rethrow to fail the script; update the block around the generateOxContentApiDocs(...) call (the const result = await generateOxContentApiDocs(...)) to implement this error handling.
66-73: ⚡ Quick winConsider making the external package candidates list dynamic.
The hardcoded list of candidate packages will require manual updates whenever new packages are added to the monorepo. Consider scanning the
packages/directory dynamically or reading frompnpm-workspace.yamlto discover packages.📝 Example dynamic package discovery
async function resolveExternalPackageSources(currentPackageDirectory: string) { - const candidates = [ - { package: '`@gunshi/plugin`', directory: 'packages/plugin' }, - { package: '`@gunshi/shared`', directory: 'packages/shared' }, - { package: '`@gunshi/resources`', directory: 'packages/resources' }, - { package: '`@gunshi/plugin-global`', directory: 'packages/plugin-global' }, - { package: '`@gunshi/plugin-i18n`', directory: 'packages/plugin-i18n' }, - { package: '`@gunshi/plugin-renderer`', directory: 'packages/plugin-renderer' } - ] + // Discover all packages by reading packages/* directories + const packagesDir = path.join(repoRoot, 'packages') + const packageDirs = await fs.readdir(packagesDir, { withFileTypes: true }) + const candidates = await Promise.all( + packageDirs + .filter(dirent => dirent.isDirectory()) + .map(async (dirent) => { + const pkgJsonPath = path.join(packagesDir, dirent.name, 'package.json') + try { + const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf8')) + return { + package: pkgJson.name, + directory: `packages/${dirent.name}` + } + } catch { + return null + } + }) + ).then(results => results.filter(Boolean)) + const sources: Array<{ package: string; entry: string }> = []🤖 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 `@scripts/api-references.ts` around lines 66 - 73, Replace the hardcoded candidates array in scripts/api-references.ts with dynamic discovery: scan the monorepo (e.g., read the packages/ directory or parse pnpm-workspace.yaml) to enumerate package folders, filter for real packages (presence of package.json and valid name), and build the same shape [{ package: <pkgName>, directory: <relativePath> }]; update the variable named candidates to be produced from that discovery logic so new packages are picked up automatically by functions that consume candidates.packages/docs/src/api/combinators/interfaces/StringOptions.md (1)
18-25: ⚡ Quick winConsider documenting inherited properties for better discoverability.
Similar to
NumberOptions, this table only shows the properties specific toStringOptions(maxLength,minLength,pattern) but omits inherited properties fromBaseOptions. Consider adding a note directing readers to the base interface for complete property documentation.🤖 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/docs/src/api/combinators/interfaces/StringOptions.md` around lines 18 - 25, The StringOptions docs currently list only string-specific fields (maxLength, minLength, pattern) and omit inherited fields from BaseOptions; update the StringOptions documentation to either (a) add a short note pointing readers to BaseOptions for inherited properties (e.g., "See BaseOptions for inherited properties") or (b) expand the properties table to include the inherited BaseOptions fields, referencing the BaseOptions interface; ensure you mention the related symbols StringOptions and BaseOptions (and mirror the approach used in NumberOptions) so readers can discover all available options.packages/docs/src/api/combinators/interfaces/NumberOptions.md (1)
18-24: ⚡ Quick winConsider documenting inherited properties for better discoverability.
The properties table only shows
maxandmin, butNumberOptionsextendsBaseOptionsand inherits properties likedescription,required, andshort. While users can navigate toBaseOptionsto find these, omitting them here reduces the self-contained nature of the documentation and may force readers to jump between pages.If this is intentional to follow DRY principles, consider adding a note like "See BaseOptions for additional inherited properties."
🤖 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/docs/src/api/combinators/interfaces/NumberOptions.md` around lines 18 - 24, The NumberOptions docs currently only list `max` and `min` but `NumberOptions` extends `BaseOptions` (which provides `description`, `required`, `short`, etc.); update the documentation for `NumberOptions` to either (a) include the inherited properties in the properties table (add rows for `description`, `required`, `short`, etc.) or (b) add a brief sentence under the table like "See BaseOptions for inherited properties" with a link to BaseOptions (e.g., BaseOptions.md) so readers can discover those fields without having to search; modify the Markdown around the properties table in NumberOptions to implement one of these two options and ensure the link text references `BaseOptions` or `BaseOptions.md` for clarity.packages/plugin-completion/docs/default/functions/default.md (1)
3-3: ⚡ Quick winEnhance the function description.
The description "completion plugin" is too terse for the main plugin entrypoint. Consider adding a more comprehensive description that explains what the completion plugin does and its primary purpose (e.g., "Creates a completion plugin that provides shell-style tab completion for command arguments").
🤖 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/plugin-completion/docs/default/functions/default.md` at line 3, The current one-line description "completion plugin" for the main plugin entrypoint (the default function / "completion plugin" entry) is too terse; update the description in packages/plugin-completion/docs/default/functions/default.md to a fuller sentence that explains what the plugin does and its primary purpose (for example: "Creates a completion plugin that provides shell-style tab completion for command arguments, integrates with CLI argument parsing, and supports customizable completion sources and async lookups"). Ensure the new description replaces the existing "completion plugin" text and mentions key behaviors (tab completion, argument suggestions, integration points) so users immediately understand the plugin's intent.packages/plugin-completion/docs/default/interfaces/CompletionConfig.md (1)
20-22: ⚡ Quick winAdd description for the
paramsparameter.The
paramsparameter in the handler Parameters table lacks a description. Consider adding a brief explanation such as "Parameters passed to the completion handler" for completeness.🤖 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/plugin-completion/docs/default/interfaces/CompletionConfig.md` around lines 20 - 22, The table row for `params` in the CompletionConfig docs is missing a description; update the `CompletionConfig` interface documentation to add a concise description for the `params` entry (e.g., "Parameters passed to the completion handler") referencing the `params` field and the `CompletionParams` type so readers know these are the parameters supplied to the completion handler.packages/plugin-dryrun/docs/default/type-aliases/DryRunWrapResult.md (1)
11-16: ⚡ Quick winAdd descriptions for type parameters.
The Type Parameters table lists
AandRbut provides no descriptions. Users need to understand what these generic parameters represent (e.g.,Aappears to be the argument tuple type,Rthe result type).📝 Suggested improvement
## Type Parameters -| Name | -| --- | -| `A` *extends* `unknown[]` | -| `R` | +| Name | Description | +| --- | --- | +| `A` *extends* `unknown[]` | The argument types tuple for the resolve function | +| `R` | The result type returned by the dry-run operation |🤖 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/plugin-dryrun/docs/default/type-aliases/DryRunWrapResult.md` around lines 11 - 16, The Type Parameters table for the DryRunWrapResult type is missing descriptions; update the table under DryRunWrapResult to explain that `A` is the tuple type of the wrapped function's arguments (e.g., the parameter list) and `R` is the return type (the wrapped function's result), so change the rows for `A` and `R` to include those brief descriptions so users understand what each generic represents.packages/plugin-i18n/docs/default/type-aliases/TranslationAdapterFactory.md (1)
15-15: ⚡ Quick winAdd a description for the
optionsparameter.The
optionsparameter is missing a description in the documentation table. Consider adding a brief description such as "Options for configuring the translation adapter factory."🤖 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/plugin-i18n/docs/default/type-aliases/TranslationAdapterFactory.md` at line 15, Update the docs row for the `options` parameter in TranslationAdapterFactory.md to include a short descriptive text; locate the table entry that currently lists `options` with type `TranslationAdapterFactoryOptions` and replace the empty description cell with something like "Options for configuring the translation adapter factory (see TranslationAdapterFactoryOptions for fields)" so readers understand the purpose and can navigate to the interface for details.packages/plugin-renderer/docs/default/functions/renderValidationErrors.md (1)
21-21: 💤 Low valueConsider clarifying that the
_ctxparameter is currently unused.The parameter is named with an underscore prefix (
_ctx), which is a TypeScript convention indicating it's intentionally unused. The documentation describes it generically as "A command context" without noting it's not currently utilized. For API clarity, consider either:
- Adding a note that this parameter is reserved for future use, or
- Updating the description to indicate it's currently unused
This would help API consumers understand whether they need to pass a meaningful context or if it's purely a placeholder for interface consistency.
🤖 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/plugin-renderer/docs/default/functions/renderValidationErrors.md` at line 21, Update the documentation row for the `_ctx` parameter in the renderValidationErrors function so it explicitly states that `_ctx: CommandContext<G>` is currently unused (or reserved for future use) rather than just "A command context"; mention the underscore denotes an intentionally unused parameter so callers know they don't need to supply meaningful data and that it exists only for interface/forward-compatibility.
🤖 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.
Inline comments:
In `@packages/docs/src/.vitepress/config.ts`:
- Around line 57-71: The config currently unconditionally adds entries to
externalPackageSources (the objects referencing '`@gunshi/plugin-renderer`' and
'`@gunshi/plugin-i18n`' via path.resolve(repoRoot,
'packages/plugin-*/lib/index.d.ts')), which can point to missing .d.ts files and
break the docs build; update the code that builds externalPackageSources in
packages/docs/src/.vitepress/config.ts to check for the presence of each target
declaration file (use fs.existsSync or fs.access) before pushing the entry,
mirroring the logic in /scripts/api-references.ts, so only packages whose
lib/index.d.ts actually exist are included (keep existing entries for
args-tokens using argsTokensDir unchanged).
In `@packages/docs/src/api/combinators/functions/integer.md`:
- Line 1: Docs build fails because `@gunshi/plugin-i18n` and
`@gunshi/plugin-renderer` type declarations (lib/index.d.ts) may not exist when
`@gunshi/docs` reads them via withOxContentApiDocs in
packages/docs/src/.vitepress/config.ts; fix by ensuring those packages are built
before docs: add a prebuild step or CI ordering so that the build for
`@gunshi/plugin-i18n` and `@gunshi/plugin-renderer` runs prior to running pnpm -F
`@gunshi/docs` build (or pnpm run build:docs), e.g., add a prebuild script on
`@gunshi/docs` that runs pnpm -F `@gunshi/plugin-i18n` -F `@gunshi/plugin-renderer`
build or adjust the CI job dependency ordering to build those packages first.
In `@packages/docs/src/api/combinators/functions/merge.md`:
- Line 12: The documentation in
packages/docs/src/api/combinators/functions/merge.md contains invalid
cross-module links to the Args interface (/api/default/interfaces/Args.md);
locate the actual Args interface doc in the repo and replace every broken link
in merge.md (all occurrences referencing Args) with the correct
relative/permalink path so the cross-reference resolves, keeping the link text
"Args" unchanged and ensuring consistency across the other Args references in
the file.
In `@packages/docs/src/api/combinators/functions/positional.md`:
- Line 64: The markdown in positional.md references
[`ArgSchema`](/api/default/interfaces/ArgSchema.md) which points to a
non-existent doc; open positional.md and either update the link target for the
[`ArgSchema`] reference to the actual location of the ArgSchema documentation
(keeping the link text and also verifying `ArgSchemaPositionalType` context
remains correct) or add the missing ArgSchema doc page so the existing link
resolves; ensure the updated link URL is consistent with the repo's API doc
structure and that the anchor/name matches the `ArgSchema` symbol.
In `@packages/docs/src/guide/plugin/guidelines.md`:
- Around line 919-924: The example package.json uses a non-portable shell
command for cleanup; update the "docs:clean" script reference (the scripts
object, "docs:clean") to a cross-platform approach (e.g., use a Node-based tool
such as rimraf or a small Node script) and mention adding the chosen tool to
devDependencies or using npx so the snippet works on Windows and POSIX shells
when copy-pasted from the guide.
In `@packages/plugin-completion/docs/default/type-aliases/CompletionHandler.md`:
- Line 19: Update the docs entry for Completion[] in CompletionHandler.md to
make the external source explicit: change the text to either link `Completion`
to `@bomb.sh/tab` or add a parenthetical like "(Completion from `@bomb.sh/tab`)";
you'll find the canonical import referenced in the codebase in
packages/plugin-completion/src/types.ts and
packages/plugin-completion/src/index.ts where `Completion` is re-exported—use
that symbol (`Completion`) as the target of the link or the name in the
parenthetical so the doc matches other type references.
In `@packages/plugin-dryrun/docs/default/functions/default.md`:
- Around line 1-9: Update the documentation title to match the exported function
name: change the header "Function: default()" to "Function: dryrun()" so it
aligns with the signature `export function dryrun(options: DryRunPluginOptions =
{}): PluginWithExtension<DryRunExtension>` and related symbols (dryrun,
DryRunPluginOptions, DryRunExtension, PluginWithExtension) to avoid confusion
about the default export name.
In `@packages/plugin-global/docs/default/functions/default.md`:
- Around line 1-8: The title says "Function: default()" but the documented
signature is `export function global():
PluginWithExtension<GlobalExtension>`—update the doc so names match: either
change the title to "Function: global()" if `global()` is the primary API, or
change the title to "Function: default" and add a one-line note stating that the
default export re-exports the `global()` function; ensure the signature remains
`export function global(): PluginWithExtension<GlobalExtension>` and mention the
export relationship to avoid confusion.
In `@packages/plugin-global/docs/index.md`:
- Around line 30-48: Update the broken absolute links in the plugin-global docs
so they resolve when published: replace occurrences of absolute paths like
/packages/plugin-global/docs/default/variables/pluginId.md and similar links for
default/functions/default.md, default/interfaces/GlobalExtension.md and
default/type-aliases/PluginId.md with relative paths (for example
./default/variables/pluginId.md, ./default/functions/default.md,
./default/interfaces/GlobalExtension.md, ./default/type-aliases/PluginId.md)
inside the markdown files in packages/plugin-global/docs so the links work
without changing the main site base or build inputs.
In `@packages/plugin-i18n/docs/default/functions/withI18nResource.md`:
- Line 45: The example has a variable name mismatch: the command is defined as
myCommand but the call uses basicCommand; update the invocation of
withI18nResource to use the actual defined symbol (myCommand) or rename the
definition to match (basicCommand) so both names are consistent; specifically
modify the line using withI18nResource(...) to reference myCommand (or rename
myCommand to basicCommand) and ensure withI18nResource and the command variable
names match throughout the example.
In `@packages/plugin-i18n/docs/default/interfaces/TranslationAdapter.md`:
- Line 34: Change the misspelling "Unicord" to "Unicode" in the
TranslationAdapter docs where the `locale` table entry explains the locale
identifier; update the three occurrences of "Unicord locale ID" (the `locale`
parameter description and the two other identical entries in this markdown) to
read "Unicode locale ID (BCP 47)" so all descriptions correctly reference
Unicode language tags.
- Line 5: Update the description sentence "This adapter is used to custom
message formatter like [Intlify message format]..., [`Intl.MessageFormat`
(MF2)]..., and etc." to correct grammar and style: change it to "This adapter is
used to customize message formatters, such as Intlify message format and
Intl.MessageFormat (MF2), etc." — ensure the phrase referencing the adapter and
the formatter names (e.g., "This adapter", "Intlify message format",
"Intl.MessageFormat (MF2)") is preserved while replacing "used to custom message
formatter" with "used to customize message formatters" (or "used for custom
message formatters") and remove the redundant "and" before "etc."
In `@packages/plugin-i18n/docs/default/type-aliases/CommandResource.md`:
- Line 15: The doc line for the type parameter `G` is incorrect: update the
description to match the signature `G extends GunshiParamsConstraint =
DefaultGunshiParams` in CommandResource.md by changing the phrase "Type
parameter extending `GunshiParams`" to "Type parameter extending
`GunshiParamsConstraint`" (and keep the default `= DefaultGunshiParams`),
ensuring the `G` entry and its description reference `GunshiParamsConstraint`,
`G`, and `DefaultGunshiParams` consistently.
In `@packages/plugin-i18n/docs/default/type-aliases/CommandResourceFetcher.md`:
- Line 15: Update the type parameter description for G to match the actual
signature: change the phrase "Type parameter extending `GunshiParams`" to
reference `GunshiParamsConstraint` (e.g., "Type parameter extending
`GunshiParamsConstraint`") so the doc for the type parameter `G` aligns with the
signature `G extends GunshiParamsConstraint`; locate the `G` type parameter line
in the CommandResourceFetcher type alias docs and replace the incorrect
constraint name accordingly.
In `@scripts/api-references.ts`:
- Line 17: The docs API generator currently fails when dependent packages (e.g.,
`@gunshi/plugin-i18n`) haven't produced their lib/index.d.ts because
scripts/api-references.ts only optionally wires externalPackageSources; update
resolveExternalPackageSources and the generation call to (1) detect missing
external package outputs and either skip following external type references or
return a defensive empty/partial externalPackageSources so
extraction.externalPackageSources is never left pointing to non-existent files,
and (2) replace the brittle hardcoded candidate list in
resolveExternalPackageSources with discovery logic (e.g., scan
workspace/package.json or pnpm-workspace) so new packages aren’t missed;
additionally, ensure CI/build steps run pnpm -r build (or at least build
referenced packages) before invoking the docs build to guarantee lib/index.d.ts
exist.
---
Outside diff comments:
In `@packages/docs/src/api/combinators/type-aliases/CombinatorSchema.md`:
- Around line 1-20: The docs build fails because VitePress API generation
(configured in packages/docs/src/.vitepress/config.ts via externalPackageSources
and used by withOxContentApiDocs) reads plugin .d.ts files that only exist after
those plugins are built; update the build ordering so `@gunshi/plugin-i18n` (and
any other external packages like `@gunshi/plugin-renderer`) are built before
`@gunshi/docs`: either add those plugins as workspace dependencies in
packages/docs package.json (so install/build respects the graph) or change the
root/monorepo build script (the sequence that runs build:api && build:readme &&
build:vitepress / build:vitepress) to invoke the plugins' build (tsdown) first,
ensuring lib/index.d.ts exists when withOxContentApiDocs runs.
---
Nitpick comments:
In `@packages/docs/src/api/combinators/interfaces/NumberOptions.md`:
- Around line 18-24: The NumberOptions docs currently only list `max` and `min`
but `NumberOptions` extends `BaseOptions` (which provides `description`,
`required`, `short`, etc.); update the documentation for `NumberOptions` to
either (a) include the inherited properties in the properties table (add rows
for `description`, `required`, `short`, etc.) or (b) add a brief sentence under
the table like "See BaseOptions for inherited properties" with a link to
BaseOptions (e.g., BaseOptions.md) so readers can discover those fields without
having to search; modify the Markdown around the properties table in
NumberOptions to implement one of these two options and ensure the link text
references `BaseOptions` or `BaseOptions.md` for clarity.
In `@packages/docs/src/api/combinators/interfaces/StringOptions.md`:
- Around line 18-25: The StringOptions docs currently list only string-specific
fields (maxLength, minLength, pattern) and omit inherited fields from
BaseOptions; update the StringOptions documentation to either (a) add a short
note pointing readers to BaseOptions for inherited properties (e.g., "See
BaseOptions for inherited properties") or (b) expand the properties table to
include the inherited BaseOptions fields, referencing the BaseOptions interface;
ensure you mention the related symbols StringOptions and BaseOptions (and mirror
the approach used in NumberOptions) so readers can discover all available
options.
In `@packages/plugin-completion/docs/default/functions/default.md`:
- Line 3: The current one-line description "completion plugin" for the main
plugin entrypoint (the default function / "completion plugin" entry) is too
terse; update the description in
packages/plugin-completion/docs/default/functions/default.md to a fuller
sentence that explains what the plugin does and its primary purpose (for
example: "Creates a completion plugin that provides shell-style tab completion
for command arguments, integrates with CLI argument parsing, and supports
customizable completion sources and async lookups"). Ensure the new description
replaces the existing "completion plugin" text and mentions key behaviors (tab
completion, argument suggestions, integration points) so users immediately
understand the plugin's intent.
In `@packages/plugin-completion/docs/default/interfaces/CompletionConfig.md`:
- Around line 20-22: The table row for `params` in the CompletionConfig docs is
missing a description; update the `CompletionConfig` interface documentation to
add a concise description for the `params` entry (e.g., "Parameters passed to
the completion handler") referencing the `params` field and the
`CompletionParams` type so readers know these are the parameters supplied to the
completion handler.
In `@packages/plugin-dryrun/docs/default/type-aliases/DryRunWrapResult.md`:
- Around line 11-16: The Type Parameters table for the DryRunWrapResult type is
missing descriptions; update the table under DryRunWrapResult to explain that
`A` is the tuple type of the wrapped function's arguments (e.g., the parameter
list) and `R` is the return type (the wrapped function's result), so change the
rows for `A` and `R` to include those brief descriptions so users understand
what each generic represents.
In `@packages/plugin-i18n/docs/default/type-aliases/TranslationAdapterFactory.md`:
- Line 15: Update the docs row for the `options` parameter in
TranslationAdapterFactory.md to include a short descriptive text; locate the
table entry that currently lists `options` with type
`TranslationAdapterFactoryOptions` and replace the empty description cell with
something like "Options for configuring the translation adapter factory (see
TranslationAdapterFactoryOptions for fields)" so readers understand the purpose
and can navigate to the interface for details.
In `@packages/plugin-renderer/docs/default/functions/renderValidationErrors.md`:
- Line 21: Update the documentation row for the `_ctx` parameter in the
renderValidationErrors function so it explicitly states that `_ctx:
CommandContext<G>` is currently unused (or reserved for future use) rather than
just "A command context"; mention the underscore denotes an intentionally unused
parameter so callers know they don't need to supply meaningful data and that it
exists only for interface/forward-compatibility.
In `@scripts/api-references.ts`:
- Around line 21-57: Wrap the generateOxContentApiDocs invocation in a try-catch
block so failures surface with context: call generateOxContentApiDocs inside
try, catch any error, log a clear message that includes the package/entry info
(e.g., packageDirectory and outDir) and the caught error, and then exit non-zero
or rethrow to fail the script; update the block around the
generateOxContentApiDocs(...) call (the const result = await
generateOxContentApiDocs(...)) to implement this error handling.
- Around line 66-73: Replace the hardcoded candidates array in
scripts/api-references.ts with dynamic discovery: scan the monorepo (e.g., read
the packages/ directory or parse pnpm-workspace.yaml) to enumerate package
folders, filter for real packages (presence of package.json and valid name), and
build the same shape [{ package: <pkgName>, directory: <relativePath> }]; update
the variable named candidates to be produced from that discovery logic so new
packages are picked up automatically by functions that consume candidates.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: df760598-47c6-4681-b087-bd83a59109f6
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (150)
package.jsonpackages/docs/.bench/docs-typedoc-vs-ox.jsonpackages/docs/.bench/docs-typedoc-vs-ox.mdpackages/docs/package.jsonpackages/docs/scripts/clean-api.tspackages/docs/src/.vitepress/config.tspackages/docs/src/.vitepress/contents.tspackages/docs/src/api/combinators/functions/args.mdpackages/docs/src/api/combinators/functions/boolean.mdpackages/docs/src/api/combinators/functions/choice.mdpackages/docs/src/api/combinators/functions/combinator.mdpackages/docs/src/api/combinators/functions/describe.mdpackages/docs/src/api/combinators/functions/extend.mdpackages/docs/src/api/combinators/functions/float.mdpackages/docs/src/api/combinators/functions/integer.mdpackages/docs/src/api/combinators/functions/map.mdpackages/docs/src/api/combinators/functions/merge.mdpackages/docs/src/api/combinators/functions/multiple.mdpackages/docs/src/api/combinators/functions/number.mdpackages/docs/src/api/combinators/functions/positional.mdpackages/docs/src/api/combinators/functions/required.mdpackages/docs/src/api/combinators/functions/short.mdpackages/docs/src/api/combinators/functions/string.mdpackages/docs/src/api/combinators/functions/unrequired.mdpackages/docs/src/api/combinators/functions/withDefault.mdpackages/docs/src/api/combinators/index.mdpackages/docs/src/api/combinators/interfaces/BaseOptions.mdpackages/docs/src/api/combinators/interfaces/BooleanOptions.mdpackages/docs/src/api/combinators/interfaces/CombinatorOptions.mdpackages/docs/src/api/combinators/interfaces/FloatOptions.mdpackages/docs/src/api/combinators/interfaces/IntegerOptions.mdpackages/docs/src/api/combinators/interfaces/NumberOptions.mdpackages/docs/src/api/combinators/interfaces/StringOptions.mdpackages/docs/src/api/combinators/type-aliases/Combinator.mdpackages/docs/src/api/combinators/type-aliases/CombinatorSchema.mdpackages/docs/src/api/docs.jsonpackages/docs/src/api/typedoc-sidebar.jsonpackages/docs/src/guide/plugin/guidelines.mdpackages/docs/typedoc.config.mjspackages/plugin-completion/docs/default/functions/default.mdpackages/plugin-completion/docs/default/interfaces/CompletionConfig.mdpackages/plugin-completion/docs/default/interfaces/CompletionExtension.mdpackages/plugin-completion/docs/default/interfaces/CompletionOptions.mdpackages/plugin-completion/docs/default/interfaces/CompletionParams.mdpackages/plugin-completion/docs/default/type-aliases/CompletionHandler.mdpackages/plugin-completion/docs/default/type-aliases/PluginId.mdpackages/plugin-completion/docs/default/variables/pluginId.mdpackages/plugin-completion/docs/functions/default.mdpackages/plugin-completion/docs/index.mdpackages/plugin-completion/docs/interfaces/CompletionConfig.mdpackages/plugin-completion/docs/interfaces/CompletionOptions.mdpackages/plugin-completion/docs/interfaces/CompletionParams.mdpackages/plugin-completion/docs/type-aliases/CompletionHandler.mdpackages/plugin-completion/docs/type-aliases/PluginId.mdpackages/plugin-completion/docs/variables/pluginId.mdpackages/plugin-completion/package.jsonpackages/plugin-completion/typedoc.config.mjspackages/plugin-dryrun/docs/default/functions/default.mdpackages/plugin-dryrun/docs/default/interfaces/DryRunExtension.mdpackages/plugin-dryrun/docs/default/interfaces/DryRunMessage.mdpackages/plugin-dryrun/docs/default/interfaces/DryRunPluginOptions.mdpackages/plugin-dryrun/docs/default/type-aliases/DryRunOptionsArg.mdpackages/plugin-dryrun/docs/default/type-aliases/DryRunRunResult.mdpackages/plugin-dryrun/docs/default/type-aliases/DryRunWrapResult.mdpackages/plugin-dryrun/docs/default/type-aliases/PluginId.mdpackages/plugin-dryrun/docs/default/variables/pluginId.mdpackages/plugin-dryrun/docs/functions/default.mdpackages/plugin-dryrun/docs/index.mdpackages/plugin-dryrun/docs/interfaces/DryRunExtension.mdpackages/plugin-dryrun/docs/interfaces/DryRunMessage.mdpackages/plugin-dryrun/docs/interfaces/DryRunPluginOptions.mdpackages/plugin-dryrun/docs/type-aliases/DryRunOptionsArg.mdpackages/plugin-dryrun/docs/type-aliases/DryRunRunResult.mdpackages/plugin-dryrun/docs/type-aliases/DryRunWrapResult.mdpackages/plugin-dryrun/docs/type-aliases/PluginId.mdpackages/plugin-dryrun/docs/variables/pluginId.mdpackages/plugin-dryrun/package.jsonpackages/plugin-dryrun/typedoc.config.mjspackages/plugin-global/docs/default/functions/default.mdpackages/plugin-global/docs/default/interfaces/GlobalExtension.mdpackages/plugin-global/docs/default/type-aliases/PluginId.mdpackages/plugin-global/docs/default/variables/pluginId.mdpackages/plugin-global/docs/functions/default.mdpackages/plugin-global/docs/index.mdpackages/plugin-global/docs/interfaces/GlobalExtension.mdpackages/plugin-global/docs/type-aliases/PluginId.mdpackages/plugin-global/docs/variables/pluginId.mdpackages/plugin-global/package.jsonpackages/plugin-global/typedoc.config.mjspackages/plugin-i18n/docs/classes/DefaultTranslation.mdpackages/plugin-i18n/docs/default/classes/DefaultTranslation.mdpackages/plugin-i18n/docs/default/functions/createTranslationAdapter.mdpackages/plugin-i18n/docs/default/functions/default.mdpackages/plugin-i18n/docs/default/functions/defineI18n.mdpackages/plugin-i18n/docs/default/functions/defineI18nWithTypes.mdpackages/plugin-i18n/docs/default/functions/resolveArgKey.mdpackages/plugin-i18n/docs/default/functions/resolveBuiltInKey.mdpackages/plugin-i18n/docs/default/functions/resolveKey.mdpackages/plugin-i18n/docs/default/functions/withI18nResource.mdpackages/plugin-i18n/docs/default/interfaces/I18nCommand.mdpackages/plugin-i18n/docs/default/interfaces/I18nExtension.mdpackages/plugin-i18n/docs/default/interfaces/I18nPluginOptions.mdpackages/plugin-i18n/docs/default/interfaces/TranslationAdapter.mdpackages/plugin-i18n/docs/default/interfaces/TranslationAdapterFactoryOptions.mdpackages/plugin-i18n/docs/default/type-aliases/CommandResource.mdpackages/plugin-i18n/docs/default/type-aliases/CommandResourceFetcher.mdpackages/plugin-i18n/docs/default/type-aliases/PluginId.mdpackages/plugin-i18n/docs/default/type-aliases/TranslationAdapterFactory.mdpackages/plugin-i18n/docs/default/variables/DEFAULT_LOCALE.mdpackages/plugin-i18n/docs/default/variables/pluginId.mdpackages/plugin-i18n/docs/functions/createTranslationAdapter.mdpackages/plugin-i18n/docs/functions/default.mdpackages/plugin-i18n/docs/functions/defineI18n.mdpackages/plugin-i18n/docs/functions/resolveArgKey.mdpackages/plugin-i18n/docs/functions/resolveBuiltInKey.mdpackages/plugin-i18n/docs/functions/resolveKey.mdpackages/plugin-i18n/docs/functions/withI18nResource.mdpackages/plugin-i18n/docs/index.mdpackages/plugin-i18n/docs/interfaces/I18nCommand.mdpackages/plugin-i18n/docs/interfaces/I18nExtension.mdpackages/plugin-i18n/docs/interfaces/I18nPluginOptions.mdpackages/plugin-i18n/docs/interfaces/TranslationAdapter.mdpackages/plugin-i18n/docs/interfaces/TranslationAdapterFactoryOptions.mdpackages/plugin-i18n/docs/type-aliases/CommandResource.mdpackages/plugin-i18n/docs/type-aliases/CommandResourceFetcher.mdpackages/plugin-i18n/docs/type-aliases/PluginId.mdpackages/plugin-i18n/docs/type-aliases/TranslationAdapterFactory.mdpackages/plugin-i18n/docs/variables/DEFAULT_LOCALE.mdpackages/plugin-i18n/docs/variables/pluginId.mdpackages/plugin-i18n/package.jsonpackages/plugin-i18n/typedoc.config.mjspackages/plugin-renderer/docs/default/functions/default.mdpackages/plugin-renderer/docs/default/functions/renderHeader.mdpackages/plugin-renderer/docs/default/functions/renderUsage.mdpackages/plugin-renderer/docs/default/functions/renderValidationErrors.mdpackages/plugin-renderer/docs/default/interfaces/UsageRendererExtension.mdpackages/plugin-renderer/docs/default/type-aliases/PluginId.mdpackages/plugin-renderer/docs/default/variables/pluginId.mdpackages/plugin-renderer/docs/functions/default.mdpackages/plugin-renderer/docs/functions/renderHeader.mdpackages/plugin-renderer/docs/functions/renderUsage.mdpackages/plugin-renderer/docs/functions/renderValidationErrors.mdpackages/plugin-renderer/docs/index.mdpackages/plugin-renderer/docs/interfaces/UsageRendererExtension.mdpackages/plugin-renderer/docs/type-aliases/PluginId.mdpackages/plugin-renderer/docs/variables/pluginId.mdpackages/plugin-renderer/package.jsonpackages/plugin-renderer/typedoc.config.mjspnpm-workspace.yamlscripts/api-references.ts
💤 Files with no reviewable changes (53)
- packages/plugin-i18n/docs/type-aliases/TranslationAdapterFactory.md
- packages/plugin-dryrun/docs/type-aliases/DryRunWrapResult.md
- packages/plugin-dryrun/docs/interfaces/DryRunMessage.md
- packages/plugin-i18n/docs/variables/pluginId.md
- packages/plugin-global/docs/functions/default.md
- packages/plugin-completion/docs/variables/pluginId.md
- packages/plugin-i18n/docs/interfaces/I18nExtension.md
- packages/plugin-dryrun/typedoc.config.mjs
- packages/plugin-i18n/docs/variables/DEFAULT_LOCALE.md
- packages/plugin-dryrun/docs/interfaces/DryRunPluginOptions.md
- packages/plugin-global/docs/variables/pluginId.md
- packages/plugin-i18n/docs/interfaces/I18nCommand.md
- packages/docs/typedoc.config.mjs
- packages/plugin-i18n/docs/functions/resolveArgKey.md
- packages/plugin-dryrun/docs/interfaces/DryRunExtension.md
- packages/plugin-i18n/docs/interfaces/TranslationAdapterFactoryOptions.md
- packages/plugin-dryrun/docs/type-aliases/PluginId.md
- packages/plugin-renderer/docs/functions/renderUsage.md
- packages/plugin-i18n/docs/interfaces/TranslationAdapter.md
- packages/plugin-i18n/docs/functions/defineI18n.md
- packages/plugin-renderer/docs/functions/renderHeader.md
- packages/plugin-completion/docs/functions/default.md
- packages/plugin-i18n/docs/type-aliases/PluginId.md
- packages/plugin-i18n/docs/functions/createTranslationAdapter.md
- packages/plugin-i18n/docs/functions/resolveBuiltInKey.md
- packages/plugin-global/docs/interfaces/GlobalExtension.md
- packages/plugin-i18n/docs/functions/resolveKey.md
- packages/plugin-global/typedoc.config.mjs
- packages/plugin-i18n/docs/type-aliases/CommandResource.md
- packages/plugin-i18n/docs/functions/default.md
- packages/plugin-renderer/docs/variables/pluginId.md
- packages/plugin-renderer/docs/type-aliases/PluginId.md
- packages/plugin-completion/docs/interfaces/CompletionConfig.md
- packages/plugin-i18n/docs/functions/withI18nResource.md
- packages/plugin-dryrun/docs/variables/pluginId.md
- packages/plugin-i18n/docs/classes/DefaultTranslation.md
- packages/plugin-global/docs/type-aliases/PluginId.md
- packages/plugin-i18n/docs/interfaces/I18nPluginOptions.md
- packages/plugin-i18n/docs/type-aliases/CommandResourceFetcher.md
- packages/plugin-completion/typedoc.config.mjs
- packages/plugin-i18n/typedoc.config.mjs
- packages/plugin-renderer/typedoc.config.mjs
- packages/docs/src/api/typedoc-sidebar.json
- packages/plugin-completion/docs/interfaces/CompletionOptions.md
- packages/plugin-renderer/docs/interfaces/UsageRendererExtension.md
- packages/plugin-completion/docs/type-aliases/PluginId.md
- packages/plugin-dryrun/docs/type-aliases/DryRunRunResult.md
- packages/plugin-completion/docs/interfaces/CompletionParams.md
- packages/plugin-dryrun/docs/functions/default.md
- packages/plugin-renderer/docs/functions/default.md
- packages/plugin-dryrun/docs/type-aliases/DryRunOptionsArg.md
- packages/plugin-renderer/docs/functions/renderValidationErrors.md
- packages/plugin-completion/docs/type-aliases/CompletionHandler.md
Comment on lines
+57
to
+71
| externalPackageSources: [ | ||
| { package: 'args-tokens', entry: path.join(argsTokensDir, 'lib/index.d.ts') }, | ||
| { | ||
| package: 'args-tokens/combinators', | ||
| entry: path.join(argsTokensDir, 'lib/combinators.d.ts') | ||
| }, | ||
| { package: 'args-tokens/utils', entry: path.join(argsTokensDir, 'lib/utils.d.ts') }, | ||
| { | ||
| package: '@gunshi/plugin-renderer', | ||
| entry: path.resolve(repoRoot, 'packages/plugin-renderer/lib/index.d.ts') | ||
| }, | ||
| { | ||
| package: '@gunshi/plugin-i18n', | ||
| entry: path.resolve(repoRoot, 'packages/plugin-i18n/lib/index.d.ts') | ||
| } |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Configured lib declaration paths:"
rg -n "packages/plugin-(renderer|i18n)/lib/index\\.d\\.ts" packages/docs/src/.vitepress/config.ts
echo
echo "Existence check for configured and fallback files:"
for f in \
packages/plugin-renderer/lib/index.d.ts \
packages/plugin-i18n/lib/index.d.ts \
packages/plugin-renderer/src/index.ts \
packages/plugin-i18n/src/index.ts
do
if [ -f "$f" ]; then
echo "FOUND $f"
else
echo "MISSING $f"
fi
doneRepository: kazupon/gunshi
Length of output: 500
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Configured lib declaration paths:"
rg -n "packages/plugin-(renderer|i18n)/lib/index\\.d\\.ts" packages/docs/src/.vitepress/config.ts
echo
echo "Existence check for configured and fallback files:"
for f in \
packages/plugin-renderer/lib/index.d.ts \
packages/plugin-i18n/lib/index.d.ts \
packages/plugin-renderer/src/index.ts \
packages/plugin-i18n/src/index.ts
do
if [ -f "$f" ]; then
echo "FOUND $f"
else
echo "MISSING $f"
fi
doneRepository: kazupon/gunshi
Length of output: 500
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find where withOxContentApiDocs and externalPackageSources are used/implemented
rg -n "withOxContentApiDocs|externalPackageSources" . -S || true
# If the package exists in node_modules, inspect its source for entry expectations (.d.ts vs .ts)
# (Search limited to likely paths to avoid huge output.)
if [ -d node_modules ]; then
rg -n "externalPackageSources" node_modules -S --glob='*.js' --glob='*.ts' --glob='*.mjs' --glob='*.cjs' --glob='*.d.ts' || true
rg -n "withOxContentApiDocs" node_modules -S --glob='*.js' --glob='*.ts' --glob='*.mjs' --glob='*.cjs' --glob='*.d.ts' || true
fi
# Locate the import in config.ts to see the exact module specifier
echo "---- config.ts import(s) ----"
rg -n "from ['\"][^'\"]+['\"]" packages/docs/src/.vitepress/config.ts || trueRepository: kazupon/gunshi
Length of output: 819
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the relevant implementation around externalPackageSources
sed -n '1,200p' scripts/api-references.ts
# Also locate the helper that resolves externalPackageSources
rg -n "function resolveExternalPackageSources|resolveExternalPackageSources\\(" scripts -S
rg -n "externalPackageSources\\." scripts -S
# If api-references.ts imports helpers, inspect them too (quick trace)
rg -n "from ['\"].+['\"]" scripts/api-references.ts -SRepository: kazupon/gunshi
Length of output: 3433
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,140p' packages/docs/src/.vitepress/config.tsRepository: kazupon/gunshi
Length of output: 5331
Fix VitePress API docs config: don’t unconditionally reference missing lib/index.d.ts files (docs build can fail)
packages/docs/src/.vitepress/config.ts hard-codes externalPackageSources entries to:
packages/plugin-renderer/lib/index.d.ts(missing)packages/plugin-i18n/lib/index.d.ts(missing)
Only packages/plugin-*/src/index.ts exists in this checkout, so docs generation can break during config loading.
/scripts/api-references.ts already implements the intended behavior: it only includes externalPackageSources candidates when lib/index.d.ts exists; otherwise it omits them so ox-content falls back to normal resolution. Apply the same conditional inclusion logic in packages/docs/src/.vitepress/config.ts (skip these entries when the .d.ts files are absent), rather than pointing to non-declaration sources.
🤖 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/docs/src/.vitepress/config.ts` around lines 57 - 71, The config
currently unconditionally adds entries to externalPackageSources (the objects
referencing '`@gunshi/plugin-renderer`' and '`@gunshi/plugin-i18n`' via
path.resolve(repoRoot, 'packages/plugin-*/lib/index.d.ts')), which can point to
missing .d.ts files and break the docs build; update the code that builds
externalPackageSources in packages/docs/src/.vitepress/config.ts to check for
the presence of each target declaration file (use fs.existsSync or fs.access)
before pushing the entry, mirroring the logic in /scripts/api-references.ts, so
only packages whose lib/index.d.ts actually exist are included (keep existing
entries for args-tokens using argsTokensDir unchanged).
Source: Pipeline failures
| > This API is experimental and may change in future versions. | ||
|
|
||
| Compose multiple [Args](../../default/interfaces/Args.md) schemas into one. | ||
| Compose multiple [Args](/api/default/interfaces/Args.md) schemas into one. |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify the Args interface is located at the referenced path
# Check if Args.md exists at the referenced location
if [ -f "packages/docs/src/api/default/interfaces/Args.md" ]; then
echo "✓ Args.md found at /api/default/interfaces/"
head -5 "packages/docs/src/api/default/interfaces/Args.md"
else
echo "✗ Args.md not found at expected path"
fi
# Search for other references to Args in the combinators docs
echo -e "\nOther Args references in combinators docs:"
rg -n "Args\.md" packages/docs/src/api/combinators/ -C1Repository: kazupon/gunshi
Length of output: 3993
Fix broken Args cross-module link in merge documentation — packages/docs/src/api/default/interfaces/Args.md does not exist in the repo, so the /api/default/interfaces/Args.md links in packages/docs/src/api/combinators/functions/merge.md (lines 12, 51, 82, 115) are very likely invalid; update them to the actual location of the Args interface doc (and keep the other Args references consistent).
🤖 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/docs/src/api/combinators/functions/merge.md` at line 12, The
documentation in packages/docs/src/api/combinators/functions/merge.md contains
invalid cross-module links to the Args interface
(/api/default/interfaces/Args.md); locate the actual Args interface doc in the
repo and replace every broken link in merge.md (all occurrences referencing
Args) with the correct relative/permalink path so the cross-reference resolves,
keeping the link text "Args" unchanged and ensuring consistency across the other
Args references in the file.
| [`ArgSchema`](../../default/interfaces/ArgSchema.md) & `ArgSchemaPositionalType` | ||
|
|
||
| A positional argument schema resolving to string. | ||
| [`ArgSchema`](/api/default/interfaces/ArgSchema.md) & `ArgSchemaPositionalType` — A positional argument schema resolving to string. |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify ArgSchema interface location
# Check if ArgSchema.md exists at the referenced location
if [ -f "packages/docs/src/api/default/interfaces/ArgSchema.md" ]; then
echo "✓ ArgSchema.md found at /api/default/interfaces/"
head -5 "packages/docs/src/api/default/interfaces/ArgSchema.md"
else
echo "✗ ArgSchema.md not found at expected path"
fi
# Check for ArgSchemaPositionalType references
echo -e "\nSearching for ArgSchemaPositionalType definition:"
rg -n "ArgSchemaPositionalType" packages/docs/src/api/ --type md -A2Repository: kazupon/gunshi
Length of output: 1425
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find where ArgSchema.md actually lives
echo "Searching for ArgSchema.md:"
fd -a --type f "ArgSchema.md" packages/docs/src/api || true
echo -e "\nSearching for references to ArgSchema interface/type declaration:"
rg -n "ArgSchema" packages/docs/src/api --type md -S
echo -e "\nChecking current link target in positional.md:"
sed -n '55,75p' packages/docs/src/api/combinators/functions/positional.mdRepository: kazupon/gunshi
Length of output: 2151
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Find ArgSchema docs files:"
find packages/docs/src/api -type f \( -iname '*argschema*' -o -iname '*ArgSchema*' \) | sed 's#^`#-` #' | head -200
echo -e "\nList parent directories for anything matching ArgSchema:"
find packages/docs/src/api -type f \( -iname '*argschema*' \) -printf '%h\n' | sed 's#^`#-` #' | sort -u | head -200Repository: kazupon/gunshi
Length of output: 143
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Listing packages/docs/src/api/default/interfaces (if it exists):"
ls -la packages/docs/src/api/default/interfaces 2>/dev/null || echo "(directory not found)"
echo -e "\nSearching contents for 'interface ArgSchema' or 'type ArgSchema' in packages/docs/src/api:"
rg -n "interface ArgSchema|type ArgSchema|ArgSchema\s*:" packages/docs/src/api --type md -S || true
echo -e "\nSearching for 'ArgSchema' headings (e.g., '## ArgSchema') in packages/docs/src/api:"
rg -n "^#{1,6}.*ArgSchema" packages/docs/src/api --type md -S || true
echo -e "\nSearching for 'ArgSchema.md' references anywhere in packages/docs:"
rg -n "ArgSchema\.md" packages/docs/src/api -S --glob '*.md' || trueRepository: kazupon/gunshi
Length of output: 1156
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Shallow directory listing for packages/docs/src/api:"
find packages/docs/src/api -maxdepth 3 -type d -print | sed 's#^`#-` #'
echo -e "\nSearch repo for ArgSchema interface/type declarations (TS/source):"
rg -n "export (interface|type) ArgSchema|interface ArgSchema|type ArgSchema" . --glob '!**/node_modules/**' --glob '!**/dist/**' -S || true
echo -e "\nSearch for docs generation artifacts mentioning ArgSchema (if any):"
rg -n "ArgSchema\.md|/api/.*/interfaces/ArgSchema\.md" packages/docs/src -S || trueRepository: kazupon/gunshi
Length of output: 1468
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Listing packages/docs/src/api/combinators/interfaces:"
ls -la packages/docs/src/api/combinators/interfaces || true
echo -e "\nSearching docs.json for ArgSchema and likely path/URL fields:"
rg -n "ArgSchema" packages/docs/src/api/docs.json -S
echo -e "\nExtracting nearby sections around the 3 ArgSchema signature occurrences:"
for ln in 1962 3617 5737; do
echo -e "\n--- around line $ln ---"
sed -n "$((ln-30)),$((ln+30))p" packages/docs/src/api/docs.json
done
echo -e "\nSearching docs.json for '/api/.*ArgSchema' style references:"
rg -n "/api/.*/ArgSchema" packages/docs/src/api/docs.json -S || true
echo -e "\nSearching docs.json for 'ArgSchema.md':"
rg -n "ArgSchema\.md" packages/docs/src/api/docs.json -S || trueRepository: kazupon/gunshi
Length of output: 12843
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "References to the default ArgSchema URL:"
rg -n "/api/default/interfaces/ArgSchema\.md" packages/docs/src -S || true
echo -e "\nAny other /api/.../ArgSchema.md link targets:"
rg -n "/api/[^\\s\"']*ArgSchema\.md" packages/docs/src -S || trueRepository: kazupon/gunshi
Length of output: 1678
Fix broken ArgSchema link in positional.md
packages/docs/src/api/combinators/functions/positional.md(line 64) links to/api/default/interfaces/ArgSchema.md, butpackages/docs/src/api/default/interfaces/ArgSchema.mdis not present in the repo—update the link to the realArgSchemadoc location or add the missing page.
🤖 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/docs/src/api/combinators/functions/positional.md` at line 64, The
markdown in positional.md references
[`ArgSchema`](/api/default/interfaces/ArgSchema.md) which points to a
non-existent doc; open positional.md and either update the link target for the
[`ArgSchema`] reference to the actual location of the ArgSchema documentation
(keeping the link text and also verifying `ArgSchemaPositionalType` context
remains correct) or add the missing ArgSchema doc page so the existing link
resolves; ensure the updated link URL is consistent with the repo's API doc
structure and that the anchor/name matches the `ArgSchema` symbol.
Comment on lines
919
to
924
| ```json [package.json] | ||
| { | ||
| "scripts": { | ||
| "docs": "typedoc", | ||
| "docs:watch": "typedoc --watch", | ||
| "docs": "tsx ./scripts/generate-api-reference.ts", | ||
| "docs:clean": "rm -rf docs" | ||
| }, |
Contributor
There was a problem hiding this comment.
Use a cross-platform clean command in the package.json example.
Line 923 uses rm -rf, which is not portable across default Windows shells and can break copy-paste usage from this guide.
💡 Proposed docs snippet update
"scripts": {
"docs": "tsx ./scripts/generate-api-reference.ts",
- "docs:clean": "rm -rf docs"
+ "docs:clean": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('docs', { recursive: true, force: true })\""
},📝 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.
Suggested change
| ```json [package.json] | |
| { | |
| "scripts": { | |
| "docs": "typedoc", | |
| "docs:watch": "typedoc --watch", | |
| "docs": "tsx ./scripts/generate-api-reference.ts", | |
| "docs:clean": "rm -rf docs" | |
| }, |
🤖 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/docs/src/guide/plugin/guidelines.md` around lines 919 - 924, The
example package.json uses a non-portable shell command for cleanup; update the
"docs:clean" script reference (the scripts object, "docs:clean") to a
cross-platform approach (e.g., use a Node-based tool such as rimraf or a small
Node script) and mention adding the chosen tool to devDependencies or using npx
so the snippet works on Windows and POSIX shells when copy-pasted from the
guide.
|
|
||
| Translation adapter. | ||
|
|
||
| This adapter is used to custom message formatter like [Intlify message format](https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf), [`Intl.MessageFormat` (MF2)](https://github.com/tc39/proposal-intl-messageformat), and etc. |
Contributor
There was a problem hiding this comment.
Fix grammar and style in description.
Two issues on this line:
- "used to custom message formatter" should be "used to customize message formatters" or "used for custom message formatters"
- "and etc." should be just "etc."
📝 Proposed fix
-This adapter is used to custom message formatter like [Intlify message format](https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf), [`Intl.MessageFormat` (MF2)](https://github.com/tc39/proposal-intl-messageformat), and etc.
+This adapter is used to customize message formatters like [Intlify message format](https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf), [`Intl.MessageFormat` (MF2)](https://github.com/tc39/proposal-intl-messageformat), etc.📝 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.
Suggested change
| This adapter is used to custom message formatter like [Intlify message format](https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf), [`Intl.MessageFormat` (MF2)](https://github.com/tc39/proposal-intl-messageformat), and etc. | |
| This adapter is used to customize message formatters like [Intlify message format](https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf), [`Intl.MessageFormat` (MF2)](https://github.com/tc39/proposal-intl-messageformat), etc. |
🧰 Tools
🪛 LanguageTool
[grammar] ~5-~5: Ensure spelling is correct
Context: ... This adapter is used to custom message formatter like [Intlify message format](https://g...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~5-~5: Write the name of the item after ‘and’ or use only “etc”.
Context: ....com/tc39/proposal-intl-messageformat), and etc. This adapter will support localization...
(AND_ETC)
🤖 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/plugin-i18n/docs/default/interfaces/TranslationAdapter.md` at line
5, Update the description sentence "This adapter is used to custom message
formatter like [Intlify message format]..., [`Intl.MessageFormat` (MF2)]..., and
etc." to correct grammar and style: change it to "This adapter is used to
customize message formatters, such as Intlify message format and
Intl.MessageFormat (MF2), etc." — ensure the phrase referencing the adapter and
the formatter names (e.g., "This adapter", "Intlify message format",
"Intl.MessageFormat (MF2)") is preserved while replacing "used to custom message
formatter" with "used to customize message formatters" (or "used for custom
message formatters") and remove the redundant "and" before "etc."
|
|
||
| | Name | Type | Description | | ||
| | --- | --- | --- | | ||
| | `locale` | `string` | A Locale at the time of command execution. That is Unicord locale ID (BCP 47) | |
Contributor
There was a problem hiding this comment.
Correct spelling: "Unicord" → "Unicode".
The term should be "Unicode locale ID" (BCP 47 language tags are based on Unicode locale identifiers), not "Unicord locale ID".
📝 Proposed fix
-| `locale` | `string` | A Locale at the time of command execution. That is Unicord locale ID (BCP 47) |
+| `locale` | `string` | A Locale at the time of command execution. That is Unicode locale ID (BCP 47) |Apply the same correction on lines 55 and 96.
Also applies to: 55-55, 96-96
🤖 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/plugin-i18n/docs/default/interfaces/TranslationAdapter.md` at line
34, Change the misspelling "Unicord" to "Unicode" in the TranslationAdapter docs
where the `locale` table entry explains the locale identifier; update the three
occurrences of "Unicord locale ID" (the `locale` parameter description and the
two other identical entries in this markdown) to read "Unicode locale ID (BCP
47)" so all descriptions correctly reference Unicode language tags.
|
|
||
| | Name | Description | | ||
| | --- | --- | | ||
| | `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParams` | |
Contributor
There was a problem hiding this comment.
Fix the type parameter description to match the signature.
The description states "Type parameter extending GunshiParams" but the signature on Line 8 shows G extends GunshiParamsConstraint. These should match.
📝 Proposed fix
-| `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParams` |
+| `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParamsConstraint` |📝 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.
Suggested change
| | `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParams` | | |
| | `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParamsConstraint` | |
🤖 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/plugin-i18n/docs/default/type-aliases/CommandResource.md` at line
15, The doc line for the type parameter `G` is incorrect: update the description
to match the signature `G extends GunshiParamsConstraint = DefaultGunshiParams`
in CommandResource.md by changing the phrase "Type parameter extending
`GunshiParams`" to "Type parameter extending `GunshiParamsConstraint`" (and keep
the default `= DefaultGunshiParams`), ensuring the `G` entry and its description
reference `GunshiParamsConstraint`, `G`, and `DefaultGunshiParams` consistently.
|
|
||
| | Name | Description | | ||
| | --- | --- | | ||
| | `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParams` | |
Contributor
There was a problem hiding this comment.
Fix the type parameter description to match the signature.
The description states "Type parameter extending GunshiParams" but the signature on Line 8 shows G extends GunshiParamsConstraint. These should match.
📝 Proposed fix
-| `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParams` |
+| `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParamsConstraint` |📝 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.
Suggested change
| | `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParams` | | |
| | `G` *extends* `GunshiParamsConstraint` = `DefaultGunshiParams` | Type parameter extending `GunshiParamsConstraint` | |
🤖 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/plugin-i18n/docs/default/type-aliases/CommandResourceFetcher.md` at
line 15, Update the type parameter description for G to match the actual
signature: change the phrase "Type parameter extending `GunshiParams`" to
reference `GunshiParamsConstraint` (e.g., "Type parameter extending
`GunshiParamsConstraint`") so the doc for the type parameter `G` aligns with the
signature `G extends GunshiParamsConstraint`; locate the `G` type parameter line
in the CommandResourceFetcher type alias docs and replace the incorrect
constraint name accordingly.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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.
Inline comments:
In `@pnpm-workspace.yaml`:
- Line 52: The overrides block pins "`@ox-content/napi`": 2.66.0 but lacks an
explanatory inline comment; add a short comment immediately above the
"`@ox-content/napi`": 2.66.0 override describing the compatibility/breakage reason
or referencing the exact issue/PR (e.g., "pins to 2.66.0 due to X regression in
2.67 — see GH#1234"), then verify that 2.66.0 is still the required/latest-safe
version by testing/upgrading locally and either keep the comment+pin or remove
the override if no longer needed; if you change/remove the override, update
pnpm-lock.yaml accordingly to reflect the new resolution.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 75ca1273-309c-454f-bdf3-f44e97a55078
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (1)
pnpm-workspace.yaml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Migrates Gunshi API reference generation from TypeDoc to vitepress-api-references powered by ox-content.
The docs build now generates API Markdown and VitePress sidebar data from config, removes TypeDoc configs and dependencies from docs and plugin packages, updates generated API pages, and adds benchmark notes showing ox-content is significantly faster than the previous TypeDoc workflow.
Linked Issues
Additional context
Summary by CodeRabbit
New Features
Documentation
Chores