diff --git a/.github/workflows/faq.yml b/.github/workflows/faq.yml new file mode 100644 index 00000000..7f300d32 --- /dev/null +++ b/.github/workflows/faq.yml @@ -0,0 +1,56 @@ +name: FAQ website +on: + pull_request: + paths: + - 'apps/website/**' + - 'docs/**' + - 'design/**' + - 'tools/website-*.mjs' + - 'package*.json' + - '.github/workflows/faq.yml' + push: + branches: [main] + paths: + - 'apps/website/**' + - 'docs/**' + - 'design/**' + - 'tools/website-*.mjs' + - 'package*.json' + - '.github/workflows/faq.yml' + workflow_dispatch: +permissions: + contents: read +concurrency: + group: faq-${{ github.ref }} + cancel-in-progress: true +jobs: + browser: + name: Built FAQ / Chromium + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + with: + ref: ${{ github.event.pull_request.head.sha || github.sha }} + persist-credentials: false + - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6 + with: + node-version: '22' + package-manager-cache: false + - name: Restore locked project packages + run: npm ci --ignore-scripts --no-audit --no-fund + - name: Build the real website and search index + env: + DIFFDEVIL_SITE_ORIGIN: https://diffdevil.dev + run: npm run website:build + - name: Install the repository-selected Chromium + run: npx --no-install playwright install --with-deps chromium + - name: Exercise FAQ navigation, links, search and responsive layout + run: node apps/website/qa/faq.mjs + - name: Preserve browser evidence + if: always() + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: faq-browser-evidence + path: artifacts/website/faq-qa/ + if-no-files-found: ignore diff --git a/.gitignore b/.gitignore index 1865c871..9662487f 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ coverage/ # Generated website docs collection (tools/website-docs.mjs) and Astro type output apps/website/src/content/docs/ apps/website/src/content/sidebar.json +apps/website/src/generated/faq.md apps/website/.astro/ # Derived website icons/rasters (tools/website-assets.mjs): the identity SVGs are the source; no raster is committed apps/website/public/favicon.ico diff --git a/README.md b/README.md index f75ac590..e66c7cdb 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ node dist/lib/cli/main.js query --report docs/examples/reports/exact.json \ # 178 ``` -**[Try the playground](https://diffdevil-playground.wolfsblvt.workers.dev)** · **[Label your PRs](docs/guides/auto-label-pull-requests.md)** · [Local scripts](docs/guides/local-automation.md) · [Policy recipes](docs/guides/policy-recipes.md) · [User manual](docs/automation.md) · [CLI reference](docs/integration/cli.md) · [Actions](docs/integration/github-actions.md) · [TypeScript API](docs/integration/typescript-api.md) +**[Try the playground](https://diffdevil-playground.wolfsblvt.workers.dev)** · **[Label your PRs](docs/guides/auto-label-pull-requests.md)** · [Local scripts](docs/guides/local-automation.md) · [Policy recipes](docs/guides/policy-recipes.md) · [FAQ](docs/manual/faq.md) · [User manual](docs/automation.md) · [CLI reference](docs/integration/cli.md) · [Actions](docs/integration/github-actions.md) · [TypeScript API](docs/integration/typescript-api.md) ## Label your PRs with one file diff --git a/apps/website/astro.config.mjs b/apps/website/astro.config.mjs index cb168850..2e11579f 100644 --- a/apps/website/astro.config.mjs +++ b/apps/website/astro.config.mjs @@ -6,6 +6,7 @@ import { readFileSync, existsSync } from 'node:fs'; import { fileURLToPath } from 'node:url'; import { diffdevilSyntax } from './src/lib/shiki-theme.ts'; import { themeScript } from './src/lib/theme-script.mjs'; +import searchIndex from './search-index.mjs'; const repositoryRoot = fileURLToPath(new URL('../../', import.meta.url)); const engine = path => fileURLToPath(new URL(`../../dist/lib/${path}`, import.meta.url)); @@ -23,6 +24,7 @@ export default defineConfig({ title: 'diffdevil', description: 'The diffdevil manual: CLI, GitHub Actions, policies and the detail language, TypeScript API, playground and GitHub App.', sidebar, + pagefind: false, customCss: ['./src/styles/fonts.css', './src/styles/tokens.css', './src/styles/global.css', './src/styles/starlight.css'], components: { Header: './src/components/docs/Header.astro', @@ -49,6 +51,7 @@ export default defineConfig({ disable404Route: true, }), react(), + searchIndex(), ], markdown: { shikiConfig: { theme: diffdevilSyntax } }, vite: { diff --git a/apps/website/docs-manifest.mjs b/apps/website/docs-manifest.mjs index e6552359..d5da06ab 100644 --- a/apps/website/docs-manifest.mjs +++ b/apps/website/docs-manifest.mjs @@ -9,13 +9,18 @@ * `tested: true` marks pages whose command/policy/workflow specimens are executed by * `src/diffdevil/tests/examples.test.mjs`; the docs footer shows "Example tested ✓" there. */ +import { FAQ_ROUTE, FAQ_SOURCE } from './faq-content.mjs'; + +/** Product prose shares source routing, but never creates a duplicate manual page. */ +export const productPages = [{ source: FAQ_SOURCE, route: FAQ_ROUTE }]; + export const groups = [ { label: 'Overview', entries: [ - { source: 'docs/README.md', slug: '', title: 'Docs' }, + { source: 'docs/README.md', faq: ["beyond-size-labels", "why-managed"], slug: '', title: 'Docs' }, ] }, { label: 'Get started', entries: [ - { source: 'docs/guides/auto-label-pull-requests.md', slug: 'get-started/auto-label-pull-requests', tested: true }, - { source: 'docs/guides/local-automation.md', slug: 'get-started/local-automation', tested: true }, + { source: 'docs/guides/auto-label-pull-requests.md', faq: ["beyond-size-labels", "automation-overlap", "trusted-policy"], slug: 'get-started/auto-label-pull-requests', tested: true }, + { source: 'docs/guides/local-automation.md', faq: ["non-javascript-projects", "no-language-required"], slug: 'get-started/local-automation', tested: true }, { source: 'docs/automation.md', slug: 'get-started/automation' }, { source: 'docs/examples/README.md', slug: 'get-started/examples', title: 'Example map' }, ] }, @@ -23,22 +28,22 @@ export const groups = [ { source: 'docs/guides/policy-recipes.md', slug: 'recipes/policy-recipes', tested: true }, ] }, { label: 'CLI', entries: [ - { source: 'docs/integration/cli.md', slug: 'cli', title: 'CLI' }, + { source: 'docs/integration/cli.md', faq: ["different-results", "no-language-required"], slug: 'cli', title: 'CLI' }, { source: 'docs/PRESENTATION.md', slug: 'cli/presentation', title: 'Human and agent presentation' }, ] }, { label: 'Actions', entries: [ - { source: 'docs/integration/github-actions.md', slug: 'actions/github-actions', tested: true }, + { source: 'docs/integration/github-actions.md', faq: ["automation-overlap", "trusted-policy"], slug: 'actions/github-actions', tested: true }, { source: 'docs/integration/action-distribution.md', slug: 'actions/action-distribution' }, - { source: 'docs/integration/github-api.md', slug: 'actions/github-api' }, + { source: 'docs/integration/github-api.md', faq: ["code-data"], slug: 'actions/github-api' }, ] }, { label: 'Policies and detail', entries: [ { source: 'docs/language/policies-and-bands.md', slug: 'policies-and-detail/policies-and-bands' }, - { source: 'docs/integration/presets-and-shortcuts.md', slug: 'policies-and-detail/presets-and-shortcuts' }, - { source: 'docs/integration/templates.md', slug: 'policies-and-detail/templates' }, + { source: 'docs/integration/presets-and-shortcuts.md', faq: ["no-language-required", "semantic-versioning"], slug: 'policies-and-detail/presets-and-shortcuts' }, + { source: 'docs/integration/templates.md', faq: ["automation-overlap"], slug: 'policies-and-detail/templates' }, { source: 'docs/language.md', slug: 'policies-and-detail/language' }, { source: 'docs/language/syntax.md', slug: 'policies-and-detail/syntax' }, - { source: 'docs/language/types-and-measurements.md', slug: 'policies-and-detail/types-and-measurements' }, - { source: 'docs/language/collections-and-scopes.md', slug: 'policies-and-detail/collections-and-scopes' }, + { source: 'docs/language/types-and-measurements.md', faq: ["changed-vs-churn", "changed-makes-sense", "measurement-evidence"], slug: 'policies-and-detail/types-and-measurements' }, + { source: 'docs/language/collections-and-scopes.md', faq: ["files-and-exclusions"], slug: 'policies-and-detail/collections-and-scopes' }, { source: 'docs/language/standard-library.md', slug: 'policies-and-detail/standard-library' }, { source: 'docs/language/diagnostics-and-limits.md', slug: 'policies-and-detail/diagnostics-and-limits' }, { source: 'docs/language/versioning-and-interchange.md', slug: 'policies-and-detail/versioning-and-interchange' }, @@ -51,6 +56,7 @@ export const groups = [ { source: 'docs/agent-skill/README.md', slug: 'agents/agent-integration', optional: true }, { source: 'skills/diffdevil/SKILL.md', slug: 'agents/skill', optional: true, title: 'Agent Skill source' }, { source: 'docs/setup/README.md', slug: 'agents/setup', optional: true }, + { source: 'docs/setup/skill.md', faq: ["coding-agents", "non-javascript-projects"], slug: 'setup/skill', title: 'Coding-agent setup' }, { source: 'docs/setup/cli.md', slug: 'setup/cli', optional: true }, { source: 'docs/setup/actions.md', slug: 'setup/actions', optional: true }, { source: 'docs/setup/app.md', slug: 'setup/app', optional: true }, @@ -58,20 +64,23 @@ export const groups = [ { link: '/docs/cli/presentation/#agent-report-projection', label: 'Agent output contract' }, ] }, { label: 'Playground', entries: [ - { source: 'docs/integration/playground.md', slug: 'playground', title: 'Playground' }, + { source: 'docs/integration/playground.md', faq: ["playground-or-extension", "code-data"], slug: 'playground', title: 'Playground' }, { source: 'apps/playground/README.md', slug: 'playground/application', title: 'Playground application and local route' }, ] }, { label: 'GitHub App', entries: [ - { source: 'docs/integration/github-app.md', slug: 'github-app/architecture', title: 'App architecture' }, - { source: 'docs/PRIVACY-AND-DATA.md', slug: 'github-app/privacy-and-data', title: 'Privacy and data' }, - { source: 'apps/github-app/README.md', slug: 'github-app/self-hosting', title: 'Self-hosting the runtime' }, + { source: 'docs/integration/github-app.md', faq: ["why-managed", "leaving-managed-service"], slug: 'github-app/architecture', title: 'App architecture' }, + { source: 'docs/PRIVACY-AND-DATA.md', faq: ["code-data", "app-history"], slug: 'github-app/privacy-and-data', title: 'Privacy and data' }, + { source: 'apps/github-app/README.md', faq: ["leaving-managed-service"], slug: 'github-app/self-hosting', title: 'Self-hosting the runtime' }, ] }, // The browser extension's manual pages are authored with the extension application. // They render as soon as that source is in the repository; until then the group is empty. { label: 'Browser extension', entries: [ - { source: 'apps/browser-extension/README.md', slug: 'browser-extension', title: 'diffdevil for GitHub', optional: true }, - { source: 'apps/browser-extension/PRIVACY.md', slug: 'browser-extension/privacy', title: 'Extension privacy', optional: true }, - { source: 'docs/integration/browser-extension.md', slug: 'browser-extension/integration', title: 'Browser integration', optional: true }, + { source: 'apps/browser-extension/README.md', faq: ["playground-or-extension", "extension-without-repo-setup"], slug: 'browser-extension', title: 'diffdevil for GitHub', optional: true }, + { source: 'apps/browser-extension/PRIVACY.md', faq: ["code-data"], slug: 'browser-extension/privacy', title: 'Extension privacy', optional: true }, + { source: 'docs/integration/browser-extension.md', faq: ["different-results"], slug: 'browser-extension/integration', title: 'Browser integration', optional: true }, + ] }, + { label: 'Help', entries: [ + { link: FAQ_ROUTE, label: 'FAQ' }, ] }, { label: 'Troubleshooting', entries: [ { link: '/docs/get-started/auto-label-pull-requests/#troubleshooting', label: 'Labels did not appear' }, diff --git a/apps/website/faq-content.mjs b/apps/website/faq-content.mjs new file mode 100644 index 00000000..038d7bec --- /dev/null +++ b/apps/website/faq-content.mjs @@ -0,0 +1,54 @@ +// SPDX-License-Identifier: AGPL-3.0-only +/** Public coordinates and extraction from the real rendered FAQ, not another answer registry. */ +export const FAQ_SOURCE = 'docs/manual/faq.md'; +export const FAQ_ROUTE = '/faq/'; +export const FAQ_CANONICAL = 'https://diffdevil.dev/faq/'; + +export function escapeHtml(text) { + return String(text).replace(/[&<>"']/gu, char => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[char]); +} +function attribute(attributes, name) { + return new RegExp(`(?:^|\\s)${name}=["']([^"']*)["']`, 'u').exec(attributes)?.[1]; +} +/** Decode the HTML entities that can occur in authored titles and metadata. */ +export function textOf(html) { + const named = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' }; + return html.replace(/<[^>]*>/gu, ' ').replace(/&(#x[0-9a-f]+|#[0-9]+|amp|lt|gt|quot|apos|nbsp);/giu, (whole, entity) => { + if (entity[0] !== '#') return named[entity.toLowerCase()] ?? whole; + const point = entity[1].toLowerCase() === 'x' ? parseInt(entity.slice(2), 16) : Number(entity.slice(1)); + return point > 0 && point <= 0x10ffff ? String.fromCodePoint(point) : whole; + }).replace(/\s+/gu, ' ').trim(); +} + +/** + * Read only the FAQ's authored h2/article structure from built HTML. Pagefind itself + * parses each resulting HTML record, so Markdown rendering and search cannot disagree. + */ +export function faqRecords(html) { + const records = [], seen = new Set(); + let category = ''; + const pieces = /]*>([\s\S]*?)<\/h2>|]*)>([\s\S]*?)<\/article>/gu; + for (const match of html.matchAll(pieces)) { + if (match[1] !== undefined) { category = textOf(match[1]); continue; } + const attributes = match[2], body = match[3]; + if (!attribute(attributes, 'class')?.split(/\s+/u).includes('faq-question')) continue; + const id = attribute(attributes, 'data-faq-id'); + const title = textOf(/]*>([\s\S]*?)<\/summary>/u.exec(body)?.[1] ?? ''); + if (!id || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(id) || seen.has(id) || !title || !category) { + throw new Error('FAQ questions need a unique semantic identifier, category and title.'); + } + if (!new RegExp(`\\bid=["']${id}["']`, 'u').test(body)) throw new Error(`FAQ fragment is missing: ${id}`); + seen.add(id); + const noteId = attribute(attributes, 'data-faq-note'); + const note = noteId ? new RegExp(`]*\\bid=["']${noteId}["'][^>]*>([\\s\\S]*?)<\\/aside>`, 'u').exec(html)?.[1] : undefined; + if (noteId && !note) throw new Error(`FAQ development note is missing: ${noteId}`); + const standing = note ? 'In development' : ''; + const canonical = `${FAQ_CANONICAL}#${id}`; + const meta = { title, kind: 'FAQ', category, identifier: `#${id}`, canonical, standing }; + const metadata = Object.entries(meta).map(([name, value]) => `${escapeHtml(value)}`).join(''); + records.push({ id, title, category, standing, canonical, url: `${FAQ_ROUTE}#${id}`, + html: `${escapeHtml(title)}
${metadata}${note ?? ''}${body}
` }); + } + if (!records.length) throw new Error('The rendered FAQ has no question records.'); + return records; +} diff --git a/apps/website/faq.test.mjs b/apps/website/faq.test.mjs new file mode 100644 index 00000000..6a9d4853 --- /dev/null +++ b/apps/website/faq.test.mjs @@ -0,0 +1,84 @@ +// SPDX-License-Identifier: AGPL-3.0-only +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { readFileSync } from 'node:fs'; +import { faqRecords, textOf, FAQ_CANONICAL, FAQ_SOURCE, FAQ_ROUTE } from './faq-content.mjs'; +import { entries, groups, productPages } from './docs-manifest.mjs'; + +const source = readFileSync(new URL('../../docs/manual/faq.md', import.meta.url), 'utf8'); +function specimen({ id = 'sample-question', title = 'A question?', extra = '', body = '

The answer.

' } = {}) { + return `

