@purview-dev/pm-docs-site 0.1.0-pre.1 → 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 (84) hide show
  1. package/README.md +130 -18
  2. package/dist/cli.d.ts +2 -0
  3. package/dist/cli.js +91 -0
  4. package/dist/dev-env.d.ts +2 -0
  5. package/dist/dev-env.js +13 -0
  6. package/dist/fs-allow.d.ts +2 -0
  7. package/dist/fs-allow.js +11 -0
  8. package/dist/index.d.ts +7 -0
  9. package/dist/index.js +152 -0
  10. package/dist/options.d.ts +5 -0
  11. package/dist/options.js +46 -0
  12. package/dist/repo-docs.d.ts +33 -0
  13. package/dist/repo-docs.js +94 -0
  14. package/dist/schema-version.d.ts +27 -0
  15. package/dist/schema-version.js +48 -0
  16. package/dist/sidebar.d.ts +10 -0
  17. package/dist/sidebar.js +32 -0
  18. package/dist/site-options.d.ts +9 -0
  19. package/dist/site-options.js +44 -0
  20. package/dist/types.d.ts +47 -0
  21. package/dist/types.js +4 -0
  22. package/lib/{repo-docs.mjs → repo-docs.ts} +22 -46
  23. package/lib/schema-version.ts +59 -0
  24. package/{index.d.ts → lib/types.ts} +5 -6
  25. package/package.json +19 -9
  26. package/src/components/FeatureSummary.astro +30 -9
  27. package/src/components/FeatureTable.astro +1 -1
  28. package/src/components/ItemDetail.astro +1 -1
  29. package/src/components/ItemDialog.astro +12 -8
  30. package/src/components/PlanInteractions.astro +15 -3
  31. package/src/components/RefLink.astro +7 -4
  32. package/src/components/board/Board.tsx +252 -0
  33. package/src/components/board/KanbanItemCard.tsx +131 -0
  34. package/src/components/board/LinkRuns.tsx +21 -0
  35. package/src/components/board/TaskKanbanCard.tsx +83 -0
  36. package/src/components/board/useBoardUrlState.ts +41 -0
  37. package/src/components/decisions/Decisions.tsx +162 -0
  38. package/src/components/decisions/useDecisionsUrlState.ts +29 -0
  39. package/src/components/graph/Graph.tsx +290 -0
  40. package/src/components/graph/GraphNodes.tsx +120 -0
  41. package/src/components/graph/useGraphUrlState.ts +58 -0
  42. package/src/components/lib/KanbanItemCard.astro +7 -11
  43. package/src/components/lib/StatusTimelineFeed.astro +3 -2
  44. package/src/components/lib/TaskKanbanCard.astro +2 -1
  45. package/src/components/timeline/Timeline.tsx +192 -0
  46. package/src/components/timeline/useTimelineLayout.ts +39 -0
  47. package/src/content.config.ts +22 -6
  48. package/src/env.d.ts +2 -2
  49. package/src/lib/board-data.ts +84 -0
  50. package/src/lib/board.ts +209 -0
  51. package/src/lib/decisions.ts +100 -0
  52. package/src/lib/graph-layout.ts +270 -0
  53. package/src/lib/graph-state.ts +99 -0
  54. package/src/lib/graph.ts +194 -0
  55. package/src/lib/link-html.ts +39 -0
  56. package/src/lib/planning-types.ts +32 -3
  57. package/src/lib/planning.ts +94 -52
  58. package/src/lib/ref-boundary.ts +19 -0
  59. package/src/lib/references.ts +67 -8
  60. package/src/lib/timeline-state.ts +119 -0
  61. package/src/lib/timeline.ts +51 -0
  62. package/src/loaders/adrs.ts +43 -0
  63. package/src/loaders/repo-docs.ts +3 -3
  64. package/src/pages/404.astro +18 -0
  65. package/src/pages/index.astro +1 -1
  66. package/src/pages/plan/board.astro +14 -113
  67. package/src/pages/plan/log.astro +18 -1
  68. package/src/pages/plan/roadmap.astro +21 -3
  69. package/src/routes/plan/decisions/[id].astro +93 -0
  70. package/src/routes/plan/decisions.astro +52 -0
  71. package/src/routes/plan/graph.astro +80 -0
  72. package/src/routes/plan/milestones/index.astro +2 -2
  73. package/src/routes/plan/now.astro +2 -3
  74. package/src/scripts/plan.ts +32 -46
  75. package/src/styles/components.css +244 -13
  76. package/src/styles/graph.css +296 -0
  77. package/src/styles/kanban.css +277 -0
  78. package/src/styles/timeline.css +210 -0
  79. package/cli.mjs +0 -120
  80. package/index.mjs +0 -97
  81. package/lib/options.mjs +0 -67
  82. package/lib/schema-version.mjs +0 -29
  83. package/lib/sidebar.mjs +0 -47
  84. package/lib/site-options.mjs +0 -38
