sigmap 7.0.0 → 7.1.0

package/src/tracking/aggregate.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * SigMap usage aggregation for the `gain` dashboard.
+ *
+ * Pure, zero-dependency functions that turn raw NDJSON usage records into the
+ * totals / by-operation / time-bucket shapes the terminal renderer consumes.
+ *
+ * Tolerant of BOTH schemas:
+ *   - new:    { op, baselineTokens, actualTokens, savedTokens, savedPct, durationMs, model }
+ *   - legacy: { rawTokens, finalTokens, reductionPct }   (from logger.js v0.9)
+ *
+ * "saved" is a counterfactual estimate (baseline − actual), never a measured
+ * delta. Callers are responsible for labeling it as such in the UI.
+ */
+
+const { resolvePrice } = require('./pricing');
+
+const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+
+/**
+ * Normalize one raw record into a canonical shape.
+ * @param {object} rec
+ */
+function normalize(rec) {
+  const baseline = num(rec.baselineTokens != null ? rec.baselineTokens : rec.rawTokens);
+  const actual = num(rec.actualTokens != null ? rec.actualTokens : rec.finalTokens);
+  const saved = rec.savedTokens != null ? num(rec.savedTokens) : Math.max(0, baseline - actual);
+  const savedPct = rec.savedPct != null
+    ? num(rec.savedPct)
+    : rec.reductionPct != null
+      ? num(rec.reductionPct)
+      : baseline > 0 ? (saved / baseline) * 100 : 0;
+  return {
+    ts: rec.ts || null,
+    op: normalizeOp(rec.op),
+    baseline,
+    actual,
+    saved,
+    savedPct: clamp(savedPct, 0, 100),
+    durationMs: num(rec.durationMs),
+    model: rec.model || null,
+  };
+}
+
+function normalizeOp(op) {
+  if (!op) return 'generate';
+  return String(op);
+}
+
+function num(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * Parse a --since value into a cutoff Date (or null for "all time").
+ * Accepts: "7d", "30d", "12h", or an ISO date "2026-06-01".
+ * @param {string} since
+ * @param {number} [nowMs] - injectable clock for tests
+ * @returns {Date|null}
+ */
+function parseSince(since, nowMs) {
+  if (!since) return null;
+  const now = nowMs != null ? nowMs : Date.now();
+  const rel = /^(\d+)([dhw])$/.exec(String(since).trim());
+  if (rel) {
+    const n = parseInt(rel[1], 10);
+    const unit = rel[2];
+    const ms = unit === 'h' ? 3.6e6 : unit === 'w' ? 6.048e8 : 8.64e7;
+    return new Date(now - n * ms);
+  }
+  const d = new Date(since);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * Bucket records by calendar granularity.
+ * @param {object[]} records - normalized records
+ * @param {'day'|'week'|'month'} granularity
+ * @returns {Array<{key,count,baseline,actual,saved,savedPct,ms}>} ascending by key
+ */
+function bucketBy(records, granularity) {
+  const map = new Map();
+  for (const r of records) {
+    if (!r.ts) continue;
+    const key = bucketKey(r.ts, granularity);
+    if (!key) continue;
+    let b = map.get(key);
+    if (!b) { b = { key, count: 0, baseline: 0, actual: 0, saved: 0, ms: 0 }; map.set(key, b); }
+    b.count += 1;
+    b.baseline += r.baseline;
+    b.actual += r.actual;
+    b.saved += r.saved;
+    b.ms += r.durationMs;
+  }
+  return [...map.values()]
+    .map((b) => ({ ...b, savedPct: b.baseline > 0 ? clamp((b.saved / b.baseline) * 100, 0, 100) : 0 }))
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+
+function bucketKey(ts, granularity) {
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return null;
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  if (granularity === 'month') return `${y}-${m}`;
+  if (granularity === 'week') {
+    // ISO-ish: key by the Monday (UTC) of that week.
+    const tmp = new Date(Date.UTC(y, d.getUTCMonth(), d.getUTCDate()));
+    const dow = (tmp.getUTCDay() + 6) % 7; // 0 = Monday
+    tmp.setUTCDate(tmp.getUTCDate() - dow);
+    return `${tmp.getUTCFullYear()}-${String(tmp.getUTCMonth() + 1).padStart(2, '0')}-${String(tmp.getUTCDate()).padStart(2, '0')}`;
+  }
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * Full aggregation for the `gain` dashboard.
+ * @param {object[]} rawRecords
+ * @param {object} [opts]
+ * @param {string} [opts.model]   pricing model
+ * @param {string} [opts.since]   window filter
+ * @param {number} [opts.top]     limit byOp rows (0 = all)
+ * @param {number} [opts.nowMs]   injectable clock
+ * @returns {object}
+ */
+function aggregate(rawRecords, opts = {}) {
+  const price = resolvePrice(opts.model);
+  const cutoff = parseSince(opts.since, opts.nowMs);
+
+  let records = (rawRecords || []).map(normalize);
+  if (cutoff) records = records.filter((r) => r.ts && new Date(r.ts) >= cutoff);
+
+  const totals = {
+    count: records.length,
+    baseline: 0,
+    actual: 0,
+    saved: 0,
+    totalMs: 0,
+    savedPct: 0,
+    avgMs: 0,
+    usdSaved: 0,
+    firstTs: null,
+    lastTs: null,
+  };
+
+  const opMap = new Map();
+  for (const r of records) {
+    totals.baseline += r.baseline;
+    totals.actual += r.actual;
+    totals.saved += r.saved;
+    totals.totalMs += r.durationMs;
+    if (r.ts) {
+      if (!totals.firstTs || r.ts < totals.firstTs) totals.firstTs = r.ts;
+      if (!totals.lastTs || r.ts > totals.lastTs) totals.lastTs = r.ts;
+    }
+    let o = opMap.get(r.op);
+    if (!o) { o = { op: r.op, count: 0, baseline: 0, saved: 0, ms: 0 }; opMap.set(r.op, o); }
+    o.count += 1;
+    o.baseline += r.baseline;
+    o.saved += r.saved;
+    o.ms += r.durationMs;
+  }
+
+  totals.savedPct = totals.baseline > 0 ? clamp((totals.saved / totals.baseline) * 100, 0, 100) : 0;
+  totals.avgMs = totals.count > 0 ? Math.round(totals.totalMs / totals.count) : 0;
+  totals.usdSaved = totals.saved * price.perToken;
+
+  let byOp = [...opMap.values()].map((o) => ({
+    op: o.op,
+    count: o.count,
+    saved: o.saved,
+    avgPct: o.baseline > 0 ? clamp((o.saved / o.baseline) * 100, 0, 100) : 0,
+    avgMs: o.count > 0 ? Math.round(o.ms / o.count) : 0,
+    usdSaved: o.saved * price.perToken,
+    sharePct: totals.saved > 0 ? (o.saved / totals.saved) * 100 : 0,
+  })).sort((a, b) => b.saved - a.saved);
+
+  if (opts.top && opts.top > 0) byOp = byOp.slice(0, opts.top);
+
+  return {
+    price,
+    totals,
+    byOp,
+    buckets: {
+      daily: bucketBy(records, 'day'),
+      weekly: bucketBy(records, 'week'),
+      monthly: bucketBy(records, 'month'),
+    },
+  };
+}
+
+module.exports = { aggregate, bucketBy, parseSince, normalize };

package/src/tracking/logger.js

@@ -18,6 +18,9 @@ const fs = require('fs');
 const path = require('path');
 
 const LOG_FILE = path.join('.context', 'usage.ndjson');
+// Dedicated log for the `gain` dashboard (extended schema). Kept separate from
+// usage.ndjson so the legacy health/nudge history never collides with it.
+const GAIN_FILE = path.join('.context', 'gain.ndjson');
 
 /**
  * Append one run entry to the usage log.
@@ -73,6 +76,25 @@ function readLog(cwd) {
   }
 }
 
+/**
+ * Read and parse all `gain` dashboard records (oldest first).
+ * @param {string} cwd
+ * @returns {object[]}
+ */
+function readGainLog(cwd) {
+  try {
+    const logPath = path.join(cwd, GAIN_FILE);
+    if (!fs.existsSync(logPath)) return [];
+    return fs.readFileSync(logPath, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => { try { return JSON.parse(line); } catch (_) { return null; } })
+      .filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
 /**
  * Compute summary statistics from an array of log records.
  * @param {object[]} entries
@@ -112,4 +134,64 @@ function summarize(entries) {
   };
 }
 
-module.exports = { logRun, readLog, summarize };
+/**
+ * Whether `gain` savings capture is enabled. Default: ON (privacy-safe,
+ * local-only, counts only — no paths, source, or query text). This is
+ * intentionally decoupled from the legacy `config.tracking` flag (which gates
+ * the usage.ndjson health log and defaults OFF). Opt out of gain capture via:
+ *   config.gainTracking === false   ·   --no-track   ·   SIGMAP_NO_TRACK=1
+ * @param {object} [config]
+ * @param {string[]} [argv]
+ * @returns {boolean}
+ */
+function isTrackingEnabled(config, argv) {
+  const a = argv || (typeof process !== 'undefined' ? process.argv : []);
+  if (process.env && process.env.SIGMAP_NO_TRACK) return false;
+  if (a && a.includes('--no-track')) return false;
+  if (config && config.gainTracking === false) return false;
+  return true;
+}
+
+/**
+ * Append one operation to the usage log using the extended `gain` schema.
+ * Reuses the same NDJSON file as logRun and is tolerant of partial input.
+ * Never throws — tracking must never break the main process.
+ *
+ * @param {object} entry
+ * @param {string} entry.op             e.g. 'ask' | 'generate' | 'query' | 'mcp:get_map'
+ * @param {number} entry.baselineTokens whole-file / candidate baseline (counterfactual)
+ * @param {number} entry.actualTokens   tokens SigMap actually emitted
+ * @param {number} [entry.durationMs]
+ * @param {string} [entry.model]
+ * @param {string} [entry.version]
+ * @param {string} cwd
+ */
+function recordUsage(entry, cwd) {
+  try {
+    const logPath = path.join(cwd, GAIN_FILE);
+    const dir = path.dirname(logPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    const baseline = Math.max(0, Number(entry.baselineTokens) || 0);
+    const actual = Math.max(0, Number(entry.actualTokens) || 0);
+    const saved = Math.max(0, baseline - actual);
+    const record = {
+      ts: new Date().toISOString(),
+      v: entry.version || '0.9.0',
+      op: entry.op || 'generate',
+      baselineTokens: baseline,
+      actualTokens: actual,
+      savedTokens: saved,
+      savedPct: baseline > 0 ? parseFloat(((saved / baseline) * 100).toFixed(1)) : 0,
+      durationMs: Math.max(0, Math.round(Number(entry.durationMs) || 0)),
+      model: entry.model || null,
+      ok: entry.ok !== false,
+    };
+    fs.appendFileSync(logPath, JSON.stringify(record) + '\n', 'utf8');
+  } catch (err) {
+    // Never crash the main process — tracking is optional.
+    if (process.stderr) process.stderr.write(`[sigmap] tracking: could not write log: ${err.message}\n`);
+  }
+}
+
+module.exports = { logRun, recordUsage, readLog, readGainLog, summarize, isTrackingEnabled, GAIN_FILE };

package/src/tracking/pricing.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * SigMap pricing table — input-token $/Mtok assumptions for the `gain` dashboard.
+ *
+ * These are ASSUMPTIONS used only to translate "tokens saved" into an estimated
+ * dollar figure. They are deliberately conservative and configurable via
+ *   --model <name>   or   config.pricingModel
+ * The `gain` views always print the model + rate inline so the $ is never
+ * presented as exact. Zero npm dependencies.
+ */
+
+// USD per 1,000,000 input tokens.
+const PRICES = {
+  'claude-sonnet': 3.0,
+  'claude-opus': 15.0,
+  'claude-haiku': 0.8,
+  'gpt-4o': 2.5,
+  'gpt-4o-mini': 0.15,
+  'gemini-1.5-pro': 1.25,
+  'gemini-1.5-flash': 0.075,
+};
+
+const DEFAULT_MODEL = 'claude-sonnet';
+
+/**
+ * Resolve a price (USD per token) for a model name.
+ * @param {string} [model]
+ * @returns {{ model: string, perMtok: number, perToken: number }}
+ */
+function resolvePrice(model) {
+  const key = (model || DEFAULT_MODEL).toLowerCase();
+  const perMtok = PRICES[key] != null ? PRICES[key] : PRICES[DEFAULT_MODEL];
+  const resolved = PRICES[key] != null ? key : DEFAULT_MODEL;
+  return { model: resolved, perMtok, perToken: perMtok / 1_000_000 };
+}
+
+/** @returns {string[]} known model keys */
+function listModels() {
+  return Object.keys(PRICES);
+}
+
+module.exports = { PRICES, DEFAULT_MODEL, resolvePrice, listModels };

package/src/util/git.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Shell-free git invocation.
+ *
+ * Uses `execFileSync('git', [...])`, which executes the git binary directly —
+ * it never spawns a system shell (`/bin/sh -c`). That means:
+ *   - no shell-injection surface (arguments are passed as an array, never
+ *     interpolated into a command string), and
+ *   - supply-chain scanners (e.g. Socket) do not flag a "Shell access" capability.
+ *
+ * stderr is discarded by default (replaces the old `2>/dev/null` redirects).
+ */
+
+const { execFileSync } = require('child_process');
+
+function git(args, opts = {}) {
+  return execFileSync('git', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    ...opts,
+  });
+}
+
+// Convenience: run git and return trimmed stdout, or '' on any failure.
+function tryGit(args, opts = {}) {
+  try { return git(args, opts).toString().trim(); }
+  catch (_) { return ''; }
+}
+
+module.exports = { git, tryGit };