Useful questions

`; +} + +test('the focused FAQ preserves 20 unique question routes in its eight ordered categories', () => { + const records = faqRecords(source); + assert.equal(records.length, 20); + assert.equal(new Set(records.map(record => record.id)).size, records.length); + assert.deepEqual(records.slice(0, 2).map(record => record.id), ['changed-vs-churn', 'beyond-size-labels']); + const counts = new Map(); + for (const record of records) { + counts.set(record.category, (counts.get(record.category) ?? 0) + 1); + assert.equal(record.url, `${FAQ_ROUTE}#${record.id}`); + assert.equal(record.canonical, `${FAQ_CANONICAL}#${record.id}`); + assert.ok(record.title.length > 0); + } + assert.deepEqual([...counts.values()], [3, 3, 3, 2, 2, 2, 2, 3]); +}); + +test('question search records carry the actual answer HTML, title, identifier and category', () => { + const [record] = faqRecords(specimen({ title: 'Who reads A & B?', body: '

A report, not a plan.

' })); + assert.equal(record.title, 'Who reads A & B?'); + assert.equal(record.category, 'Useful questions'); + assert.ok(record.html.includes('

A report, not a plan.

')); + assert.ok(record.html.includes('data-pagefind-meta="kind"')); + assert.ok(record.html.includes('data-pagefind-meta="identifier"')); + assert.ok(record.html.includes('Who reads A & B?')); +}); + +test('the subtle development note follows only affected answers into search', () => { + const records = new Map(faqRecords(source).map(record => [record.id, record])); + assert.equal(records.get('extension-without-repo-setup').standing, 'In development'); + assert.ok(records.get('extension-without-repo-setup').html.includes('managed-service experience')); + assert.equal(records.get('why-managed').standing, 'In development'); + assert.equal(records.get('changed-vs-churn').standing, ''); + assert.equal(records.get('no-language-required').standing, ''); +}); + +test('a linked development note cannot disappear silently', () => { + assert.throws(() => faqRecords(specimen({ extra: 'data-faq-note="not-present"' })), /development note is missing/u); +}); + +test('duplicate public question identifiers refuse indexing', () => { + assert.throws(() => faqRecords(specimen() + specimen()), /unique semantic identifier/u); +}); + +test('missing destinations and unsafe identifier syntax refuse indexing', () => { + assert.throws(() => faqRecords(specimen().replace('id="sample-question" class=', 'class=')), /fragment is missing/u); + assert.throws(() => faqRecords(specimen({ id: 'question with spaces' })), /unique semantic identifier/u); + assert.throws(() => faqRecords('

