seo-gravity-mcp 1.0.2 → 1.2.0

package/dist/adapters/staticAdapter.js

@@ -0,0 +1,117 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export class StaticAdapter {
+    id = 'static-html';
+    name = 'Static HTML / Web Application';
+    detect(_projectDir) {
+        return true; // Fallback
+    }
+    getProjectInfo(projectDir) {
+        return {
+            framework: 'static-html',
+            name: path.basename(projectDir),
+            hasTypeScript: fs.existsSync(path.join(projectDir, 'tsconfig.json')),
+            hasSitemapConfig: Boolean(this.findSitemapConfig(projectDir)),
+            hasRobotsConfig: Boolean(this.findRobotsConfig(projectDir)),
+            hasLlmsTxt: Boolean(this.findLlmsTxt(projectDir)),
+            rootDir: path.resolve(projectDir),
+            routesDir: '.',
+            defaultDevPort: 8080
+        };
+    }
+    discoverRoutes(projectDir) {
+        const discovered = [];
+        const scan = (dir, prefix) => {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const e of entries) {
+                if (['node_modules', '.git', 'dist', 'build', '.next'].includes(e.name))
+                    continue;
+                const full = path.join(dir, e.name);
+                if (e.isDirectory()) {
+                    const next = prefix === '/' ? `/${e.name}` : `${prefix}/${e.name}`;
+                    scan(full, next);
+                }
+                else if (e.isFile() && e.name.endsWith('.html')) {
+                    const base = e.name.replace(/\.html$/, '');
+                    let routePath = prefix;
+                    if (base !== 'index') {
+                        routePath = prefix === '/' ? `/${base}` : `${prefix}/${base}`;
+                    }
+                    if (routePath === '')
+                        routePath = '/';
+                    const rel = path.relative(projectDir, full).replace(/\\/g, '/');
+                    const content = fs.readFileSync(full, 'utf-8');
+                    discovered.push({
+                        routePath,
+                        sourceFilePath: rel,
+                        isDynamic: false,
+                        dynamicParams: [],
+                        routeType: 'page',
+                        hasMetadataExport: /<title\b|<meta\s+name=["']description["']/i.test(content),
+                        hasGenerateMetadata: false,
+                        hasSchemaMarkup: /application\/ld\+json/.test(content),
+                        hasHeadComponent: /<head\b|<title\b/i.test(content),
+                        isClientComponent: false
+                    });
+                }
+            }
+        };
+        scan(projectDir, '/');
+        return discovered;
+    }
+    mapRouteToSource(targetUrl, routes) {
+        let urlPath = targetUrl.startsWith('http') ? new URL(targetUrl).pathname : targetUrl;
+        urlPath = urlPath.replace(/\/$/, '') || '/';
+        const match = routes.find(r => r.routePath === urlPath);
+        return {
+            urlPath,
+            matchedRoute: match,
+            sourceFilePath: match?.sourceFilePath,
+            confidence: match ? 1.0 : 0.0,
+            resolutionMethod: match ? 'exact_match' : 'unmapped'
+        };
+    }
+    async findMetadataImplementation(projectDir, route) {
+        const full = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(full))
+            return { hasMetadata: false, type: 'none' };
+        const content = fs.readFileSync(full, 'utf-8');
+        const has = /<title\b|<meta\s+name=["']description["']/i.test(content);
+        return { hasMetadata: has, type: has ? 'jsx_head' : 'none' };
+    }
+    async findCanonicalDeclaration(projectDir, route) {
+        const full = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(full))
+            return { hasCanonical: false, type: 'none' };
+        const content = fs.readFileSync(full, 'utf-8');
+        return { hasCanonical: /rel=["']canonical["']/i.test(content), type: 'link_jsx_tag' };
+    }
+    async findSchemaDeclaration(projectDir, route) {
+        const full = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(full))
+            return { hasSchema: false, typesFound: [] };
+        const content = fs.readFileSync(full, 'utf-8');
+        return { hasSchema: /application\/ld\+json/i.test(content), typesFound: ['JSON-LD'] };
+    }
+    findRobotsConfig(projectDir) {
+        const paths = ['robots.txt', 'public/robots.txt'];
+        for (const p of paths)
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        return null;
+    }
+    findSitemapConfig(projectDir) {
+        const paths = ['sitemap.xml', 'public/sitemap.xml'];
+        for (const p of paths)
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        return null;
+    }
+    findLlmsTxt(projectDir) {
+        const paths = ['llms.txt', 'public/llms.txt'];
+        for (const p of paths)
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        return null;
+    }
+}

package/dist/adapters/svelteKitAdapter.d.ts

@@ -0,0 +1,16 @@
+import { FrameworkAdapter, MetadataLocationInfo, CanonicalLocationInfo, SchemaLocationInfo } from './types.js';
+import { DiscoveredRoute, ProjectFrameworkInfo, RouteSourceMapping } from '../types/findings.js';
+export declare class SvelteKitAdapter implements FrameworkAdapter {
+    id: string;
+    name: string;
+    detect(projectDir: string): boolean;
+    getProjectInfo(projectDir: string): ProjectFrameworkInfo;
+    discoverRoutes(projectDir: string): DiscoveredRoute[];
+    mapRouteToSource(targetUrl: string, routes: DiscoveredRoute[]): RouteSourceMapping;
+    findMetadataImplementation(projectDir: string, route: DiscoveredRoute): Promise<MetadataLocationInfo>;
+    findCanonicalDeclaration(projectDir: string, route: DiscoveredRoute): Promise<CanonicalLocationInfo>;
+    findSchemaDeclaration(projectDir: string, route: DiscoveredRoute): Promise<SchemaLocationInfo>;
+    findRobotsConfig(projectDir: string): string | null;
+    findSitemapConfig(projectDir: string): string | null;
+    findLlmsTxt(projectDir: string): string | null;
+}

package/dist/adapters/svelteKitAdapter.js

