recker 1.0.27 → 1.0.28-next.c61382b

package/dist/seo/index.d.ts

@@ -0,0 +1,5 @@
+export { SeoAnalyzer, analyzeSeo } from './analyzer.js';
+export { SeoRulesEngine, createRulesEngine, SEO_THRESHOLDS, ALL_SEO_RULES, } from './rules/index.js';
+export type { SeoReport, SeoCheckResult, SeoStatus, HeadingAnalysis, HeadingInfo, ContentMetrics, LinkAnalysis, ImageAnalysis, SocialMetaAnalysis, TechnicalSeo, SeoAnalyzerOptions, } from './types.js';
+export type { SeoRule, RuleContext, RuleResult, RuleEvidence, RuleCategory, RuleSeverity, RulesEngineOptions, } from './rules/index.js';
+export type { SeoAnalyzerFullOptions } from './analyzer.js';

package/dist/seo/index.js

@@ -0,0 +1,2 @@
+export { SeoAnalyzer, analyzeSeo } from './analyzer.js';
+export { SeoRulesEngine, createRulesEngine, SEO_THRESHOLDS, ALL_SEO_RULES, } from './rules/index.js';

package/dist/seo/rules/accessibility.d.ts

@@ -0,0 +1,2 @@
+import { SeoRule } from './types.js';
+export declare const accessibilityRules: SeoRule[];

package/dist/seo/rules/accessibility.js

