@ggts-sh/spec 0.43.0

package/src/validate-data-checks-layer.ts

@@ -0,0 +1,492 @@
+/**
+ * Layer walk for tier-2 data checks: geom/stat field-type rules, field existence,
+ * all-null columns, {stat} columns, and channel collection for scale checkers.
+ *
+ * Orchestrator: validate-data-checks.ts (evidence resolve → walk → style/position/color).
+ * Scale checkers: validate-data-checks-{style,position,color}.ts.
+ */
+import type { SpecError } from "./errors.js";
+import { didYouMean } from "./errors.js";
+import type { Aes, ChannelName } from "./schema.js";
+import { CHANNELS, GEOM_DEFAULTS } from "./schema-catalog.js";
+import type { ProfileFieldType } from "./validate-data.js";
+import { effectiveChannel, type FieldEvidenceMap } from "./validate-data-evidence.js";
+import type { ChannelFieldUse } from "./validate-data-checks-temporal.js";
+
+/** Columns generated by each stat ({ stat } channel resolution contract).
+ *  Documented per stat in its @ggts-sh/core module header. */
+export const STAT_COLUMNS: Record<string, readonly string[]> = {
+  identity: [],
+  count: ["count"],
+  bin: ["count", "density", "ncount", "ndensity"],
+  bin_hex: ["count", "density", "ncount", "ndensity"],
+  bin_2d: ["count", "density", "ncount", "ndensity"],
+  density: ["density", "count", "scaled", "ndensity"],
+  ydensity: ["density", "count", "scaled", "violinwidth", "y"],
+  bindot: ["stackpos"],
+  smooth: ["y", "ymin", "ymax", "se"],
+  boxplot: ["ymin", "lower", "middle", "upper", "ymax"],
+  summary: ["y", "ymin", "ymax"],
+  /** after_stat n / prop for geom_count; not published on y (y is position input). */
+  sum: ["n", "prop"],
+  function: ["y"],
+  /** ggplot2 after_stat(ecdf); y channel defaults to this column. */
+  ecdf: ["ecdf"],
+  summary_bin: ["y", "ymin", "ymax"],
+  /** Centered rolling-window summary; one row per (group, unique x). */
+  summary_rolling: ["y"],
+  contour: ["level"],
+  quantile: ["y"],
+  density_2d: ["level", "density"],
+  density_2d_filled: ["level", "density"],
+  qq: ["sample", "theoretical"],
+  qq_line: ["sample", "theoretical"],
+};
+
+/**
+ * y-channel {stat} columns, mirroring core's STAT_Y_COLUMNS
+ * (packages/core/src/pipeline/bind-layer-stat-columns.ts — keep in sync). The
+ * generic STAT_COLUMNS table covers style channels; the y channel is stricter
+ * because summary-family stats write y as a frame coordinate (a measure
+ * output) and publish no y-mappable column. Validating against STAT_COLUMNS
+ * here let specs through that the renderer rejects with unknown-stat-column.
+ */
+const STAT_Y_CHANNEL_COLUMNS: Record<string, readonly string[]> = {
+  identity: [],
+  unique: [],
+  manual: [],
+  count: ["count"],
+  bin: ["count", "density", "ncount", "ndensity"],
+  density: ["density", "count", "scaled", "ndensity"],
+  ydensity: ["density", "count", "scaled", "violinwidth"],
+  density_2d: [],
+  density_2d_filled: [],
+  bindot: ["stackpos"],
+  smooth: [],
+  boxplot: [],
+  summary: [],
+  sum: [],
+  function: ["y"],
+  ecdf: ["ecdf"],
+  summary_bin: [],
+  summary_rolling: [],
+  contour: [],
+  connect: [],
+  align: [],
+  ellipse: [],
+  bin_hex: [],
+  bin_2d: [],
+  quantile: [],
+  sf: [],
+  sf_coordinates: [],
+  qq: [],
+  qq_line: [],
+};
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Channel maps + scaled constants collected while walking layers. */
+export interface LayerWalkCollections {
+  errors: SpecError[];
+  axisFields: Record<"x" | "y", ChannelFieldUse[]>;
+  colorFields: Record<"color" | "fill", ChannelFieldUse[]>;
+  colorScaledConstants: Record<"color" | "fill", unknown[]>;
+  finiteStyleFields: Record<"shape" | "linetype", ChannelFieldUse[]>;
+  numericStyleFields: Record<"size" | "linewidth" | "alpha", ChannelFieldUse[]>;
+  numericStyleScaledConstants: Record<"size" | "linewidth" | "alpha", unknown[]>;
+}
+
+/**
+ * Walk layers once: geom/stat type contracts, field existence / all-null / {stat}
+ * columns, then collect aesthetic uses for scale checkers.
+ */
+export function collectLayerDataChecks(input: {
+  layers: readonly unknown[];
+  plotAes: Aes | undefined;
+  plotFields: FieldEvidenceMap | null;
+  /** Per-layer evidence when resolveLayerFieldEvidence succeeded; else null. */
+  layerMaps: readonly (FieldEvidenceMap | null)[] | null;
+  scaleRequestsTime: (channel: ChannelName) => boolean;
+}): LayerWalkCollections {
+  const collections = emptyLayerWalkCollections();
+  for (let index = 0; index < input.layers.length; index++) {
+    collectLayerDataChecksForLayer(input, index, collections);
+  }
+  return collections;
+}
+
+type LayerWalkInput = Parameters<typeof collectLayerDataChecks>[0];
+type FieldTypeOf = (channel: ChannelName) => [string, ProfileFieldType] | null;
+type LayerTypeContext = {
+  geom: string;
+  stat: string;
+  index: number;
+  fieldTypeOf: FieldTypeOf;
+  scaleRequestsTime: (channel: ChannelName) => boolean;
+};
+
+function emptyLayerWalkCollections(): LayerWalkCollections {
+  return {
+    errors: [],
+    axisFields: { x: [], y: [] },
+    colorFields: { color: [], fill: [] },
+    colorScaledConstants: { color: [], fill: [] },
+    finiteStyleFields: { shape: [], linetype: [] },
+    numericStyleFields: { size: [], linewidth: [], alpha: [] },
+    numericStyleScaledConstants: { size: [], linewidth: [], alpha: [] },
+  };
+}
+
+function collectLayerDataChecksForLayer(
+  input: LayerWalkInput,
+  index: number,
+  collections: LayerWalkCollections,
+): void {
+  const layer = input.layers[index];
+  if (!isRecord(layer)) return;
+  const geom = typeof layer["geom"] === "string" ? layer["geom"] : "";
+  const layerAes = isRecord(layer["aes"]) ? (layer["aes"] as Aes) : undefined;
+  const defaultStat = GEOM_DEFAULTS[geom as keyof typeof GEOM_DEFAULTS]?.stat ?? "identity";
+  const stat = typeof layer["stat"] === "string" ? layer["stat"] : defaultStat;
+  const fields =
+    input.layerMaps === null ? input.plotFields : (input.layerMaps[index] ?? input.plotFields);
+  if (fields === null) return;
+  const fieldTypeOf = layerFieldTypeLookup(
+    input.plotAes,
+    layerAes,
+    fields,
+    input.scaleRequestsTime,
+  );
+  collections.errors.push(
+    ...geomFieldTypeErrors({
+      geom,
+      stat,
+      index,
+      fieldTypeOf,
+      scaleRequestsTime: input.scaleRequestsTime,
+    }),
+  );
+  collectLayerChannels({
+    plotAes: input.plotAes,
+    layerAes,
+    fields,
+    stat,
+    index,
+    collections,
+  });
+}
+
+function layerFieldTypeLookup(
+  plotAes: Aes | undefined,
+  layerAes: Aes | undefined,
+  fields: FieldEvidenceMap,
+  scaleRequestsTime: (channel: ChannelName) => boolean,
+): FieldTypeOf {
+  return (channel) => {
+    const mapped = effectiveChannel(plotAes, layerAes, channel);
+    if (mapped === undefined || !("field" in mapped)) return null;
+    const type = fields.get(mapped.field)?.type;
+    if (type === undefined || type === null) return null;
+    return [mapped.field, scaleRequestsTime(channel) ? "temporal" : type];
+  };
+}
+
+function geomFieldTypeErrors(context: LayerTypeContext): SpecError[] {
+  return [
+    ...smoothTypeErrors(context),
+    ...boxplotTypeErrors(context),
+    ...continuousStatTypeErrors(context),
+    ...intervalTypeErrors(context),
+    ...rectTypeErrors(context),
+    ...rasterTypeErrors(context),
+    ...tileTypeErrors(context),
+  ];
+}
+
+function channelTypeError(
+  index: number,
+  channel: ChannelName,
+  message: string,
+  description: string,
+): SpecError {
+  return {
+    code: "channel-type-mismatch",
+    path: `/layers/${index}/aes/${channel}`,
+    message,
+    fix: { description },
+  };
+}
+
+function isDiscreteType(type: ProfileFieldType): boolean {
+  return type === "nominal" || type === "ordinal";
+}
+
+function smoothTypeErrors(context: LayerTypeContext): SpecError[] {
+  if (context.geom !== "smooth") return [];
+  const errors: SpecError[] = [];
+  for (const channel of ["x", "y"] as const) {
+    const info = context.fieldTypeOf(channel);
+    if (info === null || !isDiscreteType(info[1])) continue;
+    errors.push(
+      channelTypeError(
+        context.index,
+        channel,
+        `The smooth stat needs quantitative x and y, but field "${info[0]}" (${channel}) is ${info[1]}.`,
+        "Map the channel to a numeric field, or use a boxplot for discrete x.",
+      ),
+    );
+  }
+  return errors;
+}
+
+function boxplotTypeErrors(context: LayerTypeContext): SpecError[] {
+  if (context.geom !== "boxplot") return [];
+  const errors: SpecError[] = [];
+  const x = context.fieldTypeOf("x");
+  if (x !== null && (x[1] === "quantitative" || x[1] === "temporal")) {
+    errors.push(
+      channelTypeError(
+        context.index,
+        "x",
+        `The boxplot geom needs a DISCRETE x this milestone, but field "${x[0]}" is ${x[1]}.`,
+        "Map x to a categorical field (strings), or bin the values into labeled categories first.",
+      ),
+    );
+  }
+  const y = context.fieldTypeOf("y");
+  if (y !== null && isDiscreteType(y[1])) {
+    errors.push(
+      channelTypeError(
+        context.index,
+        "y",
+        `The boxplot stat needs a quantitative y, but field "${y[0]}" is ${y[1]}.`,
+        "Map y to a numeric field.",
+      ),
+    );
+  }
+  return errors;
+}
+
+function continuousStatTypeErrors(context: LayerTypeContext): SpecError[] {
+  const { geom, stat } = context;
+  const continuous =
+    ["histogram", "freqpoly", "density"].includes(geom) ||
+    ((geom === "bar" || geom === "line") && stat === "bin");
+  if (!continuous) return [];
+  const x = context.fieldTypeOf("x");
+  if (x === null || !isDiscreteType(x[1])) return [];
+  return [
+    channelTypeError(
+      context.index,
+      "x",
+      `The ${geom === "density" ? "density" : "bin"} stat needs a continuous x, but field "${x[0]}" is ${x[1]}.`,
+      'Use geom "bar" (the count stat) to count categories instead.',
+    ),
+  ];
+}
+
+function intervalTypeErrors(context: LayerTypeContext): SpecError[] {
+  if (!["errorbar", "linerange", "pointrange", "crossbar"].includes(context.geom)) return [];
+  if (context.scaleRequestsTime("y")) return [];
+  const errors: SpecError[] = [];
+  for (const channel of ["ymin", "ymax"] as const) {
+    const info = context.fieldTypeOf(channel);
+    if (info === null || !isDiscreteType(info[1])) continue;
+    errors.push(
+      channelTypeError(
+        context.index,
+        channel,
+        `The ${context.geom} geom needs quantitative bounds, but field "${info[0]}" (${channel}) is ${info[1]}.`,
+        "Map the channel to a numeric field.",
+      ),
+    );
+  }
+  return errors;
+}
+
+function rectTypeErrors(context: LayerTypeContext): SpecError[] {
+  if (context.geom !== "rect") return [];
+  return [
+    ...rectAxisTypeErrors(context, "x", ["xmin", "xmax"]),
+    ...rectAxisTypeErrors(context, "y", ["ymin", "ymax"]),
+  ];
+}
+
+function rectAxisTypeErrors(
+  context: LayerTypeContext,
+  axis: "x" | "y",
+  channels: readonly ChannelName[],
+): SpecError[] {
+  if (context.scaleRequestsTime(axis)) return [];
+  const errors: SpecError[] = [];
+  for (const channel of channels) {
+    const info = context.fieldTypeOf(channel);
+    if (info === null || !isDiscreteType(info[1])) continue;
+    errors.push(
+      channelTypeError(
+        context.index,
+        channel,
+        `The rect geom needs quantitative edges, but field "${info[0]}" (${channel}) is ${info[1]}.`,
+        "Map the channel to a numeric field.",
+      ),
+    );
+  }
+  return errors;
+}
+
+function rasterTypeErrors(context: LayerTypeContext): SpecError[] {
+  if (context.geom !== "raster") return [];
+  const errors: SpecError[] = [];
+  for (const channel of ["x", "y"] as const) {
+    const info = context.fieldTypeOf(channel);
+    if (info === null || !isDiscreteType(info[1])) continue;
+    errors.push(
+      channelTypeError(
+        context.index,
+        channel,
+        `The raster geom needs continuous ${channel}, but field "${info[0]}" is ${info[1]}.`,
+        'Use geom "tile" for discrete axes.',
+      ),
+    );
+  }
+  return errors;
+}
+
+function tileTypeErrors(context: LayerTypeContext): SpecError[] {
+  if (context.geom !== "tile") return [];
+  const errors: SpecError[] = [];
+  for (const channel of ["width", "height"] as const) {
+    const info = context.fieldTypeOf(channel);
+    if (info === null || info[1] === "quantitative") continue;
+    errors.push(
+      channelTypeError(
+        context.index,
+        channel,
+        `The tile geom needs quantitative ${channel}, but field "${info[0]}" is ${info[1]}.`,
+        `Map ${channel} to a positive numeric field, or use params.${channel}.`,
+      ),
+    );
+  }
+  return errors;
+}
+
+function collectLayerChannels(input: {
+  plotAes: Aes | undefined;
+  layerAes: Aes | undefined;
+  fields: FieldEvidenceMap;
+  stat: string;
+  index: number;
+  collections: LayerWalkCollections;
+}): void {
+  const available = [...input.fields.keys()];
+  for (const channel of CHANNELS) {
+    const mapped = effectiveChannel(input.plotAes, input.layerAes, channel);
+    if (mapped === undefined) continue;
+    const path = `/layers/${input.index}/aes/${channel}`;
+    if ("stat" in mapped) {
+      const error = statColumnError(channel, mapped.stat, input.stat, path);
+      if (error !== null) input.collections.errors.push(error);
+    } else if ("value" in mapped) {
+      collectScaledConstant(input.collections, channel, mapped);
+    } else if ("field" in mapped) {
+      collectFieldChannel(input.collections, channel, mapped.field, path, input.fields, available);
+    }
+  }
+}
+
+function statColumnError(
+  channel: ChannelName,
+  statColumn: string,
+  stat: string,
+  path: string,
+): SpecError | null {
+  const generated = (channel === "y" ? STAT_Y_CHANNEL_COLUMNS[stat] : STAT_COLUMNS[stat]) ?? [];
+  if (generated.includes(statColumn)) return null;
+  return {
+    code: "unknown-stat-column",
+    path,
+    message:
+      generated.length === 0
+        ? `Channel "${channel}" maps stat column "${statColumn}", but this layer's stat ("${stat}") generates no columns.`
+        : `Channel "${channel}" maps stat column "${statColumn}", but this layer's stat ("${stat}") generates: ${generated.join(", ")}.`,
+    ...(generated.length > 0 && { allowed: [...generated] }),
+  };
+}
+
+function collectScaledConstant(
+  collections: LayerWalkCollections,
+  channel: ChannelName,
+  mapped: { value: unknown; scale?: boolean },
+): void {
+  if (mapped.scale !== true || mapped.value === null) return;
+  if (channel === "color" || channel === "fill") {
+    collections.colorScaledConstants[channel].push(mapped.value);
+  }
+  if (channel === "size" || channel === "linewidth" || channel === "alpha") {
+    collections.numericStyleScaledConstants[channel].push(mapped.value);
+  }
+}
+
+function collectFieldChannel(
+  collections: LayerWalkCollections,
+  channel: ChannelName,
+  field: string,
+  path: string,
+  fields: FieldEvidenceMap,
+  available: string[],
+): void {
+  const info = fields.get(field);
+  if (info === undefined) {
+    collections.errors.push(unknownFieldError(channel, field, path, available));
+    return;
+  }
+  if (info.allNull) {
+    collections.errors.push({
+      code: "all-null-column",
+      path,
+      message: `Field "${field}" contains only null values; the "${channel}" channel cannot be drawn from it.`,
+    });
+    return;
+  }
+  collectFieldUse(collections, channel, { field, path });
+}
+
+function unknownFieldError(
+  channel: ChannelName,
+  field: string,
+  path: string,
+  available: string[],
+): SpecError {
+  const suggestion = didYouMean(field, available);
+  return {
+    code: "unknown-field",
+    path,
+    message:
+      `Unknown field "${field}" (available: ${available.join(", ") || "none"}).` +
+      (suggestion === undefined ? "" : ` Did you mean "${suggestion}"?`),
+    allowed: available,
+    ...(suggestion !== undefined && {
+      fix: {
+        description: `Map "${channel}" to "${suggestion}".`,
+        example: { field: suggestion },
+      },
+    }),
+  };
+}
+
+function collectFieldUse(
+  collections: LayerWalkCollections,
+  channel: ChannelName,
+  use: ChannelFieldUse,
+): void {
+  if (["x", "xmin", "xmax", "xend"].includes(channel)) collections.axisFields.x.push(use);
+  if (["y", "ymin", "ymax", "yend"].includes(channel)) collections.axisFields.y.push(use);
+  if (channel === "color" || channel === "fill") collections.colorFields[channel].push(use);
+  if (channel === "shape" || channel === "linetype")
+    collections.finiteStyleFields[channel].push(use);
+  if (channel === "size" || channel === "linewidth" || channel === "alpha") {
+    collections.numericStyleFields[channel].push(use);
+  }
+}