@@ -0,0 +1,122 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export class SvelteKitAdapter {
+    id = 'sveltekit';
+    name = 'SvelteKit';
+    detect(projectDir) {
+        const pkgPath = path.join(projectDir, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            return Boolean(deps['@sveltejs/kit']);
+        }
+        catch {
+            return false;
+        }
+    }
+    getProjectInfo(projectDir) {
+        return {
+            framework: 'sveltekit',
+            name: path.basename(projectDir),
+            hasTypeScript: fs.existsSync(path.join(projectDir, 'tsconfig.json')),
+            hasSitemapConfig: Boolean(this.findSitemapConfig(projectDir)),
+            hasRobotsConfig: Boolean(this.findRobotsConfig(projectDir)),
+            hasLlmsTxt: Boolean(this.findLlmsTxt(projectDir)),
+            rootDir: path.resolve(projectDir),
+            routesDir: 'src/routes',
+            devCommand: 'npm run dev',
+            defaultDevPort: 5173
+        };
+    }
+    discoverRoutes(projectDir) {
+        const routesDir = path.join(projectDir, 'src/routes');
+        const discovered = [];
+        if (!fs.existsSync(routesDir))
+            return discovered;
+        const scan = (dir, prefix) => {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const e of entries) {
+                const full = path.join(dir, e.name);
+                if (e.isDirectory()) {
+                    const next = prefix === '/' ? `/${e.name}` : `${prefix}/${e.name}`;
+                    scan(full, next);
+                }
+                else if (e.isFile() && e.name.startsWith('+page.svelte')) {
+                    const rel = path.relative(projectDir, full).replace(/\\/g, '/');
+                    const content = fs.readFileSync(full, 'utf-8');
+                    discovered.push({
+                        routePath: prefix,
+                        sourceFilePath: rel,
+                        isDynamic: prefix.includes('['),
+                        dynamicParams: (prefix.match(/\[([a-zA-Z0-9_-]+)\]/g) || []).map(p => p.slice(1, -1)),
+                        routeType: 'page',
+                        hasMetadataExport: /<title\b|<svelte:head\b/i.test(content),
+                        hasGenerateMetadata: false,
+                        hasSchemaMarkup: /application\/ld\+json/.test(content),
+                        hasHeadComponent: /<svelte:head\b/i.test(content),
+                        isClientComponent: false
+                    });
+                }
+            }
+        };
+        scan(routesDir, '/');
+        return discovered;
+    }
+    mapRouteToSource(targetUrl, routes) {
+        let urlPath = targetUrl.startsWith('http') ? new URL(targetUrl).pathname : targetUrl;
+        urlPath = urlPath.replace(/\/$/, '') || '/';
+        const match = routes.find(r => r.routePath === urlPath);
+        return {
+            urlPath,
+            matchedRoute: match,
+            sourceFilePath: match?.sourceFilePath,
+            confidence: match ? 1.0 : 0.0,
+            resolutionMethod: match ? 'exact_match' : 'unmapped'
+        };
+    }
+    async findMetadataImplementation(projectDir, route) {
+        const full = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(full))
+            return { hasMetadata: false, type: 'none' };
+        const content = fs.readFileSync(full, 'utf-8');
+        const has = /<svelte:head\b|<title\b/i.test(content);
+        return { hasMetadata: has, type: has ? 'jsx_head' : 'none' };
+    }
+    async findCanonicalDeclaration(projectDir, route) {
+        const full = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(full))
+            return { hasCanonical: false, type: 'none' };
+        const content = fs.readFileSync(full, 'utf-8');
+        return { hasCanonical: /rel=["']canonical["']/i.test(content), type: 'link_jsx_tag' };
+    }
+    async findSchemaDeclaration(projectDir, route) {
+        const full = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(full))
+            return { hasSchema: false, typesFound: [] };
+        const content = fs.readFileSync(full, 'utf-8');
+        return { hasSchema: /application\/ld\+json/i.test(content), typesFound: ['JSON-LD'] };
+    }
+    findRobotsConfig(projectDir) {
+        const paths = ['static/robots.txt', 'robots.txt'];
+        for (const p of paths)
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        return null;
+    }
+    findSitemapConfig(projectDir) {
+        const paths = ['static/sitemap.xml', 'sitemap.xml'];
+        for (const p of paths)
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        return null;
+    }
+    findLlmsTxt(projectDir) {
+        const paths = ['static/llms.txt', 'llms.txt'];
+        for (const p of paths)
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        return null;
+    }
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,39 @@
+import { DiscoveredRoute, ProjectFrameworkInfo, RouteSourceMapping, ASTSourceRange } from '../types/findings.js';
+export interface FrameworkDetectionResult {
+    matched: boolean;
+    confidence: number;
+    evidence: string[];
+}
+export interface MetadataLocationInfo {
+    hasMetadata: boolean;
+    type: 'static_export' | 'dynamic_function' | 'jsx_head' | 'none';
+    sourceRange?: ASTSourceRange;
+    titleSnippet?: string;
+    descriptionSnippet?: string;
+}
+export interface CanonicalLocationInfo {
+    hasCanonical: boolean;
+    type: 'metadata_property' | 'link_jsx_tag' | 'header_config' | 'none';
+    canonicalUrl?: string;
+    sourceRange?: ASTSourceRange;
+}
+export interface SchemaLocationInfo {
+    hasSchema: boolean;
+    typesFound: string[];
+    sourceRange?: ASTSourceRange;
+}
+export interface FrameworkAdapter {
+    id: string;
+    name: string;
+    detect(projectDir: string): boolean;
+    detectDetailed?(projectDir: string): FrameworkDetectionResult;
+    getProjectInfo(projectDir: string): ProjectFrameworkInfo;
+    discoverRoutes(projectDir: string): DiscoveredRoute[];
+    mapRouteToSource(targetUrl: string, routes: DiscoveredRoute[]): RouteSourceMapping;
+    findMetadataImplementation(projectDir: string, route: DiscoveredRoute): Promise<MetadataLocationInfo>;
+    findCanonicalDeclaration(projectDir: string, route: DiscoveredRoute): Promise<CanonicalLocationInfo>;
+    findSchemaDeclaration(projectDir: string, route: DiscoveredRoute): Promise<SchemaLocationInfo>;
+    findRobotsConfig(projectDir: string): string | null;
+    findSitemapConfig(projectDir: string): string | null;
+    findLlmsTxt(projectDir: string): string | null;
+}

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/viteReactAdapter.d.ts

