feat: make timeouts configurable at global and per repo levels (#29)

* feat: make timeout configurable

* Add changeset

Author: julio-rocketchat

.changeset/grumpy-pears-agree.md

@@ -0,0 +1,5 @@
+---
+"layne": minor
+---
+
+Makes timeouts configurable on global and per repo levels

src/__tests__/config.test.js

@@ -380,4 +380,30 @@ describe('loadScanConfig()', () => {
     expect(config.mode).toBe('diff_only');
     expect(config.contextLines).toBe(4);
   });
+
+  // --- timeoutMinutes ---
+
+  it('returns timeoutMinutes 10 by default', async () => {
+    vi.mocked(readFile).mockResolvedValueOnce(JSON.stringify({}));
+    const config = await loadScanConfig({ owner: 'org', repo: 'repo' });
+    expect(config.timeoutMinutes).toBe(10);
+  });
+
+  it('inherits $global timeoutMinutes when the repo has no timeoutMinutes', async () => {
+    vi.mocked(readFile).mockResolvedValueOnce(JSON.stringify({
+      '$global':       { timeoutMinutes: 20 },
+      'acme/frontend': { semgrep: { extraArgs: ['--config', 'auto'] } },
+    }));
+    const config = await loadScanConfig({ owner: 'acme', repo: 'frontend' });
+    expect(config.timeoutMinutes).toBe(20);
+  });
+
+  it('repo-level timeoutMinutes overrides $global timeoutMinutes', async () => {
+    vi.mocked(readFile).mockResolvedValueOnce(JSON.stringify({
+      '$global':       { timeoutMinutes: 20 },
+      'acme/monorepo': { timeoutMinutes: 30 },
+    }));
+    const config = await loadScanConfig({ owner: 'acme', repo: 'monorepo' });
+    expect(config.timeoutMinutes).toBe(30);
+  });
 });

src/__tests__/worker.test.js

