@jjlmoya/utils-language 1.1.0

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

@@ -0,0 +1,56 @@
+import type { ToolDefinition } from '../types';
+
+export interface ToolExportValidationResult {
+  passed: boolean;
+  failures: string[];
+}
+
+function validateComponentType(
+  toolId: string,
+  componentName: string,
+  component: unknown,
+  failures: string[],
+): void {
+  if (typeof component !== 'function') {
+    failures.push(`${toolId}: ${componentName} is not a function (${typeof component})`);
+  }
+}
+
+async function validateComponentExecution(
+  toolId: string,
+  componentName: string,
+  fn: () => Promise<unknown>,
+  failures: string[],
+): Promise<void> {
+  try {
+    const result = await fn();
+    if (!result || typeof result !== 'object') {
+      failures.push(`${toolId}: ${componentName} import returned invalid result`);
+    }
+  } catch (error) {
+    failures.push(`${toolId}: ${componentName} execution error - ${error instanceof Error ? error.message : 'unknown'}`);
+  }
+}
+
+export async function validateToolExports(tools: ToolDefinition[]): Promise<ToolExportValidationResult> {
+  const failures: string[] = [];
+
+  for (const tool of tools) {
+    validateComponentType(tool.entry.id, 'Component', tool.Component, failures);
+    validateComponentType(tool.entry.id, 'SEOComponent', tool.SEOComponent, failures);
+    validateComponentType(tool.entry.id, 'BibliographyComponent', tool.BibliographyComponent, failures);
+
+    const componentFn = tool.Component as () => Promise<unknown>;
+    const seoFn = tool.SEOComponent as () => Promise<unknown>;
+    const bibFn = tool.BibliographyComponent as () => Promise<unknown>;
+
+    await validateComponentExecution(tool.entry.id, 'Component', componentFn, failures);
+    await validateComponentExecution(tool.entry.id, 'SEOComponent', seoFn, failures);
+    await validateComponentExecution(tool.entry.id, 'BibliographyComponent', bibFn, failures);
+  }
+
+  return {
+    passed: failures.length === 0,
+    failures,
+  };
+}

package/src/tests/slug_language_code_format.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+describe('Slug Language Code Format Validation', () => {
+  ALL_TOOLS.forEach((tool) => {
+    describe(`Tool: ${tool.entry.id}`, () => {
+      it('slug should not end with 2-letter language codes like -ja, -ru, -ko', async () => {
+        const locales = Object.keys(tool.entry.i18n);
+
+        for (const locale of locales) {
+          const loader = tool.entry.i18n[locale as keyof typeof tool.entry.i18n];
+          const content = (await loader?.()) as ToolLocaleContent;
+
+          expect(
+            content.slug,
+            `Tool "${tool.entry.id}" locale "${locale}" slug ("${content.slug}") cannot end with a 2-letter language code (e.g., -ja, -ru, -ko).`,
+          ).not.toMatch(/-[a-z]{2}$/);
+        }
+      });
+    });
+  });
+});

