@jjlmoya/utils-tabletop 1.34.0 → 1.37.0

package/src/mfe/routes.ts

@@ -0,0 +1,50 @@
+import {
+    getCategoryNamespace,
+    getCategoryPath as getSharedCategoryPath,
+    getUtilitiesPath as getSharedUtilitiesPath,
+    getUtilityNamespace,
+    getUtilityPath as getSharedUtilityPath,
+    type UtilityLocale,
+} from "@jjlmoya/utils-shared/routing";
+
+export type { UtilityLocale };
+export { getCategoryNamespace, getUtilityNamespace };
+
+export const INTERNAL_LOCALES = [
+    "en", "fr", "de", "it", "pt", "nl", "sv", "pl", "id", "tr", "ru", "ja", "ko", "zh",
+] as const satisfies readonly UtilityLocale[];
+
+const getDevelopmentPath = (url: string): string => {
+    if (!import.meta.env.DEV) return url;
+    try {
+        return new URL(url, "http://localhost:4324").pathname;
+    } catch {
+        return url;
+    }
+};
+
+export const getUtilitiesPath = (locale: UtilityLocale): string =>
+    getDevelopmentPath(getSharedUtilitiesPath(locale));
+
+export const getCategoryPath = (locale: UtilityLocale, categorySlug: string): string =>
+    getDevelopmentPath(getSharedCategoryPath(locale, categorySlug));
+
+export const getUtilityPath = (
+    locale: UtilityLocale,
+    categorySlug: string,
+    toolSlug: string,
+): string => getDevelopmentPath(getSharedUtilityPath(locale, categorySlug, toolSlug));
+
+export const getCategoryRoute = (locale: UtilityLocale, categorySlug: string): string =>
+    getCategoryPath(locale, categorySlug);
+
+export const getUtilityRoute = (locale: UtilityLocale, categorySlug: string, toolSlug: string): string =>
+    getUtilityPath(locale, categorySlug, toolSlug);
+
+export const getUtilityIndexRoute = (locale: UtilityLocale): string => getUtilitiesPath(locale);
+
+export const getInternalCategoryRoute = (locale: Exclude<UtilityLocale, "es">, categorySlug: string): string =>
+    getCategoryPath(locale, categorySlug);
+
+export const getInternalUtilityRoute = (locale: Exclude<UtilityLocale, "es">, categorySlug: string, toolSlug: string): string =>
+    getUtilityPath(locale, categorySlug, toolSlug);

package/src/pages/[locale]/[utilities]/[categories]/[category]/[slug].astro

