= Dependencies & Supply Chain
:project-name: {Project Name}
:language: {Primary language}
:repo-url: {Repository URL – *REMINDER: Provide this for each project*}

== 📦 Dependency Management

This document tracks all dependencies for {project-name}, ensuring **transparency, security, and reproducibility** throughout the supply chain.

== 🎯 Core Principles

1. **Vendoring over fetching**: Critical dependencies are vendored (copied into repo)
2. **Pinning over floating**: Exact versions, no floating ranges (`~`, `^`)
3. **SBOM generation**: Software Bill of Materials for all releases
4. **Supply chain auditing**: SPDX headers on every file
5. **Automated updates**: Dependabot/Renovate with human review

== 📊 Dependency Graph

*REMINDER: Generate dependency graph for your project.*

=== Visualization

[source,bash]
----
# Generate dependency graph
just deps-graph

# Output formats:
# - deps-graph.svg (visual)
# - deps-graph.json (machine-readable)
# - deps-graph.txt (text-based tree)
----

=== Current Dependencies

*REMINDER: List all direct dependencies with versions, licences, and purposes.*

==== Runtime Dependencies

[cols="2,1,1,3"]
|===
| Dependency | Version | Licence | Purpose

| {dependency-1}
| {version}
| {licence}
| {purpose}

| {dependency-2}
| {version}
| {licence}
| {purpose}
|===

==== Build-Time Dependencies

[cols="2,1,1,3"]
|===
| Dependency | Version | Licence | Purpose

| {build-dep-1}
| {version}
| {licence}
| {purpose}
|===

==== Development Dependencies

[cols="2,1,1,3"]
|===
| Dependency | Version | Licence | Purpose

| {dev-dep-1}
| {version}
| {licence}
| {purpose}
|===

== 🔒 Security Posture

=== Vulnerability Scanning

Automated scanning runs on:

- **Every commit**: CI/CD pipeline checks for known vulnerabilities
- **Weekly**: Scheduled scans of entire dependency tree
- **On release**: Full security audit before tagging

[source,bash]
----
# Run security audit locally
just audit-security

# For Ada projects:
# gnatcheck security

# For Rust projects:
# cargo audit

# For Elixir projects:
# mix deps.audit
----

=== Known Vulnerabilities

*REMINDER: Document any known vulnerabilities and mitigation strategies.*

[cols="2,1,1,3"]
|===
| Dependency | CVE | Severity | Mitigation

| None currently
| —
| —
| —
|===

=== Supply Chain Verification

All dependencies are verified via:

1. **SPDX headers**: Every file has origin attribution
2. **Cryptographic hashing**: SHAKE256(M, d) = KECCAK[512] for integrity
3. **Signed releases**: GPG signatures for official releases
4. **SBOM**: link:sbom.json[Software Bill of Materials] generated for each release

== 📜 Licence Compatibility

=== Licence Matrix

{project-name} is dual-licensed under **MIT & Palimpsest v0.8**.

All dependencies must be compatible with at least one of these licences.

[cols="2,1,2"]
|===
| Dependency Licence | Compatible? | Notes

| MIT
| ✅ Yes
| Directly compatible

| Apache-2.0
| ✅ Yes
| Compatible with MIT

| BSD-3-Clause
| ✅ Yes
| Permissive

| GPL-3.0
| ⚠️ Conditional
| Only for development tools, not runtime

| Proprietary
| ❌ No
| Cannot be included
|===

=== Licence Audit

[source,bash]
----
# Audit all dependency licences
just audit-licence

# Generate licence report
just licence-report
----

== 🔄 Update Policy

=== Automated Updates

- **Patch versions**: Auto-merge if tests pass (e.g., 1.2.3 → 1.2.4)
- **Minor versions**: Create MR for human review (e.g., 1.2.3 → 1.3.0)
- **Major versions**: Require manual testing and approval (e.g., 1.2.3 → 2.0.0)

=== Manual Updates

Before updating dependencies manually:

1. **Check release notes**: Understand breaking changes
2. **Test locally**: Ensure compatibility
3. **Update lock file**: Commit updated lock file
4. **Document changes**: Note reason for update in commit message

[source,bash]
----
# Update dependencies
just deps-update

# For Ada projects:
# alr update

# For Rust projects:
# cargo update

# For Elixir projects:
# mix deps.update --all
----

=== Deprecation Warnings

Dependencies flagged for removal:

*REMINDER: List deprecated dependencies and replacement timelines.*

[cols="2,2,2"]
|===
| Deprecated Dependency | Reason | Replacement

| {old-dep}
| {reason}
| {new-dep} (migrate by {date})
|===

== 🏗️ Build Reproducibility

=== Nix Flake

{project-name} uses Nix flakes for hermetic builds:

- **All dependencies pinned** in `flake.lock`
- **Reproducible across machines**: Same inputs → same outputs
- **No network dependencies** during build (after initial fetch)

