🌾 feat: rebuild the landing page, and stop it from rotting again

The old page had been quietly broken for some time. It loaded @babel/standalone from an **unpinned** CDN URL, which rolled over to Babel 8 and dropped the `proposal-class-properties` plugin the page asked for, so Babel.transform threw before it ever reached the decorators — and the decorator config it passed was `{ legacy: true }`, which 0.2.0 had already made wrong. Nothing on the page said so. The copy was still selling the 0.1.0 pitch ("Spring-like"), listed about half the decorators, showed `npm install cereale` for a package the registry returns 404 for, and claimed "Zero overhead" against a README that publishes the real microsecond costs. The rebuild is one self-contained page: hand-written CSS, no Tailwind CDN, no CodeMirror, and a vendored compiler pinned by package.json. It loads nothing from the network. The playground runs the real bundled library across six examples, all verified in a headless browser. The reference covers all 68 decorators and the full API, counted from the bundle at runtime so it cannot drift. The hero's compiler error is not typed into the HTML. scripts/build-docs.mjs compiles the snippets with the real tsc and writes the verbatim diagnostics into docs/diagnostics.js, failing the build if a snippet the page calls a compile error ever compiles — and two snippets that must compile guard against the harness passing vacuously. Three guards keep it honest, all wired into CI: - check:docs fails on any remote subresource - build:docs + git diff fails if docs/ is stale against src/ - check:types compiles a consumer against dist/ with no DOM lib, no @types/node and no skipLibCheck That last one found a real packaging defect: `fromRequest` was declared as taking the global `Request`, so cereale's own published .d.ts raised "Cannot find name 'Request'" in any project whose lib and types did not happen to supply it — inside a dependency, in code they may never call, and unfixable from the outside. It now takes a structural JsonBody, which a Request still satisfies. The library's own type tests had been hiding it by enabling both DOM and skipLibCheck. An adversarial review of the finished page caught four more: the lede claimed *every* rule is type-checked (@IsDefined and @IsNotIn deliberately are not), the guarantee section was wrong about the mechanism (a legacy decorator does get design:type under emitDecoratorMetadata — the real claim is about its type signature), one sample called a Movie method on a Media[] and did not compile, and "nested objects come back as real classes" omitted that you have to declare them. WCAG contrast was measured rather than eyeballed: seven real failures fixed in the two themes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
2026-08-05 10:03:16 +00:00
parent 0938300477
commit c828f5cfe9
18 changed files with 1970 additions and 272 deletions
@@ -0,0 +1,81 @@
+/**
+ * Builds the assets the landing page needs, into docs/.
+ *
+ * The page is served by GitHub Pages straight from the repository, so everything it loads has
+ * to be committed — there is no build step on the hosting side. Everything it loads is also
+ * local: the previous page pulled Tailwind, CodeMirror and Babel from three CDNs, and its
+ * playground died silently when the unpinned `@babel/standalone` URL rolled over to Babel 8
+ * and the plugin list it passed stopped existing. Vendoring the compiler pins it to the
+ * version in package.json and to a lockfile.
+ */
+import { build } from 'esbuild';
+import { copyFile, mkdir, readFile, writeFile, stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { collectDiagnostics } from './diagnostics.mjs';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const docs = path.join(root, 'docs');
+const vendor = path.join(docs, 'vendor');
+
+const size = async (file) => {
+  const { size: bytes } = await stat(file);
+  return `${(bytes / 1024).toFixed(0)} KB`;
+};
+
+await mkdir(vendor, { recursive: true });
+
+const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+
+// 1. The library itself, as a browser global the playground can pull names out of.
+await build({
+  entryPoints: [path.join(root, 'src/index.ts')],
+  bundle: true,
+  format: 'iife',
+  globalName: 'Cereale',
+  minify: true,
+  target: 'es2022',
+  tsconfigRaw: {
+    compilerOptions: { experimentalDecorators: false, useDefineForClassFields: true, target: 'es2022' },
+  },
+  outfile: path.join(docs, 'cereale.js'),
+});
+
+// 2. Facts the page would otherwise hard-code and then get wrong. Everything else it needs —
+//    the decorator count, the export list — it derives from the bundle at runtime.
+await writeFile(
+  path.join(docs, 'meta.js'),
+  `// Generated by scripts/build-docs.mjs — do not edit.\n` +
+  `window.CEREALE_META = ${JSON.stringify({ version: pkg.version, node: pkg.engines.node }, null, 2)};\n`
+);
+
+// 3. The compiler errors the page quotes, produced by actually running the compiler. If a
+//    snippet the page calls a compile error ever compiles, this fails the build.
+const { byCase, problems } = await collectDiagnostics(root);
+if (problems.length > 0) {
+  console.error('The landing page makes a claim the compiler does not support:\n' +
+    problems.map((p) => `  - ${p}`).join('\n'));
+  process.exit(1);
+}
+await writeFile(
+  path.join(docs, 'diagnostics.js'),
+  `// Generated by scripts/build-docs.mjs from real tsc output — do not edit.\n` +
+  `window.CEREALE_DIAGNOSTICS = ${JSON.stringify(byCase, null, 2)};\n`
+);
+
+// 4. The playground's TypeScript compiler, pinned by package.json rather than by a CDN URL.
+const babel = path.join(root, 'node_modules/@babel/standalone/babel.min.js');
+await copyFile(babel, path.join(vendor, 'babel.min.js'));
+await writeFile(
+  path.join(vendor, 'README.md'),
+  `# Vendored assets\n\n` +
+  `Generated by \`npm run build:docs\`. Do not edit by hand.\n\n` +
+  `- \`babel.min.js\` — @babel/standalone ${JSON.parse(await readFile(path.join(root, 'node_modules/@babel/standalone/package.json'), 'utf8')).version}, ` +
+  `used by the playground to compile TypeScript with standard decorators in the browser. ` +
+  `Vendored rather than loaded from a CDN: the previous page referenced an unpinned unpkg URL, ` +
+  `which silently began serving Babel 8 and broke the playground.\n`
+);
+
+console.log(`docs/cereale.js       ${await size(path.join(docs, 'cereale.js'))}`);
+console.log(`docs/meta.js          ${await size(path.join(docs, 'meta.js'))}  (v${pkg.version})`);
+console.log(`docs/vendor/babel.min.js  ${await size(path.join(vendor, 'babel.min.js'))}`);
@@ -0,0 +1,78 @@
+/**
+ * Guards the two properties the landing page silently lost before.
+ *
+ * 1. It must load nothing from the network. The previous page pulled Tailwind, CodeMirror and
+ *    Babel from three CDNs, and its playground died without a sound the day the unpinned
+ *    `@babel/standalone` URL started serving Babel 8, whose plugin list no longer had the
+ *    plugin the page asked for. Nobody noticed, because nothing on the page said so.
+ * 2. The bundle the playground runs must match the library source. It is built from `src/`,
+ *    so a change there leaves the page demonstrating a version that no longer exists.
+ *
+ * Ordinary <a href> links out are fine — a link is not a subresource.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const docs = path.join(root, 'docs');
+
+const failures = [];
+
+/** Subresource references — the things a browser fetches without being clicked. */
+const SUBRESOURCES = [
+  [/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi, 'script src'],
+  [/<link\b[^>]*\bhref\s*=\s*["']([^"']+)["']/gi, 'link href'],
+  [/<(?:img|iframe|video|audio|source|embed)\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi, 'media src'],
+  [/@import\s+(?:url\()?["']([^"']+)["']/gi, 'css @import'],
+  [/url\(\s*["']?(https?:\/\/[^)"']+)/gi, 'css url()'],
+];
+
+const isRemote = (url) => /^(?:https?:)?\/\//i.test(url);
+
+const html = (await readdir(docs)).filter((name) => name.endsWith('.html'));
+if (html.length === 0) failures.push('docs/ contains no HTML page');
+
+for (const name of html) {
+  const source = await readFile(path.join(docs, name), 'utf8');
+  for (const [pattern, kind] of SUBRESOURCES) {
+    for (const match of source.matchAll(pattern)) {
+      if (isRemote(match[1])) failures.push(`docs/${name}: remote ${kind} — ${match[1]}`);
+    }
+  }
+  // A fetch to a CDN would not be caught by the markup scan.
+  for (const match of source.matchAll(/\b(?:fetch|importScripts)\(\s*["'`](https?:\/\/[^"'`]+)/gi)) {
+    failures.push(`docs/${name}: remote fetch — ${match[1]}`);
+  }
+}
+
+for (const name of (await readdir(docs)).filter((f) => f.endsWith('.js'))) {
+  const source = await readFile(path.join(docs, name), 'utf8');
+  for (const match of source.matchAll(/\.src\s*=\s*["'`](https?:\/\/[^"'`]+)/gi)) {
+    failures.push(`docs/${name}: loads a remote script — ${match[1]}`);
+  }
+  for (const match of source.matchAll(/\bfetch\(\s*["'`](https?:\/\/[^"'`]+)/gi)) {
+    failures.push(`docs/${name}: remote fetch — ${match[1]}`);
+  }
+}
+
+// The playground compiles against whatever is in the bundle, so a stale bundle means the
+// page demonstrates a library that no longer exists.
+const bundle = await readFile(path.join(docs, 'cereale.js'), 'utf8').catch(() => null);
+if (bundle === null) {
+  failures.push('docs/cereale.js is missing — run `npm run build:docs`');
+} else {
+  // Spot-check that the exports the page relies on actually made it into the bundle.
+  for (const name of ['toInstanceSync', 'toPlainSync', 'flattenErrors', 'JsonMappingError', 'IsString']) {
+    if (!bundle.includes(name)) failures.push(`docs/cereale.js does not export ${name} — rebuild it`);
+  }
+}
+
+const babel = path.join(docs, 'vendor/babel.min.js');
+await readFile(babel).catch(() => failures.push('docs/vendor/babel.min.js is missing — run `npm run build:docs`'));
+
+if (failures.length > 0) {
+  console.error('docs check failed:\n' + failures.map((f) => `  - ${f}`).join('\n'));
+  process.exit(1);
+}
+console.log(`docs check passed — ${html.length} page(s), no network dependencies.`);
@@ -0,0 +1,108 @@
+/**
+ * Compiles a minimal consumer against the built type declarations, in the least forgiving
+ * configuration a real project might have: no `skipLibCheck`, no `DOM` lib, no `types`.
+ *
+ * A zero-dependency library's public types have to stand on their own. `fromRequest` used to
+ * be declared as taking the global `Request`, so cereale's own `.d.ts` raised
+ * `Cannot find name 'Request'` in any project whose `lib` and `types` did not happen to
+ * supply it — an error inside a dependency, in code the consumer may never call, that they
+ * cannot fix from the outside. The library's own test suite hid it by enabling both.
+ *
+ * Run after `npm run build`, since it checks what is actually published.
+ */
+import ts from 'typescript';
+import { mkdtemp, rm, writeFile, access } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const types = path.join(root, 'dist/esm/index.d.ts');
+
+try {
+  await access(types);
+} catch {
+  console.error('dist/esm/index.d.ts is missing — run `npm run build` first.');
+  process.exit(1);
+}
+
+const CONSUMER = `
+import {
+  IsString, MinLength, IsInt, Min, IsDate, JsonProperty, JsonWriteOnly,
+  ValidateNested, JsonType, fromJsonSync, toPlainSync, validateSync, fromRequest,
+} from ${JSON.stringify(types.replace(/\.d\.ts$/, '.js'))};
+
+class Address {
+  @IsString() city!: string;
+}
+
+export class User {
+  @JsonProperty('display_name')
+  @IsString() @MinLength(2)
+  displayName!: string;
+
+  @IsInt() @Min(0)
+  age!: number;
+
+  @IsDate()
+  joinedAt!: Date;
+
+  @JsonWriteOnly() @IsString()
+  password!: string;
+
+  @ValidateNested() @JsonType(() => Address)
+  address!: Address;
+
+  greet(): string { return 'Hi ' + this.displayName; }
+}
+
+export function use(body: string) {
+  const user = fromJsonSync(User, body);
+  return [user.greet(), toPlainSync(user), validateSync(user)];
+}
+
+// Declared structurally, so this must type-check without the DOM or Node globals.
+export function fromAnythingWithJson(source: { json(): Promise<unknown> }) {
+  return fromRequest(User, source);
+}
+`;
+
+const dir = await mkdtemp(path.join(tmpdir(), 'cereale-consumer-'));
+try {
+  const file = path.join(dir, 'consumer.ts');
+  await writeFile(file, CONSUMER);
+
+  const program = ts.createProgram([file], {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    // Deliberately bare: no DOM, no node, and lib checking left on.
+    lib: ['lib.esnext.d.ts', 'lib.esnext.decorators.d.ts'],
+    types: [],
+    strict: true,
+    strictPropertyInitialization: false,
+    skipLibCheck: false,
+    noEmit: true,
+  });
+
+  const diagnostics = [
+    ...program.getSemanticDiagnostics(),
+    ...program.getSyntacticDiagnostics(),
+    ...program.getGlobalDiagnostics(),
+  ];
+
+  if (diagnostics.length > 0) {
+    console.error(
+      'cereale\'s published types do not stand alone. A consumer without DOM lib or @types/node sees:\n' +
+      diagnostics.slice(0, 12).map((d) => {
+        const where = d.file ? `${path.basename(d.file.fileName)}:${d.file.getLineAndCharacterOfPosition(d.start ?? 0).line + 1} ` : '';
+        return `  - ${where}TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`;
+      }).join('\n')
+    );
+    process.exit(1);
+  }
+
+  console.log('type check passed — published types resolve with no DOM lib and no @types/node.');
+} finally {
+  await rm(dir, { recursive: true, force: true });
+}
@@ -0,0 +1,210 @@
+/**
+ * Runs the real TypeScript compiler over the snippets the landing page quotes, and writes
+ * the verbatim diagnostics into docs/diagnostics.js.
+ *
+ * The page's central claim is that a rule which does not fit its field does not compile. The
+ * honest way to show that is not to type a plausible-looking error into the HTML — it is to
+ * compile the snippet and print whatever the compiler said. If a snippet marked `rejected`
+ * ever starts compiling, or a snippet marked `compiles` stops, the build fails here rather
+ * than the page quietly going on claiming something that is no longer true.
+ */
+import ts from 'typescript';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+/** Each case is compiled against the real library, not a stub. */
+export const CASES = [
+  {
+    id: 'hero',
+    expect: 'rejected',
+    // Kept character-for-character in step with the hero block in docs/index.html.
+    source: `import { JsonProperty, IsString, Matches, IsInt, Min, fromJsonSync } from '../src/index.js';
+declare const body: string;
+
+class Order {
+  @JsonProperty('order_ref')
+  @IsString() @Matches(/^[A-Z]-\\d+$/)
+  ref!: string;
+
+  @IsInt() @Min(1)
+  quantity!: number;
+
+  @IsString()
+  placedAt!: Date;
+
+  total(): number { return this.quantity * 9.99; }
+}
+
+const order = fromJsonSync(Order, body);
+order.total();
+`,
+  },
+  {
+    id: 'compare',
+    expect: 'rejected',
+    source: `import { IsString } from '../src/index.js';
+
+export class User {
+  @IsString()
+  age!: number;
+}
+`,
+  },
+  {
+    id: 'instances',
+    expect: 'compiles',
+    // The "What you get back" section. It is here because an earlier draft showed
+    // `list.items[0].hours()` on a `Media[]`, which tsc rejects with TS2339 — TypeScript that
+    // the compiler refuses, on a page whose whole argument is that the compiler is the authority.
+    source: `import { IsString, IsInt, Min, JsonPolymorphic, ValidateNested, fromJsonSync } from '../src/index.js';
+declare const body: string;
+
+class Media {
+  @IsString() title!: string;
+}
+class Movie extends Media {
+  @IsInt() @Min(1) duration!: number;
+  hours() { return this.duration / 60; }
+}
+class Song extends Media {
+  @IsString() artist!: string;
+}
+
+class Playlist {
+  @JsonPolymorphic<Media>('type', [
+    { value: Movie, name: 'movie' },
+    { value: Song,  name: 'song'  },
+  ])
+  @ValidateNested({ each: true })
+  items!: Media[];
+}
+
+const list = fromJsonSync(Playlist, body);
+const first = list.items[0];
+
+first instanceof Movie;
+
+if (first instanceof Movie) {
+  first.hours();
+}
+`,
+  },
+  {
+    id: 'correct',
+    expect: 'compiles',
+    // The same class with the rule that actually fits, so a broken harness cannot make the
+    // two cases above "pass" by failing everything.
+    source: `import { JsonProperty, IsString, Matches, IsInt, Min, IsDate, fromJsonSync } from '../src/index.js';
+declare const body: string;
+
+class Order {
+  @JsonProperty('order_ref')
+  @IsString() @Matches(/^[A-Z]-\\d+$/)
+  ref!: string;
+
+  @IsInt() @Min(1)
+  quantity!: number;
+
+  @IsDate()
+  placedAt!: Date;
+
+  total(): number { return this.quantity * 9.99; }
+}
+
+const order = fromJsonSync(Order, body);
+order.total();
+`,
+  },
+];
+
+/** Compiles every case in one program and returns its diagnostics, keyed by case id. */
+export async function collectDiagnostics(root) {
+  const dir = await mkdtemp(path.join(tmpdir(), 'cereale-diagnostics-'));
+  try {
+    const files = new Map();
+    for (const testCase of CASES) {
+      const file = path.join(dir, `${testCase.id}.ts`);
+      // The snippets import '../src/index.js' relative to a sibling of src/, so they are
+      // written one directory below the repo root.
+      const target = path.join(root, '.diagnostics', `${testCase.id}.ts`);
+      files.set(testCase.id, target);
+      await writeFile(file, testCase.source);
+    }
+
+    // Write into the repo so that '../src/index.js' resolves the way it does for a consumer.
+    const scratch = path.join(root, '.diagnostics');
+    await rm(scratch, { recursive: true, force: true });
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(scratch, { recursive: true });
+    for (const testCase of CASES) {
+      await writeFile(files.get(testCase.id), testCase.source);
+    }
+
+    const configPath = path.join(root, 'tsconfig.json');
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, root);
+
+    const program = ts.createProgram([...files.values()], {
+      ...parsed.options,
+      noEmit: true,
+      rootDir: root,
+      outDir: undefined,
+      declaration: false,
+      declarationMap: false,
+      sourceMap: false,
+    });
+
+    const all = [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()];
+    const byCase = {};
+    const problems = [];
+
+    for (const testCase of CASES) {
+      const file = files.get(testCase.id);
+      const mine = all.filter((d) => d.file && path.resolve(d.file.fileName) === path.resolve(file));
+
+      if (testCase.expect === 'rejected' && mine.length === 0) {
+        problems.push(`case "${testCase.id}" was expected to be rejected by tsc, but it compiled. ` +
+          'The landing page claims this is a compile error — either the claim or the library is wrong.');
+      }
+      if (testCase.expect === 'compiles' && mine.length > 0) {
+        problems.push(`case "${testCase.id}" was expected to compile, but tsc reported: ` +
+          ts.flattenDiagnosticMessageText(mine[0].messageText, ' '));
+      }
+
+      byCase[testCase.id] = mine.map((diagnostic) => {
+        const { line } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+        return {
+          code: diagnostic.code,
+          // The chain, flattened one message per level, so the page can show the headline
+          // and the "Type X is not assignable to type Y" leaf without inventing either.
+          messages: flattenChain(diagnostic.messageText),
+          line: line + 1,
+        };
+      });
+    }
+
+    // Diagnostics anywhere else mean the harness itself is broken.
+    const stray = all.filter((d) => !d.file || ![...files.values()].some((f) => path.resolve(d.file.fileName) === path.resolve(f)));
+    if (stray.length > 0) {
+      problems.push(`the diagnostics harness produced ${stray.length} error(s) outside the cases, ` +
+        `starting with: ${ts.flattenDiagnosticMessageText(stray[0].messageText, ' ')}`);
+    }
+
+    await rm(scratch, { recursive: true, force: true });
+    return { byCase, problems };
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function flattenChain(messageText) {
+  if (typeof messageText === 'string') return [messageText];
+  const out = [];
+  let node = messageText;
+  while (node) {
+    out.push(node.messageText);
+    node = node.next && node.next[0];
+  }
+  return out;
+}