@purview-dev/pm-docs-site 0.1.0-pre.2 → 0.1.0-pre.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +70 -10
  2. package/dist/cli.js +4 -3
  3. package/dist/dev-env.d.ts +2 -0
  4. package/dist/dev-env.js +13 -0
  5. package/dist/fs-allow.d.ts +2 -0
  6. package/dist/fs-allow.js +11 -0
  7. package/dist/index.js +38 -4
  8. package/dist/options.js +1 -1
  9. package/dist/schema-version.d.ts +17 -0
  10. package/dist/schema-version.js +30 -1
  11. package/dist/sidebar.js +2 -0
  12. package/dist/site-options.js +5 -0
  13. package/dist/types.d.ts +2 -2
  14. package/lib/schema-version.ts +36 -1
  15. package/lib/types.ts +48 -0
  16. package/package.json +7 -3
  17. package/src/components/FeatureSummary.astro +30 -9
  18. package/src/components/FeatureTable.astro +1 -1
  19. package/src/components/ItemDetail.astro +1 -1
  20. package/src/components/ItemDialog.astro +12 -8
  21. package/src/components/RefLink.astro +7 -4
  22. package/src/components/board/Board.tsx +16 -8
  23. package/src/components/board/KanbanItemCard.tsx +4 -2
  24. package/src/components/board/TaskKanbanCard.tsx +4 -2
  25. package/src/components/decisions/Decisions.tsx +162 -0
  26. package/src/components/decisions/useDecisionsUrlState.ts +29 -0
  27. package/src/components/graph/Graph.tsx +290 -0
  28. package/src/components/graph/GraphNodes.tsx +120 -0
  29. package/src/components/graph/useGraphUrlState.ts +58 -0
  30. package/src/components/lib/KanbanItemCard.astro +7 -11
  31. package/src/components/lib/StatusTimelineFeed.astro +3 -2
  32. package/src/components/lib/TaskKanbanCard.astro +2 -1
  33. package/src/components/timeline/Timeline.tsx +39 -6
  34. package/src/components/timeline/useTimelineLayout.ts +2 -2
  35. package/src/content.config.ts +22 -6
  36. package/src/lib/decisions.ts +100 -0
  37. package/src/lib/graph-layout.ts +270 -0
  38. package/src/lib/graph-state.ts +99 -0
  39. package/src/lib/graph.ts +194 -0
  40. package/src/lib/link-html.ts +39 -0
  41. package/src/lib/planning-types.ts +32 -3
  42. package/src/lib/planning.ts +30 -16
  43. package/src/lib/ref-boundary.ts +19 -0
  44. package/src/lib/references.ts +66 -7
  45. package/src/lib/timeline-state.ts +119 -0
  46. package/src/lib/timeline.ts +22 -127
  47. package/src/loaders/adrs.ts +43 -0
  48. package/src/pages/404.astro +18 -0
  49. package/src/pages/index.astro +1 -1
  50. package/src/pages/plan/log.astro +18 -1
  51. package/src/pages/plan/roadmap.astro +1 -1
  52. package/src/routes/plan/decisions/[id].astro +93 -0
  53. package/src/routes/plan/decisions.astro +52 -0
  54. package/src/routes/plan/graph.astro +80 -0
  55. package/src/routes/plan/milestones/index.astro +2 -2
  56. package/src/routes/plan/now.astro +2 -3
  57. package/src/scripts/plan.ts +33 -1
  58. package/src/styles/components.css +117 -3
  59. package/src/styles/graph.css +296 -0
  60. package/src/styles/timeline.css +1 -1