@@ -0,0 +1,100 @@
+---
+import ProductionUtilityPage from "../../../../../layouts/ProductionUtilityPage.astro";
+import { ALL_TOOLS, tabletopCategory } from "../../../../../index";
+import { LANGUAGE_CODES, type Language } from "../../../../../i18n/languages";
+import type { CategoryLocaleContent, ToolLocaleContent } from "../../../../../types";
+import type { AstroComponentFactory } from "astro/runtime/server/index.js";
+import { getCategoryNamespace, getCategoryPath, getUtilityNamespace, getUtilityPath } from "../../../../../mfe/routes";
+import { getUtilityOgImage } from "../../../../../mfe/assets";
+
+type Loader<T> = () => Promise<{ default: T }>;
+type LoadedTool = ToolLocaleContent;
+
+export async function getStaticPaths() {
+    const paths = [];
+    for (const { entry, Component: componentLoader, SEOComponent: seoLoader, BibliographyComponent: bibliographyLoader } of ALL_TOOLS) {
+        const contents = Object.fromEntries(await Promise.all(LANGUAGE_CODES.map(async (language) => {
+            const loader = entry.i18n[language] ?? entry.i18n.en;
+            if (!loader) throw new Error(`Missing ${language} locale for ${entry.id}`);
+            return [language, await loader()];
+        }))) as Record<Language, LoadedTool>;
+        const categories = Object.fromEntries(await Promise.all(LANGUAGE_CODES.map(async (language) => [
+            language,
+            await tabletopCategory.i18n[language]!(),
+        ]))) as Record<Language, CategoryLocaleContent>;
+        const { default: Component } = await (componentLoader as Loader<AstroComponentFactory>)();
+        const { default: SEOComponent } = await (seoLoader as Loader<AstroComponentFactory>)();
+        const { default: BibliographyComponent } = await (bibliographyLoader as Loader<AstroComponentFactory>)();
+        for (const locale of LANGUAGE_CODES.filter((candidate) => candidate !== "es")) {
+            const content = contents[locale];
+            const category = categories[locale];
+            paths.push({
+                params: {
+                    locale,
+                    utilities: getUtilityNamespace(locale),
+                    categories: getCategoryNamespace(locale),
+                    category: category.slug,
+                    slug: content.slug,
+                },
+                props: {
+                    locale,
+                    content,
+                    englishSlug: contents.en.slug,
+                    category,
+                    categorySlug: category.slug,
+                    Component,
+                    SEOComponent,
+                    BibliographyComponent,
+                    alternates: LANGUAGE_CODES.map((language) => ({
+                        language,
+                        url: getUtilityPath(language, categories[language].slug, contents[language].slug),
+                    })),
+                    image: getUtilityOgImage(contents.en.slug),
+                },
+            });
+        }
+    }
+    return paths;
+}
+
+const { locale, content, englishSlug, category, categorySlug, Component, SEOComponent, BibliographyComponent, relatedTools, alternates, image } = Astro.props as {
+    locale: Exclude<Language, "es">;
+    content: LoadedTool;
+    englishSlug: string;
+    category: CategoryLocaleContent;
+    categorySlug: string;
+    Component: AstroComponentFactory;
+    SEOComponent: AstroComponentFactory;
+    BibliographyComponent: AstroComponentFactory;
+    relatedTools?: { title: string; description: string; href: string }[];
+    alternates: { language: Language; url: string }[];
+    image?: string;
+};
+const related = relatedTools ?? (await Promise.all(ALL_TOOLS.map(async ({ entry: relatedEntry }) => {
+    const loader = relatedEntry.i18n[locale] ?? relatedEntry.i18n.en;
+    if (!loader) return null;
+    const relatedContent = await loader();
+    if (relatedContent.slug === content.slug) return null;
+    return {
+        icon: relatedEntry.icons.fg,
+        title: relatedContent.title,
+        description: relatedContent.description,
+        href: getUtilityPath(locale, categorySlug, relatedContent.slug),
+    };
+}))).filter((tool): tool is { icon: string; title: string; description: string; href: string } => tool !== null);
+---
+
+<ProductionUtilityPage
+    {locale}
+    {content}
+    {englishSlug}
+    categoryTitle={category.title}
+    {categorySlug}
+    categoryHref={getCategoryPath(locale, categorySlug)}
+    relatedTools={related}
+    {Component}
+    {SEOComponent}
+    {BibliographyComponent}
+    {alternates}
+    {image}
+/> 

package/src/pages/[locale]/[utilities]/[categories]/[category].astro

@@ -0,0 +1,44 @@
+---
+import ProductionCategoryPage from "../../../../layouts/ProductionCategoryPage.astro";
+import { ALL_ENTRIES, tabletopCategory } from "../../../../index";
+import { LANGUAGE_CODES, type Language } from "../../../../i18n/languages";
+import { getCategoryNamespace, getCategoryPath, getUtilityNamespace, getUtilityPath } from "../../../../mfe/routes";
+import { CATEGORY_OG_IMAGE } from "../../../../mfe/assets";
+
+export async function getStaticPaths() {
+    const categories = Object.fromEntries(await Promise.all(
+        LANGUAGE_CODES.map(async (language) => [language, await tabletopCategory.i18n[language]!()]),
+    ));
+    return LANGUAGE_CODES.filter((language) => language !== "es").map((locale) => {
+        const category = categories[locale]!;
+        const alternates = LANGUAGE_CODES.map((language) => ({
+            language,
+            url: getCategoryPath(language, categories[language]!.slug),
+        }));
+        return {
+            params: { locale, utilities: getUtilityNamespace(locale), categories: getCategoryNamespace(locale), category: category.slug },
+            props: { locale, category, alternates },
+        };
+    });
+}
+
+const { locale, category, alternates } = Astro.props as {
+    locale: Exclude<Language, "es">;
+    category: Awaited<ReturnType<NonNullable<(typeof tabletopCategory.i18n)[Language]>>>;
+    alternates: { language: Language; url: string }[];
+};
+const tools = await Promise.all(ALL_ENTRIES.map(async (entry) => {
+    const loader = entry.i18n[locale] ?? entry.i18n.en;
+    if (!loader) throw new Error(`Missing ${locale} locale for ${entry.id}`);
+    const content = await loader();
+    return {
+        id: entry.id,
+        icon: entry.icons.fg,
+        title: content.title,
+        description: content.description,
+        href: getUtilityPath(locale, category.slug, content.slug),
+    };
+}));
+---
+
+<ProductionCategoryPage locale={locale} {category} {tools} {alternates} image={CATEGORY_OG_IMAGE} />

