gbu-accessibility-package 3.12.1 → 3.13.0

package/index.js

@@ -1,3 +1,6 @@
-const AccessibilityFixer = require('./lib/fixer.js');
+const AccessibilityChecker = require('./lib/checker.js');
 
-module.exports = { AccessibilityFixer };
+module.exports = {
+  AccessibilityChecker,
+  AccessibilityFixer: AccessibilityChecker
+};

package/lib/checker.js

@@ -0,0 +1,233 @@
+const AccessibilityFixer = require('./fixer.js');
+
+class AccessibilityChecker extends AccessibilityFixer {
+  constructor(config = {}) {
+    super({
+      ...config,
+      dryRun: true,
+      backupFiles: false,
+      autoFixHeadings: false
+    });
+  }
+
+  transformLogValue(value) {
+    if (typeof value !== 'string') {
+      return value;
+    }
+
+    return value
+      .replace(/Đang sửa/g, 'Đang kiểm tra')
+      .replace(/Fixing/g, 'Checking')
+      .replace(/✅ Fixed/g, '✅ Reported')
+      .replace(/Files fixed/g, 'Files with findings')
+      .replace(/files fixed/g, 'files with findings')
+      .replace(/Tự động sửa/g, 'Rà soát')
+      .replace(/Sử dụng --meta-fix để tự động sửa các lỗi này/g, 'Các lỗi meta cần được review và xử lý thủ công')
+      .replace(/Use without --dry-run to apply changes\./g, 'Source files are never modified.');
+  }
+
+  async withCheckOnlyLogging(task) {
+    const originalLog = console.log;
+    const originalError = console.error;
+
+    console.log = (...messages) => originalLog(...messages.map((message) => this.transformLogValue(message)));
+    console.error = (...messages) => originalError(...messages.map((message) => this.transformLogValue(message)));
+
+    try {
+      return await task();
+    } finally {
+      console.log = originalLog;
+      console.error = originalError;
+    }
+  }
+
+  normalizeSimulationResults(results = []) {
+    return results.map((result) => {
+      if (result.status === 'fixed') {
+        return {
+          ...result,
+          status: 'issue-found',
+          rawStatus: result.status
+        };
+      }
+
+      if (result.status === 'no-change') {
+        return {
+          ...result,
+          status: 'clean',
+          rawStatus: result.status
+        };
+      }
+
+      return result;
+    });
+  }
+
+  async checkLang(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixHtmlLang(directory)));
+  }
+
+  async checkAltText(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixEmptyAltAttributes(directory)));
+  }
+
+  async checkRoles(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixRoleAttributes(directory)));
+  }
+
+  async checkAriaLabels(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixAriaLabels(directory)));
+  }
+
+  async checkForms(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixFormLabels(directory)));
+  }
+
+  async checkNestedControls(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixNestedInteractiveControls(directory)));
+  }
+
+  async checkButtons(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixButtonNames(directory)));
+  }
+
+  async checkLinks(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixLinkNames(directory)));
+  }
+
+  async checkLandmarks(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixLandmarks(directory)));
+  }
+
+  async checkHeadings(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixHeadingStructure(directory)));
+  }
+
+  async checkDescriptionLists(directory = '.') {
+    return this.withCheckOnlyLogging(async () => this.normalizeSimulationResults(await super.fixDescriptionLists(directory)));
+  }
+
+  async checkLinksAndResources(directory = '.') {
+    return this.withCheckOnlyLogging(async () => {
+      const [brokenLinks, missingResources] = await Promise.all([
+        this.checkBrokenLinks(directory),
+        this.check404Resources(directory)
+      ]);
+
+      return {
+        brokenLinks,
+        missingResources
+      };
+    });
+  }
+
+  async previewUnusedFilesListRemoval(directory = '.', listFile = 'unused-files-list.txt') {
+    return this.withCheckOnlyLogging(async () => super.deleteUnusedFilesFromList(directory, listFile, { dryRun: true }));
+  }
+
+  async checkMetaTags(directory = '.') {
+    return this.withCheckOnlyLogging(async () => super.checkMetaTags(directory));
+  }
+
+  async checkUnusedFiles(directory = '.') {
+    return this.withCheckOnlyLogging(async () => super.checkUnusedFiles(directory));
+  }
+
+  async generateUnusedFilesList(directory = '.', listFile = 'unused-files-list.txt') {
+    return this.withCheckOnlyLogging(async () => super.generateUnusedFilesList(directory, listFile));
+  }
+
+  async checkDeadCode(directory = '.') {
+    return this.withCheckOnlyLogging(async () => super.checkDeadCode(directory));
+  }
+
+  async checkFileSizes(directory = '.') {
+    return this.withCheckOnlyLogging(async () => super.checkFileSizes(directory));
+  }
+
+  async checkGoogleTagManager(directory = '.') {
+    return this.withCheckOnlyLogging(async () => super.checkGoogleTagManager(directory));
+  }
+
+  async generateFullReport(directory = '.', outputPath = null) {
+    return this.withCheckOnlyLogging(async () => super.generateFullReport(directory, outputPath));
+  }
+
+  async runComprehensiveChecks(directory = '.') {
+    const results = {};
+
+    results.lang = await this.checkLang(directory);
+    results.alt = await this.checkAltText(directory);
+    results.roles = await this.checkRoles(directory);
+    results.ariaLabels = await this.checkAriaLabels(directory);
+    results.forms = await this.checkForms(directory);
+    results.nestedControls = await this.checkNestedControls(directory);
+    results.buttons = await this.checkButtons(directory);
+    results.links = await this.checkLinks(directory);
+    results.landmarks = await this.checkLandmarks(directory);
+    results.headings = await this.checkHeadings(directory);
+    results.descriptionLists = await this.checkDescriptionLists(directory);
+    results.externalLinks = await this.withCheckOnlyLogging(async () => this.checkBrokenLinks(directory));
+    results.missingResources = await this.withCheckOnlyLogging(async () => this.check404Resources(directory));
+
+    return results;
+  }
+
+  async fixHtmlLang(directory = '.') {
+    return this.checkLang(directory);
+  }
+
+  async fixEmptyAltAttributes(directory = '.') {
+    return this.checkAltText(directory);
+  }
+
+  async fixRoleAttributes(directory = '.') {
+    return this.checkRoles(directory);
+  }
+
+  async fixAriaLabels(directory = '.') {
+    return this.checkAriaLabels(directory);
+  }
+
+  async fixFormLabels(directory = '.') {
+    return this.checkForms(directory);
+  }
+
+  async fixNestedInteractiveControls(directory = '.') {
+    return this.checkNestedControls(directory);
+  }
+
+  async fixButtonNames(directory = '.') {
+    return this.checkButtons(directory);
+  }
+
+  async fixLinkNames(directory = '.') {
+    return this.checkLinks(directory);
+  }
+
+  async fixLandmarks(directory = '.') {
+    return this.checkLandmarks(directory);
+  }
+
+  async fixHeadingStructure(directory = '.') {
+    return this.checkHeadings(directory);
+  }
+
+  async fixDescriptionLists(directory = '.') {
+    return this.checkDescriptionLists(directory);
+  }
+
+  async fixMetaTags(directory = '.') {
+    return this.checkMetaTags(directory);
+  }
+
+  async fixAllAccessibilityIssues(directory = '.') {
+    return this.runComprehensiveChecks(directory);
+  }
+
+  async deleteUnusedFilesFromList(directory = '.', listFile = 'unused-files-list.txt') {
+    return this.previewUnusedFilesListRemoval(directory, listFile);
+  }
+}
+
+module.exports = AccessibilityChecker;

