# 013.0-DEV-CHECK-MODE: Check Mode for CI/CD

## Release Goal

**Release 0.8: CI/CD Integration - Check Mode**

Add a `--check` mode that fails the CI/CD build when safe updates are available. This enables teams to enforce dependency freshness policies in their continuous integration pipelines.

## How This Story Contributes

Enables proactive dependency management by failing CI builds when safe updates are waiting. Teams can choose to require that dependencies are kept current, rather than letting safe updates accumulate indefinitely.

## User Story

**Format**: So that my CI/CD pipeline can enforce a policy of keeping dependencies current, as a developer, I want a --check mode that fails the build (exits with error code) when safe updates are available.

**INVEST Criteria Compliance**:

- **Independent**: Builds on exit code refinement, adds new mode
- **Negotiable**: Failure threshold and behavior can be refined
- **Valuable**: Enables enforcement of dependency freshness policies
- **Estimable**: Clear scope - add check mode flag and failure logic
- **Small**: Single iteration to add check mode
- **Testable**: Can verify exit codes and behavior

## Acceptance Criteria

- [ ] **Check Flag**: Accepts `--check` flag to enable check mode
- [ ] **Fail on Updates**: Exit code 1 when safe updates available (treats updates as failure)
- [ ] **Pass When Current**: Exit code 0 when no safe updates available
- [ ] **Error Handling**: Exit code 2 for errors (same as normal mode)
- [ ] **Clear Output**: Shows which packages need updating before failing
- [ ] **JSON/XML Support**: Works with all output formats
- [ ] **Documentation**: README shows --check usage with CI/CD examples

## Requirements (Current Implementation or To Be Implemented)

- **REQ-CHECK-FLAG**: Support `--check` CLI flag
- **REQ-EXIT-1-ON-UPDATES**: Exit 1 when safe updates available in check mode
- **REQ-EXIT-0-NO-UPDATES**: Exit 0 when no updates needed
- **REQ-EXIT-2-ON-ERROR**: Exit 2 on errors (npm fails, invalid config)
- **REQ-CLEAR-OUTPUT**: Display packages needing updates before exiting
- **REQ-FORMAT-SUPPORT**: Works with --format=json and --format=xml

## Exit Code Behavior in Check Mode

| Scenario               | Normal Mode Exit  | Check Mode Exit | Meaning                         |
| ---------------------- | ----------------- | --------------- | ------------------------------- |
| No updates available   | 0                 | 0               | ✅ Pass - dependencies current  |
| Safe updates available | 1 (informational) | 1 (failure)     | ❌ Fail - enforce update policy |
| Error occurred         | 2                 | 2               | ❌ Fail - something went wrong  |

## Usage Examples

**Basic check mode**:

```bash
dry-aged-deps --check
# Exit 0 if up to date
# Exit 1 if safe updates available (fails CI)
# Exit 2 if error occurred
```

**CI/CD Pipeline Integration**:

```yaml
# GitHub Actions - Enforce dependency freshness
name: Check Dependencies
on: [pull_request]

jobs:
  check-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Check for outdated dependencies
        run: npx dry-aged-deps --check
        # Fails if safe updates are available

      - name: Show available updates on failure
        if: failure()
        run: npx dry-aged-deps --format=json
```

## Dependencies

- **012.0-DEV-EXIT-CODE-REFINEMENT**: Requires well-defined exit codes

## Definition of Done

- [ ] All acceptance criteria met
- [ ] Code reviewed and approved
- [ ] Unit tests for check mode behavior
- [ ] Tests verify exit codes in check mode vs normal mode
- [ ] Integration tests with CI/CD examples
- [ ] Documentation updated (README.md shows CI/CD examples)
- [ ] Help text includes --check flag
- [ ] Backward compatible (check mode is opt-in)

---

## Story Notes

**Gall's Law Compliance**: Adds check mode as an opt-in feature. Default behavior unchanged - tool remains informational unless --check specified.

**Policy Enforcement**: Check mode transforms the tool from informational to enforcement. Teams can decide: "We require dependencies to be kept current within our safety policies."

**CI/CD Philosophy**: Some teams want CI to warn about updates (normal mode: exit 1 = informational). Others want CI to fail until updates are applied (check mode: exit 1 = failure). Check mode enables the second approach.

**Team Workflow**: Typical workflow with check mode:

1. PR is opened
2. CI runs `dry-aged-deps --check`
3. If safe updates available, CI fails
4. Developer runs `dry-aged-deps --update --yes` (if story 011 implemented)
5. Developer runs `npm install` and commits
6. CI passes

**Future Enhancement**: Could add more granular control:

- `--check-severity` to fail only on certain vulnerability severities
- `--check-prod` to enforce policies only for production dependencies
- `--fail-after-days=<n>` to fail only if safe updates are older than N days

**Alternative Flag Names**: Could use `--enforce`, `--require-current`, or `--strict` instead of `--check` - team preference.