seo-gravity-mcp 1.3.2 → 1.3.4

package/dist/utils/snapshotEngine.js

@@ -5,20 +5,9 @@ import { inspectSourceFileAST } from './astLocator.js';
 import { defaultInvariantRegistry } from '../invariants/registry.js';
 import * as path from 'path';
 import { execSync } from 'child_process';
-import * as crypto from 'crypto';
-export function computeLogicalPageId(urlOrPath) {
-    let clean = urlOrPath;
-    let origin = 'default';
-    try {
-        if (clean.startsWith('http')) {
-            const u = new URL(clean);
-            origin = u.origin.toLowerCase();
-            clean = u.pathname;
-        }
-    }
-    catch { }
-    clean = clean.replace(/\/$/, '') || '/';
-    return 'page_' + crypto.createHash('sha256').update(`${origin}:${clean}`).digest('hex').substring(0, 12);
+import { computeNormalizedLogicalPageId } from './urlNormalizer.js';
+export function computeLogicalPageId(urlOrPath, baseUrl) {
+    return computeNormalizedLogicalPageId(urlOrPath, baseUrl);
 }
 export function extractGitMetadata(projectDir) {
     try {
@@ -170,13 +159,18 @@ export async function createProjectSnapshot(projectPath, options = {}) {
             const pageId = computeLogicalPageId(route.routePath);
             const fullSrcPath = path.join(resolvedPath, route.sourceFilePath);
             const ast = inspectSourceFileAST(fullSrcPath);
-            // Metadata invariant
+            // Metadata & Title invariant (disaggregated)
             const hasMeta = ast.hasMetadataExport || ast.hasGenerateMetadata || route.hasHeadComponent;
+            const hasTitle = Boolean(ast.extractedTitle || route.hasHeadComponent);
             const titleInv = defaultInvariantRegistry.evaluateContext('INV-TITLE-PRESENT', {
                 url: route.routePath,
                 logicalPageId: pageId,
+                sourceFilePath: route.sourceFilePath,
+                sourceRange: ast.metadataRange,
+                hasTitle,
                 hasMetadata: hasMeta,
-                extractedTitle: ast.extractedTitle
+                extractedTitle: ast.extractedTitle,
+                hasDescription: Boolean(ast.extractedDescription)
             }, {
                 analyzer: 'astLocator',
                 source: 'ast_inspection',
@@ -190,6 +184,8 @@ export async function createProjectSnapshot(projectPath, options = {}) {
             const canonicalInv = defaultInvariantRegistry.evaluateContext('INV-CANONICAL-RESOLVES', {
                 url: route.routePath,
                 logicalPageId: pageId,
+                sourceFilePath: route.sourceFilePath,
+                sourceRange: ast.canonicalRange,
                 hasCanonical,
                 extractedCanonical: ast.extractedCanonical
             }, {
@@ -211,11 +207,9 @@ export async function createProjectSnapshot(projectPath, options = {}) {
                     evidenceType: 'observed',
                     evidence: `File '${route.sourceFilePath}' has no metadata declaration.`,
                     affectedUrl: route.routePath,
-                    sourceLocation: {
-                        filePath: route.sourceFilePath,
-                        startLine: 1,
-                        endLine: 1
-                    },
+                    sourceLocation: ast.metadataRange
+                        ? { filePath: route.sourceFilePath, startLine: ast.metadataRange.startLine, endLine: ast.metadataRange.endLine }
+                        : { filePath: route.sourceFilePath },
                     sourceRange: ast.metadataRange,
                     likelyRootCause: 'Page component does not declare SEO metadata export.',
                     recommendation: `Add metadata export or title tag in ${route.sourceFilePath}.`,
@@ -238,7 +232,9 @@ export async function createProjectSnapshot(projectPath, options = {}) {
                     evidenceType: 'observed',
                     evidence: `Route '${route.routePath}' (${route.sourceFilePath}) does not declare a canonical URL.`,
                     affectedUrl: route.routePath,
-                    sourceLocation: { filePath: route.sourceFilePath },
+                    sourceLocation: ast.canonicalRange
+                        ? { filePath: route.sourceFilePath, startLine: ast.canonicalRange.startLine, endLine: ast.canonicalRange.endLine }
+                        : { filePath: route.sourceFilePath },
                     sourceRange: ast.canonicalRange,
                     likelyRootCause: 'Page does not declare its canonical master URL, risking duplicate indexing.',
                     recommendation: `Add canonical URL declaration to ${route.sourceFilePath}.`,
@@ -283,7 +279,15 @@ export async function createProjectSnapshot(projectPath, options = {}) {
                 }
             }
         }
-        catch { }
+        catch (err) {
+            crawlGraphSummary = {
+                state: 'FAILED',
+                error: err.message || 'Crawl error',
+                baseUrl,
+                pagesCrawled: 0,
+                orphanPages: []
+            };
+        }
     }
     // 4. Compute Multidimensional Scores
     const scores = calculateMultiDimensionalScores(findings, {
@@ -390,19 +394,39 @@ export function compareSnapshots(baseline, current) {
         }
         else if (bInv && !cInv) {
             // Invariant disappeared in current snapshot!
-            status = bInv.satisfied ? 'NEW_REGRESSION' : 'RESOLVED';
-            invariantDiffs.push({
-                invariantId: bInv.id,
-                logicalPageId: bInv.logicalPageId,
-                url: bInv.url,
-                status,
-                baselineSatisfied: bInv.satisfied,
-                currentSatisfied: false,
-                requirementLevel: bInv.requirementLevel || 'REQUIRED',
-                severity: bInv.severity || 'high',
-                evidence: bInv.evidence,
-                message: `${bInv.description}: Invariant disappeared (${status})`
-            });
+            const currentRouteStillExists = (current.discoveredRoutes || []).some(r => r.routePath === bInv.url);
+            if (currentRouteStillExists) {
+                // Active route lost its invariant evidence -> Genuine regression
+                status = bInv.satisfied ? 'NEW_REGRESSION' : 'RESOLVED';
+                invariantDiffs.push({
+                    invariantId: bInv.id,
+                    logicalPageId: bInv.logicalPageId,
+                    url: bInv.url,
+                    status,
+                    baselineSatisfied: bInv.satisfied,
+                    currentSatisfied: false,
+                    requirementLevel: bInv.requirementLevel || 'REQUIRED',
+                    severity: bInv.severity || 'high',
+                    evidence: bInv.evidence,
+                    message: `${bInv.description}: Missing invariant evidence for active route (${status})`
+                });
+            }
+            else {
+                // Route was intentionally deleted or removed -> Expected change
+                status = 'EXPECTED_CHANGE';
+                invariantDiffs.push({
+                    invariantId: bInv.id,
+                    logicalPageId: bInv.logicalPageId,
+                    url: bInv.url,
+                    status,
+                    baselineSatisfied: bInv.satisfied,
+                    currentSatisfied: false,
+                    requirementLevel: bInv.requirementLevel || 'REQUIRED',
+                    severity: 'low',
+                    evidence: bInv.evidence,
+                    message: `${bInv.description}: Route was removed (EXPECTED_CHANGE)`
+                });
+            }
         }
     }
     // Score deltas

package/dist/utils/urlNormalizer.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeUrl(rawUrl: string, baseUrl?: string): string;
+export declare function computeNormalizedLogicalPageId(urlOrPath: string, baseUrl?: string): string;

package/dist/utils/urlNormalizer.js

@@ -0,0 +1,60 @@
+import * as crypto from 'crypto';
+export function normalizeUrl(rawUrl, baseUrl) {
+    if (!rawUrl)
+        return '/';
+    try {
+        let resolved;
+        if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
+            resolved = new URL(rawUrl);
+        }
+        else if (baseUrl) {
+            resolved = new URL(rawUrl, baseUrl);
+        }
+        else {
+            resolved = new URL(rawUrl, 'http://localhost');
+        }
+        // Lowercase hostname
+        resolved.hostname = resolved.hostname.toLowerCase();
+        // Strip default ports
+        if ((resolved.protocol === 'http:' && resolved.port === '80') ||
+            (resolved.protocol === 'https:' && resolved.port === '443')) {
+            resolved.port = '';
+        }
+        // Normalize path (remove duplicate slashes, keep root or trim trailing slash)
+        let pathname = resolved.pathname.replace(/\/+/g, '/');
+        if (pathname.length > 1 && pathname.endsWith('/')) {
+            pathname = pathname.slice(0, -1);
+        }
+        resolved.pathname = pathname;
+        // Sort query parameters deterministically
+        const params = Array.from(resolved.searchParams.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+        resolved.search = '';
+        for (const [k, v] of params) {
+            resolved.searchParams.append(k, v);
+        }
+        // Remove hash/fragment for canonical logical page identity
+        resolved.hash = '';
+        if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://') || baseUrl) {
+            return resolved.toString();
+        }
+        return resolved.pathname + resolved.search;
+    }
+    catch {
+        return rawUrl.trim().replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+    }
+}
+export function computeNormalizedLogicalPageId(urlOrPath, baseUrl) {
+    const norm = normalizeUrl(urlOrPath, baseUrl);
+    let origin = 'default';
+    let pathOnly = norm;
+    try {
+        if (norm.startsWith('http')) {
+            const u = new URL(norm);
+            origin = u.origin;
+            pathOnly = u.pathname + u.search;
+        }
+    }
+    catch { }
+    const payload = `${origin}:${pathOnly}`;
+    return 'page_' + crypto.createHash('sha256').update(payload).digest('hex').substring(0, 12);
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.3.2";
+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.2';
+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.2",
+  "version": "1.3.4",
   "description": "SEO Engineering Infrastructure Layer for AI Coding Agents and CI/CD Pipelines",
   "main": "dist/index.js",
   "type": "module",
@@ -37,6 +37,7 @@
     "cheerio": "^1.0.0",
     "fast-xml-parser": "^5.0.8",
     "jsdom": "^26.0.0",
+    "yaml": "^2.9.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {