feat: MVP Connection model with port-based references (#365)

[ggfevans]

Summary

Add simplified Connection type for port-to-port connections using PlacedPort.id references:

• Connection interface: id, a_port_id, b_port_id, optional label/color
• ConnectionSchema: Zod validation with self-connection rejection (a ≠ b)
• Layout.connections: Optional array for persisting connections
• 20 tests: Schema validation, layout integration, backward compatibility

Design Philosophy

MVP follows YAGNI - no connection classes, statuses, roles, or nested cable properties. Users distinguish cable types via color + label. Structured fields added when there's actual demand.

The deprecated Cable interface (device+interface refs) retained for backward compatibility.

Files Changed

• src/lib/types/index.ts: Connection interface, Layout.connections
• src/lib/schemas/index.ts: ConnectionSchema with validation
• src/tests/connection.test.ts: 20 comprehensive tests

Test Plan

• All 20 connection tests pass
• Full test suite passes (3045 tests)
• Lint passes
• Build passes

Closes #365

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added port-to-port connection capability with optional labels and custom colors
  • Implemented validation to prevent invalid self-connections
  • Maintained backward compatibility with existing cable system

• Tests

  • Added comprehensive test coverage for connection validation and layout scenarios

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Velcome, velcome! Ze pull request introduces a sleek, minimal Connection model for port-to-port relationships, vith new type definitions in src/lib/types/, corresponding Zod schemas in src/lib/schemas/, and integration into ze Layout structure. A comprehensive test suite ensures ze new model vorks vith proper validation and self-connection guards.

Changes

Cohort / File(s)	Summary
Type & Schema Definitions src/lib/types/index.ts, src/lib/schemas/index.ts	Introduced new Connection interface and ConnectionSchema vith fields for id, a_port_id, b_port_id, optional label and color (hex validation). Added connections field (optional array) to Layout and LayoutSchemaBase. Included custom validation guard to prevent self-connections (a_port_id ≠ b_port_id).
Test Suite src/tests/connection.test.ts	New comprehensive test file covering valid connections (minimal fields, optional fields, color formats, unknown field passthrough), invalid connections (missing fields, self-connections, invalid hex colors, oversized labels), and LayoutSchema integration (empty connections, valid/invalid connections arrays, deprecated cables field support).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• feat: Connection Graph Model - Phase 1: Port-Based Architecture #362: Introduces ze port-based Connection model vith a_port_id and b_port_id fields, vhich directly implements ze port ID architecture outlined in zis parent epic.
• feat: Migration from Cable to Connection #371: Ze new Connection type and Layout.connections field enable ze migration pathway for converting legacy Cable records into ze modern Connection format.

Poem

🧛‍♂️ Vhere once ve had cables tangled dark,
Now ports connect vith graceful spark—
No self-bonds vill ze schema allow,
Crimson connections, elegant, vow.
Ze model rises, minimal and bright, 🌙

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title directly reflects the main change: introducing an MVP Connection model with port-based references, which aligns perfectly with the changeset.
Linked Issues check	✅ Passed	The PR fully implements all acceptance criteria from issue #365: Connection interface with required fields, ConnectionSchema with self-connection validation, connections array in Layout, and comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #365 requirements: Connection type definitions, schema validation, Layout integration, backward compatibility, and associated tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 049a376 and 26e8286.

📒 Files selected for processing (3)

• src/lib/schemas/index.ts
• src/lib/types/index.ts
• src/tests/connection.test.ts

🧰 Additional context used

📓 Path-based instructions (1)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx}: Use TypeScript strict mode for all TypeScript files
Use NetBox-compatible field naming with snake_case (e.g., u_height, device_type, form_factor) in data types and storage models

Files:

• src/tests/connection.test.ts
• src/lib/schemas/index.ts
• src/lib/types/index.ts

🧬 Code graph analysis (1)

src/tests/connection.test.ts (2)

src/lib/types/index.ts (1)

• Connection (325-336)

src/lib/schemas/index.ts (2)

• ConnectionSchema (340-358)
• LayoutSchema (574-583)

🔇 Additional comments (12)

src/lib/types/index.ts (3)

317-336: LGTM! Elegant MVP Connection interface.

Ze Connection model is beautifully minimal, exactly as specified in ze issue #365. Ze snake_case naming (a_port_id, b_port_id) correctly follows NetBox conventions, and ze optional fields (label, color) provide just enough flexibility without unnecessary complexity. Vonderful work!

---

338-343: Proper deprecation markers in place.

Ze Cable interface is correctly marked as deprecated vith clear guidance to use Connection instead. Ze JSDoc @deprecated tag vill help developers migrate avay from ze fragile device+interface reference pattern.

---

561-566: Layout.connections integration is vell-executed.

Ze optional connections array integrates smoothly into ze Layout structure, allowing layouts vithout connections to remain valid. Ze deprecated cables field below ensures backward compatibility as required by ze PR objectives.

src/lib/schemas/index.ts (4)

333-358: Excellent ConnectionSchema vith proper self-connection guard!

Ze schema correctly validates all required and optional fields. Ze self-connection refine at lines 355-358 properly prevents ports from connecting to themselves, vith ze error message placed on ze b_port_id path for clear user feedback. Ze passthrough() enables forward compatibility as intended.

---

360-365: Cable deprecation properly documented.

Ze CableSchema is correctly marked deprecated vith clear guidance to use ConnectionSchema instead, maintaining consistency vith ze type definitions.

---

565-566: LayoutSchemaBase correctly extended vith connections.

Ze optional connections array integrates cleanly, allowing layouts to include port-based connections vhile maintaining backward compatibility vith ze deprecated cables field.

---

610-610: ConnectionZod type export follows established patterns.

Ze type export is consistent vith ze existing Zod-inferred types in this file (PlacedPortZod, CableZod, etc.).

src/tests/connection.test.ts (5)

10-81: Comprehensive valid connection test coverage.

Ze valid connection tests thoroughly verify all combinations of required and optional fields, including edge cases like lowercase hex colors. Ze use of safeParse vith conditional type guards demonstrates proper TypeScript practices.

---

83-181: Thorough invalid connection test coverage.

Ze invalid connection tests comprehensively verify all validation rules, including ze critical self-connection guard ("Cannot connect a port to itself"), color format validation, and field length constraints. Excellent negative testing!

---

183-201: Passthrough behavior correctly verified for forward compatibility.

Ze test confirms zat unknown fields are preserved during parsing, ensuring future schema extensions von't break existing data. Zis aligns perfectly vith ze ConnectionSchema's .passthrough() configuration.

---

203-290: Layout integration tests are vell-designed.

Ze tests verify zat connections integrates properly into ze Layout schema, correctly handling optional presence, empty arrays, multiple connections, and element-level validation. Ze test at line 271-290 confirms zat invalid connections in ze array are properly rejected.

---

292-340: Backward compatibility thoroughly verified.

Ze tests confirm zat existing layouts using ze deprecated cables field continue to vork, and zat both cables and connections can coexist in ze same layout. Zis is essential for gradual migration as outlined in ze PR objectives.

---

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