seo-gravity-mcp 1.3.2 → 1.3.4

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;
@@ -22,153 +47,115 @@ export class PolicyLoader {
                 }
             }
         }
-        const baseProfileName = rawConfig?.profile || 'balanced';
-        const baseProfile = BUILTIN_PROFILES[baseProfileName] || BUILTIN_PROFILES.balanced;
         if (!rawConfig) {
-            return baseProfile;
+            return BUILTIN_PROFILES.balanced;
         }
-        // Normalize regression config (support snake_case from README and camelCase)
-        const rawReg = rawConfig.regression || {};
+        const parsed = PolicyConfigSchema.safeParse(rawConfig);
+        if (!parsed.success) {
+            const details = parsed.error.issues
+                .map(issue => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+                .join('; ');
+            throw new Error(`Invalid SEO Gravity policy configuration: ${details}`);
+        }
+        const config = parsed.data;
+        const baseProfileName = config.profile || 'balanced';
+        const baseProfile = (baseProfileName !== 'custom' && BUILTIN_PROFILES[baseProfileName])
+            ? BUILTIN_PROFILES[baseProfileName]
+            : BUILTIN_PROFILES.balanced;
+        const rawReg = config.regression || {};
         const normalizedRegression = {
             ...baseProfile.regression,
-            failOnLevels: rawReg.failOnLevels || rawReg.fail_on_levels || baseProfile.regression?.failOnLevels,
-            failOnSeverities: rawReg.failOnSeverities || rawReg.fail_on_severities || baseProfile.regression?.failOnSeverities,
-            allowExpectedChanges: rawReg.allowExpectedChanges ?? rawReg.allow_expected_changes ?? baseProfile.regression?.allowExpectedChanges,
-            maxAllowedRegressions: rawReg.maxAllowedRegressions ?? rawReg.max_allowed_regressions ?? baseProfile.regression?.maxAllowedRegressions
+            failOnLevels: rawReg.failOnLevels || baseProfile.regression?.failOnLevels,
+            failOnSeverities: rawReg.failOnSeverities || baseProfile.regression?.failOnSeverities,
+            allowExpectedChanges: rawReg.allowExpectedChanges ?? baseProfile.regression?.allowExpectedChanges,
+            maxAllowedRegressions: rawReg.maxAllowedRegressions ?? baseProfile.regression?.maxAllowedRegressions
         };
-        // Normalize policy / invariants shortcuts
         const mergedInvariants = {
             ...baseProfile.invariants,
-            ...(rawConfig.invariants || {})
+            ...(config.invariants || {})
         };
-        // Handle high-level policy shortcuts (e.g. policy: { canonical: required, sitemap: recommended })
-        const rawPolicy = rawConfig.policy || {};
-        if (rawPolicy.canonical) {
-            const lvl = String(rawPolicy.canonical).toUpperCase();
+        const rawPolicy = config.policy || {};
+        if (rawPolicy.canonical !== undefined) {
+            const parsedLevel = String(rawPolicy.canonical).toUpperCase();
+            if (!['REQUIRED', 'CONDITIONAL', 'RECOMMENDED', 'OPTIONAL'].includes(parsedLevel)) {
+                throw new Error(`Invalid policy.canonical requirement level: '${rawPolicy.canonical}'.`);
+            }
+            const lvl = parsedLevel;
             mergedInvariants['INV-CANONICAL-RESOLVES'] = { requirementLevel: lvl, severity: 'high', enabled: true };
         }
-        if (rawPolicy.sitemap) {
-            const lvl = String(rawPolicy.sitemap).toUpperCase();
+        if (rawPolicy.sitemap !== undefined) {
+            const parsedLevel = String(rawPolicy.sitemap).toUpperCase();
+            if (!['REQUIRED', 'CONDITIONAL', 'RECOMMENDED', 'OPTIONAL'].includes(parsedLevel)) {
+                throw new Error(`Invalid policy.sitemap requirement level: '${rawPolicy.sitemap}'.`);
+            }
+            const lvl = parsedLevel;
             mergedInvariants['INV-SITEMAP-PRESENT'] = { requirementLevel: lvl, severity: 'medium', enabled: true };
         }
-        if (rawPolicy.llms_txt || rawPolicy.llmsTxt) {
-            const lvl = String(rawPolicy.llms_txt || rawPolicy.llmsTxt).toUpperCase();
+        if (rawPolicy.llms_txt !== undefined || rawPolicy.llmsTxt !== undefined) {
+            const rawLevel = rawPolicy.llms_txt ?? rawPolicy.llmsTxt;
+            const parsedLevel = String(rawLevel).toUpperCase();
+            if (!['REQUIRED', 'CONDITIONAL', 'RECOMMENDED', 'OPTIONAL'].includes(parsedLevel)) {
+                throw new Error(`Invalid policy.llms_txt requirement level: '${rawLevel}'.`);
+            }
+            const lvl = parsedLevel;
             mergedInvariants['INV-LLMS-TXT'] = { requirementLevel: lvl, severity: 'low', enabled: true };
         }
-        const merged = {
-            version: rawConfig.version || baseProfile.version,
+        return {
+            version: typeof config.version === 'number' ? config.version : (Number(config.version) || baseProfile.version),
             profile: baseProfileName,
             regression: normalizedRegression,
             invariants: mergedInvariants,
-            framework: rawConfig.framework
+            framework: config.framework
         };
-        return merged;
     }
     static parseConfigFile(filePath) {
-        try {
-            const content = fs.readFileSync(filePath, 'utf-8');
-            if (filePath.endsWith('.json')) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        if (filePath.endsWith('.json')) {
+            try {
                 return JSON.parse(content);
             }
+            catch (err) {
+                throw new Error(`Invalid JSON policy configuration '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        try {
             return this.parseYaml(content);
         }
-        catch {
-            return null;
+        catch (err) {
+            throw new Error(`Invalid YAML policy configuration '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     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);
-            }
+        const parsed = YAML.parse(content);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Policy YAML root must be an object.');
         }
-        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);
-        }
-        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, '');
+        return parsed;
     }
     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];
         if (invOverride && invOverride.enabled === false) {
-            return false; // Explicitly disabled by project policy
+            return false;
         }
         const level = invOverride?.requirementLevel || diff.requirementLevel || 'REQUIRED';
         const severity = invOverride?.severity || diff.severity || 'high';
         const failLevels = policy.regression?.failOnLevels || ['REQUIRED', 'CONDITIONAL'];
         const failSeverities = policy.regression?.failOnSeverities || ['critical', 'high'];
-        const levelBreached = failLevels.includes(level);
-        const severityBreached = failSeverities.includes(severity);
-        return levelBreached && severityBreached;
+        return failLevels.includes(level) && failSeverities.includes(severity);
+    }
+    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/policy/profiles.d.ts

@@ -1,2 +1,2 @@
-import { PolicyConfig, PolicyProfileName } from './types.js';
-export declare const BUILTIN_PROFILES: Record<PolicyProfileName, PolicyConfig>;
+import { PolicyConfig, BuiltinProfileName } from './types.js';
+export declare const BUILTIN_PROFILES: Record<BuiltinProfileName, PolicyConfig>;

package/dist/policy/types.d.ts

@@ -1,5 +1,6 @@
 import { RequirementLevel, InvariantSeverity } from '../types/canonical.js';
-export type PolicyProfileName = 'strict' | 'balanced' | 'startup' | 'ecommerce' | 'documentation';
+export type BuiltinProfileName = 'strict' | 'balanced' | 'startup' | 'ecommerce' | 'documentation';
+export type PolicyProfileName = BuiltinProfileName | 'custom';
 export interface InvariantPolicyOverride {
     requirementLevel?: RequirementLevel;
     severity?: InvariantSeverity;

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;
@@ -27,8 +27,8 @@ export interface TemplateEvidence extends BaseEvidence {
 }
 export interface RouteConfigEvidence extends BaseEvidence {
     type: 'route_config';
-    sourceFile: string;
-    configFormat: 'laravel_routes' | 'symfony_yaml' | 'next_app_dir' | 'next_pages_dir' | 'react_router' | 'static_file';
+    sourceFile?: string;
+    configFormat: 'laravel_routes' | 'symfony_yaml' | 'next_app_dir' | 'next_pages_dir' | 'react_router' | 'static_file' | 'implicit_default';
     declaredPattern: string;
 }
 export interface DomEvidence extends BaseEvidence {

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,