argusqa-os 9.5.9 → 9.6.0

package/glama.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://glama.ai/mcp/schemas/server.json",
   "name": "argus",
-  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 8 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff), argus_design_audit (Figma design fidelity — 13 finding types), argus_visual_diff (screenshot baseline comparison, updateBaseline flag). 136 test blocks, 626 hard assertions, 63 detection categories.",
+  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 9 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff), argus_design_audit (Figma design fidelity — 13 finding types), argus_visual_diff (screenshot baseline comparison, updateBaseline flag), argus_pr_validate (PR diff → affected routes → targeted audit → blocked flag). 137 test blocks, 634 hard assertions, 63 detection categories.",
   "maintainers": ["ironclawdevs27"],
   "tools": [
     {
@@ -35,6 +35,10 @@
     {
       "name": "argus_visual_diff",
       "description": "Screenshot baseline comparison for a URL. First call saves a baseline PNG to reports/baselines/screenshots/. Subsequent calls diff the current screenshot against the baseline using pixelmatch and return visual_regression (warning ≥0.1% / critical ≥5% pixels changed) + visual_diff_summary (always). Pass updateBaseline: true to force-refresh the stored baseline after intentional UI changes."
+    },
+    {
+      "name": "argus_pr_validate",
+      "description": "Targeted QA audit driven by a GitHub pull request diff. Fetches the PR's changed files, maps them to affected routes in your target config using path-slug heuristics (infrastructure changes trigger a full audit), then audits only those routes. Returns { findings, affectedRoutes, changedFiles, perRoute, summary, blocked, blockOn }. Use in CI to gate merges — blocked:true when findings meet the blockOn threshold (none/warning/critical, default: critical). Requires Chrome on --remote-debugging-port=9222. GITHUB_TOKEN env var recommended for private repos."
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argusqa-os",
-  "version": "9.5.9",
+  "version": "9.6.0",
   "mcpName": "io.github.ironclawdevs27/argus",
   "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
   "keywords": [
@@ -56,7 +56,7 @@
     "@opentelemetry/sdk-node": "^0.218.0",
     "@slack/web-api": "^7.16.0",
     "axe-core": "^4.12.0",
-    "dotenv": "^16.4.5",
+    "dotenv": "^17.4.2",
     "express": "^5.2.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
@@ -65,6 +65,6 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   }
 }

package/src/cli/init.js

@@ -287,11 +287,15 @@ async function main() {
                                              githubToken, githubRepo, sourceDir, envFile: envFilePath });
     const targetsContent = generateTargetsJs(finalRoutes, { framework, sourceDir, envFile: envFilePath });
 
-    if (fs.existsSync('.env')) {
-      logger.warn('  ⚠  .env already exists — skipping write to preserve existing credentials. Delete it manually to regenerate.');
-    } else {
-      fs.writeFileSync('.env', envContent, 'utf8');
+    try {
+      fs.writeFileSync('.env', envContent, { flag: 'wx', encoding: 'utf8' });
       tick('Wrote .env');
+    } catch (err) {
+      if (err.code === 'EEXIST') {
+        logger.warn('  ⚠  .env already exists — skipping write to preserve existing credentials. Delete it manually to regenerate.');
+      } else {
+        throw err;
+      }
     }
 
     const targetsPath = path.join('src', 'config', 'targets.js');

package/src/mcp-server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.5.9)
+ * Argus MCP Server (v9.6.0)
  *
  * Exposes Argus as an MCP server so Claude (or any MCP client) can call
  * argus_audit, argus_audit_full, argus_compare, argus_last_report, and
@@ -33,6 +33,7 @@ import { CdpBrowserAdapter }                  from './adapters/browser.js';
 import { getFigmaFrame }                      from './adapters/figma.js';
 import { analyzeDesignFidelity }             from './utils/design-fidelity-analyzer.js';
 import { analyzeVisualRegression }           from './utils/visual-diff-analyzer.js';
+import { parsePrUrl, fetchPrFiles, mapFilesToRoutes } from './utils/pr-diff-analyzer.js';
 
 const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
 
@@ -145,6 +146,20 @@ const TOOLS = [
       required: ['url', 'figmaFrameUrl'],
     },
   },
