Add interactive Ray.Di bindings documentation

[koriym]

Problem

Ray.Di bindings and provenance are difficult to inspect as a large Markdown report, and the relationships between selected bindings are not visible in context.

Approach

• Add a bindings output format and optional application DI context.
• Generate bindings.html from Ray.Di diagnostics and export the object graph as DOT.
• Render DOT in the browser with version-pinned Viz.js/WASM; keep shared CSS and JavaScript on jsDelivr so generated HTML stays small.
• Add incremental search over Bindings and Provenance rows, hide Modules while filtering, focus matching graph nodes with capped zoom, and support drag-to-pan/reset interactions.
• Preserve surrounding graph context with readable dimming and expose the original DOT artifact.
• Escape DOT embedded in the JSON data island and load Composer source metadata by walking up from the application directory.
• Install ray/object-visual-grapher as a runtime dependency and avoid graph work for non-bindings formats.

Dependency

• Disambiguate source links for shared PSR-4 prefixes ray-di/Ray.Di#330 adds exact source-map resolution when packages share a PSR-4 prefix. Its new vendor-directory argument is optional; the report remains functional with Ray.Di 2.21.1, while source-link disambiguation becomes active after that prerequisite is released.

Validation

• composer cs-fix
• composer test — 139 tests, 583 assertions; one existing deprecation
• composer sa — PHPStan, Psalm, and PHPMD passed
• PHPCS passed for all modified PHP files
• node --check docs/assets/bindings-object-graph.js
• composer validate --strict --no-check-publish

Full composer cs with the locally updated toolchain additionally reports four fixable issues in unchanged src-alps/ProfileDictionary.php; that file is intentionally excluded from this PR.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2404e831-4b82-4fa8-86ea-1c6db5c2ff61

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a bindings documentation format with context-aware DI metadata, generated bindings HTML, embedded object-graph visualization, supporting assets, Composer scripts, schema updates, and integration coverage.

Changes

Bindings documentation output

Layer / File(s)	Summary
Bindings configuration and dependencies apidoc.xsd, composer.json, CLAUDE.md	Adds the context configuration, accepts the bindings format, updates Ray.Di dependencies, and adds bindings documentation scripts and guidance.
Bindings metadata and object graph preparation src/Config.php	Reads the application context and conditionally generates object-graph DOT data and bindings markdown through DI metadata.
Bindings HTML generation src/ApiDoc.php	Routes bindings to bindings.html, loads Composer metadata, renders bindings HTML, and injects graph data and assets.
Interactive graph and output validation docs/assets/*, tests/ApiDocTest.php, tests/apidoc.bindings.xml, .gitignore	Adds the interactive SVG graph viewer and styling, bindings fixture and assertions, and ignores generated temporary output.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ApiDoc
  participant Config
  participant BindingsHtml
  participant Browser
  ApiDoc->>Config: load context, bindings markdown, and DOT graph
  ApiDoc->>BindingsHtml: render bindings.html
  ApiDoc->>BindingsHtml: inject graph payload and assets
  Browser->>ApiDoc: load generated HTML
  Browser->>Browser: render DOT as SVG and filter graph nodes

Loading

Possibly related PRs

• bearsunday/BEAR.ApiDoc#70: Extends the same format schema and dispatch plumbing for another documentation output target.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding interactive Ray.Di bindings documentation.
Description check	✅ Passed	The description is detailed and directly aligned with the bindings documentation and visualization changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bindings-object-graph-cdn-assets

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[koriym]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

tests/ApiDocTest.php (1)

195-203: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert actual binding data, not only the page shell.

This can pass if bindingsMarkdown falls back to the zero-bindings page while DOT generation still succeeds. Assert a known binding/module/provenance row or expected count from the Fake application.

🤖 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 `@tests/ApiDocTest.php` around lines 195 - 203, Strengthen the binding
documentation assertions in the test around the bindings.html checks so they
verify actual Fake application binding data, not just shell elements and DOT
output. Assert a known binding/module or provenance row, or the expected binding
count, using the symbols and expected values established by the Fake application
fixtures.

🤖 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.

Nitpick comments:
In `@tests/ApiDocTest.php`:
- Around line 195-203: Strengthen the binding documentation assertions in the
test around the bindings.html checks so they verify actual Fake application
binding data, not just shell elements and DOT output. Assert a known
binding/module or provenance row, or the expected binding count, using the
symbols and expected values established by the Fake application fixtures.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 57693d76-e491-46fe-9589-09979235d5d5

📥 Commits

Reviewing files that changed from the base of the PR and between 1ddbe6c and c986ee8.

📒 Files selected for processing (10)

• .gitignore
• CLAUDE.md
• apidoc.xsd
• composer.json
• docs/assets/bindings-object-graph.css
• docs/assets/bindings-object-graph.js
• src/ApiDoc.php
• src/Config.php
• tests/ApiDocTest.php
• tests/apidoc.bindings.xml

[koriym]

Closing in favor of #102.

#102 contains all of this PR's commits plus the ray/di 2.22 explicit-bindings-snapshots adaptation, and is now fully green (cs, static analysis, and PHPUnit across PHP 8.2/8.3/8.5 × highest/lowest). This PR cannot pass CI on its own: keeping the old deps (ray/di ^2.21) breaks static analysis (Ray\Bindings undefined), while bumping to ray/di ^2.22 breaks testBindingsOutput without the explicit-collection migration that lives in #102.