@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
package/LICENSE.md
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright © 2026 Kieron Lanning
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,168 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @purview-dev/pm-docs-site
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A local, searchable project site for [pm-skills](https://github.com/purview-dev/pm-skills):
|
|
4
|
+
the plan from `planning.json` (written by the `pm-export` skill) and,
|
|
5
|
+
optionally, the repository's Markdown, rendered by Astro and Starlight.
|
|
6
|
+
|
|
7
|
+
**Documentation:** [PM Skills documentation](https://purview.dev/docs/pm-skills/)
|
|
8
|
+
on purview.dev (the *Docs-site package* guide page), part of the
|
|
9
|
+
[PM Skills](https://purview.dev/projects/pm-skills/) project.
|
|
10
|
+
|
|
11
|
+
Unpublished: version `0.1.0-pre.1` and `private` until roadmap item R-013 publishes
|
|
12
|
+
it to npm. Until then the repository's `docs-site/` still renders the
|
|
13
|
+
`pm-docs-site` skill's templates.
|
|
14
|
+
|
|
15
|
+
## A consumer site
|
|
16
|
+
|
|
17
|
+
Three files: `package.json`, a lockfile, and `astro.config.mjs`. No `src/`
|
|
18
|
+
folder: the integration points Astro's `srcDir` at the package.
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"name": "my-project-site",
|
|
23
|
+
"private": true,
|
|
24
|
+
"type": "module",
|
|
25
|
+
"scripts": {
|
|
26
|
+
"dev": "pm-docs-site dev",
|
|
27
|
+
"build": "pm-docs-site build",
|
|
28
|
+
"check": "pm-docs-site check"
|
|
29
|
+
},
|
|
30
|
+
"dependencies": { "@purview-dev/pm-docs-site": "0.1.0-pre.1" }
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
// astro.config.mjs
|
|
36
|
+
import pmDocsSite from '@purview-dev/pm-docs-site';
|
|
37
|
+
|
|
38
|
+
export default {
|
|
39
|
+
integrations: [
|
|
40
|
+
pmDocsSite({
|
|
41
|
+
title: 'My project',
|
|
42
|
+
planning: '../planning/planning.json',
|
|
43
|
+
docs: {
|
|
44
|
+
root: '..',
|
|
45
|
+
sources: [{ label: 'Project', base: '.', include: ['README.md'], prefix: 'project/' }],
|
|
46
|
+
},
|
|
47
|
+
}),
|
|
48
|
+
],
|
|
49
|
+
};
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Options
|
|
53
|
+
|
|
54
|
+
| Option | Type | Default |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| `title` | string | required |
|
|
57
|
+
| `description` | string | none |
|
|
58
|
+
| `planning` | path from the site root | `../planning/planning.json` |
|
|
59
|
+
| `docs` | `{ root, sources }`; `root` from the site root, each source a folder and globs | none: no repository pages |
|
|
60
|
+
| `views` | any of `now`, `milestones`, `features`, `inbox`, `briefs`, `strategy` | all six |
|
|
61
|
+
|
|
62
|
+
Home, Board, Roadmap, Log and Risks are always rendered. A docs source has
|
|
63
|
+
`label`, `base`, `include`, and optionally `prefix`, `indexFile`, `order`,
|
|
64
|
+
`collapsed`, and `hidden` (see `index.d.ts`).
|
|
65
|
+
|
|
66
|
+
## CLI
|
|
67
|
+
|
|
68
|
+
The CLI runs under Node 22 or later.
|
|
69
|
+
|
|
70
|
+
- `pm-docs-site build [site-dir]` and `pm-docs-site dev [site-dir]` run Astro
|
|
71
|
+
on the site. A site with no `astro.config.*` builds from
|
|
72
|
+
`--title <title>` and `--planning <path>`.
|
|
73
|
+
- `pm-docs-site check [site-dir]` builds nothing. It reads the export, checks
|
|
74
|
+
its `schemaVersion`, and checks every docs source folder exists, then exits
|
|
75
|
+
0, or 1 with one line per problem.
|
|
76
|
+
|
|
77
|
+
## Supported exports
|
|
78
|
+
|
|
79
|
+
`SUPPORTED_SCHEMA_VERSIONS` in `lib/schema-version.mjs`: pm-export
|
|
80
|
+
`schemaVersion` 3. Any other version fails the build and `check`, and the
|
|
81
|
+
message says to run the `pm-export` skill.
|
|
82
|
+
|
|
83
|
+
## Development
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
just package-test # bun install --frozen-lockfile, bun test, bun run check
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`bun test` includes a build of the fixture site whose page list must equal
|
|
90
|
+
`test/fixtures/expected-pages.txt`, and a build from the packed tarball
|
|
91
|
+
installed into a temporary folder.
|
|
92
|
+
|
|
93
|
+
## Releasing
|
|
94
|
+
|
|
95
|
+
The package is versioned on its own, by `version` in this `package.json`,
|
|
96
|
+
not by the repository's skills version, and tagged `pm-docs-site-v<version>`.
|
|
97
|
+
The release follows purview-dev/astroc4: bump `version` and merge to `main`.
|
|
98
|
+
That is the whole process.
|
|
99
|
+
|
|
100
|
+
### Version changes
|
|
101
|
+
|
|
102
|
+
`scripts/check-version.ts` runs on every pull request (and the pre-push
|
|
103
|
+
hook) and fails when the package's version:
|
|
104
|
+
|
|
105
|
+
- is not SemVer (`MAJOR.MINOR.PATCH`, optionally `-<prerelease>`),
|
|
106
|
+
- is older than the version on `main`,
|
|
107
|
+
- was bumped to a version whose `pm-docs-site-v<version>` tag exists, or
|
|
108
|
+
- is a prerelease of an already released version.
|
|
109
|
+
|
|
110
|
+
A bump is not required: a change that keeps the version merges, and the
|
|
111
|
+
publish workflow then skips it (REL002).
|
|
112
|
+
|
|
113
|
+
### The publish workflow
|
|
114
|
+
|
|
115
|
+
A change to this `package.json` on `main` runs
|
|
116
|
+
`.github/workflows/publish-pm-docs-site.yml`. Its eligibility step applies
|
|
117
|
+
the purview-dev release rules:
|
|
118
|
+
|
|
119
|
+
| Rule | Passes when | Otherwise |
|
|
120
|
+
| --- | --- | --- |
|
|
121
|
+
| REL001 | the version is SemVer | fails |
|
|
122
|
+
| REL002 | `pm-docs-site-v<version>` is not tagged | skips, green: the version is released |
|
|
123
|
+
| REL003 | a stable version runs from `main` | fails |
|
|
124
|
+
|
|
125
|
+
While `package.json` sets `"private": true` it also skips, green. Then it
|
|
126
|
+
installs, tests, type-checks, and runs `scripts/check-exports.mjs`, which is
|
|
127
|
+
also the `prepublishOnly` script, so a local `npm publish` cannot burn a
|
|
128
|
+
version on a package with missing files. It publishes a prerelease
|
|
129
|
+
(`0.1.0-pre.1`) under the `prerelease` dist-tag and a stable version under
|
|
130
|
+
`latest`, skips a version already on the registry, and keeps `latest` on the
|
|
131
|
+
newest prerelease until a stable release exists. Only then does it create the
|
|
132
|
+
tag and a GitHub release, never marked as the repository's latest release.
|
|
133
|
+
Every step is idempotent, so re-run it from the Actions tab
|
|
134
|
+
(`workflow_dispatch`).
|
|
135
|
+
|
|
136
|
+
The tag is written only by the workflow. A hand-pushed
|
|
137
|
+
`pm-docs-site-v<version>` tag makes the release of that version skip.
|
|
138
|
+
|
|
139
|
+
### Authentication: npm trusted publishing
|
|
140
|
+
|
|
141
|
+
The workflow holds no npm token: `id-token: write` lets npm exchange the
|
|
142
|
+
job's OIDC token for a short-lived publish credential, and npm attaches
|
|
143
|
+
provenance itself. `scripts/workflows.test.ts` fails a pull request that adds
|
|
144
|
+
a token, `registry-url`, or `--provenance`. The job runs in the GitHub `npm`
|
|
145
|
+
environment.
|
|
146
|
+
|
|
147
|
+
A trusted publisher is configured on the package, so the package must exist
|
|
148
|
+
on npm first. Once, from an account that can publish to `@purview-dev`:
|
|
149
|
+
|
|
150
|
+
1. Remove `"private": true`, set the first version (`0.1.0-pre.1`), and
|
|
151
|
+
publish it locally: `npm publish --access public --tag prerelease`.
|
|
152
|
+
2. Add the trusted publisher, with *Allow npm publish* and *Allow npm
|
|
153
|
+
dist-tag* ticked (the CLI grants only the first):
|
|
154
|
+
|
|
155
|
+
```sh
|
|
156
|
+
npm trust github @purview-dev/pm-docs-site \
|
|
157
|
+
--repo purview-dev/pm-skills \
|
|
158
|
+
--file publish-pm-docs-site.yml \
|
|
159
|
+
--allow-publish
|
|
160
|
+
npm trust list @purview-dev/pm-docs-site
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
3. Merge that version bump. Its tag does not exist yet, so the workflow
|
|
164
|
+
finds the version on the registry, skips the publish, and writes the tag
|
|
165
|
+
and the release. Every later version is published by the workflow.
|
|
166
|
+
|
|
167
|
+
Renaming `publish-pm-docs-site.yml` stops publishing until the trusted
|
|
168
|
+
publisher is re-created, because npm validates the workflow filename.
|
package/cli.mjs
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// @ts-check
|
|
3
|
+
// pm-docs-site <dev | build | check> [site-dir] [--title <t>] [--planning <p>]
|
|
4
|
+
//
|
|
5
|
+
// dev and build run Astro on the site folder: with its astro.config file when it
|
|
6
|
+
// has one, else with the integration built from --title and --planning. check
|
|
7
|
+
// builds nothing: it reads the export and the docs sources and reports problems.
|
|
8
|
+
|
|
9
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
10
|
+
import { resolve } from 'node:path';
|
|
11
|
+
|
|
12
|
+
import { resolveOptions } from './lib/options.mjs';
|
|
13
|
+
import { checkSchemaVersion } from './lib/schema-version.mjs';
|
|
14
|
+
import { loadSiteOptions } from './lib/site-options.mjs';
|
|
15
|
+
|
|
16
|
+
const USAGE = 'usage: pm-docs-site <dev | build | check> [site-dir] [--title <title>] [--planning <path>]';
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @param {string[]} argv
|
|
20
|
+
* @returns {{ command: string | undefined; siteDir: string; flags: { title?: string; planning?: string } }}
|
|
21
|
+
*/
|
|
22
|
+
function parse(argv) {
|
|
23
|
+
/** @type {{ title?: string; planning?: string }} */
|
|
24
|
+
const flags = {};
|
|
25
|
+
/** @type {string[]} */
|
|
26
|
+
const positional = [];
|
|
27
|
+
|
|
28
|
+
for (let index = 0; index < argv.length; index++) {
|
|
29
|
+
const arg = /** @type {string} */ (argv[index]);
|
|
30
|
+
|
|
31
|
+
if (arg === '--title' || arg === '--planning') {
|
|
32
|
+
const value = argv[++index];
|
|
33
|
+
if (value === undefined) throw new Error(`pm-docs-site: ${arg} needs a value`);
|
|
34
|
+
flags[arg === '--title' ? 'title' : 'planning'] = value;
|
|
35
|
+
} else {
|
|
36
|
+
positional.push(arg);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
return { command: positional[0], siteDir: resolve(positional[1] ?? process.cwd()), flags };
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The problems check finds, one line each.
|
|
45
|
+
* @param {import('./index').ResolvedOptions} options
|
|
46
|
+
* @returns {string[]}
|
|
47
|
+
*/
|
|
48
|
+
function problems(options) {
|
|
49
|
+
/** @type {string[]} */
|
|
50
|
+
const found = [];
|
|
51
|
+
|
|
52
|
+
if (!existsSync(options.planning)) {
|
|
53
|
+
found.push(`No plan export at ${options.planning}. Run the pm-export skill to write planning.json.`);
|
|
54
|
+
} else {
|
|
55
|
+
try {
|
|
56
|
+
const planning = JSON.parse(readFileSync(options.planning, 'utf8'));
|
|
57
|
+
checkSchemaVersion(planning.schemaVersion, options.planning);
|
|
58
|
+
} catch (error) {
|
|
59
|
+
found.push(/** @type {Error} */ (error).message);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
for (const source of options.docs?.sources ?? []) {
|
|
64
|
+
const base = resolve(options.docs?.root ?? '.', source.base);
|
|
65
|
+
if (!existsSync(base)) found.push(`docs source "${source.label}": no folder at ${base}`);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
return found;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
async function main() {
|
|
72
|
+
const { command, siteDir, flags } = parse(process.argv.slice(2));
|
|
73
|
+
|
|
74
|
+
if (command !== 'dev' && command !== 'build' && command !== 'check') {
|
|
75
|
+
console.error(USAGE);
|
|
76
|
+
return 2;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const { options, configFile } = await loadSiteOptions(siteDir, flags);
|
|
80
|
+
|
|
81
|
+
if (command === 'check') {
|
|
82
|
+
const resolved = resolveOptions(options, siteDir);
|
|
83
|
+
const found = problems(resolved);
|
|
84
|
+
|
|
85
|
+
for (const line of found) console.error(`pm-docs-site: ${line}`);
|
|
86
|
+
if (found.length) return 1;
|
|
87
|
+
|
|
88
|
+
const { schemaVersion } = JSON.parse(readFileSync(resolved.planning, 'utf8'));
|
|
89
|
+
console.log(`pm-docs-site: ok (${resolved.planning}, schemaVersion ${schemaVersion})`);
|
|
90
|
+
return 0;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
const astro = await import('astro');
|
|
94
|
+
/** @type {import('astro').AstroInlineConfig} */
|
|
95
|
+
const inline = { root: siteDir };
|
|
96
|
+
|
|
97
|
+
if (!configFile) {
|
|
98
|
+
const { default: pmDocsSite } = await import('./index.mjs');
|
|
99
|
+
Object.assign(inline, { configFile: false, integrations: [pmDocsSite(options)] });
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
if (command === 'build') {
|
|
103
|
+
await astro.build(inline);
|
|
104
|
+
return 0;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
await astro.dev(inline);
|
|
108
|
+
// The dev server keeps the process alive until it is stopped.
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
main().then(
|
|
113
|
+
(code) => {
|
|
114
|
+
if (code !== null) process.exitCode = code;
|
|
115
|
+
},
|
|
116
|
+
(error) => {
|
|
117
|
+
console.error(error instanceof Error ? error.message : error);
|
|
118
|
+
process.exitCode = 1;
|
|
119
|
+
},
|
|
120
|
+
);
|
package/index.d.ts
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import type { AstroIntegration } from 'astro';
|
|
2
|
+
|
|
3
|
+
/** An optional plan view. Home, Board, Roadmap, Log and Risks are always on. */
|
|
4
|
+
export type ViewName = 'now' | 'milestones' | 'features' | 'inbox' | 'briefs' | 'strategy';
|
|
5
|
+
|
|
6
|
+
/** One folder of repository Markdown, shown as one sidebar group. */
|
|
7
|
+
export interface DocsSource {
|
|
8
|
+
/** The sidebar group for this source's pages. */
|
|
9
|
+
label: string;
|
|
10
|
+
/** The folder to read, relative to the docs root (`.` for the root). */
|
|
11
|
+
base: string;
|
|
12
|
+
/** Files to read, as globs relative to `base` (`*` within a folder, `**` across folders). */
|
|
13
|
+
include: string[];
|
|
14
|
+
/** Prepended to each page's path to make its URL. Default: none. */
|
|
15
|
+
prefix?: string;
|
|
16
|
+
/** A file name that stands for its folder, such as `SKILL.md` or `README.md`. */
|
|
17
|
+
indexFile?: string;
|
|
18
|
+
/** Sidebar order by page path. Default: `asc`. */
|
|
19
|
+
order?: 'asc' | 'desc';
|
|
20
|
+
collapsed?: boolean;
|
|
21
|
+
/** Load the pages without listing them in the sidebar. */
|
|
22
|
+
hidden?: boolean;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export interface PmDocsSiteOptions {
|
|
26
|
+
/** The site title. */
|
|
27
|
+
title: string;
|
|
28
|
+
description?: string;
|
|
29
|
+
/** The pm-export file, relative to the site root. Default: `../planning/planning.json`. */
|
|
30
|
+
planning?: string;
|
|
31
|
+
/** Repository Markdown to render as pages; `root` is relative to the site root. Default: none. */
|
|
32
|
+
docs?: { root: string; sources: DocsSource[] };
|
|
33
|
+
/** The optional views to render. Default: all six. */
|
|
34
|
+
views?: ViewName[];
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The options with defaults applied and every path absolute. */
|
|
38
|
+
export interface ResolvedOptions {
|
|
39
|
+
title: string;
|
|
40
|
+
description: string | null;
|
|
41
|
+
planning: string;
|
|
42
|
+
/** The export path as the options wrote it, `/`-separated: shown on pages instead of the machine path. */
|
|
43
|
+
planningLabel: string;
|
|
44
|
+
docs: { root: string; sources: DocsSource[] } | null;
|
|
45
|
+
views: Record<ViewName, boolean>;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The pm-docs-site integration: the plan pages, Starlight, and the docs collection. */
|
|
49
|
+
export default function pmDocsSite(options: PmDocsSiteOptions): AstroIntegration & { pmDocsSiteOptions: PmDocsSiteOptions };
|
package/index.mjs
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
// The pm-docs-site Astro integration. The consumer's astro.config.mjs holds
|
|
3
|
+
// only `integrations: [pmDocsSite({ title, ... })]`: this points Astro's srcDir
|
|
4
|
+
// at the package's own src/ (pages, components, content config), adds
|
|
5
|
+
// Starlight with the plan sidebar, and serves the resolved options to the pages
|
|
6
|
+
// as `virtual:pm-docs-site/config`.
|
|
7
|
+
|
|
8
|
+
import { fileURLToPath } from 'node:url';
|
|
9
|
+
|
|
10
|
+
import starlight from '@astrojs/starlight';
|
|
11
|
+
|
|
12
|
+
import { resolveOptions } from './lib/options.mjs';
|
|
13
|
+
import { buildSidebar } from './lib/sidebar.mjs';
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* The pages each optional view owns, in src/routes/ so Astro routes them only
|
|
17
|
+
* when the view is on. Home, Board, Roadmap, Log and Risks are in src/pages/.
|
|
18
|
+
* @type {Record<import('./index').ViewName, [pattern: string, file: string][]>}
|
|
19
|
+
*/
|
|
20
|
+
const VIEW_ROUTES = {
|
|
21
|
+
now: [['/plan/now', 'plan/now.astro']],
|
|
22
|
+
milestones: [
|
|
23
|
+
['/plan/milestones', 'plan/milestones/index.astro'],
|
|
24
|
+
['/plan/milestones/[milestone]', 'plan/milestones/[milestone].astro'],
|
|
25
|
+
],
|
|
26
|
+
features: [
|
|
27
|
+
['/plan/features', 'plan/features/index.astro'],
|
|
28
|
+
['/plan/features/[id]', 'plan/features/[id].astro'],
|
|
29
|
+
],
|
|
30
|
+
inbox: [['/plan/inbox', 'plan/inbox.astro']],
|
|
31
|
+
briefs: [['/plan/briefs', 'plan/briefs.astro']],
|
|
32
|
+
strategy: [['/plan/strategy', 'plan/strategy.astro']],
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
const NO_EXTERNAL = ['@astrojs/starlight', '@purview-dev/pm-docs-site'];
|
|
36
|
+
const SERVER_ENVIRONMENTS = ['ssr', 'astro', 'prerender'];
|
|
37
|
+
|
|
38
|
+
const VIRTUAL_ID = 'virtual:pm-docs-site/config';
|
|
39
|
+
const RESOLVED_ID = `\0${VIRTUAL_ID}`;
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* @param {import('./index').PmDocsSiteOptions} options
|
|
43
|
+
* @returns {import('astro').AstroIntegration & { pmDocsSiteOptions: import('./index').PmDocsSiteOptions }}
|
|
44
|
+
*/
|
|
45
|
+
export default function pmDocsSite(options) {
|
|
46
|
+
return {
|
|
47
|
+
name: 'pm-docs-site',
|
|
48
|
+
pmDocsSiteOptions: options,
|
|
49
|
+
hooks: {
|
|
50
|
+
'astro:config:setup': ({ config, updateConfig, injectRoute }) => {
|
|
51
|
+
const resolved = resolveOptions(options, fileURLToPath(config.root));
|
|
52
|
+
|
|
53
|
+
for (const [view, routes] of Object.entries(VIEW_ROUTES)) {
|
|
54
|
+
if (!resolved.views[/** @type {import('./index').ViewName} */ (view)]) continue;
|
|
55
|
+
|
|
56
|
+
for (const [pattern, file] of routes) {
|
|
57
|
+
injectRoute({ pattern, entrypoint: new URL(`./src/routes/${file}`, import.meta.url) });
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
updateConfig({
|
|
62
|
+
srcDir: new URL('./src/', import.meta.url),
|
|
63
|
+
integrations: [
|
|
64
|
+
starlight({
|
|
65
|
+
title: resolved.title,
|
|
66
|
+
...(resolved.description ? { description: resolved.description } : {}),
|
|
67
|
+
sidebar: buildSidebar(resolved),
|
|
68
|
+
// Every page uses the full width (src/styles/width.css).
|
|
69
|
+
customCss: [fileURLToPath(new URL('./src/styles/width.css', import.meta.url))],
|
|
70
|
+
}),
|
|
71
|
+
],
|
|
72
|
+
vite: {
|
|
73
|
+
plugins: [
|
|
74
|
+
{
|
|
75
|
+
name: 'pm-docs-site:config',
|
|
76
|
+
/** @param {string} id */
|
|
77
|
+
resolveId: (id) => (id === VIRTUAL_ID ? RESOLVED_ID : undefined),
|
|
78
|
+
/** @param {string} id */
|
|
79
|
+
load: (id) => (id === RESOLVED_ID ? `export default ${JSON.stringify(resolved)};` : undefined),
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
// Bundle Starlight and this package in every server environment, whatever
|
|
83
|
+
// the consumer's package.json lists: externalised, Starlight cannot import
|
|
84
|
+
// astro:middleware. Astro 7 renders static pages in its own `prerender`
|
|
85
|
+
// environment, which top-level `vite.ssr` does not reach.
|
|
86
|
+
name: 'pm-docs-site:no-external',
|
|
87
|
+
/** @param {string} name */
|
|
88
|
+
configEnvironment: (name) =>
|
|
89
|
+
SERVER_ENVIRONMENTS.includes(name) ? { resolve: { noExternal: [...NO_EXTERNAL] } } : undefined,
|
|
90
|
+
},
|
|
91
|
+
],
|
|
92
|
+
},
|
|
93
|
+
});
|
|
94
|
+
},
|
|
95
|
+
},
|
|
96
|
+
};
|
|
97
|
+
}
|
package/lib/options.mjs
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
// The integration's options: defaults, validation, and paths made absolute from
|
|
3
|
+
// the site root, so the pages and the content config never resolve a path again.
|
|
4
|
+
|
|
5
|
+
import { resolve } from 'node:path';
|
|
6
|
+
|
|
7
|
+
/** @typedef {import('../index').PmDocsSiteOptions} PmDocsSiteOptions */
|
|
8
|
+
/** @typedef {import('../index').ResolvedOptions} ResolvedOptions */
|
|
9
|
+
/** @typedef {import('../index').ViewName} ViewName */
|
|
10
|
+
|
|
11
|
+
/** The optional plan views. Home, Board, Roadmap, Log and Risks are always on. */
|
|
12
|
+
export const VIEW_NAMES = /** @type {const} */ (['now', 'milestones', 'features', 'inbox', 'briefs', 'strategy']);
|
|
13
|
+
|
|
14
|
+
/** Where the export lives by default, relative to the site root. */
|
|
15
|
+
const DEFAULT_PLANNING = '../planning/planning.json';
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Throw a pm-docs-site message for a malformed `docs` option, which a plain
|
|
19
|
+
* astro.config.mjs does not type-check.
|
|
20
|
+
* @param {unknown} docs
|
|
21
|
+
*/
|
|
22
|
+
function checkDocs(docs) {
|
|
23
|
+
const value = /** @type {{ root?: unknown; sources?: unknown }} */ (docs ?? {});
|
|
24
|
+
|
|
25
|
+
if (typeof value.root !== 'string') throw new Error('pm-docs-site: docs.root must be a path');
|
|
26
|
+
if (!Array.isArray(value.sources)) throw new Error('pm-docs-site: docs.sources must be a list of sources');
|
|
27
|
+
|
|
28
|
+
for (const source of value.sources) {
|
|
29
|
+
if (typeof source?.base !== 'string' || !Array.isArray(source?.include)) {
|
|
30
|
+
throw new Error(`pm-docs-site: docs source "${String(source?.label)}" needs base and include`);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* @param {PmDocsSiteOptions} options
|
|
37
|
+
* @param {string} root the site root, absolute
|
|
38
|
+
* @returns {ResolvedOptions}
|
|
39
|
+
*/
|
|
40
|
+
export function resolveOptions(options, root) {
|
|
41
|
+
if (!options || typeof options.title !== 'string' || options.title === '') {
|
|
42
|
+
throw new Error('pm-docs-site: title is required');
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const listed = options.views ?? VIEW_NAMES;
|
|
46
|
+
|
|
47
|
+
for (const name of listed) {
|
|
48
|
+
if (!VIEW_NAMES.includes(name)) {
|
|
49
|
+
throw new Error(`pm-docs-site: unknown view "${name}"; expected one of ${VIEW_NAMES.join(', ')}`);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
if (options.docs !== undefined) checkDocs(options.docs);
|
|
54
|
+
|
|
55
|
+
const views = /** @type {Record<ViewName, boolean>} */ (
|
|
56
|
+
Object.fromEntries(VIEW_NAMES.map((name) => [name, listed.includes(name)]))
|
|
57
|
+
);
|
|
58
|
+
|
|
59
|
+
return {
|
|
60
|
+
title: options.title,
|
|
61
|
+
description: options.description ?? null,
|
|
62
|
+
planning: resolve(root, options.planning ?? DEFAULT_PLANNING),
|
|
63
|
+
planningLabel: (options.planning ?? DEFAULT_PLANNING).replace(/\\/g, '/'),
|
|
64
|
+
docs: options.docs ? { root: resolve(root, options.docs.root), sources: options.docs.sources } : null,
|
|
65
|
+
views,
|
|
66
|
+
};
|
|
67
|
+
}
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
// Repository Markdown as pages: which files a docs source matches, their page
|
|
3
|
+
// IDs, and each page's title and body. Plain JavaScript because the sidebar is
|
|
4
|
+
// built from it while astro.config.mjs loads; the Astro loader in
|
|
5
|
+
// src/loaders/repo-docs.ts uses the same functions.
|
|
6
|
+
//
|
|
7
|
+
// Starlight requires a `title` in every page's frontmatter; repository Markdown
|
|
8
|
+
// rarely has one. The title is frontmatter `title`, else the first `# Title`
|
|
9
|
+
// heading (dropped from the body, so it is not shown twice), else frontmatter
|
|
10
|
+
// `name`, else the file name, so the files stay exactly as their authors write them.
|
|
11
|
+
|
|
12
|
+
import { existsSync, readdirSync } from 'node:fs';
|
|
13
|
+
import { basename, dirname, join, resolve, sep } from 'node:path';
|
|
14
|
+
|
|
15
|
+
/** @typedef {import('../index').DocsSource} DocsSource */
|
|
16
|
+
/** @typedef {{ id: string; file: string }} DocsPage */
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* A glob as a regular expression over `/`-separated paths.
|
|
20
|
+
* @param {string} glob
|
|
21
|
+
* @returns {RegExp}
|
|
22
|
+
*/
|
|
23
|
+
export function globToRegExp(glob) {
|
|
24
|
+
const pattern = glob
|
|
25
|
+
.split(/(\*\*\/|\*\*|\*)/)
|
|
26
|
+
.map((part) =>
|
|
27
|
+
part === '**/' ? '(?:.*/)?' : part === '**' ? '.*' : part === '*' ? '[^/]*' : part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'),
|
|
28
|
+
)
|
|
29
|
+
.join('');
|
|
30
|
+
|
|
31
|
+
return new RegExp(`^${pattern}$`, 'i');
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* The page ID (and URL path) for a file: prefix, path without `.md`, lower case.
|
|
36
|
+
* @param {DocsSource} source
|
|
37
|
+
* @param {string} path
|
|
38
|
+
* @returns {string}
|
|
39
|
+
*/
|
|
40
|
+
export function pageId(source, path) {
|
|
41
|
+
let page = path.replace(/\.md$/i, '');
|
|
42
|
+
|
|
43
|
+
if (source.indexFile && basename(path).toLowerCase() === source.indexFile.toLowerCase()) {
|
|
44
|
+
page = dirname(path) === '.' ? 'index' : dirname(path);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
return `${source.prefix ?? ''}${page}`.toLowerCase();
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Every file a source matches, as page IDs in its sidebar order.
|
|
52
|
+
* @param {DocsSource} source
|
|
53
|
+
* @param {string} repoRoot
|
|
54
|
+
* @returns {DocsPage[]}
|
|
55
|
+
*/
|
|
56
|
+
export function pagesOf(source, repoRoot) {
|
|
57
|
+
const base = resolve(repoRoot, source.base);
|
|
58
|
+
|
|
59
|
+
if (!existsSync(base)) return [];
|
|
60
|
+
|
|
61
|
+
const patterns = source.include.map(globToRegExp);
|
|
62
|
+
const pages = /** @type {string[]} */ (readdirSync(base, { recursive: true }))
|
|
63
|
+
.map((file) => file.split(sep).join('/'))
|
|
64
|
+
.filter((file) => !file.split('/').includes('node_modules') && patterns.some((pattern) => pattern.test(file)))
|
|
65
|
+
.map((file) => ({ id: pageId(source, file), file: join(base, file) }))
|
|
66
|
+
.sort((a, b) => a.id.localeCompare(b.id));
|
|
67
|
+
|
|
68
|
+
return source.order === 'desc' ? pages.reverse() : pages;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Simple `key: value` frontmatter (one line per key) and the body after it.
|
|
73
|
+
* @param {string} markdown
|
|
74
|
+
* @returns {{ data: Record<string, string>; body: string }}
|
|
75
|
+
*/
|
|
76
|
+
export function splitFrontmatter(markdown) {
|
|
77
|
+
const match = /^---\n([\s\S]*?)\n---\n?/.exec(markdown);
|
|
78
|
+
|
|
79
|
+
if (!match) return { data: {}, body: markdown };
|
|
80
|
+
|
|
81
|
+
/** @type {Record<string, string>} */
|
|
82
|
+
const data = {};
|
|
83
|
+
|
|
84
|
+
for (const line of (match[1] ?? '').split('\n')) {
|
|
85
|
+
const pair = /^([\w-]+):\s*(.*?)\s*$/.exec(line);
|
|
86
|
+
|
|
87
|
+
if (pair && pair[1] && pair[2]) data[pair[1]] = pair[2].replace(/^(['"])(.*)\1$/, '$2');
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
return { data, body: markdown.slice(match[0].length) };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The page title and the body without it.
|
|
95
|
+
*
|
|
96
|
+
* The title is the first `# ` heading when nothing but blank lines and HTML
|
|
97
|
+
* comments come before it; otherwise the fallback is the title and the body is
|
|
98
|
+
* kept whole.
|
|
99
|
+
* @param {string} markdown
|
|
100
|
+
* @param {string} fallback
|
|
101
|
+
* @returns {{ title: string; body: string }}
|
|
102
|
+
*/
|
|
103
|
+
export function splitTitle(markdown, fallback) {
|
|
104
|
+
const lines = markdown.split('\n');
|
|
105
|
+
let index = 0;
|
|
106
|
+
let inComment = false;
|
|
107
|
+
|
|
108
|
+
for (; index < lines.length; index++) {
|
|
109
|
+
const line = (lines[index] ?? '').trim();
|
|
110
|
+
|
|
111
|
+
if (inComment) {
|
|
112
|
+
if (line.includes('-->')) inComment = false;
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
if (line === '') continue;
|
|
117
|
+
|
|
118
|
+
if (line.startsWith('<!--')) {
|
|
119
|
+
inComment = !line.includes('-->');
|
|
120
|
+
continue;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
break;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
const heading = /^#\s+(.+?)\s*#*\s*$/.exec(lines[index] ?? '');
|
|
127
|
+
|
|
128
|
+
if (!heading || !heading[1]) return { title: fallback, body: markdown };
|
|
129
|
+
|
|
130
|
+
let start = index + 1;
|
|
131
|
+
while (start < lines.length && (lines[start] ?? '').trim() === '') start++;
|
|
132
|
+
|
|
133
|
+
return { title: heading[1], body: lines.slice(start).join('\n') };
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Title, description, and body for one page.
|
|
138
|
+
* @param {string} markdown
|
|
139
|
+
* @param {string} file
|
|
140
|
+
* @returns {{ title: string; description?: string; body: string }}
|
|
141
|
+
*/
|
|
142
|
+
export function readPage(markdown, file) {
|
|
143
|
+
const { data, body } = splitFrontmatter(markdown);
|
|
144
|
+
const fallback = data.name ?? basename(file, '.md');
|
|
145
|
+
const split = data.title ? { title: data.title, body } : splitTitle(body, fallback);
|
|
146
|
+
|
|
147
|
+
return { title: split.title, ...(data.description ? { description: data.description } : {}), body: split.body };
|
|
148
|
+
}
|