dsh-plugin-show-me-data 0.1.0

package/lib/core/insight/rules.js

@@ -0,0 +1,417 @@
+/**
+ * The eight "worth paying attention to" rules (docs/01 §4, docs/07 T5.1).
+ *
+ * Every rule is a pure function over already-computed metrics: no IO, no clock,
+ * no catalog mutation. A rule returns 'Hit[]', each carrying structured
+ * 'evidence' so the UI and the AI layer can quote *why* something was flagged
+ * instead of restating the number.
+ *
+ * Thresholds live in {@link RULE_CONFIG} at the top of the file so tuning them is
+ * a reviewable data change, and 'test/core/insight-rules.test.js' pins each rule
+ * with a hit, a near-miss and an insufficient-data case.
+ *
+ * @module core/insight/rules
+ */
+import { daysBetween } from '../time/range.js'
+
+/** Days within which a release still counts as "fresh", per frequency. */
+export const FRESH_WINDOW_DAYS = { daily: 3, weekly: 10, monthly: 10, quarterly: 45, annual: 400 }
+
+/** Days after which an expected update is considered overdue, per frequency. */
+export const STALE_WINDOW_DAYS = { daily: 5, weekly: 21, monthly: 40, quarterly: 100, annual: 400 }
+
+/** All tunable thresholds and their weights, in one reviewable place. */
+export const RULE_CONFIG = {
+  'fresh-release': { weight: 1.0, score: 30 },
+  'surprise-sigma': { weight: 1.6, score: 55, minZ: 1.5, minSamples: 6 },
+  extreme: { weight: 1.4, score: 45, percentileHigh: 0.95, percentileLow: 0.05, lookbackDays: 1095, minSamples: 12 },
+  'trend-break': { weight: 1.3, score: 40, minRelativeSlope: 0.002 },
+  'threshold-cross': { weight: 1.5, score: 50 },
+  'spread-signal': { weight: 1.5, score: 50, fastConvergenceSigma: 2 },
+  divergence: { weight: 1.2, score: 35, flatTolerance: 0.1 },
+  'stale-gap': { weight: 1.1, score: 25 },
+}
+
+/** Policy-rate and level thresholds that trigger 'threshold-cross'. */
+export const THRESHOLDS = [
+  { indicatorId: 'us.cpi.yoy', value: 3, direction: 'above', label: { zh: 'CPI 同比上穿 3%', en: 'CPI YoY crosses above 3%' } },
+  { indicatorId: 'us.core.cpi.yoy', value: 3, direction: 'above', label: { zh: '核心 CPI 同比上穿 3%', en: 'Core CPI YoY crosses above 3%' } },
+  { indicatorId: 'us.unrate', value: 4.5, direction: 'above', label: { zh: '失业率上穿 4.5%', en: 'Unemployment crosses above 4.5%' } },
+  { indicatorId: 'us.fedfunds.daily', value: 5, direction: 'any', label: { zh: '政策利率跨越 5%', en: 'Policy rate crosses 5%' } },
+  { indicatorId: 'us.fedfunds.daily', value: 4, direction: 'any', label: { zh: '政策利率跨越 4%', en: 'Policy rate crosses 4%' } },
+  { indicatorId: 'us.fedfunds.daily', value: 3, direction: 'any', label: { zh: '政策利率跨越 3%', en: 'Policy rate crosses 3%' } },
+  { indicatorId: 'us.fedfunds.daily', value: 2, direction: 'any', label: { zh: '政策利率跨越 2%', en: 'Policy rate crosses 2%' } },
+  { indicatorId: 'cn.pmi.mfg', value: 50, direction: 'any', label: { zh: '制造业 PMI 跨越荣枯线 50', en: 'Manufacturing PMI crosses 50' } },
+]
+
+/** Indicator pairs whose contradiction is itself informative. */
+export const DIVERGENCE_PAIRS = [
+  {
+    left: 'us.payrolls.change',
+    right: 'us.unrate',
+    // Payroll growth rising while unemployment does not move is the classic
+    // "two labour reports disagree" signal.
+    expect: 'same-direction',
+    label: { zh: '非农与失业率背离', en: 'Payrolls and unemployment diverge' },
+    note: { zh: '就业增长与失业率未同向变动，两个劳动力调查口径出现分歧。' },
+  },
+]
+
+/**
+ * @typedef {Object} RuleContext
+ * @property {string} today - reference date ('Clock.today()').
+ * @property {Record<string, { points: Array<{ t: string, v: number }>, stats?: object }>} seriesById - resolved series,
+ *   including derived ones (spreads/ratios) computed by the caller.
+ * @property {Record<string, object>} catalogById - indicator definitions.
+ */
+
+/**
+ * Build one hit.
+ *
+ * @param {string} ruleId - rule id.
+ * @param {string} indicatorId - indicator being flagged.
+ * @param {{ zh: string, en?: string }} reason - human reason.
+ * @param {object} evidence - structured evidence.
+ * @returns {object} hit.
+ */
+function hit(ruleId, indicatorId, reason, evidence) {
+  return {
+    ruleId,
+    indicatorId,
+    score: RULE_CONFIG[ruleId].score,
+    reason,
+    evidence,
+  }
+}
+
+/**
+ * Latest observation and its previous one.
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @returns {{ latest: object, prev: object|undefined }} last two points.
+ */
+function lastTwo(points) {
+  return { latest: points[points.length - 1], prev: points[points.length - 2] }
+}
+
+/**
+ * Rule 1 — a release landed inside the freshness window for its frequency.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {object[]} hits.
+ */
+export function freshRelease({ seriesById, catalogById, today }) {
+  const hits = []
+  for (const [id, series] of Object.entries(seriesById)) {
+    const def = catalogById[id]
+    if (def === undefined || !series.points?.length) continue
+    const window = FRESH_WINDOW_DAYS[def.freq]
+    if (window === undefined) continue
+    const age = daysBetween(series.points[series.points.length - 1].t, today)
+    if (age > window || age < 0) continue
+    hits.push(
+      hit('fresh-release', id, { zh: `新发布：${def.label.zh}（观测日 ${series.points[series.points.length - 1].t}）` }, {
+        latestAt: series.points[series.points.length - 1].t,
+        ageDays: age,
+        windowDays: window,
+        freq: def.freq,
+        value: series.points[series.points.length - 1].v,
+      }),
+    )
+  }
+  return hits
+}
+
+/**
+ * Rule 2 — the latest change is a statistical surprise.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {object[]} hits.
+ */
+export function surpriseSigma({ seriesById, catalogById }) {
+  const { minZ, minSamples } = RULE_CONFIG['surprise-sigma']
+  const hits = []
+  for (const [id, series] of Object.entries(seriesById)) {
+    const def = catalogById[id]
+    if (def === undefined || !series.points?.length) continue
+    const stats = series.stats ?? {}
+    const z = stats.zScoreLatestChange
+    if (typeof z !== 'number' || !Number.isFinite(z)) continue // insufficient sample → no fabricated σ
+    if (series.points.length < minSamples) continue
+    if (Math.abs(z) < minZ) continue
+    hits.push(
+      hit('surprise-sigma', id, { zh: `${def.label.zh} 本期变化为 ${z.toFixed(1)}σ，超出常态区间` }, {
+        z,
+        threshold: minZ,
+        latest: stats.latest,
+        changeAbs: stats.changeAbs,
+        samples: series.points.length,
+      }),
+    )
+  }
+  return hits
+}
+
+/**
+ * Rule 3 — a multi-year high/low or an extreme percentile.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {object[]} hits.
+ */
+export function extreme({ seriesById, catalogById, today }) {
+  const { percentileHigh, percentileLow, lookbackDays, minSamples } = RULE_CONFIG.extreme
+  const hits = []
+  for (const [id, series] of Object.entries(seriesById)) {
+    const def = catalogById[id]
+    if (def === undefined || !series.points || series.points.length < minSamples) continue
+    const points = series.points.filter((p) => daysBetween(p.t, today) <= lookbackDays)
+    if (points.length < minSamples) continue
+    const values = points.map((p) => p.v)
+    const latest = points[points.length - 1]
+    const isHigh = latest.v >= Math.max(...values)
+    const isLow = latest.v <= Math.min(...values)
+    const percentile = series.stats?.percentile
+    const extremePercentile = typeof percentile === 'number' && (percentile >= percentileHigh || percentile <= percentileLow)
+    if (!isHigh && !isLow && !extremePercentile) continue
+    hits.push(
+      hit('extreme', id, {
+        zh: `${def.label.zh} 处于近 3 年${isHigh ? '新高' : isLow ? '新低' : '极值分位'}（分位 ${typeof percentile === 'number' ? percentile.toFixed(2) : 'n/a'}）`,
+      }, {
+        latest: latest.v,
+        min: Math.min(...values),
+        max: Math.max(...values),
+        percentile: percentile ?? null,
+        window: `${points[0].t}..${latest.t}`,
+        dates: [latest.t],
+      }),
+    )
+  }
+  return hits
+}
+
+/**
+ * Rule 4 — the trend's slope changed sign by a meaningful amount.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {object[]} hits.
+ */
+export function trendBreak({ seriesById, catalogById }) {
+  const { minRelativeSlope } = RULE_CONFIG['trend-break']
+  const hits = []
+  for (const [id, series] of Object.entries(seriesById)) {
+    const def = catalogById[id]
+    if (def === undefined || !series.points || series.points.length < 8) continue
+    const points = series.points
+    const half = Math.floor(points.length / 2)
+    const slopeOf = (slice) => {
+      const n = slice.length
+      if (n < 3) return undefined
+      const meanX = (n - 1) / 2
+      const meanY = slice.reduce((acc, p) => acc + p.v, 0) / n
+      let num = 0
+      let den = 0
+      for (let i = 0; i < n; i += 1) {
+        num += (i - meanX) * (slice[i].v - meanY)
+        den += (i - meanX) ** 2
+      }
+      return den === 0 ? undefined : num / den
+    }
+    const early = slopeOf(points.slice(0, half))
+    const late = slopeOf(points.slice(half))
+    if (early === undefined || late === undefined) continue
+    if (Math.sign(early) === Math.sign(late) || early === 0 || late === 0) continue
+    const mean = points.reduce((acc, p) => acc + p.v, 0) / points.length
+    if (mean === 0) continue
+    const relative = Math.abs(late - early) / Math.abs(mean)
+    if (relative <= minRelativeSlope) continue
+    hits.push(
+      hit('trend-break', id, {
+        zh: `${def.label.zh} 斜率由${early > 0 ? '上行' : '下行'}转为${late > 0 ? '上行' : '下行'}，趋势出现拐点`,
+      }, {
+        earlySlope: early,
+        lateSlope: late,
+        relativeChange: relative,
+        threshold: minRelativeSlope,
+      }),
+    )
+  }
+  return hits
+}
+
+/**
+ * Rule 5 — a configured level was crossed between the last two observations.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {object[]} hits.
+ */
+export function thresholdCross({ seriesById, catalogById }) {
+  const hits = []
+  for (const threshold of THRESHOLDS) {
+    const series = seriesById[threshold.indicatorId]
+    const def = catalogById[threshold.indicatorId]
+    if (series === undefined || def === undefined || !series.points || series.points.length < 2) continue
+    const { latest, prev } = lastTwo(series.points)
+    const crossed =
+      threshold.direction === 'above'
+        ? prev.v <= threshold.value && latest.v > threshold.value
+        : (prev.v - threshold.value) * (latest.v - threshold.value) < 0
+    if (!crossed) continue
+    hits.push(
+      hit('threshold-cross', threshold.indicatorId, { zh: `${threshold.label.zh}（${prev.v} → ${latest.v}）` }, {
+        value: latest.v,
+        previous: prev.v,
+        threshold: threshold.value,
+        direction: threshold.direction,
+        dates: [prev.t, latest.t],
+      }),
+    )
+  }
+  return hits
+}
+
+/**
+ * Rule 6 — a spread flipped sign (an inversion resolving) or converged fast.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {object[]} hits.
+ */
+export function spreadSignal({ seriesById, catalogById }) {
+  const { fastConvergenceSigma } = RULE_CONFIG['spread-signal']
+  const hits = []
+  for (const [id, series] of Object.entries(seriesById)) {
+    const def = catalogById[id]
+    if (def === undefined || !series.points || series.points.length < 2) continue
+    const isSpread = def.unit === 'pp' || def.derive?.op === 'spread' || id.includes('spread')
+    if (!isSpread) continue
+    const { latest, prev } = lastTwo(series.points)
+    if (prev.v < 0 && latest.v >= 0) {
+      hits.push(
+        hit('spread-signal', id, { zh: `${def.label.zh} 由负转正，倒挂解除（${prev.v} → ${latest.v}）` }, {
+          value: latest.v,
+          previous: prev.v,
+          dates: [prev.t, latest.t],
+          kind: 'inversion-cleared',
+        }),
+      )
+      continue
+    }
+    const stats = series.stats ?? {}
+    const sigma = stats.stdDev
+    if (typeof sigma === 'number' && sigma > 0 && Math.abs(latest.v - prev.v) > fastConvergenceSigma * sigma) {
+      hits.push(
+        hit('spread-signal', id, { zh: `${def.label.zh} 快速收敛：单期变化超过 ${fastConvergenceSigma}σ` }, {
+          value: latest.v,
+          previous: prev.v,
+          changeAbs: latest.v - prev.v,
+          sigma,
+          dates: [prev.t, latest.t],
+          kind: 'fast-convergence',
+        }),
+      )
+    }
+  }
+  return hits
+}
+
+/**
+ * Rule 7 — two configured indicators contradict each other.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {object[]} hits.
+ */
+export function divergence({ seriesById, catalogById }) {
+  const { flatTolerance } = RULE_CONFIG.divergence
+  const hits = []
+  for (const pair of DIVERGENCE_PAIRS) {
+    const left = seriesById[pair.left]
+    const right = seriesById[pair.right]
+    const leftDef = catalogById[pair.left]
+    const rightDef = catalogById[pair.right]
+    if (!left?.points?.length || !right?.points?.length || !leftDef || !rightDef) continue
+    const leftStats = left.stats ?? {}
+    const rightStats = right.stats ?? {}
+    if (leftStats.changeAbs === undefined || rightStats.changeAbs === undefined) continue
+    const leftTolerance = flatTolerance * (leftDef.unit === '万人' ? 10 : 1)
+    const leftMoving = Math.abs(leftStats.changeAbs) > leftTolerance
+    const rightFlat = Math.abs(rightStats.changeAbs) <= flatTolerance
+    const contradicts =
+      pair.expect === 'same-direction' ? leftMoving && rightFlat : leftMoving === rightFlat
+    if (!contradicts) continue
+    hits.push(
+      hit('divergence', pair.left, { zh: pair.label.zh, en: pair.label.en }, {
+        pair: [pair.left, pair.right],
+        leftChange: leftStats.changeAbs,
+        rightChange: rightStats.changeAbs,
+        tolerance: flatTolerance,
+        note: pair.note.zh,
+        dates: [leftStats.latestAt, rightStats.latestAt],
+      }),
+    )
+  }
+  return hits
+}
+
+/**
+ * Rule 8 — an indicator that should have updated has not.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {object[]} hits.
+ */
+export function staleGap({ seriesById, catalogById, today }) {
+  const hits = []
+  for (const [id, series] of Object.entries(seriesById)) {
+    const def = catalogById[id]
+    if (def === undefined || !series.points?.length) continue
+    const window = STALE_WINDOW_DAYS[def.freq]
+    if (window === undefined) continue
+    const latestAt = series.points[series.points.length - 1].t
+    const age = daysBetween(latestAt, today)
+    if (age <= window) continue
+    hits.push(
+      hit('stale-gap', id, { zh: `${def.label.zh} 应更新而未更新（最后观测 ${latestAt}，已 ${age} 天）` }, {
+        latestAt,
+        ageDays: age,
+        windowDays: window,
+        freq: def.freq,
+        expectedEvery: def.freq,
+      }),
+    )
+  }
+  return hits
+}
+
+/** Every rule, in evaluation order. */
+export const RULES = [
+  { id: 'fresh-release', weight: RULE_CONFIG['fresh-release'].weight, run: freshRelease },
+  { id: 'surprise-sigma', weight: RULE_CONFIG['surprise-sigma'].weight, run: surpriseSigma },
+  { id: 'extreme', weight: RULE_CONFIG.extreme.weight, run: extreme },
+  { id: 'trend-break', weight: RULE_CONFIG['trend-break'].weight, run: trendBreak },
+  { id: 'threshold-cross', weight: RULE_CONFIG['threshold-cross'].weight, run: thresholdCross },
+  { id: 'spread-signal', weight: RULE_CONFIG['spread-signal'].weight, run: spreadSignal },
+  { id: 'divergence', weight: RULE_CONFIG.divergence.weight, run: divergence },
+  { id: 'stale-gap', weight: RULE_CONFIG['stale-gap'].weight, run: staleGap },
+]
+
+/**
+ * Run every rule.
+ *
+ * A rule that throws is contained (and reported) rather than taking the panel
+ * down with it: a data panel must never render nothing because one heuristic
+ * met an unexpected shape.
+ *
+ * @param {RuleContext} context - rule context.
+ * @returns {{ hits: object[], errors: Array<{ ruleId: string, message: string }> }} hits and contained failures.
+ */
+export function runRules(context) {
+  const hits = []
+  const errors = []
+  for (const rule of RULES) {
+    try {
+      const produced = rule.run(context) ?? []
+      for (const entry of produced) hits.push({ ...entry, weight: rule.weight })
+    } catch (error) {
+      errors.push({ ruleId: rule.id, message: error?.message ?? String(error) })
+    }
+  }
+  return { hits, errors }
+}

