seo-gravity-mcp 1.3.2 → 1.3.3

package/README.md

@@ -1,4 +1,4 @@
-# 🚀 SEO Gravity (v1.3.2)
+# 🚀 SEO Gravity (v1.3.3)
 
 <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: 3000
+        };
+    }
+    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.3',
         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
             };

package/dist/invariants/types.d.ts

@@ -7,7 +7,13 @@ 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;

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 isRegressionBreachingPolicy(diff: InvariantDiffItem, policy: PolicyConfig): boolean;
+    static evaluatePolicyGate(diffs: InvariantDiffItem[], policy: PolicyConfig): {
+        pass: boolean;
+        breachingDiffs: InvariantDiffItem[];
+        totalBreaches: number;
+        maxAllowed: number;
+        verdict: string;
+    };
 }

package/dist/policy/loader.js

@@ -1,6 +1,31 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import * as YAML from 'yaml';
+import { z } from 'zod';
 import { BUILTIN_PROFILES } from './profiles.js';
+export const InvariantRuleSchema = z.object({
+    enabled: z.boolean().optional(),
+    requirementLevel: z.enum(['REQUIRED', 'CONDITIONAL', 'RECOMMENDED', 'OPTIONAL']).optional(),
+    severity: z.enum(['critical', 'high', 'medium', 'low', 'info']).optional()
+});
+export const RegressionPolicySchema = z.object({
+    failOnLevels: z.array(z.enum(['REQUIRED', 'CONDITIONAL', 'RECOMMENDED', 'OPTIONAL'])).optional(),
+    failOnSeverities: z.array(z.enum(['critical', 'high', 'medium', 'low', 'info'])).optional(),
+    allowExpectedChanges: z.boolean().optional(),
+    maxAllowedRegressions: z.number().int().min(0).optional()
+});
+export const PolicyConfigSchema = z.object({
+    version: z.union([z.number(), z.string()]).optional(),
+    profile: z.enum(['strict', 'balanced', 'startup', 'ecommerce', 'documentation', 'custom']).optional(),
+    regression: RegressionPolicySchema.optional(),
+    invariants: z.record(InvariantRuleSchema).optional(),
+    policy: z.record(z.any()).optional(),
+    framework: z.object({
+        adapter: z.string().optional(),
+        force: z.boolean().optional(),
+        entrypoint: z.string().optional()
+    }).optional()
+});
 export class PolicyLoader {
     static resolvePolicy(projectDir = '.', explicitPath) {
         let rawConfig = null;
@@ -27,7 +52,7 @@ export class PolicyLoader {
         if (!rawConfig) {
             return baseProfile;
         }
-        // Normalize regression config (support snake_case from README and camelCase)
+        // Normalize snake_case regression options to camelCase
         const rawReg = rawConfig.regression || {};
         const normalizedRegression = {
             ...baseProfile.regression,
@@ -36,12 +61,12 @@ export class PolicyLoader {
             allowExpectedChanges: rawReg.allowExpectedChanges ?? rawReg.allow_expected_changes ?? baseProfile.regression?.allowExpectedChanges,
             maxAllowedRegressions: rawReg.maxAllowedRegressions ?? rawReg.max_allowed_regressions ?? baseProfile.regression?.maxAllowedRegressions
         };
-        // Normalize policy / invariants shortcuts
+        // Normalize invariant policy overrides
         const mergedInvariants = {
             ...baseProfile.invariants,
             ...(rawConfig.invariants || {})
         };
-        // Handle high-level policy shortcuts (e.g. policy: { canonical: required, sitemap: recommended })
+        // Support convenient high-level policy shortcuts (e.g. policy: { canonical: required, sitemap: recommended })
         const rawPolicy = rawConfig.policy || {};
         if (rawPolicy.canonical) {
             const lvl = String(rawPolicy.canonical).toUpperCase();
@@ -77,86 +102,18 @@ export class PolicyLoader {
         }
     }
     static parseYaml(content) {
-        const root = {};
-        const lines = content.split('\n');
-        let currentSection = null;
-        let currentSubsection = null;
-        for (let rawLine of lines) {
-            // Strip comments
-            const commentIdx = rawLine.indexOf('#');
-            if (commentIdx !== -1) {
-                rawLine = rawLine.slice(0, commentIdx);
-            }
-            const line = rawLine.replace(/\r/g, '');
-            if (!line.trim())
-                continue;
-            const indent = line.search(/\S/);
-            const trimmed = line.trim();
-            if (indent === 0) {
-                // Top-level key
-                const colonIdx = trimmed.indexOf(':');
-                if (colonIdx === -1)
-                    continue;
-                const key = trimmed.slice(0, colonIdx).trim();
-                const value = trimmed.slice(colonIdx + 1).trim();
-                if (value) {
-                    root[key] = this.parseScalarValue(value);
-                    currentSection = null;
-                }
-                else {
-                    root[key] = {};
-                    currentSection = key;
-                }
-                currentSubsection = null;
-            }
-            else if (indent === 2 && currentSection) {
-                // First-level nested key
-                const colonIdx = trimmed.indexOf(':');
-                if (colonIdx === -1)
-                    continue;
-                const key = trimmed.slice(0, colonIdx).trim();
-                const value = trimmed.slice(colonIdx + 1).trim();
-                if (value) {
-                    root[currentSection][key] = this.parseScalarValue(value);
-                    currentSubsection = null;
-                }
-                else {
-                    root[currentSection][key] = {};
-                    currentSubsection = key;
-                }
-            }
-            else if (indent >= 4 && currentSection && currentSubsection) {
-                // Second-level nested key
-                const colonIdx = trimmed.indexOf(':');
-                if (colonIdx === -1)
-                    continue;
-                const key = trimmed.slice(0, colonIdx).trim();
-                const value = trimmed.slice(colonIdx + 1).trim();
-                root[currentSection][currentSubsection][key] = this.parseScalarValue(value);
-            }
+        try {
+            const parsed = YAML.parse(content);
+            return (typeof parsed === 'object' && parsed !== null) ? parsed : {};
         }
-        return root;
-    }
-    static parseScalarValue(val) {
-        const clean = val.trim();
-        if (clean.startsWith('[') && clean.endsWith(']')) {
-            return clean
-                .slice(1, -1)
-                .split(',')
-                .map(s => s.trim().replace(/^['"]|['"]$/g, ''))
-                .filter(Boolean);
+        catch {
+            return {};
         }
-        if (clean === 'true')
-            return true;
-        if (clean === 'false')
-            return false;
-        if (clean === 'null')
-            return null;
-        if (!isNaN(Number(clean)) && clean !== '')
-            return Number(clean);
-        return clean.replace(/^['"]|['"]$/g, '');
     }
     static isRegressionBreachingPolicy(diff, policy) {
+        if (diff.status === 'EXPECTED_CHANGE') {
+            return policy.regression?.allowExpectedChanges === false;
+        }
         if (diff.status !== 'NEW_REGRESSION')
             return false;
         const invOverride = policy.invariants?.[diff.invariantId];
@@ -171,4 +128,20 @@ export class PolicyLoader {
         const severityBreached = failSeverities.includes(severity);
         return levelBreached && severityBreached;
     }
+    static evaluatePolicyGate(diffs, policy) {
+        const breachingDiffs = diffs.filter(d => this.isRegressionBreachingPolicy(d, policy));
+        const totalBreaches = breachingDiffs.length;
+        const maxAllowed = policy.regression?.maxAllowedRegressions ?? 0;
+        const pass = totalBreaches <= maxAllowed;
+        const verdict = pass
+            ? `✅ PASSED (Policy: ${policy.profile}): ${totalBreaches} breach(es) within allowed threshold (max: ${maxAllowed}).`
+            : `🚨 FAILED (Policy: ${policy.profile}): ${totalBreaches} invariant regression(s) breached policy (max allowed: ${maxAllowed}).`;
+        return {
+            pass,
+            breachingDiffs,
+            totalBreaches,
+            maxAllowed,
+            verdict
+        };
+    }
 }

package/dist/test.js

@@ -10,6 +10,7 @@ import { defaultCacheManager } from './utils/cacheManager.js';
 import { exportFindingsToSarif } from './utils/sarifExporter.js';
 import { defaultInvariantRegistry } from './invariants/registry.js';
 import { PolicyLoader } from './policy/loader.js';
+import { BUILTIN_PROFILES } from './policy/profiles.js';
 import { formatPrCommentMarkdown } from './utils/prCommentFormatter.js';
 import { analyzeSemanticFileChange } from './utils/gitDiffEngine.js';
 import { compareSnapshots } from './utils/snapshotEngine.js';
@@ -57,7 +58,7 @@ regression:
   fail_on_levels: [REQUIRED, CONDITIONAL, RECOMMENDED]
   fail_on_severities: [critical, high, medium]
   allow_expected_changes: false
-  max_allowed_regressions: 0
+  max_allowed_regressions: 2
 `;
     const parsedYaml = PolicyLoader.parseYaml(mockYaml);
     assert.equal(parsedYaml.version, 1);
@@ -77,7 +78,7 @@ regression:
         createdAt: new Date().toISOString(),
         projectPath: '.',
         frameworkInfo: { framework: 'nextjs-app-router', name: 'Next.js', version: '14.0.0', confidence: 1.0 },
-        discoveredRoutes: [],
+        discoveredRoutes: [{ routePath: '/deleted-route', routeType: 'page', sourceFilePath: 'app/deleted/page.tsx', hasHeadComponent: false }],
         scores: { overallHealth: 100, overallConfidence: 'High', totalEvidenceSignals: 10, technical: { score: 100, state: 'healthy' }, content: { score: 100, state: 'healthy' }, discoverability: { score: 100, state: 'healthy' }, authority: { score: 100, state: 'healthy' }, entity: { score: 100, state: 'healthy' }, performance: { score: 100, state: 'healthy' }, aiReadiness: { score: 100, state: 'healthy' } },
         findings: [],
         invariants: [
@@ -85,19 +86,86 @@ regression:
         ],
         routeMappings: []
     };
-    const fakeCurrent = {
+    const fakeCurrentActiveRouteMissingEvidence = {
         ...fakeBaseline,
         snapshotId: 'snap_curr',
-        invariants: [] // Invariant disappeared!
+        discoveredRoutes: [{ routePath: '/deleted-route', routeType: 'page', sourceFilePath: 'app/deleted/page.tsx', hasHeadComponent: false }],
+        invariants: [] // Active route missing invariant evidence
     };
-    const diffReport = compareSnapshots(fakeBaseline, fakeCurrent);
-    assert.equal(diffReport.invariantDiffs?.length, 1);
-    assert.equal(diffReport.invariantDiffs[0].status, 'NEW_REGRESSION', 'Disappearing satisfied invariant must trigger regression');
-    console.log('   ✅ Invariant Union Diffing: Disappearing satisfied invariant correctly flagged as NEW_REGRESSION.');
+    const diffReport1 = compareSnapshots(fakeBaseline, fakeCurrentActiveRouteMissingEvidence);
+    assert.equal(diffReport1.invariantDiffs?.length, 1);
+    assert.equal(diffReport1.invariantDiffs[0].status, 'NEW_REGRESSION', 'Disappearing satisfied invariant on active route must trigger regression');
+    const fakeCurrentRouteDeleted = {
+        ...fakeBaseline,
+        snapshotId: 'snap_curr',
+        discoveredRoutes: [], // Route intentionally removed from project
+        invariants: []
+    };
+    const diffReport2 = compareSnapshots(fakeBaseline, fakeCurrentRouteDeleted);
+    assert.equal(diffReport2.invariantDiffs?.length, 1);
+    assert.equal(diffReport2.invariantDiffs[0].status, 'EXPECTED_CHANGE', 'Disappearing invariant for removed route must be tagged EXPECTED_CHANGE');
+    console.log('   ✅ Invariant Union Diffing: Active route missing evidence -> NEW_REGRESSION; Deleted route -> EXPECTED_CHANGE.');
+    // -------------------------------------------------------------
+    // Test 5: Policy-Matrix Evaluation
+    // -------------------------------------------------------------
+    console.log('\n5️⃣ Testing Policy Matrix Evaluation Across Profiles & Thresholds...');
+    const lowRecDiff = {
+        invariantId: 'INV-LLMS-TXT',
+        logicalPageId: 'site_root',
+        url: '/llms.txt',
+        status: 'NEW_REGRESSION',
+        baselineSatisfied: true,
+        currentSatisfied: false,
+        requirementLevel: 'RECOMMENDED',
+        severity: 'low',
+        message: 'llms.txt missing'
+    };
+    const criticalReqDiff = {
+        invariantId: 'INV-HTTP-200',
+        logicalPageId: 'page_home',
+        url: '/',
+        status: 'NEW_REGRESSION',
+        baselineSatisfied: true,
+        currentSatisfied: false,
+        requirementLevel: 'REQUIRED',
+        severity: 'critical',
+        message: 'HTTP 500 error'
+    };
+    // Profile strict fails on RECOMMENDED + low
+    assert.equal(PolicyLoader.isRegressionBreachingPolicy(lowRecDiff, BUILTIN_PROFILES.strict), true);
+    // Profile balanced ignores RECOMMENDED + low
+    assert.equal(PolicyLoader.isRegressionBreachingPolicy(lowRecDiff, BUILTIN_PROFILES.balanced), false);
+    // Profile startup ignores RECOMMENDED + low
+    assert.equal(PolicyLoader.isRegressionBreachingPolicy(lowRecDiff, BUILTIN_PROFILES.startup), false);
+    // All profiles fail on REQUIRED + critical
+    assert.equal(PolicyLoader.isRegressionBreachingPolicy(criticalReqDiff, BUILTIN_PROFILES.strict), true);
+    assert.equal(PolicyLoader.isRegressionBreachingPolicy(criticalReqDiff, BUILTIN_PROFILES.balanced), true);
+    assert.equal(PolicyLoader.isRegressionBreachingPolicy(criticalReqDiff, BUILTIN_PROFILES.startup), true);
+    // Invariant override: disabled policy
+    const customPolicy = {
+        ...BUILTIN_PROFILES.strict,
+        invariants: {
+            'INV-HTTP-200': { enabled: false }
+        }
+    };
+    assert.equal(PolicyLoader.isRegressionBreachingPolicy(criticalReqDiff, customPolicy), false);
+    // Gate evaluation with maxAllowedRegressions
+    const gatePolicy = {
+        ...BUILTIN_PROFILES.strict,
+        regression: {
+            ...BUILTIN_PROFILES.strict.regression,
+            maxAllowedRegressions: 1
+        }
+    };
+    const gatePass = PolicyLoader.evaluatePolicyGate([criticalReqDiff], gatePolicy);
+    assert.equal(gatePass.pass, true, '1 breach with maxAllowedRegressions=1 must pass');
+    const gateFail = PolicyLoader.evaluatePolicyGate([criticalReqDiff, criticalReqDiff], gatePolicy);
+    assert.equal(gateFail.pass, false, '2 breaches with maxAllowedRegressions=1 must fail');
+    console.log('   ✅ Policy Matrix: Strict, Balanced, Startup, Invariant Overrides, and maxAllowedRegressions verified.');
     // -------------------------------------------------------------
-    // Test 5: Semantic SEO Diff & Risk Assessment (P1)
+    // Test 6: Semantic SEO Diff & Risk Assessment (P1)
     // -------------------------------------------------------------
-    console.log('\n5️⃣ Testing Semantic SEO Git Diff Engine...');
+    console.log('\n6️⃣ Testing Semantic SEO Git Diff Engine...');
     const nextAppPath = path.join(FIXTURES_DIR, 'nextjs-app');
     const semChange = analyzeSemanticFileChange('app/page.tsx', nextAppPath);
     assert.equal(semChange.affectsMetadata, true);
@@ -106,9 +174,9 @@ regression:
     assert.ok(semChange.likelyAffectedInvariants.includes('INV-TITLE-PRESENT'));
     console.log(`   ✅ Semantic Analysis for app/page.tsx: Risk=${semChange.riskLevel}`);
     // -------------------------------------------------------------
-    // Test 6: Developer-Native PR Comment Formatter (P1)
+    // Test 7: Developer-Native PR Comment Formatter (P1)
     // -------------------------------------------------------------
-    console.log('\n6️⃣ Testing Developer-Native GitHub PR Comment Formatter...');
+    console.log('\n7️⃣ Testing Developer-Native GitHub PR Comment Formatter...');
     const snapResult = await createSnapshotTool(nextAppPath);
     const regCheck = await checkRegression(nextAppPath, snapResult.snapshot);
     assert.equal(regCheck.pass, true);
@@ -117,24 +185,26 @@ regression:
     assert.ok(prComment.includes('PASSED'));
     console.log(`   ✅ PR Markdown Generated (${prComment.length} characters)`);
     // -------------------------------------------------------------
-    // Test 7: 17 Framework Adapters Coverage
+    // Test 8: 17 Framework Adapters + Unknown Adapter Coverage
     // -------------------------------------------------------------
-    console.log('\n7️⃣ Testing 17 Framework Adapters Coverage...');
+    console.log('\n8️⃣ Testing Framework Adapters & Unknown Fallback...');
     const adapters = defaultAdapterRegistry.getAllAdapters();
-    assert.equal(adapters.length, 17, 'Must have exactly 17 adapters loaded');
-    console.log(`   ✅ ${adapters.length} Framework Adapters Loaded.`);
+    assert.equal(adapters.length, 17, 'Must have exactly 17 standard adapters loaded');
+    const emptyFolderAdapter = defaultAdapterRegistry.getAdapterForProject('non_existent_folder_abc');
+    assert.equal(emptyFolderAdapter.id, 'unknown');
+    console.log(`   ✅ 17 Adapters Loaded + UnknownAdapter fallback verified.`);
     // -------------------------------------------------------------
-    // Test 8: SARIF v2.1.0 Exporter
+    // Test 9: SARIF v2.1.0 Exporter
     // -------------------------------------------------------------
-    console.log('\n8️⃣ Testing SARIF v2.1.0 Exporter for GitHub Security Tab...');
+    console.log('\n9️⃣ Testing SARIF v2.1.0 Exporter for GitHub Security Tab...');
     const sarif = exportFindingsToSarif(snapResult.snapshot.findings, nextAppPath);
     assert.equal(sarif.version, '2.1.0');
     assert.equal(sarif.runs[0].tool.driver.name, 'SEO Gravity');
     console.log(`   ✅ SARIF Report Generated: Driver=${sarif.runs[0].tool.driver.name}, Version=${sarif.version}`);
     // -------------------------------------------------------------
-    // Test 9: Content-Hash Cache Manager with Provenance & LRU
+    // Test 10: Content-Hash Cache Manager with Provenance & LRU
     // -------------------------------------------------------------
-    console.log('\n9️⃣ Testing Cache Manager with Provenance & LRU...');
+    console.log('\n🔟 Testing Cache Manager with Provenance & LRU...');
     const cacheKey = defaultCacheManager.computeKey('test_ast', { file: 'page.tsx' });
     defaultCacheManager.set(cacheKey, { parsed: true }, 10000, 'typescript_ast');
     const cachedVal = defaultCacheManager.getWithMetadata(cacheKey);

package/dist/tools/orchestration.js

@@ -295,15 +295,11 @@ export async function checkRegression(projectPath, baselineSnapshot, baseUrl, po
     const currentSnapshot = await createProjectSnapshot(projectPath, { baseUrl });
     const report = await compareSnapshotsTool(baselineSnapshot, currentSnapshot);
     const invariantDiffs = report.invariantDiffs || [];
-    const policyBreaches = invariantDiffs.filter(d => PolicyLoader.isRegressionBreachingPolicy(d, policy));
-    const pass = policyBreaches.length === 0;
-    const verdict = pass
-        ? `✅ PASSED (Policy: ${policy.profile}): No policy-breaching SEO invariant regressions detected.`
-        : `🚨 FAILED (Policy: ${policy.profile}): ${policyBreaches.length} invariant regression(s) breached policy thresholds.`;
+    const gateResult = PolicyLoader.evaluatePolicyGate(invariantDiffs, policy);
     return {
         schemaVersion: 'seo.gravity/v1',
-        pass,
-        verdict,
+        pass: gateResult.pass,
+        verdict: gateResult.verdict,
         policyProfile: policy.profile,
         regressionReport: report
     };

package/dist/types/evidence.d.ts

@@ -10,8 +10,8 @@ export interface AstEvidence extends BaseEvidence {
     sourceFile: string;
     symbolName?: string;
     nodeType?: string;
-    startLine: number;
-    endLine: number;
+    startLine?: number;
+    endLine?: number;
     startColumn?: number;
     endColumn?: number;
     codeSnippet?: string;

package/dist/types/seo.d.ts

@@ -256,6 +256,8 @@ export interface ContentBrief {
 }
 export interface JsRenderingDiffReport {
     url: string;
+    executionMode: 'static_dom_normalization';
+    domParser: string;
     serverHtmlLength: number;
     hydratedDomLength: number;
     contentDifferencePercent: number;

package/dist/utils/astLocator.d.ts

@@ -4,6 +4,8 @@ export interface ASTMetadataInspection {
     hasGenerateMetadata: boolean;
     hasCanonicalDeclaration: boolean;
     hasSchemaMarkup: boolean;
+    detectionMethod: 'ast_exact' | 'regex_heuristic';
+    confidence: number;
     metadataRange?: ASTSourceRange;
     canonicalRange?: ASTSourceRange;
     schemaRange?: ASTSourceRange;

package/dist/utils/astLocator.js

@@ -7,7 +7,9 @@ export function inspectSourceFileAST(filePath) {
             hasMetadataExport: false,
             hasGenerateMetadata: false,
             hasCanonicalDeclaration: false,
-            hasSchemaMarkup: false
+            hasSchemaMarkup: false,
+            detectionMethod: 'ast_exact',
+            confidence: 1.0
         };
     }
     const content = fs.readFileSync(filePath, 'utf-8');
@@ -109,24 +111,31 @@ export function inspectSourceFileAST(filePath) {
         ts.forEachChild(node, visit);
     };
     visit(sourceFile);
+    let regexFallbackUsed = false;
     // Strict fallback regex detection if AST missed non-standard export structures
     if (!hasMetadataExport && /export\s+const\s+metadata\b/i.test(content)) {
         hasMetadataExport = true;
+        regexFallbackUsed = true;
     }
     if (!hasGenerateMetadata && /export\s+(async\s+)?function\s+generateMetadata\b/i.test(content)) {
         hasGenerateMetadata = true;
+        regexFallbackUsed = true;
     }
     if (!hasCanonicalDeclaration && (/(rel=["']canonical["']|alternates:\s*\{[^}]*canonical:)/i.test(content))) {
         hasCanonicalDeclaration = true;
+        regexFallbackUsed = true;
     }
     if (!hasSchemaMarkup && /application\/ld\+json/i.test(content)) {
         hasSchemaMarkup = true;
+        regexFallbackUsed = true;
     }
     return {
         hasMetadataExport,
         hasGenerateMetadata,
         hasCanonicalDeclaration,
         hasSchemaMarkup,
+        detectionMethod: regexFallbackUsed ? 'regex_heuristic' : 'ast_exact',
+        confidence: regexFallbackUsed ? 0.85 : 1.0,
         metadataRange,
         canonicalRange,
         schemaRange,

package/dist/utils/jsdomRenderer.js

@@ -65,6 +65,8 @@ export async function compareServerVsClientDom(url) {
     }
     return {
         url,
+        executionMode: 'static_dom_normalization',
+        domParser: 'jsdom_html_parser',
         serverHtmlLength: serverLength,
         hydratedDomLength: clientLength,
         contentDifferencePercent: percentDiff,

package/dist/utils/projectScanner.d.ts

@@ -2,5 +2,5 @@ import { ProjectFrameworkInfo, DiscoveredRoute, RouteSourceMapping } from '../ty
 import { FrameworkAdapter } from '../adapters/types.js';
 export declare function getProjectAdapter(projectDir: string): FrameworkAdapter;
 export declare function detectFramework(projectDir: string): ProjectFrameworkInfo;
-export declare function discoverRoutes(projectDir: string, _frameworkInfo?: ProjectFrameworkInfo): DiscoveredRoute[];
+export declare function discoverRoutes(projectDir: string, frameworkInfo?: ProjectFrameworkInfo): DiscoveredRoute[];
 export declare function mapUrlToRouteSource(targetUrl: string, discoveredRoutes: DiscoveredRoute[], projectDir?: string): RouteSourceMapping;

package/dist/utils/projectScanner.js

@@ -9,9 +9,11 @@ export function detectFramework(projectDir) {
     const adapter = defaultAdapterRegistry.getAdapterForProject(resolvedDir);
     return adapter.getProjectInfo(resolvedDir);
 }
-export function discoverRoutes(projectDir, _frameworkInfo) {
+export function discoverRoutes(projectDir, frameworkInfo) {
     const resolvedDir = path.resolve(projectDir);
-    const adapter = defaultAdapterRegistry.getAdapterForProject(resolvedDir);
+    const adapter = frameworkInfo?.framework
+        ? (defaultAdapterRegistry.getAdapterById(frameworkInfo.framework) || defaultAdapterRegistry.getAdapterForProject(resolvedDir))
+        : defaultAdapterRegistry.getAdapterForProject(resolvedDir);
     return adapter.discoverRoutes(resolvedDir);
 }
 export function mapUrlToRouteSource(targetUrl, discoveredRoutes, projectDir = '.') {

package/dist/utils/snapshotEngine.d.ts

@@ -5,7 +5,7 @@ export interface CreateSnapshotOptions {
     maxPagesToAudit?: number;
     includeCrawlGraph?: boolean;
 }
-export declare function computeLogicalPageId(urlOrPath: string): string;
+export declare function computeLogicalPageId(urlOrPath: string, baseUrl?: 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;

package/dist/utils/snapshotEngine.js

@@ -5,20 +5,9 @@ import { inspectSourceFileAST } from './astLocator.js';
 import { defaultInvariantRegistry } from '../invariants/registry.js';
 import * as path from 'path';
 import { execSync } from 'child_process';
-import * as crypto from 'crypto';
-export function computeLogicalPageId(urlOrPath) {
-    let clean = urlOrPath;
-    let origin = 'default';
-    try {
-        if (clean.startsWith('http')) {
-            const u = new URL(clean);
-            origin = u.origin.toLowerCase();
-            clean = u.pathname;
-        }
-    }
-    catch { }
-    clean = clean.replace(/\/$/, '') || '/';
-    return 'page_' + crypto.createHash('sha256').update(`${origin}:${clean}`).digest('hex').substring(0, 12);
+import { computeNormalizedLogicalPageId } from './urlNormalizer.js';
+export function computeLogicalPageId(urlOrPath, baseUrl) {
+    return computeNormalizedLogicalPageId(urlOrPath, baseUrl);
 }
 export function extractGitMetadata(projectDir) {
     try {
@@ -170,13 +159,18 @@ export async function createProjectSnapshot(projectPath, options = {}) {
             const pageId = computeLogicalPageId(route.routePath);
             const fullSrcPath = path.join(resolvedPath, route.sourceFilePath);
             const ast = inspectSourceFileAST(fullSrcPath);
-            // Metadata invariant
+            // Metadata & Title invariant (disaggregated)
             const hasMeta = ast.hasMetadataExport || ast.hasGenerateMetadata || route.hasHeadComponent;
+            const hasTitle = Boolean(ast.extractedTitle || route.hasHeadComponent);
             const titleInv = defaultInvariantRegistry.evaluateContext('INV-TITLE-PRESENT', {
                 url: route.routePath,
                 logicalPageId: pageId,
+                sourceFilePath: route.sourceFilePath,
+                sourceRange: ast.metadataRange,
+                hasTitle,
                 hasMetadata: hasMeta,
-                extractedTitle: ast.extractedTitle
+                extractedTitle: ast.extractedTitle,
+                hasDescription: Boolean(ast.extractedDescription)
             }, {
                 analyzer: 'astLocator',
                 source: 'ast_inspection',
@@ -190,6 +184,8 @@ export async function createProjectSnapshot(projectPath, options = {}) {
             const canonicalInv = defaultInvariantRegistry.evaluateContext('INV-CANONICAL-RESOLVES', {
                 url: route.routePath,
                 logicalPageId: pageId,
+                sourceFilePath: route.sourceFilePath,
+                sourceRange: ast.canonicalRange,
                 hasCanonical,
                 extractedCanonical: ast.extractedCanonical
             }, {
@@ -211,11 +207,9 @@ export async function createProjectSnapshot(projectPath, options = {}) {
                     evidenceType: 'observed',
                     evidence: `File '${route.sourceFilePath}' has no metadata declaration.`,
                     affectedUrl: route.routePath,
-                    sourceLocation: {
-                        filePath: route.sourceFilePath,
-                        startLine: 1,
-                        endLine: 1
-                    },
+                    sourceLocation: ast.metadataRange
+                        ? { filePath: route.sourceFilePath, startLine: ast.metadataRange.startLine, endLine: ast.metadataRange.endLine }
+                        : { filePath: route.sourceFilePath },
                     sourceRange: ast.metadataRange,
                     likelyRootCause: 'Page component does not declare SEO metadata export.',
                     recommendation: `Add metadata export or title tag in ${route.sourceFilePath}.`,
@@ -238,7 +232,9 @@ export async function createProjectSnapshot(projectPath, options = {}) {
                     evidenceType: 'observed',
                     evidence: `Route '${route.routePath}' (${route.sourceFilePath}) does not declare a canonical URL.`,
                     affectedUrl: route.routePath,
-                    sourceLocation: { filePath: route.sourceFilePath },
+                    sourceLocation: ast.canonicalRange
+                        ? { filePath: route.sourceFilePath, startLine: ast.canonicalRange.startLine, endLine: ast.canonicalRange.endLine }
+                        : { filePath: route.sourceFilePath },
                     sourceRange: ast.canonicalRange,
                     likelyRootCause: 'Page does not declare its canonical master URL, risking duplicate indexing.',
                     recommendation: `Add canonical URL declaration to ${route.sourceFilePath}.`,
@@ -283,7 +279,15 @@ export async function createProjectSnapshot(projectPath, options = {}) {
                 }
             }
         }
-        catch { }
+        catch (err) {
+            crawlGraphSummary = {
+                state: 'FAILED',
+                error: err.message || 'Crawl error',
+                baseUrl,
+                pagesCrawled: 0,
+                orphanPages: []
+            };
+        }
     }
     // 4. Compute Multidimensional Scores
     const scores = calculateMultiDimensionalScores(findings, {
@@ -390,19 +394,39 @@ export function compareSnapshots(baseline, current) {
         }
         else if (bInv && !cInv) {
             // Invariant disappeared in current snapshot!
-            status = bInv.satisfied ? 'NEW_REGRESSION' : 'RESOLVED';
-            invariantDiffs.push({
-                invariantId: bInv.id,
-                logicalPageId: bInv.logicalPageId,
-                url: bInv.url,
-                status,
-                baselineSatisfied: bInv.satisfied,
-                currentSatisfied: false,
-                requirementLevel: bInv.requirementLevel || 'REQUIRED',
-                severity: bInv.severity || 'high',
-                evidence: bInv.evidence,
-                message: `${bInv.description}: Invariant disappeared (${status})`
-            });
+            const currentRouteStillExists = (current.discoveredRoutes || []).some(r => r.routePath === bInv.url);
+            if (currentRouteStillExists) {
+                // Active route lost its invariant evidence -> Genuine regression
+                status = bInv.satisfied ? 'NEW_REGRESSION' : 'RESOLVED';
+                invariantDiffs.push({
+                    invariantId: bInv.id,
+                    logicalPageId: bInv.logicalPageId,
+                    url: bInv.url,
+                    status,
+                    baselineSatisfied: bInv.satisfied,
+                    currentSatisfied: false,
+                    requirementLevel: bInv.requirementLevel || 'REQUIRED',
+                    severity: bInv.severity || 'high',
+                    evidence: bInv.evidence,
+                    message: `${bInv.description}: Missing invariant evidence for active route (${status})`
+                });
+            }
+            else {
+                // Route was intentionally deleted or removed -> Expected change
+                status = 'EXPECTED_CHANGE';
+                invariantDiffs.push({
+                    invariantId: bInv.id,
+                    logicalPageId: bInv.logicalPageId,
+                    url: bInv.url,
+                    status,
+                    baselineSatisfied: bInv.satisfied,
+                    currentSatisfied: false,
+                    requirementLevel: bInv.requirementLevel || 'REQUIRED',
+                    severity: 'low',
+                    evidence: bInv.evidence,
+                    message: `${bInv.description}: Route was removed (EXPECTED_CHANGE)`
+                });
+            }
         }
     }
     // Score deltas

package/dist/utils/urlNormalizer.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeUrl(rawUrl: string, baseUrl?: string): string;
+export declare function computeNormalizedLogicalPageId(urlOrPath: string, baseUrl?: string): string;

package/dist/utils/urlNormalizer.js

@@ -0,0 +1,60 @@
+import * as crypto from 'crypto';
+export function normalizeUrl(rawUrl, baseUrl) {
+    if (!rawUrl)
+        return '/';
+    try {
+        let resolved;
+        if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
+            resolved = new URL(rawUrl);
+        }
+        else if (baseUrl) {
+            resolved = new URL(rawUrl, baseUrl);
+        }
+        else {
+            resolved = new URL(rawUrl, 'http://localhost');
+        }
+        // Lowercase hostname
+        resolved.hostname = resolved.hostname.toLowerCase();
+        // Strip default ports
+        if ((resolved.protocol === 'http:' && resolved.port === '80') ||
+            (resolved.protocol === 'https:' && resolved.port === '443')) {
+            resolved.port = '';
+        }
+        // Normalize path (remove duplicate slashes, keep root or trim trailing slash)
+        let pathname = resolved.pathname.replace(/\/+/g, '/');
+        if (pathname.length > 1 && pathname.endsWith('/')) {
+            pathname = pathname.slice(0, -1);
+        }
+        resolved.pathname = pathname;
+        // Sort query parameters deterministically
+        const params = Array.from(resolved.searchParams.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+        resolved.search = '';
+        for (const [k, v] of params) {
+            resolved.searchParams.append(k, v);
+        }
+        // Remove hash/fragment for canonical logical page identity
+        resolved.hash = '';
+        if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://') || baseUrl) {
+            return resolved.toString();
+        }
+        return resolved.pathname + resolved.search;
+    }
+    catch {
+        return rawUrl.trim().replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+    }
+}
+export function computeNormalizedLogicalPageId(urlOrPath, baseUrl) {
+    const norm = normalizeUrl(urlOrPath, baseUrl);
+    let origin = 'default';
+    let pathOnly = norm;
+    try {
+        if (norm.startsWith('http')) {
+            const u = new URL(norm);
+            origin = u.origin;
+            pathOnly = u.pathname + u.search;
+        }
+    }
+    catch { }
+    const payload = `${origin}:${pathOnly}`;
+    return 'page_' + crypto.createHash('sha256').update(payload).digest('hex').substring(0, 12);
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.3.2";
+export declare const VERSION = "1.3.3";
 export declare const PACKAGE_NAME = "seo-gravity-mcp";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '1.3.2';
+export const VERSION = '1.3.3';
 export const PACKAGE_NAME = 'seo-gravity-mcp';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-gravity-mcp",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "SEO Engineering Infrastructure Layer for AI Coding Agents and CI/CD Pipelines",
   "main": "dist/index.js",
   "type": "module",
@@ -37,6 +37,7 @@
     "cheerio": "^1.0.0",
     "fast-xml-parser": "^5.0.8",
     "jsdom": "^26.0.0",
+    "yaml": "^2.9.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {