Add drift-guard test for VertexSymbol visual field coverage

Fails when a field is added to VertexVisualStyle but not consumed by
the preview or explicitly excluded with justification. Compile-time
exhaustiveness via a satisfies check on a Record, runtime via test.

Author: kmcginnes

packages/graph-explorer/src/components/VertexSymbol/visualFields.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  ALL_VISUAL_FIELDS,
+  CONSUMED_VISUAL_FIELDS,
+  EXCLUDED_VISUAL_FIELDS,
+} from "./visualFields";
+
+/**
+ * Drift guard — fails when a visual field is added to VertexVisualStyle but
+ * neither consumed by VertexSymbol nor explicitly excluded with justification.
+ *
+ * The source of truth for "all visual fields" is ALL_VISUAL_FIELDS, which is
+ * compile-time checked against `keyof VertexVisualStyle` via `satisfies`.
+ */
+describe("VertexSymbol visual field coverage", () => {
+  const allVisualFields = new Set<string>(ALL_VISUAL_FIELDS);
+
+  it("CONSUMED ∪ EXCLUDED exhausts all visual fields", () => {
+    const covered = new Set<string>([
+      ...CONSUMED_VISUAL_FIELDS,
+      ...EXCLUDED_VISUAL_FIELDS,
+    ]);
+    const uncovered = [...allVisualFields].filter(f => !covered.has(f));
+    expect(uncovered).toEqual([]);
+  });
+
+  it("CONSUMED and EXCLUDED do not overlap", () => {
+    const overlap = [...CONSUMED_VISUAL_FIELDS].filter(f =>
+      EXCLUDED_VISUAL_FIELDS.has(f),
+    );
+    expect(overlap).toHaveLength(0);
+  });
+
+  it("no phantom entries that aren't real visual fields", () => {
+    const phantoms = [
+      ...[...CONSUMED_VISUAL_FIELDS].filter(f => !allVisualFields.has(f)),
+      ...[...EXCLUDED_VISUAL_FIELDS].filter(f => !allVisualFields.has(f)),
+    ];
+    expect(phantoms).toHaveLength(0);
+  });
+});

packages/graph-explorer/src/components/VertexSymbol/visualFields.ts

@@ -0,0 +1,50 @@
+import type { VertexVisualStyle } from "@/core/StateProvider/graphStyles";
+
+/**
+ * Compile-time proof that every key of `VertexVisualStyle` is listed. If a key
+ * is added to the type but missing here, TypeScript reports it on the
+ * `satisfies` line.
+ */
+type ExhaustiveKeys = Record<keyof VertexVisualStyle, true>;
+const ALL_VISUAL_FIELDS_RECORD = {
+  color: true,
+  iconUrl: true,
+  iconImageType: true,
+  shape: true,
+  backgroundOpacity: true,
+  borderWidth: true,
+  borderColor: true,
+  borderStyle: true,
+} as const satisfies ExhaustiveKeys;
+
+export const ALL_VISUAL_FIELDS = Object.keys(
+  ALL_VISUAL_FIELDS_RECORD,
+) as (keyof VertexVisualStyle)[];
+
+/**
+ * Visual fields that VertexSymbol renders. Typed as `keyof VertexVisualStyle`
+ * so adding a field to the type without listing it here is a compile error in
+ * the drift-guard test (which asserts this set + the excluded set exhausts
+ * the type's keys).
+ */
+export const CONSUMED_VISUAL_FIELDS: ReadonlySet<keyof VertexVisualStyle> =
+  new Set([
+    "color",
+    "iconUrl",
+    "iconImageType",
+    "shape",
+    "backgroundOpacity",
+    "borderWidth",
+    "borderColor",
+    "borderStyle",
+  ]);
+
+/**
+ * Visual fields intentionally not rendered by the preview. Each entry must have
+ * a justification comment here — the drift-guard test asserts
+ * `CONSUMED ∪ EXCLUDED = all keys of VertexVisualStyle`.
+ */
+export const EXCLUDED_VISUAL_FIELDS: ReadonlySet<keyof VertexVisualStyle> =
+  new Set([
+    // None currently excluded — all visual fields are rendered.
+  ]);