Add the crate dependency graph visualization to the contributor guide

[Keavon]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the contributor guide by integrating an interactive visualization of the Rust workspace's crate dependency graph. This provides new contributors with a clear, dynamic overview of the codebase structure. The changes involve refactoring the crate-hierarchy-viz tool to produce a DOT graph, adding a new build script to convert this into an interactive SVG for the website, and updating the cargo-run utility with a convenient command to access this new resource. Additionally, other documentation generation tools were made more robust by allowing configurable output paths.

Highlights

• Crate Dependency Graph Visualization: An interactive visualization of the Rust workspace's crate dependency graph has been added to the contributor guide, providing a clear overview of the codebase structure.
• Updated crate-hierarchy-viz Tool: The Rust tool responsible for generating the dependency graph was refactored to output a DOT file directly, remove the clap dependency, and now supports glob patterns for workspace members.
• Website Integration and Interactivity: A new build script converts the DOT graph into an interactive SVG, which is embedded in the contributor guide with pan and zoom functionality via new JavaScript and CSS.
• Enhanced cargo-run Utility: A new deps command was added to cargo-run to quickly open the crate dependency graph in the browser, improving developer workflow.
• Refactored Build Tools for Flexibility: The editor-message-tree and node-docs tools were updated to accept output paths as arguments, making them more flexible for automated build processes.

Changelog

• Cargo.lock
  • Removed clap dependency from crate-hierarchy-viz.
  • Added glob dependency for crate-hierarchy-viz.
  • Added @viz-js/viz dependency for the website build process.
• tools/cargo-run/src/main.rs
  • Added a new deps command to the explore subcommand.
  • Configured the deps command to open the crate dependency graph page in the browser.
• tools/crate-hierarchy-viz/Cargo.toml
  • Removed clap dependency.
  • Added glob dependency.
• tools/crate-hierarchy-viz/src/main.rs
  • Removed clap and std::process::Command imports.
  • Removed Args struct and OutputFormat enum, simplifying argument parsing.
  • Removed WorkspaceDependency enum and related logic.
  • Removed external_dependencies field from CrateInfo.
  • Modified main function to accept output path as a command-line argument.
  • Implemented glob pattern expansion for workspace members using the glob crate.
  • Simplified dependency collection to focus only on workspace-internal dependencies.
  • Removed direct GraphViz integration, now only outputs DOT format.
  • Refactored generate_dot_format into generate_dot and updated clustering logic.
• tools/editor-message-tree/src/main.rs
  • Modified main function to accept an output file path as a command-line argument.
  • Updated file creation to use the provided output path.
• tools/node-docs/src/main.rs
  • Modified main function to accept an output directory path as a command-line argument.
  • Updated calls to page_catalog::write_catalog_index_page and page_category::write_category_index_page to pass the output path.
• tools/node-docs/src/page_catalog.rs
  • Updated write_catalog_index_page function signature to accept output_path.
  • Modified file system operations to use the provided output_path.
• tools/node-docs/src/utility.rs
  • Removed the NODE_CATALOG_PATH constant.
• website/.build-scripts/generate-crate-hierarchy.ts
  • Added a new TypeScript script to read a DOT file, use @viz-js/viz to render it as SVG, and write the SVG to an output file.
• website/content/volunteer/guide/codebase-overview/_index.md
  • Added new JavaScript and CSS files for the crate hierarchy visualization.
  • Inserted a new section for the "Crate dependency graph" with a placeholder for the generated SVG.
• website/package-lock.json
  • Added @viz-js/viz package dependency.
• website/package.json
  • Added a new generate-crate-hierarchy script.
  • Added @viz-js/viz as a dev dependency.
• website/sass/page/contributor-guide/crate-hierarchy.scss
  • Added new SCSS rules for styling the .crate-hierarchy container, including controls for zoom and pan, and SVG styling.
• website/static/js/page/contributor-guide/crate-hierarchy.js
  • Added new JavaScript for interactive pan and zoom functionality for the crate hierarchy SVG.
  • Implemented event listeners for scroll wheel, zoom buttons, and click-drag panning.
• website/templates/base.html
  • Added a new replace filter for the crate_hierarchy() macro.
• website/templates/macros/replacements.html
  • Added a new crate_hierarchy macro to embed the crate hierarchy SVG and provide local testing instructions.
  • Updated the hierarchical_message_system_tree macro's fallback instructions to use cargo run -p syntax.

Ignored Files

• Ignored by pattern: .github/workflows/** (5)
  • .github/workflows/build.yml
  • .github/workflows/ci.yml
  • .github/workflows/comment-profiling-changes.yaml
  • .github/workflows/release.yml
  • .github/workflows/website.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable crate dependency graph visualization to the contributor guide. The implementation is well-structured, separating the graph data generation in Rust from the rendering and interaction in JS/TS. The refactoring of existing tools to be more flexible is also a welcome improvement. I've found one minor issue related to path handling on Windows which should be addressed. Overall, great work!

[cubic-dev-ai]

5 issues found across 21 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tools/editor-message-tree/src/main.rs">

<violation number="1" location="tools/editor-message-tree/src/main.rs:9">
P3: Avoid `std::process::exit(1)` here; return an error from `main` instead so normal cleanup still runs.

(Based on your team's feedback about avoiding `exit()` in commands.) [FEEDBACK_USED]</violation>
</file>

<file name="tools/node-docs/src/main.rs">

<violation number="1" location="tools/node-docs/src/main.rs:13">
P2: Avoid `std::process::exit()` here; return an error/exit status from `main` so normal cleanup still runs.

(Based on your team's feedback about avoiding `exit()` and preferring returns for cleanup.) [FEEDBACK_USED]</violation>
</file>

<file name="website/static/js/page/contributor-guide/crate-hierarchy.js">

<violation number="1" location="website/static/js/page/contributor-guide/crate-hierarchy.js:28">
P2: Recompute the viewport height on resize instead of freezing it to the initial render size.</violation>

<violation number="2" location="website/static/js/page/contributor-guide/crate-hierarchy.js:109">
P2: Cancel the previous zoom animation before starting another one.</violation>
</file>

<file name="tools/crate-hierarchy-viz/src/main.rs">

<violation number="1" location="tools/crate-hierarchy-viz/src/main.rs:86">
P2: Use `args_os()` here and return an error for missing args. `args()` will panic on non-UTF-8 paths, and `exit()` bypasses `main`'s normal cleanup.

(Based on your team's feedback about avoiding `exit()` in `main`.) [FEEDBACK_USED]</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="website/static/js/page/contributor-guide/crate-hierarchy.js">

<violation number="1" location="website/static/js/page/contributor-guide/crate-hierarchy.js:35">
P2: Reapply the transform after resize so existing pan offsets are clamped to the new viewport size.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}