testlint 0.1.0

# Common Profile Data Format

This document describes the standardized JSON format for profiling data across all supported languages.

## Purpose

The common format allows:
- Cross-language profiling comparisons
- Integration with analysis tools and dashboards
- Historical tracking and trend analysis
- CI/CD pipeline integration
- Unified reporting across polyglot codebases

## Format Structure

```json
{
  "language": "Python",
  "source_file": "examples/sample.py",
  "timestamp": "2025-11-08T09:00:00Z",
  
  "static_analysis": {
    "file_size_bytes": 829,
    "line_count": 43,
    "function_count": 5,
    "class_count": 1,
    "import_count": 2,
    "complexity_score": 15
  },
  
  "runtime_analysis": {
    "total_samples": 1245,
    "execution_duration_secs": 5,
    "functions_executed": 23,
    
    "function_stats": {
      "compute_heavy": {
        "name": "compute_heavy",
        "execution_count": 892,
        "percentage": 71.65,
        "line_number": null,
        "file_path": null
      },
      "fibonacci": {
        "name": "fibonacci",
        "execution_count": 245,
        "percentage": 19.68,
        "line_number": null,
        "file_path": null
      }
    },
    
    "hot_functions": [
      {
        "rank": 1,
        "name": "compute_heavy",
        "samples": 892,
        "percentage": 71.65
      },
      {
        "rank": 2,
        "name": "fibonacci",
        "samples": 245,
        "percentage": 19.68
      }
    ]
  }
}
```

## Field Descriptions

### Top Level

| Field | Type | Description |
|-------|------|-------------|
| `language` | String | Source language (Python, Go, TypeScript) |
| `source_file` | String | Path to the profiled file |
| `timestamp` | String | ISO 8601 timestamp of when profiling occurred |
| `static_analysis` | Object | Static code metrics |
| `runtime_analysis` | Object | Runtime execution data (optional) |

### Static Analysis

| Field | Type | Description |
|-------|------|-------------|
| `file_size_bytes` | Integer | File size in bytes |
| `line_count` | Integer | Total lines of code |
| `function_count` | Integer | Number of functions/methods |
| `class_count` | Integer | Number of classes/structs/types |
| `import_count` | Integer | Number of import/dependency statements |
| `complexity_score` | Integer | Cyclomatic complexity estimate |

### Runtime Analysis

| Field | Type | Description |
|-------|------|-------------|
| `total_samples` | Integer | Total profiling samples collected |
| `execution_duration_secs` | Integer | Duration of profiling run |
| `functions_executed` | Integer | Number of unique functions executed |
| `function_stats` | Map | Detailed per-function statistics |
| `hot_functions` | Array | Top functions by execution time |

### Function Stats

| Field | Type | Description |
|-------|------|-------------|
| `name` | String | Function name |
| `execution_count` | Integer | Number of samples containing this function |
| `percentage` | Float | Percentage of total execution time |
| `line_number` | Integer? | Line number where function is defined (optional) |
| `file_path` | String? | Source file path (optional) |

### Hot Function

| Field | Type | Description |
|-------|------|-------------|
| `rank` | Integer | Ranking by execution time (1 = hottest) |
| `name` | String | Function name |
| `samples` | Integer | Number of samples |
| `percentage` | Float | Percentage of total samples |

## Usage Examples

### Reading in Rust

```rust
use profiler::CommonProfileData;

let data = CommonProfileData::from_json_file("output.json")?;
println!("Language: {}", data.language);
println!("Functions: {}", data.static_analysis.function_count);

if let Some(runtime) = &data.runtime_analysis {
    println!("Total samples: {}", runtime.total_samples);
    for hot in &runtime.hot_functions {
        println!("{}: {:.2}%", hot.name, hot.percentage);
    }
}
```

### Reading in Python

```python
import json

with open('output.json') as f:
    data = json.load(f)

print(f"Language: {data['language']}")
print(f"LOC: {data['static_analysis']['line_count']}")

if 'runtime_analysis' in data:
    for func in data['runtime_analysis']['hot_functions']:
        print(f"{func['name']}: {func['percentage']:.2f}%")
```

### Reading in JavaScript/TypeScript

```typescript
import * as fs from 'fs';

interface ProfileData {
  language: string;
  source_file: string;
  static_analysis: {
    line_count: number;
    function_count: number;
    complexity_score: number;
  };
  runtime_analysis?: {
    hot_functions: Array<{
      rank: number;
      name: string;
      percentage: number;
    }>;
  };
}

const data: ProfileData = JSON.parse(fs.readFileSync('output.json', 'utf8'));
console.log(`${data.language}: ${data.static_analysis.line_count} LOC`);
```

## Integration Ideas

### CI/CD Pipeline

```yaml
# .github/workflows/profile.yml
- name: Profile Python Code
  run: |
    cargo run -- python src/main.py --runtime 10 --json profile.json
    
- name: Upload Profile Data
  uses: actions/upload-artifact@v3
  with:
    name: profile-data
    path: profile.json
```

### Trend Analysis

Track metrics over time by storing JSON outputs:

```bash
# Daily profiling
DATE=$(date +%Y-%m-%d)
cargo run -- python app.py --runtime 5 --json "profiles/profile-${DATE}.json"

# Compare with previous day
python compare_profiles.py profiles/profile-{today,yesterday}.json
```

### Dashboard Integration

Send data to monitoring systems:

```bash
# Export to monitoring
cargo run -- python app.py --runtime 5 --json /tmp/profile.json
curl -X POST https://metrics.example.com/api/profiles \
  -H "Content-Type: application/json" \
  -d @/tmp/profile.json
```

## Future Extensions

Potential additions to the format:

- Memory profiling data
- Line-level execution counts (true coverage)
- Call graph information
- Branch coverage
- Test coverage integration
- Performance regression detection
- Multi-file aggregation