package/src/pages/index.astro

@@ -1,4 +1,4 @@
 ---
 ---
-<meta http-equiv="refresh" content="0;url=/es" />
+<meta http-equiv="refresh" content="0;url=/utilidades/categorias/juegos-de-mesa/" />
 

package/src/pages/mfe-sitemaps/[locale]/[vertical]/sitemap.xml.ts

@@ -0,0 +1,75 @@
+import type { APIRoute } from "astro";
+import { tabletopCategory } from "../../../../category";
+import { ALL_ENTRIES } from "../../../../entries";
+import { LANGUAGE_CODES, type Language } from "../../../../i18n/languages";
+import { getCategoryPath, getUtilityPath } from "../../../../mfe/routes";
+
+const GAMEBOB_URL = "https://www.gamebob.dev";
+const JJLMOYA_URL = "https://www.jjlmoya.es";
+
+type LocalizedEntry = {
+    i18n: Partial<Record<Language, () => Promise<{ slug: string }>>>;
+};
+
+const absoluteUrl = (locale: Language, path: string): string =>
+    path.startsWith("http") ? path : `${locale === "es" ? JJLMOYA_URL : GAMEBOB_URL}${path}`;
+
+const escapeXml = (value: string): string => value
+    .replaceAll("&", "&amp;")
+    .replaceAll("\"", "&quot;")
+    .replaceAll("'", "&apos;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+const getContent = async (entry: LocalizedEntry, locale: Language): Promise<{ slug: string }> => {
+    const loader = entry.i18n[locale] ?? entry.i18n.en;
+    if (!loader) throw new Error(`Missing ${locale} and English fallback`);
+    return loader();
+};
+
+export const prerender = true;
+
+export function getStaticPaths() {
+    return LANGUAGE_CODES.map((locale) => ({
+        params: { locale, vertical: "tabletop" },
+        props: { locale },
+    }));
+}
+
+const buildUrlEntry = async (locale: Language, path: string, index: number): Promise<string> => {
+    const links = await Promise.all(LANGUAGE_CODES.map(async (alternateLocale) => {
+        const alternateCategory = await getContent(tabletopCategory, alternateLocale);
+        const alternateContent = index === 0 ? null : await getContent(ALL_ENTRIES[index - 1], alternateLocale);
+        const alternatePath = alternateContent
+            ? getUtilityPath(alternateLocale, alternateCategory.slug, alternateContent.slug)
+            : getCategoryPath(alternateLocale, alternateCategory.slug);
+        return `    <xhtml:link rel="alternate" hreflang="${alternateLocale}" href="${escapeXml(absoluteUrl(alternateLocale, alternatePath))}"/>`;
+    }));
+    return [
+        "  <url>",
+        `    <loc>${escapeXml(absoluteUrl(locale, path))}</loc>`,
+        ...links,
+        `    <changefreq>${index === 0 ? "weekly" : "monthly"}</changefreq>`,
+        `    <priority>${index === 0 ? "0.7" : "0.6"}</priority>`,
+        "  </url>",
+    ].join("\n");
+};
+
+export const GET: APIRoute = async ({ props }) => {
+    const locale = props.locale as Language;
+    const category = await getContent(tabletopCategory, locale);
+    const contents = await Promise.all(ALL_ENTRIES.map((entry) => getContent(entry, locale)));
+    const paths = [
+        getCategoryPath(locale, category.slug),
+        ...contents.map((content) => getUtilityPath(locale, category.slug, content.slug)),
+    ];
+    const urls = await Promise.all(paths.map((path, index) => buildUrlEntry(locale, path, index)));
+
+    const xml = `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">\n${urls.join("\n")}\n</urlset>`;
+    return new Response(xml, {
+        headers: {
+            "Content-Type": "application/xml; charset=utf-8",
+            "Cache-Control": "public, max-age=3600, s-maxage=3600, must-revalidate",
+        },
+    });
+};

package/src/pages/utilidades/[slug].astro

