@skyhook-io/k8s-ui 1.14.5 → 1.14.7

package/src/types/gitops-insights.ts

@@ -13,6 +13,7 @@ export interface GitOpsInsight {
 }
 
 import type { GitOpsTool } from './gitops'
+import type { GitOpsHealthMode, GitOpsHealthSource } from './gitops-tree'
 
 // Closed enums mirroring `pkg/gitops/insights/vocab.go`. Keeping the FE
 // vocabulary in lockstep with the Go side means switches over these fields
@@ -79,6 +80,19 @@ export interface GitOpsInsightSummary {
   // (jqPathExpressions / managedFieldsManagers rules) — the
   // drift panel may surface fields Argo's own UI suppresses.
   ignoredDifferences?: GitOpsIgnoredDifferences
+  // Argo roots: where Argo keeps per-resource health. 'appTree' means the
+  // controller's verdicts are not in the Application object and any
+  // per-resource health shown is Radar's own read.
+  resourceHealthMode?: GitOpsHealthMode
+  // The Application deploys to another cluster; Radar derives nothing about
+  // its resources from here.
+  remoteDestination?: boolean
+  // Per-resource health came from Argo CD's API server: the verdicts shown
+  // are Argo's even though the Application object doesn't carry them.
+  resourceHealthFromApi?: boolean
+  // The controller's API server was asked and didn't answer usefully — why,
+  // in the user's words. Only set when the integration is configured.
+  resourceHealthApiError?: string
 }
 
 export interface GitOpsIgnoredDifferences {
@@ -116,6 +130,10 @@ export interface GitOpsIssue {
   // a contextual action button. Nil when no automated remedy applies — the
   // `action` string still describes the manual path in that case.
   remediation?: GitOpsRemediation
+  // Set on resource-scoped issues: 'controller' when the GitOps controller's
+  // own per-resource health produced it, 'radar' when Radar's issues engine
+  // did because the controller's verdict wasn't available.
+  source?: GitOpsHealthSource
 }
 
 export type GitOpsRemediationKind = 'create-namespace'
@@ -131,6 +149,11 @@ export interface GitOpsChange {
   category: GitOpsCategory
   sync?: string
   health?: string
+  // Provenance of `health`; see GitOpsTreeNode.healthSource. `message` holds
+  // the health message from whichever source produced `health`.
+  healthSource?: GitOpsHealthSource
+  healthReason?: string
+  healthSeverity?: string
   message?: string
   // Per-resource sync failure message (Argo's status.resources[].syncResult).
   // Distinct from `message` (live health). Empty when sync succeeded.

package/src/types/gitops-tree.ts

@@ -24,6 +24,16 @@ export interface GitOpsTreeNode {
   tool: GitOpsTreeTool
   sync?: SyncStatus
   health?: GitOpsHealthStatus
+  // Who assessed `health`. 'controller' is the GitOps controller's own
+  // verdict; 'radar' is Radar's read of the live object (topology status, or
+  // the issues engine's finding when the controller's verdict isn't
+  // available). The UI labels 'radar' values so they never pass as the
+  // controller's. Absent when `health` is absent. Kept open for sources a
+  // newer backend may add — unknown values render without a label.
+  healthSource?: GitOpsHealthSource
+  healthReason?: string
+  healthMessage?: string
+  healthSeverity?: 'critical' | 'warning' | (string & {})
   topologyStatus?: HealthStatus
   info?: GitOpsTreeInfoItem[]
   resource?: unknown
@@ -32,6 +42,16 @@ export interface GitOpsTreeNode {
   data?: Record<string, unknown>
 }
 
+// 'controllerApi' is the controller's own verdict read from its API server
+// (argocd-server) because the CR doesn't carry it; same authority as
+// 'controller'.
+export type GitOpsHealthSource = 'controller' | 'controllerApi' | 'radar' | (string & {})
+
+// Where an Argo CD Application keeps per-resource health. 'appTree' is the
+// Argo CD 3 default: the controller's per-resource verdicts are not in the
+// Application object, so any node health present came from Radar.
+export type GitOpsHealthMode = 'inline' | 'appTree' | (string & {})
+
 export type GitOpsTreeEdgeType = 'owns' | 'source' | 'dependsOn'
 
 export interface GitOpsTreeEdge {
@@ -54,4 +74,13 @@ export interface GitOpsResourceTree {
   edges: GitOpsTreeEdge[]
   warnings?: string[]
   summary?: GitOpsTreeSummary
+  healthMode?: GitOpsHealthMode
+  // Per-resource health came from the controller's API server, so in
+  // appTree mode the verdicts are still the controller's.
+  healthFromApi?: boolean
+  // The controller's API server was asked and didn't answer usefully.
+  healthApiError?: string
+  // The Application deploys to another cluster; Radar derives nothing about
+  // its resources from here.
+  remoteDestination?: boolean
 }

package/src/utils/animation.ts

@@ -1,27 +1,57 @@
 /**
  * Central animation presets for consistent motion across the UI.
  *
- * All animations use GPU-composited properties only (translate, scale, opacity)
- * to guarantee 60fps. The iOS-like spring easing gives a fast-in, gentle-out feel.
+ * One curve, a handful of durations, and class fragments that apply them.
+ * Every surface that opens, closes, expands or collapses takes its timing
+ * from here — the hub (radar-hub-web) re-exports this module so Radar Cloud
+ * chrome and the embedded Radar views move alike.
+ *
+ * Property choice: geometry that has to move (grid-template-rows on a
+ * disclosure, width on a drawer) is animated directly; everything else is
+ * transform + opacity so it stays GPU-composited.
  */
 
 // -- Easing ------------------------------------------------------------------
 
+/** The one UI curve. iOS-style decelerate: fast out of the gate, gentle
+ *  settle. Used for disclosures, menus, dialogs, sheets and drawers alike so
+ *  a click reads as the cause of the motion and the content is legible early.
+ *  Chosen over Material's standard curve in a side-by-side on real content. */
+export const CSS_EASE = 'cubic-bezier(0.32, 0.72, 0, 1)'
+/** Alias with the intent in the name; prefer it in new code. */
+export const EASE_UI = CSS_EASE
+
 // Tailwind-safe easing (no spaces — Tailwind splits class strings on whitespace)
 const TW_EASE = 'ease-[cubic-bezier(0.32,0.72,0,1)]'
-
-/** Raw CSS easing for inline transition strings */
-export const CSS_EASE = 'cubic-bezier(0.32, 0.72, 0, 1)'
+/** The same curve as a Tailwind class fragment, for class-string composition. */
+export const TW_EASE_UI = TW_EASE
 
 // -- Durations (ms) ----------------------------------------------------------
 
-/** Standard UI transitions: overlays, panels, toasts */
+/** Standard UI transitions: drawers, toasts. */
 export const DURATION_NORMAL = 300
-/** Dock height, subtle layout shifts */
+/** Dock height, subtle layout shifts. Deliberately fast: the dock is direct
+ *  manipulation the user performs dozens of times a day. */
 export const DURATION_DOCK = 150
 /** Toast exit animation */
 export const DURATION_TOAST_EXIT = 200
 
+/** In-flow disclosure (Collapse / drawer sections / row expanders): panel
+ *  and caret share this, open and close alike. Symmetric on purpose — an
+ *  interrupted toggle reverses cleanly when both directions run one clock. */
+export const DURATION_DISCLOSURE = 300
+
+/** Menus, popovers, listboxes. Exits are shorter than entrances: a dismissal
+ *  should feel immediate. */
+export const DURATION_MENU_IN = 140
+export const DURATION_MENU_OUT = 100
+/** Modal dialogs and command palettes. */
+export const DURATION_DIALOG_IN = 220
+export const DURATION_DIALOG_OUT = 160
+/** Bottom sheets: more travel, a little more time. */
+export const DURATION_SHEET_IN = 280
+export const DURATION_SHEET_OUT = 220
+
 /** Drawer ↔ fullscreen expand/collapse morph. Longer than DURATION_NORMAL so a
  *  large width change advances in small per-frame steps (reads as fluid, not
  *  abrupt). Drives the frame width, the content crossfade, and the JS window
@@ -32,19 +62,69 @@ export const DURATION_DRAWER_MORPH = 260
  *  crossfade fixed the reflow that originally needed the gentle start. */
 export const EASE_DRAWER_MORPH = 'cubic-bezier(0.2, 0.8, 0.2, 1)'
 
+// -- Reduced motion -----------------------------------------------------------
+
+/** True when the OS asks for reduced motion. Presence hooks use it to dispose
+ *  overlays at logical close instead of after an exit transition that the app
+ *  stylesheet has already zeroed. SSR- and test-safe. */
+export function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}
+
 // -- Tailwind class presets ---------------------------------------------------
 // Reusable class fragments — import and spread into clsx() calls.
 
+/** Disclosure panel: grid-template-rows 0fr ↔ 1fr on the wrapper. Pair with
+ *  TRANSITION_CHEVRON on the caret so both run one clock. */
+export const TRANSITION_DISCLOSURE =
+  `transition-[grid-template-rows] duration-300 ${TW_EASE} motion-reduce:transition-none`
+
+/** Disclosure caret (rotate). Same duration and curve as the panel it opens. */
+export const TRANSITION_CHEVRON =
+  `transition-transform duration-300 ${TW_EASE} motion-reduce:transition-none`
+
 /** Drawer slide from right — use with translate-x-0/translate-x-full + opacity.
  *  Also handles expand/collapse (width) so a single transition covers both. */
 export const TRANSITION_DRAWER =
-  `transition-[translate,opacity,width] duration-300 ${TW_EASE} will-change-[transform,width]`
+  `transition-[translate,opacity,width] duration-300 ${TW_EASE} will-change-[transform,width] motion-reduce:transition-none`
 
-
-/** Overlay backdrop fade */
+/** Overlay backdrop fade. Duration comes from the presence state (see
+ *  overlayTransitionStyle) so the exit can be shorter than the entrance. */
 export const TRANSITION_BACKDROP =
-  'transition-opacity duration-200'
+  `transition-opacity ${TW_EASE} motion-reduce:transition-none`
 
-/** Overlay panel scale + fade — use with scale-100/scale-[0.97] + opacity */
+/** Overlay panel scale + fade — use with scale-100/scale-[0.97] + opacity.
+ *  Duration comes from overlayTransitionStyle, not from this fragment. */
 export const TRANSITION_PANEL =
-  `transition-[translate,scale,opacity] duration-300 ${TW_EASE}`
+  `transition-[translate,scale,opacity] ${TW_EASE} motion-reduce:transition-none`
+
+/** Menu / popover: translate + scale + opacity from its anchor corner. Pair
+ *  with a transform-origin utility so it grows from the trigger. */
+export const TRANSITION_MENU =
+  `transition-[translate,scale,opacity] ${TW_EASE} motion-reduce:transition-none`
+
+export type OverlayKind = 'menu' | 'dialog' | 'sheet' | 'drawer'
+
+const OVERLAY_DURATIONS: Record<OverlayKind, { in: number; out: number }> = {
+  menu: { in: DURATION_MENU_IN, out: DURATION_MENU_OUT },
+  dialog: { in: DURATION_DIALOG_IN, out: DURATION_DIALOG_OUT },
+  sheet: { in: DURATION_SHEET_IN, out: DURATION_SHEET_OUT },
+  // Side drawers keep their symmetric slide (TRANSITION_DRAWER); this entry
+  // gives their backdrop the same clock.
+  drawer: { in: DURATION_NORMAL, out: DURATION_NORMAL },
+}
+
+/** Exit duration for an overlay kind — what useAnimatedUnmount should wait. */
+export function overlayExitMs(kind: OverlayKind): number {
+  return OVERLAY_DURATIONS[kind].out
+}
+
+/** Inline style that gives an overlay its entrance or exit duration. Apply to
+ *  the element that carries TRANSITION_PANEL / TRANSITION_MENU / TRANSITION_BACKDROP;
+ *  the class fragments deliberately carry no duration so the two directions
+ *  can differ. */
+export function overlayTransitionStyle(isOpen: boolean, kind: OverlayKind): { transitionDuration: string } {
+  const d = OVERLAY_DURATIONS[kind]
+  return { transitionDuration: `${isOpen ? d.in : d.out}ms` }
+}

package/src/utils/index.ts

@@ -30,3 +30,4 @@ export * from './application-history'
 export * from './bulk-workload-actions'
 export * from './inClusterConsent'
 export * from './workflow-execution'
+export * from './network-policy'

package/src/utils/navigation.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect, afterEach } from 'vitest'
 import { englishPlural } from './pluralize'
-import { kindToPlural, kindToPluralWithGroup, pluralToKind, refToSelectedResource, initNavigationMap, resetNavigationMap, laneId, laneResourceKey, groupQualifiesLaneId, parseLaneId } from './navigation'
+import { kindToPlural, kindToPluralWithGroup, pluralToKind, knownKindForPluralWithGroup, refToSelectedResource, initNavigationMap, resetNavigationMap, laneId, laneResourceKey, groupQualifiesLaneId, parseLaneId } from './navigation'
 
 afterEach(() => {
   resetNavigationMap()
@@ -223,6 +223,25 @@ describe('initNavigationMap', () => {
       { group: 'metrics.k8s.io', version: 'v1beta1', kind: 'PodMetrics', name: 'pods', namespaced: true, isCrd: false, verbs: ['get'] },
     ])
     expect(pluralToKind('pods')).toBe('Pod')
+    expect(knownKindForPluralWithGroup('pods', '')).toBe('Pod')
+    expect(knownKindForPluralWithGroup('pods', 'metrics.k8s.io')).toBe('PodMetrics')
+    expect(kindToPluralWithGroup('PodMetrics', 'metrics.k8s.io')).toBe('pods')
+  })
+
+  test('resolves discovered plural collisions by API group', () => {
+    initNavigationMap([
+      { group: 'a.example.io', version: 'v1', kind: 'Widget', name: 'widgets', namespaced: true, isCrd: true, verbs: ['get'] },
+      { group: 'b.example.io', version: 'v1', kind: 'OtherWidget', name: 'widgets', namespaced: true, isCrd: true, verbs: ['get'] },
+    ])
+    expect(knownKindForPluralWithGroup('widgets', 'a.example.io')).toBe('Widget')
+    expect(knownKindForPluralWithGroup('widgets', 'b.example.io')).toBe('OtherWidget')
+    expect(knownKindForPluralWithGroup('OtherWidget', 'b.example.io')).toBe('OtherWidget')
+  })
+
+  test('does not invent a Kind for an undiscovered irregular CRD', () => {
+    expect(knownKindForPluralWithGroup('databases', 'postgresql.cnpg.io')).toBeUndefined()
+    expect(kindToPluralWithGroup('Database', 'postgresql.cnpg.io')).toBe('databases')
+    expect(kindToPluralWithGroup('databases', 'postgresql.cnpg.io')).toBe('databases')
   })
 
   test('keeps the virtual PodGroup alias distinct from scheduling PodGroup', () => {

package/src/utils/navigation.ts

@@ -1,5 +1,6 @@
 import type { SelectedResource, ResourceRef, APIResource } from '../types/core'
 import { englishPlural, englishSingular, isEnglishPlural } from './pluralize'
+import { CORE_RESOURCES } from './api-resources'
 
 /**
  * Canonical callback type for navigating to a resource.
@@ -44,6 +45,15 @@ const BUILTIN_PLURAL_TO_KIND: Record<string, string> = {
 
 const BUILTIN_GROUP_KIND_TO_PLURAL: Record<string, string> = {
   'scheduling.k8s.io/podgroup': 'podgroups',
+  'metrics.k8s.io/podmetrics': 'pods',
+  'metrics.k8s.io/nodemetrics': 'nodes',
+}
+
+const BUILTIN_GROUP_PLURAL_TO_KIND: Record<string, string> = {
+  ...Object.fromEntries(CORE_RESOURCES.map(r => [`${r.group}/${r.name}`, r.kind])),
+  'metrics.k8s.io/pods': 'PodMetrics',
+  'metrics.k8s.io/nodes': 'NodeMetrics',
+  'scheduling.k8s.io/podgroups': 'PodGroup',
 }
 
 // Dynamic map built from API discovery — populated by initNavigationMap().
@@ -51,6 +61,7 @@ const BUILTIN_GROUP_KIND_TO_PLURAL: Record<string, string> = {
 let discoveredPluralToKind: Record<string, string> | null = null
 let discoveredKindToPlural: Record<string, string> | null = null
 let discoveredGroupKindToPlural: Record<string, string> | null = null
+let discoveredGroupPluralToKind: Record<string, string> | null = null
 
 /**
  * Initialize navigation maps from discovered API resources.
@@ -61,6 +72,7 @@ export function initNavigationMap(resources: APIResource[]) {
   const p2k: Record<string, string> = { ...BUILTIN_PLURAL_TO_KIND }
   const k2p: Record<string, string> = {}
   const gk2p: Record<string, string> = {}
+  const gp2k: Record<string, string> = { ...BUILTIN_GROUP_PLURAL_TO_KIND }
   for (const r of resources) {
     const plural = r.name.toLowerCase()
     // First-wins on plurals: BUILTIN_PLURAL_TO_KIND seeds canonical core mappings
@@ -69,10 +81,13 @@ export function initNavigationMap(resources: APIResource[]) {
     if (!(plural in p2k)) p2k[plural] = r.kind
     k2p[r.kind.toLowerCase()] = plural
     gk2p[`${r.group}/${r.kind.toLowerCase()}`] = plural
+    const groupPlural = `${r.group}/${plural}`
+    if (!(groupPlural in gp2k)) gp2k[groupPlural] = r.kind
   }
   discoveredPluralToKind = p2k
   discoveredKindToPlural = k2p
   discoveredGroupKindToPlural = gk2p
+  discoveredGroupPluralToKind = gp2k
 }
 
 /** Reset navigation maps to builtin-only state. For testing. */
@@ -80,6 +95,7 @@ export function resetNavigationMap() {
   discoveredPluralToKind = null
   discoveredKindToPlural = null
   discoveredGroupKindToPlural = null
+  discoveredGroupPluralToKind = null
 }
 
 function getPluralToKind(): Record<string, string> {
@@ -166,6 +182,15 @@ export function pluralToKind(plural: string): string {
   return singular.charAt(0).toUpperCase() + singular.slice(1)
 }
 
+/** Return an exact Kind only when the input or group-qualified discovery proves it. */
+export function knownKindForPluralWithGroup(plural: string, group: string): string | undefined {
+  if (!plural) return undefined
+  if (plural[0] !== plural[0].toLowerCase()) return plural
+  const groupPlural = `${group}/${plural.toLowerCase()}`
+  return discoveredGroupPluralToKind?.[groupPlural]
+    ?? BUILTIN_GROUP_PLURAL_TO_KIND[groupPlural]
+}
+
 /**
  * Convert a ResourceRef (from backend relationships) to a SelectedResource (for navigation).
  * Handles kind singular→plural conversion.

package/src/utils/network-policy.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { effectivePolicyTypeNames, effectivePolicyTypes, formatNetworkPolicyPort } from './network-policy'
+
+describe('effectivePolicyTypes', () => {
+  it('reads an explicit list as authoritative', () => {
+    expect(effectivePolicyTypes({ policyTypes: ['Egress'] })).toEqual({ ingress: false, egress: true, explicit: true })
+    expect(effectivePolicyTypes({ policyTypes: ['Ingress', 'Egress'], egress: [] })).toEqual({ ingress: true, egress: true, explicit: true })
+  })
+
+  it('defaults an omitted list to Ingress — the classic default-deny', () => {
+    expect(effectivePolicyTypes({ podSelector: {} })).toEqual({ ingress: true, egress: false, explicit: false })
+    expect(effectivePolicyTypes({ policyTypes: [] })).toEqual({ ingress: true, egress: false, explicit: false })
+    expect(effectivePolicyTypes(undefined)).toEqual({ ingress: true, egress: false, explicit: false })
+  })
+
+  it('adds Egress to the default only when egress rules are declared', () => {
+    expect(effectivePolicyTypes({ egress: [{}] })).toEqual({ ingress: true, egress: true, explicit: false })
+    expect(effectivePolicyTypes({ egress: [] })).toEqual({ ingress: true, egress: false, explicit: false })
+  })
+
+  it('names the effective types as Ingress then Egress', () => {
+    expect(effectivePolicyTypeNames({})).toEqual(['Ingress'])
+    expect(effectivePolicyTypeNames({ egress: [{}] })).toEqual(['Ingress', 'Egress'])
+    expect(effectivePolicyTypeNames({ policyTypes: ['Egress'] })).toEqual(['Egress'])
+    expect(effectivePolicyTypeNames({ policyTypes: ['Egress', 'Ingress'] })).toEqual(['Ingress', 'Egress'])
+  })
+})
+
+describe('formatNetworkPolicyPort', () => {
+  it('renders single ports, ranges, named ports and protocol-only entries', () => {
+    expect(formatNetworkPolicyPort({ port: 80 })).toBe('TCP/80')
+    expect(formatNetworkPolicyPort({ protocol: 'UDP', port: 53 })).toBe('UDP/53')
+    expect(formatNetworkPolicyPort({ port: 9000, endPort: 9100 })).toBe('TCP/9000-9100')
+    expect(formatNetworkPolicyPort({ port: 'metrics' })).toBe('TCP/metrics')
+    expect(formatNetworkPolicyPort({ protocol: 'SCTP' })).toBe('SCTP/*')
+  })
+
+  it('never shows a range off a named port or off no port', () => {
+    expect(formatNetworkPolicyPort({ port: 'metrics', endPort: 9100 })).toBe('TCP/metrics')
+    expect(formatNetworkPolicyPort({ endPort: 9100 })).toBe('TCP/*')
+  })
+})

package/src/utils/network-policy.ts

@@ -0,0 +1,59 @@
+/**
+ * Core networking.k8s.io/v1 NetworkPolicy presentation helpers, shared by the
+ * list column, the detail renderer and the flow diagram so the three cannot
+ * disagree about what a policy does.
+ */
+
+export interface EffectivePolicyTypes {
+  ingress: boolean
+  egress: boolean
+  /** True when spec.policyTypes was set; false when Kubernetes' defaulting decided. */
+  explicit: boolean
+}
+
+/**
+ * Kubernetes' policyTypes defaulting, applied exactly: when spec.policyTypes
+ * is set it is authoritative; when omitted, a policy always isolates Ingress
+ * and additionally isolates Egress iff it declares egress rules. The common
+ * default-deny (`podSelector: {}` and nothing else) has no policyTypes and
+ * isolates ingress — reading the field raw shows it as isolating nothing.
+ */
+export function effectivePolicyTypes(spec: any): EffectivePolicyTypes {
+  const declared: unknown = spec?.policyTypes
+  if (Array.isArray(declared) && declared.length > 0) {
+    return {
+      ingress: declared.includes('Ingress'),
+      egress: declared.includes('Egress'),
+      explicit: true,
+    }
+  }
+  const egressRules: unknown = spec?.egress
+  return {
+    ingress: true,
+    egress: Array.isArray(egressRules) && egressRules.length > 0,
+    explicit: false,
+  }
+}
+
+/** The effective types as the list they would have been declared as. */
+export function effectivePolicyTypeNames(spec: any): string[] {
+  const t = effectivePolicyTypes(spec)
+  const out: string[] = []
+  if (t.ingress) out.push('Ingress')
+  if (t.egress) out.push('Egress')
+  return out
+}
+
+/**
+ * One NetworkPolicyPort as `PROTO/port`, `PROTO/start-end` for an endPort
+ * range, or `PROTO/*` when the entry names a protocol but no port.
+ */
+export function formatNetworkPolicyPort(port: any): string {
+  const proto = port?.protocol || 'TCP'
+  const start = port?.port ?? '*'
+  const end = port?.endPort
+  // endPort only ever pairs with a numeric port; a range off a named port or
+  // off no port is not a range Kubernetes would accept, so it isn't shown as one.
+  const isRange = end != null && typeof start === 'number'
+  return isRange ? `${proto}/${start}-${end}` : `${proto}/${start}`
+}

package/src/utils/reflector.ts

@@ -0,0 +1,139 @@
+import type { Relationships } from "../types";
+
+const prefix = "reflector.v1.k8s.emberstack.com/";
+const annotationNames = [
+  "reflects",
+  "auto-reflects",
+  "reflected-version",
+  "reflected-at",
+  "reflection-allowed",
+  "reflection-auto-enabled",
+  "reflection-allowed-namespaces",
+  "reflection-allowed-namespaces-selector",
+  "reflection-auto-namespaces",
+  "reflection-auto-namespaces-selector",
+];
+
+export type Reflection = NonNullable<Relationships["reflection"]>;
+export interface ReflectorResource {
+  apiVersion?: string;
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    annotations?: Record<string, string>;
+  };
+}
+
+function annotationsFor(data: ReflectorResource): Record<string, string> {
+  return data.apiVersion === "v1" ? (data.metadata?.annotations ?? {}) : {};
+}
+
+export function hasReflectorDetails(
+  data: ReflectorResource,
+  reflection?: Reflection,
+): boolean {
+  if (data.apiVersion !== "v1") return false;
+  const annotations = annotationsFor(data);
+  return (
+    annotationNames.some((name) => prefix + name in annotations) ||
+    !!reflection?.source ||
+    !!reflection?.mirrors?.length
+  );
+}
+
+export function isReflectorMirror(data: ReflectorResource): boolean {
+  return /^[^/\s]+\/[^/\s]+$/.test(
+    annotationsFor(data)[prefix + "reflects"] ?? "",
+  );
+}
+
+export const reflectorEditNotice =
+  "This object is a Reflector mirror. Edit the source for lasting changes. Local edits may persist until the source changes, then be overwritten.";
+
+function booleanValue(value: string | undefined): boolean | undefined {
+  if (value === undefined) return false;
+  if (value.trim().toLowerCase() === "true") return true;
+  if (value.trim().toLowerCase() === "false") return false;
+  return undefined;
+}
+
+export function parseReflector(
+  data: ReflectorResource,
+  reflection?: Reflection,
+) {
+  const annotations = annotationsFor(data);
+  const value = (name: string) => annotations[prefix + name];
+  const declaration = value("reflects");
+  const hasDeclaration = declaration !== undefined;
+  const isMirror = isReflectorMirror(data);
+  const allowed = booleanValue(value("reflection-allowed"));
+  const autoEnabled = booleanValue(value("reflection-auto-enabled"));
+  const automatic = booleanValue(value("auto-reflects"));
+  const source =
+    reflection?.source &&
+    `${reflection.source.namespace}/${reflection.source.name}` === declaration
+      ? reflection.source
+      : undefined;
+  const mirrors = reflection?.mirrors ?? [];
+  const sourceSettings =
+    !isMirror ||
+    annotationNames.some(
+      (name) => name.startsWith("reflection-") && value(name) !== undefined,
+    ) ||
+    mirrors.length > 0;
+  const copiedVersion = value("reflected-version");
+  const sourceVersion = source ? reflection?.sourceResourceVersion : undefined;
+  const warnings: string[] = [];
+  for (const name of [
+    "reflection-allowed",
+    "reflection-auto-enabled",
+    "auto-reflects",
+  ]) {
+    if (booleanValue(value(name)) === undefined)
+      warnings.push(
+        `${name} must be true or false (currently "${value(name)}").`,
+      );
+  }
+  if (hasDeclaration && !isMirror)
+    warnings.push(
+      "The reflects annotation must name a source as namespace/name.",
+    );
+  if (
+    declaration &&
+    declaration === `${data.metadata?.namespace}/${data.metadata?.name}`
+  )
+    warnings.push(
+      "The reflects annotation points to this object itself. Choose a different source.",
+    );
+  if (!isMirror && mirrors.length > 0 && allowed === false)
+    warnings.push(
+      "Reflection is not enabled on this source, but visible mirrors still reference it.",
+    );
+  if (!isMirror && autoEnabled === true && allowed === false)
+    warnings.push(
+      "Automatic mirror creation requires reflection-allowed to be true.",
+    );
+  if (
+    isMirror &&
+    (mirrors.length > 0 || allowed === true || autoEnabled === true)
+  )
+    warnings.push(
+      "This object is itself a mirror. Reflector does not propagate its updates as source updates to other mirrors.",
+    );
+
+  return {
+    value,
+    declaration,
+    hasDeclaration,
+    isMirror,
+    allowed,
+    autoEnabled,
+    automatic,
+    source,
+    mirrors,
+    sourceSettings,
+    copiedVersion,
+    sourceVersion,
+    warnings,
+  };
+}