@skyhook-io/radar-app 1.16.2 → 1.17.0

package/src/components/traffic/trafficFilters.ts

@@ -1,4 +1,6 @@
 import type { AggregatedFlow, TrafficFlow } from '../../types'
+import type { TrafficEndpointPair, TrafficEndpointRef, TrafficMatch } from '../../api/traffic'
+import type { TrafficGraphSelection } from './TrafficGraph'
 
 /**
  * Does a flow fall into one of the selected HTTP status ranges?
@@ -136,6 +138,19 @@ export function mergeFlowVolume(into: AggregatedFlow, flow: AggregatedFlow): voi
   if (flow.errorCount) into.errorCount = (into.errorCount || 0) + flow.errorCount
   if (flow.requestRate) into.requestRate = (into.requestRate || 0) + flow.requestRate
   if (flow.errorRate) into.errorRate = (into.errorRate || 0) + flow.errorRate
+  // New objects rather than in-place sums: a merged edge starts as a shallow
+  // copy of the server's, so its maps are still the server's.
+  into.httpStatusCounts = sumCounts(into.httpStatusCounts, flow.httpStatusCounts)
+  into.verdictCounts = sumCounts(into.verdictCounts, flow.verdictCounts)
+  into.dropReasons = sumCounts(into.dropReasons, flow.dropReasons)
+}
+
+function sumCounts(a: Record<string, number> | undefined, b: Record<string, number> | undefined): Record<string, number> | undefined {
+  if (!b) return a
+  if (!a) return { ...b }
+  const sum = { ...a }
+  for (const [k, v] of Object.entries(b)) sum[k] = (sum[k] ?? 0) + v
+  return sum
 }
 
 /**
@@ -287,3 +302,396 @@ export function dedupeHTTPPairs(flows: TrafficFlow[], callerOriented: boolean):
   }
   return flows.filter(f => !(isHTTP(f, 'REQUEST') && answered.has(call(f.source.name, f.destination.name, f))))
 }
+
+/**
+ * A graph edge, carrying the server edges merged into it. The graph renames and
+ * merges endpoints (external services, the Internet node, the addon group), so
+ * these are what a selection is traced back through to ask the server for its
+ * records.
+ */
+export type GraphFlow = AggregatedFlow & { rawPairs?: TrafficEndpointPair[] }
+
+/**
+ * The port an edge merged from several shows: its lowest real one, whatever
+ * order the parts arrived in (0 means none was reported, so it shows only
+ * when no part has a port). The Internet node groups by it and selections
+ * find the edge by it, so it must not change from one refresh to the next.
+ */
+export function mergedEdgePort(a: number, b: number): number {
+  if (a === 0) return b
+  if (b === 0) return a
+  return Math.min(a, b)
+}
+
+/**
+ * Whether an edge carries a port: its own, or one of the edges merged into it.
+ * A merged edge shows one of its ports, so a selection made on another must
+ * still find it.
+ */
+export function edgeCarriesPort(flow: GraphFlow, port: number | undefined): boolean {
+  return port === undefined || flow.port === port || !!flow.rawPairs?.some(p => p.port === port)
+}
+
+/**
+ * Of the edges between a selection's endpoints, the ones it means: those on
+ * its exact port when any are, else those with the port merged in. Two edges
+ * can join the same endpoints (the Internet node keeps ports apart), and the
+ * one shown on a port must win over one that merely carries it.
+ */
+export function edgesOnPort<T>(candidates: T[], flowOf: (c: T) => GraphFlow | undefined, port: number | undefined): T[] {
+  if (port === undefined) return candidates
+  const exact = candidates.filter(c => flowOf(c)?.port === port)
+  if (exact.length > 0) return exact
+  return candidates.filter(c => {
+    const flow = flowOf(c)
+    return !!flow && edgeCarriesPort(flow, port)
+  })
+}
+
+export function endpointPair(flow: AggregatedFlow): TrafficEndpointPair {
+  const ref = (e: AggregatedFlow['source']) => ({
+    namespace: e.namespace || undefined,
+    name: e.name,
+    kind: e.kind,
+    ...(e.workloadKind && { workloadKind: e.workloadKind }),
+  })
+  return {
+    source: ref(flow.source),
+    destination: ref(flow.destination),
+    port: flow.port,
+    ...(flow.directionUnknown && { directionUnknown: true }),
+  }
+}
+
+/** Adds a merged edge's pairs to the edge it was merged into. The target owns
+ *  its array, so merging appends in place: copying it on every merge is
+ *  quadratic, and an ingress with tens of thousands of distinct clients
+ *  collapses into a single Internet edge. */
+export function mergeRawPairs(into: GraphFlow, from: GraphFlow): void {
+  const target = into.rawPairs ?? (into.rawPairs = [])
+  for (const pair of from.rawPairs ?? []) target.push(pair)
+}
+
+// The renderer draws the addon group's virtual endpoints as one group node.
+function selectableId(e: { namespace?: string; name: string; kind?: string }): string {
+  if (e.kind === 'AddonGroupTarget' || e.kind === 'AddonGroupSource') return 'addon-group'
+  return graphEndpointId(e)
+}
+
+/**
+ * A record's endpoint as the graph names it: a pod with a known workload is
+ * drawn as that workload. Mirrors the server's graphEndpoint (pkg/traffic),
+ * which builds the aggregation the graph is drawn from — the two have to agree
+ * for a record to be found under its node.
+ */
+export function graphEndpoint(e: TrafficFlow['source']): { namespace?: string; name: string } {
+  if (e.kind === 'Pod' && e.workload && e.namespace && e.workload !== e.name) return { namespace: e.namespace, name: e.workload }
+  return e
+}
+
+export function graphEndpointId(e: { namespace?: string; name: string }): string {
+  return e.namespace ? `${e.namespace}/${e.name}` : e.name
+}
+
+export function pairKey(source: { namespace?: string; name: string }, destination: { namespace?: string; name: string }, port: number, directionUnknown?: boolean): string {
+  return `${graphEndpointId(source)}->${graphEndpointId(destination)}:${port}${directionUnknown ? ':u' : ''}`
+}
+
+/**
+ * Whether a record belongs to the selected edges, in the grouping the graph
+ * draws (`drawn`). Without `responsesCallerOriented` the server sends an HTTP
+ * response as it was observed, server to client on the client's port, so a
+ * response is then also matched to an edge running the other way. Its port says nothing about which of the
+ * caller's edges it answers, so it is matched to each of them; other traffic
+ * between the same endpoints is not, being on edges of its own.
+ */
+export function selectedEdgeMatcher(
+  pairs: TrafficEndpointPair[] | null,
+  responsesCallerOriented: boolean,
+  drawn: (e: TrafficFlow['source']) => { namespace?: string; name: string },
+): (f: TrafficFlow) => boolean {
+  if (!pairs) return () => true
+  const keys = new Set(pairs.map(p => pairKey(p.source, p.destination, p.port, p.directionUnknown)))
+  const callers = responsesCallerOriented ? null : new Set(pairs.map(p => `${graphEndpointId(p.source)}->${graphEndpointId(p.destination)}`))
+  return f => {
+    const src = drawn(f.source)
+    const dst = drawn(f.destination)
+    if (keys.has(pairKey(src, dst, f.port, f.directionUnknown))) return true
+    // The response travels callee to caller: reversed, it is the edge's.
+    return !!callers && f.l7Protocol === 'HTTP' && f.l7Type === 'RESPONSE' &&
+      callers.has(`${graphEndpointId(dst)}->${graphEndpointId(src)}`)
+  }
+}
+
+/**
+ * The server edges behind the selected node or edge, deduplicated and in a
+ * stable order — the server returns its aggregation in no particular order,
+ * and the result keys the records query. Null when the selection traces back
+ * to none. `inAddonGroup` says which endpoints the addon group node holds
+ * while addons are grouped, so selecting the group selects their traffic too.
+ */
+export function selectionRawPairs(
+  flows: GraphFlow[],
+  selection: TrafficGraphSelection | null,
+  inAddonGroup?: (e: { namespace?: string; name: string }) => boolean,
+): TrafficEndpointPair[] | null {
+  if (!selection) return null
+  const pairs = new Map<string, TrafficEndpointPair>()
+  const groupId = (e: GraphFlow['source']) =>
+    inAddonGroup && selection.nodeId === 'addon-group' && inAddonGroup(e) ? 'addon-group' : selectableId(e)
+  const touching = flows.filter(flow => {
+    const sourceId = groupId(flow.source)
+    const destId = groupId(flow.destination)
+    return selection.type === 'node'
+      ? sourceId === selection.nodeId || destId === selection.nodeId
+      : sourceId === selection.sourceId && destId === selection.destId &&
+        !!flow.directionUnknown === !!selection.directionUnknown
+  })
+  // An edge stands for its port; an edge merged from several ports shows one
+  // of them and carries the rest (edgesOnPort).
+  const selected = selection.type === 'node' ? touching : edgesOnPort(touching, f => f, selection.port)
+  for (const flow of selected) {
+    for (const pair of flow.rawPairs ?? []) {
+      pairs.set(pairKey(pair.source, pair.destination, pair.port, pair.directionUnknown), pair)
+    }
+  }
+  if (pairs.size === 0) return null
+  return Array.from(pairs.entries()).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, pair]) => pair)
+}
+
+/**
+ * What to ask the server for, for the records behind a selection traced to
+ * `pairs` (selectionRawPairs). A node that is one server endpoint is sent as
+ * that endpoint: a busy node has too many edges to name each within a URL.
+ * The answer then holds its hidden edges too, so the caller keeps the pairs
+ * to narrow it. Anything else — an edge, a node merged from several
+ * endpoints — is sent as its edges.
+ */
+export function selectionMatch(
+  pairs: TrafficEndpointPair[] | null,
+  selection: TrafficGraphSelection | null,
+): TrafficMatch | null {
+  if (!pairs) return null
+  if (selection?.type !== 'node') return { pairs }
+  const refKey = (r: TrafficEndpointRef) => `${graphEndpointId(r)}|${r.kind ?? ''}`
+  // Only pods can be named to the source; any other endpoint sent alone would
+  // fetch everything, while its edges still name the pods at their far ends.
+  const nameable = (r: TrafficEndpointRef) => r.kind === 'Pod' || r.kind === 'Workload'
+  let only: TrafficEndpointRef | undefined
+  for (const p of pairs) {
+    const side = graphEndpointId(p.source) === selection.nodeId ? p.source
+      : graphEndpointId(p.destination) === selection.nodeId ? p.destination
+        : undefined
+    if (!side || !nameable(side) || (only && refKey(side) !== refKey(only))) return { pairs }
+    only = side
+  }
+  return only ? { endpoints: [only] } : { pairs }
+}
+
+/**
+ * How costly the graph is to draw. The layout runs on the main thread and its
+ * cost grows faster than linearly, edges more than nodes, so edges count
+ * double, as Weave Scope weighs them. Laying out whole namespaces of a dense
+ * service graph took 0.55s at a score of 493, 2s at 728, 4.5s at 1,433, 13s
+ * at 1,883 and 32s at 2,329; larger graphs overflowed ELK's stack.
+ */
+export function graphSize(flows: AggregatedFlow[]): { nodes: number; edges: number; score: number } {
+  const nodes = new Set<string>()
+  for (const flow of flows) {
+    nodes.add(graphEndpointId(flow.source))
+    nodes.add(graphEndpointId(flow.destination))
+  }
+  return { nodes: nodes.size, edges: flows.length, score: nodes.size + 2 * flows.length }
+}
+
+/** Above this the graph is not drawn until the view is narrowed (about 1.5s of layout). */
+export const GRAPH_DRAW_BUDGET = 600
+/** Above this it is not drawn at all (about 5s of layout, freezing the tab). */
+export const GRAPH_DRAW_CEILING = 1500
+
+/** 5xx responses on an edge: counted where the source observes responses,
+ *  a per-second rate where it measures one. */
+export function flowErrors(flow: AggregatedFlow): number {
+  return flow.httpStatusCounts?.['5xx'] || errorRateOf(flow)
+}
+
+export function flowDrops(flow: AggregatedFlow): number {
+  return flow.verdictCounts?.dropped ?? 0
+}
+
+/** Whether this edge carries HTTP responses, so its 5xx count is a measured
+ *  zero rather than unknown; plain TCP has none. Zero rates and counts are left
+ *  out of the response, so a healthy HTTP edge shows only by its requests or
+ *  protocol. */
+export function hasStatusData(flow: AggregatedFlow): boolean {
+  return (!!flow.httpStatusCounts && Object.keys(flow.httpStatusCounts).length > 0) ||
+    !!flow.requestRate || !!flow.requestCount || !!flow.errorRate || !!flow.errorCount ||
+    flow.l7Protocol === 'HTTP' || flow.l7Protocol === 'gRPC'
+}
+
+/**
+ * A workload (or any endpoint) the view is narrowed to: it and everything it
+ * talks to. Identified by namespace and name, the way the graph names nodes,
+ * so it means the same thing whether pods are grouped or not — ungrouped, it
+ * is the pods the workload owns.
+ */
+export interface TrafficFocus {
+  namespace?: string
+  name: string
+}
+
+/** The focus as the URL carries it: "ns/name", or "/name" for an endpoint
+ *  with no namespace, whose name can itself hold a slash (a CIDR). */
+export function focusParam(focus: TrafficFocus): string {
+  return `${focus.namespace ?? ''}/${focus.name}`
+}
+
+export function parseFocus(value: string | null): TrafficFocus | null {
+  if (!value) return null
+  const slash = value.indexOf('/')
+  if (slash < 0) return null
+  const namespace = value.slice(0, slash)
+  const name = value.slice(slash + 1)
+  if (!name) return null
+  return namespace ? { namespace, name } : { name }
+}
+
+/** The graph's id for the focused node. */
+export function focusId(focus: TrafficFocus): string {
+  return graphEndpointId(focus)
+}
+
+export function touchesFocus(e: AggregatedFlow['source'], focus: TrafficFocus): boolean {
+  if ((e.namespace || undefined) !== focus.namespace) return false
+  return e.name === focus.name || (e.kind === 'Pod' && e.workload === focus.name)
+}
+
+/** The edges with the focus at either end. */
+export function focusNeighborhood<T extends AggregatedFlow>(flows: T[], focus: TrafficFocus): T[] {
+  return flows.filter(f => touchesFocus(f.source, focus) || touchesFocus(f.destination, focus))
+}
+
+export interface EndpointSummary {
+  id: string
+  name: string
+  namespace?: string
+  kind: string
+  workloadKind?: string
+  volume: number
+  errors: number
+  drops: number
+}
+
+/** Every endpoint drawn from these flows, with the traffic on its edges. The
+ *  options a focus can be chosen from, so each one has something to show.
+ *  Pods drawn ungrouped also offer their workload, which a focus covers whole. */
+export function endpointSummaries(flows: AggregatedFlow[]): EndpointSummary[] {
+  const byId = new Map<string, EndpointSummary>()
+  const add = (e: { namespace?: string; name: string; kind: string; workloadKind?: string }, flow: AggregatedFlow, seen: Set<string>) => {
+    const id = graphEndpointId(e)
+    if (seen.has(id)) return
+    seen.add(id)
+    let s = byId.get(id)
+    if (!s) {
+      s = { id, name: e.name, namespace: e.namespace || undefined, kind: e.kind, workloadKind: e.workloadKind, volume: 0, errors: 0, drops: 0 }
+      byId.set(id, s)
+    }
+    s.volume += flow.connections
+    s.errors += flowErrors(flow)
+    s.drops += flowDrops(flow)
+  }
+  for (const flow of flows) {
+    const seen = new Set<string>()
+    for (const e of [flow.source, flow.destination]) {
+      add(e, flow, seen)
+      if (e.kind === 'Pod' && e.namespace && e.workload && e.workload !== e.name) {
+        add({ namespace: e.namespace, name: e.workload, kind: 'Workload', workloadKind: e.workloadKind }, flow, seen)
+      }
+    }
+  }
+  return Array.from(byId.values())
+}
+
+/** Where the problems are first, then the busiest. */
+export function byProblemsThenVolume(a: { errors: number; drops: number; volume: number }, b: { errors: number; drops: number; volume: number }): number {
+  const pa = a.errors > 0 || a.drops > 0 ? 1 : 0
+  const pb = b.errors > 0 || b.drops > 0 ? 1 : 0
+  if (pa !== pb) return pb - pa
+  if (a.drops + a.errors !== b.drops + b.errors) return b.drops + b.errors - (a.drops + a.errors)
+  return b.volume - a.volume
+}
+
+/**
+ * Search results for a query: a name that starts with the query before one
+ * that only contains it, and within each, problems first, then volume.
+ */
+export function searchEndpoints(summaries: EndpointSummary[], query: string, limit = 50): EndpointSummary[] {
+  const q = query.trim().toLowerCase()
+  const rank = (s: EndpointSummary) => {
+    if (!q) return 1
+    const name = s.name.toLowerCase()
+    if (name === q) return 0
+    if (name.startsWith(q)) return 1
+    if (name.includes(q)) return 2
+    if (s.id.toLowerCase().includes(q)) return 3
+    return -1
+  }
+  return summaries
+    .map(s => ({ s, r: rank(s) }))
+    .filter(x => x.r >= 0)
+    .sort((a, b) => a.r - b.r || byProblemsThenVolume(a.s, b.s))
+    .slice(0, limit)
+    .map(x => x.s)
+}
+
+export interface NamespaceSummary {
+  name: string
+  endpoints: number
+  connections: number
+  volume: number
+  errors: number
+  drops: number
+}
+
+/**
+ * Per namespace, what narrowing to it would show. Narrowing keeps an edge
+ * when either end is in the namespace, as the server does, so a cross-namespace
+ * edge counts toward both of its namespaces, and its far end toward the
+ * namespace's endpoints.
+ */
+/** Whether the namespace's own view — its edges, with either end in it — would
+ *  be over the draw budget, judged from the traffic already fetched. Picking it
+ *  fetches that namespace on its own, which can bring in more. */
+export function namespaceOverBudget(ns: NamespaceSummary): boolean {
+  return ns.endpoints + 2 * ns.connections > GRAPH_DRAW_BUDGET
+}
+
+export function namespaceSummaries(flows: AggregatedFlow[]): NamespaceSummary[] {
+  const byNs = new Map<string, { endpoints: Set<string>; connections: number; volume: number; errors: number; drops: number }>()
+  for (const flow of flows) {
+    const namespaces = new Set([flow.source.namespace, flow.destination.namespace].filter(Boolean))
+    for (const ns of namespaces) {
+      let s = byNs.get(ns)
+      if (!s) {
+        s = { endpoints: new Set(), connections: 0, volume: 0, errors: 0, drops: 0 }
+        byNs.set(ns, s)
+      }
+      s.endpoints.add(graphEndpointId(flow.source))
+      s.endpoints.add(graphEndpointId(flow.destination))
+      s.connections += 1
+      s.volume += flow.connections
+      s.errors += flowErrors(flow)
+      s.drops += flowDrops(flow)
+    }
+  }
+  return Array.from(byNs.entries())
+    .map(([name, s]) => ({ name, endpoints: s.endpoints.size, connections: s.connections, volume: s.volume, errors: s.errors, drops: s.drops }))
+    .sort((a, b) => byProblemsThenVolume(a, b) || a.name.localeCompare(b.name))
+}
+
+/** The edges as table rows, problems first, then volume. */
+export function connectionRows<T extends AggregatedFlow>(flows: T[]): T[] {
+  const keyed = flows.map(flow => ({ flow, errors: flowErrors(flow), drops: flowDrops(flow), volume: flow.connections }))
+  keyed.sort(byProblemsThenVolume)
+  return keyed.map(k => k.flow)
+}

