website: launch the Jazz documentation site - #126
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughChangesWebsite publication
Estimated code review effort: 5 (Critical) | ~120 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 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 |
Contributor
Not up to standards ⛔🔴 Issues
|
| Category | Results |
|---|---|
| BestPractice | 3 medium 2 minor |
| Documentation | 1 minor |
| Security | 2 minor 2 high 1 critical 4 medium |
| CodeStyle | 82 minor |
| Complexity | 3 medium |
🟢 Metrics 511 complexity · 5 duplication
Metric Results Complexity 511 Duplication 5
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 47 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Un3qual
marked this pull request as ready for review
August 1, 2026 19:03
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c0f2b8c413
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![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: 13
🤖 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 @.github/workflows/docs-pages.yml:
- Around line 28-77: Pin every GitHub Actions reference in
.github/workflows/docs-pages.yml to its intended full commit SHA instead of
mutable `@vN` tags. Update scripts/check-docs-pages-workflow.py to validate
SHA-pinned references, and revise the affected fixtures and assertions in
scripts/test-docs-pages-workflow.py at lines 42-83 and 176-188 to expect the SHA
format and corresponding workflow values.
- Around line 14-17: Scope GitHub Pages permissions per job: set workflow-level
permissions to empty, give build only contents: read and pages: write, and give
deploy pages: write and id-token: write in
.github/workflows/docs-pages.yml#L14-L17. Update EXPECTED_PERMISSIONS and the
job-permission validation in scripts/check-docs-pages-workflow.py#L18-L22 and
`#L182-L187` to require these scopes instead of rejecting job-level permissions.
Update VALID_WORKFLOW and replace the rejection tests with required-scope tests
in scripts/test-docs-pages-workflow.py#L29-L32 and `#L134-L170`.
In `@scripts/check-public-docs.py`:
- Around line 36-46: Update README_REQUIRED_LINKS to reference the existing
PUBLIC_WEBSITE_URL constant instead of repeating the hard-coded website URL,
keeping the required-link check behavior unchanged.
- Around line 245-296: Update markdown_inline_links to recursively scan each
extracted link label before advancing past the outer target, so nested links and
images such as linked images are returned alongside the outer link. Preserve
label and target parsing while ensuring validate and validate_readme receive the
inner image targets for their existing checks.
In `@scripts/check-website-boundary.py`:
- Around line 237-242: Update remote_resource to catch ValueError from urlsplit
when parsing arbitrary targets, and return True for parse failures. Preserve the
existing scheme and protocol checks for successfully parsed values so malformed
URLs are treated as remote violations rather than propagating an exception.
- Around line 228-234: Update the violation handling around REMOTE_REFERENCE and
allowed_authored_remote so each rejected URL is included in the violations
message alongside path_label. Iterate over the matches or retain the rejected
match value, and append one violation per non-allowlisted URL while preserving
the existing allowlist check.
- Around line 252-291: Update ResourceParser to scan inline style content for
remote CSS resources by adding handle_data state tracking for <style> blocks and
passing their text through css_targets, marking remote_fetch when any target is
remote. Ensure css_targets is defined before runtime use or otherwise resolved
safely, and reset style-tracking state when the style element closes.
- Around line 58-60: Update the REMOTE_REFERENCE regex used by
check_authored_sources to require a host-like segment immediately after the //
authority marker, while preserving valid protocol-relative and scheme-based URL
matching. Ensure comment dividers and JavaScript/TypeScript comments such as
//TODO:check are no longer treated as remote references.
In `@scripts/test-check-public-docs.py`:
- Around line 446-448: Remove the redundant
test_visible_prospective_website_links_pass method, since
test_valid_fixture_passes already covers the unmodified setUp fixture and
successful return code; only retain it if you change it to exercise a distinct
fixture.
- Around line 354-382: Update the three README decoy
tests—test_readme_comment_decoy_cannot_hide_stale_visible_wording,
test_readme_inline_code_decoy_cannot_hide_stale_visible_wording, and
test_readme_escaped_link_decoy_is_not_a_visible_link—to replace
README_WEBSITE_LINK with only the corresponding masked decoy, removing the valid
[Website] link. Keep the existing stale-label assertion and also assert the
missing canonical navigation-link violation if that is emitted, so each test
genuinely depends on comment, inline-code, or escape handling.
In `@scripts/test-check-website-boundary.py`:
- Around line 86-94: Update the generated factorial source construction in the
test to serialize factorial with json.dumps instead of f-string repr plus quote
replacement. Import or reuse the JSON module as needed, while preserving the
generated header and exact source content.
In `@website/scripts/render-social-card.mjs`:
- Around line 103-128: Update the temporary output handling in renderSocialCard
to create a unique temporary path for each invocation rather than deriving a
constant path from pngPath. Ensure sharp writes, metadata validation, rename,
and cleanup all use that invocation-specific path so concurrent renders cannot
interfere.
In `@website/src/components/CodeProof.tsx`:
- Around line 15-16: Update the descriptive copy in CodeProof to state that the
example is verified by factorial synchronization checks rather than the compiler
test suite, unless an existing required workflow explicitly validates this
example through compiler tests.
🪄 Autofix
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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: b070faf2-211d-4cdb-a043-542189061c29
⛔ Files ignored due to path filters (10)
jazz_logo.pngis excluded by!**/*.pngwebsite/package-lock.jsonis excluded by!**/package-lock.jsonwebsite/src/generated/factorial.tsis excluded by!**/generated/**website/static/img/favicon.svgis excluded by!**/*.svgwebsite/static/img/jazz-mark-dark.svgis excluded by!**/*.svgwebsite/static/img/jazz-mark.svgis excluded by!**/*.svgwebsite/static/img/jazz-wordmark-dark.svgis excluded by!**/*.svgwebsite/static/img/jazz-wordmark.svgis excluded by!**/*.svgwebsite/static/img/social-card.pngis excluded by!**/*.pngwebsite/static/img/social-card.svgis excluded by!**/*.svg
📒 Files selected for processing (37)
.codex/plans/2026-07-31-jazz-docusaurus-website.md.github/workflows/docs-pages.yml.gitignoreREADME.mddocs/getting-started/overview.mdflake.nixscripts/check-docs-pages-workflow.pyscripts/check-public-docs.pyscripts/check-website-boundary.pyscripts/check-website.shscripts/test-check-public-docs.pyscripts/test-check-website-boundary.pyscripts/test-docs-pages-workflow.pywebsite/.nvmrcwebsite/docusaurus.config.tswebsite/package.jsonwebsite/scripts/prism-jazz-grammar.d.mtswebsite/scripts/prism-jazz-grammar.mjswebsite/scripts/render-social-card.mjswebsite/scripts/sync-factorial.mjswebsite/scripts/test-brand-assets.mjswebsite/scripts/test-experience.mjswebsite/sidebars.tswebsite/src/components/BrandMark.tsxwebsite/src/components/CodeProof.tsxwebsite/src/components/EditorialBand.tsxwebsite/src/components/HomepageFooterCta.tsxwebsite/src/components/HomepageHeader.tsxwebsite/src/css/custom.csswebsite/src/pages/index.module.csswebsite/src/pages/index.tsxwebsite/src/theme/DocItem/Layout/index.tsxwebsite/src/theme/DocItem/Layout/styles.module.csswebsite/src/theme/Navbar/Logo/index.tsxwebsite/src/theme/prism-include-languages.tswebsite/static/img/brand/README.mdwebsite/tsconfig.json
🤖 CodeAnt AI — Review Status
|
Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
the
size:XXL
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3e238502fd
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 689ac3d469
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
scripts/check-website-boundary.py (1)
311-359: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueSplit
handle_starttaginto focused helpers.
handle_starttagnow performs six unrelated checks: style tracking,srcdoccollection, plain URL attributes,srcsetcandidates, inline styles, andhrefpolicy. Static analysis reports a cyclomatic complexity of 26. Extract one helper per check to keep each rule readable and testable.♻️ Suggested structure
def handle_starttag( self, tag: str, attrs: list[tuple[str, str | None]] ) -> None: folded_tag = tag.casefold() if folded_tag == "style": self.in_style = True attribute_values: dict[str, list[str]] = {} for name, value in attrs: attribute_values.setdefault(name.casefold(), []).append(value or "") - attributes = { - name: values[0] for name, values in attribute_values.items() - } - self.embedded_documents.extend( - source for source in attribute_values.get("srcdoc", []) if source - ) - for name in ( ... + self.collect_embedded_documents(attribute_values) + self.scan_url_attributes(attribute_values) + self.scan_srcset_attributes(attribute_values) + self.scan_inline_styles(attribute_values) + self.scan_href_policy(folded_tag, attribute_values)🤖 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/check-website-boundary.py` around lines 311 - 359, Split handle_starttag into focused helper methods for style tracking, srcdoc collection, plain URL attributes, srcset/imagesrcset candidates, inline CSS targets, and href navigation policy. Keep handle_starttag responsible only for orchestration and preserve the existing remote_fetch, in_style, and embedded_documents behavior while reducing its cyclomatic complexity.Source: Linters/SAST tools
🤖 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 @.github/workflows/docs-pages.yml:
- Around line 30-31: Update the actions/checkout step in the docs workflow to
set persist-credentials to false, preventing GITHUB_TOKEN storage while
preserving the existing checkout action and workflow behavior.
In `@scripts/check-docs-pages-workflow.py`:
- Around line 210-220: The permission validation logic around
EXPECTED_JOB_PERMISSIONS requires fixture coverage for real inline permission
comments. Update scripts/test-docs-pages-workflow.py at lines 41-42 and 78-80 to
add the build and deploy permission comments from
.github/workflows/docs-pages.yml to VALID_WORKFLOW;
scripts/check-docs-pages-workflow.py lines 210-220 requires no direct change.
In `@website/scripts/test-experience.mjs`:
- Around line 15-44: Update the test around the temporary fixture created in the
factorial sync test to wrap its existing body in a try/finally block, and
recursively remove fixture in the finally cleanup. Preserve all current
assertions and subprocess behavior while ensuring cleanup runs even when the
test fails.
---
Outside diff comments:
In `@scripts/check-website-boundary.py`:
- Around line 311-359: Split handle_starttag into focused helper methods for
style tracking, srcdoc collection, plain URL attributes, srcset/imagesrcset
candidates, inline CSS targets, and href navigation policy. Keep handle_starttag
responsible only for orchestration and preserve the existing remote_fetch,
in_style, and embedded_documents behavior while reducing its cyclomatic
complexity.
🪄 Autofix
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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 430f747c-ce8f-4326-b7a9-ce53ce7ab25e
⛔ Files ignored due to path filters (1)
website/src/generated/factorial.tsis excluded by!**/generated/**
📒 Files selected for processing (20)
.codex/plans/2026-07-31-jazz-docusaurus-website.md.github/workflows/docs-pages.ymlREADME.mddocs/getting-started/overview.mdflake.nixscripts/check-docs-pages-workflow.pyscripts/check-public-docs.pyscripts/check-website-boundary.pyscripts/markdown_targets.pyscripts/test-check-public-docs.pyscripts/test-check-website-boundary.pyscripts/test-docs-pages-workflow.pywebsite/scripts/render-social-card.mjswebsite/scripts/sync-factorial.mjswebsite/scripts/test-brand-assets.mjswebsite/scripts/test-experience.mjswebsite/src/components/CodeProof.tsxwebsite/src/css/custom.csswebsite/src/theme/DocItem/Layout/index.tsxwebsite/src/theme/DocItem/Layout/styles.module.css
💤 Files with no reviewable changes (1)
- website/src/theme/DocItem/Layout/styles.module.css
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e8c66c89fd
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Owner
Author
|
Outside-diff/static-analysis follow-up for 2bc908d:
Verification: 158 public-doc tests, 33 website-boundary tests, 19 Pages-workflow tests, 5 brand tests, 10 experience tests, actionlint, Ruff, Python compilation, the complete documentation gate, and the Node 22 production website build all pass. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2bc908d4d9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5643dcb720
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
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
docs/treeStack
This draft is stacked on #125 (
codex/documentation-reset). It should be reviewed and merged after that PR.Verification
npm ciDeployment follow-up
After merge, set Settings → Pages → Source to GitHub Actions, run or dispatch the workflow, verify the deployed URL, then change the prospective README and Getting Started labels to published wording.
Human visual review
These checks intentionally remain unmarked until maintainer observation:
Dependency note
npm auditcurrently reports 20 moderate and 1 high advisory in the transitive Docusaurus build dependency graph. The generated site is static, and npm proposes an invalid/older Docusaurus resolution, so this PR does not apply a forced breaking downgrade.Summary by cubic
Launch the Jazz documentation website as a static, TypeScript Docusaurus 3 app that publishes only the curated
docs/tree and deploys via a least‑privilege GitHub Pages workflow. Tightens pre/post‑build publication boundary checks and the Pages workflow contract.Bug Fixes
scripts/sync-factorial.mjs, with experience tests.Migration
Written for commit 5643dcb. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation
Tests