argusqa-os 9.2.0

package/src/utils/codebase-analyzer.js

@@ -0,0 +1,299 @@
+/**
+ * ARGUS Phase C1: Codebase Cross-Reference Analysis
+ *
+ * Reads target app source files to surface issues that browser-only testing misses:
+ *   C1.1  env_var_missing      — process.env.X used in code but absent from all .env files
+ *   C1.2  feature_flag_leakage — env var used in a conditional that is falsy/unset in .env
+ *   C1.3  error_source_linked  — console error stack trace parsed to file:line (info — enrichment)
+ *   C1.4  dead_route           — internal navigation link that returns HTTP 404
+ *
+ * All functions are pure (no MCP dependency) except detectDeadRoutes which does
+ * Node.js fetch() calls — it still requires no browser.
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('codebase-analyzer');
+
+// ── File scanning ──────────────────────────────────────────────────────────────
+
+const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.jsx', '.tsx', '.vue', '.svelte']);
+
+// Node/OS built-in env names to skip in all checks
+const BUILTIN_VARS = new Set([
+  'NODE_ENV', 'PORT', 'HOST', 'PATH', 'HOME', 'USER', 'SHELL', 'PWD',
+  'LANG', 'TZ', 'TERM', 'TMPDIR', 'TEMP', 'TMP', 'LOGNAME', 'UID',
+  'COLORTERM', 'npm_package_version', 'npm_lifecycle_event',
+]);
+
+function collectSourceFiles(sourceDir) {
+  const files = [];
+  function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || e.name === 'node_modules' || e.name === 'dist' || e.name === 'build' || e.name === '.next') continue;
+      if (e.isSymbolicLink()) continue; // avoid symlink cycles
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { walk(full); }
+      else if (SOURCE_EXTENSIONS.has(path.extname(e.name))) {
+        try {
+          const stat = fs.statSync(full);
+          if (stat.size > 1_000_000) continue; // skip files > 1MB (minified bundles, etc.)
+          files.push({ filePath: full, content: fs.readFileSync(full, 'utf8') });
+        } catch {}
+      }
+    }
+  }
+  walk(sourceDir);
+  return files;
+}
+
+function parseEnvFile(envFilePath) {
+  const vars = {};
+  let content;
+  try { content = fs.readFileSync(envFilePath, 'utf8'); } catch { return vars; }
+  for (const raw of content.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq < 1) continue;
+    const key = line.slice(0, eq).trim();
+    const val = line.slice(eq + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) vars[key] = val;
+  }
+  return vars;
+}
+
+function loadDeclaredVars(sourceDir, envFile) {
+  const declared = {};
+  const candidates = [
+    envFile,
+    envFile ? null : path.join(sourceDir, '.env'),
+    path.join(sourceDir, '.env.local'),
+    path.join(sourceDir, '.env.example'),
+    path.join(sourceDir, '.env.development'),
+    path.join(sourceDir, '.env.production'),
+  ].filter(Boolean);
+
+  for (const ef of candidates) Object.assign(declared, parseEnvFile(ef));
+
+  // Runtime env (the process running Argus) counts too — it may have vars set in CI
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v !== undefined) declared[k] = v;
+  }
+  return declared;
+}
+
+// ── C1.1: Env variable audit ───────────────────────────────────────────────────
+
+const ENV_REF_RE = /\bprocess\.env\.([A-Z_][A-Z0-9_]*)\b/g;
+
+export function auditEnvVariables(sourceDir, envFile) {
+  if (!sourceDir) return [];
+  const files    = collectSourceFiles(sourceDir);
+  const declared = loadDeclaredVars(sourceDir, envFile);
+
+  // Collect all refs: varName → [relPath, ...]
+  const refs = {};
+  for (const { filePath, content } of files) {
+    const rel = path.relative(sourceDir, filePath);
+    ENV_REF_RE.lastIndex = 0;
+    let m;
+    while ((m = ENV_REF_RE.exec(content)) !== null) {
+      const name = m[1];
+      if (BUILTIN_VARS.has(name)) continue;
+      if (!refs[name]) refs[name] = [];
+      if (!refs[name].includes(rel)) refs[name].push(rel);
+    }
+  }
+
+  return Object.entries(refs)
+    .filter(([name]) => !(name in declared))
+    .map(([name, files]) => ({
+      type:         'env_var_missing',
+      varName:      name,
+      referencedIn: files.slice(0, 5),
+      message:      `process.env.${name} referenced in source but not declared in any .env file (found in: ${files.slice(0, 3).join(', ')})`,
+      severity:     'warning',
+      url:          '',
+    }));
+}
+
+// ── C1.2: Feature flag leakage ────────────────────────────────────────────────
+// Detect env vars used in conditionals (if/&&/||/ternary) that are falsy in .env.
+// A permanently-disabled code path is a dead-weight risk — it may also shadow bugs.
+
+// Match env var on either side of a comparison / logical operator
+const FLAG_RE = /(?:(?:if\s*\(|&&|\|\||[?]|===|!==|==|!=)\s*process\.env\.([A-Z_][A-Z0-9_]*)|process\.env\.([A-Z_][A-Z0-9_]*)\s*(?:===|!==|==|!=|&&|\|\||[?:]))/g;
+
+export function detectFeatureFlagLeakage(sourceDir, envFile) {
+  if (!sourceDir) return [];
+  const files   = collectSourceFiles(sourceDir);
+  const envVars = parseEnvFile(envFile ?? path.join(sourceDir, '.env'));
+  // Don't use runtime process.env here — we want to surface flags that are absent from .env
+
+  const findings = [];
+  const seen     = new Set();
+
+  for (const { filePath, content } of files) {
+    const rel = path.relative(sourceDir, filePath);
+    FLAG_RE.lastIndex = 0;
+    let m;
+    while ((m = FLAG_RE.exec(content)) !== null) {
+      const name = m[1] ?? m[2];
+      if (!name || BUILTIN_VARS.has(name)) continue;
+
+      const dedupeKey = `${name}::${rel}`;
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+
+      const value = envVars[name]; // undefined if not in .env
+      const falsy = value === undefined || value === '' || value === 'false' || value === '0';
+      if (!falsy) continue;
+
+      findings.push({
+        type:    'feature_flag_leakage',
+        varName: name,
+        value:   value ?? '(not set)',
+        file:    rel,
+        message: `process.env.${name} is used in a conditional in ${rel} but is ${value === undefined ? 'not set in .env' : `"${value}" (falsy)`} — that code branch is permanently disabled`,
+        severity: 'warning',
+        url:     '',
+      });
+    }
+  }
+  return findings;
+}
+
+// ── C1.3: Error-to-source linking ─────────────────────────────────────────────
+// Parse stack traces from console error findings. Source maps are not resolved —
+// we surface the bundle file:line as-is; that's already enough to grep.
+
+// Chrome stack frame:  "    at FnName (http://host/bundle.js:1:4567)"
+// Chrome anon:         "    at http://host/chunk.js:1:4567"
+const FRAME_RE = /at\s+(?:([^\s(]+)\s+\()?(?:https?:\/\/[^)]+?\/([^/)\s]+\.(?:js|ts|jsx|tsx|mjs)):(\d+):(\d+)\)?|([^\s/]+\.(?:js|ts|jsx|tsx|mjs)):(\d+):(\d+))/g;
+
+export function enrichErrorsWithSource(consoleFindings) {
+  const enriched = [];
+  for (const finding of consoleFindings) {
+    if (finding.type !== 'console') continue;
+    const msg = String(finding.message ?? finding.text ?? '');
+    if (!msg.includes(' at ')) continue;
+
+    const frames = [];
+    FRAME_RE.lastIndex = 0;
+    let m;
+    while ((m = FRAME_RE.exec(msg)) !== null && frames.length < 5) {
+      frames.push({
+        fn:   m[1] ?? '(anonymous)',
+        file: m[2] ?? m[5] ?? '?',
+        line: parseInt(m[3] ?? m[6] ?? '0', 10),
+        col:  parseInt(m[4] ?? m[7] ?? '0', 10),
+      });
+    }
+    if (frames.length === 0) continue;
+
+    const top = frames[0];
+    enriched.push({
+      type:            'error_source_linked',
+      originalMessage: msg.slice(0, 200),
+      stackFrames:     frames,
+      message:         `Console error in ${top.file}:${top.line} (fn: ${top.fn})`,
+      severity:        'info',
+      url:             '',
+    });
+  }
+  return enriched;
+}
+
+// ── C1.4: Dead route detection ────────────────────────────────────────────────
+// HEAD-request each internal link discovered on crawled pages that was not already
+// in the targeted route list. 404 responses are emitted as dead_route warnings.
+
+// Uses getAttribute('href') so '#section' is caught before a.href resolves it to
+// an absolute URL (a.href always returns a fully-qualified URL in browsers).
+const INTERNAL_LINKS_SCRIPT = `() => {
+  try {
+    var o = window.location.origin;
+    return Array.from(document.querySelectorAll('a[href]'))
+      .filter(function(a){
+        var raw = a.getAttribute('href') || '';
+        if (!raw || raw.startsWith('#') || raw.startsWith('mailto:') || raw.startsWith('tel:') || raw.startsWith('javascript:')) return false;
+        try { return new URL(a.href).origin === o; } catch { return false; }
+      })
+      .map(function(a){ return a.href; });
+  } catch(e) { return []; }
+}`;
+
+export { INTERNAL_LINKS_SCRIPT };
+
+export async function detectDeadRoutes(baseUrl, discoveredLinks, alreadyTestedPaths) {
+  if (!discoveredLinks?.length) return [];
+
+  const findings  = [];
+  const testedSet = new Set(
+    (alreadyTestedPaths ?? []).map(p => p.replace(/\/$/, '') || '/')
+  );
+
+  for (const href of discoveredLinks) {
+    let normalized;
+    try {
+      const u = new URL(href, baseUrl);
+      normalized = u.pathname.replace(/\/$/, '') || '/';
+    } catch { continue; }
+
+    if (testedSet.has(normalized)) continue;
+    testedSet.add(normalized);
+
+    try {
+      const res = await fetch(new URL(href, baseUrl).href, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(5000),
+        redirect: 'follow',
+      });
+      if (res.status === 404) {
+        findings.push({
+          type:     'dead_route',
+          path:     normalized,
+          status:   404,
+          message:  `Internal link ${normalized} returns 404`,
+          severity: 'warning',
+          url:      baseUrl,
+        });
+      }
+    } catch { /* network error — skip */ }
+  }
+  return findings;
+}
+
+// ── Main export ───────────────────────────────────────────────────────────────
+
+/**
+ * C1 codebase analysis — static analysis (no MCP, no browser).
+ * detectDeadRoutes is called separately from runCrawl (needs discovered link list).
+ *
+ * @param {object}   opts
+ * @param {string}   opts.sourceDir       — abs path to target app source code
+ * @param {string}  [opts.envFile]        — path to .env file (defaults to sourceDir/.env)
+ * @param {object[]} [opts.consoleFindings] — console findings from route crawl for enrichment
+ * @returns {object[]} findings array (env_var_missing, feature_flag_leakage, error_source_linked)
+ */
+export async function analyzeCodebase({ sourceDir, envFile = null, consoleFindings = [] } = {}) {
+  if (!sourceDir) return [];
+
+  const findings = [];
+
+  try { findings.push(...auditEnvVariables(sourceDir, envFile)); }
+  catch (e) { logger.warn(`[ARGUS] C1: env audit skipped: ${e.message}`); }
+
+  try { findings.push(...detectFeatureFlagLeakage(sourceDir, envFile)); }
+  catch (e) { logger.warn(`[ARGUS] C1: feature flag check skipped: ${e.message}`); }
+
+  try { findings.push(...enrichErrorsWithSource(consoleFindings)); }
+  catch (e) { logger.warn(`[ARGUS] C1: error enrichment skipped: ${e.message}`); }
+
+  return findings;
+}

