@actuarial-ts/core 0.5.0 → 0.6.1

package/src/diagnosticOrdering.ts

@@ -0,0 +1,106 @@
+import { canonicalJson } from "./canonical.js";
+import type {
+  DiagnosticMeasureContribution,
+  DiagnosticStructuralBlocker,
+} from "./diagnosticAggregation.js";
+import type { DiagnosticMetricFinding } from "./diagnosticFormulas.js";
+import { compareDiagnosticSourceLocations } from "./diagnosticSourceOrdering.js";
+import type { DiagnosticSourceLocation } from "./diagnosticDefinitions.js";
+
+/** Section 15 total order, for values already validated by a public boundary. */
+export function compareDiagnosticIdentityValues(
+  left: unknown,
+  right: unknown,
+): number {
+  if (left === right) return 0;
+  if (left === undefined) return -1;
+  if (right === undefined) return 1;
+  if (left === null) return -1;
+  if (right === null) return 1;
+  if (typeof left === "number" && typeof right === "number")
+    return left - right;
+  if (typeof left === "boolean" && typeof right === "boolean")
+    return Number(left) - Number(right);
+  if (Array.isArray(left) && Array.isArray(right)) {
+    for (let i = 0; i < Math.min(left.length, right.length); i++) {
+      const comparison = compareDiagnosticIdentityValues(left[i], right[i]);
+      if (comparison !== 0) return comparison;
+    }
+    return left.length - right.length;
+  }
+  const a = typeof left === "string" ? left : canonicalJson(left);
+  const b = typeof right === "string" ? right : canonicalJson(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function compareSources(
+  left: readonly DiagnosticSourceLocation[],
+  right: readonly DiagnosticSourceLocation[],
+): number {
+  for (let i = 0; i < Math.min(left.length, right.length); i++) {
+    const comparison = compareDiagnosticSourceLocations(left[i]!, right[i]!);
+    if (comparison !== 0) return comparison;
+  }
+  return left.length - right.length;
+}
+
+export function compareDiagnosticFindings(
+  left: DiagnosticMetricFinding,
+  right: DiagnosticMetricFinding,
+): number {
+  const fields = [
+    "category",
+    "severity",
+    "code",
+    "ruleId",
+    "instanceId",
+    "measureId",
+    "expressionPath",
+    "sourceGroup",
+    "group",
+    "origin",
+    "valuation",
+    "developmentAge",
+    "ageUnit",
+    "recordId",
+    "claimId",
+    "exposureKey",
+    "message",
+  ] as const;
+  return (
+    compareDiagnosticIdentityValues(
+      fields.map((key) => left[key]),
+      fields.map((key) => right[key]),
+    ) ||
+    compareDiagnosticIdentityValues(left.offendingKey, right.offendingKey) ||
+    compareSources(left.sources, right.sources)
+  );
+}
+
+export function compareDiagnosticContributions(
+  left: DiagnosticMeasureContribution,
+  right: DiagnosticMeasureContribution,
+): number {
+  return (
+    compareDiagnosticIdentityValues(
+      [left.sourceId, left.status, left.deduplicated],
+      [right.sourceId, right.status, right.deduplicated],
+    ) ||
+    compareSources(left.sources, right.sources) ||
+    compareDiagnosticIdentityValues(left, right)
+  );
+}
+
+export function compareDiagnosticBlockers(
+  left: DiagnosticStructuralBlocker,
+  right: DiagnosticStructuralBlocker,
+): number {
+  return (
+    compareDiagnosticIdentityValues(
+      [left.code, left.message, left.sourceIds],
+      [right.code, right.message, right.sourceIds],
+    ) ||
+    compareSources(left.sources, right.sources) ||
+    compareDiagnosticIdentityValues(left.finding, right.finding)
+  );
+}

package/src/diagnosticPeriodAxis.ts

@@ -0,0 +1,92 @@
+import type { DiagnosticPeriodAxis } from "./diagnosticDefinitions.js";
+
+export interface NormalizedDiagnosticAxisPeriod {
+  readonly label: string;
+  readonly coordinate: number;
+}
+
+export type DiagnosticPeriodSide = "origin" | "valuation";
+
+function calendarCoordinate(
+  label: string,
+  cadence: "month" | "quarter" | "year",
+  anchor: "start" | "end",
+): number | null {
+  let year: number;
+  let start: number;
+  let width: number;
+  if (cadence === "year") {
+    const match = /^(\d{4})$/.exec(label);
+    if (!match) return null;
+    year = Number(match[1]);
+    start = year * 12;
+    width = 12;
+  } else if (cadence === "month") {
+    const match = /^(\d{4})-(0[1-9]|1[0-2])$/.exec(label);
+    if (!match) return null;
+    year = Number(match[1]);
+    start = year * 12 + Number(match[2]) - 1;
+    width = 1;
+  } else {
+    const compact = /^(\d{4})Q([1-4])$/.exec(label);
+    const hyphenated = /^(\d{4})-Q([1-4])$/.exec(label);
+    const first = /^Q([1-4]) (\d{4})$/.exec(label);
+    const match = compact ?? hyphenated ?? first;
+    if (!match) return null;
+    const quarterFirst = match === first;
+    year = Number(match[quarterFirst ? 2 : 1]);
+    const quarter = Number(match[quarterFirst ? 1 : 2]);
+    start = year * 12 + (quarter - 1) * 3;
+    width = 3;
+  }
+  if (year < 1 || year > 9999) return null;
+  return start + (anchor === "end" ? width : 0);
+}
+
+/** Pure axis-level period normalization shared by compilation and execution. */
+export function normalizeDiagnosticPeriodWithAxis(
+  axis: DiagnosticPeriodAxis,
+  side: DiagnosticPeriodSide,
+  label: unknown,
+): NormalizedDiagnosticAxisPeriod | null {
+  if (typeof label !== "string" || axis === null || typeof axis !== "object")
+    return null;
+  if (axis.kind === "calendar") {
+    const cadence =
+      side === "origin" ? axis.originCadence : axis.valuationCadence;
+    const anchor = side === "origin" ? axis.originAnchor : axis.valuationAnchor;
+    if (
+      !["month", "quarter", "year"].includes(cadence) ||
+      !["start", "end"].includes(anchor)
+    )
+      return null;
+    const coordinate = calendarCoordinate(label, cadence, anchor);
+    if (coordinate === null) return null;
+    const canonicalLabel =
+      cadence === "quarter"
+        ? (() => {
+            const startCoordinate = calendarCoordinate(
+              label,
+              cadence,
+              "start",
+            )!;
+            const year = Math.floor(startCoordinate / 12);
+            return `${String(year).padStart(4, "0")}-Q${Math.floor((startCoordinate % 12) / 3) + 1}`;
+          })()
+        : label;
+    return { label: canonicalLabel, coordinate };
+  }
+  if (
+    axis.kind !== "ordered" ||
+    !Array.isArray(axis[side === "origin" ? "origins" : "valuations"])
+  )
+    return null;
+  const catalog = side === "origin" ? axis.origins : axis.valuations;
+  const item = catalog.find(
+    (coordinate) =>
+      coordinate?.label === label || coordinate?.aliases?.includes(label),
+  );
+  return item && typeof item.coordinate === "number"
+    ? { label: item.label, coordinate: item.coordinate }
+    : null;
+}

package/src/diagnosticPeriods.ts

@@ -0,0 +1,102 @@
+import type {
+  CompiledDiagnosticDefinition,
+  DiagnosticPeriodAxis,
+} from "./diagnosticDefinitions.js";
+import { assertCompiledDiagnosticDefinition } from "./diagnosticDefinitions.js";
+import {
+  normalizeDiagnosticPeriodWithAxis,
+  type DiagnosticPeriodSide,
+} from "./diagnosticPeriodAxis.js";
+import { DiagnosticValidationError } from "./types.js";
+
+export interface DiagnosticNormalizedPeriod {
+  readonly label: string;
+  readonly coordinate: number;
+}
+
+function normalizeWithAxis(
+  axis: DiagnosticPeriodAxis,
+  side: DiagnosticPeriodSide,
+  label: string,
+): DiagnosticNormalizedPeriod {
+  const normalized = normalizeDiagnosticPeriodWithAxis(axis, side, label);
+  if (!normalized)
+    throw new DiagnosticValidationError([
+      {
+        domain: "input",
+        code: "invalid-period",
+        path: `$.${side}`,
+        message:
+          axis.kind === "calendar"
+            ? `Invalid ${side === "origin" ? axis.originCadence : axis.valuationCadence} ${side} label ${JSON.stringify(label)}`
+            : `Unknown ordered-axis ${side} label ${JSON.stringify(label)}`,
+      },
+    ]);
+  return Object.freeze(normalized);
+}
+
+export function normalizeDiagnosticPeriod(
+  definition: CompiledDiagnosticDefinition,
+  side: DiagnosticPeriodSide,
+  label: string,
+): DiagnosticNormalizedPeriod {
+  assertCompiledDiagnosticDefinition(definition);
+  return normalizeWithAxis(
+    definition.definition.periodAxis as DiagnosticPeriodAxis,
+    side,
+    label,
+  );
+}
+
+export function diagnosticDevelopmentAge(
+  definition: CompiledDiagnosticDefinition,
+  origin: string,
+  valuation: string,
+): {
+  readonly origin: DiagnosticNormalizedPeriod;
+  readonly valuation: DiagnosticNormalizedPeriod;
+  readonly developmentAge: number;
+  readonly ageUnit: string;
+} {
+  const normalizedOrigin = normalizeDiagnosticPeriod(
+    definition,
+    "origin",
+    origin,
+  );
+  const normalizedValuation = normalizeDiagnosticPeriod(
+    definition,
+    "valuation",
+    valuation,
+  );
+  const axis = definition.definition.periodAxis;
+  const developmentAge =
+    normalizedValuation.coordinate -
+    normalizedOrigin.coordinate +
+    axis.ageOffset;
+  if (!Number.isSafeInteger(developmentAge) || developmentAge < 0)
+    throw new DiagnosticValidationError([
+      {
+        domain: "input",
+        code: "invalid-period",
+        path: "$.valuation",
+        message:
+          "Valuation period precedes origin period or development age is unsafe",
+      },
+    ]);
+  return Object.freeze({
+    origin: normalizedOrigin,
+    valuation: normalizedValuation,
+    developmentAge,
+    ageUnit: axis.ageUnit,
+  });
+}
+
+export function compareDiagnosticPeriods(
+  left: DiagnosticNormalizedPeriod,
+  right: DiagnosticNormalizedPeriod,
+): number {
+  return (
+    left.coordinate - right.coordinate ||
+    (left.label < right.label ? -1 : left.label > right.label ? 1 : 0)
+  );
+}