genesis

Author: Thomas Stromberg

.gitignore

@@ -30,3 +30,5 @@ go.work.sum
 # Editor/IDE
 # .idea/
 # .vscode/
+
+.claude/

README.md

@@ -0,0 +1,76 @@
+# prcost
+
+Calculate the real-world cost of GitHub pull requests with detailed breakdowns of author effort, participant contributions, and delay costs.
+
+## Installation
+
+```bash
+go install github.com/codeGROOVE-dev/prcost/cmd/prcost@latest
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/codeGROOVE-dev/prcost
+cd prcost
+go build -o prcost ./cmd/prcost
+```
+
+## Usage
+
+```bash
+prcost https://github.com/owner/repo/pull/123
+prcost --format json https://github.com/owner/repo/pull/123
+prcost --salary 300000 https://github.com/owner/repo/pull/123
+```
+
+## Cost Model
+
+This model is based on early research combining COCOMO II effort estimation with session-based time tracking. Individual PR estimates may be under or over-estimated, particularly for delay costs. The recommendation is to use this model across a large pool of PRs and rely on the law of averages for meaningful insights.
+
+### Author Costs
+
+**Code Cost**: Writing effort estimated using COCOMO II: `Effort = 2.94 × (KLOC)^1.0997`. Minimum 20 minutes.
+
+**Code Context Switching**: Cognitive overhead during code writing: `COCOMO hours × 0.2 × sqrt(KLOC)`. Based on Microsoft interruption research (Czerwinski et al., 2004).
+
+**GitHub Time**: Session-based calculation for GitHub interactions (commits, comments).
+
+**GitHub Context Switching**: 20 minutes to context in, 20 minutes to context out per session.
+
+### Participant Costs
+
+**Review Cost**: COCOMO II estimation applied to review comments.
+
+**GitHub Time**: Session-based calculation for GitHub interactions.
+
+**GitHub Context Switching**: Same 20-minute in/out costs per session.
+
+### Delay Costs
+
+**Project Delay (20%)**: Opportunity cost of blocked engineer time: `hourly_rate × duration_hours × 0.20`.
+
+**Code Updates**: Rework cost from code drift. Power-law formula: `driftMultiplier = 1 + (0.03 × days^0.7)`, calibrated to 4% weekly churn. Applies to PRs open 3+ days, capped at 90 days. Based on Windows Vista analysis (Nagappan et al., Microsoft Research, 2008).
+
+**Future GitHub**: Cost for 3 future events (push, review, merge) with full context switching.
+
+External contributors (no write access) receive 50% delay cost reduction.
+
+## Session-Based Time Tracking
+
+Events within 60 minutes are grouped into sessions to model real work patterns. This preserves flow state during continuous work and applies context switching costs only when work is interrupted.
+
+**Example (three events 5 min apart, one session)**:
+- Event 1: 20 (in) + 20 (event) + 5 (gap) = 45 min
+- Event 2: 5 (gap) + 20 (event) + 5 (gap) = 30 min
+- Event 3: 5 (gap) + 20 (event) + 20 (out) = 45 min
+- Total: 120 minutes
+
+**Example (two events 90 min apart, two sessions)**:
+- Event 1: 20 + 20 + 20 = 60 min
+- Event 2: 20 + 20 + 20 = 60 min
+- Total: 120 minutes
+
+## License
+
+Apache 2.0

cmd/prcost/main.go

