seo-gravity-mcp 1.0.2 → 1.2.0

package/dist/utils/projectScanner.js

@@ -1,353 +1,21 @@
-import * as fs from 'fs';
 import * as path from 'path';
-export function detectFramework(projectDir) {
+import { defaultAdapterRegistry } from '../adapters/adapterRegistry.js';
+export function getProjectAdapter(projectDir) {
     const resolvedDir = path.resolve(projectDir);
-    const pkgPath = path.join(resolvedDir, 'package.json');
-    let pkg = {};
-    if (fs.existsSync(pkgPath)) {
-        try {
-            pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        }
-        catch {
-            // Ignored
-        }
-    }
-    const allDeps = {
-        ...(pkg.dependencies || {}),
-        ...(pkg.devDependencies || {})
-    };
-    const hasFile = (relPath) => fs.existsSync(path.join(resolvedDir, relPath));
-    const hasDir = (relPath) => {
-        const p = path.join(resolvedDir, relPath);
-        return fs.existsSync(p) && fs.statSync(p).isDirectory();
-    };
-    let framework = 'unknown';
-    let routesDir;
-    let devCommand = pkg.scripts?.dev ? 'npm run dev' : undefined;
-    let defaultDevPort = 3000;
-    // Next.js App Router vs Pages Router
-    if (allDeps['next']) {
-        if (hasDir('app') || hasDir('src/app')) {
-            framework = 'nextjs-app-router';
-            routesDir = hasDir('app') ? 'app' : 'src/app';
-        }
-        else {
-            framework = 'nextjs-pages-router';
-            routesDir = hasDir('pages') ? 'pages' : 'src/pages';
-        }
-        defaultDevPort = 3000;
-    }
-    // Astro
-    else if (allDeps['astro'] || hasFile('astro.config.mjs') || hasFile('astro.config.ts')) {
-        framework = 'astro';
-        routesDir = hasDir('src/pages') ? 'src/pages' : 'pages';
-        defaultDevPort = 4321;
-    }
-    // Remix
-    else if (allDeps['@remix-run/react'] || allDeps['@remix-run/node']) {
-        framework = 'remix';
-        routesDir = hasDir('app/routes') ? 'app/routes' : 'routes';
-        defaultDevPort = 3000;
-    }
-    // SvelteKit
-    else if (allDeps['@sveltejs/kit']) {
-        framework = 'sveltekit';
-        routesDir = hasDir('src/routes') ? 'src/routes' : 'routes';
-        defaultDevPort = 5173;
-    }
-    // Nuxt
-    else if (allDeps['nuxt'] || allDeps['nuxt3']) {
-        framework = 'nuxt';
-        routesDir = hasDir('pages') ? 'pages' : 'src/pages';
-        defaultDevPort = 3000;
-    }
-    // Vite / React SPA
-    else if (allDeps['vite'] || allDeps['react']) {
-        framework = 'vite-react';
-        routesDir = hasDir('src') ? 'src' : '.';
-        defaultDevPort = 5173;
-    }
-    // Static HTML
-    else if (hasFile('index.html')) {
-        framework = 'static-html';
-        routesDir = '.';
-        defaultDevPort = 8080;
-    }
-    // Detect sitemap, robots, llms.txt
-    const hasSitemapConfig = hasFile('public/sitemap.xml') ||
-        hasFile('sitemap.xml') ||
-        hasFile('app/sitemap.ts') ||
-        hasFile('app/sitemap.js') ||
-        hasFile('src/app/sitemap.ts') ||
-        hasFile('src/app/sitemap.js') ||
-        hasFile('src/pages/sitemap.xml.ts');
-    const hasRobotsConfig = hasFile('public/robots.txt') ||
-        hasFile('robots.txt') ||
-        hasFile('app/robots.ts') ||
-        hasFile('app/robots.js') ||
-        hasFile('src/app/robots.ts') ||
-        hasFile('src/app/robots.js');
-    const hasLlmsTxt = hasFile('public/llms.txt') ||
-        hasFile('llms.txt') ||
-        hasFile('public/llms-full.txt') ||
-        hasFile('llms-full.txt');
-    const hasTypeScript = hasFile('tsconfig.json') ||
-        Boolean(allDeps['typescript']);
-    // Package manager detection
-    let packageManager = 'npm';
-    if (hasFile('pnpm-lock.yaml'))
-        packageManager = 'pnpm';
-    else if (hasFile('yarn.lock'))
-        packageManager = 'yarn';
-    else if (hasFile('bun.lockb'))
-        packageManager = 'bun';
-    return {
-        framework,
-        name: pkg.name || path.basename(resolvedDir),
-        version: pkg.version,
-        packageManager,
-        hasTypeScript,
-        hasSitemapConfig,
-        hasRobotsConfig,
-        hasLlmsTxt,
-        rootDir: resolvedDir,
-        routesDir,
-        devCommand,
-        defaultDevPort
-    };
+    return defaultAdapterRegistry.getAdapterForProject(resolvedDir);
 }
-export function discoverRoutes(projectDir, frameworkInfo) {
+export function detectFramework(projectDir) {
     const resolvedDir = path.resolve(projectDir);
-    const info = frameworkInfo || detectFramework(resolvedDir);
-    const discovered = [];
-    if (!info.routesDir)
-        return discovered;
-    const fullRoutesDir = path.join(resolvedDir, info.routesDir);
-    if (!fs.existsSync(fullRoutesDir))
-        return discovered;
-    const readRouteFileContent = (relFile) => {
-        try {
-            const fullPath = path.join(resolvedDir, relFile);
-            const content = fs.readFileSync(fullPath, 'utf-8');
-            return {
-                hasMetadataExport: /export\s+const\s+metadata\b/.test(content),
-                hasGenerateMetadata: /export\s+(async\s+)?function\s+generateMetadata\b/.test(content),
-                hasSchemaMarkup: /application\/ld\+json/.test(content) || /schema\.org/.test(content),
-                hasHeadComponent: /<Head\b|<Helmet\b|astro:head|<meta\b|<title\b/.test(content),
-                isClientComponent: /['"]use client['"]/.test(content)
-            };
-        }
-        catch {
-            return {
-                hasMetadataExport: false,
-                hasGenerateMetadata: false,
-                hasSchemaMarkup: false,
-                hasHeadComponent: false,
-                isClientComponent: false
-            };
-        }
-    };
-    // Next.js App Router Scanner
-    if (info.framework === 'nextjs-app-router') {
-        const scanAppDir = (currentDir, routePrefix) => {
-            const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-            for (const entry of entries) {
-                const entryPath = path.join(currentDir, entry.name);
-                if (entry.isDirectory()) {
-                    // Ignore route groups like (marketing) in path
-                    const segment = entry.name.startsWith('(') && entry.name.endsWith(')') ? '' : entry.name;
-                    const nextPrefix = segment ? (routePrefix === '/' ? `/${segment}` : `${routePrefix}/${segment}`) : routePrefix;
-                    scanAppDir(entryPath, nextPrefix);
-                }
-                else if (entry.isFile()) {
-                    if (/^page\.(tsx|jsx|js|ts)$/.test(entry.name)) {
-                        const relFile = path.relative(resolvedDir, entryPath).replace(/\\/g, '/');
-                        const routePath = routePrefix === '' ? '/' : routePrefix;
-                        const dynamicParams = extractDynamicParams(routePath);
-                        const meta = readRouteFileContent(relFile);
-                        discovered.push({
-                            routePath,
-                            sourceFilePath: relFile,
-                            isDynamic: dynamicParams.length > 0,
-                            dynamicParams,
-                            routeType: 'page',
-                            ...meta
-                        });
-                    }
-                    else if (/^sitemap\.(ts|js|xml)$/.test(entry.name)) {
-                        const relFile = path.relative(resolvedDir, entryPath).replace(/\\/g, '/');
-                        discovered.push({
-                            routePath: '/sitemap.xml',
-                            sourceFilePath: relFile,
-                            isDynamic: false,
-                            dynamicParams: [],
-                            routeType: 'sitemap',
-                            ...readRouteFileContent(relFile)
-                        });
-                    }
-                    else if (/^robots\.(ts|js|txt)$/.test(entry.name)) {
-                        const relFile = path.relative(resolvedDir, entryPath).replace(/\\/g, '/');
-                        discovered.push({
-                            routePath: '/robots.txt',
-                            sourceFilePath: relFile,
-                            isDynamic: false,
-                            dynamicParams: [],
-                            routeType: 'robots',
-                            ...readRouteFileContent(relFile)
-                        });
-                    }
-                }
-            }
-        };
-        scanAppDir(fullRoutesDir, '/');
-    }
-    // Astro Scanner
-    else if (info.framework === 'astro') {
-        const scanAstroDir = (currentDir, routePrefix) => {
-            const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-            for (const entry of entries) {
-                const entryPath = path.join(currentDir, entry.name);
-                if (entry.isDirectory()) {
-                    const nextPrefix = routePrefix === '/' ? `/${entry.name}` : `${routePrefix}/${entry.name}`;
-                    scanAstroDir(entryPath, nextPrefix);
-                }
-                else if (entry.isFile() && (entry.name.endsWith('.astro') || entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) {
-                    const baseName = entry.name.replace(/\.(astro|md|mdx)$/, '');
-                    let routePath = routePrefix;
-                    if (baseName !== 'index') {
-                        routePath = routePrefix === '/' ? `/${baseName}` : `${routePrefix}/${baseName}`;
-                    }
-                    if (routePath === '')
-                        routePath = '/';
-                    const relFile = path.relative(resolvedDir, entryPath).replace(/\\/g, '/');
-                    const dynamicParams = extractDynamicParams(routePath);
-                    const meta = readRouteFileContent(relFile);
-                    discovered.push({
-                        routePath,
-                        sourceFilePath: relFile,
-                        isDynamic: dynamicParams.length > 0,
-                        dynamicParams,
-                        routeType: 'page',
-                        ...meta
-                    });
-                }
-            }
-        };
-        scanAstroDir(fullRoutesDir, '/');
-    }
-    // Pages Router / Nuxt / SvelteKit / Static
-    else {
-        const scanGenericDir = (currentDir, routePrefix) => {
-            const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-            for (const entry of entries) {
-                const entryPath = path.join(currentDir, entry.name);
-                if (entry.isDirectory()) {
-                    if (['node_modules', '.git', '.next', 'dist', 'build'].includes(entry.name))
-                        continue;
-                    const nextPrefix = routePrefix === '/' ? `/${entry.name}` : `${routePrefix}/${entry.name}`;
-                    scanGenericDir(entryPath, nextPrefix);
-                }
-                else if (entry.isFile() && /\.(tsx|jsx|js|ts|vue|svelte|html)$/.test(entry.name)) {
-                    const baseName = entry.name.replace(/\.(tsx|jsx|js|ts|vue|svelte|html)$/, '');
-                    let routePath = routePrefix;
-                    if (baseName !== 'index' && baseName !== 'page') {
-                        routePath = routePrefix === '/' ? `/${baseName}` : `${routePrefix}/${baseName}`;
-                    }
-                    if (routePath === '')
-                        routePath = '/';
-                    const relFile = path.relative(resolvedDir, entryPath).replace(/\\/g, '/');
-                    const dynamicParams = extractDynamicParams(routePath);
-                    const meta = readRouteFileContent(relFile);
-                    discovered.push({
-                        routePath,
-                        sourceFilePath: relFile,
-                        isDynamic: dynamicParams.length > 0,
-                        dynamicParams,
-                        routeType: 'page',
-                        ...meta
-                    });
-                }
-            }
-        };
-        scanGenericDir(fullRoutesDir, '/');
-    }
-    return discovered;
+    const adapter = defaultAdapterRegistry.getAdapterForProject(resolvedDir);
+    return adapter.getProjectInfo(resolvedDir);
 }
-function extractDynamicParams(routePath) {
-    const params = [];
-    const matches = routePath.match(/\[\.{0,3}([a-zA-Z0-9_-]+)\]/g);
-    if (matches) {
-        for (const m of matches) {
-            params.push(m.replace(/[\[\].]/g, ''));
-        }
-    }
-    return params;
+export function discoverRoutes(projectDir, _frameworkInfo) {
+    const resolvedDir = path.resolve(projectDir);
+    const adapter = defaultAdapterRegistry.getAdapterForProject(resolvedDir);
+    return adapter.discoverRoutes(resolvedDir);
 }
-export function mapUrlToRouteSource(targetUrl, discoveredRoutes) {
-    let urlPath = targetUrl;
-    try {
-        if (targetUrl.startsWith('http')) {
-            urlPath = new URL(targetUrl).pathname;
-        }
-    }
-    catch {
-        urlPath = targetUrl;
-    }
-    urlPath = urlPath.replace(/\/$/, '') || '/';
-    // 1. Exact Match
-    for (const r of discoveredRoutes) {
-        const cleanRoute = r.routePath.replace(/\/$/, '') || '/';
-        if (cleanRoute === urlPath) {
-            return {
-                urlPath,
-                matchedRoute: r,
-                sourceFilePath: r.sourceFilePath,
-                confidence: 1.0,
-                resolutionMethod: 'exact_match'
-            };
-        }
-    }
-    // 2. Dynamic Pattern Match (e.g. /blog/my-post -> /blog/[slug])
-    for (const r of discoveredRoutes) {
-        if (!r.isDynamic)
-            continue;
-        const regexStr = '^' + r.routePath
-            .replace(/\[\.\.\.([a-zA-Z0-9_-]+)\]/g, '.*')
-            .replace(/\[([a-zA-Z0-9_-]+)\]/g, '[^/]+') + '$';
-        try {
-            const reg = new RegExp(regexStr);
-            if (reg.test(urlPath)) {
-                return {
-                    urlPath,
-                    matchedRoute: r,
-                    sourceFilePath: r.sourceFilePath,
-                    confidence: 0.9,
-                    resolutionMethod: 'pattern_match'
-                };
-            }
-        }
-        catch {
-            // Ignored
-        }
-    }
-    // 3. Fallback Heuristic
-    const segments = urlPath.split('/').filter(Boolean);
-    if (segments.length > 0) {
-        const parentSegment = `/${segments[0]}`;
-        const parentRoute = discoveredRoutes.find(r => r.routePath.startsWith(parentSegment));
-        if (parentRoute) {
-            return {
-                urlPath,
-                matchedRoute: parentRoute,
-                sourceFilePath: parentRoute.sourceFilePath,
-                confidence: 0.6,
-                resolutionMethod: 'fallback_heuristic'
-            };
-        }
-    }
-    return {
-        urlPath,
-        confidence: 0.0,
-        resolutionMethod: 'unmapped'
-    };
+export function mapUrlToRouteSource(targetUrl, discoveredRoutes, projectDir = '.') {
+    const resolvedDir = path.resolve(projectDir);
+    const adapter = defaultAdapterRegistry.getAdapterForProject(resolvedDir);
+    return adapter.mapRouteToSource(targetUrl, discoveredRoutes);
 }

package/dist/utils/sarifExporter.d.ts

@@ -0,0 +1,64 @@
+import { Finding } from '../types/findings.js';
+export interface SarifPhysicalLocation {
+    artifactLocation: {
+        uri: string;
+        uriBaseId?: string;
+    };
+    region?: {
+        startLine: number;
+        startColumn?: number;
+        endLine?: number;
+        endColumn?: number;
+        snippet?: {
+            text: string;
+        };
+    };
+}
+export interface SarifResult {
+    ruleId: string;
+    ruleIndex?: number;
+    level: 'error' | 'warning' | 'note' | 'none';
+    message: {
+        text: string;
+    };
+    locations?: Array<{
+        physicalLocation: SarifPhysicalLocation;
+    }>;
+    fixes?: Array<{
+        description: {
+            text: string;
+        };
+    }>;
+}
+export interface SarifRule {
+    id: string;
+    name: string;
+    shortDescription: {
+        text: string;
+    };
+    fullDescription?: {
+        text: string;
+    };
+    help?: {
+        text: string;
+    };
+    defaultConfiguration: {
+        level: 'error' | 'warning' | 'note';
+    };
+}
+export interface SarifReport {
+    $schema: string;
+    version: string;
+    runs: Array<{
+        tool: {
+            driver: {
+                name: string;
+                version: string;
+                informationUri: string;
+                rules: SarifRule[];
+            };
+        };
+        results: SarifResult[];
+    }>;
+}
+export declare function exportFindingsToSarif(findings: Finding[], projectRootDir?: string, toolVersion?: string): SarifReport;

package/dist/utils/sarifExporter.js

@@ -0,0 +1,81 @@
+export function exportFindingsToSarif(findings, projectRootDir = '.', toolVersion = '1.2.0') {
+    const ruleMap = new Map();
+    const results = [];
+    const mapSeverityToSarifLevel = (sev) => {
+        switch (sev) {
+            case 'critical':
+            case 'high':
+                return 'error';
+            case 'medium':
+                return 'warning';
+            case 'low':
+            case 'info':
+            default:
+                return 'note';
+        }
+    };
+    for (const f of findings) {
+        if (!ruleMap.has(f.id)) {
+            ruleMap.set(f.id, {
+                id: f.id,
+                name: f.title.replace(/[^a-zA-Z0-9]/g, '_'),
+                shortDescription: { text: f.title },
+                fullDescription: { text: f.evidence },
+                help: { text: `${f.recommendation} (Expected Impact: ${f.expectedImpact})` },
+                defaultConfiguration: {
+                    level: mapSeverityToSarifLevel(f.severity)
+                }
+            });
+        }
+        const relPath = f.sourceLocation?.filePath || (f.affectedUrl.startsWith('/') ? f.affectedUrl.slice(1) : f.affectedUrl);
+        const startLine = f.sourceRange?.startLine || f.sourceLocation?.startLine || f.sourceLocation?.line || 1;
+        const endLine = f.sourceRange?.endLine || f.sourceLocation?.endLine || startLine;
+        results.push({
+            ruleId: f.id,
+            level: mapSeverityToSarifLevel(f.severity),
+            message: {
+                text: `${f.title}: ${f.evidence}. ${f.recommendation}`
+            },
+            locations: [
+                {
+                    physicalLocation: {
+                        artifactLocation: {
+                            uri: relPath.replace(/\\/g, '/')
+                        },
+                        region: {
+                            startLine,
+                            endLine,
+                            snippet: f.sourceRange?.snippet ? { text: f.sourceRange.snippet } : undefined
+                        }
+                    }
+                }
+            ],
+            fixes: f.suggestedFix?.snippet
+                ? [
+                    {
+                        description: {
+                            text: `${f.suggestedFix.explanation}\n\`\`\`\n${f.suggestedFix.snippet}\n\`\`\``
+                        }
+                    }
+                ]
+                : undefined
+        });
+    }
+    return {
+        $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'SEO Gravity',
+                        version: toolVersion,
+                        informationUri: 'https://github.com/thedevbob005/seo-gravity-mcp',
+                        rules: Array.from(ruleMap.values())
+                    }
+                },
+                results
+            }
+        ]
+    };
+}

package/dist/utils/snapshotEngine.d.ts

@@ -1,9 +1,11 @@
-import { ProjectSnapshot, RegressionReport } from '../types/findings.js';
+import { ProjectSnapshot, RegressionReport, GitMetadata } from '../types/findings.js';
 export interface CreateSnapshotOptions {
     baseUrl?: string;
     maxCrawlDepth?: number;
     maxPagesToAudit?: number;
     includeCrawlGraph?: boolean;
 }
+export declare function computeLogicalPageId(urlOrPath: 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;