@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.
- package/README.md +70 -10
- package/dist/cli.js +4 -3
- package/dist/dev-env.d.ts +2 -0
- package/dist/dev-env.js +13 -0
- package/dist/fs-allow.d.ts +2 -0
- package/dist/fs-allow.js +11 -0
- package/dist/index.js +38 -4
- package/dist/options.js +1 -1
- package/dist/schema-version.d.ts +17 -0
- package/dist/schema-version.js +30 -1
- package/dist/sidebar.js +2 -0
- package/dist/site-options.js +5 -0
- package/dist/types.d.ts +2 -2
- package/lib/schema-version.ts +36 -1
- package/lib/types.ts +48 -0
- package/package.json +7 -3
- package/src/components/FeatureSummary.astro +30 -9
- package/src/components/FeatureTable.astro +1 -1
- package/src/components/ItemDetail.astro +1 -1
- package/src/components/ItemDialog.astro +12 -8
- package/src/components/RefLink.astro +7 -4
- package/src/components/board/Board.tsx +16 -8
- package/src/components/board/KanbanItemCard.tsx +4 -2
- package/src/components/board/TaskKanbanCard.tsx +4 -2
- package/src/components/decisions/Decisions.tsx +162 -0
- package/src/components/decisions/useDecisionsUrlState.ts +29 -0
- package/src/components/graph/Graph.tsx +290 -0
- package/src/components/graph/GraphNodes.tsx +120 -0
- package/src/components/graph/useGraphUrlState.ts +58 -0
- package/src/components/lib/KanbanItemCard.astro +7 -11
- package/src/components/lib/StatusTimelineFeed.astro +3 -2
- package/src/components/lib/TaskKanbanCard.astro +2 -1
- package/src/components/timeline/Timeline.tsx +39 -6
- package/src/components/timeline/useTimelineLayout.ts +2 -2
- package/src/content.config.ts +22 -6
- package/src/lib/decisions.ts +100 -0
- package/src/lib/graph-layout.ts +270 -0
- package/src/lib/graph-state.ts +99 -0
- package/src/lib/graph.ts +194 -0
- package/src/lib/link-html.ts +39 -0
- package/src/lib/planning-types.ts +32 -3
- package/src/lib/planning.ts +30 -16
- package/src/lib/ref-boundary.ts +19 -0
- package/src/lib/references.ts +66 -7
- package/src/lib/timeline-state.ts +119 -0
- package/src/lib/timeline.ts +22 -127
- package/src/loaders/adrs.ts +43 -0
- package/src/pages/404.astro +18 -0
- package/src/pages/index.astro +1 -1
- package/src/pages/plan/log.astro +18 -1
- package/src/pages/plan/roadmap.astro +1 -1
- package/src/routes/plan/decisions/[id].astro +93 -0
- package/src/routes/plan/decisions.astro +52 -0
- package/src/routes/plan/graph.astro +80 -0
- package/src/routes/plan/milestones/index.astro +2 -2
- package/src/routes/plan/now.astro +2 -3
- package/src/scripts/plan.ts +33 -1
- package/src/styles/components.css +117 -3
- package/src/styles/graph.css +296 -0
- package/src/styles/timeline.css +1 -1
package/README.md
CHANGED
|
@@ -18,6 +18,10 @@ migrates the `pm-docs-site` skill to it, the skill and this repository's
|
|
|
18
18
|
Three files: `package.json`, a lockfile, and `astro.config.ts`. No `src/`
|
|
19
19
|
folder: the integration points Astro's `srcDir` at the package.
|
|
20
20
|
|
|
21
|
+
On Windows, keep the site and the installed package on the same drive: Astro
|
|
22
|
+
cannot build a site whose root is on another drive than the package's `src/`,
|
|
23
|
+
so a package linked from another drive fails the build.
|
|
24
|
+
|
|
21
25
|
```json
|
|
22
26
|
{
|
|
23
27
|
"name": "my-project-site",
|
|
@@ -28,11 +32,11 @@ folder: the integration points Astro's `srcDir` at the package.
|
|
|
28
32
|
"build": "pm-docs-site build",
|
|
29
33
|
"check": "pm-docs-site check"
|
|
30
34
|
},
|
|
31
|
-
"dependencies": { "@purview-dev/pm-docs-site": "0.1.0-pre.
|
|
35
|
+
"dependencies": { "@purview-dev/pm-docs-site": "0.1.0-pre.3" }
|
|
32
36
|
}
|
|
33
37
|
```
|
|
34
38
|
|
|
35
|
-
```
|
|
39
|
+
```ts
|
|
36
40
|
// astro.config.ts
|
|
37
41
|
import pmDocsSite from '@purview-dev/pm-docs-site';
|
|
38
42
|
|
|
@@ -58,7 +62,7 @@ export default {
|
|
|
58
62
|
| `description` | string | none |
|
|
59
63
|
| `planning` | path from the site root | `../planning/planning.json` |
|
|
60
64
|
| `docs` | `{ root, sources }`; `root` from the site root, each source a folder and globs | none: no repository pages |
|
|
61
|
-
| `views` | any of `now`, `milestones`, `features`, `inbox`, `briefs`, `strategy` | all
|
|
65
|
+
| `views` | any of `now`, `milestones`, `graph`, `features`, `inbox`, `briefs`, `strategy`, `decisions` | all eight |
|
|
62
66
|
|
|
63
67
|
Home, Board, Roadmap, Log and Risks are always rendered. A docs source has
|
|
64
68
|
`label`, `base`, `include`, and optionally `prefix`, `indexFile`, `order`,
|
|
@@ -89,7 +93,8 @@ board can be linked and survives a reload:
|
|
|
89
93
|
`/plan/board/?owner=user&milestone=M2&group=milestone`. Unknown or junk
|
|
90
94
|
values fall back to All / None. Column collapse still works per column,
|
|
91
95
|
across every lane, and without JavaScript the full, ungrouped board renders
|
|
92
|
-
with the filter bar hidden
|
|
96
|
+
with the filter bar hidden; the column collapse toggles appear only once
|
|
97
|
+
the island loads.
|
|
93
98
|
|
|
94
99
|
The integration adds `@astrojs/react` itself, so a consumer site stays the
|
|
95
100
|
three files above.
|
|
@@ -114,13 +119,68 @@ Zoom runs from 50% to 200% in steps of 25%: the `Zoom out`, `Zoom in`, and
|
|
|
114
119
|
pinch. Zoom resizes the cards rather than scaling the page, and it is not
|
|
115
120
|
kept in the URL: every visit starts at 100%.
|
|
116
121
|
|
|
122
|
+
## Graph
|
|
123
|
+
|
|
124
|
+
The Graph page (the `graph` view) is a React island that shows how open
|
|
125
|
+
items depend on each other: one node per open item, with its ID (a link to
|
|
126
|
+
its feature page), title, milestone, size, section, and owner, and one edge
|
|
127
|
+
per `Depends on` and `Revisits` link, drawn from the prerequisite to the item
|
|
128
|
+
that waits for it and left to right in the order the work has to happen.
|
|
129
|
+
`Revisits` edges are dashed and labelled `revisits`. A done or dropped item
|
|
130
|
+
an open item points at is a small chip (`✓ R-008`, or `✗ R-003` struck
|
|
131
|
+
through), and an ID that matches no item is a warning chip
|
|
132
|
+
(`? R-099 not found`). The active item is highlighted as on the Board; an
|
|
133
|
+
explicitly blocked item has a dashed border. Every position is computed at
|
|
134
|
+
build time, so no layout code reaches the browser.
|
|
135
|
+
|
|
136
|
+
Two switches change the view, and each is kept in the URL alongside any
|
|
137
|
+
other parameters:
|
|
138
|
+
|
|
139
|
+
| Switch | Off | URL key |
|
|
140
|
+
| --- | --- | --- |
|
|
141
|
+
| `Milestone lanes` | one flow, with unlinked items in a `No links` tray below | `lanes=off` |
|
|
142
|
+
| `Show done prerequisites` | no done or dropped chips; each node shows `✓ <n> done` instead | `done=off` |
|
|
143
|
+
|
|
144
|
+
With lanes on, each milestone with open items is a band, in strategy order,
|
|
145
|
+
labelled with its ID and name and `Focus` for the focus milestone, then
|
|
146
|
+
`No milestone`. Click a node or chip, or press Enter on it, to trace its
|
|
147
|
+
chain: everything it waits on and everything that waits on it, transitively,
|
|
148
|
+
stays bright and the rest fades. The selection is kept as `focus=<ID>`, so
|
|
149
|
+
a link opens with the same chain highlighted. Click the selected node again,
|
|
150
|
+
or its ID link, to open its feature page; Escape or a click on the
|
|
151
|
+
background clears the selection. Drag to pan, and zoom with the wheel or a
|
|
152
|
+
pinch over the graph, or the `Zoom out`, `Zoom in`, and `Fit` buttons.
|
|
153
|
+
|
|
154
|
+
Below the graph, a `Dependencies` list gives each open item's links as plain
|
|
155
|
+
text, for search, screen readers, and browsers without JavaScript.
|
|
156
|
+
|
|
157
|
+
The page adds `@xyflow/react` and `@dagrejs/dagre` as dependencies; dagre
|
|
158
|
+
runs at build time only; it never reaches the browser. The island's
|
|
159
|
+
JavaScript and `graph.css` load only on `/plan/graph/`, never on another page.
|
|
160
|
+
|
|
161
|
+
## Decisions
|
|
162
|
+
|
|
163
|
+
The Decisions page lists the architecture decision records in the export's
|
|
164
|
+
`adrs` (written by `pm-export` from `<PM root>/decisions/`) as a React
|
|
165
|
+
island: a search box over each ADR's ID, title, category, and text, status
|
|
166
|
+
chips (superseded is off by default), category chips, and `Group by`
|
|
167
|
+
category, status, or none. The state is kept in the URL, so a filtered
|
|
168
|
+
view can be shared; `Clear` returns to the default. Every ADR has its own
|
|
169
|
+
page with its header fields and its Context, Decision, Alternatives, and
|
|
170
|
+
Consequences rendered from Markdown, and search indexes it. A feature page
|
|
171
|
+
lists the ADRs whose `Item` is that item.
|
|
172
|
+
|
|
117
173
|
## CLI
|
|
118
174
|
|
|
119
175
|
The CLI runs under Node 24 or later.
|
|
120
176
|
|
|
121
177
|
- `pm-docs-site build [site-dir]` and `pm-docs-site dev [site-dir]` run Astro
|
|
122
178
|
on the site. A site with no `astro.config.*` builds from
|
|
123
|
-
`--title <title>` and `--planning <path>`.
|
|
179
|
+
`--title <title>` and `--planning <path>`. A site with an `astro.config.*`
|
|
180
|
+
takes its options from that file: the flags are ignored, with a warning.
|
|
181
|
+
`dev` turns off Astro's update check (`ASTRO_DISABLE_UPDATE_CHECK=true`):
|
|
182
|
+
this package pins Astro, and the check's settings write can restart the
|
|
183
|
+
dev server while it starts. Set the variable yourself to keep the check.
|
|
124
184
|
- `pm-docs-site check [site-dir]` builds nothing. It reads the export, checks
|
|
125
185
|
its `schemaVersion`, and checks every docs source folder exists, then exits
|
|
126
186
|
0, or 1 with one line per problem.
|
|
@@ -128,7 +188,7 @@ The CLI runs under Node 24 or later.
|
|
|
128
188
|
## Supported exports
|
|
129
189
|
|
|
130
190
|
`SUPPORTED_SCHEMA_VERSIONS` in `lib/schema-version.ts`: pm-export
|
|
131
|
-
`schemaVersion`
|
|
191
|
+
`schemaVersion` 5. Any other version fails the build and `check`, and the
|
|
132
192
|
message says to run the `pm-export` skill.
|
|
133
193
|
|
|
134
194
|
## Development
|
|
@@ -176,9 +236,9 @@ the purview-dev release rules:
|
|
|
176
236
|
While `package.json` sets `"private": true` it also skips, green. Then it
|
|
177
237
|
installs, tests, type-checks, builds `dist/`, and runs `scripts/check-exports.ts`.
|
|
178
238
|
The `prepack` script runs the same build and check, so every pack and a local
|
|
179
|
-
`npm publish` build first and cannot burn a version on a package
|
|
180
|
-
or
|
|
181
|
-
(
|
|
239
|
+
`npm publish` build first and cannot burn a version on a package whose entry points
|
|
240
|
+
are missing or the wrong kind of file. It publishes a prerelease
|
|
241
|
+
version (one with a `-pre` part) under the `prerelease` dist-tag and a stable version under
|
|
182
242
|
`latest`, skips a version already on the registry, and keeps `latest` on the
|
|
183
243
|
newest prerelease until a stable release exists. Only then does it create the
|
|
184
244
|
tag and a GitHub release, never marked as the repository's latest release.
|
|
@@ -199,7 +259,7 @@ environment.
|
|
|
199
259
|
A trusted publisher is configured on the package, so the package must exist
|
|
200
260
|
on npm first. Once, from an account that can publish to `@purview-dev`:
|
|
201
261
|
|
|
202
|
-
1. Remove `"private": true`, set
|
|
262
|
+
1. Remove `"private": true`, set a prerelease version, and
|
|
203
263
|
publish it locally: `npm publish --access public --tag prerelease`.
|
|
204
264
|
2. Add the trusted publisher, with *Allow npm publish* and *Allow npm
|
|
205
265
|
dist-tag* ticked (the CLI grants only the first):
|
package/dist/cli.js
CHANGED
|
@@ -6,8 +6,9 @@
|
|
|
6
6
|
// builds nothing: it reads the export and the docs sources and reports problems.
|
|
7
7
|
import { existsSync, readFileSync } from 'node:fs';
|
|
8
8
|
import { resolve } from 'node:path';
|
|
9
|
+
import { disableUpdateCheck } from "./dev-env.js";
|
|
9
10
|
import { resolveOptions } from "./options.js";
|
|
10
|
-
import {
|
|
11
|
+
import { parseExport } from "./schema-version.js";
|
|
11
12
|
import { loadSiteOptions } from "./site-options.js";
|
|
12
13
|
const USAGE = 'usage: pm-docs-site <dev | build | check> [site-dir] [--title <title>] [--planning <path>]';
|
|
13
14
|
function parse(argv) {
|
|
@@ -35,8 +36,7 @@ function problems(options) {
|
|
|
35
36
|
}
|
|
36
37
|
else {
|
|
37
38
|
try {
|
|
38
|
-
|
|
39
|
-
checkSchemaVersion(planning.schemaVersion, options.planning);
|
|
39
|
+
parseExport(readFileSync(options.planning, 'utf8'), options.planning);
|
|
40
40
|
}
|
|
41
41
|
catch (error) {
|
|
42
42
|
found.push(error.message);
|
|
@@ -77,6 +77,7 @@ async function main() {
|
|
|
77
77
|
await astro.build(inline);
|
|
78
78
|
return 0;
|
|
79
79
|
}
|
|
80
|
+
disableUpdateCheck(process.env);
|
|
80
81
|
await astro.dev(inline);
|
|
81
82
|
// The dev server keeps the process alive until it is stopped.
|
|
82
83
|
return null;
|
package/dist/dev-env.js
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// The environment `pm-docs-site dev` runs Astro in.
|
|
2
|
+
//
|
|
3
|
+
// Astro's dev server checks npm for a newer Astro on start (not on CI) and
|
|
4
|
+
// records the check in `.astro/settings.json`. It ignores one watcher event for
|
|
5
|
+
// that write, but on Windows a new file gives two (create, then change), so the
|
|
6
|
+
// second restarts the server; a restart while it starts cuts the content sync,
|
|
7
|
+
// and every page then answers 500 until it is restarted by hand (R-029). The
|
|
8
|
+
// package pins Astro, so the notice is not the consumer's to act on: turn the
|
|
9
|
+
// check off unless the consumer has set ASTRO_DISABLE_UPDATE_CHECK.
|
|
10
|
+
/** Sets ASTRO_DISABLE_UPDATE_CHECK to `true` in `env` when it is unset. */
|
|
11
|
+
export function disableUpdateCheck(env) {
|
|
12
|
+
env.ASTRO_DISABLE_UPDATE_CHECK ??= 'true';
|
|
13
|
+
}
|
package/dist/fs-allow.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// Whether a Vite `server.fs.allow` entry already covers a path: the in-repo
|
|
2
|
+
// fixture and linked consumers resolve this package outside the site's
|
|
3
|
+
// workspace root, so the integration allows the package folder only when no
|
|
4
|
+
// entry contains it.
|
|
5
|
+
import { isAbsolute, relative, sep } from 'node:path';
|
|
6
|
+
/** Whether `path` is `entry` or inside it. Separators, drives and case follow `node:path`. */
|
|
7
|
+
export function containsPath(entry, path) {
|
|
8
|
+
const rel = relative(entry, path);
|
|
9
|
+
const escapes = rel === '..' || rel.startsWith(`..${sep}`);
|
|
10
|
+
return !escapes && !isAbsolute(rel);
|
|
11
|
+
}
|
package/dist/index.js
CHANGED
|
@@ -4,11 +4,12 @@
|
|
|
4
4
|
// Starlight with the plan sidebar, adds React so pages can render `.tsx` islands with
|
|
5
5
|
// no consumer config, and serves the resolved options to the pages as
|
|
6
6
|
// `virtual:pm-docs-site/config`.
|
|
7
|
-
import { existsSync } from 'node:fs';
|
|
7
|
+
import { existsSync, realpathSync } from 'node:fs';
|
|
8
8
|
import { dirname, join, resolve } from 'node:path';
|
|
9
9
|
import { fileURLToPath } from 'node:url';
|
|
10
10
|
import react from '@astrojs/react';
|
|
11
11
|
import starlight from '@astrojs/starlight';
|
|
12
|
+
import { containsPath } from "./fs-allow.js";
|
|
12
13
|
import { resolveOptions } from "./options.js";
|
|
13
14
|
import { buildSidebar } from "./sidebar.js";
|
|
14
15
|
/**
|
|
@@ -21,6 +22,7 @@ const VIEW_ROUTES = {
|
|
|
21
22
|
['/plan/milestones', 'plan/milestones/index.astro'],
|
|
22
23
|
['/plan/milestones/[milestone]', 'plan/milestones/[milestone].astro'],
|
|
23
24
|
],
|
|
25
|
+
graph: [['/plan/graph', 'plan/graph.astro']],
|
|
24
26
|
features: [
|
|
25
27
|
['/plan/features', 'plan/features/index.astro'],
|
|
26
28
|
['/plan/features/[id]', 'plan/features/[id].astro'],
|
|
@@ -28,8 +30,18 @@ const VIEW_ROUTES = {
|
|
|
28
30
|
inbox: [['/plan/inbox', 'plan/inbox.astro']],
|
|
29
31
|
briefs: [['/plan/briefs', 'plan/briefs.astro']],
|
|
30
32
|
strategy: [['/plan/strategy', 'plan/strategy.astro']],
|
|
33
|
+
decisions: [
|
|
34
|
+
['/plan/decisions', 'plan/decisions.astro'],
|
|
35
|
+
['/plan/decisions/[id]', 'plan/decisions/[id].astro'],
|
|
36
|
+
],
|
|
31
37
|
};
|
|
32
38
|
const PACKAGE_NAME = '@purview-dev/pm-docs-site';
|
|
39
|
+
/**
|
|
40
|
+
* The package folder, real path, with forward slashes as Vite stores its
|
|
41
|
+
* `server.fs.allow` entries. lib/index.ts (in this repository) and
|
|
42
|
+
* dist/index.js (installed) both sit one level below it.
|
|
43
|
+
*/
|
|
44
|
+
const PACKAGE_DIR = realpathSync(fileURLToPath(new URL('../', import.meta.url))).replaceAll('\\', '/');
|
|
33
45
|
const REACT_INTEGRATION = '@astrojs/react';
|
|
34
46
|
const NO_EXTERNAL = ['@astrojs/starlight', PACKAGE_NAME];
|
|
35
47
|
const SERVER_ENVIRONMENTS = ['ssr', 'astro', 'prerender'];
|
|
@@ -46,6 +58,8 @@ function resolvesFrom(name, root) {
|
|
|
46
58
|
return false;
|
|
47
59
|
}
|
|
48
60
|
}
|
|
61
|
+
/** The islands' dependencies Vite's dev optimizer must pre-bundle (optimizedDependencies). */
|
|
62
|
+
const BROWSER_DEPENDENCIES = ['react-dom/client', '@xyflow/react'];
|
|
49
63
|
/**
|
|
50
64
|
* The `optimizeDeps.include` entries the site lacks. The island's renderer
|
|
51
65
|
* (@astrojs/react-renderer) imports react-dom/client from under node_modules,
|
|
@@ -54,12 +68,15 @@ function resolvesFrom(name, root) {
|
|
|
54
68
|
* through itself (`<package> > react-dom/client`); a site that cannot resolve
|
|
55
69
|
* the package by name (this repository's fixtures) names react-dom/client
|
|
56
70
|
* plainly, since naming a package Vite cannot resolve breaks the optimizer.
|
|
57
|
-
*
|
|
71
|
+
* The Graph island's @xyflow/react is imported from this package's own source
|
|
72
|
+
* under node_modules, which the optimizer does not scan either, and its
|
|
73
|
+
* react-compiler-runtime dependency is CommonJS, so it is pre-bundled the same
|
|
74
|
+
* way. Only missing entries: Vite's mergeConfig concatenates arrays.
|
|
58
75
|
*/
|
|
59
76
|
function optimizedDependencies(include, root) {
|
|
60
77
|
const existing = Array.isArray(include) ? include : [];
|
|
61
|
-
const
|
|
62
|
-
return
|
|
78
|
+
const viaPackage = resolvesFrom(PACKAGE_NAME, root);
|
|
79
|
+
return BROWSER_DEPENDENCIES.map((name) => (viaPackage ? `${PACKAGE_NAME} > ${name}` : name)).filter((entry) => !existing.includes(entry));
|
|
63
80
|
}
|
|
64
81
|
const VIRTUAL_ID = 'virtual:pm-docs-site/config';
|
|
65
82
|
const RESOLVED_ID = `\0${VIRTUAL_ID}`;
|
|
@@ -88,6 +105,8 @@ export default function pmDocsSite(options) {
|
|
|
88
105
|
title: resolved.title,
|
|
89
106
|
...(resolved.description ? { description: resolved.description } : {}),
|
|
90
107
|
sidebar: buildSidebar(resolved),
|
|
108
|
+
// src/pages/404.astro is the not-found page (it says why).
|
|
109
|
+
disable404Route: true,
|
|
91
110
|
// Every page uses the full width (src/styles/width.css).
|
|
92
111
|
customCss: [fileURLToPath(new URL('../src/styles/width.css', import.meta.url))],
|
|
93
112
|
}),
|
|
@@ -109,6 +128,21 @@ export default function pmDocsSite(options) {
|
|
|
109
128
|
name: 'pm-docs-site:no-external',
|
|
110
129
|
configEnvironment: (name) => SERVER_ENVIRONMENTS.includes(name) ? { resolve: { noExternal: [...NO_EXTERNAL] } } : undefined,
|
|
111
130
|
},
|
|
131
|
+
{
|
|
132
|
+
// Serve the package's own files in dev. The in-repo fixture and a linked
|
|
133
|
+
// consumer resolve the package outside the site's workspace root, so Vite
|
|
134
|
+
// refuses its node_modules (the React island client) and nothing hydrates.
|
|
135
|
+
// Append only: Vite's defaults and the consumer's entries stay. The entry
|
|
136
|
+
// serves the whole package folder in in-repo and linked dev; Vite's
|
|
137
|
+
// `server.fs.deny` still guards it. On a case-insensitive file system a
|
|
138
|
+
// path that differs only in case appends a second, harmless entry.
|
|
139
|
+
name: 'pm-docs-site:fs-allow',
|
|
140
|
+
configResolved: (resolvedConfig) => {
|
|
141
|
+
const { allow } = resolvedConfig.server.fs;
|
|
142
|
+
if (!allow.some((entry) => containsPath(entry, PACKAGE_DIR)))
|
|
143
|
+
allow.push(PACKAGE_DIR);
|
|
144
|
+
},
|
|
145
|
+
},
|
|
112
146
|
],
|
|
113
147
|
},
|
|
114
148
|
});
|
package/dist/options.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// the site root, so the pages and the content config never resolve a path again.
|
|
3
3
|
import { resolve } from 'node:path';
|
|
4
4
|
/** The optional plan views. Home, Board, Roadmap, Log and Risks are always on. */
|
|
5
|
-
export const VIEW_NAMES = ['now', 'milestones', 'features', 'inbox', 'briefs', 'strategy'];
|
|
5
|
+
export const VIEW_NAMES = ['now', 'milestones', 'graph', 'features', 'inbox', 'briefs', 'strategy', 'decisions'];
|
|
6
6
|
/** Where the export lives by default, relative to the site root. */
|
|
7
7
|
const DEFAULT_PLANNING = '../planning/planning.json';
|
|
8
8
|
/**
|
package/dist/schema-version.d.ts
CHANGED
|
@@ -8,3 +8,20 @@ export declare class PlanningExportError extends Error {
|
|
|
8
8
|
* @param path the export's path, for the message
|
|
9
9
|
*/
|
|
10
10
|
export declare function checkSchemaVersion(version: unknown, path: string): void;
|
|
11
|
+
/**
|
|
12
|
+
* Throw unless the parsed export is an object with a schemaVersion this package
|
|
13
|
+
* reads, so `null`, an array, or a scalar fails with the pm-export hint.
|
|
14
|
+
* @param path the export's path, for the message
|
|
15
|
+
*/
|
|
16
|
+
export declare function checkExport(value: unknown, path: string): asserts value is {
|
|
17
|
+
schemaVersion: number;
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* Parse and check the export's text: invalid JSON, a non-object, or an
|
|
21
|
+
* unsupported schemaVersion throws PlanningExportError, which names the path
|
|
22
|
+
* and the pm-export hint.
|
|
23
|
+
* @param path the export's path, for the message
|
|
24
|
+
*/
|
|
25
|
+
export declare function parseExport(text: string, path: string): {
|
|
26
|
+
schemaVersion: number;
|
|
27
|
+
};
|
package/dist/schema-version.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// The pm-export schemaVersions this package reads, declared once. A new export
|
|
2
2
|
// format is supported by adding its version here, with the page changes it needs.
|
|
3
|
-
export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([
|
|
3
|
+
export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([5]);
|
|
4
4
|
/** The plan export is missing, unreadable, or in a format this package does not read. */
|
|
5
5
|
export class PlanningExportError extends Error {
|
|
6
6
|
constructor(message) {
|
|
@@ -17,3 +17,32 @@ export function checkSchemaVersion(version, path) {
|
|
|
17
17
|
return;
|
|
18
18
|
throw new PlanningExportError(`${path} has schemaVersion ${String(version)}; this site reads schemaVersion ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}.`);
|
|
19
19
|
}
|
|
20
|
+
/**
|
|
21
|
+
* Throw unless the parsed export is an object with a schemaVersion this package
|
|
22
|
+
* reads, so `null`, an array, or a scalar fails with the pm-export hint.
|
|
23
|
+
* @param path the export's path, for the message
|
|
24
|
+
*/
|
|
25
|
+
export function checkExport(value, path) {
|
|
26
|
+
if (value === null || typeof value !== 'object' || Array.isArray(value)) {
|
|
27
|
+
const kind = value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
|
|
28
|
+
throw new PlanningExportError(`${path} does not hold a plan export (found ${kind}).`);
|
|
29
|
+
}
|
|
30
|
+
checkSchemaVersion(value.schemaVersion, path);
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Parse and check the export's text: invalid JSON, a non-object, or an
|
|
34
|
+
* unsupported schemaVersion throws PlanningExportError, which names the path
|
|
35
|
+
* and the pm-export hint.
|
|
36
|
+
* @param path the export's path, for the message
|
|
37
|
+
*/
|
|
38
|
+
export function parseExport(text, path) {
|
|
39
|
+
let value;
|
|
40
|
+
try {
|
|
41
|
+
value = JSON.parse(text);
|
|
42
|
+
}
|
|
43
|
+
catch (error) {
|
|
44
|
+
throw new PlanningExportError(`${path} is not valid JSON (${error.message}).`);
|
|
45
|
+
}
|
|
46
|
+
checkExport(value, path);
|
|
47
|
+
return value;
|
|
48
|
+
}
|
package/dist/sidebar.js
CHANGED
|
@@ -7,10 +7,12 @@ export function buildSidebar(options) {
|
|
|
7
7
|
views.now && { label: 'Now', link: '/plan/now/' },
|
|
8
8
|
{ label: 'Board', link: '/plan/board/' },
|
|
9
9
|
{ label: 'Roadmap', link: '/plan/roadmap/' },
|
|
10
|
+
views.graph && { label: 'Graph', link: '/plan/graph/' },
|
|
10
11
|
views.milestones && { label: 'Milestones', link: '/plan/milestones/' },
|
|
11
12
|
views.features && { label: 'Features', link: '/plan/features/' },
|
|
12
13
|
{ label: 'Log', link: '/plan/log/' },
|
|
13
14
|
{ label: 'Risks', link: '/plan/risks/' },
|
|
15
|
+
views.decisions && { label: 'Decisions', link: '/plan/decisions/' },
|
|
14
16
|
views.inbox && { label: 'Inbox', link: '/plan/inbox/' },
|
|
15
17
|
views.briefs && { label: 'Briefs', link: '/plan/briefs/' },
|
|
16
18
|
views.strategy && { label: 'Strategy', link: '/plan/strategy/' },
|
package/dist/site-options.js
CHANGED
|
@@ -21,6 +21,11 @@ export async function loadSiteOptions(siteDir, flags) {
|
|
|
21
21
|
configFile: null,
|
|
22
22
|
};
|
|
23
23
|
}
|
|
24
|
+
// The config file holds the options; a flag given beside it would be lost silently.
|
|
25
|
+
for (const flag of ['title', 'planning']) {
|
|
26
|
+
if (flags[flag] !== undefined)
|
|
27
|
+
console.warn(`pm-docs-site: --${flag} is ignored: ${configFile} sets the options.`);
|
|
28
|
+
}
|
|
24
29
|
// Plain Node loads the config, so a TypeScript config may only use what Node
|
|
25
30
|
// strips: erasable syntax and relative imports that name their file.
|
|
26
31
|
let config;
|
package/dist/types.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** An optional plan view. Home, Board, Roadmap, Log and Risks are always on. */
|
|
2
|
-
export type ViewName = 'now' | 'milestones' | 'features' | 'inbox' | 'briefs' | 'strategy';
|
|
2
|
+
export type ViewName = 'now' | 'milestones' | 'graph' | 'features' | 'inbox' | 'briefs' | 'strategy' | 'decisions';
|
|
3
3
|
/** One folder of repository Markdown, shown as one sidebar group. */
|
|
4
4
|
export interface DocsSource {
|
|
5
5
|
/** The sidebar group for this source's pages. */
|
|
@@ -29,7 +29,7 @@ export interface PmDocsSiteOptions {
|
|
|
29
29
|
root: string;
|
|
30
30
|
sources: DocsSource[];
|
|
31
31
|
};
|
|
32
|
-
/** The optional views to render. Default: all
|
|
32
|
+
/** The optional views to render. Default: all seven. */
|
|
33
33
|
views?: ViewName[];
|
|
34
34
|
}
|
|
35
35
|
/** The options with defaults applied and every path absolute. */
|
package/lib/schema-version.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// The pm-export schemaVersions this package reads, declared once. A new export
|
|
2
2
|
// format is supported by adding its version here, with the page changes it needs.
|
|
3
3
|
|
|
4
|
-
export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = Object.freeze([
|
|
4
|
+
export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = Object.freeze([5]);
|
|
5
5
|
|
|
6
6
|
/** The plan export is missing, unreadable, or in a format this package does not read. */
|
|
7
7
|
export class PlanningExportError extends Error {
|
|
@@ -22,3 +22,38 @@ export function checkSchemaVersion(version: unknown, path: string): void {
|
|
|
22
22
|
`${path} has schemaVersion ${String(version)}; this site reads schemaVersion ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}.`,
|
|
23
23
|
);
|
|
24
24
|
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Throw unless the parsed export is an object with a schemaVersion this package
|
|
28
|
+
* reads, so `null`, an array, or a scalar fails with the pm-export hint.
|
|
29
|
+
* @param path the export's path, for the message
|
|
30
|
+
*/
|
|
31
|
+
export function checkExport(value: unknown, path: string): asserts value is { schemaVersion: number } {
|
|
32
|
+
if (value === null || typeof value !== 'object' || Array.isArray(value)) {
|
|
33
|
+
const kind = value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
|
|
34
|
+
|
|
35
|
+
throw new PlanningExportError(`${path} does not hold a plan export (found ${kind}).`);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
checkSchemaVersion((value as { schemaVersion?: unknown }).schemaVersion, path);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Parse and check the export's text: invalid JSON, a non-object, or an
|
|
43
|
+
* unsupported schemaVersion throws PlanningExportError, which names the path
|
|
44
|
+
* and the pm-export hint.
|
|
45
|
+
* @param path the export's path, for the message
|
|
46
|
+
*/
|
|
47
|
+
export function parseExport(text: string, path: string): { schemaVersion: number } {
|
|
48
|
+
let value: unknown;
|
|
49
|
+
|
|
50
|
+
try {
|
|
51
|
+
value = JSON.parse(text);
|
|
52
|
+
} catch (error) {
|
|
53
|
+
throw new PlanningExportError(`${path} is not valid JSON (${(error as Error).message}).`);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
checkExport(value, path);
|
|
57
|
+
|
|
58
|
+
return value;
|
|
59
|
+
}
|
package/lib/types.ts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// The integration's option types, re-exported by index.ts. A separate module
|
|
2
|
+
// so the other lib/ modules and src/ can import them without importing the
|
|
3
|
+
// integration itself.
|
|
4
|
+
|
|
5
|
+
/** An optional plan view. Home, Board, Roadmap, Log and Risks are always on. */
|
|
6
|
+
export type ViewName = 'now' | 'milestones' | 'graph' | 'features' | 'inbox' | 'briefs' | 'strategy' | 'decisions';
|
|
7
|
+
|
|
8
|
+
/** One folder of repository Markdown, shown as one sidebar group. */
|
|
9
|
+
export interface DocsSource {
|
|
10
|
+
/** The sidebar group for this source's pages. */
|
|
11
|
+
label: string;
|
|
12
|
+
/** The folder to read, relative to the docs root (`.` for the root). */
|
|
13
|
+
base: string;
|
|
14
|
+
/** Files to read, as globs relative to `base` (`*` within a folder, `**` across folders). */
|
|
15
|
+
include: string[];
|
|
16
|
+
/** Prepended to each page's path to make its URL. Default: none. */
|
|
17
|
+
prefix?: string;
|
|
18
|
+
/** A file name that stands for its folder, such as `SKILL.md` or `README.md`. */
|
|
19
|
+
indexFile?: string;
|
|
20
|
+
/** Sidebar order by page path. Default: `asc`. */
|
|
21
|
+
order?: 'asc' | 'desc';
|
|
22
|
+
collapsed?: boolean;
|
|
23
|
+
/** Load the pages without listing them in the sidebar. */
|
|
24
|
+
hidden?: boolean;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface PmDocsSiteOptions {
|
|
28
|
+
/** The site title. */
|
|
29
|
+
title: string;
|
|
30
|
+
description?: string;
|
|
31
|
+
/** The pm-export file, relative to the site root. Default: `../planning/planning.json`. */
|
|
32
|
+
planning?: string;
|
|
33
|
+
/** Repository Markdown to render as pages; `root` is relative to the site root. Default: none. */
|
|
34
|
+
docs?: { root: string; sources: DocsSource[] };
|
|
35
|
+
/** The optional views to render. Default: all seven. */
|
|
36
|
+
views?: ViewName[];
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** The options with defaults applied and every path absolute. */
|
|
40
|
+
export interface ResolvedOptions {
|
|
41
|
+
title: string;
|
|
42
|
+
description: string | null;
|
|
43
|
+
planning: string;
|
|
44
|
+
/** The export path as the options wrote it, `/`-separated: shown on pages instead of the machine path. */
|
|
45
|
+
planningLabel: string;
|
|
46
|
+
docs: { root: string; sources: DocsSource[] } | null;
|
|
47
|
+
views: Record<ViewName, boolean>;
|
|
48
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@purview-dev/pm-docs-site",
|
|
3
|
-
"version": "0.1.0-pre.
|
|
3
|
+
"version": "0.1.0-pre.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "A local, searchable project site for pm-skills: the board, roadmap, milestones, features, log, and risks from pm-export's planning.json, with the repository's Markdown, as an Astro and Starlight integration.",
|
|
6
6
|
"license": "MIT",
|
|
@@ -43,17 +43,20 @@
|
|
|
43
43
|
"default": "./dist/index.js"
|
|
44
44
|
}
|
|
45
45
|
},
|
|
46
|
-
"files": ["dist", "src", "lib/repo-docs.ts", "lib/schema-version.ts", "README.md", "LICENSE.md"],
|
|
46
|
+
"files": ["dist", "src", "lib/repo-docs.ts", "lib/schema-version.ts", "lib/types.ts", "README.md", "LICENSE.md"],
|
|
47
47
|
"scripts": {
|
|
48
48
|
"build": "node scripts/build.ts",
|
|
49
49
|
"prepack": "node scripts/build.ts && node scripts/check-exports.ts",
|
|
50
50
|
"test": "bun test",
|
|
51
51
|
"check": "astro-check --root .",
|
|
52
|
-
"test:browser": "playwright test"
|
|
52
|
+
"test:browser": "playwright test",
|
|
53
|
+
"test:browser:dev": "playwright test -c playwright.dev.config.ts"
|
|
53
54
|
},
|
|
54
55
|
"dependencies": {
|
|
55
56
|
"@astrojs/react": "7.1.9",
|
|
56
57
|
"@astrojs/starlight": "0.42.10",
|
|
58
|
+
"@dagrejs/dagre": "3.1.3",
|
|
59
|
+
"@xyflow/react": "13.0.2",
|
|
57
60
|
"astro": "7.4.8",
|
|
58
61
|
"react": "19.3.1",
|
|
59
62
|
"react-dom": "19.3.1"
|
|
@@ -62,6 +65,7 @@
|
|
|
62
65
|
"@astrojs/check": "0.9.12",
|
|
63
66
|
"@playwright/test": "1.65.1",
|
|
64
67
|
"@types/bun": "1.4.4",
|
|
68
|
+
"@types/node": "26.6.6",
|
|
65
69
|
"@types/react": "19.3.0",
|
|
66
70
|
"@types/react-dom": "19.3.0",
|
|
67
71
|
"typescript": "6.0.3"
|
|
@@ -1,25 +1,31 @@
|
|
|
1
1
|
---
|
|
2
|
-
// One item's summary: state, milestone, facts, Done when, related items, brief
|
|
3
|
-
// and risks. The feature page shows it, and so does the item popup on the
|
|
2
|
+
// One item's summary: state, milestone, facts, Done when, related items, brief,
|
|
3
|
+
// decisions (the ADRs whose Item is this item) and risks. The feature page shows it, and so does the item popup on the
|
|
4
4
|
// Board and Roadmap, so the two never drift.
|
|
5
|
-
import { briefOf, dependents, features, loadPlanning, planProgress } from '../lib/planning';
|
|
5
|
+
import { adrsOf, briefOf, dependents, features, loadPlanning, planProgress } from '../lib/planning';
|
|
6
6
|
import LinkedText from './LinkedText.astro';
|
|
7
7
|
import RefLink from './RefLink.astro';
|
|
8
8
|
import StateBadge from './StateBadge.astro';
|
|
9
9
|
|
|
10
10
|
interface Props {
|
|
11
11
|
id: string;
|
|
12
|
+
/** h2 on the feature page (default); h3 in the item popup, below its h2 title. */
|
|
13
|
+
headingLevel?: 2 | 3;
|
|
12
14
|
}
|
|
13
15
|
|
|
16
|
+
const { id, headingLevel } = Astro.props;
|
|
17
|
+
const Heading = headingLevel === 3 ? 'h3' : 'h2';
|
|
18
|
+
|
|
14
19
|
const planning = loadPlanning();
|
|
15
20
|
const all = features(planning);
|
|
16
|
-
const feature = all.find((candidate) => candidate.id ===
|
|
21
|
+
const feature = all.find((candidate) => candidate.id === id)!;
|
|
17
22
|
const byId = new Map(all.map((candidate) => [candidate.id, candidate]));
|
|
18
23
|
const brief = briefOf(planning, feature);
|
|
19
24
|
const blocks = dependents(all, feature.id);
|
|
20
25
|
const revisedBy = all.filter((candidate) => candidate.revisits === feature.id);
|
|
21
26
|
const risks = [...planning.risks.open, ...planning.risks.closed].filter((risk) => risk.affects === feature.id);
|
|
22
27
|
const plan = feature.state === 'now' ? planning.plan : null;
|
|
28
|
+
const adrs = adrsOf(planning, feature.id);
|
|
23
29
|
|
|
24
30
|
const facts: { label: string; value: string }[] = [
|
|
25
31
|
{ label: 'Owner', value: feature.owner ?? '–' },
|
|
@@ -46,7 +52,7 @@ const facts: { label: string; value: string }[] = [
|
|
|
46
52
|
)
|
|
47
53
|
}
|
|
48
54
|
{' '}
|
|
49
|
-
<RefLink ref={feature.milestone ?? 'none'} />
|
|
55
|
+
<RefLink ref={feature.milestone ?? 'none'} fallback={feature.milestone ?? 'No milestone'} />
|
|
50
56
|
</p>
|
|
51
57
|
|
|
52
58
|
<dl class="plan-facts">
|
|
@@ -65,7 +71,7 @@ const facts: { label: string; value: string }[] = [
|
|
|
65
71
|
{
|
|
66
72
|
feature.doneWhen.length > 0 && (
|
|
67
73
|
<section>
|
|
68
|
-
<
|
|
74
|
+
<Heading>Done when</Heading>
|
|
69
75
|
<ul>
|
|
70
76
|
{feature.doneWhen.map((check) => (
|
|
71
77
|
<li>
|
|
@@ -80,7 +86,7 @@ const facts: { label: string; value: string }[] = [
|
|
|
80
86
|
{
|
|
81
87
|
(feature.dependsOn.length > 0 || blocks.length > 0 || feature.revisits || revisedBy.length > 0) && (
|
|
82
88
|
<section>
|
|
83
|
-
<
|
|
89
|
+
<Heading>Related items</Heading>
|
|
84
90
|
<ul>
|
|
85
91
|
{feature.dependsOn.map((dep) => (
|
|
86
92
|
<li>
|
|
@@ -110,7 +116,7 @@ const facts: { label: string; value: string }[] = [
|
|
|
110
116
|
{
|
|
111
117
|
(brief || feature.brief) && (
|
|
112
118
|
<section>
|
|
113
|
-
<
|
|
119
|
+
<Heading>Brief</Heading>
|
|
114
120
|
{brief ? (
|
|
115
121
|
<>
|
|
116
122
|
<p>
|
|
@@ -140,10 +146,25 @@ const facts: { label: string; value: string }[] = [
|
|
|
140
146
|
)
|
|
141
147
|
}
|
|
142
148
|
|
|
149
|
+
{
|
|
150
|
+
adrs.length > 0 && (
|
|
151
|
+
<section>
|
|
152
|
+
<Heading>Decisions</Heading>
|
|
153
|
+
<ul>
|
|
154
|
+
{adrs.map((adr) => (
|
|
155
|
+
<li>
|
|
156
|
+
<RefLink ref={adr.id} /> — {adr.status ?? 'unknown'}
|
|
157
|
+
</li>
|
|
158
|
+
))}
|
|
159
|
+
</ul>
|
|
160
|
+
</section>
|
|
161
|
+
)
|
|
162
|
+
}
|
|
163
|
+
|
|
143
164
|
{
|
|
144
165
|
risks.length > 0 && (
|
|
145
166
|
<section>
|
|
146
|
-
<
|
|
167
|
+
<Heading>Risks</Heading>
|
|
147
168
|
<ul>
|
|
148
169
|
{risks.map((risk) => (
|
|
149
170
|
<li>
|