@jjlmoya/utils-science 1.51.0 → 1.53.0

package/src/tests/script_density.test.ts

@@ -1,94 +1,94 @@
-import { describe, expect, it } from 'vitest';
-import { ALL_TOOLS } from '../tools';
-
-type ScriptLocale = keyof typeof SCRIPT_RULES;
-
-const SCRIPT_RULES = {
-  ja: {
-    language: 'Japanese',
-    scriptName: 'kana/kanji',
-    scriptCharacters: /[\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}]/gu,
-    minScriptRatio: 0.45,
-  },
-  ko: {
-    language: 'Korean',
-    scriptName: 'hangul',
-    scriptCharacters: /\p{Script=Hangul}/gu,
-    minScriptRatio: 0.55,
-  },
-  ru: {
-    language: 'Russian',
-    scriptName: 'cyrillic',
-    scriptCharacters: /\p{Script=Cyrillic}/gu,
-    minScriptRatio: 0.65,
-  },
-  zh: {
-    language: 'Chinese',
-    scriptName: 'han',
-    scriptCharacters: /\p{Script=Han}/gu,
-    minScriptRatio: 0.45,
-  },
-} as const;
-
-const LETTERS = /\p{L}/gu;
-const TRANSLATABLE_KEYS = ['title', 'description', 'ui', 'seo', 'faq', 'howTo'] as const;
-
-function collectStrings(value: unknown): string[] {
-  if (typeof value === 'string') return [value];
-  if (!value || typeof value !== 'object') return [];
-  if (Array.isArray(value)) return value.flatMap(collectStrings);
-  return Object.values(value).flatMap(collectStrings);
-}
-
-function normalizeText(value: unknown): string {
-  return collectStrings(value).join(' ').normalize('NFC');
-}
-
-function translatableContent(content: Record<string, unknown>) {
-  return TRANSLATABLE_KEYS.map((key) => content[key]);
-}
-
-function letterCount(text: string): number {
-  return text.match(LETTERS)?.length ?? 0;
-}
-
-function scriptCount(text: string, locale: ScriptLocale): number {
-  return text.match(SCRIPT_RULES[locale].scriptCharacters)?.length ?? 0;
-}
-
-function scriptRatio(text: string, locale: ScriptLocale): number {
-  const letters = letterCount(text);
-  if (letters === 0) return 0;
-  return scriptCount(text, locale) / letters;
-}
-
-describe('Native script density validation', () => {
-  ALL_TOOLS.forEach((tool) => {
-    describe(`Tool: ${tool.entry.id}`, () => {
-      Object.keys(SCRIPT_RULES).forEach((locale) => {
-        it(`${locale} keeps most translated text in its native script`, async () => {
-          const typedLocale = locale as ScriptLocale;
-          const loader = tool.entry.i18n[typedLocale];
-          if (!loader) return;
-
-          const content = await loader();
-          const rule = SCRIPT_RULES[typedLocale];
-          const text = normalizeText(translatableContent(content as Record<string, unknown>));
-          const letters = letterCount(text);
-          const matches = scriptCount(text, typedLocale);
-          const ratio = scriptRatio(text, typedLocale);
-
-          expect(
-            ratio,
-            [
-              `Possible broken translation detected in ${tool.entry.id}/${typedLocale} (${rule.language}).`,
-              `The text has ${matches} ${rule.scriptName} characters out of ${letters} analyzed letters (${(ratio * 100).toFixed(1)}%).`,
-              `Most translatable content should be written in ${rule.scriptName} script.`,
-              'Non-translatable fields such as slug, bibliography, and schemas are ignored to avoid false positives.',
-            ].join(' '),
-          ).toBeGreaterThanOrEqual(rule.minScriptRatio);
-        });
-      });
-    });
-  });
-});
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+
+type ScriptLocale = keyof typeof SCRIPT_RULES;
+
+const SCRIPT_RULES = {
+  ja: {
+    language: 'Japanese',
+    scriptName: 'kana/kanji',
+    scriptCharacters: /[\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}]/gu,
+    minScriptRatio: 0.45,
+  },
+  ko: {
+    language: 'Korean',
+    scriptName: 'hangul',
+    scriptCharacters: /\p{Script=Hangul}/gu,
+    minScriptRatio: 0.55,
+  },
+  ru: {
+    language: 'Russian',
+    scriptName: 'cyrillic',
+    scriptCharacters: /\p{Script=Cyrillic}/gu,
+    minScriptRatio: 0.65,
+  },
+  zh: {
+    language: 'Chinese',
+    scriptName: 'han',
+    scriptCharacters: /\p{Script=Han}/gu,
+    minScriptRatio: 0.45,
+  },
+} as const;
+
+const LETTERS = /\p{L}/gu;
+const TRANSLATABLE_KEYS = ['title', 'description', 'ui', 'seo', 'faq', 'howTo'] as const;
+
+function collectStrings(value: unknown): string[] {
+  if (typeof value === 'string') return [value];
+  if (!value || typeof value !== 'object') return [];
+  if (Array.isArray(value)) return value.flatMap(collectStrings);
+  return Object.values(value).flatMap(collectStrings);
+}
+
+function normalizeText(value: unknown): string {
+  return collectStrings(value).join(' ').normalize('NFC');
+}
+
+function translatableContent(content: Record<string, unknown>) {
+  return TRANSLATABLE_KEYS.map((key) => content[key]);
+}
+
+function letterCount(text: string): number {
+  return text.match(LETTERS)?.length ?? 0;
+}
+
+function scriptCount(text: string, locale: ScriptLocale): number {
+  return text.match(SCRIPT_RULES[locale].scriptCharacters)?.length ?? 0;
+}
+
+function scriptRatio(text: string, locale: ScriptLocale): number {
+  const letters = letterCount(text);
+  if (letters === 0) return 0;
+  return scriptCount(text, locale) / letters;
+}
+
+describe('Native script density validation', () => {
+  ALL_TOOLS.forEach((tool) => {
+    describe(`Tool: ${tool.entry.id}`, () => {
+      Object.keys(SCRIPT_RULES).forEach((locale) => {
+        it(`${locale} keeps most translated text in its native script`, async () => {
+          const typedLocale = locale as ScriptLocale;
+          const loader = tool.entry.i18n[typedLocale];
+          if (!loader) return;
+
+          const content = await loader();
+          const rule = SCRIPT_RULES[typedLocale];
+          const text = normalizeText(translatableContent(content as Record<string, unknown>));
+          const letters = letterCount(text);
+          const matches = scriptCount(text, typedLocale);
+          const ratio = scriptRatio(text, typedLocale);
+
+          expect(
+            ratio,
+            [
+              `Possible broken translation detected in ${tool.entry.id}/${typedLocale} (${rule.language}).`,
+              `The text has ${matches} ${rule.scriptName} characters out of ${letters} analyzed letters (${(ratio * 100).toFixed(1)}%).`,
+              `Most translatable content should be written in ${rule.scriptName} script.`,
+              'Non-translatable fields such as slug, bibliography, and schemas are ignored to avoid false positives.',
+            ].join(' '),
+          ).toBeGreaterThanOrEqual(rule.minScriptRatio);
+        });
+      });
+    });
+  });
+});

