refactor: tighten netcheck types, share webview CSS, add SDK drift guard

- Split shared netcheck into types.ts / api.ts (Api only) / utils.ts, trim the
  exported surface, and document provenance.
- Add a compile-time drift guard: the parser fails to build if the coder SDK
  renames or removes a field it reads.
- Extract shared base styles into @repo/webview-shared/base.css, consumed by
  both vanilla webviews; each index.css keeps only page-specific rules.
- Simplify connectivity (keyed cases, no nested ternary) and regions
  (map -> toSorted pipeline); render missing IPv4 as a warning, not an error.
- Move the large parser payloads into golden fixtures/ JSON files.

Author: EhabY

packages/netcheck/src/connectivity.ts

@@ -23,23 +23,27 @@ export function buildConnectivityItems(
 	}
 
 	// Tones: bad = real problem, warn = works but suboptimal, neutral = optional.
-	// So a missing optional capability stays neutral, but blocked UDP is bad.
 	const items: ConnectivityItem[] = [
-		boolItem("UDP", probe.UDP, ["Reachable", "good"], ["Blocked", "bad"]),
-		boolItem("IPv4", probe.IPv4, ["Yes", "good"], ["No", "bad"]),
-		boolItem("IPv6", probe.IPv6, ["Yes", "good"], ["No", "neutral"]),
-		boolItem(
-			"NAT mapping",
-			probe.MappingVariesByDestIP,
-			["Varies by destination (hard NAT)", "warn"],
-			["Consistent (easy NAT)", "good"],
-		),
-		boolItem(
-			"Hairpinning",
-			probe.HairPinning,
-			["Supported", "good"],
-			["Not supported", "neutral"],
-		),
+		boolItem("UDP", probe.UDP, {
+			true: ["Reachable", "good"],
+			false: ["Blocked", "bad"],
+		}),
+		boolItem("IPv4", probe.IPv4, {
+			true: ["Yes", "good"],
+			false: ["No", "warn"],
+		}),
+		boolItem("IPv6", probe.IPv6, {
+			true: ["Yes", "good"],
+			false: ["No", "neutral"],
+		}),
+		boolItem("NAT mapping", probe.MappingVariesByDestIP, {
+			true: ["Varies by destination (hard NAT)", "warn"],
+			false: ["Consistent (easy NAT)", "good"],
+		}),
+		boolItem("Hairpinning", probe.HairPinning, {
+			true: ["Supported", "good"],
+			false: ["Not supported", "neutral"],
+		}),
 		portMappingItem(probe),
 	];
 
@@ -50,19 +54,16 @@ export function buildConnectivityItems(
 	return items;
 }
 
-/** Picks the true/false outcome; null/undefined render as a neutral "Unknown". */
+/** Renders a boolean probe field; a missing value is a neutral "Unknown". */
 function boolItem(
 	label: string,
 	state: boolean | null | undefined,
-	ifTrue: Outcome,
-	ifFalse: Outcome,
+	cases: { true: Outcome; false: Outcome },
 ): ConnectivityItem {
-	const [value, tone]: Outcome =
-		state === true
-			? ifTrue
-			: state === false
-				? ifFalse
-				: ["Unknown", "neutral"];
+	if (typeof state !== "boolean") {
+		return { label, value: "Unknown", tone: "neutral" };
+	}
+	const [value, tone] = state ? cases.true : cases.false;
 	return { label, value, tone };
 }
 

packages/netcheck/src/health.ts

@@ -10,31 +10,31 @@ export interface Issue {
 	message: string;
 }
 
-const SEVERITY_LABEL: Readonly<Record<NetcheckSeverity, string>> = {
+const SEVERITY_LABEL = {
 	ok: "Healthy",
 	warning: "Warning",
 	error: "Error",
-};
+} as const satisfies Record<NetcheckSeverity, string>;
 
-export function severityLabel(severity: NetcheckSeverity): string {
-	return SEVERITY_LABEL[severity];
-}
-
-const BANNER_TITLE: Readonly<Record<NetcheckSeverity, string>> = {
+const BANNER_TITLE = {
 	ok: "Network is healthy",
 	warning: "Network has warnings",
 	error: "Network problems detected",
-};
-
-export function bannerTitle(severity: NetcheckSeverity): string {
-	return BANNER_TITLE[severity];
-}
+} as const satisfies Record<NetcheckSeverity, string>;
 
