From 77fa9e5c917f6723ade442910e880e54080bccbd Mon Sep 17 00:00:00 2001 From: Madraka <8898640+Madraka@users.noreply.github.com> Date: Sun, 25 Oct 2026 18:22:14 +0300 Subject: [PATCH 1/2] fix(mcp-server): render checks receive their regex escapes The in-page check parts were plain template literals, so a backslash in the page's code never reached the page: content.ts's long-line loop got /s/ for /\s/ (the letter s counted as blank, every real space as text), and input-label split aria-labelledby on /s+/ and called labelled inputs unlabelled. Biome's noUselessEscapeInString safe fix had deleted one of them. Every part is now a String.raw template; the rule is an error with its fix off; tests assert the guard, the evaluated whitespace regex, and the checks' behaviour in happy-dom and real Chrome (red on the old code). Co-Authored-By: Claude Opus 5.5 Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com> --- .changeset/render-check-escapes.md | 5 + biome.json | 6 + packages/cli/test/render-chrome-text.test.ts | 2 +- .../src/render/checks/components.ts | 2 +- .../mcp-server/src/render/checks/content.ts | 4 +- .../mcp-server/src/render/checks/contrast.ts | 2 +- .../mcp-server/src/render/checks/fonts.ts | 2 +- .../mcp-server/src/render/checks/index.ts | 4 + .../mcp-server/src/render/checks/layout.ts | 2 +- .../mcp-server/src/render/checks/motion.ts | 2 +- .../src/render/checks/navigation.ts | 2 +- .../mcp-server/src/render/checks/prelude.ts | 6 +- .../mcp-server/src/render/checks/scripts.ts | 4 +- .../mcp-server/test/render-content.test.ts | 129 ++++++++++++++++++ .../mcp-server/test/render-script.test.ts | 27 ++++ 15 files changed, 185 insertions(+), 14 deletions(-) create mode 100644 .changeset/render-check-escapes.md create mode 100644 packages/mcp-server/test/render-content.test.ts diff --git a/.changeset/render-check-escapes.md b/.changeset/render-check-escapes.md new file mode 100644 index 00000000..ba44e2a3 --- /dev/null +++ b/.changeset/render-check-escapes.md @@ -0,0 +1,5 @@ +--- +"@cloudhal/mcp-server": patch +--- + +render_page's long-line and input-label checks handle whitespace correctly again. A plain template literal ate the backslash, so the in-page script received `/s/` and `/s+/` instead of `/\s/` and `/\s+/`. As a result, long-line counted the letter "s" as blank and every real space and indentation run as text. input-label split `aria-labelledby` on the letter "s" and reported labelled inputs as unlabelled. The check parts are now `String.raw` templates. diff --git a/biome.json b/biome.json index 0797b2ce..5ca2c72e 100644 --- a/biome.json +++ b/biome.json @@ -74,6 +74,12 @@ "max": 4 } } + }, + "suspicious": { + "noUselessEscapeInString": { + "level": "error", + "fix": "none" + } } } }, diff --git a/packages/cli/test/render-chrome-text.test.ts b/packages/cli/test/render-chrome-text.test.ts index 3f02a1ba..b4cee368 100644 --- a/packages/cli/test/render-chrome-text.test.ts +++ b/packages/cli/test/render-chrome-text.test.ts @@ -51,7 +51,7 @@ ${linkRule}

Post

R dir ??= await mkdtemp(path.join(os.tmpdir(), "cloudhal-render-test-")); // A monospace font: every character is as wide as the next, so a column's measure is exact. const para = (chars: number) => - `

