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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +70 -10
  2. package/dist/cli.js +4 -3
  3. package/dist/dev-env.d.ts +2 -0
  4. package/dist/dev-env.js +13 -0
  5. package/dist/fs-allow.d.ts +2 -0
  6. package/dist/fs-allow.js +11 -0
  7. package/dist/index.js +38 -4
  8. package/dist/options.js +1 -1
  9. package/dist/schema-version.d.ts +17 -0
  10. package/dist/schema-version.js +30 -1
  11. package/dist/sidebar.js +2 -0
  12. package/dist/site-options.js +5 -0
  13. package/dist/types.d.ts +2 -2
  14. package/lib/schema-version.ts +36 -1
  15. package/lib/types.ts +48 -0
  16. package/package.json +7 -3
  17. package/src/components/FeatureSummary.astro +30 -9
  18. package/src/components/FeatureTable.astro +1 -1
  19. package/src/components/ItemDetail.astro +1 -1
  20. package/src/components/ItemDialog.astro +12 -8
  21. package/src/components/RefLink.astro +7 -4
  22. package/src/components/board/Board.tsx +16 -8
  23. package/src/components/board/KanbanItemCard.tsx +4 -2
  24. package/src/components/board/TaskKanbanCard.tsx +4 -2
  25. package/src/components/decisions/Decisions.tsx +162 -0
  26. package/src/components/decisions/useDecisionsUrlState.ts +29 -0
  27. package/src/components/graph/Graph.tsx +290 -0
  28. package/src/components/graph/GraphNodes.tsx +120 -0
  29. package/src/components/graph/useGraphUrlState.ts +58 -0
  30. package/src/components/lib/KanbanItemCard.astro +7 -11
  31. package/src/components/lib/StatusTimelineFeed.astro +3 -2
  32. package/src/components/lib/TaskKanbanCard.astro +2 -1
  33. package/src/components/timeline/Timeline.tsx +39 -6
  34. package/src/components/timeline/useTimelineLayout.ts +2 -2
  35. package/src/content.config.ts +22 -6
  36. package/src/lib/decisions.ts +100 -0
  37. package/src/lib/graph-layout.ts +270 -0
  38. package/src/lib/graph-state.ts +99 -0
  39. package/src/lib/graph.ts +194 -0
  40. package/src/lib/link-html.ts +39 -0
  41. package/src/lib/planning-types.ts +32 -3
  42. package/src/lib/planning.ts +30 -16
  43. package/src/lib/ref-boundary.ts +19 -0
  44. package/src/lib/references.ts +66 -7
  45. package/src/lib/timeline-state.ts +119 -0
  46. package/src/lib/timeline.ts +22 -127
  47. package/src/loaders/adrs.ts +43 -0
  48. package/src/pages/404.astro +18 -0
  49. package/src/pages/index.astro +1 -1
  50. package/src/pages/plan/log.astro +18 -1
  51. package/src/pages/plan/roadmap.astro +1 -1
  52. package/src/routes/plan/decisions/[id].astro +93 -0
  53. package/src/routes/plan/decisions.astro +52 -0
  54. package/src/routes/plan/graph.astro +80 -0
  55. package/src/routes/plan/milestones/index.astro +2 -2
  56. package/src/routes/plan/now.astro +2 -3
  57. package/src/scripts/plan.ts +33 -1
  58. package/src/styles/components.css +117 -3
  59. package/src/styles/graph.css +296 -0
  60. package/src/styles/timeline.css +1 -1
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.1" }
35
+ "dependencies": { "@purview-dev/pm-docs-site": "0.1.0-pre.3" }
32
36
  }
33
37
  ```
34
38
 
35
- ```js
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 six |
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` 3. Any other version fails the build and `check`, and the
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 with missing
180
- or non-JavaScript entry points. It publishes a prerelease
181
- (`0.1.0-pre.1`) under the `prerelease` dist-tag and a stable version under
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 the first version (`0.1.0-pre.1`), and
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 { checkSchemaVersion } from "./schema-version.js";
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
- const planning = JSON.parse(readFileSync(options.planning, 'utf8'));
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;
@@ -0,0 +1,2 @@
1
+ /** Sets ASTRO_DISABLE_UPDATE_CHECK to `true` in `env` when it is unset. */
2
+ export declare function disableUpdateCheck(env: NodeJS.ProcessEnv): void;
@@ -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
+ }
@@ -0,0 +1,2 @@
1
+ /** Whether `path` is `entry` or inside it. Separators, drives and case follow `node:path`. */
2
+ export declare function containsPath(entry: string, path: string): boolean;
@@ -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
- * Only missing entries: Vite's mergeConfig concatenates arrays.
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 entry = resolvesFrom(PACKAGE_NAME, root) ? `${PACKAGE_NAME} > react-dom/client` : 'react-dom/client';
62
- return existing.includes(entry) ? [] : [entry];
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
  /**
@@ -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
+ };
@@ -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]);
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/' },
@@ -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 six. */
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. */
@@ -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([3]);
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.2",
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 === Astro.props.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
- <h2>Done when</h2>
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
- <h2>Related items</h2>
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
- <h2>Brief</h2>
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
- <h2>Risks</h2>
167
+ <Heading>Risks</Heading>
147
168
  <ul>
148
169
  {risks.map((risk) => (
149
170
  <li>