@@ -72,6 +72,7 @@ vi.mock('../config.js', () => ({
   loadScanConfig: vi.fn().mockResolvedValue({
     mode:               'changed_files',
     contextLines:       8,
+    timeoutMinutes:     10,
     semgrep:            { enabled: true, extraArgs: ['--config', 'auto'] },
     trufflehog:         { enabled: true, extraArgs: [] },
     claude:             { enabled: false, model: 'claude-haiku-4-5-20251001' },

src/config-validator.js

@@ -8,8 +8,8 @@
  * directly via `npm run validate-config`.
  */
 
-const KNOWN_REPO_KEYS    = new Set(['mode', 'contextLines', 'semgrep', 'trufflehog', 'claude', 'notifications', 'labels', 'trigger', 'comment', 'exceptionApprovers']);
-const KNOWN_GLOBAL_KEYS  = new Set(['mode', 'contextLines', 'notifications', 'labels', 'trigger', 'comment', 'exceptionApprovers']);
+const KNOWN_REPO_KEYS    = new Set(['mode', 'contextLines', 'timeoutMinutes', 'semgrep', 'trufflehog', 'claude', 'notifications', 'labels', 'trigger', 'comment', 'exceptionApprovers']);
+const KNOWN_GLOBAL_KEYS  = new Set(['mode', 'contextLines', 'timeoutMinutes', 'notifications', 'labels', 'trigger', 'comment', 'exceptionApprovers']);
 const VALID_MODES        = new Set(['changed_files', 'diff_only']);
 const VALID_TRIGGER_ONS  = new Set(['pull_request', 'workflow_run', 'workflow_job']);
 const VALID_CONCLUSIONS  = new Set(['success', 'failure', 'neutral', 'cancelled', 'skipped', 'timed_out', 'action_required']);
@@ -83,6 +83,10 @@ function validateScanMode(block, ctx, errors) {
     if (!Number.isInteger(block.contextLines) || block.contextLines < 0)
       errors.push(`${ctx}.contextLines: must be a non-negative integer`);
   }
+  if (block.timeoutMinutes !== undefined) {
+    if (!Number.isInteger(block.timeoutMinutes) || block.timeoutMinutes < 1)
+      errors.push(`${ctx}.timeoutMinutes: must be a positive integer`);
+  }
 }
 
 function validateScanner(block, ctx, errors) {

src/config.js

@@ -7,8 +7,9 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPOS_CONFIG_PATH = join(__dirname, '..', 'config', 'layne.json');
 
 export const DEFAULT_CONFIG = Object.freeze({
-  mode:         'changed_files',
-  contextLines: 8,
+  mode:           'changed_files',
+  contextLines:   8,
+  timeoutMinutes: 10,
   semgrep: Object.freeze({
     enabled:   true,
     extraArgs: ['--config', 'auto'],
@@ -78,8 +79,9 @@ export async function loadScanConfig({ owner, repo }) {
   const repoExceptionApprovers   = repoOverrides.exceptionApprovers ?? null;
 
   return {
-    mode:          repoOverrides.mode         ?? reposConfig['$global']?.mode         ?? DEFAULT_CONFIG.mode,
-    contextLines:  repoOverrides.contextLines ?? reposConfig['$global']?.contextLines ?? DEFAULT_CONFIG.contextLines,
+    mode:           repoOverrides.mode           ?? reposConfig['$global']?.mode           ?? DEFAULT_CONFIG.mode,
+    contextLines:   repoOverrides.contextLines   ?? reposConfig['$global']?.contextLines   ?? DEFAULT_CONFIG.contextLines,
+    timeoutMinutes: repoOverrides.timeoutMinutes ?? reposConfig['$global']?.timeoutMinutes ?? DEFAULT_CONFIG.timeoutMinutes,
     semgrep:       { ...DEFAULT_CONFIG.semgrep,    ...(repoOverrides.semgrep    ?? {}) },
     trufflehog:    { ...DEFAULT_CONFIG.trufflehog, ...(repoOverrides.trufflehog ?? {}) },
     claude:        { ...DEFAULT_CONFIG.claude,     ...(repoOverrides.claude     ?? {}) },

src/worker.js

@@ -31,7 +31,6 @@ import {
   queueFailed,
 } from './metrics.js';
 
-const SCAN_TIMEOUT_MS  = 10 * 60 * 1000; // 10 minutes
 const NOTIFY_COUNT_TTL = 30 * 24 * 60 * 60; // 30 days in seconds
 const METRICS_ENABLED  = process.env.METRICS_ENABLED === 'true';
 const METRICS_PORT     = parseInt(process.env.METRICS_PORT ?? '9091', 10);
@@ -83,20 +82,24 @@ function appendDiscardedCandidateSummary(summary, discardedCount) {
  * without needing a live BullMQ worker or Redis connection.
  */
 export async function processJob(job) {
+  const { owner, repo } = job.data;
+  const scanConfig = await loadScanConfig({ owner, repo });
+  const timeoutMs = scanConfig.timeoutMinutes * 60 * 1000;
+
   // Resolving sentinel rather than a rejecting promise so there is no risk of an
   // unhandled rejection if the race settles before handlers attach.
   let timer;
   const timeoutSentinel = Symbol('timeout');
   const timeoutPromise  = new Promise(resolve => {
-    timer = setTimeout(() => resolve(timeoutSentinel), SCAN_TIMEOUT_MS);
+    timer = setTimeout(() => resolve(timeoutSentinel), timeoutMs);
   });
 
   try {
-    const result = await Promise.race([runScan(job).then(() => null), timeoutPromise]);
+    const result = await Promise.race([runScan(job, scanConfig).then(() => null), timeoutPromise]);
 
     if (result === timeoutSentinel) {
       scanTimeoutsTotal.inc();
-      throw new Error(`Scan timed out after ${SCAN_TIMEOUT_MS / 60000} minutes`);
+      throw new Error(`Scan timed out after ${timeoutMs / 60000} minutes`);
     }
   } catch (err) {
     const safeMessage = sanitizeError(err.message);
@@ -134,7 +137,7 @@ export async function processJob(job) {
   }
 }
 
-async function runScan(job) {
+async function runScan(job, scanConfig) {
   const {
     installationId,
     owner,
@@ -174,8 +177,6 @@ async function runScan(job) {
     const changedLineRanges = await getChangedLineRanges({ workspacePath, baseSha: mergeBaseSha, headSha });
     const changedFiles = await checkoutFiles({ workspacePath, headSha, files: rawChanged });
 
-    const scanConfig = await loadScanConfig({ owner, repo });
-
     const scanContext = await createScanContext({ workspacePath, changedFiles, baseSha: mergeBaseSha, headSha, scanConfig });
     debug('worker', `dispatching ${scanContext.scanFiles.length} file(s) to scanners (mode: ${scanContext.mode})`);
 

website/docs/configuration.md

@@ -64,7 +64,7 @@ Not all keys merge the same way when a per-repo entry overrides `$global`. The r
 
 | Key | How per-repo overrides `$global` |
 |---|---|
-| `mode`, `contextLines` | Per-repo value replaces global value |
+| `mode`, `contextLines`, `timeoutMinutes` | Per-repo value replaces global value |
 | `semgrep`, `trufflehog`, `claude` | Merged at the key level - per-repo values overwrite matching keys, unset keys inherit from global |
 | `trigger` | Full replacement - per-repo `trigger` replaces the global block entirely |
 | `labels` | Full replacement - per-repo `labels` replaces the global block entirely |
@@ -106,6 +106,26 @@ Number of surrounding lines to include around each changed hunk when `mode` is `
 - **Default:** `8`
 - Ignored when `mode` is `"changed_files"`
 
+### `timeoutMinutes`
+
+Hard time limit for a single scan job. If the limit is reached, the job is rethrown so BullMQ can retry it. The Check Run is only marked as failed on the final attempt.
+
+- **Default:** `10`
+- Accepts any positive integer
+
+Raise this for large monorepos where Semgrep takes a long time, or lower it to fail fast on repos that should scan quickly.
+
+```json title="config/layne.json"
+{
+  "$global": {
+    "timeoutMinutes": 10
+  },
+  "org/monorepo": {
+    "timeoutMinutes": 25
+  }
+}
+```
+
 ### Examples
 
 **Use `diff_only` globally, fall back to full scan for a compliance-critical repo:**

website/docs/reference.md

@@ -35,7 +35,7 @@ For how findings are converted to GitHub annotations and how severities affect P
 
 ## Scan timeout
 
-Each job has a hard 10-minute timeout. If a scan exceeds this limit:
+Each job has a configurable timeout (default 10 minutes, controlled by [`timeoutMinutes`](configuration.md#timeoutminutes) in `layne.json`). If a scan exceeds this limit:
 - The job is rethrown so BullMQ can retry it
 - The Check Run is only marked as failed on the **final** attempt (not on intermediate retries)
 - `layne_scan_timeouts_total` is incremented (when metrics are enabled)