@@ -0,0 +1,16 @@
+import { FrameworkAdapter, MetadataLocationInfo, CanonicalLocationInfo, SchemaLocationInfo } from './types.js';
+import { DiscoveredRoute, ProjectFrameworkInfo, RouteSourceMapping } from '../types/findings.js';
+export declare class ViteReactAdapter implements FrameworkAdapter {
+    id: string;
+    name: string;
+    detect(projectDir: string): boolean;
+    getProjectInfo(projectDir: string): ProjectFrameworkInfo;
+    discoverRoutes(projectDir: string): DiscoveredRoute[];
+    mapRouteToSource(targetUrl: string, routes: DiscoveredRoute[]): RouteSourceMapping;
+    findMetadataImplementation(projectDir: string, route: DiscoveredRoute): Promise<MetadataLocationInfo>;
+    findCanonicalDeclaration(projectDir: string, route: DiscoveredRoute): Promise<CanonicalLocationInfo>;
+    findSchemaDeclaration(projectDir: string, route: DiscoveredRoute): Promise<SchemaLocationInfo>;
+    findRobotsConfig(projectDir: string): string | null;
+    findSitemapConfig(projectDir: string): string | null;
+    findLlmsTxt(projectDir: string): string | null;
+}

package/dist/adapters/viteReactAdapter.js

