mtrl 0.3.8 → 0.4.0

package/git-user-stats.js

@@ -1,545 +0,0 @@
-#!/usr/bin/env bun
-
-/**
- * Git Work Time Estimation Script
- * ==============================
- *
- * This script analyzes git commit history to estimate the time spent working on a project.
- * It combines several methodologies for estimation:
- *
- * 1. COCOMO II Model (Constructive Cost Model)
- *    - Modified for commit-level analysis
- *    - Uses different approaches for small vs large changes
- *    - Incorporates effort multipliers based on commit types
- *
- * 2. Git Metadata Analysis
- *    - Analyzes commit messages for type classification
- *    - Processes line addition/deletion statistics
- *    - Optionally analyzes across all branches
- *
- * 3. Time Constraints and Reality Checks
- *    - Enforces daily work hour limits
- *    - Accounts for minimum overhead time per commit
- *    - Caps maximum time per individual commit
- *
- * Theory and Methodology
- * =====================
- *
- * COCOMO II Adaptation:
- * Traditional COCOMO II formula: Effort = A × Size^B
- * where:
- * - A is the base effort coefficient (typically 2.94)
- * - B is the scale factor (typically 0.91)
- * - Size is measured in thousands of lines of code (KLOC)
- *
- * Our modifications:
- * 1. Reduced base coefficient for commit-level granularity
- * 2. Different calculation for small changes (<100 lines)
- * 3. Weighted treatment of deletions vs additions
- * 4. Additional effort multipliers based on commit type
- *
- * Usage Examples
- * =============
- *
- * Basic usage:
- *   bun git-user-stats.js --authors "Author Name"
- *
- * Multiple authors:
- *   bun git-user-stats.js --authors "Author One" "author.one@email.com" "Author Two"
- *
- * Date range:
- *   bun git-user-stats.js --authors "Author" --since "2024-01-01" --until "2024-02-01"
- *
- * Branch analysis:
- *   bun git-user-stats.js --authors "Author" --all-branches
- *   bun git-user-stats.js --authors "Author" --branch main
- *
- * Combined options:
- *   bun git-user-stats.js --authors "Author" --all-branches --since "1 month ago" --no-merges
- *
- * Command Line Options
- * ===================
- *
- * Required:
- *   --authors        One or more author identifiers (names or emails)
- *
- * Optional:
- *   --since         Start date (YYYY-MM-DD or git-compatible date)
- *   --until         End date
- *   --all-branches  Include commits from all branches
- *   --branch        Analyze specific branch only
- *   --no-merges     Exclude merge commits
- *
- * Date Format Options:
- *   - ISO dates: "2024-01-01"
- *   - Relative: "1 month ago", "2 weeks ago"
- *   - Named: "yesterday", "last monday"
- */
-
-import { exec } from 'child_process'
-import { promisify } from 'util'
-import progress from '../radiooooo/monorepo/packages/script/src/module/progress.js'
-
-const execAsync = promisify(exec)
-
-/**
- * Command line argument parser
- * Processes arguments and provides defaults for optional parameters
- * @returns {Object} Parsed arguments with default values
- */
-const parseArgs = () => {
-  const args = {
-    authors: [],
-    since: null,
-    until: null,
-    allBranches: false,
-    branch: null,
-    noMerges: false
-  }
-
-  for (let i = 2; i < process.argv.length; i++) {
-    const arg = process.argv[i]
-    switch (arg) {
-      case '--authors':
-        while (i + 1 < process.argv.length && !process.argv[i + 1].startsWith('--')) {
-          args.authors.push(process.argv[++i])
-        }
-        break
-      case '--since':
-        args.since = process.argv[++i]
-        break
-      case '--until':
-        args.until = process.argv[++i]
-        break
-      case '--all-branches':
-        args.allBranches = true
-        break
-      case '--branch':
-        args.branch = process.argv[++i]
-        break
-      case '--no-merges':
-        args.noMerges = true
-        break
-    }
-  }
-
-  return args
-}
-
-const args = parseArgs()
-
-// Input validation with detailed help
-if (args.authors.length === 0) {
-  console.error('Usage: bun git-user-stats.js --authors "Author Name" ["Author Email"...]')
-  console.error('\nOptions:')
-  console.error('  --authors       One or more author identifiers (names or emails)')
-  console.error('  --since         Start date (YYYY-MM-DD or "1 month ago")')
-  console.error('  --until         End date')
-  console.error('  --all-branches  Include commits from all branches')
-  console.error('  --branch        Analyze specific branch only')
-  console.error('  --no-merges     Exclude merge commits')
-  console.error('\nExamples:')
-  console.error('  bun git-user-stats.js --authors "John Doe" --since "2024-01-01"')
-  console.error('  bun git-user-stats.js --authors "john@doe.com" --all-branches')
-  console.error('  bun git-user-stats.js --authors "John Doe" "john@doe.com" --branch main')
-  process.exit(1)
-}
-
-/**
- * COCOMO Model Configuration
- * -------------------------
- * Modified version of COCOMO II for commit-level analysis
- *
- * Key differences from standard COCOMO II:
- * 1. Lower base coefficient for smaller units of work
- * 2. Hybrid approach for different sized changes
- * 3. Additional effort multipliers for commit types
- */
-const COCOMO = {
-  // Base effort coefficient (reduced from standard 2.94)
-  A: 0.91,
-
-  // Scale factor (standard COCOMO II value)
-  B: 0.91,
-
-  // Industry standard work month
-  PERSON_MONTH_HOURS: 152,
-
-  // Realistic daily limit including overtime
-  MAX_HOURS_PER_DAY: 10,
-
-  /**
-   * Effort multipliers based on commit type
-   * Derived from COCOMO II cost drivers:
-   * - CPLX (Product Complexity)
-   * - RUSE (Required Reusability)
-   * - PDIF (Platform Difficulty)
-   */
-  TYPE_MULTIPLIERS: {
-    refactor: 1.24, // High complexity
-    fix: 1.15, // High attention to detail
-    test: 1.12, // Medium complexity
-    merge: 0.82, // Low complexity
-    update: 0.87, // Simple changes
-    cleanup: 0.85, // Very low complexity
-    default: 1.0 // Nominal case
-  },
-
-  /**
-   * Effort estimation function
-   * Uses different approaches based on change size:
-   * - COCOMO II for large changes
-   * - Linear estimation for small changes
-   *
-   * @param {number} kloc - Size in thousands of lines of code
-   * @returns {number} Estimated minutes of effort
-   */
-  estimateEffort: (kloc) => {
-    if (kloc >= 0.1) { // More than 100 lines
-      const personMonths = COCOMO.A * Math.pow(kloc, COCOMO.B)
-      return personMonths * COCOMO.PERSON_MONTH_HOURS * 60
-    } else {
-      // Linear estimation for small changes (3 minutes per line)
-      return kloc * 1000 * 3
-    }
-  }
-}
-
-/**
- * Time Formatting Helper
- * Converts minutes to human-readable duration
- * @param {number} minutes - Total minutes to format
- * @returns {string} Formatted string like "5h30m"
- */
-const formatHours = minutes => {
-  const hours = Math.floor(minutes / 60)
-  const remainingMinutes = Math.round(minutes % 60)
-  return `${hours}h${remainingMinutes}m`
-}
-
-/**
- * Git Line Statistics Analyzer
- * Retrieves the number of lines added and deleted for a commit
- * Uses git show --numstat for detailed change information
- *
- * @param {string} hash - Git commit hash
- * @returns {Promise<Object>} Object containing added and deleted line counts
- */
-const getLineStats = async hash => {
-  try {
-    const { stdout } = await execAsync(`git show --numstat ${hash}`)
-    const stats = stdout.split('\n')
-      .filter(line => /^\d+\t\d+\t/.test(line))
-      .reduce((acc, line) => {
-        const [added, deleted] = line.split('\t').map(Number)
-        return {
-          added: acc.added + (added || 0),
-          deleted: acc.deleted + (deleted || 0)
-        }
-      }, { added: 0, deleted: 0 })
-    return stats
-  } catch (err) {
-    return { added: 0, deleted: 0 }
-  }
-}
-
-/**
- * Commit Type Analyzer
- * Determines the effort multiplier based on commit message content
- * Uses keyword analysis to categorize the type of change
- *
- * @param {string} message - Git commit message
- * @returns {number} Effort multiplier value
- */
-const getCommitMultiplier = message => {
-  const msg = message.toLowerCase()
-  for (const [type, multiplier] of Object.entries(COCOMO.TYPE_MULTIPLIERS)) {
-    if (msg.includes(type)) return multiplier
-  }
-  return COCOMO.TYPE_MULTIPLIERS.default
-}
-
-/**
- * Time Estimation Function
- * Calculates estimated time for a single commit
- *
- * Factors considered:
- * - Lines added (full weight)
- * - Lines deleted (partial weight)
- * - Commit type multiplier
- * - Minimum overhead time
- * - Maximum time cap
- *
- * @param {number} added - Lines added
- * @param {number} deleted - Lines deleted
- * @param {string} message - Commit message
- * @returns {number} Estimated minutes for this commit
- */
-const estimateCommitTime = (added, deleted, message) => {
-  // Weight deletions as 20% of additions
-  const kloc = (added + (deleted * 0.2)) / 1000
-
-  // Get base effort estimate
-  let minutes = COCOMO.estimateEffort(kloc)
-
-  // Apply type-based multiplier
-  const multiplier = getCommitMultiplier(message)
-  minutes *= multiplier
-
-  // Enforce minimum and maximum bounds
-  minutes = Math.max(minutes + 5, 10) // At least 10 minutes
-  return Math.min(minutes, 240) // Cap at 4 hours
-}
-
-/**
- * Git Log Retriever
- * Gets commit history for a specific author
- * Handles branch selection and date range filtering
- *
- * @param {string} author - Author name or email
- * @returns {Promise<string>} Git log output
- */
-const getGitLog = async author => {
-  const cmd = ['git log']
-
-  // Branch selection
-  if (args.allBranches) {
-    cmd.push('--all')
-  } else if (args.branch) {
-    cmd.push(args.branch)
-  }
-
-  // Additional flags
-  if (args.noMerges) cmd.push('--no-merges')
-  cmd.push(`--author="${author}"`)
-  cmd.push('--date=iso')
-  cmd.push('--format="%ad|%h|%ae|%s|%D"')
-
-  // Date range
-  if (args.since) cmd.push(`--since="${args.since}"`)
-  if (args.until) cmd.push(`--until="${args.until}"`)
-
-  const { stdout } = await execAsync(cmd.join(' '))
-  return stdout.trim()
-}
-
-/**
- * Main Analysis Function
- * Processes git history and generates time estimates
- *
- * Steps:
- * 1. Fetches commit history
- * 2. Analyzes each commit
- * 3. Groups by date
- * 4. Applies time constraints
- * 5. Generates statistics
- *
- * @param {string[]} authors - List of author identifiers
- */
-const getCommitStats = async authors => {
-  try {
-    // Initial status message
-    if (args.allBranches) {
-      console.log('Fetching git history from all branches...')
-    } else if (args.branch) {
-      console.log(`Fetching git history from branch: ${args.branch}`)
-    } else {
-      console.log('Fetching git history from current branch...')
-    }
-
-    const allLogs = await Promise.all(authors.map(getGitLog))
-
-    // Parse commit information
-    const commits = allLogs
-      .join('\n')
-      .split('\n')
-      .filter(line => line.length > 0)
-      .map(line => {
-        const [datetime, hash, email, message, refs] = line.split('|')
-        return {
-          date: datetime.split(' ')[0],
-          timestamp: new Date(datetime),
-          hash,
-          email,
-          message,
-          branch: refs ? refs.split(',')[0].trim() : 'main'
-        }
-      })
-      .sort((a, b) => b.timestamp - a.timestamp)
-
-    if (commits.length === 0) {
-      console.log('No commits found for the specified author(s)')
-      return
-    }
-
-    console.log(`Processing ${commits.length} commits...`)
-
-    // Initialize tracking variables
-    let processedCount = 0
-    const startTime = Date.now()
-    const totalCommits = commits.length
-    const commitsByDate = {}
-    const totalLines = { added: 0, deleted: 0 }
-
-    // Process each commit
-    for (const commit of commits) {
-      processedCount++
-      progress(processedCount, totalCommits, startTime, commit.hash.substring(0, 7))
-
-      const lines = await getLineStats(commit.hash)
-      const estimatedMinutes = estimateCommitTime(lines.added, lines.deleted, commit.message)
-
-      // Group by date
-      if (!commitsByDate[commit.date]) {
-        commitsByDate[commit.date] = {
-          commits: [],
-          lines: { added: 0, deleted: 0 },
-          estimatedMinutes: 0
-        }
-      }
-
-      // Accumulate statistics
-      commitsByDate[commit.date].commits.push(commit)
-      commitsByDate[commit.date].lines.added += lines.added
-      commitsByDate[commit.date].lines.deleted += lines.deleted
-      commitsByDate[commit.date].estimatedMinutes += estimatedMinutes
-
-      totalLines.added += lines.added
-      totalLines.deleted += lines.deleted
-    }
-
-    // Apply daily work limits
-    Object.values(commitsByDate).forEach(day => {
-      day.estimatedMinutes = Math.min(day.estimatedMinutes, COCOMO.MAX_HOURS_PER_DAY * 60)
-    })
-
-    progress(null)
-
-    // Branch statistics (only if analyzing all branches)
-    if (args.allBranches) {
-      const branchStats = commits.reduce((acc, commit) => {
-        if (commit.branch && commit.branch !== '') {
-          acc[commit.branch] = (acc[commit.branch] || 0) + 1
-        }
-        return acc
-      }, {})
-
-      console.log('\nCommits by branch:')
-      Object.entries(branchStats)
-        .sort(([, a], [, b]) => b - a)
-        .forEach(([branch, count]) => {
-          console.log(`${branch}: ${count} commits`)
-        })
-    }
-
-    /**
-     * Display daily breakdown of work
-     * Shows for each day:
-     * - Number of commits
-     * - Lines changed
-     * - Estimated work time
-     */
-    console.log('\nWork time estimation per date:')
-    Object.entries(commitsByDate)
-      .sort(([a], [b]) => new Date(b) - new Date(a))
-      .forEach(([date, stats]) => {
-        console.log(
-          `${date}: ${stats.commits.length} commits, ` +
-          `+${stats.lines.added}/-${stats.lines.deleted} lines, ` +
-          `≈ ${formatHours(stats.estimatedMinutes)}`
-        )
-      })
-
-    /**
-     * Calculate summary statistics
-     * Includes:
-     * - Total metrics (commits, lines, days)
-     * - Averages (per day, per commit)
-     * - Time estimations
-     */
-    const totalCommitCount = Object.values(commitsByDate)
-      .reduce((sum, { commits }) => sum + commits.length, 0)
-    const totalMinutes = Object.values(commitsByDate)
-      .reduce((sum, { estimatedMinutes }) => sum + estimatedMinutes, 0)
-    const uniqueEmails = [...new Set(commits.map(c => c.email))]
-    const totalDays = Object.keys(commitsByDate).length
-    const avgHoursPerDay = (totalMinutes / 60 / totalDays)
-    const avgCommitsPerDay = totalCommitCount / totalDays
-    const avgTimePerCommit = totalMinutes / totalCommitCount
-
-    /**
-     * Display comprehensive summary
-     * Shows overall project statistics and averages
-     */
-    console.log('\nSummary:')
-    console.log(`Total commits: ${totalCommitCount}`)
-    console.log(`Total lines added: ${totalLines.added}`)
-    console.log(`Total lines deleted: ${totalLines.deleted}`)
-    console.log(`Total active days: ${totalDays}`)
-    console.log(`Estimated total work time: ${formatHours(totalMinutes)}`)
-    console.log(`Average hours per active day: ${avgHoursPerDay.toFixed(1)}h`)
-    console.log(`Average commits per day: ${avgCommitsPerDay.toFixed(1)}`)
-    console.log(`Average time per commit: ${formatHours(Math.round(avgTimePerCommit))}`)
-    console.log(`Identified email addresses: ${uniqueEmails.join(', ')}`)
-
-    /**
-     * Display analysis configuration
-     * Shows all parameters used for the analysis
-     */
-    console.log('\nAnalysis Configuration:')
-    console.log('Repository Analysis:')
-    if (args.allBranches) {
-      console.log('- Analyzing all branches')
-    } else if (args.branch) {
-      console.log(`- Analyzing branch: ${args.branch}`)
-    } else {
-      console.log('- Analyzing current branch only')
-    }
-    if (args.noMerges) console.log('- Excluding merge commits')
-    if (args.since) console.log(`- Since: ${args.since}`)
-    if (args.until) console.log(`- Until: ${args.until}`)
-
-    /**
-     * Display estimation model details
-     * Shows all factors and multipliers used in calculations
-     */
-    console.log('\nEstimation Model Details:')
-    console.log('Time Calculation:')
-    console.log('- Using modified COCOMO II for large changes (>100 lines)')
-    console.log('- Linear estimation for small changes (3 min/line)')
-    console.log(`- Maximum ${COCOMO.MAX_HOURS_PER_DAY} hours per day`)
-    console.log('- Maximum 4 hours per commit')
-    console.log('- Minimum 10 minutes per commit')
-    console.log('- Deletions counted as 20% of additions')
-
-    console.log('\nCOCOMO II Parameters:')
-    console.log(`- Base effort coefficient (A): ${COCOMO.A}`)
-    console.log(`- Scale factor (B): ${COCOMO.B}`)
-    console.log(`- Person-month: ${COCOMO.PERSON_MONTH_HOURS} hours`)
-
-    console.log('\nEffort Multipliers:')
-    Object.entries(COCOMO.TYPE_MULTIPLIERS)
-      .sort(([, a], [, b]) => b - a)
-      .forEach(([type, mult]) => {
-        console.log(`  * ${type}: ${mult}x`)
-      })
-  } catch (err) {
-    progress(null)
-    console.error('Error analyzing git log:', err)
-    process.exit(1)
-  }
-}
-
-/**
- * Signal Handler
- * Ensures clean exit on interrupt
- * Restores cursor and terminal state
- */
-process.on('SIGINT', () => {
-  console.log('\nCaught interrupt signal')
-  progress(null)
-  process.exit()
-})
-
-// Start the analysis
-getCommitStats(args.authors)

package/index.ts

@@ -1,10 +0,0 @@
-// index.ts
-/**
- * Main mtrl library exports
- * 
- * This file re-exports everything from the internal implementation.
- * 
- * @packageDocumentation
- */
-
-export * from './src/index';