@skyhook-io/k8s-ui 1.18.2 → 1.20.0

package/src/utils/animation.ts

@@ -45,6 +45,17 @@ export const DURATION_DISCLOSURE = 300
  *  should feel immediate. */
 export const DURATION_MENU_IN = 140
 export const DURATION_MENU_OUT = 100
+/** Hover-revealed row actions (HOVER_REVEAL_*). In the range of Radar's other
+ *  hover effects (150–200ms) rather than the menu clock, which reads as a
+ *  flicker on something the pointer merely passes over. The exit is shorter
+ *  so leaving a row feels immediate. The preset class strings spell these
+ *  values out for Tailwind's scanner; a test keeps them in step. */
+export const DURATION_HOVER_REVEAL_IN = 200
+export const DURATION_HOVER_REVEAL_OUT = 120
+/** Hover intent before a row action comes in: a pointer sweeping down a long
+ *  list passes each row in well under this, so actions don't ripple in behind
+ *  it. Entrance only; leaving a row hides its action at once. */
+export const HOVER_INTENT_DELAY = 60
 /** Modal dialogs and command palettes. */
 export const DURATION_DIALOG_IN = 220
 export const DURATION_DIALOG_OUT = 160
@@ -104,6 +115,29 @@ export const TRANSITION_PANEL =
 export const TRANSITION_MENU =
   `transition-[translate,scale,opacity] ${TW_EASE} motion-reduce:transition-none`
 