@@ -0,0 +1,270 @@
1
+ // Build-time layouts for the dependency graph: four fixed sets of node boxes
2
+ // (milestone lanes or one flow, with or without done and dropped chips),
3
+ // computed with dagre in page frontmatter and shipped to the island as data.
4
+ // Only this module imports dagre, so the island never bundles it. Edges are
5
+ // not routed here: React Flow draws each as a bezier between node handles.
6
+ //
7
+ // dagre lays out the linked nodes only (those with a drawn edge), so isolated
8
+ // items never stretch the linked graph. In a cycle dagre reverses one edge to
9
+ // rank the nodes, so that edge runs right to left; the left-to-right rule
10
+ // cannot hold for it.
11
+
12
+ import { Graph, layout } from '@dagrejs/dagre';
13
+
14
+ import type { GraphData, GraphEdge, GraphNode } from './graph';
15
+ import { milestoneSummaries } from './planning';
16
+ import type { Planning } from './planning-types';
17
+
18
+ export type LayoutKey = 'lanes-done' | 'lanes-open' | 'flow-done' | 'flow-open';
19
+
20
+ /** A node's box: top-left corner and size, in whole pixels. */
21
+ export interface Box {
22
+ x: number;
23
+ y: number;
24
+ width: number;
25
+ height: number;
26
+ }
27
+
28
+ /** One milestone lane, top to bottom. */
29
+ export interface Lane {
30
+ /** The milestone ID, or `none` for the items with no milestone. */
31
+ key: string;
32
+ /** `<ID> <name>`, or `No milestone`. */
33
+ label: string;
34
+ isFocus: boolean;
35
+ y: number;
36
+ height: number;
37
+ }
38
+
39
+ /** One positioned graph. A node absent from `boxes` is hidden; an edge is drawn only when both ends have boxes. */
40
+ export interface GraphLayout {
41
+ boxes: Record<string, Box>;
42
+ /** Empty in the flow layouts. */
43
+ lanes: Lane[];
44
+ /** The `No links` row of isolated items in the flow layouts; `null` when there is none. */
45
+ tray: { y: number } | null;
46
+ width: number;
47
+ height: number;
48
+ }
49
+
50
+ /** Node sizes, in pixels. */
51
+ export const SIZES = {
52
+ item: { width: 220, height: 64 },
53
+ chip: { width: 120, height: 28 },
54
+ } as const;
55
+
56
+ /** The space between nodes in one column, and between tray boxes. */
57
+ const NODE_SEP = 24;
58
+ const RANK_SEP = 80;
59
+ /** The lane's or tray's label band, above its nodes. */
60
+ const LABEL_BAND = 32;
61
+ /** The space below the label band and below a lane's nodes. */
62
+ const LANE_PADDING = 16;
63
+ /** The space between the linked graph and the tray. */
64
+ const TRAY_GAP = 48;
65
+ /** Tray boxes per row when no node is linked. */
66
+ const TRAY_COLUMNS = 4;
67
+ const NONE = 'none';
68
+
69
+ const byId = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
70
+
71
+ const sizeOf = (node: GraphNode) => (node.kind === 'item' ? SIZES.item : SIZES.chip);
72
+
73
+ /**
74
+ * dagre's position for each linked node, as a whole-pixel top-left box,
75
+ * shifted so the linked graph starts at x 0 and y 0.
76
+ */
77
+ function dagreBoxes(nodes: GraphNode[], edges: GraphEdge[]): Map<string, Box> {
78
+ const boxes = new Map<string, Box>();
79
+
80
+ if (nodes.length === 0) return boxes;
81
+
82
+ const graph = new Graph();
83
+
84
+ graph.setGraph({ rankdir: 'LR', nodesep: NODE_SEP, ranksep: RANK_SEP });
85
+ graph.setDefaultEdgeLabel(() => ({}));
86
+ for (const node of [...nodes].sort((a, b) => byId(a.id, b.id))) graph.setNode(node.id, { ...sizeOf(node) });
87
+
88
+ const pairs = [...new Set(edges.map((edge) => `${edge.source}\n${edge.target}`))].sort(byId);
89
+
90
+ for (const pair of pairs) {
91
+ const [source, target] = pair.split('\n') as [string, string];
92
+
93
+ graph.setEdge(source, target);
94
+ }
95
+ layout(graph);
96
+
97
+ for (const node of nodes) {
98
+ const { x, y, width, height } = graph.node(node.id) as { x: number; y: number; width: number; height: number };
99
+
100
+ boxes.set(node.id, { x: Math.round(x - width / 2), y: Math.round(y - height / 2), width, height });
101
+ }
102
+
103
+ const minX = Math.min(...[...boxes.values()].map((box) => box.x));
104
+ const minY = Math.min(...[...boxes.values()].map((box) => box.y));
105
+
106
+ for (const [id, box] of boxes) boxes.set(id, { ...box, x: box.x - minX, y: box.y - minY });
107
+
108
+ return boxes;
109
+ }
110
+
111
+ /** The candidate lanes, in `milestoneSummaries` order, with `No milestone` last. */
112
+ function laneCandidates(planning: Planning): Omit<Lane, 'y' | 'height'>[] {
113
+ const milestones = milestoneSummaries(planning).filter((summary) => summary.id !== null);
114
+
115
+ return [
116
+ ...milestones.map((summary) => ({ key: summary.id!, label: `${summary.id} ${summary.name}`, isFocus: summary.isFocus })),
117
+ { key: NONE, label: 'No milestone', isFocus: false },
118
+ ];
119
+ }
120
+
121
+ /**
122
+ * Lanes: dagre's columns for linked nodes, each node in its lane, stacked per
123
+ * lane and column in dagre's order; isolated items go in the first column of
124
+ * their lane, below the linked nodes they would otherwise overlap.
125
+ */
126
+ function lanesLayout(nodes: GraphNode[], edges: GraphEdge[], placed: Map<string, Box>, planning: Planning): GraphLayout {
127
+ const candidates = laneCandidates(planning);
128
+ const laneIndex = new Map(candidates.map((lane, index) => [lane.key, index]));
129
+ const nodeById = new Map(nodes.map((node) => [node.id, node]));
130
+ const itemLane = (node: GraphNode): number => laneIndex.get(node.milestone ?? NONE) ?? laneIndex.get(NONE)!;
131
+ const laneOf = (node: GraphNode): number => {
132
+ if (node.kind === 'item') return itemLane(node);
133
+
134
+ const dependants = edges.map((edge) => (edge.source === node.id ? nodeById.get(edge.target) : undefined)).filter((target): target is GraphNode => target?.kind === 'item');
135
+
136
+ return dependants.length > 0 ? Math.min(...dependants.map(itemLane)) : laneIndex.get(NONE)!;
137
+ };
138
+ const firstX = placed.size > 0 ? Math.min(...[...placed.values()].map((box) => box.x)) : 0;
139
+
140
+ // Group linked nodes by lane, then by column (dagre's centre x); isolated items by lane, in node order.
141
+ const linkedByLane = new Map<number, Map<number, GraphNode[]>>();
142
+ const isolatedByLane = new Map<number, GraphNode[]>();
143
+
144
+ for (const node of nodes) {
145
+ const lane = laneOf(node);
146
+ const box = placed.get(node.id);
147
+
148
+ if (!box) {
149
+ isolatedByLane.set(lane, [...(isolatedByLane.get(lane) ?? []), node]);
150
+ continue;
151
+ }
152
+
153
+ const columns = linkedByLane.get(lane) ?? new Map<number, GraphNode[]>();
154
+ const column = box.x + box.width / 2;
155
+
156
+ columns.set(column, [...(columns.get(column) ?? []), node]);
157
+ linkedByLane.set(lane, columns);
158
+ }
159
+
160
+ const boxes: Record<string, Box> = {};
161
+ const lanes: Lane[] = [];
162
+ let top = 0;
163
+
164
+ candidates.forEach((candidate, index) => {
165
+ const columns = linkedByLane.get(index);
166
+ const isolated = isolatedByLane.get(index) ?? [];
167
+
168
+ if (!columns && isolated.length === 0) return;
169
+
170
+ const start = top + LABEL_BAND + LANE_PADDING;
171
+ const laneBoxes: Box[] = [];
172
+
173
+ for (const column of columns?.values() ?? []) {
174
+ column.sort((a, b) => placed.get(a.id)!.y - placed.get(b.id)!.y || byId(a.id, b.id));
175
+
176
+ let y = start;
177
+
178
+ for (const node of column) {
179
+ const box = { ...placed.get(node.id)!, y };
180
+
181
+ boxes[node.id] = box;
182
+ laneBoxes.push(box);
183
+ y += box.height + NODE_SEP;
184
+ }
185
+ }
186
+
187
+ // Isolated items stack in the first column, below any linked box their width would reach.
188
+ const width = SIZES.item.width;
189
+ let y = laneBoxes.filter((box) => box.x < firstX + width && firstX < box.x + box.width).reduce((bottom, box) => Math.max(bottom, box.y + box.height + NODE_SEP), start);
190
+
191
+ for (const node of isolated) {
192
+ const box = { x: firstX, y, ...sizeOf(node) };
193
+
194
+ boxes[node.id] = box;
195
+ laneBoxes.push(box);
196
+ y += box.height + NODE_SEP;
197
+ }
198
+
199
+ const bottom = laneBoxes.reduce((max, box) => Math.max(max, box.y + box.height), start);
200
+ const height = bottom - top + LANE_PADDING;
201
+
202
+ lanes.push({ ...candidate, y: top, height });
203
+ top += height;
204
+ });
205
+
206
+ return { boxes, lanes, tray: null, width: extent(boxes, 'x'), height: top };
207
+ }
208
+
209
+ /** Flow: dagre's positions for linked nodes, and isolated items in a tray below, wrapping at the linked width or TRAY_COLUMNS, whichever is wider. */
210
+ function flowLayout(nodes: GraphNode[], placed: Map<string, Box>): GraphLayout {
211
+ const boxes: Record<string, Box> = Object.fromEntries(nodes.filter((node) => placed.has(node.id)).map((node) => [node.id, placed.get(node.id)!]));
212
+ const isolated = nodes.filter((node) => !placed.has(node.id));
213
+ const linkedWidth = extent(boxes, 'x');
214
+ let tray: GraphLayout['tray'] = null;
215
+
216
+ if (isolated.length > 0) {
217
+ const step = SIZES.item.width + NODE_SEP;
218
+ const perRow = placed.size > 0 ? Math.max(TRAY_COLUMNS, Math.floor((linkedWidth + NODE_SEP) / step)) : TRAY_COLUMNS;
219
+ const trayY = placed.size > 0 ? extent(boxes, 'y') + TRAY_GAP : 0;
220
+
221
+ tray = { y: trayY };
222
+ isolated.forEach((node, index) => {
223
+ boxes[node.id] = {
224
+ x: (index % perRow) * step,
225
+ y: trayY + LABEL_BAND + Math.floor(index / perRow) * (SIZES.item.height + NODE_SEP),
226
+ ...sizeOf(node),
227
+ };
228
+ });
229
+ }
230
+
231
+ return { boxes, lanes: [], tray, width: extent(boxes, 'x'), height: extent(boxes, 'y') };
232
+ }
233
+
234
+ /** The furthest right (`x`) or bottom (`y`) edge of any box, or 0 with none. */
235
+ function extent(boxes: Record<string, Box>, axis: 'x' | 'y'): number {
236
+ return Object.values(boxes).reduce((max, box) => Math.max(max, axis === 'x' ? box.x + box.width : box.y + box.height), 0);
237
+ }
238
+
239
+ /** The two layouts for one set of drawn nodes, from a single dagre run over the linked ones so columns line up across them. */
240
+ function variant(data: GraphData, showDone: boolean, planning: Planning): { lanes: GraphLayout; flow: GraphLayout } {
241
+ const nodes = data.nodes.filter((node) => showDone || (node.kind !== 'done' && node.kind !== 'dropped'));
242
+
243
+ if (nodes.length === 0) {
244
+ const empty = (): GraphLayout => ({ boxes: {}, lanes: [], tray: null, width: 0, height: 0 });
245
+
246
+ return { lanes: empty(), flow: empty() };
247
+ }
248
+
249
+ const drawn = new Set(nodes.map((node) => node.id));
250
+ const edges = data.edges.filter((edge) => drawn.has(edge.source) && drawn.has(edge.target));
251
+ const linkedIds = new Set(edges.flatMap((edge) => [edge.source, edge.target]));
252
+ const placed = dagreBoxes(
253
+ nodes.filter((node) => linkedIds.has(node.id)),
254
+ edges,
255
+ );
256
+
257
+ return { lanes: lanesLayout(nodes, edges, placed, planning), flow: flowLayout(nodes, placed) };
258
+ }
259
+
260
+ /**
261
+ * The graph's four layouts: milestone lanes or one flow, each with done and
262
+ * dropped chips (`*-done`) or without them (`*-open`); missing chips stay in
263
+ * all four. Deterministic, in whole pixels.
264
+ */
265
+ export function graphLayouts(data: GraphData, planning: Planning): Record<LayoutKey, GraphLayout> {
266
+ const done = variant(data, true, planning);
267
+ const open = variant(data, false, planning);
268
+
269
+ return { 'lanes-done': done.lanes, 'lanes-open': open.lanes, 'flow-done': done.flow, 'flow-open': open.flow };
270
+ }
@@ -0,0 +1,99 @@
1
+ // The Graph island's URL state and chain tracing, kept apart from graph.ts so
2
+ // the island imports no module that reads planning.json: graph.ts imports
3
+ // planning.ts, which imports node:fs, and under `pm-docs-site dev` every
4
+ // module an island imports reaches the browser, used or not. `GraphState`
5
+ // lives in the URL like `TimelineLayout` in timeline.ts: defaults write no key,
6
+ // and every other parameter and the hash are kept. graph.ts re-exports all of
7
+ // it.
8
+
9
+ import type { GraphEdge } from './graph';
10
+ import type { GraphLayout, LayoutKey } from './graph-layout';
11
+
12
+ /** The graph page's own URL state: milestone lanes, done and dropped chips, and the focused node. */
13
+ export interface GraphState {
14
+ lanes: boolean;
15
+ done: boolean;
16
+ focus: string | null;
17
+ }
18
+
19
+ /** `GraphState` from `?lanes=off&done=off&focus=<ID>`; a key's absence, or any value other than the exact `off`, is the default `true`. */
20
+ export function parseGraphQuery(search: string): GraphState {
21
+ const params = new URLSearchParams(search);
22
+
23
+ return {
24
+ lanes: params.get('lanes') !== 'off',
25
+ done: params.get('done') !== 'off',
26
+ focus: params.get('focus'),
27
+ };
28
+ }
29
+
30
+ /** `search` with `lanes`, `done`, and `focus` set for each non-default value, in that order (appended last); keeps every other parameter. `''` when none remain. */
31
+ export function graphQuery(state: GraphState, search: string): string {
32
+ const params = new URLSearchParams(search);
33
+
34
+ params.delete('lanes');
35
+ params.delete('done');
36
+ params.delete('focus');
37
+
38
+ if (!state.lanes) params.append('lanes', 'off');
39
+ if (!state.done) params.append('done', 'off');
40
+ if (state.focus !== null) params.append('focus', state.focus);
41
+
42
+ const query = params.toString();
43
+
44
+ return query === '' ? '' : `?${query}`;
45
+ }
46
+
47
+ /** The layout key for the lanes/flow and done/open switches. */
48
+ export function layoutKey(state: Pick<GraphState, 'lanes' | 'done'>): LayoutKey {
49
+ return `${state.lanes ? 'lanes' : 'flow'}-${state.done ? 'done' : 'open'}` as LayoutKey;
50
+ }
51
+
52
+ /** `focus` when it names a node drawn in `layout`, else `null` (no focus, or a hidden or missing ID). */
53
+ export function resolveFocus(focus: string | null, layout: GraphLayout): string | null {
54
+ return focus !== null && layout.boxes[focus] ? focus : null;
55
+ }
56
+
57
+ /**
58
+ * Every node and edge reached from `id` by walking drawn edges (both ends
59
+ * boxed in `layout`) upstream and downstream, each direction with its own
60
+ * visited set so a cycle terminates. Includes `id` itself.
61
+ */
62
+ export function chainOf(edges: GraphEdge[], id: string, layout: GraphLayout): Set<string> {
63
+ const drawn = edges.filter((edge) => Boolean(layout.boxes[edge.source]) && Boolean(layout.boxes[edge.target]));
64
+ const result = new Set<string>([id]);
65
+
66
+ const walk = (endpoint: (edge: GraphEdge) => string, neighbour: (edge: GraphEdge) => string) => {
67
+ const visited = new Set<string>([id]);
68
+ const queue = [id];
69
+
70
+ while (queue.length > 0) {
71
+ const current = queue.shift()!;
72
+
73
+ for (const edge of drawn) {
74
+ if (endpoint(edge) !== current) continue;
75
+
76
+ result.add(edge.id);
77
+
78
+ const other = neighbour(edge);
79
+
80
+ result.add(other);
81
+ if (!visited.has(other)) {
82
+ visited.add(other);
83
+ queue.push(other);
84
+ }
85
+ }
86
+ }
87
+ };
88
+
89
+ walk(
90
+ (edge) => edge.target,
91
+ (edge) => edge.source,
92
+ );
93
+ walk(
94
+ (edge) => edge.source,
95
+ (edge) => edge.target,
96
+ );
97
+
98
+ return result;
99
+ }
@@ -0,0 +1,194 @@
1
+ // Pure derivation of the dependency graph's nodes, chips, and edges, and the
2
+ // Dependencies list's rows, from planning.json's items. graph-layout.ts turns
3
+ // GraphData into positioned React Flow nodes and edges; nothing here lays
4
+ // anything out or touches the DOM. The URL state and chain tracing the island
5
+ // uses live in graph-state.ts, re-exported at the end.
6
+
7
+ import { features } from './planning';
8
+ import type { Feature } from './planning';
9
+ import type { Size } from './planning-types';
10
+ import type { Planning } from './planning-types';
11
+ import type { Target } from './references';
12
+
13
+ export type GraphNodeKind = 'item' | 'done' | 'dropped' | 'missing';
14
+
15
+ export interface GraphNode {
16
+ id: string;
17
+ kind: GraphNodeKind;
18
+ /** `null` for a `missing` chip. */
19
+ title: string | null;
20
+ /** `known.get(id)?.href ?? null`. */
21
+ href: string | null;
22
+ /** Items only; `null` for a chip. */
23
+ milestone: string | null;
24
+ size: Size | null;
25
+ /** Items only; `null` for a chip. */
26
+ section: 'now' | 'next' | 'later' | null;
27
+ /** Items only; `null` for a chip. */
28
+ owner: string | null;
29
+ /** `label === 'blocked' || status?.value === 'blocked'`. */
30
+ blocked: boolean;
31
+ /** `section === 'now'`. */
32
+ active: boolean;
33
+ /** Distinct Depends on + Revisits IDs that resolve to a done or dropped node; a repeated ID counts once. */
34
+ donePrerequisites: number;
35
+ }
36
+
37
+ export interface GraphEdge {
38
+ /** `${source}>${target}:${kind}:${n}`, `n` counts repeats of the same source, target, and kind from 0. */
39
+ id: string;
40
+ /** The prerequisite, or the item being revisited. */
41
+ source: string;
42
+ /** The waiting item, or the revision. */
43
+ target: string;
44
+ kind: 'depends' | 'revisits';
45
+ /** `true` when `source` is a done, dropped, or missing node. */
46
+ fromChip: boolean;
47
+ }
48
+
49
+ export interface GraphData {
50
+ nodes: GraphNode[];
51
+ edges: GraphEdge[];
52
+ }
53
+
54
+ export interface Ref {
55
+ id: string;
56
+ /** `<ID> <title>`, or `<ID> not found` when the ID resolves to no node. */
57
+ label: string;
58
+ href: string | null;
59
+ }
60
+
61
+ export interface DependencyRow {
62
+ id: string;
63
+ title: string;
64
+ href: string | null;
65
+ waitsOn: Ref[];
66
+ waitedOnBy: Ref[];
67
+ /** The row's own `Revisits` target, or `null`. */
68
+ revisits: Ref | null;
69
+ /** Open items whose `Revisits` names this row's item. */
70
+ revisedBy: Ref[];
71
+ }
72
+
73
+ const OPEN_STATES = new Set<Feature['state']>(['now', 'next', 'later']);
74
+
75
+ /** An ID's node kind, from the full feature list: an open item, its log state, or missing. */
76
+ function classify(id: string, all: Feature[]): GraphNodeKind {
77
+ const feature = all.find((candidate) => candidate.id === id);
78
+
79
+ if (!feature) return 'missing';
80
+
81
+ return OPEN_STATES.has(feature.state) ? 'item' : (feature.state as 'done' | 'dropped');
82
+ }
83
+
84
+ /** The next `${source}>${target}:${kind}` edge ID, counting repeats of the same triple from 0. */
85
+ function nextEdgeId(counts: Map<string, number>, source: string, target: string, kind: GraphEdge['kind']): string {
86
+ const key = `${source}>${target}:${kind}`;
87
+ const n = counts.get(key) ?? 0;
88
+
89
+ counts.set(key, n + 1);
90
+
91
+ return `${key}:${n}`;
92
+ }
93
+
94
+ /**
95
+ * The graph's nodes and edges: one node per open item (Now, Next, Later, in
96
+ * `features()` order), then one chip per done, dropped, or missing ID an open
97
+ * item's `Depends on` or `Revisits` names, sorted by ID. An edge runs from the
98
+ * prerequisite or original to the waiting or revising item.
99
+ */
100
+ export function graphData(planning: Planning, known: Map<string, Pick<Target, 'href'>>): GraphData {
101
+ const all = features(planning);
102
+ const open = all.filter((feature) => OPEN_STATES.has(feature.state));
103
+ const chipIds = new Set<string>();
104
+ const edgeCounts = new Map<string, number>();
105
+ const edges: GraphEdge[] = [];
106
+
107
+ const addEdge = (source: string, target: string, kind: GraphEdge['kind']) => {
108
+ const kindOfSource = classify(source, all);
109
+
110
+ edges.push({ id: nextEdgeId(edgeCounts, source, target, kind), source, target, kind, fromChip: kindOfSource !== 'item' });
111
+ if (kindOfSource !== 'item') chipIds.add(source);
112
+ };
113
+
114
+ for (const feature of open) {
115
+ for (const dep of feature.dependsOn) addEdge(dep, feature.id, 'depends');
116
+ if (feature.revisits) addEdge(feature.revisits, feature.id, 'revisits');
117
+ }
118
+
119
+ const donePrerequisites = (feature: Feature): number =>
120
+ new Set(
121
+ [...feature.dependsOn, ...(feature.revisits ? [feature.revisits] : [])].filter((id) => {
122
+ const kind = classify(id, all);
123
+
124
+ return kind === 'done' || kind === 'dropped';
125
+ }),
126
+ ).size;
127
+
128
+ const itemNodes: GraphNode[] = open.map((feature) => ({
129
+ id: feature.id,
130
+ kind: 'item',
131
+ title: feature.title,
132
+ href: known.get(feature.id)?.href ?? null,
133
+ milestone: feature.milestone,
134
+ size: feature.size,
135
+ section: feature.state as 'now' | 'next' | 'later',
136
+ owner: feature.owner,
137
+ blocked: feature.label === 'blocked' || feature.status?.value === 'blocked',
138
+ active: feature.state === 'now',
139
+ donePrerequisites: donePrerequisites(feature),
140
+ }));
141
+
142
+ const chipNodes: GraphNode[] = [...chipIds]
143
+ .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
144
+ .map((id) => {
145
+ const feature = all.find((candidate) => candidate.id === id) ?? null;
146
+
147
+ return {
148
+ id,
149
+ kind: classify(id, all),
150
+ title: feature?.title ?? null,
151
+ href: known.get(id)?.href ?? null,
152
+ milestone: null,
153
+ size: null,
154
+ section: null,
155
+ owner: null,
156
+ blocked: false,
157
+ active: false,
158
+ donePrerequisites: 0,
159
+ };
160
+ });
161
+
162
+ return { nodes: [...itemNodes, ...chipNodes], edges };
163
+ }
164
+
165
+ /** One row per item node, in node order, with its waits-on, waited-on-by, revisits, and revised-by references. */
166
+ export function dependencyRows(data: GraphData): DependencyRow[] {
167
+ const nodeById = new Map(data.nodes.map((node) => [node.id, node]));
168
+ const ref = (id: string): Ref => {
169
+ const title = nodeById.get(id)?.title ?? null;
170
+
171
+ return { id, label: title ? `${id} ${title}` : `${id} not found`, href: nodeById.get(id)?.href ?? null };
172
+ };
173
+ const depends = data.edges.filter((edge) => edge.kind === 'depends');
174
+ const revisits = data.edges.filter((edge) => edge.kind === 'revisits');
175
+
176
+ return data.nodes
177
+ .filter((node) => node.kind === 'item')
178
+ .map((node) => {
179
+ const ownRevisits = revisits.find((edge) => edge.target === node.id) ?? null;
180
+
181
+ return {
182
+ id: node.id,
183
+ title: node.title!,
184
+ href: node.href,
185
+ waitsOn: depends.filter((edge) => edge.target === node.id).map((edge) => ref(edge.source)),
186
+ waitedOnBy: depends.filter((edge) => edge.source === node.id).map((edge) => ref(edge.target)),
187
+ revisits: ownRevisits ? ref(ownRevisits.source) : null,
188
+ revisedBy: revisits.filter((edge) => edge.source === node.id).map((edge) => ref(edge.target)),
189
+ };
190
+ });
191
+ }
192
+
193
+ export { chainOf, graphQuery, layoutKey, parseGraphQuery, resolveFocus } from './graph-state';
194
+ export type { GraphState } from './graph-state';
@@ -0,0 +1,39 @@
1
+ // Links the known IDs and brief paths inside rendered HTML (an ADR's sections),
2
+ // the way LinkedText does for plain text: the same linkify runs, so a link here
3
+ // is one `references()` already lists. Text inside an existing link stays as
4
+ // written; IDs inside code are linked, as LinkedText links them in plain text,
5
+ // because the link test requires every known ID on a page to be a link.
6
+
7
+ import { linkify, type Target } from './references';
8
+
9
+ const SKIP = new Set(['a']);
10
+ const escapeAttribute = (text: string) => text.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
11
+
12
+ /** The HTML with each known reference in its text wrapped in a link to its page. */
13
+ export function linkHtml(html: string, known: Map<string, Target>): string {
14
+ const open: string[] = [];
15
+ let out = '';
16
+
17
+ for (const part of html.split(/(<[^>]+>)/)) {
18
+ if (part.startsWith('<')) {
19
+ const tag = /^<\/?([a-zA-Z][\w-]*)/.exec(part)?.[1]?.toLowerCase();
20
+
21
+ if (tag && SKIP.has(tag) && !part.endsWith('/>')) {
22
+ if (part.startsWith('</')) {
23
+ const at = open.lastIndexOf(tag);
24
+
25
+ if (at !== -1) open.splice(at, 1);
26
+ } else open.push(tag);
27
+ }
28
+ out += part;
29
+ } else if (open.length > 0 || part === '') {
30
+ out += part;
31
+ } else {
32
+ out += linkify(part, known)
33
+ .map((run) => (run.target?.href ? `<a href="${escapeAttribute(run.target.href)}">${run.text}</a>` : run.text))
34
+ .join('');
35
+ }
36
+ }
37
+
38
+ return out;
39
+ }
@@ -1,4 +1,4 @@
1
- // The part of planning.json (pm-export, schemaVersion 3) the site reads.
1
+ // The part of planning.json (pm-export, schemaVersion 5) the site reads.
2
2
  // The full shape is planning.schema.json; only what the pages use is typed.