package/src/utils/content-analyzer.js

@@ -0,0 +1,155 @@
+/**
+ * ARGUS Content Analyzer (v3 Phase A5)
+ *
+ * DOM-based content quality checks via evaluate_script:
+ *   1. undefined / null / NaN rendered as visible text
+ *   2. Placeholder text — "Lorem ipsum", "TODO", "FIXME", etc.
+ *   3. Broken images — <img> that loaded but has naturalWidth === 0
+ *   4. Empty data-oriented lists — <ul>/<ol> with a results/items/grid class but zero <li> children
+ */
+
+/**
+ * Synchronous arrow function injected into the page via mcp.evaluate_script.
+ * Returns a JSON string consumed by parseContentAnalysisResult().
+ */
+import { childLogger } from './logger.js';
+
+const logger = childLogger('content-analyzer');
+
+export const CONTENT_ANALYSIS_SCRIPT = `() => {
+  var body = document.body || {};
+  var bodyText = body.innerText || '';
+
+  // 1. Standalone undefined / null / NaN in visible body text
+  var nullMatches = [];
+  var nullSet = {};
+  var nullPat = /\\bundefined\\b|\\bnull\\b|\\bNaN\\b/g;
+  var m;
+  while ((m = nullPat.exec(bodyText)) !== null) {
+    if (!nullSet[m[0]]) { nullSet[m[0]] = true; nullMatches.push(m[0]); }
+  }
+
+  // 2. Placeholder text patterns
+  var placeholders = [];
+  var phChecks = [
+    ['lorem ipsum',     /lorem ipsum/i],
+    ['todo',            /\\btodo\\b/i],
+    ['fixme',           /\\bfixme\\b/i],
+    ['coming soon',     /\\bcoming soon\\b/i],
+    ['placeholder',     /\\bplaceholder text\\b/i],
+    ['sample text',     /\\bsample text\\b/i],
+    ['insert content',  /\\binsert (content|text|copy) here\\b/i],
+    ['hello world',     /\\bhello[\\s-]world\\b/i],
+    ['test user',       /\\btest user\\b/i],
+    ['foo bar',         /\\bfoo bar\\b/i],
+    ['dummy text',      /\\bdummy (text|data|content)\\b/i],
+    ['ipsa lore',       /\\bipsa lore\\b/i],
+  ];
+  phChecks.forEach(function(pair) {
+    if (pair[1].test(bodyText)) placeholders.push(pair[0]);
+  });
+
+  // 3. Broken images — loaded (complete) but naturalWidth === 0 (excludes data: URIs)
+  var brokenImages = [];
+  var imgs = Array.prototype.slice.call(document.querySelectorAll('img[src]'));
+  imgs.forEach(function(img) {
+    if (img.complete && img.naturalWidth === 0 &&
+        img.src && img.src.indexOf('data:') !== 0) {
+      brokenImages.push(img.src.slice(0, 200));
+    }
+  });
+
+  // 4. Empty data-oriented lists (ul/ol with results/items/list/feed/grid class but 0 li children)
+  var emptyLists = [];
+  var listClassPat = /results|items|list|feed|grid|entries|collection/i;
+  var lists = Array.prototype.slice.call(document.querySelectorAll('ul, ol'));
+  lists.forEach(function(list) {
+    // Use :scope > li to count only direct children, not nested <li> elements.
+    // querySelectorAll('li') descends into nested lists and would miss genuinely empty parents.
+    if (!list.querySelector(':scope > li') && listClassPat.test(list.className || '')) {
+      emptyLists.push((list.className || 'unnamed').slice(0, 100));
+    }
+  });
+
+  return JSON.stringify({
+    nullMatches:  nullMatches,
+    placeholders: placeholders,
+    brokenImages: brokenImages,
+    emptyLists:   emptyLists,
+  });
+}`;
+
+/**
+ * Convert the raw evaluate_script result from CONTENT_ANALYSIS_SCRIPT into
+ * structured bug entries for the Argus report.
+ *
+ * @param {object|string|null} rawResult
+ * @param {string} url - Page URL for context
+ * @returns {object[]}
+ */
+export function parseContentAnalysisResult(rawResult, url) {
+  if (rawResult == null) return [];
+
+  let data;
+  try {
+    // Unwrap MCP { result: '...' } wrapper before parsing. Without this,
+    // JSON.stringify({ result: '{"nullMatches":[],...}' }) → parse → { result: '...' } and
+    // all field lookups (nullMatches, brokenImages, etc.) return undefined — zero findings.
+    // JSON.stringify on a circular object throws; catch logs and returns [].
+    let raw = rawResult;
+    if (typeof raw === 'object' && !Array.isArray(raw) && raw !== null && raw.result !== undefined) {
+      raw = raw.result;
+    }
+    const str = typeof raw === 'string' ? raw : JSON.stringify(raw);
+    data = JSON.parse(str);
+  } catch (e) {
+    logger.warn('[ARGUS] parseContentAnalysisResult: parse failed —', e.message);
+    return [];
+  }
+
+  if (!data || typeof data !== 'object') return [];
+
+  const bugs = [];
+
+  if (Array.isArray(data.nullMatches) && data.nullMatches.length > 0) {
+    bugs.push({
+      type:    'content_null_rendered',
+      values:  data.nullMatches,
+      message: `Null-like value rendered as visible text: ${data.nullMatches.join(', ')}`,
+      severity: 'warning',
+      url,
+    });
+  }
+
+  if (Array.isArray(data.placeholders) && data.placeholders.length > 0) {
+    bugs.push({
+      type:        'content_placeholder_text',
+      placeholders: data.placeholders,
+      message:     `Placeholder text found in page body: ${data.placeholders.join(', ')}`,
+      severity:    'warning',
+      url,
+    });
+  }
+
+  for (const src of (Array.isArray(data.brokenImages) ? data.brokenImages : [])) {
+    bugs.push({
+      type:     'content_broken_image',
+      src,
+      message:  `Broken image (naturalWidth=0): ${src}`,
+      severity: 'warning',
+      url,
+    });
+  }
+
+  if (Array.isArray(data.emptyLists) && data.emptyLists.length > 0) {
+    bugs.push({
+      type:    'content_empty_list',
+      classes: data.emptyLists,
+      message: `Empty data list detected (${data.emptyLists.length} list(s) with no items): ${data.emptyLists.join(', ')}`,
+      severity: 'warning',
+      url,
+    });
+  }
+
+  return bugs;
+}

