@rexezuge/tooling 0.0.0-stage → 1.0.0

package/src/scripts/spa-shell.test.ts

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { ensureSpaShellStub, spaShellCli, verifySpaShell } from './spa-shell';
+
+function tempTree(): string {
+  return mkdtempSync(join(tmpdir(), 'spa-shell-'));
+}
+
+function writeBuild(root: string, html: string): void {
+  const shell = join(root, 'apps/api/src/generated');
+  mkdirSync(shell, { recursive: true });
+  writeFileSync(join(shell, 'spa-shell.ts'), `export const SPA_HTML: string = ${JSON.stringify(html)};\n`, 'utf8');
+  const distAssets = join(root, 'apps/web/dist/assets');
+  mkdirSync(distAssets, { recursive: true });
+  writeFileSync(join(root, 'apps/web/dist/index.html'), html, 'utf8');
+  for (const asset of html.matchAll(/\/assets\/([^"]+)/g)) {
+    writeFileSync(join(distAssets, asset[1] as string), 'console.log(1)', 'utf8');
+  }
+}
+
+const REAL_HTML = `<!doctype html><html><head><meta charset="utf-8" /><title>Spa Shell Fixture</title><link rel="stylesheet" href="/assets/index-def456.css" /><script type="module" src="/assets/index-abc123.js"></script></head><body><div id="root"></div><!-- fixture padding so the shell exceeds the 200-char minimum --></body></html>`;
+
+describe('ensureSpaShellStub', () => {
+  it('creates the stub when absent', () => {
+    const root = tempTree();
+    const result = ensureSpaShellStub({ root });
+    expect(result.created).toBe(true);
+    expect(existsSync(join(root, 'apps/api/src/generated/spa-shell.ts'))).toBe(true);
+    expect(readFileSync(result.path, 'utf8')).toContain("SPA_HTML: string = ''");
+  });
+
+  it('never overwrites an existing file', () => {
+    const root = tempTree();
+    const path = join(root, 'apps/api/src/generated', 'spa-shell.ts');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, 'real content', 'utf8');
+    const result = ensureSpaShellStub({ root });
+    expect(result.created).toBe(false);
+    expect(readFileSync(path, 'utf8')).toBe('real content');
+  });
+});
+
+describe('verifySpaShell', () => {
+  it('passes a self-consistent build', () => {
+    const root = tempTree();
+    writeBuild(root, REAL_HTML);
+    expect(verifySpaShell({ root }).problems).toStrictEqual([]);
+  });
+
+  it('reports a missing shell', () => {
+    const root = tempTree();
+    const { problems } = verifySpaShell({ root });
+    expect(problems.join('\n')).toContain('is missing');
+  });
+
+  it('reports the postinstall stub', () => {
+    const root = tempTree();
+    const path = join(root, 'apps/api/src/generated', 'spa-shell.ts');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, "export const SPA_HTML: string = '';\n", 'utf8');
+    expect(verifySpaShell({ root }).problems.join('\n')).toContain('postinstall stub');
+  });
+
+  it('reports referenced-but-missing assets', () => {
+    const root = tempTree();
+    writeBuild(root, REAL_HTML);
+    rmSync(join(root, 'apps/web/dist/assets'), { recursive: true, force: true });
+    expect(verifySpaShell({ root }).problems.join('\n')).toContain('/assets/index-abc123.js');
+  });
+
+  it('reports a shell that disagrees with dist/index.html', () => {
+    const root = tempTree();
+    writeBuild(root, REAL_HTML);
+    writeFileSync(join(root, 'apps/web/dist/index.html'), '<!doctype html><html>different</html>', 'utf8');
+    expect(verifySpaShell({ root }).problems.join('\n')).toContain('does not match');
+  });
+});
+
+describe('spaShellCli', () => {
+  it('verifies and reports per mode', () => {
+    const root = tempTree();
+    expect(spaShellCli(['ensure', root])).toBe(0);
+    expect(spaShellCli(['ensure', root])).toBe(0);
+    expect(spaShellCli(['verify', root])).toBe(1); // still the stub
+    writeBuild(root, REAL_HTML);
+    expect(spaShellCli(['verify', root])).toBe(0);
+    expect(spaShellCli(['bogus', root])).toBe(1);
+  });
+});

package/src/scripts/spa-shell.ts

@@ -0,0 +1,179 @@
+/**
+ * The SPA shell pair: `ensure-spa-shell-stub` + `verify-spa-shell`.
+ *
+ * Provenance: the `scripts/ensure-spa-shell-stub.mjs` +
+ * `scripts/verify-spa-shell.mjs` pair (Durable-DAV) and Edge-Sonic's typed
+ * `scripts/build/{ensure-spa-shell-stub,spa-shell-checks,verify-spa-shell}.ts`.
+ * The generate step itself is a Vite plugin (`spaShellEmbedPlugin` in
+ * `vite.ts`) because it must run on every build; this module holds the
+ * freshness contract around the generated file.
+ *
+ * Why the pair exists: `apps/api/src/generated/spa-shell.ts` and
+ * `apps/web/dist/` are both gitignored build artifacts. A fresh clone gets the
+ * empty postinstall stub and every browser navigation returns a blank page,
+ * with nothing in the source tree saying so.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+
+interface SpaShellPaths {
+  /** Repo root. */
+  root: string;
+  /** Generated TS module path, relative to root. */
+  shellPath?: string;
+  /** Built SPA index.html path, relative to root. */
+  distIndexPath?: string;
+}
+
+interface VerifyResult {
+  problems: string[];
+}
+
+const DEFAULT_SHELL = 'apps/api/src/generated/spa-shell.ts';
+const DEFAULT_DIST_INDEX = 'apps/web/dist/index.html';
+const STUB_CONTENT =
+  "// Auto-generated stub - real content is produced by the build step via the Vite plugin.\nexport const SPA_HTML: string = '';\n";
+
+/** A built shell is a full Vite index.html; any small threshold rejects the stub. */
+const MIN_HTML_CHARS = 200;
+
+function resolvePaths(options: SpaShellPaths): { shell: string; distIndex: string; distAssets: string } {
+  const root = resolve(options.root);
+  const shell = join(root, options.shellPath ?? DEFAULT_SHELL);
+  const distIndex = join(root, options.distIndexPath ?? DEFAULT_DIST_INDEX);
+  return { shell, distIndex, distAssets: join(dirname(distIndex), 'assets') };
+}
+
+/**
+ * Create the empty stub when (and only when) nothing is there yet, so a fresh
+ * clone typechecks and `pnpm run build` regenerates the real thing. Never
+ * overwrites an existing file — overwriting would erase a real build with a
+ * stub on the next `pnpm install`.
+ */
+function ensureSpaShellStub(options: SpaShellPaths): { created: boolean; path: string } {
+  const { shell } = resolvePaths(options);
+  if (existsSync(shell)) {
+    return { created: false, path: shell };
+  }
+  mkdirSync(dirname(shell), { recursive: true });
+  writeFileSync(shell, STUB_CONTENT, 'utf8');
+  return { created: true, path: shell };
+}
+
+/** The `SPA_HTML` string literal, decoded from the generated TS module. */
+function readEmbeddedHtml(shell: string, problems: string[]): string | null {
+  if (!existsSync(shell)) {
+    problems.push(
+      `${shell} is missing — run the build (only apps/web has a build step).`,
+    );
+    return null;
+  }
+  const source = readFileSync(shell, 'utf8');
+  const marker = 'export const SPA_HTML: string = ';
+  const at = source.indexOf(marker);
+  if (at === -1) {
+    problems.push(`${shell} does not export SPA_HTML — regenerate it with the build.`);
+    return null;
+  }
+  const literal = source.slice(at + marker.length).replace(/;\s*$/, '');
+  if (literal === "''" || literal === '""') {
+    problems.push(
+      `${shell} still holds the empty postinstall stub — run the build. Until then every browser navigation served by the API worker is a blank page.`,
+    );
+    return null;
+  }
+  let html: unknown;
+  try {
+    html = JSON.parse(literal);
+  } catch {
+    problems.push(`${shell} is not the generated shape — delete it and run the build.`);
+    return null;
+  }
+  if (typeof html !== 'string' || html.length < MIN_HTML_CHARS) {
+    problems.push(`${shell} holds no usable HTML — run the build. Until then every browser navigation is a blank page.`);
+    return null;
+  }
+  return html;
+}
+
+/**
+ * Fail when the shell the API worker serves is missing or self-inconsistent:
+ *
+ * - the postinstall stub (or no build at all) still in place;
+ * - `/assets/...` bundles referenced but not emitted (a half-cleaned dist,
+ *   which serves a shell whose JS 404s);
+ * - `spa-shell.ts` and `dist/index.html` disagreeing — only one half of the
+ *   build was refreshed.
+ *
+ * Known limit, stated rather than papered over: a *stale but self-consistent*
+ * pair passes. That class is covered at the source level by each repo's SPA
+ * parser integration test; the remaining duty is operational — run the build
+ * after touching `apps/web`, before deploy.
+ */
+function verifySpaShell(options: SpaShellPaths): VerifyResult {
+  const { shell, distIndex, distAssets } = resolvePaths(options);
+  const problems: string[] = [];
+  const html = readEmbeddedHtml(shell, problems);
+  if (html === null) {
+    return { problems };
+  }
+  const referenced = [...html.matchAll(/(?:src|href)="\/assets\/([^"]+)"/g)].map((match) => match[1] as string);
+  if (referenced.length === 0) {
+    problems.push('The embedded shell references no /assets/ bundles — it is not a real build output.');
+  }
+  for (const asset of new Set(referenced)) {
+    if (!existsSync(join(distAssets, asset))) {
+      problems.push(`The embedded shell references /assets/${asset}, which is not in ${distAssets} — run the build.`);
+    }
+  }
+  if (!existsSync(distIndex)) {
+    problems.push(`${distIndex} is missing — run the build.`);
+  } else if (readFileSync(distIndex, 'utf8') !== html) {
+    problems.push(`${shell} does not match ${distIndex} — run the build.`);
+  }
+  return { problems };
+}
+
+const CLI_SHAPES = 'verify|ensure';
+
+/** CLI entry: `spaShellCli(['verify'|'ensure', 'repo-root?'])`. */
+function spaShellCli(argv: readonly string[] = process.argv.slice(2)): number {
+  const mode = argv[0] ?? 'verify';
+  if (!CLI_SHAPES.split('|').includes(mode)) {
+    console.error(`Usage: tsx spa-shell.ts <${CLI_SHAPES}> [repo-root]`);
+    return 1;
+  }
+  const options: SpaShellPaths = { root: argv[1] ?? process.cwd() };
+  if (mode === 'ensure') {
+    const result = ensureSpaShellStub(options);
+    if (result.created) {
+      console.log(`ensure-spa-shell-stub: created stub at ${result.path}`);
+    } else {
+      console.log(`ensure-spa-shell-stub: ${result.path} already present, left untouched`);
+    }
+    return 0;
+  }
+  const { problems } = verifySpaShell(options);
+  if (problems.length > 0) {
+    console.error('SPA shell check failed:');
+    for (const problem of problems) console.error(`  - ${problem}`);
+    return 1;
+  }
+  console.log('SPA shell check passed.');
+  return 0;
+}
+
+export { ensureSpaShellStub, spaShellCli, verifySpaShell };
+export type { SpaShellPaths, VerifyResult };
+
+// Run only when this file is the entrypoint.
+//
+// The rules above are pure and the tests import them directly, so a module-level
+// call would shell out (and exit) during a test run. The URL comparison rather than
+// an unconditional call is the same guard Durable-DAV's init-secrets.ts uses, and
+// it is what keeps the rule modules importable — which is the whole reason they are
+// separate modules in the first place.
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exit(spaShellCli(process.argv.slice(2)));
+}

