feat: Add virtual relationships for multi-hop path traversal [INFP-313]

[minitriga]

Why

Problem: Users modeling complex infrastructure (e.g., chassis with bays, line cards, modules, interfaces) are forced to choose between schema correctness and query simplicity. To answer "give me all interfaces on this device," they must traverse multiple relationship hops manually — via complex GraphQL queries, custom Python code, or tedious UI navigation.

Impact: This forces a trade-off: model data correctly (many hops) or duplicate relationships for convenience (risking inconsistency). AI/MCP use cases are particularly affected — LLMs need simplified access without full schema context.

What

Implements virtual relationships — schema-level computed relationship definitions that traverse multi-hop paths to collect target nodes at query time, without data duplication.

Schema Definition

nodes:
  - name: Device
    namespace: Infra
    virtual_relationships:
      - name: all_interfaces
        label: "All Interfaces"
        path: bays__line_cards__modules__interfaces
      - name: affected_services
        path: interfaces__circuits__containers__services

Key Changes

Backend (Python)

• Schema layer: VirtualRelationshipSchema model with path validation (segment count, circular refs, name conflicts, generic inheritance resolution)
• Query layer: Cypher multi-hop traversal queries with branch-aware filtering, deduplication, pagination
• GraphQL layer: Virtual relationship fields generated as NestedPaginated{Kind} types with dedicated resolver supporting filtering via NodeManager.query
• API: OpenAPI schema regenerated with virtual_relationships on node/generic schemas

Frontend (TypeScript/React)

• Virtual relationship tabs on node detail pages with count badges
• Read-only (no "Add relationship" button)
• Reuses existing RelationshipTable and useGetRelationshipCount infrastructure

Tests

• 15 unit tests: schema parsing, path validation, name conflicts, peer derivation, label generation
• 10 functional tests: basic query, empty results, pagination, filtering, branch-aware resolution, deduplication, cross-domain traversal (4 node kinds), schema validation rejection

Architecture Decisions

• Query-time resolution (not materialized) — ensures consistency, avoids cache invalidation complexity
• Path notation uses __ separator, consistent with existing Infrahub filter conventions
• Generic inheritance resolution — when peer kind is a Generic, validation checks concrete implementations for available relationships
• Read-only in initial release; write support deferred

Files Changed (26 files, +2133/-17)

Area	Files	Purpose
Schema model	virtual_relationship_schema.py, definitions/internal.py, generated/	VirtualRelationshipSchema definition + generation
Schema integration	__init__.py, basenode_schema.py, schema_branch.py	Loading, validation, processing, extensions
Query	core/query/virtual_relationship.py	Cypher traversal + count queries
GraphQL	graphql/manager.py, resolvers/virtual_relationship.py	Field generation + resolver
Frontend	object-details-tabs.tsx, object-tabs.tsx, object-relationships-manager.tsx	Tab rendering + read-only handling
Tests	test_virtual_relationship_schema.py, test_virtual_relationship.py	Unit + functional tests
Docs	virtual-relationships.mdx, changelog fragment	User documentation

Test plan

• Unit tests pass (15/15)
• Functional tests pass (10/10) — requires Neo4j
• Manual testing with infrahub-bundle-dc schemas (all_services, connected_devices)
• Schema validation rejects invalid paths
• Branch-aware resolution verified
• Cross-domain traversal (4 node kinds) verified
• Deduplication verified
• Filtering verified
• E2E test (Playwright) — written, needs CI environment
• Permission filtering — deferred to integration tests
• Branch merge behavior — deferred to integration_docker tests

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

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: 453e9550-59b2-4585-9295-1ec9febcaa5f

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

📝 Coding Plan

• Generate coding plan for human review comments

---

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 and usage tips.}

[codspeed-hq]

Merging this PR will improve performance by 38.1%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 12 improved benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_schemabranch_process	1,040.9 ms	802.3 ms	+29.73%
⚡	test_query_rel_many	693.3 ms	523.8 ms	+32.35%
⚡	test_base_schema_duplicate_CoreProposedChange	2.1 ms	1.7 ms	+22.73%
⚡	test_graphql_generate_schema	516 ms	373.6 ms	+38.1%
⚡	test_schemabranch_duplicate	7.2 ms	5.5 ms	+31.38%
⚡	test_query_rel_one	663.2 ms	501.7 ms	+32.17%
⚡	test_nodemanager_querypeers	1.5 ms	1.3 ms	+21.6%
⚡	test_relationshipmanager_getpeer	160.5 µs	134.2 µs	+19.57%
⚡	test_load_node_to_db_node_schema	67 ms	52.5 ms	+27.58%
⚡	test_get_menu	245.5 ms	188.7 ms	+30.14%
⚡	test_query_one_model	464.9 ms	354 ms	+31.32%
⚡	test_get_schema	328 ms	253 ms	+29.68%

---

_{Comparing infp-313-virtual-relationships (081bd1e) with develop (34ce17e)}

[github-actions]

This PR has been inactive for 2 weeks and has been marked as stale.

If you're still working on this, please:

• Push new commits, or
• Leave a comment to indicate this PR is still active

The stale label will be removed automatically when there's new activity.