@jjlmoya/utils-games-development 1.66.0 → 1.68.0

package/src/tests/no_h1_in_components.test.ts

@@ -1,48 +1,48 @@
-import { describe, it, expect } from 'vitest';
-import { readdirSync, readFileSync } from 'fs';
-import { join } from 'path';
-
-const EXCLUDED_DIRS = ['node_modules', 'pages', 'layouts'];
-
-function findAstroFiles(dir: string): string[] {
-  const files: string[] = [];
-  const entries = readdirSync(dir, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory() && !EXCLUDED_DIRS.includes(entry.name)) {
-      files.push(...findAstroFiles(fullPath));
-    } else if (entry.isFile() && entry.name.endsWith('.astro')) {
-      files.push(fullPath);
-    }
-  }
-
-  return files;
-}
-
-function hasH1(content: string): boolean {
-  return /<h1[\s>]/i.test(content);
-}
-
-const srcDir = join(process.cwd(), 'src');
-const astroFiles = findAstroFiles(srcDir);
-
-describe('No H1 in Components', () => {
-  if (astroFiles.length === 0) {
-    it('no astro components found', () => {
-      expect(true).toBe(true);
-    });
-  }
-
-  astroFiles.forEach((file) => {
-    const relativePath = file.replace(process.cwd(), '');
-    it(`${relativePath} should not contain <h1>`, () => {
-      const content = readFileSync(file, 'utf-8');
-      expect(
-        hasH1(content),
-        `File "${relativePath}" contains a <h1> element. Use <h2> or lower inside components — h1 belongs to the page layout.`,
-      ).toBe(false);
-    });
-  });
-});
-
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const EXCLUDED_DIRS = ['node_modules', 'pages', 'layouts'];
+
+function findAstroFiles(dir: string): string[] {
+  const files: string[] = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory() && !EXCLUDED_DIRS.includes(entry.name)) {
+      files.push(...findAstroFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith('.astro')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function hasH1(content: string): boolean {
+  return /<h1[\s>]/i.test(content);
+}
+
+const srcDir = join(process.cwd(), 'src');
+const astroFiles = findAstroFiles(srcDir);
+
+describe('No H1 in Components', () => {
+  if (astroFiles.length === 0) {
+    it('no astro components found', () => {
+      expect(true).toBe(true);
+    });
+  }
+
+  astroFiles.forEach((file) => {
+    const relativePath = file.replace(process.cwd(), '');
+    it(`${relativePath} should not contain <h1>`, () => {
+      const content = readFileSync(file, 'utf-8');
+      expect(
+        hasH1(content),
+        `File "${relativePath}" contains a <h1> element. Use <h2> or lower inside components — h1 belongs to the page layout.`,
+      ).toBe(false);
+    });
+  });
+});
+

package/src/tests/pagespeed_best_practices.test.ts

@@ -1,198 +1,198 @@
-import { describe, expect, it } from 'vitest';
-import { readdirSync, readFileSync } from 'fs';
-import { join, relative } from 'path';
-import { ALL_TOOLS } from '../tools';
-import type { SEOSection, ToolLocaleContent } from '../types';
-
-const srcDir = join(process.cwd(), 'src');
-const toolDir = join(srcDir, 'tool');
-const geometryReads = [
-  'offsetWidth',
-  'offsetHeight',
-  'offsetTop',
-  'offsetLeft',
-  'clientWidth',
-  'clientHeight',
-  'clientTop',
-  'clientLeft',
-  'scrollWidth',
-  'scrollHeight',
-  'scrollTop',
-  'scrollLeft',
-  'getBoundingClientRect',
-  'getClientRects',
-  'computedStyle',
-  'getComputedStyle',
-];
-const domWrites = [
-  '.style.',
-  '.classList.add',
-  '.classList.remove',
-  '.classList.toggle',
-  '.appendChild',
-  '.insertBefore',
-  '.prepend',
-  '.append',
-  '.remove',
-  '.innerHTML',
-  '.textContent',
-  '.setAttribute',
-];
-
-function findFiles(dir: string, extensions: string[]): string[] {
-  const files: string[] = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) files.push(...findFiles(fullPath, extensions));
-    else if (extensions.some((extension) => entry.name.endsWith(extension))) files.push(fullPath);
-  }
-  return files;
-}
-
-function relativePath(file: string): string {
-  return relative(process.cwd(), file).replace(/\\/g, '/');
-}
-
-function findFormControls(content: string, tagName: 'input' | 'select'): RegExpMatchArray[] {
-  return Array.from(content.matchAll(new RegExp(`<${tagName}\\b[^>]*>`, 'gi')));
-}
-
-function attrValue(tag: string, attr: string): string | null {
-  const match = tag.match(new RegExp(`\\b${attr}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|\\{([^}]+)\\})`, 'i'));
-  return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
-}
-
-function booleanAttr(tag: string, attr: string): boolean {
-  return new RegExp(`\\b${attr}\\b`, 'i').test(tag);
-}
-
-function controlStartIndex(content: string, tag: RegExpMatchArray): number {
-  return tag.index ?? content.indexOf(tag[0]);
-}
-
-function hasWrappingLabel(content: string, tag: RegExpMatchArray): boolean {
-  const index = controlStartIndex(content, tag);
-  const before = content.slice(0, index);
-  const labelOpen = before.lastIndexOf('<label');
-  const labelClose = before.lastIndexOf('</label>');
-  const nextLabelClose = content.indexOf('</label>', index + tag[0].length);
-  return labelOpen > labelClose && nextLabelClose !== -1;
-}
-
-function hasAccessibleName(content: string, tag: RegExpMatchArray): boolean {
-  const source = tag[0];
-  if (attrValue(source, 'aria-label')) return true;
-  if (attrValue(source, 'aria-labelledby')) return true;
-  const id = attrValue(source, 'id');
-  if (id && hasExplicitLabel(content, id)) return true;
-  return hasWrappingLabel(content, tag);
-}
-
-function isVisuallyHiddenFileInput(tag: string): boolean {
-  const type = attrValue(tag, 'type')?.toLowerCase() ?? 'text';
-  const attributes = `${attrValue(tag, 'style') ?? ''} ${attrValue(tag, 'class') ?? ''}`.toLowerCase();
-  const hiddenPatterns = ['display:none', 'display: none', 'file-input'];
-  return type === 'file' && hiddenPatterns.some((pattern) => attributes.includes(pattern));
-}
-
-function isIgnoredInput(tag: string): boolean {
-  const type = attrValue(tag, 'type')?.toLowerCase() ?? 'text';
-  return ['hidden', 'button', 'submit', 'reset'].includes(type) || booleanAttr(tag, 'aria-hidden') || isVisuallyHiddenFileInput(tag);
-}
-
-function controlFailures(content: string, tagName: 'input' | 'select'): string[] {
-  return findFormControls(content, tagName)
-    .filter((tag) => tagName !== 'input' || !isIgnoredInput(tag[0]))
-    .filter((tag) => !hasAccessibleName(content, tag))
-    .map((tag) => tag[0]);
-}
-
-function explicitLabelMessage(tagName: string, path: string, failures: string[]): string {
-  return `${tagName} controls without label, wrapping label, aria-label or aria-labelledby in ${path}:\n${failures.join('\n')}`;
-}
-
-function hasExplicitLabel(content: string, id: string): boolean {
-  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  return (
-    new RegExp(`<label\\b[^>]*\\bfor\\s*=\\s*["']${escapedId}["'][^>]*>`, 'i').test(content)
-    || new RegExp(`<label\\b[^>]*\\bfor\\s*=\\s*\\{${escapedId}\\}[^>]*>`, 'i').test(content)
-  );
-}
-
-function headingLevels(sections: SEOSection[]): number[] {
-  return sections
-    .filter((section) => section.type === 'title')
-    .map((section) => Number('level' in section ? section.level : 0))
-    .filter((level) => Number.isInteger(level) && level > 0);
-}
-
-function findHeadingLevelJumps(levels: number[]): string[] {
-  const failures: string[] = [];
-  levels.forEach((level, index) => {
-    const previous = index === 0 ? 1 : levels[index - 1];
-    if (previous && level > previous + 1) {
-      failures.push(`h${previous} -> h${level}`);
-    }
-  });
-  return failures;
-}
-
-function hasDomWriteBeforeGeometryRead(content: string): boolean {
-  const normalized = content.replace(/\s+/g, ' ');
-  return domWrites.some((write) => {
-    const writeIndex = normalized.indexOf(write);
-    if (writeIndex === -1) return false;
-    return geometryReads.some((read) => normalized.indexOf(read, writeIndex + write.length) !== -1);
-  });
-}
-
-describe('PageSpeed best-practice guards', () => {
-  const astroToolFiles = findFiles(toolDir, ['.astro']);
-  const scriptFiles = findFiles(toolDir, ['.astro', '.ts', '.js']);
-
-  astroToolFiles.forEach((file) => {
-    const displayPath = relativePath(file);
-
-    it(`${displayPath} labels every input with an explicit label`, () => {
-      const content = readFileSync(file, 'utf-8');
-      const failures = controlFailures(content, 'input');
-
-      expect(failures, explicitLabelMessage('Input', displayPath, failures)).toEqual([]);
-    });
-
-    it(`${displayPath} labels every select with an explicit label`, () => {
-      const content = readFileSync(file, 'utf-8');
-      const failures = controlFailures(content, 'select');
-
-      expect(failures, explicitLabelMessage('Select', displayPath, failures)).toEqual([]);
-    });
-  });
-
-  ALL_TOOLS.forEach((tool) => {
-    Object.entries(tool.entry.i18n).forEach(([locale, loader]) => {
-      it(`${tool.entry.id}/${locale} keeps SEO headings sequential`, async () => {
-        if (!loader) return;
-        const content = (await loader()) as ToolLocaleContent;
-        const levels = headingLevels(content.seo);
-        const failures = findHeadingLevelJumps(levels);
-
-        expect(
-          failures,
-          `SEO headings in ${tool.entry.id}/${locale} skip levels: ${failures.join(', ')}`,
-        ).toEqual([]);
-      });
-    });
-  });
-
-  scriptFiles.forEach((file) => {
-    const displayPath = relativePath(file);
-
-    it(`${displayPath} avoids static forced-reflow patterns`, () => {
-      const content = readFileSync(file, 'utf-8');
-      expect(
-        hasDomWriteBeforeGeometryRead(content),
-        `${displayPath} appears to read layout geometry after DOM/style mutations. Split writes and reads across frames or measure before mutating.`,
-      ).toBe(false);
-    });
-  });
-});
+import { describe, expect, it } from 'vitest';
+import { readdirSync, readFileSync } from 'fs';
+import { join, relative } from 'path';
+import { ALL_TOOLS } from '../tools';
+import type { SEOSection, ToolLocaleContent } from '../types';
+
+const srcDir = join(process.cwd(), 'src');
+const toolDir = join(srcDir, 'tool');
+const geometryReads = [
+  'offsetWidth',
+  'offsetHeight',
+  'offsetTop',
+  'offsetLeft',
+  'clientWidth',
+  'clientHeight',
+  'clientTop',
+  'clientLeft',
+  'scrollWidth',
+  'scrollHeight',
+  'scrollTop',
+  'scrollLeft',
+  'getBoundingClientRect',
+  'getClientRects',
+  'computedStyle',
+  'getComputedStyle',
+];
+const domWrites = [
+  '.style.',
+  '.classList.add',
+  '.classList.remove',
+  '.classList.toggle',
+  '.appendChild',
+  '.insertBefore',
+  '.prepend',
+  '.append',
+  '.remove',
+  '.innerHTML',
+  '.textContent',
+  '.setAttribute',
+];
+
+function findFiles(dir: string, extensions: string[]): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...findFiles(fullPath, extensions));
+    else if (extensions.some((extension) => entry.name.endsWith(extension))) files.push(fullPath);
+  }
+  return files;
+}
+
+function relativePath(file: string): string {
+  return relative(process.cwd(), file).replace(/\\/g, '/');
+}
+
+function findFormControls(content: string, tagName: 'input' | 'select'): RegExpMatchArray[] {
+  return Array.from(content.matchAll(new RegExp(`<${tagName}\\b[^>]*>`, 'gi')));
+}
+
+function attrValue(tag: string, attr: string): string | null {
+  const match = tag.match(new RegExp(`\\b${attr}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|\\{([^}]+)\\})`, 'i'));
+  return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+
+function booleanAttr(tag: string, attr: string): boolean {
+  return new RegExp(`\\b${attr}\\b`, 'i').test(tag);
+}
+
+function controlStartIndex(content: string, tag: RegExpMatchArray): number {
+  return tag.index ?? content.indexOf(tag[0]);
+}
+
+function hasWrappingLabel(content: string, tag: RegExpMatchArray): boolean {
+  const index = controlStartIndex(content, tag);
+  const before = content.slice(0, index);
+  const labelOpen = before.lastIndexOf('<label');
+  const labelClose = before.lastIndexOf('</label>');
+  const nextLabelClose = content.indexOf('</label>', index + tag[0].length);
+  return labelOpen > labelClose && nextLabelClose !== -1;
+}
+
+function hasAccessibleName(content: string, tag: RegExpMatchArray): boolean {
+  const source = tag[0];
+  if (attrValue(source, 'aria-label')) return true;
+  if (attrValue(source, 'aria-labelledby')) return true;
+  const id = attrValue(source, 'id');
+  if (id && hasExplicitLabel(content, id)) return true;
+  return hasWrappingLabel(content, tag);
+}
+
+function isVisuallyHiddenFileInput(tag: string): boolean {
+  const type = attrValue(tag, 'type')?.toLowerCase() ?? 'text';
+  const attributes = `${attrValue(tag, 'style') ?? ''} ${attrValue(tag, 'class') ?? ''}`.toLowerCase();
+  const hiddenPatterns = ['display:none', 'display: none', 'file-input'];
+  return type === 'file' && hiddenPatterns.some((pattern) => attributes.includes(pattern));
+}
+
+function isIgnoredInput(tag: string): boolean {
+  const type = attrValue(tag, 'type')?.toLowerCase() ?? 'text';
+  return ['hidden', 'button', 'submit', 'reset'].includes(type) || booleanAttr(tag, 'aria-hidden') || isVisuallyHiddenFileInput(tag);
+}
+
+function controlFailures(content: string, tagName: 'input' | 'select'): string[] {
+  return findFormControls(content, tagName)
+    .filter((tag) => tagName !== 'input' || !isIgnoredInput(tag[0]))
+    .filter((tag) => !hasAccessibleName(content, tag))
+    .map((tag) => tag[0]);
+}
+
+function explicitLabelMessage(tagName: string, path: string, failures: string[]): string {
+  return `${tagName} controls without label, wrapping label, aria-label or aria-labelledby in ${path}:\n${failures.join('\n')}`;
+}
+
+function hasExplicitLabel(content: string, id: string): boolean {
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return (
+    new RegExp(`<label\\b[^>]*\\bfor\\s*=\\s*["']${escapedId}["'][^>]*>`, 'i').test(content)
+    || new RegExp(`<label\\b[^>]*\\bfor\\s*=\\s*\\{${escapedId}\\}[^>]*>`, 'i').test(content)
+  );
+}
+
+function headingLevels(sections: SEOSection[]): number[] {
+  return sections
+    .filter((section) => section.type === 'title')
+    .map((section) => Number('level' in section ? section.level : 0))
+    .filter((level) => Number.isInteger(level) && level > 0);
+}
+
+function findHeadingLevelJumps(levels: number[]): string[] {
+  const failures: string[] = [];
+  levels.forEach((level, index) => {
+    const previous = index === 0 ? 1 : levels[index - 1];
+    if (previous && level > previous + 1) {
+      failures.push(`h${previous} -> h${level}`);
+    }
+  });
+  return failures;
+}
+
+function hasDomWriteBeforeGeometryRead(content: string): boolean {
+  const normalized = content.replace(/\s+/g, ' ');
+  return domWrites.some((write) => {
+    const writeIndex = normalized.indexOf(write);
+    if (writeIndex === -1) return false;
+    return geometryReads.some((read) => normalized.indexOf(read, writeIndex + write.length) !== -1);
+  });
+}
+
+describe('PageSpeed best-practice guards', () => {
+  const astroToolFiles = findFiles(toolDir, ['.astro']);
+  const scriptFiles = findFiles(toolDir, ['.astro', '.ts', '.js']);
+
+  astroToolFiles.forEach((file) => {
+    const displayPath = relativePath(file);
+
+    it(`${displayPath} labels every input with an explicit label`, () => {
+      const content = readFileSync(file, 'utf-8');
+      const failures = controlFailures(content, 'input');
+
+      expect(failures, explicitLabelMessage('Input', displayPath, failures)).toEqual([]);
+    });
+
+    it(`${displayPath} labels every select with an explicit label`, () => {
+      const content = readFileSync(file, 'utf-8');
+      const failures = controlFailures(content, 'select');
+
+      expect(failures, explicitLabelMessage('Select', displayPath, failures)).toEqual([]);
+    });
+  });
+
+  ALL_TOOLS.forEach((tool) => {
+    Object.entries(tool.entry.i18n).forEach(([locale, loader]) => {
+      it(`${tool.entry.id}/${locale} keeps SEO headings sequential`, async () => {
+        if (!loader) return;
+        const content = (await loader()) as ToolLocaleContent;
+        const levels = headingLevels(content.seo);
+        const failures = findHeadingLevelJumps(levels);
+
+        expect(
+          failures,
+          `SEO headings in ${tool.entry.id}/${locale} skip levels: ${failures.join(', ')}`,
+        ).toEqual([]);
+      });
+    });
+  });
+
+  scriptFiles.forEach((file) => {
+    const displayPath = relativePath(file);
+
+    it(`${displayPath} avoids static forced-reflow patterns`, () => {
+      const content = readFileSync(file, 'utf-8');
+      expect(
+        hasDomWriteBeforeGeometryRead(content),
+        `${displayPath} appears to read layout geometry after DOM/style mutations. Split writes and reads across frames or measure before mutating.`,
+      ).toBe(false);
+    });
+  });
+});

package/src/tests/qa-test-helpers.ts

@@ -1,32 +1,32 @@
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
-
-export const repositoryRoot = process.cwd();
-export const toolRoot = join(repositoryRoot, 'src', 'tool');
-
-export function listToolDirectories(): string[] {
-  return readdirSync(toolRoot)
-    .map((name) => join(toolRoot, name))
-    .filter((path) => statSync(path).isDirectory());
-}
-
-export function findFiles(directory: string, extensions: string[]): string[] {
-  const files: string[] = [];
-
-  for (const entry of readdirSync(directory, { withFileTypes: true })) {
-    const path = join(directory, entry.name);
-    if (entry.isDirectory()) files.push(...findFiles(path, extensions));
-    else if (extensions.some((extension) => entry.name.endsWith(extension))) files.push(path);
-  }
-
-  return files;
-}
-
-export function read(path: string): string {
-  return readFileSync(path, 'utf8');
-}
-
-export function displayPath(path: string): string {
-  return relative(repositoryRoot, path).replace(/\\/g, '/');
-}
-
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export const repositoryRoot = process.cwd();
+export const toolRoot = join(repositoryRoot, 'src', 'tool');
+
+export function listToolDirectories(): string[] {
+  return readdirSync(toolRoot)
+    .map((name) => join(toolRoot, name))
+    .filter((path) => statSync(path).isDirectory());
+}
+
+export function findFiles(directory: string, extensions: string[]): string[] {
+  const files: string[] = [];
+
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...findFiles(path, extensions));
+    else if (extensions.some((extension) => entry.name.endsWith(extension))) files.push(path);
+  }
+
+  return files;
+}
+
+export function read(path: string): string {
+  return readFileSync(path, 'utf8');
+}
+
+export function displayPath(path: string): string {
+  return relative(repositoryRoot, path).replace(/\\/g, '/');
+}
+