@@ -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;
@@ -9,10 +9,10 @@ import { relative, sep } from 'node:path';
9
9
 
10
10
  import config from 'virtual:pm-docs-site/config';
11
11
 
12
- import type { DocsSource } from '../../index';
13
- import { pagesOf } from '../../lib/repo-docs.mjs';
14
- import { checkSchemaVersion, PlanningExportError, SUPPORTED_SCHEMA_VERSIONS } from '../../lib/schema-version.mjs';
15
- import type { Brief, InboxEntry, Level, Milestone, Owner, Planning, Rag, Risk, RoadmapItem, Size, Stage } from './planning-types';
12
+ import type { DocsSource } from '../../lib/types.ts';
13
+ import { pagesOf } from '../../lib/repo-docs.ts';
14
+ import { parseExport, PlanningExportError, SUPPORTED_SCHEMA_VERSIONS } from '../../lib/schema-version.ts';
15
+ import type { Adr, Brief, InboxEntry, Level, Milestone, Owner, Planning, Rag, Risk, RoadmapItem, Size, Stage } from './planning-types';
16
16
 
17
17
  export { PlanningExportError, SUPPORTED_SCHEMA_VERSIONS };
18
18
 
@@ -26,17 +26,7 @@ export function loadPlanning(path: string = config.planning): Planning {
26
26
  throw new PlanningExportError(`No plan export at ${path}.`);
27
27
  }
28
28
 
29
- let planning: { schemaVersion?: unknown };
30
-
31
- try {
32
- planning = JSON.parse(text);
33
- } catch (error) {
34
- throw new PlanningExportError(`${path} is not valid JSON (${(error as Error).message}).`);
35
- }
36
-
37
- checkSchemaVersion(planning.schemaVersion, path);
38
-
39
- return planning as Planning;
29
+ return parseExport(text, path) as unknown as Planning;
40
30
  }
41
31
 
42
32
  /** Board-card priority from item size — the PM state has no priority of its own. */
@@ -63,6 +53,7 @@ export interface RoadmapGroup {
63
53
  id: string;
64
54
  name: string;
65
55
  status: string | null;
56
+ target: string | null;
66
57
  exitCriteria: string | null;
67
58
  isFocus: boolean;
68
59
  } | null;
@@ -71,64 +62,84 @@ export interface RoadmapGroup {
71
62
  progress: { done: number; total: number };
72
63
  }
73
64
 
65
+ /** Lower wins: a non-null ID keeps only the event in this state, the same precedence `features()` uses. */
66
+ const EVENT_PRECEDENCE: Record<TimelineEvent['status'], number> = { active: 0, pending: 1, done: 2 };
67
+
68
+ /**
69
+ * Each non-null ID kept once across the whole page, in the higher-precedence
70
+ * state, so a group never lists an ID that another group's count holds.
71
+ */
72
+ function dedupeEvents<T extends { event: TimelineEvent }>(entries: T[]): T[] {
73
+ const best = new Map<string, TimelineEvent>();
74
+
75
+ for (const { event } of entries) {
76
+ if (event.id === null) continue;
77
+
78
+ const current = best.get(event.id);
79
+
80
+ if (!current || EVENT_PRECEDENCE[event.status] < EVENT_PRECEDENCE[current.status]) best.set(event.id, event);
81
+ }
82
+
83
+ return entries.filter(({ event }) => event.id === null || best.get(event.id) === event);
84
+ }
85
+
74
86
  /**
75
- * One group per milestone in strategy order, then "no milestone": the Done log
76
- * (newest first), the Now item, then Next and Later in roadmap order.
87
+ * One group per milestone in strategy order, then "no milestone" when it
88
+ * counts an item: the Done log (newest first), the Now item, then Next and
89
+ * Later in roadmap order. An ID that appears more than once (for example done
90
+ * under one milestone and still queued under another) is listed once on the
91
+ * page, in the state and group `features()` counts it in.
77
92
  */
