@purview-dev/pm-docs-site 0.0.0-stage → 0.1.0-pre.1
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 +167 -2
- package/cli.mjs +120 -0
- package/index.d.ts +49 -0
- package/index.mjs +97 -0
- package/lib/options.mjs +67 -0
- package/lib/repo-docs.mjs +148 -0
- package/lib/schema-version.mjs +29 -0
- package/lib/sidebar.mjs +47 -0
- package/lib/site-options.mjs +38 -0
- package/package.json +62 -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 +18 -0
- package/src/components/RefLink.astro +18 -0
- package/src/components/StateBadge.astro +15 -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/content.config.ts +16 -0
- package/src/env.d.ts +7 -0
- package/src/lib/planning-types.ts +207 -0
- package/src/lib/planning.ts +387 -0
- package/src/lib/references.ts +360 -0
- package/src/loaders/repo-docs.ts +69 -0
- package/src/pages/index.astro +158 -0
- package/src/pages/plan/board.astro +140 -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 +90 -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 +86 -0
- package/src/styles/components.css +374 -0
- package/src/styles/width.css +4 -0
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
// Every reference the site links: what an ID or brief path points at, how prose
|
|
2
|
+
// is split into plain text and links, and (references) which pages link to
|
|
3
|
+
// each target. Links and `Linked from` lists both come from here, so they
|
|
4
|
+
// cannot disagree. All from planning.json.
|
|
5
|
+
|
|
6
|
+
import config from 'virtual:pm-docs-site/config';
|
|
7
|
+
|
|
8
|
+
import type { ViewName } from '../../index';
|
|
9
|
+
import { briefAnchor, briefOf, featureHref, features, loadPlanning, milestoneHref, milestoneSummaries, roadmapGroups, type Feature } from './planning';
|
|
10
|
+
import type { Planning } from './planning-types';
|
|
11
|
+
|
|
12
|
+
export type Views = Record<ViewName, boolean>;
|
|
13
|
+
|
|
14
|
+
export type TargetKind = 'item' | 'milestone' | 'risk' | 'brief';
|
|
15
|
+
|
|
16
|
+
export interface Target {
|
|
17
|
+
kind: TargetKind;
|
|
18
|
+
/** The ID, `none` for the No-milestone page, or the brief's path. */
|
|
19
|
+
key: string;
|
|
20
|
+
/** The page or anchor; `null` when that page is not built. */
|
|
21
|
+
href: string | null;
|
|
22
|
+
label: string;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** The page of one open or closed risk, or a removed risk's row on the Risks page. */
|
|
26
|
+
export function riskHref(risk: { id: string }, removed = false): string {
|
|
27
|
+
return removed ? `/plan/risks/#${risk.id.toLowerCase()}` : `/plan/risks/${risk.id.toLowerCase()}/`;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Every link target in the export, keyed by `Target.key`. */
|
|
31
|
+
export function targets(planning: Planning, views: Views): Map<string, Target> {
|
|
32
|
+
const known = new Map<string, Target>();
|
|
33
|
+
const add = (target: Target) => known.set(target.key, target);
|
|
34
|
+
const all = features(planning);
|
|
35
|
+
|
|
36
|
+
for (const feature of all) {
|
|
37
|
+
add({ kind: 'item', key: feature.id, href: views.features ? featureHref(feature.id) : null, label: `${feature.id} ${feature.title}` });
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
for (const summary of milestoneSummaries(planning, all)) {
|
|
41
|
+
add({
|
|
42
|
+
kind: 'milestone',
|
|
43
|
+
key: summary.id ?? 'none',
|
|
44
|
+
href: views.milestones ? milestoneHref(summary.id) : null,
|
|
45
|
+
label: summary.id ? `${summary.id} ${summary.name}` : summary.name,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
|
|
50
|
+
add({ kind: 'risk', key: risk.id, href: riskHref(risk), label: `${risk.id} ${risk.title}` });
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
for (const risk of planning.risks.removed) {
|
|
54
|
+
add({ kind: 'risk', key: risk.id, href: riskHref(risk, true), label: `${risk.id} ${risk.title}` });
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
for (const brief of planning.briefs) {
|
|
58
|
+
add({ kind: 'brief', key: brief.path, href: views.briefs ? `/plan/briefs/#${briefAnchor(brief.path)}` : null, label: brief.title });
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
return known;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** A run of prose: plain text, or the text of one known reference and its target. */
|
|
65
|
+
export interface Run {
|
|
66
|
+
text: string;
|
|
67
|
+
target?: Target;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const ID = String.raw`\b(?:RK-\d{3,}|R-\d{3,}|M\d+)\b`;
|
|
71
|
+
const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
72
|
+
|
|
73
|
+
/** Split text into plain runs and runs that are a known ID or brief path with a page. */
|
|
74
|
+
export function linkify(text: string, known: Map<string, Target>): Run[] {
|
|
75
|
+
const paths = [...known.values()].filter((target) => target.kind === 'brief').map((target) => escape(target.key));
|
|
76
|
+
const pattern = new RegExp([...paths, ID].join('|'), 'g');
|
|
77
|
+
const runs: Run[] = [];
|
|
78
|
+
const plain = (value: string) => {
|
|
79
|
+
if (!value) return;
|
|
80
|
+
const last = runs.at(-1);
|
|
81
|
+
|
|
82
|
+
if (last && !last.target) last.text += value;
|
|
83
|
+
else runs.push({ text: value });
|
|
84
|
+
};
|
|
85
|
+
let at = 0;
|
|
86
|
+
|
|
87
|
+
for (const match of text.matchAll(pattern)) {
|
|
88
|
+
const target = known.get(match[0]);
|
|
89
|
+
|
|
90
|
+
plain(text.slice(at, match.index));
|
|
91
|
+
if (target?.href) runs.push({ text: match[0], target });
|
|
92
|
+
else plain(match[0]);
|
|
93
|
+
at = match.index + match[0].length;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
plain(text.slice(at));
|
|
97
|
+
|
|
98
|
+
return runs;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export type Relation = 'depends on' | 'revisits' | 'milestone' | 'affects' | 'mitigation' | 'related' | 'brief' | 'mentions' | 'listed';
|
|
102
|
+
|
|
103
|
+
/** The order and heading of each relation in a `Linked from` section. */
|
|
104
|
+
export const RELATION_LABELS: Record<Relation, string> = {
|
|
105
|
+
'depends on': 'Depends on',
|
|
106
|
+
revisits: 'Revisits',
|
|
107
|
+
milestone: 'Milestone',
|
|
108
|
+
affects: 'Affects',
|
|
109
|
+
mitigation: 'Mitigation',
|
|
110
|
+
related: 'Related',
|
|
111
|
+
brief: 'Brief',
|
|
112
|
+
mentions: 'Mentioned on',
|
|
113
|
+
listed: 'Listed on',
|
|
114
|
+
};
|
|
115
|
+
|
|
116
|
+
/** One page that links a target, and how. */
|
|
117
|
+
export interface Backlink {
|
|
118
|
+
href: string;
|
|
119
|
+
label: string;
|
|
120
|
+
relation: Relation;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* For every target, the pages that link to it. Each source page below must
|
|
125
|
+
* render exactly these links (through RefLink and LinkedText); the link test
|
|
126
|
+
* checks that every rendered link appears in its target's list.
|
|
127
|
+
*/
|
|
128
|
+
export function references(planning: Planning, views: Views): Map<string, Backlink[]> {
|
|
129
|
+
const known = targets(planning, views);
|
|
130
|
+
const back = new Map<string, Backlink[]>([...known.keys()].map((key) => [key, []]));
|
|
131
|
+
const all = features(planning);
|
|
132
|
+
const summaries = milestoneSummaries(planning, all);
|
|
133
|
+
const milestoneKey = (id: string | null) => (id ?? (summaries.some((summary) => summary.id === null) ? 'none' : null));
|
|
134
|
+
// What a FeatureTable row shows in its last column.
|
|
135
|
+
const decision = (feature: Feature) => (feature.state === 'done' ? feature.result : feature.state === 'dropped' ? feature.reason : feature.doneWhen.join(' '));
|
|
136
|
+
|
|
137
|
+
const source = (href: string, label: string) => {
|
|
138
|
+
const link = (key: string | null | undefined, relation: Relation) => {
|
|
139
|
+
const target = key ? known.get(key) : undefined;
|
|
140
|
+
const list = key ? back.get(key) : undefined;
|
|
141
|
+
|
|
142
|
+
if (!target?.href || !list || target.href === href) return;
|
|
143
|
+
if (!list.some((entry) => entry.href === href && entry.relation === relation)) list.push({ href, label, relation });
|
|
144
|
+
};
|
|
145
|
+
const prose = (text: string | null | undefined, relation: Relation = 'mentions') => {
|
|
146
|
+
for (const run of linkify(text ?? '', known)) if (run.target) link(run.target.key, relation);
|
|
147
|
+
};
|
|
148
|
+
|
|
149
|
+
return { link, prose };
|
|
150
|
+
};
|
|
151
|
+
|
|
152
|
+
if (views.features) {
|
|
153
|
+
for (const feature of all) {
|
|
154
|
+
const page = source(featureHref(feature.id), `${feature.id} ${feature.title}`);
|
|
155
|
+
|
|
156
|
+
for (const dep of feature.dependsOn) page.link(dep, 'depends on');
|
|
157
|
+
page.link(feature.revisits, 'revisits');
|
|
158
|
+
page.link(milestoneKey(feature.milestone), 'milestone');
|
|
159
|
+
for (const other of all) {
|
|
160
|
+
if (other.dependsOn.includes(feature.id) || other.revisits === feature.id) page.link(other.id, 'related');
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
const brief = briefOf(planning, feature);
|
|
164
|
+
|
|
165
|
+
page.link(brief?.path ?? feature.brief, 'brief');
|
|
166
|
+
for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
|
|
167
|
+
if (risk.affects !== feature.id) continue;
|
|
168
|
+
page.link(risk.id, 'affects');
|
|
169
|
+
page.prose(risk.title);
|
|
170
|
+
}
|
|
171
|
+
for (const text of [...feature.doneWhen, feature.result, feature.reason, feature.note, feature.status?.reason, brief?.status, brief?.problem, brief?.decision]) page.prose(text);
|
|
172
|
+
for (const entry of planning.inbox) if (entry.affects === feature.id || entry.related.includes(feature.id)) page.prose(entry.title);
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
if (views.milestones) {
|
|
177
|
+
for (const summary of summaries) {
|
|
178
|
+
const page = source(milestoneHref(summary.id), summary.id ? `${summary.id} ${summary.name}` : summary.name);
|
|
179
|
+
|
|
180
|
+
for (const feature of summary.features) {
|
|
181
|
+
page.link(feature.id, 'listed');
|
|
182
|
+
page.prose(decision(feature));
|
|
183
|
+
}
|
|
184
|
+
page.prose(summary.exitCriteria);
|
|
185
|
+
if (summary.id) {
|
|
186
|
+
for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
|
|
187
|
+
if (risk.affects !== summary.id) continue;
|
|
188
|
+
page.link(risk.id, 'affects');
|
|
189
|
+
page.prose(risk.title);
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
for (const risk of [...planning.risks.open, ...planning.risks.closed]) {
|
|
196
|
+
const page = source(riskHref(risk), `${risk.id} ${risk.title}`);
|
|
197
|
+
|
|
198
|
+
page.prose(risk.affects, 'affects');
|
|
199
|
+
page.prose(risk.trigger);
|
|
200
|
+
page.prose(risk.mitigation, 'mitigation');
|
|
201
|
+
for (const text of [risk.ragOverride, risk.raised, risk.reviewed, risk.closed]) page.prose(text);
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
const byId = new Map(all.map((feature) => [feature.id, feature]));
|
|
205
|
+
const board = source('/plan/board/', 'Board');
|
|
206
|
+
const { columns } = planning.board;
|
|
207
|
+
|
|
208
|
+
for (const card of [...columns.now, ...columns.next, ...columns.foryou, ...columns.waiting]) {
|
|
209
|
+
board.link(card.id, 'listed');
|
|
210
|
+
board.prose(card.detail);
|
|
211
|
+
if (columns.now.every((now) => now.id !== card.id)) board.link(milestoneKey(byId.get(card.id)?.milestone ?? null), 'listed');
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
for (const entry of columns.done) {
|
|
215
|
+
board.link(entry.id, 'listed');
|
|
216
|
+
board.link(milestoneKey(byId.get(entry.id ?? '')?.milestone ?? null), 'listed');
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
const roadmap = source('/plan/roadmap/', 'Roadmap');
|
|
220
|
+
|
|
221
|
+
for (const group of roadmapGroups(planning)) {
|
|
222
|
+
roadmap.link(group.milestone?.id ?? milestoneKey(null), 'listed');
|
|
223
|
+
roadmap.prose(group.milestone?.exitCriteria);
|
|
224
|
+
for (const event of group.events) {
|
|
225
|
+
roadmap.link(event.id, 'listed');
|
|
226
|
+
roadmap.prose(event.desc);
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
const log = source('/plan/log/', 'Log');
|
|
231
|
+
|
|
232
|
+
for (const entry of planning.board.activity) {
|
|
233
|
+
if (entry.id) log.link(entry.id, 'listed');
|
|
234
|
+
else log.prose(entry.title);
|
|
235
|
+
log.prose(entry.result);
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
const risks = source('/plan/risks/', 'Risks');
|
|
239
|
+
|
|
240
|
+
// Open risks show their detail; closed ones their title and closing reason; removed ones their reason.
|
|
241
|
+
for (const risk of planning.risks.open) {
|
|
242
|
+
risks.link(risk.id, 'listed');
|
|
243
|
+
risks.prose(risk.title);
|
|
244
|
+
risks.prose(risk.affects, 'affects');
|
|
245
|
+
risks.prose(risk.trigger);
|
|
246
|
+
risks.prose(risk.ragOverride);
|
|
247
|
+
risks.prose(risk.mitigation, 'mitigation');
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
for (const risk of planning.risks.closed) {
|
|
251
|
+
risks.link(risk.id, 'listed');
|
|
252
|
+
risks.prose(risk.title);
|
|
253
|
+
risks.prose(risk.closed);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
for (const risk of planning.risks.removed) {
|
|
257
|
+
risks.link(risk.id, 'listed');
|
|
258
|
+
risks.prose(risk.title);
|
|
259
|
+
risks.prose(risk.reason);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
if (views.features) {
|
|
263
|
+
const page = source('/plan/features/', 'Features');
|
|
264
|
+
|
|
265
|
+
for (const feature of all) {
|
|
266
|
+
page.link(feature.id, 'listed');
|
|
267
|
+
page.link(milestoneKey(feature.milestone), 'listed');
|
|
268
|
+
page.prose(decision(feature));
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
if (views.milestones) {
|
|
273
|
+
const page = source('/plan/milestones/', 'Milestones');
|
|
274
|
+
|
|
275
|
+
for (const summary of summaries) {
|
|
276
|
+
page.link(summary.id ?? 'none', 'listed');
|
|
277
|
+
page.prose(summary.exitCriteria);
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
if (views.now && planning.now.item) {
|
|
282
|
+
const page = source('/plan/now/', 'Now');
|
|
283
|
+
const checkpoint = planning.now.checkpoint;
|
|
284
|
+
|
|
285
|
+
page.link(planning.now.item.id, 'listed');
|
|
286
|
+
page.link(planning.now.brief, 'listed');
|
|
287
|
+
for (const text of [...planning.now.doneWhen, checkpoint?.stoppedAt, checkpoint?.nextAction, checkpoint?.startWith, checkpoint?.decisions, checkpoint?.context, checkpoint?.openQuestion]) page.prose(text);
|
|
288
|
+
for (const task of planning.plan?.tasks ?? []) page.prose(task.title);
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
if (views.inbox) {
|
|
292
|
+
const page = source('/plan/inbox/', 'Inbox');
|
|
293
|
+
|
|
294
|
+
for (const entry of planning.inbox) {
|
|
295
|
+
page.prose(entry.title);
|
|
296
|
+
page.prose(entry.affects, 'affects');
|
|
297
|
+
for (const id of entry.related) page.link(id, 'related');
|
|
298
|
+
page.link(entry.brief, 'brief');
|
|
299
|
+
page.prose(entry.idea);
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
if (views.briefs) {
|
|
304
|
+
const page = source('/plan/briefs/', 'Briefs');
|
|
305
|
+
|
|
306
|
+
for (const brief of planning.briefs) {
|
|
307
|
+
page.link(brief.id, 'listed');
|
|
308
|
+
for (const text of [brief.status, brief.origin, brief.problem, brief.decision, brief.doneWhen, ...brief.revisions.map((revision) => revision.text)]) page.prose(text);
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
if (views.strategy) {
|
|
313
|
+
const page = source('/plan/strategy/', 'Strategy');
|
|
314
|
+
const { strategy, vision } = planning;
|
|
315
|
+
|
|
316
|
+
page.prose(strategy.focus.milestone, 'listed');
|
|
317
|
+
for (const text of [
|
|
318
|
+
vision.problem,
|
|
319
|
+
vision.customer,
|
|
320
|
+
...vision.outcomes.map((outcome) => outcome.text),
|
|
321
|
+
...vision.outOfScope,
|
|
322
|
+
vision.constraints.timeAvailable,
|
|
323
|
+
vision.constraints.budget,
|
|
324
|
+
vision.constraints.stack,
|
|
325
|
+
strategy.focus.whyNow,
|
|
326
|
+
...strategy.bets.flatMap((bet) => [bet.statement, bet.evidence, bet.signal, bet.status]),
|
|
327
|
+
...strategy.assumptions.flatMap((assumption) => [assumption.statement, assumption.test, assumption.status]),
|
|
328
|
+
...strategy.notDoing.flatMap((entry) => [entry.thing, entry.why, entry.revisit]),
|
|
329
|
+
...strategy.decisions.flatMap((decision) => [decision.date, decision.decision, decision.why, decision.rejected]),
|
|
330
|
+
])
|
|
331
|
+
page.prose(text);
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
const home = source('/', 'Home');
|
|
335
|
+
|
|
336
|
+
home.prose(planning.strategy.focus.milestone, 'listed');
|
|
337
|
+
home.prose(planning.strategy.focus.whyNow);
|
|
338
|
+
if (!views.now && planning.now.item) home.link(planning.now.item.id, 'listed');
|
|
339
|
+
for (const id of planning.checks.claimable) home.link(id, 'listed');
|
|
340
|
+
for (const risk of planning.risks.open.filter((candidate) => candidate.rag === 'red')) {
|
|
341
|
+
home.link(risk.id, 'listed');
|
|
342
|
+
home.prose(risk.title);
|
|
343
|
+
home.prose(risk.mitigation, 'mitigation');
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
return back;
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
let cache: { known: Map<string, Target>; back: Map<string, Backlink[]> } | null = null;
|
|
350
|
+
|
|
351
|
+
/** The site's targets and backlinks, computed once per build from the integration's options. */
|
|
352
|
+
export function siteRefs(): { known: Map<string, Target>; back: Map<string, Backlink[]> } {
|
|
353
|
+
if (!cache) {
|
|
354
|
+
const planning = loadPlanning();
|
|
355
|
+
|
|
356
|
+
cache = { known: targets(planning, config.views), back: references(planning, config.views) };
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
return cache;
|
|
360
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
// Markdown from anywhere in the repository as Starlight's `docs` collection,
|
|
2
|
+
// read in place. The matching and parsing live in lib/repo-docs.mjs, shared with
|
|
3
|
+
// the sidebar.
|
|
4
|
+
|
|
5
|
+
import { readFile } from 'node:fs/promises';
|
|
6
|
+
import { relative, resolve, sep } from 'node:path';
|
|
7
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
8
|
+
|
|
9
|
+
import type { Loader } from 'astro/loaders';
|
|
10
|
+
|
|
11
|
+
import type { DocsSource } from '../../index';
|
|
12
|
+
import { pagesOf, readPage } from '../../lib/repo-docs.mjs';
|
|
13
|
+
|
|
14
|
+
/** Starlight's `docs` collection over every source; `root` is the docs root, absolute or relative to the site root. */
|
|
15
|
+
export function repoDocsLoader(options: { root: string; sources: DocsSource[] }): Loader {
|
|
16
|
+
return {
|
|
17
|
+
name: 'repo-docs',
|
|
18
|
+
async load({ config, store, parseData, renderMarkdown, generateDigest, watcher, logger }) {
|
|
19
|
+
const siteRoot = fileURLToPath(config.root);
|
|
20
|
+
const repoRoot = resolve(siteRoot, options.root);
|
|
21
|
+
const pages = new Map<string, string>();
|
|
22
|
+
|
|
23
|
+
// The first source to claim a file wins, so a hidden catch-all can follow the listed sources.
|
|
24
|
+
for (const source of options.sources) {
|
|
25
|
+
for (const page of pagesOf(source, repoRoot)) {
|
|
26
|
+
if (![...pages.values()].includes(page.file) && !pages.has(page.id)) pages.set(page.id, page.file);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
async function sync(id: string, file: string): Promise<void> {
|
|
31
|
+
const content = (await readFile(file, 'utf8')).replace(/\r\n/g, '\n');
|
|
32
|
+
const { title, description, body } = readPage(content, file);
|
|
33
|
+
const data = await parseData({ id, data: { title, ...(description ? { description } : {}) } });
|
|
34
|
+
|
|
35
|
+
store.set({
|
|
36
|
+
id,
|
|
37
|
+
data,
|
|
38
|
+
body,
|
|
39
|
+
filePath: relative(siteRoot, file).split(sep).join('/'),
|
|
40
|
+
digest: generateDigest(content),
|
|
41
|
+
// The file URL lets Markdown plugins name the page in what they report.
|
|
42
|
+
rendered: await renderMarkdown(body, { fileURL: pathToFileURL(file) }),
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
store.clear();
|
|
47
|
+
await Promise.all([...pages].map(([id, file]) => sync(id, file)));
|
|
48
|
+
logger.info(`loaded ${pages.size} pages from ${options.sources.length} sources`);
|
|
49
|
+
|
|
50
|
+
if (!watcher) return;
|
|
51
|
+
|
|
52
|
+
// The loaded files only: watching a source folder that is the repository root
|
|
53
|
+
// would watch node_modules too. A new file shows up on the next start.
|
|
54
|
+
const byFile = new Map([...pages].map(([id, file]) => [resolve(file), id]));
|
|
55
|
+
|
|
56
|
+
watcher.add([...byFile.keys()]);
|
|
57
|
+
watcher.on('change', (path) => {
|
|
58
|
+
const id = byFile.get(resolve(path));
|
|
59
|
+
|
|
60
|
+
if (id) void sync(id, path);
|
|
61
|
+
});
|
|
62
|
+
watcher.on('unlink', (path) => {
|
|
63
|
+
const id = byFile.get(resolve(path));
|
|
64
|
+
|
|
65
|
+
if (id) store.delete(id);
|
|
66
|
+
});
|
|
67
|
+
},
|
|
68
|
+
};
|
|
69
|
+
}
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
---
|
|
2
|
+
// The site's front page: where the project is, from planning.json, and the
|
|
3
|
+
// way into the plan and the repository docs (the integration's options).
|
|
4
|
+
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
|
|
5
|
+
|
|
6
|
+
import ExportStamp from '../components/ExportStamp.astro';
|
|
7
|
+
import LinkedText from '../components/LinkedText.astro';
|
|
8
|
+
import RefLink from '../components/RefLink.astro';
|
|
9
|
+
import { loadPlanning, milestoneId } from '../lib/planning';
|
|
10
|
+
import config from 'virtual:pm-docs-site/config';
|
|
11
|
+
import '../styles/components.css';
|
|
12
|
+
|
|
13
|
+
const planning = loadPlanning();
|
|
14
|
+
const { counts, checks } = planning;
|
|
15
|
+
const focusId = milestoneId(planning.strategy.focus.milestone, planning.strategy.milestones);
|
|
16
|
+
|
|
17
|
+
const figures = [
|
|
18
|
+
{ label: 'In Next', value: `${counts.next} of ${counts.nextMax}` },
|
|
19
|
+
{ label: 'In Later', value: counts.later },
|
|
20
|
+
{ label: 'Done', value: counts.done },
|
|
21
|
+
{ label: 'Open ideas', value: counts.openInbox },
|
|
22
|
+
{ label: 'Blocked', value: counts.blockers },
|
|
23
|
+
{ label: 'Red risks', value: `${counts.redRisks} of ${counts.openRisks}` },
|
|
24
|
+
];
|
|
25
|
+
|
|
26
|
+
const redRisks = planning.risks.open.filter((risk) => risk.rag === 'red');
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
<StarlightPage
|
|
30
|
+
frontmatter={{
|
|
31
|
+
title: config.title,
|
|
32
|
+
...(config.description ? { description: config.description } : {}),
|
|
33
|
+
template: 'splash',
|
|
34
|
+
}}
|
|
35
|
+
>
|
|
36
|
+
<ExportStamp />
|
|
37
|
+
|
|
38
|
+
<section>
|
|
39
|
+
<h2>Focus</h2>
|
|
40
|
+
<p>
|
|
41
|
+
<strong>
|
|
42
|
+
{focusId ? <RefLink ref={focusId} /> : planning.strategy.focus.milestone ? <LinkedText text={planning.strategy.focus.milestone} /> : 'No focus set'}
|
|
43
|
+
</strong>
|
|
44
|
+
</p>
|
|
45
|
+
{planning.strategy.focus.whyNow && (
|
|
46
|
+
<p>
|
|
47
|
+
<LinkedText text={planning.strategy.focus.whyNow} />
|
|
48
|
+
</p>
|
|
49
|
+
)}
|
|
50
|
+
<p>
|
|
51
|
+
{
|
|
52
|
+
planning.now.item ? (
|
|
53
|
+
<>
|
|
54
|
+
Now:{' '}
|
|
55
|
+
<strong>
|
|
56
|
+
{config.views.now ? (
|
|
57
|
+
<a href="/plan/now/">
|
|
58
|
+
{planning.now.item.id} {planning.now.item.title}
|
|
59
|
+
</a>
|
|
60
|
+
) : (
|
|
61
|
+
<RefLink ref={planning.now.item.id} />
|
|
62
|
+
)}
|
|
63
|
+
</strong>{' '}
|
|
64
|
+
({planning.now.stage})
|
|
65
|
+
</>
|
|
66
|
+
) : (
|
|
67
|
+
'Nothing is in progress.'
|
|
68
|
+
)
|
|
69
|
+
}
|
|
70
|
+
</p>
|
|
71
|
+
</section>
|
|
72
|
+
|
|
73
|
+
<section>
|
|
74
|
+
<h2>Figures</h2>
|
|
75
|
+
<dl class="home-figures">
|
|
76
|
+
{
|
|
77
|
+
figures.map((figure) => (
|
|
78
|
+
<div>
|
|
79
|
+
<dt>{figure.label}</dt>
|
|
80
|
+
<dd>{figure.value}</dd>
|
|
81
|
+
</div>
|
|
82
|
+
))
|
|
83
|
+
}
|
|
84
|
+
</dl>
|
|
85
|
+
</section>
|
|
86
|
+
|
|
87
|
+
<section>
|
|
88
|
+
<h2>Ready to start</h2>
|
|
89
|
+
{checks.claimable.length === 0 && <p class="plan-empty">Nothing in Next can be started.</p>}
|
|
90
|
+
<ul>
|
|
91
|
+
{
|
|
92
|
+
checks.claimable.map((id) => (
|
|
93
|
+
<li>
|
|
94
|
+
<RefLink ref={id} />
|
|
95
|
+
</li>
|
|
96
|
+
))
|
|
97
|
+
}
|
|
98
|
+
</ul>
|
|
99
|
+
</section>
|
|
100
|
+
|
|
101
|
+
<section>
|
|
102
|
+
<h2>Red risks</h2>
|
|
103
|
+
{redRisks.length === 0 && <p class="plan-empty">No open risk is red.</p>}
|
|
104
|
+
<ul>
|
|
105
|
+
{
|
|
106
|
+
redRisks.map((risk) => (
|
|
107
|
+
<li>
|
|
108
|
+
<span class="rag rag--red">red</span> <strong><RefLink ref={risk.id} label="id" /></strong>{' '}
|
|
109
|
+
<LinkedText text={risk.title} /> — mitigation: {risk.mitigation ? <LinkedText text={risk.mitigation} /> : 'none'}
|
|
110
|
+
</li>
|
|
111
|
+
))
|
|
112
|
+
}
|
|
113
|
+
</ul>
|
|
114
|
+
</section>
|
|
115
|
+
|
|
116
|
+
<section>
|
|
117
|
+
<h2>Read on</h2>
|
|
118
|
+
<ul>
|
|
119
|
+
{config.views.now && <li><a href="/plan/now/">Now</a> — the active item, its checkpoint and its plan</li>}
|
|
120
|
+
<li><a href="/plan/board/">Board</a> — Now, Next, For you, Waiting and Done</li>
|
|
121
|
+
<li><a href="/plan/roadmap/">Roadmap</a> — milestones in order</li>
|
|
122
|
+
{config.views.milestones && <li><a href="/plan/milestones/">Milestones</a> — each milestone, its exit criteria and its items</li>}
|
|
123
|
+
{config.views.features && <li><a href="/plan/features/">Features</a> — every item, with a page each</li>}
|
|
124
|
+
<li><a href="/plan/log/">Log</a> — done, dropped and reviews</li>
|
|
125
|
+
<li><a href="/plan/risks/">Risks</a> — the risk register by RAG status</li>
|
|
126
|
+
{config.views.inbox && <li><a href="/plan/inbox/">Inbox</a> — parked ideas, bugs and questions</li>}
|
|
127
|
+
{config.views.briefs && <li><a href="/plan/briefs/">Briefs</a> — shaped ideas and their decisions</li>}
|
|
128
|
+
{config.views.strategy && <li><a href="/plan/strategy/">Strategy</a> — the vision, bets, assumptions and decisions</li>}
|
|
129
|
+
<li>Search — every page above is in the site search once it is built (<code>just docs-preview</code>)</li>
|
|
130
|
+
{config.docs !== null && <li>Documentation — the repository's Markdown, grouped in the sidebar</li>}
|
|
131
|
+
</ul>
|
|
132
|
+
</section>
|
|
133
|
+
</StarlightPage>
|
|
134
|
+
|
|
135
|
+
<style>
|
|
136
|
+
.home-figures {
|
|
137
|
+
display: grid;
|
|
138
|
+
grid-template-columns: repeat(auto-fit, minmax(9rem, 1fr));
|
|
139
|
+
gap: 0.75rem;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
.home-figures > div {
|
|
143
|
+
padding: 0.75rem 1rem;
|
|
144
|
+
border: 1px solid var(--sl-color-hairline);
|
|
145
|
+
border-radius: 10px;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
.home-figures dt {
|
|
149
|
+
color: var(--sl-color-gray-3);
|
|
150
|
+
font-size: var(--sl-text-sm);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
.home-figures dd {
|
|
154
|
+
margin: 0;
|
|
155
|
+
font-size: var(--sl-text-2xl);
|
|
156
|
+
font-weight: 700;
|
|
157
|
+
}
|
|
158
|
+
</style>
|