Gira Blame JSON Output Schema

This document describes the JSON output format for the gira blame command, designed for reliable parsing by tools and AI agents.

Overview

The blame command outputs a structured JSON format that provides ticket attribution information for source code files.

The schema is defined using Pydantic models, which provide: - Runtime validation with helpful error messages - Automatic JSON schema generation - Type safety and IDE support - Consistent serialization/deserialization

Schema Structure

Top-Level Object

{
  "files": [...],
  "summary": {...}
}

Field	Type	Description	Required
files	array	Array of file analysis results	Yes
summary	object	Aggregate statistics across all files	Yes

File Object

Each element in the files array represents analysis results for a single file:

{
  "file": "src/example.py",
  "range": {
    "start": 10,
    "end": 20
  },
  "tickets": {...}
}

Field	Type	Description	Required
file	string	Path to the analyzed file	Yes
range	object	Line range filter (only present if -L option used)	No
tickets	object	Map of ticket IDs to ticket information	Yes

Range Object

When a line range is specified with the -L option:

{
  "start": 10,
  "end": 20
}

Field	Type	Description	Required
start	integer	Starting line number (1-based, inclusive)	Yes
end	integer	Ending line number (1-based, inclusive)	Yes

Ticket Information Object

Each ticket ID maps to its detailed information:

{
  "GCM-123": {
    "title": "Implement new feature",
    "status": "done",
    "type": "feature",
    "lines_affected": [[10, 15], [18, 20]],
    "total_lines": 8,
    "last_modified": "2025-01-20T10:30:00",
    "commits": ["abc1234", "def4567"]
  }
}

Field	Type	Description	Required
title	string	Ticket title	Yes
status	string	Current ticket status	Yes
type	string	Ticket type	Yes
lines_affected	array	Array of [start, end] line ranges	Yes
total_lines	integer	Total number of lines affected	Yes
last_modified	string/null	ISO 8601 timestamp or null	Yes
commits	array	Array of commit SHAs	Yes

Valid Status Values

• todo
• in_progress
• review
• done
• archived

Valid Type Values

• feature
• bug
• task
• story
• epic
• subtask

Summary Object

Aggregate statistics for the entire blame operation:

{
  "total_files": 2,
  "unique_tickets": ["GCM-123", "GCM-456"],
  "ticket_count": 2
}

Field	Type	Description	Required
total_files	integer	Number of files analyzed	Yes
unique_tickets	array	All unique ticket IDs found	Yes
ticket_count	integer	Count of unique tickets	Yes

Complete Example

{
  "files": [
    {
      "file": "src/gira/commands/ticket/blame.py",
      "tickets": {
        "GCM-572": {
          "title": "Implement blame CLI command",
          "status": "done",
          "type": "feature",
          "lines_affected": [[1, 50], [100, 150]],
          "total_lines": 101,
          "last_modified": "2025-01-21T14:30:00",
          "commits": ["a1b2c3d4e5f6", "e4f5678901234"]
        }
      }
    },
    {
      "file": "src/gira/utils/blame.py",
      "range": {
        "start": 50,
        "end": 100
      },
      "tickets": {
        "GCM-570": {
          "title": "Create core blame utility module",
          "status": "done",
          "type": "subtask",
          "lines_affected": [[50, 75], [80, 90]],
          "total_lines": 36,
          "last_modified": "2025-01-21T12:00:00",
          "commits": ["i7j8k9l0m1n2o"]
        },
        "GCM-573": {
          "title": "Add unit tests for blame",
          "status": "done",
          "type": "subtask",
          "lines_affected": [[91, 100]],
          "total_lines": 10,
          "last_modified": null,
          "commits": ["m0n1o2p3q4r5s"]
        }
      }
    }
  ],
  "summary": {
    "total_files": 2,
    "unique_tickets": ["GCM-570", "GCM-572", "GCM-573"],
    "ticket_count": 3
  }
}

Usage in Tools

Python Example

import json
import subprocess

# Run blame command
result = subprocess.run(
    ["gira", "blame", "src/file.py", "--json"],
    capture_output=True,
    text=True
)

# Parse JSON output
data = json.loads(result.stdout)

# Process tickets directly (no schema version needed)

# Process tickets
for file_info in data["files"]:
    print(f"File: {file_info['file']}")
    for ticket_id, ticket_info in file_info["tickets"].items():
        print(f"  {ticket_id}: {ticket_info['title']} ({ticket_info['total_lines']} lines)")

Shell Example

# Get all unique ticket IDs
gira blame src/*.py --json | jq -r '.summary.unique_tickets[]'

# Get tickets for a specific file
gira blame src/main.py --json | jq '.files[0].tickets'

# Count total lines affected per ticket
gira blame src/*.py --json | jq '.files[].tickets | to_entries[] | "\(.key): \(.value.total_lines)"'

Schema Validation

Using Pydantic (Recommended)

The schema is defined using Pydantic models, providing automatic validation:

from gira.schemas.blame import BlameOutput, validate_blame_output

# Validate JSON data
json_data = {...}  # Your blame JSON output
is_valid = validate_blame_output(json_data)

# Parse and validate with detailed errors
try:
    output = BlameOutput(**json_data)
    # Access typed fields
    print(f"Found {output.summary.ticket_count} tickets")
except ValidationError as e:
    print(f"Validation error: {e}")

Using JSON Schema

A JSON Schema can be generated from the Pydantic models:

from gira.schemas.blame import generate_json_schema
import json

# Generate JSON Schema
schema = generate_json_schema()

# Save for external tools
with open("blame_schema.json", "w") as f:
    json.dump(schema, f, indent=2)

Features

• Comprehensive ticket attribution information
• Support for line ranges
• Aggregate summary statistics
• ISO 8601 timestamp format
• Stable ticket status and type enums
• Pydantic-based schema with automatic validation
• JSON Schema generation support