+  {
+    name: 'argus_pr_validate',
+    description: 'Runs a targeted Argus audit on the routes affected by a GitHub pull request. Fetches the PR diff, maps changed files to routes in your target config using path-slug heuristics (infrastructure changes trigger a full audit; targeted otherwise), and audits only those routes — faster than a full scan and focused on what the PR actually touched. Returns { findings, affectedRoutes, changedFiles, perRoute, summary, blocked, blockOn }. Use in CI to gate merges: check blocked:true or pipe findings to an AI verdict step. Requires Chrome on --remote-debugging-port=9222. GITHUB_TOKEN env var recommended for private repos.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prUrl:       { type: 'string',  description: 'Full GitHub PR URL (e.g. https://github.com/owner/repo/pull/42). Used to fetch the list of changed files via the GitHub REST API.' },
+        targetUrl:   { type: 'string',  description: 'Base URL to audit (e.g. https://staging.example.com). Overrides TARGET_DEV_URL env var.' },
+        githubToken: { type: 'string',  description: 'GitHub Personal Access Token or workflow GITHUB_TOKEN. Optional for public repos. Falls back to GITHUB_TOKEN env var.' },
+        blockOn:     { type: 'string',  enum: ['none', 'warning', 'critical'], description: '"critical" = block only when critical findings exist. "warning" = block on any warning or critical. "none" = never block. Defaults to ARGUS_BLOCK_ON env var, then "critical".', default: 'critical' },
+      },
+      required: ['prUrl'],
+    },
+  },
 ];
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
@@ -368,6 +383,52 @@ async function handleDesignAudit({ url, figmaFrameUrl }) {
   });
 }
 
