mtrl 0.3.1 → 0.3.2

package/git-user-stats.js

@@ -0,0 +1,545 @@
+#!/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,68 +1,10 @@
-// index.js
-import {
-  createLayout,
-  createElement,
-  createBadge,
-  createBottomAppBar,
-  createButton,
-  createDatePicker,
-  createFab,
-  createExtendedFab,
-  createSegmentedButton,
-  createCard,
-  createCarousel,
-  createCheckbox,
-  createChip,
-  createDialog,
-  createDivider,
-  createList,
-  createMenu,
-  createNavigation,
-  createNavigationSystem,
-  createProgress,
-  createRadios,
-  createSearch,
-  createSheet,
-  createSlider,
-  createSnackbar,
-  createTabs,
-  createTextfield,
-  createTimePicker,
-  createTooltip,
-  createTopAppBar,
-  createSwitch
-} from './src/index.js'
+// index.ts
+/**
+ * Main mtrl library exports
+ * 
+ * This file re-exports everything from the internal implementation.
+ * 
+ * @packageDocumentation
+ */
 
-export {
-  createLayout,
-  createElement,
-  createBadge,
-  createBottomAppBar,
-  createButton,
-  createDatePicker,
-  createFab,
-  createExtendedFab,
-  createSegmentedButton,
-  createCard,
-  createCarousel,
-  createCheckbox,
-  createChip,
-  createDialog,
-  createDivider,
-  createList,
-  createMenu,
-  createNavigation,
-  createNavigationSystem,
-  createProgress,
-  createRadios,
-  createSearch,
-  createSheet,
-  createSlider,
-  createSnackbar,
-  createTabs,
-  createTextfield,
-  createTimePicker,
-  createTooltip,
-  createTopAppBar,
-  createSwitch
-}
+export * from './src/index';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "A functional TypeScript/JavaScript component library with composable architecture based on Material Design 3",
   "author": "floor",
   "license": "MIT License",
@@ -13,7 +13,11 @@
     "functional",
     "composable",
     "material design 3",
-    "md3"
+    "md3",
+    "testing",
+    "jsdom",
+    "tested",
+    "type-safe"
   ],
   "type": "module",
   "main": "index.js",
@@ -45,6 +49,7 @@
     "@types/jsdom": "^21.1.7",
     "jsdom": "^26.0.0",
     "sass": "^1.85.1",
-    "typedoc": "^0.27.9"
+    "typedoc": "^0.27.9",
+    "typescript": "^5.8.2"
   }
 }

package/src/components/badge/api.ts

@@ -2,6 +2,11 @@
 import { BadgeComponent, BadgeColor, BadgeVariant, BadgePosition } from './types';
 import { formatBadgeLabel } from './config';
 
+/**
+ * API configuration options for badge component
+ * @category Components
+ * @internal
+ */
 interface ApiOptions {
   visibility: {
     show: () => void;
@@ -14,6 +19,11 @@ interface ApiOptions {
   };
 }
 
+/**
+ * Component with required elements and methods for API enhancement
+ * @category Components
+ * @internal
+ */
 interface ComponentWithElements {
   element: HTMLElement;
   wrapper?: HTMLElement;
@@ -44,9 +54,13 @@ const ALL_VARIANTS = ['small', 'large'];
 const ALL_POSITIONS = ['top-right', 'top-left', 'bottom-right', 'bottom-left'];
 
 /**
- * Enhances a badge component with API methods
+ * Enhances a badge component with API methods.
+ * This follows the higher-order function pattern to add public API methods
+ * to the component, making them available to the end user.
+ * 
  * @param {ApiOptions} options - API configuration options
  * @returns {Function} Higher-order function that adds API methods to component
+ * @category Components
  * @internal This is an internal utility for the Badge component
  */
 export const withAPI = ({ visibility, lifecycle }: ApiOptions) =>