@purview-dev/pm-docs-site 0.0.0-stage → 0.1.0-pre.2
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.
- package/LICENSE.md +9 -0
- package/README.md +219 -2
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +90 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +118 -0
- package/dist/options.d.ts +5 -0
- package/dist/options.js +46 -0
- package/dist/repo-docs.d.ts +33 -0
- package/dist/repo-docs.js +94 -0
- package/dist/schema-version.d.ts +10 -0
- package/dist/schema-version.js +19 -0
- package/dist/sidebar.d.ts +10 -0
- package/dist/sidebar.js +30 -0
- package/dist/site-options.d.ts +9 -0
- package/dist/site-options.js +39 -0
- package/dist/types.d.ts +47 -0
- package/dist/types.js +4 -0
- package/lib/repo-docs.ts +124 -0
- package/lib/schema-version.ts +24 -0
- package/package.json +68 -5
- package/src/components/ExportStamp.astro +29 -0
- package/src/components/FeatureSummary.astro +160 -0
- package/src/components/FeatureTable.astro +64 -0
- package/src/components/ItemDetail.astro +16 -0
- package/src/components/ItemDialog.astro +16 -0
- package/src/components/LinkedFrom.astro +33 -0
- package/src/components/LinkedText.astro +12 -0
- package/src/components/PlanInteractions.astro +30 -0
- package/src/components/RefLink.astro +18 -0
- package/src/components/StateBadge.astro +15 -0
- package/src/components/board/Board.tsx +244 -0
- package/src/components/board/KanbanItemCard.tsx +129 -0
- package/src/components/board/LinkRuns.tsx +21 -0
- package/src/components/board/TaskKanbanCard.tsx +81 -0
- package/src/components/board/useBoardUrlState.ts +41 -0
- package/src/components/lib/KanbanItemCard.astro +264 -0
- package/src/components/lib/StatusTimelineFeed.astro +194 -0
- package/src/components/lib/TaskKanbanCard.astro +215 -0
- package/src/components/timeline/Timeline.tsx +159 -0
- package/src/components/timeline/useTimelineLayout.ts +39 -0
- package/src/content.config.ts +16 -0
- package/src/env.d.ts +7 -0
- package/src/lib/board-data.ts +84 -0
- package/src/lib/board.ts +209 -0
- package/src/lib/planning-types.ts +207 -0
- package/src/lib/planning.ts +415 -0
- package/src/lib/references.ts +360 -0
- package/src/lib/timeline.ts +156 -0
- package/src/loaders/repo-docs.ts +69 -0
- package/src/pages/index.astro +158 -0
- package/src/pages/plan/board.astro +41 -0
- package/src/pages/plan/log.astro +83 -0
- package/src/pages/plan/risks/[id].astro +72 -0
- package/src/pages/plan/risks.astro +263 -0
- package/src/pages/plan/roadmap.astro +108 -0
- package/src/routes/plan/briefs.astro +66 -0
- package/src/routes/plan/features/[id].astro +113 -0
- package/src/routes/plan/features/index.astro +29 -0
- package/src/routes/plan/inbox.astro +78 -0
- package/src/routes/plan/milestones/[milestone].astro +113 -0
- package/src/routes/plan/milestones/index.astro +56 -0
- package/src/routes/plan/now.astro +135 -0
- package/src/routes/plan/strategy.astro +194 -0
- package/src/scripts/plan.ts +40 -0
- package/src/styles/components.css +491 -0
- package/src/styles/kanban.css +277 -0
- package/src/styles/timeline.css +210 -0
- package/src/styles/width.css +4 -0
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
// The part of planning.json (pm-export, schemaVersion 3) the site reads.
|
|
2
|
+
// The full shape is planning.schema.json; only what the pages use is typed.
|
|
3
|
+
|
|
4
|
+
export type Owner = 'agent' | 'user' | 'both';
|
|
5
|
+
export type Size = 'S' | 'M' | 'L';
|
|
6
|
+
export type Level = 'low' | 'medium' | 'high';
|
|
7
|
+
export type Rag = 'red' | 'amber' | 'green';
|
|
8
|
+
export type Stage = 'design' | 'plan' | 'execute' | 'finish';
|
|
9
|
+
|
|
10
|
+
export interface ItemRef {
|
|
11
|
+
id: string;
|
|
12
|
+
title: string;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export interface Milestone {
|
|
16
|
+
id: string;
|
|
17
|
+
name: string;
|
|
18
|
+
serves: string[];
|
|
19
|
+
exitCriteria: string | null;
|
|
20
|
+
target: string | null;
|
|
21
|
+
status: string | null;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface RoadmapItem {
|
|
25
|
+
id: string;
|
|
26
|
+
title: string;
|
|
27
|
+
section: 'next' | 'later';
|
|
28
|
+
position: number;
|
|
29
|
+
label: 'next' | 'later' | 'blocked' | 'waiting';
|
|
30
|
+
serves: string[];
|
|
31
|
+
milestone: string | null;
|
|
32
|
+
owner: Owner;
|
|
33
|
+
doneWhen: string;
|
|
34
|
+
size: Size;
|
|
35
|
+
dependsOn: string[];
|
|
36
|
+
status: { value: 'ready' | 'paused' | 'blocked'; reason: string | null; since: string | null };
|
|
37
|
+
brief: string | null;
|
|
38
|
+
note: string | null;
|
|
39
|
+
revisits: string | null;
|
|
40
|
+
claimable: boolean;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export interface Card {
|
|
44
|
+
id: string;
|
|
45
|
+
title: string;
|
|
46
|
+
owner: Owner | null;
|
|
47
|
+
size: Size | null;
|
|
48
|
+
detail: string | null;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export interface DoneEntry {
|
|
52
|
+
date: string;
|
|
53
|
+
id: string | null;
|
|
54
|
+
title: string;
|
|
55
|
+
milestone: string | null;
|
|
56
|
+
owner: string | null;
|
|
57
|
+
plan: string | null;
|
|
58
|
+
result: string | null;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export interface DroppedEntry {
|
|
62
|
+
date: string;
|
|
63
|
+
id: string | null;
|
|
64
|
+
title: string;
|
|
65
|
+
reason: string | null;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export interface Activity {
|
|
69
|
+
date: string;
|
|
70
|
+
kind: 'done' | 'dropped' | 'review';
|
|
71
|
+
id: string | null;
|
|
72
|
+
title: string | null;
|
|
73
|
+
milestone: string | null;
|
|
74
|
+
owner: string | null;
|
|
75
|
+
result: string | null;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export interface Checkpoint {
|
|
79
|
+
at: string;
|
|
80
|
+
stoppedAt: string | null;
|
|
81
|
+
nextAction: string | null;
|
|
82
|
+
startWith: string | null;
|
|
83
|
+
decisions: string | null;
|
|
84
|
+
context: string | null;
|
|
85
|
+
openQuestion: string | null;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export interface PlanTask {
|
|
89
|
+
number: number;
|
|
90
|
+
title: string;
|
|
91
|
+
checked: number;
|
|
92
|
+
total: number;
|
|
93
|
+
steps: { text: string; checked: boolean }[];
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export interface InboxEntry {
|
|
97
|
+
file: string;
|
|
98
|
+
title: string;
|
|
99
|
+
captured: string | null;
|
|
100
|
+
source: string | null;
|
|
101
|
+
kind: 'feature' | 'bug' | 'improvement' | 'question' | 'inspiration' | 'tech-debt' | null;
|
|
102
|
+
severity: 'blocker' | 'major' | 'minor' | 'cosmetic' | null;
|
|
103
|
+
affects: string | null;
|
|
104
|
+
context: string | null;
|
|
105
|
+
discuss: 'yes' | 'no';
|
|
106
|
+
related: string[];
|
|
107
|
+
brief: string | null;
|
|
108
|
+
reviewed: string | null;
|
|
109
|
+
idea: string | null;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export interface Brief {
|
|
113
|
+
path: string;
|
|
114
|
+
id: string | null;
|
|
115
|
+
title: string;
|
|
116
|
+
status: string | null;
|
|
117
|
+
origin: string | null;
|
|
118
|
+
updated: string | null;
|
|
119
|
+
decision: string | null;
|
|
120
|
+
problem: string | null;
|
|
121
|
+
doneWhen: string | null;
|
|
122
|
+
revisions: { date: string | null; text: string }[];
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
export interface Risk {
|
|
126
|
+
id: string;
|
|
127
|
+
title: string;
|
|
128
|
+
likelihood: Level;
|
|
129
|
+
impact: Level;
|
|
130
|
+
rag: Rag;
|
|
131
|
+
ragOverride: string | null;
|
|
132
|
+
status: 'open' | 'mitigating' | 'accepted' | 'closed';
|
|
133
|
+
owner: Owner;
|
|
134
|
+
affects: string | null;
|
|
135
|
+
trigger: string | null;
|
|
136
|
+
mitigation: string | null;
|
|
137
|
+
raised: string | null;
|
|
138
|
+
reviewed: string | null;
|
|
139
|
+
closed: string | null;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
export interface RemovedRisk {
|
|
143
|
+
date: string;
|
|
144
|
+
id: string;
|
|
145
|
+
title: string;
|
|
146
|
+
reason: string | null;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
export interface Planning {
|
|
150
|
+
schemaVersion: 3;
|
|
151
|
+
generatedAt: string;
|
|
152
|
+
source: { branch: string | null; head: string | null };
|
|
153
|
+
vision: {
|
|
154
|
+
problem: string | null;
|
|
155
|
+
customer: string | null;
|
|
156
|
+
outcomes: { id: string; text: string }[];
|
|
157
|
+
outOfScope: string[];
|
|
158
|
+
constraints: { timeAvailable: string | null; budget: string | null; stack: string | null };
|
|
159
|
+
};
|
|
160
|
+
strategy: {
|
|
161
|
+
focus: { milestone: string | null; whyNow: string | null };
|
|
162
|
+
milestones: Milestone[];
|
|
163
|
+
bets: { id: string; statement: string; evidence: string | null; signal: string | null; status: string | null }[];
|
|
164
|
+
assumptions: { id: string; statement: string; test: string | null; status: string | null }[];
|
|
165
|
+
notDoing: { thing: string; why: string | null; revisit: string | null }[];
|
|
166
|
+
decisions: { date: string | null; decision: string; why: string | null; rejected: string | null }[];
|
|
167
|
+
};
|
|
168
|
+
now: {
|
|
169
|
+
status: 'idle' | 'active';
|
|
170
|
+
item: ItemRef | null;
|
|
171
|
+
stage: Stage | null;
|
|
172
|
+
session: string | null;
|
|
173
|
+
brief: string | null;
|
|
174
|
+
milestone: string | null;
|
|
175
|
+
spec: string | null;
|
|
176
|
+
plan: string | null;
|
|
177
|
+
started: string | null;
|
|
178
|
+
doneWhen: string[];
|
|
179
|
+
checkpoint: Checkpoint | null;
|
|
180
|
+
};
|
|
181
|
+
plan: { path: string; checked: number; total: number; tasks: PlanTask[] } | null;
|
|
182
|
+
roadmap: { next: RoadmapItem[]; later: RoadmapItem[] };
|
|
183
|
+
board: {
|
|
184
|
+
columns: { now: Card[]; next: Card[]; foryou: Card[]; waiting: Card[]; done: DoneEntry[] };
|
|
185
|
+
activity: Activity[];
|
|
186
|
+
};
|
|
187
|
+
log: { done: DoneEntry[]; dropped: DroppedEntry[]; reviews: { date: string; summary: string | null }[] };
|
|
188
|
+
inbox: InboxEntry[];
|
|
189
|
+
briefs: Brief[];
|
|
190
|
+
risks: { open: Risk[]; closed: Risk[]; removed: RemovedRisk[] };
|
|
191
|
+
counts: {
|
|
192
|
+
next: number;
|
|
193
|
+
later: number;
|
|
194
|
+
nextMax: number;
|
|
195
|
+
openInbox: number;
|
|
196
|
+
discuss: number;
|
|
197
|
+
shapingBriefs: number;
|
|
198
|
+
done: number;
|
|
199
|
+
dropped: number;
|
|
200
|
+
blockers: number;
|
|
201
|
+
openRisks: number;
|
|
202
|
+
redRisks: number;
|
|
203
|
+
amberRisks: number;
|
|
204
|
+
greenRisks: number;
|
|
205
|
+
};
|
|
206
|
+
checks: { reviewDue: boolean; lastReview: string | null; claimable: string[]; drift: boolean };
|
|
207
|
+
}
|
|
@@ -0,0 +1,415 @@
|
|
|
1
|
+
// The plan, read from planning.json and shaped for the plan pages.
|
|
2
|
+
//
|
|
3
|
+
// planning.json is written by the pm-export skill from the Markdown PM state;
|
|
4
|
+
// it is the only source of plan data on this site. Nothing here parses the PM
|
|
5
|
+
// Markdown, and nothing on a page is typed by hand.
|
|
6
|
+
|
|
7
|
+
import { readFileSync } from 'node:fs';
|
|
8
|
+
import { relative, sep } from 'node:path';
|
|
9
|
+
|
|
10
|
+
import config from 'virtual:pm-docs-site/config';
|
|
11
|
+
|
|
12
|
+
import type { DocsSource } from '../../lib/types.ts';
|
|
13
|
+
import { pagesOf } from '../../lib/repo-docs.ts';
|
|
14
|
+
import { checkSchemaVersion, PlanningExportError, SUPPORTED_SCHEMA_VERSIONS } from '../../lib/schema-version.ts';
|
|
15
|
+
import type { Brief, InboxEntry, Level, Milestone, Owner, Planning, Rag, Risk, RoadmapItem, Size, Stage } from './planning-types';
|
|
16
|
+
|
|
17
|
+
export { PlanningExportError, SUPPORTED_SCHEMA_VERSIONS };
|
|
18
|
+
|
|
19
|
+
/** Read and check the export: by default the one the integration's `planning` option names. */
|
|
20
|
+
export function loadPlanning(path: string = config.planning): Planning {
|
|
21
|
+
let text: string;
|
|
22
|
+
|
|
23
|
+
try {
|
|
24
|
+
text = readFileSync(path, 'utf8');
|
|
25
|
+
} catch {
|
|
26
|
+
throw new PlanningExportError(`No plan export at ${path}.`);
|
|
27
|
+
}
|
|
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;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Board-card priority from item size — the PM state has no priority of its own. */
|
|
43
|
+
export function sizeToPriority(size: Size | null): 'low' | 'medium' | 'high' {
|
|
44
|
+
return size === 'L' ? 'high' : size === 'M' ? 'medium' : 'low';
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The owner as a card's initials. A missing owner means `agent` (PM rules). */
|
|
48
|
+
export function initials(owner: Owner | string | null): string {
|
|
49
|
+
return owner === 'user' ? 'YOU' : owner === 'both' ? 'AG+U' : 'AG';
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export interface TimelineEvent {
|
|
53
|
+
/** The item's ID, or `null` for a log line without one. */
|
|
54
|
+
id: string | null;
|
|
55
|
+
title: string;
|
|
56
|
+
desc: string;
|
|
57
|
+
time: string;
|
|
58
|
+
status: 'done' | 'active' | 'pending';
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export interface RoadmapGroup {
|
|
62
|
+
milestone: {
|
|
63
|
+
id: string;
|
|
64
|
+
name: string;
|
|
65
|
+
status: string | null;
|
|
66
|
+
target: string | null;
|
|
67
|
+
exitCriteria: string | null;
|
|
68
|
+
isFocus: boolean;
|
|
69
|
+
} | null;
|
|
70
|
+
events: TimelineEvent[];
|
|
71
|
+
/** Done items against every item in the group (done, in progress and queued). */
|
|
72
|
+
progress: { done: number; total: number };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Lower wins: a non-null ID keeps only the event in this state, the same precedence `features()` uses. */
|
|
76
|
+
const EVENT_PRECEDENCE: Record<TimelineEvent['status'], number> = { active: 0, pending: 1, done: 2 };
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Each non-null ID kept once across the whole page, in the higher-precedence
|
|
80
|
+
* state, so a group never lists an ID that another group's count holds.
|
|
81
|
+
*/
|
|
82
|
+
function dedupeEvents<T extends { event: TimelineEvent }>(entries: T[]): T[] {
|
|
83
|
+
const best = new Map<string, TimelineEvent>();
|
|
84
|
+
|
|
85
|
+
for (const { event } of entries) {
|
|
86
|
+
if (event.id === null) continue;
|
|
87
|
+
|
|
88
|
+
const current = best.get(event.id);
|
|
89
|
+
|
|
90
|
+
if (!current || EVENT_PRECEDENCE[event.status] < EVENT_PRECEDENCE[current.status]) best.set(event.id, event);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
return entries.filter(({ event }) => event.id === null || best.get(event.id) === event);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* One group per milestone in strategy order, then "no milestone" when it
|
|
98
|
+
* counts an item: the Done log (newest first), the Now item, then Next and
|
|
99
|
+
* Later in roadmap order. An ID that appears more than once (for example done
|
|
100
|
+
* under one milestone and still queued under another) is listed once on the
|
|
101
|
+
* page, in the state and group `features()` counts it in.
|
|
102
|
+
*/
|
|
103
|
+
export function roadmapGroups(planning: Planning): RoadmapGroup[] {
|
|
104
|
+
const groupOf = (milestone: string | null) => milestoneId(milestone, planning.strategy.milestones);
|
|
105
|
+
const focus = planning.strategy.focus.milestone ?? '';
|
|
106
|
+
const summaries = milestoneSummaries(planning);
|
|
107
|
+
const progressFor = (id: string | null) => summaries.find((summary) => summary.id === id)?.progress ?? { done: 0, total: 0 };
|
|
108
|
+
|
|
109
|
+
const placed = dedupeEvents([
|
|
110
|
+
...planning.log.done.map((entry) => ({
|
|
111
|
+
group: groupOf(entry.milestone),
|
|
112
|
+
event: { id: entry.id, title: label(entry.id, entry.title), desc: entry.result ?? '', time: entry.date, status: 'done' as const },
|
|
113
|
+
})),
|
|
114
|
+
...(planning.now.item
|
|
115
|
+
? [
|
|
116
|
+
{
|
|
117
|
+
group: groupOf(planning.now.milestone),
|
|
118
|
+
event: {
|
|
119
|
+
id: planning.now.item.id,
|
|
120
|
+
title: label(planning.now.item.id, planning.now.item.title),
|
|
121
|
+
desc: planning.now.stage ? `In progress: ${planning.now.stage}` : 'In progress',
|
|
122
|
+
time: 'Now',
|
|
123
|
+
status: 'active' as const,
|
|
124
|
+
},
|
|
125
|
+
},
|
|
126
|
+
]
|
|
127
|
+
: []),
|
|
128
|
+
...[...planning.roadmap.next, ...planning.roadmap.later].map((item) => ({
|
|
129
|
+
group: groupOf(item.milestone),
|
|
130
|
+
event: { id: item.id, title: label(item.id, item.title), desc: item.doneWhen, time: item.section === 'next' ? 'Next' : 'Later', status: 'pending' as const },
|
|
131
|
+
})),
|
|
132
|
+
]);
|
|
133
|
+
|
|
134
|
+
const eventsFor = (id: string | null): TimelineEvent[] => placed.filter((entry) => entry.group === id).map((entry) => entry.event);
|
|
135
|
+
|
|
136
|
+
const groups: RoadmapGroup[] = planning.strategy.milestones.map((milestone) => ({
|
|
137
|
+
milestone: {
|
|
138
|
+
id: milestone.id,
|
|
139
|
+
name: milestone.name,
|
|
140
|
+
status: milestone.status,
|
|
141
|
+
target: normaliseTarget(milestone.target),
|
|
142
|
+
exitCriteria: milestone.exitCriteria,
|
|
143
|
+
isFocus: milestoneId(focus, [milestone]) !== null,
|
|
144
|
+
},
|
|
145
|
+
events: eventsFor(milestone.id),
|
|
146
|
+
progress: progressFor(milestone.id),
|
|
147
|
+
}));
|
|
148
|
+
|
|
149
|
+
// The same rule as the `No milestone` card: shown only when it counts an item.
|
|
150
|
+
const unassignedProgress = progressFor(null);
|
|
151
|
+
|
|
152
|
+
return unassignedProgress.total > 0 ? [...groups, { milestone: null, events: eventsFor(null), progress: unassignedProgress }] : groups;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
const LEVELS: Level[] = ['low', 'medium', 'high'];
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* The RAG the PM rules derive from likelihood and impact (low 1, medium 2,
|
|
159
|
+
* high 3; a product of 6 or more is red, 3 or 4 amber, otherwise green).
|
|
160
|
+
* A risk's own `rag` may differ when it carries an override; it colours the
|
|
161
|
+
* risk, and this colours a matrix cell.
|
|
162
|
+
*/
|
|
163
|
+
export function derivedRag(likelihood: Level, impact: Level): Rag {
|
|
164
|
+
const score = (LEVELS.indexOf(likelihood) + 1) * (LEVELS.indexOf(impact) + 1);
|
|
165
|
+
|
|
166
|
+
return score >= 6 ? 'red' : score >= 3 ? 'amber' : 'green';
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
export interface MatrixCell {
|
|
170
|
+
likelihood: Level;
|
|
171
|
+
impact: Level;
|
|
172
|
+
rag: Rag;
|
|
173
|
+
risks: Risk[];
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/** The likelihood × impact grid: rows from high impact down, columns from low likelihood up. */
|
|
177
|
+
export function riskMatrix(risks: Risk[]): MatrixCell[][] {
|
|
178
|
+
return [...LEVELS].reverse().map((impact) =>
|
|
179
|
+
LEVELS.map((likelihood) => ({
|
|
180
|
+
likelihood,
|
|
181
|
+
impact,
|
|
182
|
+
rag: derivedRag(likelihood, impact),
|
|
183
|
+
risks: risks.filter((risk) => risk.likelihood === likelihood && risk.impact === impact),
|
|
184
|
+
})),
|
|
185
|
+
);
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Every repository docs page this site builds, keyed by its file relative to
|
|
190
|
+
* the docs root (`/`-separated). The first source to claim a file wins, as in
|
|
191
|
+
* the repo-docs loader.
|
|
192
|
+
*/
|
|
193
|
+
export function docsPages(docs: { root: string; sources: DocsSource[] } | null = config.docs): Map<string, string> {
|
|
194
|
+
const pages = new Map<string, string>();
|
|
195
|
+
const ids = new Set<string>();
|
|
196
|
+
|
|
197
|
+
for (const source of docs?.sources ?? []) {
|
|
198
|
+
for (const page of pagesOf(source, docs!.root)) {
|
|
199
|
+
const file = relative(docs!.root, page.file).split(sep).join('/');
|
|
200
|
+
|
|
201
|
+
if (pages.has(file) || ids.has(page.id)) continue;
|
|
202
|
+
ids.add(page.id);
|
|
203
|
+
pages.set(file, page.id === 'index' ? '/' : `/${page.id}/`);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
return pages;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
let sitePages: Map<string, string> | undefined;
|
|
211
|
+
|
|
212
|
+
/** The site URL of a repository file named in the plan, or `null` when this site does not build it as a page. */
|
|
213
|
+
export function docsHref(path: string | null, pages: Map<string, string> = (sitePages ??= docsPages())): string | null {
|
|
214
|
+
const file = path?.trim().replace(/^\.\//, '') ?? '';
|
|
215
|
+
|
|
216
|
+
return pages.get(file) ?? null;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
function label(id: string | null, title: string): string {
|
|
220
|
+
return id ? `${id} ${title}` : title;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* The known milestone a value names: its ID (`M2`) or its ID and name
|
|
225
|
+
* (`M2 Billing`). Anything else (`none`, an unknown ID, `null`) is no milestone.
|
|
226
|
+
*/
|
|
227
|
+
export function milestoneId(value: string | null, milestones: Pick<Milestone, 'id'>[]): string | null {
|
|
228
|
+
const text = value?.trim() ?? '';
|
|
229
|
+
|
|
230
|
+
return milestones.find((milestone) => text === milestone.id || text.startsWith(`${milestone.id} `))?.id ?? null;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** A plan's completion as a whole percentage; `0` when there is no plan or it has no steps. */
|
|
234
|
+
export function planProgress(plan: { checked: number; total: number } | null): number {
|
|
235
|
+
return plan && plan.total > 0 ? Math.round((plan.checked / plan.total) * 100) : 0;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** A milestone's target, written as given; `null`, empty, or `none` (any case) is no target. */
|
|
239
|
+
export function normaliseTarget(target: string | null): string | null {
|
|
240
|
+
const text = target?.trim() ?? '';
|
|
241
|
+
|
|
242
|
+
return text === '' || text.toLowerCase() === 'none' ? null : text;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** Inbox severity as a card priority: the inbox has no priority of its own. */
|
|
246
|
+
export function severityToPriority(severity: InboxEntry['severity']): 'low' | 'medium' | 'high' | 'urgent' {
|
|
247
|
+
return severity === 'blocker' ? 'urgent' : severity === 'major' ? 'high' : severity === 'minor' ? 'medium' : 'low';
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
export type FeatureState = 'now' | 'next' | 'later' | 'done' | 'dropped';
|
|
251
|
+
|
|
252
|
+
/** The words each state is shown with, in the order the Features page lists them. */
|
|
253
|
+
export const FEATURE_STATES: Record<FeatureState, string> = {
|
|
254
|
+
now: 'In progress',
|
|
255
|
+
next: 'Next',
|
|
256
|
+
later: 'Later',
|
|
257
|
+
done: 'Done',
|
|
258
|
+
dropped: 'Dropped',
|
|
259
|
+
};
|
|
260
|
+
|
|
261
|
+
/**
|
|
262
|
+
* One roadmap item wherever the export holds it — the Now item, Next, Later,
|
|
263
|
+
* the Done log, or the Dropped log — with the fields that place holds.
|
|
264
|
+
*/
|
|
265
|
+
export interface Feature {
|
|
266
|
+
id: string;
|
|
267
|
+
title: string;
|
|
268
|
+
state: FeatureState;
|
|
269
|
+
/** A known milestone ID (`milestoneId`), or `null`. */
|
|
270
|
+
milestone: string | null;
|
|
271
|
+
owner: string | null;
|
|
272
|
+
size: Size | null;
|
|
273
|
+
serves: string[];
|
|
274
|
+
doneWhen: string[];
|
|
275
|
+
dependsOn: string[];
|
|
276
|
+
label: RoadmapItem['label'] | null;
|
|
277
|
+
status: RoadmapItem['status'] | null;
|
|
278
|
+
position: number | null;
|
|
279
|
+
brief: string | null;
|
|
280
|
+
note: string | null;
|
|
281
|
+
revisits: string | null;
|
|
282
|
+
stage: Stage | null;
|
|
283
|
+
started: string | null;
|
|
284
|
+
/** Done or dropped: the log date. */
|
|
285
|
+
date: string | null;
|
|
286
|
+
result: string | null;
|
|
287
|
+
plan: string | null;
|
|
288
|
+
reason: string | null;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/** Every item with an ID, in this order: Now, Next, Later, Done (newest first), Dropped (newest first). */
|
|
292
|
+
export function features(planning: Planning): Feature[] {
|
|
293
|
+
const known = planning.strategy.milestones;
|
|
294
|
+
const blank = { serves: [], doneWhen: [], dependsOn: [], label: null, status: null, position: null, brief: null, note: null, revisits: null, stage: null, started: null, date: null, result: null, plan: null, reason: null };
|
|
295
|
+
const now = planning.now.item
|
|
296
|
+
? [
|
|
297
|
+
{
|
|
298
|
+
...blank,
|
|
299
|
+
id: planning.now.item.id,
|
|
300
|
+
title: planning.now.item.title,
|
|
301
|
+
state: 'now' as const,
|
|
302
|
+
milestone: milestoneId(planning.now.milestone, known),
|
|
303
|
+
owner: planning.board.columns.now[0]?.owner ?? null,
|
|
304
|
+
size: planning.board.columns.now[0]?.size ?? null,
|
|
305
|
+
doneWhen: planning.now.doneWhen,
|
|
306
|
+
brief: planning.now.brief,
|
|
307
|
+
stage: planning.now.stage,
|
|
308
|
+
started: planning.now.started,
|
|
309
|
+
plan: planning.now.plan,
|
|
310
|
+
},
|
|
311
|
+
]
|
|
312
|
+
: [];
|
|
313
|
+
const queued = [...planning.roadmap.next, ...planning.roadmap.later].map((item) => ({
|
|
314
|
+
...blank,
|
|
315
|
+
id: item.id,
|
|
316
|
+
title: item.title,
|
|
317
|
+
state: item.section,
|
|
318
|
+
milestone: milestoneId(item.milestone, known),
|
|
319
|
+
owner: item.owner,
|
|
320
|
+
size: item.size,
|
|
321
|
+
serves: item.serves,
|
|
322
|
+
doneWhen: item.doneWhen ? [item.doneWhen] : [],
|
|
323
|
+
dependsOn: item.dependsOn,
|
|
324
|
+
label: item.label,
|
|
325
|
+
status: item.status,
|
|
326
|
+
position: item.position,
|
|
327
|
+
brief: item.brief,
|
|
328
|
+
note: item.note,
|
|
329
|
+
revisits: item.revisits,
|
|
330
|
+
}));
|
|
331
|
+
const done = planning.log.done.flatMap((entry) =>
|
|
332
|
+
entry.id
|
|
333
|
+
? [{ ...blank, id: entry.id, title: entry.title, state: 'done' as const, milestone: milestoneId(entry.milestone, known), owner: entry.owner, size: null, date: entry.date, result: entry.result, plan: entry.plan }]
|
|
334
|
+
: [],
|
|
335
|
+
);
|
|
336
|
+
const dropped = planning.log.dropped.flatMap((entry) =>
|
|
337
|
+
entry.id ? [{ ...blank, id: entry.id, title: entry.title, state: 'dropped' as const, milestone: null, owner: null, size: null, date: entry.date, reason: entry.reason }] : [],
|
|
338
|
+
);
|
|
339
|
+
|
|
340
|
+
const seen = new Set<string>();
|
|
341
|
+
|
|
342
|
+
return [...now, ...queued, ...done, ...dropped].filter((feature) => !seen.has(feature.id) && seen.add(feature.id));
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
/** The items whose `Depends on` names `id`. */
|
|
346
|
+
export function dependents(all: Feature[], id: string): Feature[] {
|
|
347
|
+
return all.filter((feature) => feature.dependsOn.includes(id));
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/** The brief a feature links to, by its `Brief` path, else by the brief's own ID. */
|
|
351
|
+
export function briefOf(planning: Planning, feature: Pick<Feature, 'id' | 'brief'>): Brief | null {
|
|
352
|
+
return planning.briefs.find((brief) => brief.path === feature.brief) ?? planning.briefs.find((brief) => brief.id === feature.id) ?? null;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
export interface MilestoneSummary {
|
|
356
|
+
/** `null` for the items with no milestone. */
|
|
357
|
+
id: string | null;
|
|
358
|
+
/** The page slug: the lower-case ID, or `none`. */
|
|
359
|
+
slug: string;
|
|
360
|
+
name: string;
|
|
361
|
+
status: string | null;
|
|
362
|
+
target: string | null;
|
|
363
|
+
exitCriteria: string | null;
|
|
364
|
+
serves: string[];
|
|
365
|
+
isFocus: boolean;
|
|
366
|
+
features: Feature[];
|
|
367
|
+
/** Done items against every item that is not dropped. */
|
|
368
|
+
progress: { done: number; total: number };
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
/** One summary per milestone in strategy order, then `No milestone` when an item has none. */
|
|
372
|
+
export function milestoneSummaries(planning: Planning, all: Feature[] = features(planning)): MilestoneSummary[] {
|
|
373
|
+
const focus = planning.strategy.focus.milestone;
|
|
374
|
+
const summary = (milestone: Milestone | null): MilestoneSummary => {
|
|
375
|
+
const members = all.filter((feature) => feature.milestone === (milestone?.id ?? null));
|
|
376
|
+
const counted = members.filter((feature) => feature.state !== 'dropped');
|
|
377
|
+
|
|
378
|
+
return {
|
|
379
|
+
id: milestone?.id ?? null,
|
|
380
|
+
slug: milestone ? milestone.id.toLowerCase() : 'none',
|
|
381
|
+
name: milestone?.name ?? 'No milestone',
|
|
382
|
+
status: milestone?.status ?? null,
|
|
383
|
+
target: milestone?.target ?? null,
|
|
384
|
+
exitCriteria: milestone?.exitCriteria ?? null,
|
|
385
|
+
serves: milestone?.serves ?? [],
|
|
386
|
+
isFocus: milestone ? milestoneId(focus, [milestone]) !== null : false,
|
|
387
|
+
features: members,
|
|
388
|
+
progress: { done: counted.filter((feature) => feature.state === 'done').length, total: counted.length },
|
|
389
|
+
};
|
|
390
|
+
};
|
|
391
|
+
const groups = planning.strategy.milestones.map(summary);
|
|
392
|
+
const unassigned = summary(null);
|
|
393
|
+
|
|
394
|
+
return unassigned.features.length > 0 ? [...groups, unassigned] : groups;
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
/** An inbox file's source as a card's initials: `agent (…)` → `AG`, anything else (the user) → `YOU`. */
|
|
398
|
+
export function sourceInitials(source: string | null): string {
|
|
399
|
+
return /^agent\b/i.test(source?.trim() ?? '') ? 'AG' : 'YOU';
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/** The anchor of a brief's row on the Briefs page: its file name without `.md`, lower-case. */
|
|
403
|
+
export function briefAnchor(path: string): string {
|
|
404
|
+
return (path.split('/').at(-1) ?? path).replace(/\.md$/i, '').toLowerCase();
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
/** The page of one item on this site. */
|
|
408
|
+
export function featureHref(id: string): string {
|
|
409
|
+
return `/plan/features/${id.toLowerCase()}/`;
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/** The page of one milestone on this site; `null` is the `No milestone` page. */
|
|
413
|
+
export function milestoneHref(id: string | null): string {
|
|
414
|
+
return `/plan/milestones/${id ? id.toLowerCase() : 'none'}/`;
|
|
415
|
+
}
|