# sublime_pkg_tools - Implementation Plan

**Status**: 📋 Ready for Implementation  
**Version**: 1.0  
**Based on**: CONCEPT.md v1.0  
**Last Updated**: 2024-01-15

---

## Table of Contents

1. [Executive Summary](#executive-summary)
2. [Priority Analysis](#priority-analysis)
3. [Dependency Graph](#dependency-graph)
4. [Implementation Phases](#implementation-phases)
5. [Module Structure](#module-structure)
6. [Quality Standards](#quality-standards)
7. [Testing Strategy](#testing-strategy)
8. [Documentation Requirements](#documentation-requirements)
9. [Milestones & Timeline](#milestones--timeline)
10. [Risk Assessment](#risk-assessment)

---

## Executive Summary

### Project Overview

`sublime_pkg_tools` is a comprehensive library for changeset-based package version management in Node.js projects. The implementation is divided into **4 major phases** across **6 core modules**, following strict quality standards (100% test coverage, 100% clippy compliance, 100% documentation).

### Key Success Criteria

- ✅ All modules pass clippy without warnings
- ✅ 100% test coverage (unit + integration)
- ✅ 100% API documentation with examples
- ✅ Zero `unwrap()`, `expect()`, `todo!()`, `panic!()`, `unimplemented!()`
- ✅ All errors implement `AsRef<str>`
- ✅ Internal visibility uses `pub(crate)` consistently
- ✅ Follows patterns from `sublime_standard_tools`

### Estimated Timeline

- **Phase 1**: 2-3 weeks (Foundation)
- **Phase 2**: 3-4 weeks (Core Functionality)
- **Phase 3**: 2-3 weeks (Advanced Features)
- **Phase 4**: 1-2 weeks (Integration & Polish)
- **Total**: 8-12 weeks

---

## Priority Analysis

### Critical Path (Must Have - Phase 1 & 2)

1. **Configuration System** - Foundation for all modules
2. **Error Handling** - Required by everything
3. **Core Types** - Data structures used across modules
4. **Versioning** - Core business logic
5. **Changesets** - Core workflow management

### High Priority (Phase 2 & 3)

6. **Changes Analysis** - Required for intelligent versioning
7. **Dependency Graph** - Required for propagation
8. **Changelog Generation** - Release workflow completion

### Medium Priority (Phase 3 & 4)

9. **Dependency Upgrades** - Enhancement feature
10. **Audit** - Aggregation and reporting

### Priority Rationale

```
Configuration & Errors (P0)
    ↓
Core Types & Version Resolution (P1)
    ↓
Changesets + Changes Analysis (P1-P2)
    ↓
Changelog Generation (P2)
    ↓
Upgrades + Audit (P3)
```

**Why this order:**
- **Config first**: Everything needs configuration
- **Errors early**: Required by all modules for proper error handling
- **Types & Versioning**: Core business logic that others depend on
- **Changesets**: Central to the workflow
- **Changes**: Provides intelligence for versioning decisions
- **Changelog**: Completes the release workflow
- **Upgrades & Audit**: Enhancement features that aggregate others

---

## Dependency Graph

### Module Dependencies

```mermaid
graph TD
    Config[Configuration]
    Error[Error Handling]
    Types[Core Types]
    
    Version[Versioning]
    Changeset[Changesets]
    Changes[Changes Analysis]
    Changelog[Changelog Generation]
    Upgrades[Dependency Upgrades]
    Audit[Audit & Health]
    
    Config --> Error
    Config --> Types
    
    Error --> Version
    Error --> Changeset
    Error --> Changes
    Error --> Changelog
    Error --> Upgrades
    Error --> Audit
    
    Types --> Version
    Types --> Changeset
    Types --> Changes
    
    Version --> Changelog
    Version --> Audit
    
    Changeset --> Changes
    Changeset --> Changelog
    Changeset --> Audit
    
    Changes --> Changelog
    Changes --> Audit
    
    Changelog --> Audit
    
    Upgrades --> Changeset
    Upgrades --> Audit
    
    Version -.-> Upgrades
    Changes -.-> Upgrades
```

### External Dependencies

```
sublime_pkg_tools
    ↓
├─ sublime_standard_tools (filesystem, monorepo, config)
├─ sublime_git_tools (git operations)
├─ package-json (parsing)
├─ semver (version comparison)
├─ regex (conventional commits)
└─ tokio, serde, chrono, thiserror (standard)
```

---

## Implementation Phases

## Phase 1: Foundation (Weeks 1-3)

### Objective
Establish the foundational infrastructure that all other modules depend on.

### Deliverables

#### 1.1 Project Setup & Structure
- [ ] Initialize crate structure following `sublime_standard_tools` patterns
- [ ] Configure `Cargo.toml` with dependencies
- [ ] Setup `lib.rs` with crate-level documentation and clippy rules
- [ ] Create `mod.rs` files for each module (export-only, no implementation)

**Files to create:**
```
crates/pkg/
├── Cargo.toml
├── src/
│   ├── lib.rs                    # Crate root with version()
│   ├── config/
│   │   └── mod.rs               # Export only
│   ├── error/
│   │   └── mod.rs               # Export only
│   └── types/
│       └── mod.rs               # Export only
```

#### 1.2 Error Handling Module
- [ ] Define `Error` enum with all error variants
- [ ] Implement `AsRef<str>` for all error types
- [ ] Create domain-specific error types:
  - [ ] `ConfigError`
  - [ ] `VersionError`
  - [ ] `ChangesetError`
  - [ ] `ChangesError`
  - [ ] `ChangelogError`
  - [ ] `UpgradeError`
  - [ ] `AuditError`
- [ ] Implement error context and recovery strategies
- [ ] Write comprehensive error tests

**Files:**
```
src/error/
├── mod.rs                       # Exports and Error enum
├── config.rs                    # ConfigError
├── version.rs                   # VersionError
├── changeset.rs                 # ChangesetError
├── changes.rs                   # ChangesError
├── changelog.rs                 # ChangelogError
├── upgrade.rs                   # UpgradeError
├── audit.rs                     # AuditError
└── tests.rs                     # Error tests
```

**Quality Gates:**
- ✅ All errors implement `Display`, `Debug`, `Error`
- ✅ All errors implement `AsRef<str>`
- ✅ 100% test coverage on error creation and conversion
- ✅ Clippy clean

#### 1.3 Configuration System
- [ ] Define `PackageToolsConfig` struct
- [ ] Implement sub-configs:
  - [ ] `ChangesetConfig`
  - [ ] `VersionConfig`
  - [ ] `DependencyConfig`
  - [ ] `GitConfig`
  - [ ] `ChangelogConfig`
  - [ ] `UpgradeConfig`
  - [ ] `AuditConfig`
- [ ] Implement `Configurable` trait from standard tools
- [ ] TOML/YAML/JSON deserialization
- [ ] Environment variable overrides
- [ ] Default implementations
- [ ] Configuration validation

**Files:**
```
src/config/
├── mod.rs                       # PackageToolsConfig export
├── types.rs                     # Main config structs
├── changeset.rs                 # ChangesetConfig
├── version.rs                   # VersionConfig + DependencyConfig
├── git.rs                       # GitConfig
├── changelog.rs                 # ChangelogConfig
├── upgrade.rs                   # UpgradeConfig
├── audit.rs                     # AuditConfig
├── validation.rs                # Config validation logic
└── tests.rs                     # Config tests
```

**Quality Gates:**
- ✅ All configs have sensible defaults
- ✅ Validation logic prevents invalid configurations
- ✅ Environment variables work correctly
- ✅ Integration with `sublime_standard_tools::config::ConfigManager`
- ✅ 100% test coverage

#### 1.4 Core Types
- [ ] Define `Version` struct with semver parsing
- [ ] Define `VersionBump` enum
- [ ] Define `VersioningStrategy` enum
- [ ] Define `PackageInfo` struct
- [ ] Define `Changeset` struct
- [ ] Implement serialization/deserialization
- [ ] Implement Display traits

**Files:**
```
src/types/
├── mod.rs                       # Export all types
├── version.rs                   # Version, VersionBump, VersioningStrategy
├── package.rs                   # PackageInfo
├── changeset.rs                 # Changeset, ArchivedChangeset
├── dependency.rs                # DependencyType, etc.
└── tests.rs                     # Type tests
```

**Quality Gates:**
- ✅ All types implement required traits (Clone, Debug, Serialize, Deserialize)
- ✅ Version parsing handles all semver cases
- ✅ 100% test coverage

### Phase 1 Exit Criteria
- ✅ All foundation modules compile
- ✅ Clippy passes without warnings
- ✅ 100% test coverage on all Phase 1 modules
- ✅ Documentation complete with examples
- ✅ Integration tests pass with `sublime_standard_tools`

---

## Phase 2: Core Functionality (Weeks 4-7)

### Objective
Implement the core business logic for versioning and changesets.

### Deliverables

#### 2.1 Versioning Module
- [ ] Implement `VersionResolver` with monorepo/single-package detection
- [ ] Version resolution with dry-run support
- [ ] Dependency propagation logic
- [ ] Circular dependency detection
- [ ] Snapshot version generation
- [ ] Package.json reading/writing using `sublime_standard_tools`

**Files:**
```
src/version/
├── mod.rs                       # Export VersionResolver
├── resolver.rs                  # VersionResolver implementation
├── resolution.rs                # VersionResolution types
├── propagation.rs               # Dependency propagation logic
├── graph.rs                     # DependencyGraph
├── snapshot.rs                  # Snapshot version generation
└── tests/
    ├── mod.rs
    ├── resolver_tests.rs
    ├── propagation_tests.rs
    └── snapshot_tests.rs
```

**Key APIs:**
```rust
impl VersionResolver {
    pub async fn new(workspace_root: &Path, config: VersionConfig) -> Result<Self>;
    pub async fn resolve_versions(&self, changeset: &Changeset) -> Result<VersionResolution>;
    pub async fn apply_versions(&self, changeset: &Changeset, dry_run: bool) -> Result<ApplyResult>;
}
```

**Quality Gates:**
- ✅ Handles both monorepo and single-package
- ✅ Circular dependency detection works correctly
- ✅ Propagation follows configured rules
- ✅ Dry-run mode doesn't modify files
- ✅ Rollback on partial failure
- ✅ 100% test coverage with mock filesystem

#### 2.2 Changesets Module
- [ ] Implement `ChangesetManager` for CRUD operations
- [ ] File-based storage with `FileSystemManager`
- [ ] Changeset history and archiving
- [ ] Git integration for commit detection
- [ ] Changeset validation

**Files:**
```
src/changeset/
├── mod.rs                       # Export ChangesetManager
├── manager.rs                   # ChangesetManager implementation
├── storage.rs                   # ChangesetStorage trait + FileBasedStorage
├── history.rs                   # ChangesetHistory
├── git_integration.rs           # Git commit detection
└── tests/
    ├── mod.rs
    ├── manager_tests.rs
    ├── storage_tests.rs
    └── history_tests.rs
```

**Key APIs:**
```rust
impl ChangesetManager {
    pub async fn create(&self, branch: &str, bump: VersionBump) -> Result<Changeset>;
    pub async fn load(&self, branch: &str) -> Result<Changeset>;
    pub async fn update(&self, branch: &str, updates: ChangesetUpdate) -> Result<UpdateSummary>;
    pub async fn add_commits_from_git(&self, branch: &str, commit_range: &str) -> Result<UpdateSummary>;
    pub async fn archive(&self, branch: &str, release_info: ReleaseInfo) -> Result<()>;
}
```

**Quality Gates:**
- ✅ Atomic file operations
- ✅ Concurrent access handling
- ✅ Git integration works correctly
- ✅ Archive/history queryable
- ✅ 100% test coverage

#### 2.3 Changes Analysis Module
- [ ] Implement `ChangesAnalyzer` with git integration
- [ ] File-to-package mapping
- [ ] Commit-to-package association
- [ ] Working directory analysis
- [ ] Commit range analysis
- [ ] Version preview calculation

**Files:**
```
src/changes/
├── mod.rs                       # Export ChangesAnalyzer
├── analyzer.rs                  # ChangesAnalyzer implementation
├── report.rs                    # ChangesReport types
├── package_changes.rs           # PackageChanges
├── file_change.rs               # FileChange types
├── commit_info.rs               # CommitInfo
├── mapping.rs                   # File-to-package mapping
├── stats.rs                     # Statistics calculation
└── tests/
    ├── mod.rs
    ├── analyzer_tests.rs
    └── mapping_tests.rs
```

**Key APIs:**
```rust
impl ChangesAnalyzer {
    pub async fn new(workspace_root: PathBuf) -> Result<Self>;
    pub async fn analyze_working_directory(&self) -> Result<ChangesReport>;
    pub async fn analyze_commit_range(&self, base: &str, head: &str) -> Result<ChangesReport>;
    pub async fn analyze_with_versions(&self, base: &str, head: &str, changeset: &Changeset) -> Result<ChangesReport>;
}
```

**Quality Gates:**
- ✅ Correctly maps files to packages in monorepo
- ✅ Handles multi-package commits
- ✅ Version calculation accurate
- ✅ Works with both staged and unstaged changes
- ✅ 100% test coverage with mock git repo

### Phase 2 Exit Criteria
- ✅ Core versioning workflow complete
- ✅ Changesets create, update, archive correctly
- ✅ Changes analysis provides accurate package information
- ✅ Integration between modules works
- ✅ All quality gates passed
- ✅ Documentation complete

---

## Phase 3: Advanced Features (Weeks 8-10)

### Objective
Implement changelog generation and dependency upgrades.

### Deliverables

#### 3.1 Changelog Generation Module
- [ ] Implement `ChangelogGenerator`
- [ ] Conventional commits parser
- [ ] Keep a Changelog formatter
- [ ] Custom template support
- [ ] Existing changelog parser
- [ ] Git tag detection and version comparison
- [ ] Merge commit message generation

**Files:**
```
src/changelog/
├── mod.rs                       # Export ChangelogGenerator
├── generator.rs                 # ChangelogGenerator implementation
├── changelog.rs                 # Changelog types
├── section.rs                   # ChangelogSection
├── entry.rs                     # ChangelogEntry
├── conventional.rs              # ConventionalCommit parser
├── parser.rs                    # Existing changelog parser
├── formatter/
│   ├── mod.rs
│   ├── keep_a_changelog.rs
│   ├── conventional.rs
│   └── custom.rs
└── tests/
    ├── mod.rs
    ├── generator_tests.rs
    ├── conventional_tests.rs
    └── formatter_tests.rs
```

**Key APIs:**
```rust
impl ChangelogGenerator {
    pub async fn new(workspace_root: PathBuf, config: ChangelogConfig) -> Result<Self>;
    pub async fn generate_for_version(&self, package: Option<&str>, version: &str, prev: Option<&str>) -> Result<Changelog>;
    pub async fn generate_from_changeset(&self, changeset: &Changeset, resolution: &VersionResolution) -> Result<Vec<GeneratedChangelog>>;
    pub async fn update_changelog(&self, path: &Path, changelog: &Changelog, dry_run: bool) -> Result<String>;
}

impl ConventionalCommit {
    pub fn parse(message: &str) -> Result<Self, ParseError>;
    pub fn section_type(&self) -> SectionType;
    pub fn extract_references(&self) -> Vec<String>;
}
```

**Quality Gates:**
- ✅ Conventional commit parsing handles all cases
- ✅ Breaking change detection accurate
- ✅ Multiple formats supported
- ✅ Merge commit messages generated correctly
- ✅ 100% test coverage

#### 3.2 Dependency Upgrades Module
- [ ] Implement `UpgradeManager`
- [ ] Registry client with .npmrc support
- [ ] Upgrade detection with version classification
- [ ] Dry-run and apply with rollback
- [ ] Automatic changeset creation
- [ ] Concurrent registry queries

**Files:**
```
src/upgrade/
├── mod.rs                       # Export UpgradeManager
├── manager.rs                   # UpgradeManager implementation
├── registry/
│   ├── mod.rs
│   ├── client.rs               # RegistryClient
│   ├── npmrc.rs                # .npmrc parsing
│   └── metadata.rs             # PackageMetadata types
├── detection.rs                 # Upgrade detection
├── apply.rs                     # Apply upgrades
├── backup.rs                    # Backup and rollback
├── types.rs                     # UpgradePreview, etc.
└── tests/
    ├── mod.rs
    ├── manager_tests.rs
    ├── registry_tests.rs
    └── apply_tests.rs
```

**Key APIs:**
```rust
impl UpgradeManager {
    pub async fn new(workspace_root: PathBuf, config: UpgradeConfig) -> Result<Self>;
    pub async fn detect_upgrades(&self, options: DetectionOptions) -> Result<UpgradePreview>;
    pub async fn apply_upgrades(&self, selection: UpgradeSelection, dry_run: bool) -> Result<UpgradeResult>;
    pub async fn rollback_last(&self) -> Result<Vec<PathBuf>>;
}
```

**Quality Gates:**
- ✅ Registry queries work (with mock server for tests)
- ✅ .npmrc parsing correct
- ✅ Backup/rollback reliable
- ✅ Automatic changeset creation
- ✅ 100% test coverage

### Phase 3 Exit Criteria
- ✅ Changelog generation works for all formats
- ✅ Dependency upgrades detect and apply correctly
- ✅ Integration with changesets works
- ✅ All quality gates passed

---

## Phase 4: Integration & Polish (Weeks 11-12)

### Objective
Complete the audit module, integration testing, and final polish.

### Deliverables

#### 4.1 Audit Module
- [ ] Implement `AuditManager` aggregating all modules
- [ ] Upgrade audit section
- [ ] Dependency audit section
- [ ] Breaking changes audit section
- [ ] Categorization section
- [ ] Version consistency section
- [ ] Health score calculation
- [ ] Report formatting (Markdown, JSON)

**Files:**
```
src/audit/
├── mod.rs                       # Export AuditManager
├── manager.rs                   # AuditManager implementation
├── report.rs                    # AuditReport types
├── sections/
│   ├── mod.rs
│   ├── upgrades.rs
│   ├── dependencies.rs
│   ├── breaking_changes.rs
│   ├── categorization.rs
│   └── version_consistency.rs
├── issue.rs                     # AuditIssue types
├── formatter.rs                 # Report formatters
├── health_score.rs              # Health score calculation
└── tests/
    ├── mod.rs
    ├── manager_tests.rs
    └── sections_tests.rs
```

**Key APIs:**
```rust
impl AuditManager {
    pub async fn new(workspace_root: PathBuf, config: AuditConfig) -> Result<Self>;
    pub async fn run_audit(&self) -> Result<AuditReport>;
    pub async fn audit_upgrades(&self) -> Result<UpgradeAuditSection>;
    pub async fn audit_dependencies(&self) -> Result<DependencyAuditSection>;
    pub async fn categorize_dependencies(&self) -> Result<DependencyCategorization>;
}
```

**Quality Gates:**
- ✅ Aggregates data from all modules correctly
- ✅ Health score calculation accurate
- ✅ Report formats valid (Markdown, JSON)
- ✅ 100% test coverage

#### 4.2 Integration Testing
- [ ] End-to-end workflow tests
- [ ] Monorepo integration tests
- [ ] Single-package integration tests
- [ ] Cross-module integration tests
- [ ] Performance benchmarks

**Files:**
```
tests/
├── integration/
│   ├── mod.rs
│   ├── workflow_tests.rs       # Full release workflow
│   ├── monorepo_tests.rs       # Monorepo scenarios
│   ├── single_package_tests.rs # Single package scenarios
│   └── upgrade_workflow_tests.rs
├── fixtures/
│   ├── monorepo_sample/
│   └── single_package_sample/
└── common/
    ├── mod.rs
    └── test_helpers.rs
```

#### 4.3 Documentation & Examples
- [ ] Complete API documentation
- [ ] Usage examples for each module
- [ ] Integration examples
- [ ] Migration guides
- [ ] Performance notes

**Files:**
```
examples/
├── 01_basic_changeset.rs
├── 02_version_resolution.rs
├── 03_changelog_generation.rs
├── 04_dependency_upgrades.rs
├── 05_audit_report.rs
└── 06_full_release_workflow.rs

docs/
├── guides/
│   ├── getting-started.md
│   ├── monorepo-guide.md
│   └── ci-cd-integration.md
└── architecture/
    ├── overview.md
    └── module-interactions.md
```

### Phase 4 Exit Criteria
- ✅ Audit module complete
- ✅ All integration tests pass
- ✅ Documentation complete
- ✅ Examples working
- ✅ Performance acceptable
- ✅ Ready for production use

---

## Module Structure

### File Organization Pattern

Following `sublime_standard_tools` conventions:

```
src/
├── lib.rs                          # Crate root, version(), clippy rules
├── config/
│   ├── mod.rs                      # Exports only
│   ├── types.rs                    # Core config types
│   ├── [domain].rs                 # Domain configs
│   ├── validation.rs               # Validation logic
│   └── tests.rs                    # Tests
├── error/
│   ├── mod.rs                      # Error enum + exports
│   ├── [domain].rs                 # Domain errors
│   └── tests.rs                    # Error tests
├── types/
│   ├── mod.rs                      # Type exports
│   ├── [type_group].rs             # Related types
│   └── tests.rs                    # Type tests
├── [module]/
│   ├── mod.rs                      # Module exports
│   ├── [main_struct].rs            # Primary implementation
│   ├── [supporting].rs             # Supporting types/logic
│   └── tests/                      # Module tests
│       ├── mod.rs
│       └── [test_category].rs
└── tests/                          # Integration tests (separate)
```

### Visibility Rules

```rust
// Public API - exported from crate
pub struct PublicType { ... }
pub fn public_api() { ... }

// Internal to crate - shared between modules
pub(crate) struct InternalType { ... }
pub(crate) fn internal_helper() { ... }

// Private to module
struct PrivateType { ... }
fn private_helper() { ... }

// Private to struct (if fields need encapsulation)
pub struct TypeWithPrivateFields {
    pub(crate) shared_field: String,  // Accessible within crate
    private_field: String,             // Only within module
}
```

### mod.rs Pattern

```rust
//! # Module Name
//!
//! ## What
//! Brief description of module purpose
//!
//! ## How
//! How the module achieves its purpose
//!
//! ## Why
//! Why this design was chosen

// Internal modules
mod implementation;
mod supporting_types;

#[cfg(test)]
mod tests;

// Re-exports (public API)
pub use implementation::{PublicStruct, PublicTrait};
pub use supporting_types::PublicEnum;

// Internal re-exports (for crate use)
pub(crate) use implementation::InternalHelper;
```

### lib.rs Pattern

```rust
//! # `sublime_pkg_tools`
//!
//! ## What
//! Comprehensive package management toolkit for Node.js projects
//!
//! ## How
//! [Architecture description]
//!
//! ## Why
//! [Rationale]
//!
//! ## Quick Start
//! [Examples]

#![doc = include_str!("../CONCEPT.md")]
#![warn(missing_docs)]
#![warn(rustdoc::missing_crate_level_docs)]
#![deny(unused_must_use)]
#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![deny(clippy::todo)]
#![deny(clippy::unimplemented)]
#![deny(clippy::panic)]

pub mod audit;
pub mod changeset;
pub mod changelog;
pub mod changes;
pub mod config;
pub mod error;
pub mod types;
pub mod upgrade;
pub mod version;

/// Version of the crate
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Returns the version of the crate
#[must_use]
pub fn version() -> &'static str {
    VERSION
}
```

---

## Quality Standards

### Clippy Rules (Mandatory)

All code must pass these clippy rules:

```rust
#![warn(missing_docs)]
#![warn(rustdoc::missing_crate_level_docs)]
#![deny(unused_must_use)]
#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![deny(clippy::todo)]
#![deny(clippy::unimplemented)]
#![deny(clippy::panic)]
```

**Enforcement:**
```bash
cargo clippy --all-targets --all-features -- -D warnings
```

### Code Quality Checklist

For every module/file:

- [ ] Module-level documentation (What, How, Why)
- [ ] All public items documented with examples
- [ ] All functions have doc comments
- [ ] All structs/enums documented with field descriptions
- [ ] Examples in documentation compile and run
- [ ] No `unwrap()` or `expect()` calls
- [ ] No `todo!()`, `unimplemented!()`, `panic!()`
- [ ] All `Result` types used correctly
- [ ] Errors implement `AsRef<str>`
- [ ] Internal types use `pub(crate)`
- [ ] Tests in separate files/modules

### Error Handling Pattern

```rust
/// Domain-specific error type
#[derive(Debug, Clone, thiserror::Error)]
pub enum DomainError {
    #[error("Specific error: {reason}")]
    SpecificError { reason: String },
    
    #[error("Nested error: {0}")]
    Nested(#[from] OtherError),
}

impl AsRef<str> for DomainError {
    fn as_ref(&self) -> &str {
        match self {
            DomainError::SpecificError { .. } => "DomainError::SpecificError",
            DomainError::Nested(_) => "DomainError::Nested",
        }
    }
}

pub type DomainResult<T> = Result<T, DomainError>;
```

### Documentation Pattern

```rust
/// Brief one-line description
///
/// Detailed description explaining:
/// - What this does
/// - When to use it
/// - Important considerations
///
/// # Arguments
///
/// * `arg1` - Description of first argument
/// * `arg2` - Description of second argument
///
/// # Returns
///
/// Description of return value
///
/// # Errors
///
/// This function will return an error if:
/// - Condition 1
/// - Condition 2
///
/// # Examples
///
/// ```
/// use sublime_pkg_tools::module::Function;
///
/// let result = Function::new("value")?;
/// assert_eq!(result.field, "value");
/// ```
///
/// # Panics
///
/// This function will panic if... (only if unavoidable)
pub fn function_name(arg1: &str, arg2: usize) -> Result<Type, Error> {
    // Implementation
}
```

---

## Testing Strategy

### Test Organization

```
src/
└── module/
    ├── mod.rs
    ├── implementation.rs
    └── tests/
        ├── mod.rs              # Test module exports
        ├── unit_tests.rs       # Unit tests
        └── integration_tests.rs # Module integration tests

tests/                          # Crate-level integration tests
├── integration/
│   ├── mod.rs
│   └── workflow_tests.rs
└── fixtures/
    └── test_data/
```

### Test Coverage Requirements

**100% coverage on:**
- All public APIs
- All error paths
- All configuration variations
- All edge cases

**Tools:**
```bash
# Install tarpaulin
cargo install cargo-tarpaulin

# Run coverage
cargo tarpaulin --out Html --output-dir coverage/ --all-features

# Must achieve 100% coverage
```

### Test Categories

#### Unit Tests
- Test individual functions/methods
- Mock external dependencies
- Fast execution (<1ms per test)
- Located in `tests/` submodule

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_function_success() {
        let result = function_name("input", 42);
        assert!(result.is_ok());
    }

    #[test]
    fn test_function_error() {
        let result = function_name("", 0);
        assert!(result.is_err());
    }
}
```

#### Integration Tests
- Test module interactions
- Use real filesystem (temp directories)
- Use mock git repositories
- Located in `tests/` directory

```rust
#[tokio::test]
async fn test_full_workflow() {
    let temp_dir = tempfile::tempdir().unwrap();
    // Setup
    // Execute workflow
    // Assert results
}
```

#### Property-Based Tests
- Use `proptest` for property testing
- Test invariants across random inputs
- Especially for versioning and parsing logic

```rust
use proptest::prelude::*;

proptest! {
    #[test]
    fn test_version_parsing(s in "\\d+\\.\\d+\\.\\d+") {
        let version = Version::parse(&s);
        assert!(version.is_ok());
    }
}
```

### Test Data Management

```
tests/fixtures/
├── monorepo/
│   ├── package.json
│   ├── packages/
│   │   ├── pkg1/package.json
│   │   └── pkg2/package.json
│   └── .changesets/
├── single-package/
│   └── package.json
└── configs/
    ├── valid-config.toml
    └── invalid-config.toml
```

### Mock Implementations

Create mock implementations for external dependencies:

```rust
// Mock filesystem for tests
pub(crate) struct MockFileSystem {
    files: HashMap<PathBuf, String>,
}

impl AsyncFileSystem for MockFileSystem {
    async fn read_file_string(&self, path: &Path) -> Result<String> {
        self.files.get(path).cloned()
            .ok_or_else(|| Error::FileNotFound)
    }
    // ... other methods
}

// Mock git repository
pub(crate) struct MockGitRepository {
    commits: Vec<MockCommit>,
}

// Mock registry for upgrade tests
pub(crate) struct MockRegistry {
    packages: HashMap<String, PackageMetadata>,
}
```

---

## Documentation Requirements

### API Documentation (100%)

Every public item must have:
- Summary line
- Detailed description
- Arguments/fields documentation
- Return value description
- Error conditions
- At least one working example
- Links to related items

### Module Documentation

Every module must have:
- What: Purpose and responsibility
- How: Implementation approach
- Why: Design decisions and rationale
- Examples: Usage patterns

### Crate Documentation

`lib.rs` must include:
- Overview of the crate
- Architecture diagram
- Quick start guide
- Links to modules
- Common workflows

### External Documentation

Create in `docs/` directory:
- Getting Started guide
- Architecture overview
- Monorepo guide
- CI/CD integration guide
- Migration guides
- Troubleshooting guide

### Examples

Create runnable examples in `examples/`:
- Basic usage for each module
- Integration patterns
- Full workflows
- Edge cases

Each example must:
- Be self-contained
- Include comments explaining each step
- Show error handling
- Demonstrate best practices

---

## Milestones & Timeline

### Milestone 1: Foundation Complete (End of Week 3)

**Deliverables:**
- [ ] Project structure established
- [ ] Error handling module complete
- [ ] Configuration system complete
- [ ] Core types defined
- [ ] All Phase 1 quality gates passed

**Success Criteria:**
- ✅ Clippy clean
- ✅ 100% test coverage on foundation modules
- ✅ Documentation complete
- ✅ Can load configuration from files
- ✅ All errors implement `AsRef<str>`

### Milestone 2: Core Functionality (End of Week 7)

**Deliverables:**
- [ ] Versioning module complete
- [ ] Changesets module complete
- [ ] Changes analysis module complete
- [ ] Integration between modules working
- [ ] All Phase 2 quality gates passed

**Success Criteria:**
- ✅ Can create and manage changesets
- ✅ Version resolution works for monorepo and single-package
- ✅ Dependency propagation correct
- ✅ Changes analysis accurate
- ✅ Dry-run mode works
- ✅ Integration tests pass

### Milestone 3: Advanced Features (End of Week 10)

**Deliverables:**
- [ ] Changelog generation complete
- [ ] Dependency upgrades complete
- [ ] All Phase 3 quality gates passed

**Success Criteria:**
- ✅ Conventional commits parsed correctly
- ✅ Changelogs generated in multiple formats
- ✅ Dependency upgrades detect and apply
- ✅ Registry integration works
- ✅ Automatic changeset creation

### Milestone 4: Production Ready (End of Week 12)

**Deliverables:**
- [ ] Audit module complete
- [ ] All integration tests pass
- [ ] Documentation complete
- [ ] Examples working
- [ ] Performance benchmarks meet targets
- [ ] All Phase 4 quality gates passed

**Success Criteria:**
- ✅ Health checks comprehensive
- ✅ 100% test coverage overall
- ✅ All clippy rules pass
- ✅ Documentation 100%
- ✅ Ready for v1.0.0 release

---

## Risk Assessment

### High Risk Items

#### 1. Dependency Graph Circular Detection
**Risk**: Complex algorithm, edge cases
**Mitigation**:
- Implement early in Phase 2
- Extensive testing with various graph structures
- Review algorithm with team
- Property-based testing

#### 2. Git Integration Complexity
**Risk**: Different git states, merge conflicts
**Mitigation**:
- Use proven `sublime_git_tools` crate
- Comprehensive test cases
- Handle all git states explicitly
- Clear error messages

#### 3. Registry API Changes
**Risk**: External APIs may change
**Mitigation**:
- Version pinning
- Graceful degradation
- Retry logic with exponential backoff
- Comprehensive error handling

#### 4. Performance in Large Monorepos
**Risk**: Slow operations with many packages
**Mitigation**:
- Early performance testing
- Concurrent operations where possible
- Caching strategies
- Benchmark suite

### Medium Risk Items

#### 1. Configuration Complexity
**Risk**: Too many options, hard to understand
**Mitigation**:
- Sensible defaults
- Configuration validation
- Documentation with examples
- Migration guides

#### 2. Test Coverage
**Risk**: Hard to achieve 100% in some areas
**Mitigation**:
- Mock implementations for external deps
- Property-based testing
- Integration test fixtures
- Regular coverage checks

### Low Risk Items

#### 1. Documentation Maintenance
**Risk**: Docs get outdated
**Mitigation**:
- Doc tests that compile
- Examples as integration tests
- Regular doc reviews

---

## Development Workflow

### Daily Workflow

1. **Pull latest changes**
2. **Create feature branch** from current milestone
3. **Implement feature** following quality standards
4. **Write tests** (aim for 100% coverage)
5. **Run quality checks**:
   ```bash
   cargo fmt
   cargo clippy --all-targets --all-features -- -D warnings
   cargo test --all-features
   cargo tarpaulin --out Html
   cargo doc --no-deps --open
   ```
6. **Commit with conventional commit message**
7. **Push and create PR**

### PR Requirements

Every PR must:
- [ ] Pass all CI checks
- [ ] Have 100% test coverage on changed code
- [ ] Pass clippy without warnings
- [ ] Have complete documentation
- [ ] Include examples if adding new API
- [ ] Update CHANGELOG.md (yes, we eat our own dog food!)
- [ ] Be reviewed by at least one team member

### Conventional Commit Format

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style changes
- `refactor`: Code refactoring
- `perf`: Performance improvement
- `test`: Adding tests
- `chore`: Maintenance tasks

**Examples:**
```
feat(version): implement dependency propagation

Add support for propagating version updates through dependency graph.
Handles circular dependencies and respects configuration.

Closes #123
```

---

## CI/CD Pipeline

### GitHub Actions Workflow

```yaml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        rust: [stable, nightly]
    steps:
      - uses: actions/checkout@v2
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: ${{ matrix.rust }}
      - run: cargo fmt --check
      - run: cargo clippy --all-targets --all-features -- -D warnings
      - run: cargo test --all-features
      - run: cargo doc --no-deps
  
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions-rs/toolchain@v1
      - uses: actions-rs/tarpaulin@v0.1
      - name: Upload coverage
        uses: codecov/codecov-action@v1
      - name: Check 100% coverage
        run: |
          COVERAGE=$(cargo tarpaulin --output-format Json | jq '.files[].coverage')
          if [ "$COVERAGE" != "100.0" ]; then
            echo "Coverage is not 100%"
            exit 1
          fi
```

---

## Success Metrics

### Code Metrics
- ✅ 100% test coverage
- ✅ 0 clippy warnings
- ✅ 100% documentation coverage
- ✅ <100ms for 95% of operations
- ✅ <1s for complex operations (large monorepos)

### Quality Metrics
- ✅ All public APIs documented with examples
- ✅ All errors have clear messages
- ✅ All edge cases tested
- ✅ Cross-platform compatibility verified

### Usability Metrics
- ✅ Getting Started guide takes <15 minutes
- ✅ Common workflows have examples
- ✅ Error messages are actionable
- ✅ Configuration is intuitive

---

## Appendix A: File Checklist

Complete file structure to be created:

```
crates/pkg/
├── Cargo.toml
├── CONCEPT.md (✅ existing)
├── PLAN.md (✅ this file)
├── README.md
├── CHANGELOG.md
│
├── src/
│   ├── lib.rs
│   │
│   ├── config/
│   │   ├── mod.rs
│   │   ├── types.rs
│   │   ├── changeset.rs
│   │   ├── version.rs
│   │   ├── git.rs
│   │   ├── changelog.rs
│   │   ├── upgrade.rs
│   │   ├── audit.rs
│   │   ├── validation.rs
│   │   └── tests.rs
│   │
│   ├── error/
│   │   ├── mod.rs
│   │   ├── config.rs
│   │   ├── version.rs
│   │   ├── changeset.rs
│   │   ├── changes.rs
│   │   ├── changelog.rs
│   │   ├── upgrade.rs
│   │   ├── audit.rs
│   │   └── tests.rs
│   │
│   ├── types/
│   │   ├── mod.rs
│   │   ├── version.rs
│   │   ├── package.rs
│   │   ├── changeset.rs
│   │   ├── dependency.rs
│   │   └── tests.rs
│   │
│   ├── version/
│   │   ├── mod.rs
│   │   ├── resolver.rs
│   │   ├── resolution.rs
│   │   ├── propagation.rs
│   │   ├── graph.rs
│   │   ├── snapshot.rs
│   │   └── tests/
│   │       ├── mod.rs
│   │       ├── resolver_tests.rs
│   │       ├── propagation_tests.rs
│   │       └── snapshot_tests.rs
│   │
│   ├── changeset/
│   │   ├── mod.rs
│   │   ├── manager.rs
│   │   ├── storage.rs
│   │   ├── history.rs
│   │   ├── git_integration.rs
│   │   └── tests/
│   │       ├── mod.rs
│   │       ├── manager_tests.rs
│   │       ├── storage_tests.rs
│   │       └── history_tests.rs
│   │
│   ├── changes/
│   │   ├── mod.rs
│   │   ├── analyzer.rs
│   │   ├── report.rs
│   │   ├── package_changes.rs
│   │   ├── file_change.rs
│   │   ├── commit_info.rs
│   │   ├── mapping.rs
│   │   ├── stats.rs
│   │   └── tests/
│   │       ├── mod.rs
│   │       ├── analyzer_tests.rs
│   │       └── mapping_tests.rs
│   │
│   ├── changelog/
│   │   ├── mod.rs
│   │   ├── generator.rs
│   │   ├── changelog.rs
│   │   ├── section.rs
│   │   ├── entry.rs
│   │   ├── conventional.rs
│   │   ├── parser.rs
│   │   ├── formatter/
│   │   │   ├── mod.rs
│   │   │   ├── keep_a_changelog.rs
│   │   │   ├── conventional.rs
│   │   │   └── custom.rs
│   │   └── tests/
│   │       ├── mod.rs
│   │       ├── generator_tests.rs
│   │       ├── conventional_tests.rs
│   │       └── formatter_tests.rs
│   │
│   ├── upgrade/
│   │   ├── mod.rs
│   │   ├── manager.rs
│   │   ├── registry/
│   │   │   ├── mod.rs
│   │   │   ├── client.rs
│   │   │   ├── npmrc.rs
│   │   │   └── metadata.rs
│   │   ├── detection.rs
│   │   ├── apply.rs
│   │   ├── backup.rs
│   │   ├── types.rs
│   │   └── tests/
│   │       ├── mod.rs
│   │       ├── manager_tests.rs
│   │       ├── registry_tests.rs
│   │       └── apply_tests.rs
│   │
│   └── audit/
│       ├── mod.rs
│       ├── manager.rs
│       ├── report.rs
│       ├── sections/
│       │   ├── mod.rs
│       │   ├── upgrades.rs
│       │   ├── dependencies.rs
│       │   ├── breaking_changes.rs
│       │   ├── categorization.rs
│       │   └── version_consistency.rs
│       ├── issue.rs
│       ├── formatter.rs
│       ├── health_score.rs
│       └── tests/
│           ├── mod.rs
│           ├── manager_tests.rs
│           └── sections_tests.rs
│
├── tests/
│   ├── integration/
│   │   ├── mod.rs
│   │   ├── workflow_tests.rs
│   │   ├── monorepo_tests.rs
│   │   ├── single_package_tests.rs
│   │   └── upgrade_workflow_tests.rs
│   ├── fixtures/
│   │   ├── monorepo_sample/
│   │   └── single_package_sample/
│   └── common/
│       ├── mod.rs
│       └── test_helpers.rs
│
├── examples/
│   ├── 01_basic_changeset.rs
│   ├── 02_version_resolution.rs
│   ├── 03_changelog_generation.rs
│   ├── 04_dependency_upgrades.rs
│   ├── 05_audit_report.rs
│   └── 06_full_release_workflow.rs
│
└── docs/
    ├── guides/
    │   ├── getting-started.md
    │   ├── monorepo-guide.md
    │   └── ci-cd-integration.md
    └── architecture/
        ├── overview.md
        └── module-interactions.md
```

---

## Appendix B: Dependencies

### Cargo.toml

```toml
[package]
name = "sublime_pkg_tools"
version = "0.1.0"
edition = "2021"
authors = ["Your Team"]
license = "MIT OR Apache-2.0"
description = "Changeset-based package version management for Node.js projects"
repository = "https://github.com/yourorg/workspace-tools"
keywords = ["nodejs", "package", "version", "monorepo", "changeset"]
categories = ["development-tools"]

[dependencies]
# Internal crates
sublime_standard_tools = { path = "../standard" }
sublime_git_tools = { path = "../git" }

# Async runtime
tokio = { version = "1", features = ["full"] }
futures = "0.3"

# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
toml = "0.8"

# Date/time
chrono = { version = "0.4", features = ["serde"] }

# Error handling
thiserror = "1.0"

# Package management
package-json = "0.2"
semver = "1.0"

# Registry/HTTP
reqwest = { version = "0.11", features = ["json", "rustls-tls"] }
reqwest-retry = "0.3"
reqwest-middleware = "0.2"

# Parsing
regex = "1.10"

[dev-dependencies]
# Testing
tempfile = "3"
proptest = "1"
mockito = "1"
pretty_assertions = "1"

# Coverage
cargo-tarpaulin = "0.27"

[features]
default = []
```

---

## Appendix C: Quality Checklist Template

Use this checklist for each module:

### Module: `__________`

#### Code Quality
- [ ] Module documentation (What, How, Why)
- [ ] All public items documented
- [ ] All functions have doc comments
- [ ] Examples in documentation compile
- [ ] No `unwrap()` or `expect()`
- [ ] No `todo!()`, `unimplemented!()`, `panic!()`
- [ ] Errors implement `AsRef<str>`
- [ ] Uses `pub(crate)` for internal items

#### Testing
- [ ] Unit tests cover all functions
- [ ] Edge cases tested
- [ ] Error paths tested
- [ ] Integration tests written
- [ ] 100% coverage achieved
- [ ] Tests pass on all platforms

#### Review
- [ ] Clippy passes without warnings
- [ ] Code reviewed by peer
- [ ] Documentation reviewed
- [ ] Follows project patterns
- [ ] PR approved and merged

---

## Status: Ready for Implementation

This plan is comprehensive and ready for execution. Each phase has clear deliverables, quality gates, and success criteria. The structure follows proven patterns from `sublime_standard_tools`, and all quality requirements are explicit and measurable.

**Next Steps:**
1. Review and approve this plan
2. Set up project structure
3. Begin Phase 1 implementation
4. Regular check-ins at milestone boundaries

---

**PLAN.md STATUS**: ✅ **COMPLETE** - Ready to begin implementation