# 010.0-DEV-CONFIG-FILE-SUPPORT: Configuration File Support

## Release Goal

**Release 0.6: Team Collaboration & Persistence**

Add support for `.dry-aged-deps.json` configuration file to allow teams to share consistent dependency update policies across projects and avoid repeating CLI flag combinations.

## How This Story Contributes

Enables teams to define and share dependency update policies as code. Configuration files can be committed to version control, ensuring all team members use the same maturity and security thresholds. Reduces friction by eliminating the need to remember and type long CLI flag combinations.

**Note**: Stories 005-007 specified config file support in their acceptance criteria, but implementation was deferred. This story formally implements the config file functionality that was originally planned but not completed.

## User Story

**Format**: So that my team can share consistent dependency update policies and avoid repeating CLI flags, as a developer, I want to define thresholds and preferences in a `.dry-aged-deps.json` configuration file that dry-aged-deps reads automatically.

**INVEST Criteria Compliance**:

- **Independent**: Builds on existing CLI flag functionality without changing core logic
- **Negotiable**: Config file schema and location can be refined
- **Valuable**: Enables team consistency and reduces CLI complexity
- **Estimable**: Clear scope - read config file and merge with CLI args
- **Small**: Single iteration to add config file parsing
- **Testable**: Can verify config file values are applied correctly

## Acceptance Criteria

- [ ] **Config File Location**: Reads `.dry-aged-deps.json` from project root (where package.json is)
- [ ] **Config Schema**: Supports all CLI options in JSON format
- [ ] **CLI Override**: CLI flags override config file values (precedence: CLI > config > defaults)
- [ ] **Validation**: Validates config file structure and values
- [ ] **Error Handling**: Clear error messages for invalid config files
- [ ] **Optional**: Config file is optional - tool works without it
- [ ] **Documentation**: README shows config file format and all supported options
- [ ] **Schema Support**: Consider adding JSON schema for editor validation/autocomplete
- [ ] **Default Values**: Tool uses sensible defaults when neither config nor CLI flags provided

## Requirements (Current Implementation or To Be Implemented)

- **REQ-CONFIG-LOCATION**: Look for `.dry-aged-deps.json` in current working directory
- **REQ-CONFIG-SCHEMA**: Support JSON config with fields:
  ```json
  {
    "minAge": 7,
    "severity": "none",
    "prod": {
      "minAge": 30,
      "minSeverity": "moderate"
    },
    "dev": {
      "minAge": 7,
      "minSeverity": "high"
    },
    "format": "table"
  }
  ```
- **REQ-PRECEDENCE**: CLI flags > config file > built-in defaults
- **REQ-VALIDATION**: Validate config structure matches schema
- **REQ-ERROR-MESSAGES**: Clear, actionable error messages for invalid config
- **REQ-OPTIONAL**: Tool must work without config file present
- **REQ-MERGE-LOGIC**: Properly merge config values with CLI args (CLI wins)

## Dependencies

- **005.0-DEV-CONFIGURABLE-AGE-THRESHOLD**: Builds on age threshold configuration
- **006.0-DEV-CONFIGURABLE-SECURITY-THRESHOLD**: Builds on severity threshold configuration
- **007.0-DEV-SEPARATE-PROD-DEV-THRESHOLDS**: Builds on prod/dev distinction

## Example Configuration

**.dry-aged-deps.json** (in project root):

```json
{
  "minAge": 14,
  "severity": "low",
  "prod": {
    "minAge": 30,
    "minSeverity": "moderate"
  },
  "dev": {
    "minAge": 7,
    "minSeverity": "high"
  },
  "format": "table"
}
```

**Usage with config file**:

```bash
# Uses values from .dry-aged-deps.json
dry-aged-deps

# CLI flag overrides config file
dry-aged-deps --min-age=21  # Uses 21 instead of 14 from config
```

## Definition of Done

- [ ] All acceptance criteria met
- [ ] Code reviewed and approved
- [ ] Unit tests for config file parsing and merging
- [ ] Tests for precedence (CLI > config > defaults)
- [ ] Tests for validation and error handling
- [ ] Integration tests with real config files
- [ ] Documentation updated (README.md shows config file format)
- [ ] Example config file added to repository
- [ ] JSON schema file created (optional but recommended)
- [ ] Backward compatible (no config file = existing behavior)

---

## Story Notes

**Gall's Law Compliance**: Adds config file reading on top of working CLI flag system. Existing behavior unchanged when config file absent.

**Backward Compatibility**: Tool continues to work exactly as before when no config file is present. CLI-only workflows remain fully supported.

**Team Collaboration**: Teams can commit `.dry-aged-deps.json` to git, ensuring everyone uses the same update policies. Particularly valuable for organizations with specific risk management requirements.

**JSON Schema**: Consider providing a JSON schema file for editor autocomplete and validation (e.g., `$schema` property support in VS Code).

**Future Enhancement**: Could support multiple config locations (project root, user home directory, global config) with appropriate precedence.