package/src/tests/slug_uniqueness.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+const sharingLocales = ['ja', 'ko', 'zh'];
+
+interface ValidateParams {
+  toolId: string;
+  locale: string;
+  content: ToolLocaleContent;
+  enSlug: string;
+  slugs: Map<string, string>;
+}
+
+const validateLocaleSlug = ({
+  toolId,
+  locale,
+  content,
+  enSlug,
+  slugs,
+}: ValidateParams) => {
+  expect(
+    content.slug,
+    `Tool "${toolId}" locale "${locale}" has an invalid slug ("${content.slug}"). Slugs must be transliterated (only a-z, 0-9, and -).`,
+  ).toMatch(/^[a-z0-9-]+$/);
+
+  if (locale === 'en') {
+    return;
+  }
+
+  if (sharingLocales.includes(locale)) {
+    expect(
+      content.slug,
+      `Tool "${toolId}" locale "${locale}" must use the same slug as "en" ("${enSlug}").`,
+    ).toBe(enSlug);
+  } else {
+    expect(
+      content.slug,
+      `Tool "${toolId}" locale "${locale}" has the same slug as "en" ("${enSlug}"). Cada slug tiene que estar en su propia idioma`,
+    ).not.toBe(enSlug);
+
+    if (slugs.has(content.slug)) {
+      const previousLocale = slugs.get(content.slug);
+      expect(
+        false,
+        `Tool "${toolId}" locales "${locale}" and "${previousLocale}" share the same slug ("${content.slug}"). Cada slug tiene que estar en su propia idioma`,
+      ).toBe(true);
+    }
+    slugs.set(content.slug, locale);
+  }
+};
+
+describe('Slug Localization and Uniqueness Validation', () => {
+  ALL_TOOLS.forEach((tool) => {
+    describe(`Tool: ${tool.entry.id}`, () => {
+      it('every locale should have a unique, translated slug', async () => {
+        const slugs = new Map<string, string>();
+        const locales = Object.keys(tool.entry.i18n);
+
+        let enSlug = '';
+        if (locales.includes('en')) {
+          const enLoader = tool.entry.i18n['en' as keyof typeof tool.entry.i18n];
+          const enContent = (await enLoader?.()) as ToolLocaleContent;
+          enSlug = enContent.slug;
+        }
+
+        for (const locale of locales) {
+          const loader = tool.entry.i18n[locale as keyof typeof tool.entry.i18n];
+          const content = (await loader?.()) as ToolLocaleContent;
+          validateLocaleSlug({
+            toolId: tool.entry.id,
+            locale,
+            content,
+            enSlug,
+            slugs,
+          });
+        }
+      });
+    });
+  });
+});

