@jjlmoya/utils-tabletop 1.34.0 → 1.37.0

package/src/tests/qa_logic_reference_coverage.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { basename, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  displayPath,
+  findFiles,
+  listToolDirectories,
+  read,
+  repositoryRoot,
+} from './qa-test-helpers';
+
+function hasDedicatedLogicTest(toolDirectory: string): boolean {
+  const localCandidates = [
+    join(toolDirectory, 'logic.test.ts'),
+    join(toolDirectory, 'logic.spec.ts'),
+    join(toolDirectory, '__tests__', 'logic.test.ts'),
+    join(toolDirectory, '__tests__', 'logic.spec.ts'),
+  ];
+  if (localCandidates.some(existsSync)) return true;
+
+  const toolName = basename(toolDirectory);
+  const centralTests = findFiles(join(repositoryRoot, 'src', 'tests'), ['.test.ts', '.spec.ts']);
+  return centralTests.some((testPath) => {
+    const source = read(testPath).replace(/\\/g, '/');
+    return source.includes(`/tool/${toolName}/logic`) || source.includes(`../tool/${toolName}/logic`);
+  });
+}
+
+describe('QA: calculation logic has reference tests', () => {
+  it('gives every public calculator logic module its own behavioral test suite', () => {
+    const failures = listToolDirectories()
+      .filter((directory) => existsSync(join(directory, 'logic.ts')))
+      .filter((directory) => !hasDedicatedLogicTest(directory))
+      .map((directory) => `${displayPath(join(directory, 'logic.ts'))} -> no test imports this module`);
+
+    expect(
+      failures,
+      [
+        'Add behavioral tests through each logic module public API.',
+        'At minimum cover a documented reference case, boundaries, invalid input and invariants.',
+        ...failures,
+      ].join('\n'),
+    ).toEqual([]);
+  });
+});
+

