refactor(stats): migrate to pkg/csvops library

Stats(ctx, StatsOptions) (StatsResult, error). Returns structured per-column
data (Unique, UniqueCapped, Empty, Top []ValueCount) — desktop UI renders it
as a table without re-parsing text. cmd/stats.go handles the tablewriter
formatting.

Tests cover basic counts, --max-unique cap behavior (and that early-seen
values keep counting after the cap hits), top-N selection, and empty files.

Author: maherelgamil

cmd/stats.go

@@ -1,13 +1,12 @@
 package cmd
 
 import (
-	"encoding/csv"
+	"context"
 	"fmt"
-	"io"
 	"os"
-	"sort"
 	"strings"
 
+	"github.com/maherelgamil/csvops/pkg/csvops"
 	"github.com/olekukonko/tablewriter"
 	"github.com/schollz/progressbar/v3"
 	"github.com/spf13/cobra"
@@ -26,116 +25,48 @@ var statsCmd = &cobra.Command{
 			return fmt.Errorf("please provide an input file using --input")
 		}
 
-		totalRows, err := countDataRows(statsInput, ',')
+		var bar *progressbar.ProgressBar
+		res, err := csvops.Stats(context.Background(), csvops.StatsOptions{
+			Input:     statsInput,
+			MaxUnique: statsMaxUnique,
+			Delimiter: ',',
+			Progress: func(done, total int64) {
+				if bar == nil {
+					bar = progressbar.Default(total, "Analyzing")
+				}
+				_ = bar.Set64(done)
+			},
+		})
 		if err != nil {
 			return err
 		}
 
-		file, err := os.Open(statsInput)
-		if err != nil {
-			return fmt.Errorf("failed to open file: %w", err)
-		}
-		defer file.Close()
-
-		reader := csv.NewReader(file)
-		reader.FieldsPerRecord = -1
-
-		headers, err := reader.Read()
-		if err != nil {
-			return fmt.Errorf("failed to read headers: %w", err)
-		}
-
-		columnCount := len(headers)
-
-		type columnStats struct {
-			empty     int
-			uniques   map[string]int
-			capped    bool
-			totalVals int
-		}
-
-		stats := make([]columnStats, columnCount)
-		for i := 0; i < columnCount; i++ {
-			stats[i].uniques = make(map[string]int)
-		}
-
-		bar := progressbar.Default(totalRows, "Analyzing")
-		rowCount := 0
-
-		for {
-			row, err := reader.Read()
-			if err == io.EOF {
-				break
-			}
-			if err != nil {
-				continue
-			}
-			rowCount++
-			for i := range headers {
-				cell := ""
-				if i < len(row) {
-					cell = strings.TrimSpace(row[i])
-				}
-				if cell == "" {
-					stats[i].empty++
-					continue
-				}
-				stats[i].totalVals++
-				if statsMaxUnique > 0 && len(stats[i].uniques) >= statsMaxUnique {
-					if _, exists := stats[i].uniques[cell]; exists {
-						stats[i].uniques[cell]++
-					} else {
-						stats[i].capped = true
-					}
-				} else {
-					stats[i].uniques[cell]++
-				}
-			}
-			_ = bar.Add(1)
-		}
-
 		fmt.Printf("\n📊 Stats for: %s\n", statsInput)
-		fmt.Printf("Total Rows (excluding header): %d\n", rowCount)
-		fmt.Printf("Columns: %d\n\n", columnCount)
+		fmt.Printf("Total Rows (excluding header): %d\n", res.TotalRows)
+		fmt.Printf("Columns: %d\n\n", len(res.Columns))
 
 		table := tablewriter.NewWriter(os.Stdout)
 		table.SetHeader([]string{"Column", "Unique Values", "Empty Fields", "Top 3 Values"})
 		table.SetAutoWrapText(false)
 		table.SetRowLine(true)
 		table.SetAlignment(tablewriter.ALIGN_LEFT)
 
-		type kv struct {
-			Key   string
-			Count int
-		}
-
-		for i, name := range headers {
-			uniqueCount := fmt.Sprintf("%d", len(stats[i].uniques))
-			if stats[i].capped {
-				uniqueCount = fmt.Sprintf(">=%d (capped)", len(stats[i].uniques))
+		for _, col := range res.Columns {
+			unique := fmt.Sprintf("%d", col.Unique)
+			if col.UniqueCapped {
+				unique = fmt.Sprintf(">=%d (capped)", col.Unique)
 			}
-
-			sorted := make([]kv, 0, len(stats[i].uniques))
-			for k, v := range stats[i].uniques {
-				sorted = append(sorted, kv{k, v})
+			top := make([]string, 0, len(col.Top))
+			for _, v := range col.Top {
+				top = append(top, fmt.Sprintf("%s (%d)", v.Value, v.Count))
 			}
-			sort.Slice(sorted, func(a, b int) bool {
-				return sorted[a].Count > sorted[b].Count
-			})
-
-			topValues := []string{}
-			for j := 0; j < len(sorted) && j < 3; j++ {
-				topValues = append(topValues, fmt.Sprintf("%s (%d)", sorted[j].Key, sorted[j].Count))
-			}
-
 			table.Append([]string{
-				name,
-				uniqueCount,
-				fmt.Sprintf("%d", stats[i].empty),
-				strings.Join(topValues, ", "),
+				col.Name,
+				unique,
+				fmt.Sprintf("%d", col.Empty),
+				strings.Join(top, ", "),
 			})
 		}
-
 		table.Render()
 		return nil
 	},

pkg/csvops/stats.go

@@ -0,0 +1,147 @@
+package csvops
+
+import (
+	"context"
+	"encoding/csv"
+	"fmt"
+	"io"
+	"os"
+	"sort"
+	"strings"
+)
+
+// StatsOptions configures a Stats operation.
+type StatsOptions struct {
+	Input string
+	// MaxUnique caps the number of distinct values tracked per column.
+	// 0 means unlimited. When a column hits the cap, new values are not
+	// recorded but existing values' counts continue to increment and the
+	// column is flagged as UniqueCapped.
+	MaxUnique int
+	Delimiter rune
+	Progress  Progress
+}
+
+// ValueCount is a single (value, occurrence count) pair.
+type ValueCount struct {
+	Value string
+	Count int
+}
+
+// ColumnStats is the per-column summary.
+type ColumnStats struct {
+	Name         string
+	Unique       int  // number of distinct non-empty values seen (bounded by MaxUnique)
+	UniqueCapped bool // true if MaxUnique was reached
+	Empty        int
+	Top          []ValueCount // top N by count (N=3)
+}
+
+// StatsResult is returned from Stats.
+type StatsResult struct {
+	TotalRows int64
+	Columns   []ColumnStats
+}
+
+// Stats scans the CSV and returns row count plus per-column summary
+// (unique value count, empty cell count, and top 3 most frequent values).
+func Stats(ctx context.Context, opts StatsOptions) (StatsResult, error) {
+	var res StatsResult
+
+	if opts.Input == "" {
+		return res, fmt.Errorf("input is required")
+	}
+	if opts.Delimiter == 0 {
+		opts.Delimiter = ','
+	}
+
+	total, err := CountDataRows(opts.Input, opts.Delimiter)
+	if err != nil {
+		return res, err
+	}
+
+	f, err := os.Open(opts.Input)
+	if err != nil {
+		return res, fmt.Errorf("open input: %w", err)
+	}
+	defer f.Close()
+
+	reader := csv.NewReader(f)
+	reader.Comma = opts.Delimiter
+	reader.FieldsPerRecord = -1
+
+	headers, err := reader.Read()
+	if err != nil {
+		return res, fmt.Errorf("read headers: %w", err)
+	}
+
+	type acc struct {
+		empty   int
+		uniques map[string]int
+		capped  bool
+	}
+	cols := make([]acc, len(headers))
+	for i := range cols {
+		cols[i].uniques = make(map[string]int)
+	}
+
+	var processed int64
+	for {
+		if err := ctx.Err(); err != nil {
+			return res, err
+		}
+		row, err := reader.Read()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			continue
+		}
+		res.TotalRows++
+		for i := range headers {
+			cell := ""
+			if i < len(row) {
+				cell = strings.TrimSpace(row[i])
+			}
+			if cell == "" {
+				cols[i].empty++
+				continue
+			}
+			if opts.MaxUnique > 0 && len(cols[i].uniques) >= opts.MaxUnique {
+				if _, exists := cols[i].uniques[cell]; exists {
+					cols[i].uniques[cell]++
+				} else {
+					cols[i].capped = true
+				}
+			} else {
+				cols[i].uniques[cell]++
+			}
+		}
+		processed++
+		safeProgress(opts.Progress, processed, total)
+	}
+
+	res.Columns = make([]ColumnStats, len(headers))
+	for i, name := range headers {
+		c := &cols[i]
+		sorted := make([]ValueCount, 0, len(c.uniques))
+		for k, v := range c.uniques {
+			sorted = append(sorted, ValueCount{Value: k, Count: v})
+		}
+		sort.Slice(sorted, func(a, b int) bool {
+			return sorted[a].Count > sorted[b].Count
+		})
+		top := sorted
+		if len(top) > 3 {
+			top = top[:3]
+		}
+		res.Columns[i] = ColumnStats{
+			Name:         name,
+			Unique:       len(c.uniques),
+			UniqueCapped: c.capped,
+			Empty:        c.empty,
+			Top:          top,
+		}
+	}
+	return res, nil
+}