@@ -0,0 +1,90 @@
+---
+import ProductionUtilityPage from "../../layouts/ProductionUtilityPage.astro";
+import { ALL_TOOLS, tabletopCategory } from "../../index";
+import { LANGUAGE_CODES, type Language } from "../../i18n/languages";
+import type { CategoryLocaleContent, ToolLocaleContent } from "../../types";
+import type { AstroComponentFactory } from "astro/runtime/server/index.js";
+import { getCategoryPath, getUtilityPath } from "../../mfe/routes";
+import { getUtilityOgImage } from "../../mfe/assets";
+
+type Loader<T> = () => Promise<{ default: T }>;
+type LoadedTool = ToolLocaleContent;
+
+export async function getStaticPaths() {
+    const category = await tabletopCategory.i18n.es!();
+    const categories = Object.fromEntries(await Promise.all(LANGUAGE_CODES.map(async (language) => [
+        language,
+        await tabletopCategory.i18n[language]!(),
+    ]))) as Record<Language, CategoryLocaleContent>;
+    const paths = [];
+    for (const { entry, Component: componentLoader, SEOComponent: seoLoader, BibliographyComponent: bibliographyLoader } of ALL_TOOLS) {
+        const contents = Object.fromEntries(await Promise.all(LANGUAGE_CODES.map(async (language) => {
+            const loader = entry.i18n[language] ?? entry.i18n.en;
+            if (!loader) throw new Error(`Missing ${language} locale for ${entry.id}`);
+            return [language, await loader()];
+        }))) as Record<Language, LoadedTool>;
+        const { default: Component } = await (componentLoader as Loader<AstroComponentFactory>)();
+        const { default: SEOComponent } = await (seoLoader as Loader<AstroComponentFactory>)();
+        const { default: BibliographyComponent } = await (bibliographyLoader as Loader<AstroComponentFactory>)();
+        paths.push({
+            params: { slug: contents.es.slug },
+            props: {
+                locale: "es",
+                content: contents.es,
+                englishSlug: contents.en.slug,
+                category,
+                categorySlug: category.slug,
+                Component,
+                SEOComponent,
+                BibliographyComponent,
+                alternates: LANGUAGE_CODES.map((language) => ({
+                    language,
+                    url: getUtilityPath(language, categories[language].slug, contents[language].slug),
+                })),
+                image: getUtilityOgImage(contents.en.slug),
+            },
+        });
+    }
+    return paths;
+}
+
+const { locale, content, englishSlug, category, categorySlug, Component, SEOComponent, BibliographyComponent, alternates, image } = Astro.props as {
+    locale: "es";
+    content: LoadedTool;
+    englishSlug: string;
+    category: CategoryLocaleContent;
+    categorySlug: string;
+    Component: AstroComponentFactory;
+    SEOComponent: AstroComponentFactory;
+    BibliographyComponent: AstroComponentFactory;
+    alternates: { language: Language; url: string }[];
+    image?: string;
+};
+const relatedTools = (await Promise.all(ALL_TOOLS.map(async ({ entry: relatedEntry }) => {
+    const loader = relatedEntry.i18n.es ?? relatedEntry.i18n.en;
+    if (!loader) return null;
+    const relatedContent = await loader();
+    if (relatedContent.slug === content.slug) return null;
+    return {
+        icon: relatedEntry.icons.fg,
+        title: relatedContent.title,
+        description: relatedContent.description,
+        href: getUtilityPath("es", categorySlug, relatedContent.slug),
+    };
+}))).filter((tool): tool is { icon: string; title: string; description: string; href: string } => tool !== null);
+---
+
+<ProductionUtilityPage
+    {locale}
+    {content}
+    {englishSlug}
+    categoryTitle={category.title}
+    {categorySlug}
+    categoryHref={getCategoryPath(locale, categorySlug)}
+    {relatedTools}
+    {Component}
+    {SEOComponent}
+    {BibliographyComponent}
+    {alternates}
+    {image}
+/> 

package/src/pages/utilidades/categorias/[category].astro

