gbu-accessibility-package 3.8.9 → 3.10.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.10.0] - 2025-12-09
+
+### Added
+- **Meta Tags & Open Graph Protocol Validation**: New `--meta-check` command for comprehensive meta tag validation
+  - **4 Required OG Tags Check**: Validates presence of og:title, og:type, og:image, og:url
+  - **Syntax Validation**: Detects common mistake of using `name=""` instead of `property=""` for OG tags
+  - **Typo Detection**: Detects common typos in property names (og:sitename → og:site_name, og:imge → og:image, etc.)
+  - **Levenshtein Distance Algorithm**: Smart typo detection for unknown OG properties
+  - **Twitter Card Validation**: Checks twitter:card and related tags with valid value validation
+  - **Basic Meta Tags Check**: Validates description, viewport, canonical URL
+  - **Content Quality Check**: Title/description length, URL format, empty values
+  - **og:image Best Practices**: Suggests og:image:width, og:image:height, og:image:alt
+  - **Detailed Suggestions**: Provides specific fix recommendations for each issue
+  - **Summary Statistics**: Shows files with OG, issues count, and warnings count
+
+- **Auto-Fix Meta Tags**: New `--meta-fix` command for automatic fixing
+  - **Typo Auto-Fix**: Automatically corrects misspelled OG/Twitter property names
+  - **Syntax Auto-Fix**: Corrects `name=""` to `property=""` for OG tags
+  - **Dry-Run Support**: Preview changes with `--meta-fix --dry-run`
+  - **Backup Support**: Create backups with `--meta-fix --backup`
+
+### Changed
+- **CLI Simplified**: Removed redundant aliases (`--og-check`, `--check-meta`, `--open-graph`), now using only `--meta-check`
+- **Clear Separation**: `--meta-check` for checking only, `--meta-fix` for auto-fixing
+
+### Technical
+- **New Methods**: `checkMetaTags()`, `analyzeMetaTags()`, `parseMetaTagAttributes()`, `fixMetaTags()`, `findClosestOGProperty()`, `levenshteinDistance()`
+- **Test Files**: Added `demo/meta-tags-test.html` and `demo/meta-tags-incomplete.html` for testing
+- **npm Scripts**: Added `meta-check` and `meta-fix` scripts
+
+
 ## [3.8.3] - 2025-10-06
 
 ### Added

package/README-vi.md

@@ -25,6 +25,8 @@ gbu-a11y --forms-only        # Sửa form labels + dọn dẹpio/js/gbu-accessib
 - 🎯 **Nested Controls Detection** - Phát hiện và sửa các control tương tác lồng nhau
 - 🔍 **Broken Links Detection** - Phát hiện liên kết external bị hỏng
 - 📁 **404 Resources Detection** - Phát hiện tài nguyên local bị thiếu (hình ảnh, CSS, JS, v.v.)
+- 🏷️ **Kiểm tra Google Tag Manager** - Xác thực cài đặt GTM (script + noscript)
+- 🏷️ **Kiểm tra Meta Tags & Open Graph** - Xác thực meta tags theo chuẩn Open Graph Protocol
 - 🗂️ **Unused Files Detection** - Tìm file không được tham chiếu ở đâu trong dự án
 - ☠️ **Dead Code Analysis** - Phát hiện CSS rules và JavaScript functions không sử dụng
 - 📏 **File Size Analysis** - Kiểm tra dung lượng file và đề xuất tối ưu hóa
@@ -162,9 +164,12 @@ Chế độ sửa lỗi:
   --links-check            Kiểm tra liên kết bị hỏng và tài nguyên 404 (toàn diện, không tự động sửa)
   --broken-links           Chỉ kiểm tra liên kết external bị hỏng (không tự động sửa)
   --404-resources          Chỉ kiểm tra tài nguyên local bị thiếu (không tự động sửa)
