@rankcli/agent-runtime 0.0.9 → 0.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +90 -196
  2. package/dist/analyzer-GMURJADU.mjs +7 -0
  3. package/dist/chunk-2JADKV3Z.mjs +244 -0
  4. package/dist/chunk-3ZSCLNTW.mjs +557 -0
  5. package/dist/chunk-4E4MQOSP.mjs +374 -0
  6. package/dist/chunk-6BWS3CLP.mjs +16 -0
  7. package/dist/chunk-AK2IC22C.mjs +206 -0
  8. package/dist/chunk-K6VSXDD6.mjs +293 -0
  9. package/dist/chunk-M27NQCWW.mjs +303 -0
  10. package/dist/{chunk-YNZYHEYM.mjs → chunk-PJLNXOLN.mjs} +0 -14
  11. package/dist/chunk-VSQD74I7.mjs +474 -0
  12. package/dist/core-web-vitals-analyzer-TE6LQJMS.mjs +7 -0
  13. package/dist/geo-analyzer-D47LTMMA.mjs +25 -0
  14. package/dist/image-optimization-analyzer-XP4OQGRP.mjs +9 -0
  15. package/dist/index.d.mts +612 -17
  16. package/dist/index.d.ts +612 -17
  17. package/dist/index.js +9020 -2686
  18. package/dist/index.mjs +4177 -328
  19. package/dist/internal-linking-analyzer-MRMBV7NM.mjs +9 -0
  20. package/dist/mobile-seo-analyzer-67HNQ7IO.mjs +7 -0
  21. package/dist/security-headers-analyzer-3ZUQARS5.mjs +9 -0
  22. package/dist/structured-data-analyzer-2I4NQAUP.mjs +9 -0
  23. package/package.json +2 -2
  24. package/src/analyzers/core-web-vitals-analyzer.test.ts +236 -0
  25. package/src/analyzers/core-web-vitals-analyzer.ts +557 -0
  26. package/src/analyzers/geo-analyzer.test.ts +310 -0
  27. package/src/analyzers/geo-analyzer.ts +814 -0
  28. package/src/analyzers/image-optimization-analyzer.test.ts +145 -0
  29. package/src/analyzers/image-optimization-analyzer.ts +348 -0
  30. package/src/analyzers/index.ts +233 -0
  31. package/src/analyzers/internal-linking-analyzer.test.ts +141 -0
  32. package/src/analyzers/internal-linking-analyzer.ts +419 -0
  33. package/src/analyzers/mobile-seo-analyzer.test.ts +140 -0
  34. package/src/analyzers/mobile-seo-analyzer.ts +455 -0
  35. package/src/analyzers/security-headers-analyzer.test.ts +115 -0
  36. package/src/analyzers/security-headers-analyzer.ts +318 -0
  37. package/src/analyzers/structured-data-analyzer.test.ts +210 -0
  38. package/src/analyzers/structured-data-analyzer.ts +590 -0
  39. package/src/audit/engine.ts +3 -3
  40. package/src/audit/types.ts +3 -2
  41. package/src/fixer/framework-fixes.test.ts +489 -0
  42. package/src/fixer/framework-fixes.ts +3418 -0
  43. package/src/frameworks/detector.ts +642 -114
  44. package/src/frameworks/suggestion-engine.ts +38 -1
  45. package/src/index.ts +3 -0
  46. package/src/types.ts +15 -1
  47. package/dist/analyzer-2CSWIQGD.mjs +0 -6
