@rankcli/agent-runtime 0.0.14 → 0.0.16

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 (199) hide show
  1. package/dist/index.d.mts +77 -393
  2. package/dist/index.d.ts +77 -393
  3. package/dist/index.js +417 -6443
  4. package/dist/index.mjs +296 -6313
  5. package/package.json +6 -1
  6. package/scripts/build-deno.ts +0 -134
  7. package/src/analyzers/core-web-vitals-analyzer.test.ts +0 -236
  8. package/src/analyzers/core-web-vitals-analyzer.ts +0 -557
  9. package/src/analyzers/geo-analyzer.test.ts +0 -310
  10. package/src/analyzers/geo-analyzer.ts +0 -814
  11. package/src/analyzers/image-optimization-analyzer.test.ts +0 -145
  12. package/src/analyzers/image-optimization-analyzer.ts +0 -348
  13. package/src/analyzers/index.ts +0 -233
  14. package/src/analyzers/internal-linking-analyzer.test.ts +0 -141
  15. package/src/analyzers/internal-linking-analyzer.ts +0 -419
  16. package/src/analyzers/mobile-seo-analyzer.test.ts +0 -140
  17. package/src/analyzers/mobile-seo-analyzer.ts +0 -455
  18. package/src/analyzers/security-headers-analyzer.test.ts +0 -115
  19. package/src/analyzers/security-headers-analyzer.ts +0 -318
  20. package/src/analyzers/structured-data-analyzer.test.ts +0 -210
  21. package/src/analyzers/structured-data-analyzer.ts +0 -590
  22. package/src/audit/ai/analyzer.ts +0 -347
  23. package/src/audit/ai/index.ts +0 -29
  24. package/src/audit/ai/prompts/content-analysis.ts +0 -271
  25. package/src/audit/ai/types.ts +0 -179
  26. package/src/audit/checks/additional-checks.ts +0 -439
  27. package/src/audit/checks/ai-citation-worthiness.ts +0 -399
  28. package/src/audit/checks/ai-content-structure.ts +0 -325
  29. package/src/audit/checks/ai-readiness.ts +0 -339
  30. package/src/audit/checks/anchor-text.ts +0 -179
  31. package/src/audit/checks/answer-conciseness.ts +0 -322
  32. package/src/audit/checks/asset-minification.ts +0 -270
  33. package/src/audit/checks/bing-optimization.ts +0 -206
  34. package/src/audit/checks/brand-mention-optimization.ts +0 -349
  35. package/src/audit/checks/caching-headers.ts +0 -305
  36. package/src/audit/checks/canonical-advanced.ts +0 -150
  37. package/src/audit/checks/canonical-domain.ts +0 -196
  38. package/src/audit/checks/citation-quality.ts +0 -358
  39. package/src/audit/checks/client-rendering.ts +0 -542
  40. package/src/audit/checks/color-contrast.ts +0 -342
  41. package/src/audit/checks/content-freshness.ts +0 -170
  42. package/src/audit/checks/content-science.ts +0 -589
  43. package/src/audit/checks/conversion-elements.ts +0 -526
  44. package/src/audit/checks/crawlability.ts +0 -220
  45. package/src/audit/checks/directory-listing.ts +0 -172
  46. package/src/audit/checks/dom-analysis.ts +0 -191
  47. package/src/audit/checks/dom-size.ts +0 -246
  48. package/src/audit/checks/duplicate-content.ts +0 -194
  49. package/src/audit/checks/eeat-signals.ts +0 -990
  50. package/src/audit/checks/entity-seo.ts +0 -396
  51. package/src/audit/checks/featured-snippet.ts +0 -473
  52. package/src/audit/checks/freshness-signals.ts +0 -443
  53. package/src/audit/checks/funnel-intent.ts +0 -463
  54. package/src/audit/checks/hreflang.ts +0 -174
  55. package/src/audit/checks/html-compliance.ts +0 -302
  56. package/src/audit/checks/image-dimensions.ts +0 -167
  57. package/src/audit/checks/images.ts +0 -160
  58. package/src/audit/checks/indexnow.ts +0 -275
  59. package/src/audit/checks/interactive-tools.ts +0 -475
  60. package/src/audit/checks/internal-link-graph.ts +0 -436
  61. package/src/audit/checks/keyword-analysis.ts +0 -239
  62. package/src/audit/checks/keyword-cannibalization.ts +0 -385
  63. package/src/audit/checks/keyword-placement.ts +0 -471
  64. package/src/audit/checks/links.ts +0 -273
  65. package/src/audit/checks/llms-txt.ts +0 -224
  66. package/src/audit/checks/local-seo.ts +0 -296
  67. package/src/audit/checks/mobile.ts +0 -167
  68. package/src/audit/checks/modern-images.ts +0 -226
  69. package/src/audit/checks/navboost-signals.ts +0 -395
  70. package/src/audit/checks/on-page.ts +0 -209
  71. package/src/audit/checks/page-resources.ts +0 -285
  72. package/src/audit/checks/pagination.ts +0 -180
  73. package/src/audit/checks/performance.ts +0 -153
  74. package/src/audit/checks/platform-presence.ts +0 -580
  75. package/src/audit/checks/redirect-analysis.ts +0 -153
  76. package/src/audit/checks/redirect-chain.ts +0 -389
  77. package/src/audit/checks/resource-hints.ts +0 -420
  78. package/src/audit/checks/responsive-css.ts +0 -247
  79. package/src/audit/checks/responsive-images.ts +0 -396
  80. package/src/audit/checks/review-ecosystem.ts +0 -415
  81. package/src/audit/checks/robots-validation.ts +0 -373
  82. package/src/audit/checks/security-headers.ts +0 -188
  83. package/src/audit/checks/security.ts +0 -144
  84. package/src/audit/checks/serp-preview.ts +0 -251
  85. package/src/audit/checks/site-maturity.ts +0 -453
  86. package/src/audit/checks/social-meta.test.ts +0 -275
  87. package/src/audit/checks/social-meta.ts +0 -134
  88. package/src/audit/checks/soft-404.ts +0 -151
  89. package/src/audit/checks/structured-data.ts +0 -238
  90. package/src/audit/checks/tech-detection.ts +0 -496
  91. package/src/audit/checks/topical-clusters.ts +0 -435
  92. package/src/audit/checks/tracker-bloat.ts +0 -462
  93. package/src/audit/checks/tracking-verification.test.ts +0 -371
  94. package/src/audit/checks/tracking-verification.ts +0 -636
  95. package/src/audit/checks/url-safety.ts +0 -682
  96. package/src/audit/deno-entry.ts +0 -66
  97. package/src/audit/discovery/index.ts +0 -15
  98. package/src/audit/discovery/link-crawler.ts +0 -233
  99. package/src/audit/discovery/repo-routes.ts +0 -347
  100. package/src/audit/engine.ts +0 -627
  101. package/src/audit/fixes/index.ts +0 -209
  102. package/src/audit/fixes/social-meta-fixes.test.ts +0 -329
  103. package/src/audit/fixes/social-meta-fixes.ts +0 -463
  104. package/src/audit/index.ts +0 -74
  105. package/src/audit/runner.test.ts +0 -299
  106. package/src/audit/runner.ts +0 -130
  107. package/src/audit/types.ts +0 -1963
  108. package/src/content/featured-snippet.ts +0 -367
  109. package/src/content/generator.test.ts +0 -534
  110. package/src/content/generator.ts +0 -501
  111. package/src/content/headline.ts +0 -317
  112. package/src/content/index.ts +0 -62
  113. package/src/content/intent.ts +0 -258
  114. package/src/content/keyword-density.ts +0 -349
  115. package/src/content/readability.ts +0 -262
  116. package/src/executor.ts +0 -336
  117. package/src/fixer/framework-fixes.test.ts +0 -489
  118. package/src/fixer/framework-fixes.ts +0 -5287
  119. package/src/fixer/index.ts +0 -6
  120. package/src/fixer/schemas.ts +0 -971
  121. package/src/fixer.ts +0 -642
  122. package/src/frameworks/detector.test.ts +0 -248
  123. package/src/frameworks/detector.ts +0 -899
  124. package/src/frameworks/index.ts +0 -68
  125. package/src/frameworks/recipes/angular.yaml +0 -171
  126. package/src/frameworks/recipes/astro.yaml +0 -206
  127. package/src/frameworks/recipes/django.yaml +0 -180
  128. package/src/frameworks/recipes/laravel.yaml +0 -137
  129. package/src/frameworks/recipes/nextjs.yaml +0 -268
  130. package/src/frameworks/recipes/nuxt.yaml +0 -175
  131. package/src/frameworks/recipes/rails.yaml +0 -188
  132. package/src/frameworks/recipes/react.yaml +0 -202
  133. package/src/frameworks/recipes/sveltekit.yaml +0 -154
  134. package/src/frameworks/recipes/vue.yaml +0 -137
  135. package/src/frameworks/recipes/wordpress.yaml +0 -209
  136. package/src/frameworks/suggestion-engine.ts +0 -357
  137. package/src/geo/geo-content.test.ts +0 -305
  138. package/src/geo/geo-content.ts +0 -266
  139. package/src/geo/geo-history.test.ts +0 -473
  140. package/src/geo/geo-history.ts +0 -433
  141. package/src/geo/geo-tracker.test.ts +0 -359
  142. package/src/geo/geo-tracker.ts +0 -411
  143. package/src/geo/index.ts +0 -11
  144. package/src/geo/llm-citation-checker.ts +0 -188
  145. package/src/git/commit-helper.test.ts +0 -261
  146. package/src/git/commit-helper.ts +0 -329
  147. package/src/git/index.ts +0 -12
  148. package/src/git/pr-helper.test.ts +0 -284
  149. package/src/git/pr-helper.ts +0 -307
  150. package/src/index.ts +0 -76
  151. package/src/keywords/ai-keyword-engine.ts +0 -1062
  152. package/src/keywords/ai-summarizer.ts +0 -387
  153. package/src/keywords/ci-mode.ts +0 -555
  154. package/src/keywords/engine.ts +0 -359
  155. package/src/keywords/index.ts +0 -151
  156. package/src/keywords/llm-judge.ts +0 -357
  157. package/src/keywords/nlp-analysis.ts +0 -706
  158. package/src/keywords/prioritizer.ts +0 -295
  159. package/src/keywords/site-crawler.ts +0 -342
  160. package/src/keywords/sources/autocomplete.ts +0 -139
  161. package/src/keywords/sources/competitive-search.ts +0 -450
  162. package/src/keywords/sources/competitor-analysis.ts +0 -374
  163. package/src/keywords/sources/dataforseo.ts +0 -206
  164. package/src/keywords/sources/free-sources.ts +0 -294
  165. package/src/keywords/sources/gsc.ts +0 -123
  166. package/src/keywords/topic-grouping.ts +0 -327
  167. package/src/keywords/types.ts +0 -144
  168. package/src/keywords/wizard.ts +0 -457
  169. package/src/loader.ts +0 -40
  170. package/src/ranking/index.ts +0 -5
  171. package/src/ranking/serp-client.ts +0 -348
  172. package/src/ranking/tracker.ts +0 -380
  173. package/src/ranking/types.ts +0 -123
  174. package/src/reports/index.ts +0 -7
  175. package/src/reports/report-generator.test.ts +0 -293
  176. package/src/reports/report-generator.ts +0 -713
  177. package/src/scheduler/alerts.test.ts +0 -458
  178. package/src/scheduler/alerts.ts +0 -328
  179. package/src/scheduler/index.ts +0 -8
  180. package/src/scheduler/scheduled-audit.test.ts +0 -377
  181. package/src/scheduler/scheduled-audit.ts +0 -149
  182. package/src/test/integration-test.ts +0 -325
  183. package/src/tools/analyzer.ts +0 -373
  184. package/src/tools/crawl.ts +0 -293
  185. package/src/tools/files.ts +0 -301
  186. package/src/tools/h1-fixer.ts +0 -249
  187. package/src/tools/index.ts +0 -67
  188. package/src/tracking/github-action.ts +0 -326
  189. package/src/tracking/google-analytics.ts +0 -265
  190. package/src/tracking/index.ts +0 -45
  191. package/src/tracking/report-generator.ts +0 -386
  192. package/src/tracking/search-console.ts +0 -335
  193. package/src/types.ts +0 -148
  194. package/src/utils/http.ts +0 -302
  195. package/src/wasm-adapter.ts +0 -297
  196. package/src/wasm-entry.ts +0 -14
  197. package/tsconfig.json +0 -17
  198. package/tsup.wasm.config.ts +0 -26
  199. package/vitest.config.ts +0 -15
