@actuarial-ts/data 0.3.0 → 0.4.0

package/src/exposure.ts

@@ -0,0 +1,136 @@
+import type { ExposureRecord } from "@actuarial-ts/core";
+import { ReservingError } from "@actuarial-ts/core";
+import { z } from "zod";
+import { parseCsv } from "./csv.js";
+
+/** Runtime schema for an exposure record after CSV field parsing. */
+export const exposureRecordSchema = z
+  .object({
+    origin: z.string().trim().min(1),
+    earnedPremium: z.number().finite().nullable(),
+    exposureUnits: z.number().finite().nullable(),
+  })
+  .strict()
+  .refine((record) => record.earnedPremium !== null || record.exposureUnits !== null, {
+    message: "earnedPremium and exposureUnits cannot both be null",
+  });
+
+export interface ExposureRowError {
+  /** 1-based physical file line where the row starts. */
+  row: number;
+  message: string;
+}
+
+export interface ExposureParseResult {
+  exposures: ExposureRecord[];
+  errors: ExposureRowError[];
+}
+
+function normalizeHeader(header: string): string {
+  return header.trim().toLowerCase().replace(/\s+/g, "_");
+}
+
+function optionalAmount(
+  name: string,
+  raw: string,
+  errors: string[],
+): number | null {
+  const value = raw.trim();
+  if (value === "") return null;
+  if (/[,()]|\s/.test(value) || !/^-?\d+(\.\d+)?$/.test(value)) {
+    errors.push(
+      `${name} must be blank or an unformatted finite decimal (got "${raw}")`,
+    );
+    return null;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    errors.push(`${name} must be blank or a finite decimal number (got "${raw}")`);
+    return null;
+  }
+  return parsed;
+}
+
+/**
+ * Parses origin-period exposure data.
+ *
+ * Required header: `origin`, plus at least one of `earned_premium` or
+ * `exposure_units`. Either numeric field may be blank on an individual row,
+ * but not both. Extra source fields (for example gross written premium or a
+ * source claim count) are intentionally preserved in the caller's source file
+ * and ignored here rather than relabeled as an SDK measure.
+ */
+export function parseExposureCsv(text: string): ExposureParseResult {
+  const { rows: grid, rowLines, warnings } = parseCsv(text);
+  const headers = (grid[0] ?? []).map(normalizeHeader);
+  if (!headers.includes("origin")) {
+    throw new ReservingError(
+      "SHAPE",
+      `Missing required column: origin. Found: ${headers.filter(Boolean).join(", ") || "(none)"}`,
+    );
+  }
+  if (!headers.includes("earned_premium") && !headers.includes("exposure_units")) {
+    throw new ReservingError(
+      "SHAPE",
+      "Exposure CSV must include earned_premium, exposure_units, or both",
+    );
+  }
+
+  const columnIndex = new Map<string, number>();
+  headers.forEach((header, index) => {
+    if (!columnIndex.has(header)) columnIndex.set(header, index);
+  });
+  const errors: ExposureRowError[] = warnings.map((warning) => {
+    const line = /line (\d+)/.exec(warning)?.[1];
+    return { row: line === undefined ? 1 : Number(line), message: `CSV structure: ${warning}` };
+  });
+  const parsedRows: { exposure: ExposureRecord; row: number }[] = [];
+
+  for (let index = 1; index < grid.length; index++) {
+    const row = grid[index]!;
+    const rowNumber = rowLines[index]!;
+    const cell = (name: string): string => {
+      const position = columnIndex.get(name);
+      return position === undefined ? "" : (row[position] ?? "").trim();
+    };
+    const rowErrors: string[] = [];
+    const origin = cell("origin");
+    if (origin === "") rowErrors.push("origin is required");
+    const earnedPremium = optionalAmount("earned_premium", cell("earned_premium"), rowErrors);
+    const exposureUnits = optionalAmount("exposure_units", cell("exposure_units"), rowErrors);
+    if (earnedPremium === null && exposureUnits === null && rowErrors.length === 0) {
+      rowErrors.push("earned_premium and exposure_units cannot both be blank");
+    }
+    if (rowErrors.length > 0) {
+      for (const message of rowErrors) errors.push({ row: rowNumber, message });
+      continue;
+    }
+    const validated = exposureRecordSchema.safeParse({ origin, earnedPremium, exposureUnits });
+    if (!validated.success) {
+      for (const issue of validated.error.issues) {
+        errors.push({ row: rowNumber, message: issue.message });
+      }
+      continue;
+    }
+    parsedRows.push({ exposure: validated.data, row: rowNumber });
+  }
+
+  const rowsByOrigin = new Map<string, { exposure: ExposureRecord; row: number }[]>();
+  for (const parsed of parsedRows) {
+    const sameOrigin = rowsByOrigin.get(parsed.exposure.origin);
+    if (sameOrigin === undefined) rowsByOrigin.set(parsed.exposure.origin, [parsed]);
+    else sameOrigin.push(parsed);
+  }
+  const exposures: ExposureRecord[] = [];
+  for (const [origin, sameOrigin] of rowsByOrigin) {
+    if (sameOrigin.length > 1) {
+      for (const duplicate of sameOrigin) {
+        errors.push({ row: duplicate.row, message: `duplicate origin "${origin}"` });
+      }
+    } else {
+      exposures.push(sameOrigin[0]!.exposure);
+    }
+  }
+  errors.sort((a, b) => a.row - b.row);
+  return { exposures, errors };
+}

package/src/index.ts

@@ -1,4 +1,8 @@
 export * from "./csv.js";
