# Project Mapping Utility

## Purpose

Manages the JIRA expansion pack configuration that ensures reports and synchronization use the correct data sources, including team member roles and smart assignment rules.

## Configuration File Location

`.bmad-workspace/ck-jira-integration/config/jira-expansion-config.yaml`

## Core Functions

### 1. Load Project Mapping

[[LLM: Load and validate project mapping:

1. Check if file exists at `.bmad-workspace/ck-jira-integration/config/jira-expansion-config.yaml`
2. Parse YAML configuration
3. Validate required fields
4. Return configuration object or error
   ]]

### 2. Validate Mapping

**Required Fields:**

- `jira.project_key` - JIRA project identifier
- `jira.instance_url` - JIRA instance URL
- `git.primary.path` - Primary repository path

**Validation Checks:**

- Project key format (uppercase letters + optional numbers)
- Valid URL format for JIRA instance
- Git paths exist and are repositories
- Remote URLs are accessible

### 3. Display Configuration

[[LLM: Format configuration for display:

```
📋 Active Configuration:
JIRA Project: {{project_key}} - {{project_name}}
Instance: {{instance_url}}

Git Repositories ({{count}}):
  Primary: {{primary_path}}
    Remote: {{primary_remote}}
    Branch: {{primary_branch}}

  Additional:
  {{#each repositories}}
  - {{name}}: {{path}}
  {{/each}}

Sync Settings:
  Story Paths: {{story_paths}}
  Ticket Pattern: {{ticket_pattern}}
```

]]

### 4. Update Mapping

**Update Operations:**

- Add/remove git repositories
- Update field mappings
- Change sync settings
- Update validation timestamp

[[LLM: Always preserve existing configuration when updating]]

### 5. Error Handling

**Common Errors:**

- **Missing Configuration**: Direct to setup task
- **Invalid YAML**: Show parsing error and fix hints
- **Missing Repositories**: Offer to remove or update paths
- **Connection Issues**: Retry with guidance

### 6. Git Repository Analysis

[[LLM: For each configured repository:

1. Verify path exists and is git repo
2. Get current branch
3. Get remote URLs
4. Check for uncommitted changes
5. Find JIRA ticket references in recent commits
   ]]

### 7. JIRA Query Filtering

[[LLM: When querying JIRA:

1. Always filter by configured project_key
2. Use JQL: `project = {{project_key}}`
3. Don't rely on repository name matching
4. Use explicit project filtering
   ]]

## Usage Examples

### In Report Task

```
1. Load project mapping
2. Display configuration in report header
3. Use ALL configured git repositories
4. Filter JIRA queries by project key
```

### In Sync Task

```
1. Validate mapping exists
2. Get all repository paths
3. Analyze commits from all repos
4. Sync only to configured JIRA project
```

### In Setup Task

```
1. Auto-detect current repository
2. Guide through multi-repo setup
3. Save configuration
4. Validate connectivity
```

## Best Practices

1. **Always Check First**: Never assume mapping exists
2. **Display Configuration**: Show users what data sources are active
3. **Use Project Key**: Filter all JIRA operations by configured project
4. **Multi-Repo Aware**: Analyze ALL configured repositories
5. **Clear Errors**: Guide users to setup when mapping missing