+  --gtm-check              Kiểm tra cài đặt Google Tag Manager (không tự động sửa)
   --unused-files           Kiểm tra file không sử dụng trong dự án
   --dead-code              Kiểm tra dead code trong CSS và JavaScript
   --file-size, --size-check Kiểm tra dung lượng file và đề xuất tối ưu hóa
+  --meta-check             Kiểm tra Meta Tags và Open Graph Protocol
+  --meta-fix               Tự động sửa lỗi chính tả và cú pháp OG/Twitter
   --cleanup-only           Chỉ dọn dẹp role attributes trùng lặp
 
 Tùy chọn Enhanced Alt:
@@ -199,9 +204,12 @@ gbu-a11y --headings-only --auto-fix-headings  # Tự động sửa heading struc
 gbu-a11y --links-check       # Kiểm tra liên kết bị hỏng và tài nguyên thiếu + dọn dẹp
 gbu-a11y --broken-links      # Chỉ kiểm tra liên kết external bị hỏng + dọn dẹp
 gbu-a11y --404-resources     # Chỉ kiểm tra tài nguyên local bị thiếu + dọn dẹp
+gbu-a11y --gtm-check         # Kiểm tra cài đặt Google Tag Manager
 gbu-a11y --unused-files      # Kiểm tra file không sử dụng trong dự án
 gbu-a11y --dead-code         # Kiểm tra dead CSS và JavaScript code
 gbu-a11y --file-size         # Kiểm tra dung lượng file và đề xuất tối ưu hóa
+gbu-a11y --meta-check        # Kiểm tra Meta Tags và Open Graph Protocol
+gbu-a11y --meta-fix          # Tự động sửa lỗi chính tả và cú pháp OG/Twitter
 
 # Tính năng enhanced alt attribute
 gbu-a11y --enhanced-alt                                    # Chế độ enhanced cơ bản
@@ -373,11 +381,244 @@ await fixer.checkFileSizes('./src');
   - JavaScript functions không bao giờ được gọi trong toàn bộ codebase
   - Variables được khai báo nhưng không sử dụng
   - Smart skipping các patterns động và third-party code
+- **Kiểm tra Google Tag Manager** → Xác thực cài đặt GTM
+  - Phát hiện GTM script trong phần `<head>`
+  - Xác minh noscript fallback trong phần `<body>`
+  - Kiểm tra tính nhất quán của container ID
+  - Xác thực vị trí đặt đúng của cả hai đoạn mã
+  - Báo cáo: cài đặt hoàn chỉnh, thiếu thành phần, vấn đề vị trí
 - **Phân tích dung lượng file** → Kiểm tra kích thước file và đề xuất tối ưu hóa
   - Phát hiện file lớn vượt ngưỡng khuyến nghị
   - Đề xuất tối ưu hóa theo từng loại file (hình ảnh, CSS, JS, v.v.)
   - Thống kê dung lượng theo loại file
   - Top 10 file có dung lượng lớn nhất
