Implement project-scoped networks in Compose plugin

[muandane]

• Introduced support for defining networks in the root of the compose file, allowing for project-scoped subnets named {project}_{network}.
• Updated service definitions to attach to these networks, enhancing container communication via DNS resolution by container names.
• Enhanced the Up, Down, and Run commands to manage network creation and removal, ensuring proper lifecycle handling.
• Added error handling for unsupported network options and external networks, improving user feedback.
• Updated documentation in AGENTS.md and README.md to reflect new networking features and usage examples.

These changes significantly enhance the networking capabilities of the Compose plugin, providing users with more control and flexibility in service communication.

Fixes #57

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for declaring and managing Docker Compose networks in project scope.
  • Networks are automatically created during startup and removed during shutdown.
  • Containers can resolve each other by name within networks.

• Documentation

  • Updated documentation to describe supported network features and limitations.

• Tests

  • Added smoke tests for network creation, membership, and container DNS resolution on macOS 26+.

[coderabbitai]

Warning

Review limit reached

@muandane, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 44 minutes and 27 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3f991dad-260e-482e-b53b-7c9cc7821b21

📥 Commits

Reviewing files that changed from the base of the PR and between 52918a9 and f7fb165.

📒 Files selected for processing (14)

• Sources/ComposeCore/Commands/Down.swift
• Sources/ComposeCore/Commands/DownShutdown.swift
• Sources/ComposeCore/Model/ComposeNetwork.swift
• Sources/ComposeCore/Model/ComposeService+Decode.swift
• Sources/ComposeCore/Model/ComposeService.swift
• Sources/ComposeCore/Parser/ComposeFileMerge.swift
• Sources/ComposeCore/Runtime/NetworkPlanning.swift
• Sources/ComposeCore/Runtime/NetworkRunner.swift
• Sources/compose-verify/TestRunner+Networks.swift
• Sources/compose-verify/TestRunner+NetworksShutdown.swift
• Tests/composeTests/Fixtures/merge/override-network-null.yml
• Tests/composeTests/Fixtures/networks-compose.yml
• Tests/composeTests/Fixtures/networks-null-override-compose.yml
• Tests/composeTests/Fixtures/networks-profile-bad-ref-compose.yml

📝 Walkthrough

Walkthrough

This PR adds complete Docker Compose network support, enabling project-scoped subnets with container-name DNS. Services declare network membership at the service level, networks are created before startup using a {project}_{network} naming scheme, and networks are conditionally removed during shutdown based on whether remaining services still reference them.

Changes

Compose networks feature

Layer / File(s)	Summary
Network types, errors, and contracts Sources/ComposeCore/Model/ComposeNetwork.swift, Sources/ComposeCore/Model/ComposeError.swift, Sources/ComposeCore/Model/ComposeFile.swift, Sources/ComposeCore/Model/ComposeService.swift	ComposeNetwork type holds the external option; seven network-related ComposeError cases cover unsupported external networks, invalid options, undefined references, invalid names, include conflicts, creation failures, and macOS version gating. ComposeFile and ComposeService extend with networks properties.
Network parsing and model propagation Sources/ComposeCore/Model/ComposeNetwork.swift, Sources/ComposeCore/Model/ComposeService+Decode.swift, Sources/ComposeCore/Parser/ComposeFile*.swift, Sources/ComposeCore/Parser/ComposeInclude*.swift	Root and service-level network parsing via ComposeNetworkDecoder; validation rejects external networks and per-network options. Networks propagate through merge, include expansion, and config resolution stages, with include-level conflict detection.
Network planning, validation, and runtime naming Sources/ComposeCore/Runtime/NetworkPlanning.swift, Sources/ComposeCore/Runtime/ServicePlanner*.swift, Sources/ComposeCore/Runtime/ServiceRunMapping.swift	NetworkPlanning validates service network references exist, computes {project}_{logical} runtime names via regex, generates --network <runtimeName> flags per service, and produces a deduplicated sorted plan list. Validation integrates into planner startup and run-plan flows.
Network creation and removal operations Sources/ComposeCore/Runtime/NetworkRunner.swift, Sources/ComposeCore/Runtime/ComposeLabels.swift, Sources/ComposeCore/Runtime/DryRunManifest.swift, Sources/ComposeCore/Runtime/DryRunManifest+Formatting.swift	NetworkRunner.createAll creates missing networks (host-mode and machine-mode paths, macOS 26+ gating); removeProjectNetworks deletes networks by label matching with concurrent deletion and per-network warning handling. Dry-run manifest records create/remove operations with deterministic ordering.
Up command: network planning and creation Sources/ComposeCore/Commands/Up+Planning.swift, Sources/ComposeCore/Commands/Up+DryRun.swift, Sources/ComposeCore/Commands/Up+Startup.swift, Sources/ComposeCore/Commands/Up.swift	Startup plan computes networks plans; DryRunInput and LiveInput carry plans; runDryRun and runLive invoke NetworkRunner.createAll before service orchestration.
Run and Down commands: network operations Sources/ComposeCore/Commands/Run.swift, Sources/ComposeCore/Commands/Down.swift, Sources/ComposeCore/Commands/DownShutdown.swift	Run computes network plans and creates networks before RunSession. Down computes removal plans, records them in dry-run manifest, and removes networks during shutdown; DownShutdown.networkRemovalPlans filters by remaining member services.
Testing, documentation, and fixtures Sources/compose-verify/TestRunner+Networks.swift, Sources/compose-verify/main.swift, README.md, AGENTS.md, Tests/composeTests/Fixtures/networks*.yml, fixtures/network-smoke/compose.yml, scripts/smoke-networks.sh, Makefile	Comprehensive test suite covering parsing, errors, naming, planning, merging, config export, dry-run formatting, and down-removal scenarios. Documentation describes network declarations, attachment, DNS, cleanup, and unsupported features. Multiple fixtures and smoke test validate runtime behavior including container-name cross-service DNS resolution.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• Simplifi-ED/compose#56: Both PRs modify the same core service model and decoding paths (ComposeService, ComposeService+Decode) to add distinct service-level fields, so they share overlapping code regions that may require careful merge conflict handling.

Poem

🐰 A network grows, project-scoped and true,
Services find each other in subnets anew,
DNS whispers container names through the air,
Networks appear, then vanish with care! 🌐

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.71% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Implement project-scoped networks in Compose plugin' directly and clearly summarizes the main objective of the changeset, which is to add comprehensive network support.
Linked Issues check	✅ Passed	The PR implements all in-scope coding requirements from issue #57: parsing root/service networks, creating project-scoped networks before up, attaching containers via --network flags, and comprehensive parser/planner tests via compose-verify.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #57 in-scope objectives. Documentation updates (AGENTS.md, README.md) and build/test infrastructure (Makefile, smoke tests) are necessary supporting changes with no unrelated modifications present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch compose-networks

---

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