refactor: address PR review feedback and improve code quality

Implemented all improvements suggested in PR #7 code review:

- Fix hardcoded site URL by using centralized SITE_CONFIG
- Improve related posts algorithm to use relative recency scoring
- Document reading time regex limitations with comments
- Add comprehensive tag validation with Unicode support
- Enable previously skipped tests for Portuguese language and reading progress
- Extract magic numbers to named constants for better maintainability
- Add JSDoc comments to all exported utility functions

All tests passing (42/42). Build successful.

Author: jjuanrivvera99

src/config/site.ts

@@ -6,7 +6,7 @@ export const SITE_CONFIG = {
   author: 'Juan Felipe Rivera González',
   email: 'jjuanrivvera@gmail.com',
   twitter: '@jjuanrivvera99',
-  github: 'jjuanrivvera',
+  github: 'jjuanrivvera99',
   linkedin: 'jjuanrivvera99',
   defaultLanguage: 'en' as const,
   supportedLanguages: ['en', 'es', 'pt'] as const,

src/content/config.ts

@@ -28,7 +28,16 @@ const blog = defineCollection({
 
         // Taxonomy
         tags: z
-          .array(z.string())
+          .array(
+            z
+              .string()
+              .min(2, 'Tags should be at least 2 characters')
+              .max(30, 'Tags should be 30 characters or less')
+              .regex(
+                /^[\p{L}\p{N}\s-]+$/u,
+                'Tags should only contain letters, numbers, hyphens, and spaces'
+              )
+          )
           .min(1, 'At least one tag is required')
           .max(5, 'Maximum 5 tags allowed'),
 

src/utils/blogHreflang.ts

@@ -4,29 +4,27 @@
  */
 
 import type { BlogPost, HreflangLink, SupportedLang } from '@models/blog';
-
-const SITE_URL = 'https://jjuanrivvera.com';
-
-// Language code mapping for hreflang (ISO 639-1 + ISO 3166-1)
-const LANG_CODES: Record<SupportedLang, string> = {
-  en: 'en-US',
-  es: 'es-ES',
-  pt: 'pt-BR',
-};
+import { SITE_CONFIG, LOCALE_MAP } from '@config/site';
 
 /**
  * Build blog post URL for a specific language
+ * @param slug - The post slug (with or without language prefix)
+ * @param lang - The target language code
+ * @returns Full URL to the blog post
+ * @example
+ * buildPostUrl('my-post', 'en') // => 'https://jjuanrivvera.com/blog/my-post'
+ * buildPostUrl('my-post', 'es') // => 'https://jjuanrivvera.com/es/blog/my-post'
  */
 function buildPostUrl(slug: string, lang: SupportedLang): string {
   // Remove language prefix from slug if present (safe regex)
   const cleanSlug = slug.replace(/^(en|es|pt)\//, '');
 
   // English posts don't have language prefix
   if (lang === 'en') {
-    return `${SITE_URL}/blog/${cleanSlug}`;
+    return `${SITE_CONFIG.url}/blog/${cleanSlug}`;
   }
 
-  return `${SITE_URL}/${lang}/blog/${cleanSlug}`;
+  return `${SITE_CONFIG.url}/${lang}/blog/${cleanSlug}`;
 }
 
 /**
@@ -43,7 +41,7 @@ export function generateHreflangLinks(
 
   // Add current post's language
   links.push({
-    lang: LANG_CODES[currentPost.data.lang],
+    lang: LOCALE_MAP[currentPost.data.lang],
     url: buildPostUrl(currentPost.slug, currentPost.data.lang),
   });
 
@@ -58,7 +56,7 @@ export function generateHreflangLinks(
 
     translations.forEach((translation) => {
       links.push({
-        lang: LANG_CODES[translation.data.lang],
+        lang: LOCALE_MAP[translation.data.lang],
         url: buildPostUrl(translation.slug, translation.data.lang),
       });
     });
@@ -87,6 +85,12 @@ export function generateHreflangLinks(
 
 /**
  * Get translation of a post in a specific language
+ * @param currentPost - The current blog post
+ * @param targetLang - The target language to find translation for
+ * @param allPosts - All blog posts to search within
+ * @returns The translated post or null if not found
+ * @example
+ * const spanishPost = getTranslation(englishPost, 'es', allPosts);
  */
 export function getTranslation(
   currentPost: BlogPost,
@@ -107,6 +111,12 @@ export function getTranslation(
 
 /**
  * Get all available translations for a post
+ * @param currentPost - The current blog post
+ * @param allPosts - All blog posts to search within
+ * @returns Map of language codes to their corresponding posts
+ * @example
+ * const translations = getAllTranslations(post, allPosts);
+ * const spanishVersion = translations.get('es');
  */
 export function getAllTranslations(
   currentPost: BlogPost,
@@ -136,24 +146,36 @@ export function getAllTranslations(
 
 /**
  * Build blog listing URL for a specific language
+ * @param lang - The target language code
+ * @param page - The page number (defaults to 1)
+ * @returns Full URL to the blog listing page
+ * @example
+ * buildBlogListingUrl('en', 1) // => 'https://jjuanrivvera.com/blog'
+ * buildBlogListingUrl('es', 2) // => 'https://jjuanrivvera.com/es/blog/2'
  */
 export function buildBlogListingUrl(
   lang: SupportedLang,
   page: number = 1
 ): string {
   const basePath = lang === 'en' ? '/blog' : `/${lang}/blog`;
   return page === 1
-    ? `${SITE_URL}${basePath}`
-    : `${SITE_URL}${basePath}/${page}`;
+    ? `${SITE_CONFIG.url}${basePath}`
+    : `${SITE_CONFIG.url}${basePath}/${page}`;
 }
 
 /**
  * Build tag page URL for a specific language
+ * @param tag - The tag name (will be normalized to lowercase with hyphens)
+ * @param lang - The target language code
+ * @returns Full URL to the tag archive page
+ * @example
+ * buildTagUrl('TypeScript', 'en') // => 'https://jjuanrivvera.com/blog/tag/typescript'
+ * buildTagUrl('Web Dev', 'es') // => 'https://jjuanrivvera.com/es/blog/tag/web-dev'
  */
 export function buildTagUrl(tag: string, lang: SupportedLang): string {
   const normalizedTag = tag.toLowerCase().replace(/\s+/g, '-');
   const basePath = lang === 'en' ? '/blog/tag' : `/${lang}/blog/tag`;
-  return `${SITE_URL}${basePath}/${normalizedTag}`;
+  return `${SITE_CONFIG.url}${basePath}/${normalizedTag}`;
 }
 
 /**

src/utils/readingTime.ts

@@ -35,6 +35,9 @@ export function getReadingTime(
   const imageCount = imageMatches.length;
 
   // Count code blocks (both fenced and indented)
+  // Note: This regex handles most common cases but may not capture
+  // all edge cases (nested/escaped backticks). For production use with
+  // complex code examples, consider using the MDX AST parser instead.
   const codeBlockMatches =
     content.match(/```[\s\S]*?```|~~~[\s\S]*?~~~/g) || [];
   const codeBlockCount = codeBlockMatches.length;

src/utils/relatedPosts.ts

@@ -38,21 +38,41 @@ function calculateTagSimilarity(tagsA: string[], tagsB: string[]): number {
   return intersection.size / union.size;
 }
 
+// Recency scoring thresholds (in days)
+const RECENCY_THRESHOLDS = {
+  VERY_RECENT: 30, // Within 30 days = max score
+  RECENT: 90, // Within 90 days = high score
+  MODERATE: 180, // Within 180 days = medium score
+  OLD: 365, // Within 365 days = low score
+} as const;
+
+// Recency scores for each threshold
+const RECENCY_SCORES = {
+  VERY_RECENT: 1.0,
+  RECENT: 0.8,
+  MODERATE: 0.6,
+  OLD: 0.4,
+  VERY_OLD: 0.2,
+} as const;
+
 /**
  * Calculate recency score (0-1 scale)
- * More recent posts get higher scores
+ * Scores posts based on temporal proximity to reference date
+ * Posts closer in time to the reference get higher scores
  */
-function calculateRecencyScore(postDate: Date, newestDate: Date): number {
+function calculateRecencyScore(postDate: Date, referenceDate: Date): number {
+  const MS_PER_DAY = 1000 * 60 * 60 * 24;
   const daysDiff = Math.abs(
-    (newestDate.getTime() - postDate.getTime()) / (1000 * 60 * 60 * 24)
+    (referenceDate.getTime() - postDate.getTime()) / MS_PER_DAY
   );
 
-  // Posts within 30 days get max score, older posts decay
-  if (daysDiff <= 30) return 1;
-  if (daysDiff <= 90) return 0.8;
-  if (daysDiff <= 180) return 0.6;
-  if (daysDiff <= 365) return 0.4;
-  return 0.2;
+  // Posts within thresholds get corresponding scores
+  if (daysDiff <= RECENCY_THRESHOLDS.VERY_RECENT)
+    return RECENCY_SCORES.VERY_RECENT;
+  if (daysDiff <= RECENCY_THRESHOLDS.RECENT) return RECENCY_SCORES.RECENT;
+  if (daysDiff <= RECENCY_THRESHOLDS.MODERATE) return RECENCY_SCORES.MODERATE;
+  if (daysDiff <= RECENCY_THRESHOLDS.OLD) return RECENCY_SCORES.OLD;
+  return RECENCY_SCORES.VERY_OLD;
 }
 
 /**
@@ -85,16 +105,10 @@ export function getRelatedPosts(
     return true;
   });
 
-  // Find newest post date for recency calculation
-  const newestDate = new Date(
-    Math.max(
-      ...candidates.map((p) =>
-        p.data.updatedDate
-          ? p.data.updatedDate.getTime()
-          : p.data.pubDate.getTime()
-      )
-    )
-  );
+  // Use current post's date as reference for recency calculation
+  // This ensures related posts are relative to the current post's timeframe
+  const currentPostDate =
+    currentPost.data.updatedDate || currentPost.data.pubDate;
 
   // Calculate similarity scores
   const scoredPosts: RelatedPost[] = candidates.map((post) => {
@@ -104,7 +118,7 @@ export function getRelatedPosts(
     );
 
     const postDate = post.data.updatedDate || post.data.pubDate;
-    const recencyScore = calculateRecencyScore(postDate, newestDate);
+    const recencyScore = calculateRecencyScore(postDate, currentPostDate);
 
     // Weighted score: configurable weights
     const score =
@@ -125,6 +139,12 @@ export function getRelatedPosts(
 
 /**
  * Get posts by specific tag
+ * @param allPosts - All blog posts to filter
+ * @param tag - The tag to filter by (case-insensitive)
+ * @param excludeDrafts - Whether to exclude draft posts (defaults to true)
+ * @returns Array of posts with the specified tag, sorted by date (newest first)
+ * @example
+ * const typescriptPosts = getPostsByTag(allPosts, 'TypeScript');
  */
 export function getPostsByTag(
   allPosts: BlogPost[],
@@ -145,6 +165,12 @@ export function getPostsByTag(
 
 /**
  * Get all unique tags from posts with counts
+ * @param posts - All blog posts to extract tags from
+ * @param excludeDrafts - Whether to exclude draft posts (defaults to true)
+ * @returns Map of normalized tag names to their occurrence counts, sorted by count (descending)
+ * @example
+ * const tagCounts = getAllTags(allPosts);
+ * // Map { 'typescript' => 5, 'javascript' => 3, 'react' => 2 }
  */
 export function getAllTags(
   posts: BlogPost[],

tests/blog.spec.ts

@@ -196,16 +196,25 @@ test.describe('Blog', () => {
       }
     });
 
-    test.skip('language switcher falls back to blog listing when translation unavailable', async ({
-      page,
-    }) => {
-      // Skip: Portuguese language switcher test needs more investigation
+    test('language switcher provides Portuguese option', async ({ page }) => {
       await page.goto('/blog');
       await page.locator('.post-card__title a').first().click();
+      await page.waitForLoadState('networkidle');
 
-      // Try to switch to Portuguese
-      await page.getByRole('button', { name: 'Change language' }).click();
-      // Portuguese option may not be immediately visible
+      // Open language switcher (use first one - desktop navbar)
+      await page
+        .getByRole('button', { name: 'Change language' })
+        .first()
+        .click();
+
+      // Portuguese link should be visible and have a valid href
+      const ptLink = page.locator('#navbar a[hreflang="pt"]').first();
+      await expect(ptLink).toBeVisible();
+
+      const href = await ptLink.getAttribute('href');
+      expect(href).toBeTruthy();
+      // Href should either point to /pt/blog (fallback) or /pt/blog/[slug] (translation)
+      expect(href).toMatch(/^\/pt\/blog/);
     });
 
     test('language switcher is visible on blog posts', async ({ page }) => {
@@ -345,12 +354,32 @@ test.describe('Blog', () => {
   });
 
   test.describe('Reading Progress', () => {
-    test.skip('reading progress bar is visible on blog posts', async ({
-      page,
-    }) => {
-      // Skip: Component may not be visible depending on page scroll position
+    test('reading progress bar is visible on blog posts', async ({ page }) => {
       await page.goto('/blog');
       await page.locator('.post-card__title a').first().click();
+      await page.waitForLoadState('networkidle');
+
+      // Reading progress bar should exist
+      const progressBar = page.locator('.reading-progress');
+      await expect(progressBar).toBeVisible();
+
+      // Verify ARIA attributes
+      await expect(progressBar).toHaveAttribute('role', 'progressbar');
+      await expect(progressBar).toHaveAttribute('aria-valuemin', '0');
+      await expect(progressBar).toHaveAttribute('aria-valuemax', '100');
+
+      // Scroll down and verify progress updates
+      await page.evaluate(() =>
+        window.scrollTo(0, document.body.scrollHeight / 2)
+      );
+      await page.waitForTimeout(100); // Wait for scroll handler
+
+      // Progress bar inner should have some width
+      const progressBarInner = page.locator('#reading-progress-bar');
+      const width = await progressBarInner.evaluate((el) => {
+        return window.getComputedStyle(el).width;
+      });
+      expect(width).not.toBe('0px');
     });
   });