@@ -0,0 +1,38 @@
+---
+import ProductionCategoryPage from "../../../layouts/ProductionCategoryPage.astro";
+import { ALL_ENTRIES, tabletopCategory } from "../../../index";
+import { LANGUAGE_CODES, type Language } from "../../../i18n/languages";
+import { getCategoryPath, getUtilityPath } from "../../../mfe/routes";
+import { CATEGORY_OG_IMAGE } from "../../../mfe/assets";
+
+export async function getStaticPaths() {
+    const categories = Object.fromEntries(await Promise.all(
+        LANGUAGE_CODES.map(async (language) => [language, await tabletopCategory.i18n[language]!()]),
+    ));
+    const category = categories.es!;
+    const alternates = LANGUAGE_CODES.map((language) => ({
+        language,
+        url: getCategoryPath(language, categories[language]!.slug),
+    }));
+    return [{ params: { category: category.slug }, props: { category, alternates } }];
+}
+
+const { category, alternates } = Astro.props as {
+    category: Awaited<ReturnType<NonNullable<(typeof tabletopCategory.i18n)[Language]>>>;
+    alternates: { language: Language; url: string }[];
+};
+const tools = await Promise.all(ALL_ENTRIES.map(async (entry) => {
+    const loader = entry.i18n.es ?? entry.i18n.en;
+    if (!loader) throw new Error(`Missing Spanish locale for ${entry.id}`);
+    const content = await loader();
+    return {
+        id: entry.id,
+        icon: entry.icons.fg,
+        title: content.title,
+        description: content.description,
+        href: getUtilityPath("es", category.slug, content.slug),
+    };
+}));
+---
+
+<ProductionCategoryPage locale="es" {category} {tools} {alternates} image={CATEGORY_OG_IMAGE} />

package/src/tests/category_ui.test.ts

@@ -0,0 +1,16 @@
+import { UTILITY_LOCALES } from '@jjlmoya/utils-shared/routing';
+import { describe, expect, it } from 'vitest';
+import { CATEGORY_UI, getCategoryUi } from '../mfe/category-ui';
+
+describe('category UI translations', () => {
+  it('provides a translated use-tool CTA for every supported locale', () => {
+    for (const locale of UTILITY_LOCALES) {
+      expect(getCategoryUi(locale).useTool.trim()).not.toBe('');
+      expect(getCategoryUi(locale).openTool.trim()).not.toBe('');
+    }
+
+    expect(Object.keys(CATEGORY_UI).sort()).toEqual([...UTILITY_LOCALES].sort());
+    expect(UTILITY_LOCALES.filter((locale) => locale !== 'en').every((locale) => getCategoryUi(locale).useTool !== 'Use tool')).toBe(true);
+    expect(UTILITY_LOCALES.filter((locale) => locale !== 'en').every((locale) => getCategoryUi(locale).openTool !== 'Open tool')).toBe(true);
+  });
+});

package/src/tests/locale_completeness.test.ts

@@ -18,6 +18,6 @@ describe('Locale Completeness Validation', () => {
   });
 
   it('all tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(16);
+    expect(ALL_TOOLS.length).toBe(17);
   });
 });

package/src/tests/mfe_assets_contract.test.ts

@@ -0,0 +1,44 @@
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import {
+  CATEGORY_OG_IMAGE,
+  getUtilityCssPath,
+  getUtilityOgImage,
+  TABLETOP_ASSET_VERSION,
+} from '../mfe/assets';
+
+const assetRoot = join(process.cwd(), 'public', '_utilities', 'tabletop', 'images');
+
+describe('MFE asset contract', () => {
+  it('keeps one English OG asset per category and tool', async () => {
+    const expectedSlugs = new Set(['tabletop']);
+
+    for (const { entry } of ALL_TOOLS) {
+      const loader = entry.i18n.en;
+      if (!loader) throw new Error(`Missing English locale for ${entry.id}`);
+      expectedSlugs.add((await loader()).slug);
+    }
+
+    const actualSlugs = new Set(
+      readdirSync(assetRoot)
+        .filter((filename) => filename.endsWith('.webp'))
+        .map((filename) => filename.slice(0, -'.webp'.length)),
+    );
+
+    expect(actualSlugs).toEqual(expectedSlugs);
+    for (const slug of expectedSlugs) {
+      expect(existsSync(join(assetRoot, `${slug}.webp`))).toBe(true);
+      expect(getUtilityOgImage(slug)).toBe(
+        `/_utilities/tabletop/images/${slug}.webp?version=${TABLETOP_ASSET_VERSION}`,
+      );
+      expect(getUtilityCssPath(slug)).toBe(
+        `/_utilities/tabletop/styles/${slug}.css?version=${TABLETOP_ASSET_VERSION}`,
+      );
+    }
+    expect(CATEGORY_OG_IMAGE).toBe(
+      `/_utilities/tabletop/images/tabletop.webp?version=${TABLETOP_ASSET_VERSION}`,
+    );
+  });
+});

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

