seo-gravity-mcp 1.0.2 → 1.2.0

package/dist/server/types.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface ServerOptions {
+    name?: string;
+    version?: string;
+    transport?: 'stdio';
+}
+export type ToolRegistrationFn = (server: McpServer) => void;

package/dist/server/types.js

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

package/dist/test.js

@@ -3,163 +3,133 @@ import { fileURLToPath } from 'url';
 // Core Tool Imports
 import { auditOnPage } from './tools/onpage.js';
 import { auditGeoAiReadiness } from './tools/geo.js';
-import { clusterKeywords, classifySearchIntent } from './tools/keywords.js';
-import { generateSchemaMarkup, validateSchema } from './tools/schema.js';
-// New v1.0.2 Agent Orchestration Imports
-import { auditProject, diagnoseSeo, prioritizeFindings, generateFixPlan, createSnapshotTool, checkRegression } from './tools/orchestration.js';
-import { detectFramework, discoverRoutes, mapUrlToRouteSource } from './utils/projectScanner.js';
-import { CrawlGraphBuilder } from './utils/crawlGraph.js';
-import { calculatePriorityScore } from './utils/findingEngine.js';
+// Modular Server & Agent Orchestration
+import { createMcpServer } from './server/server.js';
+import { TOOLS } from './server/registry.js';
+import { auditProject, prioritizeFindings, createSnapshotTool, checkRegression } from './tools/orchestration.js';
+import { defaultAdapterRegistry } from './adapters/adapterRegistry.js';
+import { inspectSourceFileAST } from './utils/astLocator.js';
+import { defaultCacheManager } from './utils/cacheManager.js';
+import { defaultProviderRegistry } from './providers/providerRegistry.js';
+import { detectOpportunities } from './utils/opportunityEngine.js';
+import { exportFindingsToSarif } from './utils/sarifExporter.js';
+import { defaultInvariantRegistry } from './invariants/registry.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const FIXTURES_DIR = path.resolve(__dirname, '../test/fixtures');
 async function runTests() {
-    console.log('🧪 Starting SEO Gravity MCP v1.0.2 Comprehensive Test Suite...\n');
+    console.log('🧪 Starting SEO Gravity MCP v1.2.0 (Engineering Infrastructure) Test Suite...\n');
     // -------------------------------------------------------------
-    // Test 1: On-Page Audit
+    // Test 1: Modular Server & 35 Tool Catalog
     // -------------------------------------------------------------
-    console.log('1️⃣ Testing On-Page Audit...');
+    console.log('1️⃣ Testing Modular Server Architecture...');
+    const server = createMcpServer({ name: 'seo-gravity-mcp', version: '1.2.0' });
+    console.log(`   ✅ Server Initialized: ${TOOLS.length} tools registered across all 8 architectural layers.`);
+    // -------------------------------------------------------------
+    // Test 2: On-Page & GEO Evidence Analysis
+    // -------------------------------------------------------------
+    console.log('\n2️⃣ Testing On-Page & GEO Evidence Analysis...');
     const sampleHtml = `
     <!DOCTYPE html>
     <html>
       <head>
-        <title>Best Project Management Software in 2026 - Top 10 Picks</title>
-        <meta name="description" content="Discover the best project management software tools for agile teams in 2026. Compare pricing, features, and user ratings. Start free today.">
-        <link rel="canonical" href="https://example.com/best-project-management-software">
+        <title>Best Project Management Software in 2026</title>
+        <meta name="description" content="Compare the best agile tools for engineering teams.">
+        <link rel="canonical" href="https://example.com/best-tools">
       </head>
       <body>
-        <h1>Best Project Management Software for Teams</h1>
-        <h2>1. Why Project Management Tools Matter</h2>
-        <p>Project management software refers to digital platforms designed to plan, organize, and allocate resources efficiently across engineering and marketing teams.</p>
-        <h2>2. Top Features Comparison</h2>
-        <p>Key features include Gantt charts, real-time collaboration, and API integrations.</p>
-        <img src="hero.png" alt="Project management dashboard preview">
-        <a href="/pricing">View Pricing</a>
-        <a href="https://wikipedia.org/wiki/Project_management">Learn more on Wikipedia</a>
+        <h1>Best Project Management Software</h1>
+        <p>Project management software refers to digital platforms designed to plan and organize workflows.</p>
+        <a href="/pricing">Pricing</a>
       </body>
     </html>
   `;
     const onpage = await auditOnPage(sampleHtml, 'project management software');
-    console.log(`   ✅ On-Page Score: ${onpage.overallScore}/100 | Title: ${onpage.titleAudit.status} | H1s: ${onpage.headingsAudit.h1Count}`);
+    const geo = await auditGeoAiReadiness(sampleHtml, 'best project management software');
+    console.log(`   ✅ On-Page Score: ${onpage.overallScore}/100 | Title: ${onpage.titleAudit.status}`);
+    console.log(`   ✅ GEO AI Retrieval Signals: Direct Answer=${geo.aiRetrievalSignals?.directEntityDefinition}`);
     // -------------------------------------------------------------
-    // Test 2: GEO / AEO Readiness with Evidence Tiers
+    // Test 3: Framework Adapters & Multi-Framework Route Discovery
     // -------------------------------------------------------------
-    console.log('\n2️⃣ Testing GEO & AI Search Readiness Audit (with Evidence Tiers)...');
-    const geo = await auditGeoAiReadiness(sampleHtml, 'best project management software');
-    console.log(`   ✅ GEO Score: ${geo.overallGeoScore}/100 | Citation: ${geo.citationLikelihood} | Confidence: ${geo.confidence}`);
-    console.log(`   ✅ AI Retrieval Signals: Direct Answer=${geo.aiRetrievalSignals?.directEntityDefinition}, Stats=${geo.aiRetrievalSignals?.factualDataAndStats}`);
-    // -------------------------------------------------------------
-    // Test 3: Schema Generation & Validation
-    // -------------------------------------------------------------
-    console.log('\n3️⃣ Testing Schema.org JSON-LD Generation & Validation...');
-    const schema = generateSchemaMarkup('FAQPage', {
-        items: [
-            { question: 'What is project management software?', answer: 'It is a platform to coordinate team tasks and roadmaps.' },
-            { question: 'Is it free to start?', answer: 'Yes, free tiers are available for small teams.' }
-        ]
-    });
-    const val = await validateSchema(schema.jsonLdScript.replace(/<script[^>]*>/, '').replace(/<\/script>/, ''));
-    console.log(`   ✅ Schema Validated (${val.schemasDetectedCount} detected, Valid: ${val.schemas[0]?.isValid})`);
-    // -------------------------------------------------------------
-    // Test 4: Keyword Clustering & Intent Classification
-    // -------------------------------------------------------------
-    console.log('\n4️⃣ Testing Keyword Clustering & Search Intent Classification...');
-    const keywords = [
-        'best running shoes',
-        'buy running shoes online',
-        'how to choose running shoes',
-        'running shoes for flat feet',
-        'running shoes review',
-        'running shoes sale discount'
-    ];
-    const clusters = clusterKeywords(keywords);
-    const intents = classifySearchIntent(keywords);
-    console.log(`   ✅ Clustered ${keywords.length} keywords into ${clusters.clusterCount} cluster(s)`);
-    console.log(`   ✅ Intent: "${keywords[1]}" -> ${intents[1].intent} (${(intents[1].confidenceScore * 100).toFixed(0)}%)`);
-    // -------------------------------------------------------------
-    // Test 5: Priority Scoring Algorithm
-    // -------------------------------------------------------------
-    console.log('\n5️⃣ Testing Finding Priority Scoring Algorithm...');
-    const p1 = calculatePriorityScore('critical', 1.0, 'trivial', 'site_wide');
-    const p2 = calculatePriorityScore('low', 0.8, 'high', 'isolated');
-    console.log(`   ✅ Critical Site-wide Issue Priority: ${p1.priorityScore} (Tier: ${p1.priorityTier})`);
-    console.log(`   ✅ Isolated Low-Severity Issue Priority: ${p2.priorityScore} (Tier: ${p2.priorityTier})`);
-    // -------------------------------------------------------------
-    // Test 6: Project Framework Detection & Route Discovery
-    // -------------------------------------------------------------
-    console.log('\n6️⃣ Testing Framework Scanner & Route Discovery on Fixtures...');
+    console.log('\n3️⃣ Testing Framework Adapters (Next.js, Astro, Remix, Vite, SvelteKit)...');
     const nextAppPath = path.join(FIXTURES_DIR, 'nextjs-app');
-    const nextFramework = detectFramework(nextAppPath);
-    const nextRoutes = discoverRoutes(nextAppPath, nextFramework);
-    console.log(`   ✅ Next.js Fixture: Framework=${nextFramework.framework}, TypeScript=${nextFramework.hasTypeScript}, Sitemap=${nextFramework.hasSitemapConfig}`);
-    console.log(`   ✅ Discovered ${nextRoutes.length} route(s): ${nextRoutes.map(r => r.routePath).join(', ')}`);
-    const astroAppPath = path.join(FIXTURES_DIR, 'astro-app');
-    const astroFramework = detectFramework(astroAppPath);
-    const astroRoutes = discoverRoutes(astroAppPath, astroFramework);
-    console.log(`   ✅ Astro Fixture: Framework=${astroFramework.framework}, Routes=${astroRoutes.map(r => r.routePath).join(', ')}`);
-    // -------------------------------------------------------------
-    // Test 7: Source-to-URL Mapping
-    // -------------------------------------------------------------
-    console.log('\n7️⃣ Testing Source-to-URL Correlation...');
-    const map1 = mapUrlToRouteSource('/blog/ai-productivity-2026', nextRoutes);
-    const map2 = mapUrlToRouteSource('/about', nextRoutes);
-    console.log(`   ✅ URL '/blog/ai-productivity-2026' mapped to -> ${map1.sourceFilePath} (Method: ${map1.resolutionMethod}, Conf: ${map1.confidence})`);
-    console.log(`   ✅ URL '/about' mapped to -> ${map2.sourceFilePath} (Method: ${map2.resolutionMethod}, Conf: ${map2.confidence})`);
-    // -------------------------------------------------------------
-    // Test 8: Crawl Graph Analysis & PageRank
-    // -------------------------------------------------------------
-    console.log('\n8️⃣ Testing Crawl Graph Analysis...');
-    const brokenPath = path.join(FIXTURES_DIR, 'broken-site/index.html');
-    const crawlBuilder = new CrawlGraphBuilder(brokenPath);
-    const crawlGraph = await crawlBuilder.buildGraph();
-    console.log(`   ✅ Crawl Graph Built: ${crawlGraph.totalNodes} node(s), ${crawlGraph.totalEdges} edge(s), Max Depth: ${crawlGraph.maxClickDepth}`);
-    // -------------------------------------------------------------
-    // Test 9: Flagship Project Audit (seo_project_audit)
-    // -------------------------------------------------------------
-    console.log('\n9️⃣ Testing Flagship seo_project_audit Tool...');
-    const auditResult = await auditProject(nextAppPath);
-    console.log(`   ✅ Project Audit Completed:`);
-    console.log(`      - Overall Health Score: ${auditResult.scores.overallHealth}/100 (Confidence: ${auditResult.scores.overallConfidence})`);
-    console.log(`      - Technical: ${auditResult.scores.technical.score}/100 (${auditResult.scores.technical.state})`);
-    console.log(`      - Content: ${auditResult.scores.content.score}/100 (${auditResult.scores.content.state})`);
-    console.log(`      - AI Readiness: ${auditResult.scores.aiReadiness.score}/100 (${auditResult.scores.aiReadiness.state})`);
-    console.log(`      - Total Findings Detected: ${auditResult.totalFindingsCount}`);
-    console.log(`      - Immediate Action: ${auditResult.recommendedImmediateAction}`);
-    // -------------------------------------------------------------
-    // Test 10: Deep Root-Cause Diagnosis (seo_diagnose)
-    // -------------------------------------------------------------
-    console.log('\n🔟 Testing Deep Diagnostic (seo_diagnose)...');
-    const diagResult = await diagnoseSeo(nextAppPath, '/about');
-    console.log(`   ✅ Diagnosis for '/about':`);
-    console.log(`      - Matched File: ${diagResult.sourceLocation?.filePath}`);
-    console.log(`      - Issues Detected: ${diagResult.detectedIssues.length}`);
-    if (diagResult.suggestedFixBlueprints.length > 0) {
-        console.log(`      - Suggested Fix Blueprint: ${diagResult.suggestedFixBlueprints[0].title}`);
-    }
-    // -------------------------------------------------------------
-    // Test 11: Sprint Prioritization (seo_prioritize)
-    // -------------------------------------------------------------
-    console.log('\n1️⃣1️⃣ Testing Finding Prioritization (seo_prioritize)...');
-    const sprintResult = await prioritizeFindings(nextAppPath);
-    console.log(`   ✅ Prioritization Sprints:`);
-    console.log(`      - Quick Wins: ${sprintResult.sprints.quickWins.length} items`);
-    console.log(`      - Critical Blockers: ${sprintResult.sprints.criticalBlockers.length} items`);
-    console.log(`      - Projected Score After Quick Wins: ${sprintResult.projectedScoreImprovement.projectedScoreAfterQuickWins}/100`);
-    // -------------------------------------------------------------
-    // Test 12: Fix Plan Generation (seo_fix_plan)
-    // -------------------------------------------------------------
-    console.log('\n1️⃣2️⃣ Testing Fix Plan Generation (seo_fix_plan)...');
-    const fixPlan = await generateFixPlan(nextAppPath);
-    console.log(`   ✅ Fix Plan Generated: ${fixPlan.totalSteps} remediation step(s) ready for AI coding execution.`);
-    // -------------------------------------------------------------
-    // Test 13: Snapshot Creation, Diffing & Regression Checks
-    // -------------------------------------------------------------
-    console.log('\n1️⃣3️⃣ Testing Snapshot Creation & Regression Verification (seo_snapshot_create & seo_regression_check)...');
-    const baselineSnap = await createSnapshotTool(nextAppPath);
-    console.log(`   ✅ Baseline Snapshot Created: ID=${baselineSnap.snapshot.snapshotId}, Score=${baselineSnap.snapshot.scores.overallHealth}/100`);
-    const regCheck = await checkRegression(nextAppPath, baselineSnap.snapshot);
-    console.log(`   ✅ Regression Check: ${regCheck.verdict} (Status: ${regCheck.regressionReport.status})`);
-    console.log('\n🎉 ALL 13 TEST SUITES (CORE + v1.0.2 ORCHESTRATION) PASSED CLEANLY!\n');
+    const nextAdapter = defaultAdapterRegistry.getAdapterForProject(nextAppPath);
+    const nextRoutes = nextAdapter.discoverRoutes(nextAppPath);
+    console.log(`   ✅ Next.js Adapter: ${nextAdapter.name} -> Discovered ${nextRoutes.length} route(s)`);
+    const pagesAppPath = path.join(FIXTURES_DIR, 'nextjs-pages');
+    const pagesAdapter = defaultAdapterRegistry.getAdapterForProject(pagesAppPath);
+    const pagesRoutes = pagesAdapter.discoverRoutes(pagesAppPath);
+    console.log(`   ✅ Next.js Pages Adapter: ${pagesAdapter.name} -> Discovered ${pagesRoutes.length} route(s)`);
+    const viteAppPath = path.join(FIXTURES_DIR, 'vite-react');
+    const viteAdapter = defaultAdapterRegistry.getAdapterForProject(viteAppPath);
+    const viteRoutes = viteAdapter.discoverRoutes(viteAppPath);
+    console.log(`   ✅ Vite React Adapter: ${viteAdapter.name} -> Discovered ${viteRoutes.length} route(s)`);
+    const remixAppPath = path.join(FIXTURES_DIR, 'remix-app');
+    const remixAdapter = defaultAdapterRegistry.getAdapterForProject(remixAppPath);
+    const remixRoutes = remixAdapter.discoverRoutes(remixAppPath);
+    console.log(`   ✅ Remix Adapter: ${remixAdapter.name} -> Discovered ${remixRoutes.length} route(s)`);
+    const svelteAppPath = path.join(FIXTURES_DIR, 'sveltekit-app');
+    const svelteAdapter = defaultAdapterRegistry.getAdapterForProject(svelteAppPath);
+    const svelteRoutes = svelteAdapter.discoverRoutes(svelteAppPath);
+    console.log(`   ✅ SvelteKit Adapter: ${svelteAdapter.name} -> Discovered ${svelteRoutes.length} route(s)`);
+    // -------------------------------------------------------------
+    // Test 4: Deep AST & Line-Range Correlation Engine
+    // -------------------------------------------------------------
+    console.log('\n4️⃣ Testing AST Inspection & Line-Range Locator...');
+    const homePageFile = path.join(nextAppPath, 'app/page.tsx');
+    const astResult = inspectSourceFileAST(homePageFile);
+    console.log(`   ✅ AST Analysis for app/page.tsx:`);
+    console.log(`      - Has Metadata Export: ${astResult.hasMetadataExport} (Lines ${astResult.metadataRange?.startLine}-${astResult.metadataRange?.endLine})`);
+    console.log(`      - Title Extracted: "${astResult.extractedTitle}"`);
+    console.log(`      - Canonical Declared: ${astResult.hasCanonicalDeclaration} ("${astResult.extractedCanonical}")`);
+    // -------------------------------------------------------------
+    // Test 5: Formal Invariant Registry & Evaluation
+    // -------------------------------------------------------------
+    console.log('\n5️⃣ Testing Formal Invariant Registry...');
+    const allInvariants = defaultInvariantRegistry.getAll();
+    console.log(`   ✅ Loaded Invariants: ${allInvariants.length} formal rules (${allInvariants.map(i => i.id).join(', ')})`);
+    const snapResult = await createSnapshotTool(nextAppPath);
+    console.log(`   ✅ Snapshot ID: ${snapResult.snapshot.snapshotId}`);
+    console.log(`   ✅ Formal Invariants Evaluated: ${snapResult.snapshot.invariants?.length || 0} invariant check(s) recorded`);
+    const regCheck = await checkRegression(nextAppPath, snapResult.snapshot);
+    console.log(`   ✅ Invariant Regression Check: ${regCheck.verdict}`);
+    // -------------------------------------------------------------
+    // Test 6: SARIF v2.1.0 Exporter
+    // -------------------------------------------------------------
+    console.log('\n6️⃣ Testing SARIF v2.1.0 Exporter for CI/CD...');
+    const sarif = exportFindingsToSarif(snapResult.snapshot.findings, nextAppPath);
+    console.log(`   ✅ SARIF Report Generated: Version ${sarif.version}, Tool: ${sarif.runs[0].tool.driver.name}, Rules: ${sarif.runs[0].tool.driver.rules.length}, Results: ${sarif.runs[0].results.length}`);
+    // -------------------------------------------------------------
+    // Test 7: Cache Manager with Provenance
+    // -------------------------------------------------------------
+    console.log('\n7️⃣ Testing Content-Hash Cache Manager with Provenance...');
+    const cacheKey = defaultCacheManager.computeKey('test_ast', { file: 'page.tsx', size: 500 });
+    defaultCacheManager.set(cacheKey, { parsed: true }, 10000, 'typescript_ast');
+    const cachedVal = defaultCacheManager.getWithMetadata(cacheKey);
+    console.log(`   ✅ Cache Provenance: Provider=${cachedVal?.metadata.provider}, Age=${cachedVal?.metadata.ageMs}ms, Key=${cachedVal?.metadata.key}`);
+    // -------------------------------------------------------------
+    // Test 8: Pluggable Provider Abstraction
+    // -------------------------------------------------------------
+    console.log('\n8️⃣ Testing Pluggable Provider Abstraction...');
+    const serpProv = defaultProviderRegistry.getSerpProvider();
+    const speedProv = defaultProviderRegistry.getPageSpeedProvider();
+    console.log(`   ✅ Default SERP Provider: ${serpProv.name} (Free: ${serpProv.isFree})`);
+    console.log(`   ✅ Default PageSpeed Provider: ${speedProv.name}`);
+    // -------------------------------------------------------------
+    // Test 9: Opportunity Engine
+    // -------------------------------------------------------------
+    console.log('\n9️⃣ Testing Strategic Opportunity Engine...');
+    const opps = await detectOpportunities(nextAppPath, ['saas pricing calculator', 'agile workflows']);
+    console.log(`   ✅ Opportunities Discovered: ${opps.totalOpportunitiesFound} strategic opportunity item(s)`);
+    // -------------------------------------------------------------
+    // Test 10: Flagship Project Audit & Sprint Prioritization
+    // -------------------------------------------------------------
+    console.log('\n🔟 Testing Flagship Project Audit & Sprint Prioritization...');
+    const audit = await auditProject(nextAppPath);
+    const sprints = await prioritizeFindings(nextAppPath);
+    console.log(`   ✅ Audit Complete: Overall Score=${audit.scores.overallHealth}/100 | Dynamic Routes=${audit.routesSummary.dynamicRoutesCount}`);
+    console.log(`   ✅ Priority Sprints: Quick Wins=${sprints.sprints.quickWins.length}, Critical=${sprints.sprints.criticalBlockers.length}`);
+    console.log('\n🎉 ALL v1.2.0 ARCHITECTURAL & CI TEST SUITES PASSED CLEANLY!\n');
 }
 runTests().catch(err => {
     console.error('❌ Test failed:', err);

package/dist/tools/orchestration.js

@@ -1,8 +1,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { detectFramework, discoverRoutes, mapUrlToRouteSource } from '../utils/projectScanner.js';
+import { getProjectAdapter } from '../utils/projectScanner.js';
 import { createProjectSnapshot, compareSnapshots } from '../utils/snapshotEngine.js';
 import { calculateMultiDimensionalScores } from '../utils/findingEngine.js';
+import { inspectSourceFileAST } from '../utils/astLocator.js';
 export async function auditProject(projectPath, baseUrl, crawlDepth = 2) {
     const snapshot = await createProjectSnapshot(projectPath, {
         baseUrl,
@@ -21,7 +22,6 @@ export async function auditProject(projectPath, baseUrl, crawlDepth = 2) {
     for (const f of snapshot.findings) {
         findingsByCategory[f.category] = (findingsByCategory[f.category] || 0) + 1;
     }
-    // Sort by priorityScore descending
     const sortedFindings = [...snapshot.findings].sort((a, b) => b.priorityScore - a.priorityScore);
     const missingMetaCount = snapshot.discoveredRoutes.filter(r => r.routeType === 'page' && !r.hasMetadataExport && !r.hasGenerateMetadata).length;
     const missingSchemaCount = snapshot.discoveredRoutes.filter(r => r.routeType === 'page' && !r.hasSchemaMarkup).length;
@@ -34,6 +34,7 @@ export async function auditProject(projectPath, baseUrl, crawlDepth = 2) {
         schemaVersion: 'seo.gravity/v1',
         projectPath: snapshot.projectPath,
         scannedAt: snapshot.createdAt,
+        gitMetadata: snapshot.gitMetadata,
         framework: snapshot.frameworkInfo,
         routesSummary: {
             totalDiscovered: snapshot.discoveredRoutes.length,
@@ -60,9 +61,10 @@ export async function auditProject(projectPath, baseUrl, crawlDepth = 2) {
 }
 export async function diagnoseSeo(projectPath, targetUrlOrFile, focusIssueId) {
     const resolvedPath = path.resolve(projectPath);
-    const frameworkInfo = detectFramework(resolvedPath);
-    const discoveredRoutes = discoverRoutes(resolvedPath, frameworkInfo);
-    const mapping = mapUrlToRouteSource(targetUrlOrFile, discoveredRoutes);
+    const adapter = getProjectAdapter(resolvedPath);
+    const frameworkInfo = adapter.getProjectInfo(resolvedPath);
+    const discoveredRoutes = adapter.discoverRoutes(resolvedPath);
+    const mapping = adapter.mapRouteToSource(targetUrlOrFile, discoveredRoutes);
     let sourceFile = mapping.sourceFilePath;
     if (!sourceFile && fs.existsSync(path.join(resolvedPath, targetUrlOrFile))) {
         sourceFile = targetUrlOrFile;
@@ -70,22 +72,18 @@ export async function diagnoseSeo(projectPath, targetUrlOrFile, focusIssueId) {
     const detectedIssues = [];
     const rootCauses = [];
     const fixBlueprints = [];
+    let ast = null;
     let fileContent = '';
     if (sourceFile) {
-        try {
-            fileContent = fs.readFileSync(path.join(resolvedPath, sourceFile), 'utf-8');
-        }
-        catch {
-            // File read failed
+        const absPath = path.join(resolvedPath, sourceFile);
+        if (fs.existsSync(absPath)) {
+            fileContent = fs.readFileSync(absPath, 'utf-8');
+            ast = inspectSourceFileAST(absPath);
         }
     }
     // Next.js App Router diagnostics
-    if (frameworkInfo.framework === 'nextjs-app-router' && sourceFile) {
-        const hasMeta = /export\s+const\s+metadata\b/.test(fileContent);
-        const hasGenMeta = /export\s+(async\s+)?function\s+generateMetadata\b/.test(fileContent);
-        const hasCanonical = /canonical/.test(fileContent);
-        const hasSchema = /application\/ld\+json/.test(fileContent);
-        if (!hasMeta && !hasGenMeta) {
+    if (frameworkInfo.framework === 'nextjs-app-router' && sourceFile && ast) {
+        if (!ast.hasMetadataExport && !ast.hasGenerateMetadata) {
             const issueId = 'SEO-METATAG-001';
             detectedIssues.push({
                 id: issueId,
@@ -96,7 +94,8 @@ export async function diagnoseSeo(projectPath, targetUrlOrFile, focusIssueId) {
                 evidenceType: 'observed',
                 evidence: `File '${sourceFile}' contains no 'metadata' or 'generateMetadata' export.`,
                 affectedUrl: targetUrlOrFile,
-                sourceLocation: { filePath: sourceFile, line: 1 },
+                sourceLocation: { filePath: sourceFile, line: 1, startLine: 1, endLine: 1 },
+                sourceRange: { filePath: sourceFile, startLine: 1, endLine: 1, astNodeType: 'SourceFile' },
                 likelyRootCause: 'Next.js App Router relies on explicit metadata exports to generate <title> and <meta> tags.',
                 recommendation: 'Export a Metadata object or dynamic generateMetadata function.',
                 expectedImpact: 'Generates proper search snippet title and description.',
@@ -113,18 +112,20 @@ export async function diagnoseSeo(projectPath, targetUrlOrFile, focusIssueId) {
                 issueId,
                 description: 'Missing Next.js metadata export in page component.',
                 sourceCodeSnippet: fileContent.slice(0, 150),
+                sourceRange: { filePath: sourceFile, startLine: 1, endLine: 1 },
                 whyItOccurs: 'Without metadata export, Next.js falls back to empty root title, causing generic SERP snippets.'
             });
             fixBlueprints.push({
                 issueId,
                 title: 'Add static metadata export',
                 targetFile: sourceFile,
+                sourceRange: { filePath: sourceFile, startLine: 1, endLine: 1 },
                 actionType: 'modify_file',
                 codeToInsertOrReplace: `import type { Metadata } from 'next';\n\nexport const metadata: Metadata = {\n  title: 'Descriptive Page Title | Brand',\n  description: 'High-converting search meta description under 155 characters.',\n};\n`,
                 verificationInstructions: 'Run `npm run build` to ensure type-check passes, then curl page and inspect <head>.'
             });
         }
-        if (!hasCanonical) {
+        if (!ast.hasCanonicalDeclaration) {
             const issueId = 'SEO-CANONICAL-001';
             detectedIssues.push({
                 id: issueId,
@@ -135,7 +136,8 @@ export async function diagnoseSeo(projectPath, targetUrlOrFile, focusIssueId) {
                 evidenceType: 'observed',
                 evidence: `File '${sourceFile}' does not declare alternates.canonical.`,
                 affectedUrl: targetUrlOrFile,
-                sourceLocation: { filePath: sourceFile },
+                sourceLocation: { filePath: sourceFile, line: 1 },
+                sourceRange: ast.canonicalRange || { filePath: sourceFile, startLine: 1, endLine: 1 },
                 likelyRootCause: 'Page does not declare its canonical master URL, risking duplicate content indexation.',
                 recommendation: 'Add alternates.canonical to page metadata.',
                 expectedImpact: 'Consolidates ranking signals onto the primary URL.',
@@ -152,6 +154,7 @@ export async function diagnoseSeo(projectPath, targetUrlOrFile, focusIssueId) {
                 issueId,
                 title: 'Add canonical tag to metadata',
                 targetFile: sourceFile,
+                sourceRange: ast.metadataRange,
                 actionType: 'modify_file',
                 codeToInsertOrReplace: `alternates: {\n  canonical: 'https://yourdomain.com${mapping.matchedRoute?.routePath || ''}',\n},`,
                 verificationInstructions: 'Verify <link rel="canonical"> in server response.'
@@ -163,6 +166,7 @@ export async function diagnoseSeo(projectPath, targetUrlOrFile, focusIssueId) {
         targetUrlOrFile,
         matchedRoute: mapping.matchedRoute,
         sourceLocation: sourceFile ? { filePath: sourceFile, line: 1 } : undefined,
+        sourceRange: ast?.metadataRange || (sourceFile ? { filePath: sourceFile, startLine: 1, endLine: 1 } : undefined),
         detectedIssues,
         likelyRootCauses: rootCauses,
         suggestedFixBlueprints: fixBlueprints
@@ -195,14 +199,12 @@ export async function prioritizeFindings(findingsOrProjectPath, maxCount = 20) {
             minorPolish.push(f);
         }
     }
-    // Sort each sprint by priorityScore descending
     quickWins.sort((a, b) => b.priorityScore - a.priorityScore);
     criticalBlockers.sort((a, b) => b.priorityScore - a.priorityScore);
     architecturalImprovements.sort((a, b) => b.priorityScore - a.priorityScore);
     minorPolish.sort((a, b) => b.priorityScore - a.priorityScore);
     const initialScores = calculateMultiDimensionalScores(findingsList);
     const currentScore = initialScores.overallHealth;
-    // Estimate post quick-wins score
     const remainingAfterQuickWins = findingsList.filter(f => !quickWins.includes(f));
     const scoreAfterQuickWins = calculateMultiDimensionalScores(remainingAfterQuickWins).overallHealth;
     const totalEffortHours = quickWins.length * 0.25 +

package/dist/types/canonical.d.ts

@@ -0,0 +1,64 @@
+export type ProvenanceSource = 'rendered_dom' | 'raw_html' | 'ast_inspection' | 'http_headers' | 'robots_txt' | 'sitemap_xml' | 'static_analysis' | 'provider_api';
+export interface Provenance {
+    analyzer: string;
+    source: ProvenanceSource;
+    timestamp: string;
+    provider: string;
+}
+export interface PageIdentity {
+    logicalPageId: string;
+    canonicalUrl?: string;
+    observedUrl: string;
+    routePattern?: string;
+    normalizedPath: string;
+}
+export interface Observation {
+    id: string;
+    logicalPageId: string;
+    observedUrl: string;
+    key: string;
+    rawValue: any;
+    normalizedValue?: string | number | boolean;
+    provenance: Provenance;
+}
+export interface ASTSourceRange {
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    startColumn?: number;
+    endColumn?: number;
+    astNodeType?: string;
+    exportName?: string;
+    snippet?: string;
+}
+export type InvariantType = 'INVARIANT_HTTP_200' | 'INVARIANT_CANONICAL_PRESENT' | 'INVARIANT_INDEXABLE' | 'INVARIANT_SCHEMA_VALID' | 'INVARIANT_TITLE_PRESENT' | 'INVARIANT_DESCRIPTION_PRESENT' | 'INVARIANT_LINK_ACCESSIBLE' | 'INVARIANT_ROBOTS_ALLOWED';
+export interface SEOInvariant {
+    id: InvariantType;
+    logicalPageId: string;
+    url: string;
+    description: string;
+    expectedCondition: string;
+    observedCondition: string;
+    satisfied: boolean;
+    provenance: Provenance;
+}
+export type InvariantDiffStatus = 'NEW_REGRESSION' | 'RESOLVED' | 'UNCHANGED' | 'EXPECTED_CHANGE' | 'UNKNOWN';
+export interface InvariantDiffItem {
+    invariantId: InvariantType;
+    logicalPageId: string;
+    url: string;
+    status: InvariantDiffStatus;
+    baselineSatisfied: boolean;
+    currentSatisfied: boolean;
+    message: string;
+    sourceRange?: ASTSourceRange;
+}
+export interface GitMetadata {
+    commitHash?: string;
+    shortHash?: string;
+    branch?: string;
+    isDirty?: boolean;
+    author?: string;
+    commitDate?: string;
+    changedFilesSinceBase?: string[];
+}

package/dist/types/canonical.js

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

package/dist/types/findings.d.ts

@@ -1,3 +1,5 @@
+import { Provenance, Observation, ASTSourceRange, SEOInvariant, InvariantDiffItem, GitMetadata } from './canonical.js';
+export * from './canonical.js';
 export type FindingCategory = 'technical' | 'content' | 'discoverability' | 'authority' | 'entity' | 'performance' | 'ai_readiness';
 export type SeverityLevel = 'critical' | 'high' | 'medium' | 'low' | 'info';
 export type EvidenceType = 'observed' | 'derived' | 'heuristic' | 'predictive';
@@ -8,6 +10,8 @@ export interface SourceLocation {
     filePath: string;
     line?: number;
     column?: number;
+    startLine?: number;
+    endLine?: number;
     exportName?: string;
     componentName?: string;
     snippet?: string;
@@ -18,17 +22,24 @@ export interface SuggestedFix {
     explanation: string;
     snippet?: string;
     diffPreview?: string;
+    startLine?: number;
+    endLine?: number;
 }
 export interface Finding {
     id: string;
+    ruleId?: string;
     category: FindingCategory;
     title: string;
     severity: SeverityLevel;
     confidence: number;
     evidenceType: EvidenceType;
     evidence: string;
+    observations?: Observation[];
+    provenance?: Provenance;
     affectedUrl: string;
+    logicalPageId?: string;
     sourceLocation?: SourceLocation;
+    sourceRange?: ASTSourceRange;
     likelyRootCause?: string;
     recommendation: string;
     suggestedFix?: SuggestedFix;
@@ -88,16 +99,19 @@ export interface DiscoveredRoute {
     hasSchemaMarkup: boolean;
     hasHeadComponent: boolean;
     isClientComponent: boolean;
+    astSourceRange?: ASTSourceRange;
 }
 export interface RouteSourceMapping {
     urlPath: string;
     matchedRoute?: DiscoveredRoute;
     sourceFilePath?: string;
+    sourceRange?: ASTSourceRange;
     confidence: number;
     resolutionMethod: 'exact_match' | 'pattern_match' | 'fallback_heuristic' | 'unmapped';
 }
 export interface CrawlGraphNode {
     url: string;
+    logicalPageId?: string;
     routePath?: string;
     title: string;
     statusCode: number;
@@ -134,10 +148,13 @@ export interface ProjectSnapshot {
     snapshotId: string;
     createdAt: string;
     projectPath: string;
+    gitMetadata?: GitMetadata;
     frameworkInfo: ProjectFrameworkInfo;
     discoveredRoutes: DiscoveredRoute[];
     scores: MultiDimensionalScores;
     findings: Finding[];
+    observations?: Observation[];
+    invariants?: SEOInvariant[];
     crawlGraph?: CrawlGraphSummary;
     routeMappings: RouteSourceMapping[];
 }
@@ -157,6 +174,7 @@ export interface RegressionReport {
     resolvedFindings: Finding[];
     newRegressions: Finding[];
     unresolvedFindings: Finding[];
+    invariantDiffs?: InvariantDiffItem[];
     totalResolvedCount: number;
     totalNewRegressionsCount: number;
     alerts: string[];
@@ -165,6 +183,7 @@ export interface ProjectAuditResult {
     schemaVersion: 'seo.gravity/v1';
     projectPath: string;
     scannedAt: string;
+    gitMetadata?: GitMetadata;
     framework: ProjectFrameworkInfo;
     routesSummary: {
         totalDiscovered: number;
@@ -189,17 +208,20 @@ export interface DiagnosticResult {
     targetUrlOrFile: string;
     matchedRoute?: DiscoveredRoute;
     sourceLocation?: SourceLocation;
+    sourceRange?: ASTSourceRange;
     detectedIssues: Finding[];
     likelyRootCauses: Array<{
         issueId: string;
         description: string;
         sourceCodeSnippet?: string;
+        sourceRange?: ASTSourceRange;
         whyItOccurs: string;
     }>;
     suggestedFixBlueprints: Array<{
         issueId: string;
         title: string;
         targetFile: string;
+        sourceRange?: ASTSourceRange;
         actionType: 'modify_file' | 'create_file' | 'config_update';
         codeToInsertOrReplace: string;
         verificationInstructions: string;

package/dist/types/findings.js

@@ -1 +1 @@
-export {};
+export * from './canonical.js';