@jjlmoya/utils-civic 1.1.0

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/schemas_fulfillment.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+describe('Schemas Fulfillment Validation', () => {
+  ALL_TOOLS.forEach((tool) => {
+    describe(`Tool: ${tool.entry.id}`, () => {
+      Object.keys(tool.entry.i18n).forEach((locale) => {
+        it(`Locale: ${locale} should have faqSchema, appSchema and howToSchema`, async () => {
+          const loader = tool.entry.i18n[locale as keyof typeof tool.entry.i18n];
+          if (!loader) return;
+          const content = (await loader()) as ToolLocaleContent;
+
+          const schemaTypes = content.schemas.map((s: any) => s['@type']);
+
+          expect(schemaTypes, `Tool "${tool.entry.id}" locale "${locale}" is missing FAQPage schema`).toContain('FAQPage');
+          expect(schemaTypes, `Tool "${tool.entry.id}" locale "${locale}" is missing SoftwareApplication schema`).toContain('SoftwareApplication');
+          expect(schemaTypes, `Tool "${tool.entry.id}" locale "${locale}" is missing HowTo schema`).toContain('HowTo');
+        });
+      });
+    });
+  });
+});

package/src/tests/script_density.test.ts

@@ -0,0 +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 unknown 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

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import * as DATA from '../data';
+
+const ENTRIES = [
+  { id: 'civicCategory', i18n: DATA.civicCategory.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) return;
+          const content = await loader();
+          if (!content.seo) return;
+          expect(Array.isArray(content.seo)).toBe(true);
+        });
+      });
+    });
+  });
+});
+

package/src/tests/seo_parity.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_ENTRIES } from '../entries';
+import type { KnownLocale } from '../types';
+
+interface ExpectedCounts {
+  seo: number;
+  faq: number;
+  howTo: number;
+}
+
+function countItems(arr: unknown[] | undefined): number {
+  return arr?.length ?? 0;
+}
+
+async function verifyLocaleParity(
+  entry: typeof ALL_ENTRIES[number],
+  loc: KnownLocale,
+  expected: ExpectedCounts,
+): Promise<void> {
+  const locContent = await entry.i18n[loc]?.();
+  expect(locContent, `Locale ${loc} missing content`).toBeDefined();
+
+  const locSeoCount = countItems(locContent?.seo);
+  const locFaqCount = countItems(locContent?.faq);
+  const locHowToCount = countItems(locContent?.howTo);
+
+  expect(
+    locSeoCount,
+    `Locale ${loc} SEO sections count (${locSeoCount}) must match EN (${expected.seo})`,
+  ).toBeGreaterThanOrEqual(expected.seo);
+  expect(
+    locFaqCount,
+    `Locale ${loc} FAQ items count (${locFaqCount}) must match EN (${expected.faq})`,
+  ).toBe(expected.faq);
+  expect(
+    locHowToCount,
+    `Locale ${loc} HowTo steps count (${locHowToCount}) must match EN (${expected.howTo})`,
+  ).toBe(expected.howTo);
+}
+
+describe('SEO & i18n Structural Parity Suite', () => {
+  ALL_ENTRIES.forEach((entry) => {
+    describe(`Tool: ${entry.id}`, () => {
+      it('all 15 locales should provide at least the complete English SEO section set', async () => {
+        const enContent = await entry.i18n.en?.();
+        expect(enContent).toBeDefined();
+        const expected: ExpectedCounts = {
+          seo: countItems(enContent?.seo),
+          faq: countItems(enContent?.faq),
+          howTo: countItems(enContent?.howTo),
+        };
+
+        const locales = Object.keys(entry.i18n) as KnownLocale[];
+        for (const loc of locales) {
+          await verifyLocaleParity(entry, loc, expected);
+        }
+      });
+    });
+  });
+});

package/src/tests/seo_translation_completeness.test.ts

@@ -0,0 +1,75 @@
+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 = isAsian ? 120 : Math.max(240, Math.floor(enLen * 0.35));
+  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}":\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);
+    });
+  });
+});

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,
+          });
+        }
+      });
+    });
+  });
+});