Empty category

'), /no question records/u); +}); + +test('metadata decodes authored entities without turning them into HTML', () => { + assert.equal(textOf('

A & B ? 'quoted' <tag>

'), "A & B ? 'quoted' "); + const [record] = faqRecords(specimen({ title: '<img src=x>' })); + assert.equal(record.title, ''); + assert.ok(record.html.includes('<img src=x>')); +}); + +test('the FAQ is a product route and Help link, never a duplicate docs entry', () => { + assert.deepEqual(productPages.filter(page => page.source === FAQ_SOURCE), [{ source: FAQ_SOURCE, route: FAQ_ROUTE }]); + assert.equal(entries.some(entry => entry.source === FAQ_SOURCE), false); + assert.ok(groups.find(group => group.label === 'Help')?.entries.some(entry => entry.link === FAQ_ROUTE)); +}); + +test('contextual documentation links select real question identifiers, not copied titles', () => { + const ids = new Set(faqRecords(source).map(record => record.id)); + const linked = entries.filter(entry => entry.faq?.length); + assert.ok(linked.length > 0); + for (const entry of linked) { + assert.equal(new Set(entry.faq).size, entry.faq.length, entry.source); + for (const id of entry.faq) assert.ok(ids.has(id), `${entry.source}: ${id}`); + } +}); diff --git a/apps/website/qa/faq.mjs b/apps/website/qa/faq.mjs new file mode 100644 index 00000000..2dd8ffa9 --- /dev/null +++ b/apps/website/qa/faq.mjs @@ -0,0 +1,176 @@ +// SPDX-License-Identifier: AGPL-3.0-only +/** Actual built-site FAQ, shared navigation, Pagefind and browser interaction qualification. */ +import assert from 'node:assert/strict'; +import { createServer } from 'node:http'; +import { readFile, mkdir, writeFile } from 'node:fs/promises'; +import { resolve, extname, sep } from 'node:path'; +import { chromium, expect } from '@playwright/test'; +import { faqRecords, FAQ_CANONICAL, FAQ_SOURCE } from '../faq-content.mjs'; + +const directory = resolve('artifacts/website/dist'); +const output = resolve('artifacts/website/faq-qa'); +const records = faqRecords(await readFile(resolve(directory, 'faq/index.html'), 'utf8')); +const authored = faqRecords(await readFile(resolve(FAQ_SOURCE), 'utf8')); +assert.deepEqual(records.map(({ id, title }) => ({ id, title })), authored.map(({ id, title }) => ({ id, title }))); +const authoredLinkCount = authored.reduce((count, question) => count + [...question.html.matchAll(/\[[^\]]+\]\([^)]+\)/gu)].length, 0); +const mime = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.wasm': 'application/wasm', '.woff2': 'font/woff2', '.png': 'image/png', '.ico': 'image/x-icon' }; +const server = createServer(async (request, response) => { + try { + let pathname = decodeURIComponent(new URL(request.url, 'http://127.0.0.1').pathname); + if (pathname.endsWith('/')) pathname += 'index.html'; + const file = resolve(directory, `.${pathname}`); + if (!file.startsWith(directory + sep)) throw new Error('Outside site'); + const content = await readFile(file); + response.writeHead(200, { 'Content-Type': mime[extname(file)] ?? 'application/octet-stream' }); + response.end(content); + } catch { response.writeHead(404); response.end('Not found'); } +}); +await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); +const origin = `http://127.0.0.1:${server.address().port}`; +const failures = [], evidence = []; +let browser, page; +try { + await mkdir(output, { recursive: true }); + browser = await chromium.launch(process.env.PLAYWRIGHT_EXECUTABLE_PATH ? { executablePath: process.env.PLAYWRIGHT_EXECUTABLE_PATH } : {}); + const context = await browser.newContext({ viewport: { width: 1280, height: 900 }, colorScheme: 'dark', reducedMotion: 'reduce' }); + await context.grantPermissions(['clipboard-read', 'clipboard-write']); + page = await context.newPage(); + page.on('pageerror', error => failures.push(error.message)); + await context.route('**/*', route => { + if (new URL(route.request().url()).origin === origin) return route.continue(); + failures.push(`Unexpected external request: ${route.request().url()}`); + return route.abort(); + }); + await page.goto(`${origin}/faq/`); + await page.evaluate(() => document.fonts.ready); + await expect(page.locator('h1')).toHaveCount(1); + await expect(page.locator('.faq-question')).toHaveCount(20); + await expect(page.locator('.faq-categories a')).toHaveCount(8); + await expect(page.locator('.faq-answer a')).toHaveCount(authoredLinkCount); + await expect(page.locator('.faq-question details[open]')).toHaveCount(2); + await expect(page.locator('.sidebar-pane')).toHaveCount(0); + await expect(page.locator('.primary-nav .site-nav > li').last().locator('a')).toHaveAttribute('href', '/faq/'); + await expect(page.locator('footer a[href="/faq/"]')).toBeVisible(); + assert.equal(await page.locator('meta[name="robots"]').count(), 0); + for (const question of records) { + assert.ok(await page.locator(`[data-faq-id="${question.id}"] .faq-answer a`).count() <= 1, question.id); + } + await page.screenshot({ path: resolve(output, 'faq-dark-desktop.png') }); + evidence.push('Standalone page, all 20 disclosures, category navigation, shared header/footer and one-link limit.'); + + const custom = page.locator('[data-faq-id="no-language-required"]'); + await page.goto(`${origin}/faq/#changed-vs-churn`); + await custom.locator('.faq-id').click(); + await expect(custom.locator('details')).toHaveAttribute('open', ''); + await expect(custom.locator('summary')).toBeFocused(); + await expect.poll(() => page.evaluate(() => navigator.clipboard.readText())).toBe(`${FAQ_CANONICAL}#no-language-required`); + await custom.locator('summary').press('Enter'); + await expect(custom.locator('details')).not.toHaveAttribute('open', ''); + await custom.locator('.faq-id').click(); + await expect(custom.locator('details')).toHaveAttribute('open', ''); + await page.goBack(); + await expect(page).toHaveURL(/#changed-vs-churn$/u); + await expect(page.locator('#changed-vs-churn')).toBeVisible(); + await page.goForward(); + await expect(page).toHaveURL(/#no-language-required$/u); + await expect(custom.locator('summary')).toBeFocused(); + await custom.locator('summary').press('Space'); + await expect(custom.locator('details')).not.toHaveAttribute('open', ''); + evidence.push('Keyboard toggles, canonical clipboard links, same-fragment reopening and browser Back/Forward.'); + + // Query the actual emitted index for every stable identifier. No fixture search response. + const indexed = await page.evaluate(async expected => { + const engine = await import('/pagefind/pagefind.js'); + await engine.init(); + const observed = []; + for (const id of expected) { + const result = await engine.search(id); + const data = await Promise.all(result.results.map(hit => hit.data())); + const matches = data.filter(hit => hit.meta.kind === 'FAQ' && hit.meta.identifier === `#${id}`); + if (matches.length !== 1) throw new Error(`Expected one indexed FAQ answer for ${id}; got ${matches.length}`); + if (data.some(hit => new URL(hit.url, location.origin).pathname === '/faq/' && !new URL(hit.url, location.origin).hash)) throw new Error('Whole-page FAQ duplicate in search'); + observed.push({ id, url: matches[0].url, category: matches[0].meta.category, standing: matches[0].meta.standing }); + } + return observed; + }, records.map(record => record.id)); + assert.equal(indexed.length, 20); + assert.equal(indexed.find(record => record.id === 'extension-without-repo-setup').standing, 'In development'); + assert.ok(indexed.every(record => record.category && new URL(record.url, origin).hash === `#${record.id}`)); + await page.keyboard.press('Control+k'); + const input = page.locator('[data-search-input]'); + await input.fill('another analysis provider'); + const result = page.locator('.search-hit[data-kind="faq"][href$="#code-data"]'); + await expect(result).toBeVisible(); + await expect(result.locator('.search-faq-context')).toContainText('In development'); + await result.click(); + await expect(page.locator('[data-search-dialog]')).not.toBeVisible(); + await expect(page.locator('#code-data')).toBeVisible(); + await expect(page.locator('[data-faq-id="code-data"] summary')).toBeFocused(); + evidence.push('All 20 actual Pagefind records; visible FAQ kind/category/standing; search opens and focuses the answer outside the modal.'); + + // Resolve the real built destinations and fragments selected by the FAQ's Markdown links. + const links = await page.locator('.faq-answer a').evaluateAll(anchors => anchors.map(anchor => anchor.getAttribute('href'))); + for (const href of links) { + if (!href.startsWith('/')) continue; + const target = new URL(href, origin); + const response = await context.request.get(target.href); + assert.equal(response.status(), 200, href); + if (target.hash) { + const html = await response.text(); + assert.ok(html.includes(`id="${decodeURIComponent(target.hash.slice(1))}"`), href); + } + } + await page.goto(`${origin}/docs/actions/github-actions/`); + await expect(page.locator('a[href="/faq/#trusted-policy"]').first()).toBeVisible(); + await page.locator('a[href="/faq/#trusted-policy"]').first().click(); + await expect(page.locator('#trusted-policy')).toBeVisible(); + evidence.push('Rendered deeper links and fragments resolve; a contextual manual link opens the matching FAQ answer.'); + + for (const width of [320, 375, 640, 1080, 1180, 1280, 1440]) { + await page.setViewportSize({ width, height: 900 }); + await page.goto(`${origin}/faq/`); + assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1), `Horizontal overflow at ${width}`); + if (width <= 1080) { + await page.locator('[aria-controls="panel-menu"]').click(); + await expect(page.locator('#panel-menu a[href="/faq/"]')).toBeVisible(); + await page.keyboard.press('Escape'); + } + } + await page.setViewportSize({ width: 375, height: 850 }); + // Use the shared theme preference, not FAQ-specific theme state. + await page.emulateMedia({ colorScheme: 'light' }); + await page.evaluate(() => localStorage.setItem('diffdevil.theme', 'light')); + // A same-page hash navigation does not rerun the shared before-paint script. + await page.reload(); + await page.goto(`${origin}/faq/#code-data`); + await expect(page.locator('html')).toHaveAttribute('data-theme', 'light'); + await page.screenshot({ path: resolve(output, 'faq-light-mobile-answer.png') }); + await page.goto(`${origin}/faq/#%E0%A4%A`); + await expect(page.locator('h1')).toBeVisible(); + evidence.push('Responsive layout at 320–1440px, compact FAQ navigation, light/mobile deep link and malformed-fragment recovery.'); + + const plain = await browser.newContext({ javaScriptEnabled: false, viewport: { width: 1280, height: 900 } }); + const noScript = await plain.newPage(); + await noScript.goto(`${origin}/faq/`); + const featured = noScript.locator('[data-faq-id="beyond-size-labels"]'); + await expect(featured.locator('.faq-answer')).toBeVisible(); + await featured.locator('summary').click(); + await expect(featured.locator('.faq-answer')).toBeHidden(); + + const collapsed = noScript.locator('[data-faq-id="no-language-required"]'); + await expect(collapsed.locator('.faq-answer')).toBeHidden(); + await collapsed.locator('summary').click(); + await expect(collapsed.locator('.faq-answer')).toBeVisible(); + await plain.close(); + evidence.push('Server-rendered answer content and native disclosures work without JavaScript.'); + assert.deepEqual(failures, []); + await writeFile(resolve(output, 'result.json'), JSON.stringify({ passed: true, origin, browser: browser.version(), questions: records.length, evidence, indexed }, null, 2)); + console.log(`FAQ browser qualification passed: ${records.length} questions; ${evidence.length} exercised journeys.`); +} catch (error) { + await page?.screenshot({ path: resolve(output, 'faq-failure.png') }).catch(() => {}); + await writeFile(resolve(output, 'result.json'), JSON.stringify({ passed: false, evidence, failures, error: String(error?.stack ?? error) }, null, 2)); + throw error; +} finally { + await browser?.close(); + await new Promise(resolve => server.close(resolve)); +} diff --git a/apps/website/search-index.mjs b/apps/website/search-index.mjs new file mode 100644 index 00000000..9c6e2518 --- /dev/null +++ b/apps/website/search-index.mjs @@ -0,0 +1,34 @@ +// SPDX-License-Identifier: AGPL-3.0-only +import { readFile } from 'node:fs/promises'; +import * as pagefind from 'pagefind'; +import { fileURLToPath } from 'node:url'; +import { join } from 'node:path'; +import { faqRecords } from './faq-content.mjs'; + +// The locked Starlight toolchain already supplies Pagefind. Use its ESM API directly; +// CommonJS resolution does not support this package's import-only exports. +function checked(result, operation) { + if (result.errors?.length) throw new Error(`${operation}: ${result.errors.join('; ')}`); + return result; +} +/** One search index for selected site/manual bodies and independently linked FAQ answers. */ +export default function searchIndex() { + return { name: 'diffdevil-search', hooks: { + 'astro:build:done': async ({ dir, logger }) => { + const directory = fileURLToPath(dir); + // A page without this marker (legal pages or the complete FAQ) must not be + // indexed through header/footer text. FAQ entries supply their own body. + const { index } = checked(await pagefind.createIndex({ rootSelector: '[data-pagefind-body]' }), 'Create search index'); + if (!index) throw new Error('Pagefind returned no index.'); + try { + checked(await index.addDirectory({ path: directory }), 'Index site and manual'); + const questions = faqRecords(await readFile(join(directory, 'faq/index.html'), 'utf8')); + for (const question of questions) { + checked(await index.addHTMLFile({ url: question.url, content: question.html }), `Index FAQ ${question.id}`); + } + checked(await index.writeFiles({ outputPath: join(directory, 'pagefind') }), 'Write search index'); + logger.info(`Indexed ${questions.length} individual FAQ answers with site and manual pages.`); + } finally { await pagefind.close(); } + }, + } }; +} diff --git a/apps/website/src/components/Footer.astro b/apps/website/src/components/Footer.astro index 1de229e8..246fc3f4 100644 --- a/apps/website/src/components/Footer.astro +++ b/apps/website/src/components/Footer.astro @@ -1,6 +1,6 @@ --- // SPDX-License-Identifier: AGPL-3.0-only -// Footer. Product wording goes to the product page and action wording straight to the +// The same footer on every route. Product names link to the product page and action wording straight to the // action, here as everywhere. "Get" lists every way to obtain diffdevil, package and Action // first; "Learn" points into the manual, where a row may carry sibling links; socials are // icons only, never collapsed and complete (Works, Discord, Bluesky, GitHub). @@ -19,6 +19,7 @@ const learn: Item[][] = [ [['Extension', extensionDocs], ['GitHub App', docPaths.app]], [['CLI', docPaths.cli], ['Actions', docPaths.actions], ['Library API', docPaths.api]], [['Policies and detail', docPaths.policies]], [['Agent integration', docPaths.agents]], + [[copy.nav.faq, paths.faq]], ]; const project: Item[] = [['Source on GitHub', GITHUB], ['Releases', docPaths.releases], ['Security', paths.security], ['Licences', paths.licences], ['Privacy and data', paths.privacy], ['Impressum', paths.impressum]]; const rel = (href: string) => (href.startsWith('http') ? 'noopener' : undefined); diff --git a/apps/website/src/components/Header.astro b/apps/website/src/components/Header.astro index 7c609b25..9ff69aa8 100644 --- a/apps/website/src/components/Header.astro +++ b/apps/website/src/components/Header.astro @@ -3,7 +3,7 @@ // The one site header, identical on every route including the manual. It applies the // Wolfsblvt Works header grammar: // -// [brand + section label] [search] Docs Playground Examples Install⌄ │ [GitHub] [Community⌄] [Theme] [one action] +// [brand + section label] [search] Docs Playground Examples Install⌄ FAQ │ [GitHub] [Community⌄] [Theme] [one action] // // Identity → discovery → navigation → one divider → utilities → one trailing action. // · The section label sits outside the home link and is plain text. @@ -54,6 +54,7 @@ const installCurrent = current === 'app' || current === 'extension'; +
  • {copy.nav.faq}
    • @@ -64,6 +65,7 @@ const installCurrent = current === 'app' || current === 'extension';

    {copy.nav.install}

    +
    diff --git a/apps/website/src/data/copy.ts b/apps/website/src/data/copy.ts index 49d9fc59..97116605 100644 --- a/apps/website/src/data/copy.ts +++ b/apps/website/src/data/copy.ts @@ -7,7 +7,7 @@ */ export const copy = { nav: { - docs: 'Docs', playground: 'Playground', examples: 'Examples', menu: 'Menu', install: 'Install', dashboard: 'Dashboard', + docs: 'Docs', faq: 'FAQ', playground: 'Playground', examples: 'Examples', menu: 'Menu', install: 'Install', dashboard: 'Dashboard', command: 'npm i -D @wolfsblvt/diffdevil', copied: 'Copied ✓', source: 'Source on GitHub', }, /** Install⌄: a menu of the site's own pages. Every entry is [title, short description]. */ @@ -26,8 +26,8 @@ export const copy = { discord: ['Discord', 'Wolfsblvt Works community'], bluesky: ['Bluesky', 'Development updates'], works: ['Wolfsblvt Works', 'About the maker'], github: ['GitHub', 'Source code'], }, search: { - trigger: 'Search', title: 'Search diffdevil', placeholder: 'Search the site and the manual', close: 'Close search', - hint: 'Searches site pages and the manual. Every result says which one it is.', kindDocs: 'Docs', kindSite: 'Site', + trigger: 'Search', title: 'Search diffdevil', placeholder: 'Search the site, manual and FAQ', close: 'Close search', + hint: 'Searches site pages, the manual and individual FAQ answers.', kindDocs: 'Docs', kindSite: 'Site', kindFaq: 'FAQ', unavailable: 'The search index is part of the built site and is not available in this preview.', none: (query: string) => `Nothing found for "${query}".`, count: (total: number, shown: number) => (total > shown ? `${total} results · showing the first ${shown}` : `${total} result${total === 1 ? '' : 's'}`), diff --git a/apps/website/src/data/site.ts b/apps/website/src/data/site.ts index 24e49cea..3c92bc3e 100644 --- a/apps/website/src/data/site.ts +++ b/apps/website/src/data/site.ts @@ -54,6 +54,7 @@ export const paths = { playground: '/playground/', examples: '/examples/', docs: '/docs/', + faq: '/faq/', app: '/app/', extension: '/extension/', security: '/docs/security/', diff --git a/apps/website/src/layouts/Base.astro b/apps/website/src/layouts/Base.astro index 68c07f70..26d1bff8 100644 --- a/apps/website/src/layouts/Base.astro +++ b/apps/website/src/layouts/Base.astro @@ -11,11 +11,13 @@ import { themeScript } from '../lib/theme-script.mjs'; interface Props { title: string; description: string; /** The short top-level section label shown beside the lockup; never an article title. */ - surface?: 'Playground' | 'Docs' | 'Examples' | 'GitHub App' | 'Extension' | undefined; current?: string | undefined; + surface?: 'Playground' | 'Docs' | 'Examples' | 'GitHub App' | 'Extension' | 'FAQ' | undefined; current?: string | undefined; /** Legal routes stay public and fetchable but out of search engines, snippets and the site's own search. */ noindex?: boolean | undefined; + /** False when the page supplies finer-grained global search records instead. */ + siteSearch?: boolean | undefined; } -const { title, description, surface, current, noindex = false } = Astro.props; +const { title, description, surface, current, noindex = false, siteSearch = true } = Astro.props; const pageTitle = title === 'diffdevil' ? 'diffdevil — The devil is in the diff.' : `${title} · diffdevil`; const canonical = ORIGIN_IS_PLACEHOLDER ? undefined : `${ORIGIN}${Astro.url.pathname}`; --- @@ -45,7 +47,7 @@ const canonical = ORIGIN_IS_PLACEHOLDER ? undefined : `${ORIGIN}${Astro.url.path
    -
    +