78
93
  export function roadmapGroups(planning: Planning): RoadmapGroup[] {
79
94
  const groupOf = (milestone: string | null) => milestoneId(milestone, planning.strategy.milestones);
80
95
  const focus = planning.strategy.focus.milestone ?? '';
96
+ const summaries = milestoneSummaries(planning);
97
+ const progressFor = (id: string | null) => summaries.find((summary) => summary.id === id)?.progress ?? { done: 0, total: 0 };
81
98
 
82
- const eventsFor = (id: string | null): TimelineEvent[] => [
83
- ...planning.log.done
84
- .filter((entry) => groupOf(entry.milestone) === id)
85
- .map((entry) => ({
86
- id: entry.id,
87
- title: label(entry.id, entry.title),
88
- desc: entry.result ?? '',
89
- time: entry.date,
90
- status: 'done' as const,
91
- })),
92
- ...(planning.now.item && groupOf(planning.now.milestone) === id
99
+ const placed = dedupeEvents([
100
+ ...planning.log.done.map((entry) => ({
101
+ group: groupOf(entry.milestone),
102
+ event: { id: entry.id, title: label(entry.id, entry.title), desc: entry.result ?? '', time: entry.date, status: 'done' as const },
103
+ })),
104
+ ...(planning.now.item
93
105
  ? [
94
106
  {
95
- id: planning.now.item.id,
96
- title: label(planning.now.item.id, planning.now.item.title),
97
- desc: planning.now.stage ? `In progress: ${planning.now.stage}` : 'In progress',
98
- time: 'Now',
99
- status: 'active' as const,
107
+ group: groupOf(planning.now.milestone),
108
+ event: {
109
+ id: planning.now.item.id,
110
+ title: label(planning.now.item.id, planning.now.item.title),
111
+ desc: planning.now.stage ? `In progress: ${planning.now.stage}` : 'In progress',
112
+ time: 'Now',
113
+ status: 'active' as const,
114
+ },
100
115
  },
101
116
  ]
102
117
  : []),
103
- ...[...planning.roadmap.next, ...planning.roadmap.later]
104
- .filter((item) => groupOf(item.milestone) === id)
105
- .map((item) => ({
106
- id: item.id,
107
- title: label(item.id, item.title),
108
- desc: item.doneWhen,
109
- time: item.section === 'next' ? 'Next' : 'Later',
110
- status: 'pending' as const,
111
- })),
112
- ];
118
+ ...[...planning.roadmap.next, ...planning.roadmap.later].map((item) => ({
119
+ group: groupOf(item.milestone),
120
+ event: { id: item.id, title: label(item.id, item.title), desc: item.doneWhen, time: item.section === 'next' ? 'Next' : 'Later', status: 'pending' as const },
121
+ })),
122
+ ]);
123
+
124
+ const eventsFor = (id: string | null): TimelineEvent[] => placed.filter((entry) => entry.group === id).map((entry) => entry.event);
113
125
 
114
126
  const groups: RoadmapGroup[] = planning.strategy.milestones.map((milestone) => ({
115
127
  milestone: {
116
128
  id: milestone.id,
117
129
  name: milestone.name,
118
130
  status: milestone.status,
131
+ target: normaliseTarget(milestone.target),
119
132
  exitCriteria: milestone.exitCriteria,
120
133
  isFocus: milestoneId(focus, [milestone]) !== null,
121
134
  },
122
- ...withProgress(eventsFor(milestone.id)),
135
+ events: eventsFor(milestone.id),
136
+ progress: progressFor(milestone.id),
123
137
  }));
124
138
 
125
- const unassigned = eventsFor(null);
126
-
127
- return unassigned.length > 0 ? [...groups, { milestone: null, ...withProgress(unassigned) }] : groups;
128
- }
139
+ // The same rule as milestoneCards: shown only when it counts an item.
140
+ const unassignedProgress = progressFor(null);
129
141
 
130
- function withProgress(events: TimelineEvent[]): Pick<RoadmapGroup, 'events' | 'progress'> {
131
- return { events, progress: { done: events.filter((event) => event.status === 'done').length, total: events.length } };
142
+ return unassignedProgress.total > 0 ? [...groups, { milestone: null, events: eventsFor(null), progress: unassignedProgress }] : groups;
132
143
  }
133
144
 
134
145
  const LEVELS: Level[] = ['low', 'medium', 'high'];
@@ -214,6 +225,13 @@ export function planProgress(plan: { checked: number; total: number } | null): n
214
225
  return plan && plan.total > 0 ? Math.round((plan.checked / plan.total) * 100) : 0;
215
226
  }
216
227
 
228
+ /** A milestone's target, written as given; `null`, empty, or `none` (any case) is no target. */
229
+ export function normaliseTarget(target: string | null): string | null {
230
+ const text = target?.trim() ?? '';
231
+
232
+ return text === '' || text.toLowerCase() === 'none' ? null : text;
233
+ }
234
+
217
235
  /** Inbox severity as a card priority: the inbox has no priority of its own. */