package/src/tests/spanish_leakage.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import { ALL_ENTRIES } from '../entries';
+
+const STRUCTURAL_KEYS = new Set([
+  'id',
+  'slug',
+  'url',
+  'icon',
+  'image',
+  'imageUrl',
+  'keywords',
+  'category',
+  'tags',
+  'toolId',
+  'type',
+  'locale',
+  'language',
+  'direction',
+]);
+
+const TRANSLATABLE_KEYS = [
+  'title',
+  'description',
+  'faqTitle',
+  'faq',
+  'howTo',
+  'seo',
+  'schemas',
+] as const;
+
+const COPY_THRESHOLD = 0.9;
+
+const SPANISH_MARKERS = [
+  ['sangre', /\bsangre\b/gi],
+  ['molino', /\bmolino\b/gi],
+  ['grano', /\bgrano\b/gi],
+  ['paladar', /\bpaladar\b/gi],
+  ['cuchillas', /\bcuchillas\b/gi],
+  ['trozos', /\btrozos\b/gi],
+  ['frescura', /\bfrescura\b/gi],
+  ['ingresa', /\bingresa\b/gi],
+  ['selecciona', /\bselecciona\b/gi],
+  ['herramienta', /\bherramienta\b/gi],
+  ['según', /\bsegún\b/gi],
+  ['después', /\bdespués\b/gi],
+  ['puedes', /\bpuedes\b/gi],
+  ['debes', /\bdebes\b/gi],
+  ['tus', /\btus\b/gi],
+  ['a la vez', /\ba la vez\b/gi],
+  ['los datos', /\blos datos\b/gi],
+  ['las opciones', /\blas opciones\b/gi],
+  ['el resultado', /\bel resultado\b/gi],
+  ['método de extracción', /\bmétodo de extracción\b/gi],
+  ['uniformidad del molino', /\buniformidad del molino\b/gi],
+  ['café recién tostado', /\bcafé recién tostado\b/gi],
+] as const;
+
+type UnknownRecord = Record<string, unknown>;
+
+function normalize(value: string): string {
+  return value
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLocaleLowerCase('es');
+}
+
+function isTechnicalInvariant(text: string): boolean {
+  const ledUnitMatches = text.match(/\b\d+(?:-\d+)?\s*(?:w|lm)\b/g) ?? [];
+  return [
+    'data:image/svg+xml;base64',
+    'background-image: url',
+    '.layout-playground {',
+    'const samplerate =',
+  ].some((pattern) => text.includes(pattern)) ||
+    (text.includes('presets') && text.includes('hz')) ||
+    (text.includes('t_rectal') && text.includes('exp(-k * t)')) ||
+    (text.includes('led') && ledUnitMatches.length >= 3);
+}
+
+function collectString(value: string, output: string[]): void {
+  const text = normalize(value);
+  if (!isTechnicalInvariant(text) && text.length >= 20) output.push(text);
+}
+
+function collectObject(value: UnknownRecord, output: string[]): void {
+  Object.entries(value).forEach(([childKey, childValue]) => {
+    collectText(childValue, output, childKey);
+  });
+}
+
+function collectText(value: unknown, output: string[], key?: string): void {
+  if (key && STRUCTURAL_KEYS.has(key)) return;
+  if (typeof value === 'string') return collectString(value, output);
+  if (Array.isArray(value)) return value.forEach((item) => collectText(item, output));
+  if (value && typeof value === 'object') collectObject(value as UnknownRecord, output);
+}
+
+async function loadText(loader: unknown): Promise<string[]> {
+  if (typeof loader !== 'function') return [];
+  const module = await (loader as () => Promise<unknown>)();
+  const output: string[] = [];
+  if (module && typeof module === 'object') {
+    const record = module as UnknownRecord;
+    for (const key of TRANSLATABLE_KEYS) {
+      collectText(record[key], output, key);
+    }
+  }
+  return output;
+}
+
+function findSpanishMarkers(text: string[]): string[] {
+  const corpus = text.join(' ');
+  return SPANISH_MARKERS.flatMap(([label, pattern]) =>
+    pattern.test(corpus) ? [label] : [],
+  );
+}
+
+function similarity(left: string, right: string): number {
+  const leftTokens = left.split(/\s+/);
+  const rightCounts = new Map<string, number>();
+  right.split(/\s+/).forEach((token) => rightCounts.set(token, (rightCounts.get(token) ?? 0) + 1));
+  const matches = leftTokens.reduce((total, token) => {
+    const count = rightCounts.get(token) ?? 0;
+    if (count > 0) rightCounts.set(token, count - 1);
+    return total + (count > 0 ? 1 : 0);
+  }, 0);
+  return (2 * matches) / (leftTokens.length + right.split(/\s+/).length);
+}
+
+function findCopiedFragments(spanish: string[], translated: string[]): string[] {
+  return spanish
+    .filter((fragment) => fragment.length >= 80)
+    .filter((fragment) => translated.some((candidate) =>
+      candidate.length >= 80 &&
+      Math.min(fragment.length, candidate.length) / Math.max(fragment.length, candidate.length) >= COPY_THRESHOLD &&
+      similarity(fragment, candidate) >= COPY_THRESHOLD,
+    ))
+    .sort((a, b) => b.length - a.length)
+    .slice(0, 3);
+}
+
+describe('Locales must not contain copied Spanish content', () => {
+  for (const entry of ALL_ENTRIES) {
+    it(`${entry.id} has no untranslated Spanish blocks`, async () => {
+      const spanish = await loadText(entry.i18n.es);
+      const failures: string[] = [];
+
+      for (const [locale, loader] of Object.entries(entry.i18n)) {
+        if (locale === 'es') continue;
+
+        const translated = await loadText(loader);
+        const copiedFragments = findCopiedFragments(spanish, translated);
+        const markerHits = findSpanishMarkers(translated);
+
+        if (copiedFragments.length > 0 || markerHits.length >= 2) {
+          const details = [
+            copiedFragments.length > 0
+              ? `copied fragments: ${copiedFragments
+                  .map((fragment) => JSON.stringify(fragment.slice(0, 120)))
+                  .join(', ')}`
+              : '',
+            markerHits.length >= 2 ? `Spanish markers: ${markerHits.join(', ')}` : '',
+          ]
+            .filter(Boolean)
+            .join('; ');
+          failures.push(`${locale}: ${details}`);
+        }
+      }
+
+      expect(failures, failures.join('\n')).toEqual([]);
+    });
+  }
+});