+- **Kiểm tra Meta Tags & Open Graph** → Xác thực meta tags theo chuẩn OGP
+  - Kiểm tra 4 thẻ OG bắt buộc: og:title, og:type, og:image, og:url
+  - Phát hiện sai cú pháp (dùng name="" thay vì property="")
+  - **Phát hiện lỗi chính tả** trong tên property (vd: og:sitename → og:site_name)
+  - Kiểm tra Twitter Card tags
+  - Xác thực meta description, viewport, canonical URL
+  - Đề xuất cải thiện SEO và accessibility
+  - **Auto-fix** lỗi chính tả và cú pháp với `--meta-fix`
+
+## 🏷️ Xác thực Meta Tags và Open Graph Protocol
+
+Tính năng `--meta-check` kiểm tra meta tags theo chuẩn Open Graph Protocol.
+Tính năng `--meta-fix` tự động sửa lỗi chính tả và cú pháp OG/Twitter.
+
+### Những gì được kiểm tra
+
+1. **4 thẻ OG bắt buộc**: og:title, og:type, og:image, og:url
+2. **Cú pháp đúng**: OG tags phải dùng `property=""` thay vì `name=""`
+3. **Lỗi chính tả**: Phát hiện typo trong tên property (og:sitename, og:imge, twitter:tittle...)
+4. **Twitter Card**: Kiểm tra twitter:card và các thẻ liên quan
+5. **Meta cơ bản**: description, viewport, canonical URL
+6. **Chất lượng nội dung**: Độ dài, giá trị hợp lệ, URL format
+
+### Cách sử dụng
+
+```bash
+# Kiểm tra meta tags trong toàn bộ dự án
+gbu-a11y --meta-check
+
+# Kiểm tra thư mục cụ thể
+gbu-a11y --meta-check ./public
+
+# Tự động sửa lỗi chính tả và cú pháp OG/Twitter
+gbu-a11y --meta-fix
+
+# Xem trước trước khi sửa
+gbu-a11y --meta-fix --dry-run
+```
+
+### Ví dụ kết quả
+
+```
+🏷️  Đang kiểm tra Meta Tags và Open Graph Protocol...
+
+📁 index.html:
+  ✅ Open Graph Protocol: Đã cài đặt
+    ✅ og:title: Trang chủ - GBU Tool
+    ✅ og:type: website
+    ✅ og:image: https://example.com/og-image.jpg
+    ✅ og:url: https://example.com/
+  ✅ Twitter Card: Đã cài đặt
+
+📁 about.html:
+  ⚠️ Open Graph Protocol: Chưa cài đặt
+  ❌ Thiếu thẻ OG bắt buộc: Thiếu og:title
+    💡 Thêm <meta property="og:title" content="...">
+  ❌ Sai cú pháp OG: og:image sử dụng name="" thay vì property=""
+    💡 Thay đổi từ <meta name="og:image" ...> thành <meta property="og:image" ...>
+  ⚠️ Thiếu Meta Description: Không tìm thấy thẻ meta description
+    💡 Thêm <meta name="description" content="Mô tả trang web của bạn">
+
+📊 Tóm tắt: Đã phân tích 2 file
+  ✅ File có Open Graph: 1
+  ❌ File có lỗi: 1 (3 vấn đề)
+  ⚠️ File có cảnh báo: 1 (1 cảnh báo)
+💡 Open Graph Protocol cần có 4 thẻ bắt buộc: og:title, og:type, og:image, og:url
+```
+
+### Yêu cầu Open Graph Protocol
+
+Để cài đặt OG tags đúng cách, mỗi trang cần có:
+
+```html
+<head>
+  <!-- Meta cơ bản -->
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="description" content="Mô tả ngắn gọn về trang">
+  <title>Tiêu đề trang</title>
+  
+  <!-- Open Graph Protocol (bắt buộc) -->
+  <meta property="og:title" content="Tiêu đề trang">
+  <meta property="og:type" content="website">
+  <meta property="og:image" content="https://example.com/images/og-image.jpg">
+  <meta property="og:url" content="https://example.com/your-page">
+  
+  <!-- Open Graph Protocol (khuyến nghị) -->
+  <meta property="og:description" content="Mô tả chi tiết">
+  <meta property="og:site_name" content="Tên website">
+  <meta property="og:locale" content="vi_VN">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta property="og:image:alt" content="Mô tả hình ảnh">
+  
+  <!-- Twitter Card -->
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Tiêu đề trang">
+  <meta name="twitter:description" content="Mô tả">
+  <meta name="twitter:image" content="https://example.com/images/twitter.jpg">
+  
+  <!-- Canonical URL -->
+  <link rel="canonical" href="https://example.com/your-page">
+</head>
+```
+
+### Các vấn đề thường gặp được phát hiện
+
+- ❌ **Thiếu thẻ OG bắt buộc**: og:title, og:type, og:image, og:url
+- ❌ **Sai cú pháp OG**: Dùng `name="og:..."` thay vì `property="og:..."` (✅ tự động sửa)
+- ❌ **Lỗi chính tả OG/Twitter**: og:sitename, og:imge, twitter:tittle... (✅ tự động sửa)
+- ❌ **Giá trị rỗng**: Thẻ meta có content rỗng
+- ❌ **og:url không hợp lệ**: URL không bắt đầu bằng http:// hoặc https://
+- ❌ **twitter:card không hợp lệ**: Giá trị không phải summary, summary_large_image, app, player
+- ⚠️ **og:image không phải URL tuyệt đối**: Nên dùng URL đầy đủ
+- ⚠️ **Thiếu kích thước og:image**: Chưa khai báo og:image:width, og:image:height
+- ⚠️ **Thiếu og:image:alt**: Chưa có mô tả accessibility cho hình ảnh OG
+- ⚠️ **Title/Description quá dài/ngắn**: Ảnh hưởng đến SEO
+- ⚠️ **Thiếu Canonical URL**: Link rel="canonical" chưa được khai báo
+- ⚠️ **Thiếu Twitter Card**: Đã có OG nhưng chưa có Twitter Card
+
+### Lỗi chính tả được phát hiện và tự động sửa
+
+Công cụ sử dụng **thuật toán Levenshtein Distance** để phát hiện **TẤT CẢ** các lỗi chính tả, không chỉ các lỗi đã được định nghĩa sẵn.
+
+#### Cách hoạt động:
+1. **Danh sách lỗi phổ biến** - Phát hiện nhanh các lỗi đã biết (og:sitename, og:imge...)
+2. **Thuật toán Levenshtein** - So sánh với danh sách property hợp lệ và tìm gợi ý gần nhất
+3. **Ngưỡng động** - Dựa trên độ dài property để quyết định có phải typo hay không
+
+#### Ví dụ các lỗi được phát hiện tự động:
+
+| Lỗi chính tả | Sửa thành | Phương pháp |
+|--------------|-----------|-------------|
+| og:sitename | og:site_name | Danh sách cố định |
+| og:imge | og:image | Danh sách cố định |
+| og:ttle | og:title | Levenshtein (distance=1) |
+| og:descritpion | og:description | Levenshtein (distance=2) |
+| og:locle | og:locale | Levenshtein (distance=1) |
+| og:image:wdth | og:image:width | Levenshtein (distance=1) |
+| twitter:descrption | twitter:description | Levenshtein (distance=1) |
+| twitter:imag | twitter:image | Levenshtein (distance=1) |
+| name="og:..." | property="og:..." | Sai cú pháp |
+
+💡 **Mọi property OG/Twitter không hợp lệ đều được kiểm tra và đề xuất sửa!**
+
+## 🏷️ Xác thực Google Tag Manager
+
+### Những gì được kiểm tra
+
+1. **Script trong `<head>`**: Xác minh GTM script có mặt trước thẻ đóng `</head>`
+2. **Noscript trong `<body>`**: Xác nhận noscript fallback ngay sau thẻ mở `<body>`
+3. **Container ID**: Đảm bảo cả hai đoạn mã sử dụng cùng GTM container ID (định dạng: GTM-XXXXXX)
+4. **Xác thực vị trí**: Kiểm tra vị trí tối ưu của cả hai đoạn mã
+
+### Cách sử dụng
+
+```bash
+# Kiểm tra cài đặt GTM trong toàn bộ dự án
+gbu-a11y --gtm-check
+
+# Kiểm tra thư mục cụ thể
+gbu-a11y --gtm-check ./public
+
+# Các lệnh thay thế
+gbu-a11y --check-gtm
+gbu-a11y --google-tag-manager
+```
+
+### Ví dụ kết quả
+
+```
+🏷️ Đang kiểm tra cài đặt Google Tag Manager (GTM)...
+
+📁 public/index.html:
+  ✅ GTM Container ID: GTM-ABC1234
+  ✅ Script trong head: Đã đặt đúng vị trí trước </head>
+  ✅ Noscript trong body: Đã đặt đúng vị trí sau <body>
+
+📁 public/about.html:
+  ✅ GTM Container ID: GTM-ABC1234
+  ✅ Script trong head: Đã đặt đúng vị trí trước </head>
+  ❌ Noscript trong body: Thiếu sau thẻ <body>
+  ❌ Thiếu GTM Noscript: Tìm thấy GTM script nhưng thiếu noscript dự phòng trong <body>
+    💡 Thêm đoạn mã GTM noscript ngay sau thẻ mở <body>
+
+📊 Tóm tắt: Đã phân tích 2 file
+  ✅ File có GTM: 2
+  ⚠️ File có vấn đề về GTM: 1
+💡 GTM cần có cả <script> trong <head> và <noscript> sau <body>
+```
+
+### Yêu cầu cài đặt GTM
+
+Để cài đặt GTM đúng cách, mỗi trang cần có:
+
+1. **Đoạn mã script trong `<head>`**:
+```html
+<head>
+  <!-- Google Tag Manager -->
+  <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+  new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+  j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+  'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+  })(window,document,'script','dataLayer','GTM-XXXXXX');</script>
+  <!-- End Google Tag Manager -->
+</head>
+```
+
+2. **Đoạn mã noscript ngay sau `<body>`**:
+```html
+<body>
+  <!-- Google Tag Manager (noscript) -->
+  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXX"
+  height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
+  <!-- End Google Tag Manager (noscript) -->
+  
+  <!-- Nội dung trang của bạn -->
+</body>
+```
+
+### Các vấn đề thường gặp được phát hiện
+
+- ❌ **Thiếu Script**: Không tìm thấy GTM script trong `<head>`
+- ❌ **Thiếu Noscript**: Không tìm thấy noscript fallback sau `<body>`
+- ⚠️ **Vị trí sai**: Script hoặc noscript không ở vị trí tối ưu
+- ❌ **ID không khớp**: Container ID khác nhau giữa script và noscript
+- ⚠️ **Cài đặt không đầy đủ**: Chỉ có một trong hai đoạn mã bắt buộc
 
 ## 🔧 Quản lý Package
 

