seo-gravity-mcp 1.3.2 → 1.3.4

package/dist/utils/crawlGraph.js

@@ -1,4 +1,5 @@
 import { fetchAndParsePage } from './scraper.js';
+import { normalizeUrl } from './urlNormalizer.js';
 export class CrawlGraphBuilder {
     startUrl;
     options;
@@ -13,22 +14,27 @@ export class CrawlGraphBuilder {
         const maxDepth = this.options.maxDepth ?? 3;
         const maxPages = this.options.maxPages ?? 50;
         const queue = [{ url: this.startUrl, depth: 0 }];
-        let origin = '';
+        let origin = this.options.baseOrigin || '';
         try {
             if (this.startUrl.startsWith('http')) {
                 origin = new URL(this.startUrl).origin;
             }
         }
         catch {
-            origin = this.options.baseOrigin || '';
+            // Keep explicitly supplied baseOrigin, otherwise operate on relative paths.
         }
-        // Initialize start node
         this.ensureNode(this.startUrl, 0);
-        // Seed with known route paths if provided
+        // Known routes are deliberately seeded as crawl candidates. Their depth is unknown
+        // until an actual internal link is observed, but we still crawl them so they can be
+        // evaluated rather than being mistaken for observed orphan nodes.
         if (this.options.knownRoutePaths && origin) {
             for (const route of this.options.knownRoutePaths) {
                 const fullUrl = `${origin}${route.startsWith('/') ? route : '/' + route}`;
-                this.ensureNode(fullUrl, -1);
+                const norm = normalizeUrl(fullUrl);
+                if (norm !== normalizeUrl(this.startUrl) && !this.visited.has(norm)) {
+                    this.ensureNode(norm, -1);
+                    queue.push({ url: norm, depth: 1 });
+                }
             }
         }
         while (queue.length > 0 && this.visited.size < maxPages) {
@@ -38,27 +44,34 @@ export class CrawlGraphBuilder {
                 continue;
             this.visited.add(normUrl);
             const node = this.ensureNode(normUrl, current.depth);
-            // Don't crawl beyond maxDepth
+            if (node.clickDepth === -1 || current.depth < node.clickDepth) {
+                node.clickDepth = current.depth;
+            }
             if (current.depth >= maxDepth)
                 continue;
             try {
                 const parsed = await fetchAndParsePage(normUrl, origin);
                 node.title = parsed.title;
                 node.statusCode = parsed.statusCode;
-                const internalLinks = parsed.links.internal;
                 const pageDomain = origin || (normUrl.startsWith('http') ? new URL(normUrl).origin : '');
-                for (const rawTarget of internalLinks) {
-                    const targetUrl = resolveInternalUrl(rawTarget, pageDomain, normUrl);
+                const internalDetails = parsed.links.internalDetails || parsed.links.internal.map(href => ({
+                    href,
+                    anchorText: href,
+                    rel: []
+                }));
+                for (const detail of internalDetails) {
+                    const targetUrl = resolveInternalUrl(detail.href, pageDomain, normUrl);
                     if (!targetUrl)
                         continue;
                     const normTarget = normalizeUrl(targetUrl);
-                    const isGeneric = isGenericAnchorText(rawTarget);
+                    const anchorText = detail.anchorText.trim();
+                    const rel = detail.rel.map(value => value.toLowerCase());
                     this.edges.push({
                         sourceUrl: normUrl,
                         targetUrl: normTarget,
-                        anchorText: rawTarget,
-                        isNofollow: false,
-                        isGenericAnchor: isGeneric
+                        anchorText,
+                        isNofollow: rel.includes('nofollow'),
+                        isGenericAnchor: isGenericAnchorText(anchorText)
                     });
                     const targetNode = this.ensureNode(normTarget, current.depth + 1);
                     if (targetNode.clickDepth === -1 || targetNode.clickDepth > current.depth + 1) {
@@ -73,7 +86,6 @@ export class CrawlGraphBuilder {
                 node.statusCode = 500;
             }
         }
-        // Calculate In-degree and Out-degree
         for (const edge of this.edges) {
             const src = this.nodesMap.get(edge.sourceUrl);
             const tgt = this.nodesMap.get(edge.targetUrl);
@@ -82,24 +94,21 @@ export class CrawlGraphBuilder {
             if (tgt)
                 tgt.incomingLinksCount++;
         }
-        // Compute PageRank Heuristic
         this.computePageRank();
-        // Identify Orphans, Hubs, and Dead-Ends
         const orphanPages = [];
         const hubPages = [];
         const deadEnds = [];
         for (const [url, node] of this.nodesMap.entries()) {
-            // Orphan: page in graph with 0 incoming internal links (excluding the root starting URL)
-            if (node.incomingLinksCount === 0 && url !== normalizeUrl(this.startUrl)) {
+            // Only evaluated/visited nodes can be classified. Unobserved known routes are not
+            // treated as orphans until they have been crawled.
+            if (this.visited.has(url) && node.incomingLinksCount === 0 && url !== normalizeUrl(this.startUrl)) {
                 node.isOrphan = true;
                 orphanPages.push(url);
             }
-            // Hub: 5 or more outgoing links
             if (node.outgoingLinksCount >= 5) {
                 node.isHubPage = true;
                 hubPages.push(url);
             }
-            // Dead end: visited page with 0 outgoing links
             if (this.visited.has(url) && node.outgoingLinksCount === 0) {
                 node.isDeadEnd = true;
                 deadEnds.push(url);
@@ -145,15 +154,13 @@ export class CrawlGraphBuilder {
         let pr = {};
         for (const u of nodes)
             pr[u] = 1 / N;
-        // Build incoming edge map
         const incomingMap = new Map();
         for (const u of nodes)
             incomingMap.set(u, []);
         for (const edge of this.edges) {
             const arr = incomingMap.get(edge.targetUrl);
-            if (arr && !arr.includes(edge.sourceUrl)) {
+            if (arr && !arr.includes(edge.sourceUrl))
                 arr.push(edge.sourceUrl);
-            }
         }
         for (let iter = 0; iter < iterations; iter++) {
             const nextPr = {};
@@ -169,13 +176,11 @@ export class CrawlGraphBuilder {
             }
             pr = nextPr;
         }
-        // Normalize PageRank scores to 0.0 - 1.0
         const maxPr = Math.max(...Object.values(pr), 0.0001);
         for (const u of nodes) {
             const node = this.nodesMap.get(u);
-            if (node) {
+            if (node)
                 node.pageRankScore = Math.round(((pr[u] || 0) / maxPr) * 100) / 100;
-            }
         }
     }
     findSimpleCycles() {
@@ -191,38 +196,23 @@ export class CrawlGraphBuilder {
         return cycles.slice(0, 5);
     }
 }
-function normalizeUrl(url) {
-    try {
-        if (url.startsWith('http')) {
-            const u = new URL(url);
-            return `${u.origin}${u.pathname.replace(/\/$/, '') || '/'}`;
-        }
-    }
-    catch {
-        // Ignored
-    }
-    return url.replace(/\/$/, '') || '/';
-}
 function resolveInternalUrl(href, origin, currentUrl) {
     if (!href || href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:') || href.startsWith('javascript:')) {
         return null;
     }
-    if (href.startsWith('http://') || href.startsWith('https://')) {
-        if (origin && href.startsWith(origin))
-            return href;
-        return null;
-    }
-    if (href.startsWith('/')) {
-        return origin ? `${origin}${href}` : href;
-    }
-    // Relative path
     try {
-        const base = currentUrl.startsWith('http') ? currentUrl : `http://localhost${currentUrl}`;
-        const resolved = new URL(href, base).pathname;
-        return origin ? `${origin}${resolved}` : resolved;
+        const base = currentUrl.startsWith('http')
+            ? currentUrl
+            : origin
+                ? `${origin}${currentUrl.startsWith('/') ? currentUrl : '/' + currentUrl}`
+                : `http://localhost${currentUrl.startsWith('/') ? currentUrl : '/' + currentUrl}`;
+        const resolved = new URL(href, base);
+        if (origin && resolved.origin !== origin)
+            return null;
+        return resolved.toString();
     }
     catch {
-        return href;
+        return null;
     }
 }
 function isGenericAnchorText(text) {

package/dist/utils/gitDiffEngine.js

@@ -17,7 +17,11 @@ export function getChangedFilesSince(projectDir, baseRef = 'HEAD~1') {
         });
         return output.split('\n').map(l => l.trim().replace(/\\/g, '/')).filter(Boolean);
     }
-    catch {
+    catch (err) {
+        // A failed requested diff is not equivalent to a dirty-worktree query. Fall back
+        // only for the conventional local-development baseline and make that behavior explicit.
+        if (baseRef !== 'HEAD~1')
+            throw new Error(`Unable to compute Git diff from '${baseRef}'.`);
         try {
             const status = execFileSync('git', ['status', '--porcelain'], {
                 cwd: projectDir,
@@ -30,24 +34,43 @@ export function getChangedFilesSince(projectDir, baseRef = 'HEAD~1') {
                 .filter(Boolean);
         }
         catch {
-            return [];
+            throw new Error(`Unable to determine Git changes in '${projectDir}'.`);
         }
     }
 }
 export function analyzeSemanticFileChange(filePath, projectDir) {
-    const fullPath = path.join(projectDir, filePath);
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    const fullPath = path.resolve(projectDir, normalizedPath);
+    const projectRoot = path.resolve(projectDir);
+    if (fullPath !== projectRoot && !fullPath.startsWith(projectRoot + path.sep)) {
+        throw new Error(`Changed file '${filePath}' resolves outside the project root.`);
+    }
     if (!fs.existsSync(fullPath)) {
+        // Deleted files need a conservative classification. We can reliably identify
+        // route/config categories from the path, but should not claim every invariant is affected.
+        const base = path.basename(normalizedPath).toLowerCase();
+        if (base.includes('sitemap') || base.includes('robots') || base.includes('llms')) {
+            return {
+                affectsMetadata: false,
+                affectsCanonical: false,
+                affectsSchema: false,
+                affectsLinks: false,
+                affectsRobotsOrSitemap: true,
+                likelyAffectedInvariants: ['INV-ROBOTS-ALLOWED', 'INV-SITEMAP-PRESENT', 'INV-LLMS-TXT'],
+                riskLevel: 'MEDIUM'
+            };
+        }
         return {
-            affectsMetadata: true,
-            affectsCanonical: true,
-            affectsSchema: true,
-            affectsLinks: true,
-            affectsRobotsOrSitemap: true,
-            likelyAffectedInvariants: ['INV-HTTP-200', 'INV-CANONICAL-RESOLVES', 'INV-TITLE-PRESENT'],
-            riskLevel: 'HIGH'
+            affectsMetadata: false,
+            affectsCanonical: false,
+            affectsSchema: false,
+            affectsLinks: false,
+            affectsRobotsOrSitemap: false,
+            likelyAffectedInvariants: [],
+            riskLevel: 'LOW'
         };
     }
-    const base = path.basename(filePath).toLowerCase();
+    const base = path.basename(normalizedPath).toLowerCase();
     if (base.includes('sitemap') || base.includes('robots') || base.includes('llms')) {
         return {
             affectsMetadata: false,
@@ -65,13 +88,18 @@ export function analyzeSemanticFileChange(filePath, projectDir) {
     const affectsCanonical = ast.hasCanonicalDeclaration || /rel=["']canonical["']/i.test(content);
     const affectsSchema = ast.hasSchemaMarkup || /application\/ld\+json/.test(content);
     const affectsLinks = /<Link\b|<a\b|href=/i.test(content);
-    const affectedInvariants = ['INV-HTTP-200'];
+    const affectedInvariants = [];
     if (affectsMetadata)
         affectedInvariants.push('INV-TITLE-PRESENT');
     if (affectsCanonical)
         affectedInvariants.push('INV-CANONICAL-RESOLVES');
     if (affectsLinks)
         affectedInvariants.push('INV-LINK-ACCESSIBLE');
+    // A file can only affect HTTP status if it plausibly participates in routing/runtime
+    // behavior. Generic content/style files are not automatically treated as HTTP-risky.
+    if (affectsMetadata || affectsCanonical || affectsLinks || /route|page|server|middleware|controller/i.test(base)) {
+        affectedInvariants.unshift('INV-HTTP-200');
+    }
     const riskLevel = (affectsCanonical || affectsMetadata) ? 'HIGH' : affectsLinks ? 'MEDIUM' : 'LOW';
     return {
         affectsMetadata,
@@ -79,21 +107,26 @@ export function analyzeSemanticFileChange(filePath, projectDir) {
         affectsSchema,
         affectsLinks,
         affectsRobotsOrSitemap: false,
-        likelyAffectedInvariants: affectedInvariants,
+        likelyAffectedInvariants: [...new Set(affectedInvariants)],
         riskLevel
     };
 }
 export function mapChangedFilesToRoutes(changedFiles, routes) {
+    const normalizedChanged = changedFiles.map(f => f.replace(/\\/g, '/'));
     const affected = [];
     const unaffected = [];
-    const isGlobalFile = changedFiles.some(f => f.includes('layout.') ||
-        f.includes('sitemap.') ||
-        f.includes('robots.') ||
-        f.includes('package.json') ||
-        f.includes('next.config') ||
-        f.includes('astro.config'));
+    const isGlobalFile = normalizedChanged.some(f => {
+        const base = path.basename(f).toLowerCase();
+        return base.startsWith('layout.') ||
+            base.startsWith('sitemap.') ||
+            base.startsWith('robots.') ||
+            base === 'package.json' ||
+            base.startsWith('next.config') ||
+            base.startsWith('astro.config');
+    });
     for (const r of routes) {
-        if (isGlobalFile || changedFiles.some(f => r.sourceFilePath.includes(f) || f.includes(r.sourceFilePath))) {
+        const routeSource = r.sourceFilePath.replace(/\\/g, '/');
+        if (isGlobalFile || normalizedChanged.includes(routeSource)) {
             affected.push(r);
         }
         else {
@@ -113,16 +146,17 @@ export async function runDifferentialAudit(projectDir, baseRef = 'HEAD~1', baseU
     for (const file of changedFiles) {
         const sem = analyzeSemanticFileChange(file, resolved);
         semanticImpacts[file] = sem;
-        const matchingRoute = routes.find(r => r.sourceFilePath === file);
+        const normalizedFile = file.replace(/\\/g, '/');
+        const matchingRoute = routes.find(r => r.sourceFilePath.replace(/\\/g, '/') === normalizedFile);
         semanticDiffs.push({
-            changedFile: file,
+            changedFile: normalizedFile,
             affectedRoute: matchingRoute?.routePath,
             semanticCategory: sem,
-            impactDescription: `File change triggers risk [${sem.riskLevel}] on invariants: ${sem.likelyAffectedInvariants.join(', ')}`
+            impactDescription: `File change triggers risk [${sem.riskLevel}] on invariants: ${sem.likelyAffectedInvariants.join(', ') || 'none detected'}`
         });
     }
     const snapshot = await createProjectSnapshot(resolved, { baseUrl });
-    const targetedFindings = snapshot.findings.filter(f => affected.some(r => r.routePath === f.affectedUrl || f.sourceLocation?.filePath === r.sourceFilePath));
+    const targetedFindings = snapshot.findings.filter(f => affected.some(r => r.routePath === f.affectedUrl || f.sourceLocation?.filePath?.replace(/\\/g, '/') === r.sourceFilePath.replace(/\\/g, '/')));
     const hasCritical = targetedFindings.some(f => f.severity === 'critical' || f.severity === 'high');
     return {
         schemaVersion: 'seo.gravity/v1',

package/dist/utils/jsdomRenderer.d.ts

@@ -1,5 +1,6 @@
 import { JsRenderingDiffReport } from '../types/seo.js';
 /**
- * Compares initial server HTML with the rendered DOM (JavaScript SEO Hydration diffing).
+ * Compares initial server HTML with a normalized JSDOM parse.
+ * This is a static DOM comparison; it does not execute application JavaScript.
  */
 export declare function compareServerVsClientDom(url: string): Promise<JsRenderingDiffReport>;

package/dist/utils/jsdomRenderer.js

@@ -2,7 +2,8 @@ import { JSDOM, VirtualConsole } from 'jsdom';
 import axios from 'axios';
 import { getRandomUserAgent } from './scraper.js';
 /**
- * Compares initial server HTML with the rendered DOM (JavaScript SEO Hydration diffing).
+ * Compares initial server HTML with a normalized JSDOM parse.
+ * This is a static DOM comparison; it does not execute application JavaScript.
  */
 export async function compareServerVsClientDom(url) {
     let serverHtml = '';
@@ -20,11 +21,10 @@ export async function compareServerVsClientDom(url) {
     catch (err) {
         throw new Error(`Failed to fetch server HTML from ${url}: ${err.message}`);
     }
-    // Render in JSDOM with script execution enabled
     const virtualConsole = new VirtualConsole();
-    virtualConsole.on('error', () => { }); // silence js console errors
+    virtualConsole.on('error', () => { });
     virtualConsole.on('warn', () => { });
-    let hydratedDomHtml = serverHtml;
+    let normalizedDomHtml = serverHtml;
     try {
         const dom = new JSDOM(serverHtml, {
             url,
@@ -32,21 +32,20 @@ export async function compareServerVsClientDom(url) {
             resources: 'usable',
             virtualConsole
         });
-        hydratedDomHtml = dom.serialize();
+        normalizedDomHtml = dom.serialize();
     }
     catch {
-        hydratedDomHtml = serverHtml;
+        normalizedDomHtml = serverHtml;
     }
     const serverLength = serverHtml.length;
-    const clientLength = hydratedDomHtml.length;
+    const clientLength = normalizedDomHtml.length;
     const lengthDiff = Math.abs(clientLength - serverLength);
     const percentDiff = Number(((lengthDiff / Math.max(serverLength, 1)) * 100).toFixed(1));
-    // Inspect link and heading differences
     const serverLinks = Array.from(serverHtml.matchAll(/href=["'](https?:\/\/[^"']+|\/[^"']+)["']/gi)).map(m => m[1]);
-    const clientLinks = Array.from(hydratedDomHtml.matchAll(/href=["'](https?:\/\/[^"']+|\/[^"']+)["']/gi)).map(m => m[1]);
+    const clientLinks = Array.from(normalizedDomHtml.matchAll(/href=["'](https?:\/\/[^"']+|\/[^"']+)["']/gi)).map(m => m[1]);
     const linksOnlyInClient = clientLinks.filter(l => !serverLinks.includes(l)).slice(0, 10);
     const serverH1s = Array.from(serverHtml.matchAll(/<h1[^>]*>([\s\S]*?)<\/h1>/gi)).map(m => m[1].replace(/<[^>]+>/g, '').trim());
-    const clientH1s = Array.from(hydratedDomHtml.matchAll(/<h1[^>]*>([\s\S]*?)<\/h1>/gi)).map(m => m[1].replace(/<[^>]+>/g, '').trim());
+    const clientH1s = Array.from(normalizedDomHtml.matchAll(/<h1[^>]*>([\s\S]*?)<\/h1>/gi)).map(m => m[1].replace(/<[^>]+>/g, '').trim());
     const headingsOnlyInClient = clientH1s.filter(h => !serverH1s.includes(h));
     const crawlerRisk = linksOnlyInClient.length > 5 || percentDiff > 50
         ? 'High (Significant Hydration Dependence)'
@@ -54,17 +53,16 @@ export async function compareServerVsClientDom(url) {
             ? 'Medium'
             : 'Low';
     const recommendations = [];
-    if (linksOnlyInClient.length > 0) {
-        recommendations.push(`Ensure critical navigation links (${linksOnlyInClient.length} detected) are present in the initial Server-Side Rendered (SSR) HTML rather than injected via client JavaScript.`);
+    if (percentDiff < 15 && linksOnlyInClient.length === 0 && headingsOnlyInClient.length === 0) {
+        recommendations.push('Static DOM normalization shows strong parity. This does not execute client JavaScript.');
     }
-    if (headingsOnlyInClient.length > 0) {
-        recommendations.push('H1 tag is rendered via client-side JavaScript. Pre-render H1 in server HTML to guarantee immediate crawler indexing.');
-    }
-    if (percentDiff < 15 && linksOnlyInClient.length === 0) {
-        recommendations.push('Excellent hydration parity. Initial HTML matches rendered DOM cleanly for search engine bots.');
+    else {
+        recommendations.push('This result reflects static DOM normalization only; use a real browser runtime to test post-JavaScript hydration behavior.');
     }
     return {
         url,
+        executionMode: 'static_dom_normalization',
+        domParser: 'jsdom_html_parser',
         serverHtmlLength: serverLength,
         hydratedDomLength: clientLength,
         contentDifferencePercent: percentDiff,

package/dist/utils/projectScanner.d.ts

@@ -2,5 +2,5 @@ import { ProjectFrameworkInfo, DiscoveredRoute, RouteSourceMapping } from '../ty
 import { FrameworkAdapter } from '../adapters/types.js';
 export declare function getProjectAdapter(projectDir: string): FrameworkAdapter;
 export declare function detectFramework(projectDir: string): ProjectFrameworkInfo;
-export declare function discoverRoutes(projectDir: string, _frameworkInfo?: ProjectFrameworkInfo): DiscoveredRoute[];
+export declare function discoverRoutes(projectDir: string, frameworkInfo?: ProjectFrameworkInfo): DiscoveredRoute[];
 export declare function mapUrlToRouteSource(targetUrl: string, discoveredRoutes: DiscoveredRoute[], projectDir?: string): RouteSourceMapping;

package/dist/utils/projectScanner.js

@@ -9,9 +9,11 @@ export function detectFramework(projectDir) {
     const adapter = defaultAdapterRegistry.getAdapterForProject(resolvedDir);
     return adapter.getProjectInfo(resolvedDir);
 }
-export function discoverRoutes(projectDir, _frameworkInfo) {
+export function discoverRoutes(projectDir, frameworkInfo) {
     const resolvedDir = path.resolve(projectDir);
-    const adapter = defaultAdapterRegistry.getAdapterForProject(resolvedDir);
+    const adapter = frameworkInfo?.framework
+        ? (defaultAdapterRegistry.getAdapterById(frameworkInfo.framework) || defaultAdapterRegistry.getAdapterForProject(resolvedDir))
+        : defaultAdapterRegistry.getAdapterForProject(resolvedDir);
     return adapter.discoverRoutes(resolvedDir);
 }
 export function mapUrlToRouteSource(targetUrl, discoveredRoutes, projectDir = '.') {

package/dist/utils/scraper.d.ts

@@ -1,5 +1,10 @@
 import * as cheerio from 'cheerio';
 export declare function getRandomUserAgent(): string;
+export interface InternalLinkDetail {
+    href: string;
+    anchorText: string;
+    rel: string[];
+}
 export interface FetchedPageContent {
     url: string;
     statusCode: number;
@@ -19,6 +24,7 @@ export interface FetchedPageContent {
     links: {
         internal: string[];
         external: string[];
+        internalDetails: InternalLinkDetail[];
     };
     images: Array<{
         src: string;
@@ -26,11 +32,4 @@ export interface FetchedPageContent {
     }>;
     schemas: any[];
 }
-/**
- * Robust fetcher that supports:
- * 1. Live Web URLs (https://example.com)
- * 2. Localhost Dev Servers (http://localhost:3000)
- * 3. Local Workspace File Paths (d:/aide/index.html, ./public/test.html)
- * 4. Raw HTML strings
- */
 export declare function fetchAndParsePage(input: string, baseOrigin?: string): Promise<FetchedPageContent>;

package/dist/utils/scraper.js

@@ -14,29 +14,19 @@ export function getRandomUserAgent() {
         return custom;
     return USER_AGENTS[Math.floor(Math.random() * USER_AGENTS.length)];
 }
-/**
- * Robust fetcher that supports:
- * 1. Live Web URLs (https://example.com)
- * 2. Localhost Dev Servers (http://localhost:3000)
- * 3. Local Workspace File Paths (d:/aide/index.html, ./public/test.html)
- * 4. Raw HTML strings
- */
 export async function fetchAndParsePage(input, baseOrigin) {
     let html = '';
     let url = input;
     let statusCode = 200;
     let headers = {};
-    // Check if input is raw HTML
     if (input.trim().startsWith('<') && input.includes('>')) {
         html = input;
         url = baseOrigin || 'raw-html-input';
     }
-    // Check if input is a local file path
     else if (fs.existsSync(input) && fs.statSync(input).isFile()) {
         html = fs.readFileSync(input, 'utf-8');
         url = `file://${path.resolve(input).replace(/\\/g, '/')}`;
     }
-    // Otherwise treat as URL (local or remote)
     else {
         try {
             const response = await axios.get(input, {
@@ -60,70 +50,68 @@ export async function fetchAndParsePage(input, baseOrigin) {
         }
     }
     const $ = cheerio.load(html);
-    // Extract metadata
     const title = $('title').first().text().trim() || $('meta[property="og:title"]').attr('content')?.trim() || '';
     const metaDescription = $('meta[name="description"]').attr('content')?.trim() || $('meta[property="og:description"]').attr('content')?.trim() || '';
-    // Extract headings
     const headings = {
         h1: $('h1').map((_, el) => $(el).text().trim()).get().filter(Boolean),
         h2: $('h2').map((_, el) => $(el).text().trim()).get().filter(Boolean),
         h3: $('h3').map((_, el) => $(el).text().trim()).get().filter(Boolean),
         h4: $('h4').map((_, el) => $(el).text().trim()).get().filter(Boolean),
     };
-    // Clean body text
     const cloneBody = $('body').clone();
     cloneBody.find('script, style, noscript, nav, footer, iframe, svg').remove();
     const cleanText = cloneBody.text().replace(/\s+/g, ' ').trim();
     const words = cleanText.split(/\s+/).filter(w => w.length > 0);
     const wordCount = words.length;
-    // Extract links
-    const domain = url.startsWith('http') ? new URL(url).hostname : '';
+    const domain = url.startsWith('http') ? new URL(url).hostname.toLowerCase() : '';
     const internal = [];
     const external = [];
+    const internalDetails = [];
     $('a[href]').each((_, el) => {
         const href = $(el).attr('href')?.trim() || '';
         if (!href || href.startsWith('#') || href.startsWith('javascript:') || href.startsWith('mailto:') || href.startsWith('tel:'))
             return;
+        const anchorText = $(el).text().replace(/\s+/g, ' ').trim();
+        const rel = ($(el).attr('rel') || '').split(/\s+/).map(v => v.trim()).filter(Boolean);
         try {
             if (href.startsWith('/')) {
                 internal.push(href);
+                internalDetails.push({ href, anchorText, rel });
             }
-            else if (href.startsWith('http')) {
+            else if (href.startsWith('http://') || href.startsWith('https://')) {
                 const parsed = new URL(href);
-                if (domain && parsed.hostname === domain) {
+                if (domain && parsed.hostname.toLowerCase() === domain) {
                     internal.push(parsed.pathname + parsed.search);
+                    internalDetails.push({ href, anchorText, rel });
                 }
                 else {
                     external.push(href);
                 }
             }
             else if (!href.includes(':')) {
-                // Relative link (e.g. "about", "../docs")
                 internal.push('/' + href.replace(/^\.?\//, ''));
+                internalDetails.push({ href, anchorText, rel });
             }
         }
         catch {
-            // Ignore malformed URLs
+            // Ignore malformed URLs.
         }
     });
-    // Extract images
     const images = [];
     $('img').each((_, el) => {
         const src = $(el).attr('src') || $(el).attr('data-src') || '';
         const alt = $(el).attr('alt') || '';
         images.push({ src, alt });
     });
-    // Extract JSON-LD schemas
     const schemas = [];
     $('script[type="application/ld+json"]').each((_, el) => {
         try {
             const text = $(el).html();
-            if (text) {
+            if (text)
                 schemas.push(JSON.parse(text));
-            }
         }
         catch {
-            // Ignore invalid JSON-LD parsing errors
+            // Preserve the page result; invalid JSON-LD is handled by schema analysis.
         }
     });
     return {
@@ -137,7 +125,7 @@ export async function fetchAndParsePage(input, baseOrigin) {
         headings,
         cleanText,
         wordCount,
-        links: { internal, external },
+        links: { internal, external, internalDetails },
         images,
         schemas
     };

package/dist/utils/snapshotEngine.d.ts

@@ -5,7 +5,7 @@ export interface CreateSnapshotOptions {
     maxPagesToAudit?: number;
     includeCrawlGraph?: boolean;
 }
-export declare function computeLogicalPageId(urlOrPath: string): string;
+export declare function computeLogicalPageId(urlOrPath: string, baseUrl?: string): string;
 export declare function extractGitMetadata(projectDir: string): GitMetadata;
 export declare function createProjectSnapshot(projectPath: string, options?: CreateSnapshotOptions): Promise<ProjectSnapshot>;
 export declare function compareSnapshots(baseline: ProjectSnapshot, current: ProjectSnapshot): RegressionReport;