diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fde2ae..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 @@ -37,6 +40,16 @@ ### 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. +- **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. - **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/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/docs/guide/configuration.md b/docs/guide/configuration.md index cf1b6bf..d2cdaf6 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -189,6 +189,10 @@ 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.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 380a3d5..a7fd757 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 @@ -1183,6 +1193,49 @@ 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 `

`, + file: { path: "about.md", text: "---\ntitle: About\n---\n\n\n" }, + }, { route: "/tags/x/", html: `

` }], + stylesheets: [".styled { color: red }"], + templates: [`

`], + }); + 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-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(``); }); + 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-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-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 { + 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> = {}): 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 { + 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> = {}): 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> { + const out = new Map(); + const walk = async (d: string): Promise => { + 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("https://bench.example.test/guides/"); + expect(await readFile(join(out, "guides", "setup", "index.html"), "utf8")).toContain(``); + }, 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 2f07122..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"; @@ -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"); @@ -282,13 +316,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"))); } @@ -349,159 +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("https://bench.example.test/guides/"); - expect(await readFile(join(out, "guides", "setup", "index.html"), "utf8")).toContain(``); - }, 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("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 { + 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> = {}): 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); +}); 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..c381cdf --- /dev/null +++ b/packages/dev-server/test/storefront-style-checks.spec.ts @@ -0,0 +1,123 @@ +// 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"; +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 { + 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): 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 { + const dir = join(root, "src", "patterns", "components", "badge"); + await mkdir(dir, { recursive: true }); + await save(join(dir, "badge.hbs"), `{{label}}\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\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); +}); + +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); +}); 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 } 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, []); + }); +} 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 }); 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]");