diff options
| author | Claude <noreply@anthropic.com> | 2026-11-06 00:54:48 +0000 |
|---|---|---|
| committer | Claude <noreply@anthropic.com> | 2026-11-06 00:54:48 +0000 |
| commit | 7aba3deae3ff17d032c37e07d2929d1426b34278 (patch) | |
| tree | 9c482f9acda1599bd2f9bed95a6a46b75e634e80 /plugins/code-modernization/hooks/map | |
| parent | 5472f5f56e0070feeeb464318b316714fe3e9105 (diff) | |
| parent | b8331dd69ab3e132bbf8cd6e89b5d8c1747e21b1 (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.ts | 258 | ||||
| -rw-r--r-- | plugins/code-modernization/hooks/map/raster.ts | 92 | ||||
| -rw-r--r-- | plugins/code-modernization/hooks/map/treemap.ts | 156 |
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), + })) +} |
