@tokscale/cli 1.0.5 → 1.0.7

package/src/graph-types.ts

@@ -0,0 +1,188 @@
+/**
+ * Type definitions for contribution graph data
+ * Note: intensity is calculated based on COST ($), not tokens
+ */
+
+/**
+ * Valid source identifiers
+ */
+export type SourceType = "opencode" | "claude" | "codex" | "gemini" | "cursor";
+
+/**
+ * Token breakdown by category
+ */
+export interface TokenBreakdown {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  reasoning: number;
+}
+
+/**
+ * Per-source contribution for a single day
+ */
+export interface SourceContribution {
+  /** Source identifier */
+  source: SourceType;
+
+  /** Exact model ID as reported by the source */
+  modelId: string;
+
+  /** Provider ID if available */
+  providerId?: string;
+
+  /** Token counts */
+  tokens: TokenBreakdown;
+
+  /** Calculated cost for this source/model combination */
+  cost: number;
+
+  /** Number of messages/requests */
+  messages: number;
+}
+
+/**
+ * Daily contribution entry with full granularity
+ */
+export interface DailyContribution {
+  /** ISO date string (YYYY-MM-DD) */
+  date: string;
+
+  /** Aggregated totals for the day */
+  totals: {
+    /** Total tokens (input + output + cache) */
+    tokens: number;
+    /** Total cost in USD */
+    cost: number;
+    /** Number of messages/requests */
+    messages: number;
+  };
+
+  /**
+   * Calculated intensity grade (0-4)
+   * Based on COST, not tokens
+   * 0 = no activity, 4 = highest cost relative to max
+   */
+  intensity: 0 | 1 | 2 | 3 | 4;
+
+  /** Token breakdown by category (aggregated across all sources) */
+  tokenBreakdown: TokenBreakdown;
+
+  /** Per-source breakdown with model information */
+  sources: SourceContribution[];
+}
+
+/**
+ * Year-level summary
+ */
+export interface YearSummary {
+  /** Year as string (e.g., "2024") */
+  year: string;
+
+  /** Total tokens for the year */
+  totalTokens: number;
+
+  /** Total cost for the year */
+  totalCost: number;
+
+  /** Date range for this year's data */
+  range: {
+    start: string;
+    end: string;
+  };
+}
+
+/**
+ * Summary statistics
+ */
+export interface DataSummary {
+  /** Total tokens across all time */
+  totalTokens: number;
+
+  /** Total cost across all time */
+  totalCost: number;
+
+  /** Total number of days in date range */
+  totalDays: number;
+
+  /** Number of days with activity */
+  activeDays: number;
+
+  /** Average cost per day (based on active days) */
+  averagePerDay: number;
+
+  /** Maximum cost in a single day (used for intensity calculation) */
+  maxCostInSingleDay: number;
+
+  /** All sources present in the data */
+  sources: SourceType[];
+
+  /** All unique model IDs across all sources */
+  models: string[];
+}
+
+/**
+ * Metadata about the export
+ */
+export interface ExportMeta {
+  /** ISO timestamp of when the data was generated */
+  generatedAt: string;
+
+  /** CLI version that generated this data */
+  version: string;
+
+  /** Date range of the data */
+  dateRange: {
+    start: string;
+    end: string;
+  };
+}
+
+/**
+ * Root data structure exported by CLI
+ * This is the complete JSON schema for contribution graph data
+ */
+export interface TokenContributionData {
+  /** Metadata about the export */
+  meta: ExportMeta;
+
+  /** Summary statistics */
+  summary: DataSummary;
+
+  /** Year-by-year breakdown for multi-year views */
+  years: YearSummary[];
+
+  /** Daily contribution data - the core dataset */
+  contributions: DailyContribution[];
+}
+
+/**
+ * Options for graph data generation
+ */
+export interface GraphOptions {
+  /** Filter to specific sources */
+  sources?: SourceType[];
+
+  /** Start date filter (ISO format) */
+  since?: string;
+
+  /** End date filter (ISO format) */
+  until?: string;
+
+  /** Filter to specific year */
+  year?: string;
+}
+
+/**
+ * Unified message format for aggregation
+ * Used internally to normalize data from different sources
+ */
+export interface UnifiedMessage {
+  source: SourceType;
+  modelId: string;
+  providerId?: string;
+  timestamp: number; // Unix milliseconds
+  tokens: TokenBreakdown;
+  cost: number;
+}

package/src/graph.ts

