Skip to content

Commit e25dadd

Browse files
dragosdev-codedragosdev-code
committed
feat(docs): add Starlight site and migrate wiki
- Add Astro Starlight app under docs/ with DaisyUI theme bridge aligned to the extension - Move wiki architecture pages into content collections and link README/runbook to GitHub Pages URLs - Add Mermaid ELK layout, static inline diagram fit, and click-to-expand fullscreen pan/zoom - Publish docs via GitHub Actions (build, astro check, deploy-pages) on docs path changes - Retire wiki sidebar; leave wiki/README pointing at the new docs site
1 parent 489d16d commit e25dadd

51 files changed

Lines changed: 11478 additions & 407 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "docs/**"
8+
- ".github/workflows/docs.yml"
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
concurrency:
17+
group: pages
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
defaults:
24+
run:
25+
working-directory: docs
26+
steps:
27+
- uses: actions/checkout@v4
28+
- uses: actions/setup-node@v4
29+
with:
30+
node-version: "22"
31+
cache: npm
32+
cache-dependency-path: docs/package-lock.json
33+
- run: npm ci
34+
- run: npm run build
35+
- run: npm run check
36+
- uses: actions/upload-pages-artifact@v3
37+
with:
38+
path: docs/dist
39+
40+
deploy:
41+
needs: build
42+
runs-on: ubuntu-latest
43+
environment:
44+
name: github-pages
45+
url: ${{ steps.deployment.outputs.page_url }}
46+
steps:
47+
- id: deployment
48+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Pullwatch has two halves: a background service worker that fetches and parses pa
5050

5151
The service worker wakes up on a Chrome alarm every 3 minutes, asks GitHub for your pulls list HTML using the cookie your browser already has, runs the HTML through a three stage parser (embedded JSON, then the new dashboard HTML, then the legacy HTML), and writes the result into `chrome.storage.local`. If GitHub returns a 429, an exponential backoff kicks in. The popup itself never calls GitHub. When you open it, it pulls the last persisted lists straight from `chrome.storage.local` before the first paint, then listens for storage updates while it stays open.
5252