package/src/analyzers/core-web-vitals-analyzer.ts DELETED
@@ -1,557 +0,0 @@
1
- /**
2
- * Core Web Vitals Analyzer
3
- *
4
- * Estimates Core Web Vitals from HTML analysis without actual page load.
5
- * Identifies common issues that impact LCP, FID, CLS, INP, and TTFB.
6
- */
7
-
8
- import * as cheerio from 'cheerio';
9
- import type { AuditIssue } from '../audit/types.js';
10
-
11
- export interface CoreWebVitalsEstimate {
12
- lcp: {
13
- estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
14
- issues: string[];
15
- recommendations: string[];
16
- };
17
- fid: {
18
- estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
19
- issues: string[];
20
- recommendations: string[];
21
- };
22
- cls: {
23
- estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
24
- issues: string[];
25
- recommendations: string[];
26
- };
27
- inp: {
28
- estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
29
- issues: string[];
30
- recommendations: string[];
31
- };
32
- ttfb: {
33
- estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
34
- issues: string[];
35
- recommendations: string[];
36
- };
37
- overallScore: number;
38
- issues: AuditIssue[];
39
- }
40
-
41
- /**
42
- * Analyze HTML for LCP (Largest Contentful Paint) issues
43
- */
44
- function analyzeLCP(html: string, $: cheerio.CheerioAPI): {
45
- estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
46
- issues: string[];
47
- recommendations: string[];
48
- } {
49
- const issues: string[] = [];
50
- const recommendations: string[] = [];
51
- let score = 100;
52
-
53
- // Check for hero images without optimization
54
- const heroImages = $('img').filter((_, el) => {
55
- const parent = $(el).parent();
56
- const isHero = parent.is('header, .hero, [class*="hero"], [class*="banner"], section:first-of-type');
57
- const isLarge = (parseInt($(el).attr('width') || '0') > 400) ||
58
- ($(el).attr('class')?.includes('full') ?? false);
59
- return isHero || isLarge;
60
- });
61
-
62
- heroImages.each((_, img) => {
63
- const $img = $(img);
64
- const src = $img.attr('src') || '';
65
-
66
- // Check loading attribute
67
- if ($img.attr('loading') === 'lazy') {
68
- issues.push('Hero/LCP image has loading="lazy" - delays rendering');
69
- score -= 20;
70
- }
71
-
72
- // Check for preload
73
- const preloads = $('link[rel="preload"][as="image"]');
74
- const isPreloaded = preloads.toArray().some(p =>
75
- $(p).attr('href')?.includes(src.split('/').pop() || '')
76
- );
77
- if (!isPreloaded && src) {
78
- issues.push('Hero image not preloaded');
79
- recommendations.push(`Add: <link rel="preload" as="image" href="${src}">`);
80
- score -= 15;
81
- }
82
-
83
- // Check for width/height attributes (prevents layout shift)
84
- if (!$img.attr('width') || !$img.attr('height')) {
85
- issues.push('Hero image missing width/height attributes');
86
- score -= 10;
87
- }
88
-
89
- // Check for modern formats
90
- const format = src.split('.').pop()?.toLowerCase();
91
- if (format && !['webp', 'avif'].includes(format)) {
92
- recommendations.push('Consider using WebP or AVIF format for hero image');
93
- score -= 5;
94
- }
95
- });
96
-
97
- // Check for render-blocking resources
98
- const blockingCSS = $('link[rel="stylesheet"]').filter((_, el) => {
99
- const media = $(el).attr('media');
100
- return !media || media === 'all' || media === 'screen';
101
- });
102
-
103
- if (blockingCSS.length > 3) {
104
- issues.push(`${blockingCSS.length} render-blocking stylesheets`);
105
- recommendations.push('Inline critical CSS and defer non-critical stylesheets');
106
- score -= 15;
107
- }
108
-
109
- // Check for blocking scripts in head
110
- const blockingScripts = $('head script:not([async]):not([defer]):not([type="module"])').filter((_, el) => {
111
- return $(el).attr('src') !== undefined;
112
- });
113
-
114
- if (blockingScripts.length > 0) {
115
- issues.push(`${blockingScripts.length} render-blocking scripts in <head>`);
116
- recommendations.push('Add async or defer attribute to scripts');
117
- score -= 20;
118
- }
119
-
120
- // Check for web fonts
121
- const fontLinks = $('link[rel="preload"][as="font"], link[href*="fonts.googleapis.com"], link[href*="fonts.gstatic.com"]');
122
- const fontPreconnects = $('link[rel="preconnect"][href*="fonts"]');
123
-
124
- if (fontLinks.length > 0 && fontPreconnects.length === 0) {
125
- issues.push('Web fonts without preconnect');
126
- recommendations.push('Add <link rel="preconnect" href="https://fonts.googleapis.com">');
127
- score -= 10;
128
- }
129
-
130
- // Check for large inline styles
131
- const inlineStyles = $('style').text();
132
- if (inlineStyles.length > 50000) {
133
- issues.push('Very large inline CSS (>50KB)');
134
- score -= 10;
135
- }
136
-
137
- let estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown' = 'unknown';
138
- if (score >= 80) estimate = 'good';
139
- else if (score >= 50) estimate = 'needs-improvement';
140
- else estimate = 'poor';
141
-
142
- return { estimate, issues, recommendations };
143
- }
144
-
145
- /**
146
- * Analyze HTML for FID (First Input Delay) / INP issues
147
- */
148
- function analyzeFID_INP(html: string, $: cheerio.CheerioAPI): {
149
- fidEstimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
150
- inpEstimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
151
- issues: string[];
152
- recommendations: string[];
153
- } {
154
- const issues: string[] = [];
155
- const recommendations: string[] = [];
156
- let score = 100;
157
-
158
- // Count total JavaScript size (approximate from script tags)
159
- let totalJSIndicators = 0;
160
-
161
- // Check for large JS bundles
162
- $('script[src]').each((_, el) => {
163
- const src = $(el).attr('src') || '';
164
- if (src.includes('bundle') || src.includes('vendor') || src.includes('chunk')) {
165
- totalJSIndicators++;
166
- }
167
- });
168
-
169
- if (totalJSIndicators > 5) {
170
- issues.push('Many JavaScript bundle files detected');
171
- recommendations.push('Consider code splitting and lazy loading');
172
- score -= 15;
173
- }
174
-
175
- // Check for heavy frameworks
176
- const hasHeavyFramework = html.includes('angular') ||
177
- html.includes('__NUXT__') ||
178
- (html.includes('react') && !html.includes('preact'));
179
-
180
- // Check for inline scripts (potential long tasks)
181
- const inlineScriptContent = $('script:not([src])').text();
182
- if (inlineScriptContent.length > 10000) {
183
- issues.push('Large inline JavaScript (>10KB)');
184
- recommendations.push('Move large scripts to external files with async/defer');
185
- score -= 15;
186
- }
187
-
188
- // Check for event handlers in HTML
189
- const inlineHandlers = $('[onclick], [onchange], [onsubmit], [onload], [onerror]');
190
- if (inlineHandlers.length > 10) {
191
- issues.push(`${inlineHandlers.length} inline event handlers`);
192
- recommendations.push('Use addEventListener instead of inline handlers');
193
- score -= 10;
194
- }
195
-
196
- // Check for third-party scripts
197
- const thirdPartyScripts = $('script[src]').filter((_, el) => {
198
- const src = $(el).attr('src') || '';
199
- return src.includes('//') && !src.includes('localhost');
200
- });
201
-
202
- const heavyThirdParties = ['analytics', 'facebook', 'twitter', 'linkedin', 'hotjar', 'intercom', 'drift', 'hubspot'];
203
- let heavyScriptCount = 0;
204
-
205
- thirdPartyScripts.each((_, el) => {
206
- const src = $(el).attr('src') || '';
207
- if (heavyThirdParties.some(tp => src.toLowerCase().includes(tp))) {
208
- heavyScriptCount++;
209
- }
210
- });
211
-
212
- if (heavyScriptCount > 3) {
213
- issues.push(`${heavyScriptCount} heavy third-party scripts`);
214
- recommendations.push('Lazy load third-party scripts after page interaction');
215
- score -= 20;
216
- }
217
-
218
- // Check for synchronous XHR patterns
219
- if (html.includes('XMLHttpRequest') && !html.includes('async')) {
220
- issues.push('Potential synchronous XHR detected');
221
- score -= 10;
222
- }
223
-
224
- let estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown' = 'unknown';
225
- if (score >= 80) estimate = 'good';
226
- else if (score >= 50) estimate = 'needs-improvement';
227
- else estimate = 'poor';
228
-
229
- return {
230
- fidEstimate: estimate,
231
- inpEstimate: estimate, // Similar factors affect both
232
- issues,
233
- recommendations
234
- };
235
- }
236
-
237
- /**
238
- * Analyze HTML for CLS (Cumulative Layout Shift) issues
239
- */
240
- function analyzeCLS(html: string, $: cheerio.CheerioAPI): {
241
- estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
242
- issues: string[];
243
- recommendations: string[];
244
- } {
245
- const issues: string[] = [];
246
- const recommendations: string[] = [];
247
- let score = 100;
248
-
249
- // Check images without dimensions
250
- const imagesWithoutDimensions = $('img').filter((_, el) => {
251
- const width = $(el).attr('width');
252
- const height = $(el).attr('height');
253
- const style = $(el).attr('style') || '';
254
- const hasStyleDimensions = style.includes('width') && style.includes('height');
255
- return !width || !height || (!hasStyleDimensions && width === 'auto');
256
- });
257
-
258
- if (imagesWithoutDimensions.length > 0) {
259
- issues.push(`${imagesWithoutDimensions.length} images without width/height`);
260
- recommendations.push('Add explicit width and height attributes to all images');
261
- score -= Math.min(imagesWithoutDimensions.length * 5, 25);
262
- }
263
-
264
- // Check videos/iframes without dimensions
265
- const mediaWithoutDimensions = $('video, iframe').filter((_, el) => {
266
- const width = $(el).attr('width');
267
- const height = $(el).attr('height');
268
- return !width || !height;
269
- });
270
-
271
- if (mediaWithoutDimensions.length > 0) {
272
- issues.push(`${mediaWithoutDimensions.length} videos/iframes without dimensions`);
273
- recommendations.push('Add explicit width and height to all video and iframe elements');
274
- score -= Math.min(mediaWithoutDimensions.length * 10, 20);
275
- }
276
-
277
- // Check for ads (common CLS culprit)
278
- const adContainers = $('[class*="ad-"], [class*="ads-"], [id*="ad-"], [data-ad], ins.adsbygoogle');
279
- if (adContainers.length > 0) {
280
- const hasReservedSpace = adContainers.filter((_, el) => {
281
- const style = $(el).attr('style') || '';
282
- return style.includes('min-height') || style.includes('height');
283
- });
284
-
285
- if (hasReservedSpace.length < adContainers.length) {
286
- issues.push('Ad containers without reserved space');
287
- recommendations.push('Reserve space for ads with min-height CSS');
288
- score -= 20;
289
- }
290
- }
291
-
292
- // Check for dynamic content insertion points
293
- const dynamicContainers = $('[data-loading], [class*="skeleton"], [class*="placeholder"]');
294
- if (dynamicContainers.length > 0) {
295
- // This is actually good - they're using skeletons
296
- score += 5;
297
- }
298
-
299
- // Check for web fonts with potential FOUT
300
- const webFonts = $('link[href*="fonts"], style').filter((_, el) => {
301
- const content = $(el).attr('href') || $(el).text();
302
- return content.includes('font-face') || content.includes('fonts.googleapis');
303
- });
304
-
305
- if (webFonts.length > 0) {
306
- const hasFontDisplay = html.includes('font-display');
307
- if (!hasFontDisplay) {
308
- issues.push('Web fonts without font-display property');
309
- recommendations.push('Add font-display: swap or optional to prevent FOUT');
310
- score -= 10;
311
- }
312
- }
313
-
314
- // Check for fixed headers/footers that might cause shifts
315
- const stickyElements = $('[class*="sticky"], [class*="fixed"], [style*="position: fixed"], [style*="position: sticky"]');
316
- // This is informational - sticky headers are common and acceptable
317
-
318
- // Check for aspect ratio containers
319
- const aspectRatioContainers = $('[style*="aspect-ratio"], [class*="aspect-"]');
320
- if (aspectRatioContainers.length > 0) {
321
- score += 5; // Good practice
322
- }
323
-
324
- let estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown' = 'unknown';
325
- if (score >= 80) estimate = 'good';
326
- else if (score >= 50) estimate = 'needs-improvement';
327
- else estimate = 'poor';
328
-
329
- return { estimate, issues, recommendations };
330
- }
331
-
332
- /**
333
- * Analyze for TTFB (Time to First Byte) indicators
334
- */
335
- function analyzeTTFB($: cheerio.CheerioAPI, headers?: Record<string, string>): {
336
- estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown';
337
- issues: string[];
338
- recommendations: string[];
339
- } {
340
- const issues: string[] = [];
341
- const recommendations: string[] = [];
342
- let score = 100;
343
-
344
- // Check for caching headers (if provided)
345
- if (headers) {
346
- const cacheControl = headers['cache-control'];
347
- if (!cacheControl) {
348
- issues.push('No Cache-Control header');
349
- recommendations.push('Add Cache-Control header for static assets');
350
- score -= 10;
351
- }
352
-
353
- const hasCompression = headers['content-encoding']?.includes('gzip') ||
354
- headers['content-encoding']?.includes('br');
355
- if (!hasCompression) {
356
- issues.push('Response not compressed (no gzip/brotli)');
357
- recommendations.push('Enable Brotli or Gzip compression');
358
- score -= 15;
359
- }
360
- }
361
-
362
- // Check for hints that suggest server-side processing
363
- const hasDynamicIndicators = $('[data-server-rendered], [data-user-id], [data-session]').length > 0;
364
- if (hasDynamicIndicators) {
365
- recommendations.push('Consider edge caching or CDN for dynamic pages');
366
- }
367
-
368
- // Check for preconnect/dns-prefetch hints
369
- const preconnects = $('link[rel="preconnect"], link[rel="dns-prefetch"]');
370
- if (preconnects.length === 0) {
371
- issues.push('No preconnect hints for external origins');
372
- recommendations.push('Add preconnect for critical external origins (fonts, CDN, API)');
373
- score -= 10;
374
- }
375
-
376
- // Check for early hints / resource hints
377
- const resourceHints = $('link[rel="preload"], link[rel="prefetch"], link[rel="modulepreload"]');
378
- if (resourceHints.length === 0) {
379
- recommendations.push('Consider adding preload hints for critical resources');
380
- score -= 5;
381
- }
382
-
383
- let estimate: 'good' | 'needs-improvement' | 'poor' | 'unknown' = 'unknown';
384
- if (score >= 80) estimate = 'good';
385
- else if (score >= 50) estimate = 'needs-improvement';
386
- else estimate = 'poor';
387
-
388
- return { estimate, issues, recommendations };
389
- }
390
-
391
- /**
392
- * Generate audit issues from Core Web Vitals analysis
393
- */
394
- function generateCWVIssues(
395
- lcp: ReturnType<typeof analyzeLCP>,
396
- fidInp: ReturnType<typeof analyzeFID_INP>,
397
- cls: ReturnType<typeof analyzeCLS>,
398
- ttfb: ReturnType<typeof analyzeTTFB>,
399
- url: string
400
- ): AuditIssue[] {
401
- const issues: AuditIssue[] = [];
402
-
403
- // LCP Issues
404
- if (lcp.estimate === 'poor') {
405
- issues.push({
406
- code: 'CWV_LCP_POOR',
407
- severity: 'critical',
408
- category: 'performance',
409
- title: 'Largest Contentful Paint likely poor',
410
- description: `LCP issues detected: ${lcp.issues.join('; ')}`,
411
- impact: 'Poor LCP hurts rankings and user experience. Google uses LCP as a ranking factor.',
412
- howToFix: lcp.recommendations.join('\n'),
413
- affectedUrls: [url],
414
- });
415
- } else if (lcp.estimate === 'needs-improvement' && lcp.issues.length > 0) {
416
- issues.push({
417
- code: 'CWV_LCP_NEEDS_IMPROVEMENT',
418
- severity: 'warning',
419
- category: 'performance',
420
- title: 'Largest Contentful Paint needs improvement',
421
- description: `LCP issues: ${lcp.issues.join('; ')}`,
422
- impact: 'LCP affects Core Web Vitals score and rankings',
423
- howToFix: lcp.recommendations.join('\n'),
424
- affectedUrls: [url],
425
- });
426
- }
427
-
428
- // FID/INP Issues
429
- if (fidInp.fidEstimate === 'poor') {
430
- issues.push({
431
- code: 'CWV_INP_POOR',
432
- severity: 'critical',
433
- category: 'performance',
434
- title: 'Interaction to Next Paint likely poor',
435
- description: `INP/FID issues detected: ${fidInp.issues.join('; ')}`,
436
- impact: 'Poor interactivity hurts user experience and rankings',
437
- howToFix: fidInp.recommendations.join('\n'),
438
- affectedUrls: [url],
439
- });
440
- } else if (fidInp.fidEstimate === 'needs-improvement' && fidInp.issues.length > 0) {
441
- issues.push({
442
- code: 'CWV_INP_NEEDS_IMPROVEMENT',
443
- severity: 'warning',
444
- category: 'performance',
445
- title: 'Interaction responsiveness needs improvement',
446
- description: `INP issues: ${fidInp.issues.join('; ')}`,
447
- impact: 'Affects user experience and Core Web Vitals',
448
- howToFix: fidInp.recommendations.join('\n'),
449
- affectedUrls: [url],
450
- });
451
- }
452
-
453
- // CLS Issues
454
- if (cls.estimate === 'poor') {
455
- issues.push({
456
- code: 'CWV_CLS_POOR',
457
- severity: 'critical',
458
- category: 'performance',
459
- title: 'Cumulative Layout Shift likely poor',
460
- description: `CLS issues detected: ${cls.issues.join('; ')}`,
461
- impact: 'Visual instability frustrates users and hurts rankings',
462
- howToFix: cls.recommendations.join('\n'),
463
- affectedUrls: [url],
464
- });
465
- } else if (cls.estimate === 'needs-improvement' && cls.issues.length > 0) {
466
- issues.push({
467
- code: 'CWV_CLS_NEEDS_IMPROVEMENT',
468
- severity: 'warning',
469
- category: 'performance',
470
- title: 'Layout stability needs improvement',
471
- description: `CLS issues: ${cls.issues.join('; ')}`,
472
- impact: 'Layout shifts degrade user experience',
473
- howToFix: cls.recommendations.join('\n'),
474
- affectedUrls: [url],
475
- });
476
- }
477
-
478
- // TTFB Issues
479
- if (ttfb.issues.length > 0) {
480
- issues.push({
481
- code: 'CWV_TTFB_ISSUES',
482
- severity: 'info',
483
- category: 'performance',
484
- title: 'Server response optimizations available',
485
- description: `TTFB issues: ${ttfb.issues.join('; ')}`,
486
- impact: 'Slow server response delays all other metrics',
487
- howToFix: ttfb.recommendations.join('\n'),
488
- affectedUrls: [url],
489
- });
490
- }
491
-
492
- return issues;
493
- }
494
-
495
- /**
496
- * Main Core Web Vitals analysis function
497
- */
498
- export function analyzeCoreWebVitals(
499
- html: string,
500
- url: string,
501
- headers?: Record<string, string>
502
- ): CoreWebVitalsEstimate {
503
- const $ = cheerio.load(html);
504
-
505
- const lcp = analyzeLCP(html, $);
506
- const fidInp = analyzeFID_INP(html, $);
507
- const cls = analyzeCLS(html, $);
508
- const ttfb = analyzeTTFB($, headers);
509
-
510
- const issues = generateCWVIssues(lcp, fidInp, cls, ttfb, url);
511
-
512
- // Calculate overall score
513
- const scores = {
514
- lcp: lcp.estimate === 'good' ? 100 : lcp.estimate === 'needs-improvement' ? 60 : 30,
515
- fid: fidInp.fidEstimate === 'good' ? 100 : fidInp.fidEstimate === 'needs-improvement' ? 60 : 30,
516
- cls: cls.estimate === 'good' ? 100 : cls.estimate === 'needs-improvement' ? 60 : 30,
517
- ttfb: ttfb.estimate === 'good' ? 100 : ttfb.estimate === 'needs-improvement' ? 60 : 30,
518
- };
519
-
520
- // Weighted average (LCP and CLS are most impactful)
521
- const overallScore = Math.round(
522
- (scores.lcp * 0.30) +
523
- (scores.fid * 0.20) +
524
- (scores.cls * 0.30) +
525
- (scores.ttfb * 0.20)
526
- );
527
-
528
- return {
529
- lcp: {
530
- estimate: lcp.estimate,
531
- issues: lcp.issues,
532
- recommendations: lcp.recommendations,
533
- },
534
- fid: {
535
- estimate: fidInp.fidEstimate,
536
- issues: fidInp.issues,
537
- recommendations: fidInp.recommendations,
538
- },
539
- cls: {
540
- estimate: cls.estimate,
541
- issues: cls.issues,
542
- recommendations: cls.recommendations,
543
- },
544
- inp: {
545
- estimate: fidInp.inpEstimate,
546
- issues: fidInp.issues,
547
- recommendations: fidInp.recommendations,
548
- },
549
- ttfb: {
550
- estimate: ttfb.estimate,
551
- issues: ttfb.issues,
552
- recommendations: ttfb.recommendations,
553
- },
554
- overallScore,
555
- issues,
556
- };
557
- }