package/src/utils/contract-validator.js

@@ -0,0 +1,178 @@
+/**
+ * Argus D7.4 — API contract validation.
+ * Validates captured network response bodies against JSON Schema-like schemas
+ * defined in src/config/targets.js apiContracts[].
+ *
+ * Supported schema keywords: type, required, properties, items.
+ * URL matching: exact pathname or pathname-prefix; full URL for http(s) contracts.
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('contract-validator');
+
+/**
+ * Lightweight JSON Schema validator.
+ * Supports: type, required, properties (recursive), items (first element).
+ *
+ * @param {any}    value  - Value to validate
+ * @param {object} schema - Schema object
+ * @param {string} path   - JSONPath prefix for error messages (internal)
+ * @returns {string[]} Array of human-readable violation strings (empty = valid)
+ */
+export function validateSchema(value, schema, path = '') {
+  const violations = [];
+  if (!schema || typeof schema !== 'object') return violations;
+  const label = path || 'root';
+
+  // Type check
+  if (schema.type !== undefined) {
+    const actual = Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value;
+    if (actual !== schema.type) {
+      violations.push(`${label}: expected type "${schema.type}", got "${actual}"`);
+      return violations; // no point descending if the type is wrong
+    }
+  }
+
+  // Required fields (objects only)
+  if (schema.required && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    for (const field of schema.required) {
+      if (!(field in value)) {
+        violations.push(`${label}: missing required field "${field}"`);
+      }
+    }
+  }
+
+  // Properties (recursive, objects only)
+  if (schema.properties && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (key in value) {
+        violations.push(...validateSchema(value[key], propSchema, path ? `${path}.${key}` : key));
+      }
+    }
+  }
+
+  // Array items — validate first 5 elements; deduplicate identical violations
+  if (schema.items && Array.isArray(value) && value.length > 0) {
+    const seen = new Set();
+    for (let i = 0; i < Math.min(value.length, 5); i++) {
+      for (const v of validateSchema(value[i], schema.items, `${label}[${i}]`)) {
+        const norm = v.replace(/\[\d+\]/, '[*]');
+        if (!seen.has(norm)) { seen.add(norm); violations.push(v); }
+      }
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Decide whether a captured network request matches a contract definition.
+ *
+ * URL matching rules:
+ *   - If contract.url starts with http(s)://  → exact full-URL match
+ *   - Otherwise                               → pathname exact-match or prefix-match
+ *
+ * Method matching: case-insensitive; no constraint when contract.method is falsy.
+ *
+ * @param {string} reqUrl      - Full URL from list_network_requests
+ * @param {string} reqMethod   - HTTP method from list_network_requests
+ * @param {object} contract    - Entry from apiContracts[]
+ * @returns {boolean}
+ */
+export function matchesContract(reqUrl, reqMethod, contract) {
+  if (!contract?.url) return false;
+  const method = (reqMethod ?? 'GET').toUpperCase();
+  if (contract.method && contract.method.toUpperCase() !== method) return false;
+
+  if (contract.url.startsWith('http://') || contract.url.startsWith('https://')) {
+    return reqUrl === contract.url;
+  }
+
+  // Path-based match
+  try {
+    const { pathname } = new URL(reqUrl);
+    return pathname === contract.url || pathname.startsWith(contract.url + '/');
+  } catch {
+    return reqUrl.includes(contract.url);
+  }
+}
+
+/**
+ * Load a schema from a contract definition.
+ * Prefers contract.schema (inline); falls back to contract.schemaFile (JSON file).
+ * Returns null if neither is present or the file cannot be parsed.
+ */
+function loadSchema(contract) {
+  if (contract.schema) return contract.schema;
+  if (contract.schemaFile) {
+    // Prevent path traversal — schemaFile must stay within the project directory
+    const resolved = path.resolve(contract.schemaFile);
+    const cwd = process.cwd();
+    if (!resolved.startsWith(cwd + path.sep) && resolved !== cwd) {
+      logger.warn('[ARGUS] contract-validator: schemaFile outside project directory — skipping:', contract.schemaFile);
+      return null;
+    }
+    try {
+      return JSON.parse(fs.readFileSync(resolved, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate captured network requests against apiContracts[].
+ * For each request that matches a contract, fetches the response body via
+ * browser.getNetworkRequest and validates the parsed JSON against the schema.
+ *
+ * Gracefully skips requests whose body cannot be fetched or parsed.
+ *
+ * @param {object[]} networkReqs - Route-sliced requests from list_network_requests()
+ * @param {object}   browser     - CdpBrowserAdapter
+ * @param {object[]} contracts   - apiContracts[] from targets.js
+ * @param {string}   pageUrl     - Current page URL (stored on each finding)
+ * @returns {Promise<object[]>}  api_contract_violation findings
+ */
+export async function validateApiContracts(networkReqs, browser, contracts, pageUrl) {
+  if (!contracts?.length) return [];
+  const findings = [];
+
+  for (const req of networkReqs) {
+    for (const contract of contracts) {
+      if (!matchesContract(req.url, req.method, contract)) continue;
+
+      const schema = loadSchema(contract);
+      if (!schema) continue;
+
+      // Fetch response body — graceful: skip if unavailable or not JSON
+      let body = null;
+      try {
+        const raw = await browser.getNetworkRequest(req.id ?? req.requestId);
+        const text = raw?.responseBody ?? raw?.body ?? null;
+        if (text) body = JSON.parse(text);
+      } catch {
+        continue; // body unavailable — skip validation for this request
+      }
+
+      if (body === null) continue;
+
+      const violations = validateSchema(body, schema);
+      for (const violation of violations) {
+        findings.push({
+          type:       'api_contract_violation',
+          requestUrl: req.url,
+          method:     req.method ?? 'GET',
+          message:    `API contract violation for ${req.method ?? 'GET'} ${req.url}: ${violation}`,
+          severity:   'warning',
+          url:        pageUrl,
+        });
+      }
+    }
+  }
+
+  return findings;
+}