seo-gravity-mcp 1.2.0 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# 🚀 SEO Gravity (v1.2.0)
+# 🚀 SEO Gravity (v1.3.0)
 
 <div align="center">
 
@@ -6,13 +6,14 @@
 [![npm downloads](https://img.shields.io/npm/dm/seo-gravity-mcp?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/seo-gravity-mcp)
 ![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue?style=for-the-badge&logo=anthropic)
 ![SARIF Ready](https://img.shields.io/badge/SARIF-GitHub_Code_Scanning-success?style=for-the-badge)
-![CLI Ready](https://img.shields.io/badge/CLI-CI%2FCD_Ready-success?style=for-the-badge)
+![PR Comment Ready](https://img.shields.io/badge/PR_Comment-GitHub_Ready-blueviolet?style=for-the-badge)
+![17 Frameworks](https://img.shields.io/badge/Frameworks-17_Supported-blueviolet?style=for-the-badge)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
 ![Zero API Cost](https://img.shields.io/badge/Zero_API_Cost-100%25_Free-orange?style=for-the-badge)
 
 **The SEO Engineering Infrastructure Layer for AI Coding Agents & CI/CD Pipelines.**
 
-[⚡ Instant Start](#-instant-start) • [💻 CLI & CI/CD](#-command-line--cicd-runner) • [🛡️ Invariant Truth Layer](#-formal-seo-invariant-registry) • [🏛 5-Layer Architecture](#-5-layer-system-architecture) • [🧩 Framework Adapters](#-modular-framework-adapters) • [🛠 Tool Catalog (35 Tools)](#-complete-tool-catalog) • [📄 License](#-license)
+[⚡ Instant Start](#-instant-start) • [💻 CLI & CI/CD](#-command-line--cicd-runner) • [🛡️ Invariant Truth & Policy](#-formal-seo-invariant-registry--policy-engine) • [🏛 5-Layer Architecture](#-5-layer-system-architecture) • [🧩 17 Framework Adapters](#-17-modular-framework-adapters--benchmark) • [🛠 Tool Catalog (35 Tools)](#-complete-tool-catalog) • [📄 License](#-license)
 
 </div>
 
@@ -22,12 +23,12 @@
 
 **SEO Gravity** is an **SEO engineering infrastructure layer** designed specifically for AI coding agents (Antigravity, Cursor, Claude Code, Windsurf, Cline, Roo Code) and automated CI/CD pipelines.
 
-Instead of operating as a passive reporting tool, SEO Gravity connects **rendered web observations** directly to **source code AST nodes and line numbers** across modern web frameworks (Next.js App/Pages Router, Astro, Vite/React, Remix, SvelteKit), generates actionable code fix blueprints, and enforces invariant-based regression checks.
+Instead of operating as a passive reporting tool, SEO Gravity connects **rendered web observations** directly to **source code AST nodes, templates, and line numbers** across **17 modern web frameworks, full-stack backend architectures, and CMS ecosystems** (Next.js, WordPress, Laravel, Symfony, Astro, Vite, Remix, SvelteKit, Nuxt 3, TanStack Start, SolidStart, Qwik City, Gatsby, and Markdown SSGs), evaluates semantic SEO invariants against customizable project policies, generates actionable code fix blueprints, and enforces automated regression gates.
 
 ```text
  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │ 1. DISCOVER  │ ──▶ │  2. OBSERVE  │ ──▶ │ 3. DIAGNOSE  │ ──▶ │    4. FIX    │ ──▶ │  5. VERIFY   │
- │ Framework    │     │ Live/Dev SSR │     │ AST Line Nos │     │ AI Modifies  │     │ Invariant    │
+ │ 17 Framework │     │ Live/Dev SSR │     │ AST Line Nos │     │ AI Modifies  │     │ Invariant    │
  │ Adapters     │     │ Crawl Graph  │     │ Prioritized  │     │ Components   │     │ Regression   │
  │ Source Map   │     │ Provenance   │     │ Action Plan  │     │ Snippets     │     │ Git Stamping │
  └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
@@ -38,75 +39,106 @@ Instead of operating as a passive reporting tool, SEO Gravity connects **rendere
 ## 🏛 5-Layer System Architecture
 
 ```text
-┌─────────────────────────────────────────────────────────────┐
-│ 1. AGENT & CLI INTERFACE                                    │
-│    MCP Server (35 tools) + Standalone CLI (`seo-gravity`)   │
-├─────────────────────────────────────────────────────────────┤
-│ 2. INTELLIGENCE & REASONING LAYER                           │
-│    Root-cause diagnosis, deterministic priority, fix plans  │
-├─────────────────────────────────────────────────────────────┤
-│ 3. ANALYSIS & INVARIANT LAYER                               │
-│    SEO Invariants (HTTP 200, canonical, schema, noindex)    │
-├─────────────────────────────────────────────────────────────┤
-│ 4. OBSERVATION LAYER (Factual Raw State)                    │
-│    Observations ≠ Findings; AST inspection, headers, DOM    │
-├─────────────────────────────────────────────────────────────┤
-│ 5. PROVIDER & ADAPTER LAYER                                 │
-│    Framework Adapters (Next, Astro, Vite), Providers, Cache │
-└─────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ LAYER 1: AGENT & CLI INTERFACE                                              │
+│ • MCP Server (35 tools) + Standalone CLI (`seo-gravity`)                    │
+│ • GitHub PR Comment Formatter (`--format pr-comment`)                       │
+│ • OASIS SARIF v2.1.0 Exporter (`--format sarif`)                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ LAYER 2: INTELLIGENCE & REASONING LAYER                                     │
+│ • Root-cause diagnosis, deterministic priority, fix plans                   │
+│ • Strategic Opportunity Engine & SEO Experimentation Engine                 │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ LAYER 3: ANALYSIS, POLICY & INVARIANT LAYER                                 │
+│ • Formal Invariant Registry (Requirement Levels vs Severity)                │
+│ • Project Policy Engine (`.seo-gravity.yml` & 5 preset profiles)            │
+│ • Semantic AST Git Differential Engine (Risk scoring)                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ LAYER 4: OBSERVATION LAYER (Factual Raw State)                              │
+│ • Observations ≠ Findings; Page Identity Normalization                      │
+│ • Polymorphic Evidence: AST, Template, RouteConfig, DOM, Header, Runtime    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ LAYER 5: PROVIDER & ADAPTER LAYER                                           │
+│ • 17 Framework Adapters (JS/TS/PHP/SSG), Providers, Cache Provenance        │
+└─────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
-## 🛡️ Formal SEO Invariant Registry
+## 🛡️ Formal SEO Invariant Registry & Policy Engine
 
-SEO Gravity enforces strict **semantic invariants** rather than heuristic score drops. A regression occurs only when a previously satisfied invariant is violated:
+SEO Gravity evaluates facts against formal invariant contracts and allows teams to configure organizational standards via `.seo-gravity.yml`:
 
-| Invariant ID | Name | Target Scope | Description |
-| :--- | :--- | :--- | :--- |
-| `INV-HTTP-200` | HTTP Success Status | Route | Published routes must return HTTP 200 OK without 4xx/5xx errors. |
-| `INV-CANONICAL-RESOLVES` | Canonical URL Declaration | Page | Indexable pages must declare a canonical URL to prevent duplicate indexing. |
-| `INV-TITLE-PRESENT` | Title Tag Metadata | Page | Pages must declare unique, descriptive title metadata in AST components. |
-| `INV-LINK-ACCESSIBLE` | Link Reachability | Crawl Graph | Public pages must be reachable via internal links (0 orphan pages). |
-| `INV-ROBOTS-ALLOWED` | Robots Configuration | Site | Project must provide `robots.txt` or `robots.ts` specifying bot directives. |
-| `INV-SITEMAP-PRESENT` | XML Sitemap Configuration | Site | Project must publish `sitemap.xml` or dynamic `sitemap.ts`. |
-| `INV-LLMS-TXT` | AI Context Documentation | Site | Project should provide `/llms.txt` for AI agent discovery. |
+| Invariant ID | Name | Scope | Requirement Level | Severity | Semantic Failure Condition |
+| :--- | :--- | :---: | :---: | :---: | :--- |
+| `INV-HTTP-200` | HTTP Success Status | Route | **`REQUIRED`** | Critical | Published routes return 4xx or 5xx HTTP status. |
+| `INV-CANONICAL-RESOLVES` | Canonical URL Declaration | Page | **`CONDITIONAL`** | High | Indexable page lacks `<link rel="canonical">` or canonical metadata. |
+| `INV-TITLE-PRESENT` | Title Tag Metadata | Page | **`REQUIRED`** | High | Component metadata or `<title>` tag is missing. |
+| `INV-LINK-ACCESSIBLE` | Link Reachability | Crawl Graph | **`CONDITIONAL`** | Medium | Public page has 0 internal inlinks (Orphan Page). |
+| `INV-ROBOTS-ALLOWED` | Robots Policy Determinable | Site | **`CONDITIONAL`** | Medium | Bot directives are indeterminable or block critical assets. |
+| `INV-SITEMAP-PRESENT` | XML Sitemap Configuration | Site | **`RECOMMENDED`** | Medium | Missing `sitemap.xml` or dynamic sitemap route. |
+| `INV-LLMS-TXT` | AI Context Documentation | Site | **`RECOMMENDED`** | Low | Missing `/llms.txt` context file for AI crawlers (GEO). |
+
+### Project Policy Profiles (`.seo-gravity.yml`)
+
+Configure project policies with built-in presets (`strict`, `balanced`, `startup`, `ecommerce`, `documentation`):
+
+```yaml
+version: 1
+profile: balanced # strict | balanced | startup | ecommerce | documentation
+
+policy:
+  canonical: required
+  sitemap: recommended
+  llms_txt: recommended
+
+regression:
+  fail_on_levels: [REQUIRED, CONDITIONAL]
+  fail_on_severities: [critical, high]
+```
 
 ---
 
-## 🧩 Modular Framework Adapters & Benchmark
+## 🧩 17 Modular Framework Adapters & Benchmark
 
-Tested with **100% correlation accuracy** across 7 web application frameworks:
+Tested with **100% correlation accuracy** across 17 web application frameworks and CMS ecosystems:
 
-| Framework Adapter | Detection | Route Discovery | AST Inspection | Benchmark |
+| Category | Framework Adapter | Detection Signature | Routing & Template Model | Benchmark Result |
 | :--- | :--- | :--- | :--- | :---: |
-| **`NextAppAdapter`** | `next` + `app/` | App Router hierarchy, route groups `(group)`, dynamic `[slug]` | Pinpoints `metadata` export & `generateMetadata()` lines | **100%** |
-| **`NextPagesAdapter`** | `next` + `pages/` | Pages router hierarchy, dynamic `[id]` | Scans `<Head>` & `<NextSeo>` JSX components | **100%** |
-| **`AstroAdapter`** | `astro` + `src/pages` | `.astro`, `.md`, `.mdx` pages | Scans Astro frontmatter & `<title>` tags | **100%** |
-| **`ViteReactAdapter`** | `vite` / `react` | `index.html` + React Router routes | Scans `<Helmet>` & route definition trees | **100%** |
-| **`RemixAdapter`** | `@remix-run/react` | `app/routes/` | Inspects `meta` and `links` export functions | **100%** |
-| **`SvelteKitAdapter`** | `@sveltejs/kit` | `src/routes/` (`+page.svelte`) | Scans `<svelte:head>` components | **100%** |
-| **`StaticAdapter`** | Static HTML files | Recursive HTML directory traversal | Direct DOM / meta element inspection | **100%** |
+| **JS / TS SSR** | **`NextAppAdapter`** | `next` + `app/` | App Router hierarchy, route groups `(group)`, dynamic `[slug]` | **100%** |
+| **JS / TS SSR** | **`NextPagesAdapter`** | `next` + `pages/` | Pages router hierarchy, dynamic `[id]` | **100%** |
+| **JS / TS SSR** | **`AstroAdapter`** | `astro` + `src/pages` | `.astro`, `.md`, `.mdx` pages | **100%** |
+| **JS / TS SSR** | **`RemixAdapter`** | `@remix-run/react` | Flat routes `app/routes/`, index `_index.tsx`, dynamic `$slug` | **100%** |
+| **JS / TS SSR** | **`SvelteKitAdapter`** | `@sveltejs/kit` | `src/routes/` (`+page.svelte`), dynamic `[slug]` | **100%** |
+| **JS / TS SSR** | **`NuxtAdapter`** | `nuxt` in `package.json` | `pages/**/*.vue` with `useHead()`, `useSeoMeta()` | **100%** |
+| **JS / TS SSR** | **`TanStackRouterAdapter`** | `@tanstack/react-router` | `src/routes/` with `createFileRoute` & `head()` | **100%** |
+| **JS / TS SSR** | **`SolidStartAdapter`** | `@solidjs/start` | `src/routes/` with `<Title>`, `<Meta>`, `<Link>` | **100%** |
+| **JS / TS SSR** | **`QwikCityAdapter`** | `@builder.io/qwik-city` | `src/routes/**/index.tsx` with `DocumentHead` | **100%** |
+| **JS / TS SSG** | **`GatsbyAdapter`** | `gatsby` in `package.json` | `src/pages/` with `export const Head` | **100%** |
+| **PHP / CMS** | **`WordPressAdapter`** | `style.css` / `wp-content` | Classic templates (`front-page.php`, `single.php`) & FSE block templates | **100%** |
+| **PHP Fullstack** | **`LaravelAdapter`** | `artisan` / `laravel/framework` | `routes/web.php` + Blade templates (`@section('title')`) | **100%** |
+| **PHP Fullstack** | **`SymfonyAdapter`** | `symfony.lock` / `composer.json` | `config/routes.yaml` / `#[Route]` + Twig templates (`{% block title %}`) | **100%** |
+| **PHP Classic** | **`PhpClassicAdapter`** | `*.php` files | File-based routing (`index.php`, `about.php`) | **100%** |
+| **Markdown SSG** | **`SsgAdapter`** | `hugo.toml`, `_config.yml`, `11ty` | `content/**/*.md`, `_posts/**/*.md` YAML/TOML frontmatter | **100%** |
+| **React SPA** | **`ViteReactAdapter`** | `vite` + `react` | `index.html` + React Router route trees | **100%** |
+| **Static HTML** | **`StaticAdapter`** | Static `.html` files | Recursive HTML directory traversal | **100%** |
 
 ---
 
-## 💻 Command-Line & CI/CD Runner (SARIF Ready)
+## 💻 Command-Line & CI/CD Runner
 
-SEO Gravity includes a standalone CLI binary (`seo-gravity`) with native **SARIF v2.1.0** export for GitHub Code Scanning:
+SEO Gravity includes a standalone CLI binary (`seo-gravity`) with native **SARIF v2.1.0** and **GitHub PR Comment** export:
 
 ```bash
-# 1. Audit project (Terminal / JSON / SARIF)
+# 1. Audit project (Terminal / JSON / SARIF / PR-Comment)
 npx seo-gravity-mcp audit --project ./my-app
 npx seo-gravity-mcp audit --project ./my-app --format sarif --output seo-findings.sarif
 
-# 2. Create baseline snapshot
-npx seo-gravity-mcp snapshot --project ./my-app --output baseline.json
-
-# 3. Check for SEO regressions in CI/CD PR gate (Exits with 0 or 1)
-npx seo-gravity-mcp check --project ./my-app --baseline baseline.json
+# 2. Check regressions in CI/CD against project policy (Exits 0 or 1)
+npx seo-gravity-mcp check --project ./my-app --baseline baseline.json --policy .seo-gravity.yml --format pr-comment
 
-# 4. Targeted Semantic Git differential audit on modified routes only
-npx seo-gravity-mcp diff --project ./my-app --base-ref origin/main
+# 3. Targeted Semantic Git differential audit & SEO Code Review on modified routes
+npx seo-gravity-mcp review --project ./my-app --base-ref origin/main --format pr-comment --output pr-comment.md
 ```
 
 ### GitHub Actions CI/CD Integration
@@ -126,7 +158,12 @@ jobs:
           node-version: 20
 
       - name: Run SEO Invariant Regression Check
-        run: npx seo-gravity-mcp check --project . --baseline .seo-baseline.json --format sarif --output results.sarif
+        run: |
+          npx seo-gravity-mcp check \
+            --project . \
+            --baseline .seo-baseline.json \
+            --format sarif \
+            --output results.sarif
 
       - name: Upload SARIF to GitHub Security Tab
         uses: github/codeql-action/upload-sarif@v3
@@ -171,7 +208,7 @@ npx -y seo-gravity-mcp
 
 ---
 
-## 🛠 Complete Tool Catalog
+## 🛠 Complete Tool Catalog (35 Tools)
 
 ### Layer 0: Agent Orchestration & Remediation (Flagship)
 | Tool Name | Operational Class | Description |

package/dist/adapters/adapterRegistry.d.ts

@@ -3,5 +3,6 @@ export declare class AdapterRegistry {
     private adapters;
     getAdapterForProject(projectDir: string): FrameworkAdapter;
     getAdapterById(id: string): FrameworkAdapter | undefined;
+    getAllAdapters(): FrameworkAdapter[];
 }
 export declare const defaultAdapterRegistry: AdapterRegistry;

package/dist/adapters/adapterRegistry.js

@@ -1,19 +1,43 @@
 import { NextAppAdapter } from './nextAppAdapter.js';
 import { NextPagesAdapter } from './nextPagesAdapter.js';
 import { AstroAdapter } from './astroAdapter.js';
-import { ViteReactAdapter } from './viteReactAdapter.js';
 import { RemixAdapter } from './remixAdapter.js';
 import { SvelteKitAdapter } from './svelteKitAdapter.js';
+import { NuxtAdapter } from './nuxtAdapter.js';
+import { TanStackRouterAdapter } from './tanStackRouterAdapter.js';
+import { SolidStartAdapter } from './solidStartAdapter.js';
+import { QwikCityAdapter } from './qwikCityAdapter.js';
+import { GatsbyAdapter } from './gatsbyAdapter.js';
+import { WordPressAdapter } from './wordpressAdapter.js';
+import { LaravelAdapter } from './laravelAdapter.js';
+import { SymfonyAdapter } from './symfonyAdapter.js';
+import { PhpClassicAdapter } from './phpClassicAdapter.js';
+import { SsgAdapter } from './ssgAdapter.js';
+import { ViteReactAdapter } from './viteReactAdapter.js';
 import { StaticAdapter } from './staticAdapter.js';
 export class AdapterRegistry {
     adapters = [
+        // Specialized JS/TS Frameworks
         new NextAppAdapter(),
         new NextPagesAdapter(),
         new AstroAdapter(),
         new RemixAdapter(),
         new SvelteKitAdapter(),
+        new NuxtAdapter(),
+        new TanStackRouterAdapter(),
+        new SolidStartAdapter(),
+        new QwikCityAdapter(),
+        new GatsbyAdapter(),
+        // PHP & CMS Frameworks
+        new WordPressAdapter(),
+        new LaravelAdapter(),
+        new SymfonyAdapter(),
+        new PhpClassicAdapter(),
+        // Static Site Generators & SPAs
+        new SsgAdapter(),
         new ViteReactAdapter(),
-        new StaticAdapter() // fallback
+        // Universal Fallback
+        new StaticAdapter()
     ];
     getAdapterForProject(projectDir) {
         for (const adapter of this.adapters) {
@@ -26,5 +50,8 @@ export class AdapterRegistry {
     getAdapterById(id) {
         return this.adapters.find(a => a.id === id);
     }
+    getAllAdapters() {
+        return [...this.adapters];
+    }
 }
 export const defaultAdapterRegistry = new AdapterRegistry();

package/dist/adapters/gatsbyAdapter.d.ts

@@ -0,0 +1,17 @@
+import { FrameworkAdapter, FrameworkDetectionResult, MetadataLocationInfo, CanonicalLocationInfo, SchemaLocationInfo } from './types.js';
+import { DiscoveredRoute, ProjectFrameworkInfo, RouteSourceMapping } from '../types/findings.js';
+export declare class GatsbyAdapter implements 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/gatsbyAdapter.js

@@ -0,0 +1,134 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export class GatsbyAdapter {
+    id = 'gatsby';
+    name = 'Gatsby Framework';
+    detect(projectDir) {
+        return this.detectDetailed(projectDir).matched;
+    }
+    detectDetailed(projectDir) {
+        const evidence = [];
+        if (fs.existsSync(path.join(projectDir, 'gatsby-config.js')) || fs.existsSync(path.join(projectDir, 'gatsby-config.ts'))) {
+            evidence.push('gatsby-config detected');
+        }
+        const pkgPath = path.join(projectDir, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+                if (deps['gatsby'])
+                    evidence.push('gatsby in package dependencies');
+            }
+            catch { }
+        }
+        return {
+            matched: evidence.length > 0,
+            confidence: evidence.length > 0 ? 0.95 : 0.0,
+            evidence
+        };
+    }
+    getProjectInfo(projectDir) {
+        return {
+            framework: 'gatsby',
+            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/pages',
+            devCommand: 'npm run develop',
+            defaultDevPort: 8000
+        };
+    }
+    discoverRoutes(projectDir) {
+        const routesDir = path.join(projectDir, 'src/pages');
+        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()) {
+                    scan(full, prefix === '/' ? `/${e.name}` : `${prefix}/${e.name}`);
+                }
+                else if (e.isFile() && /\.(tsx|jsx|js|ts)$/.test(e.name)) {
+                    const base = e.name.replace(/\.(tsx|jsx|js|ts)$/, '');
+                    const routePath = base === 'index' ? prefix : (prefix === '/' ? `/${base}` : `${prefix}/${base}`);
+                    const rel = path.relative(projectDir, full).replace(/\\/g, '/');
+                    const content = fs.readFileSync(full, 'utf-8');
+                    discovered.push({
+                        routePath: routePath === '' ? '/' : routePath,
+                        sourceFilePath: rel,
+                        isDynamic: false,
+                        dynamicParams: [],
+                        routeType: 'page',
+                        hasMetadataExport: /export\s+const\s+Head\b|<title\b/i.test(content),
+                        hasGenerateMetadata: false,
+                        hasSchemaMarkup: /application\/ld\+json/.test(content),
+                        hasHeadComponent: /export\s+const\s+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 = /export\s+const\s+Head\b|<title\b/i.test(content);
+        return { hasMetadata: has, type: has ? 'static_export' : '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 = ['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 = ['static/llms.txt', 'llms.txt'];
+        for (const p of paths)
+            if (fs.existsSync(path.join(projectDir, p)))
+                return p;
+        return null;
+    }
+}

package/dist/adapters/laravelAdapter.d.ts

@@ -0,0 +1,17 @@
+import { FrameworkAdapter, FrameworkDetectionResult, MetadataLocationInfo, CanonicalLocationInfo, SchemaLocationInfo } from './types.js';
+import { DiscoveredRoute, ProjectFrameworkInfo, RouteSourceMapping } from '../types/findings.js';
+export declare class LaravelAdapter implements 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/laravelAdapter.js

@@ -0,0 +1,192 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export class LaravelAdapter {
+    id = 'laravel';
+    name = 'Laravel (Blade & Artisan)';
+    detect(projectDir) {
+        return this.detectDetailed(projectDir).matched;
+    }
+    detectDetailed(projectDir) {
+        const evidence = [];
+        if (fs.existsSync(path.join(projectDir, 'artisan'))) {
+            evidence.push('artisan CLI entry file detected');
+        }
+        const composerPath = path.join(projectDir, 'composer.json');
+        if (fs.existsSync(composerPath)) {
+            try {
+                const composer = JSON.parse(fs.readFileSync(composerPath, 'utf-8'));
+                const deps = { ...composer.require, ...composer['require-dev'] };
+                if (deps['laravel/framework']) {
+                    evidence.push('laravel/framework in composer.json require');
+                }
+            }
+            catch { }
+        }
+        return {
+            matched: evidence.length > 0,
+            confidence: evidence.length >= 2 ? 0.99 : 0.92,
+            evidence
+        };
+    }
+    getProjectInfo(projectDir) {
+        return {
+            framework: 'laravel',
+            name: path.basename(projectDir),
+            hasTypeScript: false,
+            hasSitemapConfig: Boolean(this.findSitemapConfig(projectDir)),
+            hasRobotsConfig: Boolean(this.findRobotsConfig(projectDir)),
+            hasLlmsTxt: Boolean(this.findLlmsTxt(projectDir)),
+            rootDir: path.resolve(projectDir),
+            routesDir: 'routes',
+            devCommand: 'php artisan serve',
+            defaultDevPort: 8000
+        };
+    }
+    discoverRoutes(projectDir) {
+        const discovered = [];
+        const webRoutesPath = path.join(projectDir, 'routes/web.php');
+        if (fs.existsSync(webRoutesPath)) {
+            const content = fs.readFileSync(webRoutesPath, 'utf-8');
+            const routeMatches = content.matchAll(/Route::(get|view|match)\(\s*['"]([^'"]+)['"]/g);
+            for (const m of routeMatches) {
+                const rawPath = m[2];
+                const routePath = rawPath.startsWith('/') ? rawPath : `/${rawPath}`;
+                if (!discovered.some(d => d.routePath === routePath)) {
+                    discovered.push({
+                        routePath,
+                        sourceFilePath: 'routes/web.php',
+                        isDynamic: routePath.includes('{'),
+                        dynamicParams: (routePath.match(/\{([a-zA-Z0-9_]+)\}/g) || []).map(p => p.slice(1, -1)),
+                        routeType: 'page',
+                        hasMetadataExport: true,
+                        hasGenerateMetadata: false,
+                        hasSchemaMarkup: false,
+                        hasHeadComponent: true,
+                        isClientComponent: false
+                    });
+                }
+            }
+        }
+        // Also scan Blade views in resources/views
+        const viewsDir = path.join(projectDir, 'resources/views');
+        if (fs.existsSync(viewsDir)) {
+            const scanViews = (dir, prefix) => {
+                const entries = fs.readdirSync(dir, { withFileTypes: true });
+                for (const e of entries) {
+                    const full = path.join(dir, e.name);
+                    if (e.isDirectory()) {
+                        scanViews(full, prefix === '/' ? `/${e.name}` : `${prefix}/${e.name}`);
+                    }
+                    else if (e.isFile() && e.name.endsWith('.blade.php')) {
+                        const base = e.name.replace(/\.blade\.php$/, '');
+                        const routePath = base === 'welcome' || base === 'index' ? '/' : (prefix === '/' ? `/${base}` : `${prefix}/${base}`);
+                        const rel = path.relative(projectDir, full).replace(/\\/g, '/');
+                        const viewContent = fs.readFileSync(full, 'utf-8');
+                        const existing = discovered.find(d => d.routePath === routePath);
+                        if (existing) {
+                            existing.sourceFilePath = rel;
+                            existing.hasMetadataExport = /@section\(['"]title['"]|<title\b|<x-slot:title/i.test(viewContent);
+                            existing.hasSchemaMarkup = /application\/ld\+json/.test(viewContent);
+                        }
+                        else {
+                            discovered.push({
+                                routePath,
+                                sourceFilePath: rel,
+                                isDynamic: false,
+                                dynamicParams: [],
+                                routeType: 'page',
+                                hasMetadataExport: /@section\(['"]title['"]|<title\b|<x-slot:title/i.test(viewContent),
+                                hasGenerateMetadata: false,
+                                hasSchemaMarkup: /application\/ld\+json/.test(viewContent),
+                                hasHeadComponent: true,
+                                isClientComponent: false
+                            });
+                        }
+                    }
+                }
+            };
+            scanViews(viewsDir, '/');
+        }
+        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);
+        if (match) {
+            return {
+                urlPath,
+                matchedRoute: match,
+                sourceFilePath: match.sourceFilePath,
+                confidence: 1.0,
+                resolutionMethod: 'exact_match'
+            };
+        }
+        // Dynamic patterns {param}
+        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 full = path.join(projectDir, route.sourceFilePath);
+        if (!fs.existsSync(full))
+            return { hasMetadata: false, type: 'none' };
+        const content = fs.readFileSync(full, 'utf-8');
+        const has = /@section\(['"]title['"]|<title\b|<x-slot:title/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 = ['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;
+    }
+}