package/src/tests/qa_bibliography_links.test.ts

@@ -1,41 +1,41 @@
-import { describe, expect, it } from 'vitest';
-import { ALL_TOOLS } from '../tools';
-import type { ToolLocaleContent } from '../types';
-
-interface LinkFailure {
-  tool: string;
-  message: string;
-}
-
-function inspectEntry(tool: string, entry: { url: string }, seen: Set<string>): LinkFailure[] {
-  let url: URL;
-  try {
-    url = new URL(entry.url);
-  } catch {
-    return [{ tool, message: `invalid URL: ${entry.url}` }];
-  }
-
-  const failures: LinkFailure[] = [];
-  if (url.protocol !== 'https:') failures.push({ tool, message: `non-HTTPS URL: ${entry.url}` });
-  if (url.pathname === '/' && !url.search && !url.hash) failures.push({ tool, message: `generic homepage, cite the exact document: ${entry.url}` });
-  if (seen.has(url.href)) failures.push({ tool, message: `duplicate source URL: ${entry.url}` });
-  seen.add(url.href);
-  return failures;
-}
-
-async function inspectTool(tool: (typeof ALL_TOOLS)[number]): Promise<LinkFailure[]> {
-  const loader = tool.entry.i18n.en;
-  if (!loader) return [{ tool: tool.entry.id, message: 'English locale loader is missing' }];
-  const content = await loader() as ToolLocaleContent;
-  const seen = new Set<string>();
-  return (content.bibliography ?? []).flatMap((entry) => inspectEntry(tool.entry.id, entry, seen));
-}
-
-describe('QA: bibliography links are specific and usable', () => {
-  it('uses unique HTTPS links to exact source pages instead of generic homepages', async () => {
-    const failures = (await Promise.all(ALL_TOOLS.map(inspectTool))).flat();
-
-    const messages = failures.map(({ tool, message }) => `${tool}: ${message}`);
-    expect(messages, `Bibliography hygiene failures:\n${messages.join('\n')}`).toEqual([]);
-  });
-});
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+interface LinkFailure {
+  tool: string;
+  message: string;
+}
+
+function inspectEntry(tool: string, entry: { url: string }, seen: Set<string>): LinkFailure[] {
+  let url: URL;
+  try {
+    url = new URL(entry.url);
+  } catch {
+    return [{ tool, message: `invalid URL: ${entry.url}` }];
+  }
+
+  const failures: LinkFailure[] = [];
+  if (url.protocol !== 'https:') failures.push({ tool, message: `non-HTTPS URL: ${entry.url}` });
+  if (url.pathname === '/' && !url.search && !url.hash) failures.push({ tool, message: `generic homepage, cite the exact document: ${entry.url}` });
+  if (seen.has(url.href)) failures.push({ tool, message: `duplicate source URL: ${entry.url}` });
+  seen.add(url.href);
+  return failures;
+}
+
+async function inspectTool(tool: (typeof ALL_TOOLS)[number]): Promise<LinkFailure[]> {
+  const loader = tool.entry.i18n.en;
+  if (!loader) return [{ tool: tool.entry.id, message: 'English locale loader is missing' }];
+  const content = await loader() as ToolLocaleContent;
+  const seen = new Set<string>();
+  return (content.bibliography ?? []).flatMap((entry) => inspectEntry(tool.entry.id, entry, seen));
+}
+
+describe('QA: bibliography links are specific and usable', () => {
+  it('uses unique HTTPS links to exact source pages instead of generic homepages', async () => {
+    const failures = (await Promise.all(ALL_TOOLS.map(inspectTool))).flat();
+
+    const messages = failures.map(({ tool, message }) => `${tool}: ${message}`);
+    expect(messages, `Bibliography hygiene failures:\n${messages.join('\n')}`).toEqual([]);
+  });
+});