summaryrefslogtreecommitdiff
path: root/plugins/code-modernization/hooks/map
diff options
context:
space:
mode:
authorClaude <noreply@anthropic.com>2026-11-06 00:54:48 +0000
committerClaude <noreply@anthropic.com>2026-11-06 00:54:48 +0000
commit7aba3deae3ff17d032c37e07d2929d1426b34278 (patch)
tree9c482f9acda1599bd2f9bed95a6a46b75e634e80 /plugins/code-modernization/hooks/map
parent5472f5f56e0070feeeb464318b316714fe3e9105 (diff)
parentb8331dd69ab3e132bbf8cd6e89b5d8c1747e21b1 (diff)
Merge remote-tracking branch 'origin/main' into add-plugin/xcodeadd-plugin/xcode
Diffstat (limited to 'plugins/code-modernization/hooks/map')
-rw-r--r--plugins/code-modernization/hooks/map/estate.ts258
-rw-r--r--plugins/code-modernization/hooks/map/raster.ts92
-rw-r--r--plugins/code-modernization/hooks/map/treemap.ts156
3 files changed, 506 insertions, 0 deletions
diff --git a/plugins/code-modernization/hooks/map/estate.ts b/plugins/code-modernization/hooks/map/estate.ts
new file mode 100644
index 00000000..c57f19a2
--- /dev/null
+++ b/plugins/code-modernization/hooks/map/estate.ts
@@ -0,0 +1,258 @@
+import { estateOfTopology, languageOf, type EstateUnit } from '../reader/estate-model'
+import type { ModuleState } from '../reader/modernized'
+import type { Snapshot } from '../reader/progress'
+import { STATE_WORDS_BY_TRACK, type TrackKey } from '../reader/tracks'
+import { DEFAULT_COLOR, luma, mix, packCells, type Cell } from './raster'
+import { layoutGroups, type Rect } from './treemap'
+
+/**
+ * The estate map: every unit of the legacy system as a tile, sized by its lines of code
+ * (or bytes of source, where there is no map), grouped by domain or directory, coloured by
+ * how far its modernization has come, and lit for a moment when a file beneath it is read or written.
+ */
+
+export type TouchKind = 'read' | 'write'
+
+export type Touch = { atMs: number; kind: TouchKind }
+
+export type TileState = ModuleState | 'untouched'
+
+/** A module's verdict, as the map marks it: a tile's label starts with the mark. */
+export type TileProof = 'proven' | 'partly' | 'not'
+
+export const PROOF_MARKS: Record<TileProof, string> = { proven: '✓', partly: '±', not: '✗' }
+
+export type Tile = {
+ id: string
+ name: string
+ /** What the tile shows of its name: the last path segment, without its extension and without the prefix most tiles share. */
+ label: string
+ domain: string
+ loc: number
+ state: TileState
+ /** What the proof says of the module, once the verify command has checked it. */
+ proof?: TileProof
+ rect: Rect
+ isNext: boolean
+}
+
+export type Estate = {
+ columns: number
+ rows: number
+ tiles: Tile[]
+ /** Base64 for the Raster's `cells`. */
+ cells: string
+ /** True while any tile is still fading from a touch, so another frame is due. */
+ isAnimating: boolean
+}
+
+/** How long a touch stays visible, in milliseconds. */
+export const FLASH_MS = 4000
+
+/**
+ * Mid-tones on purpose: a tile has to show against a dark terminal and a light one, and the map cannot ask which it is.
+ * The labels are drawn in whichever of light or dark ink reads on the tile.
+ */
+export const STATE_COLORS: Record<TileState, number> = {
+ untouched: 0x5b6577,
+ scaffolded: 0x4a6cb0,
+ 'tests-written': 0x94741f,
+ 'tests-red': 0xb23b3b,
+ 'tests-failing': 0xc2683a,
+ 'tests-green': 0x2c7a4c,
+ reviewed: 0x2fa568,
+ ported: 0x2b8ea6,
+ switched: 0x3bd184,
+}
+
+/** What a state is called in a track: the same colors, worded for what the work is. */
+export const stateWord = (track: TrackKey, state: TileState): string => STATE_WORDS_BY_TRACK[track][state] ?? state
+
+const FLASH_COLORS: Record<TouchKind, number> = {
+ read: 0x9fd4ff,
+ write: 0xffe27a,
+}
+
+/** A stable small jitter per tile, so neighbours of one state still read as separate tiles. */
+const jitterOf = (id: string): number => {
+ let hash = 2166136261
+
+ for (let index = 0; index < id.length; index += 1) {
+ hash = Math.imul(hash ^ id.charCodeAt(index), 16777619)
+ }
+
+ return ((hash >>> 0) % 1000) / 1000
+}
+
+/** The module ids of the step the snapshot says comes next, when it is a transform. */
+function nextModuleOf(snapshot: Snapshot): string | null {
+ const text = snapshot.next?.text ?? ''
+ const match = /transform\s+\S+\s+(\S+)/.exec(text)
+
+ return snapshot.next?.isByHand === false ? (match?.[1] ?? null) : null
+}
+
+/**
+ * Short names for tiles, which show a few letters: a path is cut to its last segment, a source file's extension goes, and
+ * the prefix most of the units share (`jetty-` in `jetty-server`, `jetty-client`) goes too, so the letters that tell
+ * one tile from the next are the ones drawn.
+ */
+export function labelsOf(names: readonly string[]): string[] {
+ const stems = names.map(name => {
+ const last = name.includes('/') ? (name.split('/').filter(part => part !== '').at(-1) ?? name) : name
+
+ return languageOf(last) !== undefined ? last.replace(/\.[^.]+$/, '') : last
+ })
+
+ const counts = new Map<string, number>()
+
+ for (const stem of stems) {
+ const head = /^[^-_.\s]{2,}[-_.]/.exec(stem)?.[0]
+
+ if (head !== undefined) {
+ counts.set(head, (counts.get(head) ?? 0) + 1)
+ }
+ }
+
+ const [top, count] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0] ?? ['', 0]
+ const isShared = top !== '' && count >= 4 && count >= names.length * 0.4
+
+ return stems.map(stem => (isShared && stem.startsWith(top) && stem.length > top.length ? stem.slice(top.length) : stem))
+}
+
+/** The tile's proof, when its module has a fresh verdict; nothing for a module nobody has checked or that changed since. */
+function proofMarkOf(snapshot: Snapshot, unitId: string): { proof: TileProof } | Record<string, never> {
+ const module = snapshot.byNode.get(unitId)
+
+ if (module === undefined || snapshot.track === 'uplift') {
+ return {}
+ }
+
+ const state = snapshot.proofs.get(module.dir.toLowerCase())?.state
+
+ return state === 'proven' || state === 'partly' || state === 'not' ? { proof: state } : {}
+}
+
+/** How many tiles carry each proof, in the order a legend draws them. */
+export function proofCountsOf(tiles: readonly Tile[]): { kind: TileProof; count: number }[] {
+ return (['proven', 'partly', 'not'] as const)
+ .map(kind => ({ kind, count: tiles.filter(tile => tile.proof === kind).length }))
+ .filter(entry => entry.count > 0)
+}
+
+/** Lays the snapshot's estate out in `columns` by `rows` cells. */
+export function tilesOf(snapshot: Snapshot, columns: number, rows: number): Tile[] {
+ const estate = snapshot.estate ?? (snapshot.topology !== null ? estateOfTopology(snapshot.topology, 0) : null)
+
+ if (estate === null || columns < 4 || rows < 2) {
+ return []
+ }
+
+ const next = nextModuleOf(snapshot)
+ const groups = new Map<string, EstateUnit[]>()
+ const short = labelsOf(estate.units.map(unit => unit.name))
+ const labels = new Map(estate.units.map((unit, index) => [unit.id, short[index] ?? unit.name] as const))
+
+ for (const unit of estate.units) {
+ const members = groups.get(unit.group) ?? []
+
+ members.push(unit)
+ groups.set(unit.group, members)
+ }
+
+ const placed = layoutGroups(
+ [...groups.entries()].map(([name, members]) => ({
+ name,
+ items: members.map(unit => ({ item: unit, size: Math.max(1, unit.size) })),
+ })),
+ { x: 0, y: 0, w: columns, h: rows },
+ )
+
+ return placed.flatMap(group =>
+ group.items
+ .filter(entry => entry.rect.w > 0 && entry.rect.h > 0)
+ .map(entry => ({
+ id: entry.item.id,
+ name: entry.item.name,
+ label: labels.get(entry.item.id) ?? entry.item.name,
+ domain: group.name,
+ loc: entry.item.size,
+ state: snapshot.byNode.get(entry.item.id)?.state ?? ('untouched' as const),
+ ...proofMarkOf(snapshot, entry.item.id),
+ rect: entry.rect,
+ isNext: entry.item.id === next,
+ })),
+ )
+}
+
+/** Paints the tiles into cells and packs them for the Raster. */
+export function paint(
+ tiles: readonly Tile[],
+ columns: number,
+ rows: number,
+ touches: ReadonlyMap<string, Touch>,
+ nowMs: number,
+): Estate {
+ const blank: Cell = { glyph: ' ', fg: DEFAULT_COLOR, bg: DEFAULT_COLOR }
+ const cells: Cell[] = Array.from({ length: columns * rows }, () => blank)
+ let isAnimating = false
+
+ for (const tile of tiles) {
+ const base = mix(STATE_COLORS[tile.state], 0xffffff, (jitterOf(tile.id) - 0.5) * 0.14 + 0.02)
+ const touch = touches.get(tile.id)
+ const age = touch !== undefined ? nowMs - touch.atMs : Infinity
+ const heat = age < FLASH_MS ? 1 - age / FLASH_MS : 0
+
+ if (heat > 0) {
+ isAnimating = true
+ }
+
+ const body = heat > 0 && touch !== undefined ? mix(base, FLASH_COLORS[touch.kind], heat * 0.85) : base
+ const edge = mix(body, 0x000000, 0.32)
+ const ink = luma(body) > 140 ? 0x101418 : 0xf2f5f8
+ const { x, y, w, h } = tile.rect
+ const hasBevel = w >= 3 && h >= 2
+ const label = w >= 5 && tile.proof !== undefined ? `${tile.isNext ? '▸' : ''}${PROOF_MARKS[tile.proof]}${tile.label}` : w >= 4 ? (tile.isNext ? '▸' : '') + tile.label : w >= 2 && tile.isNext ? '▸' : ''
+ const shown = label.slice(0, Math.max(0, w - (hasBevel ? 1 : 0)))
+
+ for (let row = 0; row < h; row += 1) {
+ for (let col = 0; col < w; col += 1) {
+ const cx = x + col
+ const cy = y + row
+
+ if (cx >= columns || cy >= rows) {
+ continue
+ }
+
+ const isEdge = hasBevel && (col === w - 1 || row === h - 1)
+ const glyph = row === 0 && col < shown.length ? (shown[col] ?? ' ') : ' '
+
+ cells[cy * columns + cx] = { glyph, fg: ink, bg: isEdge ? edge : body }
+ }
+ }
+ }
+
+ return { columns, rows, tiles: [...tiles], cells: packCells(cells), isAnimating }
+}
+
+/** How many modules sit in each state, in the order the legend draws them. */
+export function countsOf(tiles: readonly Tile[]): { state: TileState; count: number }[] {
+ const order: TileState[] = [
+ 'untouched',
+ 'scaffolded',
+ 'tests-written',
+ 'tests-red',
+ 'tests-failing',
+ 'tests-green',
+ 'reviewed',
+ 'ported',
+ 'switched',
+ ]
+
+ return order
+ .map(state => ({ state, count: tiles.filter(tile => tile.state === state).length }))
+ .filter(entry => entry.count > 0)
+}
+
+/** `0x00RRGGBB` as the `#rrggbb` a `Text`'s `color` takes. */
+export const hexOf = (color: number): string => `#${(color & 0xffffff).toString(16).padStart(6, '0')}`
diff --git a/plugins/code-modernization/hooks/map/raster.ts b/plugins/code-modernization/hooks/map/raster.ts
new file mode 100644
index 00000000..1a9b0ee0
--- /dev/null
+++ b/plugins/code-modernization/hooks/map/raster.ts
@@ -0,0 +1,92 @@
+/**
+ * Packing for the terminal's `Raster` element: a grid of cells, each a glyph
+ * with a foreground and a background colour, as the base64 the element takes
+ * (`columns * rows` little-endian u32 triplets `[codePoint, fg, bg]`).
+ */
+
+export type Cell = { glyph: string; fg: number; bg: number }
+
+/** The terminal's own default colour, as `RasterProps` spells it. */
+export const DEFAULT_COLOR = 0x01000000
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+/** Standard padded base64 of bytes, with no dependence on `btoa` or `Uint8Array.toBase64`. */
+export function base64Of(bytes: Uint8Array): string {
+ let out = ''
+
+ for (let index = 0; index < bytes.length; index += 3) {
+ const a = bytes[index] ?? 0
+ const b = bytes[index + 1] ?? 0
+ const c = bytes[index + 2] ?? 0
+ const has2 = index + 1 < bytes.length
+ const has3 = index + 2 < bytes.length
+
+ out +=
+ (B64[a >> 2] ?? '') +
+ (B64[((a & 3) << 4) | (b >> 4)] ?? '') +
+ (has2 ? (B64[((b & 15) << 2) | (c >> 6)] ?? '') : '=') +
+ (has3 ? (B64[c & 63] ?? '') : '=')
+ }
+
+ return out
+}
+
+/** A printable width-1 BMP code point for `glyph`, or a space when it is not one. */
+export function codePointOf(glyph: string): number {
+ const point = glyph.codePointAt(0) ?? 0x20
+
+ const isPrintable =
+ point >= 0x20 &&
+ point <= 0xffff &&
+ point !== 0x7f &&
+ !(point >= 0x80 && point < 0xa0) &&
+ !(point >= 0xd800 && point <= 0xdfff) &&
+ // East Asian wide and fullwidth ranges draw two cells.
+ !(point >= 0x1100 && point <= 0x115f) &&
+ !(point >= 0x2e80 && point <= 0xa4cf) &&
+ !(point >= 0xac00 && point <= 0xd7a3) &&
+ !(point >= 0xf900 && point <= 0xfaff) &&
+ !(point >= 0xfe30 && point <= 0xfe6f) &&
+ !(point >= 0xff00 && point <= 0xff60) &&
+ !(point >= 0xffe0 && point <= 0xffe6)
+
+ return isPrintable ? point : 0x20
+}
+
+/** Packs row-major `cells` (`columns * rows` of them) for a `Raster`'s `cells` prop. */
+export function packCells(cells: readonly Cell[]): string {
+ const bytes = new Uint8Array(cells.length * 12)
+ const view = new DataView(bytes.buffer)
+
+ cells.forEach((cell, index) => {
+ view.setUint32(index * 12, codePointOf(cell.glyph), true)
+ view.setUint32(index * 12 + 4, cell.fg >>> 0, true)
+ view.setUint32(index * 12 + 8, cell.bg >>> 0, true)
+ })
+
+ return base64Of(bytes)
+}
+
+/** `0x00RRGGBB` from three 0-255 channels. */
+export const rgb = (r: number, g: number, b: number): number =>
+ ((Math.max(0, Math.min(255, Math.round(r))) << 16) |
+ (Math.max(0, Math.min(255, Math.round(g))) << 8) |
+ Math.max(0, Math.min(255, Math.round(b)))) >>>
+ 0
+
+/** `a` moved `t` of the way (0 to 1) toward `b`, channel by channel. */
+export function mix(a: number, b: number, t: number): number {
+ const k = Math.max(0, Math.min(1, t))
+ const ch = (c: number, shift: number) => (c >> shift) & 0xff
+
+ return rgb(
+ ch(a, 16) + (ch(b, 16) - ch(a, 16)) * k,
+ ch(a, 8) + (ch(b, 8) - ch(a, 8)) * k,
+ ch(a, 0) + (ch(b, 0) - ch(a, 0)) * k,
+ )
+}
+
+/** Perceived brightness, 0 to 255. */
+export const luma = (color: number): number =>
+ 0.299 * ((color >> 16) & 0xff) + 0.587 * ((color >> 8) & 0xff) + 0.114 * (color & 0xff)
diff --git a/plugins/code-modernization/hooks/map/treemap.ts b/plugins/code-modernization/hooks/map/treemap.ts
new file mode 100644
index 00000000..21042734
--- /dev/null
+++ b/plugins/code-modernization/hooks/map/treemap.ts
@@ -0,0 +1,156 @@
+/**
+ * A squarified treemap over a grid of terminal cells, two levels deep:
+ * groups (domains) first, then each group's items (modules) inside its
+ * rectangle. Pure: sizes in, integer cell rectangles out.
+ *
+ * A terminal cell is about twice as tall as it is wide, so the layout works
+ * in a space where each row counts double and rounds back to whole cells.
+ */
+
+export type Rect = { x: number; y: number; w: number; h: number }
+
+export type Sized<T> = { item: T; size: number }
+
+export type Placed<T> = { item: T; rect: Rect }
+
+/** How much taller than wide one cell is; rows are weighted by it when judging squareness. */
+const CELL_ASPECT = 2
+
+const worst = (row: number[], side: number, scale: number): number => {
+ const sum = row.reduce((a, b) => a + b, 0)
+
+ if (sum === 0 || side === 0) {
+ return Infinity
+ }
+
+ const max = Math.max(...row)
+ const min = Math.min(...row)
+ const s2 = sum * sum
+ const side2 = side * side * scale
+
+ return Math.max((side2 * max) / s2, s2 / (side2 * min))
+}
+
+/**
+ * Squarified layout of `sizes` (already scaled so they sum to the area of
+ * `rect`) into fractional rectangles, in the order given.
+ */
+function squarify(sizes: number[], rect: Rect): Rect[] {
+ const out: Rect[] = []
+ let { x, y, w, h } = rect
+ let index = 0
+
+ while (index < sizes.length) {
+ // Lay rows along the visually shorter side.
+ const isWide = w >= h * CELL_ASPECT
+ const side = isWide ? h : w
+ const scale = isWide ? CELL_ASPECT : 1 / CELL_ASPECT
+ const row: number[] = []
+
+ while (index < sizes.length) {
+ const next = sizes[index] ?? 0
+ const grown = [...row, next]
+
+ if (row.length > 0 && worst(grown, side, scale) > worst(row, side, scale)) {
+ break
+ }
+
+ row.push(next)
+ index += 1
+ }
+
+ const sum = row.reduce((a, b) => a + b, 0)
+ const thick = side > 0 ? sum / side : 0
+ let offset = 0
+
+ for (const size of row) {
+ const length = thick > 0 ? size / thick : 0
+
+ out.push(
+ isWide
+ ? { x, y: y + offset, w: thick, h: length }
+ : { x: x + offset, y, w: length, h: thick },
+ )
+
+ offset += length
+ }
+
+ if (isWide) {
+ x += thick
+ w -= thick
+ } else {
+ y += thick
+ h -= thick
+ }
+
+ if (w <= 0 || h <= 0) {
+ // Out of room: whatever is left collapses onto the last edge.
+ while (index < sizes.length) {
+ out.push({ x: rect.x + rect.w, y: rect.y + rect.h, w: 0, h: 0 })
+ index += 1
+ }
+ }
+ }
+
+ return out
+}
+
+/** Rounds fractional rectangles to whole cells without gaps or overlaps on shared edges. */
+function snap(rects: Rect[], bounds: Rect): Rect[] {
+ const clampX = (v: number) => Math.min(bounds.x + bounds.w, Math.max(bounds.x, Math.round(v)))
+ const clampY = (v: number) => Math.min(bounds.y + bounds.h, Math.max(bounds.y, Math.round(v)))
+
+ return rects.map(rect => {
+ const x0 = clampX(rect.x)
+ const y0 = clampY(rect.y)
+ const x1 = clampX(rect.x + rect.w)
+ const y1 = clampY(rect.y + rect.h)
+
+ return { x: x0, y: y0, w: Math.max(0, x1 - x0), h: Math.max(0, y1 - y0) }
+ })
+}
+
+/** Lays `entries` out in `rect`, largest first, each given at least `floor` of the mean size. */
+export function layout<T>(entries: Sized<T>[], rect: Rect, floor = 0.35): Placed<T>[] {
+ if (entries.length === 0 || rect.w <= 0 || rect.h <= 0) {
+ return []
+ }
+
+ const positive = entries.map(entry => ({ ...entry, size: Math.max(0, entry.size) }))
+ const mean = positive.reduce((sum, entry) => sum + entry.size, 0) / positive.length || 1
+
+ // A tiny item next to a huge one would round to zero cells: lift it to a floor.
+ const lifted = positive
+ .map(entry => ({ ...entry, size: Math.max(entry.size, mean * floor) }))
+ .sort((a, b) => b.size - a.size)
+
+ const total = lifted.reduce((sum, entry) => sum + entry.size, 0)
+ const area = rect.w * rect.h
+ const scaled = lifted.map(entry => (entry.size / total) * area)
+ const snapped = snap(squarify(scaled, rect), rect)
+
+ return lifted.map((entry, index) => ({
+ item: entry.item,
+ rect: snapped[index] ?? { x: rect.x, y: rect.y, w: 0, h: 0 },
+ }))
+}
+
+export type Group<T> = { name: string; items: Sized<T>[] }
+
+export type PlacedGroup<T> = { name: string; rect: Rect; items: Placed<T>[] }
+
+/** Two-level layout: groups by their items' total size, then items within each group. */
+export function layoutGroups<T>(groups: Group<T>[], rect: Rect): PlacedGroup<T>[] {
+ const sized = groups
+ .filter(group => group.items.length > 0)
+ .map(group => ({
+ item: group,
+ size: group.items.reduce((sum, entry) => sum + Math.max(0, entry.size), 0),
+ }))
+
+ return layout(sized, rect, 0.2).map(placed => ({
+ name: placed.item.name,
+ rect: placed.rect,
+ items: layout(placed.item.items, placed.rect),
+ }))
+}