${"abcd " + `

${"miss " .repeat(Math.ceil(chars / 5)) .slice(0, chars) .trim()}

`; diff --git a/packages/mcp-server/src/render/checks/components.ts b/packages/mcp-server/src/render/checks/components.ts index 6f4496e3..15a58f66 100644 --- a/packages/mcp-server/src/render/checks/components.ts +++ b/packages/mcp-server/src/render/checks/components.ts @@ -2,7 +2,7 @@ * In-page checks, part of `RENDER_CHECK_SCRIPT`: carousel-label / -lcp / -focus / -autoplay, image-fit, overlay-open; ends at the top of the page. * Plain source text, run inside the page; it shares the script's locals (see ./index.ts). */ -export const COMPONENT_CHECKS = ` // A static preview runs no scripts (its CSP), so checks of what a module does wait for the site. +export const COMPONENT_CHECKS = String.raw` // A static preview runs no scripts (its CSP), so checks of what a module does wait for the site. const staticPreview = !!document.querySelector('meta[name="generator"][content="Cloudhal preview"]'); // carousel-label and carousel-lcp: named carousels and slides; a hero's first slide not lazy. for (const c of document.querySelectorAll('[aria-roledescription="carousel"], [aria-roledescription="kaydırmalı alan"]')) { diff --git a/packages/mcp-server/src/render/checks/content.ts b/packages/mcp-server/src/render/checks/content.ts index f7b258ee..64f712c3 100644 --- a/packages/mcp-server/src/render/checks/content.ts +++ b/packages/mcp-server/src/render/checks/content.ts @@ -2,7 +2,7 @@ * In-page checks, part of `RENDER_CHECK_SCRIPT`: empty-section, tap-target, input-label, chart-empty, long-line. * Plain source text, run inside the page; it shares the script's locals (see ./index.ts). */ -export const CONTENT_CHECKS = ` // empty-section +export const CONTENT_CHECKS = String.raw` // empty-section for (const s of document.querySelectorAll("[data-section-id]")) { if (getComputedStyle(s).display === "none") continue; const text = (s.innerText || "").trim(); @@ -41,7 +41,7 @@ export const CONTENT_CHECKS = ` // empty-section if (!visible(el) && !(el.type === "radio" || el.type === "checkbox")) continue; const named = [...(el.labels || [])].some((l) => (l.innerText || l.textContent || "").trim()) || (el.getAttribute("aria-label") || "").trim() || - (el.getAttribute("aria-labelledby") || "").split(/s+/).some((id) => id && (document.getElementById(id)?.textContent || "").trim()); + (el.getAttribute("aria-labelledby") || "").split(/\s+/).some((id) => id && (document.getElementById(id)?.textContent || "").trim()); if (!named) add("input-label", el, "no label a screen reader can announce"); } diff --git a/packages/mcp-server/src/render/checks/contrast.ts b/packages/mcp-server/src/render/checks/contrast.ts index cd5aa87b..56f68f2e 100644 --- a/packages/mcp-server/src/render/checks/contrast.ts +++ b/packages/mcp-server/src/render/checks/contrast.ts @@ -2,7 +2,7 @@ * In-page checks, part of `RENDER_CHECK_SCRIPT`: contrast: text against what is painted beneath it, band by band. * Plain source text, run inside the page; it shares the script's locals (see ./index.ts). */ -export const CONTRAST_CHECKS = ` // contrast: text against what is painted beneath it (elementsFromPoint), band by band. +export const CONTRAST_CHECKS = String.raw` // contrast: text against what is painted beneath it (elementsFromPoint), band by band. const canvas = document.createElement("canvas"); canvas.width = canvas.height = 1; const g = canvas.getContext("2d", { willReadFrequently: true }); diff --git a/packages/mcp-server/src/render/checks/fonts.ts b/packages/mcp-server/src/render/checks/fonts.ts index 0bc620cc..c9221b72 100644 --- a/packages/mcp-server/src/render/checks/fonts.ts +++ b/packages/mcp-server/src/render/checks/fonts.ts @@ -2,7 +2,7 @@ * In-page checks, part of `RENDER_CHECK_SCRIPT`: font-fallback. * Plain source text, run inside the page; it shares the script's locals (see ./index.ts). */ -export const FONT_CHECKS = ` // font-fallback (RFC-0023 §2): text set in a web font whose stack has no metric-matched fallback +export const FONT_CHECKS = String.raw` // font-fallback (RFC-0023 §2): text set in a web font whose stack has no metric-matched fallback // right after it (a face with size-adjust or ascent-override). Without one, the text is first // drawn in a system font of another size and moves when the web font arrives. if (document.fonts) { diff --git a/packages/mcp-server/src/render/checks/index.ts b/packages/mcp-server/src/render/checks/index.ts index d44cbc61..f19722ee 100644 --- a/packages/mcp-server/src/render/checks/index.ts +++ b/packages/mcp-server/src/render/checks/index.ts @@ -6,6 +6,10 @@ * prelude defines the helpers (`add`, `describe`, `visible`, `imgs`, `W`, `H`); the motion part * scrolls the page once and defines `frame`, which the navigation and component parts use; the * component part ends back at the top. Keep the order. + * + * Every part is a `String.raw` template, so a backslash in the page's code (`/\s/`) reaches the + * page as written: in a plain template `\s` arrives as `s` and `\b` as a control character, and + * Biome's useless-escape fix deleted the backslash (test/render-script.test.ts checks this). */ import { COMPONENT_CHECKS } from "./components.ts"; import { CONTENT_CHECKS } from "./content.ts"; diff --git a/packages/mcp-server/src/render/checks/layout.ts b/packages/mcp-server/src/render/checks/layout.ts index b95da1b6..2069c972 100644 --- a/packages/mcp-server/src/render/checks/layout.ts +++ b/packages/mcp-server/src/render/checks/layout.ts @@ -2,7 +2,7 @@ * In-page checks, part of `RENDER_CHECK_SCRIPT`: overflow-x, img-alt / img-broken, heading-order. * Plain source text, run inside the page; it shares the script's locals (see ./index.ts). */ -export const LAYOUT_CHECKS = ` // overflow-x: the outermost elements that stick out past the screen's right edge. +export const LAYOUT_CHECKS = String.raw` // overflow-x: the outermost elements that stick out past the screen's right edge. const sw = document.documentElement.scrollWidth; if (sw > W + 1) { const clipped = (el) => { diff --git a/packages/mcp-server/src/render/checks/motion.ts b/packages/mcp-server/src/render/checks/motion.ts index 90b82a11..429e2de8 100644 --- a/packages/mcp-server/src/render/checks/motion.ts +++ b/packages/mcp-server/src/render/checks/motion.ts @@ -2,7 +2,7 @@ * In-page checks, part of `RENDER_CHECK_SCRIPT`: The reader's scroll pass, then motion-cls, reduced-motion, motion-budget, flash; defines `frame`. * Plain source text, run inside the page; it shares the script's locals (see ./index.ts). */ -export const MOTION_CHECKS = ` // RFC-0024 §8: scroll through the page once, as a reader would, so reveals play, then measure. +export const MOTION_CHECKS = String.raw` // RFC-0024 §8: scroll through the page once, as a reader would, so reveals play, then measure. let shift = 0; let po; try { diff --git a/packages/mcp-server/src/render/checks/navigation.ts b/packages/mcp-server/src/render/checks/navigation.ts index c8723991..8f44cf24 100644 --- a/packages/mcp-server/src/render/checks/navigation.ts +++ b/packages/mcp-server/src/render/checks/navigation.ts @@ -2,7 +2,7 @@ * In-page checks, part of `RENDER_CHECK_SCRIPT`: skip-link, landmarks, header-contrast, focus-obscured. * Plain source text, run inside the page; it shares the script's locals (see ./index.ts). */ -export const NAVIGATION_CHECKS = ` // skip-link: the first focusable element is a link to the main content (or inside it). +export const NAVIGATION_CHECKS = String.raw` // skip-link: the first focusable element is a link to the main content (or inside it). const shown = (e) => e.getClientRects().length > 0 && getComputedStyle(e).visibility !== "hidden"; const focusables = [...document.querySelectorAll('a[href],button,input,select,textarea,summary,[tabindex]:not([tabindex="-1"])')] .filter((e) => !e.disabled && !e.closest("[inert],dialog:not([open]),[popover]:not(:popover-open)") && shown(e)); diff --git a/packages/mcp-server/src/render/checks/prelude.ts b/packages/mcp-server/src/render/checks/prelude.ts index f62c3585..d01a3876 100644 --- a/packages/mcp-server/src/render/checks/prelude.ts +++ b/packages/mcp-server/src/render/checks/prelude.ts @@ -4,7 +4,7 @@ */ import { RENDER_CHECK_IDS } from "../types.ts"; -export const PRELUDE = ` const W = document.documentElement.clientWidth || window.innerWidth, H = window.innerHeight, MAX = 5; +export const PRELUDE = String.raw` const W = document.documentElement.clientWidth || window.innerWidth, H = window.innerHeight, MAX = 5; const ids = ${JSON.stringify(RENDER_CHECK_IDS)}; const out = Object.fromEntries(ids.map((id) => [id, { id, count: 0, examples: [] }])); const clip = (s, n) => (s.length > n ? s.slice(0, n - 1) + "…" : s); @@ -22,9 +22,9 @@ export const PRELUDE = ` const W = document.documentElement.clientWidth || wind let tag = el.tagName.toLowerCase(); if (el.id) tag += "#" + el.id; else if (typeof el.className === "string" && el.className.trim()) - tag += "." + el.className.trim().split(/\\s+/).slice(0, 2).join("."); + tag += "." + el.className.trim().split(/\s+/).slice(0, 2).join("."); parts.push(tag); - const text = ((el.innerText || "").trim() || el.getAttribute("alt") || el.getAttribute("src") || "").replace(/\\s+/g, " "); + const text = ((el.innerText || "").trim() || el.getAttribute("alt") || el.getAttribute("src") || "").replace(/\s+/g, " "); if (text) parts.push(JSON.stringify(clip(text, 48))); return parts.join(" "); }; diff --git a/packages/mcp-server/src/render/checks/scripts.ts b/packages/mcp-server/src/render/checks/scripts.ts index 5f1df660..b50574d2 100644 --- a/packages/mcp-server/src/render/checks/scripts.ts +++ b/packages/mcp-server/src/render/checks/scripts.ts @@ -8,7 +8,7 @@ * keeps the Content-Security-Policy violations the page raises while it loads, which the * `script-blocked` check reads. Report-only ones (`cloudhal dev`) are kept too. */ -export const CSP_LISTENER = `(() => { +export const CSP_LISTENER = String.raw`(() => { const seen = (window.__chCsp = []); window.addEventListener("securitypolicyviolation", (e) => { if (seen.length < 50) @@ -16,7 +16,7 @@ export const CSP_LISTENER = `(() => { }, true); })();`; -export const SCRIPT_CHECKS = ` // surface-broken: a body surface the preview could not draw (RFC-0020 §5), or a component in one +export const SCRIPT_CHECKS = String.raw` // surface-broken: a body surface the preview could not draw (RFC-0020 §5), or a component in one // with an unknown block type or props that do not fit it. Theme blocks the preview leaves to the // site are fine. for (const el of document.querySelectorAll(".ch-surface-problem")) { diff --git a/packages/mcp-server/test/render-content.test.ts b/packages/mcp-server/test/render-content.test.ts new file mode 100644 index 00000000..38d02443 --- /dev/null +++ b/packages/mcp-server/test/render-content.test.ts @@ -0,0 +1,129 @@ +// @vitest-environment happy-dom +/** + * render_page's content checks (src/render/checks/content.ts) on their own: the prelude's helpers + * are stubbed and a fake monospace layout stands in for Chrome's, in which a collapsed blank is + * drawn on the line of the character before it. They must see whitespace as whitespace: + * `long-line` counts a run of blanks once and the letter "s" as text, `input-label` splits + * `aria-labelledby` on blanks. + */ +import { afterEach, describe, expect, it } from "vitest"; +import { CONTENT_CHECKS } from "../src/render/checks/content.ts"; + +interface TextNode { + data: string; +} +/** The happy-dom globals this test uses (the package's types have no DOM lib). */ +interface Doc { + body: { innerHTML: string }; + querySelectorAll(selector: string): Iterable; + createTreeWalker(root: unknown, what: number): { nextNode(): unknown; currentNode: TextNode }; +} +const dom = globalThis as unknown as { document: Doc }; + +const LINE = 24; +const SHOW_TEXT = 4; + +/** Lays every paragraph out `cols` characters a line, a run of blanks drawn as one. */ +function layout(cols: number): Map { + const at = new Map(); + for (const p of dom.document.querySelectorAll("p")) { + const tw = dom.document.createTreeWalker(p, SHOW_TEXT); + let drawn = 0; + let blankBefore = true; + while (tw.nextNode()) { + const node = tw.currentNode; + const lines: number[] = []; + for (const c of node.data) { + const blank = /\s/.test(c); + if (!(blank && blankBefore)) drawn++; + blankBefore = blank; + lines.push(Math.floor(Math.max(0, drawn - 1) / cols)); + } + at.set(node, lines); + } + } + return at; +} + +/** Runs the content checks on `html` laid out `cols` characters a line: `id: note` per finding. */ +async function run(html: string, cols: number): Promise { + dom.document.body.innerHTML = html; + const lines = layout(cols); + const createRange = () => { + let node: TextNode | undefined; + let offset = 0; + return { + setStart(n: TextNode, i: number) { + node = n; + offset = i; + }, + setEnd() {}, + getClientRects: () => [ + { top: ((node && lines.get(node)?.[offset]) ?? 0) * LINE, width: 8, height: LINE }, + ], + }; + }; + const document = new Proxy(dom.document, { + get(target, key) { + if (key === "createRange") return createRange; + const value: unknown = Reflect.get(target, key, target); + return typeof value === "function" ? value.bind(target) : value; + }, + }); + const style = () => ({ + display: "block", + lineHeight: `${LINE}px`, + fontSize: "16px", + fontFamily: "monospace", + }); + const found: string[] = []; + const add = (id: string, _el: unknown, note: string) => found.push(`${id}: ${note}`); + // Constructing a Function from the part's source (tests only; Workers forbid eval). + const checks = new Function( + "document", + "getComputedStyle", + "NodeFilter", + "W", + "add", + "visible", + "clip", + `return (async () => {${CONTENT_CHECKS}})();`, + ); + await checks( + document, + style, + { SHOW_TEXT }, + 1440, + add, + () => true, + (s: string) => s, + ); + return found; +} + +const words = (word: string, n: number) => Array.from({ length: n }, () => word).join(" "); +const only = (found: string[], id: string) => found.filter((f) => f.startsWith(`${id}: `)); + +afterEach(() => { + dom.document.body.innerHTML = ""; +}); + +describe("content checks see whitespace as whitespace", () => { + it("long-line counts an unminified template's line breaks and indentation once", async () => { + // 85 drawn characters a line; the source breaks and indents every 11 words. + const text = words("abcd", 120).replace(/((?:abcd ){11})/g, "$1\n "); + const found = await run(`

\n ${text}\n

`, 85); + expect(only(found, "long-line")).toEqual([]); + }); + + it("long-line counts the letter s as text", async () => { + const found = only(await run(`

${words("less", 120)}

`, 95), "long-line"); + expect(found).toHaveLength(1); + expect(found[0]).toMatch(/^long-line: about 95 characters a line/); + }); + + it("input-label reads every id aria-labelledby names", async () => { + const html = `

First name

As on your passport

`; + expect(only(await run(html, 85), "input-label")).toEqual([]); + }); +}); diff --git a/packages/mcp-server/test/render-script.test.ts b/packages/mcp-server/test/render-script.test.ts index 1c699809..91eb765c 100644 --- a/packages/mcp-server/test/render-script.test.ts +++ b/packages/mcp-server/test/render-script.test.ts @@ -1,6 +1,10 @@ +import { readdirSync, readFileSync } from "node:fs"; +import path from "node:path"; import { describe, expect, it } from "vitest"; import { RENDER_CHECK_IDS, RENDER_CHECK_SCRIPT } from "../src/render.ts"; +const CHECKS_DIR = path.join(import.meta.dirname, "../src/render/checks"); + /** `RENDER_CHECK_SCRIPT` is assembled from ordered parts (src/render/checks); they must still form one script. */ describe("RENDER_CHECK_SCRIPT", () => { it("parses as one async expression and names every check id", () => { @@ -10,4 +14,27 @@ describe("RENDER_CHECK_SCRIPT", () => { expect(RENDER_CHECK_SCRIPT.endsWith("\n return ids.map((id) => out[id]);\n})()")).toBe(true); expect(RENDER_CHECK_SCRIPT).toContain(JSON.stringify(RENDER_CHECK_IDS)); }); + + it("every part is a String.raw template, so backslashes reach the page as written", () => { + const parts: string[] = []; + for (const file of readdirSync(CHECKS_DIR)) { + if (!file.endsWith(".ts") || file === "index.ts") continue; + const source = readFileSync(path.join(CHECKS_DIR, file), "utf8"); + for (const [, name, start] of source.matchAll(/export const (\w+) = (\S+)/g)) { + expect(start, `${file}: ${name}`).toMatch(/^String\.raw`/); + parts.push(`${file}: ${name}`); + } + } + expect(parts).toHaveLength(10); + }); + + it("the page receives its whitespace regexes with their backslashes", () => { + for (const code of [ + String.raw`const blank = /\s/.test(`, + String.raw`.split(/\s+/).some(`, + String.raw`.split(/\s+/).slice(0, 2)`, + String.raw`.replace(/\s+/g, " ")`, + ]) + expect(RENDER_CHECK_SCRIPT).toContain(code); + }); }); From 8a30e3029d4b0472d5dd657274be31c9a493713f Mon Sep 17 00:00:00 2001 From: Madraka <8898640+Madraka@users.noreply.github.com> Date: Sun, 25 Oct 2026 18:22:14 +0300 Subject: [PATCH 2/2] fix(build): ship the ./testing subpath the packages export storage, analytics, comments and schedules export ./testing (documented in their READMEs, the released storage changelog and RFC-0004/0006/0007/0008), but build-packages skipped every testing.ts, so the published import failed with ERR_MODULE_NOT_FOUND. A testing.ts now ships where exports name it; other packages' testing.ts and all *.test.* files stay out. vitest (>=3) and, for storage, miniflare (*) are optional peers, wide on purpose: npm stops with ERESOLVE on a mismatched optional peer of a direct dependency, and no range matches wrangler's prerelease miniflare. build-packages now verifies every published exports/bin target exists (scripts/verify-exports.ts, also --verify), packaging tests cover the ship rule, and smoke-pack installs the four packages next to vitest 4 and miniflare 3. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com> --- .changeset/testing-subpath-ships.md | 8 ++++ .github/workflows/npm-smoke.yml | 1 + packages/analytics/README.md | 2 +- packages/analytics/package.json | 8 ++++ packages/cli/test/packaging.test.ts | 54 ++++++++++++++++++++- packages/comments/package.json | 8 ++++ packages/schedules/package.json | 8 ++++ packages/storage/README.md | 2 +- packages/storage/package.json | 10 +++- scripts/build-packages.ts | 37 +++++++++++++-- scripts/smoke-pack.ts | 45 ++++++++++++++++-- scripts/verify-exports.ts | 73 +++++++++++++++++++++++++++++ tsconfig.build.json | 8 ++++ 13 files changed, 254 insertions(+), 10 deletions(-) create mode 100644 .changeset/testing-subpath-ships.md create mode 100644 scripts/verify-exports.ts diff --git a/.changeset/testing-subpath-ships.md b/.changeset/testing-subpath-ships.md new file mode 100644 index 00000000..dfadd45f --- /dev/null +++ b/.changeset/testing-subpath-ships.md @@ -0,0 +1,8 @@ +--- +"@cloudhal/storage": patch +"@cloudhal/analytics": patch +"@cloudhal/comments": patch +"@cloudhal/schedules": patch +--- + +The `./testing` subpath now ships. The published packages pointed `./testing` at `dist/src/testing.js` and `.d.ts`, but the build left those files out, so importing `@cloudhal/{storage,analytics,comments,schedules}/testing` failed with ERR_MODULE_NOT_FOUND. The suites run on your own vitest, 3 or later, which is an optional peer dependency. `@cloudhal/storage`'s Miniflare helpers also load your own `miniflare`, an optional peer of any version. The ranges are wide on purpose. When a direct dependency's optional peer does not match the copy in your project, npm stops with ERESOLVE, even if nothing imports `./testing`. No semver range matches the prerelease miniflare that wrangler currently brings in, so with a narrower range npm would install a second miniflare beside it. diff --git a/.github/workflows/npm-smoke.yml b/.github/workflows/npm-smoke.yml index a0bb64bb..0cdb7431 100644 --- a/.github/workflows/npm-smoke.yml +++ b/.github/workflows/npm-smoke.yml @@ -9,6 +9,7 @@ on: pull_request: paths: - "scripts/build-packages.ts" + - "scripts/verify-exports.ts" - "scripts/smoke-pack.ts" - "packages/*/package.json" - "packages/cli/src/assets.ts" diff --git a/packages/analytics/README.md b/packages/analytics/README.md index d11fad7d..61c2505e 100644 --- a/packages/analytics/README.md +++ b/packages/analytics/README.md @@ -12,7 +12,7 @@ Everything here is **Worker-safe** (AGENTS.md rule 5): SQLite is reached only th | `@cloudhal/analytics/rollup` | `runRollups`, `RollupReader`, `collectDailyRows`, `writeDailyRows` | | `@cloudhal/analytics/reader` | `CompositeReader` (rollups for complete days, the rest live), `mergeResults` | | `@cloudhal/analytics/service` | `AnalyticsService` (one per deployment: composite reads, settings with the salt and purge rules, rollups, status, CSV export of rollups), `presetRange`, `rangeFromParams`, `parseFilterParam`, `ANALYTICS_OFF` | -| `@cloudhal/analytics/testing` | conformance, bot-traffic, state and rollup suites; `FIXTURE_EVENTS`, `CONFORMANCE_CASES` | +| `@cloudhal/analytics/testing` | conformance, bot-traffic, state and rollup suites; `FIXTURE_EVENTS`, `CONFORMANCE_CASES` (vitest 3 or later, an optional peer) | | `@cloudhal/analytics/client` | the browser sources (`pageview.browser.js`, `vitals.browser.js` with `web-vitals`) and their names; build input for the `cloudhal()` integration, which ships them as `/_cloudhal/p..js` (≤ `PAGEVIEW_GZIP_BUDGET`, 1 KB gzipped) and `/_cloudhal/v..js`. Node only (build time) | The site side (`POST /__cloudhal/e`, the script tag, render events) lives in `@cloudhal/astro-renderer` (`SiteAnalytics` in `./analytics`, used by the Site Worker entry and the `cloudhal dev` middleware). diff --git a/packages/analytics/package.json b/packages/analytics/package.json index 93ccc1a4..960001e6 100644 --- a/packages/analytics/package.json +++ b/packages/analytics/package.json @@ -37,6 +37,14 @@ "@cloudhal/storage": "workspace:*", "web-vitals": "catalog:" }, + "peerDependencies": { + "vitest": ">=3.0.0" + }, + "peerDependenciesMeta": { + "vitest": { + "optional": true + } + }, "devDependencies": { "@cloudflare/workers-types": "catalog:", "@types/better-sqlite3": "catalog:", diff --git a/packages/cli/test/packaging.test.ts b/packages/cli/test/packaging.test.ts index 4793cc0f..34e8c14b 100644 --- a/packages/cli/test/packaging.test.ts +++ b/packages/cli/test/packaging.test.ts @@ -1,14 +1,18 @@ /** What makes the published packages installable (ADR-0013). */ -import { readFile, realpath } from "node:fs/promises"; +import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises"; +import os from "node:os"; import path from "node:path"; import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; import { + exportedSources, PACKAGES, publishConfigFor, publishExports, rewriteSpecifiers, + shipsFile, } from "../../../scripts/build-packages.ts"; +import { verifyPublishTargets } from "../../../scripts/verify-exports.ts"; import { assetDir, materializeDependencies, @@ -75,6 +79,54 @@ describe("build: specifiers and exports", () => { expect(pkg.private, name).toBeUndefined(); } }); + + it("ships every source a package exports; tests and unexported testing.ts stay out", async () => { + for (const name of PACKAGES) { + const pkg = JSON.parse( + await readFile(path.join(ROOT, "packages", name, "package.json"), "utf8"), + ); + const exported = exportedSources(pkg); + for (const rel of exported) { + if (rel.includes("*") || !/\.tsx?$/.test(rel)) continue; + expect(shipsFile(name, rel, exported), `${name}/${rel}`).toBe(true); + } + } + expect(shipsFile("core-ts", "src/testing.ts", new Set())).toBe(false); + expect(shipsFile("storage", "src/a.test.ts", new Set(["src/a.test.ts"]))).toBe(false); + expect(shipsFile("core-ts", "scripts/gen-icons.ts", new Set(["scripts/gen-icons.ts"]))).toBe( + false, + ); + }); + + it("reports published exports/bin targets outside files or missing from dist", async () => { + const dir = await mkdtemp(path.join(os.tmpdir(), "cloudhal-exports-")); + try { + await mkdir(path.join(dir, "dist/src/c"), { recursive: true }); + for (const file of ["dist/src/index.js", "dist/src/index.d.ts", "dist/src/c/a.js"]) + await writeFile(path.join(dir, file), ""); + const pkg = { + name: "fixture", + files: ["dist"], + publishConfig: { + exports: { + ".": { types: "./dist/src/index.d.ts", default: "./dist/src/index.js" }, + "./testing": { types: "./dist/src/testing.d.ts", default: "./dist/src/testing.js" }, + "./c/*": "./dist/src/c/*", + "./schemas/*": "./schemas/*", + }, + bin: { y: "./dist/bin/y.js" }, + }, + }; + expect(await verifyPublishTargets(dir, pkg)).toEqual([ + "fixture: ./testing (types) → ./dist/src/testing.d.ts: missing", + "fixture: ./testing (default) → ./dist/src/testing.js: missing", + "fixture: ./schemas/* → ./schemas/*: outside files", + "fixture: bin (y) → ./dist/bin/y.js: missing", + ]); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); }); describe("starter dependencies outside the monorepo", () => { diff --git a/packages/comments/package.json b/packages/comments/package.json index ee04a087..6d9174c8 100644 --- a/packages/comments/package.json +++ b/packages/comments/package.json @@ -34,6 +34,14 @@ "@cloudhal/core-ts": "workspace:*", "@cloudhal/storage": "workspace:*" }, + "peerDependencies": { + "vitest": ">=3.0.0" + }, + "peerDependenciesMeta": { + "vitest": { + "optional": true + } + }, "devDependencies": { "@cloudflare/workers-types": "catalog:", "@types/better-sqlite3": "catalog:", diff --git a/packages/schedules/package.json b/packages/schedules/package.json index d43bea01..f4944054 100644 --- a/packages/schedules/package.json +++ b/packages/schedules/package.json @@ -35,6 +35,14 @@ "@cloudhal/storage": "workspace:*", "temporal-polyfill": "catalog:" }, + "peerDependencies": { + "vitest": ">=3.0.0" + }, + "peerDependenciesMeta": { + "vitest": { + "optional": true + } + }, "devDependencies": { "@cloudflare/workers-types": "catalog:", "@types/better-sqlite3": "catalog:", diff --git a/packages/storage/README.md b/packages/storage/README.md index 5e7ad531..a1fc1a33 100644 --- a/packages/storage/README.md +++ b/packages/storage/README.md @@ -10,7 +10,7 @@ Storage interfaces and adapters for Cloudhal. The interface is shaped by the mos | `@cloudhal/storage/do-sqlite` | `DoSqliteDriver` — a SQLite-backed Durable Object's `ctx.storage` (RFC-0036); `batch` runs in `transactionSync` | | `@cloudhal/storage/fs` | `FsBlobStore` — directory on disk | | `@cloudhal/storage/r2` | `R2BlobStore` — Cloudflare R2 binding | -| `@cloudhal/storage/testing` | conformance suites + Miniflare helpers (`createMiniflareD1`, `createMiniflareR2`, `createMiniflareDoSqlite`) | +| `@cloudhal/storage/testing` | conformance suites + Miniflare helpers (`createMiniflareD1`, `createMiniflareR2`, `createMiniflareDoSqlite`); needs vitest 3 or later, and miniflare for the helpers (optional peers) | ```ts import { migrate, migrations } from "@cloudhal/storage"; diff --git a/packages/storage/package.json b/packages/storage/package.json index bf554ebf..47954b75 100644 --- a/packages/storage/package.json +++ b/packages/storage/package.json @@ -36,11 +36,19 @@ "@cloudhal/core-contracts": "workspace:*" }, "peerDependencies": { - "better-sqlite3": "^13.0.0" + "better-sqlite3": "^13.0.0", + "miniflare": "*", + "vitest": ">=3.0.0" }, "peerDependenciesMeta": { "better-sqlite3": { "optional": true + }, + "miniflare": { + "optional": true + }, + "vitest": { + "optional": true } }, "devDependencies": { diff --git a/scripts/build-packages.ts b/scripts/build-packages.ts index 22fd2548..eda0347e 100644 --- a/scripts/build-packages.ts +++ b/scripts/build-packages.ts @@ -8,9 +8,13 @@ * each package keeps its own `.d.ts` files, specifiers rewritten the same way. * - Assets (`.astro`, `.json`, generated `.js`/`.d.ts`, `.css`) are copied, `.ts` specifiers in * `.astro`/`.js` rewritten too. + * - Tests never ship. A package's test-support entry (`src/testing.ts`, on vitest) ships only where + * its `exports` name it (`./testing`); its `testing-*.ts` siblings ship as they are. + * - After the build every published `exports`/`bin` target must exist (scripts/verify-exports.ts). * - * node scripts/build-packages.ts # build all + * node scripts/build-packages.ts # build all, then verify the targets * node scripts/build-packages.ts --check # verify publishConfig matches exports (CI) + * node scripts/build-packages.ts --verify # verify the targets of the current dist only * node scripts/build-packages.ts --write-publish-config */ import { execFileSync } from "node:child_process"; @@ -18,6 +22,7 @@ import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promi import { createRequire, stripTypeScriptTypes } from "node:module"; import path from "node:path"; import { fileURLToPath } from "node:url"; +import { publishTargets, verifyPackages } from "./verify-exports.ts"; const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); const require = createRequire(path.join(ROOT, "packages/core-ts/package.json")); @@ -41,11 +46,26 @@ export const PACKAGES = [ /** Directories inside a package that hold code or runtime assets (mirrored into dist/). */ const SOURCE_DIRS = ["src", "scripts", "bin", "migrations"]; -const SKIP_FILE = /(\.test\.tsx?|[\\/]testing\.ts)$/; +const TEST_FILE = /\.test\.tsx?$/; +/** A package's test-support entry; it ships only where its exports name it (./testing). */ +const TESTING_ENTRY = /(^|[\\/])testing\.ts$/; /** Development-only generators: they run in the monorepo (on dev dependencies) and never ship. */ const DEV_ONLY = new Set(["core-ts/scripts/gen-icons.ts"]); type Json = Record; + +/** The package-relative sources (no `./`) that a package's `exports` and `bin` name. */ +export function exportedSources(pkg: Json): Set { + const targets = [...publishTargets(pkg.exports, "."), ...publishTargets(pkg.bin, "bin")]; + return new Set(targets.map(([, target]) => target.replace(/^\.\//, ""))); +} + +/** Whether `rel` (relative to package `name`) goes into dist. */ +export function shipsFile(name: string, rel: string, exported: ReadonlySet): boolean { + if (TEST_FILE.test(rel) || DEV_ONLY.has(`${name}/${rel}`)) return false; + return !TESTING_ENTRY.test(rel) || exported.has(rel); +} + interface LexedImport { specifier?: string | null; start?: number; @@ -160,10 +180,11 @@ async function buildPackage(name: string, typesRoot: string): Promise { const dir = path.join(ROOT, "packages", name); const dist = path.join(dir, "dist"); await rm(dist, { recursive: true, force: true }); + const exported = exportedSources(await readPkg(name)); for (const sub of SOURCE_DIRS) { for (const file of await walk(path.join(dir, sub))) { const rel = path.relative(dir, file); - if (SKIP_FILE.test(file) || DEV_ONLY.has(`${name}/${rel}`)) continue; + if (!shipsFile(name, rel, exported)) continue; const target = path.join(dist, rel); await mkdir(path.dirname(target), { recursive: true }); if (/\.tsx?$/.test(file) && !file.endsWith(".d.ts")) { @@ -236,8 +257,17 @@ async function readPkg(name: string): Promise { ) as Json; } +/** Prints every published exports/bin target that does not resolve; false when there is one. */ +async function reportTargets(): Promise { + const problems = await verifyPackages(ROOT, PACKAGES); + for (const problem of problems) console.error(problem); + if (!problems.length) console.log("every published exports/bin target resolves"); + return problems.length === 0; +} + async function main() { const args = new Set(process.argv.slice(2)); + if (args.has("--verify")) process.exit((await reportTargets()) ? 0 : 1); if (args.has("--check") || args.has("--write-publish-config")) { let stale = 0; for (const name of PACKAGES) { @@ -275,6 +305,7 @@ async function main() { if (name === "cli") await buildCliAssets(); console.log(`built ${name}`); } + if (!(await reportTargets())) process.exit(1); } if (import.meta.url === `file://${process.argv[1]}`) await main(); diff --git a/scripts/smoke-pack.ts b/scripts/smoke-pack.ts index 11273e1b..d8e9dd1a 100644 --- a/scripts/smoke-pack.ts +++ b/scripts/smoke-pack.ts @@ -2,8 +2,10 @@ * End-to-end check of what npm users get (ADR-0013): build, `pnpm pack` every publishable package, * then — in an empty directory outside the monorepo, with plain npm — `npm create cloudhal`, * `npm install`, snapshot + build the site, serve it with `cloudhal dev`, and bundle both - * Cloudflare Workers with `cloudhal deploy --dry-run`. Needs network access to the npm registry - * for third-party dependencies; @cloudhal/* come from the local tarballs. + * Cloudflare Workers with `cloudhal deploy --dry-run`. A second project, with the packages that + * ship `./testing` suites as direct dependencies next to vitest 4 and miniflare 3, must resolve + * with `npm install --dry-run` (no ERESOLVE on their optional peers). Needs network access to the + * npm registry for third-party dependencies; @cloudhal/* come from the local tarballs. * * node scripts/smoke-pack.ts [--keep] [--tarballs ] * @@ -11,7 +13,7 @@ * (`publish-ci.ts`) publishes exactly what this test installed. */ import { execFileSync, spawn } from "node:child_process"; -import { mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises"; +import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { fileURLToPath } from "node:url"; @@ -92,6 +94,7 @@ try { JSON.stringify({ ...pkg, overrides: transitive }, null, 2), ); run("npm", ["install", "--no-audit", "--no-fund"], site); + await directPeersInstall(path.join(tmp, "direct-peers"), overrides); run("npx", ["cloudhal", "snapshot", "--publish", "--label", "smoke"], site); run("npx", ["cloudhal", "build"], site); const html = await readFile(path.join(site, "dist/index.html"), "utf8"); @@ -139,3 +142,39 @@ try { // A dev server child may still be flushing node_modules/.vite for a moment after the group stops. else await rm(tmp, { recursive: true, force: true, maxRetries: 10, retryDelay: 300 }); } + +/** + * A project that depends directly on the packages whose `./testing` suites have optional + * vitest/miniflare peers, with other majors of both. npm stops with ERESOLVE when a direct + * dependency's optional peer does not match the project's copy, whether or not anything imports + * `./testing`. The default starter only reaches these packages transitively, so it misses that. + */ +async function directPeersInstall(dir: string, tarballs: Record): Promise { + const direct = [ + "@cloudhal/storage", + "@cloudhal/analytics", + "@cloudhal/comments", + "@cloudhal/schedules", + ]; + const dependencies = Object.fromEntries(direct.map((name) => [name, tarballs[name]])); + const overrides = Object.fromEntries( + Object.entries(tarballs).filter(([name]) => !direct.includes(name)), + ); + await mkdir(dir, { recursive: true }); + await writeFile( + path.join(dir, "package.json"), + JSON.stringify( + { + name: "smoke-direct-peers", + private: true, + dependencies, + devDependencies: { vitest: "^4.0.0", miniflare: "^3.0.0" }, + overrides, + }, + null, + 2, + ), + ); + run("npm", ["install", "--dry-run", "--no-audit", "--no-fund"], dir); + console.log("✓ direct dependencies resolve next to vitest 4 and miniflare 3"); +} diff --git a/scripts/verify-exports.ts b/scripts/verify-exports.ts new file mode 100644 index 00000000..7617a8e3 --- /dev/null +++ b/scripts/verify-exports.ts @@ -0,0 +1,73 @@ +/** + * Every target a published package names must be in its tarball (ADR-0013: the tarballs ship + * `files`, i.e. `dist`, and point `publishConfig.exports`/`bin` at it). A target outside `files` + * or missing from the build fails only in a consumer's install (`ERR_MODULE_NOT_FOUND`), so + * scripts/build-packages.ts runs this after every build (CI's publishable-packages build, + * smoke-pack, publish) and on its own with `--verify`. + */ +import { readdir, readFile, stat } from "node:fs/promises"; +import path from "node:path"; + +type Json = Record; + +/** `[key, target]` for every string leaf of an exports or bin map, conditions included. */ +export function publishTargets(value: unknown, key: string): [string, string][] { + if (typeof value === "string") return [[key, value]]; + if (!value || typeof value !== "object") return []; + return Object.entries(value as Json).flatMap(([k, v]) => + publishTargets(v, k.startsWith(".") ? k : `${key} (${k})`), + ); +} + +async function isFile(file: string): Promise { + try { + return (await stat(file)).isFile(); + } catch { + return false; + } +} + +/** A plain target must be a file; a wildcard one needs an entry starting with its prefix. */ +async function exists(dir: string, rel: string): Promise { + const star = rel.indexOf("*"); + if (star < 0) return isFile(path.join(dir, rel)); + const prefix = rel.slice(0, star); + const slash = prefix.lastIndexOf("/") + 1; + try { + const entries = await readdir(path.join(dir, prefix.slice(0, slash))); + return entries.some((e) => e.startsWith(prefix.slice(slash))); + } catch { + return false; + } +} + +/** Problems with a package's published exports and bin, one line each (`name: key → target: why`). */ +export async function verifyPublishTargets(dir: string, pkg: Json): Promise { + const publish = (pkg.publishConfig ?? {}) as Json; + const files = Array.isArray(pkg.files) + ? (pkg.files as string[]).map((f) => f.replace(/^\.\//, "").replace(/\/$/, "")) + : undefined; + const problems: string[] = []; + for (const [key, target] of [ + ...publishTargets(publish.exports, "."), + ...publishTargets(publish.bin, "bin"), + ]) { + const rel = target.replace(/^\.\//, ""); + let why: string | undefined; + if (files && !files.some((f) => rel === f || rel.startsWith(`${f}/`))) why = "outside files"; + else if (!(await exists(dir, rel))) why = "missing"; + if (why) problems.push(`${String(pkg.name)}: ${key} → ${target}: ${why}`); + } + return problems; +} + +/** `verifyPublishTargets` over `packages/` for each name. */ +export async function verifyPackages(root: string, names: readonly string[]): Promise { + const problems: string[] = []; + for (const name of names) { + const dir = path.join(root, "packages", name); + const pkg = JSON.parse(await readFile(path.join(dir, "package.json"), "utf8")) as Json; + problems.push(...(await verifyPublishTargets(dir, pkg))); + } + return problems; +} diff --git a/tsconfig.build.json b/tsconfig.build.json index 160920ad..082e6bf4 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -13,6 +13,14 @@ "typeRoots": ["packages/cli/node_modules/@types", "packages/cli/node_modules"], "types": ["node", "@cloudflare/workers-types"] }, + // The test-support entries these packages export as ./testing (they ship). `exclude` below does + // not apply to `files`, so the other packages' testing.ts stay out of the program. + "files": [ + "packages/storage/src/testing.ts", + "packages/analytics/src/testing.ts", + "packages/comments/src/testing.ts", + "packages/schedules/src/testing.ts" + ], "include": [ "packages/core-contracts/src", "packages/core-contracts/scripts",