package/README.md

@@ -22,6 +22,7 @@
 - 🎯 **Nested Controls Detection** - Detect and fix nested interactive controls
 - 🔍 **Broken Links Detection** - Detect broken external links
 - 📁 **404 Resources Detection** - Detect missing local resources (images, CSS, JS, etc.)
+- 🏷️ **Google Tag Manager Check** - Validate GTM installation (script + noscript)
 - 🗂️ **Unused Files Detection** - Find files not referenced anywhere in the project
 - ☠️ **Dead Code Analysis** - Detect unused CSS rules and JavaScript functions
 - 📏 **File Size Analysis** - Check file sizes and suggest optimizations
@@ -154,9 +155,10 @@ Fix Modes:
   --landmarks-only         Fix landmarks + cleanup
   --headings-only          Analyze heading structure with optional auto-fix
   --auto-fix-headings      Enable automatic heading structure fixes
-    --links-check            Check for broken links and 404 resources (comprehensive, no auto-fix)
+  --links-check            Check for broken links and 404 resources (comprehensive, no auto-fix)
   --broken-links           Check for broken external links only (no auto-fix)
   --404-resources          Check for missing local resources only (no auto-fix)
+  --gtm-check              Check Google Tag Manager installation (no auto-fix)
   --unused-files           Check for unused files in project
   --dead-code              Check for dead code in CSS and JavaScript
   --file-size, --size-check Check file sizes and suggest optimizations