@@ -0,0 +1,189 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export class ViteReactAdapter {
+    id = 'vite-react';
+    name = 'Vite / React SPA';
+    detect(projectDir) {
+        const pkgPath = path.join(projectDir, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            return Boolean(deps['vite'] || (deps['react'] && !deps['next'] && !deps['astro'] && !deps['@remix-run/react']));
+        }
+        catch {
+            return false;
+        }
+    }
+    getProjectInfo(projectDir) {
+        const pkgPath = path.join(projectDir, 'package.json');
+        let pkg = {};
+        if (fs.existsSync(pkgPath)) {
+            try {
+                pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            }
+            catch { }
+        }
+        return {
+            framework: 'vite-react',
+            name: pkg.name || path.basename(projectDir),
+            version: pkg.dependencies?.vite || pkg.devDependencies?.vite,
+            packageManager: 'npm',
+            hasTypeScript: fs.existsSync(path.join(projectDir, 'tsconfig.json')),
+            hasSitemapConfig: Boolean(this.findSitemapConfig(projectDir)),
+            hasRobotsConfig: Boolean(this.findRobotsConfig(projectDir)),
+            hasLlmsTxt: Boolean(this.findLlmsTxt(projectDir)),
+            rootDir: path.resolve(projectDir),
+            routesDir: 'src',
+            devCommand: 'npm run dev',
+            defaultDevPort: 5173
+        };
+    }
+    discoverRoutes(projectDir) {
+        const discovered = [];
+        // Check index.html
+        if (fs.existsSync(path.join(projectDir, 'index.html'))) {
+            const content = fs.readFileSync(path.join(projectDir, 'index.html'), 'utf-8');
+            discovered.push({
+                routePath: '/',
+                sourceFilePath: 'index.html',
+                isDynamic: false,
+                dynamicParams: [],
+                routeType: 'page',
+                hasMetadataExport: /<title\b|<meta\s+name=["']description["']/i.test(content),
+                hasGenerateMetadata: false,
+                hasSchemaMarkup: /application\/ld\+json/.test(content),
+                hasHeadComponent: true,
+                isClientComponent: true
+            });
+        }
+        // Scan src for router declarations
+        const srcDir = path.join(projectDir, 'src');
+        if (fs.existsSync(srcDir)) {
+            const scanSrc = (dir) => {
+                const entries = fs.readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        scanSrc(fullPath);
+                    }
+                    else if (entry.isFile() && /\.(tsx|jsx|js|ts)$/.test(entry.name)) {
+                        const content = fs.readFileSync(fullPath, 'utf-8');
+                        const rel = path.relative(projectDir, fullPath).replace(/\\/g, '/');
+                        const routeMatches = content.matchAll(/path=["']([^"']+)["']/g);
+                        for (const m of routeMatches) {
+                            const rPath = m[1];
+                            if (rPath && !discovered.some(d => d.routePath === rPath)) {
+                                discovered.push({
+                                    routePath: rPath,
+                                    sourceFilePath: rel,
+                                    isDynamic: rPath.includes(':'),
+                                    dynamicParams: (rPath.match(/:[a-zA-Z0-9_-]+/g) || []).map(p => p.slice(1)),
+                                    routeType: 'page',
+                                    hasMetadataExport: /<Helmet\b|<title\b/i.test(content),
+                                    hasGenerateMetadata: false,
+                                    hasSchemaMarkup: /application\/ld\+json/.test(content),
+                                    hasHeadComponent: /<Helmet\b/i.test(content),
+                                    isClientComponent: true
+                                });
+                            }
+                        }
+                    }
+                }
+            };
+            scanSrc(srcDir);
+        }
+        return discovered;
+    }
+    mapRouteToSource(targetUrl, routes) {
+        let urlPath = targetUrl;
+        try {
+            if (targetUrl.startsWith('http')) {
+                urlPath = new URL(targetUrl).pathname;
+            }
+        }
+        catch {
+            urlPath = targetUrl;
+        }
+        urlPath = urlPath.replace(/\/$/, '') || '/';
+        const match = routes.find(r => r.routePath === urlPath);
+        if (match) {
+            return {
+                urlPath,
+                matchedRoute: match,
+                sourceFilePath: match.sourceFilePath,
+                confidence: 1.0,
+                resolutionMethod: 'exact_match'
+            };
+        }
+        for (const r of routes) {
+            if (!r.isDynamic)
+                continue;
+            const regexStr = '^' + r.routePath.replace(/:[a-zA-Z0-9_-]+/g, '[^/]+') + '$';
+            try {
+                if (new RegExp(regexStr).test(urlPath)) {
+                    return {
+                        urlPath,
+                        matchedRoute: r,
+                        sourceFilePath: r.sourceFilePath,
+                        confidence: 0.95,
+                        resolutionMethod: 'pattern_match'
+                    };
+                }
+            }
+            catch { }
+        }
+        return {
+            urlPath,
+            confidence: 0.0,
+            resolutionMethod: 'unmapped'
+        };
+    }
+    async findMetadataImplementation(projectDir, route) {
+        const fullPath = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(fullPath))
+            return { hasMetadata: false, type: 'none' };
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        const has = /<Helmet\b|<title\b/i.test(content);
+        return { hasMetadata: has, type: has ? 'jsx_head' : 'none' };
+    }
+    async findCanonicalDeclaration(projectDir, route) {
+        const fullPath = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(fullPath))
+            return { hasCanonical: false, type: 'none' };
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        return { hasCanonical: /rel=["']canonical["']/i.test(content), type: 'link_jsx_tag' };
+    }
+    async findSchemaDeclaration(projectDir, route) {
+        const fullPath = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(fullPath))
+            return { hasSchema: false, typesFound: [] };
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        return { hasSchema: /application\/ld\+json/i.test(content), typesFound: ['JSON-LD'] };
+    }
+    findRobotsConfig(projectDir) {
+        const paths = ['public/robots.txt', 'robots.txt'];
+        for (const p of paths) {
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        }
+        return null;
+    }
+    findSitemapConfig(projectDir) {
+        const paths = ['public/sitemap.xml', 'sitemap.xml'];
+        for (const p of paths) {
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        }
+        return null;
+    }
+    findLlmsTxt(projectDir) {
+        const paths = ['public/llms.txt', 'llms.txt'];
+        for (const p of paths) {
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        }
+        return null;
+    }
+}

package/dist/benchmark/correlationBenchmark.d.ts

@@ -0,0 +1 @@
+export declare function runCorrelationBenchmark(): Promise<boolean>;

