@qobi/seocode 0.1.0

package/dist/src/engine/rules/declarative-evaluator.js

@@ -0,0 +1,105 @@
+import { buildIssue } from './helpers.js';
+/**
+ * Evaluates a rule using its declarative `check` descriptor.
+ * Returns `null`        — rule passed.
+ * Returns `SeoIssue`   — rule fired.
+ * Returns `undefined`  — no check descriptor present; caller must use hand-coded handler.
+ */
+export function evaluateDeclarative(rule, doc) {
+    const check = rule.check;
+    if (!check)
+        return undefined;
+    return dispatch(check, rule, doc);
+}
+// ── dispatcher ───────────────────────────────────────────────────────────────
+function dispatch(check, rule, doc) {
+    const raw = doc;
+    switch (check.type) {
+        // field is null / undefined / falsy
+        case 'field-null': {
+            const val = raw[check.field];
+            return !val ? buildIssue(rule, doc, null, rule.fixTemplate) : null;
+        }
+        // boolean field is true
+        case 'field-truthy': {
+            const val = raw[check.field];
+            return val ? buildIssue(rule, doc, null, rule.fixTemplate) : null;
+        }
+        // boolean field is false / falsy
+        case 'field-falsy': {
+            const val = raw[check.field];
+            return !val ? buildIssue(rule, doc, null, rule.fixTemplate) : null;
+        }
+        // { value: string; line: number } field whose value.length > threshold
+        case 'field-length-gt': {
+            const field = raw[check.field];
+            if (!field)
+                return null; // absence handled by a separate missing-X rule
+            const len = field.value.length;
+            if (len > check.threshold) {
+                return buildIssue(rule, doc, field.line, rule.fixTemplate.replace(/\{\{CURRENT_LENGTH\}\}/g, String(len)));
+            }
+            return null;
+        }
+        // { value: string; line: number } field whose value.length < threshold (and non-empty)
+        case 'field-length-lt': {
+            const field = raw[check.field];
+            if (!field)
+                return null;
+            const len = field.value.length;
+            if (len > 0 && len < check.threshold) {
+                return buildIssue(rule, doc, field.line, rule.fixTemplate.replace(/\{\{CURRENT_LENGTH\}\}/g, String(len)));
+            }
+            return null;
+        }
+        // { value: string; line: number } field whose value contains a substring (case-insensitive)
+        case 'field-contains': {
+            const field = raw[check.field];
+            if (!field)
+                return null;
+            if (field.value.toLowerCase().includes(check.value.toLowerCase())) {
+                return buildIssue(rule, doc, field.line, rule.fixTemplate);
+            }
+            return null;
+        }
+        // array field that is empty
+        case 'field-array-empty': {
+            const arr = raw[check.field];
+            return (!arr || arr.length === 0)
+                ? buildIssue(rule, doc, null, rule.fixTemplate)
+                : null;
+        }
+        // any JSON-LD block contains the given @type
+        case 'jsonld-has-type': {
+            for (const block of doc.jsonLdBlocks) {
+                try {
+                    const items = (() => {
+                        const p = JSON.parse(block.content);
+                        return Array.isArray(p) ? p : [p];
+                    })();
+                    for (const item of items) {
+                        const t = item['@type'];
+                        const types = Array.isArray(t) ? t : [t];
+                        if (types.includes(check.schemaType)) {
+                            return buildIssue(rule, doc, block.line, rule.fixTemplate);
+                        }
+                    }
+                }
+                catch { /* invalid JSON handled by invalid-json-ld rule */ }
+            }
+            return null;
+        }
+        // rawContent matches a single regex pattern
+        case 'raw-match': {
+            const re = new RegExp(check.pattern, check.flags ?? 'i');
+            return re.test(doc.rawContent)
+                ? buildIssue(rule, doc, null, rule.fixTemplate)
+                : null;
+        }
+        // rawContent matches ALL patterns in the list
+        case 'raw-all-match': {
+            const allMatch = check.patterns.every(p => new RegExp(p, 'i').test(doc.rawContent));
+            return allMatch ? buildIssue(rule, doc, null, rule.fixTemplate) : null;
+        }
+    }
+}

