@actuarial-ts/core 0.6.0 → 0.7.0

package/src/diagnosticExpressions.ts

@@ -2,6 +2,10 @@ import type {
   DiagnosticValidationIssue,
   DiagnosticValidationIssueCode,
 } from "./types.js";
+import {
+  isDiagnosticPlainRecord,
+  isDiagnosticToken,
+} from "./diagnosticRuntime.js";
 
 export const MAX_DIAGNOSTIC_EXPRESSION_DEPTH = 64;
 export const MAX_DIAGNOSTIC_EXPRESSION_NODES = 10_000;
@@ -56,12 +60,6 @@ interface WalkFrame {
   readonly ancestors: readonly object[];
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-  const prototype: unknown = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-
 function issue(
   issues: DiagnosticValidationIssue[],
   code: DiagnosticValidationIssueCode,
@@ -71,6 +69,30 @@ function issue(
   issues.push({ domain: "definition", code, path, message });
 }
 
+function propertyPath(parent: string, key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+    ? `${parent}.${key}`
+    : `${parent}[${JSON.stringify(key)}]`;
+}
+
+function rejectUnknownKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+  issues: DiagnosticValidationIssue[],
+): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      issue(
+        issues,
+        "unknown-key",
+        propertyPath(path, key),
+        `Unknown expression key ${key}`,
+      );
+    }
+  }
+}
+
 /**
  * Iterative structural/resource walk used before recursive normalization. It
  * deliberately accepts unknown so hostile inputs cannot overflow the host
@@ -81,9 +103,12 @@ export function walkDiagnosticExpression(
   kind: DiagnosticExpressionKind,
   path: string,
   issues: DiagnosticValidationIssue[],
+  initialDepth = 1,
 ): DiagnosticExpressionWalk {
   const dependencies = new Set<string>();
-  const stack: WalkFrame[] = [{ value, path, depth: 1, ancestors: [] }];
+  const stack: WalkFrame[] = [
+    { value, path, depth: initialDepth, ancestors: [] },
+  ];
   let nodeCount = 0;
   let maxDepth = 0;
   while (stack.length > 0) {
@@ -108,8 +133,13 @@ export function walkDiagnosticExpression(
       );
       break;
     }
-    if (!isRecord(frame.value)) {
-      issue(issues, "invalid-type", frame.path, "Expression node must be a plain object");
+    if (!isDiagnosticPlainRecord(frame.value)) {
+      issue(
+        issues,
+        "invalid-type",
+        frame.path,
+        "Expression node must be a plain object",
+      );
       continue;
     }
     if (frame.ancestors.includes(frame.value)) {
@@ -119,23 +149,64 @@ export function walkDiagnosticExpression(
     const op = frame.value.op;
     const nextAncestors = [...frame.ancestors, frame.value];
     if (kind === "role" && op === "role") {
-      if (typeof frame.value.role === "string") dependencies.add(frame.value.role);
-      else issue(issues, "invalid-type", `${frame.path}.role`, "Role reference must be a string");
+      rejectUnknownKeys(frame.value, ["op", "role"], frame.path, issues);
+      if (isDiagnosticToken(frame.value.role))
+        dependencies.add(frame.value.role);
+      else
+        issue(
+          issues,
+          typeof frame.value.role === "string"
+            ? "invalid-string"
+            : "invalid-type",
+          `${frame.path}.role`,
+          "Role reference must be a nonempty token",
+        );
       continue;
     }
     if ((kind === "measure" || kind === "claim") && op === "measure") {
-      if (typeof frame.value.measureId === "string") dependencies.add(frame.value.measureId);
-      else issue(issues, "invalid-type", `${frame.path}.measureId`, "Measure reference must be a string");
+      rejectUnknownKeys(frame.value, ["op", "measureId"], frame.path, issues);
+      if (isDiagnosticToken(frame.value.measureId))
+        dependencies.add(frame.value.measureId);
+      else
+        issue(
+          issues,
+          typeof frame.value.measureId === "string"
+            ? "invalid-string"
+            : "invalid-type",
+          `${frame.path}.measureId`,
+          "Measure reference must be a nonempty token",
+        );
       continue;
     }
     if (kind === "claim" && op === "claim-layer") {
-      if (typeof frame.value.measureId === "string") dependencies.add(frame.value.measureId);
-      else issue(issues, "invalid-type", `${frame.path}.measureId`, "Measure reference must be a string");
+      rejectUnknownKeys(
+        frame.value,
+        ["op", "measureId", "attachment", "limit"],
+        frame.path,
+        issues,
+      );
+      if (isDiagnosticToken(frame.value.measureId))
+        dependencies.add(frame.value.measureId);
+      else
+        issue(
+          issues,
+          typeof frame.value.measureId === "string"
+            ? "invalid-string"
+            : "invalid-type",
+          `${frame.path}.measureId`,
+          "Measure reference must be a nonempty token",
+        );
       continue;
     }
     if (op === "add") {
+      rejectUnknownKeys(frame.value, ["op", "terms"], frame.path, issues);
       if (!Array.isArray(frame.value.terms) || frame.value.terms.length === 0) {
-        issue(issues, "invalid-type", `${frame.path}.terms`, "Add expression requires at least one term");
+        issue(
+          issues,
+          "invalid-type",
+          `${frame.path}.terms`,
+          "Add expression requires at least one term",
+        );
         continue;
       }
       for (let index = frame.value.terms.length - 1; index >= 0; index--) {
@@ -149,6 +220,12 @@ export function walkDiagnosticExpression(
       continue;
     }
     if (op === "subtract") {
+      rejectUnknownKeys(
+        frame.value,
+        ["op", "left", "right"],
+        frame.path,
+        issues,
+      );
       stack.push({
         value: frame.value.right,
         path: `${frame.path}.right`,
@@ -163,7 +240,12 @@ export function walkDiagnosticExpression(
       });
       continue;
     }
-    issue(issues, "invalid-type", `${frame.path}.op`, `Unknown ${kind} expression operator`);
+    issue(
+      issues,
+      "invalid-type",
+      `${frame.path}.op`,
+      `Unknown ${kind} expression operator`,
+    );
   }
   return {
     dependencies: [...dependencies].sort(),

package/src/diagnosticFormulas.ts

@@ -6,16 +6,96 @@ import type {
   DiagnosticMeasureStats,
   DiagnosticMetricPresentation,
 } from "./diagnosticDefinitions.js";
-import type { DiagnosticMeasureExpression, DiagnosticRoleExpression } from "./diagnosticExpressions.js";
-import type { DiagnosticExpressionOverflow, DiagnosticRuleNotEvaluatedReason } from "./diagnosticRules.js";
+import type {
+  DiagnosticMeasureExpression,
+  DiagnosticRoleExpression,
+} from "./diagnosticExpressions.js";
+import type {
+  DiagnosticExpressionOverflow,
+  DiagnosticRuleNotEvaluatedReason,
+} from "./diagnosticRules.js";
+import { normalizeDiagnosticSourceLocations } from "./diagnosticSourceOrdering.js";
+import { hasDiagnosticOwn } from "./diagnosticRuntime.js";
 
 export const CASUALTY_FORMULA_TEMPLATES = Object.freeze([
-  { id: "frequency", version: "1.0.0", roles: { claims: { kind: "count" }, exposure: { kind: "exposure" } }, numerator: { op: "role", role: "claims" }, denominator: { op: "role", role: "exposure" }, denominatorPolicy: "positive-or-null" },
-  { id: "share", version: "1.0.0", roles: { part: { kind: "count", compatibilityGroup: "count-population" }, whole: { kind: "count", compatibilityGroup: "count-population" } }, numerator: { op: "role", role: "part" }, denominator: { op: "role", role: "whole" }, denominatorPolicy: "positive-or-null" },
-  { id: "paid-to-incurred", version: "1.0.0", roles: { paid: { kind: "amount", compatibilityGroup: "amount-basis", developmentSemantics: "cumulative" }, incurred: { kind: "amount", compatibilityGroup: "amount-basis", developmentSemantics: "cumulative" } }, numerator: { op: "role", role: "paid" }, denominator: { op: "role", role: "incurred" }, denominatorPolicy: "positive-or-null" },
-  { id: "amount-per-exposure", version: "1.0.0", roles: { amount: { kind: "amount" }, exposure: { kind: "exposure" } }, numerator: { op: "role", role: "amount" }, denominator: { op: "role", role: "exposure" }, denominatorPolicy: "positive-or-null" },
-  { id: "amount-per-claim", version: "1.0.0", roles: { amount: { kind: "amount" }, claims: { kind: "count" } }, numerator: { op: "role", role: "amount" }, denominator: { op: "role", role: "claims" }, denominatorPolicy: "positive-or-null" },
-  { id: "case-per-open", version: "1.0.0", roles: { incurred: { kind: "amount", compatibilityGroup: "amount-basis", developmentSemantics: "cumulative" }, paid: { kind: "amount", compatibilityGroup: "amount-basis", developmentSemantics: "cumulative" }, open: { kind: "count", developmentSemantics: "point-in-time" } }, numerator: { op: "subtract", left: { op: "role", role: "incurred" }, right: { op: "role", role: "paid" } }, denominator: { op: "role", role: "open" }, denominatorPolicy: "positive-or-null" },
+  {
+    id: "frequency",
+    version: "1.0.0",
+    roles: { claims: { kind: "count" }, exposure: { kind: "exposure" } },
+    numerator: { op: "role", role: "claims" },
+    denominator: { op: "role", role: "exposure" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "share",
+    version: "1.0.0",
+    roles: {
+      part: { kind: "count", compatibilityGroup: "count-population" },
+      whole: { kind: "count", compatibilityGroup: "count-population" },
+    },
+    numerator: { op: "role", role: "part" },
+    denominator: { op: "role", role: "whole" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "paid-to-incurred",
+    version: "1.0.0",
+    roles: {
+      paid: {
+        kind: "amount",
+        compatibilityGroup: "amount-basis",
+        developmentSemantics: "cumulative",
+      },
+      incurred: {
+        kind: "amount",
+        compatibilityGroup: "amount-basis",
+        developmentSemantics: "cumulative",
+      },
+    },
+    numerator: { op: "role", role: "paid" },
+    denominator: { op: "role", role: "incurred" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "amount-per-exposure",
+    version: "1.0.0",
+    roles: { amount: { kind: "amount" }, exposure: { kind: "exposure" } },
+    numerator: { op: "role", role: "amount" },
+    denominator: { op: "role", role: "exposure" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "amount-per-claim",
+    version: "1.0.0",
+    roles: { amount: { kind: "amount" }, claims: { kind: "count" } },
+    numerator: { op: "role", role: "amount" },
+    denominator: { op: "role", role: "claims" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "case-per-open",
+    version: "1.0.0",
+    roles: {
+      incurred: {
+        kind: "amount",
+        compatibilityGroup: "amount-basis",
+        developmentSemantics: "cumulative",
+      },
+      paid: {
+        kind: "amount",
+        compatibilityGroup: "amount-basis",
+        developmentSemantics: "cumulative",
+      },
+      open: { kind: "count", developmentSemantics: "point-in-time" },
+    },
+    numerator: {
+      op: "subtract",
+      left: { op: "role", role: "incurred" },
+      right: { op: "role", role: "paid" },
+    },
+    denominator: { op: "role", role: "open" },
+    denominatorPolicy: "positive-or-null",
+  },
 ] as const satisfies readonly DiagnosticFormulaTemplate[]);
 
 export interface DiagnosticQuantitySemantics {
@@ -34,11 +114,17 @@ export interface DiagnosticMetricFinding {
   readonly code: string;
   readonly message: string;
   readonly severity: "info" | "warning" | "fail";
-  readonly category: "structural" | "aggregation" | "calculation" | "rule" | "presentation";
+  readonly category:
+    | "structural"
+    | "aggregation"
+    | "calculation"
+    | "rule"
+    | "presentation";
   readonly ruleId?: string;
   readonly measureId?: string;
   readonly instanceId?: string;
   readonly expressionPath?: string;
+  readonly offendingKey?: string;
   readonly sourceGroup?: string;
   readonly group?: string;
   readonly origin?: string;
@@ -56,12 +142,14 @@ export interface FinalizedDiagnosticMeasure {
   readonly stats: DiagnosticMeasureStats;
   readonly readiness: readonly DiagnosticRuleNotEvaluatedReason[];
   readonly expressionOverflows?: readonly DiagnosticExpressionOverflow[];
+  readonly sources?: readonly import("./diagnosticDefinitions.js").DiagnosticSourceLocation[];
 }
 
 interface ExpressionResult {
   readonly value: number | null;
   readonly reasons: readonly DiagnosticRuleNotEvaluatedReason[];
   readonly overflows: readonly DiagnosticExpressionOverflow[];
+  readonly sources: readonly import("./diagnosticDefinitions.js").DiagnosticSourceLocation[];
 }
 
 function neumaier(values: readonly number[]): number | null {
@@ -69,7 +157,10 @@ function neumaier(values: readonly number[]): number | null {
   let correction = 0;
   for (const value of values) {
     const next = sum + value;
-    correction += Math.abs(sum) >= Math.abs(value) ? (sum - next) + value : (value - next) + sum;
+    correction +=
+      Math.abs(sum) >= Math.abs(value)
+        ? sum - next + value
+        : value - next + sum;
     sum = next;
     if (!Number.isFinite(sum) || !Number.isFinite(correction)) return null;
   }
@@ -77,42 +168,90 @@ function neumaier(values: readonly number[]): number | null {
   return Number.isFinite(result) ? (Object.is(result, -0) ? 0 : result) : null;
 }
 
-function uniqueReasons(values: readonly DiagnosticRuleNotEvaluatedReason[]): readonly DiagnosticRuleNotEvaluatedReason[] {
-  const order: readonly DiagnosticRuleNotEvaluatedReason[] = ["missing", "imputed", "non-finite", "structural-ambiguity", "aggregation-overflow", "expression-overflow", "tolerance-overflow"];
+function uniqueReasons(
+  values: readonly DiagnosticRuleNotEvaluatedReason[],
+): readonly DiagnosticRuleNotEvaluatedReason[] {
+  const order: readonly DiagnosticRuleNotEvaluatedReason[] = [
+    "missing",
+    "imputed",
+    "non-finite",
+    "structural-ambiguity",
+    "aggregation-overflow",
+    "expression-overflow",
+    "tolerance-overflow",
+  ];
   return order.filter((reason) => values.includes(reason));
 }
 
+function pointer(path: string, segment: string | number): string {
+  const escaped = String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+  return `${path}/${escaped}`;
+}
+
 export function evaluateDiagnosticMeasureExpression(
   expression: DiagnosticDeepReadonly<DiagnosticMeasureExpression>,
   measures: Readonly<Record<string, FinalizedDiagnosticMeasure>>,
   path: string,
 ): ExpressionResult {
   if (expression.op === "measure") {
-    const value = measures[expression.measureId];
+    const value = hasDiagnosticOwn(measures, expression.measureId)
+      ? measures[expression.measureId]
+      : undefined;
     return value
-      ? { value: value.quantity.value, reasons: value.readiness, overflows: value.expressionOverflows ?? [] }
-      : { value: null, reasons: ["missing"], overflows: [] };
+      ? {
+          value: value.quantity.value,
+          reasons: value.readiness,
+          overflows: value.expressionOverflows ?? [],
+          sources: value.sources ?? [],
+        }
+      : { value: null, reasons: ["missing"], overflows: [], sources: [] };
   }
-  const children = expression.op === "add"
-    ? expression.terms.map((term, index) => evaluateDiagnosticMeasureExpression(term, measures, `${path}.terms[${index}]`))
-    : [
-        evaluateDiagnosticMeasureExpression(expression.left, measures, `${path}.left`),
-        evaluateDiagnosticMeasureExpression(expression.right, measures, `${path}.right`),
-      ];
+  const children =
+    expression.op === "add"
+      ? expression.terms.map((term, index) =>
+          evaluateDiagnosticMeasureExpression(
+            term,
+            measures,
+            pointer(pointer(path, "terms"), index),
+          ),
+        )
+      : [
+          evaluateDiagnosticMeasureExpression(
+            expression.left,
+            measures,
+            pointer(path, "left"),
+          ),
+          evaluateDiagnosticMeasureExpression(
+            expression.right,
+            measures,
+            pointer(path, "right"),
+          ),
+        ];
   const reasons = uniqueReasons(children.flatMap((child) => child.reasons));
   const overflows = children.flatMap((child) => child.overflows);
-  if (children.some((child) => child.value === null)) return { value: null, reasons, overflows };
-  const value = expression.op === "add"
-    ? neumaier(children.map((child) => child.value!))
-    : children[0]!.value! - children[1]!.value!;
+  const sources = normalizeDiagnosticSourceLocations(
+    children.flatMap((child) => child.sources),
+  );
+  if (children.some((child) => child.value === null))
+    return { value: null, reasons, overflows, sources };
+  const value =
+    expression.op === "add"
+      ? neumaier(children.map((child) => child.value!))
+      : children[0]!.value! - children[1]!.value!;
   if (value === null || !Number.isFinite(value)) {
     return {
       value: null,
       reasons: uniqueReasons([...reasons, "expression-overflow"]),
-      overflows: [...overflows, { expressionPath: path, sources: [] }],
+      overflows: [...overflows, { expressionPath: path, sources }],
+      sources,
     };
   }
-  return { value: Object.is(value, -0) ? 0 : value, reasons, overflows };
+  return {
+    value: Object.is(value, -0) ? 0 : value,
+    reasons,
+    overflows,
+    sources,
+  };
 }
 
 export function evaluateDiagnosticRoleExpression(
@@ -120,20 +259,69 @@ export function evaluateDiagnosticRoleExpression(
   bindings: Readonly<Record<string, ExpressionResult>>,
   path: string,
 ): ExpressionResult {
-  if (expression.op === "role") return bindings[expression.role] ?? { value: null, reasons: ["missing"], overflows: [] };
-  const children = expression.op === "add"
-    ? expression.terms.map((term, index) => evaluateDiagnosticRoleExpression(term, bindings, `${path}.terms[${index}]`))
-    : [evaluateDiagnosticRoleExpression(expression.left, bindings, `${path}.left`), evaluateDiagnosticRoleExpression(expression.right, bindings, `${path}.right`)];
+  if (expression.op === "role")
+    return hasDiagnosticOwn(bindings, expression.role)
+      ? bindings[expression.role]!
+      : { value: null, reasons: ["missing"], overflows: [], sources: [] };
+  const children =
+    expression.op === "add"
+      ? expression.terms.map((term, index) =>
+          evaluateDiagnosticRoleExpression(
+            term,
+            bindings,
+            pointer(pointer(path, "terms"), index),
+          ),
+        )
+      : [
+          evaluateDiagnosticRoleExpression(
+            expression.left,
+            bindings,
+            pointer(path, "left"),
+          ),
+          evaluateDiagnosticRoleExpression(
+            expression.right,
+            bindings,
+            pointer(path, "right"),
+          ),
+        ];
   const reasons = uniqueReasons(children.flatMap((child) => child.reasons));
   const overflows = children.flatMap((child) => child.overflows);
-  if (children.some((child) => child.value === null)) return { value: null, reasons, overflows };
-  const value = expression.op === "add" ? neumaier(children.map((child) => child.value!)) : children[0]!.value! - children[1]!.value!;
-  if (value === null || !Number.isFinite(value)) return { value: null, reasons: uniqueReasons([...reasons, "expression-overflow"]), overflows: [...overflows, { expressionPath: path, sources: [] }] };
-  return { value: Object.is(value, -0) ? 0 : value, reasons, overflows };
+  const sources = normalizeDiagnosticSourceLocations(
+    children.flatMap((child) => child.sources),
+  );
+  if (children.some((child) => child.value === null))
+    return { value: null, reasons, overflows, sources };
+  const value =
+    expression.op === "add"
+      ? neumaier(children.map((child) => child.value!))
+      : children[0]!.value! - children[1]!.value!;
+  if (value === null || !Number.isFinite(value))
+    return {
+      value: null,
+      reasons: uniqueReasons([...reasons, "expression-overflow"]),
+      overflows: [...overflows, { expressionPath: path, sources }],
+      sources,
+    };
+  return {
+    value: Object.is(value, -0) ? 0 : value,
+    reasons,
+    overflows,
+    sources,
+  };
 }
 
-export function diagnosticRawRatio(numerator: number | null, denominator: number | null): number | null {
-  if (numerator === null || denominator === null || !Number.isFinite(numerator) || !Number.isFinite(denominator) || denominator <= 0) return null;
+export function diagnosticRawRatio(
+  numerator: number | null,
+  denominator: number | null,
+): number | null {
+  if (
+    numerator === null ||
+    denominator === null ||
+    !Number.isFinite(numerator) ||
+    !Number.isFinite(denominator) ||
+    denominator <= 0
+  )
+    return null;
   const ratio = safeRatio(numerator, denominator);
   return ratio !== null && Number.isFinite(ratio) ? ratio : null;
 }
@@ -141,10 +329,22 @@ export function diagnosticRawRatio(numerator: number | null, denominator: number
 export function applyDiagnosticPresentation(
   rawValue: number | null,
   presentation: DiagnosticDeepReadonly<DiagnosticMetricPresentation>,
-): { readonly value: number | null; readonly finding: DiagnosticMetricFinding | null } {
+): {
+  readonly value: number | null;
+  readonly finding: DiagnosticMetricFinding | null;
+} {
   if (rawValue === null) return { value: null, finding: null };
   const value = rawValue * presentation.scale;
   return Number.isFinite(value)
     ? { value: Object.is(value, -0) ? 0 : value, finding: null }
-    : { value: null, finding: { code: "diagnostic-presentation-overflow", message: "Diagnostic presentation scaling overflowed", severity: "fail", category: "presentation", sources: [] } };
+    : {
+        value: null,
+        finding: {
+          code: "diagnostic-presentation-overflow",
+          message: "Diagnostic presentation scaling overflowed",
+          severity: "fail",
+          category: "presentation",
+          sources: [],
+        },
+      };
 }