package/src/tests/qa_runtime_i18n.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { basename, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  displayPath,
+  findFiles,
+  listToolDirectories,
+  read,
+  repositoryRoot,
+} from './qa-test-helpers';
+
+interface VisibleLiteral {
+  line: number;
+  value: string;
+}
+
+const domTextAssignment = /\.(?:innerText|textContent|innerHTML)\s*=/;
+const quotedLiteral = /(['"`])((?:\\.|(?!\1).)*)\1/g;
+
+function visibleWords(value: string): string {
+  return value
+    .replace(/\$\{[^}]*\}/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-z]+;/gi, ' ')
+    .replace(/[\d\p{P}\p{S}_]+/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function isTechnicalLiteral(value: string): boolean {
+  return ['.', '#', '['].some((prefix) => value.startsWith(prefix))
+    || /^data-[a-z0-9-]+$/i.test(value);
+}
+
+function hardcodedVisibleLiterals(source: string): VisibleLiteral[] {
+  const failures: VisibleLiteral[] = [];
+
+  source.split(/\r?\n/).forEach((line, index) => {
+    if (!domTextAssignment.test(line)) return;
+
+    const assignment = line.slice(line.search(domTextAssignment));
+    for (const match of assignment.matchAll(quotedLiteral)) {
+      const value = match[2];
+      if (!value || isTechnicalLiteral(value)) continue;
+      const words = visibleWords(value);
+      if (words && /\p{L}/u.test(words)) {
+        failures.push({ line: index + 1, value });
+      }
+    }
+  });
+
+  return failures;
+}
+
+function runtimeSources(toolDirectory: string): string {
+  return findFiles(toolDirectory, ['.astro', '.ts', '.js'])
+    .filter((path) => !path.includes(`${join(toolDirectory, 'i18n')}`))
+    .filter((path) => basename(path) !== 'ui.ts')
+    .map(read)
+    .join('\n');
+}
+
+describe('QA: runtime copy is localized', () => {
+  const componentFiles = findFiles(join(repositoryRoot, 'src', 'tool'), ['.astro']);
+
+  it('does not write user-facing string literals directly into the DOM', () => {
+    const failures = componentFiles.flatMap((path) =>
+      hardcodedVisibleLiterals(read(path)).map(
+        ({ line, value }) => `${displayPath(path)}:${line} -> ${JSON.stringify(value)}`,
+      ),
+    );
+
+    expect(
+      failures,
+      `Move visible browser copy to the tool UI locale contract:\n${failures.join('\n')}`,
+    ).toEqual([]);
+  });
+
+  it('uses every string declared by each UI locale contract', () => {
+    const failures: string[] = [];
+
+    for (const directory of listToolDirectories()) {
+      const uiPath = join(directory, 'ui.ts');
+      if (!existsSync(uiPath)) continue;
+
+      const keys = Array.from(read(uiPath).matchAll(/^\s*(\w+)\??:\s*string\s*;/gm), (match) => match[1]);
+      const runtime = runtimeSources(directory);
+      const unused = keys.filter((key) => !new RegExp(`\\b${key}\\b`).test(runtime));
+
+      if (unused.length > 0) {
+        failures.push(`${displayPath(uiPath)} -> unused: ${unused.join(', ')}`);
+      }
+    }
+
+    expect(
+      failures,
+      `Unused locale keys are dead copy or may mean the browser bypasses translations:\n${failures.join('\n')}`,
+    ).toEqual([]);
+  });
+});

package/src/tests/registry_contract.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import { ALL_ENTRIES } from '../entries';
+import { ALL_TOOLS } from '../tools';
+import type { ToolDefinition } from '../types';
+
+function isToolDefinition(value: unknown): value is ToolDefinition {
+  if (!value || typeof value !== 'object') return false;
+
+  const candidate = value as Record<string, unknown>;
+  return Boolean(
+    candidate.entry &&
+      typeof candidate.entry === 'object' &&
+      typeof candidate.Component === 'function' &&
+      typeof candidate.SEOComponent === 'function' &&
+      typeof candidate.BibliographyComponent === 'function',
+  );
+}
+
+const toolRoot = join(process.cwd(), 'src', 'tool');
+const toolDirectories = readdirSync(toolRoot, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && existsSync(join(toolRoot, entry.name, 'index.ts')))
+  .map((entry) => entry.name)
+  .sort();
+
+describe('Library registry contract', () => {
+  it('keeps ALL_ENTRIES and ALL_TOOLS synchronized by id', () => {
+    const entryIds = ALL_ENTRIES.map((entry) => entry.id);
+    const toolIds = ALL_TOOLS.map((tool) => tool.entry.id);
+
+    expect(new Set(entryIds).size).toBe(entryIds.length);
+    expect(new Set(toolIds).size).toBe(toolIds.length);
+    expect([...toolIds].sort()).toEqual([...entryIds].sort());
+  });
+
+  it('registers every tool runtime index in both public registries', async () => {
+    const failures: string[] = [];
+
+    for (const directory of toolDirectories) {
+      const runtimeModule = await import(
+        pathToFileURL(join(toolRoot, directory, 'index.ts')).href,
+      );
+      const definitions = [...new Set(Object.values(runtimeModule).filter(isToolDefinition))];
+
+      if (definitions.length !== 1) {
+        failures.push(`${directory}: expected exactly one ToolDefinition export, found ${definitions.length}`);
+        continue;
+      }
+
+      const [definition] = definitions;
+      if (!definition) {
+        failures.push(`${directory}: runtime definition is undefined`);
+        continue;
+      }
+      if (!ALL_TOOLS.some((tool) => tool.entry.id === definition.entry.id)) {
+        failures.push(`${directory}: runtime definition is missing from ALL_TOOLS`);
+      }
+      if (!ALL_ENTRIES.some((entry) => entry.id === definition.entry.id)) {
+        failures.push(`${directory}: runtime entry is missing from ALL_ENTRIES`);
+      }
+    }
+
+    expect(failures).toEqual([]);
+  });
+});

package/src/tests/routing_contract.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import {
+  UTILITY_LOCALES,
+  getCategoryNamespace,
+  getCategoryPath,
+  getUtilitiesPath,
+  getUtilityPath,
+  getUtilityNamespace,
+} from '@jjlmoya/utils-shared/routing';
+
+describe('Public utility routing contract', () => {
+  it('keeps the complete fifteen-locale utility set', () => {
+    expect(UTILITY_LOCALES).toHaveLength(15);
+    expect(new Set(UTILITY_LOCALES).size).toBe(15);
+  });
+
+  it('keeps Spanish on the external jjlmoya host', () => {
+    expect(getUtilitiesPath('es')).toBe('https://www.jjlmoya.es/utilidades/');
+    expect(getCategoryPath('es', 'juegos-de-mesa')).toBe(
+      'https://www.jjlmoya.es/utilidades/categorias/juegos-de-mesa/',
+    );
+    expect(getUtilityPath('es', 'juegos-de-mesa', 'tirador-de-dados')).toBe(
+      'https://www.jjlmoya.es/utilidades/tirador-de-dados/',
+    );
+  });
+
+  it('serializes every internal locale with both translated namespaces', () => {
+    for (const locale of UTILITY_LOCALES.filter((candidate) => candidate !== 'es')) {
+      expect(getUtilitiesPath(locale)).toBe(`/${locale}/${getUtilityNamespace(locale)}/`);
+      const category = getCategoryPath(locale, 'tabletop');
+      const utility = getUtilityPath(locale, 'tabletop', 'dice-roller-simulator');
+
+      expect(category).toBe(
+        `/${locale}/${getUtilityNamespace(locale)}/${getCategoryNamespace(locale)}/tabletop/`,
+      );
+      expect(utility).toBe(
+        `/${locale}/${getUtilityNamespace(locale)}/${getCategoryNamespace(locale)}/tabletop/dice-roller-simulator/`,
+      );
+    }
+  });
+});

package/src/tests/tool_validation.test.ts

@@ -5,7 +5,7 @@ import { tabletopCategory } from '../data';
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
     it('should have tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(16);
+      expect(ALL_TOOLS.length).toBe(17);
     });
 
     it('tabletopCategory should be defined', () => {

package/src/tests/translation_copy.test.ts

@@ -121,4 +121,3 @@ describe('Locales must not copy another locale wholesale', () => {
   });
 });
 
-

package/src/tool/board-game-timer/component.astro

@@ -1,5 +1,4 @@
 ---
-import './board-game-timer.css';
 import SetupPanel from './components/SetupPanel.astro';
 import DuelTimer from './components/DuelTimer.astro';
 import MultiplayerTimer from './components/MultiplayerTimer.astro';

package/src/tool/board-game-timer/i18n/en.ts

@@ -60,7 +60,7 @@ export const content: ToolLocaleContent<BoardGameTimerUI> = {
   ui,
   seo: [
     { type: 'title', text: 'Mastering Tabletop Pace: How Professional Time Controls Enhance Tabletop Gaming', level: 2 },
-    { type: 'paragraph', html: 'Time management is a vital component in modern tabletop gaming. Whether you are contesting a fast-paced party challenge or engaging in a deep strategic wargame, regulating thinking time ensures that all participants have a fair share of the spotlight. Utilizing professional timing methods like Fischer increment, Bronstein delay, or Hourglass modes eliminates analysis paralysis, guarantees game pace consistency, and adds an extra layer of strategic decision-making to the game board.' },
+    { type: 'paragraph', html: 'Time management is a vital component in modern tabletop gaming. Whether you are contesting a fast-paced party challenge or engaging in a deep strategic wargame, regulating thinking time helps give all participants a fair share of the spotlight. Utilizing professional timing methods like Fischer increment, Bronstein delay, or Hourglass modes can reduce analysis paralysis, support a consistent game pace, and add an extra layer of strategic decision-making to the game board.' },
     {
       type: 'stats',
       items: [
@@ -301,4 +301,3 @@ export const content: ToolLocaleContent<BoardGameTimerUI> = {
     }
   ],
 };
-

package/src/tool/board-game-timer/i18n/es.ts

@@ -60,7 +60,7 @@ export const content: ToolLocaleContent<BoardGameTimerUI> = {
   ui,
   seo: [
     { type: 'title', text: 'Dominando el ritmo de juego: Cómo los controles de tiempo profesionales mejoran las partidas', level: 2 },
-    { type: 'paragraph', html: 'La gestión del tiempo es un componente vital en los juegos de mesa modernos. Ya sea que estés disputando una partida rápida o participando en un juego de estrategia complejo, regular el tiempo de reflexión garantiza que todos tengan una participación justa. El uso de métodos de cronometraje profesional como el incremento Fischer, el retraso Bronstein o el reloj de arena elimina el análisis por parálisis y añade una capa estratégica adicional al tablero.' },
+    { type: 'paragraph', html: 'La gestión del tiempo es un componente vital en los juegos de mesa modernos. Ya sea que estés disputando una partida rápida o participando en un juego de estrategia complejo, regular el tiempo de reflexión ayuda a repartir el tiempo de forma justa. El uso de métodos de cronometraje profesional como el incremento Fischer, el retraso Bronstein o el reloj de arena puede reducir el análisis por parálisis y añadir una capa estratégica adicional al tablero.' },
     {
       type: 'stats',
       items: [
@@ -147,7 +147,7 @@ export const content: ToolLocaleContent<BoardGameTimerUI> = {
         },
         {
           title: 'Partidas competitivas en duelo',
-          description: 'Los duelos estrictos con reloj de ajedrez requieren pantallas rotables para garantizar la integridad competitiva y un reparto de tiempo equilibrado entre los jugadores.',
+          description: 'Los duelos estrictos con reloj de ajedrez requieren pantallas rotables para favorecer la integridad competitiva y un reparto de tiempo equilibrado entre los jugadores.',
           icon: 'mdi:trophy',
           highlight: false,
           points: [

package/src/tool/card-draw-odds-calculator/bibliography.astro

@@ -0,0 +1,16 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { cardDrawOddsCalculator } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props as Props;
+const loader = cardDrawOddsCalculator.i18n[locale] || cardDrawOddsCalculator.i18n.en;
+const content = await loader?.();
+if (!content) return null;
+---
+
+{content && <SharedBibliography links={content.bibliography} />}

package/src/tool/card-draw-odds-calculator/bibliography.ts

@@ -0,0 +1,7 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  { name: 'NIST Engineering Statistics Handbook: Hypergeometric CDF', url: 'https://www.itl.nist.gov/div898/software/dataplot/refman2/ch8/hypcdf.pdf' },
+  { name: 'Penn State STAT 414: Hypergeometric Distribution', url: 'https://online.stat.psu.edu/stat414/Lesson07' },
+  { name: 'UNAM: Distribución hipergeométrica', url: 'https://prometeo.matem.unam.mx/recursos/VariosNiveles/iCartesiLibri/recursos/Estadistica_Probabilidad_e_Inferencia/index.html' },
+];