@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

package/src/validation/validateDatasource.ts

@@ -1,174 +1,174 @@
-/**
- * Datasource validation (FR-015, FR-017, FR-007a).
- *
- * Rules V1-V8 from specs/007-rn-chart-package/data-model.md §6. Every failure
- * returns a `ChartError` built from the fixed message catalogue, so validation
- * output can never carry a data value or a series label.
- *
- * Note V8: an empty datasource is **not** an error. It resolves to the empty
- * state, which is a first-class outcome rather than a failure.
- */
-import {
-	familyAcceptsPositionKind,
-	type ChartDatasource,
-	type ChartFamily,
-} from '../contract/datasource';
-import { validationError, type ChartError } from '../contract/errors';
-import { isKnown } from '../contract/value';
-
-export interface ValidationResult {
-	readonly error?: ChartError;
-	/** No points at all across every series (V8). */
-	readonly isEmpty: boolean;
-	/** Some points are known and others are not (FR-032). */
-	readonly isPartial: boolean;
-	/** Distribution segments that do not sum to the whole (V6, FR-024). */
-	readonly totalIncomplete: boolean;
-}
-
-const DISTRIBUTION_SUM_TOLERANCE = 0.001;
-
-export function validateDatasource<M>(
-	datasource: ChartDatasource<M>,
-	family: ChartFamily,
-	chartId?: string,
-): ValidationResult {
-	const base = { isEmpty: true, isPartial: false, totalIncomplete: false };
-
-	// V4 — the receiving family must accept the declared position kind. Checked
-	// first because a mismatch here makes everything downstream meaningless.
-	if (!familyAcceptsPositionKind(family, datasource.positionKind)) {
-		return {
-			...base,
-			isEmpty: false,
-			error: validationError('familyPositionKindUnsupported', {
-				chartId,
-				family,
-				detail: { actualKind: datasource.positionKind },
-			}),
-		};
-	}
-
-	// V1 — series ids unique.
-	const seenSeriesIds = new Set<string>();
-	for (const series of datasource.series) {
-		if (seenSeriesIds.has(series.id)) {
-			return {
-				...base,
-				isEmpty: false,
-				error: validationError('duplicateSeriesId', {
-					chartId,
-					family,
-					detail: { occurrences: seenSeriesIds.size },
-				}),
-			};
-		}
-		seenSeriesIds.add(series.id);
-	}
-
-	let totalPoints = 0;
-	let knownPoints = 0;
-	const matrixRows = new Set<string>();
-	const matrixColumns = new Set<string>();
-
-	for (const series of datasource.series) {
-		// V2 — point ids unique within their series.
-		const seenPointIds = new Set<string>();
-
-		for (const point of series.points) {
-			if (seenPointIds.has(point.id)) {
-				return {
-					...base,
-					isEmpty: false,
-					error: validationError('duplicatePointId', {
-						chartId,
-						family,
-						detail: { occurrences: seenPointIds.size },
-					}),
-				};
-			}
-			seenPointIds.add(point.id);
-
-			// V3 — every point matches the declared position kind.
-			if (point.position.kind !== datasource.positionKind) {
-				return {
-					...base,
-					isEmpty: false,
-					error: validationError('positionKindMismatch', {
-						chartId,
-						family,
-						detail: {
-							expectedKind: datasource.positionKind,
-							actualKind: point.position.kind,
-						},
-					}),
-				};
-			}
-
-			if (point.position.kind === 'matrix') {
-				matrixRows.add(point.position.row);
-				matrixColumns.add(point.position.column);
-			}
-
-			totalPoints += 1;
-			if (isKnown(point.value)) {
-				knownPoints += 1;
-			}
-		}
-	}
-
-	// V5 — a matrix must be rectangular: every row/column pair accounted for.
-	if (datasource.positionKind === 'matrix' && totalPoints > 0) {
-		const expected = matrixRows.size * matrixColumns.size;
-		if (totalPoints !== expected) {
-			return {
-				...base,
-				isEmpty: false,
-				error: validationError('inconsistentMatrix', {
-					chartId,
-					family,
-					detail: { occurrences: Math.abs(expected - totalPoints) },
-				}),
-			};
-		}
-	}
-
-	// V6 — distribution segments that do not sum to the whole are flagged, never
-	// rescaled. This is a flag rather than a rejection: the chart still renders
-	// and marks the total incomplete.
-	let totalIncomplete = knownPoints < totalPoints;
-	if (family === 'distribution' && totalPoints > 0) {
-		totalIncomplete = totalIncomplete || !distributionSumsToWhole(datasource);
-	}
-
-	return {
-		isEmpty: totalPoints === 0,
-		isPartial: totalPoints > 0 && knownPoints > 0 && knownPoints < totalPoints,
-		totalIncomplete,
-	};
-}
-
-/**
- * Distribution values may be supplied either as proportions summing to 1 or as
- * absolute values that the chart normalises for display. Only the proportion
- * case can be checked for wholeness, and only when every point is known.
- */
-function distributionSumsToWhole<M>(datasource: ChartDatasource<M>): boolean {
-	const values: number[] = [];
-	for (const series of datasource.series) {
-		for (const point of series.points) {
-			if (!isKnown(point.value)) {
-				return false;
-			}
-			values.push(point.value.value);
-		}
-	}
-
-	const sum = values.reduce((acc, n) => acc + n, 0);
-	const looksLikeProportions = values.every(v => v >= 0 && v <= 1);
-	if (!looksLikeProportions) {
-		// Absolute values: any positive sum is a whole by definition.
-		return sum > 0;
-	}
-	return Math.abs(sum - 1) <= DISTRIBUTION_SUM_TOLERANCE;
-}
+/**
+ * Datasource validation (FR-015, FR-017, FR-007a).
+ *
+ * Rules V1-V8 from specs/007-rn-chart-package/data-model.md §6. Every failure
+ * returns a `ChartError` built from the fixed message catalogue, so validation
+ * output can never carry a data value or a series label.
+ *
+ * Note V8: an empty datasource is **not** an error. It resolves to the empty
+ * state, which is a first-class outcome rather than a failure.
+ */
+import {
+	familyAcceptsPositionKind,
+	type ChartDatasource,
+	type ChartFamily,
+} from '../contract/datasource';
+import { validationError, type ChartError } from '../contract/errors';
+import { isKnown } from '../contract/value';
+
+export interface ValidationResult {
+	readonly error?: ChartError;
+	/** No points at all across every series (V8). */
+	readonly isEmpty: boolean;
+	/** Some points are known and others are not (FR-032). */
+	readonly isPartial: boolean;
+	/** Distribution segments that do not sum to the whole (V6, FR-024). */
+	readonly totalIncomplete: boolean;
+}
+
+const DISTRIBUTION_SUM_TOLERANCE = 0.001;
+
+export function validateDatasource<M>(
+	datasource: ChartDatasource<M>,
+	family: ChartFamily,
+	chartId?: string,
+): ValidationResult {
+	const base = { isEmpty: true, isPartial: false, totalIncomplete: false };
+
+	// V4 — the receiving family must accept the declared position kind. Checked
+	// first because a mismatch here makes everything downstream meaningless.
+	if (!familyAcceptsPositionKind(family, datasource.positionKind)) {
+		return {
+			...base,
+			isEmpty: false,
+			error: validationError('familyPositionKindUnsupported', {
+				chartId,
+				family,
+				detail: { actualKind: datasource.positionKind },
+			}),
+		};
+	}
+
+	// V1 — series ids unique.
+	const seenSeriesIds = new Set<string>();
+	for (const series of datasource.series) {
+		if (seenSeriesIds.has(series.id)) {
+			return {
+				...base,
+				isEmpty: false,
+				error: validationError('duplicateSeriesId', {
+					chartId,
+					family,
+					detail: { occurrences: seenSeriesIds.size },
+				}),
+			};
+		}
+		seenSeriesIds.add(series.id);
+	}
+
+	let totalPoints = 0;
+	let knownPoints = 0;
+	const matrixRows = new Set<string>();
+	const matrixColumns = new Set<string>();
+
+	for (const series of datasource.series) {
+		// V2 — point ids unique within their series.
+		const seenPointIds = new Set<string>();
+
+		for (const point of series.points) {
+			if (seenPointIds.has(point.id)) {
+				return {
+					...base,
+					isEmpty: false,
+					error: validationError('duplicatePointId', {
+						chartId,
+						family,
+						detail: { occurrences: seenPointIds.size },
+					}),
+				};
+			}
+			seenPointIds.add(point.id);
+
+			// V3 — every point matches the declared position kind.
+			if (point.position.kind !== datasource.positionKind) {
+				return {
+					...base,
+					isEmpty: false,
+					error: validationError('positionKindMismatch', {
+						chartId,
+						family,
+						detail: {
+							expectedKind: datasource.positionKind,
+							actualKind: point.position.kind,
+						},
+					}),
+				};
+			}
+
+			if (point.position.kind === 'matrix') {
+				matrixRows.add(point.position.row);
+				matrixColumns.add(point.position.column);
+			}
+
+			totalPoints += 1;
+			if (isKnown(point.value)) {
+				knownPoints += 1;
+			}
+		}
+	}
+
+	// V5 — a matrix must be rectangular: every row/column pair accounted for.
+	if (datasource.positionKind === 'matrix' && totalPoints > 0) {
+		const expected = matrixRows.size * matrixColumns.size;
+		if (totalPoints !== expected) {
+			return {
+				...base,
+				isEmpty: false,
+				error: validationError('inconsistentMatrix', {
+					chartId,
+					family,
+					detail: { occurrences: Math.abs(expected - totalPoints) },
+				}),
+			};
+		}
+	}
+
+	// V6 — distribution segments that do not sum to the whole are flagged, never
+	// rescaled. This is a flag rather than a rejection: the chart still renders
+	// and marks the total incomplete.
+	let totalIncomplete = knownPoints < totalPoints;
+	if (family === 'distribution' && totalPoints > 0) {
+		totalIncomplete = totalIncomplete || !distributionSumsToWhole(datasource);
+	}
+
+	return {
+		isEmpty: totalPoints === 0,
+		isPartial: totalPoints > 0 && knownPoints > 0 && knownPoints < totalPoints,
+		totalIncomplete,
+	};
+}
+
+/**
+ * Distribution values may be supplied either as proportions summing to 1 or as
+ * absolute values that the chart normalises for display. Only the proportion
+ * case can be checked for wholeness, and only when every point is known.
+ */
+function distributionSumsToWhole<M>(datasource: ChartDatasource<M>): boolean {
+	const values: number[] = [];
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			if (!isKnown(point.value)) {
+				return false;
+			}
+			values.push(point.value.value);
+		}
+	}
+
+	const sum = values.reduce((acc, n) => acc + n, 0);
+	const looksLikeProportions = values.every(v => v >= 0 && v <= 1);
+	if (!looksLikeProportions) {
+		// Absolute values: any positive sum is a whole by definition.
+		return sum > 0;
+	}
+	return Math.abs(sum - 1) <= DISTRIBUTION_SUM_TOLERANCE;
+}