package/dist/benchmark/correlationBenchmark.js

@@ -0,0 +1,96 @@
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { defaultAdapterRegistry } from '../adapters/adapterRegistry.js';
+import { inspectSourceFileAST } from '../utils/astLocator.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const FIXTURES_ROOT = path.resolve(__dirname, '../../test/fixtures');
+export async function runCorrelationBenchmark() {
+    console.log('\n📊 Running Multi-Framework Correlation Accuracy Benchmark...\n');
+    const frameworksToTest = [
+        {
+            id: 'nextjs-app-router',
+            dir: 'nextjs-app',
+            expectedRoutes: ['/', '/about', '/blog/[slug]', '/sitemap.xml'],
+            testUrl: '/blog/ai-seo',
+            expectedFile: 'app/blog/[slug]/page.tsx'
+        },
+        {
+            id: 'nextjs-pages-router',
+            dir: 'nextjs-pages',
+            expectedRoutes: ['/', '/blog/[id]'],
+            testUrl: '/blog/123',
+            expectedFile: 'pages/blog/[id].tsx'
+        },
+        {
+            id: 'astro',
+            dir: 'astro-app',
+            expectedRoutes: ['/'],
+            testUrl: '/',
+            expectedFile: 'src/pages/index.astro'
+        },
+        {
+            id: 'vite-react',
+            dir: 'vite-react',
+            expectedRoutes: ['/', '/about', '/docs/:slug'],
+            testUrl: '/about',
+            expectedFile: 'src/App.tsx'
+        },
+        {
+            id: 'remix',
+            dir: 'remix-app',
+            expectedRoutes: ['/', '/features'],
+            testUrl: '/features',
+            expectedFile: 'app/routes/features.tsx'
+        },
+        {
+            id: 'sveltekit',
+            dir: 'sveltekit-app',
+            expectedRoutes: ['/'],
+            testUrl: '/',
+            expectedFile: 'src/routes/+page.svelte'
+        },
+        {
+            id: 'static-html',
+            dir: 'static-site',
+            expectedRoutes: ['/'],
+            testUrl: '/',
+            expectedFile: 'index.html'
+        }
+    ];
+    let passed = 0;
+    let total = frameworksToTest.length;
+    for (const item of frameworksToTest) {
+        const projectPath = path.join(FIXTURES_ROOT, item.dir);
+        const adapter = defaultAdapterRegistry.getAdapterForProject(projectPath);
+        if (adapter.id !== item.id) {
+            console.error(`❌ [${item.id}] Detection mismatch: got '${adapter.id}'`);
+            continue;
+        }
+        const routes = adapter.discoverRoutes(projectPath);
+        const routePaths = routes.map(r => r.routePath);
+        const missingRoutes = item.expectedRoutes.filter(er => !routePaths.includes(er));
+        if (missingRoutes.length > 0) {
+            console.error(`❌ [${item.id}] Missing expected routes: ${missingRoutes.join(', ')} (Found: ${routePaths.join(', ')})`);
+            continue;
+        }
+        const mapping = adapter.mapRouteToSource(item.testUrl, routes);
+        if (!mapping.sourceFilePath || !mapping.sourceFilePath.includes(path.basename(item.expectedFile))) {
+            console.error(`❌ [${item.id}] Source mapping error for '${item.testUrl}': expected '${item.expectedFile}', got '${mapping.sourceFilePath}'`);
+            continue;
+        }
+        // AST inspection check if typescript/tsx
+        if (mapping.sourceFilePath.endsWith('.tsx') || mapping.sourceFilePath.endsWith('.ts')) {
+            const ast = inspectSourceFileAST(path.join(projectPath, mapping.sourceFilePath));
+        }
+        console.log(`✅ [${item.id.padEnd(20)}] 100% Precision: Routes=[${routePaths.join(', ')}] -> Mapped '${item.testUrl}' to '${mapping.sourceFilePath}'`);
+        passed++;
+    }
+    const score = Math.round((passed / total) * 100);
+    console.log(`\n🎯 Benchmark Result: ${passed}/${total} frameworks verified (${score}% correlation precision).\n`);
+    return passed === total;
+}
+runCorrelationBenchmark().then(success => {
+    if (!success)
+        process.exit(1);
+});