+/** Hover-revealed row action, the resting half: the row content the action
+ *  replaces (an age, a chip) lifts 3px and fades on the exit clock. Needs a
+ *  `group` ancestor; keyboard reveal keys on :focus-visible inside the group,
+ *  so a row left focused by a mouse click doesn't keep its action up. Timing
+ *  is DURATION_HOVER_REVEAL_IN / _OUT and HOVER_INTENT_DELAY. */
+export const HOVER_REVEAL_REST =
+  `transition-[opacity,translate] duration-200 ${TW_EASE} motion-reduce:transition-none group-hover:opacity-0 group-hover:-translate-y-[3px] group-hover:duration-120 group-hover:delay-60 group-has-[:focus-visible]:opacity-0 group-has-[:focus-visible]:-translate-y-[3px] group-has-[:focus-visible]:duration-120 group-has-[:focus-visible]:delay-60`
+
+/** Hover-revealed row action, the action half: rises 3px into place on the
+ *  entrance clock after the hover-intent delay, drops out on the exit clock.
+ *  Never a hit target itself, so its padding and any backdrop leave clicks to
+ *  the row underneath; put HOVER_REVEAL_HIT on the control inside it. Pair
+ *  with HOVER_REVEAL_REST in one group. */
+export const HOVER_REVEAL_ACTION =
+  `transition-[opacity,translate] duration-120 ${TW_EASE} motion-reduce:transition-none pointer-events-none opacity-0 translate-y-[3px] group-hover:opacity-100 group-hover:translate-y-0 group-hover:duration-200 group-hover:delay-60 group-has-[:focus-visible]:opacity-100 group-has-[:focus-visible]:translate-y-0 group-has-[:focus-visible]:duration-200 group-has-[:focus-visible]:delay-60`
+
+/** Hover-revealed row action, the control inside it: takes clicks only while
+ *  shown. pointer-events transitions as a discrete property on the same
+ *  clock, so it flips partway through the entrance rather than at hover start
+ *  and a click during the intent delay lands on the row. */
+export const HOVER_REVEAL_HIT =
+  `transition-[pointer-events] transition-discrete duration-120 ${TW_EASE} motion-reduce:transition-none pointer-events-none group-hover:pointer-events-auto group-hover:duration-200 group-hover:delay-60 group-has-[:focus-visible]:pointer-events-auto group-has-[:focus-visible]:duration-200 group-has-[:focus-visible]:delay-60`
+
 export type OverlayKind = 'menu' | 'dialog' | 'sheet' | 'drawer'
 
 const OVERLAY_DURATIONS: Record<OverlayKind, { in: number; out: number }> = {

package/src/utils/api-resources-crd.test.ts

@@ -0,0 +1,11 @@
+import { expect, it } from 'vitest'
+import { categorizeResources, resourceSearchAliases } from './api-resources'
+import type { APIResource } from '../types'
+const crd: APIResource = { group: 'apiextensions.k8s.io', version: 'v1', kind: 'CustomResourceDefinition', name: 'customresourcedefinitions', namespaced: false, isCrd: false, verbs: ['get', 'list'] }
+it('places discovered definitions in Cluster without a fallback row', () => {
+  expect(categorizeResources([crd]).find(c => c.name === 'Cluster')?.resources).toContainEqual(crd)
+  expect(categorizeResources([]).flatMap(c => c.resources).some(r => r.kind === crd.kind)).toBe(false)
+  expect(categorizeResources([{ ...crd, verbs: ['get'] }]).flatMap(c => c.resources).some(r => r.kind === crd.kind)).toBe(false)
+  expect(resourceSearchAliases(crd)).toEqual(['crd', 'crds'])
+  expect(resourceSearchAliases({ group: 'other.io', kind: crd.kind })).toEqual([])
+})

package/src/utils/api-resources.ts

@@ -12,7 +12,7 @@ const NETWORKING_KINDS = ['Service', 'Ingress', 'IngressClass', 'NetworkPolicy',
 const CONFIG_KINDS = ['ConfigMap', 'Secret', 'HorizontalPodAutoscaler', 'PodDisruptionBudget', 'LimitRange', 'ResourceQuota', 'PriorityClass', 'RuntimeClass', 'Lease', 'MutatingWebhookConfiguration', 'ValidatingWebhookConfiguration']
 const STORAGE_KINDS = ['PersistentVolumeClaim', 'PersistentVolume', 'StorageClass', 'VolumeAttachment']
 const ACCESS_CONTROL_KINDS = ['ServiceAccount', 'Role', 'ClusterRole', 'RoleBinding', 'ClusterRoleBinding']
-const CLUSTER_KINDS = ['Node', 'Namespace', 'Event']
+const CLUSTER_KINDS = ['Node', 'Namespace', 'Event', 'CustomResourceDefinition']
 const CORE_CATEGORY_NAMES = new Set(['Workloads', 'Networking', 'Configuration', 'Storage', 'Access Control', 'Cluster'])
 // Core resources that must always be present (fallback if API discovery misses them)
 export const CORE_RESOURCES: APIResource[] = [
@@ -346,3 +346,7 @@ export function getKindLabel(kind: string): string {
 export function getKindPlural(resource: APIResource): string {
   return resource.name
 }
+
+export function resourceSearchAliases(resource: Pick<APIResource, 'group' | 'kind'>): string[] {
+  return resource.group === 'apiextensions.k8s.io' && resource.kind === 'CustomResourceDefinition' ? ['crd', 'crds'] : []
+}

package/src/utils/applications.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { compareVersions, appGroupingExplainer, APP_IDENTITY_ANNOTATION, appGroupLagMessage, matchWorkloadAcrossInstances, foldAppGroups, identityEnvInferred, worstHealth, buildAppMembershipIndex, batchActivityForApp, batchRuntimeForApp, servingReadiness, resolveAppWorkloadSelection, type AppGroupFoldEntry, type AppRow, type AppWorkload } from './applications'
+import { compareVersions, appGroupingExplainer, APP_IDENTITY_ANNOTATION, appGroupLagMessage, matchWorkloadAcrossInstances, foldAppGroups, identityEnvInferred, worstHealth, buildAppMembershipIndex, batchActivityForApp, batchRuntimeForApp, batchSignalForApp, servingReadiness, resolveAppWorkloadSelection, type AppGroupFoldEntry, type AppRow, type AppWorkload } from './applications'
 
 describe('application workload scope resolution', () => {
   const sole = ['Deployment/prod/api']
@@ -64,6 +64,20 @@ describe('application workload scope resolution', () => {
 })
 
 describe('batch application runtime', () => {
+  it('uses JobSet root health without interpreting child activity as running Pods', () => {
+    const workload: AppWorkload = { kind: 'JobSet', group: 'jobset.x-k8s.io', name: 'train', namespace: 'ml', health: 'unknown', ready: 0, desired: 0, restarts: 0, batch: { latestRunPhase: 'Unknown', retainedRuns: 1 } }
+    const app: AppRow = { key: 'ml/JobSet/train', name: 'train', health: 'unknown', workload_class: 'job', workloads: [workload] }
+    for (const [health, phase] of [['unknown', 'Unknown'], ['degraded', 'Restarting'], ['neutral', 'Active'], ['neutral', 'Succeeded'], ['unhealthy', 'Failed']]) {
+      workload.health = health
+      workload.batch = { latestRunPhase: phase, retainedRuns: 1, activeRuns: phase === 'Active' ? 1 : 0 }
+      expect(batchRuntimeForApp(app)).toMatchObject({ health, label: phase })
+      expect(batchSignalForApp(app)).toMatchObject({ label: `JobSet ${phase}` })
+      expect(batchActivityForApp(app)[0]).toMatchObject({ label: phase })
+    }
+    workload.health = 'unhealthy'
+    app.workloads!.push({ ...workload, kind: 'CronJob', group: 'batch', health: 'neutral', batch: { activeRuns: 1, latestRunPhase: 'Running' } })
+    expect(batchRuntimeForApp(app).health).toBe('unhealthy')
+  })
   it('uses the latest retained outcome instead of historical failure count', () => {
     const app: AppRow = {
       key: 'batch', name: 'batch', health: 'unhealthy', workload_class: 'job',

package/src/utils/applications.ts

@@ -1203,7 +1203,7 @@ export const CLASS_META: Record<
     label: "Job",
     pill: CHIP_TONE.amber,
     tooltip:
-      "Finite or scheduled work (Job/CronJob/Workflow/CronWorkflow/WorkflowTemplate/ClusterWorkflowTemplate/ScaledJob).",
+      "Finite or scheduled work (Job/CronJob/Workflow/CronWorkflow/WorkflowTemplate/ClusterWorkflowTemplate/ScaledJob/JobSet).",
   },
   mixed: {
     label: "Mixed",
@@ -1293,6 +1293,8 @@ export function batchSignalForApp(app: AppRow): BatchSignal | null {
 function batchSignalForWorkload(workload: AppWorkload): BatchSignal | null {
   const batch = workload.batch;
   if (!batch) return null;
+  const root = jobSetBatchRuntime(workload)
+  if (root) return { tone: root.health === 'unhealthy' ? 'rose' : root.health === 'degraded' ? 'amber' : 'sky', label: `JobSet ${root.label}`, detail: root.detail, workload }
   const latestPhase = batch.latestRunPhase || "";
   const name = `${workload.kind}/${workload.name}`;
   if (latestPhase === "Failed" || latestPhase === "Error") {
@@ -1330,7 +1332,23 @@ export interface AppBatchRuntime {
   detail: string;
 }
 
+function jobSetBatchRuntime(workload: AppWorkload): AppBatchRuntime | null {
+  if (workload.kind !== 'JobSet' || workload.group !== 'jobset.x-k8s.io') return null
+  return {
+    label: workload.batch?.latestRunPhase || 'Unknown',
+    health: healthOf(workload.health),
+    detail: workload.batch?.message || `JobSet/${workload.name} root lifecycle.`,
+  }
+}
+
 export function batchRuntimeForApp(app: AppRow): AppBatchRuntime {
+  const jobSets = (app.workloads || []).filter(w => w.kind === 'JobSet' && w.group === 'jobset.x-k8s.io')
+  if (jobSets.length > 0) {
+    const runtimes: AppBatchRuntime[] = jobSets.map(workload => jobSetBatchRuntime(workload)!)
+    const others = (app.workloads || []).filter(w => !jobSets.includes(w))
+    if (others.length > 0) runtimes.push(batchRuntimeForApp({ ...app, workloads: others }))
+    return runtimes.reduce((worst, next) => HEALTH_RANK[next.health] > HEALTH_RANK[worst.health] ? next : worst)
+  }
   const activity = batchActivityForApp(app);
   if (
     activity.some(
@@ -1504,6 +1522,13 @@ function batchActivityForWorkload(
   const activeRuns = batch.activeRuns ?? 0;
   const retainedRuns = batch.retainedRuns ?? 0;
   const failedRuns = batch.failedRuns ?? 0;
+  const root = jobSetBatchRuntime(workload)
+  if (root) return {
+    workload, tone: root.health === 'unhealthy' ? 'rose' : root.health === 'degraded' ? 'amber' : 'sky',
+    rank: root.health === 'unhealthy' ? 50 : root.health === 'degraded' ? 40 : 10,
+    label: root.label, detail: root.detail, latestRunName: batch.latestRunName,
+    latestRunPhase: latestPhase, activeRuns, retainedRuns, failedRuns,
+  }
   if (latestPhase === "Failed" || latestPhase === "Error") {
     return {
       workload,

package/src/utils/crd-schema.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+import { compareKubeAwareVersions, displaySchemaPath, filterCRDSchema, indexCRDSchema, preferredCRDVersion, schemaChildren, schemaCompositions, schemaConstraints, schemaTypeLabel, schemaLeafName, schemaParentPath, schemaElement, enclosingRules, type CRDSchema } from './crd-schema'
+
+describe('CRD schemas', () => {
+  it('labels arrays, maps, boolean additionalProperties and Kubernetes extensions', () => {
+    expect(schemaTypeLabel({ type: 'array', items: { type: 'string' } })).toBe('[]string')
+    expect(schemaTypeLabel({ type: 'object', additionalProperties: { type: 'integer' } })).toBe('map[string]integer')
+    expect(schemaTypeLabel({ type: 'object', additionalProperties: true })).toBe('map[string]any')
+    expect(schemaTypeLabel({ type: 'object', additionalProperties: false })).toBe('object')
+    expect(schemaTypeLabel({ 'x-kubernetes-int-or-string': true })).toBe('int-or-string')
+    expect(schemaTypeLabel({ type: 'object', 'x-kubernetes-preserve-unknown-fields': true })).toBe('object')
+  })
+  it('retains requiredness, array/map traversal and dotted property identity', () => {
+    const nodes = indexCRDSchema({ required: ['a.b'], properties: {
+      'a.b': { type: 'string' }, a: { properties: { b: { type: 'number' } } },
+      list: { items: { properties: { x: { type: 'boolean' } } } },
+      map: { additionalProperties: { properties: { y: { type: 'integer' } } } },
+    } })
+    expect(nodes[0].required).toBe(true)
+    expect(nodes.filter(n => displaySchemaPath(n.path) === 'a.b')).toHaveLength(1)
+    expect(nodes.filter(n => displaySchemaPath(n.path) === '["a.b"]')).toHaveLength(1)
+    expect(nodes.map(n => displaySchemaPath(n.path))).toContain('list[].x')
+    expect(nodes.map(n => displaySchemaPath(n.path))).toContain('map{}.y')
+    expect(nodes.map(n => displaySchemaPath(n.path))).not.toContain('list[]')
+    expect(nodes.map(n => displaySchemaPath(n.path))).not.toContain('map{}')
+    const deep = nodes.find(n => displaySchemaPath(n.path) === 'list[].x')!
+    expect(schemaLeafName(deep.path)).toBe('x')
+    expect(schemaParentPath(deep.path)).toBe('list[].')
+    expect(schemaElement({ type: 'array', items: { type: 'string', enum: ['a'] } })).toEqual({ label: 'items', schema: { type: 'string', enum: ['a'] } })
+    expect(schemaChildren({ additionalProperties: true })).toEqual([])
+  })
+  it('retains zero/false/default, constraints, CEL and compositions', () => {
+    const schema = { type: 'integer', minimum: 0, maximum: 4, default: false, enum: [0, 1], format: 'int32', pattern: '^a', minLength: 0, maxLength: 4, minItems: 0, maxItems: 2,
+      'x-kubernetes-validations': [{ rule: 'self > 0', message: 'positive' }],
+      oneOf: [{ required: ['a'] }, { required: ['b', 'c'] }], anyOf: [{ type: 'string' }], allOf: [{ minimum: 0 }], not: { type: 'boolean' } }
+    expect(schemaConstraints(schema)).toEqual(expect.arrayContaining([{ label: 'minimum', value: '0' }, { label: 'default', value: 'false' }, { label: 'enum', value: '0 · 1' }]))
+    expect(schema['x-kubernetes-validations'][0]).toEqual({ rule: 'self > 0', message: 'positive' })
+    expect(schemaCompositions(schema)).toEqual([{ label: 'One of', value: 'a · b + c' }, { label: 'anyOf', value: '[{"type":"string"}]' }, { label: 'allOf', value: '[{"minimum":0}]' }, { label: 'not', value: '{"type":"boolean"}' }])
+  })
+  it('finds a field from an API server error path or a path without brackets', () => {
+    const index = indexCRDSchema({ properties: { spec: { properties: {
+      ports: { type: 'array', items: { properties: { name: { type: 'string' } } } },
+      labels: { type: 'object', additionalProperties: { type: 'object', properties: { tier: { type: 'string' } } } },
+    } } } })
+    const paths = (q: string) => filterCRDSchema(index, q).nodes.map(n => displaySchemaPath(n.path))
+    expect(paths('spec.ports[0].name')).toEqual(['spec.ports[].name'])
+    expect(paths('ports.name')).toEqual(['spec.ports[].name'])
+    expect(paths(' spec.ports[].name ')).toEqual(['spec.ports[].name'])
+    expect(paths('spec.labels[app].tier')).toEqual(['spec.labels{}.tier'])
+    expect(paths('ports.tier')).toEqual([])
+  })
+  it('lists the rules on enclosing fields, nearest first, including array item rules', () => {
+    const root = {
+      'x-kubernetes-validations': [{ rule: 'has(self.spec)' }],
+      properties: { spec: {
+        'x-kubernetes-validations': [{ rule: 'has(self.a) != has(self.b)', message: 'set a or b' }],
+        oneOf: [{ required: ['a'] }, { required: ['b'] }],
+        properties: { list: { type: 'array', items: { 'x-kubernetes-validations': [{ rule: 'self.x > 0' }], properties: { x: { type: 'integer' } } } } },
+      } },
+    }
+    const x = indexCRDSchema(root).find(n => displaySchemaPath(n.path) === 'spec.list[].x')!
+    expect(enclosingRules(x, root)).toEqual([
+      { path: 'spec.list[]', validations: [{ rule: 'self.x > 0' }], compositions: [] },
+      { path: 'spec', validations: [{ rule: 'has(self.a) != has(self.b)', message: 'set a or b' }], compositions: [{ label: 'One of', value: 'a · b' }] },
+      { path: '', validations: [{ rule: 'has(self.spec)' }], compositions: [] },
+    ])
+    expect(enclosingRules(indexCRDSchema({ properties: { a: { type: 'string' } } })[0], { properties: { a: { type: 'string' } } })).toEqual([])
+  })
+  it('reports list, map and key semantics as facts', () => {
+    expect(schemaConstraints({ type: 'array', 'x-kubernetes-list-type': 'map', 'x-kubernetes-list-map-keys': ['name', 'protocol'] })).toEqual([
+      { label: 'list type', value: 'map' }, { label: 'list keys', value: 'name, protocol' },
+    ])
+    expect(schemaConstraints({ type: 'object', 'x-kubernetes-map-type': 'atomic' })).toEqual([{ label: 'map type', value: 'atomic' }])
+  })
+  it('reports rules at every container level a search hit sits in, under the path self refers to', () => {
+    const root = { properties: { spec: { properties: { groups: { type: 'array',
+      'x-kubernetes-validations': [{ rule: 'size(self) < 5' }],
+      items: { type: 'object', additionalProperties: { type: 'object',
+        'x-kubernetes-validations': [{ rule: 'self.min <= self.max' }],
+        properties: { min: { type: 'integer' }, max: { type: 'integer' } } } } } } } } }
+    const min = filterCRDSchema(indexCRDSchema(root), 'spec.groups[0][a].min').nodes
+    expect(min.map(n => displaySchemaPath(n.path))).toEqual(['spec.groups[]{}.min'])
+    expect(enclosingRules(min[0], root).map(r => [r.path, r.validations.map(v => v.rule)])).toEqual([
+      ['spec.groups[]{}', ['self.min <= self.max']],
+      ['spec.groups', ['size(self) < 5']],
+    ])
+  })
+  it('keeps a quoted property exact and ahead of the result cap', () => {
+    const properties: Record<string, CRDSchema> = Object.fromEntries(Array.from({ length: 205 }, (_, i) => [`f${i}`, { type: 'string' }]))
+    properties['a.b'] = { type: 'string' }
+    const result = filterCRDSchema(indexCRDSchema({ properties: { spec: { properties } } }), 'spec["a.b"]')
+    expect(result.nodes.map(n => displaySchemaPath(n.path))).toEqual(['spec["a.b"]'])
+    expect(filterCRDSchema(indexCRDSchema({ properties: { spec: { properties } } }), 'spec.f20').nodes[0].path.at(-1)?.name).toBe('f20')
+  })
+  it('orders kube versions by stability then descending major/minor, with other names last', () => {
+    expect(['v2alpha2', 'foo', 'v1beta2', 'v2', 'v1', 'v3beta1', 'v1beta10', 'bar', 'v2alpha10'].sort(compareKubeAwareVersions)).toEqual(['v2', 'v1', 'v3beta1', 'v1beta10', 'v1beta2', 'v2alpha10', 'v2alpha2', 'bar', 'foo'])
+    expect(preferredCRDVersion([{ name: 'v3', served: false }, { name: 'v1', served: true }, { name: 'v2', served: true }])?.name).toBe('v2')
+  })
+  it('filters case-insensitive displayed paths with a 200 cap and exact total; accepts missing schema', () => {
+    const index = indexCRDSchema({ properties: Object.fromEntries(Array.from({ length: 245 }, (_, i) => [`field${i}`, { type: 'string' }])) })
+    const result = filterCRDSchema(index, 'FIELD')
+    expect(result.total).toBe(245)
+    expect(result.nodes).toHaveLength(200)
+    expect(indexCRDSchema(undefined)).toEqual([])
+    expect(preferredCRDVersion([])).toBeUndefined()
+  })
+})

package/src/utils/crd-schema.ts

@@ -0,0 +1,201 @@
+export interface CRDSchema {
+  type?: string
+  description?: string
+  properties?: Record<string, CRDSchema>
+  required?: string[]
+  items?: CRDSchema
+  additionalProperties?: CRDSchema | boolean
+  'x-kubernetes-int-or-string'?: boolean
+  'x-kubernetes-preserve-unknown-fields'?: boolean
+  'x-kubernetes-validations'?: { rule: string; message?: string }[]
+  oneOf?: CRDSchema[]
+  anyOf?: CRDSchema[]
+  allOf?: CRDSchema[]
+  not?: CRDSchema
+  [key: string]: unknown
+}
+
+export interface CRDVersion {
+  name: string
+  served?: boolean
+  storage?: boolean
+  deprecated?: boolean
+  deprecationWarning?: string
+  schema?: { openAPIV3Schema?: CRDSchema }
+}
+
+export type SchemaPath = { kind: 'property' | 'items' | 'map'; name: string }[]
+export interface SchemaNode {
+  path: SchemaPath
+  schema: CRDSchema
+  required: boolean
+  parent?: SchemaNode
+}
+
+export function compareKubeAwareVersions(a: string, b: string): number {
+  const parse = (v: string) => /^v(\d+)(?:(alpha|beta)(\d+))?$/.exec(v)
+  const x = parse(a), y = parse(b)
+  if (!x || !y) return x ? -1 : y ? 1 : a.localeCompare(b)
+  const rank = (stage?: string) => stage === 'alpha' ? 0 : stage === 'beta' ? 1 : 2
+  return rank(y[2]) - rank(x[2]) || Number(y[1]) - Number(x[1]) || Number(y[3] || 0) - Number(x[3] || 0)
+}
+
+export function preferredCRDVersion(versions: CRDVersion[]): CRDVersion | undefined {
+  return [...versions].filter(v => v.served).sort((a, b) => compareKubeAwareVersions(a.name, b.name))[0] ?? versions[0]
+}
+
+export function schemaTypeLabel(schema: CRDSchema): string {
+  if (schema['x-kubernetes-int-or-string']) return 'int-or-string'
+  if (schema.type === 'array') return `[]${schema.items ? schemaTypeLabel(schema.items) : 'any'}`
+  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') return `map[string]${schemaTypeLabel(schema.additionalProperties)}`
+  if (schema.additionalProperties === true) return 'map[string]any'
+  return schema.type || 'any'
+}
+
+// Array items and map values get no row of their own, as in `kubectl explain`:
+// a field's children are the fields of what it holds, reached through a `[]` or
+// `{}` path segment.
+export function schemaChildren(schema: CRDSchema, path: SchemaPath = [], parent?: SchemaNode): SchemaNode[] {
+  const children: SchemaNode[] = Object.entries(schema.properties || {}).map(([name, child]) => ({
+    path: [...path, { kind: 'property', name }], schema: child, required: !!schema.required?.includes(name), parent,
+  }))
+  if (schema.items) children.push(...schemaChildren(schema.items, [...path, { kind: 'items', name: '[]' }], parent))
+  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+    children.push(...schemaChildren(schema.additionalProperties, [...path, { kind: 'map', name: '{}' }], parent))
+  }
+  return children
+}
+
+export interface EnclosingRules {
+  /** Display path of the enclosing field; empty for the document root. */
+  path: string
+  validations: { rule: string; message?: string }[]
+  compositions: { label: string; value: string }[]
+}
+
+// A field's own rules, then those of each array item or map value it holds
+// (`spec.groups`, `spec.groups[]`, `spec.groups[]{}`), each under the path its
+// `self` refers to. Nearest the leaf first.
+function rulesOf(schema: CRDSchema, path: string): EnclosingRules[] {
+  const levels: EnclosingRules[] = []
+  for (let level: CRDSchema | undefined = schema, at = path; level;) {
+    const validations = level['x-kubernetes-validations'] ?? []
+    const compositions = schemaCompositions(level)
+    if (validations.length || compositions.length) levels.push({ path: at, validations, compositions })
+    const element = schemaElement(level)
+    at += element?.label === 'items' ? '[]' : '{}'
+    level = element?.schema
+  }
+  return levels.reverse()
+}
+
+/** Rules declared on the fields that contain `node`, nearest first. CEL rules
+ *  and oneOf/anyOf constraints on a parent often decide whether a field's value
+ *  is accepted, so a field found by search has to show them too. */
+export function enclosingRules(node: SchemaNode, root: CRDSchema): EnclosingRules[] {
+  const result: EnclosingRules[] = []
+  for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+    result.push(...rulesOf(ancestor.schema, displaySchemaPath(ancestor.path)))
+  }
+  result.push(...rulesOf(root, ''))
+  return result
+}
+
+/** The schema an array or map holds, whose constraints belong to the field. */
+export function schemaElement(schema: CRDSchema): { label: 'items' | 'values'; schema: CRDSchema } | undefined {
+  if (schema.items) return { label: 'items', schema: schema.items }
+  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') return { label: 'values', schema: schema.additionalProperties }
+  return undefined
+}
+
+export function schemaLeafName(path: SchemaPath): string {
+  for (let i = path.length - 1; i >= 0; i--) if (path[i].kind === 'property') return path[i].name
+  return ''
+}
+
+/** Display path of everything above the leaf property, with its trailing dot. */
+export function schemaParentPath(path: SchemaPath): string {
+  let leaf = path.length - 1
+  while (leaf >= 0 && path[leaf].kind !== 'property') leaf--
+  const parent = displaySchemaPath(path.slice(0, leaf))
+  return parent ? `${parent}.` : ''
+}
+
+// A property name that would read as path syntax is quoted, so a literal
+// `a.b` key and a nested `a` → `b` never display alike.
+function displayPropertyName(name: string): string {
+  return /^[A-Za-z0-9_$@-]+$/.test(name) ? name : `[${JSON.stringify(name)}]`
+}
+
+export function displaySchemaPath(path: SchemaPath): string {
+  return path.map((segment, i) => {
+    if (segment.kind !== 'property') return segment.name
+    const name = displayPropertyName(segment.name)
+    return name.startsWith('[') || i === 0 ? name : `.${name}`
+  }).join('')
+}
+
+const EXTENSION_FACTS: [key: string, label: string][] = [
+  ['x-kubernetes-list-type', 'list type'],
+  ['x-kubernetes-list-map-keys', 'list keys'],
+  ['x-kubernetes-map-type', 'map type'],
+]
+
+export function schemaConstraints(schema: CRDSchema): { label: string; value: string }[] {
+  const extensions = EXTENSION_FACTS
+    .filter(([key]) => schema[key] !== undefined)
+    .map(([key, label]) => ({ label, value: Array.isArray(schema[key]) ? (schema[key] as unknown[]).join(', ') : String(schema[key]) }))
+  return [...extensions, ...['format', 'enum', 'default', 'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
+    'minLength', 'maxLength', 'pattern', 'minItems', 'maxItems', 'uniqueItems', 'minProperties', 'maxProperties', 'nullable']
+    .filter(key => schema[key] !== undefined)
+    .map(key => ({ label: key, value: key === 'enum' && Array.isArray(schema.enum) ? schema.enum.map(v => typeof v === 'string' ? v : JSON.stringify(v)).join(' · ')
+      : typeof schema[key] === 'string' ? schema[key] as string : JSON.stringify(schema[key]) }))]
+}
+
+export function schemaCompositions(schema: CRDSchema): { label: string; value: string }[] {
+  return (['oneOf', 'anyOf', 'allOf', 'not'] as const).flatMap(key => {
+    const value = schema[key]
+    if (!value) return []
+    const alternatives = Array.isArray(value) ? value : [value]
+    const requiredOnly = alternatives.every(v => v.required?.length && Object.keys(v).every(k => k === 'required'))
+    return [{ label: key === 'oneOf' && requiredOnly ? 'One of' : key,
+      value: requiredOnly ? alternatives.map(v => v.required!.join(' + ')).join(' · ') : JSON.stringify(value) }]
+  })
+}
+
+export function indexCRDSchema(schema: CRDSchema | undefined): SchemaNode[] {
+  if (!schema) return []
+  const result: SchemaNode[] = []
+  const stack = schemaChildren(schema).reverse()
+  while (stack.length) {
+    const node = stack.pop()!
+    result.push(node)
+    stack.push(...schemaChildren(node.schema, node.path, node).reverse())
+  }
+  return result
+}
+
+// Paths in API server errors and kubectl output index into lists and maps
+// (`spec.ports[0].name`, `metadata.labels[app]`), and people often leave the
+// brackets out entirely. Matching ignores both so a pasted path still finds its field.
+function matchablePath(path: string): string {
+  return path.toLowerCase().replace(/\[(?!")[^\]]*\]|\{\}/g, '').replace(/\.{2,}/g, '.')
+}
+
+export function filterCRDSchema(index: SchemaNode[], query: string, limit = 200): { nodes: SchemaNode[]; total: number } {
+  const term = query.trim().toLowerCase()
+  const looseTerm = matchablePath(term)
+  // The field the query names exactly leads, so the cap can never hide it.
+  const exact: SchemaNode[] = []
+  const nodes: SchemaNode[] = []
+  let total = 0
+  for (const node of index) {
+    const display = displaySchemaPath(node.path).toLowerCase()
+    const loose = matchablePath(display)
+    if (!display.includes(term) && !(looseTerm && loose.includes(looseTerm))) continue
+    total++
+    if (display === term || loose === looseTerm) exact.push(node)
+    else if (nodes.length < limit) nodes.push(node)
+  }
+  return { nodes: [...exact, ...nodes].slice(0, limit), total }
+}

package/src/utils/format.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { formatCompactAge, formatCPUString, formatMemoryString, formatRelativeAgeTime, parseMemoryToBytes, parseQuantityToNumber } from './format'
+import { formatCompactAge, formatCPUString, formatMemoryString, formatRelativeAgeTime, parseCPUToNanocores, parseMemoryToBytes, parseQuantity, parseQuantityToNumber } from './format'
 
 describe('formatCPUString', () => {
   it('renders exact zero as zero, not a fabricated near-zero', () => {
@@ -169,3 +169,39 @@ describe('relative ages', () => {
     expect(formatRelativeAgeTime('not a time')).toBe('not a time')
   })
 })
+
+describe('parseCPUToNanocores', () => {
+  it.each([
+    ['', 0],
+    ['2', 2_000_000_000],
+    ['1.5', 1_500_000_000],
+    ['.5', 500_000_000],
+    ['1.', 1_000_000_000],
+    ['250m', 250_000_000],
+    ['98753000n', 98_753_000],
+    // metrics-server's shortest exact form for the same reading
+    ['98753u', 98_753_000],
+    ['2k', 2_000_000_000_000],
+    ['garbage', 0],
+  ])('%s -> %d', (input, want) => {
+    expect(parseCPUToNanocores(input)).toBe(want)
+  })
+})
+
+describe('parseQuantity', () => {
+  it.each([
+    ['+1Gi', 1024 ** 3],
+    ['.5Ki', 512],
+    ['-.5', -0.5],
+    ['1.e3', 1000],
+    ['0', 0],
+  ])('%s -> %d', (input, want) => {
+    expect(parseQuantity(input)).toBe(want)
+    expect(parseMemoryToBytes(input)).toBe(want)
+  })
+
+  it.each(['', 'abcMi', '.', '1.2.3', '5Xi', null, undefined])('cannot read %s', (input) => {
+    expect(parseQuantity(input)).toBeNull()
+    expect(parseQuantityToNumber(input)).toBe(0)
+  })
+})