package/lib/core/stats/derive.js

@@ -0,0 +1,123 @@
+/**
+ * Derived series — spreads, ratios and averages built from catalog indicators
+ * (docs/03 §3.5). All operations join on the **date**, never on position:
+ * two series with different publication calendars must not be paired by index.
+ *
+ * @module core/stats/derive
+ */
+import { sortDedupe } from './series.js'
+
+/** Minimum number of overlapping observations before a derived series is usable. */
+export const MIN_OVERLAP = 3
+
+/**
+ * @typedef {Object} DeriveResult
+ * @property {Array<{ t: string, v: number }>} points - derived points.
+ * @property {number} overlap - number of joined observations.
+ * @property {string} [reason] - why the result is empty, when it is.
+ */
+
+/**
+ * Join two series on their exact dates.
+ *
+ * @param {Array<{ t: string, v: number }>} a - left series.
+ * @param {Array<{ t: string, v: number }>} b - right series.
+ * @returns {Array<{ t: string, a: number, b: number }>} joined rows, ascending.
+ */
+export function innerJoin(a, b) {
+  const left = new Map(sortDedupe(a).map((p) => [p.t, p.v]))
+  const right = new Map(sortDedupe(b).map((p) => [p.t, p.v]))
+  const dates = [...left.keys()].filter((t) => right.has(t)).sort()
+  return dates.map((t) => ({ t, a: left.get(t), b: right.get(t) }))
+}
+
+/**
+ * Pointwise transformation over an exact-date join.
+ *
+ * @param {Array<{ t: string, v: number }>} a - left series.
+ * @param {Array<{ t: string, v: number }>} b - right series.
+ * @param {(a: number, b: number) => number|undefined} combine - pointwise op; 'undefined' drops the row.
+ * @returns {DeriveResult} derived points with the overlap count.
+ */
+function pointwise(a, b, combine) {
+  const rows = innerJoin(a, b)
+  const points = []
+  for (const row of rows) {
+    const value = combine(row.a, row.b)
+    if (typeof value === 'number' && Number.isFinite(value)) points.push({ t: row.t, v: value })
+  }
+  if (rows.length < MIN_OVERLAP) {
+    return { points: [], overlap: rows.length, reason: 'insufficient-overlap' }
+  }
+  return { points, overlap: rows.length }
+}
+
+/**
+ * 'a − b' on shared dates — the spread of two rates or the real rate from a
+ * nominal rate and an inflation expectation.
+ *
+ * @param {Array<{ t: string, v: number }>} a - minuend series.
+ * @param {Array<{ t: string, v: number }>} b - subtrahend series.
+ * @returns {DeriveResult} spread series.
+ */
+export function spread(a, b) {
+  return pointwise(a, b, (x, y) => x - y)
+}
+
+/**
+ * 'a / b' on shared dates. Rows whose denominator is zero are skipped rather
+ * than producing 'Infinity'.
+ *
+ * @param {Array<{ t: string, v: number }>} a - numerator series.
+ * @param {Array<{ t: string, v: number }>} b - denominator series.
+ * @returns {DeriveResult} ratio series.
+ */
+export function ratio(a, b) {
+  return pointwise(a, b, (x, y) => (y === 0 ? undefined : x / y))
+}
+
+/**
+ * Mean of two or more series on dates every operand shares.
+ *
+ * @param {Array<Array<{ t: string, v: number }>>} series - operand series.
+ * @returns {DeriveResult} averaged series.
+ */
+export function avgOf(series) {
+  if (!Array.isArray(series) || series.length === 0) {
+    return { points: [], overlap: 0, reason: 'insufficient-overlap' }
+  }
+  const maps = series.map((s) => new Map(sortDedupe(s).map((p) => [p.t, p.v])))
+  const dates = [...maps[0].keys()]
+    .filter((t) => maps.every((m) => m.has(t)))
+    .sort()
+  // Rule (docs/07 T1.3): a derived series is *empty* when the overlap is below
+  // the floor. That makes "the spread exists" a guarantee the UI and the AI
+  // layer can rely on, instead of a two-point spread masquerading as history.
+  if (dates.length < MIN_OVERLAP) {
+    return { points: [], overlap: dates.length, reason: 'insufficient-overlap' }
+  }
+  return {
+    points: dates.map((t) => ({
+      t,
+      v: maps.reduce((acc, m) => acc + m.get(t), 0) / maps.length,
+    })),
+    overlap: dates.length,
+  }
+}
+
+/**
+ * Apply a catalog 'derive' directive (docs/03 §3.5).
+ *
+ * @param {{ op: 'spread'|'ratio'|'avg', operands: string[] }} directive - catalog directive.
+ * @param {Record<string, Array<{ t: string, v: number }>>} seriesById - resolved operand series.
+ * @returns {DeriveResult & { missing?: string[] }} derived series, plus operands that were unavailable.
+ */
+export function applyDerive(directive, seriesById) {
+  const missing = directive.operands.filter((id) => !Array.isArray(seriesById[id]))
+  if (missing.length > 0) return { points: [], overlap: 0, reason: 'insufficient-overlap', missing }
+  const operands = directive.operands.map((id) => seriesById[id])
+  if (directive.op === 'spread') return spread(operands[0], operands[1])
+  if (directive.op === 'ratio') return ratio(operands[0], operands[1])
+  if (directive.op === 'avg') return avgOf(operands)
+  throw new RangeError(`unknown derive op: ${JSON.stringify(directive.op)}`)
+}