-const SECTION_STATUS: Readonly<Record<NetcheckSeverity, string>> = {
+const SECTION_STATUS = {
 	ok: "healthy",
 	warning: "warning",
 	error: "error",
-};
+} as const satisfies Record<NetcheckSeverity, string>;
+
+export function severityLabel(severity: NetcheckSeverity): string {
+	return SEVERITY_LABEL[severity];
+}
+
+export function bannerTitle(severity: NetcheckSeverity): string {
+	return BANNER_TITLE[severity];
+}
 
 /** One-line status for a report section, e.g. "2 warnings" or "healthy". */
 export function sectionSummary(section: NetcheckSectionHealth): string {

packages/netcheck/src/index.css

@@ -1,8 +1,4 @@
-*,
-*::before,
-*::after {
-	box-sizing: border-box;
-}
+/* Base reset, body, and button styles come from @repo/webview-shared/base.css. */
 
 /* Local aliases composed from VS Code theme tokens so every theme (light,
  * dark, high contrast) renders consistently. */
@@ -15,15 +11,6 @@
 	--card-bg: var(--vscode-editorWidget-background, transparent);
 }
 
-body {
-	margin: 0;
-	padding: 1.5em;
-	background: var(--vscode-editor-background);
-	color: var(--vscode-foreground, var(--vscode-editor-foreground));
-	font-family: var(--vscode-font-family);
-	font-size: var(--vscode-font-size);
-}
-
 #root {
 	max-width: 56em;
 	margin: 0 auto;
@@ -286,39 +273,14 @@ body {
 }
 
 .actions {
-	display: flex;
-	justify-content: center;
 	margin-top: 1.5em;
 }
 
-button {
-	padding: 0.4em 1em;
-	border: 1px solid var(--vscode-button-border, transparent);
-	border-radius: 2px;
-	background: var(--vscode-button-secondaryBackground);
-	color: var(--vscode-button-secondaryForeground);
-	font: inherit;
-	cursor: pointer;
-}
-
-button:hover {
-	background: var(--vscode-button-secondaryHoverBackground);
-}
-
-button:focus-visible {
-	outline: 1px solid var(--vscode-focusBorder);
-	outline-offset: 2px;
-}
-
 .error,
 .empty {
 	margin: 0.5em 0;
 }
 
-.error {
-	color: var(--vscode-errorForeground);
-}
-
 .empty {
 	color: var(--muted);
 }
@@ -339,8 +301,4 @@ button:focus-visible {
 	.section-body {
 		padding: 0.75em;
 	}
-
-	.section-body-flush {
-		padding: 0;
-	}
 }

packages/netcheck/src/index.ts

@@ -1,12 +1,13 @@
 import { NetcheckApi, toError, type NetcheckData } from "@repo/shared";
 import { sendCommand, subscribeNotifications } from "@repo/webview-shared";