3
3
 
4
4
  export type Owner = 'agent' | 'user' | 'both';
@@ -12,6 +12,14 @@ export interface ItemRef {
12
12
  title: string;
13
13
  }
14
14
 
15
+ export interface NowItem extends ItemRef {
16
+ serves: string[];
17
+ owner: Owner | null;
18
+ size: Size | null;
19
+ dependsOn: string[];
20
+ revisits: string | null;
21
+ }
22
+
15
23
  export interface Milestone {
16
24
  id: string;
17
25
  name: string;
@@ -146,8 +154,28 @@ export interface RemovedRisk {
146
154
  reason: string | null;
147
155
  }
148
156
 
157
+ export type AdrStatus = 'proposed' | 'accepted' | 'deprecated' | 'superseded';
158
+
159
+ /** One ADR, whole: the four sections are the Markdown under each heading; `""` when empty, `null` when missing. */
160
+ export interface Adr {
161
+ id: string;
162
+ path: string;
163
+ title: string;
164
+ status: AdrStatus | null;
165
+ supersededBy: string | null;
166
+ date: string | null;
167
+ category: string | null;
168
+ supersedes: string | null;
169
+ item: string | null;
170
+ source: string | null;
171
+ context: string | null;
172
+ decision: string | null;
173
+ alternatives: string | null;
174
+ consequences: string | null;
175
+ }
176
+
149
177
  export interface Planning {
150
- schemaVersion: 3;
178
+ schemaVersion: 5;
151
179
  generatedAt: string;
152
180
  source: { branch: string | null; head: string | null };
153
181
  vision: {
@@ -167,7 +195,7 @@ export interface Planning {
167
195
  };
168
196
  now: {
169
197
  status: 'idle' | 'active';
170
- item: ItemRef | null;
198
+ item: NowItem | null;
171
199
  stage: Stage | null;
172
200
  session: string | null;
173
201
  brief: string | null;
@@ -188,6 +216,7 @@ export interface Planning {
188
216
  inbox: InboxEntry[];
189
217
  briefs: Brief[];
190
218
  risks: { open: Risk[]; closed: Risk[]; removed: RemovedRisk[] };
219
+ adrs: Adr[];
191
220
  counts: {
192
221
  next: number;
193
222
  later: number;