@@ -0,0 +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, '/');
+}
+

package/src/tests/qa_bibliography_links.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+interface LinkFailure {
+  tool: string;
+  message: string;
+}
+
+function parseUrl(tool: string, rawUrl: string, failures: LinkFailure[]): URL | undefined {
+  try {
+    return new URL(rawUrl);
+  } catch {
+    failures.push({ tool, message: `invalid URL: ${rawUrl}` });
+    return undefined;
+  }
+}
+
+function checkUrl(tool: string, url: URL, seen: Set<string>, failures: LinkFailure[]): void {
+  if (url.protocol !== 'https:') failures.push({ tool, message: `non-HTTPS URL: ${url.href}` });
+  if (url.pathname === '/' && !url.search && !url.hash) failures.push({ tool, message: `generic homepage, cite the exact document: ${url.href}` });
+  if (seen.has(url.href)) failures.push({ tool, message: `duplicate source URL: ${url.href}` });
+  seen.add(url.href);
+}
+
+async function checkTool(tool: (typeof ALL_TOOLS)[number]): Promise<LinkFailure[]> {
+  const failures: 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>();
+  for (const entry of content.bibliography ?? []) {
+    const url = parseUrl(tool.entry.id, entry.url, failures);
+    if (url) checkUrl(tool.entry.id, url, seen, failures);
+  }
+  return failures;
+}
+
+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(checkTool))).flat();
+    const messages = failures.map(({ tool, message }) => `${tool}: ${message}`);
+    expect(messages, `Bibliography hygiene failures:\n${messages.join('\n')}`).toEqual([]);
+  });
+});

package/src/tests/qa_claim_evidence.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { displayPath, listToolDirectories, read } from './qa-test-helpers';
+
+const evidenceClaims = [
+  /\bofficial algorithm\b/i,
+  /\balgoritmo oficial\b/i,
+  /\b(?:records|data|rates|tables) updated(?:\s+(?:to|through)\s+20\d{2})?\b/i,
+  /\b(?:registros|datos|tasas|tablas) actualizad[oa]s?(?:\s+(?:a|hasta)\s+20\d{2})?\b/i,
+  /\b(?:validated|verified) (?:method|algorithm|calculation)\b/i,
+  /\b(?:método|algoritmo|cálculo) (?:validado|verificado)\b/i,
+  /\b(?:guarantees|ensures)\b/i,
+  /\bgarantiza\b/i,
+  /\bofficial (?:data|rate|calculation)\b/i,
+  /\b(?:datos|tasa|cálculo) oficial(?:es)?\b/i,
+];
+
+const requiredEvidenceFields = [
+  'reviewedAt',
+  'methodology',
+  'sources',
+  'referenceCases',
+  'limitations',
+];
+
+describe('QA: strong factual claims are traceable', () => {
+  it('requires machine-readable validation evidence beside tools making strong claims', () => {
+    const failures: string[] = [];
+
+    for (const directory of listToolDirectories()) {
+      const localePaths = ['en', 'es']
+        .map((locale) => join(directory, 'i18n', `${locale}.ts`))
+        .filter(existsSync);
+      const claims = localePaths.flatMap((path) => {
+        const source = read(path);
+        return evidenceClaims
+          .filter((pattern) => pattern.test(source))
+          .map((pattern) => `${displayPath(path)} matches ${pattern.source}`);
+      });
+      if (claims.length === 0) continue;
+
+      const evidencePath = join(directory, 'validation.ts');
+      if (!existsSync(evidencePath)) {
+        failures.push(`${displayPath(evidencePath)} missing; claims: ${claims.join(' | ')}`);
+        continue;
+      }
+
+      const evidence = read(evidencePath);
+      const missingFields = requiredEvidenceFields.filter(
+        (field) => !new RegExp(`\\b${field}\\s*:`).test(evidence),
+      );
+      if (missingFields.length > 0) {
+        failures.push(`${displayPath(evidencePath)} missing fields: ${missingFields.join(', ')}`);
+      }
+    }
+
+    expect(
+      failures,
+      [
+        'Claims such as official, validated, guaranteed or updated need inspectable evidence.',
+        'Add validation.ts with reviewedAt, methodology, sources, referenceCases and limitations,',
+        'or weaken/remove the unsupported claim.',
+        ...failures,
+      ].join('\n'),
+    ).toEqual([]);
+  });
+});
+