package/src/tests/title_quality.test.ts

@@ -0,0 +1,55 @@
+import { describe, it } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function getFiles(dir: string, ext: string[]): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+  const list = fs.readdirSync(dir);
+  for (const file of list) {
+    const fullPath = path.join(dir, file);
+    const stat = fs.statSync(fullPath);
+    if (stat && stat.isDirectory()) {
+      results.push(...getFiles(fullPath, ext));
+    } else if (ext.some((e) => file.endsWith(e))) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+const SRC_DIR = path.join(process.cwd(), 'src');
+
+describe('Project Titles - Separator Validation', () => {
+  const files = [
+    ...getFiles(path.join(SRC_DIR, 'tool'), ['.ts']),
+    ...getFiles(path.join(SRC_DIR, 'category'), ['.ts']),
+  ].filter(f => f.includes('i18n'));
+
+  it.each(files)('Verify that titles in %s do not contain | or -', (filePath) => {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const relativePath = path.relative(process.cwd(), filePath);
+
+    const titlePatterns = [
+      /const\s+title\s*=\s*['"]([^'"]+)['"]/g,
+      /title\s*:\s*['"]([^'"]+)['"]/g,
+    ];
+
+    const findings: string[] = [];
+
+    for (const pattern of titlePatterns) {
+      let match;
+      while ((match = pattern.exec(content)) !== null) {
+        const title = match[1]!;
+        if (title.includes('|') || title.includes('-')) {
+          findings.push(title);
+        }
+      }
+    }
+
+    if (findings.length > 0) {
+      const list = findings.map((f) => `  - "${f}"`).join('\n');
+      throw new Error(`Forbidden separators (| or -) found in titles in ${relativePath}:\n${list}`);
+    }
+  });
+});

package/src/tests/tool_exports.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import { validateToolExports } from './shared-test-helpers';
+
+describe('Tool Exports Pattern Validation', () => {
+  describe('Component Exports Format', () => {
+    ALL_TOOLS.forEach((tool) => {
+      it(`${tool.entry.id}: Component should be a lazy-loaded function`, () => {
+        expect(typeof tool.Component).toBe('function');
+        expect(tool.Component).toBeInstanceOf(Function);
+      });
+
+      it(`${tool.entry.id}: SEOComponent should be a lazy-loaded function`, () => {
+        expect(typeof tool.SEOComponent).toBe('function');
+        expect(tool.SEOComponent).toBeInstanceOf(Function);
+      });
+
+      it(`${tool.entry.id}: BibliographyComponent should be a lazy-loaded function`, () => {
+        expect(typeof tool.BibliographyComponent).toBe('function');
+        expect(tool.BibliographyComponent).toBeInstanceOf(Function);
+      });
+    });
+  });
+
+  describe('Dynamic Import Validation', () => {
+    it('all tools must have functional dynamic imports', async () => {
+      const result = await validateToolExports(ALL_TOOLS);
+      if (!result.passed) {
+        throw new Error(`Tool export validation failed:\n${result.failures.join('\n')}`);
+      }
+      expect(result.passed).toBe(true);
+    });
+  });
+});

package/src/tests/tool_validation.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import { languageCategory } from '../data';
+
+describe('Tool Validation Suite', () => {
+  describe('Library Registration', () => {
+    it('should have tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(1);
+    });
+
+    it('languageCategory should be defined', () => {
+      expect(languageCategory).toBeDefined();
+      expect(languageCategory.i18n).toBeDefined();
+    });
+  });
+});

