Skip to content
Codemetry

Basic Usage

Running an Analysis

Terminal window
php artisan codemetry:analyze --days=7

This analyzes the last 7 days and outputs a table:

DateMoodScoreConfidenceTop Reasons
2024-01-15good780.80Low churn; stable patterns
2024-01-14medium580.70Elevated fix density
2024-01-13bad350.75High churn p95; multiple reverts

Understanding the Output

Mood Labels

LabelScore RangeMeaning
good75-100Normal activity, low risk indicators
medium45-74Elevated signals, worth monitoring
bad0-44High strain indicators, may need attention

Score

A number from 0-100 representing overall quality risk:

  • Starts at 70 (neutral baseline)
  • Penalties applied for high churn, scatter, fix density, reverts
  • Rewards applied for low activity with stable patterns
  • Clamped to 0-100

Confidence

A number from 0.0-1.0 indicating how reliable the score is:

  • Higher with more commits (more data)
  • Higher when follow-up analysis ran successfully
  • Lower with very few commits (limited data)
  • Lower if signal providers were skipped

Top Reasons

Human-readable explanations of the main factors affecting the score. Examples:

  • “High churn at p95+ percentile”
  • “Elevated follow-up fix density”
  • “Multiple revert commits detected”
  • “Scattered changes across many directories”

Output Formats

Table (default)

Terminal window
php artisan codemetry:analyze --days=7

Best for quick visual inspection in the terminal.

JSON

Terminal window
php artisan codemetry:analyze --days=7 --format=json

Returns structured JSON with full details:

{
  "schema_version": "1.0",
  "repo_id": "a1b2c3d4...",
  "analyzed_at": "2024-01-15T10:30:00+00:00",
  "request_summary": {
    "days": 7,
    "baseline_days": 56
  },
  "windows": [
    {
      "window_label": "2024-01-15",
      "mood_label": "good",
      "mood_score": 78,
      "confidence": 0.80,
      "reasons": [...],
      "confounders": [],
      "raw_signals": {...},
      "normalized": {...}
    }
  ]
}

Filtering Results

By Date Range

Terminal window
# Specific date range
php artisan codemetry:analyze --since=2024-01-01 --until=2024-01-15


# Last N days
php artisan codemetry:analyze --days=30

By Author

Analyze commits from a specific author:

Terminal window
php artisan codemetry:analyze --days=7 --author="Jane Doe"

The author filter uses substring matching on the Git author name.

By Branch

Analyze a specific branch:

Terminal window
php artisan codemetry:analyze --days=7 --branch=feature/new-auth

Customizing Analysis

Override Baseline Days

Terminal window
php artisan codemetry:analyze --days=7 --baseline-days=30

A shorter baseline reacts faster to recent changes but may be less stable.

Override Follow-up Horizon

Terminal window
php artisan codemetry:analyze --days=7 --follow-up-horizon=5

Extend the window for detecting follow-up fix commits.

Analyze a Different Repository

Terminal window
php artisan codemetry:analyze --days=7 --repo=/path/to/other/repo

Interpreting Results

A “bad” day isn’t necessarily bad

High churn during a major refactor is expected. Look for:

  • large_refactor_suspected confounder
  • Low follow-up fix density despite high churn
  • Commit messages indicating intentional restructuring

Watch for patterns

Single bad days happen. Consecutive bad days may indicate:

  • Rushed deadline
  • Technical debt accumulation
  • Understaffed period

Use confidence as a guide

Low confidence (< 0.5) means limited data:

  • Weekend with 1-2 commits
  • New repository with short history
  • Filtered view with few matching commits

Take low-confidence scores with appropriate skepticism.