package/src/tests/seo_length.test.ts

@@ -1,24 +1,24 @@
-import { describe, it, expect } from 'vitest';
-import * as DATA from '../data';
-
-const ENTRIES = [
-  { id: 'scienceCategory', i18n: DATA.scienceCategory.i18n },
-];
-
-describe('SEO Content Length Validation', () => {
-  ENTRIES.forEach((entry) => {
-    describe(`Tool: ${entry.id}`, () => {
-      Object.keys(entry.i18n).forEach((locale) => {
-        it(`${locale}: SEO section should exist`, async () => {
-          const loader = (entry.i18n as Record<string, () => Promise<{ seo?: unknown[] }>>)[locale];
-          if (loader) {
-            const content = await loader();
-            if (!content.seo) return;
-            expect(Array.isArray(content.seo)).toBe(true);
-          }
-        });
-      });
-    });
-  });
-});
-
+import { describe, it, expect } from 'vitest';
+import * as DATA from '../data';
+
+const ENTRIES = [
+  { id: 'scienceCategory', i18n: DATA.scienceCategory.i18n },
+];
+
+describe('SEO Content Length Validation', () => {
+  ENTRIES.forEach((entry) => {
+    describe(`Tool: ${entry.id}`, () => {
+      Object.keys(entry.i18n).forEach((locale) => {
+        it(`${locale}: SEO section should exist`, async () => {
+          const loader = (entry.i18n as Record<string, () => Promise<{ seo?: unknown[] }>>)[locale];
+          if (loader) {
+            const content = await loader();
+            if (!content.seo) return;
+            expect(Array.isArray(content.seo)).toBe(true);
+          }
+        });
+      });
+    });
+  });
+});
+

package/src/tests/seo_parity.test.ts

