From 0bb67b12fa81871ddd735904896fd16589aeb548 Mon Sep 17 00:00:00 2001 From: Stefan Bauer Date: Mon, 16 Nov 2026 10:30:25 +0100 Subject: [PATCH 1/7] feat(storefront): list generated pages under their layout in the workbench LayoutPageUse gains the source "generated" for a tag or category page and the index of them, naming what generated it (kind and term). A layout's Relationships tab lists them after the page files, by route. The detail route now reads the page model with the discovery map, so the term pages are in it. --- apps/dev-ui/src/inspector/panel.ts | 13 ++++++++++--- packages/contracts/src/dev-protocol.ts | 19 +++++++++++++++++-- packages/dev-server/src/routes.ts | 3 ++- packages/dev-server/src/storefront/pages.ts | 8 ++++++-- .../dev-server/test/storefront-bench.spec.ts | 4 ++++ .../dev-server/test/storefront-build.spec.ts | 18 ++++++++++++------ storefront-bench/e2e/workbench.spec.ts | 16 ++++++++++++++++ 7 files changed, 67 insertions(+), 14 deletions(-) diff --git a/apps/dev-ui/src/inspector/panel.ts b/apps/dev-ui/src/inspector/panel.ts index 2946f2b..9be4368 100644 --- a/apps/dev-ui/src/inspector/panel.ts +++ b/apps/dev-ui/src/inspector/panel.ts @@ -147,9 +147,16 @@ export async function renderPanel(): Promise { appendComponentGroup("Used by", relAvail.usedBy, section); // A layout of a project with a website: the pages that render with it, and where each got its layout. if (relAvail.pages) { - appendPlainGroup("Pages", relAvail.pages.map(p => `${p.path} (${ - p.source === "own" ? "its own layout" : p.source === "default" ? "the default layout" : `childLayout of ${p.from ?? "its folder"}` - })`), section); + appendPlainGroup("Pages", relAvail.pages.map(p => { + if (p.source === "generated") { + const kind = p.generated.kind; + const what = p.generated.term !== undefined ? `the page of the ${kind} "${p.generated.term}"` : `the index of the ${kind === "tag" ? "tags" : "categories"}`; + return `${p.route} (${what}, from storefront.${kind}Pages)`; + } + return `${p.path} (${ + p.source === "own" ? "its own layout" : p.source === "default" ? "the default layout" : `childLayout of ${p.from ?? "its folder"}` + })`; + }), section); } // Style umbrella: groups Style uses + Style modules under a shared heading. diff --git a/packages/contracts/src/dev-protocol.ts b/packages/contracts/src/dev-protocol.ts index 06b1f86..b152c34 100644 --- a/packages/contracts/src/dev-protocol.ts +++ b/packages/contracts/src/dev-protocol.ts @@ -483,8 +483,12 @@ export interface RelationshipsAvailable { pages?: LayoutPageUse[]; } -/** A storefront page that renders with a layout, and where its layout came from. */ -export interface LayoutPageUse { +/** A storefront page that renders with a layout, and where its layout came from: a page file, or a page Pattern Dump + * generated. */ +export type LayoutPageUse = LayoutFilePageUse | LayoutGeneratedPageUse; + +/** A page of the pages folder that renders with a layout. */ +export interface LayoutFilePageUse { route: string; /** The page file, relative to the pages folder ("articles/one.md"). */ path: string; @@ -495,6 +499,17 @@ export interface LayoutPageUse { from?: string; } +/** A page Pattern Dump generated (a tag's or category's page, or the index of them: storefront.tagPages, + * storefront.categoryPages), which has no file. Its layout is the one of its kind (layouts/tag, tags, category, + * categories). */ +export interface LayoutGeneratedPageUse { + route: string; + source: "generated"; + /** What generated it: the tag or category whose page it is (`term`, its key), or without `term` the index of + * that kind. */ + generated: { kind: "tag" | "category"; term?: string }; +} + export type Relationships = RelationshipsAvailable; /** diff --git a/packages/dev-server/src/routes.ts b/packages/dev-server/src/routes.ts index 80e455e..912f45e 100644 --- a/packages/dev-server/src/routes.ts +++ b/packages/dev-server/src/routes.ts @@ -481,7 +481,8 @@ async function routeRequest( // 200 + RENDER_ERROR, not 404. // A layout of a project with a website: the pages that render with it, and where each got it. if (cfg.storefront && /^layouts\/[^/~]+$/.test(componentId)) { - detail.relationships.pages = layoutPages(await readStorefrontPages(ctx, cfg.storefront), componentId.slice("layouts/".length)); + // With the discovery map, so the tag and category pages its layouts generate are in the model too. + detail.relationships.pages = layoutPages(await readStorefrontPages(ctx, cfg.storefront, discovery.discoveryMap), componentId.slice("layouts/".length)); } const quarantineEntry = discovery.quarantineMap.get(componentId); const { previewHtml, diagnostics } = await checkComponent(componentId, variant, render, quarantineEntry); diff --git a/packages/dev-server/src/storefront/pages.ts b/packages/dev-server/src/storefront/pages.ts index 06c7466..91a86ac 100644 --- a/packages/dev-server/src/storefront/pages.ts +++ b/packages/dev-server/src/storefront/pages.ts @@ -118,12 +118,16 @@ export interface PageModel extends StorefrontPagesResponse { /** The pages that render with the layout `name`, by path, each with where it got it (the workbench's Relationships). */ export function layoutPages(model: PageModel, name: string): LayoutPageUse[] { - // A generated tag or category page has no file: not listed yet (contracts' LayoutPageUse has no source for it). - return model.pages.filter(p => p.layout === name && model.files.has(p.route)).map(p => { + const files = model.pages.filter(p => p.layout === name && model.files.has(p.route)).map(p => { const f = model.files.get(p.route)!; const source = p.layoutFrom !== undefined ? "folder" : f.frontmatter.values["layout"] !== undefined ? "own" : "default"; return { route: p.route, path: f.path, source, ...(p.layoutFrom !== undefined ? { from: p.layoutFrom } : {}) } satisfies LayoutPageUse; }).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0); + // A tag or category page, or an index of them, has no file: after the files, by route, with what generated it. + const generated = [...model.generated.values()].filter(g => g.layout === name) + .map(g => ({ route: g.route, source: "generated", generated: { kind: g.kind, ...(g.term ? { term: g.term.key } : {}) } }) satisfies LayoutPageUse) + .sort((a, b) => a.route < b.route ? -1 : a.route > b.route ? 1 : 0); + return [...files, ...generated]; } /** "guides/setup.md" -> "/guides/setup/", "index.md" -> "/", "guides/index.md" -> "/guides/". */ diff --git a/packages/dev-server/test/storefront-bench.spec.ts b/packages/dev-server/test/storefront-bench.spec.ts index c260741..6a3fcb4 100644 --- a/packages/dev-server/test/storefront-bench.spec.ts +++ b/packages/dev-server/test/storefront-bench.spec.ts @@ -129,6 +129,10 @@ describe("storefront bench in the workbench", () => { { route: "/guides/setup/", path: "guides/setup.md", source: "own" }, ]); expect(await pagesOf("layouts/page")).toEqual([{ route: "/guides/", path: "guides/index.md", source: "default" }]); + // A generated page: by route, with what generated it (a term's page, or the index of its kind). + expect(await pagesOf("layouts/tag")).toEqual(["design", "images", "layout"].map(t => + ({ route: `/tags/${t}/`, source: "generated", generated: { kind: "tag", term: t } }))); + expect(await pagesOf("layouts/tags")).toEqual([{ route: "/tags/", source: "generated", generated: { kind: "tag" } }]); // Not a layout: no pages at all. expect(await pagesOf("components/card")).toBeUndefined(); }); diff --git a/packages/dev-server/test/storefront-build.spec.ts b/packages/dev-server/test/storefront-build.spec.ts index 2f07122..7eda60a 100644 --- a/packages/dev-server/test/storefront-build.spec.ts +++ b/packages/dev-server/test/storefront-build.spec.ts @@ -282,13 +282,19 @@ describe("pd build — the storefront root", () => { // A layout's detail lists the pages that render with it (relationships.pages), which only a site has: that, and // nothing else, differs. const layouts = ["article", "doc", "home", "listing", "page"].map(l => `api/component/layouts/${l}/index.json`); - // The generated pages' layouts list none yet (a generated page has no source in contracts' LayoutPageUse): with a - // site their list is there, and empty. - const generated = ["categories", "category", "tag", "tags"].map(l => `api/component/layouts/${l}/index.json`); - expect(differing.sort()).toEqual([...layouts, ...generated].sort()); - for (const k of generated) { + // The generated pages' layouts list the tag and category pages and their indexes, each with what generated it. + const generated: Record = { + categories: [{ route: "/categories/", source: "generated", generated: { kind: "category" } }], + category: ["design-systems", "guides"].map(t => ({ route: `/categories/${t}/`, source: "generated", generated: { kind: "category", term: t } })), + tag: ["design", "images", "layout"].map(t => ({ route: `/tags/${t}/`, source: "generated", generated: { kind: "tag", term: t } })), + tags: [{ route: "/tags/", source: "generated", generated: { kind: "tag" } }], + }; + const generatedKeys = Object.keys(generated).map(l => `api/component/layouts/${l}/index.json`); + expect(differing.sort()).toEqual([...layouts, ...generatedKeys].sort()); + for (const [l, pages] of Object.entries(generated)) { + const k = `api/component/layouts/${l}/index.json`; const withSite = JSON.parse(a.get(k)!.bytes.toString("utf8")) as { relationships: { pages?: unknown[] } }; - expect(withSite.relationships.pages, k).toEqual([]); + expect(withSite.relationships.pages, k).toEqual(pages); delete withSite.relationships.pages; expect(withSite, k).toEqual(JSON.parse(b.get(k)!.bytes.toString("utf8"))); } diff --git a/storefront-bench/e2e/workbench.spec.ts b/storefront-bench/e2e/workbench.spec.ts index 4e3ba9a..34de3bc 100644 --- a/storefront-bench/e2e/workbench.spec.ts +++ b/storefront-bench/e2e/workbench.spec.ts @@ -59,6 +59,22 @@ test.describe("the skin in the workbench", () => { .toHaveText(["about.md (its own layout)", "articles/plain.md (its own layout)", "guides/setup.md (its own layout)"]); }); + // A generated tag or category page has no file: listed by route, with what generated it. + test("lists the generated tag pages and their index under their layouts", async ({ page }) => { + const itemsOf = async (id: string) => { + await page.goto(`${WORKBENCH}/${id}`); + await page.waitForSelector("#preview-frame[srcdoc]"); + await page.click("button[data-tab='relationships']"); + return page.locator(".rel-panel .rel-group-heading", { hasText: /^Pages$/ }).locator("xpath=following-sibling::ul[1]").locator(".rel-item"); + }; + await expect(await itemsOf("layouts/tag")).toHaveText([ + `/tags/design/ (the page of the tag "design", from storefront.tagPages)`, + `/tags/images/ (the page of the tag "images", from storefront.tagPages)`, + `/tags/layout/ (the page of the tag "layout", from storefront.tagPages)`, + ]); + await expect(await itemsOf("layouts/categories")).toHaveText(["/categories/ (the index of the categories, from storefront.categoryPages)"]); + }); + test("shows no Pages group on a component that is not a layout", async ({ page }) => { await page.goto(`${WORKBENCH}/components/card`); await page.waitForSelector("#preview-frame[srcdoc]"); From 0d1213269a8bf4a889db1307b8f7198c23b6b9df Mon Sep 17 00:00:00 2001 From: Stefan Bauer Date: Mon, 16 Nov 2026 10:31:08 +0100 Subject: [PATCH 2/7] test: every E2E spec file is matched by a Playwright project A spec that no project's testMatch takes never runs, and its suite stays green without it. The script tests now list each Playwright config's files and fail naming any tracked spec none of its projects matches. --- package.json | 2 +- scripts/e2e-specs.test.mjs | 45 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 scripts/e2e-specs.test.mjs diff --git a/package.json b/package.json index c57d798..d8ee9d4 100644 --- a/package.json +++ b/package.json @@ -46,7 +46,7 @@ "e2e:storefront": "nx run storefront-bench:e2e", "e2e:package-bench": "nx run package-bench:e2e", "dev:check": "node scripts/check-server-fresh.mjs", - "test:scripts": "node --test scripts/ci/burn-in.test.mjs scripts/no-em-dash.test.mjs", + "test:scripts": "node --test scripts/ci/burn-in.test.mjs scripts/no-em-dash.test.mjs scripts/e2e-specs.test.mjs", "burn-in": "node scripts/ci/burn-in.mjs", "pack:pd": "npm run build && node packages/cli/scripts/pack.mjs", "verify:install": "node scripts/verify-install.mjs", diff --git a/scripts/e2e-specs.test.mjs b/scripts/e2e-specs.test.mjs new file mode 100644 index 0000000..67f31d2 --- /dev/null +++ b/scripts/e2e-specs.test.mjs @@ -0,0 +1,45 @@ +// Every E2E spec runs: each tracked *.spec.ts under a Playwright config's folder is matched by at least one of that +// config's projects. A spec no project matches never runs, and its suite stays green without it +// (storefront-bench/e2e/categories.spec.ts, step 4 of 0.5.0). The matching is Playwright's own: `playwright test +// --list` reports the files each project takes, without starting a server. +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { dirname, relative, resolve } from "node:path"; + +const ROOT = resolve(import.meta.dirname, ".."); +const CONFIGS = [ + "apps/dev-ui/e2e/playwright.config.ts", + "storefront-bench/e2e/playwright.config.ts", + "skins/experimental/e2e/playwright.config.ts", + "package-bench/e2e/playwright.config.ts", +]; + +/** The spec files Playwright lists for `config`, relative to the repository. */ +function listed(config) { + const out = execFileSync(process.execPath, [resolve(ROOT, "node_modules/playwright/cli.js"), "test", "--list", "--reporter=json", "-c", config], + { cwd: ROOT, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }); + const report = JSON.parse(out); + const rootDir = report.config.rootDir; + const files = new Set(); + const walk = suite => { + if (suite.file) files.add(relative(ROOT, resolve(rootDir, suite.file))); + for (const s of suite.specs ?? []) files.add(relative(ROOT, resolve(rootDir, s.file))); + for (const s of suite.suites ?? []) walk(s); + }; + for (const s of report.suites) walk(s); + return files; +} + +/** The tracked spec files under `dir`. */ +const tracked = dir => execFileSync("git", ["ls-files", "-z", `${dir}/**/*.spec.ts`, `${dir}/*.spec.ts`], { cwd: ROOT, encoding: "utf-8" }) + .split("\0").filter(Boolean); + +for (const config of CONFIGS) { + test(`every E2E spec under ${dirname(config)} is matched by a Playwright project`, () => { + const runs = listed(config); + const unmatched = [...new Set(tracked(dirname(config)))].filter(f => !runs.has(f)) + .map(f => `${f} is matched by no project in ${config}: add it to a project's testMatch`); + assert.deepEqual(unmatched, []); + }); +} From c597131b9d1e4d27583f41491132922807307e99 Mon Sep 17 00:00:00 2001 From: Stefan Bauer Date: Mon, 16 Nov 2026 10:41:36 +0100 Subject: [PATCH 3/7] feat(storefront): pd build writes llms.txt The site for language models, in the llmstxt.org format: the site's title and the home page's description, then the top-level pages and one section per collection, each page with its title, link and teaser. The same pages as the sitemap (no drafts, scheduled pages or index: false), absolute URLs with storefront.url, under the site's path. On unless the site has index: false; storefront.llms: false turns it off. --- CHANGELOG.md | 3 + docs/guide/configuration.md | 1 + docs/guide/storefront.md | 10 +++ packages/config/src/index.ts | 6 ++ packages/config/src/validate.spec.ts | 6 ++ packages/config/src/validate.ts | 1 + packages/core/src/index.ts | 1 + packages/dev-server/src/server-config.ts | 3 + packages/dev-server/src/static-build.ts | 19 ++++- .../dev-server/src/storefront/site-files.ts | 42 ++++++++++- .../test/storefront-base-path-build.spec.ts | 10 +++ .../dev-server/test/storefront-build.spec.ts | 72 ++++++++++++++++++- 12 files changed, 170 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fde2ae..a5a2a5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,9 @@ ### Added +- **`llms.txt`.** `pd build` writes one at the site's root (llmstxt.org): the site's title and description, then + the top-level pages and each collection, every page with its title, link and teaser. The same pages as the sitemap; + absolute URLs with `storefront.url`, under the site's path. On by default; `storefront.llms: false` turns it off. - **Regions.** A layout declares regions besides the body on `page.regions` (`"x-pd-regions": ["sidebar"]`) and writes each as `{{{page.regions.sidebar}}}`, null when the page puts nothing there. A placed component goes into one with `region="sidebar"` on its tag, or its schema's `"x-pd-region"`; components keep the page's order there. A region diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index cf1b6bf..05f8a70 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -189,6 +189,7 @@ in [storefront.md](storefront.md). | `storefront.tagPages` | boolean or object | on when the skin has `layouts/tag` | A page per tag at `/tags//` and an index at `/tags/`. `false`: off; `true` or `{ path, title }`: on, and a missing layout is a problem ([storefront.md](storefront.md#tag-and-category-pages)) | | `storefront.categoryPages` | boolean or object | on when the skin has `layouts/category` | The same for categories, at `/categories/` | | `storefront.search` | boolean | on when the project has Pagefind | Search: `pd build` indexes every page's own content with Pagefind into `_pd/search/`. `true`: a build without Pagefind stops; `false`: off ([storefront.md](storefront.md#search)) | +| `storefront.llms` | boolean | `true` (`false` with `index: false`) | `pd build` writes `llms.txt` at the site's root: the site's title and description and each page's title, link and teaser, by collection ([storefront.md](storefront.md#search-engines-and-link-previews)). `false`: none | | `storefront.site` | object | (none) | Values every page shares, such as the site's title or footer line. Every layout gets them as `site`, and a page cannot set them. Their keys and types are what the `site` property of `partials/base`'s schema declares, and they are checked against it. One key is Pattern Dump's: `navigations`, named lists of links ([storefront.md](storefront.md#declared-navigations)) | ## When changes take effect diff --git a/docs/guide/storefront.md b/docs/guide/storefront.md index 380a3d5..cdc066b 100644 --- a/docs/guide/storefront.md +++ b/docs/guide/storefront.md @@ -999,6 +999,15 @@ redirect pages, each with a `lastmod` of its `updated`, else its `date`, else no shallow clone, a `datePublished` git would give is left out of the JSON-LD and the build notes it once (in CI, check out with `fetch-depth: 0`). A layout that shows `page.created` still fails the build there. +**`llms.txt`** ([llmstxt.org](https://llmstxt.org/)) gives a language model the site in one file: the site's title +(`storefront.site.title`, else the home page's) and the home page's description as a quote, then a `## Pages` section +with the top-level pages and one section per collection (a folder with an `index.md`, headed by its title and led by +it), in nav order. Each page is a line `- [title](url): teaser`, its description else its first paragraph. It lists +the same pages as the sitemap (no draft, no scheduled page, none with `index: false`); tag and category pages are left +out, since their pages are listed. URLs are absolute with `storefront.url`, else paths from the site's root. `pd +build` writes it to the site's root (under a path, at `llms.txt`); `pd dev` has none. On unless the site has +`index: false`; `storefront.llms: false` turns it off. + **`robots.txt`.** Both output roots get one. The storefront's keeps crawlers out of `/preview/` (the live examples: component demos, not pages) and names the sitemap. The workbench's keeps them out of its previews only; the workbench itself stays searchable. A workbench on the storefront's own host @@ -1097,6 +1106,7 @@ site/ 404.html the 404 page setup/index.html start/index.html pages that forward from old routes robots.txt sitemap.xml for crawlers (the sitemap with storefront.url) + llms.txt the site for language models preview/components/callout/index.html the previews the pages show _pd/ assets/ what pages and previews reference .nojekyll diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts index 894203f..b8dda40 100644 --- a/packages/config/src/index.ts +++ b/packages/config/src/index.ts @@ -261,6 +261,12 @@ export interface StorefrontConfig { * `true`: on, and a build without Pagefind stops. `false`: off. The search UI is a component of the skin's. */ search?: boolean; + /** + * llms.txt (llmstxt.org): pd build writes one at the site's root, with the site's title and description and each + * page's title, link and teaser, by collection; the same pages as the sitemap. Left out: on, unless `index` is + * false. `false`: none. + */ + llms?: boolean; } /** storefront.tagPages and storefront.categoryPages as an object. */ diff --git a/packages/config/src/validate.spec.ts b/packages/config/src/validate.spec.ts index 1b3d094..0b9e4c8 100644 --- a/packages/config/src/validate.spec.ts +++ b/packages/config/src/validate.spec.ts @@ -265,6 +265,12 @@ describe("configProblems — storefront", () => { expect(storefront({ ...base, search: "pagefind" })).toEqual([`"storefront.search" must be true or false`]); }); + it("takes llms: true or false", () => { + const base = { pagesDir: "./pages", outDir: "./www" }; + expect(storefront({ ...base, llms: false })).toEqual([]); + expect(storefront({ ...base, llms: "no" })).toEqual([`"storefront.llms" must be true or false`]); + }); + it("takes tagPages and categoryPages: true, false, or { path, title }", () => { const base = { pagesDir: "./pages", outDir: "./www" }; for (const ok of [true, false, {}, { path: "topics" }, { title: "Topics" }, { path: "t2", title: "All tags" }]) { diff --git a/packages/config/src/validate.ts b/packages/config/src/validate.ts index c719e73..93447af 100644 --- a/packages/config/src/validate.ts +++ b/packages/config/src/validate.ts @@ -64,6 +64,7 @@ const SHAPE: Shape = { pagesDir: "string", outDir: "string", host: "host", workbenchUrl: "workbench-url", site: "plain-object", url: "site-url", lang: "lang", index: "boolean", image: "asset-path", images: IMAGES, head: "hbs-file", categories: "categories", tags: "tags", tagPages: "term-pages", categoryPages: "term-pages", search: "boolean", + llms: "boolean", }, required: ["pagesDir", "outDir"], }, diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index feb27d0..87fc14d 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -65,6 +65,7 @@ export async function runBuild( console.log(`[pd build] images: ${n ? `${n} with a variant that doesn't fit:` : "every variant fits its box"}`); for (const w of report.images.warnings) console.log(`[pd build] warning: ${w}`); } + if (report.llms) console.log(`[pd build] llms.txt: ${report.llms.pages} pages`); if (report.search) { console.log(`[pd build] search: ${report.search.pages} pages indexed → ${report.search.files} files in _pd/search/ (${(report.search.bytes / 1024).toFixed(0)} KB)`); } diff --git a/packages/dev-server/src/server-config.ts b/packages/dev-server/src/server-config.ts index fc14f6d..16c953d 100644 --- a/packages/dev-server/src/server-config.ts +++ b/packages/dev-server/src/server-config.ts @@ -107,6 +107,8 @@ export interface ResolvedConfig { /** storefront.tagPages and storefront.categoryPages, as the config writes them (terms.ts reads them). */ readonly tagPages: boolean | StorefrontTermPages | undefined; readonly categoryPages: boolean | StorefrontTermPages | undefined; + /** storefront.llms: pd build writes llms.txt; false for a site with index: false. */ + readonly llms: boolean; /** storefront.search as the config writes it (search.ts reads it). */ readonly search: boolean | undefined; } | null; @@ -253,6 +255,7 @@ export function resolveServerConfig( tagPages: config.storefront.tagPages, categoryPages: config.storefront.categoryPages, search: config.storefront.search, + llms: config.storefront.index !== false && config.storefront.llms !== false, } : null, images, overviewsEnabled: config.overviews !== false, diff --git a/packages/dev-server/src/static-build.ts b/packages/dev-server/src/static-build.ts index 4382664..3058a13 100644 --- a/packages/dev-server/src/static-build.ts +++ b/packages/dev-server/src/static-build.ts @@ -31,7 +31,7 @@ import { checkLinks, linkedWorkbenchRoutes } from "./storefront/links.js"; import { checkPageBasics } from "./storefront/page-basics.js"; import { loadProjectPlaywright, runBrowserChecks, VIEWPORTS, type PlaywrightModule } from "./storefront/browser-checks.js"; import { runPageA11y, type PageA11yFinding } from "@pattern-dump/a11y"; -import { workbenchRobotsTxt } from "./storefront/site-files.js"; +import { llmsTxt, workbenchRobotsTxt } from "./storefront/site-files.js"; import { withNoindex } from "./storefront/base-path.js"; import { buildSearchIndex, SEARCH_PATH, searchPagefind, type PagefindModule, type SearchRecord } from "./storefront/search.js"; @@ -84,6 +84,8 @@ export interface StaticBuildReport { /** The storefront's search index (search.ts), written to its _pd/search/: the pages in it, and its files. Absent * when the site has no search. */ search?: { pages: number; files: number; bytes: number }; + /** llms.txt, at the site's root: how many pages it lists. Absent when none is written (storefront.llms). */ + llms?: { pages: number }; /** `--browser`: one line per image whose chosen variant doesn't fit the box it is laid out in. */ images?: { warnings: string[] }; /** The storefront's drafts left out of the build (a draft, and each page under a draft folder's index.md), by @@ -429,6 +431,19 @@ export async function buildStaticSite( counts.bytes += bytes; report.search = { pages: searchRecords.size, files: searchFiles.size, bytes }; } + // The pages as this build has them (no draft, no scheduled page): llms.txt, and the report's drafts and scheduled. + const model = await readPages(storefront.pagesDir, { + drafts: "leave-out", scheduled: "leave-out", today, categories: storefront.categories, tags: storefront.tags, + }); + if (storefront.llms) { + const siteTitle = typeof storefront.site?.["title"] === "string" ? storefront.site["title"] : undefined; + const llms = llmsTxt(model, { title: siteTitle, siteUrl: storefront.url }); + const bytes = Buffer.from(llms.text, "utf8"); + await writeFile(join(sfOut, "llms.txt"), bytes); + counts.files++; + counts.bytes += bytes.byteLength; + report.llms = { pages: llms.pages }; + } const stubs = new Set((await (await sfGet(PD_ROUTES.pages)).json() as StorefrontPagesResponse).pages.flatMap(p => p.redirectFrom ?? [])); const pages = sfCrawl.urls.filter(u => !/^\/(?:_pd|assets|preview)\//.test(u) && !sfFiles.includes(u) && !stubs.has(u)).length; report.storefront = { outDir: sfOut, basePath: sfBase, pages, files: counts.files, bytes: counts.bytes }; @@ -450,7 +465,7 @@ export async function buildStaticSite( if (linkSummary) report.links = linkSummary; if (a11ySummary) report.accessibility = a11ySummary; if (imageSummary) report.images = imageSummary; - const { drafts, scheduled } = await readPages(storefront.pagesDir, { drafts: "leave-out", scheduled: "leave-out", today }); + const { drafts, scheduled } = model; if (drafts.length) report.drafts = drafts; if (scheduled.length) report.scheduled = scheduled; log(`… storefront: ${pages} pages, ${counts.files} files`); diff --git a/packages/dev-server/src/storefront/site-files.ts b/packages/dev-server/src/storefront/site-files.ts index 0309def..d726fc3 100644 --- a/packages/dev-server/src/storefront/site-files.ts +++ b/packages/dev-server/src/storefront/site-files.ts @@ -1,5 +1,6 @@ // The storefront's files for crawlers, at the root of its host: robots.txt, and sitemap.xml when the site has -// an address (storefront.url). Both are text built from the page model on every request, never stored. +// an address (storefront.url). Both are text built from the page model on every request, never stored. And +// llms.txt, for language models, which only pd build writes. import type { PageModel } from "./pages.js"; @@ -32,6 +33,45 @@ export function sitemapXml(entries: readonly SitemapEntry[]): string { + `${urls.map(u => `${u}\n`).join("")}\n`; } +/** + * llms.txt (llmstxt.org), which pd build writes: `# `, the home page's description (or teaser) as a quote, + * then `## Pages` (the top-level pages but the home page) and a section per collection (a folder with an index.md, + * headed by its title and led by it), in nav order. Each page is `- [title](url): teaser`, its description else its + * first paragraph; no `: ` part when it has neither. The same pages as the sitemap: no draft, no scheduled page, no + * page with `index: false`; a section with none left is not written. Tag and category pages are left out: they have + * no content of their own, and their pages are listed. `siteUrl`: absolute URLs; without it, the route. + */ +export function llmsTxt(model: PageModel, o: { title: string | undefined; siteUrl: string | undefined }): { text: string; pages: number } { + const titles = new Map(model.pages.map(p => [p.route, p.title])); + const listed = (route: string): boolean => { + const file = model.files.get(route), entry = model.entries.get(route); + return !!file && !!entry && !entry.draft && !entry.scheduled && file.frontmatter.values["index"] !== "false"; + }; + const oneLine = (s: string): string => s.replace(/\s+/g, " ").trim(); + const linkText = (s: string): string => oneLine(s).replace(/[[\]\\]/g, m => `\\${m}`); + const href = (route: string): string => o.siteUrl !== undefined ? new URL(route.slice(1), o.siteUrl).href : route; + const line = (route: string): string => { + const teaser = model.entries.get(route)?.description; + return `- [${linkText(titles.get(route) ?? route)}](${href(route)})${teaser ? `: ${oneLine(teaser)}` : ""}`; + }; + const pagesOf = (folder: string): string[] => (model.folders.get(folder)?.children ?? []).filter(r => r !== "/" && !model.folders.has(r)); + const sections: { heading: string; routes: string[] }[] = [{ heading: "Pages", routes: pagesOf("/") }]; + for (const p of model.pages) { + if (p.route !== "/" && model.folders.has(p.route)) sections.push({ heading: p.title, routes: [p.route, ...pagesOf(p.route)] }); + } + const out = [`# ${oneLine(o.title ?? titles.get("/") ?? "Site")}`, ""]; + const about = listed("/") ? model.entries.get("/")?.description : null; + if (about) out.push(`> ${oneLine(about)}`, ""); + let pages = 0; + for (const s of sections) { + const routes = s.routes.filter(listed); + if (!routes.length) continue; + pages += routes.length; + out.push(`## ${oneLine(s.heading)}`, "", ...routes.map(line), ""); + } + return { text: out.join("\n"), pages }; +} + /** * The workbench's robots.txt: the workbench stays searchable, its previews (/preview/ under the base path) do * not. Crawlers read robots.txt only at a host's root, so under a base path other than "/" the file in the diff --git a/packages/dev-server/test/storefront-base-path-build.spec.ts b/packages/dev-server/test/storefront-base-path-build.spec.ts index 002601a..6f8e0c0 100644 --- a/packages/dev-server/test/storefront-base-path-build.spec.ts +++ b/packages/dev-server/test/storefront-base-path-build.spec.ts @@ -90,6 +90,16 @@ describe("pd build — a storefront under a path", () => { expect(underPath.get("about/index.html")).toContain(`<link rel="canonical" href="https://bench.example.test/sub/about/">`); }); + it("writes llms.txt at the site's own root, every link under the path", () => { + const llms = underPath.get("llms.txt")!; + expect(llms).toContain("- [About](https://bench.example.test/sub/about/): What the bench is for.\n"); + const links = [...llms.matchAll(/\]\(([^)]+)\)/g)].map(m => m[1]!); + expect(links.length).toBe(6); + for (const l of links) expect(l, l).toMatch(/^https:\/\/bench\.example\.test\/sub\/[a-z]/); + // The same text as at the root, but for the path. + expect(llms).toBe(atRoot.get("llms.txt")!.replaceAll("https://bench.example.test/", "https://bench.example.test/sub/")); + }); + it("says what the host's own robots.txt needs", () => { expect(report.notes).toContain("robots.txt is not written: the site is published under /sub/, and crawlers read robots.txt only at a " + "host's root. Where you can, add to the host's own robots.txt: Disallow: /sub/preview/; Sitemap: https://bench.example.test/sub/sitemap.xml"); diff --git a/packages/dev-server/test/storefront-build.spec.ts b/packages/dev-server/test/storefront-build.spec.ts index 7eda60a..80dcc12 100644 --- a/packages/dev-server/test/storefront-build.spec.ts +++ b/packages/dev-server/test/storefront-build.spec.ts @@ -115,6 +115,7 @@ describe("pd build — the storefront root", () => { "guides/index.html", "guides/setup/index.html", "index.html", + "llms.txt", "preview/components/callout/index.html", "preview/components/callout~warning/index.html", "robots.txt", @@ -129,7 +130,9 @@ describe("pd build — the storefront root", () => { "tags/layout/index.html", "tags/pictures/index.html", ]); - expect(report.storefront).toEqual({ outDir: join(root, ".out", "storefront"), basePath: "/", pages: 14, files: 50, bytes: expect.any(Number) }); + expect(report.storefront).toEqual({ outDir: join(root, ".out", "storefront"), basePath: "/", pages: 14, files: 51, bytes: expect.any(Number) }); + // llms.txt lists six pages: every page of the folder but the home page, whose title and description head it. + expect(report.llms).toEqual({ pages: 6 }); }); it("notes a heading whose anchor the layout has, and leaves nothing out for it", () => { @@ -220,6 +223,37 @@ describe("pd build — the storefront root", () => { for (const loc of locs) expect(loc.length).toBeLessThanOrEqual(2048); }); + // llmstxt.org: the site's title and description, then a section of the top-level pages and one per collection (a + // folder with an index.md, led by it), each page's title, link and teaser. Tag and category pages are left out. + it("writes llms.txt: the site, then each collection's pages with their teasers", () => { + const llms = files.get("llms.txt")!.bytes.toString("utf8"); + const at = (route: string) => `https://bench.example.test${route}`; + expect(llms).toBe([ + "# Storefront bench", + "", + "> A small website rendered from markdown, with the bench's own skin.", + "", + "## Pages", + "", + `- [About](${at("/about/")}): What the bench is for.`, + "", + "## Guides", + "", + `- [Guides](${at("/guides/")}): Longer texts about the bench.`, + `- [Setup](${at("/guides/setup/")}): How the bench is put together.`, + "", + "## Articles", + "", + `- [Articles](${at("/articles/")}): Everything written for the bench, newest first.`, + `- [A harbour of cable cars](${at("/articles/harbour/")}): This article has no description, so its listing shows this first ` + + "paragraph instead: the text of the page as it starts, without its markup, never shortened in the data. The card in the " + + "listing limits it to three lines.", + `- [Plain on purpose](${at("/articles/plain/")}): Why the bench's skin is a wireframe.`, + "", + ].join("\n")); + expect(llms).not.toMatch(/\/tags\/|\/categories\//); + }); + it("writes a page that forwards at each of a page's old routes, out of the sitemap", () => { for (const old of ["setup", "start"]) { const html = files.get(`${old}/index.html`)!.bytes.toString("utf8"); @@ -500,6 +534,42 @@ describe("pd build — the storefront's settings", () => { await build(root, join(root, "..", "wb-base-cfg-ok"), withBase("/workbench/")); }, 60_000); + it("leaves drafts, scheduled pages and pages with index: false out of llms.txt", async () => { + const root = await benchCopy(); + const edit = async (path: string, from: string, to: string) => { + const file = join(root, "pages", path); + await save(file, (await readFile(file, "utf8")).replace(from, to)); + }; + await edit("guides/setup.md", "title: Setup\n", "title: Setup\nindex: false\n"); + await edit("articles/harbour.md", "date: 2026-11-01\n", "date: 2026-11-01\ndraft: true\n"); + // After the build's day (NOW): scheduled, so left out. + await edit("articles/plain.md", "date: 2026-10-02", "date: 2027-03-01"); + await build(root, join(root, "..", "wb-llms-out")); + const llms = await readFile(join(root, ".out", "storefront", "llms.txt"), "utf8"); + expect(llms).not.toMatch(/\/guides\/setup\/|\/articles\/harbour\/|\/articles\/plain\//); + // The rest is there. + expect(llms).toContain("## Guides\n\n- [Guides](https://bench.example.test/guides/): Longer texts about the bench.\n\n"); + expect(llms).toContain("## Articles\n\n- [Articles](https://bench.example.test/articles/): Everything written for the bench, newest first.\n"); + expect(llms).toContain("- [About](https://bench.example.test/about/)"); + }, 60_000); + + it("writes no llms.txt with storefront.llms: false, or for a site with index: false", async () => { + const root = await benchCopy(); + await build(root, join(root, "..", "wb-llms-off"), config({ llms: false })); + expect(await exists(join(root, ".out", "storefront", "llms.txt"))).toBe(false); + await build(root, join(root, "..", "wb-llms-staging"), config({ index: false })); + expect(await exists(join(root, ".out", "storefront", "llms.txt"))).toBe(false); + }, 60_000); + + it("without storefront.url: llms.txt links each page by its path from the site's root", async () => { + const root = await benchCopy(); + const { url: _u, ...rest } = benchConfig.storefront!; + await buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, { outDir: join(root, "..", "wb-llms-nourl"), pdVersion: "x", now: NOW }); + const llms = await readFile(join(root, ".out", "storefront", "llms.txt"), "utf8"); + expect(llms).toContain("- [About](/about/): What the bench is for.\n"); + expect(llms).not.toContain("https://"); + }, 60_000); + it("keeps the storefront's output apart from the workbench's and from what PD reads", async () => { const root = await benchCopy(); await expect(build(root, join(root, ".out", "storefront"))).rejects.toThrow(/and --out .* overlap: the storefront and the workbench each need a folder of their own/); From 680a74613904941b3873ca6137362568f30d4a46 Mon Sep 17 00:00:00 2001 From: Stefan Bauer <stefan.bauer@n8d.at> Date: Mon, 16 Nov 2026 10:58:03 +0100 Subject: [PATCH 4/7] feat(storefront): pd build checks for classes outside the design system Each class on a site page that no stylesheet of the style guide names and no component template writes is listed, naming the page's file and line. A word a template builds from a value defines its family; state classes, Pattern Dump's own tooling classes and storefront.checks.allowClasses are allowed. A warning by default; storefront.checks.classes "error" stops the build, "off" skips it. The starter's install check asserts its pages are clean. --- CHANGELOG.md | 4 + docs/guide/configuration.md | 2 + docs/guide/storefront.md | 24 ++++ packages/config/src/index.ts | 13 ++ packages/config/src/validate.spec.ts | 10 ++ packages/config/src/validate.ts | 1 + packages/core/src/index.ts | 7 +- packages/dev-server/src/index.ts | 20 +++- packages/dev-server/src/server-config.ts | 6 + packages/dev-server/src/static-build.ts | 40 ++++++- .../dev-server/src/storefront/class-check.ts | 112 ++++++++++++++++++ packages/dev-server/src/storefront/crawl.ts | 13 +- .../src/storefront/css-vocabulary.ts | 38 ++++++ .../dev-server/test/css-vocabulary.spec.ts | 48 ++++++++ .../test/storefront-style-checks.spec.ts | 93 +++++++++++++++ scripts/verify-install.mjs | 4 + 16 files changed, 425 insertions(+), 10 deletions(-) create mode 100644 packages/dev-server/src/storefront/class-check.ts create mode 100644 packages/dev-server/src/storefront/css-vocabulary.ts create mode 100644 packages/dev-server/test/css-vocabulary.spec.ts create mode 100644 packages/dev-server/test/storefront-style-checks.spec.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index a5a2a5d..84a6f4f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,10 @@ ### Added +- **The class check.** `pd build` lists each class on a site page that no component or style of the style guide + defines, naming the page's file and line: `about.md:12: class "hero-big-title" isn't defined by any component or + style`. State classes (`is-`, `has-`, `js-`) and Pattern Dump's own are allowed, and so is + `storefront.checks.allowClasses`. A warning; `storefront.checks.classes: "error"` stops the build, `"off"` skips it. - **`llms.txt`.** `pd build` writes one at the site's root (llmstxt.org): the site's title and description, then the top-level pages and each collection, every page with its title, link and teaser. The same pages as the sitemap; absolute URLs with `storefront.url`, under the site's path. On by default; `storefront.llms: false` turns it off. diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 05f8a70..8894e98 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -190,6 +190,8 @@ in [storefront.md](storefront.md). | `storefront.categoryPages` | boolean or object | on when the skin has `layouts/category` | The same for categories, at `/categories/` | | `storefront.search` | boolean | on when the project has Pagefind | Search: `pd build` indexes every page's own content with Pagefind into `_pd/search/`. `true`: a build without Pagefind stops; `false`: off ([storefront.md](storefront.md#search)) | | `storefront.llms` | boolean | `true` (`false` with `index: false`) | `pd build` writes `llms.txt` at the site's root: the site's title and description and each page's title, link and teaser, by collection ([storefront.md](storefront.md#search-engines-and-link-previews)). `false`: none | +| `storefront.checks.classes` | `"warning"`, `"error"` or `"off"` | `"warning"` | The class check: a class on a page that no component or style of the style guide defines is listed in the report, stops the build, or isn't checked ([storefront.md](storefront.md#the-class-check)) | +| `storefront.checks.allowClasses` | list of strings | `[]` | Classes a page may carry anyway: names, or a prefix ending in `*` (`"chart-*"`) | | `storefront.site` | object | (none) | Values every page shares, such as the site's title or footer line. Every layout gets them as `site`, and a page cannot set them. Their keys and types are what the `site` property of `partials/base`'s schema declares, and they are checked against it. One key is Pattern Dump's: `navigations`, named lists of links ([storefront.md](storefront.md#declared-navigations)) | ## When changes take effect diff --git a/docs/guide/storefront.md b/docs/guide/storefront.md index cdc066b..fde2f68 100644 --- a/docs/guide/storefront.md +++ b/docs/guide/storefront.md @@ -1193,6 +1193,30 @@ pd build: the storefront has broken links, so nothing was written: Code examples are text, so a link written in one is not checked. In `pd dev`, a page's links to pages that don't exist and to anchors it doesn't have are warnings in the terminal; the full check runs in `pd build`. +### The class check + +Before it writes anything, `pd build` looks at every class on every page of the site (its pages and its 404 page) +and lists each one the style guide doesn't define, so a class improvised outside the design system shows, whether a +person or an agent wrote it. + +- **Defined:** a class a stylesheet of the style guide names in a selector (the project's and its packages', and each + stylesheet the site loads), and a class a component's template writes, styled or not. A word a template builds + from a value, such as `doc-toc-h{{level}}`, defines every class that starts that way. A page's own `<style>` counts + too. +- **Allowed:** state classes JavaScript adds (`is-`, `has-`, `js-`), the classes Pattern Dump writes itself (code + highlighting, the copy button, pattern links, live examples), and the names in `storefront.checks.allowClasses` + (a trailing `*` for a prefix). +- A page's markdown can't write HTML, so what the check finds is a value a component writes into a `class` + attribute (`<pd-components-badge look="hero-big-title">`, a template with `class="{{look}}"`). It names the page's + file and the line that gives the value. + +``` +[pd build] classes: 1 outside the design system: +[pd build] warning: about.md:12: class "hero-big-title" isn't defined by any component or style +``` + +A warning by default; with `storefront.checks.classes: "error"` it stops the build, and `"off"` skips the check. + ### The accessibility check After the link check, `pd build` checks every page of the site (not the previews or the pages that forward from old diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts index b8dda40..ab6c159 100644 --- a/packages/config/src/index.ts +++ b/packages/config/src/index.ts @@ -267,6 +267,19 @@ export interface StorefrontConfig { * false. `false`: none. */ llms?: boolean; + /** pd build's checks of the site against its style guide. */ + checks?: StorefrontChecks; +} + +/** storefront.checks: what pd build checks the site's classes against. */ +export interface StorefrontChecks { + /** + * A class on a page that no component or style of the style guide defines: `"warning"` (the default) lists it in + * the report, `"error"` stops the build, `"off"` skips the check. + */ + classes?: "warning" | "error" | "off"; + /** Classes a page may carry anyway: names, or a prefix ending in `*` (`"chart-*"`). */ + allowClasses?: string[]; } /** storefront.tagPages and storefront.categoryPages as an object. */ diff --git a/packages/config/src/validate.spec.ts b/packages/config/src/validate.spec.ts index 0b9e4c8..eab2ab1 100644 --- a/packages/config/src/validate.spec.ts +++ b/packages/config/src/validate.spec.ts @@ -271,6 +271,16 @@ describe("configProblems — storefront", () => { expect(storefront({ ...base, llms: "no" })).toEqual([`"storefront.llms" must be true or false`]); }); + it("takes checks: classes warning, error or off, and a list of allowed classes", () => { + const base = { pagesDir: "./pages", outDir: "./www" }; + expect(storefront({ ...base, checks: { classes: "error", allowClasses: ["chart-*"] } })).toEqual([]); + expect(storefront({ ...base, checks: { classes: "strict", allowClasses: "chart-*", allowClass: [] } })).toEqual([ + `unknown key "storefront.checks.allowClass": did you mean "storefront.checks.allowClasses"?`, + `"storefront.checks.classes" must be "warning" or "error" or "off"`, + `"storefront.checks.allowClasses" must be a list of strings`, + ]); + }); + it("takes tagPages and categoryPages: true, false, or { path, title }", () => { const base = { pagesDir: "./pages", outDir: "./www" }; for (const ok of [true, false, {}, { path: "topics" }, { title: "Topics" }, { path: "t2", title: "All tags" }]) { diff --git a/packages/config/src/validate.ts b/packages/config/src/validate.ts index 93447af..4eb0467 100644 --- a/packages/config/src/validate.ts +++ b/packages/config/src/validate.ts @@ -65,6 +65,7 @@ const SHAPE: Shape = { url: "site-url", lang: "lang", index: "boolean", image: "asset-path", images: IMAGES, head: "hbs-file", categories: "categories", tags: "tags", tagPages: "term-pages", categoryPages: "term-pages", search: "boolean", llms: "boolean", + checks: { keys: { classes: { values: ["warning", "error", "off"] }, allowClasses: "strings" } }, }, required: ["pagesDir", "outDir"], }, diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 87fc14d..6baef75 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -65,7 +65,12 @@ export async function runBuild( console.log(`[pd build] images: ${n ? `${n} with a variant that doesn't fit:` : "every variant fits its box"}`); for (const w of report.images.warnings) console.log(`[pd build] warning: ${w}`); } - if (report.llms) console.log(`[pd build] llms.txt: ${report.llms.pages} pages`); + if (report.classes) { + const n = report.classes.warnings.length; + console.log(`[pd build] classes: ${n ? `${n} outside the design system:` : "every class on the site's pages is the style guide's"}`); + for (const w of report.classes.warnings) console.log(`[pd build] warning: ${w}`); + } + if (report.llms) console.log(`[pd build] llms.txt: ${report.llms.pages} page${report.llms.pages === 1 ? "" : "s"}`); if (report.search) { console.log(`[pd build] search: ${report.search.pages} pages indexed → ${report.search.files} files in _pd/search/ (${(report.search.bytes / 1024).toFixed(0)} KB)`); } diff --git a/packages/dev-server/src/index.ts b/packages/dev-server/src/index.ts index 13041c0..d3ea328 100644 --- a/packages/dev-server/src/index.ts +++ b/packages/dev-server/src/index.ts @@ -42,7 +42,7 @@ const SILENT_RELOADER: HotReloader = { close: async () => { /* nothing opened */ }, }; import { createServer } from "node:http"; -import { stat } from "node:fs/promises"; +import { readFile, stat } from "node:fs/promises"; import { join, sep } from "node:path"; import { fileURLToPath } from "node:url"; // HTTP/HTML leaf helpers. Kept in their own module because `escapeHtml` is shared by the Markdown @@ -72,7 +72,7 @@ export type { StaticBuildOptions, StaticBuildReport } from "./static-build.js"; // All mutable server state in one typed object — the seam that lets routes and the watcher // stop sharing lexical scope. Its header documents the three hazards. import { reportUnresolvableScripts } from "./requires.js"; -import { applyStyleData, cachedDiscovery, compositionFor, createServerState, setDiscovery } from "./server-state.js"; +import { applyStyleData, cachedDiscovery, compositionFor, createServerState, currentDiscovery, setDiscovery } from "./server-state.js"; // Resolved paths + flags, derived once from PatternDumpConfig against the ONE resolution base. import { resolveServerConfig } from "./server-config.js"; import { createImageService } from "./image-service.js"; @@ -154,6 +154,15 @@ export interface DevServerOptions { export interface DevServer { port: number; close(): Promise<void>; + /** For pd build's class check (class-check.ts), not part of the HTTP contract: every compiled + * stylesheet of the style guide (each component's, the base layer, each theme; project and packages) and every + * component template's source. */ + styleGuide(): Promise<StyleGuideSources>; +} + +export interface StyleGuideSources { + stylesheets: string[]; + templates: string[]; } const devUiDist = resolveDevUiDist(import.meta.url); @@ -391,6 +400,13 @@ export async function startDevServer( return { port: actualPort, + async styleGuide() { + const discovery = await currentDiscovery(state, patternRoots); + await state.style.get(() => buildAllStyleData(styleRoots, baseComponentIds(discovery))); + const templates = await Promise.all([...discovery.discoveryMap.values()].filter(e => e.hbsPath !== "") + .map(e => readFile(e.hbsPath, "utf8").catch(() => ""))); + return { stylesheets: [...state.perComponentCss.values(), state.baseCss, ...state.themeCss.values()], templates }; + }, async close() { await watcher?.close(); await hotreloader.close(); diff --git a/packages/dev-server/src/server-config.ts b/packages/dev-server/src/server-config.ts index 16c953d..6e66956 100644 --- a/packages/dev-server/src/server-config.ts +++ b/packages/dev-server/src/server-config.ts @@ -109,6 +109,8 @@ export interface ResolvedConfig { readonly categoryPages: boolean | StorefrontTermPages | undefined; /** storefront.llms: pd build writes llms.txt; false for a site with index: false. */ readonly llms: boolean; + /** storefront.checks, with its defaults: the class check warns, nothing is allowed beyond the built-in lists. */ + readonly checks: { readonly classes: "warning" | "error" | "off"; readonly allowClasses: readonly string[] }; /** storefront.search as the config writes it (search.ts reads it). */ readonly search: boolean | undefined; } | null; @@ -256,6 +258,10 @@ export function resolveServerConfig( categoryPages: config.storefront.categoryPages, search: config.storefront.search, llms: config.storefront.index !== false && config.storefront.llms !== false, + checks: { + classes: config.storefront.checks?.classes ?? "warning", + allowClasses: config.storefront.checks?.allowClasses ?? [], + }, } : null, images, overviewsEnabled: config.overviews !== false, diff --git a/packages/dev-server/src/static-build.ts b/packages/dev-server/src/static-build.ts index 3058a13..2d87baa 100644 --- a/packages/dev-server/src/static-build.ts +++ b/packages/dev-server/src/static-build.ts @@ -10,7 +10,7 @@ // is included — its <link>/<script>/url() references are root-relative too. // - the shell: one shell page per route, carrying the static ShellRuntime instead of a port. -import { cp, mkdir, readdir, rm, stat, writeFile } from "node:fs/promises"; +import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises"; import { basename, dirname, join, relative, resolve, sep } from "node:path"; import { createImageCache } from "@pattern-dump/build"; import { sameHostWorkbenchPath, type PatternDumpConfig } from "@pattern-dump/config"; @@ -32,6 +32,7 @@ import { checkPageBasics } from "./storefront/page-basics.js"; import { loadProjectPlaywright, runBrowserChecks, VIEWPORTS, type PlaywrightModule } from "./storefront/browser-checks.js"; import { runPageA11y, type PageA11yFinding } from "@pattern-dump/a11y"; import { llmsTxt, workbenchRobotsTxt } from "./storefront/site-files.js"; +import { checkClasses } from "./storefront/class-check.js"; import { withNoindex } from "./storefront/base-path.js"; import { buildSearchIndex, SEARCH_PATH, searchPagefind, type PagefindModule, type SearchRecord } from "./storefront/search.js"; @@ -84,6 +85,9 @@ export interface StaticBuildReport { /** The storefront's search index (search.ts), written to its _pd/search/: the pages in it, and its files. Absent * when the site has no search. */ search?: { pages: number; files: number; bytes: number }; + /** The class check (storefront.checks.classes): with "warning", one line per class a page carries that the style + * guide doesn't define; with "error" a class stops the build, so `warnings` is empty. Absent with "off". */ + classes?: { severity: "warning" | "error"; warnings: string[] }; /** llms.txt, at the site's root: how many pages it lists. Absent when none is written (storefront.llms). */ llms?: { pages: number }; /** `--browser`: one line per image whose chosen variant doesn't fit the box it is laid out in. */ @@ -204,6 +208,8 @@ export async function buildStaticSite( // its 404 page; not the previews and redirect stubs it writes) resolves to what this build writes, a link into the // workbench to a component and variant the workbench snapshot has. Other hosts are listed in the notes. let linkSummary: StaticBuildReport["links"]; + let classSummary: StaticBuildReport["classes"]; + let pageModel: Awaited<ReturnType<typeof readPages>> | undefined; let a11ySummary: StaticBuildReport["accessibility"]; let imageSummary: StaticBuildReport["images"]; const externalNotes: string[] = []; @@ -239,6 +245,33 @@ export async function buildStaticSite( linkSummary = { pages: pages.length, references: links.references, external: links.external.size }; log(`… links checked: ${links.references} references on ${pages.length} pages`); + // The class check, also before anything is written (class-check.ts): every class a site page carries is defined + // by the style guide (a warning unless storefront.checks.classes says otherwise). + pageModel = await readPages(storefront.pagesDir, { + drafts: "leave-out", scheduled: "leave-out", today, categories: storefront.categories, tags: storefront.tags, + }); + const guide = await server.styleGuide(); + const stylesheets = [...guide.stylesheets, ...sfCrawl.stylesheets.values()]; + const fail = async (what: string, lines: string[]): Promise<never> => { + await server.close(); + throw new Error(`pd build: ${what}, so nothing was written:\n${lines.map(l => ` - ${l}`).join("\n")}`); + }; + if (storefront.checks.classes !== "off") { + const model = pageModel; + const checkPages = await Promise.all(pages.flatMap(route => { + const html = sfCrawl.documents.get(route); + if (html === undefined) return []; + const f = route === PD_ROUTES.notFound ? model.notFound : model.files.get(route); + return [(async () => ({ route, html, ...(f ? { file: { path: f.path, text: await readFile(f.file, "utf8") } } : {}) }))()]; + })); + const classes = checkClasses({ pages: checkPages, stylesheets, templates: guide.templates, allow: storefront.checks.allowClasses }); + if (storefront.checks.classes === "error" && classes.length) { + await fail("the storefront uses classes outside the design system (storefront.checks.classes is \"error\")", classes); + } + classSummary = { severity: storefront.checks.classes, warnings: storefront.checks.classes === "warning" ? classes : [] }; + } + log(`… styles checked against the style guide`); + // Accessibility (step 6b), also before anything is written: one main landmark and one <h1> per site page, and // axe's rules that jsdom decides (@pattern-dump/a11y). A critical or serious WCAG finding, and a page without // exactly one main and one <h1>, stop the build; the rest are warnings in the report, grouped by rule. @@ -432,9 +465,7 @@ export async function buildStaticSite( report.search = { pages: searchRecords.size, files: searchFiles.size, bytes }; } // The pages as this build has them (no draft, no scheduled page): llms.txt, and the report's drafts and scheduled. - const model = await readPages(storefront.pagesDir, { - drafts: "leave-out", scheduled: "leave-out", today, categories: storefront.categories, tags: storefront.tags, - }); + const model = pageModel!; if (storefront.llms) { const siteTitle = typeof storefront.site?.["title"] === "string" ? storefront.site["title"] : undefined; const llms = llmsTxt(model, { title: siteTitle, siteUrl: storefront.url }); @@ -463,6 +494,7 @@ export async function buildStaticSite( } report.notes.push(...storefrontNotes, ...externalNotes); if (linkSummary) report.links = linkSummary; + if (classSummary) report.classes = classSummary; if (a11ySummary) report.accessibility = a11ySummary; if (imageSummary) report.images = imageSummary; const { drafts, scheduled } = model; diff --git a/packages/dev-server/src/storefront/class-check.ts b/packages/dev-server/src/storefront/class-check.ts new file mode 100644 index 0000000..30cd32f --- /dev/null +++ b/packages/dev-server/src/storefront/class-check.ts @@ -0,0 +1,112 @@ +// The class check: pd build reports each class on a site page that nothing in the style guide defines, so +// improvising outside the design system shows (by a person or an agent): the HTML counterpart of the schema checks. +// +// - Defined: a class any stylesheet of the style guide names in a selector (project and packages, compiled, and +// each stylesheet the site loads), a class any component template writes (the static words of a class="...", and +// the family it builds from a value: `doc-toc-h{{level}}` is every "doc-toc-h..." class), and a class the page's own +// <style> names. A class a template writes is part of that component, styled or not: a skin may keep its markup +// plain on purpose. What is left is a class that arrives whole from a value (`class="{{look}}"`, a page's +// `look="hero-big-title"`), which no part of the system wrote: a page's markdown can't write HTML of its own. +// - Allowed: state classes JavaScript adds (is-, has-, js-), the classes Pattern Dump's own tooling writes into a +// page (PD_CLASSES), and storefront.checks.allowClasses. +// - Where: the page's markdown file and line when the class is written there; else the file alone (it came from a +// value, such as frontmatter a template writes), or the route for a page with no file (a tag or category page). +// - A warning by default; storefront.checks.classes: "error" stops the build, "off" skips the check. + +import { nameMatcher, readCss } from "./css-vocabulary.js"; + +/** State classes, which JavaScript adds and takes away. */ +export const STATE_CLASSES: readonly string[] = ["is-*", "has-*", "js-*"]; + +/** The classes Pattern Dump writes into a site page itself: code highlighting (shiki, its themes and lines) and its + * copy button, pattern links, live examples and their errors, and its own problem lists. */ +export const PD_CLASSES: readonly string[] = [ + "shiki", "shiki-*", "__shiki_*", "line", "copy-btn", "pd-*", + "pattern-link", "pattern-link--unresolved", + "doc-example", "doc-example-id", "doc-example-variants", "doc-error", +]; + +/** The classes a template writes: each static word of a class="...", and the families it builds from a value, by the + * static start of the word (`doc-toc-h{{level}}` builds every class starting with "doc-toc-h"). A word an + * expression starts (`{{prefix}}-item`) names no class of its own. */ +export function templateClasses(source: string): { classes: string[]; prefixes: string[] } { + const classes = new Set<string>(), prefixes = new Set<string>(); + const EXPR = "\u0000"; + for (const m of source.matchAll(/\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) { + // A block's tags ({{#if}}, {{else}}, {{/if}}) only choose words, so they part them; any other expression is a value. + const words = (m[1] ?? m[2] ?? "").replace(/\{\{~?\s*(?:[#/^]|else\b)[\s\S]*?\}\}/g, " ").replace(/\{\{[\s\S]*?\}\}/g, EXPR); + for (const word of words.split(/\s+/)) { + if (!word || word.startsWith(EXPR)) continue; + if (!word.includes(EXPR)) classes.add(word); + else prefixes.add(word.slice(0, word.indexOf(EXPR))); + } + } + return { classes: [...classes], prefixes: [...prefixes] }; +} + +/** The classes on the elements of a built page, in order of first use. Scripts and comments are not markup. */ +export function documentClasses(html: string): string[] { + const markup = html.replace(/<script\b[\s\S]*?<\/script>/gi, "").replace(/<!--[\s\S]*?-->/g, ""); + const out = new Set<string>(); + for (const m of markup.matchAll(/<[a-z][^>]*?\sclass\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) { + for (const word of (m[1] ?? m[2] ?? "").split(/\s+/)) if (word) out.add(word.replace(/&/g, "&")); + } + return [...out]; +} + +/** The text of the page's own <style> blocks. */ +const styleBlocks = (html: string): string[] => [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map(m => m[1]!); + +export interface ClassCheckPage { + route: string; + html: string; + /** The page's markdown file (path in the pages folder, and its text); absent for a generated page. */ + file?: { path: string; text: string }; +} + +export interface ClassCheckInput { + pages: readonly ClassCheckPage[]; + /** Every compiled stylesheet of the style guide, and every stylesheet the site loads. */ + stylesheets: readonly string[]; + /** Every component template's source. */ + templates: readonly string[]; + /** storefront.checks.allowClasses. */ + allow?: readonly string[]; +} + +/** The line of `text` (1-based) that writes `name` as a word, in a class attribute if one does; else null. */ +function lineOf(text: string, name: string): number | null { + const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const word = new RegExp(`(^|[^\\w-])${escaped}(?![\\w-])`); + const lines = text.split("\n"); + const inClass = lines.findIndex(l => /\bclass\s*=/.test(l) && word.test(l)); + if (inClass >= 0) return inClass + 1; + const any = lines.findIndex(l => word.test(l)); + return any >= 0 ? any + 1 : null; +} + +/** One line per class a page uses and nothing defines, in page order: `about.md:12: class "x" isn't defined by any + * component or style`. */ +export function checkClasses(input: ClassCheckInput): string[] { + const defined = new Set<string>(); + for (const css of input.stylesheets) for (const c of readCss(css).classes) defined.add(c); + const families: string[] = []; + for (const t of input.templates) { + const written = templateClasses(t); + for (const c of written.classes) defined.add(c); + families.push(...written.prefixes.map(p => `${p}*`)); + } + const allowed = nameMatcher([...STATE_CLASSES, ...PD_CLASSES, ...families, ...(input.allow ?? [])]); + const out: string[] = []; + for (const page of input.pages) { + const own = new Set<string>(); + for (const css of styleBlocks(page.html)) for (const c of readCss(css).classes) own.add(c); + for (const name of documentClasses(page.html)) { + if (defined.has(name) || own.has(name) || allowed(name)) continue; + const line = page.file ? lineOf(page.file.text, name) : null; + const where = page.file ? `${page.file.path}${line !== null ? `:${line}` : ""}` : page.route; + out.push(`${where}: class "${name}" isn't defined by any component or style`); + } + } + return out; +} diff --git a/packages/dev-server/src/storefront/crawl.ts b/packages/dev-server/src/storefront/crawl.ts index b8ad79f..c844fcc 100644 --- a/packages/dev-server/src/storefront/crawl.ts +++ b/packages/dev-server/src/storefront/crawl.ts @@ -55,6 +55,8 @@ export interface StorefrontCrawl { problems: string[]; /** The HTML of every document crawled, by its URL: the link check reads it (links.ts). */ documents: Map<string, string>; + /** Every stylesheet crawled, by its URL: the class check reads it (class-check.ts). */ + stylesheets: Map<string, string>; } /** `files`: the root files to write besides the pages and what they reference (robots.txt, sitemap.xml). `get` @@ -68,12 +70,13 @@ export async function crawlStorefront(get: (liveUrl: string) => Promise<Response const body = await list.text(); let error = body; try { error = (JSON.parse(body) as { error?: string }).error ?? body; } catch { /* not JSON */ } - return { urls: [], problems: error.split("\n").filter(Boolean), documents: new Map() }; + return { urls: [], problems: error.split("\n").filter(Boolean), documents: new Map(), stylesheets: new Map() }; } const { pages } = await list.json() as StorefrontPagesResponse; const urls: string[] = []; const documents = new Map<string, string>(); + const stylesheets = new Map<string, string>(); const seen = new Set<string>(); const queue: string[] = []; const add = (url: string): void => { if (!seen.has(url)) { seen.add(url); queue.push(url); } }; @@ -104,7 +107,11 @@ export async function crawlStorefront(get: (liveUrl: string) => Promise<Response documents.set(url, html); for (const ref of markupRefs(html, basePath)) add(ref); } - else if (/text\/css/.test(type)) for (const ref of cssRefs(await res.text(), basePath)) add(ref); + else if (/text\/css/.test(type)) { + const css = await res.text(); + stylesheets.set(url, css); + for (const ref of cssRefs(css, basePath)) add(ref); + } } - return { urls, problems, documents }; + return { urls, problems, documents, stylesheets }; } diff --git a/packages/dev-server/src/storefront/css-vocabulary.ts b/packages/dev-server/src/storefront/css-vocabulary.ts new file mode 100644 index 0000000..e467976 --- /dev/null +++ b/packages/dev-server/src/storefront/css-vocabulary.ts @@ -0,0 +1,38 @@ +// What a stylesheet says, for pd build's class check (class-check.ts): the classes its selectors name. Compiled CSS is +// read with postcss: what it names is what a browser gets, whatever Sass built it from. + +import postcss from "postcss"; +import selectorParser from "postcss-selector-parser"; + +export interface CssVocabulary { + classes: Set<string>; +} + +/** The classes a selector names. */ +export function selectorClassNames(selector: string): string[] { + const out: string[] = []; + try { + selectorParser(root => { root.walkClasses(c => { out.push(c.value); }); }).processSync(selector); + } catch { /* not a selector postcss-selector-parser reads: no classes from it */ } + return out; +} + +/** The classes of compiled CSS. */ +export function readCss(text: string): CssVocabulary { + const classes = new Set<string>(); + let root: postcss.Root; + try { + root = postcss.parse(text); + } catch { + return { classes }; + } + root.walkRules(rule => { for (const c of selectorClassNames(rule.selector)) classes.add(c); }); + return { classes }; +} + +/** A matcher for names and prefixes (`is-*`): true for a name one of `patterns` covers. */ +export function nameMatcher(patterns: readonly string[]): (name: string) => boolean { + const exact = new Set(patterns.filter(p => !p.endsWith("*"))); + const prefixes = patterns.filter(p => p.endsWith("*")).map(p => p.slice(0, -1)); + return name => exact.has(name) || prefixes.some(p => name.startsWith(p)); +} diff --git a/packages/dev-server/test/css-vocabulary.spec.ts b/packages/dev-server/test/css-vocabulary.spec.ts new file mode 100644 index 0000000..6c557b5 --- /dev/null +++ b/packages/dev-server/test/css-vocabulary.spec.ts @@ -0,0 +1,48 @@ +// The class check's readers: the classes a stylesheet names (css-vocabulary.ts), and what a template and a built +// page write as classes (class-check.ts). +import { describe, expect, it } from "vitest"; +import { nameMatcher, readCss } from "../src/storefront/css-vocabulary.js"; +import { checkClasses, documentClasses, templateClasses } from "../src/storefront/class-check.js"; + +describe("readCss and nameMatcher", () => { + it("names the classes of every selector, and reads nothing from text that isn't CSS, rather than failing", () => { + expect([...readCss(".a .b:hover, .c > .d { color: red; }\n@media (width > 1px) { .e { margin: 0; } }").classes].sort()) + .toEqual(["a", "b", "c", "d", "e"]); + expect(readCss("{{{").classes.size).toBe(0); + }); + + it("matches names and prefixes", () => { + const m = nameMatcher(["exact", "pre-*"]); + expect([m("exact"), m("pre-fix"), m("pre"), m("exactly")]).toEqual([true, true, false, false]); + }); +}); + +describe("templateClasses", () => { + it("takes a class attribute's static words, a family by the start of a word built from a value, and a block's words", () => { + const t = `<aside class="callout{{#if tone}} callout-{{tone}}{{/if}}"><li class="doc-toc-h{{level}}"><p class='{{x}}-y z'>` + + `<b class="{{#if open}}is-open{{else}}is-shut{{/if}}">`; + expect(templateClasses(t)).toEqual({ classes: ["callout", "z", "is-open", "is-shut"], prefixes: ["callout-", "doc-toc-h"] }); + }); +}); + +describe("documentClasses and checkClasses", () => { + it("reads a built page's classes, but not from its scripts or comments", () => { + expect(documentClasses(`<p class="a b"><!-- <i class="c"> --><script>x = '<i class="d">'</script><i class='e'>`)).toEqual(["a", "b", "e"]); + }); + + it("names a class nothing defines by its page's file and line; counts styles, templates, families, the page's own <style>", () => { + const warnings = checkClasses({ + pages: [{ + route: "/about/", + html: `<style>.own{}</style><p class="styled written family-2 own pd-x is-open stray">`, + file: { path: "about.md", text: "---\ntitle: About\n---\n\n<pd-badge look=\"stray\"></pd-badge>\n" }, + }, { route: "/tags/x/", html: `<p class="stray">` }], + stylesheets: [".styled { color: red }"], + templates: [`<p class="written family-{{n}}">`], + }); + expect(warnings).toEqual([ + `about.md:5: class "stray" isn't defined by any component or style`, + `/tags/x/: class "stray" isn't defined by any component or style`, + ]); + }); +}); diff --git a/packages/dev-server/test/storefront-style-checks.spec.ts b/packages/dev-server/test/storefront-style-checks.spec.ts new file mode 100644 index 0000000..5df93d7 --- /dev/null +++ b/packages/dev-server/test/storefront-style-checks.spec.ts @@ -0,0 +1,93 @@ +// pd build's class check on a storefront, on copies of the bench: a class on a page that nothing in the style guide +// defines (a warning, or an error with storefront.checks.classes), naming file and line. +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { execFileSync } from "node:child_process"; +import { cp, mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { validateConfig, type PatternDumpConfig } from "@pattern-dump/config"; +import { buildStaticSite } from "@pattern-dump/dev-server"; +import benchConfig from "../../../storefront-bench/pattern-dump.config.js"; +import { save } from "../../../test-support/save.js"; + +const repo = fileURLToPath(new URL("../../../", import.meta.url)); +const NOW = new Date("2027-01-02T03:04:05.000Z"); +let tmp = ""; + +beforeAll(async () => { tmp = await mkdtemp(join(tmpdir(), "pd-sf-checks-")); }); +afterAll(async () => { if (tmp) await rm(tmp, { recursive: true, force: true }); }); + +let n = 0; +async function benchCopy(): Promise<string> { + const root = join(tmp, `bench-${n++}`); + for (const file of execFileSync("git", ["ls-files", "storefront-bench"], { cwd: repo, encoding: "utf8" }).split("\n").filter(Boolean)) { + const to = join(root, file.slice("storefront-bench/".length)); + await mkdir(dirname(to), { recursive: true }); + await cp(join(repo, file), to); + } + return root; +} +const config = (checks?: Record<string, unknown>): PatternDumpConfig => + validateConfig({ ...benchConfig, storefront: { ...benchConfig.storefront!, ...(checks ? { checks } : {}) } }, "test"); +const build = (root: string, cfg: PatternDumpConfig = config()) => + buildStaticSite(cfg, root, { outDir: join(root, "..", `wb-${n++}`), pdVersion: "0.0.0-test", now: NOW }); +const append = async (path: string, text: string) => save(path, `${await readFile(path, "utf8")}${text}`); +const exists = (p: string) => stat(p).then(() => true, () => false); +/** The line `text` is on in `file` (1-based). */ +const lineIn = async (file: string, text: string) => (await readFile(file, "utf8")).split("\n").findIndex(l => l.includes(text)) + 1; + +/** A component that writes what a page gives it into its class and style attributes: the one way a page's value + * becomes a class (a page's markdown can't write HTML). Placed on about.md with `look` and `size`. */ +async function placeBadge(root: string, look: string, size = "2rem"): Promise<string> { + const dir = join(root, "src", "patterns", "components", "badge"); + await mkdir(dir, { recursive: true }); + await save(join(dir, "badge.hbs"), `<span class="badge {{look}}" style="--badge-size: {{size}}">{{label}}</span>\n`); + await save(join(dir, "badge.json"), JSON.stringify({ look: "", size: "1rem", label: "New" })); + await save(join(dir, "badge.schema.json"), JSON.stringify({ type: "object", properties: { + look: { type: "string" }, size: { type: "string" }, label: { type: "string" } } })); + const about = join(root, "pages", "about.md"); + await append(about, `\n<pd-components-badge look="${look}" size="${size}" label="Big"></pd-components-badge>\n`); + return about; +} + +describe("pd build — classes outside the design system", () => { + it("finds none on the bench: every class its pages carry is a component's, a style's or Pattern Dump's own", async () => { + const report = await build(await benchCopy()); + expect(report.classes).toEqual({ severity: "warning", warnings: [] }); + }, 60_000); + + it("warns about a class a page gives a component that nothing defines, naming the page and line, and still builds", async () => { + const root = await benchCopy(); + const about = await placeBadge(root, "lede hero-big-title"); + const report = await build(root); + const line = await lineIn(about, "hero-big-title"); + expect(report.classes?.warnings).toEqual([ + `about.md:${line}: class "lede" isn't defined by any component or style`, + `about.md:${line}: class "hero-big-title" isn't defined by any component or style`, + ]); + expect(await exists(join(root, ".out", "storefront", "about", "index.html"))).toBe(true); + }, 60_000); + + it("stops the build with checks.classes: \"error\", and writes nothing", async () => { + const root = await benchCopy(); + await placeBadge(root, "hero-big-title"); + await expect(build(root, config({ classes: "error" }))).rejects.toThrow(/classes outside the design system[\s\S]*about\.md:\d+: class "hero-big-title"/); + expect(await exists(join(root, ".out", "storefront"))).toBe(false); + }, 60_000); + + it("takes allowClasses, by name and by prefix, and skips the check with checks.classes: \"off\"", async () => { + const root = await benchCopy(); + await placeBadge(root, "lede hero-big-title"); + expect((await build(root)).classes?.warnings).toHaveLength(2); + expect((await build(root, config({ allowClasses: ["lede", "hero-*"] }))).classes?.warnings).toEqual([]); + expect((await build(root, config({ classes: "off" }))).classes).toBeUndefined(); + }, 120_000); + + it("counts a state class (is-, has-, js-) and a class a stylesheet of the style guide names as defined", async () => { + const root = await benchCopy(); + // .card-title is the card's (in its stylesheet), worn here by another component. + await placeBadge(root, "is-open has-icon js-toggle card-title"); + expect((await build(root)).classes?.warnings).toEqual([]); + }, 60_000); +}); diff --git a/scripts/verify-install.mjs b/scripts/verify-install.mjs index a4afe08..14620b9 100644 --- a/scripts/verify-install.mjs +++ b/scripts/verify-install.mjs @@ -283,6 +283,10 @@ if (failures.length === 0 && tmp) { check(built.status === 0, "npm run build on the website starter", `${built.stdout}${built.stderr}`.slice(-800)); check(!`${built.stdout}${built.stderr}`.includes("add its rule"), "the build doesn't ask for the workbench's robots rule: the website's robots.txt carries it", `${built.stdout}`.slice(-800)); + // A new site starts inside its design system: no class on its pages that the style guide doesn't define. + check(built.stdout.includes("classes: every class on the site's pages is the style guide's"), + "the website starter's pages carry only the style guide's classes", built.stdout.split("\n").filter(l => /class/.test(l)).join("\n").slice(-800)); + check(existsSync(join(starter, "site", "llms.txt")), "the website starter's build writes llms.txt"); // As the workflow does it: the website at the root, the workbench copied in under /workbench/. const out = join(tmp, "website-pages"); await cp(join(starter, "site"), out, { recursive: true }); From 955c55c1b5fa4d7e8c6f23d4a195003e3602db00 Mon Sep 17 00:00:00 2001 From: Stefan Bauer <stefan.bauer@n8d.at> Date: Mon, 16 Nov 2026 10:59:09 +0100 Subject: [PATCH 5/7] feat(storefront): pd build fails on custom properties nothing defines A var(--x) without a fallback in the project's own styles, with no --x in any compiled stylesheet of the style guide or its packages, a stylesheet the site loads, or a style attribute the build writes, stops the build, naming file and line. Properties JavaScript sets go in storefront.checks.allowProperties. The CSS reading is shared with the class check. --- CHANGELOG.md | 6 ++ docs/guide/configuration.md | 1 + docs/guide/storefront.md | 19 ++++ packages/config/src/index.ts | 5 +- packages/config/src/validate.spec.ts | 8 +- packages/config/src/validate.ts | 2 +- packages/dev-server/src/index.ts | 2 +- packages/dev-server/src/server-config.ts | 3 +- packages/dev-server/src/static-build.ts | 27 +++++- packages/dev-server/src/storefront/crawl.ts | 2 +- .../src/storefront/css-vocabulary.ts | 97 +++++++++++++++++-- .../src/storefront/property-check.ts | 50 ++++++++++ .../dev-server/test/css-vocabulary.spec.ts | 52 ++++++++-- .../test/storefront-style-checks.spec.ts | 34 ++++++- 14 files changed, 280 insertions(+), 28 deletions(-) create mode 100644 packages/dev-server/src/storefront/property-check.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 84a6f4f..b3cd0c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ ### Changed +- **A skin that reads a custom property nothing defines no longer builds:** a `var(--x)` without a fallback in the + project's styles needs `--x` defined in the style guide or its packages, a fallback, or `--x` listed in + `storefront.checks.allowProperties` (see Added). - `toc` is a key the build owns now (the table of contents): a layout's schema that declares it must rename it. - **A storefront page's "last changed" date is the author's, never git's.** Git's last commit counts a typo fix or a reformat as a change, so it is no longer used for anything a reader or a search engine sees. A page sets @@ -41,6 +44,9 @@ defines, naming the page's file and line: `about.md:12: class "hero-big-title" isn't defined by any component or style`. State classes (`is-`, `has-`, `js-`) and Pattern Dump's own are allowed, and so is `storefront.checks.allowClasses`. A warning; `storefront.checks.classes: "error"` stops the build, `"off"` skips it. +- **Custom properties nothing defines stop the build.** A `var(--x)` without a fallback in the project's own styles, + with no `--x` in any stylesheet of the style guide or its packages (or a `style` attribute the build writes), fails + `pd build`, naming the file and line. A property JavaScript sets goes in `storefront.checks.allowProperties`. - **`llms.txt`.** `pd build` writes one at the site's root (llmstxt.org): the site's title and description, then the top-level pages and each collection, every page with its title, link and teaser. The same pages as the sitemap; absolute URLs with `storefront.url`, under the site's path. On by default; `storefront.llms: false` turns it off. diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 8894e98..d2cdaf6 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -192,6 +192,7 @@ in [storefront.md](storefront.md). | `storefront.llms` | boolean | `true` (`false` with `index: false`) | `pd build` writes `llms.txt` at the site's root: the site's title and description and each page's title, link and teaser, by collection ([storefront.md](storefront.md#search-engines-and-link-previews)). `false`: none | | `storefront.checks.classes` | `"warning"`, `"error"` or `"off"` | `"warning"` | The class check: a class on a page that no component or style of the style guide defines is listed in the report, stops the build, or isn't checked ([storefront.md](storefront.md#the-class-check)) | | `storefront.checks.allowClasses` | list of strings | `[]` | Classes a page may carry anyway: names, or a prefix ending in `*` (`"chart-*"`) | +| `storefront.checks.allowProperties` | list of strings | `[]` | Custom properties JavaScript sets, which the skin's `var()` may read with no definition in CSS: names, or a prefix ending in `*` (`"--chart-*"`). Any other `var()` without a fallback and without a definition stops the build ([storefront.md](storefront.md#custom-properties-nothing-defines)) | | `storefront.site` | object | (none) | Values every page shares, such as the site's title or footer line. Every layout gets them as `site`, and a page cannot set them. Their keys and types are what the `site` property of `partials/base`'s schema declares, and they are checked against it. One key is Pattern Dump's: `navigations`, named lists of links ([storefront.md](storefront.md#declared-navigations)) | ## When changes take effect diff --git a/docs/guide/storefront.md b/docs/guide/storefront.md index fde2f68..a7fd757 100644 --- a/docs/guide/storefront.md +++ b/docs/guide/storefront.md @@ -1217,6 +1217,25 @@ person or an agent wrote it. A warning by default; with `storefront.checks.classes: "error"` it stops the build, and `"off"` skips the check. +### Custom properties nothing defines + +A `var(--x)` in the project's own styles (its styles folder, SCSS or CSS) with no `--x` defined anywhere stops the +build, naming the file and line. Without the check it falls back to nothing, and a colour just goes missing on screen. + +- **Defined:** `--x:` or `@property --x` in any compiled stylesheet of the style guide (the project's and its + packages', the base layer and the themes) or one the site loads, and `--x:` in a `style` attribute of a page or + preview the build writes (`style="--cols: {{cols}}"` in a template). +- `var(--x, fallback)` is fine: it says what to show without `--x`. A name Sass builds (`var(--#{$name})`) and a + `var()` in a comment are not checked. A package's own stylesheets are not checked: they are not the project's to fix. +- A property JavaScript sets goes in `storefront.checks.allowProperties` (a trailing `*` for a prefix). + +``` +pd build: the skin reads custom properties nothing defines, so nothing was written: + - src/styles/components/card.scss:42: var(--card-gap) reads a custom property nothing defines: define --card-gap + in the skin, give it a fallback (var(--card-gap, ...)), or, if JavaScript sets it, list it in + storefront.checks.allowProperties +``` + ### The accessibility check After the link check, `pd build` checks every page of the site (not the previews or the pages that forward from old diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts index ab6c159..d0408e6 100644 --- a/packages/config/src/index.ts +++ b/packages/config/src/index.ts @@ -271,7 +271,7 @@ export interface StorefrontConfig { checks?: StorefrontChecks; } -/** storefront.checks: what pd build checks the site's classes against. */ +/** storefront.checks: what pd build checks the site's classes and custom properties against. */ export interface StorefrontChecks { /** * A class on a page that no component or style of the style guide defines: `"warning"` (the default) lists it in @@ -280,6 +280,9 @@ export interface StorefrontChecks { classes?: "warning" | "error" | "off"; /** Classes a page may carry anyway: names, or a prefix ending in `*` (`"chart-*"`). */ allowClasses?: string[]; + /** Custom properties JavaScript sets, which a skin's var() may read without a definition in CSS: names, or a prefix + * ending in `*` (`"--chart-*"`). */ + allowProperties?: string[]; } /** storefront.tagPages and storefront.categoryPages as an object. */ diff --git a/packages/config/src/validate.spec.ts b/packages/config/src/validate.spec.ts index eab2ab1..904546a 100644 --- a/packages/config/src/validate.spec.ts +++ b/packages/config/src/validate.spec.ts @@ -271,11 +271,11 @@ describe("configProblems — storefront", () => { expect(storefront({ ...base, llms: "no" })).toEqual([`"storefront.llms" must be true or false`]); }); - it("takes checks: classes warning, error or off, and a list of allowed classes", () => { + it("takes checks: classes warning, error or off, and lists of allowed classes and properties", () => { const base = { pagesDir: "./pages", outDir: "./www" }; - expect(storefront({ ...base, checks: { classes: "error", allowClasses: ["chart-*"] } })).toEqual([]); - expect(storefront({ ...base, checks: { classes: "strict", allowClasses: "chart-*", allowClass: [] } })).toEqual([ - `unknown key "storefront.checks.allowClass": did you mean "storefront.checks.allowClasses"?`, + expect(storefront({ ...base, checks: { classes: "error", allowClasses: ["chart-*"], allowProperties: ["--x"] } })).toEqual([]); + expect(storefront({ ...base, checks: { classes: "strict", allowClasses: "chart-*", allowProperty: [] } })).toEqual([ + `unknown key "storefront.checks.allowProperty": did you mean "storefront.checks.allowProperties"?`, `"storefront.checks.classes" must be "warning" or "error" or "off"`, `"storefront.checks.allowClasses" must be a list of strings`, ]); diff --git a/packages/config/src/validate.ts b/packages/config/src/validate.ts index 4eb0467..c6b7931 100644 --- a/packages/config/src/validate.ts +++ b/packages/config/src/validate.ts @@ -65,7 +65,7 @@ const SHAPE: Shape = { url: "site-url", lang: "lang", index: "boolean", image: "asset-path", images: IMAGES, head: "hbs-file", categories: "categories", tags: "tags", tagPages: "term-pages", categoryPages: "term-pages", search: "boolean", llms: "boolean", - checks: { keys: { classes: { values: ["warning", "error", "off"] }, allowClasses: "strings" } }, + checks: { keys: { classes: { values: ["warning", "error", "off"] }, allowClasses: "strings", allowProperties: "strings" } }, }, required: ["pagesDir", "outDir"], }, diff --git a/packages/dev-server/src/index.ts b/packages/dev-server/src/index.ts index d3ea328..7dfc34c 100644 --- a/packages/dev-server/src/index.ts +++ b/packages/dev-server/src/index.ts @@ -154,7 +154,7 @@ export interface DevServerOptions { export interface DevServer { port: number; close(): Promise<void>; - /** For pd build's class check (class-check.ts), not part of the HTTP contract: every compiled + /** For pd build's style checks (class-check.ts, property-check.ts), not part of the HTTP contract: every compiled * stylesheet of the style guide (each component's, the base layer, each theme; project and packages) and every * component template's source. */ styleGuide(): Promise<StyleGuideSources>; diff --git a/packages/dev-server/src/server-config.ts b/packages/dev-server/src/server-config.ts index 6e66956..dd9f1ab 100644 --- a/packages/dev-server/src/server-config.ts +++ b/packages/dev-server/src/server-config.ts @@ -110,7 +110,7 @@ export interface ResolvedConfig { /** storefront.llms: pd build writes llms.txt; false for a site with index: false. */ readonly llms: boolean; /** storefront.checks, with its defaults: the class check warns, nothing is allowed beyond the built-in lists. */ - readonly checks: { readonly classes: "warning" | "error" | "off"; readonly allowClasses: readonly string[] }; + readonly checks: { readonly classes: "warning" | "error" | "off"; readonly allowClasses: readonly string[]; readonly allowProperties: readonly string[] }; /** storefront.search as the config writes it (search.ts reads it). */ readonly search: boolean | undefined; } | null; @@ -261,6 +261,7 @@ export function resolveServerConfig( checks: { classes: config.storefront.checks?.classes ?? "warning", allowClasses: config.storefront.checks?.allowClasses ?? [], + allowProperties: config.storefront.checks?.allowProperties ?? [], }, } : null, images, diff --git a/packages/dev-server/src/static-build.ts b/packages/dev-server/src/static-build.ts index 2d87baa..66f3d1a 100644 --- a/packages/dev-server/src/static-build.ts +++ b/packages/dev-server/src/static-build.ts @@ -33,6 +33,7 @@ import { loadProjectPlaywright, runBrowserChecks, VIEWPORTS, type PlaywrightModu import { runPageA11y, type PageA11yFinding } from "@pattern-dump/a11y"; import { llmsTxt, workbenchRobotsTxt } from "./storefront/site-files.js"; import { checkClasses } from "./storefront/class-check.js"; +import { checkProperties } from "./storefront/property-check.js"; import { withNoindex } from "./storefront/base-path.js"; import { buildSearchIndex, SEARCH_PATH, searchPagefind, type PagefindModule, type SearchRecord } from "./storefront/search.js"; @@ -245,8 +246,9 @@ export async function buildStaticSite( linkSummary = { pages: pages.length, references: links.references, external: links.external.size }; log(`… links checked: ${links.references} references on ${pages.length} pages`); - // The class check, also before anything is written (class-check.ts): every class a site page carries is defined - // by the style guide (a warning unless storefront.checks.classes says otherwise). + // The style checks, also before anything is written (class-check.ts, property-check.ts): every class a site page + // carries is defined by the style guide (a warning unless storefront.checks.classes says otherwise), and every + // var() the skin's own styles read without a fallback has a definition somewhere (an error). pageModel = await readPages(storefront.pagesDir, { drafts: "leave-out", scheduled: "leave-out", today, categories: storefront.categories, tags: storefront.tags, }); @@ -256,6 +258,11 @@ export async function buildStaticSite( await server.close(); throw new Error(`pd build: ${what}, so nothing was written:\n${lines.map(l => ` - ${l}`).join("\n")}`); }; + const properties = checkProperties({ + sources: await styleSources(cfg.stylesDir, project), stylesheets, documents: [...sfCrawl.documents.values()], + allow: storefront.checks.allowProperties, + }); + if (properties.length) await fail("the skin reads custom properties nothing defines", properties); if (storefront.checks.classes !== "off") { const model = pageModel; const checkPages = await Promise.all(pages.flatMap(route => { @@ -523,3 +530,19 @@ export async function buildStaticSite( report.ms = Math.round(performance.now() - started); return report; } + +/** The project's own style sources (SCSS and CSS) under `stylesDir`, each by its path from the project's root. */ +async function styleSources(stylesDir: string, project: string): Promise<{ path: string; text: string }[]> { + const out: { path: string; text: string }[] = []; + const walk = async (dir: string): Promise<void> => { + let entries; + try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; } + for (const e of entries.sort((a, b) => a.name < b.name ? -1 : 1)) { + const p = join(dir, e.name); + if (e.isDirectory()) await walk(p); + else if (/\.(?:scss|css)$/.test(e.name)) out.push({ path: relative(project, p).split(sep).join("/"), text: await readFile(p, "utf8") }); + } + }; + await walk(stylesDir); + return out; +} diff --git a/packages/dev-server/src/storefront/crawl.ts b/packages/dev-server/src/storefront/crawl.ts index c844fcc..4c7e9fd 100644 --- a/packages/dev-server/src/storefront/crawl.ts +++ b/packages/dev-server/src/storefront/crawl.ts @@ -55,7 +55,7 @@ export interface StorefrontCrawl { problems: string[]; /** The HTML of every document crawled, by its URL: the link check reads it (links.ts). */ documents: Map<string, string>; - /** Every stylesheet crawled, by its URL: the class check reads it (class-check.ts). */ + /** Every stylesheet crawled, by its URL: the style checks read it (class-check.ts, property-check.ts). */ stylesheets: Map<string, string>; } diff --git a/packages/dev-server/src/storefront/css-vocabulary.ts b/packages/dev-server/src/storefront/css-vocabulary.ts index e467976..ad15c36 100644 --- a/packages/dev-server/src/storefront/css-vocabulary.ts +++ b/packages/dev-server/src/storefront/css-vocabulary.ts @@ -1,11 +1,48 @@ -// What a stylesheet says, for pd build's class check (class-check.ts): the classes its selectors name. Compiled CSS is -// read with postcss: what it names is what a browser gets, whatever Sass built it from. +// What a stylesheet says, for pd build's two style checks (class-check.ts, property-check.ts): the classes its +// selectors name, the custom properties it defines, and each var() it reads without a fallback, with its line. +// +// - Compiled CSS is read with postcss (readCss): what it defines is what a browser gets, whatever Sass built it from. +// - A project's style sources (SCSS or CSS) are scanned as text (sourceVarUses), comments taken out, for where a +// var() is written. A name Sass builds (`--#{$name}`) is not a name yet, so it is skipped, never guessed. +// - Defined: `--x: ...` in any rule or at-rule, and `@property --x`. +// - A use: `var(--x)`. `var(--x, fallback)` has a fallback and is no use to check; a var() inside the fallback is +// read on its own (`var(--a, var(--b))` uses --b). import postcss from "postcss"; import selectorParser from "postcss-selector-parser"; +/** A var() without a fallback: the property it reads, and where (1-based). */ +export interface VarUse { name: string; line: number; column: number } + export interface CssVocabulary { classes: Set<string>; + properties: Set<string>; + uses: VarUse[]; +} + +const SASS_NAME = /#\{/; +const NAME = /^--[\w-]+$/; + +/** Every var() in `text` without a fallback, by its offset: a scan that matches parentheses, so a var() inside + * another's fallback, or inside calc(), is found too. Quoted strings are skipped. */ +export function varUses(source: string): { name: string; offset: number }[] { + const out: { name: string; offset: number }[] = []; + // A string's contents blanked, offsets kept: nothing in quotes is a var() or a parenthesis. + const text = source.replace(/"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/g, q => `${q[0]}${" ".repeat(q.length - 2)}${q[0]}`); + const re = /\bvar\(/gi; + for (let m = re.exec(text); m; m = re.exec(text)) { + let depth = 1, i = m.index + m[0].length, comma = -1; + for (; i < text.length && depth > 0; i++) { + const c = text[i]!; + if (c === "(") depth++; + else if (c === ")") depth--; + else if (c === "," && depth === 1 && comma < 0) comma = i; + } + const end = comma >= 0 ? comma : i - 1; + const name = text.slice(m.index + m[0].length, end).trim(); + if (comma < 0 && NAME.test(name) && !SASS_NAME.test(name)) out.push({ name, offset: m.index }); + } + return out; } /** The classes a selector names. */ @@ -17,17 +54,63 @@ export function selectorClassNames(selector: string): string[] { return out; } -/** The classes of compiled CSS. */ +const position = (text: string, offset: number): { line: number; column: number } => { + const before = text.slice(0, offset).split("\n"); + return { line: before.length, column: before.at(-1)!.length + 1 }; +}; + +/** The classes, defined custom properties and var() uses (by line in `text`) of compiled CSS. */ export function readCss(text: string): CssVocabulary { - const classes = new Set<string>(); + const classes = new Set<string>(), properties = new Set<string>(), uses: VarUse[] = []; let root: postcss.Root; try { root = postcss.parse(text); } catch { - return { classes }; + return { classes, properties, uses }; + } + root.walk(node => { + if (node.type === "rule") { + for (const c of selectorClassNames(node.selector)) classes.add(c); + } else if (node.type === "atrule") { + if (node.name.toLowerCase() === "property" && NAME.test(node.params.trim())) properties.add(node.params.trim()); + } else if (node.type === "decl") { + if (NAME.test(node.prop)) properties.add(node.prop); + const at = node.source?.start?.offset; + for (const u of varUses(node.value)) { + // Where the value starts in the text, when postcss says; else the declaration's own line. + const start = at !== undefined ? text.indexOf(node.value, at) : -1; + const p = start >= 0 ? position(text, start + u.offset) : { line: node.source?.start?.line ?? 0, column: node.source?.start?.column ?? 0 }; + uses.push({ name: u.name, ...p }); + } + } + }); + return { classes, properties, uses }; +} + +/** `text` with its comments blanked (newlines kept, so lines and columns stay): `/* *\/`, and in SCSS `//` to the end + * of the line where it starts a comment (at a line's start, or after a space, `;`, `{` or `}`: never in `url(https://...)`). */ +export function withoutComments(text: string, scss: boolean): string { + const blank = (s: string): string => s.replace(/[^\n]/g, " "); + let out = text.replace(/\/\*[\s\S]*?\*\//g, blank); + if (scss) out = out.replace(/(^|[\s;{}])(\/\/[^\n]*)/g, (_, pre: string, c: string) => pre + blank(c)); + return out; +} + +/** Each var() without a fallback written in a style source (SCSS or CSS), with its line and column. */ +export function sourceVarUses(text: string, scss: boolean): VarUse[] { + const clean = withoutComments(text, scss); + return varUses(clean).map(u => ({ name: u.name, ...position(clean, u.offset) })); +} + +/** The custom properties a `style` attribute's text sets. */ +export function inlineProperties(style: string): string[] { + try { + const out: string[] = []; + postcss.parse(`x{${style}}`).walkDecls(d => { if (NAME.test(d.prop)) out.push(d.prop); }); + return out; + } catch { + return []; } - root.walkRules(rule => { for (const c of selectorClassNames(rule.selector)) classes.add(c); }); - return { classes }; } /** A matcher for names and prefixes (`is-*`): true for a name one of `patterns` covers. */ diff --git a/packages/dev-server/src/storefront/property-check.ts b/packages/dev-server/src/storefront/property-check.ts new file mode 100644 index 0000000..3079b10 --- /dev/null +++ b/packages/dev-server/src/storefront/property-check.ts @@ -0,0 +1,50 @@ +// Undefined custom properties: pd build fails on a var(--x) in the project's own style sources with no --x defined +// anywhere, naming file and line. Without the check it silently falls back to nothing, and a colour just goes +// missing on screen. +// +// - Checked: each var() without a fallback written in the project's styles folder (SCSS or CSS). A pattern +// package's stylesheets are not the project's to fix, so they are not checked; what they define counts. +// - Defined: `--x:` or `@property --x` in any compiled stylesheet of the style guide (project and packages, its +// base and themes), or in a stylesheet the site loads; `--x:` in a style attribute of any page or preview the +// build writes; and storefront.checks.allowProperties, for what JavaScript sets. +// - var(--x, fallback) is fine: it says what to show without --x. + +import { inlineProperties, nameMatcher, readCss, sourceVarUses } from "./css-vocabulary.js"; + +export interface PropertyCheckInput { + /** The project's own style sources: path (as the message names it) and text. */ + sources: readonly { path: string; text: string }[]; + /** Every compiled stylesheet of the style guide, and every stylesheet the site loads. */ + stylesheets: readonly string[]; + /** Every document the build writes (pages, previews): their style attributes set properties too. */ + documents: readonly string[]; + /** storefront.checks.allowProperties. */ + allow?: readonly string[]; +} + +/** The properties `stylesheets` and `documents` define. */ +export function definedProperties(stylesheets: readonly string[], documents: readonly string[]): Set<string> { + const defined = new Set<string>(); + for (const css of stylesheets) for (const p of readCss(css).properties) defined.add(p); + for (const html of documents) { + for (const m of html.matchAll(/\sstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) { + for (const p of inlineProperties((m[1] ?? m[2] ?? "").replace(/"/g, `"`).replace(/&/g, "&"))) defined.add(p); + } + } + return defined; +} + +/** One line per use of an undefined property, by file and line: `styles/card.scss:4: var(--card-gap) ...`. */ +export function checkProperties(input: PropertyCheckInput): string[] { + const defined = definedProperties(input.stylesheets, input.documents); + const allowed = nameMatcher(input.allow ?? []); + const out: string[] = []; + for (const s of input.sources) { + for (const u of sourceVarUses(s.text, s.path.endsWith(".scss"))) { + if (defined.has(u.name) || allowed(u.name)) continue; + out.push(`${s.path}:${u.line}: var(${u.name}) reads a custom property nothing defines: define ${u.name} in the skin, ` + + `give it a fallback (var(${u.name}, ...)), or, if JavaScript sets it, list it in storefront.checks.allowProperties`); + } + } + return out; +} diff --git a/packages/dev-server/test/css-vocabulary.spec.ts b/packages/dev-server/test/css-vocabulary.spec.ts index 6c557b5..3abeaeb 100644 --- a/packages/dev-server/test/css-vocabulary.spec.ts +++ b/packages/dev-server/test/css-vocabulary.spec.ts @@ -1,17 +1,53 @@ -// The class check's readers: the classes a stylesheet names (css-vocabulary.ts), and what a template and a built -// page write as classes (class-check.ts). +// The style checks' readers: what a stylesheet defines and reads (css-vocabulary.ts), and what a template and a +// built page write as classes (class-check.ts). import { describe, expect, it } from "vitest"; -import { nameMatcher, readCss } from "../src/storefront/css-vocabulary.js"; +import { inlineProperties, nameMatcher, readCss, sourceVarUses, varUses } from "../src/storefront/css-vocabulary.js"; import { checkClasses, documentClasses, templateClasses } from "../src/storefront/class-check.js"; -describe("readCss and nameMatcher", () => { - it("names the classes of every selector, and reads nothing from text that isn't CSS, rather than failing", () => { - expect([...readCss(".a .b:hover, .c > .d { color: red; }\n@media (width > 1px) { .e { margin: 0; } }").classes].sort()) - .toEqual(["a", "b", "c", "d", "e"]); +describe("varUses", () => { + it("finds a var() without a fallback, inside calc() and inside another's fallback, and skips one with a fallback", () => { + expect(varUses("calc(var(--a) + var(--b, 1px))").map(u => u.name)).toEqual(["--a"]); + expect(varUses("var(--x, var(--y))").map(u => u.name)).toEqual(["--y"]); + expect(varUses("var(--x, var(--y, red))")).toEqual([]); + expect(varUses(`var( --spaced )`).map(u => u.name)).toEqual(["--spaced"]); + }); + + it("skips a name Sass builds, and a var() in a quoted string", () => { + expect(varUses("var(--#{$name})")).toEqual([]); + expect(varUses(`"var(--quoted)" var(--real)`).map(u => u.name)).toEqual(["--real"]); + }); +}); + +describe("readCss", () => { + it("names the classes of every selector, the properties defined, and each var() read, by line", () => { + const v = readCss(".a .b:hover, .c > .d { --x: 1; color: var(--y); }\n@property --z { syntax: '*'; inherits: false; }\n.e { margin:\n var(--w); }"); + expect([...v.classes].sort()).toEqual(["a", "b", "c", "d", "e"]); + expect([...v.properties].sort()).toEqual(["--x", "--z"]); + expect(v.uses).toEqual([{ name: "--y", line: 1, column: 39 }, { name: "--w", line: 4, column: 3 }]); + }); + + it("reads nothing from text that isn't CSS, rather than failing", () => { expect(readCss("{{{").classes.size).toBe(0); }); +}); + +describe("sourceVarUses", () => { + it("finds var() in SCSS by line and column, outside comments, and leaves a URL's // alone", () => { + const scss = [ + "// var(--commented)", + ".a { /* var(--blocked) */ color: var(--real); }", + ".b { background: url(https://example.test/x.png); border-color: var(--after-url); }", + ].join("\n"); + expect(sourceVarUses(scss, true)).toEqual([ + { name: "--real", line: 2, column: 34 }, + { name: "--after-url", line: 3, column: 65 }, + ]); + }); +}); - it("matches names and prefixes", () => { +describe("inlineProperties and nameMatcher", () => { + it("reads the custom properties of a style attribute, and matches names and prefixes", () => { + expect(inlineProperties("--cols: 3; color: red; --gap:1rem")).toEqual(["--cols", "--gap"]); const m = nameMatcher(["exact", "pre-*"]); expect([m("exact"), m("pre-fix"), m("pre"), m("exactly")]).toEqual([true, true, false, false]); }); diff --git a/packages/dev-server/test/storefront-style-checks.spec.ts b/packages/dev-server/test/storefront-style-checks.spec.ts index 5df93d7..c381cdf 100644 --- a/packages/dev-server/test/storefront-style-checks.spec.ts +++ b/packages/dev-server/test/storefront-style-checks.spec.ts @@ -1,5 +1,6 @@ -// pd build's class check on a storefront, on copies of the bench: a class on a page that nothing in the style guide -// defines (a warning, or an error with storefront.checks.classes), naming file and line. +// pd build's two style checks on a storefront, on copies of the bench: a class on a page that nothing in the style +// guide defines (a warning, or an error with storefront.checks.classes), and a var() in the skin's own styles with no +// definition anywhere (an error), each naming file and line. import { afterAll, beforeAll, describe, expect, it } from "vitest"; import { execFileSync } from "node:child_process"; import { cp, mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises"; @@ -91,3 +92,32 @@ describe("pd build — classes outside the design system", () => { expect((await build(root)).classes?.warnings).toEqual([]); }, 60_000); }); + +describe("pd build — custom properties nothing defines", () => { + it("stops the build on a var() in the skin with no definition, naming file and line, and writes nothing", async () => { + const root = await benchCopy(); + const card = join(root, "src", "styles", "components", "card.scss"); + await append(card, `\n.card-title {\n color: var(--wf-ink-missing);\n}\n`); + const line = await lineIn(card, "--wf-ink-missing"); + await expect(build(root)).rejects.toThrow( + `src/styles/components/card.scss:${line}: var(--wf-ink-missing) reads a custom property nothing defines`); + expect(await exists(join(root, ".out", "storefront"))).toBe(false); + }, 60_000); + + it("builds with a fallback, with allowProperties, and with the property set in a component's style attribute", async () => { + const root = await benchCopy(); + const card = join(root, "src", "styles", "components", "card.scss"); + await append(card, `\n.card-title {\n color: var(--wf-ink-missing, currentColor);\n gap: var(--js-gap);\n margin: var(--badge-size);\n}\n`); + // The badge's template sets --badge-size in a style attribute, on a page the build writes. + await placeBadge(root, ""); + await build(root, config({ allowProperties: ["--js-*"] })); + await expect(build(root)).rejects.toThrow(/var\(--js-gap\)/); + }, 90_000); + + it("skips a var() in a comment, and one whose name Sass builds", async () => { + const root = await benchCopy(); + await append(join(root, "src", "styles", "components", "card.scss"), + `\n// color: var(--in-a-comment);\n/* var(--in-a-block) */\n$k: x;\n.card-title { color: var(--wf-#{$k}); }\n`); + await build(root); + }, 60_000); +}); From 072d39e0746f8baf1289960fe0fbe2b88a0180b3 Mon Sep 17 00:00:00 2001 From: Stefan Bauer <stefan.bauer@n8d.at> Date: Mon, 16 Nov 2026 12:16:53 +0100 Subject: [PATCH 6/7] test: split the storefront build settings into spec files of their own storefront-build.spec.ts took about 190 s a run on a loaded runner, so its 20 burn-in repeats alone came to more than the job's 60 minutes, and the burn-in groups split by file, never within one. Its settings tests move, unchanged, into three files: storefront-build-settings.spec.ts (workbench URL, storefront.url, sitemap, robots.txt, the 404 page and the output folders), storefront-build-same-host.spec.ts (a workbench on the storefront's host and its base path) and storefront-llms.spec.ts. The same 34 tests run. --- .../test/storefront-build-same-host.spec.ts | 112 ++++++++++ .../test/storefront-build-settings.spec.ts | 133 ++++++++++++ .../dev-server/test/storefront-build.spec.ts | 194 +----------------- .../dev-server/test/storefront-llms.spec.ts | 74 +++++++ 4 files changed, 320 insertions(+), 193 deletions(-) create mode 100644 packages/dev-server/test/storefront-build-same-host.spec.ts create mode 100644 packages/dev-server/test/storefront-build-settings.spec.ts create mode 100644 packages/dev-server/test/storefront-llms.spec.ts diff --git a/packages/dev-server/test/storefront-build-same-host.spec.ts b/packages/dev-server/test/storefront-build-same-host.spec.ts new file mode 100644 index 0000000..8229cef --- /dev/null +++ b/packages/dev-server/test/storefront-build-same-host.spec.ts @@ -0,0 +1,112 @@ +// pd build with the workbench published on the storefront's own host: robots.txt keeps its previews out, +// a page can't take its place, and the workbench must be built for its path. Split from +// storefront-build.spec.ts to keep each file's burn-in inside its time budget. +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { execFileSync } from "node:child_process"; +import { cp, mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { validateConfig, type PatternDumpConfig } from "@pattern-dump/config"; +import { buildStaticSite } from "@pattern-dump/dev-server"; +import benchConfig from "../../../storefront-bench/pattern-dump.config.js"; +import { save } from "../../../test-support/save.js"; + +const repo = fileURLToPath(new URL("../../../", import.meta.url)); +// A fixed clock, after every date the bench's pages carry: the build's day decides which pages are scheduled. +const NOW = new Date("2027-01-02T03:04:05.000Z"); +let tmp = ""; + +beforeAll(async () => { tmp = await mkdtemp(join(tmpdir(), "pd-sf-same-host-")); }); +afterAll(async () => { if (tmp) await rm(tmp, { recursive: true, force: true }); }); + +let n = 0; +async function benchCopy(): Promise<string> { + const root = join(tmp, `bench-${n++}`); + for (const file of execFileSync("git", ["ls-files", "storefront-bench"], { cwd: repo, encoding: "utf8" }).split("\n").filter(Boolean)) { + const to = join(root, file.slice("storefront-bench/".length)); + await mkdir(dirname(to), { recursive: true }); + await cp(join(repo, file), to); + } + return root; +} +const config = (over: Partial<NonNullable<PatternDumpConfig["storefront"]>> = {}): PatternDumpConfig => + validateConfig({ ...benchConfig, storefront: { ...benchConfig.storefront!, ...over } }, "test"); +const build = (root: string, out: string, cfg: PatternDumpConfig = config()) => + buildStaticSite(cfg, root, { outDir: out, pdVersion: "0.0.0-test", now: NOW }); +const exists = (p: string) => stat(p).then(() => true, () => false); + +describe("pd build — a workbench on the storefront's host", () => { + // A workbench published on the storefront's own host (storefront.workbenchUrl a path, or an absolute URL on + // storefront.url's origin): its previews are kept out by the storefront's robots.txt, at the host's root, so + // the build no longer asks for its rule to be copied there. + const sameHostNote = "robots.txt is written to the workbench's root, but crawlers read it only at a host's root: " + + "with the base path /workbench/, each preview carries a robots noindex tag instead; where you can, also add its rule " + + "(Disallow: /workbench/preview/) to the robots.txt the host serves at /"; + const buildAt = (root: string, out: string, cfg: PatternDumpConfig) => + buildStaticSite(cfg, root, { outDir: out, basePath: "/workbench/", pdVersion: "0.0.0-test", now: NOW }); + + it("a workbench at a path on the storefront's host: robots.txt keeps its previews out, and the build asks nothing", async () => { + const root = await benchCopy(); + const report = await buildAt(root, join(root, "..", "wb-samehost"), config({ workbenchUrl: "/workbench/" })); + expect(await readFile(join(root, ".out", "storefront", "robots.txt"), "utf8")) + .toBe("User-agent: *\nDisallow: /preview/\nDisallow: /workbench/preview/\n\nSitemap: https://bench.example.test/sitemap.xml\n"); + expect(report.notes).not.toContain(sameHostNote); + }, 60_000); + + it("an absolute workbenchUrl on the site's own origin counts as the same host", async () => { + const root = await benchCopy(); + const report = await buildAt(root, join(root, "..", "wb-sameorigin"), config({ workbenchUrl: "https://bench.example.test/workbench/" })); + expect(await readFile(join(root, ".out", "storefront", "robots.txt"), "utf8")).toContain("Disallow: /workbench/preview/\n"); + expect(report.notes).not.toContain(sameHostNote); + }, 60_000); + + it("a workbench on a host of its own: no line for it, and the build still says where its rule must go", async () => { + const root = await benchCopy(); + const report = await buildAt(root, join(root, "..", "wb-ownhost"), config({ workbenchUrl: "https://workbench.example.test/workbench/" })); + expect(await readFile(join(root, ".out", "storefront", "robots.txt"), "utf8")) + .toBe("User-agent: *\nDisallow: /preview/\n\nSitemap: https://bench.example.test/sitemap.xml\n"); + expect(report.notes).toContain(sameHostNote); + }, 60_000); + + it("fails on a page where the same-host workbench is published, naming it, and writes nothing", async () => { + const root = await benchCopy(); + await save(join(root, "pages", "workbench.md"), "---\ntitle: Workbench\n---\n\nA page in the workbench's place.\n"); + const out = join(root, "..", "wb-taken"); + await expect(buildAt(root, out, config({ workbenchUrl: "/workbench/" }))) + .rejects.toThrow(`workbench.md: the page /workbench/ is at /workbench/, where the workbench is published on this host (storefront.workbenchUrl), so the workbench would overwrite it there`); + expect(await exists(out)).toBe(false); + }, 60_000); + + // A same-host workbench is linked at its path, so the build must make it for that path. + const builtFor = (got: string) => `pd build: storefront.workbenchUrl is /workbench/, so the workbench must be built for /workbench/ ` + + `(build.basePath or --base); it is being built for ${got}`; + const withBase = (basePath: string | undefined) => validateConfig({ ...benchConfig, ...(basePath ? { build: { basePath } } : {}), + storefront: { ...benchConfig.storefront!, workbenchUrl: "/workbench/" } }, "test"); + + it("fails when the base path in the config is not the same-host workbench's path, and writes nothing", async () => { + const root = await benchCopy(); + const out = join(root, "..", "wb-base-config"); + await expect(build(root, out, withBase("/docs/"))).rejects.toThrow(builtFor("/docs/")); + expect(await exists(out)).toBe(false); + }, 60_000); + + it("fails when --base overrides a matching build.basePath with another path", async () => { + const root = await benchCopy(); + const out = join(root, "..", "wb-base-flag"); + await expect(buildStaticSite(withBase("/workbench/"), root, { outDir: out, basePath: "/docs/", pdVersion: "0.0.0-test", now: NOW })) + .rejects.toThrow(builtFor("/docs/")); + expect(await exists(out)).toBe(false); + }, 60_000); + + it("fails when no base path is given at all: the workbench would be built for /", async () => { + const root = await benchCopy(); + await expect(build(root, join(root, "..", "wb-base-none"), withBase(undefined))).rejects.toThrow(builtFor("/")); + }, 60_000); + + it("builds when --base names the same-host path in another spelling, and when build.basePath alone gives it", async () => { + const root = await benchCopy(); + await buildStaticSite(withBase(undefined), root, { outDir: join(root, "..", "wb-base-spelled"), basePath: "/workbench", pdVersion: "0.0.0-test", now: NOW }); + await build(root, join(root, "..", "wb-base-cfg-ok"), withBase("/workbench/")); + }, 60_000); +}); diff --git a/packages/dev-server/test/storefront-build-settings.spec.ts b/packages/dev-server/test/storefront-build-settings.spec.ts new file mode 100644 index 0000000..fb02f69 --- /dev/null +++ b/packages/dev-server/test/storefront-build-settings.spec.ts @@ -0,0 +1,133 @@ +// pd build and the storefront's settings: storefront.workbenchUrl and storefront.url, the sitemap and +// robots.txt, the 404 page, and where the output may go. Split from storefront-build.spec.ts to keep each +// file's burn-in inside its time budget. Built from copies of the bench, with a fixed clock. +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { execFileSync } from "node:child_process"; +import { cp, mkdir, mkdtemp, readFile, readdir, rm, stat } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join, relative } from "node:path"; +import { fileURLToPath } from "node:url"; +import { defineConfig, validateConfig, type PatternDumpConfig } from "@pattern-dump/config"; +import { buildStaticSite } from "@pattern-dump/dev-server"; +import benchConfig from "../../../storefront-bench/pattern-dump.config.js"; +import { save } from "../../../test-support/save.js"; + +const repo = fileURLToPath(new URL("../../../", import.meta.url)); +// A fixed clock, after every date the bench's pages carry: the build's day decides which pages are scheduled. +const NOW = new Date("2027-01-02T03:04:05.000Z"); +let tmp = ""; + +beforeAll(async () => { tmp = await mkdtemp(join(tmpdir(), "pd-sf-settings-")); }); +afterAll(async () => { if (tmp) await rm(tmp, { recursive: true, force: true }); }); + +let n = 0; +async function benchCopy(): Promise<string> { + const root = join(tmp, `bench-${n++}`); + for (const file of execFileSync("git", ["ls-files", "storefront-bench"], { cwd: repo, encoding: "utf8" }).split("\n").filter(Boolean)) { + const to = join(root, file.slice("storefront-bench/".length)); + await mkdir(dirname(to), { recursive: true }); + await cp(join(repo, file), to); + } + return root; +} +const config = (over: Partial<NonNullable<PatternDumpConfig["storefront"]>> = {}): PatternDumpConfig => + validateConfig({ ...benchConfig, storefront: { ...benchConfig.storefront!, ...over } }, "test"); +const build = (root: string, out: string, cfg: PatternDumpConfig = config()) => + buildStaticSite(cfg, root, { outDir: out, pdVersion: "0.0.0-test", now: NOW }); + +async function tree(dir: string): Promise<Map<string, { bytes: Buffer; mtimeMs: number }>> { + const out = new Map<string, { bytes: Buffer; mtimeMs: number }>(); + const walk = async (d: string): Promise<void> => { + for (const e of await readdir(d, { withFileTypes: true })) { + const p = join(d, e.name); + if (e.isDirectory()) await walk(p); + else out.set(relative(dir, p), { bytes: await readFile(p), mtimeMs: (await stat(p)).mtimeMs }); + } + }; + await walk(dir); + return out; +} +const exists = (p: string) => stat(p).then(() => true, () => false); + +describe("pd build — the storefront's settings", () => { + it("needs storefront.workbenchUrl, and writes nothing without it", async () => { + const root = await benchCopy(); + const { workbenchUrl: _w, ...rest } = benchConfig.storefront!; + const out = join(root, "..", "wb-nourl"); + await expect(buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, { outDir: out, pdVersion: "x" })) + .rejects.toThrow("pd build: storefront.workbenchUrl is required to build the storefront: its pages link into the workbench at that address"); + expect(await exists(out)).toBe(false); + }); + + it("without storefront.url: no canonical, Open Graph or card, and one note for the whole build", async () => { + const root = await benchCopy(); + const { url: _u, ...rest } = benchConfig.storefront!; + const report = await buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, + { outDir: join(root, "..", "wb-nosite"), pdVersion: "x", now: NOW }); + const note = `storefront.url is not set, so pages have no canonical URL, og:url, og:image or JSON-LD, ` + + `and there is no sitemap: set storefront.url to the site's address, such as "https://example.com/"`; + expect(report.notes.filter(n => n === note)).toHaveLength(1); + const pages = await tree(join(root, ".out", "storefront")); + for (const [file, { bytes }] of pages) { + if (file.endsWith(".html")) expect(bytes.toString("utf8"), file).not.toMatch(/rel="canonical"|property="og:|name="twitter:/); + } + }, 60_000); + + it("fails on an old route that is a page, naming it, and writes nothing", async () => { + const root = await benchCopy(); + const about = join(root, "pages", "about.md"); + await save(about, (await readFile(about, "utf8")).replace("title: About\n", "title: About\nredirectFrom: /guides/\n")); + const out = join(root, "..", "wb-redirect-page"); + await expect(build(root, out)).rejects.toThrow(`about.md:4: redirectFrom "/guides/" is the page guides/index.md: a route can't both be a page and forward to one`); + expect(await exists(out)).toBe(false); + }, 60_000); + + it("fails on a 404 page with a relative URL, naming it, and writes nothing", async () => { + const root = await benchCopy(); + await save(join(root, "pages", "404.md"), "---\ntitle: Lost\n---\n\nTry [the guides](./guides/).\n"); + const out = join(root, "..", "wb-rel404"); + await expect(build(root, out)).rejects.toThrow(`the 404 page (404.md): the URL "./guides/" is relative, and the 404 page is served at every address, ` + + `so it only works from the site's root: use "/guides/" instead`); + expect(await exists(out)).toBe(false); + }, 60_000); + + it("leaves a page with index: false out of the sitemap", async () => { + const root = await benchCopy(); + const setup = join(root, "pages", "guides", "setup.md"); + await save(setup, (await readFile(setup, "utf8")).replace("title: Setup\n", "title: Setup\nindex: false\n")); + await build(root, join(root, "..", "wb-noindex")); + const out = join(root, ".out", "storefront"); + const sitemap = await readFile(join(out, "sitemap.xml"), "utf8"); + expect(sitemap).not.toContain("/guides/setup/"); + expect(sitemap).toContain("<loc>https://bench.example.test/guides/</loc>"); + expect(await readFile(join(out, "guides", "setup", "index.html"), "utf8")).toContain(`<meta name="robots" content="noindex">`); + }, 60_000); + + it("a site with index: false: no sitemap, and robots.txt keeps everything out", async () => { + const root = await benchCopy(); + await build(root, join(root, "..", "wb-staging"), config({ index: false })); + const out = join(root, ".out", "storefront"); + expect(await exists(join(out, "sitemap.xml"))).toBe(false); + expect(await readFile(join(out, "robots.txt"), "utf8")).toBe("User-agent: *\nDisallow: /\n"); + }, 60_000); + + it("without storefront.url: no sitemap, and robots.txt names none", async () => { + const root = await benchCopy(); + const { url: _u, ...rest } = benchConfig.storefront!; + await buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, { outDir: join(root, "..", "wb-nourl2"), pdVersion: "x", now: NOW }); + const out = join(root, ".out", "storefront"); + expect(await exists(join(out, "sitemap.xml"))).toBe(false); + expect(await readFile(join(out, "robots.txt"), "utf8")).toBe("User-agent: *\nDisallow: /preview/\n"); + }, 60_000); + + it("keeps the storefront's output apart from the workbench's and from what PD reads", async () => { + const root = await benchCopy(); + await expect(build(root, join(root, ".out", "storefront"))).rejects.toThrow(/and --out .* overlap: the storefront and the workbench each need a folder of their own/); + await expect(build(root, join(root, "..", "wb-x"), config({ outDir: "./src/styles/out" }))).rejects.toThrow(/storefront\.outDir .* overlaps .*styles, which Pattern Dump reads/); + // An output root that contains the project is already refused by the config (it holds the pages and the + // patterns); the build refuses it too, for a config that never went through validation. + expect(() => config({ outDir: "." })).toThrow(/"storefront\.pagesDir" \("\.\/pages"\) is inside "storefront\.outDir" \("\."\)/); + const unvalidated = defineConfig({ ...benchConfig, storefront: { ...benchConfig.storefront!, outDir: "." } }); + await expect(build(root, join(root, "..", "wb-y"), unvalidated)).rejects.toThrow(/storefront\.outDir .* would contain the project itself/); + }); +}); diff --git a/packages/dev-server/test/storefront-build.spec.ts b/packages/dev-server/test/storefront-build.spec.ts index 80dcc12..ac3b702 100644 --- a/packages/dev-server/test/storefront-build.spec.ts +++ b/packages/dev-server/test/storefront-build.spec.ts @@ -9,7 +9,7 @@ import { cp, mkdir, mkdtemp, readFile, readdir, rm, stat } from "node:fs/promise import { tmpdir } from "node:os"; import { dirname, join, relative } from "node:path"; import { fileURLToPath } from "node:url"; -import { defineConfig, validateConfig, type PatternDumpConfig } from "@pattern-dump/config"; +import { validateConfig, type PatternDumpConfig } from "@pattern-dump/config"; import { buildStaticSite, startDevServer } from "@pattern-dump/dev-server"; import { relativeUrls } from "../src/storefront/page.js"; import benchConfig from "../../../storefront-bench/pattern-dump.config.js"; @@ -389,195 +389,3 @@ describe("pd build — a storefront with problems writes nothing", () => { } }, 120_000); }); - -describe("pd build — the storefront's settings", () => { - it("needs storefront.workbenchUrl, and writes nothing without it", async () => { - const root = await benchCopy(); - const { workbenchUrl: _w, ...rest } = benchConfig.storefront!; - const out = join(root, "..", "wb-nourl"); - await expect(buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, { outDir: out, pdVersion: "x" })) - .rejects.toThrow("pd build: storefront.workbenchUrl is required to build the storefront: its pages link into the workbench at that address"); - expect(await exists(out)).toBe(false); - }); - - it("without storefront.url: no canonical, Open Graph or card, and one note for the whole build", async () => { - const root = await benchCopy(); - const { url: _u, ...rest } = benchConfig.storefront!; - const report = await buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, - { outDir: join(root, "..", "wb-nosite"), pdVersion: "x", now: NOW }); - const note = `storefront.url is not set, so pages have no canonical URL, og:url, og:image or JSON-LD, ` - + `and there is no sitemap: set storefront.url to the site's address, such as "https://example.com/"`; - expect(report.notes.filter(n => n === note)).toHaveLength(1); - const pages = await tree(join(root, ".out", "storefront")); - for (const [file, { bytes }] of pages) { - if (file.endsWith(".html")) expect(bytes.toString("utf8"), file).not.toMatch(/rel="canonical"|property="og:|name="twitter:/); - } - }, 60_000); - - it("fails on an old route that is a page, naming it, and writes nothing", async () => { - const root = await benchCopy(); - const about = join(root, "pages", "about.md"); - await save(about, (await readFile(about, "utf8")).replace("title: About\n", "title: About\nredirectFrom: /guides/\n")); - const out = join(root, "..", "wb-redirect-page"); - await expect(build(root, out)).rejects.toThrow(`about.md:4: redirectFrom "/guides/" is the page guides/index.md: a route can't both be a page and forward to one`); - expect(await exists(out)).toBe(false); - }, 60_000); - - it("fails on a 404 page with a relative URL, naming it, and writes nothing", async () => { - const root = await benchCopy(); - await save(join(root, "pages", "404.md"), "---\ntitle: Lost\n---\n\nTry [the guides](./guides/).\n"); - const out = join(root, "..", "wb-rel404"); - await expect(build(root, out)).rejects.toThrow(`the 404 page (404.md): the URL "./guides/" is relative, and the 404 page is served at every address, ` - + `so it only works from the site's root: use "/guides/" instead`); - expect(await exists(out)).toBe(false); - }, 60_000); - - it("leaves a page with index: false out of the sitemap", async () => { - const root = await benchCopy(); - const setup = join(root, "pages", "guides", "setup.md"); - await save(setup, (await readFile(setup, "utf8")).replace("title: Setup\n", "title: Setup\nindex: false\n")); - await build(root, join(root, "..", "wb-noindex")); - const out = join(root, ".out", "storefront"); - const sitemap = await readFile(join(out, "sitemap.xml"), "utf8"); - expect(sitemap).not.toContain("/guides/setup/"); - expect(sitemap).toContain("<loc>https://bench.example.test/guides/</loc>"); - expect(await readFile(join(out, "guides", "setup", "index.html"), "utf8")).toContain(`<meta name="robots" content="noindex">`); - }, 60_000); - - it("a site with index: false: no sitemap, and robots.txt keeps everything out", async () => { - const root = await benchCopy(); - await build(root, join(root, "..", "wb-staging"), config({ index: false })); - const out = join(root, ".out", "storefront"); - expect(await exists(join(out, "sitemap.xml"))).toBe(false); - expect(await readFile(join(out, "robots.txt"), "utf8")).toBe("User-agent: *\nDisallow: /\n"); - }, 60_000); - - it("without storefront.url: no sitemap, and robots.txt names none", async () => { - const root = await benchCopy(); - const { url: _u, ...rest } = benchConfig.storefront!; - await buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, { outDir: join(root, "..", "wb-nourl2"), pdVersion: "x", now: NOW }); - const out = join(root, ".out", "storefront"); - expect(await exists(join(out, "sitemap.xml"))).toBe(false); - expect(await readFile(join(out, "robots.txt"), "utf8")).toBe("User-agent: *\nDisallow: /preview/\n"); - }, 60_000); - - // A workbench published on the storefront's own host (storefront.workbenchUrl a path, or an absolute URL on - // storefront.url's origin): its previews are kept out by the storefront's robots.txt, at the host's root, so - // the build no longer asks for its rule to be copied there. - const sameHostNote = "robots.txt is written to the workbench's root, but crawlers read it only at a host's root: " - + "with the base path /workbench/, each preview carries a robots noindex tag instead; where you can, also add its rule " - + "(Disallow: /workbench/preview/) to the robots.txt the host serves at /"; - const buildAt = (root: string, out: string, cfg: PatternDumpConfig) => - buildStaticSite(cfg, root, { outDir: out, basePath: "/workbench/", pdVersion: "0.0.0-test", now: NOW }); - - it("a workbench at a path on the storefront's host: robots.txt keeps its previews out, and the build asks nothing", async () => { - const root = await benchCopy(); - const report = await buildAt(root, join(root, "..", "wb-samehost"), config({ workbenchUrl: "/workbench/" })); - expect(await readFile(join(root, ".out", "storefront", "robots.txt"), "utf8")) - .toBe("User-agent: *\nDisallow: /preview/\nDisallow: /workbench/preview/\n\nSitemap: https://bench.example.test/sitemap.xml\n"); - expect(report.notes).not.toContain(sameHostNote); - }, 60_000); - - it("an absolute workbenchUrl on the site's own origin counts as the same host", async () => { - const root = await benchCopy(); - const report = await buildAt(root, join(root, "..", "wb-sameorigin"), config({ workbenchUrl: "https://bench.example.test/workbench/" })); - expect(await readFile(join(root, ".out", "storefront", "robots.txt"), "utf8")).toContain("Disallow: /workbench/preview/\n"); - expect(report.notes).not.toContain(sameHostNote); - }, 60_000); - - it("a workbench on a host of its own: no line for it, and the build still says where its rule must go", async () => { - const root = await benchCopy(); - const report = await buildAt(root, join(root, "..", "wb-ownhost"), config({ workbenchUrl: "https://workbench.example.test/workbench/" })); - expect(await readFile(join(root, ".out", "storefront", "robots.txt"), "utf8")) - .toBe("User-agent: *\nDisallow: /preview/\n\nSitemap: https://bench.example.test/sitemap.xml\n"); - expect(report.notes).toContain(sameHostNote); - }, 60_000); - - it("fails on a page where the same-host workbench is published, naming it, and writes nothing", async () => { - const root = await benchCopy(); - await save(join(root, "pages", "workbench.md"), "---\ntitle: Workbench\n---\n\nA page in the workbench's place.\n"); - const out = join(root, "..", "wb-taken"); - await expect(buildAt(root, out, config({ workbenchUrl: "/workbench/" }))) - .rejects.toThrow(`workbench.md: the page /workbench/ is at /workbench/, where the workbench is published on this host (storefront.workbenchUrl), so the workbench would overwrite it there`); - expect(await exists(out)).toBe(false); - }, 60_000); - - // A same-host workbench is linked at its path, so the build must make it for that path. - const builtFor = (got: string) => `pd build: storefront.workbenchUrl is /workbench/, so the workbench must be built for /workbench/ ` - + `(build.basePath or --base); it is being built for ${got}`; - const withBase = (basePath: string | undefined) => validateConfig({ ...benchConfig, ...(basePath ? { build: { basePath } } : {}), - storefront: { ...benchConfig.storefront!, workbenchUrl: "/workbench/" } }, "test"); - - it("fails when the base path in the config is not the same-host workbench's path, and writes nothing", async () => { - const root = await benchCopy(); - const out = join(root, "..", "wb-base-config"); - await expect(build(root, out, withBase("/docs/"))).rejects.toThrow(builtFor("/docs/")); - expect(await exists(out)).toBe(false); - }, 60_000); - - it("fails when --base overrides a matching build.basePath with another path", async () => { - const root = await benchCopy(); - const out = join(root, "..", "wb-base-flag"); - await expect(buildStaticSite(withBase("/workbench/"), root, { outDir: out, basePath: "/docs/", pdVersion: "0.0.0-test", now: NOW })) - .rejects.toThrow(builtFor("/docs/")); - expect(await exists(out)).toBe(false); - }, 60_000); - - it("fails when no base path is given at all: the workbench would be built for /", async () => { - const root = await benchCopy(); - await expect(build(root, join(root, "..", "wb-base-none"), withBase(undefined))).rejects.toThrow(builtFor("/")); - }, 60_000); - - it("builds when --base names the same-host path in another spelling, and when build.basePath alone gives it", async () => { - const root = await benchCopy(); - await buildStaticSite(withBase(undefined), root, { outDir: join(root, "..", "wb-base-spelled"), basePath: "/workbench", pdVersion: "0.0.0-test", now: NOW }); - await build(root, join(root, "..", "wb-base-cfg-ok"), withBase("/workbench/")); - }, 60_000); - - it("leaves drafts, scheduled pages and pages with index: false out of llms.txt", async () => { - const root = await benchCopy(); - const edit = async (path: string, from: string, to: string) => { - const file = join(root, "pages", path); - await save(file, (await readFile(file, "utf8")).replace(from, to)); - }; - await edit("guides/setup.md", "title: Setup\n", "title: Setup\nindex: false\n"); - await edit("articles/harbour.md", "date: 2026-11-01\n", "date: 2026-11-01\ndraft: true\n"); - // After the build's day (NOW): scheduled, so left out. - await edit("articles/plain.md", "date: 2026-10-02", "date: 2027-03-01"); - await build(root, join(root, "..", "wb-llms-out")); - const llms = await readFile(join(root, ".out", "storefront", "llms.txt"), "utf8"); - expect(llms).not.toMatch(/\/guides\/setup\/|\/articles\/harbour\/|\/articles\/plain\//); - // The rest is there. - expect(llms).toContain("## Guides\n\n- [Guides](https://bench.example.test/guides/): Longer texts about the bench.\n\n"); - expect(llms).toContain("## Articles\n\n- [Articles](https://bench.example.test/articles/): Everything written for the bench, newest first.\n"); - expect(llms).toContain("- [About](https://bench.example.test/about/)"); - }, 60_000); - - it("writes no llms.txt with storefront.llms: false, or for a site with index: false", async () => { - const root = await benchCopy(); - await build(root, join(root, "..", "wb-llms-off"), config({ llms: false })); - expect(await exists(join(root, ".out", "storefront", "llms.txt"))).toBe(false); - await build(root, join(root, "..", "wb-llms-staging"), config({ index: false })); - expect(await exists(join(root, ".out", "storefront", "llms.txt"))).toBe(false); - }, 60_000); - - it("without storefront.url: llms.txt links each page by its path from the site's root", async () => { - const root = await benchCopy(); - const { url: _u, ...rest } = benchConfig.storefront!; - await buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, { outDir: join(root, "..", "wb-llms-nourl"), pdVersion: "x", now: NOW }); - const llms = await readFile(join(root, ".out", "storefront", "llms.txt"), "utf8"); - expect(llms).toContain("- [About](/about/): What the bench is for.\n"); - expect(llms).not.toContain("https://"); - }, 60_000); - - it("keeps the storefront's output apart from the workbench's and from what PD reads", async () => { - const root = await benchCopy(); - await expect(build(root, join(root, ".out", "storefront"))).rejects.toThrow(/and --out .* overlap: the storefront and the workbench each need a folder of their own/); - await expect(build(root, join(root, "..", "wb-x"), config({ outDir: "./src/styles/out" }))).rejects.toThrow(/storefront\.outDir .* overlaps .*styles, which Pattern Dump reads/); - // An output root that contains the project is already refused by the config (it holds the pages and the - // patterns); the build refuses it too, for a config that never went through validation. - expect(() => config({ outDir: "." })).toThrow(/"storefront\.pagesDir" \("\.\/pages"\) is inside "storefront\.outDir" \("\."\)/); - const unvalidated = defineConfig({ ...benchConfig, storefront: { ...benchConfig.storefront!, outDir: "." } }); - await expect(build(root, join(root, "..", "wb-y"), unvalidated)).rejects.toThrow(/storefront\.outDir .* would contain the project itself/); - }); -}); diff --git a/packages/dev-server/test/storefront-llms.spec.ts b/packages/dev-server/test/storefront-llms.spec.ts new file mode 100644 index 0000000..a4eb178 --- /dev/null +++ b/packages/dev-server/test/storefront-llms.spec.ts @@ -0,0 +1,74 @@ +// pd build writes llms.txt for an indexed storefront (the llmstxt.org format): what it leaves out, how to +// turn it off, and its links without storefront.url. The full text is pinned in storefront-build.spec.ts. +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { execFileSync } from "node:child_process"; +import { cp, mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { validateConfig, type PatternDumpConfig } from "@pattern-dump/config"; +import { buildStaticSite } from "@pattern-dump/dev-server"; +import benchConfig from "../../../storefront-bench/pattern-dump.config.js"; +import { save } from "../../../test-support/save.js"; + +const repo = fileURLToPath(new URL("../../../", import.meta.url)); +// A fixed clock, after every date the bench's pages carry: the build's day decides which pages are scheduled. +const NOW = new Date("2027-01-02T03:04:05.000Z"); +let tmp = ""; + +beforeAll(async () => { tmp = await mkdtemp(join(tmpdir(), "pd-sf-llms-")); }); +afterAll(async () => { if (tmp) await rm(tmp, { recursive: true, force: true }); }); + +let n = 0; +async function benchCopy(): Promise<string> { + const root = join(tmp, `bench-${n++}`); + for (const file of execFileSync("git", ["ls-files", "storefront-bench"], { cwd: repo, encoding: "utf8" }).split("\n").filter(Boolean)) { + const to = join(root, file.slice("storefront-bench/".length)); + await mkdir(dirname(to), { recursive: true }); + await cp(join(repo, file), to); + } + return root; +} +const config = (over: Partial<NonNullable<PatternDumpConfig["storefront"]>> = {}): PatternDumpConfig => + validateConfig({ ...benchConfig, storefront: { ...benchConfig.storefront!, ...over } }, "test"); +const build = (root: string, out: string, cfg: PatternDumpConfig = config()) => + buildStaticSite(cfg, root, { outDir: out, pdVersion: "0.0.0-test", now: NOW }); +const exists = (p: string) => stat(p).then(() => true, () => false); + +describe("pd build — llms.txt", () => { + it("leaves drafts, scheduled pages and pages with index: false out of llms.txt", async () => { + const root = await benchCopy(); + const edit = async (path: string, from: string, to: string) => { + const file = join(root, "pages", path); + await save(file, (await readFile(file, "utf8")).replace(from, to)); + }; + await edit("guides/setup.md", "title: Setup\n", "title: Setup\nindex: false\n"); + await edit("articles/harbour.md", "date: 2026-11-01\n", "date: 2026-11-01\ndraft: true\n"); + // After the build's day (NOW): scheduled, so left out. + await edit("articles/plain.md", "date: 2026-10-02", "date: 2027-03-01"); + await build(root, join(root, "..", "wb-llms-out")); + const llms = await readFile(join(root, ".out", "storefront", "llms.txt"), "utf8"); + expect(llms).not.toMatch(/\/guides\/setup\/|\/articles\/harbour\/|\/articles\/plain\//); + // The rest is there. + expect(llms).toContain("## Guides\n\n- [Guides](https://bench.example.test/guides/): Longer texts about the bench.\n\n"); + expect(llms).toContain("## Articles\n\n- [Articles](https://bench.example.test/articles/): Everything written for the bench, newest first.\n"); + expect(llms).toContain("- [About](https://bench.example.test/about/)"); + }, 60_000); + + it("writes no llms.txt with storefront.llms: false, or for a site with index: false", async () => { + const root = await benchCopy(); + await build(root, join(root, "..", "wb-llms-off"), config({ llms: false })); + expect(await exists(join(root, ".out", "storefront", "llms.txt"))).toBe(false); + await build(root, join(root, "..", "wb-llms-staging"), config({ index: false })); + expect(await exists(join(root, ".out", "storefront", "llms.txt"))).toBe(false); + }, 60_000); + + it("without storefront.url: llms.txt links each page by its path from the site's root", async () => { + const root = await benchCopy(); + const { url: _u, ...rest } = benchConfig.storefront!; + await buildStaticSite(validateConfig({ ...benchConfig, storefront: rest }, "test"), root, { outDir: join(root, "..", "wb-llms-nourl"), pdVersion: "x", now: NOW }); + const llms = await readFile(join(root, ".out", "storefront", "llms.txt"), "utf8"); + expect(llms).toContain("- [About](/about/): What the bench is for.\n"); + expect(llms).not.toContain("https://"); + }, 60_000); +}); From 1881313dabb7451616a2cfc1c9d07ac3007b55f7 Mon Sep 17 00:00:00 2001 From: Stefan Bauer <stefan.bauer@n8d.at> Date: Mon, 16 Nov 2026 12:16:54 +0100 Subject: [PATCH 7/7] ci: refresh the burn-in times from the loaded runs of 2026-11-16 Measured from the six burn-in jobs of run 43846557396. The four storefront build spec files split from storefront-build.spec.ts share its measured time by the sums of their tests in that run, until a later refresh measures them. --- scripts/ci/burn-in-times.json | 54 ++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/scripts/ci/burn-in-times.json b/scripts/ci/burn-in-times.json index a884de1..f36eac7 100644 --- a/scripts/ci/burn-in-times.json +++ b/scripts/ci/burn-in-times.json @@ -1,44 +1,52 @@ { "apps/dev-ui/e2e/schema-helper-name.spec.ts": 1.9, + "packages/config/src/validate.spec.ts": 0.1, "packages/dev-server/test/config-change.unit.spec.ts": 0.8, + "packages/dev-server/test/css-vocabulary.spec.ts": 1.3, "packages/dev-server/test/declared-values-placed.spec.ts": 0.8, "packages/dev-server/test/docs.spec.ts": 3.7, "packages/dev-server/test/git-dates.spec.ts": 1.2, "packages/dev-server/test/raw-writes-guard.spec.ts": 0.9, - "packages/dev-server/test/reload.spec.ts": 8.8, + "packages/dev-server/test/reload.spec.ts": 6.7, "packages/dev-server/test/settle-hook.spec.ts": 3.7, "packages/dev-server/test/slug.spec.ts": 0.8, "packages/dev-server/test/storefront-anchors.spec.ts": 1.3, - "packages/dev-server/test/storefront-bench.spec.ts": 3.7, - "packages/dev-server/test/storefront-build.spec.ts": 13.1, + "packages/dev-server/test/storefront-base-path-build.spec.ts": 58.3, + "packages/dev-server/test/storefront-bench.spec.ts": 10.6, + "packages/dev-server/test/storefront-build-same-host.spec.ts": 51.8, + "packages/dev-server/test/storefront-build-settings.spec.ts": 44.6, + "packages/dev-server/test/storefront-build.spec.ts": 56, "packages/dev-server/test/storefront-derived.spec.ts": 1.2, "packages/dev-server/test/storefront-frontmatter.spec.ts": 0.9, + "packages/dev-server/test/storefront-llms.spec.ts": 40.1, "packages/dev-server/test/storefront-navigations.spec.ts": 0.8, "packages/dev-server/test/storefront-page.spec.ts": 1.4, "packages/dev-server/test/storefront-pages.spec.ts": 0.9, "packages/dev-server/test/storefront-position.spec.ts": 0.8, "packages/dev-server/test/storefront-sample-data.spec.ts": 0.9, "packages/dev-server/test/storefront-site.spec.ts": 0.9, + "packages/dev-server/test/storefront-style-checks.spec.ts": 68.3, "packages/dev-server/test/storefront-watch-config.spec.ts": 2.8, "packages/dev-server/test/storefront-watch-nav.spec.ts": 2.5, - "packages/dev-server/test/watcher-barrier.spec.ts": 3.2, - "packages/dev-server/test/watcher-change-batch.spec.ts": 3.9, - "packages/dev-server/test/watcher-characterization.spec.ts": 19.7, - "packages/dev-server/test/watcher-chokidar.spec.ts": 2.3, - "packages/dev-server/test/watcher-close-drain.spec.ts": 6.3, - "packages/dev-server/test/watcher-component-json.spec.ts": 5.5, - "packages/dev-server/test/watcher-duplicate-change.spec.ts": 4.3, - "packages/dev-server/test/watcher-handler-failure.spec.ts": 3.8, - "packages/dev-server/test/watcher-new-component.spec.ts": 3.6, - "packages/dev-server/test/watcher-new-folder.spec.ts": 11.2, - "packages/dev-server/test/watcher-ordered-hrefs.spec.ts": 3.6, - "packages/dev-server/test/watcher-placed.spec.ts": 4.2, - "packages/dev-server/test/watcher-queue.spec.ts": 2.9, - "packages/dev-server/test/watcher-quick-save.spec.ts": 3.3, - "packages/dev-server/test/watcher-reaudit-order.spec.ts": 3.7, - "packages/dev-server/test/watcher-restyle.spec.ts": 3.8, - "packages/dev-server/test/watcher-step-settle.spec.ts": 3.9, - "packages/dev-server/test/watcher.spec.ts": 5.2, + "packages/dev-server/test/watcher-barrier.spec.ts": 3.9, + "packages/dev-server/test/watcher-base-orphans.spec.ts": 4.2, + "packages/dev-server/test/watcher-change-batch.spec.ts": 3.2, + "packages/dev-server/test/watcher-characterization.spec.ts": 13.3, + "packages/dev-server/test/watcher-chokidar.spec.ts": 2, + "packages/dev-server/test/watcher-close-drain.spec.ts": 6.9, + "packages/dev-server/test/watcher-component-json.spec.ts": 6.7, + "packages/dev-server/test/watcher-duplicate-change.spec.ts": 3.2, + "packages/dev-server/test/watcher-handler-failure.spec.ts": 2.9, + "packages/dev-server/test/watcher-new-component.spec.ts": 4.2, + "packages/dev-server/test/watcher-new-folder.spec.ts": 10, + "packages/dev-server/test/watcher-ordered-hrefs.spec.ts": 2.4, + "packages/dev-server/test/watcher-placed.spec.ts": 3.2, + "packages/dev-server/test/watcher-queue.spec.ts": 2.2, + "packages/dev-server/test/watcher-quick-save.spec.ts": 2.5, + "packages/dev-server/test/watcher-reaudit-order.spec.ts": 2.8, + "packages/dev-server/test/watcher-restyle.spec.ts": 2.9, + "packages/dev-server/test/watcher-step-settle.spec.ts": 4.4, + "packages/dev-server/test/watcher.spec.ts": 4.2, "packages/renderer/test/schema-helper-names.spec.ts": 0.8, "storefront-bench/e2e/add-page.spec.ts": 1.8, "storefront-bench/e2e/config-reload.spec.ts": 2, @@ -46,7 +54,7 @@ "storefront-bench/e2e/derived-page.spec.ts": 0.9, "storefront-bench/e2e/dom-parity.spec.ts": 3.1, "storefront-bench/e2e/headings.spec.ts": 2.9, - "storefront-bench/e2e/hmr.spec.ts": 2, + "storefront-bench/e2e/hmr.spec.ts": 2.3, "storefront-bench/e2e/js-off.spec.ts": 3.1, "storefront-bench/e2e/live-handshake.spec.ts": 8.9, "storefront-bench/e2e/navigations.spec.ts": 2.8, @@ -56,5 +64,5 @@ "storefront-bench/e2e/position.spec.ts": 3.5, "storefront-bench/e2e/static.spec.ts": 0.1, "storefront-bench/e2e/workbench-links.spec.ts": 2.7, - "storefront-bench/e2e/workbench.spec.ts": 8.3 + "storefront-bench/e2e/workbench.spec.ts": 9.5 }