feat(updater): add mandatory returnsBasis and performanceAsOf to metrics (#41)

* feat(updater): add mandatory returnsBasis and performanceAsOf to metrics

* chore(data): backfill returnsBasis and performanceAsOf

Author: daggerok

README.md

@@ -44,6 +44,8 @@ Each fund carries a derived `metrics` object that powers the catalog columns sha
 - `siAnn` - since-inception annualized -> *SI Ann.*
 - `dividendYield` - 12-month trailing yield or indicated yield (latest distribution x frequency / price)
 - `secYield` - 30-day SEC yield when published; unavailable values stay empty and are never shown as 0
+- `returnsBasis` - mandatory non-empty text saying how the returns were computed: official WisdomTree month-end Market Price Returns (gaps filled with Yahoo estimates), or estimates derived from Yahoo adjusted closes when the product page is unavailable
+- `performanceAsOf` - mandatory ISO `YYYY-MM-DD` date the returns are as of: the WisdomTree month-end performance table date, or the last Yahoo close date when derived (not the NAV date); `null` only when truly unknown
 - NAV and the catalog figures come from WisdomTree; history and returns derived from Yahoo adjusted closes are market-price estimates, not official NAV returns
 - A limited `HISTORY_RANGE` shortens the published history, so long-tenor figures derived from Yahoo are unavailable for ranges shorter than the tenor
 

api/wisdomtree/index.json

@@ -140,7 +140,8 @@
         "dividendYieldText": "3.73%",
         "secYield": 3.81,
         "secYieldText": "3.81%",
-        "returnsBasis": "WisdomTree product-page Market Price Returns where published; Yahoo adjusted market-price closes for missing values"
+        "returnsBasis": "official WisdomTree product-page Market Price Returns (month-end table); gaps filled with estimates derived from Yahoo Finance adjusted closes",
+        "performanceAsOf": "2026-08-31"
       },
       "holdings": 5,
       "history": 3184

scripts/update-data.test.ts

@@ -4,6 +4,10 @@ import { describe, expect, test } from 'bun:test';
 import { readFileSync } from 'node:fs';
 import {
   annualizedToTotal,
+  deriveMetrics,
+  performanceAsOfDate,
+  RETURNS_BASIS_OFFICIAL,
+  RETURNS_BASIS_DERIVED,
   cleanHoldingTicker,
   inferDistributionFrequency,
   mergeDistributionRecords,
@@ -230,6 +234,24 @@ describe('Yahoo chart and derived metrics', () => {
     expect(annualizedToTotal(10, 3)).toBe(33.1);
   });
 
+  test('metrics end with returnsBasis then performanceAsOf', () => {
+    const days = [
+      { date: '2025-01-02', close: 100, adjClose: 100, volume: 1 },
+      { date: '2026-01-02', close: 110, adjClose: 110, volume: 1 },
+    ];
+    const fund = { dividendYield: null, secYield: null } as any;
+    const derived = priceReturns(days, new Date('2026-01-03T00:00:00Z'));
+    const estimated = deriveMetrics(derived, fund, [], { paymentsPerYear: null }, 110);
+    expect(estimated.returnsBasis).toBe(RETURNS_BASIS_DERIVED);
+    expect(estimated.performanceAsOf).toBe('2026-01-02');
+    expect(Object.keys(estimated).slice(-2)).toEqual(['returnsBasis', 'performanceAsOf']);
+    const official = deriveMetrics({ ...derived, asOfDate: '2025-12-31' }, fund, [], { paymentsPerYear: null }, 110, true);
+    expect(official.returnsBasis).toBe(RETURNS_BASIS_OFFICIAL);
+    expect(official.performanceAsOf).toBe('2025-12-31');
+    expect(performanceAsOfDate({ ...derived, asOfDate: '' })).toBeNull();
+    expect(estimated.ytd).not.toBe(0);
+  });
+
   test('frequency inference follows the shared ETF updater convention', () => {
     const monthly = [0, 1, 2, 3].map((month) => ({ epoch: Date.UTC(2026, month, 15) / 1000, amount: 0.1 }));
     expect(inferDistributionFrequency(monthly)).toEqual({ frequency: 'Monthly', paymentsPerYear: 12 });

scripts/update-data.ts

@@ -1258,7 +1258,16 @@ function lastCompletedQuarterEnd(now = new Date()): string {
   return day.toISOString().slice(0, 10);
 }
 
-function deriveMetrics(derived: PriceReturns, fund: CatalogFund, dividends: Array<{ epoch: number; amount: number }>, frequency: { paymentsPerYear: number | null }, price: number | null): JsonRecord {
+export const RETURNS_BASIS_OFFICIAL = 'official WisdomTree product-page Market Price Returns (month-end table); gaps filled with estimates derived from Yahoo Finance adjusted closes';
+export const RETURNS_BASIS_DERIVED = 'estimates derived from Yahoo Finance adjusted market-price closes, not official WisdomTree NAV returns';
+
+/** performanceAsOf: the provider's month-end performance table date, or the last Yahoo close date when derived; null when unknown. */
+export function performanceAsOfDate(returns: PriceReturns): string | null {
+  const iso = toIsoDate(returns.asOfDate);
+  return /^\d{4}-\d{2}-\d{2}$/.test(iso) ? iso : null;
+}
+
+export function deriveMetrics(derived: PriceReturns, fund: CatalogFund, dividends: Array<{ epoch: number; amount: number }>, frequency: { paymentsPerYear: number | null }, price: number | null, official = false): JsonRecord {
   const latest = dividends[dividends.length - 1];
   const indicated = fund.dividendYield ?? (latest && frequency.paymentsPerYear && price ? round((latest.amount * frequency.paymentsPerYear / price) * 100, 2) : null);
   return {
@@ -1275,7 +1284,8 @@ function deriveMetrics(derived: PriceReturns, fund: CatalogFund, dividends: Arra
     dividendYieldText: indicated === null ? '—' : `${indicated.toFixed(2)}%`,
     secYield: fund.secYield,
     secYieldText: fund.secYield === null ? '—' : `${fund.secYield.toFixed(2)}%`,
-    returnsBasis: 'adjusted market-price closes (Yahoo chart API), not official WisdomTree NAV returns',
+    returnsBasis: official ? RETURNS_BASIS_OFFICIAL : RETURNS_BASIS_DERIVED,
+    performanceAsOf: performanceAsOfDate(derived),
   };
 }
 
@@ -1584,10 +1594,7 @@ async function processFund(fund: CatalogFund, config: UpdaterConfig, previous: J
   const officialReturns = productSummary?.officialReturns.monthEnd || null;
   const effectiveReturns = mergeOfficialReturns(derived, officialReturns);
   const price = productSummary?.marketPrice ?? chart?.regularMarketPrice ?? (days.length ? days[days.length - 1].close : numberOrNull(previous.closePriceValue));
-  const metrics = deriveMetrics(effectiveReturns, fund, distributionEvents, frequency, price);
-  if (officialReturns) {
-    metrics.returnsBasis = 'WisdomTree product-page Market Price Returns where published; Yahoo adjusted market-price closes for missing values';
-  }
+  const metrics = deriveMetrics(effectiveReturns, fund, distributionEvents, frequency, price, Boolean(officialReturns));
   const returnFilterReasons = matchesReturnFilters(metrics, config);
   if (returnFilterReasons.length) {
     return { __skipped: true, ticker: fund.ticker, __skipReasons: returnFilterReasons };