package/src/scripts/validate-locales.test.ts

@@ -0,0 +1,89 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { parseObjectLiteral, validateLocales, validateLocalesCli } from './validate-locales';
+
+function writeBundles(root: string, locale: string, bundle: Record<string, unknown>): string {
+  const dir = join(root, locale);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'translation.json'), JSON.stringify(bundle), 'utf8');
+  return root;
+}
+
+const EN = { common: { unauthorized: 'Unauthorized', forbidden: 'Forbidden' } };
+
+describe('validateLocales', () => {
+  it('passes when every locale mirrors the base keys', () => {
+    const root = mkdtempSync(join(tmpdir(), 'locales-'));
+    writeBundles(root, 'en', EN);
+    writeBundles(root, 'de', { common: { unauthorized: 'Nicht autorisiert', forbidden: 'Verboten' } });
+    const report = validateLocales(root);
+    expect(report.locales).toStrictEqual(['de', 'en']);
+    expect(report.keys).toBe(2);
+    expect(report.problems).toStrictEqual([]);
+  });
+
+  it('reports both missing and extra keys', () => {
+    const root = mkdtempSync(join(tmpdir(), 'locales-'));
+    writeBundles(root, 'en', EN);
+    writeBundles(root, 'de', { common: { unauthorized: 'x', oops: 'y' } });
+    const problems = validateLocales(root).problems;
+    expect(problems).toStrictEqual([
+      { locale: 'de', problem: 'missing key: common.forbidden' },
+      { locale: 'de', problem: 'extra key not in en: common.oops' },
+    ]);
+  });
+
+  it('reports a missing directory and a missing base locale', () => {
+    expect(validateLocales('/nonexistent-xyz').problems.length).toBeGreaterThan(0);
+    const root = mkdtempSync(join(tmpdir(), 'locales-'));
+    writeBundles(root, 'de', EN);
+    expect(validateLocales(root).problems[0]?.problem).toContain('base locale');
+  });
+
+  it('supports flat <locale>.json bundles', () => {
+    const root = mkdtempSync(join(tmpdir(), 'locales-'));
+    writeFileSync(join(root, 'en.json'), JSON.stringify(EN), 'utf8');
+    writeFileSync(join(root, 'de.json'), JSON.stringify({ common: { unauthorized: 'x', forbidden: 'y' } }), 'utf8');
+    expect(validateLocales(root).problems).toStrictEqual([]);
+  });
+
+  it('CLI returns 1 with problems and 0 without', () => {
+    const root = mkdtempSync(join(tmpdir(), 'locales-'));
+    writeBundles(root, 'en', EN);
+    writeBundles(root, 'de', { common: { unauthorized: 'x' } });
+    expect(validateLocalesCli([root])).toBe(1);
+    writeFileSync(join(root, 'de', 'translation.json'), JSON.stringify(EN), 'utf8');
+    expect(validateLocalesCli([root])).toBe(0);
+  });
+
+  it('reads the module shape the kit i18n bundles use', () => {
+    // `@rexezuge/i18n` ships `const enStrings: BackendStrings = { … }` per file, so
+    // the same gate covers the backend catalogs and the SPA JSON bundles.
+    const root = mkdtempSync(join(tmpdir(), 'locales-'));
+    writeFileSync(join(root, 'en.ts'), "import type { BackendStrings } from '../BackendStrings';\n\nconst enStrings: BackendStrings = {\n  common: {\n    unauthorized: 'Authentication Required.',\n    forbidden: 'Access Denied.',\n  },\n};\n\nexport { enStrings };\n", 'utf8');
+    writeFileSync(join(root, 'de.ts'), "const deStrings = {\n  common: {\n    unauthorized: 'Authentifizierung Erforderlich.',\n    forbidden: 'Zugriff Verweigert.',\n  },\n};\n", 'utf8');
+    expect(validateLocales(root).problems).toStrictEqual([]);
+  });
+
+  it('extracts an object literal, ignoring the type annotation and the import', () => {
+    const source = [
+      "import type { BackendStrings } from '../BackendStrings';",
+      '',
+      'const enStrings: BackendStrings = {',
+      "  common: { unauthorized: 'It\\'s fine', },",
+      '};',
+      '',
+      'export { enStrings };',
+    ].join('\n');
+    expect(parseObjectLiteral(source, 'en.ts')).toStrictEqual({ common: { unauthorized: "It's fine" } });
+  });
+
+  it('reports an unparseable module rather than passing it silently', () => {
+    const root = mkdtempSync(join(tmpdir(), 'locales-'));
+    writeFileSync(join(root, 'en.ts'), 'const enStrings = {};\n', 'utf8');
+    const problems = validateLocales(root).problems;
+    expect(problems[0]?.problem).toMatch(/no keys|object literal/);
+  });
+});