[source,bash]
----
# Build reproducibly
nix build

# Update flake dependencies
nix flake update

# Check flake status
nix flake check
----

=== Lock Files

*REMINDER: List all lock files used by the project.*

- `flake.lock` (Nix dependencies)
- `Cargo.lock` (Rust dependencies, if applicable)
- `mix.lock` (Elixir dependencies, if applicable)
- `alire.lock` (Ada dependencies, if applicable)

**All lock files are committed to version control.**

== 📦 Vendoring Strategy

=== Vendored Dependencies

Critical dependencies are vendored (copied into the repository) for:

1. **Offline development**: No network required after initial clone
2. **Supply chain security**: No risk of upstream disappearance
3. **Auditability**: Exact code is visible in repository
4. **Stability**: Upstream changes don't break builds

*REMINDER: List vendored dependencies and their locations.*

[cols="2,2,2"]
|===
| Dependency | Version | Vendored Location

| {vendored-dep}
| {version}
| `vendor/{dep-name}/`
|===

=== Vendoring Workflow

[source,bash]
----
# Vendor a new dependency
just vendor-add <dependency>

# Update vendored dependency
just vendor-update <dependency>

# Remove vendored dependency
just vendor-remove <dependency>
----

== 🔗 Dependency Pinning

All dependencies use **exact version pinning**:

❌ **Bad** (floating versions):
[source,toml]
----
[dependencies]
some-crate = "~1.2"  # Matches 1.2.x
another = "^2.0"     # Matches 2.x.x
----

✅ **Good** (exact versions):
[source,toml]
----
[dependencies]
some-crate = "1.2.3"  # Exactly 1.2.3
another = "2.0.5"     # Exactly 2.0.5
----

== 🗺️ Upstream Dependency Tracking

=== Critical Upstream Projects

*REMINDER: List projects you depend on and monitor.*

[cols="2,2,2,2"]
|===
| Project | Current Version | Update Frequency | Contact

| {upstream-1}
| {version}
| {frequency}
| {contact/repo}
|===

=== Monitoring Strategy

- **RSS/Atom feeds**: Subscribe to release announcements
- **GitHub/GitLab watch**: Enable notifications for releases
- **Security mailing lists**: Subscribe to security advisories
- **Automated tools**: Dependabot/Renovate for update PRs

== 📊 SBOM (Software Bill of Materials)

=== Generation

[source,bash]
----
# Generate SBOM
just sbom-generate

# Output: sbom.json (SPDX format)
----

=== SBOM Contents

The SBOM includes:

- All runtime dependencies
- All build-time dependencies
- Exact versions and hashes
- Licence information
- Vulnerability status
- Provenance chains

=== SBOM Publishing

- **Attached to releases**: Every release includes `sbom.json`
- **Publicly accessible**: link:{repo-url}/-/releases[Releases page]
- **Machine-readable**: SPDX 2.3 format

== 🔄 Lifecycle Management

=== End-of-Life Dependencies

When a dependency reaches end-of-life:

1. **Evaluate alternatives**: Find actively maintained replacement
2. **Plan migration**: Document migration path
3. **Set deadline**: Establish timeline for migration
4. **Communicate**: Notify users via CHANGELOG and release notes
5. **Execute**: Migrate and test thoroughly

=== Forking Strategy

If a critical dependency is abandoned:

1. **Fork the repository**: Create organizational fork
2. **Apply security patches**: Fix known vulnerabilities
3. **Minimal maintenance**: Only critical fixes, no new features
4. **Document fork**: Note in DEPENDENCIES.md
5. **Seek replacement**: Continue searching for maintained alternative

== 🚨 Incident Response

=== Dependency Compromise

If a dependency is compromised:

1. **Immediate response**:
   - Remove compromised dependency
   - Revert to last known-good version
   - Notify users via security advisory

2. **Investigation**:
   - Audit all uses of compromised dependency
   - Check for data exfiltration or backdoors
   - Review commit history for malicious changes

3. **Recovery**:
   - Find alternative or fork
   - Apply security patches
   - Update all dependent projects

4. **Communication**:
   - link:{repo-url}/-/security[Security advisory]
   - Email notification to users
   - Post-mortem analysis

== 📚 Additional Resources

- **SBOM Specification**: link:https://spdx.dev/[SPDX]
- **Supply Chain Levels for Software Artefacts**: link:https://slsa.dev/[SLSA]
- **Dependency Confusion**: link:https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610[Article]
- **Software Supply Chain Security**: link:https://www.cisa.gov/supply-chain[CISA guidance]

== 📞 Contact

For dependency-related questions:

- **Security issues**: link:{repo-url}/-/security[Security advisory]
- **Licence questions**: link:{repo-url}/-/issues[Open issue]
- **Update requests**: link:{repo-url}/-/merge_requests[Submit MR]

---

*"Transparency in dependencies is security in production."*

— The Rhodium Standard