@@ -0,0 +1,128 @@
+import { createResult } from './types.js';
+export const accessibilityRules = [
+    {
+        id: 'a11y-buttons-aria',
+        name: 'Button Accessibility',
+        category: 'accessibility',
+        severity: 'warning',
+        description: 'Buttons without visible text must have aria-label',
+        check: (ctx) => {
+            const count = ctx.buttonsWithoutAriaLabel ?? 0;
+            if (count > 0) {
+                return createResult({ id: 'a11y-buttons-aria', name: 'Button Accessibility', category: 'accessibility', severity: 'warning' }, 'warn', `${count} button(s) without accessible text/aria-label`, { value: count, recommendation: 'Add aria-label to icon-only buttons' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'a11y-links-aria',
+        name: 'Link Accessibility',
+        category: 'accessibility',
+        severity: 'warning',
+        description: 'Links without visible text must have aria-label',
+        check: (ctx) => {
+            const count = ctx.linksWithoutAriaLabel ?? 0;
+            if (count > 0) {
+                return createResult({ id: 'a11y-links-aria', name: 'Link Accessibility', category: 'accessibility', severity: 'warning' }, 'warn', `${count} link(s) without accessible text/aria-label`, { value: count, recommendation: 'Add aria-label to icon-only links' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'a11y-inputs-label',
+        name: 'Input Labels',
+        category: 'accessibility',
+        severity: 'error',
+        description: 'Form inputs must have associated labels',
+        check: (ctx) => {
+            const count = ctx.inputsWithoutLabel ?? 0;
+            if (count > 0) {
+                return createResult({ id: 'a11y-inputs-label', name: 'Input Labels', category: 'accessibility', severity: 'error' }, 'fail', `${count} input(s) without associated label`, { value: count, recommendation: 'Add <label for="id"> or aria-label to all form inputs' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'a11y-iframes-title',
+        name: 'Iframe Titles',
+        category: 'accessibility',
+        severity: 'warning',
+        description: 'Iframes must have title attribute',
+        check: (ctx) => {
+            const count = ctx.iframesWithoutTitle ?? 0;
+            if (count > 0) {
+                return createResult({ id: 'a11y-iframes-title', name: 'Iframe Titles', category: 'accessibility', severity: 'warning' }, 'warn', `${count} iframe(s) without title attribute`, { value: count, recommendation: 'Add title attribute to describe iframe content' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'a11y-tables-caption',
+        name: 'Table Captions',
+        category: 'accessibility',
+        severity: 'info',
+        description: 'Data tables should have caption or aria-label',
+        check: (ctx) => {
+            const count = ctx.tablesWithoutCaption ?? 0;
+            if (count > 0) {
+                return createResult({ id: 'a11y-tables-caption', name: 'Table Captions', category: 'accessibility', severity: 'info' }, 'info', `${count} table(s) without caption/aria-label`, { value: count, recommendation: 'Add <caption> or aria-label to data tables' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'a11y-svg-title',
+        name: 'SVG Accessibility',
+        category: 'accessibility',
+        severity: 'warning',
+        description: 'SVGs should have <title> or aria-label for accessibility',
+        check: (ctx) => {
+            const count = ctx.svgsWithoutTitle ?? 0;
+            if (count > 0) {
+                return createResult({ id: 'a11y-svg-title', name: 'SVG Accessibility', category: 'accessibility', severity: 'warning' }, 'warn', `${count} SVG(s) without accessible title`, { value: count, recommendation: 'Add <title> inside SVG or aria-label for decorative SVGs' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'a11y-images-decorative',
+        name: 'Decorative Images',
+        category: 'accessibility',
+        severity: 'info',
+        description: 'Decorative images should have empty alt=""',
+        check: (ctx) => {
+            const decorative = ctx.imagesDecorativeCount ?? 0;
+            const emptyAlt = ctx.imagesWithEmptyAlt ?? 0;
+            if (decorative > 0 && emptyAlt === 0) {
+                return createResult({ id: 'a11y-images-decorative', name: 'Decorative Images', category: 'accessibility', severity: 'info' }, 'info', 'Some images may be decorative - use alt="" for decorative images', { recommendation: 'For decorative images, use alt="" (empty string) not missing alt' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'a11y-buttons-aria-label',
+        name: 'Buttons with Accessible Name',
+        category: 'accessibility',
+        severity: 'error',
+        description: 'Buttons without text content must have an aria-label or title',
+        check: (ctx) => {
+            if (ctx.buttonsWithoutAriaLabel && ctx.buttonsWithoutAriaLabel > 0) {
+                return createResult({ id: 'a11y-buttons-aria-label', name: 'Buttons Accessible Name', category: 'accessibility', severity: 'error' }, 'fail', `${ctx.buttonsWithoutAriaLabel} button(s) without accessible name found`, { recommendation: 'Add descriptive text, aria-label, aria-labelledby, or title to buttons' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'a11y-links-aria-label',
+        name: 'Links with Accessible Name',
+        category: 'accessibility',
+        severity: 'error',
+        description: 'Icon-only links must have an aria-label or title',
+        check: (ctx) => {
+            if (ctx.linksWithoutAriaLabel && ctx.linksWithoutAriaLabel > 0) {
+                return createResult({ id: 'a11y-links-aria-label', name: 'Links Accessible Name', category: 'accessibility', severity: 'error' }, 'fail', `${ctx.linksWithoutAriaLabel} icon-only link(s) without accessible name found`, { recommendation: 'Add descriptive text, aria-label, aria-labelledby, or title to icon-only links' });
+            }
+            return null;
+        },
+    },
+];

package/dist/seo/rules/content.d.ts

@@ -0,0 +1,2 @@
+import { SeoRule } from './types.js';
+export declare const contentRules: SeoRule[];

package/dist/seo/rules/content.js

@@ -0,0 +1,236 @@
+import { createResult } from './types.js';
+import { SEO_THRESHOLDS } from './thresholds.js';
+export const contentRules = [
+    {
+        id: 'content-depth-word-count',
+        name: 'Content Depth (Word Count)',
+        category: 'content',
+        severity: 'warning',
+        description: 'Page should meet minimum word count for its purpose.',
+        check: (ctx) => {
+            if (ctx.wordCount === undefined)
+                return null;
+            const { minWordsSimple, minWordsRanking, minWordsAuthority } = SEO_THRESHOLDS.content;
+            const veryThinWords = SEO_THRESHOLDS.thinContent.veryThinWords;
+            if (ctx.wordCount < veryThinWords) {
+                return createResult({ id: 'content-depth-word-count', name: 'Content Depth', category: 'content', severity: 'error' }, 'fail', `Very thin content (${ctx.wordCount} words, min: ${veryThinWords})`, { recommendation: 'Add more substantial content (at least 150-300 words).' });
+            }
+            if (ctx.wordCount < minWordsSimple) {
+                return createResult({ id: 'content-depth-word-count', name: 'Content Depth', category: 'content', severity: 'warning' }, 'warn', `Thin content (${ctx.wordCount} words, min for simple: ${minWordsSimple})`, { recommendation: `Consider expanding to at least ${minWordsSimple} words for simple pages, or more for ranking.` });
+            }
+            if (ctx.wordCount < minWordsRanking) {
+                return createResult({ id: 'content-depth-word-count', name: 'Content Depth', category: 'content', severity: 'info' }, 'warn', `Content may be too short to rank (${ctx.wordCount} words, min for ranking: ${minWordsRanking})`, { recommendation: `Expand content to at least ${minWordsRanking} words for competitive keywords.` });
+            }
+            if (ctx.wordCount < minWordsAuthority) {
+                return createResult({ id: 'content-depth-word-count', name: 'Content Depth', category: 'content', severity: 'info' }, 'info', `Content is not authority-level (${ctx.wordCount} words, min for authority: ${minWordsAuthority})`, { recommendation: `For authority content, aim for ${minWordsAuthority} words or more.` });
+            }
+            return createResult({ id: 'content-depth-word-count', name: 'Content Depth', category: 'content', severity: 'info' }, 'pass', `Good content depth (${ctx.wordCount} words)`, { value: ctx.wordCount });
+        },
+    },
+    {
+        id: 'content-readability-sentence-length',
+        name: 'Readability (Sentence Length)',
+        category: 'content',
+        severity: 'info',
+        description: 'Sentences should average under 25 words for better readability.',
+        check: (ctx) => {
+            if (ctx.avgWordsPerSentence === undefined)
+                return null;
+            const max = SEO_THRESHOLDS.content.maxWordsPerSentence;
+            if (ctx.avgWordsPerSentence > max) {
+                return createResult({ id: 'content-readability-sentence-length', name: 'Readability', category: 'content', severity: 'info' }, 'warn', `Long sentences (avg ${ctx.avgWordsPerSentence} words/sentence)`, { value: ctx.avgWordsPerSentence, recommendation: `Aim for under ${max} words per sentence for better readability.` });
+            }
+            return createResult({ id: 'content-readability-sentence-length', name: 'Readability', category: 'content', severity: 'info' }, 'pass', `Good sentence length (avg ${ctx.avgWordsPerSentence} words)`, { value: ctx.avgWordsPerSentence });
+        },
+    },
+    {
+        id: 'content-paragraph-length',
+        name: 'Paragraph Length',
+        category: 'content',
+        severity: 'info',
+        description: 'Paragraphs should be concise (ideal 40-90 words) for mobile readability.',
+        check: (ctx) => {
+            if (!ctx.paragraphWordCounts || ctx.paragraphWordCounts.length === 0)
+                return null;
+            const { minWordsPerParagraph, maxWordsPerParagraph } = SEO_THRESHOLDS.content;
+            let tooShort = 0;
+            let tooLong = 0;
+            ctx.paragraphWordCounts.forEach(count => {
+                if (count < minWordsPerParagraph)
+                    tooShort++;
+                if (count > maxWordsPerParagraph)
+                    tooLong++;
+            });
+            if (tooShort > 0 || tooLong > 0) {
+                let message = '';
+                const recs = [];
+                if (tooShort > 0) {
+                    message += `${tooShort} paragraph(s) are too short (min: ${minWordsPerParagraph} words). `;
+                    recs.push('Expand short paragraphs.');
+                }
+                if (tooLong > 0) {
+                    message += `${tooLong} paragraph(s) are too long (max: ${maxWordsPerParagraph} words).`;
+                    recs.push('Break long paragraphs into smaller ones.');
+                }
+                return createResult({ id: 'content-paragraph-length', name: 'Paragraph Length', category: 'content', severity: 'warning' }, 'warn', message.trim(), { recommendation: `Aim for paragraphs between ${minWordsPerParagraph}-${maxWordsPerParagraph} words. ${recs.join(' ')}` });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'content-lists-presence',
+        name: 'Lists Usage',
+        category: 'content',
+        severity: 'info',
+        description: 'Use lists (ul/ol) to improve readability and SGE compatibility.',
+        check: (ctx) => {
+            if (ctx.listCount === undefined || ctx.listCount === 0) {
+                return createResult({ id: 'content-lists-presence', name: 'Lists Usage', category: 'content', severity: 'info' }, 'info', 'No lists (ul/ol) found', { recommendation: 'Consider using bullet points or numbered lists for better scannability and AI summarization.' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'content-subheading-frequency',
+        name: 'Subheading Frequency',
+        category: 'content',
+        severity: 'info',
+        description: 'Subheadings (H2/H3) should be used frequently to break up content.',
+        check: (ctx) => {
+            const idealFrequencyPer100Words = 0.5;
+            if (ctx.wordCount && ctx.wordCount > 300 && (ctx.subheadingFrequency ?? 0) < idealFrequencyPer100Words) {
+                return createResult({ id: 'content-subheading-frequency', name: 'Subheading Frequency', category: 'content', severity: 'info' }, 'warn', `Low subheading frequency (${(ctx.subheadingFrequency ?? 0).toFixed(2)} per 100 words)`, { recommendation: `Add more subheadings (H2/H3) to break up long text blocks.` });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'content-emphasis-tags',
+        name: 'Emphasis Tags Usage',
+        category: 'content',
+        severity: 'info',
+        description: 'Use strong/em tags moderately for emphasis, avoid keyword stuffing.',
+        check: (ctx) => {
+            const totalEmphasisTags = (ctx.strongTagCount ?? 0) + (ctx.emTagCount ?? 0);
+            if (ctx.wordCount && ctx.wordCount > 200 && totalEmphasisTags === 0) {
+                return createResult({ id: 'content-emphasis-tags', name: 'Emphasis Tags Usage', category: 'content', severity: 'info' }, 'info', 'No strong/em tags found in substantial content', { recommendation: 'Use <strong> or <em> tags to highlight important keywords or phrases.' });
+            }
+            const emphasisRatio = totalEmphasisTags / (ctx.wordCount || 1);
+            const maxEmphasisRatio = 0.05;
+            if (ctx.wordCount && ctx.wordCount > 100 && emphasisRatio > maxEmphasisRatio) {
+                return createResult({ id: 'content-emphasis-tags', name: 'Emphasis Tags Usage', category: 'content', severity: 'warning' }, 'warn', `Potentially excessive emphasis tags (${totalEmphasisTags} tags for ${ctx.wordCount} words)`, { recommendation: 'Moderate the use of <strong> and <em> tags to avoid over-optimization.' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'multimedia-video-audio',
+        name: 'Multimedia Content',
+        category: 'content',
+        severity: 'info',
+        description: 'Rich content with videos and audio can enhance user experience.',
+        check: (ctx) => {
+            const totalMultimedia = (ctx.videoCount ?? 0) + (ctx.audioCount ?? 0);
+            if (totalMultimedia === 0 && ctx.wordCount && ctx.wordCount > 500) {
+                return createResult({ id: 'multimedia-video-audio', name: 'Multimedia Content', category: 'content', severity: 'info' }, 'info', 'No video or audio elements found for substantial content', { recommendation: 'Consider adding relevant videos, audio, or other rich media to engage users.' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'content-sge-optimization',
+        name: 'AI Overview (SGE) Optimization',
+        category: 'content',
+        severity: 'info',
+        description: 'Optimize content for Google AI Overviews by using question-based headings and clear lists.',
+        check: (ctx) => {
+            if (ctx.wordCount && ctx.wordCount > 300) {
+                let messages = [];
+                let recommendation = '';
+                if (!ctx.hasQuestionHeadings) {
+                    messages.push('No question-based headings (H2/H3) found.');
+                    recommendation += 'Use H2/H3 headings that phrase common questions (e.g., "What is X?", "How to do Y?"). ';
+                }
+                if (ctx.listCount === 0) {
+                    messages.push('No lists (ul/ol) found.');
+                    recommendation += 'Incorporate clear numbered or bulleted lists for steps, features, or summaries.';
+                }
+                if (messages.length > 0) {
+                    return createResult({ id: 'content-sge-optimization', name: 'AI Overview Optimization', category: 'content', severity: 'info' }, 'info', `Content could be better optimized for AI Overviews: ${messages.join(' ')}`, { recommendation: recommendation.trim() });
+                }
+            }
+            return null;
+        },
+    },
+    {
+        id: 'content-flesch-readability',
+        name: 'Flesch Reading Ease Score',
+        category: 'content',
+        severity: 'info',
+        description: 'Measures readability, aiming for a Flesch score above 60 for broad audiences.',
+        check: (ctx) => {
+            if (ctx.fleschReadingEase === undefined) {
+                return createResult({ id: 'content-flesch-readability', name: 'Flesch Reading Ease', category: 'content', severity: 'info' }, 'info', 'Flesch Reading Ease score could not be calculated.', { recommendation: 'To enable Flesch score analysis, ensure the analyzer has capabilities to count syllables per word.' });
+            }
+            const score = ctx.fleschReadingEase;
+            if (score < 60) {
+                return createResult({ id: 'content-flesch-readability', name: 'Flesch Reading Ease', category: 'content', severity: 'warning' }, 'warn', `Low Flesch Reading Ease score: ${score.toFixed(2)} (target > 60)`, { value: score, recommendation: 'Simplify sentence structure and vocabulary to improve readability for a broader audience.' });
+            }
+            return createResult({ id: 'content-flesch-readability', name: 'Flesch Reading Ease', category: 'content', severity: 'info' }, 'pass', `Good Flesch Reading Ease score: ${score.toFixed(2)}`, { value: score });
+        },
+    },
+    {
+        id: 'content-faq-mandatory',
+        name: 'Mandatory FAQ Section',
+        category: 'content',
+        severity: 'info',
+        description: 'For comprehensive content, an FAQ section is recommended.',
+        check: (ctx) => {
+            if (ctx.wordCount && ctx.wordCount > SEO_THRESHOLDS.content.minWordsAuthority && (ctx.faqCount ?? 0) < 3) {
+                return createResult({ id: 'content-faq-mandatory', name: 'FAQ Section', category: 'content', severity: 'info' }, 'warn', 'Consider adding a dedicated FAQ section for comprehensive content', { recommendation: 'Include 3-7 common questions as H3s and optionally use Schema.org FAQPage markup for rich results.' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'content-image-text-proportion',
+        name: 'Image-Text Proportion',
+        category: 'content',
+        severity: 'info',
+        description: 'Maintain a healthy image-to-text ratio for engaging content.',
+        check: (ctx) => {
+            if (ctx.wordCount === undefined || ctx.wordCount < 200 || ctx.totalImages === undefined || ctx.totalImages === 0)
+                return null;
+            const { min: minWords, max: maxWords } = SEO_THRESHOLDS.content.imageWordRatio;
+            const actualWordsPerImage = ctx.wordCount / ctx.totalImages;
+            if (actualWordsPerImage > maxWords) {
+                return createResult({ id: 'content-image-text-proportion', name: 'Image-Text Proportion', category: 'content', severity: 'info' }, 'warn', `Low image density (1 image per ${actualWordsPerImage.toFixed(0)} words, ideal: 1 per ${minWords}-${maxWords})`, { recommendation: 'Add more relevant images to break up text and improve engagement.' });
+            }
+            if (actualWordsPerImage < minWords) {
+                return createResult({ id: 'content-image-text-proportion', name: 'Image-Text Proportion', category: 'content', severity: 'info' }, 'warn', `High image density (1 image per ${actualWordsPerImage.toFixed(0)} words, ideal: 1 per ${minWords}-${maxWords})`, { recommendation: 'Ensure images are relevant and not excessive, as too many can be distracting.' });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'content-main-keyword-redundancy',
+        name: 'Main Keyword Redundancy',
+        category: 'content',
+        severity: 'info',
+        description: 'Avoid keyword stuffing in key areas (title, H1, first paragraph, image alt).',
+        check: (ctx) => {
+            if (!ctx.mainKeyword || !ctx.title || !ctx.h1Text || !ctx.metaDescription || !ctx.paragraphWordCounts || ctx.paragraphWordCounts.length === 0)
+                return null;
+            const keyword = ctx.mainKeyword.toLowerCase();
+            let redundancyCount = 0;
+            if (ctx.title.toLowerCase().includes(keyword))
+                redundancyCount++;
+            if (ctx.h1Text.toLowerCase().includes(keyword))
+                redundancyCount++;
+            if (redundancyCount > SEO_THRESHOLDS.content.redundancyTolerance) {
+                return createResult({ id: 'content-main-keyword-redundancy', name: 'Main Keyword Redundancy', category: 'content', severity: 'warning' }, 'warn', `Main keyword "${ctx.mainKeyword}" appears too often in key SEO elements.`, { recommendation: 'Ensure natural language use of keywords. Avoid over-optimization (keyword stuffing) in title, H1, meta description, and alt texts.' });
+            }
+            return null;
+        },
+    },
+];

package/dist/seo/rules/crawl.d.ts

@@ -0,0 +1,2 @@
+import { SeoRule } from './types.js';
+export declare const crawlRules: SeoRule[];