package/src/tests/translation_copy.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+import { ALL_ENTRIES } from '../entries';
+
+const COPY_THRESHOLD = 0.9;
+
+const STRUCTURAL_KEYS = new Set([
+  '@context',
+  '@type',
+  'applicationCategory',
+  'columns',
+  'highlight',
+  'icon',
+  'level',
+  'operatingSystem',
+  'position',
+  'positive',
+  'price',
+  'priceCurrency',
+  'slug',
+  'trend',
+  'type',
+  'url',
+  'value',
+  'variant',
+]);
+
+function normalizeText(value: string): string {
+  return value
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&(?:amp|lt|gt|quot|apos|nbsp);/gi, ' ')
+    .replace(/[\u2018\u2019]/g, "'")
+    .replace(/[\u201c\u201d]/g, '"')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLocaleLowerCase();
+}
+
+function collectText(value: unknown, path: string, parts: string[]): void {
+  if (typeof value === 'string') {
+    const normalized = normalizeText(value);
+    if (normalized.length >= 2) parts.push(normalized);
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => collectText(item, `${path}[${index}]`, parts));
+    return;
+  }
+
+  if (!value || typeof value !== 'object') return;
+
+  Object.entries(value).forEach(([key, child]) => {
+    if (STRUCTURAL_KEYS.has(key)) return;
+    collectText(child, `${path}.${key}`, parts);
+  });
+}
+
+function localeCorpus(content: unknown): string {
+  if (!content || typeof content !== 'object') return '';
+
+  const record = content as Record<string, unknown>;
+  const parts: string[] = [];
+  collectText(record.title, 'title', parts);
+  collectText(record.description, 'description', parts);
+  collectText(record.faqTitle, 'faqTitle', parts);
+  collectText(record.faq, 'faq', parts);
+  collectText(record.seo, 'seo', parts);
+  collectText(record.schemas, 'schemas', parts);
+  return parts.join(' ');
+}
+
+function tokenCounts(text: string): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const token of text.match(/[\p{L}\p{N}]+/gu) ?? []) {
+    counts.set(token, (counts.get(token) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function copySimilarity(left: string, right: string): number {
+  const leftCounts = tokenCounts(left);
+  const rightCounts = tokenCounts(right);
+  const leftTotal = [...leftCounts.values()].reduce((sum, count) => sum + count, 0);
+  const rightTotal = [...rightCounts.values()].reduce((sum, count) => sum + count, 0);
+  if (leftTotal === 0 || rightTotal === 0) return 0;
+
+  let shared = 0;
+  for (const [token, count] of leftCounts) {
+    shared += Math.min(count, rightCounts.get(token) ?? 0);
+  }
+  return (2 * shared) / (leftTotal + rightTotal);
+}
+
+describe('Locales must not copy another locale wholesale', () => {
+  ALL_ENTRIES.forEach((entry) => {
+    it(`${entry.id} is not at least ${COPY_THRESHOLD * 100}% identical to another locale`, async () => {
+      const corpora = new Map<string, string>();
+
+      for (const [locale, loader] of Object.entries(entry.i18n)) {
+        if (!loader) continue;
+        corpora.set(locale, localeCorpus(await loader()));
+      }
+
+      const locales = [...corpora.keys()];
+      const violations: string[] = [];
+
+      for (let leftIndex = 0; leftIndex < locales.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < locales.length; rightIndex += 1) {
+          const left = locales[leftIndex]!;
+          const right = locales[rightIndex]!;
+          const similarity = copySimilarity(String(corpora.get(left) ?? ''), String(corpora.get(right) ?? ''));
+
+          if (similarity >= COPY_THRESHOLD) {
+            violations.push(`${left} ↔ ${right}: ${(similarity * 100).toFixed(1)}%`);
+          }
+        }
+      }
+
+      expect(violations, `Locale copy threshold exceeded in ${entry.id}`).toEqual([]);
+    });
+  });
+});

package/src/tool/language-learning-study-plan-planner/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography } from '@jjlmoya/utils-shared';
+import { bibliography } from './bibliography';
+---
+
+<Bibliography links={bibliography} />

package/src/tool/language-learning-study-plan-planner/bibliography.ts

@@ -0,0 +1,6 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  { name: 'Council of Europe: CEFR Companion Volume, Spanish edition', url: 'https://rm.coe.int/marco-comun-europeo-de-referencia-para-las-lenguas-aprendizaje-ensenan/1680a52d53' },
+  { name: 'Cambridge English: Guided learning hours', url: 'https://support.cambridgeenglish.org/hc/en-gb/articles/202838506-Guided-learning-hours' },
+];