validateHtml method
Validates an HTML document string against HTML5 conformance and SEO quality rules.
Implementation
HtmlDocumentValidationReport validateHtml(
String htmlContent, {
String filePath = 'index.html',
Directory? baseDir,
}) {
final issues = <HtmlValidationIssue>[];
var rulesCount = 0;
// 1. Encoding check (Mojibake & Replacement Character)
rulesCount++;
if (htmlContent.contains('\uFFFD')) {
issues.add(
const HtmlValidationIssue(
message: 'Document contains U+FFFD Unicode replacement characters (decoding corruption).',
severity: HtmlValidationSeverity.error,
rule: 'utf8-encoding',
),
);
}
// Check known Windows-1252 to UTF-8 mojibake signatures
final mojibakeSignatures = [
'→',
'“',
'â€',
'’',
'é',
'ñ',
'ü',
'©',
'â„¢',
];
for (final sig in mojibakeSignatures) {
if (htmlContent.contains(sig)) {
issues.add(
HtmlValidationIssue(
message:
'Detected mojibake encoding artifact ("$sig"). Document has corrupted UTF-8 bytes.',
severity: HtmlValidationSeverity.error,
rule: 'utf8-encoding',
),
);
break;
}
}
// 2. Pre-parse source-level structural checks (to catch errors normalized away by DOM parser)
rulesCount += 4;
final doctypeMatches = RegExp(
r'<!DOCTYPE\b',
caseSensitive: false,
).allMatches(htmlContent);
if (doctypeMatches.length > 1) {
issues.add(
HtmlValidationIssue(
message:
'Malformed document: found ${doctypeMatches.length} <!DOCTYPE> declarations in source.',
severity: HtmlValidationSeverity.error,
rule: 'structure-doctype-duplicate',
),
);
}
final rawHtmlTags = RegExp(
r'<html\b',
caseSensitive: false,
).allMatches(htmlContent);
if (rawHtmlTags.length > 1) {
issues.add(
HtmlValidationIssue(
message:
'Malformed document: found ${rawHtmlTags.length} <html> opening tags in source (multiple root elements).',
severity: HtmlValidationSeverity.error,
rule: 'structure-html-duplicate',
),
);
}
final rawHeadTags = RegExp(
r'<head\b',
caseSensitive: false,
).allMatches(htmlContent);
if (rawHeadTags.length > 1) {
issues.add(
HtmlValidationIssue(
message:
'Malformed document: found ${rawHeadTags.length} <head> opening tags in source (duplicate <head> structure).',
severity: HtmlValidationSeverity.error,
rule: 'structure-head-duplicate',
),
);
}
final rawBodyTags = RegExp(
r'<body\b',
caseSensitive: false,
).allMatches(htmlContent);
if (rawBodyTags.length > 1) {
issues.add(
HtmlValidationIssue(
message:
'Malformed document: found ${rawBodyTags.length} <body> opening tags in source (duplicate <body> structure).',
severity: HtmlValidationSeverity.error,
rule: 'structure-body-duplicate',
),
);
}
final doc = html_parser.parse(htmlContent);
// 2. Document Structure (single html, head, body)
rulesCount += 4;
final htmlElements = doc.querySelectorAll('html');
if (htmlElements.isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Missing root <html> element.',
severity: HtmlValidationSeverity.error,
rule: 'structure-html',
),
);
} else {
final rootHtml = htmlElements.first;
final lang = rootHtml.attributes['lang']?.trim();
if (lang == null || lang.isEmpty) {
issues.add(
const HtmlValidationIssue(
message:
'Missing or empty "lang" attribute on root <html> element.',
severity: HtmlValidationSeverity.error,
rule: 'html-lang',
),
);
}
}
final headElements = doc.querySelectorAll('head');
if (headElements.isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Missing <head> element.',
severity: HtmlValidationSeverity.error,
rule: 'structure-head',
),
);
}
final bodyElements = doc.querySelectorAll('body');
if (bodyElements.isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Missing <body> element.',
severity: HtmlValidationSeverity.error,
rule: 'structure-body',
),
);
}
// 3. Misplaced or nested HTML/body/head tags
rulesCount += 5;
if (headElements.isNotEmpty) {
final head = headElements.first;
// Never insert html or body inside head
final nestedHtmls = head.querySelectorAll('html');
if (nestedHtmls.isNotEmpty) {
issues.add(
HtmlValidationIssue(
message:
'Malformed document: found ${nestedHtmls.length} <html> element(s) inside <head>.',
severity: HtmlValidationSeverity.error,
rule: 'misplaced-element',
),
);
}
final nestedBodies = head.querySelectorAll('body');
if (nestedBodies.isNotEmpty) {
issues.add(
HtmlValidationIssue(
message:
'Malformed document: found ${nestedBodies.length} <body> element(s) inside <head>.',
severity: HtmlValidationSeverity.error,
rule: 'misplaced-element',
),
);
}
// Check character encoding declaration
final hasCharset =
head.querySelectorAll('meta[charset]').isNotEmpty ||
head
.querySelectorAll('meta')
.any(
(m) =>
m.attributes['http-equiv']?.toLowerCase() == 'content-type',
);
if (!hasCharset) {
issues.add(
const HtmlValidationIssue(
message: 'Missing character encoding declaration (<meta charset="UTF-8">) in <head>.',
severity: HtmlValidationSeverity.error,
rule: 'charset-meta',
),
);
}
}
if (bodyElements.isNotEmpty) {
final body = bodyElements.first;
final nestedHtmls = body.querySelectorAll('html');
if (nestedHtmls.isNotEmpty) {
issues.add(
HtmlValidationIssue(
message:
'Malformed document: found ${nestedHtmls.length} <html> element(s) inside <body>.',
severity: HtmlValidationSeverity.error,
rule: 'misplaced-element',
),
);
}
final nestedHeads = body.querySelectorAll('head');
if (nestedHeads.isNotEmpty) {
issues.add(
HtmlValidationIssue(
message:
'Malformed document: found ${nestedHeads.length} <head> element(s) inside <body>.',
severity: HtmlValidationSeverity.error,
rule: 'misplaced-element',
),
);
}
// Misplaced title or base in body
final misplacedHeadTags = body.querySelectorAll('title, base');
if (misplacedHeadTags.isNotEmpty) {
issues.add(
HtmlValidationIssue(
message:
'Misplaced <${misplacedHeadTags.first.localName}> element found inside <body>.',
severity: HtmlValidationSeverity.error,
rule: 'misplaced-element',
),
);
}
}
// 4. Metadata Uniqueness & Validation
rulesCount += 6;
if (headElements.isNotEmpty) {
final head = headElements.first;
// Title
final titles = head.querySelectorAll('title');
if (titles.isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Missing <title> element in <head>.',
severity: HtmlValidationSeverity.error,
rule: 'title-missing',
),
);
} else if (titles.length > 1) {
issues.add(
HtmlValidationIssue(
message:
'Duplicate <title> elements detected (${titles.length} elements).',
severity: HtmlValidationSeverity.error,
rule: 'title-duplicate',
),
);
} else if (titles.first.text.trim().isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Empty <title> element.',
severity: HtmlValidationSeverity.warning,
rule: 'title-empty',
),
);
}
// Meta Description
final descriptions = head
.querySelectorAll('meta')
.where((m) => m.attributes['name']?.toLowerCase() == 'description')
.toList();
if (descriptions.length > 1) {
issues.add(
HtmlValidationIssue(
message:
'Duplicate <meta name="description"> elements detected (${descriptions.length} elements).',
severity: HtmlValidationSeverity.error,
rule: 'description-duplicate',
),
);
} else if (descriptions.isNotEmpty &&
(descriptions.first.attributes['content']?.trim().isEmpty ?? true)) {
issues.add(
const HtmlValidationIssue(
message: 'Empty content in <meta name="description">.',
severity: HtmlValidationSeverity.warning,
rule: 'description-empty',
),
);
}
// Canonical Link
final canonicals = head
.querySelectorAll('link')
.where((l) => l.attributes['rel']?.toLowerCase() == 'canonical')
.toList();
if (canonicals.length > 1) {
issues.add(
HtmlValidationIssue(
message:
'Duplicate <link rel="canonical"> elements detected (${canonicals.length} elements).',
severity: HtmlValidationSeverity.error,
rule: 'canonical-duplicate',
),
);
} else if (canonicals.isNotEmpty) {
final href = canonicals.first.attributes['href']?.trim();
if (href == null || href.isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Empty href in <link rel="canonical">.',
severity: HtmlValidationSeverity.error,
rule: 'canonical-empty',
),
);
} else if (!href.startsWith('http://') &&
!href.startsWith('https://') &&
!href.startsWith('/')) {
issues.add(
HtmlValidationIssue(
message:
'Invalid canonical URL format: "$href". Must start with http://, https://, or /.',
severity: HtmlValidationSeverity.error,
rule: 'canonical-format',
),
);
}
}
// Robots
final robots = head
.querySelectorAll('meta')
.where((m) => m.attributes['name']?.toLowerCase() == 'robots')
.toList();
if (robots.length > 1) {
issues.add(
HtmlValidationIssue(
message:
'Duplicate <meta name="robots"> elements detected (${robots.length} elements).',
severity: HtmlValidationSeverity.error,
rule: 'robots-duplicate',
),
);
}
// Open Graph duplicates
final ogProperties = <String>{};
for (final og in head.querySelectorAll('meta')) {
final prop = og.attributes['property']?.toLowerCase();
if (prop != null && prop.startsWith('og:')) {
// Some og properties like og:image:alt or multiple og:image are allowed,
// but primary tags like og:title, og:description, og:url, og:site_name, og:type must be unique.
final primaryProps = {
'og:title',
'og:description',
'og:url',
'og:site_name',
'og:type',
};
if (primaryProps.contains(prop) && !ogProperties.add(prop)) {
issues.add(
HtmlValidationIssue(
message: 'Duplicate Open Graph property detected: "$prop".',
severity: HtmlValidationSeverity.error,
rule: 'og-duplicate',
),
);
}
}
}
// Twitter duplicates
final twitterNames = <String>{};
for (final tw in head.querySelectorAll('meta')) {
final name = tw.attributes['name']?.toLowerCase();
if (name != null && name.startsWith('twitter:')) {
if (!twitterNames.add(name)) {
issues.add(
HtmlValidationIssue(
message: 'Duplicate Twitter card metadata detected: "$name".',
severity: HtmlValidationSeverity.error,
rule: 'twitter-duplicate',
),
);
}
}
}
}
// 5. Structured Data (JSON-LD) Validation
rulesCount++;
final jsonLdScripts = doc.querySelectorAll(
'script[type="application/ld+json"]',
);
final seenJsonLdSignatures = <String>{};
for (final script in jsonLdScripts) {
final jsonText = script.text.trim();
if (jsonText.isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Empty <script type="application/ld+json"> tag.',
severity: HtmlValidationSeverity.error,
rule: 'jsonld-empty',
),
);
continue;
}
try {
final decoded = json.decode(jsonText);
if (decoded is Map) {
if (!decoded.containsKey('@context')) {
issues.add(
const HtmlValidationIssue(
message: 'JSON-LD object missing "@context" property.',
severity: HtmlValidationSeverity.error,
rule: 'jsonld-context',
),
);
}
if (!decoded.containsKey('@type')) {
issues.add(
const HtmlValidationIssue(
message: 'JSON-LD object missing "@type" property.',
severity: HtmlValidationSeverity.error,
rule: 'jsonld-type',
),
);
}
final keys = HeadInjector.computeJsonLdEntityKeys(decoded);
for (final key in keys) {
if (!seenJsonLdSignatures.add(key)) {
issues.add(
HtmlValidationIssue(
message:
'Duplicate JSON-LD structured data block for entity "$key".',
severity: HtmlValidationSeverity.warning,
rule: 'jsonld-duplicate',
),
);
break;
}
}
} else if (decoded is List) {
final keys = HeadInjector.computeJsonLdEntityKeys(decoded);
for (final key in keys) {
if (!seenJsonLdSignatures.add(key)) {
issues.add(
HtmlValidationIssue(
message:
'Duplicate JSON-LD structured data block for entity "$key".',
severity: HtmlValidationSeverity.warning,
rule: 'jsonld-duplicate',
),
);
break;
}
}
} else {
issues.add(
const HtmlValidationIssue(
message: 'JSON-LD root must be a JSON object or array.',
severity: HtmlValidationSeverity.error,
rule: 'jsonld-structure',
),
);
}
} on FormatException catch (e) {
issues.add(
HtmlValidationIssue(
message: 'Malformed JSON-LD syntax: ${e.message}',
severity: HtmlValidationSeverity.error,
rule: 'jsonld-syntax',
),
);
}
}
// 6. Responsive Image Quality & Accessibility
rulesCount += 2;
final images = doc.querySelectorAll('img');
for (final img in images) {
final src = img.attributes['src']?.trim();
if (src == null || src.isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Image element has empty or missing "src" attribute.',
severity: HtmlValidationSeverity.error,
rule: 'img-src',
),
);
}
if (!img.attributes.containsKey('alt')) {
issues.add(
HtmlValidationIssue(
message:
'Missing "alt" attribute on <img> element (src: "${src ?? 'unknown'}").',
severity: HtmlValidationSeverity.warning,
rule: 'img-alt',
),
);
}
// Check fixed dimensions vs responsiveness
final style = img.attributes['style'] ?? '';
final hasFixedWidthPx = RegExp(r'\bwidth:\s*\d+(\.\d+)?px\b')
.hasMatch(style);
final hasMaxWidth =
style.contains('max-width: 100%') || style.contains('max-width:100%');
if (hasFixedWidthPx && !hasMaxWidth) {
issues.add(
HtmlValidationIssue(
message:
'Image has fixed pixel width without "max-width: 100%" (risks viewport overflow on mobile): "${src ?? 'unknown'}".',
severity: HtmlValidationSeverity.warning,
rule: 'img-responsive',
),
);
}
}
// 7. Navigation Semantics
rulesCount += 2;
// Check for buttons with role="tab" used outside tablist
final tabButtons = doc.querySelectorAll('button[role="tab"]');
for (final btn in tabButtons) {
final parentTabList =
btn.parent?.attributes['role'] == 'tablist' ||
btn.parent?.parent?.attributes['role'] == 'tablist';
if (!parentTabList) {
issues.add(
HtmlValidationIssue(
message: 'Invalid navigation semantics: <button role="tab"> used outside of an element with role="tablist" (navigation items must be anchor <a> links).',
severity: HtmlValidationSeverity.error,
rule: 'nav-semantics',
),
);
}
}
// Check ordinary buttons for invalid selection attributes
final allButtons = doc.querySelectorAll('button');
for (final btn in allButtons) {
if (btn.attributes.containsKey('aria-selected') &&
btn.attributes['role'] != 'tab') {
issues.add(
const HtmlValidationIssue(
message: 'Invalid ARIA attribute: <button> must not have "aria-selected" unless role="tab". For toggle buttons, use "aria-pressed".',
severity: HtmlValidationSeverity.error,
rule: 'button-aria-selected',
),
);
}
}
// Anchor links validation
final anchors = doc.querySelectorAll('a');
for (final a in anchors) {
final href = a.attributes['href']?.trim();
if (a.attributes.containsKey('aria-selected') &&
a.attributes['role'] != 'tab') {
issues.add(
HtmlValidationIssue(
message:
'Invalid navigation ARIA: anchor <a> with href "${href ?? ''}" must not use "aria-selected" (use "aria-current=\\"page\\"" for active page links).',
severity: HtmlValidationSeverity.error,
rule: 'nav-aria-selected',
),
);
}
if (href == null || href.isEmpty) {
issues.add(
const HtmlValidationIssue(
message: 'Anchor tag <a> has missing or empty "href" attribute.',
severity: HtmlValidationSeverity.error,
rule: 'anchor-href',
),
);
} else if (baseDir != null &&
href.startsWith('/') &&
!href.startsWith('//')) {
// Internal route link verification
final cleanPath = href.split('?').first.split('#').first;
if (cleanPath.isNotEmpty && cleanPath != '/') {
final relPath = cleanPath.substring(1);
final candidates = [
File('${baseDir.path}/$relPath/index.html'),
File('${baseDir.path}/$relPath.html'),
File('${baseDir.path}/$relPath'),
];
final exists = candidates.any((f) => f.existsSync());
if (!exists) {
issues.add(
HtmlValidationIssue(
message:
'Broken internal route link: href "$href" does not resolve to an existing route file.',
severity: HtmlValidationSeverity.error,
rule: 'link-internal',
),
);
}
}
}
}
// 8. Broken Local Asset References
if (baseDir != null) {
rulesCount += 2;
// Local scripts
for (final script in doc.querySelectorAll('script[src]')) {
final src = script.attributes['src']?.trim() ?? '';
if (src.isNotEmpty &&
!src.startsWith('http://') &&
!src.startsWith('https://') &&
!src.startsWith('//') &&
!src.startsWith('data:')) {
final cleanSrc = src.split('?').first.split('#').first;
final assetFile = File(
cleanSrc.startsWith('/')
? '${baseDir.path}$cleanSrc'
: '${baseDir.path}/$cleanSrc',
);
if (!assetFile.existsSync()) {
issues.add(
HtmlValidationIssue(
message:
'Broken local asset reference: script "$src" does not exist in build output.',
severity: HtmlValidationSeverity.error,
rule: 'asset-script',
),
);
}
}
}
// Local stylesheets
for (final link in doc.querySelectorAll('link[rel="stylesheet"][href]')) {
final href = link.attributes['href']?.trim() ?? '';
if (href.isNotEmpty &&
!href.startsWith('http://') &&
!href.startsWith('https://') &&
!href.startsWith('//')) {
final cleanHref = href.split('?').first.split('#').first;
final assetFile = File(
cleanHref.startsWith('/')
? '${baseDir.path}$cleanHref'
: '${baseDir.path}/$cleanHref',
);
if (!assetFile.existsSync()) {
issues.add(
HtmlValidationIssue(
message:
'Broken local asset reference: stylesheet "$href" does not exist in build output.',
severity: HtmlValidationSeverity.error,
rule: 'asset-stylesheet',
),
);
}
}
}
// Local image assets
for (final img in images) {
final src = img.attributes['src']?.trim() ?? '';
if (src.isNotEmpty &&
!src.startsWith('http://') &&
!src.startsWith('https://') &&
!src.startsWith('//') &&
!src.startsWith('data:')) {
final cleanSrc = src.split('?').first.split('#').first;
final assetFile = File(
cleanSrc.startsWith('/')
? '${baseDir.path}$cleanSrc'
: '${baseDir.path}/$cleanSrc',
);
if (!assetFile.existsSync()) {
issues.add(
HtmlValidationIssue(
message:
'Broken local image asset: "$src" does not exist in build output.',
severity: HtmlValidationSeverity.error,
rule: 'asset-image',
),
);
}
}
}
}
return HtmlDocumentValidationReport(
filePath: filePath,
issues: issues,
checkedRulesCount: rulesCount,
);
}