fix(docs): bump constructs pin to 10.6.0 in documentation-generation tool#305
Open
so0k wants to merge 3 commits into
Open
fix(docs): bump constructs pin to 10.6.0 in documentation-generation tool#305so0k wants to merge 3 commits into
so0k wants to merge 3 commits into
Conversation
…tool The tools/documentation-generation package pinned constructs@10.3.0 for resolving the jsii assembly via assembliesDir, while every other package in the repo uses 10.6.0. jsii-docgen documents inherited Construct members from that assembly, so the stale 10.3.0 copy predates the with()/IMixin mixin API and silently omitted it from all generated construct docs across every language. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
so0k
added
ci/skip-examples
tools/documentation-generation was excluded from pnpm-workspace.yaml, a holdover from Yarn Classic days when workspace hoisting could flatten `constructs` to a conflicting version. pnpm doesn't hoist, so that constraint no longer applies, but the exclusion was never revisited. Being outside the workspace made this package invisible to lerna-based tooling, including the existing upgradeJSII CI job that already keeps `constructs`/`jsii-docgen`/`jsii-rosetta` in lockstep everywhere else - which is exactly how the constructs pin went stale (the prior commit in this PR fixed the version; this restores the mechanism that would have kept it correct going forward). - Add tools/documentation-generation to pnpm-workspace.yaml - Switch its `cdktn` dependency to `workspace:*` (was a manual `link:`) - Align jsii-rosetta to ~5.9.0 (matches @cdktn/hcl2cdk) - drift sherif can now actually see now that the package is workspace-visible - Drop its standalone pnpm-lock.yaml in favor of the root lockfile - Simplify the generate-docs:api script now that a plain `pnpm install` covers this package too Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Now that tools/documentation-generation is a workspace member, knip scans it and flags cdktn/constructs as unused — generate-documentation.js only resolves them on disk through assembliesDir for jsii-docgen, never via a static import, so knip's usage analysis can't see it. Same pattern already used for constructs in packages/cdktn-cli's knip config. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
Summary
tools/documentation-generationpinnedconstructs@10.3.0, while every other package in the repo (packages/cdktn,@cdktn/cli-core,@cdktn/provider-generator,cdktn-cli, all examples) uses10.6.0. The pin dates back to thecdktfera (2024-05-06) and was never bumped since.jsii-docgendocuments inheritedConstructmembers by resolving the base-class assembly it's pointed at viaassembliesDir. Since that assembly came from the staleconstructs@10.3.0, which predates thewith(...mixins: IMixin[])mixin API, none of the generated construct docs (across all 5 languages) documentedwith()/IMixinat all.tools/documentation-generationwas excluded frompnpm-workspace.yaml— a holdover from Yarn Classic days, when workspace hoisting could genuinely flattenconstructsto a conflicting version. pnpm doesn't hoist, so that constraint stopped applying after the pnpm migration, but the exclusion was never revisited. Being outside the workspace made the package invisible tolerna exec-based tooling, including the existingupgradeJSIICI job that already keepsconstructs/jsii-docgen/jsii-rosettain lockstep everywhere else — which is exactly how this pin went stale in the first place.Changes
constructsto10.6.0intools/documentation-generation/package.json.tools/documentation-generationtopnpm-workspace.yaml.cdktndependency toworkspace:*(was a manuallink:../../packages/cdktn).jsii-rosettato~5.9.0(matches@cdktn/hcl2cdk) — this drift was invisible before and only surfaced oncesherif/lerna could actually see the package.pnpm-lock.yamlin favor of the root lockfile; simplifygenerate-docs:apinow that a plainpnpm installcovers this package too.Test plan
pnpm generate-docs:apipipeline (install + build + regenerate docs) twice — once for the version-bump-only fix, once after the workspace restructuring — from a clean worktree each timetools/documentation-generation/node_modules/constructs/package.jsonresolves to10.6.0andnode_modules/cdktnsymlinks correctly via the workspace protocolwith()/IMixin— verified across all 5 languages'constructs/topic (40 construct files each, 0 before the fix)website/docs/cdktn/**output is gitignored, so no generated-doc diff is part of this PR@tools/documentation-generationnow shows up inlerna ls --all(so futureupgradeJSIIruns will enumerate it) and innpx sherifoutput (so future drift will be flagged) — verified by simulating the regression (reverting the pin) and confirming detection tooling behaves correctly both ways🤖 Generated with Claude Code