218
236
  export function severityToPriority(severity: InboxEntry['severity']): 'low' | 'medium' | 'high' | 'urgent' {
219
237
  return severity === 'blocker' ? 'urgent' : severity === 'major' ? 'high' : severity === 'minor' ? 'medium' : 'low';
@@ -272,8 +290,11 @@ export function features(planning: Planning): Feature[] {
272
290
  title: planning.now.item.title,
273
291
  state: 'now' as const,
274
292
  milestone: milestoneId(planning.now.milestone, known),
275
- owner: planning.board.columns.now[0]?.owner ?? null,
276
- size: planning.board.columns.now[0]?.size ?? null,
293
+ owner: planning.now.item.owner,
294
+ size: planning.now.item.size,
295
+ serves: planning.now.item.serves,
296
+ dependsOn: planning.now.item.dependsOn,
297
+ revisits: planning.now.item.revisits,
277
298
  doneWhen: planning.now.doneWhen,
278
299
  brief: planning.now.brief,
279
300
  stage: planning.now.stage,
@@ -319,6 +340,16 @@ export function dependents(all: Feature[], id: string): Feature[] {
319
340
  return all.filter((feature) => feature.dependsOn.includes(id));
320
341
  }
321
342
 
343
+ /** The ADRs whose `Item` is this item, by ID number. */
344
+ export function adrsOf(planning: Planning, itemId: string): Adr[] {
345
+ return planning.adrs.filter((adr) => adr.item === itemId).sort((a, b) => Number(a.id.slice(4)) - Number(b.id.slice(4)));
346
+ }
347
+
348
+ /** The page of one ADR on this site. */
349
+ export function adrHref(id: string): string {
350
+ return `/plan/decisions/${id.toLowerCase()}/`;
351
+ }
352
+
322
353
  /** The brief a feature links to, by its `Brief` path, else by the brief's own ID. */
323
354
  export function briefOf(planning: Planning, feature: Pick<Feature, 'id' | 'brief'>): Brief | null {
324
355
  return planning.briefs.find((brief) => brief.path === feature.brief) ?? planning.briefs.find((brief) => brief.id === feature.id) ?? null;
@@ -366,6 +397,17 @@ export function milestoneSummaries(planning: Planning, all: Feature[] = features
366
397
  return unassigned.features.length > 0 ? [...groups, unassigned] : groups;
367
398
  }
368
399
 
400
+ /**
401
+ * `milestoneSummaries`, with `No milestone` dropped when every unassigned
402
+ * item is dropped (its `progress.total` is then `0`, since dropped items are
403
+ * never counted). The Milestones page and the Roadmap page's timeline share
404
+ * this rule; `milestoneSummaries` itself is unchanged, because the `none`
405
+ * milestone page still lists a dropped unassigned item.
406
+ */
407
+ export function milestoneCards(planning: Planning, all: Feature[] = features(planning)): MilestoneSummary[] {
408
+ return milestoneSummaries(planning, all).filter((summary) => summary.id !== null || summary.progress.total > 0);
409
+ }
410
+
369
411
  /** An inbox file's source as a card's initials: `agent (…)` → `AG`, anything else (the user) → `YOU`. */
370
412
  export function sourceInitials(source: string | null): string {
371
413
  return /^agent\b/i.test(source?.trim() ?? '') ? 'AG' : 'YOU';
@@ -0,0 +1,19 @@
1
+ // Where a reference (an ID or a brief path) may start and end in prose. The
2
+ // site's links (linkify) and the link test's scanner (test/scan.ts) both build
3
+ // their patterns here, so a reference is linked exactly where the test looks
4
+ // for one. No imports, so the test helper can load it outside Astro.
5
+
6
+ /**
7
+ * Not inside a word, a path, or a hyphenated token. An ID after `/` is
8
+ * deliberately not linked (`M1/M2` links only `M1`, and `./planning/briefs/x.md`
9
+ * stays plain), because a `/` also starts a path segment (`src/M1`).
10
+ * test/references.test.ts pins it.
11
+ */
12
+ export const REF_BEFORE = String.raw`(?<![\w/-])`;
13
+ /** Not followed by more of a word or a hyphenated token. */
14
+ export const REF_AFTER = String.raw`(?![\w-])`;
15
+
16
+ /** A global pattern for any of `alternatives` (already escaped; longest first) at reference boundaries. */
17
+ export function refPattern(alternatives: string[]): RegExp {
18
+ return new RegExp(`${REF_BEFORE}(?:${alternatives.join('|')})${REF_AFTER}`, 'g');
19
+ }