jellytau/docs/TRACEABILITY_CI.md

Requirement Traceability CI/CD Pipeline

This document explains the automated requirement traceability validation system for JellyTau.

Overview

The CI/CD pipeline automatically validates that code changes are properly traced to requirements. This ensures:

• ✅ Requirements are implemented with clear traceability
• ✅ No requirement coverage regressions
• ✅ Code changes are linked to specific requirements
• ✅ Quality metrics are tracked over time

Gitea Actions Workflows

Two workflows are configured in .gitea/workflows/:

1. traceability-check.yml (Primary - Recommended)

Gitea-native workflow with:

• ✅ Automatic trace extraction
• ✅ Coverage validation against minimum threshold (50%)
• ✅ Modified file checking
• ✅ Artifact preservation
• ✅ Summary reports

Runs on: Every push and pull request

2. traceability.yml (Alternative)

GitHub-compatible workflow with additional features:

• Pull request comments with coverage stats
• GitHub-specific integrations

What Gets Validated

1. Trace Extraction

bun run traces:json > traces-report.json

Extracts all TRACES comments from:

• TypeScript files (src/**/*.ts)
• Svelte components (src/**/*.svelte)
• Rust code (src-tauri/src/**/*.rs)
• Test files

2. Coverage Thresholds

The workflow checks:

• Minimum overall coverage: 50% (57+ requirements traced)
• Requirements by type:
  • UR (User): 23+ of 39
  • IR (Integration): 5+ of 24
  • DR (Development): 28+ of 48
  • JA (Jellyfin API): 0+ of 3

If coverage drops below threshold, the workflow fails and blocks merge.

3. Modified File Checking

On pull requests, the workflow:

1. Detects all changed TypeScript/Svelte/Rust files
2. Warns if new/modified files lack TRACES comments
3. Suggests the TRACES format for missing comments

How to Add Traces to New Code

When you add new code or modify existing code, include TRACES comments:

TypeScript/Svelte Example

// TRACES: UR-005, UR-026 | DR-029
export function handlePlayback() {
  // Implementation...
}

Rust Example

/// TRACES: UR-005 | DR-001
pub fn player_state_changed(state: PlayerState) {
    // Implementation...
}

Test Example

// TRACES: UR-005 | DR-001 | UT-026, UT-027
#[cfg(test)]
mod tests {
    // Tests...
}

TRACES Format

TRACES: [UR-###, ...] | [IR-###, ...] | [DR-###, ...] | [JA-###, ...]

• UR-### - User Requirements (features users see)
• IR-### - Integration Requirements (API/platform integration)
• DR-### - Development Requirements (internal architecture)
• JA-### - Jellyfin API Requirements (Jellyfin API usage)

Examples:

• // TRACES: UR-005 - Single requirement
• // TRACES: UR-005, UR-026 - Multiple of same type
• // TRACES: UR-005 | DR-029 - Multiple types
• // TRACES: UR-005, UR-026 | DR-001, DR-029 | UT-001 - Complex

Workflow Behavior

On Push to Main Branch

1. ✅ Extracts all traces from code
2. ✅ Validates coverage is >= 50%
3. ✅ Generates full traceability report
4. ✅ Saves report as artifact

On Pull Request

1. ✅ Extracts all traces
2. ✅ Validates coverage >= 50%
3. ✅ Checks modified files for TRACES
4. ✅ Warns if new code lacks TRACES
5. ✅ Suggests proper format
6. ✅ Generates report artifact

Failure Scenarios

The workflow fails (blocks merge) if:

• Coverage drops below 50%
• JSON extraction fails
• Invalid trace format

The workflow warns (but doesn't block) if:

• New files lack TRACES comments
• Coverage drops (but still above threshold)

Viewing Reports

In Gitea Actions UI

1. Go to Actions tab
2. Click the Traceability Validation workflow run
3. Download traceability-reports artifact
4. View:
   • traces-report.json - Raw trace data
   • docs/TRACEABILITY.md - Formatted report

Locally

# Extract current traces
bun run traces:json | jq '.byType'

# Generate full report
bun run traces:markdown
cat docs/TRACEABILITY.md

Coverage Goals

Current Status

• Overall: 51% (56/114)
• UR: 59% (23/39)
• IR: 21% (5/24)
• DR: 58% (28/48)
• JA: 0% (0/3)

Targets

• Short term (Sprint): Maintain ≥50% overall
• Medium term (Month): Reach 70% overall coverage
• Long term (Release): Reach 90% coverage with focus on:
  • IR requirements (API clients)
  • JA requirements (Jellyfin API endpoints)
  • Remaining UR/DR requirements

Improving Coverage

For Missing User Requirements (UR)

1. Review README.md for unimplemented features
2. Add TRACES to code that implements them
3. Focus on high-priority features (High/Medium priority)

For Missing Integration Requirements (IR)

1. Add TRACES to Jellyfin API client methods
2. Add TRACES to platform-specific backends (Android/Linux)
3. Link to corresponding Jellyfin API endpoints

For Missing Development Requirements (DR)

1. Add TRACES to UI components in src/lib/components/
2. Add TRACES to composables in src/lib/composables/
3. Add TRACES to player backend in src-tauri/src/player/

For Jellyfin API Requirements (JA)

1. Add TRACES to Jellyfin API wrapper methods
2. Document which endpoints map to which requirements
3. Link to Jellyfin API documentation

Example PR Checklist

When submitting a pull request:

• All new code has TRACES comments linking to requirements
• TRACES format is correct: // TRACES: UR-001 | DR-002
• Workflow passes (coverage ≥ 50%)
• No coverage regressions
• Artifact traceability report was generated

Troubleshooting

"Coverage below minimum threshold"

Problem: Workflow fails with coverage < 50%

Solution:

1. Run bun run traces:json locally
2. Check which requirements are traced
3. Add TRACES to untraced code sections
4. Re-run extraction to verify

"New files without TRACES"

Problem: Workflow warns about new files lacking TRACES

Solution:

1. Add TRACES comments to all new code
2. Format: // TRACES: UR-001 | DR-002
3. Map code to specific requirements from README.md
4. Re-push

"Invalid JSON format"

Problem: Trace extraction produces invalid JSON

Solution:

1. Check for malformed TRACES comments
2. Run locally: bun run traces:json
3. Look for parsing errors
4. Fix and retry

Integration with Development

Before Committing

# Check your traces
bun run traces:json | jq '.byType'

# Regenerate report
bun run traces:markdown

# Verify traces syntax
grep "TRACES:" src/**/*.ts src/**/*.rs

In Your IDE

Add a file watcher to regenerate traces on save:

{
  "fileWatcher.watchPatterns": [
    "src/**/*.ts",
    "src/**/*.svelte",
    "src-tauri/src/**/*.rs"
  ],
  "fileWatcher.command": "bun run traces:markdown"
}

Git Hooks

Add a pre-push hook to validate traces:

#!/bin/bash
# .git/hooks/pre-push
bun run traces:json > /dev/null
if [ $? -ne 0 ]; then
  echo "❌ Invalid TRACES format"
  exit 1
fi

References

• Extract Traces Script
• Requirements Specification
• Traceability Matrix
• Gitea Actions Documentation

Support

For issues or questions:

1. Check this document
2. Review example traces in src/lib/stores/
3. Check existing TRACES comments for format
4. Review workflow logs in Gitea Actions

---

Last Updated: 2026-02-13