@@ -24,15 +24,15 @@ async function verifyLocaleParity(
   const locFaqCount = countItems(locContent?.faq);
   const locHowToCount = countItems(locContent?.howTo);
 
-  expect(
+  expect.soft(
     locSeoCount,
-    `Locale ${loc} SEO sections count (${locSeoCount}) must match EN (${expected.seo})`,
-  ).toBe(expected.seo);
-  expect(
+    `Locale ${loc} SEO sections count (${locSeoCount}) must include the EN structure (${expected.seo})`,
+  ).toBeGreaterThanOrEqual(expected.seo);
+  expect.soft(
     locFaqCount,
     `Locale ${loc} FAQ items count (${locFaqCount}) must match EN (${expected.faq})`,
   ).toBe(expected.faq);
-  expect(
+  expect.soft(
     locHowToCount,
     `Locale ${loc} HowTo steps count (${locHowToCount}) must match EN (${expected.howTo})`,
   ).toBe(expected.howTo);

package/src/tests/seo_translation_completeness.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+
+const ASIAN_LOCALES = ['ja', 'ko', 'zh'];
+
+function getSimpleSectionLength(section: any): number {
+  if (section.type === 'title') return section.text ? section.text.length : 0;
+  if (section.type === 'paragraph') return section.html ? section.html.replace(/<[^>]*>/g, '').length : 0;
+  if (section.type === 'list') return section.items ? section.items.join('').length : 0;
+  return 0;
+}
+
+function getComplexSectionLength(section: any): number {
+  if (section.type === 'diagnostic' || section.type === 'tip') {
+    return (section.title ? section.title.length : 0) + (section.html ? section.html.replace(/<[^>]*>/g, '').length : 0);
+  }
+  if (section.type === 'table') {
+    return ((section.headers || []).join('').length) + ((section.rows || []).flat().join('').length);
+  }
+  return 0;
+}
+
+function getSectionLength(section: any): number {
+  return getSimpleSectionLength(section) || getComplexSectionLength(section);
+}
+
+function calculateSeoTextLength(seoSections: any[]): number {
+  return seoSections.reduce((acc, section) => acc + getSectionLength(section), 0);
+}
+
+function checkLocaleSeoLength(toolId: string, locale: string, localeLen: number, enLen: number): string | null {
+  const isAsian = ASIAN_LOCALES.includes(locale);
+  const minLength = Math.floor(enLen * (isAsian ? 0.25 : 0.70));
+  const msgType = isAsian ? 'suspiciously short' : 'truncated/lazy';
+
+  if (localeLen >= minLength) return null;
+
+  return `[LAZY SEO TRANSLATION] Tool "${toolId}" locale "${locale}" SEO text is ${msgType} (${localeLen} chars vs EN ${enLen} chars, expected min ${minLength})`;
+}
+
+async function auditSingleLocale(toolId: string, locale: string, loader: any, enSeoLength: number): Promise<string | null> {
+  if (locale === 'en' || !loader) return null;
+  const content = await loader();
+  if (!content.seo || !Array.isArray(content.seo)) return null;
+
+  return checkLocaleSeoLength(toolId, locale, calculateSeoTextLength(content.seo), enSeoLength);
+}
+
+describe('SEO Translation Completeness & Laziness Audit', () => {
+  ALL_TOOLS.forEach(({ entry }) => {
+    describe(`Tool: ${entry.id}`, () => {
+      it('should not have lazy or truncated SEO content compared to English reference', async () => {
+        const enLoader = entry.i18n['en' as keyof typeof entry.i18n];
+        if (!enLoader) return;
+
+        const enContent = await enLoader();
+        if (!enContent.seo || !Array.isArray(enContent.seo)) return;
+
+        const enSeoLength = calculateSeoTextLength(enContent.seo);
+
+        const failures: string[] = [];
+        for (const [locale, loader] of Object.entries(entry.i18n)) {
+          const failure = await auditSingleLocale(entry.id, locale, loader, enSeoLength);
+          if (failure) failures.push(failure);
+        }
+
+        expect(
+          failures,
+          failures.length > 0
+            ? `SEO translation completeness failures for "${entry.id}" (${failures.length}):\n${failures.map((failure, index) => `${index + 1}. ${failure}`).join('\n')}`
+            : undefined,
+        ).toEqual([]);
+      });
+    });
+  });
+});

package/src/tests/seo_wellformed_export.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join, relative } from 'path';
+
+function findSeoAstroFiles(dir: string): string[] {
+  const files: string[] = [];
+  if (!existsSync(dir)) return files;
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...findSeoAstroFiles(fullPath));
+    } else if (entry.isFile() && entry.name === 'seo.astro') {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+const toolDir = join(process.cwd(), 'src', 'tool');
+const seoFiles = findSeoAstroFiles(toolDir);
+
+describe('SEO Component Wellformed Export', () => {
+  it('found tool seo.astro components', () => {
+    expect(seoFiles.length).toBeGreaterThan(0);
+  });
+
+  seoFiles.forEach((file) => {
+    const relativePath = relative(process.cwd(), file);
+
+    it(`${relativePath} should dynamically load SEO sections and use SEORenderer`, () => {
+      const content = readFileSync(file, 'utf-8');
+
+      const usesSeoRenderer =
+        content.includes('@jjlmoya/utils-shared') &&
+        (content.includes('SEORenderer') || content.includes('SEOArticle'));
+
+      const acquiresDynamicContent =
+        content.includes('.i18n') ||
+        content.includes('loader') ||
+        content.includes('await loader') ||
+        content.includes('.seo');
+
+      const isBrokenPattern =
+        /sections\s*=\s*\[\s*\]/.test(content) && !acquiresDynamicContent;
+
+      expect(
+        usesSeoRenderer,
+        `File "${relativePath}" does not import or use SEORenderer from @jjlmoya/utils-shared.`,
+      ).toBe(true);
+
+      expect(
+        isBrokenPattern,
+        `File "${relativePath}" relies on a static sections=[] prop default without fetching content from entry.i18n, resulting in empty SEO text on consumers.`,
+      ).toBe(false);
+
+      expect(
+        acquiresDynamicContent,
+        `File "${relativePath}" does not fetch dynamic i18n content for SEO rendering.`,
+      ).toBe(true);
+    });
+  });
+});