@@ -195,6 +197,7 @@ gbu-a11y --headings-only --auto-fix-headings  # Auto-fix heading structure
 gbu-a11y --links-check       # Check broken links and missing resources + cleanup
 gbu-a11y --broken-links      # Check broken external links only + cleanup
 gbu-a11y --404-resources     # Check missing local resources only + cleanup
+gbu-a11y --gtm-check         # Check Google Tag Manager installation
 gbu-a11y --unused-files      # Check for unused files in project
 gbu-a11y --dead-code         # Check for dead CSS and JavaScript code
 gbu-a11y --file-size         # Check file sizes and suggest optimizations
@@ -357,12 +360,103 @@ await fixer.checkFileSizes('./src');
   - JavaScript functions never called
   - Variables declared but never used
   - Smart skipping of dynamic patterns
+- **Google Tag Manager Check** → Validate GTM installation
+  - Detect GTM script in `<head>` section
+  - Verify noscript fallback in `<body>` section
+  - Check container ID consistency
+  - Validate proper positioning of both snippets
+  - Reports: complete installation, missing components, position issues
 - **File Size Analysis** → Check file sizes and suggest optimizations
   - Detect large files exceeding recommended thresholds
   - Type-specific optimization suggestions (images, CSS, JS, etc.)
   - File size breakdown by type
   - Top 10 largest files reporting
 
