@purview-dev/pm-docs-site 0.1.0-pre.1 → 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 +130 -18
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +91 -0
- 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.d.ts +7 -0
- package/dist/index.js +152 -0
- package/dist/options.d.ts +5 -0
- package/dist/options.js +46 -0
- package/dist/repo-docs.d.ts +33 -0
- package/dist/repo-docs.js +94 -0
- package/dist/schema-version.d.ts +27 -0
- package/dist/schema-version.js +48 -0
- package/dist/sidebar.d.ts +10 -0
- package/dist/sidebar.js +32 -0
- package/dist/site-options.d.ts +9 -0
- package/dist/site-options.js +44 -0
- package/dist/types.d.ts +47 -0
- package/dist/types.js +4 -0
- package/lib/{repo-docs.mjs → repo-docs.ts} +22 -46
- package/lib/schema-version.ts +59 -0
- package/{index.d.ts → lib/types.ts} +5 -6
- package/package.json +19 -9
- 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/PlanInteractions.astro +15 -3
- package/src/components/RefLink.astro +7 -4
- package/src/components/board/Board.tsx +252 -0
- package/src/components/board/KanbanItemCard.tsx +131 -0
- package/src/components/board/LinkRuns.tsx +21 -0
- package/src/components/board/TaskKanbanCard.tsx +83 -0
- package/src/components/board/useBoardUrlState.ts +41 -0
- 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 +192 -0
- package/src/components/timeline/useTimelineLayout.ts +39 -0
- package/src/content.config.ts +22 -6
- package/src/env.d.ts +2 -2
- package/src/lib/board-data.ts +84 -0
- package/src/lib/board.ts +209 -0
- 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 +94 -52
- package/src/lib/ref-boundary.ts +19 -0
- package/src/lib/references.ts +67 -8
- package/src/lib/timeline-state.ts +119 -0
- package/src/lib/timeline.ts +51 -0
- package/src/loaders/adrs.ts +43 -0
- package/src/loaders/repo-docs.ts +3 -3
- package/src/pages/404.astro +18 -0
- package/src/pages/index.astro +1 -1
- package/src/pages/plan/board.astro +14 -113
- package/src/pages/plan/log.astro +18 -1
- package/src/pages/plan/roadmap.astro +21 -3
- 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 +32 -46
- package/src/styles/components.css +244 -13
- package/src/styles/graph.css +296 -0
- package/src/styles/kanban.css +277 -0
- package/src/styles/timeline.css +210 -0
- package/cli.mjs +0 -120
- package/index.mjs +0 -97
- package/lib/options.mjs +0 -67
- package/lib/schema-version.mjs +0 -29
- package/lib/sidebar.mjs +0 -47
- package/lib/site-options.mjs +0 -38
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
// Repository Markdown as pages: which files a docs source matches, their page
|
|
2
|
+
// IDs, and each page's title and body. Node-loadable (no Astro or Vite import)
|
|
3
|
+
// because the sidebar is built from it while astro.config loads; the Astro
|
|
4
|
+
// loader in src/loaders/repo-docs.ts uses the same functions.
|
|
5
|
+
//
|
|
6
|
+
// Starlight requires a `title` in every page's frontmatter; repository Markdown
|
|
7
|
+
// rarely has one. The title is frontmatter `title`, else the first `# Title`
|
|
8
|
+
// heading (dropped from the body, so it is not shown twice), else frontmatter
|
|
9
|
+
// `name`, else the file name, so the files stay exactly as their authors write them.
|
|
10
|
+
import { existsSync, readdirSync } from 'node:fs';
|
|
11
|
+
import { basename, dirname, join, resolve, sep } from 'node:path';
|
|
12
|
+
/** A glob as a regular expression over `/`-separated paths. */
|
|
13
|
+
export function globToRegExp(glob) {
|
|
14
|
+
const pattern = glob
|
|
15
|
+
.split(/(\*\*\/|\*\*|\*)/)
|
|
16
|
+
.map((part) => part === '**/' ? '(?:.*/)?' : part === '**' ? '.*' : part === '*' ? '[^/]*' : part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
|
|
17
|
+
.join('');
|
|
18
|
+
return new RegExp(`^${pattern}$`, 'i');
|
|
19
|
+
}
|
|
20
|
+
/** The page ID (and URL path) for a file: prefix, path without `.md`, lower case. */
|
|
21
|
+
export function pageId(source, path) {
|
|
22
|
+
let page = path.replace(/\.md$/i, '');
|
|
23
|
+
if (source.indexFile && basename(path).toLowerCase() === source.indexFile.toLowerCase()) {
|
|
24
|
+
page = dirname(path) === '.' ? 'index' : dirname(path);
|
|
25
|
+
}
|
|
26
|
+
return `${source.prefix ?? ''}${page}`.toLowerCase();
|
|
27
|
+
}
|
|
28
|
+
/** Every file a source matches, as page IDs in its sidebar order. */
|
|
29
|
+
export function pagesOf(source, repoRoot) {
|
|
30
|
+
const base = resolve(repoRoot, source.base);
|
|
31
|
+
if (!existsSync(base))
|
|
32
|
+
return [];
|
|
33
|
+
const patterns = source.include.map(globToRegExp);
|
|
34
|
+
const pages = readdirSync(base, { recursive: true })
|
|
35
|
+
.map((file) => file.split(sep).join('/'))
|
|
36
|
+
.filter((file) => !file.split('/').includes('node_modules') && patterns.some((pattern) => pattern.test(file)))
|
|
37
|
+
.map((file) => ({ id: pageId(source, file), file: join(base, file) }))
|
|
38
|
+
.sort((a, b) => a.id.localeCompare(b.id));
|
|
39
|
+
return source.order === 'desc' ? pages.reverse() : pages;
|
|
40
|
+
}
|
|
41
|
+
/** Simple `key: value` frontmatter (one line per key) and the body after it. */
|
|
42
|
+
export function splitFrontmatter(markdown) {
|
|
43
|
+
const match = /^---\n([\s\S]*?)\n---\n?/.exec(markdown);
|
|
44
|
+
if (!match)
|
|
45
|
+
return { data: {}, body: markdown };
|
|
46
|
+
const data = {};
|
|
47
|
+
for (const line of (match[1] ?? '').split('\n')) {
|
|
48
|
+
const pair = /^([\w-]+):\s*(.*?)\s*$/.exec(line);
|
|
49
|
+
if (pair && pair[1] && pair[2])
|
|
50
|
+
data[pair[1]] = pair[2].replace(/^(['"])(.*)\1$/, '$2');
|
|
51
|
+
}
|
|
52
|
+
return { data, body: markdown.slice(match[0].length) };
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* The page title and the body without it.
|
|
56
|
+
*
|
|
57
|
+
* The title is the first `# ` heading when nothing but blank lines and HTML
|
|
58
|
+
* comments come before it; otherwise the fallback is the title and the body is
|
|
59
|
+
* kept whole.
|
|
60
|
+
*/
|
|
61
|
+
export function splitTitle(markdown, fallback) {
|
|
62
|
+
const lines = markdown.split('\n');
|
|
63
|
+
let index = 0;
|
|
64
|
+
let inComment = false;
|
|
65
|
+
for (; index < lines.length; index++) {
|
|
66
|
+
const line = (lines[index] ?? '').trim();
|
|
67
|
+
if (inComment) {
|
|
68
|
+
if (line.includes('-->'))
|
|
69
|
+
inComment = false;
|
|
70
|
+
continue;
|
|
71
|
+
}
|
|
72
|
+
if (line === '')
|
|
73
|
+
continue;
|
|
74
|
+
if (line.startsWith('<!--')) {
|
|
75
|
+
inComment = !line.includes('-->');
|
|
76
|
+
continue;
|
|
77
|
+
}
|
|
78
|
+
break;
|
|
79
|
+
}
|
|
80
|
+
const heading = /^#\s+(.+?)\s*#*\s*$/.exec(lines[index] ?? '');
|
|
81
|
+
if (!heading || !heading[1])
|
|
82
|
+
return { title: fallback, body: markdown };
|
|
83
|
+
let start = index + 1;
|
|
84
|
+
while (start < lines.length && (lines[start] ?? '').trim() === '')
|
|
85
|
+
start++;
|
|
86
|
+
return { title: heading[1], body: lines.slice(start).join('\n') };
|
|
87
|
+
}
|
|
88
|
+
/** Title, description, and body for one page. */
|
|
89
|
+
export function readPage(markdown, file) {
|
|
90
|
+
const { data, body } = splitFrontmatter(markdown);
|
|
91
|
+
const fallback = data.name ?? basename(file, '.md');
|
|
92
|
+
const split = data.title ? { title: data.title, body } : splitTitle(body, fallback);
|
|
93
|
+
return { title: split.title, ...(data.description ? { description: data.description } : {}), body: split.body };
|
|
94
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
export declare const SUPPORTED_SCHEMA_VERSIONS: readonly number[];
|
|
2
|
+
/** The plan export is missing, unreadable, or in a format this package does not read. */
|
|
3
|
+
export declare class PlanningExportError extends Error {
|
|
4
|
+
constructor(message: string);
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Throw unless the export's schemaVersion is one this package reads.
|
|
8
|
+
* @param path the export's path, for the message
|
|
9
|
+
*/
|
|
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
|
+
};
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// The pm-export schemaVersions this package reads, declared once. A new export
|
|
2
|
+
// format is supported by adding its version here, with the page changes it needs.
|
|
3
|
+
export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([5]);
|
|
4
|
+
/** The plan export is missing, unreadable, or in a format this package does not read. */
|
|
5
|
+
export class PlanningExportError extends Error {
|
|
6
|
+
constructor(message) {
|
|
7
|
+
super(`${message} Run the pm-export skill to write planning.json.`);
|
|
8
|
+
this.name = 'PlanningExportError';
|
|
9
|
+
}
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Throw unless the export's schemaVersion is one this package reads.
|
|
13
|
+
* @param path the export's path, for the message
|
|
14
|
+
*/
|
|
15
|
+
export function checkSchemaVersion(version, path) {
|
|
16
|
+
if (typeof version === 'number' && SUPPORTED_SCHEMA_VERSIONS.includes(version))
|
|
17
|
+
return;
|
|
18
|
+
throw new PlanningExportError(`${path} has schemaVersion ${String(version)}; this site reads schemaVersion ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}.`);
|
|
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
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { ResolvedOptions } from './types.js';
|
|
2
|
+
export type SidebarItem = string | {
|
|
3
|
+
label: string;
|
|
4
|
+
link: string;
|
|
5
|
+
} | {
|
|
6
|
+
label: string;
|
|
7
|
+
items: SidebarItem[];
|
|
8
|
+
collapsed?: boolean;
|
|
9
|
+
};
|
|
10
|
+
export declare function buildSidebar(options: ResolvedOptions): SidebarItem[];
|
package/dist/sidebar.js
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
// The Starlight sidebar: the plan, its optional views switched on in the
|
|
2
|
+
// options, then one group per docs source that has pages.
|
|
3
|
+
import { pagesOf } from "./repo-docs.js";
|
|
4
|
+
export function buildSidebar(options) {
|
|
5
|
+
const { views, docs } = options;
|
|
6
|
+
const plan = [
|
|
7
|
+
views.now && { label: 'Now', link: '/plan/now/' },
|
|
8
|
+
{ label: 'Board', link: '/plan/board/' },
|
|
9
|
+
{ label: 'Roadmap', link: '/plan/roadmap/' },
|
|
10
|
+
views.graph && { label: 'Graph', link: '/plan/graph/' },
|
|
11
|
+
views.milestones && { label: 'Milestones', link: '/plan/milestones/' },
|
|
12
|
+
views.features && { label: 'Features', link: '/plan/features/' },
|
|
13
|
+
{ label: 'Log', link: '/plan/log/' },
|
|
14
|
+
{ label: 'Risks', link: '/plan/risks/' },
|
|
15
|
+
views.decisions && { label: 'Decisions', link: '/plan/decisions/' },
|
|
16
|
+
views.inbox && { label: 'Inbox', link: '/plan/inbox/' },
|
|
17
|
+
views.briefs && { label: 'Briefs', link: '/plan/briefs/' },
|
|
18
|
+
views.strategy && { label: 'Strategy', link: '/plan/strategy/' },
|
|
19
|
+
];
|
|
20
|
+
const groups = docs
|
|
21
|
+
? docs.sources
|
|
22
|
+
.filter((source) => !source.hidden)
|
|
23
|
+
.map((source) => ({
|
|
24
|
+
label: source.label,
|
|
25
|
+
collapsed: source.collapsed ?? false,
|
|
26
|
+
items: pagesOf(source, docs.root).map((page) => page.id),
|
|
27
|
+
}))
|
|
28
|
+
// Starlight rejects an empty group.
|
|
29
|
+
.filter((group) => group.items.length > 0)
|
|
30
|
+
: [];
|
|
31
|
+
return [{ label: 'Plan', items: plan.filter((item) => item !== false) }, ...groups];
|
|
32
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { PmDocsSiteOptions } from './types.js';
|
|
2
|
+
/** @param siteDir absolute */
|
|
3
|
+
export declare function loadSiteOptions(siteDir: string, flags: {
|
|
4
|
+
title?: string;
|
|
5
|
+
planning?: string;
|
|
6
|
+
}): Promise<{
|
|
7
|
+
options: PmDocsSiteOptions;
|
|
8
|
+
configFile: string | null;
|
|
9
|
+
}>;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
// The options a site gives the integration, read the way the CLI needs them:
|
|
2
|
+
// from its astro.config file when it has one, else from command-line flags.
|
|
3
|
+
var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
|
|
4
|
+
if (typeof path === "string" && /^\.\.?\//.test(path)) {
|
|
5
|
+
return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
|
|
6
|
+
return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
|
|
7
|
+
});
|
|
8
|
+
}
|
|
9
|
+
return path;
|
|
10
|
+
};
|
|
11
|
+
import { existsSync } from 'node:fs';
|
|
12
|
+
import { join } from 'node:path';
|
|
13
|
+
import { pathToFileURL } from 'node:url';
|
|
14
|
+
const CONFIG_FILES = ['astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.mts'];
|
|
15
|
+
/** @param siteDir absolute */
|
|
16
|
+
export async function loadSiteOptions(siteDir, flags) {
|
|
17
|
+
const configFile = CONFIG_FILES.map((name) => join(siteDir, name)).find((file) => existsSync(file)) ?? null;
|
|
18
|
+
if (!configFile) {
|
|
19
|
+
return {
|
|
20
|
+
options: { title: flags.title ?? 'Project plan', ...(flags.planning ? { planning: flags.planning } : {}) },
|
|
21
|
+
configFile: null,
|
|
22
|
+
};
|
|
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
|
+
}
|
|
29
|
+
// Plain Node loads the config, so a TypeScript config may only use what Node
|
|
30
|
+
// strips: erasable syntax and relative imports that name their file.
|
|
31
|
+
let config;
|
|
32
|
+
try {
|
|
33
|
+
config = (await import(__rewriteRelativeImportExtension(pathToFileURL(configFile).href))).default ?? {};
|
|
34
|
+
}
|
|
35
|
+
catch (error) {
|
|
36
|
+
throw new Error(`pm-docs-site: could not load ${configFile} under Node (${error.message.trim()}). ` +
|
|
37
|
+
'Keep astro.config.ts to erasable TypeScript, with explicit .ts extensions on relative imports.');
|
|
38
|
+
}
|
|
39
|
+
const integrations = (Array.isArray(config.integrations) ? config.integrations : []).flat(Infinity);
|
|
40
|
+
const ours = integrations.find((entry) => entry?.name === 'pm-docs-site');
|
|
41
|
+
if (!ours?.pmDocsSiteOptions)
|
|
42
|
+
throw new Error(`pm-docs-site: no pm-docs-site integration in ${configFile}`);
|
|
43
|
+
return { options: ours.pmDocsSiteOptions, configFile };
|
|
44
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/** An optional plan view. Home, Board, Roadmap, Log and Risks are always on. */
|
|
2
|
+
export type ViewName = 'now' | 'milestones' | 'graph' | 'features' | 'inbox' | 'briefs' | 'strategy' | 'decisions';
|
|
3
|
+
/** One folder of repository Markdown, shown as one sidebar group. */
|
|
4
|
+
export interface DocsSource {
|
|
5
|
+
/** The sidebar group for this source's pages. */
|
|
6
|
+
label: string;
|
|
7
|
+
/** The folder to read, relative to the docs root (`.` for the root). */
|
|
8
|
+
base: string;
|
|
9
|
+
/** Files to read, as globs relative to `base` (`*` within a folder, `**` across folders). */
|
|
10
|
+
include: string[];
|
|
11
|
+
/** Prepended to each page's path to make its URL. Default: none. */
|
|
12
|
+
prefix?: string;
|
|
13
|
+
/** A file name that stands for its folder, such as `SKILL.md` or `README.md`. */
|
|
14
|
+
indexFile?: string;
|
|
15
|
+
/** Sidebar order by page path. Default: `asc`. */
|
|
16
|
+
order?: 'asc' | 'desc';
|
|
17
|
+
collapsed?: boolean;
|
|
18
|
+
/** Load the pages without listing them in the sidebar. */
|
|
19
|
+
hidden?: boolean;
|
|
20
|
+
}
|
|
21
|
+
export interface PmDocsSiteOptions {
|
|
22
|
+
/** The site title. */
|
|
23
|
+
title: string;
|
|
24
|
+
description?: string;
|
|
25
|
+
/** The pm-export file, relative to the site root. Default: `../planning/planning.json`. */
|
|
26
|
+
planning?: string;
|
|
27
|
+
/** Repository Markdown to render as pages; `root` is relative to the site root. Default: none. */
|
|
28
|
+
docs?: {
|
|
29
|
+
root: string;
|
|
30
|
+
sources: DocsSource[];
|
|
31
|
+
};
|
|
32
|
+
/** The optional views to render. Default: all seven. */
|
|
33
|
+
views?: ViewName[];
|
|
34
|
+
}
|
|
35
|
+
/** The options with defaults applied and every path absolute. */
|
|
36
|
+
export interface ResolvedOptions {
|
|
37
|
+
title: string;
|
|
38
|
+
description: string | null;
|
|
39
|
+
planning: string;
|
|
40
|
+
/** The export path as the options wrote it, `/`-separated: shown on pages instead of the machine path. */
|
|
41
|
+
planningLabel: string;
|
|
42
|
+
docs: {
|
|
43
|
+
root: string;
|
|
44
|
+
sources: DocsSource[];
|
|
45
|
+
} | null;
|
|
46
|
+
views: Record<ViewName, boolean>;
|
|
47
|
+
}
|
package/dist/types.js
ADDED
|
@@ -1,8 +1,7 @@
|
|
|
1
|
-
// @ts-check
|
|
2
1
|
// Repository Markdown as pages: which files a docs source matches, their page
|
|
3
|
-
// IDs, and each page's title and body.
|
|
4
|
-
// built from it while astro.config
|
|
5
|
-
// src/loaders/repo-docs.ts uses the same functions.
|
|
2
|
+
// IDs, and each page's title and body. Node-loadable (no Astro or Vite import)
|
|
3
|
+
// because the sidebar is built from it while astro.config loads; the Astro
|
|
4
|
+
// loader in src/loaders/repo-docs.ts uses the same functions.
|
|
6
5
|
//
|
|
7
6
|
// Starlight requires a `title` in every page's frontmatter; repository Markdown
|
|
8
7
|
// rarely has one. The title is frontmatter `title`, else the first `# Title`
|
|
@@ -12,15 +11,15 @@
|
|
|
12
11
|
import { existsSync, readdirSync } from 'node:fs';
|
|
13
12
|
import { basename, dirname, join, resolve, sep } from 'node:path';
|
|
14
13
|
|
|
15
|
-
|
|
16
|
-
/** @typedef {{ id: string; file: string }} DocsPage */
|
|
14
|
+
import type { DocsSource } from './types.ts';
|
|
17
15
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
16
|
+
export interface DocsPage {
|
|
17
|
+
id: string;
|
|
18
|
+
file: string;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** A glob as a regular expression over `/`-separated paths. */
|
|
22
|
+
export function globToRegExp(glob: string): RegExp {
|
|
24
23
|
const pattern = glob
|
|
25
24
|
.split(/(\*\*\/|\*\*|\*)/)
|
|
26
25
|
.map((part) =>
|
|
@@ -31,13 +30,8 @@ export function globToRegExp(glob) {
|
|
|
31
30
|
return new RegExp(`^${pattern}$`, 'i');
|
|
32
31
|
}
|
|
33
32
|
|
|
34
|
-
/**
|
|
35
|
-
|
|
36
|
-
* @param {DocsSource} source
|
|
37
|
-
* @param {string} path
|
|
38
|
-
* @returns {string}
|
|
39
|
-
*/
|
|
40
|
-
export function pageId(source, path) {
|
|
33
|
+
/** The page ID (and URL path) for a file: prefix, path without `.md`, lower case. */
|
|
34
|
+
export function pageId(source: DocsSource, path: string): string {
|
|
41
35
|
let page = path.replace(/\.md$/i, '');
|
|
42
36
|
|
|
43
37
|
if (source.indexFile && basename(path).toLowerCase() === source.indexFile.toLowerCase()) {
|
|
@@ -47,19 +41,14 @@ export function pageId(source, path) {
|
|
|
47
41
|
return `${source.prefix ?? ''}${page}`.toLowerCase();
|
|
48
42
|
}
|
|
49
43
|
|
|
50
|
-
/**
|
|
51
|
-
|
|
52
|
-
* @param {DocsSource} source
|
|
53
|
-
* @param {string} repoRoot
|
|
54
|
-
* @returns {DocsPage[]}
|
|
55
|
-
*/
|
|
56
|
-
export function pagesOf(source, repoRoot) {
|
|
44
|
+
/** Every file a source matches, as page IDs in its sidebar order. */
|
|
45
|
+
export function pagesOf(source: DocsSource, repoRoot: string): DocsPage[] {
|
|
57
46
|
const base = resolve(repoRoot, source.base);
|
|
58
47
|
|
|
59
48
|
if (!existsSync(base)) return [];
|
|
60
49
|
|
|
61
50
|
const patterns = source.include.map(globToRegExp);
|
|
62
|
-
const pages =
|
|
51
|
+
const pages = (readdirSync(base, { recursive: true }) as string[])
|
|
63
52
|
.map((file) => file.split(sep).join('/'))
|
|
64
53
|
.filter((file) => !file.split('/').includes('node_modules') && patterns.some((pattern) => pattern.test(file)))
|
|
65
54
|
.map((file) => ({ id: pageId(source, file), file: join(base, file) }))
|
|
@@ -68,18 +57,13 @@ export function pagesOf(source, repoRoot) {
|
|
|
68
57
|
return source.order === 'desc' ? pages.reverse() : pages;
|
|
69
58
|
}
|
|
70
59
|
|
|
71
|
-
/**
|
|
72
|
-
|
|
73
|
-
* @param {string} markdown
|
|
74
|
-
* @returns {{ data: Record<string, string>; body: string }}
|
|
75
|
-
*/
|
|
76
|
-
export function splitFrontmatter(markdown) {
|
|
60
|
+
/** Simple `key: value` frontmatter (one line per key) and the body after it. */
|
|
61
|
+
export function splitFrontmatter(markdown: string): { data: Record<string, string>; body: string } {
|
|
77
62
|
const match = /^---\n([\s\S]*?)\n---\n?/.exec(markdown);
|
|
78
63
|
|
|
79
64
|
if (!match) return { data: {}, body: markdown };
|
|
80
65
|
|
|
81
|
-
|
|
82
|
-
const data = {};
|
|
66
|
+
const data: Record<string, string> = {};
|
|
83
67
|
|
|
84
68
|
for (const line of (match[1] ?? '').split('\n')) {
|
|
85
69
|
const pair = /^([\w-]+):\s*(.*?)\s*$/.exec(line);
|
|
@@ -96,11 +80,8 @@ export function splitFrontmatter(markdown) {
|
|
|
96
80
|
* The title is the first `# ` heading when nothing but blank lines and HTML
|
|
97
81
|
* comments come before it; otherwise the fallback is the title and the body is
|
|
98
82
|
* kept whole.
|
|
99
|
-
* @param {string} markdown
|
|
100
|
-
* @param {string} fallback
|
|
101
|
-
* @returns {{ title: string; body: string }}
|
|
102
83
|
*/
|
|
103
|
-
export function splitTitle(markdown, fallback) {
|
|
84
|
+
export function splitTitle(markdown: string, fallback: string): { title: string; body: string } {
|
|
104
85
|
const lines = markdown.split('\n');
|
|
105
86
|
let index = 0;
|
|
106
87
|
let inComment = false;
|
|
@@ -133,13 +114,8 @@ export function splitTitle(markdown, fallback) {
|
|
|
133
114
|
return { title: heading[1], body: lines.slice(start).join('\n') };
|
|
134
115
|
}
|
|
135
116
|
|
|
136
|
-
/**
|
|
137
|
-
|
|
138
|
-
* @param {string} markdown
|
|
139
|
-
* @param {string} file
|
|
140
|
-
* @returns {{ title: string; description?: string; body: string }}
|
|
141
|
-
*/
|
|
142
|
-
export function readPage(markdown, file) {
|
|
117
|
+
/** Title, description, and body for one page. */
|
|
118
|
+
export function readPage(markdown: string, file: string): { title: string; description?: string; body: string } {
|
|
143
119
|
const { data, body } = splitFrontmatter(markdown);
|
|
144
120
|
const fallback = data.name ?? basename(file, '.md');
|
|
145
121
|
const split = data.title ? { title: data.title, body } : splitTitle(body, fallback);
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
// The pm-export schemaVersions this package reads, declared once. A new export
|
|
2
|
+
// format is supported by adding its version here, with the page changes it needs.
|
|
3
|
+
|
|
4
|
+
export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = Object.freeze([5]);
|
|
5
|
+
|
|
6
|
+
/** The plan export is missing, unreadable, or in a format this package does not read. */
|
|
7
|
+
export class PlanningExportError extends Error {
|
|
8
|
+
constructor(message: string) {
|
|
9
|
+
super(`${message} Run the pm-export skill to write planning.json.`);
|
|
10
|
+
this.name = 'PlanningExportError';
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Throw unless the export's schemaVersion is one this package reads.
|
|
16
|
+
* @param path the export's path, for the message
|
|
17
|
+
*/
|
|
18
|
+
export function checkSchemaVersion(version: unknown, path: string): void {
|
|
19
|
+
if (typeof version === 'number' && SUPPORTED_SCHEMA_VERSIONS.includes(version)) return;
|
|
20
|
+
|
|
21
|
+
throw new PlanningExportError(
|
|
22
|
+
`${path} has schemaVersion ${String(version)}; this site reads schemaVersion ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}.`,
|
|
23
|
+
);
|
|
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
|
+
}
|
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
|
|
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.
|
|
2
4
|
|
|
3
5
|
/** An optional plan view. Home, Board, Roadmap, Log and Risks are always on. */
|
|
4
|
-
export type ViewName = 'now' | 'milestones' | 'features' | 'inbox' | 'briefs' | 'strategy';
|
|
6
|
+
export type ViewName = 'now' | 'milestones' | 'graph' | 'features' | 'inbox' | 'briefs' | 'strategy' | 'decisions';
|
|
5
7
|
|
|
6
8
|
/** One folder of repository Markdown, shown as one sidebar group. */
|
|
7
9
|
export interface DocsSource {
|
|
@@ -30,7 +32,7 @@ export interface PmDocsSiteOptions {
|
|
|
30
32
|
planning?: string;
|
|
31
33
|
/** Repository Markdown to render as pages; `root` is relative to the site root. Default: none. */
|
|
32
34
|
docs?: { root: string; sources: DocsSource[] };
|
|
33
|
-
/** The optional views to render. Default: all
|
|
35
|
+
/** The optional views to render. Default: all seven. */
|
|
34
36
|
views?: ViewName[];
|
|
35
37
|
}
|
|
36
38
|
|
|
@@ -44,6 +46,3 @@ export interface ResolvedOptions {
|
|
|
44
46
|
docs: { root: string; sources: DocsSource[] } | null;
|
|
45
47
|
views: Record<ViewName, boolean>;
|
|
46
48
|
}
|
|
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/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",
|
|
@@ -32,32 +32,42 @@
|
|
|
32
32
|
"access": "public"
|
|
33
33
|
},
|
|
34
34
|
"engines": {
|
|
35
|
-
"node": ">=
|
|
35
|
+
"node": ">=24"
|
|
36
36
|
},
|
|
37
37
|
"bin": {
|
|
38
|
-
"pm-docs-site": "./cli.
|
|
38
|
+
"pm-docs-site": "./dist/cli.js"
|
|
39
39
|
},
|
|
40
40
|
"exports": {
|
|
41
41
|
".": {
|
|
42
|
-
"types": "./index.d.ts",
|
|
43
|
-
"default": "./index.
|
|
42
|
+
"types": "./dist/index.d.ts",
|
|
43
|
+
"default": "./dist/index.js"
|
|
44
44
|
}
|
|
45
45
|
},
|
|
46
|
-
"files": ["
|
|
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
|
+
"prepack": "node scripts/build.ts && node scripts/check-exports.ts",
|
|
49
50
|
"test": "bun test",
|
|
50
51
|
"check": "astro-check --root .",
|
|
51
|
-
"test:browser": "playwright test"
|
|
52
|
+
"test:browser": "playwright test",
|
|
53
|
+
"test:browser:dev": "playwright test -c playwright.dev.config.ts"
|
|
52
54
|
},
|
|
53
55
|
"dependencies": {
|
|
56
|
+
"@astrojs/react": "7.1.9",
|
|
54
57
|
"@astrojs/starlight": "0.42.10",
|
|
55
|
-
"
|
|
58
|
+
"@dagrejs/dagre": "3.1.3",
|
|
59
|
+
"@xyflow/react": "13.0.2",
|
|
60
|
+
"astro": "7.4.8",
|
|
61
|
+
"react": "19.3.1",
|
|
62
|
+
"react-dom": "19.3.1"
|
|
56
63
|
},
|
|
57
64
|
"devDependencies": {
|
|
58
65
|
"@astrojs/check": "0.9.12",
|
|
59
66
|
"@playwright/test": "1.65.1",
|
|
60
67
|
"@types/bun": "1.4.4",
|
|
68
|
+
"@types/node": "26.6.6",
|
|
69
|
+
"@types/react": "19.3.0",
|
|
70
|
+
"@types/react-dom": "19.3.0",
|
|
61
71
|
"typescript": "6.0.3"
|
|
62
72
|
}
|
|
63
73
|
}
|