53-
When GitHub returns a transport error or its [Statuspage](https://www.githubstatus.com) reports a Pull Requests incident, Pullwatch keeps the last-known list and shows an outage banner over the top of it; the banner links to `githubstatus.com` only when the cached snapshot corroborates a real incident. The full reason taxonomy and the integrity layer that catches "200 OK with an incomplete list" are documented in the [GitHub Health and Outages](https://github.com/dragosdev-code/pullwatch/wiki/GitHub-Health-and-Outages) wiki cluster.
53+
When GitHub returns a transport error or its [Statuspage](https://www.githubstatus.com) reports a Pull Requests incident, Pullwatch keeps the last-known list and shows an outage banner over the top of it; the banner links to `githubstatus.com` only when the cached snapshot corroborates a real incident. The full reason taxonomy and the integrity layer that catches "200 OK with an incomplete list" are documented in the [GitHub Health and Outages](https://dragosdev-code.github.io/pullwatch/architecture/github-health/) docs cluster.
5454

5555
```mermaid
5656
flowchart LR
@@ -73,7 +73,7 @@ flowchart LR
7373
React --> Store
7474
```
7575

76-
For the longer tour of the service worker lifecycle, the parser waterfall, the remote pattern config, and the popup hydration flow, see the wiki's [Architecture Overview](https://github.com/dragosdev-code/pullwatch/wiki/Architecture-Overview).
76+
For the longer tour of the service worker lifecycle, the parser waterfall, the remote pattern config, and the popup hydration flow, see the [Architecture Overview](https://dragosdev-code.github.io/pullwatch/architecture/overview/) in the docs site ([full docs](https://dragosdev-code.github.io/pullwatch/)).
7777

7878
## Canary monitor
7979

‎canary/DOM_CHANGE_RUNBOOK.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ The extension parses GitHub HTML pages using regex patterns to extract PR data.
111111
- **Runtime validation**: Before compiling, the service runs `validateRemoteConfig()` (from `extension/common/pattern-registry-schema.ts`) against the raw JSON. If the structure is invalid, it is rejected immediately with a dotted-path error message logged to the extension console — e.g., `prRowSelectors.0.type: Expected 'class' | 'attribute' | 'balanced-div', received 'xpath'`. The current compiled patterns are preserved unchanged. This is a **structural** check; regex syntax is still validated by `safeCompile` (a second defense layer) after the schema passes.
112112
- **Two version numbers to keep straight** (plus the bundled floor):
113113
- `version` (integer, in `patterns.json`): the config revision. Increment by 1 every time you push updated patterns. Starts at 1; the extension may still have `0` in storage from older installs.
114-
- `BUNDLED_PATTERNS_REGISTRY_VERSION` (integer, in `extension/common/constants.ts`): the floor written when the extension falls back to bundled `default-patterns.ts`. Bump only when `default-patterns.ts` changes in the extension repo. Remote-only hotfixes bump `patterns.json` `version` only. See [Remote Configuration § When to bump which version](../wiki/Remote-Configuration.md#when-to-bump-which-version).
114+
- `BUNDLED_PATTERNS_REGISTRY_VERSION` (integer, in `extension/common/constants.ts`): the floor written when the extension falls back to bundled `default-patterns.ts`. Bump only when `default-patterns.ts` changes in the extension repo. Remote-only hotfixes bump `patterns.json` `version` only. See [Remote Configuration § When to bump which version](https://dragosdev-code.github.io/pullwatch/architecture/remote-configuration/#when-to-bump-which-version).
115115
- `minExtensionVersion` (semver string, in `patterns.json`): the minimum extension build that should apply this config. Set this if new patterns require new extension code; leave it at `"0.0.0"` if all builds can safely use them. This is compared against `chrome.runtime.getManifest().version`, not against the config `version` number.
116116
- **Production reads `main`, not `staging`.** Smoke tests on `staging` do not change what live extensions fetch until you merge to `main`.
117117
- **Clearing extension storage while debugging:** After a rebuild with a newer bundle, a cache clear reloads bundled patterns at the floor version; outdated `main` configs (lower `version` than the floor) are skipped. Older builds reset storage to version `0`, so an outdated remote could overwrite the bundle. If you see that, rebuild with the floor constant or push a newer `patterns.json` to `main`.

‎docs/.gitignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# build output
2+
dist/
3+
# generated types
4+
.astro/
5+
6+
# dependencies
7+
node_modules/
8+
9+
# logs
10+
npm-debug.log*
11+
yarn-debug.log*
12+
yarn-error.log*
13+
pnpm-debug.log*
14+
15+
16+
# environment variables
17+
.env
18+
.env.production
19+
20+
# macOS-specific files
21+
.DS_Store

‎docs/.vscode/extensions.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"recommendations": ["astro-build.astro-vscode"],
3+
"unwantedRecommendations": []
4+
}

‎docs/.vscode/launch.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"command": "./node_modules/.bin/astro dev",
6+
"name": "Development server",
7+
"request": "launch",
8+
"type": "node-terminal"
9+
}
10+
]
11+
}

‎docs/CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Documentation changelog
2+
3+
## 2026-06-02
4+
5+
- DaisyUI 5.0.43 + Tailwind 4.2.2: docs UI matches extension themes (35 themes, `pr-extension-theme` storage).
6+
- Migrated wiki to Starlight (`docs/`) and GitHub Pages at `/pullwatch`.
7+
- Added GitHub Health cluster: list trust, outage banner, assessor diagrams.
8+
- Tuned Mermaid spacing and added interactive scenario walkthrough on list trust (pilot).

‎docs/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Pullwatch documentation site
2+
3+
Starlight docs for [Pullwatch](https://github.com/dragosdev-code/pullwatch). Published at [https://dragosdev-code.github.io/pullwatch/](https://dragosdev-code.github.io/pullwatch/).
4+
5+
## Commands
6+
7+
```bash
8+
npm install
9+
npm run dev # local preview at http://localhost:4321/pullwatch/
10+
npm run build # static output in dist/
11+
npm run preview # serve dist/
12+
npm run check # astro check (types + content)
13+
```
14+
15+
If you see `UnknownContentCollectionError` for a page after renaming or removing `.mdx` files, clear the Astro cache and restart:
16+
17+
```bash
18+
rm -rf .astro node_modules/.vite
19+
npm run dev
20+
```
21+
22+
## Content
23+
24+
Markdown lives in `src/content/docs/`. To re-run the one-time wiki import from `../wiki/`:
25+
26+
```bash
27+
node scripts/migrate-wiki.mjs
28+
```
29+
30+
(from repo root)
31+
32+
## Theming (DaisyUI)
33+
34+
The docs site uses **DaisyUI 5.0.43** and **Tailwind CSS 4.2.2** — the same versions as the extension (`package.json` at repo root). All 35 themes from `src/components/settings/appearance/themes.ts` are available via the header theme dropdown.
35+
36+
Theme choice is stored under `pr-extension-theme` in `localStorage` (same key as the extension popup).
37+
38+
## Diagrams
39+
40+
Flowcharts use the **[ELK](https://eclipse.dev/elk/)** layout engine (`@mermaid-js/layout-elk`) for clearer large graphs. In the page, diagrams **scale to fill** the card (not draggable). **Click** a diagram for fullscreen pan/zoom; **Esc** closes.
41+
42+
To use Dagre on a single diagram, add YAML frontmatter at the top of the `mermaid` code block (`layout: dagre`). See [Mermaid layouts](https://mermaid.js.org/config/layouts.html).
43+
44+
## Interactive components (optional)
45+
46+
`@astrojs/react` and MDX are installed for future scenario walkthroughs. Pages are plain Markdown + Mermaid for now.

‎docs/astro.config.ts‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
import { defineConfig } from 'astro/config';
2+
import starlight from '@astrojs/starlight';
3+
import mermaid from 'astro-mermaid';
4+
import react from '@astrojs/react';
5+
import mdx from '@astrojs/mdx';
6+
import tailwindcss from '@tailwindcss/vite';
7+
8+
import { pullwatchMermaidConfig } from './mermaid.config';
9+
10+
// https://astro.build/config
11+
12+
export default defineConfig({
13+
site: 'https://dragosdev-code.github.io',
14+
15+
base: '/pullwatch',
16+
17+
vite: {
18+
plugins: [tailwindcss()],
19+
},
20+
21+
integrations: [
22+
mermaid({
23+
theme: 'base',
24+
25+
autoTheme: true,
26+
27+
enableLog: false,
28+
29+
mermaidConfig: pullwatchMermaidConfig,
30+
}),
31+
32+
starlight({
33+
title: 'Pullwatch',
34+
35+
description:
36+
'Your GitHub PR inbox. Sorted. No tokens. No noise. Architecture and deep dives.',
37+
38+
logo: {
39+
src: './src/assets/logo.png',
40+
},
41+
42+
editLink: {
43+
baseUrl: 'https://github.com/dragosdev-code/pullwatch/edit/main/docs/',
44+
},
45+
46+
social: [
47+
{
48+
icon: 'github',
49+
50+
label: 'GitHub',
51+
52+
href: 'https://github.com/dragosdev-code/pullwatch',
53+
},
54+
],
55+
56+
components: {
57+
ThemeSelect: './src/components/DocsThemeSelect.astro',
58+
59+
Head: './src/components/HeadWithTheme.astro',
60+
61+
Footer: './src/components/FooterWithDiagrams.astro',
62+
},
63+
64+
head: [],
65+
66+
customCss: [
67+
'./src/styles/global.css',
68+
69+
'./src/styles/starlight-daisy-bridge.css',
70+
71+
'./src/styles/docs-overrides.css',
72+
],
73+
74+
sidebar: [
75+
{
76+
label: 'Welcome',
77+
78+
items: ['index', 'getting-started'],
79+
},
80+
81+
{
82+
label: 'The big picture',
83+
84+
items: ['architecture/overview'],
85+
},
86+
87+
{
88+
label: 'Deep dives',
89+
90+
items: [
91+
'architecture/import-paths-and-aliases',
92+
93+
'architecture/service-worker-lifecycle',
94+
95+
'architecture/parser-waterfall',
96+
97+
{
98+
label: 'GitHub health and outages',
99+
100+
items: [
101+
'architecture/github-health',
102+
103+
'architecture/github-health/list-trust',
104+
105+
'architecture/github-health/outage-banner',
106+
],
107+
},
108+
109+
'architecture/remote-configuration',
110+
111+
'architecture/data-hydration-and-storage',
112+
113+
'architecture/popup-and-background-communication',
114+
115+
'architecture/onboarding-and-session-gates',
116+
117+
'architecture/notifications-and-sound',
118+
119+
'architecture/canary-monitor',
120+
],
121+
},
122+
123+
{
124+
label: 'Related',
125+
126+
items: [
127+
{
128+
label: 'DOM change runbook',
129+
130+
link: 'https://github.com/dragosdev-code/pullwatch/blob/main/canary/DOM_CHANGE_RUNBOOK.md',
131+
},
132+
133+
{
134+
label: 'Squash minigame docs',
135+
136+
link: 'https://github.com/dragosdev-code/pullwatch/tree/main/src/components/squash-minigame/docs',
137+
},
138+
],
139+
},
140+
],
141+
}),
142+
143+
react(),
144+
145+
mdx(),
146+
],
147+
});

‎docs/mermaid.config.ts‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import type { MermaidConfig } from "mermaid";
2+
3+
/** Shared Mermaid tuning for dense architecture diagrams. */
4+
export const pullwatchMermaidConfig: MermaidConfig = {
5+
startOnLoad: false,
6+
logLevel: "error",
7+
theme: "base",
8+
/** ELK layout (requires `@mermaid-js/layout-elk`; astro-mermaid registers it when installed). */
9+
layout: "elk",
10+
themeVariables: {
11+
fontSize: "16px",
12+
fontFamily: "ui-sans-serif, system-ui, sans-serif",
13+
},
14+
elk: {
15+
mergeEdges: false,
16+
nodePlacementStrategy: "NETWORK_SIMPLEX",
17+
},
18+
flowchart: {
19+
curve: "basis",
20+
padding: 24,
21+
nodeSpacing: 65,
22+
rankSpacing: 85,
23+
htmlLabels: true,
24+
useMaxWidth: true,
25+
defaultRenderer: "elk",
26+
},
27+
sequence: {
28+
diagramMarginX: 48,
29+
diagramMarginY: 16,
30+
actorFontSize: 15,
31+
noteFontSize: 14,
32+
messageFontSize: 15,
33+
useMaxWidth: true,
34+
},
35+
state: {
36+
nodeSpacing: 55,
37+
rankSpacing: 70,
38+
useMaxWidth: true,
39+
},
40+
};

0 commit comments

Comments
 (0)