+## 🏷️ Google Tag Manager Validation
+
+The `--gtm-check` feature validates proper Google Tag Manager installation across your project.
+
+### What It Checks
+
+1. **Script in `<head>`**: Verifies GTM script is present before `</head>` closing tag
+2. **Noscript in `<body>`**: Confirms noscript fallback is immediately after `<body>` opening tag
+3. **Container ID**: Ensures both snippets use the same GTM container ID (format: GTM-XXXXXX)
+4. **Position Validation**: Checks optimal placement of both code snippets
+
+### Usage
+
+```bash
+# Check GTM installation in entire project
+gbu-a11y --gtm-check
+
+# Check specific directory
+gbu-a11y --gtm-check ./public
+
+# Alternative commands
+gbu-a11y --check-gtm
+gbu-a11y --google-tag-manager
+```
+
+### Example Output
+
+```
+🏷️ Đang kiểm tra cài đặt Google Tag Manager (GTM)...
+
+📁 public/index.html:
+  ✅ GTM Container ID: GTM-ABC1234
+  ✅ Script trong head: Đã đặt đúng vị trí trước </head>
+  ✅ Noscript trong body: Đã đặt đúng vị trí sau <body>
+
+📁 public/about.html:
+  ✅ GTM Container ID: GTM-ABC1234
+  ✅ Script trong head: Đã đặt đúng vị trí trước </head>
+  ❌ Noscript trong body: Thiếu sau thẻ <body>
+  ❌ Thiếu GTM Noscript: Tìm thấy GTM script nhưng thiếu noscript dự phòng trong <body>
+    💡 Thêm đoạn mã GTM noscript ngay sau thẻ mở <body>
+
+📊 Tóm tắt: Đã phân tích 2 file
+  ✅ File có GTM: 2
+  ⚠️ File có vấn đề về GTM: 1
+💡 GTM cần có cả <script> trong <head> và <noscript> sau <body>
+```
+
+### GTM Installation Requirements
+
+For proper GTM installation, each page should have:
+
+1. **Script snippet in `<head>`**:
+```html
+<head>
+  <!-- Google Tag Manager -->
+  <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+  new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+  j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+  'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+  })(window,document,'script','dataLayer','GTM-XXXXXX');</script>
+  <!-- End Google Tag Manager -->
+</head>
+```
+
+2. **Noscript snippet immediately after `<body>`**:
+```html
+<body>
+  <!-- Google Tag Manager (noscript) -->
+  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXX"
+  height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
+  <!-- End Google Tag Manager (noscript) -->
+  
+  <!-- Your page content -->
+</body>
+```
+
+### Common Issues Detected
+
+- ❌ **Missing Script**: GTM script not found in `<head>`
+- ❌ **Missing Noscript**: Noscript fallback not found after `<body>`
+- ⚠️ **Wrong Position**: Script or noscript not in optimal position
+- ❌ **ID Mismatch**: Different container IDs between script and noscript
+- ⚠️ **Incomplete Installation**: Only one of the two required snippets present
+
 ## 🔧 Package Management
 
 ### Check package information