package/dist/benchmark/invariantBenchmark.d.ts

@@ -0,0 +1 @@
+export declare function runInvariantBenchmark(): Promise<boolean>;

package/dist/benchmark/invariantBenchmark.js

@@ -0,0 +1,47 @@
+import { defaultInvariantRegistry } from '../invariants/registry.js';
+import { createProjectSnapshot, compareSnapshots } from '../utils/snapshotEngine.js';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const FIXTURES_ROOT = path.resolve(__dirname, '../../test/fixtures');
+export async function runInvariantBenchmark() {
+    console.log('\n🛡️ Running Invariant Precision & Regression Recall Benchmark...\n');
+    // Test 1: Invariant Registry Completeness
+    const allInvariants = defaultInvariantRegistry.getAll();
+    console.log(`✅ Invariant Registry loaded: ${allInvariants.length} built-in invariants`);
+    // Test 2: Invariant Evaluation
+    const testPageId = 'page_test_123';
+    const now = new Date().toISOString();
+    const titlePass = defaultInvariantRegistry.evaluateContext('INV-TITLE-PRESENT', { url: '/test', logicalPageId: testPageId, hasMetadata: true, extractedTitle: 'My Title' }, { analyzer: 'test', source: 'ast_inspection', timestamp: now, provider: 'test' });
+    const titleFail = defaultInvariantRegistry.evaluateContext('INV-TITLE-PRESENT', { url: '/test', logicalPageId: testPageId, hasMetadata: false }, { analyzer: 'test', source: 'ast_inspection', timestamp: now, provider: 'test' });
+    if (!titlePass?.satisfied || titleFail?.satisfied) {
+        console.error('❌ Title invariant evaluation failed logic test.');
+        return false;
+    }
+    console.log('✅ Title Invariant logic: Satisfied when metadata present, Failed when metadata missing.');
+    const canonicalPass = defaultInvariantRegistry.evaluateContext('INV-CANONICAL-RESOLVES', { url: '/test', logicalPageId: testPageId, hasCanonical: true, extractedCanonical: 'https://example.com/test' }, { analyzer: 'test', source: 'ast_inspection', timestamp: now, provider: 'test' });
+    const canonicalFail = defaultInvariantRegistry.evaluateContext('INV-CANONICAL-RESOLVES', { url: '/test', logicalPageId: testPageId, hasCanonical: false }, { analyzer: 'test', source: 'ast_inspection', timestamp: now, provider: 'test' });
+    if (!canonicalPass?.satisfied || canonicalFail?.satisfied) {
+        console.error('❌ Canonical invariant evaluation failed logic test.');
+        return false;
+    }
+    console.log('✅ Canonical Invariant logic: Satisfied when canonical present, Failed when canonical missing.');
+    // Test 3: Snapshot Invariant Evaluation on Next.js App
+    const nextAppPath = path.join(FIXTURES_ROOT, 'nextjs-app');
+    const snap1 = await createProjectSnapshot(nextAppPath);
+    console.log(`✅ Project Snapshot evaluation recorded ${snap1.invariants?.length || 0} invariant checks.`);
+    // Verify regression diffing
+    const report = compareSnapshots(snap1, snap1);
+    if (report.newRegressions.length !== 0) {
+        console.error('❌ Self-comparison generated false positive regressions.');
+        return false;
+    }
+    console.log(`✅ Invariant Regression Diffing: Self-comparison generated 0 regressions (Pass).`);
+    console.log('\n🎯 Invariant Benchmark: 100% Invariant Evaluation Precision Verified.\n');
+    return true;
+}
+runInvariantBenchmark().then(success => {
+    if (!success)
+        process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export declare const EXIT_CODES: {
+    PASS: number;
+    REGRESSION: number;
+    CONFIG_ERROR: number;
+    ANALYZER_FAILURE: number;
+    PARTIAL_UNKNOWN: number;
+};