package/src/components/whats-new/WhatsNew.test.ts

@@ -1,50 +1,125 @@
 import { describe, expect, it } from 'vitest'
 import { Megaphone } from 'lucide-react'
-import { nextSeenVersion, whatsNewToShow } from './WhatsNew'
-import { latestReleaseNotesFor, releaseLine, RELEASE_NOTES, releaseNotesFor, type ReleaseNotes } from './releaseNotes'
+import { nextSeenVersion, whatsNewToOpen } from './WhatsNew'
+import {
+  AUTO_OPEN_SCORE,
+  composeReleaseNotes,
+  latestReleaseNotesFor,
+  MAX_CARDS,
+  MAX_LINES,
+  releaseLine,
+  RELEASE_NOTES,
+  releaseNotesFor,
+  unreadReleases,
+  type ReleaseNotes,
+} from './releaseNotes'
 import { compareVersions } from '../../utils/version'
 
-const entry = (version: string): ReleaseNotes => ({
+const highlight = (id: string, importance: number) => ({ id, icon: Megaphone, title: id, description: 'd', importance })
+
+const entry = (version: string, importances: number[] = [9, 9, 9], improvements: string[] = []): ReleaseNotes => ({
   version,
-  releaseUrl: 'https://github.com/skyhook-io/radar/releases',
-  highlights: [{ id: 'x', icon: Megaphone, title: 'X', description: 'Y' }],
-  improvements: [],
+  highlights: importances.map((importance, i) => highlight(`${version}-${i}`, importance)),
+  improvements,
 })
 
 const catalog = [entry('v1.15.0'), entry('v2.0.0')]
 
-const show = (current: string, lastSeen: string | null, prior = true) =>
-  whatsNewToShow(current, lastSeen, prior, catalog)?.version ?? null
+const unread = (current: string, lastSeen: string | null, prior = true, list = catalog) =>
+  unreadReleases(current, lastSeen, prior, list).map(n => n.version)
 
-describe('whatsNewToShow', () => {
-  it('shows when the notes are newer than the last version seen', () => {
-    expect(show('v2.0.0', 'v1.15.0')).toBe('v2.0.0')
-    expect(show('v2.0.0', 'v2.0.0')).toBeNull()
-    expect(show('2.0.0', 'v2.0.0')).toBeNull()
+describe('unreadReleases', () => {
+  it('lists the releases after the last one seen, newest first', () => {
+    expect(unread('v2.0.0', 'v1.14.0')).toEqual(['v2.0.0', 'v1.15.0'])
+    expect(unread('v2.0.0', 'v1.15.0')).toEqual(['v2.0.0'])
+    expect(unread('v2.0.0', 'v2.0.0')).toEqual([])
+    expect(unread('2.0.0', 'v2.0.0')).toEqual([])
   })
 
-  it('shows the newest earlier notes when the running release has none of its own', () => {
-    expect(show('v1.15.1', 'v1.14.1')).toBe('v1.15.0')
-    expect(show('v2.3.4', 'v1.15.2')).toBe('v2.0.0')
+  it('covers a patch of a release with notes, and nothing above the running version', () => {
+    expect(unread('v1.15.1', 'v1.14.1')).toEqual(['v1.15.0'])
+    expect(unread('v2.3.4', 'v1.15.2')).toEqual(['v2.0.0'])
   })
 
-  it('stays closed once a later release was seen, including after a downgrade', () => {
-    expect(show('v1.15.2', 'v1.15.1')).toBeNull()
-    expect(show('v1.15.0', 'v2.0.0')).toBeNull()
+  it('is empty once a later release was seen, including after a downgrade', () => {
+    expect(unread('v1.15.2', 'v1.15.1')).toEqual([])
+    expect(unread('v1.15.0', 'v2.0.0')).toEqual([])
   })
 
-  it('stays closed on a fresh install, and shows for installs that predate the seen record', () => {
-    expect(show('v2.0.0', null, false)).toBeNull()
-    expect(show('v2.0.0', null, true)).toBe('v2.0.0')
+  it('is empty on a fresh install, and covers everything for installs that predate the seen record', () => {
+    expect(unread('v2.0.0', null, false)).toEqual([])
+    expect(unread('v2.0.0', null, true)).toEqual(['v2.0.0', 'v1.15.0'])
   })
 
   it('treats a record that is not a version as an install with nothing seen', () => {
-    expect(show('v2.0.0', 'vdev', false)).toBe('v2.0.0')
+    expect(unread('v2.0.0', 'vdev', false)).toEqual(['v2.0.0', 'v1.15.0'])
+  })
+
+  it('is empty when no notes exist at or below the running version', () => {
+    expect(unread('v1.14.9', 'v1.14.0')).toEqual([])
+    expect(unread('dev', 'v1.14.1')).toEqual([])
+  })
+
+  it('orders by version whatever the catalog order', () => {
+    expect(unread('v2.0.0', null, true, [entry('v1.15.0'), entry('v2.0.0'), entry('v1.16.0')])).toEqual(['v2.0.0', 'v1.16.0', 'v1.15.0'])
+  })
+})
+
+describe('composeReleaseNotes', () => {
+  it('ranks highlights by importance, weighting older releases down', () => {
+    const notes = composeReleaseNotes([entry('v1.17.0', [6]), entry('v1.16.0', [9]), entry('v1.15.0', [10])])
+    expect(notes.highlights.map(h => [h.id, h.score])).toEqual([
+      ['v1.16.0-0', 6.75],
+      ['v1.17.0-0', 6],
+      ['v1.15.0-0', 5],
+    ])
+  })
+
+  it('breaks ties toward the newer release, then the authored order', () => {
+    const notes = composeReleaseNotes([entry('v1.16.0', [3, 6]), entry('v1.15.0', [8])])
+    expect(notes.highlights.map(h => h.id)).toEqual(['v1.16.0-1', 'v1.15.0-0', 'v1.16.0-0'])
+  })
+
+  it('keeps the authored order of a single release with equal importance', () => {
+    expect(composeReleaseNotes([entry('v1.16.0', [5, 5, 5])]).highlights.map(h => h.id)).toEqual(['v1.16.0-0', 'v1.16.0-1', 'v1.16.0-2'])
+  })
+
+  it('shows at most three releases and says when older ones were left out', () => {
+    const four = [entry('v1.18.0'), entry('v1.17.0'), entry('v1.16.0'), entry('v1.15.0')]
+    const notes = composeReleaseNotes(four)
+    expect(notes.versions).toEqual(['v1.18.0', 'v1.17.0', 'v1.16.0'])
+    expect(notes.complete).toBe(false)
+    expect(notes.highlights.some(h => h.version === 'v1.15.0')).toBe(false)
+    expect(composeReleaseNotes(four.slice(0, 3)).complete).toBe(true)
+  })
+
+  it('turns highlights past the cards into lines ahead of the improvements, within the line cap', () => {
+    const notes = composeReleaseNotes([
+      entry('v1.16.0', [7, 7, 7, 7, 7, 2], ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']),
+      entry('v1.15.0', [1], ['old']),
+    ])
+    expect(notes.highlights).toHaveLength(MAX_CARDS)
+    expect(notes.lines).toHaveLength(MAX_LINES)
+    expect(notes.lines.slice(0, 2).map(l => l.text)).toEqual(['v1.16.0-5', 'v1.15.0-0'])
+    expect(notes.lines.map(l => l.text)).not.toContain('old')
+  })
+
+  it('scores the dialog by the cards it shows', () => {
+    expect(composeReleaseNotes([entry('v1.16.0', [4, 4, 4, 4, 4, 10])]).score).toBe(10 + 4 * 4)
+  })
+})
+
+describe('whatsNewToOpen', () => {
+  it('opens when the unseen releases show enough, and not for a quiet release', () => {
+    const list = [entry('v1.15.0', [9, 8, 7, 7, 7]), entry('v1.16.0', [6, 5, 4])]
+    expect(whatsNewToOpen('v1.15.0', 'v1.14.1', true, list)?.score).toBe(38)
+    expect(whatsNewToOpen('v1.16.0', 'v1.15.0', true, list)).toBeNull()
+    expect(whatsNewToOpen('v1.16.0', 'v1.14.1', true, list)?.score).toBeGreaterThanOrEqual(AUTO_OPEN_SCORE)
   })
 
-  it('stays closed when no notes exist at or below the running version', () => {
-    expect(show('v1.14.9', 'v1.14.0')).toBeNull()
-    expect(show('dev', 'v1.14.1')).toBeNull()
+  it('stays closed when nothing is unseen', () => {
+    expect(whatsNewToOpen('v2.0.0', 'v2.0.0', true, catalog)).toBeNull()
+    expect(whatsNewToOpen('v2.0.0', null, false, catalog)).toBeNull()
   })
 })
 
@@ -91,13 +166,17 @@ describe('the shipped catalog', () => {
     expect(new Set(versions).size).toBe(versions.length)
     for (const notes of RELEASE_NOTES) {
       expect(notes.version, notes.version).toMatch(/^v\d+\.\d+\.\d+$/)
-      expect(notes.highlights.length, `${notes.version} needs a lead highlight`).toBeGreaterThan(0)
+      expect(notes.highlights.length, `${notes.version} needs a highlight`).toBeGreaterThan(0)
       expect(new Set(notes.highlights.map(h => h.id)).size, `${notes.version} highlight ids`).toBe(notes.highlights.length)
+      expect(new Set(notes.improvements).size, `${notes.version} improvements`).toBe(notes.improvements.length)
+      const top = notes.highlights.reduce((best, h) => (h.importance > best.importance ? h : best))
       for (const h of notes.highlights) {
+        expect(h.description.length, `${notes.version}/${h.id}: description fits a card`).toBeLessThanOrEqual(150)
+        if (h.leadDescription) expect(h.id, `${notes.version}/${h.id}: only the release's top highlight can lead`).toBe(top.id)
+        expect(Number.isInteger(h.importance) && h.importance >= 1 && h.importance <= 10, `${notes.version}/${h.id}: importance is 1-10`).toBe(true)
         expect(!!h.path === !!h.cta, `${notes.version}/${h.id}: path and cta go together`).toBe(true)
         if (h.path) expect(h.path, `${notes.version}/${h.id}`).toMatch(/^\//)
       }
-      expect(notes.releaseUrl, notes.version).toMatch(/^https:\/\//)
     }
   })
 })