dsh-plugin-show-me-data 0.1.0

package/lib/core/types.js

@@ -0,0 +1,478 @@
+/**
+ * Core contract validators — pure functions, zero IO, zero DSH imports.
+ *
+ * Every validator returns '{ ok, errors }' where 'errors' is a list of
+ * human-readable strings (never thrown). The CI gate runs these over the seed
+ * catalog and over every adapter fixture output (docs/08 §8).
+ *
+ * @module core/types
+ */
+
+/** Allowed indicator groups (docs/03 §1.2). */
+export const GROUPS = ['US', 'CN', 'GLOBAL', 'CUSTOM']
+
+/** Allowed frequencies, slowest last. */
+export const FREQUENCIES = ['daily', 'weekly', 'monthly', 'quarterly', 'annual']
+
+/** Allowed seasonal adjustments. */
+export const SEASONALS = ['SA', 'NSA', 'NA']
+
+/** Allowed display transforms. */
+export const TRANSFORMS = [
+  'raw',
+  'diff',
+  'pctChange',
+  'yoy',
+  'mom',
+  'annualize',
+  'ratio',
+]
+
+/** Allowed polarities: which direction of change is "good". */
+export const POLARITIES = ['up-is-good', 'down-is-good', 'neutral']
+
+/** Allowed metric/series statuses (docs/03 §1.7). */
+export const STATUSES = ['fresh', 'stale', 'error', 'missing']
+
+/** Allowed derivation ops for derived indicators (docs/03 §3.5). */
+export const DERIVE_OPS = ['spread', 'ratio', 'avg']
+
+/** Allowed source-error kinds (docs/03 §1.7). */
+export const ERROR_KINDS = ['network', 'http', 'parse', 'empty', 'unsupported']
+
+/** 'YYYY-MM-DD' calendar date, no time component. */
+export const DATE_RE = /^\d{4}-\d{2}-\d{2}$/
+
+/** Dotted lowercase id, at least two segments, no empty segment. */
+const ID_RE = /^[a-z0-9]+(\.[a-z0-9]+)+$/
+
+/**
+ * Validate a calendar date string: 'YYYY-MM-DD' and a real calendar day
+ * (rejects '2026-02-31').
+ *
+ * @param {unknown} value - candidate date.
+ * @returns {boolean} whether the value is a real 'YYYY-MM-DD' date.
+ */
+export function isDateString(value) {
+  if (typeof value !== 'string' || !DATE_RE.test(value)) return false
+  const [y, m, d] = value.split('-').map(Number)
+  if (m < 1 || m > 12 || d < 1) return false
+  // Reject impossible days (2026-02-31) without reading a clock: a constant
+  // epoch plus setUTCFullYear normalizes overflow, so a round-trip mismatch
+  // means the input was not a real calendar date.
+  const at = new Date(0)
+  at.setUTCFullYear(y, m - 1, d)
+  return at.getUTCFullYear() === y && at.getUTCMonth() === m - 1 && at.getUTCDate() === d
+}
+
+/**
+ * Whether a value is a finite number (rejects NaN, Infinity, numeric strings).
+ *
+ * @param {unknown} value - candidate.
+ * @returns {boolean} true for finite 'number'.
+ */
+export function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/**
+ * @typedef {{ ok: boolean, errors: string[] }} ValidationResult
+ */
+
+/**
+ * Build a validation result from an error list.
+ *
+ * @param {string[]} errors - collected error messages.
+ * @returns {ValidationResult} result object.
+ */
+function result(errors) {
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * Validate an 'IndicatorDef' (docs/03 §1.2).
+ *
+ * @param {unknown} value - candidate indicator definition.
+ * @returns {ValidationResult} validation result.
+ */
+export function validateIndicatorDef(value) {
+  const errors = []
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return result(['indicator: expected an object'])
+  }
+  const def = /** @type {Record<string, any>} */ (value)
+
+  if (typeof def.id !== 'string' || !ID_RE.test(def.id)) {
+    errors.push(`id: expected dotted lowercase id (got ${JSON.stringify(def.id)})`)
+  }
+  if (!GROUPS.includes(def.group)) {
+    errors.push(`group: expected one of ${GROUPS.join('|')} (got ${JSON.stringify(def.group)})`)
+  }
+  if (def.label === null || typeof def.label !== 'object') {
+    errors.push('label: expected { zh, en }')
+  } else {
+    if (typeof def.label.zh !== 'string' || def.label.zh.trim() === '') {
+      errors.push('label.zh: expected a non-empty string')
+    }
+    if (typeof def.label.en !== 'string' || def.label.en.trim() === '') {
+      errors.push('label.en: expected a non-empty string')
+    }
+  }
+  if (typeof def.unit !== 'string' || def.unit === '') {
+    errors.push('unit: expected a non-empty string')
+  }
+  if (!FREQUENCIES.includes(def.freq)) {
+    errors.push(`freq: expected one of ${FREQUENCIES.join('|')}`)
+  }
+  if (!SEASONALS.includes(def.seasonal)) {
+    errors.push(`seasonal: expected one of ${SEASONALS.join('|')}`)
+  }
+  if (!Number.isInteger(def.importance) || def.importance < 1 || def.importance > 5) {
+    errors.push('importance: expected an integer in [1,5]')
+  }
+
+  const derived = def.derive !== undefined && def.derive !== null
+  if (derived) {
+    if (def.derive === null || typeof def.derive !== 'object') {
+      errors.push('derive: expected { op, operands }')
+    } else {
+      if (!DERIVE_OPS.includes(def.derive.op)) {
+        errors.push(`derive.op: expected one of ${DERIVE_OPS.join('|')}`)
+      }
+      if (!Array.isArray(def.derive.operands) || def.derive.operands.length < 2) {
+        errors.push('derive.operands: expected an array of at least 2 indicator ids')
+      } else if (def.derive.operands.some((id) => typeof id !== 'string')) {
+        errors.push('derive.operands: every operand must be a string')
+      }
+    }
+  } else {
+    const source = def.source
+    if (source === null || typeof source !== 'object') {
+      errors.push('source: expected { adapter, seriesRef }')
+    } else {
+      if (typeof source.adapter !== 'string' || source.adapter === '') {
+        errors.push('source.adapter: expected a non-empty string')
+      }
+      if (typeof source.seriesRef !== 'string' || source.seriesRef === '') {
+        errors.push('source.seriesRef: expected a non-empty string')
+      }
+    }
+  }
+
+  const display = def.display
+  if (display === null || typeof display !== 'object') {
+    errors.push('display: expected an object')
+  } else {
+    if (!TRANSFORMS.includes(display.transform)) {
+      errors.push(`display.transform: expected one of ${TRANSFORMS.join('|')}`)
+    }
+    if (display.window !== undefined && (!Number.isInteger(display.window) || display.window < 1)) {
+      errors.push('display.window: expected a positive integer')
+    }
+    if (display.movingAvg !== undefined && (!Number.isInteger(display.movingAvg) || display.movingAvg < 2)) {
+      errors.push('display.movingAvg: expected an integer >= 2')
+    }
+    if (display.decimals !== undefined && (!Number.isInteger(display.decimals) || display.decimals < 0 || display.decimals > 8)) {
+      errors.push('display.decimals: expected an integer in [0,8]')
+    }
+    if (display.polarity !== undefined && !POLARITIES.includes(display.polarity)) {
+      errors.push(`display.polarity: expected one of ${POLARITIES.join('|')}`)
+    }
+  }
+  if (def.notes !== undefined && def.notes !== null) {
+    if (typeof def.notes !== 'object' || typeof def.notes.zh !== 'string') {
+      errors.push('notes: expected { zh, en? }')
+    }
+  }
+  if (def.tags !== undefined && (!Array.isArray(def.tags) || def.tags.some((t) => typeof t !== 'string'))) {
+    errors.push('tags: expected an array of strings')
+  }
+  return result(errors)
+}
+
+/**
+ * Validate a 'RawSeries' (docs/03 §1.3): ascending 't', finite 'v', real
+ * 'YYYY-MM-DD' dates, non-empty 'sourceRef.url'.
+ *
+ * @param {unknown} value - candidate raw series.
+ * @returns {ValidationResult} validation result.
+ */
+export function validateRawSeries(value) {
+  const errors = []
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return result(['rawSeries: expected an object'])
+  }
+  const series = /** @type {Record<string, any>} */ (value)
+
+  if (typeof series.adapterId !== 'string' || series.adapterId === '') {
+    errors.push('adapterId: expected a non-empty string')
+  }
+  if (typeof series.seriesRef !== 'string' || series.seriesRef === '') {
+    errors.push('seriesRef: expected a non-empty string')
+  }
+  if (!Array.isArray(series.points)) {
+    errors.push('points: expected an array')
+  } else {
+    let prev = null
+    for (let i = 0; i < series.points.length; i += 1) {
+      const point = series.points[i]
+      if (point === null || typeof point !== 'object') {
+        errors.push(`points[${i}]: expected { t, v }`)
+        continue
+      }
+      if (!isDateString(point.t)) {
+        errors.push(`points[${i}].t: expected a real YYYY-MM-DD date (got ${JSON.stringify(point.t)})`)
+      } else if (prev !== null && point.t < prev) {
+        errors.push(`points[${i}].t: points must be ascending (${point.t} after ${prev})`)
+      }
+      if (isDateString(point.t)) prev = point.t
+      // Optional OHLC bar: all three or none, and the high/low must actually
+      // bound the open/close, so a malformed bar is reported here instead of
+      // rendering as an impossible candle.
+      const bar = ['o', 'h', 'l'].filter((key) => point[key] !== undefined)
+      if (bar.length !== 0 && bar.length !== 3) {
+        errors.push(`points[${i}]: an OHLC bar needs all of o/h/l (got ${bar.join(', ') || 'none'})`)
+      } else if (bar.length === 3) {
+        for (const key of bar) {
+          if (!isFiniteNumber(point[key])) errors.push(`points[${i}].${key}: expected a finite number`)
+        }
+        if (isFiniteNumber(point.h) && isFiniteNumber(point.l)) {
+          const bound = [point.h, point.l, point.o, point.v].filter((entry) => isFiniteNumber(entry))
+          if (bar.every((key) => isFiniteNumber(point[key])) && (point.h < Math.max(...bound) || point.l > Math.min(...bound))) {
+            errors.push(`points[${i}]: high/low must bound open and close`)
+          }
+        }
+      }
+      if (!isFiniteNumber(point.v)) {
+        errors.push(`points[${i}].v: expected a finite number (got ${JSON.stringify(point.v)})`)
+      }
+    }
+  }
+  if (series.meta === null || typeof series.meta !== 'object') {
+    errors.push('meta: expected an object with a name')
+  } else if (typeof series.meta.name !== 'string' || series.meta.name === '') {
+    errors.push('meta.name: expected a non-empty string')
+  }
+  if (typeof series.fetchedAt !== 'string' || series.fetchedAt === '') {
+    errors.push('fetchedAt: expected an ISO timestamp string')
+  }
+  const ref = series.sourceRef
+  if (ref === null || typeof ref !== 'object') {
+    errors.push('sourceRef: expected an object')
+  } else {
+    if (typeof ref.adapterId !== 'string' || ref.adapterId === '') {
+      errors.push('sourceRef.adapterId: expected a non-empty string')
+    }
+    if (typeof ref.seriesRef !== 'string' || ref.seriesRef === '') {
+      errors.push('sourceRef.seriesRef: expected a non-empty string')
+    }
+    if (typeof ref.url !== 'string' || !/^https:\/\/\S+$/.test(ref.url)) {
+      errors.push('sourceRef.url: expected a non-empty https:// URL')
+    }
+    if (typeof ref.label !== 'string' || ref.label === '') {
+      errors.push('sourceRef.label: expected a non-empty string')
+    }
+  }
+  return result(errors)
+}
+
+/**
+ * Validate a 'SeriesStats' object's required fields and status-independent
+ * invariants (docs/03 §1.4).
+ *
+ * @param {unknown} value - candidate stats object.
+ * @returns {ValidationResult} validation result.
+ */
+export function validateSeriesStats(value) {
+  const errors = []
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return result(['stats: expected an object'])
+  }
+  const stats = /** @type {Record<string, any>} */ (value)
+  if (!isFiniteNumber(stats.latest)) errors.push('stats.latest: expected a finite number')
+  if (!isDateString(stats.latestAt)) errors.push('stats.latestAt: expected a real YYYY-MM-DD date')
+  for (const key of ['mean', 'min', 'max', 'stdDev', 'missingCount']) {
+    if (!isFiniteNumber(stats[key])) errors.push(`stats.${key}: expected a finite number`)
+  }
+  for (const key of ['prev', 'changeAbs', 'changePct', 'yoy', 'mom', 'zScoreLatestChange', 'slope', 'percentile']) {
+    const field = stats[key]
+    if (field !== undefined && field !== null && !isFiniteNumber(field)) {
+      errors.push(`stats.${key}: expected a finite number when present`)
+    }
+  }
+  if (isFiniteNumber(stats.percentile) && (stats.percentile < 0 || stats.percentile > 1)) {
+    errors.push('stats.percentile: expected a value in [0,1]')
+  }
+  return result(errors)
+}
+
+/**
+ * Validate a 'Metric' card (docs/03 §1.5).
+ *
+ * @param {unknown} value - candidate metric.
+ * @returns {ValidationResult} validation result.
+ */
+export function validateMetric(value) {
+  const errors = []
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return result(['metric: expected an object'])
+  }
+  const metric = /** @type {Record<string, any>} */ (value)
+  if (typeof metric.indicatorId !== 'string' || !ID_RE.test(metric.indicatorId)) {
+    errors.push('indicatorId: expected a dotted lowercase id')
+  }
+  if (metric.label === null || typeof metric.label !== 'object') {
+    errors.push('label: expected { zh, en }')
+  } else if (typeof metric.label.zh !== 'string' || metric.label.zh === '') {
+    errors.push('label.zh: expected a non-empty string')
+  }
+  if (typeof metric.unit !== 'string') errors.push('unit: expected a string')
+  if (!STATUSES.includes(metric.status)) {
+    errors.push(`status: expected one of ${STATUSES.join('|')}`)
+  }
+  if (metric.status !== 'error' && !isFiniteNumber(metric.latest)) {
+    errors.push('latest: expected a finite number unless status is error')
+  }
+  if (metric.latestAt !== undefined && !isDateString(metric.latestAt)) {
+    errors.push('latestAt: expected a real YYYY-MM-DD date when present')
+  }
+  if (!Array.isArray(metric.sparkline)) {
+    errors.push('sparkline: expected an array of numbers')
+  } else if (metric.sparkline.some((v) => !isFiniteNumber(v))) {
+    errors.push('sparkline: every value must be finite')
+  }
+  if (!Array.isArray(metric.hits)) errors.push('hits: expected an array')
+  if (!isFiniteNumber(metric.score)) errors.push('score: expected a finite number')
+  const ref = metric.sourceRef
+  if (ref === null || typeof ref !== 'object' || typeof ref.url !== 'string' || !/^https:\/\//.test(ref.url)) {
+    errors.push('sourceRef.url: expected an https:// URL')
+  }
+  return result(errors)
+}
+
+/**
+ * Validate a 'SeriesView' (docs/03 §1.4).
+ *
+ * @param {unknown} value - candidate series view.
+ * @returns {ValidationResult} validation result.
+ */
+export function validateSeriesView(value) {
+  const errors = []
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return result(['seriesView: expected an object'])
+  }
+  const view = /** @type {Record<string, any>} */ (value)
+  if (typeof view.indicatorId !== 'string' || !ID_RE.test(view.indicatorId)) {
+    errors.push('indicatorId: expected a dotted lowercase id')
+  }
+  const range = view.range
+  if (range === null || typeof range !== 'object' || !isDateString(range.from) || !isDateString(range.to)) {
+    errors.push('range: expected { from, to } as YYYY-MM-DD')
+  }
+  if (!Array.isArray(view.points)) {
+    errors.push('points: expected an array')
+  } else if (view.points.some((p) => p === null || typeof p !== 'object' || !isDateString(p.t) || !isFiniteNumber(p.v))) {
+    errors.push('points: every point must be { t: YYYY-MM-DD, v: finite number }')
+  }
+  if (!STATUSES.includes(view.status)) {
+    errors.push(`status: expected one of ${STATUSES.join('|')}`)
+  }
+  if (view.stats !== undefined && view.stats !== null) {
+    for (const error of validateSeriesStats(view.stats).errors) errors.push(`stats: ${error}`)
+  }
+  const ref = view.sourceRef
+  if (ref === null || typeof ref !== 'object' || typeof ref.url !== 'string' || !/^https:\/\//.test(ref.url)) {
+    errors.push('sourceRef.url: expected an https:// URL')
+  }
+  return result(errors)
+}
+
+/**
+ * Validate a 'SourceError' (docs/03 §1.7).
+ *
+ * @param {unknown} value - candidate error payload.
+ * @returns {ValidationResult} validation result.
+ */
+export function validateSourceError(value) {
+  const errors = []
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return result(['sourceError: expected an object'])
+  }
+  const error = /** @type {Record<string, any>} */ (value)
+  if (!ERROR_KINDS.includes(error.kind)) {
+    errors.push(`kind: expected one of ${ERROR_KINDS.join('|')}`)
+  }
+  if (typeof error.adapterId !== 'string') errors.push('adapterId: expected a string')
+  if (typeof error.seriesRef !== 'string') errors.push('seriesRef: expected a string')
+  if (typeof error.detail !== 'string') errors.push('detail: expected a string')
+  if (typeof error.retryable !== 'boolean') errors.push('retryable: expected a boolean')
+  return result(errors)
+}
+
+/**
+ * A classified source failure (docs/03 §1.7). Adapters throw exactly this.
+ */
+export class SourceError extends Error {
+  /**
+   * @param {object} init - error fields.
+   * @param {'network'|'http'|'parse'|'empty'|'unsupported'} init.kind - classification.
+   * @param {string} init.adapterId - owning adapter id.
+   * @param {string} init.seriesRef - requested series reference.
+   * @param {string} init.detail - human-readable detail.
+   * @param {number} [init.httpStatus] - upstream status when known.
+   */
+  constructor({ kind, adapterId, seriesRef, detail, httpStatus }) {
+    super(`${adapterId}/${seriesRef}: ${detail}`)
+    this.name = 'SourceError'
+    /** @type {'network'|'http'|'parse'|'empty'|'unsupported'} */
+    this.kind = kind
+    /** @type {string} */
+    this.adapterId = adapterId
+    /** @type {string} */
+    this.seriesRef = seriesRef
+    /** @type {string} */
+    this.detail = detail
+    if (httpStatus !== undefined) this.httpStatus = httpStatus
+    /**
+     * Only transport-level failures are worth a retry: a wrong series id
+     * ('unsupported') or a shape change ('parse') will fail again identically.
+     */
+    this.retryable = kind === 'network' || (kind === 'http' && (httpStatus ?? 0) >= 500)
+  }
+
+  /**
+   * Lossless-JSON projection for transport.
+   *
+   * @returns {object} plain JSON payload.
+   */
+  toJSON() {
+    return {
+      kind: this.kind,
+      adapterId: this.adapterId,
+      seriesRef: this.seriesRef,
+      detail: this.detail,
+      retryable: this.retryable,
+      ...(this.httpStatus === undefined ? {} : { httpStatus: this.httpStatus }),
+    }
+  }
+}
+
+/**
+ * Coerce any thrown value into a 'SourceError'-shaped JSON payload.
+ *
+ * @param {unknown} error - thrown value.
+ * @param {string} adapterId - owning adapter id.
+ * @param {string} seriesRef - requested series reference.
+ * @returns {{ kind: string, adapterId: string, seriesRef: string, detail: string, retryable: boolean, httpStatus?: number }} payload.
+ */
+export function toSourceErrorPayload(error, adapterId, seriesRef) {
+  if (error instanceof SourceError) return error.toJSON()
+  const detail = error instanceof Error ? error.message : String(error)
+  return {
+    kind: 'parse',
+    adapterId,
+    seriesRef,
+    detail,
+    retryable: false,
+  }
+}