+import "@repo/webview-shared/base.css";
 
 import "./index.css";
 import { renderError, renderPage } from "./page";
 
 function main(): void {
-	// The extension re-sends `data` on visibility/theme changes, so each render
-	// replaces the whole root, clearing any prior error or report.
+	// The extension re-sends `data` on visibility/theme changes; each render
+	// replaces the root, clearing any prior error.
 	subscribeNotifications(NetcheckApi, {
 		data: (data) => render(data),
 	});

packages/netcheck/src/regions.ts

@@ -26,25 +26,35 @@ export function regionName(
 
 /** Rows for the regions table: preferred first, then by latency, then name. */
 export function buildRegionRows(report: NetcheckReport): RegionRow[] {
-	const latencies = report.derp.netcheck?.RegionLatency ?? {};
-	const preferredId = report.derp.netcheck?.PreferredDERP;
-	const rows = Object.entries(report.derp.regions).map(([key, region]) => {
-		const id = Number(key);
-		const nodes = region.node_reports;
-		const stunNodes = nodes.filter((n) => n.stun.Enabled);
-		const relayNodes = nodes.filter((n) => !(n.node?.STUNOnly ?? false));
-		return {
-			name: regionName(region, id),
-			severity: region.severity,
-			latencyMs: regionLatencyMs(latencies[key], relayNodes),
-			preferred: id === preferredId,
-			embeddedRelay: region.region?.EmbeddedRelay ?? false,
-			stun: anyTriState(stunNodes, (n) => n.stun.CanSTUN),
-			relay: anyTriState(relayNodes, (n) => n.can_exchange_messages),
-			error: region.error ?? undefined,
-		};
-	});
-	return rows.sort(compareRegionRows);
+	const probe = report.derp.netcheck;
+	return Object.entries(report.derp.regions)
+		.map(([key, region]) =>
+			toRegionRow(region, Number(key), probe?.PreferredDERP, probe?.RegionLatency[key]),
+		)
+		.toSorted(compareRegionRows);
+}
+
+function toRegionRow(
+	region: NetcheckRegionReport,
+	id: number,
+	preferredId: number | undefined,
+	latencyNanos: number | undefined,
+): RegionRow {
+	// STUN and relay capability come from different node sets.
+	const relayNodes = region.node_reports.filter(
+		(n) => !(n.node?.STUNOnly ?? false),
+	);
+	const stunNodes = region.node_reports.filter((n) => n.stun.Enabled);
+	return {
+		name: regionName(region, id),
+		severity: region.severity,
+		latencyMs: regionLatencyMs(latencyNanos, relayNodes),
+		preferred: id === preferredId,
+		embeddedRelay: region.region?.EmbeddedRelay ?? false,
+		stun: anyTriState(stunNodes, (n) => n.stun.CanSTUN),
+		relay: anyTriState(relayNodes, (n) => n.can_exchange_messages),
+		error: region.error ?? undefined,
+	};
 }
 
 function regionLatencyMs(

packages/shared/src/index.ts

@@ -18,19 +18,17 @@ export {
 } from "./speedtest/api";
 
 // Netcheck API
-export {
-	NetcheckApi,
-	overallNetcheckSeverity,
-	type NetcheckConnectivity,
-	type NetcheckData,
-	type NetcheckHealthMessage,
-	type NetcheckInterface,
-	type NetcheckNodeReport,
-	type NetcheckRegionReport,
-	type NetcheckReport,
-	type NetcheckSectionHealth,
-	type NetcheckSeverity,
-} from "./netcheck/api";
+export { NetcheckApi } from "./netcheck/api";
+export { overallNetcheckSeverity } from "./netcheck/utils";
+export type {
+	NetcheckConnectivity,
+	NetcheckData,
+	NetcheckInterface,
+	NetcheckRegionReport,
+	NetcheckReport,
+	NetcheckSectionHealth,
+	NetcheckSeverity,
+} from "./netcheck/types";
 
 // Workspaces API
 export { WorkspacesApi } from "./workspaces/api";

packages/shared/src/netcheck/api.ts

@@ -1,95 +1,6 @@
 import { defineCommand, defineNotification } from "../ipc/protocol";
 
-export type NetcheckSeverity = "ok" | "warning" | "error";
-
-export interface NetcheckHealthMessage {
-	code: string;
-	message: string;
-}
-
-/** Health fields shared by the DERP and interfaces sections of the report. */
-export interface NetcheckSectionHealth {
-	severity: NetcheckSeverity;
-	warnings: NetcheckHealthMessage[];
-	error?: string | null;
-}
-
-export interface NetcheckNodeReport {
-	can_exchange_messages: boolean;
-	round_trip_ping_ms: number;
-	/** Field names match the CLI's Go JSON output, which has no tags here. */
-	stun: { Enabled: boolean; CanSTUN: boolean };
-	/** Field names match tailscale's DERP map JSON. */
-	node?: { STUNOnly?: boolean | null } | null;
-}
-
-export interface NetcheckRegionReport {
-	severity: NetcheckSeverity;
-	error?: string | null;
-	/** Field names match tailscale's DERP map JSON. */
-	region?: {
-		RegionID: number;
-		RegionName: string;
-		EmbeddedRelay: boolean;
-	} | null;
-	node_reports: NetcheckNodeReport[];
-}
-
-/** Subset of tailscale's netcheck report; field names match its JSON output. */
-export interface NetcheckConnectivity {
-	UDP: boolean;
-	IPv4: boolean;
-	IPv6: boolean;
-	MappingVariesByDestIP?: boolean | null;
-	HairPinning?: boolean | null;
-	UPnP?: boolean | null;
-	PMP?: boolean | null;
-	PCP?: boolean | null;
-	/** Region ID of the preferred DERP region; 0 when undetermined. */
-	PreferredDERP: number;
-	/** Latency per DERP region ID, in nanoseconds. */
-	RegionLatency: Record<string, number>;
-}
-
-export interface NetcheckInterface {
-	name: string;
-	mtu: number;
-	addresses: string[];
-}
-
-/** Subset of the CLI's ClientNetcheckReport that the extension renders. */
-export interface NetcheckReport {
-	derp: NetcheckSectionHealth & {
-		regions: Record<string, NetcheckRegionReport>;
-		netcheck?: NetcheckConnectivity | null;
-		netcheck_err?: string | null;
-	};
-	interfaces: NetcheckSectionHealth & {
-		interfaces: NetcheckInterface[];
-	};
-}
-
-export interface NetcheckData {
-	/** Hostname of the deployment the report was generated against. */
-	host: string;
-	report: NetcheckReport;
-}
-
-const SEVERITY_RANK: Record<NetcheckSeverity, number> = {
-	ok: 0,
-	warning: 1,
-	error: 2,
-};
-
-/** Worst severity across the DERP and interfaces sections. */
-export function overallNetcheckSeverity(
-	report: NetcheckReport,
-): NetcheckSeverity {
-	const { derp, interfaces } = report;
-	return SEVERITY_RANK[derp.severity] >= SEVERITY_RANK[interfaces.severity]
-		? derp.severity
-		: interfaces.severity;
-}
+import type { NetcheckData } from "./types";
 
 export const NetcheckApi = {
 	/** Extension pushes the parsed report to the webview */