seo-gravity-mcp 1.3.2 → 1.3.4

package/README.md

@@ -1,4 +1,4 @@
-# 🚀 SEO Gravity (v1.3.2)
+# 🚀 SEO Gravity (v1.3.4)
 
 <div align="center">
 

package/dist/adapters/adapterRegistry.d.ts

@@ -1,5 +1,6 @@
 import { FrameworkAdapter } from './types.js';
 export declare class AdapterRegistry {
+    private unknownAdapter;
     private adapters;
     getAdapterForProject(projectDir: string): FrameworkAdapter;
     getAdapterById(id: string): FrameworkAdapter | undefined;

package/dist/adapters/adapterRegistry.js

@@ -15,7 +15,9 @@ import { PhpClassicAdapter } from './phpClassicAdapter.js';
 import { SsgAdapter } from './ssgAdapter.js';
 import { ViteReactAdapter } from './viteReactAdapter.js';
 import { StaticAdapter } from './staticAdapter.js';
+import { UnknownAdapter } from './unknownAdapter.js';
 export class AdapterRegistry {
+    unknownAdapter = new UnknownAdapter();
     adapters = [
         // Specialized JS/TS Frameworks
         new NextAppAdapter(),
@@ -36,7 +38,7 @@ export class AdapterRegistry {
         // Static Site Generators & SPAs
         new SsgAdapter(),
         new ViteReactAdapter(),
-        // Universal Fallback
+        // Static HTML Sites
         new StaticAdapter()
     ];
     getAdapterForProject(projectDir) {
@@ -45,9 +47,11 @@ export class AdapterRegistry {
                 return adapter;
             }
         }
-        return this.adapters[this.adapters.length - 1]; // fallback static
+        return this.unknownAdapter;
     }
     getAdapterById(id) {
+        if (id === 'unknown')
+            return this.unknownAdapter;
         return this.adapters.find(a => a.id === id);
     }
     getAllAdapters() {

package/dist/adapters/staticAdapter.d.ts

@@ -3,7 +3,7 @@ import { DiscoveredRoute, ProjectFrameworkInfo, RouteSourceMapping } from '../ty
 export declare class StaticAdapter implements FrameworkAdapter {
     id: string;
     name: string;
-    detect(_projectDir: string): boolean;
+    detect(projectDir: string): boolean;
     getProjectInfo(projectDir: string): ProjectFrameworkInfo;
     discoverRoutes(projectDir: string): DiscoveredRoute[];
     mapRouteToSource(targetUrl: string, routes: DiscoveredRoute[]): RouteSourceMapping;

package/dist/adapters/staticAdapter.js

@@ -3,8 +3,9 @@ import * as path from 'path';
 export class StaticAdapter {
     id = 'static-html';
     name = 'Static HTML / Web Application';
-    detect(_projectDir) {
-        return true; // Fallback
+    detect(projectDir) {
+        return fs.existsSync(path.join(projectDir, 'index.html')) ||
+            fs.existsSync(path.join(projectDir, 'public/index.html'));
     }
     getProjectInfo(projectDir) {
         return {

package/dist/adapters/unknownAdapter.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 UnknownAdapter 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/unknownAdapter.js

@@ -0,0 +1,49 @@
+import * as path from 'path';
+export class UnknownAdapter {
+    id = 'unknown';
+    name = 'Unknown / Unrecognized Framework';
+    detect(_projectDir) {
+        return false;
+    }
+    getProjectInfo(projectDir) {
+        return {
+            framework: 'unknown',
+            name: path.basename(projectDir),
+            hasTypeScript: false,
+            hasSitemapConfig: false,
+            hasRobotsConfig: false,
+            hasLlmsTxt: false,
+            rootDir: path.resolve(projectDir),
+            routesDir: '.',
+            defaultDevPort: undefined
+        };
+    }
+    discoverRoutes(_projectDir) {
+        return [];
+    }
+    mapRouteToSource(targetUrl, _routes) {
+        return {
+            urlPath: targetUrl,
+            confidence: 0.0,
+            resolutionMethod: 'unmapped'
+        };
+    }
+    async findMetadataImplementation(_projectDir, _route) {
+        return { hasMetadata: false, type: 'none' };
+    }
+    async findCanonicalDeclaration(_projectDir, _route) {
+        return { hasCanonical: false, type: 'none' };
+    }
+    async findSchemaDeclaration(_projectDir, _route) {
+        return { hasSchema: false, typesFound: [] };
+    }
+    findRobotsConfig(_projectDir) {
+        return null;
+    }
+    findSitemapConfig(_projectDir) {
+        return null;
+    }
+    findLlmsTxt(_projectDir) {
+        return null;
+    }
+}

package/dist/benchmark/methodology.js

@@ -179,7 +179,7 @@ export function generateBenchmarkMethodologyReport() {
     }
     return {
         title: 'SEO Gravity Multi-Framework Correlation & Invariant Benchmark Methodology',
-        version: '1.3.2',
+        version: '1.3.4',
         evaluatedAt: new Date().toISOString(),
         definitionOfCorrelation: 'A correlation is defined as a verified mapping connecting an observed URL or Route Pattern to its exact physical source file, template, route configuration, and AST symbol coordinate range.',
         totalFrameworksTested: BENCHMARK_FIXTURES.length,

package/dist/invariants/registry.js

@@ -49,8 +49,8 @@ export const BUILTIN_INVARIANTS = [
                     type: 'ast',
                     description: has ? 'Canonical declaration found in AST' : 'Canonical missing from source AST',
                     sourceFile: ctx.sourceFilePath,
-                    startLine: 1,
-                    endLine: 1,
+                    startLine: ctx.sourceRange?.startLine,
+                    endLine: ctx.sourceRange?.endLine,
                     timestamp: new Date().toISOString()
                 } : undefined
             };
@@ -69,7 +69,7 @@ export const BUILTIN_INVARIANTS = [
         remediationGuide: 'Export title in page metadata, define @section/block title, or add <title> in component head.',
         verificationMethod: 'Inspect page <title> in AST, template, or rendered DOM.',
         evaluate(ctx) {
-            const has = Boolean(ctx.hasMetadata || ctx.extractedTitle);
+            const has = ctx.hasTitle !== undefined ? ctx.hasTitle : Boolean(ctx.extractedTitle || ctx.hasMetadata);
             return {
                 satisfied: has,
                 observedCondition: has ? `Title present ("${ctx.extractedTitle || 'Declared'}")` : 'Title missing',
@@ -78,8 +78,8 @@ export const BUILTIN_INVARIANTS = [
                     type: 'ast',
                     description: has ? `Title metadata: "${ctx.extractedTitle || 'Declared'}"` : 'Title metadata missing',
                     sourceFile: ctx.sourceFilePath,
-                    startLine: 1,
-                    endLine: 1,
+                    startLine: ctx.sourceRange?.startLine,
+                    endLine: ctx.sourceRange?.endLine,
                     timestamp: new Date().toISOString()
                 } : undefined
             };
@@ -116,26 +116,36 @@ export const BUILTIN_INVARIANTS = [
     {
         id: 'INV-ROBOTS-ALLOWED',
         name: 'Robots Policy Determinable',
-        description: 'Project must provide a determinable robots crawl policy via robots.txt, robots.ts, or standard allow-all defaults.',
+        description: 'The effective robots crawl policy must be determinable; absence of robots.txt defaults to allow-all unless another blocking mechanism is observed.',
         category: 'robots',
         requirementLevel: 'CONDITIONAL',
         severity: 'medium',
         scope: 'SITE',
         expectedCondition: 'Robots crawl policy is determinable and does not block critical assets',
-        failureEvidence: 'No robots crawl configuration detected.',
-        remediationGuide: 'Create public/robots.txt or app/robots.ts if specific bot directives are desired.',
-        verificationMethod: 'Check GET /robots.txt response or adapter robots inspection.',
+        failureEvidence: 'Robots policy could not be determined or an observed policy blocks required resources.',
+        remediationGuide: 'Create or correct robots.txt/app/robots.ts when explicit crawler directives are needed.',
+        verificationMethod: 'Check GET /robots.txt and relevant meta/X-Robots directives.',
         evaluate(ctx) {
-            const ok = Boolean(ctx.hasRobots);
+            const policy = ctx.robotsPolicyState ?? (ctx.hasRobots ? 'explicit' : 'default_allow');
+            const ok = policy === 'explicit' || policy === 'default_allow';
+            const observed = policy === 'explicit'
+                ? 'Explicit robots policy resolved.'
+                : policy === 'default_allow'
+                    ? 'No explicit robots file; standard default allow policy assumed.'
+                    : policy === 'blocking'
+                        ? 'Blocking robots policy observed.'
+                        : 'Robots policy could not be determined.';
             return {
                 satisfied: ok,
-                observedCondition: ok ? 'Robots policy determinable' : 'Robots policy not explicitly declared',
-                evidence: ok ? 'robots.txt configuration present.' : 'No robots.txt found (default allow-all).',
+                observedCondition: observed,
+                evidence: ok
+                    ? 'Effective robots policy is determinable.'
+                    : 'Effective robots policy is not safely determinable or is blocking.',
                 polymorphicEvidence: {
                     type: 'route_config',
-                    description: ok ? 'Robots config resolved' : 'Robots config absent',
-                    sourceFile: 'robots.txt',
-                    configFormat: 'static_file',
+                    description: observed,
+                    sourceFile: ctx.hasRobots ? 'robots.txt' : undefined,
+                    configFormat: ctx.hasRobots ? 'static_file' : 'implicit_default',
                     declaredPattern: '/robots.txt',
                     timestamp: new Date().toISOString()
                 }
@@ -204,9 +214,8 @@ export const BUILTIN_INVARIANTS = [
 export class InvariantRegistry {
     invariants = new Map();
     constructor(initial = BUILTIN_INVARIANTS) {
-        for (const inv of initial) {
+        for (const inv of initial)
             this.invariants.set(inv.id, inv);
-        }
     }
     register(invariant) {
         this.invariants.set(invariant.id, invariant);

package/dist/invariants/types.d.ts

@@ -3,22 +3,30 @@ import { PolymorphicEvidence } from '../types/evidence.js';
 export type RequirementLevel = 'REQUIRED' | 'CONDITIONAL' | 'RECOMMENDED' | 'OPTIONAL';
 export type InvariantScope = 'SITE' | 'ROUTE' | 'PAGE' | 'COMPONENT' | 'RESOURCE' | 'site_wide' | 'crawl_graph';
 export type InvariantCategory = 'http' | 'indexability' | 'canonical' | 'metadata' | 'links' | 'schema' | 'robots' | 'ai_readiness';
+export type RobotsPolicyState = 'explicit' | 'default_allow' | 'blocking' | 'unknown';
 export interface InvariantEvaluationContext {
     url: string;
     logicalPageId: string;
     sourceFilePath?: string;
+    sourceRange?: {
+        startLine: number;
+        endLine: number;
+    };
     statusCode?: number;
+    hasTitle?: boolean;
+    hasDescription?: boolean;
     hasMetadata?: boolean;
     hasCanonical?: boolean;
     isIndexable?: boolean;
     hasSchema?: boolean;
     hasRobots?: boolean;
+    robotsPolicyState?: RobotsPolicyState;
     hasSitemap?: boolean;
     hasLlmsTxt?: boolean;
     incomingLinksCount?: number;
     extractedTitle?: string;
     extractedCanonical?: string;
-    rawPayload?: any;
+    rawPayload?: unknown;
 }
 export interface InvariantEvaluationResult {
     satisfied: boolean;

package/dist/policy/loader.d.ts

@@ -1,9 +1,132 @@
+import { z } from 'zod';
 import { PolicyConfig } from './types.js';
 import { InvariantDiffItem } from '../types/canonical.js';
+export declare const InvariantRuleSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    requirementLevel: z.ZodOptional<z.ZodEnum<["REQUIRED", "CONDITIONAL", "RECOMMENDED", "OPTIONAL"]>>;
+    severity: z.ZodOptional<z.ZodEnum<["critical", "high", "medium", "low", "info"]>>;
+}, "strip", z.ZodTypeAny, {
+    requirementLevel?: "REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL" | undefined;
+    severity?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+    enabled?: boolean | undefined;
+}, {
+    requirementLevel?: "REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL" | undefined;
+    severity?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+    enabled?: boolean | undefined;
+}>;
+export declare const RegressionPolicySchema: z.ZodObject<{
+    failOnLevels: z.ZodOptional<z.ZodArray<z.ZodEnum<["REQUIRED", "CONDITIONAL", "RECOMMENDED", "OPTIONAL"]>, "many">>;
+    failOnSeverities: z.ZodOptional<z.ZodArray<z.ZodEnum<["critical", "high", "medium", "low", "info"]>, "many">>;
+    allowExpectedChanges: z.ZodOptional<z.ZodBoolean>;
+    maxAllowedRegressions: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    allowExpectedChanges?: boolean | undefined;
+    failOnLevels?: ("REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL")[] | undefined;
+    failOnSeverities?: ("critical" | "high" | "medium" | "low" | "info")[] | undefined;
+    maxAllowedRegressions?: number | undefined;
+}, {
+    allowExpectedChanges?: boolean | undefined;
+    failOnLevels?: ("REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL")[] | undefined;
+    failOnSeverities?: ("critical" | "high" | "medium" | "low" | "info")[] | undefined;
+    maxAllowedRegressions?: number | undefined;
+}>;
+export declare const PolicyConfigSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    profile: z.ZodOptional<z.ZodEnum<["strict", "balanced", "startup", "ecommerce", "documentation", "custom"]>>;
+    regression: z.ZodOptional<z.ZodObject<{
+        failOnLevels: z.ZodOptional<z.ZodArray<z.ZodEnum<["REQUIRED", "CONDITIONAL", "RECOMMENDED", "OPTIONAL"]>, "many">>;
+        failOnSeverities: z.ZodOptional<z.ZodArray<z.ZodEnum<["critical", "high", "medium", "low", "info"]>, "many">>;
+        allowExpectedChanges: z.ZodOptional<z.ZodBoolean>;
+        maxAllowedRegressions: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        allowExpectedChanges?: boolean | undefined;
+        failOnLevels?: ("REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL")[] | undefined;
+        failOnSeverities?: ("critical" | "high" | "medium" | "low" | "info")[] | undefined;
+        maxAllowedRegressions?: number | undefined;
+    }, {
+        allowExpectedChanges?: boolean | undefined;
+        failOnLevels?: ("REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL")[] | undefined;
+        failOnSeverities?: ("critical" | "high" | "medium" | "low" | "info")[] | undefined;
+        maxAllowedRegressions?: number | undefined;
+    }>>;
+    invariants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        requirementLevel: z.ZodOptional<z.ZodEnum<["REQUIRED", "CONDITIONAL", "RECOMMENDED", "OPTIONAL"]>>;
+        severity: z.ZodOptional<z.ZodEnum<["critical", "high", "medium", "low", "info"]>>;
+    }, "strip", z.ZodTypeAny, {
+        requirementLevel?: "REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL" | undefined;
+        severity?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+        enabled?: boolean | undefined;
+    }, {
+        requirementLevel?: "REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL" | undefined;
+        severity?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+        enabled?: boolean | undefined;
+    }>>>;
+    policy: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    framework: z.ZodOptional<z.ZodObject<{
+        adapter: z.ZodOptional<z.ZodString>;
+        force: z.ZodOptional<z.ZodBoolean>;
+        entrypoint: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        adapter?: string | undefined;
+        force?: boolean | undefined;
+        entrypoint?: string | undefined;
+    }, {
+        adapter?: string | undefined;
+        force?: boolean | undefined;
+        entrypoint?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    framework?: {
+        adapter?: string | undefined;
+        force?: boolean | undefined;
+        entrypoint?: string | undefined;
+    } | undefined;
+    invariants?: Record<string, {
+        requirementLevel?: "REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL" | undefined;
+        severity?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+        enabled?: boolean | undefined;
+    }> | undefined;
+    version?: string | number | undefined;
+    profile?: "strict" | "balanced" | "startup" | "ecommerce" | "documentation" | "custom" | undefined;
+    regression?: {
+        allowExpectedChanges?: boolean | undefined;
+        failOnLevels?: ("REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL")[] | undefined;
+        failOnSeverities?: ("critical" | "high" | "medium" | "low" | "info")[] | undefined;
+        maxAllowedRegressions?: number | undefined;
+    } | undefined;
+    policy?: Record<string, any> | undefined;
+}, {
+    framework?: {
+        adapter?: string | undefined;
+        force?: boolean | undefined;
+        entrypoint?: string | undefined;
+    } | undefined;
+    invariants?: Record<string, {
+        requirementLevel?: "REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL" | undefined;
+        severity?: "critical" | "high" | "medium" | "low" | "info" | undefined;
+        enabled?: boolean | undefined;
+    }> | undefined;
+    version?: string | number | undefined;
+    profile?: "strict" | "balanced" | "startup" | "ecommerce" | "documentation" | "custom" | undefined;
+    regression?: {
+        allowExpectedChanges?: boolean | undefined;
+        failOnLevels?: ("REQUIRED" | "CONDITIONAL" | "RECOMMENDED" | "OPTIONAL")[] | undefined;
+        failOnSeverities?: ("critical" | "high" | "medium" | "low" | "info")[] | undefined;
+        maxAllowedRegressions?: number | undefined;
+    } | undefined;
+    policy?: Record<string, any> | undefined;
+}>;
 export declare class PolicyLoader {
     static resolvePolicy(projectDir?: string, explicitPath?: string): PolicyConfig;
-    static parseConfigFile(filePath: string): any;
-    static parseYaml(content: string): Record<string, any>;
-    private static parseScalarValue;
+    static parseConfigFile(filePath: string): unknown;
+    static parseYaml(content: string): Record<string, unknown>;
     static isRegressionBreachingPolicy(diff: InvariantDiffItem, policy: PolicyConfig): boolean;
+    static evaluatePolicyGate(diffs: InvariantDiffItem[], policy: PolicyConfig): {
+        pass: boolean;
+        breachingDiffs: InvariantDiffItem[];
+        totalBreaches: number;
+        maxAllowed: number;
+        verdict: string;
+    };
 }