package/lib/fixer.js

@@ -1229,18 +1229,22 @@ class EnhancedAltChecker {
 class AccessibilityFixer {
   constructor(config = {}) {
     this.config = {
-      backupFiles: config.backupFiles === true,
+      backupFiles: false,
       language: config.language || 'ja',
-      dryRun: config.dryRun || false,
+      dryRun: true,
       enhancedAltMode: config.enhancedAltMode || false,
       altCreativity: config.altCreativity || 'balanced', // conservative, balanced, creative
       includeEmotions: config.includeEmotions || false,
       strictAltChecking: config.strictAltChecking || false,
-      // New options for advanced features
-      autoFixHeadings: config.autoFixHeadings || false, // Enable automatic heading fixes
-      fixDescriptionLists: config.fixDescriptionLists || true, // Enable DL structure fixes
+      autoFixHeadings: false,
+      fixDescriptionLists: config.fixDescriptionLists !== false,
+      checkOnlyMode: true,
       ...config
     };
+    this.config.backupFiles = false;
+    this.config.dryRun = true;
+    this.config.autoFixHeadings = false;
+    this.config.checkOnlyMode = true;
     
     // Initialize enhanced alt tools
     this.enhancedAltChecker = new EnhancedAltChecker({
@@ -5886,108 +5890,8 @@ class AccessibilityFixer {
 
   // Fix meta tags in HTML files
   async fixMetaTags(directory = '.', options = {}) {
-    const { dryRun = false, backup = false } = options;
-    console.log(chalk.blue('🔧 Fixing meta tag typos and syntax errors...'));
-    
-    const htmlFiles = await this.findHtmlFiles(directory);
-    let totalFiles = 0;
-    let fixedFiles = 0;
-    let skippedFiles = 0;
-    let totalFixes = 0;
-    
-    for (const file of htmlFiles) {
-      try {
-        const content = await fs.readFile(file, 'utf8');
-        const analysis = this.analyzeMetaTags(content, file);
-        const relativePath = path.relative(directory, file);
-        
-        if (analysis.isIncludeFile) {
-          skippedFiles++;
-          console.log(chalk.gray(`⏭️  Skipped: ${relativePath} (include file)`));
-          continue;
-        }
-        
-        totalFiles++;
-        
-        if (analysis.fixable.length === 0) {
-          console.log(chalk.green(`✅ ${relativePath} - No errors to fix`));
-          continue;
-        }
-        
-        console.log(chalk.yellow(`\n🔧 Fixing: ${relativePath}`));
-        
-        let newContent = content;
-        let fixCount = 0;
-        
-        // Group fixes by tag to handle multiple fixes on same tag
-        const tagFixes = new Map();
-        for (const fix of analysis.fixable) {
-          if (!tagFixes.has(fix.fullTag)) {
-            tagFixes.set(fix.fullTag, []);
-          }
-          tagFixes.get(fix.fullTag).push(fix);
-        }
-        
-        // Apply all fixes for each tag
-        for (const [originalTag, fixes] of tagFixes) {
-          let newTag = originalTag;
-          
-          for (const fix of fixes) {
-            if (fix.type === 'property') {
-              // Fix property name typo
-              newTag = newTag.replace(
-                new RegExp(`((?:name|property)\\s*=\\s*["'])${fix.wrong.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(["'])`, 'i'),
-                `$1${fix.correct}$2`
-              );
-              console.log(chalk.green(`   ✓ Fixed property: ${fix.wrong} → ${fix.correct}`));
-              fixCount++;
-            } else if (fix.type === 'content') {
-              // Fix content value typo
-              newTag = newTag.replace(
-                new RegExp(`(content\\s*=\\s*["'])${fix.wrong.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(["'])`, 'i'),
-                `$1${fix.correct}$2`
-              );
-              console.log(chalk.green(`   ✓ Fixed ${fix.property} value: ${fix.wrong} → ${fix.correct}`));
-              fixCount++;
-            }
-          }
-          
-          // Replace the original tag with the fixed tag
-          newContent = newContent.replace(originalTag, newTag);
-        }
-        
-        // Save file if modified
-        if (fixCount > 0) {
-          if (!dryRun) {
-            // Create backup if enabled
-            if (backup) {
-              const backupPath = `${file}.bak`;
-              await fs.writeFile(backupPath, content, 'utf8');
-            }
-            
-            await fs.writeFile(file, newContent, 'utf8');
-            console.log(chalk.green(`   💾 Saved ${fixCount} fix(es) to ${relativePath}`));
-            fixedFiles++;
-            totalFixes += fixCount;
-          } else {
-            console.log(chalk.blue(`   🔍 Dry run - would fix ${fixCount} error(s) in ${relativePath}`));
-            totalFixes += fixCount;
-          }
-        }
-      } catch (error) {
-        console.log(chalk.red(`❌ Error processing ${file}: ${error.message}`));
-      }
-    }
-    
-    console.log(chalk.blue('\n📊 Summary:'));
-    console.log(`   Total files checked: ${totalFiles}`);
-    console.log(`   Files skipped (includes): ${skippedFiles}`);
-    console.log(chalk.green(`   Files fixed: ${fixedFiles}`));
-    console.log(chalk.green(`   Total fixes applied: ${totalFixes}`));
-    
-    if (dryRun) {
-      console.log(chalk.blue('\n💡 This was a dry run. Use without --dry-run to apply changes.'));
-    }
+    console.log(chalk.yellow('⚠️ Check-only mode: auto-fixing meta tags has been removed. Running analysis only.'));
+    return this.checkMetaTags(directory, options);
   }
 
   // Check for unused files in the project - enhanced for comprehensive project-wide scanning
@@ -6106,7 +6010,7 @@ class AccessibilityFixer {
   async deleteUnusedFilesFromList(directory = '.', listFile = 'unused-files-list.txt', options = {}) {
     const scanDirectory = path.resolve(directory);
     const listPath = this.resolveUnusedFilesListPath(scanDirectory, listFile);
-    const dryRun = Boolean(options.dryRun);
+    const dryRun = true;
     const deletedFiles = [];
     const missingFiles = [];
     const skippedEntries = [];
@@ -6151,10 +6055,6 @@ class AccessibilityFixer {
           continue;
         }
 
-        if (!dryRun) {
-          await fs.unlink(resolvedPath);
-        }
-
         deletedFiles.push({
           path: resolvedPath,
           relativePath: relativeToScan.replace(/\\/g, '/')
@@ -7804,6 +7704,7 @@ class AccessibilityFixer {
         { header: 'Loại lỗi', key: 'type', width: 20 },
         { header: 'Mô tả', key: 'description', width: 60 },
         { header: 'Element', key: 'element', width: 40 },
+        { header: 'Gợi ý xử lý', key: 'suggestion', width: 50 },
         { header: 'Mức độ', key: 'severity', width: 15 }
       ];
       
@@ -7819,6 +7720,7 @@ class AccessibilityFixer {
             type: issue.type,
             description: issue.description,
             element: issue.element || '',
+            suggestion: this.getAccessibilitySuggestion(issue),
             severity: '❌ Lỗi'
           });
           row.getCell('severity').style = errorStyle;
@@ -7826,7 +7728,7 @@ class AccessibilityFixer {
         }
       }
       
-      accessSheet.autoFilter = 'A1:E1';
+      accessSheet.autoFilter = 'A1:F1';
       console.log(chalk.green(`  ✅ Accessibility: ${accessResults.length} file có vấn đề`));
     } catch (error) {
       console.log(chalk.yellow(`  ⚠️ Accessibility: ${error.message}`));
@@ -7844,6 +7746,7 @@ class AccessibilityFixer {
         { header: 'Loại lỗi', key: 'type', width: 25 },
         { header: 'Mô tả', key: 'description', width: 60 },
         { header: 'Element', key: 'element', width: 40 },
+        { header: 'Gợi ý xử lý', key: 'suggestion', width: 50 },
         { header: 'Mức độ', key: 'severity', width: 15 }
       ];
       
@@ -7859,6 +7762,7 @@ class AccessibilityFixer {
             type: issue.type,
             description: issue.description,
             element: issue.element || '',
+            suggestion: this.getFormSuggestion(issue),
             severity: '❌ Lỗi'
           });
           row.getCell('severity').style = errorStyle;
@@ -7866,7 +7770,7 @@ class AccessibilityFixer {
         }
       }
       
-      formsSheet.autoFilter = 'A1:E1';
+      formsSheet.autoFilter = 'A1:F1';
       console.log(chalk.green(`  ✅ Forms: ${formsResults.length} file có vấn đề`));
     } catch (error) {
       console.log(chalk.yellow(`  ⚠️ Forms: ${error.message}`));
@@ -7884,6 +7788,7 @@ class AccessibilityFixer {
         { header: 'Loại lỗi', key: 'type', width: 25 },
         { header: 'Mô tả', key: 'description', width: 60 },
         { header: 'Element', key: 'element', width: 40 },
+        { header: 'Gợi ý xử lý', key: 'suggestion', width: 50 },
         { header: 'Mức độ', key: 'severity', width: 15 }
       ];
       
@@ -7899,6 +7804,7 @@ class AccessibilityFixer {
             type: issue.type,
             description: issue.description,
             element: issue.element || '',
+            suggestion: this.getButtonSuggestion(issue),
             severity: '❌ Lỗi'
           });
           row.getCell('severity').style = errorStyle;
@@ -7906,7 +7812,7 @@ class AccessibilityFixer {
         }
       }
       
-      buttonsSheet.autoFilter = 'A1:E1';
+      buttonsSheet.autoFilter = 'A1:F1';
       console.log(chalk.green(`  ✅ Buttons: ${buttonsResults.length} file có vấn đề`));
     } catch (error) {
       console.log(chalk.yellow(`  ⚠️ Buttons: ${error.message}`));
@@ -7970,7 +7876,8 @@ class AccessibilityFixer {
         { header: 'URL/Đường dẫn', key: 'url', width: 60 },
         { header: 'Loại', key: 'type', width: 20 },
         { header: 'Trạng thái', key: 'status', width: 15 },
-        { header: 'Mô tả', key: 'description', width: 40 }
+        { header: 'Mô tả', key: 'description', width: 40 },
+        { header: 'Gợi ý xử lý', key: 'suggestion', width: 50 }
       ];
       
       linksSheet.getRow(1).eachCell(cell => {
@@ -7983,7 +7890,8 @@ class AccessibilityFixer {
           url: link.url,
           type: 'External Link',
           status: link.status || 'Broken',
-          description: link.error || 'Link không thể truy cập'
+          description: link.error || 'Link không thể truy cập',
+          suggestion: link.suggestion || this.getLinkReportSuggestion(link, 'external')
         });
         row.getCell('status').style = errorStyle;
         allResults.summary.totalIssues++;
@@ -7995,13 +7903,14 @@ class AccessibilityFixer {
           url: resource.path,
           type: 'Local Resource',
           status: '404',
-          description: 'File không tồn tại'
+          description: 'File không tồn tại',
+          suggestion: resource.suggestion || this.getLinkReportSuggestion(resource, 'local')
         });
         row.getCell('status').style = errorStyle;
         allResults.summary.totalIssues++;
       }
       
-      linksSheet.autoFilter = 'A1:E1';
+      linksSheet.autoFilter = 'A1:F1';
       console.log(chalk.green(`  ✅ Broken Links: ${allResults.brokenLinks.length} link, ${allResults.missingResources.length} resource`));
     } catch (error) {
       console.log(chalk.yellow(`  ⚠️ Broken Links: ${error.message}`));
@@ -8018,7 +7927,8 @@ class AccessibilityFixer {
         { header: 'File', key: 'file', width: 60 },
         { header: 'Loại', key: 'type', width: 20 },
         { header: 'Kích thước', key: 'size', width: 15 },
-        { header: 'Ghi chú', key: 'note', width: 40 }
+        { header: 'Ghi chú', key: 'note', width: 40 },
+        { header: 'Gợi ý xử lý', key: 'suggestion', width: 50 }
       ];
       
       unusedSheet.getRow(1).eachCell(cell => {
@@ -8034,13 +7944,14 @@ class AccessibilityFixer {
           file: filePath,
           type: fileType,
           size: fileSize,
-          note: 'Không được tham chiếu trong project'
+          note: 'Không được tham chiếu trong project',
+          suggestion: typeof file === 'object' ? (file.suggestion || 'Xác minh file có đang được dùng động không; nếu không cần, xóa thủ công khỏi project.') : 'Xác minh file có đang được dùng động không; nếu không cần, xóa thủ công khỏi project.'
         });
         row.getCell('note').style = warningStyle;
         allResults.summary.totalWarnings++;
       }
       
-      unusedSheet.autoFilter = 'A1:D1';
+      unusedSheet.autoFilter = 'A1:E1';
       console.log(chalk.green(`  ✅ Unused Files: ${unusedResults.length} file`));
     } catch (error) {
       console.log(chalk.yellow(`  ⚠️ Unused Files: ${error.message}`));
@@ -8096,7 +8007,8 @@ class AccessibilityFixer {
         { header: 'Head Script', key: 'head', width: 15 },
         { header: 'Body Noscript', key: 'body', width: 15 },
         { header: 'Container ID', key: 'containerId', width: 30 },
-        { header: 'Vấn đề', key: 'issues', width: 50 }
+        { header: 'Vấn đề', key: 'issues', width: 50 },
+        { header: 'Gợi ý xử lý', key: 'suggestion', width: 50 }
       ];
       
       gtmSheet.getRow(1).eachCell(cell => {
@@ -8110,7 +8022,8 @@ class AccessibilityFixer {
           head: item.hasHeadScript ? '✅' : '❌',
           body: item.hasBodyNoscript ? '✅' : '❌',
           containerId: item.containerId || '-',
-          issues: (item.issues || []).join('; ') || 'Không có vấn đề'
+          issues: (item.issues || []).join('; ') || 'Không có vấn đề',
+          suggestion: this.getGTMReportSuggestion(item)
         });
         if (!item.hasGTM || item.issues?.length > 0) {
           row.getCell('status').style = errorStyle;
@@ -8120,7 +8033,7 @@ class AccessibilityFixer {
         }
       }
       
-      gtmSheet.autoFilter = 'A1:F1';
+      gtmSheet.autoFilter = 'A1:G1';
       console.log(chalk.green(`  ✅ GTM: ${gtmResults.length} file`));
     } catch (error) {
       console.log(chalk.yellow(`  ⚠️ GTM: ${error.message}`));
@@ -8190,6 +8103,77 @@ class AccessibilityFixer {
   }
 
   // Helper methods for report generation
+  getAccessibilitySuggestion(issue = {}) {
+    const type = (issue.type || '').toLowerCase();
+
+    if (type.includes('missing alt')) {
+      return 'Thêm thuộc tính alt mô tả đúng nội dung/chức năng của ảnh; nếu ảnh chỉ để trang trí, dùng alt="" và cân nhắc role="presentation".';
+    }
+
+    if (type.includes('empty alt')) {
+      return 'Điền alt text có ý nghĩa cho ảnh, hoặc nếu ảnh thực sự chỉ để trang trí thì giữ alt="" và đánh dấu rõ là decorative.';
+    }
+
+    if (type.includes('empty aria-label')) {
+      return 'Điền aria-label ngắn gọn nhưng đủ nghĩa, hoặc thay bằng text hiển thị/aria-labelledby nếu phần tử đã có nội dung liên kết rõ ràng.';
+    }
+
+    return 'Xem lại accessible name và semantic của phần tử, rồi cập nhật text thay thế hoặc ARIA cho phù hợp với chức năng thực tế.';
+  }
+
+  getFormSuggestion(issue = {}) {
+    const type = (issue.type || '').toLowerCase();
+
+    if (type.includes('missing form label')) {
+      return 'Thêm <label for="..."> liên kết với input, hoặc bổ sung aria-label/aria-labelledby nếu không thể dùng label hiển thị.';
+    }
+
+    return 'Đảm bảo mỗi trường nhập liệu có accessible name rõ ràng và không phụ thuộc riêng vào placeholder.';
+  }
+
+  getButtonSuggestion(issue = {}) {
+    const type = (issue.type || '').toLowerCase();
+
+    if (type.includes('empty button')) {
+      return 'Thêm text hiển thị cho button, hoặc bổ sung aria-label nếu button chỉ chứa icon nhưng vẫn cần tên truy cập được.';
+    }
+
+    return 'Đảm bảo button có accessible name rõ ràng, ngắn gọn, và phản ánh đúng hành động của nó.';
+  }
+
+  getLinkReportSuggestion(item = {}, mode = 'external') {
+    if (item.suggestion) {
+      return item.suggestion;
+    }
+
+    if (mode === 'local') {
+      return 'Kiểm tra lại path tham chiếu, tạo file còn thiếu, hoặc cập nhật/xóa reference không còn dùng.';
+    }
+
+    return 'Kiểm tra lại URL đích, cập nhật link mới nếu trang đã đổi, hoặc gỡ liên kết nếu tài nguyên không còn tồn tại.';
+  }
+
+  getGTMReportSuggestion(item = {}) {
+    if (!item.hasGTM) {
+      return 'Thêm đầy đủ GTM script trong <head> và GTM noscript ngay sau thẻ mở <body> nếu trang này cần được tracking.';
+    }
+
+    const suggestions = [];
+    const issues = item.issues || [];
+
+    for (const issue of issues) {
+      if (issue.includes('Thiếu GTM script')) {
+        suggestions.push('Bổ sung GTM script vào <head>, ưu tiên đặt ngay trước </head>.');
+      } else if (issue.includes('Thiếu GTM noscript')) {
+        suggestions.push('Bổ sung GTM noscript ngay sau thẻ mở <body>.');
+      } else if (issue.includes('không khớp')) {
+        suggestions.push('Đồng bộ số lượng script/noscript với các container ID GTM đang dùng trên trang.');
+      }
+    }
+
+    return suggestions.join(' ') || 'Xác minh lại cấu hình GTM giữa phần head, body noscript, và container ID.';
+  }
+
   async checkMetaTagsForReport(directory) {
     const htmlFiles = await this.findHtmlFiles(directory);
     const results = [];