@@ -0,0 +1,191 @@
+// Package main implements a CLI tool to calculate the real-world cost of GitHub PRs.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"os/exec"
+	"strings"
+	"time"
+
+	"github.com/codeGROOVE-dev/prcost/pkg/cost"
+	"github.com/codeGROOVE-dev/prcost/pkg/github"
+)
+
+func main() {
+	// Define command-line flags
+	salary := flag.Float64("salary", 250000, "Annual salary for cost calculation")
+	benefits := flag.Float64("benefits", 1.3, "Benefits multiplier (1.3 = 30% benefits)")
+	eventMinutes := flag.Float64("event-minutes", 20, "Minutes per review event")
+	overheadFactor := flag.Float64("overhead-factor", 0.25, "Delay cost factor (0.25 = 25%)")
+	format := flag.String("format", "human", "Output format: human or json")
+
+	flag.Usage = func() {
+		fmt.Fprintf(os.Stderr, "Usage: %s [options] <PR_URL>\n\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "Calculate the real-world cost of a GitHub pull request.\n\n")
+		fmt.Fprintf(os.Stderr, "Options:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(os.Stderr, "\nExamples:\n")
+		fmt.Fprintf(os.Stderr, "  %s https://github.com/owner/repo/pull/123\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "  %s --salary 300000 --benefits 1.4 https://github.com/owner/repo/pull/123\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "  %s --salary 200000 --benefits 1.25 --event-minutes 30 --format json https://github.com/owner/repo/pull/123\n", os.Args[0])
+	}
+
+	flag.Parse()
+
+	// Validate that we have a PR URL
+	if flag.NArg() != 1 {
+		flag.Usage()
+		os.Exit(1)
+	}
+
+	prURL := flag.Arg(0)
+
+	// Validate PR URL format
+	if !strings.HasPrefix(prURL, "https://github.com/") || !strings.Contains(prURL, "/pull/") {
+		log.Fatalf("Invalid PR URL. Expected format: https://github.com/owner/repo/pull/123")
+	}
+
+	// Create cost configuration from flags
+	cfg := cost.DefaultConfig()
+	cfg.AnnualSalary = *salary
+	cfg.BenefitsMultiplier = *benefits
+	cfg.MinutesPerEvent = *eventMinutes
+	cfg.DelayCostFactor = *overheadFactor
+
+	// Get GitHub token from gh CLI
+	ctx := context.Background()
+	token, err := getGitHubToken(ctx)
+	if err != nil {
+		log.Fatalf("Failed to get GitHub token: %v\nPlease ensure 'gh' is installed and authenticated (run 'gh auth login')", err)
+	}
+
+	// Fetch PR data
+	prData, err := github.FetchPRData(ctx, prURL, token)
+	if err != nil {
+		log.Fatalf("Failed to fetch PR data: %v", err)
+	}
+
+	// Calculate costs
+	breakdown := cost.Calculate(prData, cfg)
+
+	// Output in requested format
+	switch *format {
+	case "human":
+		printHumanReadable(breakdown, prURL)
+	case "json":
+		printJSON(breakdown)
+	default:
+		log.Fatalf("Unknown format: %s (must be human or json)", *format)
+	}
+}
+
+// getGitHubToken retrieves a GitHub token using the gh CLI.
+func getGitHubToken(ctx context.Context) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "gh", "auth", "token")
+	output, err := cmd.Output()
+	if err != nil {
+		if ctx.Err() == context.DeadlineExceeded {
+			return "", fmt.Errorf("timeout getting auth token")
+		}
+		return "", fmt.Errorf("failed to get auth token (is 'gh' installed and authenticated?): %w", err)
+	}
+
+	token := strings.TrimSpace(string(output))
+	return token, nil
+}
+
+// printHumanReadable outputs a detailed itemized bill in human-readable format.
+func printHumanReadable(b cost.Breakdown, prURL string) {
+	fmt.Printf("PULL REQUEST COST ANALYSIS\n")
+	fmt.Printf("==========================\n\n")
+	fmt.Printf("PR URL:      %s\n", prURL)
+	fmt.Printf("Hourly Rate: $%.2f ($%.0f salary * %.1fX total benefits multiplier)\n\n",
+		b.HourlyRate, b.AnnualSalary, b.BenefitsMultiplier)
+
+	// Author Costs
+	fmt.Printf("AUTHOR COSTS\n")
+	fmt.Printf("  Code Cost (COCOMO)          $%10.2f   (%d LOC, %.2f hrs)\n",
+		b.Author.CodeCost, b.Author.LinesAdded, b.Author.CodeHours)
+	fmt.Printf("  Code Context Switching      $%10.2f   (%.2f hrs)\n",
+		b.Author.CodeContextCost, b.Author.CodeContextHours)
+	fmt.Printf("  GitHub Time                 $%10.2f   (%d events, %.2f hrs)\n",
+		b.Author.GitHubCost, b.Author.Events, b.Author.GitHubHours)
+	fmt.Printf("  GitHub Context Switching    $%10.2f   (%d sessions, %.2f hrs)\n",
+		b.Author.GitHubContextCost, b.Author.Sessions, b.Author.GitHubContextHours)
+	fmt.Printf("  ---\n")
+	fmt.Printf("  Author Subtotal             $%10.2f   (%.2f hrs total)\n\n",
+		b.Author.TotalCost, b.Author.TotalHours)
+
+	// Participant Costs
+	if len(b.Participants) > 0 {
+		fmt.Printf("PARTICIPANT COSTS\n")
+		for _, p := range b.Participants {
+			fmt.Printf("  %s\n", p.Actor)
+			fmt.Printf("    Event Time                $%10.2f   (%d events, %.2f hrs)\n",
+				p.GitHubCost, p.Events, p.GitHubHours)
+			fmt.Printf("    Context Switching         $%10.2f   (%d sessions, %.2f hrs)\n",
+				p.GitHubContextCost, p.Sessions, p.GitHubContextHours)
+			fmt.Printf("    Subtotal                  $%10.2f   (%.2f hrs total)\n",
+				p.TotalCost, p.TotalHours)
+		}
+
+		// Sum all participant costs
+		var totalParticipantCost float64
+		var totalParticipantHours float64
+		for _, p := range b.Participants {
+			totalParticipantCost += p.TotalCost
+			totalParticipantHours += p.TotalHours
+		}
+		fmt.Printf("  ---\n")
+		fmt.Printf("  Participants Subtotal       $%10.2f   (%.2f hrs total)\n\n",
+			totalParticipantCost, totalParticipantHours)
+	}
+
+	// Delay Cost
+	fmt.Printf("DELAY COST\n")
+	if b.DelayCapped {
+		fmt.Printf("  Project Delay (20%%)         $%10.2f   (%.0f hrs, capped at 90 days)\n",
+			b.DelayCostDetail.ProjectDelayCost, b.DelayCostDetail.ProjectDelayHours)
+	} else {
+		fmt.Printf("  Project Delay (20%%)         $%10.2f   (%.2f hrs)\n",
+			b.DelayCostDetail.ProjectDelayCost, b.DelayCostDetail.ProjectDelayHours)
+	}
+
+	if b.DelayCostDetail.ReworkPercentage > 0 {
+		fmt.Printf("  Code Updates (%.0f%% rework)  $%10.2f   (%.2f hrs)\n",
+			b.DelayCostDetail.ReworkPercentage*100, b.DelayCostDetail.CodeUpdatesCost, b.DelayCostDetail.CodeUpdatesHours)
+	}
+
+	fmt.Printf("  Future GitHub (3 events)    $%10.2f   (%.2f hrs)\n",
+		b.DelayCostDetail.FutureGitHubCost, b.DelayCostDetail.FutureGitHubHours)
+	fmt.Printf("  ---\n")
+
+	if b.DelayCapped {
+		fmt.Printf("  Total Delay Cost            $%10.2f   (actual: %.0f hours open)\n\n",
+			b.DelayCost, b.DelayHours)
+	} else {
+		fmt.Printf("  Total Delay Cost            $%10.2f\n\n", b.DelayCost)
+	}
+
+	// Total
+	fmt.Printf("==========================\n")
+	fmt.Printf("TOTAL COST                  $%10.2f\n", b.TotalCost)
+	fmt.Printf("==========================\n")
+}
+
+// printJSON outputs the cost breakdown in JSON format.
+func printJSON(b cost.Breakdown) {
+	encoder := json.NewEncoder(os.Stdout)
+	encoder.SetIndent("", "  ")
+	if err := encoder.Encode(b); err != nil {
+		log.Fatalf("Failed to encode JSON: %v", err)
+	}
+}

go.mod

@@ -0,0 +1,7 @@
+module github.com/codeGROOVE-dev/prcost
+
+go 1.25.3
+
+require github.com/codeGROOVE-dev/prx v0.0.0-20251016165946-00c6c6e90c29
+
+require github.com/codeGROOVE-dev/retry v1.2.0 // indirect

go.sum

@@ -0,0 +1,4 @@
+github.com/codeGROOVE-dev/prx v0.0.0-20251016165946-00c6c6e90c29 h1:MSBy3Ywr3ky/LXhDSFbeJXDdAsfMMrzNdMNehyTvSuA=
+github.com/codeGROOVE-dev/prx v0.0.0-20251016165946-00c6c6e90c29/go.mod h1:7qLbi18baOyS8yO/6/64SBIqtyzSzLFdsDST15NPH3w=
+github.com/codeGROOVE-dev/retry v1.2.0 h1:xYpYPX2PQZmdHwuiQAGGzsBm392xIMl4nfMEFApQnu8=
+github.com/codeGROOVE-dev/retry v1.2.0/go.mod h1:8OgefgV1XP7lzX2PdKlCXILsYKuz6b4ZpHa/20iLi8E=

pkg/cocomo/cocomo.go

@@ -0,0 +1,67 @@
+// Package cocomo implements COCOMO II effort estimation for software projects.
+// COCOMO (Constructive Cost Model) estimates development effort based on lines of code.
+package cocomo
+
+import (
+	"math"
+	"time"
+)
+
+// Config holds parameters for COCOMO II effort estimation.
+// These defaults are based on the COCOMO II model for organic projects.
+type Config struct {
+	// Multiplier is the base effort coefficient (default: 2.94)
+	Multiplier float64
+
+	// Exponent is the scale factor (default: 1.0997)
+	Exponent float64
+
+	// MinimumEffort is the minimum effort in minutes (default: 20)
+	MinimumEffort time.Duration
+}
+
+// DefaultConfig returns COCOMO II configuration with standard values.
+func DefaultConfig() Config {
+	return Config{
+		Multiplier:    2.94,
+		Exponent:      1.0997,
+		MinimumEffort: 20 * time.Minute,
+	}
+}
+
+// EstimateEffort calculates development effort based on lines of code.
+//
+// The formula used is: Effort = Multiplier × (KLOC)^Exponent
+// where KLOC is thousands of lines of code.
+//
+// The result is in person-months, which we convert to hours by multiplying by 152
+// (a standard industry conversion: 1 person-month = 152 hours).
+//
+// Parameters:
+//   - linesOfCode: The number of lines of code written
+//   - cfg: COCOMO configuration parameters
+//
+// Returns:
+//   - Effort in hours (never less than config.MinimumEffort)
+func EstimateEffort(linesOfCode int, cfg Config) time.Duration {
+	// Convert lines of code to thousands of lines (KLOC)
+	kloc := float64(linesOfCode) / 1000.0
+
+	// Apply COCOMO II formula: Effort = Multiplier × (KLOC)^Exponent
+	// Result is in person-months
+	personMonths := cfg.Multiplier * math.Pow(kloc, cfg.Exponent)
+
+	// Convert person-months to hours (1 person-month = 152 hours)
+	const hoursPerPersonMonth = 152.0
+	hours := personMonths * hoursPerPersonMonth
+
+	// Convert to duration
+	effort := time.Duration(hours * float64(time.Hour))
+
+	// Apply minimum effort floor
+	if effort < cfg.MinimumEffort {
+		return cfg.MinimumEffort
+	}
+
+	return effort
+}