+export * from "./annualDevelopment.js";
+export * from "./exposure.js";
+export * from "./diagnosticInput.js";
+export * from "./diagnosticReview.js";
 export * from "./lossRun.js";
 export * from "./longFormat.js";
 export * from "./review.js";

package/src/lossRun.ts

@@ -15,8 +15,9 @@ import { parseCsv } from "./csv.js";
  * collected — not thrown — so the caller decides whether to abort or load
  * the clean rows; a row with any error contributes no claim.
  *
- * Row numbers in errors are 1-based INCLUDING the header row, so the first
- * data row is row 2.
+ * Row numbers in errors are the 1-based PHYSICAL line in the file where the
+ * row starts (header included; blank lines and newlines inside quoted fields
+ * count), so in a file with no blank lines the first data row is row 2.
  *
  * Unlike the workbench importer, negative paid/case amounts are accepted
  * here: the ASOP 23 review layer (reviewClaimData) flags them, keeping the
@@ -34,7 +35,7 @@ const REQUIRED_COLUMNS = [
 ] as const;
 
 export interface LossRunRowError {
-  /** 1-based row number including the header (first data row = 2). */
+  /** 1-based physical file line where the row starts (first data row = 2 when nothing precedes it). */
   row: number;
   message: string;
 }
@@ -68,7 +69,7 @@ function isValidIsoDate(value: string): boolean {
 
 /** Parses a loss-run CSV into ClaimSnapshots plus per-row validation errors. */
 export function parseLossRunCsv(text: string): LossRunParseResult {
-  const { rows: grid, warnings: csvWarnings } = parseCsv(text);
+  const { rows: grid, rowLines, warnings: csvWarnings } = parseCsv(text);
   const headers = (grid[0] ?? []).map(normalizeHeader);
   const missing = REQUIRED_COLUMNS.filter((c) => !headers.includes(c));
   if (missing.length > 0) {
@@ -94,7 +95,11 @@ export function parseLossRunCsv(text: string): LossRunParseResult {
   }
 
   for (let r = 1; r < grid.length; r++) {
-    const rowNumber = r + 1; // 1-based including the header row
+    // Physical 1-based line in the file where this row starts — NOT r + 1:
+    // blank lines and quoted embedded newlines make grid index and file line
+    // diverge, and the structural-warning path above already reports physical
+    // lines. One errors array, one numbering scheme.
+    const rowNumber = rowLines[r]!;
     const cells = grid[r]!;
     const cell = (name: string): string => (cells[columnIndex.get(name)!] ?? "").trim();
     const rowErrors: string[] = [];

package/src/review.ts

@@ -24,11 +24,29 @@ import type { ClaimSnapshot, Triangle } from "@actuarial-ts/core";
 
 export type DataCheckStatus = "pass" | "warning" | "fail" | "not-evaluated";
 
+export interface DataFindingContext {
+  origin?: string;
+  valuation?: string;
+  ageMonths?: number;
+  group?: string;
+  sourceFile?: string;
+  sourceRow?: number;
+}
+
+export interface DataFinding {
+  /** Stable machine-readable finding code, usually the containing check id. */
+  code: string;
+  message: string;
+  context?: DataFindingContext;
+}
+
 export interface DataCheck {
   id: string;
   description: string;
   status: DataCheckStatus;
   details: string[];
+  /** Additive structured detail for consumers that should not parse prose. */
+  findings?: DataFinding[];
 }
 
 export interface DataReviewReport {
@@ -78,6 +96,39 @@ function summarize(checks: DataCheck[]): DataReviewReport {
   return { checks, summary };
 }
 
+/** Builds a structured check while retaining the established status/details contract. */
+export function createStructuredDataCheck(
+  id: string,
+  description: string,
+  statusWhenFound: "warning" | "fail",
+  findings: readonly DataFinding[],
+): DataCheck {
+  const capped = findings.length <= MAX_DETAILS ? [...findings] : [...findings.slice(0, MAX_DETAILS)];
+  const details = capped.map((finding) => finding.message);
+  if (findings.length > MAX_DETAILS) details.push(`+${findings.length - MAX_DETAILS} more`);
+  return {
+    id,
+    description,
+    status: findings.length > 0 ? statusWhenFound : "pass",
+    details,
+    findings: capped,
+  };
+}
+
+/** Public report summarizer for additive review suites. */
+export function summarizeDataChecks(checks: DataCheck[]): DataReviewReport {
+  return summarize(checks);
+}
+
+/** Public not-evaluated constructor so additive suites preserve report semantics. */
+export function createNotEvaluatedDataCheck(
+  id: string,
+  description: string,
+  reason: string,
+): DataCheck {
+  return notEvaluated(id, description, reason);
+}
+
 const CLAIM_DESCRIPTIONS = {
   "non-finite-value": "Every money field is a finite number (no NaN or Infinity)",
   "negative-paid": "Cumulative paid amounts are non-negative",
@@ -105,9 +156,9 @@ export function reviewClaimData(
     // Identified by claimId + evaluation date, which the DATA carries. The old
     // label fabricated "row N" from this array's index — but this function
     // receives parsed claims, not the file, and parseLossRunCsv numbers real
-    // CSV rows (header-inclusive) in its own errors. Two different "row"
-    // meanings pointed auditors at the wrong line; an identifier we cannot
-    // compute is one we must not print.
+    // physical file lines in its own errors. Two different "row" meanings
+    // pointed auditors at the wrong line; an identifier we cannot compute is
+    // one we must not print.
     const where = `claim ${c.claimId} (eval ${c.evaluationDate})`;
     if (c.paidToDate < 0) {
       negativePaid.push(`${where}: paid_to_date ${c.paidToDate}`);