Add YTD realized income tax section to holding overview command

Author: bufdev

cmd/ibctl/internal/command/holding/holdingoverview/holdingoverview.go

@@ -0,0 +1,273 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package holdingoverview implements the "holding overview" command.
+// It prints the results of holding list, holding category list, holding geo list,
+// and holding value in sequence, separated by newlines.
+package holdingoverview
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+
+	"buf.build/go/app/appcmd"
+	"buf.build/go/app/appext"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/ibctlcmd"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlholdings"
+	"github.com/bufdev/ibctl/internal/pkg/cliio"
+	"github.com/spf13/pflag"
+)
+
+const (
+	// formatFlagName is the flag name for the output format.
+	formatFlagName = "format"
+	// downloadFlagName is the flag name for downloading fresh data before displaying.
+	downloadFlagName = "download"
+	// baseCurrencyFlagName is the flag name for the base currency for value conversion.
+	baseCurrencyFlagName = "base-currency"
+	// realtimeFlagName is the flag name for fetching real-time quotes and FX rates.
+	realtimeFlagName = "realtime"
+)
+
+// NewCommand returns a new holding overview command.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	flags := newFlags()
+	return &appcmd.Command{
+		Use:   name,
+		Short: "Display combined portfolio overview",
+		Long: `Display a combined portfolio overview showing holdings, category breakdown,
+geographic breakdown, and portfolio value with estimated tax impact.
+
+Equivalent to running holding list, holding category list, holding geo list,
+and holding value in sequence, separated by blank lines. Data is loaded once
+and shared across all sections.`,
+		Args: appcmd.NoArgs,
+		Run: builder.NewRunFunc(
+			func(ctx context.Context, container appext.Container) error {
+				return run(ctx, container, flags)
+			},
+		),
+		BindFlags: flags.Bind,
+	}
+}
+
+type flags struct {
+	// Format is the output format (table, csv, json).
+	Format string
+	// Download fetches fresh data before displaying.
+	Download bool
+	// BaseCurrency is the target currency for value conversion (e.g., "USD", "CAD").
+	BaseCurrency string
+	// Realtime fetches real-time quotes and FX rates from Yahoo Finance.
+	Realtime bool
+}
+
+func newFlags() *flags {
+	return &flags{}
+}
+
+// Bind registers the flag definitions with the given flag set.
+func (f *flags) Bind(flagSet *pflag.FlagSet) {
+	flagSet.StringVar(&f.Format, formatFlagName, "table", "Output format (table, csv, json)")
+	flagSet.BoolVar(&f.Download, downloadFlagName, false, "Download fresh data before displaying")
+	flagSet.StringVar(&f.BaseCurrency, baseCurrencyFlagName, "USD", "Base currency for value conversion (e.g., USD, CAD)")
+	flagSet.BoolVar(&f.Realtime, realtimeFlagName, false, "Fetch real-time quotes and FX rates from Yahoo Finance")
+}
+
+// overviewJSON is the combined JSON output for the overview command.
+type overviewJSON struct {
+	// Holdings is the list of individual holdings.
+	Holdings []*ibctlholdings.HoldingOverview `json:"holdings"`
+	// Categories is holdings aggregated by category.
+	Categories []*ibctlholdings.CategoryOverview `json:"categories"`
+	// Geos is holdings aggregated by geographic classification.
+	Geos []*ibctlholdings.GeoOverview `json:"geos"`
+	// Value is the portfolio value summary with tax impact.
+	Value *valueJSON `json:"value"`
+	// YTDTax is the YTD realized income tax summary.
+	YTDTax *ytdTaxJSON `json:"ytd_tax"`
+}
+
+// ytdTaxJSON is the YTD realized income tax summary for JSON output.
+type ytdTaxJSON struct {
+	// DividendMicros is the total YTD dividend income (including WHT) in base currency micros.
+	DividendMicros int64 `json:"dividend_micros"`
+	// DividendTaxMicros is the estimated tax on dividend income in micros.
+	DividendTaxMicros int64 `json:"dividend_tax_micros"`
+	// InterestMicros is the total YTD interest income in base currency micros.
+	InterestMicros int64 `json:"interest_micros"`
+	// InterestTaxMicros is the estimated tax on interest income in micros.
+	InterestTaxMicros int64 `json:"interest_tax_micros"`
+	// STCGMicros is the total YTD realized short-term capital gains in base currency micros.
+	STCGMicros int64 `json:"stcg_micros"`
+	// STCGTaxMicros is the estimated tax on realized STCG in micros.
+	STCGTaxMicros int64 `json:"stcg_tax_micros"`
+	// LTCGMicros is the total YTD realized long-term capital gains in base currency micros.
+	LTCGMicros int64 `json:"ltcg_micros"`
+	// LTCGTaxMicros is the estimated tax on realized LTCG in micros.
+	LTCGTaxMicros int64 `json:"ltcg_tax_micros"`
+	// TotalTaxOwedMicros is the total estimated tax owed across all income types.
+	TotalTaxOwedMicros int64 `json:"total_tax_owed_micros"`
+	// TaxPaidMicros is the total tax already paid, converted to base currency.
+	TaxPaidMicros int64 `json:"tax_paid_micros"`
+	// TaxRemainingMicros is the net tax remaining (owed minus paid).
+	TaxRemainingMicros int64 `json:"tax_remaining_micros"`
+	// TaxRateDividend is the dividend tax rate from config.
+	TaxRateDividend float64 `json:"tax_rate_dividend"`
+	// TaxRateInterest is the interest tax rate from config.
+	TaxRateInterest float64 `json:"tax_rate_interest"`
+	// TaxRateSTCG is the short-term capital gains tax rate from config.
+	TaxRateSTCG float64 `json:"tax_rate_stcg"`
+	// TaxRateLTCG is the long-term capital gains tax rate from config.
+	TaxRateLTCG float64 `json:"tax_rate_ltcg"`
+}
+
+// valueJSON is the portfolio value summary for JSON output.
+type valueJSON struct {
+	// PortfolioValueMicros is the total portfolio market value in micros.
+	PortfolioValueMicros int64 `json:"portfolio_value_micros"`
+	// STCGMicros is the total short-term capital gains in micros.
+	STCGMicros int64 `json:"stcg_micros"`
+	// STCGTaxMicros is the estimated short-term capital gains tax in micros.
+	STCGTaxMicros int64 `json:"stcg_tax_micros"`
+	// LTCGMicros is the total long-term capital gains in micros.
+	LTCGMicros int64 `json:"ltcg_micros"`
+	// LTCGTaxMicros is the estimated long-term capital gains tax in micros.
+	LTCGTaxMicros int64 `json:"ltcg_tax_micros"`
+	// TotalTaxMicros is the total estimated tax in micros.
+	TotalTaxMicros int64 `json:"total_tax_micros"`
+	// AfterTaxMicros is the after-tax portfolio value in micros.
+	AfterTaxMicros int64 `json:"after_tax_micros"`
+	// TaxRateSTCG is the short-term capital gains tax rate from config.
+	TaxRateSTCG float64 `json:"tax_rate_stcg"`
+	// TaxRateLTCG is the long-term capital gains tax rate from config.
+	TaxRateLTCG float64 `json:"tax_rate_ltcg"`
+}
+
+func run(ctx context.Context, container appext.Container, flags *flags) error {
+	format, err := cliio.ParseFormat(flags.Format)
+	if err != nil {
+		return appcmd.NewInvalidArgumentError(err.Error())
+	}
+	// Load data through the common pipeline (config, merge, FX, optional download/realtime).
+	data, err := ibctlcmd.LoadHoldingsData(ctx, container, flags.Download, flags.Realtime, flags.BaseCurrency)
+	if err != nil {
+		return err
+	}
+	// Compute holdings via FIFO from all trade data, verified against IBKR positions.
+	result, err := ibctlholdings.GetHoldingsOverview(data.MergedData.Trades, data.MergedData.Positions, data.MergedData.CashPositions, data.Config, data.FxStore, data.BaseCurrency)
+	if err != nil {
+		return err
+	}
+	// Log any data inconsistencies detected during computation.
+	ibctlcmd.LogHoldingsResult(container, result)
+	// Aggregate holdings by category and geo with no filters for the overview.
+	categories := ibctlholdings.GetCategoryList(result.Holdings, "")
+	geos := ibctlholdings.GetGeoList(result.Holdings, "")
+	// Compute portfolio value summary for the value section.
+	summary := ibctlcmd.ComputeValueSummary(result.Holdings, data.Config)
+	// Compute YTD realized income tax summary.
+	ytdSummary, err := ibctlcmd.ComputeYTDTaxSummary(data.MergedData, data.Config, data.FxStore, data.BaseCurrency)
+	if err != nil {
+		return err
+	}
+	// Write output in the requested format.
+	formatBase := ibctlcmd.FormatBaseFunc(data.BaseCurrency)
+	formatBaseMicros := ibctlcmd.FormatBaseMicrosFunc(data.BaseCurrency)
+	writer := os.Stdout
+	switch format {
+	case cliio.FormatTable:
+		// Section 1: holding list table.
+		if err := ibctlcmd.WriteHoldingListTable(writer, result.Holdings, data.BaseCurrency, formatBase, formatBaseMicros); err != nil {
+			return err
+		}
+		fmt.Fprintln(writer)
+		// Section 2: holding category list table.
+		if err := ibctlcmd.WriteCategoryListTable(writer, categories, data.BaseCurrency, formatBase); err != nil {
+			return err
+		}
+		fmt.Fprintln(writer)
+		// Section 3: holding geo list table.
+		if err := ibctlcmd.WriteGeoListTable(writer, geos, data.BaseCurrency, formatBase); err != nil {
+			return err
+		}
+		fmt.Fprintln(writer)
+		// Section 4: holding value text summary.
+		ibctlcmd.WriteValueSummary(writer, summary, data.Config, formatBaseMicros)
+		fmt.Fprintln(writer)
+		// Section 5: YTD realized income tax summary.
+		ibctlcmd.WriteYTDTaxSummary(writer, ytdSummary, data.Config, formatBaseMicros)
+		return nil
+	case cliio.FormatCSV:
+		// Section 1: holding list CSV.
+		if err := ibctlcmd.WriteHoldingListCSV(writer, result.Holdings, data.BaseCurrency); err != nil {
+			return err
+		}
+		fmt.Fprintln(writer)
+		// Section 2: holding category list CSV.
+		if err := ibctlcmd.WriteCategoryListCSV(writer, categories, data.BaseCurrency); err != nil {
+			return err
+		}
+		fmt.Fprintln(writer)
+		// Section 3: holding geo list CSV.
+		if err := ibctlcmd.WriteGeoListCSV(writer, geos, data.BaseCurrency); err != nil {
+			return err
+		}
+		fmt.Fprintln(writer)
+		// Section 4: holding value text summary.
+		ibctlcmd.WriteValueSummary(writer, summary, data.Config, formatBaseMicros)
+		fmt.Fprintln(writer)
+		// Section 5: YTD realized income tax summary.
+		ibctlcmd.WriteYTDTaxSummary(writer, ytdSummary, data.Config, formatBaseMicros)
+		return nil
+	case cliio.FormatJSON:
+		// Combined JSON object with all five sections.
+		overview := &overviewJSON{
+			Holdings:   result.Holdings,
+			Categories: categories,
+			Geos:       geos,
+			Value: &valueJSON{
+				PortfolioValueMicros: summary.TotalValueMicros,
+				STCGMicros:           summary.TotalSTCGMicros,
+				STCGTaxMicros:        summary.STCGTaxMicros,
+				LTCGMicros:           summary.TotalLTCGMicros,
+				LTCGTaxMicros:        summary.LTCGTaxMicros,
+				TotalTaxMicros:       summary.TotalTaxMicros,
+				AfterTaxMicros:       summary.AfterTaxMicros,
+				TaxRateSTCG:          data.Config.TaxRateSTCG,
+				TaxRateLTCG:          data.Config.TaxRateLTCG,
+			},
+			YTDTax: &ytdTaxJSON{
+				DividendMicros:     ytdSummary.DividendMicros,
+				DividendTaxMicros:  ytdSummary.DividendTaxMicros,
+				InterestMicros:     ytdSummary.InterestMicros,
+				InterestTaxMicros:  ytdSummary.InterestTaxMicros,
+				STCGMicros:         ytdSummary.STCGMicros,
+				STCGTaxMicros:      ytdSummary.STCGTaxMicros,
+				LTCGMicros:         ytdSummary.LTCGMicros,
+				LTCGTaxMicros:      ytdSummary.LTCGTaxMicros,
+				TotalTaxOwedMicros: ytdSummary.TotalTaxOwedMicros,
+				TaxPaidMicros:      ytdSummary.TaxPaidMicros,
+				TaxRemainingMicros: ytdSummary.TaxRemainingMicros,
+				TaxRateDividend:    data.Config.TaxRateDividend,
+				TaxRateInterest:    data.Config.TaxRateInterest,
+				TaxRateSTCG:        data.Config.TaxRateSTCG,
+				TaxRateLTCG:        data.Config.TaxRateLTCG,
+			},
+		}
+		jsonData, err := json.Marshal(overview)
+		if err != nil {
+			return err
+		}
+		if _, err := writer.Write(jsonData); err != nil {
+			return err
+		}
+		_, err = writer.WriteString("\n")
+		return err
+	default:
+		return appcmd.NewInvalidArgumentErrorf("unsupported format: %s", format)
+	}
+}