package/src/analyzers/image-optimization-analyzer.test.ts ADDED
@@ -0,0 +1,145 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import { analyzeImages, generateResponsiveImage } from './image-optimization-analyzer.js';
3
+
4
+ describe('Image Optimization Analyzer', () => {
5
+ describe('analyzeImages', () => {
6
+ it('detects images with alt text', () => {
7
+ const html = `
8
+ <html><body>
9
+ <img src="/photo1.jpg" alt="A beautiful sunset">
10
+ <img src="/photo2.jpg" alt="Mountain landscape">
11
+ </body></html>
12
+ `;
13
+ const result = analyzeImages(html, 'https://example.com');
14
+ expect(result.totalImages).toBe(2);
15
+ expect(result.imagesWithAlt).toBe(2);
16
+ });
17
+
18
+ it('detects images without alt text', () => {
19
+ const html = `
20
+ <html><body>
21
+ <img src="/photo1.jpg">
22
+ <img src="/photo2.jpg" alt="Has alt">
23
+ </body></html>
24
+ `;
25
+ const result = analyzeImages(html, 'https://example.com');
26
+ expect(result.missingAlt.length).toBe(1);
27
+ expect(result.issues.some(i => i.code === 'IMG_MISSING_ALT')).toBe(true);
28
+ });
29
+
30
+ it('detects images with dimensions', () => {
31
+ const html = `
32
+ <html><body>
33
+ <img src="/photo.jpg" alt="Test" width="800" height="600">
34
+ </body></html>
35
+ `;
36
+ const result = analyzeImages(html, 'https://example.com');
37
+ expect(result.imagesWithDimensions).toBe(1);
38
+ });
39
+
40
+ it('detects images without dimensions', () => {
41
+ const html = `
42
+ <html><body>
43
+ <img src="/photo1.jpg" alt="Test">
44
+ <img src="/photo2.jpg" alt="Test">
45
+ </body></html>
46
+ `;
47
+ const result = analyzeImages(html, 'https://example.com');
48
+ expect(result.issues.some(i => i.code === 'IMG_MISSING_DIMENSIONS')).toBe(true);
49
+ });
50
+
51
+ it('detects modern image formats', () => {
52
+ const html = `
53
+ <html><body>
54
+ <img src="/photo.webp" alt="Test" width="800" height="600">
55
+ <img src="/photo.avif" alt="Test" width="800" height="600">
56
+ </body></html>
57
+ `;
58
+ const result = analyzeImages(html, 'https://example.com');
59
+ expect(result.modernFormats).toBe(2);
60
+ expect(result.legacyFormats).toBe(0);
61
+ });
62
+
63
+ it('detects legacy image formats', () => {
64
+ const html = `
65
+ <html><body>
66
+ <img src="/photo.jpg" alt="Test" width="800" height="600">
67
+ <img src="/photo.png" alt="Test" width="800" height="600">
68
+ </body></html>
69
+ `;
70
+ const result = analyzeImages(html, 'https://example.com');
71
+ expect(result.legacyFormats).toBe(2);
72
+ expect(result.issues.some(i => i.code === 'IMG_NO_MODERN_FORMATS')).toBe(true);
73
+ });
74
+
75
+ it('detects lazy loading', () => {
76
+ const html = `
77
+ <html><body>
78
+ <img src="/photo1.jpg" alt="Test" loading="lazy">
79
+ <img src="/photo2.jpg" alt="Test">
80
+ </body></html>
81
+ `;
82
+ const result = analyzeImages(html, 'https://example.com');
83
+ expect(result.imagesWithLazyLoading).toBe(1);
84
+ });
85
+
86
+ it('warns about lazy loading hero images', () => {
87
+ const html = `
88
+ <html><body>
89
+ <img src="/hero.jpg" alt="Hero" loading="lazy" width="1200" height="600">
90
+ </body></html>
91
+ `;
92
+ const result = analyzeImages(html, 'https://example.com');
93
+ expect(result.issues.some(i => i.code === 'IMG_HERO_LAZY')).toBe(true);
94
+ });
95
+
96
+ it('accepts decorative images with empty alt', () => {
97
+ const html = `
98
+ <html><body>
99
+ <img src="/decoration.png" alt="" role="presentation">
100
+ </body></html>
101
+ `;
102
+ const result = analyzeImages(html, 'https://example.com');
103
+ expect(result.imagesWithAlt).toBe(1);
104
+ expect(result.decorativeWithoutRole.length).toBe(0);
105
+ });
106
+
107
+ it('warns decorative images without role', () => {
108
+ const html = `
109
+ <html><body>
110
+ <img src="/decoration.png" alt="">
111
+ </body></html>
112
+ `;
113
+ const result = analyzeImages(html, 'https://example.com');
114
+ expect(result.decorativeWithoutRole.length).toBe(1);
115
+ });
116
+ });
117
+
118
+ describe('generateResponsiveImage', () => {
119
+ it('generates responsive image HTML', () => {
120
+ const html = generateResponsiveImage({
121
+ src: '/images/hero.jpg',
122
+ alt: 'Hero image',
123
+ widths: [400, 800, 1200],
124
+ sizes: '(max-width: 768px) 100vw, 50vw',
125
+ });
126
+
127
+ expect(html).toContain('<picture>');
128
+ expect(html).toContain('srcset=');
129
+ expect(html).toContain('type="image/webp"');
130
+ expect(html).toContain('alt="Hero image"');
131
+ expect(html).toContain('loading="lazy"');
132
+ });
133
+
134
+ it('respects loading option', () => {
135
+ const html = generateResponsiveImage({
136
+ src: '/images/hero.jpg',
137
+ alt: 'Hero image',
138
+ widths: [800],
139
+ loading: 'eager',
140
+ });
141
+
142
+ expect(html).toContain('loading="eager"');
143
+ });
144
+ });
145
+ });
package/src/analyzers/image-optimization-analyzer.ts ADDED
@@ -0,0 +1,348 @@
1
+ /**
2
+ * Image Optimization Analyzer
3
+ *
4
+ * Analyzes images for SEO and performance optimization.
5
+ * Checks formats, dimensions, alt text, lazy loading, and compression indicators.
6
+ */
7
+
8
+ import * as cheerio from 'cheerio';
9
+ import type { AuditIssue } from '../audit/types.js';
10
+
11
+ export interface ImageAnalysisResult {
12
+ score: number;
13
+ totalImages: number;
14
+ imagesWithAlt: number;
15
+ imagesWithDimensions: number;
16
+ imagesWithLazyLoading: number;
17
+ modernFormats: number;
18
+ legacyFormats: number;
19
+ oversizedImages: ImageInfo[];
20
+ missingAlt: ImageInfo[];
21
+ decorativeWithoutRole: ImageInfo[];
22
+ issues: AuditIssue[];
23
+ recommendations: string[];
24
+ }
25
+
26
+ export interface ImageInfo {
27
+ src: string;
28
+ alt?: string;
29
+ width?: number;
30
+ height?: number;
31
+ format?: string;
32
+ loading?: string;
33
+ issues: string[];
34
+ }
35
+
36
+ const MODERN_FORMATS = ['webp', 'avif'];
37
+ const LEGACY_FORMATS = ['jpg', 'jpeg', 'png', 'gif', 'bmp'];
38
+ const MAX_RECOMMENDED_DIMENSION = 2000;
39
+
40
+ /**
41
+ * Extract format from image URL
42
+ */
43
+ function getImageFormat(src: string): string | undefined {
44
+ // Handle data URLs
45
+ if (src.startsWith('data:image/')) {
46
+ const match = src.match(/data:image\/(\w+)/);
47
+ return match ? match[1] : undefined;
48
+ }
49
+
50
+ // Handle regular URLs
51
+ try {
52
+ const url = new URL(src, 'https://example.com');
53
+ const pathname = url.pathname.toLowerCase();
54
+ const ext = pathname.split('.').pop();
55
+ return ext && ext.length <= 5 ? ext : undefined;
56
+ } catch {
57
+ const ext = src.split('.').pop()?.toLowerCase();
58
+ return ext && ext.length <= 5 ? ext : undefined;
59
+ }
60
+ }
61
+
62
+ /**
63
+ * Analyze all images on a page
64
+ */
65
+ export function analyzeImages(html: string, url: string): ImageAnalysisResult {
66
+ const $ = cheerio.load(html);
67
+ const issues: AuditIssue[] = [];
68
+ const recommendations: string[] = [];
69
+ let score = 100;
70
+
71
+ const allImages: ImageInfo[] = [];
72
+ const missingAlt: ImageInfo[] = [];
73
+ const oversizedImages: ImageInfo[] = [];
74
+ const decorativeWithoutRole: ImageInfo[] = [];
75
+
76
+ let imagesWithAlt = 0;
77
+ let imagesWithDimensions = 0;
78
+ let imagesWithLazyLoading = 0;
79
+ let modernFormats = 0;
80
+ let legacyFormats = 0;
81
+
82
+ // Analyze each image
83
+ $('img').each((_, el) => {
84
+ const $img = $(el);
85
+ const src = $img.attr('src') || $img.attr('data-src') || '';
86
+ const alt = $img.attr('alt');
87
+ const width = parseInt($img.attr('width') || '0');
88
+ const height = parseInt($img.attr('height') || '0');
89
+ const loading = $img.attr('loading');
90
+ const role = $img.attr('role');
91
+ const format = getImageFormat(src);
92
+
93
+ const imageIssues: string[] = [];
94
+
95
+ const imgInfo: ImageInfo = {
96
+ src: src.substring(0, 200), // Truncate long data URLs
97
+ alt,
98
+ width: width || undefined,
99
+ height: height || undefined,
100
+ format,
101
+ loading,
102
+ issues: imageIssues,
103
+ };
104
+
105
+ // Check alt attribute
106
+ if (alt === undefined) {
107
+ imageIssues.push('Missing alt attribute');
108
+ missingAlt.push(imgInfo);
109
+ } else if (alt === '') {
110
+ // Empty alt is valid for decorative images, but should have role="presentation"
111
+ if (role !== 'presentation' && role !== 'none') {
112
+ imageIssues.push('Empty alt without role="presentation"');
113
+ decorativeWithoutRole.push(imgInfo);
114
+ }
115
+ imagesWithAlt++; // Empty alt still counts as having alt
116
+ } else {
117
+ imagesWithAlt++;
118
+
119
+ // Check for poor alt text patterns
120
+ if (alt.toLowerCase().includes('image') ||
121
+ alt.toLowerCase().includes('picture') ||
122
+ alt.toLowerCase().includes('photo')) {
123
+ imageIssues.push('Alt text contains generic terms');
124
+ }
125
+
126
+ if (alt.length > 125) {
127
+ imageIssues.push('Alt text too long (>125 chars)');
128
+ }
129
+
130
+ // Check for filename-like alt
131
+ if (/\.(jpg|jpeg|png|gif|webp|svg)$/i.test(alt)) {
132
+ imageIssues.push('Alt text appears to be a filename');
133
+ }
134
+ }
135
+
136
+ // Check dimensions
137
+ if (width > 0 && height > 0) {
138
+ imagesWithDimensions++;
139
+
140
+ // Check for oversized images
141
+ if (width > MAX_RECOMMENDED_DIMENSION || height > MAX_RECOMMENDED_DIMENSION) {
142
+ imageIssues.push(`Dimensions too large (${width}x${height})`);
143
+ oversizedImages.push(imgInfo);
144
+ }
145
+ } else {
146
+ imageIssues.push('Missing width/height attributes');
147
+ }
148
+
149
+ // Check lazy loading
150
+ if (loading === 'lazy') {
151
+ imagesWithLazyLoading++;
152
+ }
153
+
154
+ // Check format
155
+ if (format) {
156
+ if (MODERN_FORMATS.includes(format)) {
157
+ modernFormats++;
158
+ } else if (LEGACY_FORMATS.includes(format)) {
159
+ legacyFormats++;
160
+ }
161
+ }
162
+
163
+ allImages.push(imgInfo);
164
+ });
165
+
166
+ const totalImages = allImages.length;
167
+
168
+ // Generate issues
169
+ if (missingAlt.length > 0) {
170
+ const percentage = Math.round((missingAlt.length / totalImages) * 100);
171
+ const severity = percentage > 50 ? 'critical' : percentage > 20 ? 'warning' : 'info';
172
+
173
+ issues.push({
174
+ code: 'IMG_MISSING_ALT',
175
+ severity,
176
+ category: 'content',
177
+ title: `${missingAlt.length} images missing alt attribute`,
178
+ description: `${percentage}% of images lack alt text, hurting accessibility and SEO.`,
179
+ impact: 'Screen readers cannot describe images; search engines lose context',
180
+ howToFix: 'Add descriptive alt text to all images. Use alt="" for decorative images.',
181
+ affectedUrls: [url],
182
+ });
183
+ score -= Math.min(missingAlt.length * 3, 25);
184
+ }
185
+
186
+ const missingDimensions = totalImages - imagesWithDimensions;
187
+ if (missingDimensions > 0) {
188
+ issues.push({
189
+ code: 'IMG_MISSING_DIMENSIONS',
190
+ severity: 'warning',
191
+ category: 'performance',
192
+ title: `${missingDimensions} images missing width/height`,
193
+ description: 'Images without explicit dimensions cause layout shifts (CLS).',
194
+ impact: 'Poor Core Web Vitals, degraded user experience',
195
+ howToFix: 'Add width and height attributes to all images.',
196
+ affectedUrls: [url],
197
+ });
198
+ score -= Math.min(missingDimensions * 2, 20);
199
+ }
200
+
201
+ if (legacyFormats > 0 && modernFormats === 0) {
202
+ issues.push({
203
+ code: 'IMG_NO_MODERN_FORMATS',
204
+ severity: 'warning',
205
+ category: 'performance',
206
+ title: 'No modern image formats (WebP/AVIF)',
207
+ description: `All ${legacyFormats} images use legacy formats (JPEG/PNG).`,
208
+ impact: 'Larger file sizes, slower page load',
209
+ howToFix: 'Convert images to WebP or AVIF format. Use <picture> element for fallbacks.',
210
+ affectedUrls: [url],
211
+ });
212
+ score -= 10;
213
+ recommendations.push('Convert images to WebP/AVIF for 30-50% smaller file sizes');
214
+ }
215
+
216
+ if (oversizedImages.length > 0) {
217
+ issues.push({
218
+ code: 'IMG_OVERSIZED',
219
+ severity: 'warning',
220
+ category: 'performance',
221
+ title: `${oversizedImages.length} images have excessive dimensions`,
222
+ description: `Images larger than ${MAX_RECOMMENDED_DIMENSION}px may be wasteful on most screens.`,
223
+ impact: 'Unnecessary bandwidth usage, slower loading',
224
+ howToFix: 'Resize images to match their display size. Use srcset for responsive images.',
225
+ affectedUrls: [url],
226
+ });
227
+ score -= Math.min(oversizedImages.length * 3, 15);
228
+ }
229
+
230
+ // Check hero/above-fold images with lazy loading
231
+ const firstImage = allImages[0];
232
+ if (firstImage?.loading === 'lazy') {
233
+ issues.push({
234
+ code: 'IMG_HERO_LAZY',
235
+ severity: 'warning',
236
+ category: 'performance',
237
+ title: 'First image has loading="lazy"',
238
+ description: 'Above-the-fold images should not be lazy-loaded as it delays LCP.',
239
+ impact: 'Slower Largest Contentful Paint',
240
+ howToFix: 'Remove loading="lazy" from hero/above-fold images. Keep it for below-fold images.',
241
+ affectedUrls: [url],
242
+ });
243
+ score -= 10;
244
+ }
245
+
246
+ // Check for images without lazy loading (below potential fold)
247
+ const belowFoldWithoutLazy = allImages.slice(3).filter(img => img.loading !== 'lazy');
248
+ if (belowFoldWithoutLazy.length > 5) {
249
+ recommendations.push(`Consider adding loading="lazy" to ${belowFoldWithoutLazy.length} below-fold images`);
250
+ }
251
+
252
+ // Check for decorative images without proper role
253
+ if (decorativeWithoutRole.length > 0) {
254
+ issues.push({
255
+ code: 'IMG_DECORATIVE_NO_ROLE',
256
+ severity: 'info',
257
+ category: 'content',
258
+ title: `${decorativeWithoutRole.length} decorative images without role`,
259
+ description: 'Images with empty alt should have role="presentation" for accessibility.',
260
+ impact: 'Minor accessibility issue',
261
+ howToFix: 'Add role="presentation" to decorative images with empty alt.',
262
+ affectedUrls: [url],
263
+ });
264
+ }
265
+
266
+ // Check for background images (informational)
267
+ const elementsWithBgImage = $('[style*="background-image"], [style*="background:"]').length;
268
+ if (elementsWithBgImage > 3) {
269
+ recommendations.push(`${elementsWithBgImage} CSS background images detected - ensure they're not content images`);
270
+ }
271
+
272
+ // Check for SVG images (good for icons)
273
+ const svgImages = $('svg, img[src$=".svg"]').length;
274
+ if (svgImages > 0) {
275
+ // This is positive, no action needed
276
+ }
277
+
278
+ // Positive recommendations
279
+ if (totalImages > 0 && imagesWithAlt === totalImages) {
280
+ recommendations.push('✓ All images have alt attributes');
281
+ }
282
+
283
+ if (modernFormats > legacyFormats) {
284
+ recommendations.push('✓ Majority of images use modern formats');
285
+ }
286
+
287
+ return {
288
+ score: Math.max(0, Math.min(100, score)),
289
+ totalImages,
290
+ imagesWithAlt,
291
+ imagesWithDimensions,
292
+ imagesWithLazyLoading,
293
+ modernFormats,
294
+ legacyFormats,
295
+ oversizedImages,
296
+ missingAlt,
297
+ decorativeWithoutRole,
298
+ issues,
299
+ recommendations,
300
+ };
301
+ }
302
+
303
+ /**
304
+ * Generate responsive image HTML
305
+ */
306
+ export function generateResponsiveImage(options: {
307
+ src: string;
308
+ alt: string;
309
+ widths: number[];
310
+ sizes?: string;
311
+ loading?: 'lazy' | 'eager';
312
+ className?: string;
313
+ }): string {
314
+ const { src, alt, widths, sizes = '100vw', loading = 'lazy', className } = options;
315
+
316
+ // Assume src is the largest size
317
+ const basename = src.replace(/\.[^.]+$/, '');
318
+ const ext = src.split('.').pop() || 'jpg';
319
+
320
+ const srcset = widths
321
+ .map(w => `${basename}-${w}w.webp ${w}w`)
322
+ .join(', ');
323
+
324
+ const fallbackSrcset = widths
325
+ .map(w => `${basename}-${w}w.${ext} ${w}w`)
326
+ .join(', ');
327
+
328
+ return `<picture>
329
+ <source
330
+ type="image/webp"
331
+ srcset="${srcset}"
332
+ sizes="${sizes}"
333
+ />
334
+ <source
335
+ type="image/${ext === 'jpg' ? 'jpeg' : ext}"
336
+ srcset="${fallbackSrcset}"
337
+ sizes="${sizes}"
338
+ />
339
+ <img
340
+ src="${src}"
341
+ alt="${alt}"
342
+ width="${widths[widths.length - 1]}"
343
+ height="auto"
344
+ loading="${loading}"${className ? `\n class="${className}"` : ''}
345
+ decoding="async"
346
+ />
347
+ </picture>`;
348
+ }