seo-gravity-mcp 1.3.3 → 1.3.4

package/README.md

@@ -1,4 +1,4 @@
-# 🚀 SEO Gravity (v1.3.3)
+# 🚀 SEO Gravity (v1.3.4)
 
 <div align="center">
 

package/dist/adapters/unknownAdapter.js

@@ -15,7 +15,7 @@ export class UnknownAdapter {
             hasLlmsTxt: false,
             rootDir: path.resolve(projectDir),
             routesDir: '.',
-            defaultDevPort: 3000
+            defaultDevPort: undefined
         };
     }
     discoverRoutes(_projectDir) {

package/dist/benchmark/methodology.js

@@ -179,7 +179,7 @@ export function generateBenchmarkMethodologyReport() {
     }
     return {
         title: 'SEO Gravity Multi-Framework Correlation & Invariant Benchmark Methodology',
-        version: '1.3.3',
+        version: '1.3.4',
         evaluatedAt: new Date().toISOString(),
         definitionOfCorrelation: 'A correlation is defined as a verified mapping connecting an observed URL or Route Pattern to its exact physical source file, template, route configuration, and AST symbol coordinate range.',
         totalFrameworksTested: BENCHMARK_FIXTURES.length,

package/dist/invariants/registry.js

@@ -116,26 +116,36 @@ export const BUILTIN_INVARIANTS = [
     {
         id: 'INV-ROBOTS-ALLOWED',
         name: 'Robots Policy Determinable',
-        description: 'Project must provide a determinable robots crawl policy via robots.txt, robots.ts, or standard allow-all defaults.',
+        description: 'The effective robots crawl policy must be determinable; absence of robots.txt defaults to allow-all unless another blocking mechanism is observed.',
         category: 'robots',
         requirementLevel: 'CONDITIONAL',
         severity: 'medium',
         scope: 'SITE',
         expectedCondition: 'Robots crawl policy is determinable and does not block critical assets',
-        failureEvidence: 'No robots crawl configuration detected.',
-        remediationGuide: 'Create public/robots.txt or app/robots.ts if specific bot directives are desired.',
-        verificationMethod: 'Check GET /robots.txt response or adapter robots inspection.',
+        failureEvidence: 'Robots policy could not be determined or an observed policy blocks required resources.',
+        remediationGuide: 'Create or correct robots.txt/app/robots.ts when explicit crawler directives are needed.',
+        verificationMethod: 'Check GET /robots.txt and relevant meta/X-Robots directives.',
         evaluate(ctx) {
-            const ok = Boolean(ctx.hasRobots);
+            const policy = ctx.robotsPolicyState ?? (ctx.hasRobots ? 'explicit' : 'default_allow');
+            const ok = policy === 'explicit' || policy === 'default_allow';
+            const observed = policy === 'explicit'
+                ? 'Explicit robots policy resolved.'
+                : policy === 'default_allow'
+                    ? 'No explicit robots file; standard default allow policy assumed.'
+                    : policy === 'blocking'
+                        ? 'Blocking robots policy observed.'
+                        : 'Robots policy could not be determined.';
             return {
                 satisfied: ok,
-                observedCondition: ok ? 'Robots policy determinable' : 'Robots policy not explicitly declared',
-                evidence: ok ? 'robots.txt configuration present.' : 'No robots.txt found (default allow-all).',
+                observedCondition: observed,
+                evidence: ok
+                    ? 'Effective robots policy is determinable.'
+                    : 'Effective robots policy is not safely determinable or is blocking.',
                 polymorphicEvidence: {
                     type: 'route_config',
-                    description: ok ? 'Robots config resolved' : 'Robots config absent',
-                    sourceFile: 'robots.txt',
-                    configFormat: 'static_file',
+                    description: observed,
+                    sourceFile: ctx.hasRobots ? 'robots.txt' : undefined,
+                    configFormat: ctx.hasRobots ? 'static_file' : 'implicit_default',
                     declaredPattern: '/robots.txt',
                     timestamp: new Date().toISOString()
                 }
@@ -204,9 +214,8 @@ export const BUILTIN_INVARIANTS = [
 export class InvariantRegistry {
     invariants = new Map();
     constructor(initial = BUILTIN_INVARIANTS) {
-        for (const inv of initial) {
+        for (const inv of initial)
             this.invariants.set(inv.id, inv);
-        }
     }
     register(invariant) {
         this.invariants.set(invariant.id, invariant);

package/dist/invariants/types.d.ts

@@ -3,6 +3,7 @@ import { PolymorphicEvidence } from '../types/evidence.js';
 export type RequirementLevel = 'REQUIRED' | 'CONDITIONAL' | 'RECOMMENDED' | 'OPTIONAL';
 export type InvariantScope = 'SITE' | 'ROUTE' | 'PAGE' | 'COMPONENT' | 'RESOURCE' | 'site_wide' | 'crawl_graph';
 export type InvariantCategory = 'http' | 'indexability' | 'canonical' | 'metadata' | 'links' | 'schema' | 'robots' | 'ai_readiness';
+export type RobotsPolicyState = 'explicit' | 'default_allow' | 'blocking' | 'unknown';
 export interface InvariantEvaluationContext {
     url: string;
     logicalPageId: string;
@@ -19,12 +20,13 @@ export interface InvariantEvaluationContext {
     isIndexable?: boolean;
     hasSchema?: boolean;
     hasRobots?: boolean;
+    robotsPolicyState?: RobotsPolicyState;
     hasSitemap?: boolean;
     hasLlmsTxt?: boolean;
     incomingLinksCount?: number;
     extractedTitle?: string;
     extractedCanonical?: string;
-    rawPayload?: any;
+    rawPayload?: unknown;
 }
 export interface InvariantEvaluationResult {
     satisfied: boolean;

package/dist/policy/loader.d.ts

@@ -119,8 +119,8 @@ export declare const PolicyConfigSchema: z.ZodObject<{
 }>;
 export declare class PolicyLoader {
     static resolvePolicy(projectDir?: string, explicitPath?: string): PolicyConfig;
-    static parseConfigFile(filePath: string): any;
-    static parseYaml(content: string): Record<string, any>;
+    static parseConfigFile(filePath: string): unknown;
+    static parseYaml(content: string): Record<string, unknown>;
     static isRegressionBreachingPolicy(diff: InvariantDiffItem, policy: PolicyConfig): boolean;
     static evaluatePolicyGate(diffs: InvariantDiffItem[], policy: PolicyConfig): {
         pass: boolean;

package/dist/policy/loader.js

@@ -47,68 +47,90 @@ export class PolicyLoader {
                 }
             }
         }
-        const baseProfileName = rawConfig?.profile || 'balanced';
-        const baseProfile = BUILTIN_PROFILES[baseProfileName] || BUILTIN_PROFILES.balanced;
         if (!rawConfig) {
-            return baseProfile;
+            return BUILTIN_PROFILES.balanced;
         }
-        // Normalize snake_case regression options to camelCase
-        const rawReg = rawConfig.regression || {};
+        const parsed = PolicyConfigSchema.safeParse(rawConfig);
+        if (!parsed.success) {
+            const details = parsed.error.issues
+                .map(issue => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+                .join('; ');
+            throw new Error(`Invalid SEO Gravity policy configuration: ${details}`);
+        }
+        const config = parsed.data;
+        const baseProfileName = config.profile || 'balanced';
+        const baseProfile = (baseProfileName !== 'custom' && BUILTIN_PROFILES[baseProfileName])
+            ? BUILTIN_PROFILES[baseProfileName]
+            : BUILTIN_PROFILES.balanced;
+        const rawReg = config.regression || {};
         const normalizedRegression = {
             ...baseProfile.regression,
-            failOnLevels: rawReg.failOnLevels || rawReg.fail_on_levels || baseProfile.regression?.failOnLevels,
-            failOnSeverities: rawReg.failOnSeverities || rawReg.fail_on_severities || baseProfile.regression?.failOnSeverities,
-            allowExpectedChanges: rawReg.allowExpectedChanges ?? rawReg.allow_expected_changes ?? baseProfile.regression?.allowExpectedChanges,
-            maxAllowedRegressions: rawReg.maxAllowedRegressions ?? rawReg.max_allowed_regressions ?? baseProfile.regression?.maxAllowedRegressions
+            failOnLevels: rawReg.failOnLevels || baseProfile.regression?.failOnLevels,
+            failOnSeverities: rawReg.failOnSeverities || baseProfile.regression?.failOnSeverities,
+            allowExpectedChanges: rawReg.allowExpectedChanges ?? baseProfile.regression?.allowExpectedChanges,
+            maxAllowedRegressions: rawReg.maxAllowedRegressions ?? baseProfile.regression?.maxAllowedRegressions
         };
-        // Normalize invariant policy overrides
         const mergedInvariants = {
             ...baseProfile.invariants,
-            ...(rawConfig.invariants || {})
+            ...(config.invariants || {})
         };
-        // Support convenient high-level policy shortcuts (e.g. policy: { canonical: required, sitemap: recommended })
-        const rawPolicy = rawConfig.policy || {};
-        if (rawPolicy.canonical) {
-            const lvl = String(rawPolicy.canonical).toUpperCase();
+        const rawPolicy = config.policy || {};
+        if (rawPolicy.canonical !== undefined) {
+            const parsedLevel = String(rawPolicy.canonical).toUpperCase();
+            if (!['REQUIRED', 'CONDITIONAL', 'RECOMMENDED', 'OPTIONAL'].includes(parsedLevel)) {
+                throw new Error(`Invalid policy.canonical requirement level: '${rawPolicy.canonical}'.`);
+            }
+            const lvl = parsedLevel;
             mergedInvariants['INV-CANONICAL-RESOLVES'] = { requirementLevel: lvl, severity: 'high', enabled: true };
         }
-        if (rawPolicy.sitemap) {
-            const lvl = String(rawPolicy.sitemap).toUpperCase();
+        if (rawPolicy.sitemap !== undefined) {
+            const parsedLevel = String(rawPolicy.sitemap).toUpperCase();
+            if (!['REQUIRED', 'CONDITIONAL', 'RECOMMENDED', 'OPTIONAL'].includes(parsedLevel)) {
+                throw new Error(`Invalid policy.sitemap requirement level: '${rawPolicy.sitemap}'.`);
+            }
+            const lvl = parsedLevel;
             mergedInvariants['INV-SITEMAP-PRESENT'] = { requirementLevel: lvl, severity: 'medium', enabled: true };
         }
-        if (rawPolicy.llms_txt || rawPolicy.llmsTxt) {
-            const lvl = String(rawPolicy.llms_txt || rawPolicy.llmsTxt).toUpperCase();
+        if (rawPolicy.llms_txt !== undefined || rawPolicy.llmsTxt !== undefined) {
+            const rawLevel = rawPolicy.llms_txt ?? rawPolicy.llmsTxt;
+            const parsedLevel = String(rawLevel).toUpperCase();
+            if (!['REQUIRED', 'CONDITIONAL', 'RECOMMENDED', 'OPTIONAL'].includes(parsedLevel)) {
+                throw new Error(`Invalid policy.llms_txt requirement level: '${rawLevel}'.`);
+            }
+            const lvl = parsedLevel;
             mergedInvariants['INV-LLMS-TXT'] = { requirementLevel: lvl, severity: 'low', enabled: true };
         }
-        const merged = {
-            version: rawConfig.version || baseProfile.version,
+        return {
+            version: typeof config.version === 'number' ? config.version : (Number(config.version) || baseProfile.version),
             profile: baseProfileName,
             regression: normalizedRegression,
             invariants: mergedInvariants,
-            framework: rawConfig.framework
+            framework: config.framework
         };
-        return merged;
     }
     static parseConfigFile(filePath) {
-        try {
-            const content = fs.readFileSync(filePath, 'utf-8');
-            if (filePath.endsWith('.json')) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        if (filePath.endsWith('.json')) {
+            try {
                 return JSON.parse(content);
             }
+            catch (err) {
+                throw new Error(`Invalid JSON policy configuration '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        try {
             return this.parseYaml(content);
         }
-        catch {
-            return null;
+        catch (err) {
+            throw new Error(`Invalid YAML policy configuration '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     static parseYaml(content) {
-        try {
-            const parsed = YAML.parse(content);
-            return (typeof parsed === 'object' && parsed !== null) ? parsed : {};
-        }
-        catch {
-            return {};
+        const parsed = YAML.parse(content);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Policy YAML root must be an object.');
         }
+        return parsed;
     }
     static isRegressionBreachingPolicy(diff, policy) {
         if (diff.status === 'EXPECTED_CHANGE') {
@@ -118,15 +140,13 @@ export class PolicyLoader {
             return false;
         const invOverride = policy.invariants?.[diff.invariantId];
         if (invOverride && invOverride.enabled === false) {
-            return false; // Explicitly disabled by project policy
+            return false;
         }
         const level = invOverride?.requirementLevel || diff.requirementLevel || 'REQUIRED';
         const severity = invOverride?.severity || diff.severity || 'high';
         const failLevels = policy.regression?.failOnLevels || ['REQUIRED', 'CONDITIONAL'];
         const failSeverities = policy.regression?.failOnSeverities || ['critical', 'high'];
-        const levelBreached = failLevels.includes(level);
-        const severityBreached = failSeverities.includes(severity);
-        return levelBreached && severityBreached;
+        return failLevels.includes(level) && failSeverities.includes(severity);
     }
     static evaluatePolicyGate(diffs, policy) {
         const breachingDiffs = diffs.filter(d => this.isRegressionBreachingPolicy(d, policy));
@@ -136,12 +156,6 @@ export class PolicyLoader {
         const verdict = pass
             ? `✅ PASSED (Policy: ${policy.profile}): ${totalBreaches} breach(es) within allowed threshold (max: ${maxAllowed}).`
             : `🚨 FAILED (Policy: ${policy.profile}): ${totalBreaches} invariant regression(s) breached policy (max allowed: ${maxAllowed}).`;
-        return {
-            pass,
-            breachingDiffs,
-            totalBreaches,
-            maxAllowed,
-            verdict
-        };
+        return { pass, breachingDiffs, totalBreaches, maxAllowed, verdict };
     }
 }

package/dist/policy/profiles.d.ts

@@ -1,2 +1,2 @@
-import { PolicyConfig, PolicyProfileName } from './types.js';
-export declare const BUILTIN_PROFILES: Record<PolicyProfileName, PolicyConfig>;
+import { PolicyConfig, BuiltinProfileName } from './types.js';
+export declare const BUILTIN_PROFILES: Record<BuiltinProfileName, PolicyConfig>;

package/dist/policy/types.d.ts

@@ -1,5 +1,6 @@
 import { RequirementLevel, InvariantSeverity } from '../types/canonical.js';
-export type PolicyProfileName = 'strict' | 'balanced' | 'startup' | 'ecommerce' | 'documentation';
+export type BuiltinProfileName = 'strict' | 'balanced' | 'startup' | 'ecommerce' | 'documentation';
+export type PolicyProfileName = BuiltinProfileName | 'custom';
 export interface InvariantPolicyOverride {
     requirementLevel?: RequirementLevel;
     severity?: InvariantSeverity;

package/dist/types/evidence.d.ts

@@ -27,8 +27,8 @@ export interface TemplateEvidence extends BaseEvidence {
 }
 export interface RouteConfigEvidence extends BaseEvidence {
     type: 'route_config';
-    sourceFile: string;
-    configFormat: 'laravel_routes' | 'symfony_yaml' | 'next_app_dir' | 'next_pages_dir' | 'react_router' | 'static_file';
+    sourceFile?: string;
+    configFormat: 'laravel_routes' | 'symfony_yaml' | 'next_app_dir' | 'next_pages_dir' | 'react_router' | 'static_file' | 'implicit_default';
     declaredPattern: string;
 }
 export interface DomEvidence extends BaseEvidence {

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,14 +53,11 @@ 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,

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/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.3.3";
+export declare const VERSION = "1.3.4";
 export declare const PACKAGE_NAME = "seo-gravity-mcp";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '1.3.3';
+export const VERSION = '1.3.4';
 export const PACKAGE_NAME = 'seo-gravity-mcp';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-gravity-mcp",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "SEO Engineering Infrastructure Layer for AI Coding Agents and CI/CD Pipelines",
   "main": "dist/index.js",
   "type": "module",