package/dist/src/engine/rules/heading-rules.js

@@ -0,0 +1,43 @@
+import { buildIssue } from './helpers.js';
+export function checkHeadingRules(rule, doc) {
+    switch (rule.id) {
+        case 'missing-h1': {
+            const h1s = doc.headings.filter((h) => h.tag === 'h1');
+            if (h1s.length === 0)
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            return null;
+        }
+        case 'multiple-h1': {
+            const h1s = doc.headings.filter((h) => h.tag === 'h1');
+            if (h1s.length > 1) {
+                return buildIssue(rule, doc, h1s[1].line, rule.fixTemplate.replace('{{COUNT}}', String(h1s.length)));
+            }
+            return null;
+        }
+        case 'heading-hierarchy': {
+            const issues = [];
+            let prevLevel = 0;
+            for (const heading of doc.headings) {
+                const currentLevel = parseInt(heading.tag[1], 10);
+                if (currentLevel > prevLevel + 1 && prevLevel !== 0) {
+                    issues.push(buildIssue(rule, doc, heading.line, rule.fixTemplate
+                        .replace('{{FROM}}', `h${prevLevel}`)
+                        .replace('{{TO}}', heading.tag)));
+                }
+                prevLevel = currentLevel;
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        case 'empty-heading': {
+            const issues = [];
+            for (const heading of doc.headings) {
+                if (!heading.text.trim()) {
+                    issues.push(buildIssue(rule, doc, heading.line, rule.fixTemplate.replace('{{TAG}}', heading.tag)));
+                }
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        default:
+            return null;
+    }
+}

package/dist/src/engine/rules/helpers.js

@@ -0,0 +1,16 @@
+export function buildIssue(rule, doc, line, fix, suggestion) {
+    const issue = {
+        ruleId: rule.id,
+        ruleName: rule.name,
+        severity: rule.severity,
+        category: rule.category,
+        file: doc.filePath,
+        line,
+        description: rule.description,
+        fix,
+        references: rule.references,
+    };
+    if (suggestion)
+        issue.suggestion = suggestion;
+    return issue;
+}

package/dist/src/engine/rules/image-rules.js

@@ -0,0 +1,82 @@
+import { buildIssue } from './helpers.js';
+import { suggestImgAttr } from './suggest.js';
+export function checkImageRules(rule, doc) {
+    switch (rule.id) {
+        case 'image-missing-alt': {
+            const issues = [];
+            for (const img of doc.images) {
+                if (img.alt === null) {
+                    issues.push(buildIssue(rule, doc, img.line, rule.fixTemplate.replace('{{SRC}}', img.src)));
+                }
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        case 'image-empty-alt': {
+            const issues = [];
+            for (const img of doc.images) {
+                if (img.alt === '' && img.src && !img.src.includes('icon') && !img.src.includes('decoration')) {
+                    issues.push(buildIssue(rule, doc, img.line, rule.fixTemplate.replace('{{SRC}}', img.src)));
+                }
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        case 'image-missing-lazy-loading': {
+            const issues = [];
+            for (const img of doc.images) {
+                if (!img.loading) {
+                    // `loading="lazy"` is a deterministic, always-safe addition — offer it
+                    // as a committable 1-click fix when the <img> sits on a single line.
+                    const suggestion = suggestImgAttr(doc, img.line, 'loading="lazy"', 'loading');
+                    issues.push(buildIssue(rule, doc, img.line, rule.fixTemplate.replace('{{SRC}}', img.src), suggestion));
+                }
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        case 'avif-image-format-supported': {
+            if (doc.images.length === 0)
+                return null;
+            const hasAvifSource = /type\s*=\s*["']image\/avif["']/.test(doc.rawContent);
+            if (!hasAvifSource) {
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'image-preferred-source-metadata': {
+            // Only fire when JSON-LD is present but the og:image URL isn't reflected in it
+            if (!doc.ogImage || doc.jsonLdBlocks.length === 0)
+                return null;
+            const ogImgUrl = doc.ogImage.value;
+            let hasMatchingImage = false;
+            for (const block of doc.jsonLdBlocks) {
+                try {
+                    const str = JSON.stringify(JSON.parse(block.content));
+                    if (str.includes('"image"') && str.includes(ogImgUrl)) {
+                        hasMatchingImage = true;
+                        break;
+                    }
+                }
+                catch { }
+            }
+            if (!hasMatchingImage) {
+                return buildIssue(rule, doc, doc.ogImage.line, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'image-url-consistency': {
+            if (doc.images.length < 2)
+                return null;
+            const httpImages = doc.images.filter(img => img.src.startsWith('http://'));
+            const httpsImages = doc.images.filter(img => img.src.startsWith('https://'));
+            if (httpImages.length > 0 && httpsImages.length > 0) {
+                return buildIssue(rule, doc, httpImages[0].line, rule.fixTemplate);
+            }
+            return null;
+        }
+        // Cannot verify thumbnail opacity or C2PA metadata from HTML alone
+        case 'video-transparency':
+        case 'c2pa-metadata':
+            return null;
+        default:
+            return null;
+    }
+}

package/dist/src/engine/rules/index.js

@@ -0,0 +1,28 @@
+import { evaluateDeclarative } from './declarative-evaluator.js';
+import { checkMetaRules } from './meta-rules.js';
+import { checkHeadingRules } from './heading-rules.js';
+import { checkImageRules } from './image-rules.js';
+import { checkLinkRules } from './link-rules.js';
+import { checkTechnicalRules } from './technical-rules.js';
+import { checkSchemaRules } from './schema-rules.js';
+import { checkPerformanceRules } from './performance-rules.js';
+// Returns null if rule passes, SeoIssue or SeoIssue[] if it fails
+export function runRule(rule, doc) {
+    // Declarative path: rule carries its own check descriptor in the JSON.
+    // undefined means "no descriptor" — fall through to hand-coded handler.
+    const declarativeResult = evaluateDeclarative(rule, doc);
+    if (declarativeResult !== undefined)
+        return declarativeResult;
+    // Hand-coded path: for rules whose logic is too complex to express as a
+    // single descriptor (iteration, compound conditions, nested schema checks).
+    switch (rule.category) {
+        case 'meta': return checkMetaRules(rule, doc);
+        case 'headings': return checkHeadingRules(rule, doc);
+        case 'images': return checkImageRules(rule, doc);
+        case 'links': return checkLinkRules(rule, doc);
+        case 'technical': return checkTechnicalRules(rule, doc);
+        case 'schema': return checkSchemaRules(rule, doc);
+        case 'performance': return checkPerformanceRules(rule, doc);
+        default: return null;
+    }
+}

package/dist/src/engine/rules/link-rules.js

@@ -0,0 +1,39 @@
+import { buildIssue } from './helpers.js';
+import { suggestTagAttr } from './suggest.js';
+const VAGUE_LINK_TEXTS = ['click here', 'read more', 'learn more', 'here', 'this', 'link', 'more'];
+export function checkLinkRules(rule, doc) {
+    switch (rule.id) {
+        case 'vague-link-text': {
+            const issues = [];
+            for (const link of doc.links) {
+                if (VAGUE_LINK_TEXTS.includes(link.text.toLowerCase().trim())) {
+                    issues.push(buildIssue(rule, doc, link.line, rule.fixTemplate.replace('{{TEXT}}', link.text).replace('{{HREF}}', link.href)));
+                }
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        case 'external-link-no-rel': {
+            const issues = [];
+            for (const link of doc.links) {
+                const isExternal = link.href.startsWith('http') || link.href.startsWith('//');
+                if (isExternal) {
+                    // noreferrer implies noopener in all modern browsers — either token satisfies the rule
+                    const tokens = (link.rel ?? '').split(/\s+/).filter(Boolean);
+                    const isSafe = tokens.includes('noopener') || tokens.includes('noreferrer');
+                    if (!isSafe) {
+                        // Provably-correct 1-click fix: add rel="noopener noreferrer" — but
+                        // only when the <a> has no rel at all (merging tokens into an
+                        // existing rel is left advisory to avoid clobbering author intent).
+                        const suggestion = link.rel
+                            ? undefined
+                            : suggestTagAttr(doc, link.line, 'a', 'rel="noopener noreferrer"', 'rel');
+                        issues.push(buildIssue(rule, doc, link.line, rule.fixTemplate.replace('{{HREF}}', link.href), suggestion));
+                    }
+                }
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        default:
+            return null;
+    }
+}

package/dist/src/engine/rules/meta-rules.js

@@ -0,0 +1,34 @@
+import { buildIssue } from './helpers.js';
+/**
+ * Hand-coded handlers for meta rules whose logic is too complex for a
+ * declarative check descriptor.  Simple "missing X" and length checks for
+ * meta tags live in seo-rules.json as `check` descriptors instead.
+ */
+export function checkMetaRules(rule, doc) {
+    switch (rule.id) {
+        case 'missing-og-locale': {
+            const hasHreflang = doc.hreflangLinks.length > 0;
+            const hasNonEnglishLang = doc.langAttribute && !/^en(-|$)/i.test(doc.langAttribute.value);
+            if ((hasHreflang || hasNonEnglishLang) && !doc.ogLocale) {
+                return buildIssue(rule, doc, doc.langAttribute?.line ?? null, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'read-more-deeplink': {
+            if (!doc.isPageDocument)
+                return null;
+            const subheadings = doc.headings.filter(h => h.tag !== 'h1');
+            if (subheadings.length < 2)
+                return null;
+            const headingsWithId = (doc.rawContent.match(/<h[2-6][^>]+id\s*=/gi) ?? []).length;
+            if (headingsWithId === 0)
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            return null;
+        }
+        // Content-strategy advisory — nothing actionable to detect statically
+        case 'generative-ai-optimization':
+            return null;
+        default:
+            return null;
+    }
+}

package/dist/src/engine/rules/performance-rules.js

@@ -0,0 +1,24 @@
+import { buildIssue } from './helpers.js';
+export function checkPerformanceRules(rule, doc) {
+    switch (rule.id) {
+        case 'missing-preload-lcp':
+            if (doc.images.length > 0 && doc.preloadLinks.length === 0) {
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            }
+            return null;
+        case 'inp-core-web-vital': {
+            // Detect render-blocking external scripts (no async or defer attribute)
+            const scriptTags = doc.rawContent.match(/<script[^>]+src\s*=\s*["'][^"']+["'][^>]*>/gi) ?? [];
+            const blockingCount = scriptTags.filter(tag => !/\b(?:async|defer)\b/i.test(tag)).length;
+            if (blockingCount > 1) {
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            }
+            return null;
+        }
+        // FID was removed as a Core Web Vital in March 2024 — disabled
+        case 'missing-fid':
+            return null;
+        default:
+            return null;
+    }
+}

package/dist/src/engine/rules/schema-rules.js

@@ -0,0 +1,228 @@
+import { buildIssue } from './helpers.js';
+// ── JSON-LD helpers ──────────────────────────────────────────────────────────
+function parseAllJsonLd(doc) {
+    const result = [];
+    for (const block of doc.jsonLdBlocks) {
+        try {
+            const parsed = JSON.parse(block.content);
+            const items = Array.isArray(parsed) ? parsed : [parsed];
+            for (const item of items) {
+                result.push(item);
+                if (Array.isArray(item?.['@graph']))
+                    result.push(...item['@graph']);
+            }
+        }
+        catch { /* invalid JSON is handled by the invalid-json-ld rule */ }
+    }
+    return result;
+}
+function schemaTypes(item) {
+    const t = item?.['@type'];
+    if (!t)
+        return [];
+    return Array.isArray(t) ? t : [t];
+}
+function hasSchemaType(items, type) {
+    return items.some(item => schemaTypes(item).includes(type));
+}
+function findByType(items, type) {
+    return items.filter(item => schemaTypes(item).includes(type));
+}
+function lineForType(doc, type) {
+    for (const block of doc.jsonLdBlocks) {
+        try {
+            const parsed = JSON.parse(block.content);
+            const items = Array.isArray(parsed) ? parsed : [parsed];
+            if (items.some((item) => {
+                const t = item?.['@type'];
+                return Array.isArray(t) ? t.includes(type) : t === type;
+            }))
+                return block.line;
+        }
+        catch { }
+    }
+    return null;
+}
+const HOMEPAGE_PATTERN = /(?:^|[/\\])(?:index|page|app|root)\.[a-z]+$/i;
+// ── Rule handler ─────────────────────────────────────────────────────────────
+/**
+ * Hand-coded handlers for schema rules whose logic is too complex for a
+ * declarative check descriptor.
+ *
+ * Simple deprecated-type checks (faq-schema-deprecated, etc.) and
+ * missing-json-ld live as `check` descriptors in seo-rules.json instead.
+ */
+export function checkSchemaRules(rule, doc) {
+    switch (rule.id) {
+        case 'invalid-json-ld': {
+            const issues = [];
+            for (const block of doc.jsonLdBlocks) {
+                // Runtime-generated JSON-LD (dangerouslySetInnerHTML / {expr}) has no
+                // literal body to validate — never flag it as invalid.
+                if (block.dynamic)
+                    continue;
+                try {
+                    JSON.parse(block.content);
+                }
+                catch {
+                    issues.push(buildIssue(rule, doc, block.line, rule.fixTemplate));
+                }
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        case 'json-ld-recommended-format': {
+            const hasMicrodata = /\bitemscope\b/.test(doc.rawContent);
+            const hasRdfa = /\btypeof\s*=\s*["']/.test(doc.rawContent);
+            if ((hasMicrodata || hasRdfa) && doc.jsonLdBlocks.length === 0) {
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'structured-data-javascript-initial-html': {
+            if (doc.fileType === 'html')
+                return null;
+            if (doc.jsonLdBlocks.length > 0) {
+                return buildIssue(rule, doc, doc.jsonLdBlocks[0].line, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'review-snippet-requires-comment': {
+            const items = parseAllJsonLd(doc);
+            for (const review of findByType(items, 'Review')) {
+                if (!review.reviewBody || !review.author) {
+                    return buildIssue(rule, doc, lineForType(doc, 'Review'), rule.fixTemplate);
+                }
+            }
+            return null;
+        }
+        case 'review-no-multiple-reviewed-entities': {
+            const items = parseAllJsonLd(doc);
+            for (const type of ['Review', 'AggregateRating']) {
+                for (const item of findByType(items, type)) {
+                    const reviewed = item.itemReviewed;
+                    if (Array.isArray(reviewed) && reviewed.length > 1) {
+                        return buildIssue(rule, doc, lineForType(doc, type), rule.fixTemplate);
+                    }
+                }
+            }
+            return null;
+        }
+        case 'video-indexing-criteria': {
+            const items = parseAllJsonLd(doc);
+            for (const video of findByType(items, 'VideoObject')) {
+                const missing = [];
+                if (!video.name)
+                    missing.push('name');
+                if (!video.thumbnailUrl && !video.thumbnail)
+                    missing.push('thumbnailUrl');
+                if (!video.contentUrl && !video.embedUrl)
+                    missing.push('contentUrl/embedUrl');
+                if (!video.uploadDate)
+                    missing.push('uploadDate');
+                if (missing.length > 0) {
+                    return buildIssue(rule, doc, lineForType(doc, 'VideoObject'), `${rule.fixTemplate} Missing: ${missing.join(', ')}.`);
+                }
+            }
+            return null;
+        }
+        case 'recipe-thumbnail-property': {
+            const items = parseAllJsonLd(doc);
+            for (const recipe of findByType(items, 'Recipe')) {
+                if (recipe.thumbnail && !recipe.image) {
+                    return buildIssue(rule, doc, lineForType(doc, 'Recipe'), rule.fixTemplate);
+                }
+            }
+            return null;
+        }
+        case 'product-structured-data-single-product': {
+            const items = parseAllJsonLd(doc);
+            if (findByType(items, 'Product').length > 1) {
+                return buildIssue(rule, doc, lineForType(doc, 'Product'), rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'merchant-shipping-policy-schema': {
+            const items = parseAllJsonLd(doc);
+            if (findByType(items, 'Product').length === 0)
+                return null;
+            const hasShipping = items.some(item => item.shippingDetails) ||
+                findByType(items, 'Product').some(p => JSON.stringify(p.offers ?? {}).includes('shippingDetails'));
+            if (!hasShipping) {
+                return buildIssue(rule, doc, lineForType(doc, 'Product'), rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'merchant-return-policy-schema': {
+            const items = parseAllJsonLd(doc);
+            if (findByType(items, 'Product').length === 0)
+                return null;
+            const hasReturn = hasSchemaType(items, 'MerchantReturnPolicy') ||
+                items.some(item => item.hasMerchantReturnPolicy) ||
+                findByType(items, 'Product').some(p => p.hasMerchantReturnPolicy);
+            if (!hasReturn) {
+                return buildIssue(rule, doc, lineForType(doc, 'Product'), rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'loyalty-program-schema': {
+            const items = parseAllJsonLd(doc);
+            if (findByType(items, 'Product').length === 0)
+                return null;
+            const orgs = findByType(items, 'Organization').concat(findByType(items, 'LocalBusiness'));
+            if (orgs.length === 0)
+                return null;
+            if (!orgs.some(org => org.memberOf || org.hasMembershipProgram)) {
+                return buildIssue(rule, doc, lineForType(doc, 'Organization'), rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'event-structured-data-requirements': {
+            const items = parseAllJsonLd(doc);
+            for (const event of findByType(items, 'Event')) {
+                const location = event.location;
+                if (!location) {
+                    return buildIssue(rule, doc, lineForType(doc, 'Event'), rule.fixTemplate);
+                }
+                const locArr = Array.isArray(location) ? location : [location];
+                const hasPhysicalPlace = locArr.some((loc) => {
+                    const t = schemaTypes(loc);
+                    return t.includes('Place') || t.includes('PostalAddress');
+                });
+                if (!hasPhysicalPlace) {
+                    return buildIssue(rule, doc, lineForType(doc, 'Event'), rule.fixTemplate);
+                }
+            }
+            return null;
+        }
+        case 'site-name-schema': {
+            if (!doc.isPageDocument || !HOMEPAGE_PATTERN.test(doc.filePath))
+                return null;
+            const items = parseAllJsonLd(doc);
+            if (!hasSchemaType(items, 'WebSite')) {
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'organization-markup': {
+            if (!doc.isPageDocument || !HOMEPAGE_PATTERN.test(doc.filePath))
+                return null;
+            const items = parseAllJsonLd(doc);
+            if (!hasSchemaType(items, 'Organization') && !hasSchemaType(items, 'LocalBusiness')) {
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'breadcrumbs-desktop-only': {
+            const items = parseAllJsonLd(doc);
+            if (hasSchemaType(items, 'BreadcrumbList')) {
+                return buildIssue(rule, doc, lineForType(doc, 'BreadcrumbList'), rule.fixTemplate);
+            }
+            return null;
+        }
+        // Regional feature — cannot determine site geography from file content
+        case 'south-africa-carousel-structured-data':
+            return null;
+        default:
+            return null;
+    }
+}