@@ -0,0 +1,485 @@
+/**
+ * Graph data generation module
+ * Aggregates token usage data by date for contribution graph visualization
+ *
+ * Key design: intensity is calculated based on COST ($), not tokens
+ * 
+ * This module supports two implementations:
+ * - Native Rust (fast, ~10x faster) - used when available
+ * - Pure TypeScript (fallback) - always available
+ */
+
+import { format } from "date-fns";
+import {
+  parseOpenCodeMessages,
+  parseClaudeCodeMessages,
+  parseCodexMessages,
+  parseGeminiMessages,
+} from "./sessions/index.js";
+import { PricingFetcher } from "./pricing.js";
+import type {
+  TokenContributionData,
+  DailyContribution,
+  YearSummary,
+  DataSummary,
+  GraphOptions,
+  UnifiedMessage,
+  SourceType,
+} from "./graph-types.js";
+
+const VERSION = "1.0.0";
+
+// Try to load native module
+let nativeModule: typeof import("./native.js") | null = null;
+try {
+  nativeModule = await import("./native.js");
+} catch {
+  // Native module not available, will use TypeScript implementation
+}
+
+/**
+ * Check if native implementation is available
+ */
+export function isNativeAvailable(): boolean {
+  return nativeModule?.isNativeAvailable() ?? false;
+}
+
+/**
+ * Generate contribution graph data from all sources
+ * 
+ * Uses native Rust implementation if available, falls back to TypeScript.
+ * Set `options.forceTypescript = true` to skip native module.
+ */
+export async function generateGraphData(
+  options: GraphOptions & { forceTypescript?: boolean } = {}
+): Promise<TokenContributionData> {
+  // Try native implementation first (unless forced to use TypeScript)
+  if (!options.forceTypescript && nativeModule?.isNativeAvailable()) {
+    try {
+      return nativeModule.generateGraphNative(options);
+    } catch (e) {
+      // Fall through to TypeScript implementation
+      console.warn("Native module failed, falling back to TypeScript:", e);
+    }
+  }
+  
+  // TypeScript implementation
+  return generateGraphDataTS(options);
+}
+
+/**
+ * Pure TypeScript implementation of graph data generation
+ */
+export async function generateGraphDataTS(
+  options: GraphOptions = {}
+): Promise<TokenContributionData> {
+  const fetcher = new PricingFetcher();
+  await fetcher.fetchPricing();
+
+  // Collect all messages from enabled sources
+  const messages = collectMessages(options, fetcher);
+
+  // Filter by date range
+  const filteredMessages = filterMessagesByDate(messages, options);
+
+  // Aggregate by date
+  const dailyMap = aggregateByDate(filteredMessages, fetcher);
+
+  // Convert to sorted array
+  let contributions = Array.from(dailyMap.values()).sort((a, b) =>
+    a.date.localeCompare(b.date)
+  );
+
+  // Calculate intensity based on COST
+  contributions = calculateAllIntensities(contributions);
+
+  // Build final structure
+  const summary = calculateSummary(contributions);
+  const years = calculateYears(contributions);
+
+  const dateRange = {
+    start: contributions[0]?.date ?? "",
+    end: contributions[contributions.length - 1]?.date ?? "",
+  };
+
+  return {
+    meta: {
+      generatedAt: new Date().toISOString(),
+      version: VERSION,
+      dateRange,
+    },
+    summary,
+    years,
+    contributions,
+  };
+}
+
+/**
+ * Collect messages from all enabled sources
+ */
+function collectMessages(
+  options: GraphOptions,
+  fetcher: PricingFetcher
+): UnifiedMessage[] {
+  const messages: UnifiedMessage[] = [];
+  const enabledSources = getEnabledSources(options);
+
+  // OpenCode
+  if (enabledSources.includes("opencode")) {
+    const openCodeMessages = parseOpenCodeMessages();
+    for (const msg of openCodeMessages) {
+      const pricing = fetcher.getModelPricing(msg.modelId);
+      const cost = pricing
+        ? fetcher.calculateCost(
+            {
+              input: msg.tokens.input,
+              output: msg.tokens.output,
+              reasoning: msg.tokens.reasoning,
+              cacheRead: msg.tokens.cacheRead,
+              cacheWrite: msg.tokens.cacheWrite,
+            },
+            pricing
+          )
+        : 0;
+
+      messages.push({
+        source: "opencode",
+        modelId: msg.modelId,
+        providerId: msg.providerId,
+        timestamp: msg.timestamp,
+        tokens: msg.tokens,
+        cost,
+      });
+    }
+  }
+
+  // Claude Code
+  if (enabledSources.includes("claude")) {
+    const claudeMessages = parseClaudeCodeMessages();
+    for (const msg of claudeMessages) {
+      const pricing = fetcher.getModelPricing(msg.modelId);
+      const cost = pricing
+        ? fetcher.calculateCost(
+            {
+              input: msg.tokens.input,
+              output: msg.tokens.output,
+              cacheRead: msg.tokens.cacheRead,
+              cacheWrite: msg.tokens.cacheWrite,
+            },
+            pricing
+          )
+        : 0;
+
+      messages.push({
+        source: "claude",
+        modelId: msg.modelId,
+        providerId: msg.providerId,
+        timestamp: msg.timestamp,
+        tokens: msg.tokens,
+        cost,
+      });
+    }
+  }
+
+  // Codex
+  if (enabledSources.includes("codex")) {
+    const codexMessages = parseCodexMessages();
+    for (const msg of codexMessages) {
+      const pricing = fetcher.getModelPricing(msg.modelId);
+      const cost = pricing
+        ? fetcher.calculateCost(
+            {
+              input: msg.tokens.input,
+              output: msg.tokens.output,
+              cacheRead: msg.tokens.cacheRead,
+              cacheWrite: msg.tokens.cacheWrite,
+            },
+            pricing
+          )
+        : 0;
+
+      messages.push({
+        source: "codex",
+        modelId: msg.modelId,
+        providerId: msg.providerId,
+        timestamp: msg.timestamp,
+        tokens: msg.tokens,
+        cost,
+      });
+    }
+  }
+
+  // Gemini
+  if (enabledSources.includes("gemini")) {
+    const geminiMessages = parseGeminiMessages();
+    for (const msg of geminiMessages) {
+      const pricing = fetcher.getModelPricing(msg.modelId);
+      // Gemini: thoughts/reasoning count as output for billing
+      const cost = pricing
+        ? fetcher.calculateCost(
+            {
+              input: msg.tokens.input,
+              output: msg.tokens.output + msg.tokens.reasoning,
+              cacheRead: 0, // Gemini cached tokens are free
+              cacheWrite: 0,
+            },
+            pricing
+          )
+        : 0;
+
+      messages.push({
+        source: "gemini",
+        modelId: msg.modelId,
+        providerId: msg.providerId,
+        timestamp: msg.timestamp,
+        tokens: msg.tokens,
+        cost,
+      });
+    }
+  }
+
+  return messages;
+}
+
+/**
+ * Get list of enabled sources based on options
+ */
+function getEnabledSources(options: GraphOptions): SourceType[] {
+  if (options.sources && options.sources.length > 0) {
+    return options.sources;
+  }
+  return ["opencode", "claude", "codex", "gemini"];
+}
+
+/**
+ * Filter messages by date range
+ */
+function filterMessagesByDate(
+  messages: UnifiedMessage[],
+  options: GraphOptions
+): UnifiedMessage[] {
+  let filtered = messages;
+
+  // Filter by year
+  if (options.year) {
+    const yearStart = new Date(`${options.year}-01-01`).getTime();
+    const yearEnd = new Date(`${options.year}-12-31T23:59:59.999`).getTime();
+    filtered = filtered.filter(
+      (m) => m.timestamp >= yearStart && m.timestamp <= yearEnd
+    );
+  }
+
+  // Filter by since
+  if (options.since) {
+    const sinceTime = new Date(options.since).getTime();
+    filtered = filtered.filter((m) => m.timestamp >= sinceTime);
+  }
+
+  // Filter by until
+  if (options.until) {
+    const untilTime = new Date(`${options.until}T23:59:59.999`).getTime();
+    filtered = filtered.filter((m) => m.timestamp <= untilTime);
+  }
+
+  return filtered;
+}
+
+/**
+ * Aggregate messages by date
+ */
+function aggregateByDate(
+  messages: UnifiedMessage[],
+  _fetcher: PricingFetcher
+): Map<string, DailyContribution> {
+  const dailyMap = new Map<string, DailyContribution>();
+
+  for (const msg of messages) {
+    const dateKey = format(new Date(msg.timestamp), "yyyy-MM-dd");
+
+    let daily = dailyMap.get(dateKey);
+    if (!daily) {
+      daily = createEmptyDailyContribution(dateKey);
+      dailyMap.set(dateKey, daily);
+    }
+
+    // Update totals
+    const totalTokens =
+      msg.tokens.input +
+      msg.tokens.output +
+      msg.tokens.cacheRead +
+      msg.tokens.cacheWrite +
+      msg.tokens.reasoning;
+
+    daily.totals.tokens += totalTokens;
+    daily.totals.cost += msg.cost;
+    daily.totals.messages += 1;
+
+    // Update token breakdown
+    daily.tokenBreakdown.input += msg.tokens.input;
+    daily.tokenBreakdown.output += msg.tokens.output;
+    daily.tokenBreakdown.cacheRead += msg.tokens.cacheRead;
+    daily.tokenBreakdown.cacheWrite += msg.tokens.cacheWrite;
+    daily.tokenBreakdown.reasoning += msg.tokens.reasoning;
+
+    // Update source contributions
+    let sourceContrib = daily.sources.find(
+      (s) => s.source === msg.source && s.modelId === msg.modelId
+    );
+
+    if (!sourceContrib) {
+      sourceContrib = {
+        source: msg.source,
+        modelId: msg.modelId,
+        providerId: msg.providerId,
+        tokens: {
+          input: 0,
+          output: 0,
+          cacheRead: 0,
+          cacheWrite: 0,
+          reasoning: 0,
+        },
+        cost: 0,
+        messages: 0,
+      };
+      daily.sources.push(sourceContrib);
+    }
+
+    sourceContrib.tokens.input += msg.tokens.input;
+    sourceContrib.tokens.output += msg.tokens.output;
+    sourceContrib.tokens.cacheRead += msg.tokens.cacheRead;
+    sourceContrib.tokens.cacheWrite += msg.tokens.cacheWrite;
+    sourceContrib.tokens.reasoning += msg.tokens.reasoning;
+    sourceContrib.cost += msg.cost;
+    sourceContrib.messages += 1;
+  }
+
+  return dailyMap;
+}
+
+/**
+ * Create empty daily contribution
+ */
+function createEmptyDailyContribution(date: string): DailyContribution {
+  return {
+    date,
+    totals: {
+      tokens: 0,
+      cost: 0,
+      messages: 0,
+    },
+    intensity: 0,
+    tokenBreakdown: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      reasoning: 0,
+    },
+    sources: [],
+  };
+}
+
+/**
+ * Calculate intensity for all contributions based on COST
+ */
+function calculateAllIntensities(
+  contributions: DailyContribution[]
+): DailyContribution[] {
+  if (contributions.length === 0) return contributions;
+
+  // Find max cost for intensity calculation
+  const maxCost = Math.max(...contributions.map((c) => c.totals.cost));
+
+  return contributions.map((c) => ({
+    ...c,
+    intensity: calculateIntensity(c.totals.cost, maxCost),
+  }));
+}
+
+/**
+ * Calculate intensity grade based on cost ratio
+ * 0 = no activity, 4 = highest
+ */
+function calculateIntensity(
+  cost: number,
+  maxCost: number
+): 0 | 1 | 2 | 3 | 4 {
+  if (cost === 0 || maxCost === 0) return 0;
+  const ratio = cost / maxCost;
+  if (ratio >= 0.75) return 4;
+  if (ratio >= 0.5) return 3;
+  if (ratio >= 0.25) return 2;
+  return 1;
+}
+
+/**
+ * Calculate summary statistics
+ */
+function calculateSummary(contributions: DailyContribution[]): DataSummary {
+  const totalTokens = contributions.reduce((sum, c) => sum + c.totals.tokens, 0);
+  const totalCost = contributions.reduce((sum, c) => sum + c.totals.cost, 0);
+  const activeDays = contributions.filter((c) => c.totals.cost > 0).length;
+  const maxCostInSingleDay = Math.max(
+    ...contributions.map((c) => c.totals.cost),
+    0
+  );
+
+  // Collect unique sources and models
+  const sourcesSet = new Set<SourceType>();
+  const modelsSet = new Set<string>();
+
+  for (const c of contributions) {
+    for (const s of c.sources) {
+      sourcesSet.add(s.source);
+      modelsSet.add(s.modelId);
+    }
+  }
+
+  return {
+    totalTokens,
+    totalCost,
+    totalDays: contributions.length,
+    activeDays,
+    averagePerDay: activeDays > 0 ? totalCost / activeDays : 0,
+    maxCostInSingleDay,
+    sources: Array.from(sourcesSet),
+    models: Array.from(modelsSet),
+  };
+}
+
+/**
+ * Calculate year summaries
+ */
+function calculateYears(contributions: DailyContribution[]): YearSummary[] {
+  const yearsMap = new Map<
+    string,
+    { tokens: number; cost: number; start: string; end: string }
+  >();
+
+  for (const c of contributions) {
+    const year = c.date.substring(0, 4);
+    let yearData = yearsMap.get(year);
+
+    if (!yearData) {
+      yearData = { tokens: 0, cost: 0, start: c.date, end: c.date };
+      yearsMap.set(year, yearData);
+    }
+
+    yearData.tokens += c.totals.tokens;
+    yearData.cost += c.totals.cost;
+    if (c.date < yearData.start) yearData.start = c.date;
+    if (c.date > yearData.end) yearData.end = c.date;
+  }
+
+  return Array.from(yearsMap.entries())
+    .map(([year, data]) => ({
+      year,
+      totalTokens: data.tokens,
+      totalCost: data.cost,
+      range: {
+        start: data.start,
+        end: data.end,
+      },
+    }))
+    .sort((a, b) => a.year.localeCompare(b.year));
+}