feat: added draft for dependency handling ADR

[rebEllieous]

Closes #167

Summary by CodeRabbit

• Documentation
  • Added architecture documentation describing component dependency management and enforcement for air-gapped deployments, including dependency tracking, resolution strategies, and handling of complex dependency relationships.

[coderabbitai]

Warning

Rate limit exceeded

@rebEllieous has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 51 minutes and 37 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, 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 have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: de48b130-926f-460f-996a-ea52059cb8e4

📥 Commits

Reviewing files that changed from the base of the PR and between a5b0c99 and f591827.

📒 Files selected for processing (1)

• docs/developer-guide/adrs/011-component-dependencies.md

📝 Walkthrough

Walkthrough

A new ADR (ADR 011) proposes modeling OCM ComponentReferences as explicit ComponentVersion dependencies with dependency resolution, locking, and render-gating logic for air-gapped deployments, including API changes, discovery pipeline extensions, release controller behavior, and detailed risk mitigation strategies.

Changes

Component Dependency Design

Layer / File(s)	Summary
Problem and motivation docs/developer-guide/adrs/011-component-dependencies.md	Current Solar discovery discards OCM ComponentReferences. The proposal is to represent direct and transitive OCM references as explicit ComponentVersion dependencies to enable pre-flight determinism and dependency validation for air-gapped edge deployments.
Proposed API and system changes docs/developer-guide/adrs/011-component-dependencies.md	ComponentVersionSpec gains a Dependencies field with version constraints and optional cluster-wide semantics. Discovery extracts and emits OCM references; an API writer upserts dependency records; a release controller gates rendering until dependencies are resolved and themselves rendered; a lock resolver evaluates SemVer constraints against locally available ComponentVersion resources.
Risk handling and detailed concerns docs/developer-guide/adrs/011-component-dependencies.md	Addresses lock-file determinism vs exact pinning, diamond dependency conflicts with clusterWide constraints, race conditions for shared dependencies, discovery cycle detection, catalog layering and RBAC separation, cross-namespace reference counting and garbage collection requirements, and infrastructure registry placement options.
Consequences and tradeoffs docs/developer-guide/adrs/011-component-dependencies.md	Positive outcomes include dependency visibility, SemVer determinism without external registry calls, and informative render gating. Negative impacts include expanded API surface, increased pipeline and controller complexity, new lock-resolver control loop, and operational rollout considerations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• trevex
• olzemal

Poem

🐰 A diagram of dependencies drawn with care,
ComponentVersions linked through the air,
Lock files ensuring we know what we'll find,
In air-gapped clusters, no surprises of any kind,
Discovery's gaze now sees what lies ahead! 📦✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is minimal and only contains 'Closes #167' without addressing the required template sections.	Complete the description template by adding 'What', 'Why', 'Testing', and 'Notes for reviewers' sections with relevant details.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the primary change: adding a draft ADR document for dependency handling.
Linked Issues check	✅ Passed	The PR successfully delivers the spike objective by providing a comprehensive ADR document that gathers and evaluates approaches for dependency handling.
Out of Scope Changes check	✅ Passed	Only a new ADR documentation file was added, which is directly aligned with the spike objective to produce guidance on dependency handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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 feature/167-dependency-handling

---

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

[coderabbitai]

Actionable comments posted: 3

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

Inline comments:
In `@docs/developer-guide/adrs/011-component-dependencies.md`:
- Line 164: Fix the spelling typo in the ADR text: replace “regitry” with
“registry” in the sentence referencing ComponentVersions and ReferenceGrant (and
ADR-005) so it reads "...a different namespace / registry (e.g. the public
catalog from ADR-005)"; update the string in
docs/developer-guide/adrs/011-component-dependencies.md where that sentence
appears.
- Line 224: Replace the typo "rergistries" with "registries" in the ADR sentence
that currently reads "only the local rergistries exist" so the user-facing text
correctly states "only the local registries exist"; ensure the spelling change
is applied where that phrase appears in the ADR content.
- Line 191: The table row for pkg/discovery/apiwriter/ incorrectly references
spec.cluster-wide; update the text to align with the actual schema by
referencing the clusterWide field on ComponentDependency entries (or otherwise
reflect the modeled field name), e.g., indicate that apiwriter must set
ComponentVersion.spec.dependencies and each ComponentDependency.clusterWide and
spec.layer as appropriate so the documentation matches the code model.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d19ba9e6-d1bf-4eaf-a2b7-1ba328b637c5

📥 Commits

Reviewing files that changed from the base of the PR and between 94fff12 and a5b0c99.

📒 Files selected for processing (1)

• docs/developer-guide/adrs/011-component-dependencies.md