+async function handlePrValidate({ prUrl, targetUrl, githubToken, blockOn } = {}) {
+  if (!prUrl) throw new Error('argus_pr_validate: prUrl is required');
+
+  const { routes } = await import('./config/targets.js');
+  const token  = githubToken ?? process.env.GITHUB_TOKEN;
+  const base   = targetUrl  ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
+  const policy = blockOn    ?? process.env.ARGUS_BLOCK_ON ?? 'critical';
+
+  const changedFiles   = await fetchPrFiles(prUrl, token);
+  const affectedRoutes = mapFilesToRoutes(changedFiles, routes ?? []);
+
+  const allFindings = [];
+  const perRoute    = [];
+
+  for (const route of affectedRoutes) {
+    const url = new URL(route.path, base).href;
+    const res = await handleAudit({ url, critical: route.critical ?? false });
+    const data = JSON.parse(res.content[0].text);
+    allFindings.push(...(data.findings ?? []));
+    perRoute.push({ route: route.path, ...data.summary });
+  }
+
+  const summary = {
+    critical: allFindings.filter(f => f.severity === 'critical').length,
+    warning:  allFindings.filter(f => f.severity === 'warning').length,
+    info:     allFindings.filter(f => f.severity === 'info').length,
+  };
+
+  const blocked =
+    policy === 'critical' ? summary.critical > 0 :
+    policy === 'warning'  ? summary.critical + summary.warning > 0 :
+    false;
+
+  return { content: [{ type: 'text', text: JSON.stringify({
+    prUrl,
+    targetUrl: base,
+    affectedRoutes: affectedRoutes.map(r => r.path),
+    changedFiles,
+    findings: allFindings,
+    perRoute,
+    summary,
+    blocked,
+    blockOn: policy,
+  }, null, 2) }] };
+}
+
 async function handleLastReport() {
   if (!fs.existsSync(REPORTS_DIR)) {
     return { content: [{ type: 'text', text: '{"error":"No reports found in reports/"}' }] };
@@ -386,7 +447,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.5.9' },
+  { name: 'argus', version: '9.6.0' },
   { capabilities: { tools: {} } },
 );
 
@@ -403,6 +464,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       case 'argus_get_context':     return await handleGetContext(req.params.arguments ?? {});
       case 'argus_visual_diff':     return await handleVisualDiff(req.params.arguments ?? {});
       case 'argus_design_audit':    return await handleDesignAudit(req.params.arguments ?? {});
+      case 'argus_pr_validate':     return await handlePrValidate(req.params.arguments ?? {});
       default: throw new Error(`Unknown tool: ${req.params.name}`);
     }
   } catch (err) {

package/src/orchestration/dispatcher.js

@@ -26,7 +26,7 @@ function openInBrowser(filePath) {
   try {
     const abs = path.resolve(filePath);
     if (process.platform === 'win32') {
-      execFile('cmd', ['/c', 'start', '', abs], () => {});
+      execFile('cmd', ['/c', 'start', '', abs], () => {}); // lgtm[js/shell-command-injection-from-environment] — execFile with args array is injection-safe; abs is path.resolve() of an internally-computed report path
     } else if (process.platform === 'darwin') {
       execFile('open', [abs], () => {});
     } else {

package/src/orchestration/env-comparison.js

@@ -21,7 +21,6 @@ import { unwrapEval } from '../utils/mcp-client.js';
 import { childLogger } from '../utils/logger.js';
 
 const logger = childLogger('env-comparison');
-import { normalizeArray } from '../utils/flow-runner.js';
 import { CdpBrowserAdapter } from '../adapters/browser.js';
 
 import { comparisonRoutes, config } from '../config/targets.js';

package/src/orchestration/orchestrator.js

@@ -490,7 +490,7 @@ export async function crawlRouteCheap(route, baseUrl, mcp) {
     const text = (msg.text ?? msg.message ?? '');
     if (text.toLowerCase().includes('has been blocked by cors policy')) continue;
     const severity = classifyConsoleMessage(msg, route.critical);
-    if (severity !== null && msg.level !== 'log') {
+    if (msg.level !== 'log') {
       result.errors.push({
         type: 'console',
         level: msg.level,
@@ -1026,10 +1026,10 @@ export async function runCrawl(mcp, routeOverrides = null, baseUrlOverride = nul
   // Auth session persistence (B2)
   const sessionFile = auth?.sessionFile ?? '.argus-session.json';
   if (auth?.steps?.length > 0) {
-    if (!hasSession(sessionFile, auth.sessionMaxAgeMs)) {
-      logger.info(`[ARGUS] Auth: running login flow (${auth.steps.length} steps)...`);
+    if (!hasSession(sessionFile, auth?.sessionMaxAgeMs)) {
+      logger.info(`[ARGUS] Auth: running login flow (${auth?.steps?.length ?? 0} steps)...`);
       try {
-        await runLoginFlow(browser, targetBaseUrl, auth.steps);
+        await runLoginFlow(browser, targetBaseUrl, auth?.steps ?? []);
         await saveSession(browser, sessionFile);
       } catch (err) {
         logger.warn(`[ARGUS] Auth: login flow failed — crawl will proceed unauthenticated: ${err.message}`);
@@ -1154,5 +1154,5 @@ export async function runCrawl(mcp, routeOverrides = null, baseUrlOverride = nul
 if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
   logger.info('[ARGUS] orchestrator.js loaded. Invoke runCrawl(mcp) from Claude Code with MCP tools connected.');
   logger.info('[ARGUS] Target base URL: ' + BASE_URL);
-  logger.info('[ARGUS] Routes to crawl: ' + (routes ?? []).map(r => r?.path ?? '(no path)').join(', '));
+  logger.info('[ARGUS] Routes to crawl: ' + routes.map(r => r?.path ?? '(no path)').join(', '));
 }

package/src/orchestration/report-processor.js

@@ -108,7 +108,7 @@ export async function processReport(report, { outputDir, severityOverrides }) {
   const timestamp  = new Date().toISOString().replace(/[:.]/g, '-');
   const reportPath = path.join(outputDir, `error-report-${timestamp}.json`);
   try {
-    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2)); // lgtm[js/network-data-to-file] — intentional: Argus persists crawl findings to a local JSON report file by design
   } catch (err) {
     logger.error(`[ARGUS] Failed to write report JSON: ${err.message}`);
     throw err;

package/src/orchestration/slack-notifier.js

@@ -99,7 +99,7 @@ async function uploadFileToSlack(filePath, channelId, filename) {
     const response = await fetch(uploadUrl, {
       method: 'PUT',
       headers: { 'Content-Type': 'application/octet-stream' },
-      body: fileBuffer,
+      body: fileBuffer, // lgtm[js/file-access-to-http] — intentional screenshot upload to Slack pre-signed URL; file path is internally generated by Argus, not from HTTP request input
       signal: AbortSignal.timeout(30000),
     });
     if (!response.ok) {

package/src/orchestration/watch-mode.js

@@ -35,10 +35,6 @@ import {
 import { postBugReport }      from './slack-notifier.js';
 import { isSlackConfigured }  from '../utils/slack-guard.js';
 import { generateHtmlReport } from '../utils/html-reporter.js';
-import {
-  parseConsoleMsgResponse,
-  parseNetworkReqResponse,
-} from '../utils/mcp-parsers.js';
 
 const __dirname   = path.dirname(fileURLToPath(import.meta.url));
 const REPORTS_DIR = path.resolve(__dirname, '../../reports');

package/src/server/index.js

@@ -50,6 +50,28 @@ app.use((req, res, next) => {
   next();
 });
 
+// ── Rate limiting (per-IP, in-memory) ──────────────────────────────────────────
+// 30 requests per minute per IP — prevents Slack endpoint flooding.
+// Slack signature verification rejects invalid payloads, but rate limiting adds
+// a defence-in-depth layer before signature verification even runs.
+const RATE_WINDOW_MS = 60_000;
+const RATE_MAX       = 30;
+const rateLimitMap   = new Map();
+
+function slackRateLimit(req, res, next) {
+  const key   = req.ip ?? 'unknown';
+  const now   = Date.now();
+  const entry = rateLimitMap.get(key) ?? { count: 0, start: now };
+  if (now - entry.start > RATE_WINDOW_MS) { entry.count = 0; entry.start = now; }
+  entry.count++;
+  rateLimitMap.set(key, entry);
+  if (entry.count > RATE_MAX) {
+    res.setHeader('Retry-After', Math.ceil(RATE_WINDOW_MS / 1000));
+    return res.status(429).json({ error: 'Too Many Requests' });
+  }
+  next();
+}
+
 // ── Routes ─────────────────────────────────────────────────────────────────────
 
 app.get('/health', (req, res) => {
@@ -57,10 +79,10 @@ app.get('/health', (req, res) => {
 });
 
 // Slack slash commands
-app.post('/slack/commands', handleSlashCommand);
+app.post('/slack/commands', slackRateLimit, handleSlashCommand);
 
 // Slack Block Kit interactions (button clicks)
-app.post('/slack/interactions', handleInteraction);
+app.post('/slack/interactions', slackRateLimit, handleInteraction);
 
 // ── Start ──────────────────────────────────────────────────────────────────────
 

package/src/server/slash-command-handler.js

@@ -15,7 +15,6 @@
  */
 
 import crypto from 'crypto';
-import { postBugReport } from '../orchestration/slack-notifier.js';
 import { createMcpClient } from '../utils/mcp-client.js';
 import { runCrawl } from '../orchestration/crawl-and-report.js';
 import { WebClient } from '@slack/web-api';

package/src/utils/a11y-deep-analyzer.js

@@ -27,9 +27,7 @@
  */
 
 import fs                    from 'fs';
-import path                  from 'path';
 import { createRequire }     from 'module';
-import { fileURLToPath }     from 'url';
 import { registerExpensive } from '../registry.js';
 import { unwrapEval }        from './mcp-client.js';
 import { childLogger }       from './logger.js';

package/src/utils/baseline-manager.js

@@ -110,7 +110,7 @@ export function saveBaseline(baselineFile, report) {
     flows[flowResult.flowName] = (flowResult.findings ?? []).map(findingKey);
   }
   const codebase = (report.codebase ?? []).map(findingKey);
-  const tmpBaseline = baselineFile + '.tmp';
+  const tmpBaseline = `${baselineFile}.${process.pid}.${Date.now()}.tmp`;
   fs.writeFileSync(
     tmpBaseline,
     JSON.stringify({ savedAt: new Date().toISOString(), routes, flows, codebase }, null, 2),
@@ -245,8 +245,8 @@ export function appendTrend(trendsFile, entry) {
     }
     trends.push(entry);
     if (trends.length > 500) trends = trends.slice(-500);
-    const tmpTrends = trendsFile + '.tmp';
-    fs.writeFileSync(tmpTrends, JSON.stringify(trends, null, 2));
+    const tmpTrends = `${trendsFile}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmpTrends, JSON.stringify(trends, null, 2)); // lgtm[js/network-data-to-file] — intentional: Argus persists crawl trend data to a local baseline file by design
     fs.renameSync(tmpTrends, trendsFile);
   } finally {
     try { fs.closeSync(lockFd); } catch {}

package/src/utils/codebase-analyzer.js

@@ -40,9 +40,9 @@ function collectSourceFiles(sourceDir) {
       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') });
+          const content = fs.readFileSync(full, 'utf8');
+          if (Buffer.byteLength(content, 'utf8') > 1_000_000) continue; // skip files > 1MB
+          files.push({ filePath: full, content });
         } catch {}
       }
     }

package/src/utils/content-analyzer.js

@@ -97,7 +97,7 @@ export function parseContentAnalysisResult(rawResult, url) {
     // 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) {
+    if (typeof raw === 'object' && !Array.isArray(raw) && raw !== null && raw.result !== undefined) { // lgtm[js/comparison-of-unconvertible-types] — typeof null === 'object', so raw !== null is required after the typeof check
       raw = raw.result;
     }
     const str = typeof raw === 'string' ? raw : JSON.stringify(raw);

package/src/utils/flow-runner.js

@@ -223,7 +223,7 @@ async function runAssert(step, browser, flowName, baseUrl, baselines) {
       const start = Date.now();
       let present = false;
       do {
-        const raw = await browser.evaluate(`() => !!document.querySelector(${JSON.stringify(step.selector)})`);
+        const raw = await browser.evaluate(`() => !!document.querySelector(${JSON.stringify(step.selector)})`); // lgtm[js/code-injection] — selector is JSON.stringify-escaped; derived from developer-configured flow steps, not HTTP input
         present = !!unwrapEval(raw);
         if (present) break;
         await new Promise(r => setTimeout(r, 200));
@@ -244,7 +244,7 @@ async function runAssert(step, browser, flowName, baseUrl, baselines) {
     }
 
     case 'element_not_visible': {
-      const raw = await browser.evaluate(`() => !document.querySelector(${JSON.stringify(step.selector)})`);
+      const raw = await browser.evaluate(`() => !document.querySelector(${JSON.stringify(step.selector)})`); // lgtm[js/code-injection] — selector is JSON.stringify-escaped; derived from developer-configured flow steps, not HTTP input
       const absent = unwrapEval(raw);
       if (!absent) {
         findings.push({
@@ -261,7 +261,7 @@ async function runAssert(step, browser, flowName, baseUrl, baselines) {
     }
 
     case 'url_contains': {
-      const raw = await browser.evaluate(`() => window.location.href.includes(${JSON.stringify(step.value)})`);
+      const raw = await browser.evaluate(`() => window.location.href.includes(${JSON.stringify(step.value)})`); // lgtm[js/code-injection] — value is JSON.stringify-escaped; derived from developer-configured flow steps, not HTTP input
       const matches = unwrapEval(raw);
       if (!matches) {
         findings.push({
@@ -545,7 +545,7 @@ export async function runFlow(flow, baseUrl, browser) {
 export async function waitForSelector(browser, selector, timeoutMs = 10_000) {
   const end = Date.now() + timeoutMs;
   while (Date.now() < end) {
-    const raw = await browser.evaluate(`() => !!document.querySelector(${JSON.stringify(selector)})`).catch(() => null);
+    const raw = await browser.evaluate(`() => !!document.querySelector(${JSON.stringify(selector)})`).catch(() => null); // lgtm[js/code-injection] — selector is JSON.stringify-escaped; derived from developer-configured flow steps, not HTTP input
     const found = unwrapEval(raw);
     if (found === true || String(found) === 'true') return true;
     if (Date.now() < end) await new Promise(r => setTimeout(r, 300));

package/src/utils/github-reporter.js

@@ -41,7 +41,7 @@ function sevIcon(sev) { return SEV_ICON[sev] ?? '⚪'; }
 
 /** Escape pipe characters so they don't break Markdown tables. */
 function mdCell(text, maxLen = 100) {
-  return String(text ?? '').slice(0, maxLen).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+  return String(text ?? '').slice(0, maxLen).replace(/\|/g, '\\|').replace(/\n/g, ' '); // lgtm[js/incomplete-string-escaping] — escaping pipe and newline is correct and sufficient for GitHub Markdown table cells
 }
 
 // ── C2.1: PR comment formatter (pure — no I/O) ───────────────────────────────
@@ -429,7 +429,6 @@ export function generateReleaseNotes(currentReport, prevReport, opts = {}) {
 
     if (newOnes.length > 0) {
       const crits = newOnes.filter(f => f.severity === 'critical').length;
-      const warns = newOnes.filter(f => f.severity === 'warning').length;
       lines.push(`### 🆕 New Issues (${newOnes.length})`);
       if (crits > 0) lines.push(`> ⚠️ ${crits} new critical issue(s) require attention`);
       lines.push('');

package/src/utils/har-recorder.js

@@ -79,20 +79,25 @@ export async function analyzeHar(browser, url, opts = {}) {
   const harFile = path.join(harDir, `${slug}.json`);
 
   // ── First run: save baseline ──────────────────────────────────────────────
-  if (!fs.existsSync(harFile)) {
-    try {
-      fs.mkdirSync(harDir, { recursive: true });
-      const baseline = {
-        version: '1.2',
-        createdAt: new Date().toISOString(),
-        url,
-        entries: requests.map(toBaselineEntry),
-      };
-      fs.writeFileSync(harFile, JSON.stringify(baseline, null, 2));
-    } catch (err) {
+  // Use flag:'wx' for atomic create — throws EEXIST if baseline already exists (TOCTOU-safe).
+  fs.mkdirSync(harDir, { recursive: true });
+  const baseline = {
+    version: '1.2',
+    createdAt: new Date().toISOString(),
+    url,
+    entries: requests.map(toBaselineEntry),
+  };
+  let harIsNew = false;
+  try {
+    fs.writeFileSync(harFile, JSON.stringify(baseline, null, 2), { flag: 'wx' });
+    harIsNew = true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') {
       logger.warn(`[ARGUS] har-recorder: failed to write baseline: ${err.message}`);
       return findings;
     }
+  }
+  if (harIsNew) {
 
     findings.push({
       type:         'har_baseline_created',
@@ -106,15 +111,15 @@ export async function analyzeHar(browser, url, opts = {}) {
   }
 
   // ── Subsequent runs: compare against baseline ─────────────────────────────
-  let baseline;
+  let existingBaseline;
   try {
-    baseline = JSON.parse(fs.readFileSync(harFile, 'utf8'));
+    existingBaseline = JSON.parse(fs.readFileSync(harFile, 'utf8'));
   } catch (err) {
     logger.warn(`[ARGUS] har-recorder: failed to read baseline: ${err.message}`);
     return findings;
   }
 
-  const baselineEntries = baseline.entries ?? [];
+  const baselineEntries = existingBaseline.entries ?? [];
   const baselineMap     = new Map(baselineEntries.map(e => [normaliseUrl(e.request.url), e]));
   const currentMap      = new Map(requests.map(r => [normaliseUrl(r.url), r]));
 

package/src/utils/pr-diff-analyzer.js

@@ -0,0 +1,121 @@
+/**
+ * PR Diff Analyzer — maps GitHub PR changed files to affected Argus routes.
+ *
+ * parsePrUrl(prUrl)               → { owner, repo, prNumber }
+ * fetchPrFiles(prUrl, token)      → string[] of changed file paths
+ * mapFilesToRoutes(files, routes) → Route[] subset likely affected by the diff
+ *
+ * Pure functions + one async fetch — no Chrome, no MCP, no AI verdict.
+ * AI verdict logic ships separately in the private argus-pro repo.
+ */
+
+/**
+ * Parse a GitHub PR URL into its owner/repo/prNumber components.
+ *
+ * Accepted formats:
+ *   https://github.com/owner/repo/pull/123
+ *   https://github.com/owner/repo/pull/123/files
+ *
+ * @param {string} prUrl
+ * @returns {{ owner: string, repo: string, prNumber: number }}
+ */
+export function parsePrUrl(prUrl) {
+  const match = String(prUrl).match(
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/,
+  );
+  if (!match) throw new Error(`Invalid GitHub PR URL: ${prUrl}`);
+  return { owner: match[1], repo: match[2], prNumber: parseInt(match[3], 10) };
+}
+
+/**
+ * Fetch the list of file paths changed by a GitHub pull request (up to 100 files).
+ *
+ * @param {string} prUrl        - GitHub PR URL (any format accepted by parsePrUrl)
+ * @param {string} [githubToken] - GitHub token; omit for public repos
+ * @returns {Promise<string[]>}  - Changed file paths relative to the repo root
+ */
+export async function fetchPrFiles(prUrl, githubToken) {
+  const { owner, repo, prNumber } = parsePrUrl(prUrl);
+  const apiUrl =
+    `https://api.github.com/repos/${owner}/${repo}/pulls/${prNumber}/files?per_page=100`;
+  const headers = {
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': 'argusqa-os',
+    ...(githubToken ? { Authorization: `Bearer ${githubToken}` } : {}),
+  };
+
+  const res = await fetch(apiUrl, { headers });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`GitHub API ${res.status}: ${body || res.statusText}`);
+  }
+  const files = await res.json();
+  return files.map(f => f.filename);
+}
+
+/**
+ * Patterns that indicate an infrastructure-level file whose change can affect
+ * every route — framework configs, root layouts, global stylesheets, package.json.
+ */
+const INFRA_PATTERNS = [
+  /next\.config\./i,
+  /vite\.config\./i,
+  /tailwind\.config\./i,
+  /postcss\.config\./i,
+  /webpack\.config\./i,
+  /global(s)?\.(css|scss|less)$/i,
+  /(^|[/\\])(layout|_app|_document|root)\.(tsx?|jsx?)$/i,
+  /(^|[/\\])app\.(tsx?|jsx?)$/i,
+  /(^|[/\\])main\.(tsx?|jsx?)$/i,
+  /package\.json$/i,
+];
+
+/**
+ * Map a list of changed file paths to the subset of Argus route configs that
+ * are likely affected, using heuristic slug matching.
+ *
+ * Heuristic rules (applied in order):
+ *   1. Any infrastructure file → return ALL routes (full audit)
+ *   2. File path contains a slug that matches a route path segment → include that route
+ *   3. No matches → return ALL routes (conservative fallback — never miss a regression)
+ *
+ * @param {string[]} changedFiles - Relative file paths from fetchPrFiles
+ * @param {Array<{ path: string, name: string }>} routes - Route configs from targets.js
+ * @returns {Array<{ path: string, name: string }>}
+ */
+export function mapFilesToRoutes(changedFiles, routes) {
+  if (!routes || routes.length === 0) return [];
+  if (!changedFiles || changedFiles.length === 0) return routes;
+
+  // Infrastructure change → full audit
+  if (changedFiles.some(f => INFRA_PATTERNS.some(re => re.test(f)))) {
+    return routes;
+  }
+
+  // Build a flat set of lowercase slugs from every changed file path
+  const fileSlugs = new Set(
+    changedFiles.flatMap(f =>
+      // Strip extension, split on separators, keep non-trivial tokens
+      f.toLowerCase()
+        .replace(/\.[^./\\]+$/, '')
+        .split(/[/\\._-]+/)
+        .filter(s => s.length > 1),
+    ),
+  );
+
+  // Extract meaningful segments from a route path (e.g. "/checkout/review" → ["checkout","review"])
+  const routeSegments = (route) =>
+    route.path
+      .toLowerCase()
+      .split('/')
+      .map(s => s.replace(/[^a-z0-9]/g, ''))
+      .filter(s => s.length > 1);
+
+  const matched = routes.filter(route =>
+    routeSegments(route).some(seg => fileSlugs.has(seg)),
+  );
+
+  // Conservative fallback: if nothing matched, audit everything
+  return matched.length > 0 ? matched : routes;
+}

package/src/utils/route-discoverer.js

@@ -74,7 +74,7 @@ export async function discoverFromSitemap(baseUrl) {
   const origin = new URL(baseUrl).origin;
   const sitemapUrl = `${baseUrl.replace(/\/$/, '')}/sitemap.xml`;
   try {
-    const res = await fetch(sitemapUrl, { signal: AbortSignal.timeout(10000) });
+    const res = await fetch(sitemapUrl, { signal: AbortSignal.timeout(10000) }); // lgtm[js/ssrf] — sitemapUrl is derived from developer-configured baseUrl in targets.js, not from HTTP request input
     if (!res.ok) return [];
 
     const buf = await res.arrayBuffer();

package/src/utils/security-analyzer.js

@@ -132,7 +132,7 @@ export function parseSecurityAnalysisResult(rawResult, url) {
     // all field lookups (storageTokenKeys, evalUsage, 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) {
+    if (typeof raw === 'object' && !Array.isArray(raw) && raw !== null && raw.result !== undefined) { // lgtm[js/comparison-of-unconvertible-types] — typeof null === 'object', so raw !== null is required after the typeof check
       raw = raw.result;
     }
     const str = typeof raw === 'string' ? raw : JSON.stringify(raw);

package/src/utils/seo-analyzer.js

@@ -48,7 +48,7 @@ export function parseSeoAnalysisResult(rawResult, url) {
   // client returns an object wrapper, JSON.stringify(rawResult) serialises the envelope
   // instead of the inner payload and all SEO fields are undefined → false positives.
   let inner = rawResult;
-  if (typeof rawResult === 'object' && rawResult !== null && !Array.isArray(rawResult)) {
+  if (typeof rawResult === 'object' && rawResult !== null && !Array.isArray(rawResult)) { // lgtm[js/comparison-of-unconvertible-types] — typeof null === 'object', so rawResult !== null is required after the typeof check
     inner = rawResult.result !== undefined ? rawResult.result : rawResult;
   }
 

package/src/utils/session-persistence.js

@@ -65,7 +65,7 @@ function buildRestoreScript(state) {
     lines.push(`sessionStorage.setItem(${JSON.stringify(k)},${JSON.stringify(String(v ?? ''))});`);
   }
 
-  return `() => { ${lines.join(' ')} return true; }`;
+  return `() => { ${lines.join(' ')} return true; }`; // lgtm[js/code-injection] — all k/v values are JSON.stringify-escaped before insertion; derived from browser session storage, not HTTP request input
 }
 
 // ── Session Save ────────────────────────────────────────────────────────────────