@testspectra/cli 1.1.11-rc.5 → 1.1.13

package/dist/lifecycle/__tests__/lifecycle-engine.test.js

@@ -0,0 +1,290 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { discoverGlobalHooks, discoverSuiteHooks } from '../hook-discovery.js';
+import { LifecycleDispatcher, HookExecutionError } from '../hook-dispatcher.js';
+import { calculateWorkerCount, groupSpecs } from '../parallel-grouping.js';
+describe('Core Lifecycle Execution Engine (docs/v2/cli/lifecycle-execution-engine.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-lifecycle-test-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    describe('Hook Discovery', () => {
+        it('discovers global-hooks and filters by platform hierarchy', () => {
+            const gBefore = path.join(tmpDir, 'global-hooks', 'before');
+            const gAfter = path.join(tmpDir, 'global-hooks', 'after');
+            fs.mkdirSync(gBefore, { recursive: true });
+            fs.mkdirSync(gAfter, { recursive: true });
+            fs.writeFileSync(path.join(gBefore, 'web.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gBefore, 'mobile.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gBefore, 'common.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gAfter, 'web.hook.ts'), 'export default async () => {}');
+            const webGlobal = discoverGlobalHooks(tmpDir, 'web');
+            expect(webGlobal.before.some((h) => h.endsWith('web.hook.ts'))).toBe(true);
+            expect(webGlobal.before.some((h) => h.endsWith('common.hook.ts'))).toBe(true);
+            expect(webGlobal.before.some((h) => h.endsWith('mobile.hook.ts'))).toBe(false);
+            const mobileGlobal = discoverGlobalHooks(tmpDir, 'mobile');
+            expect(mobileGlobal.before.some((h) => h.endsWith('mobile.hook.ts'))).toBe(true);
+            expect(mobileGlobal.before.some((h) => h.endsWith('common.hook.ts'))).toBe(true);
+            expect(mobileGlobal.before.some((h) => h.endsWith('web.hook.ts'))).toBe(false);
+        });
+        it('discovers suite hooks (before, beforeEach, afterEach, after)', () => {
+            const suiteDir = path.join(tmpDir, 'specs', 'Auth');
+            for (const hookType of ['before', 'beforeEach', 'afterEach', 'after']) {
+                const hDir = path.join(suiteDir, 'hooks', hookType);
+                fs.mkdirSync(hDir, { recursive: true });
+                fs.writeFileSync(path.join(hDir, 'web.hook.ts'), 'export default async () => {}');
+            }
+            const suiteHooks = discoverSuiteHooks(suiteDir, 'web');
+            expect(suiteHooks.before.length).toBe(1);
+            expect(suiteHooks.beforeEach.length).toBe(1);
+            expect(suiteHooks.afterEach.length).toBe(1);
+            expect(suiteHooks.after.length).toBe(1);
+        });
+    });
+    describe('Lifecycle Dispatcher & Execution Flow', () => {
+        it('single run executes suite hooks without triggering global hooks', async () => {
+            const executionOrder = [];
+            const globalBeforeFn = vi.fn(async () => {
+                executionOrder.push('globalBefore');
+            });
+            const globalAfterFn = vi.fn(async () => {
+                executionOrder.push('globalAfter');
+            });
+            const suiteHooks = {
+                before: [
+                    async () => {
+                        executionOrder.push('suiteBefore');
+                    },
+                ],
+                beforeEach: [
+                    async () => {
+                        executionOrder.push('beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        executionOrder.push('afterEach');
+                    },
+                ],
+                after: [
+                    async () => {
+                        executionOrder.push('suiteAfter');
+                    },
+                ],
+            };
+            const dispatcher = new LifecycleDispatcher('single', {
+                before: [globalBeforeFn],
+                after: [globalAfterFn],
+            });
+            // Single run bypasses global before & global after
+            await dispatcher.runGlobalBefore();
+            expect(globalBeforeFn).not.toHaveBeenCalled();
+            const result = await dispatcher.executeSuite('AuthSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Valid Login',
+                    fn: async () => {
+                        executionOrder.push('testBody');
+                    },
+                },
+            ]);
+            await dispatcher.runGlobalAfter();
+            expect(globalAfterFn).not.toHaveBeenCalled();
+            expect(result.status).toBe('PASSED');
+            expect(executionOrder).toEqual(['suiteBefore', 'beforeEach', 'testBody', 'afterEach', 'suiteAfter']);
+        });
+        it('global batch run executes global-hooks/before once at start and global-hooks/after once at finish', async () => {
+            const executionOrder = [];
+            const globalBeforeFn = vi.fn(async () => {
+                executionOrder.push('globalBefore');
+            });
+            const globalAfterFn = vi.fn(async () => {
+                executionOrder.push('globalAfter');
+            });
+            const dispatcher = new LifecycleDispatcher('global', {
+                before: [globalBeforeFn],
+                after: [globalAfterFn],
+            });
+            await dispatcher.runGlobalBefore();
+            expect(globalBeforeFn).toHaveBeenCalledTimes(1);
+            const suiteHooks = {
+                before: [
+                    async () => {
+                        executionOrder.push('suiteBefore');
+                    },
+                ],
+                beforeEach: [
+                    async () => {
+                        executionOrder.push('beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        executionOrder.push('afterEach');
+                    },
+                ],
+                after: [
+                    async () => {
+                        executionOrder.push('suiteAfter');
+                    },
+                ],
+            };
+            const result = await dispatcher.executeSuite('AuthSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Test 1',
+                    fn: async () => {
+                        executionOrder.push('tc1');
+                    },
+                },
+                {
+                    id: 'TC-02',
+                    title: 'Test 2',
+                    fn: async () => {
+                        executionOrder.push('tc2');
+                    },
+                },
+            ]);
+            await dispatcher.runGlobalAfter();
+            expect(globalAfterFn).toHaveBeenCalledTimes(1);
+            expect(result.status).toBe('PASSED');
+            expect(executionOrder).toEqual([
+                'globalBefore',
+                'suiteBefore',
+                'beforeEach',
+                'tc1',
+                'afterEach',
+                'beforeEach',
+                'tc2',
+                'afterEach',
+                'suiteAfter',
+                'globalAfter',
+            ]);
+        });
+        it('when beforeEach fails, test body is skipped, afterEach is guaranteed to execute, and test is marked as ERROR', async () => {
+            const testBodyFn = vi.fn();
+            let afterEachRan = false;
+            const suiteHooks = {
+                before: [],
+                beforeEach: [
+                    async () => {
+                        throw new Error('Database connection failed in beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        afterEachRan = true;
+                    },
+                ],
+                after: [],
+            };
+            const dispatcher = new LifecycleDispatcher('single');
+            const result = await dispatcher.executeSuite('FailingBeforeEachSuite', suiteHooks, [
+                {
+                    id: 'TC-FAIL-01',
+                    title: 'Should be skipped',
+                    fn: testBodyFn,
+                },
+            ]);
+            expect(testBodyFn).not.toHaveBeenCalled();
+            expect(afterEachRan).toBe(true);
+            expect(result.results[0].status).toBe('ERROR');
+            expect(result.results[0].error?.message).toContain('Database connection failed in beforeEach');
+            expect(result.status).toBe('ERROR');
+        });
+        it('when afterEach fails, test transitions to ERROR status', async () => {
+            const suiteHooks = {
+                before: [],
+                beforeEach: [],
+                afterEach: [
+                    async () => {
+                        throw new Error('Teardown resource leak in afterEach');
+                    },
+                ],
+                after: [],
+            };
+            const dispatcher = new LifecycleDispatcher('single');
+            const result = await dispatcher.executeSuite('TeardownFailSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Passing Body but failing afterEach',
+                    fn: async () => {
+                        // Passing body
+                    },
+                },
+            ]);
+            expect(result.results[0].status).toBe('ERROR');
+            expect(result.results[0].error?.message).toContain('Teardown resource leak in afterEach');
+            expect(result.status).toBe('ERROR');
+        });
+        it('when global-hooks/before fails, throws HookExecutionError immediately', async () => {
+            const dispatcher = new LifecycleDispatcher('global', {
+                before: [
+                    async () => {
+                        throw new Error('Global health check failed');
+                    },
+                ],
+                after: [],
+            });
+            await expect(dispatcher.runGlobalBefore()).rejects.toThrow(HookExecutionError);
+            await expect(dispatcher.runGlobalBefore()).rejects.toThrow('Global health check failed');
+        });
+    });
+    describe('Parallel Spec Grouping & Dynamic Worker Sizing', () => {
+        it('prioritizes explicit user concurrency flag over auto-calculation', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            expect(calculateWorkerCount(targets, { userConcurrency: 4 })).toBe(4);
+            // Clamps to item count if items < userConcurrency
+            expect(calculateWorkerCount(['only-one.ts'], { userConcurrency: 4 })).toBe(1);
+        });
+        it('enforces low-CPU safety ratio based on container/host CPU quota', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            const highRam = 16 * 1024 * 1024 * 1024; // 16 GB
+            // CPU <= 2 (e.g. 2-vCPU standard CI runner): clamped to 1 worker
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 1, memoryBytesOverride: highRam })).toBe(1);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 2, memoryBytesOverride: highRam })).toBe(1);
+            // CPU 3 - 4: allocates 2 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 3, memoryBytesOverride: highRam })).toBe(2);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 4, memoryBytesOverride: highRam })).toBe(2);
+            // CPU > 4: allocates (cpu - 2) capped at maxWorkersCap (default 6)
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 6, memoryBytesOverride: highRam })).toBe(4);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 8, memoryBytesOverride: highRam })).toBe(6);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 64, memoryBytesOverride: highRam })).toBe(6);
+        });
+        it('enforces memory-aware guard to prevent OOM kills during browser automation', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            const highCpu = 16;
+            // 500 MB RAM budget -> allows at most 1 worker (~600MB budget per browser)
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 500 * 1024 * 1024 })).toBe(1);
+            // 1.5 GB RAM budget -> allows 2 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 1500 * 1024 * 1024 })).toBe(2);
+            // 2.5 GB RAM budget -> allows 4 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 2500 * 1024 * 1024 })).toBe(4);
+        });
+        it('groups specs by suite directory in nested array format when mode is "suite"', () => {
+            const specs = [
+                'specs/Auth/TC-001/web.test.ts',
+                'specs/Auth/TC-002/web.test.ts',
+                'specs/Cart/TC-010/web.test.ts',
+                'specs/Cart/TC-011/web.test.ts',
+            ];
+            const grouped = groupSpecs(specs, 'suite');
+            expect(grouped.length).toBe(2);
+            expect(grouped[0]).toEqual(['specs/Auth/TC-001/web.test.ts', 'specs/Auth/TC-002/web.test.ts']);
+            expect(grouped[1]).toEqual(['specs/Cart/TC-010/web.test.ts', 'specs/Cart/TC-011/web.test.ts']);
+        });
+        it('flattens specs when mode is "testcase"', () => {
+            const specs = ['specs/Auth/TC-001/web.test.ts', 'specs/Auth/TC-002/web.test.ts', 'specs/Cart/TC-010/web.test.ts'];
+            const flat = groupSpecs(specs, 'testcase');
+            expect(flat).toEqual(specs);
+        });
+    });
+});

package/dist/lifecycle/hook-discovery.d.ts

@@ -0,0 +1,24 @@
+import { PlatformTarget } from '../generator/type-generator.js';
+export type HookEntry = string | (() => Promise<void> | void);
+export interface DiscoveredSuiteHooks {
+    before: string[];
+    beforeEach: string[];
+    afterEach: string[];
+    after: string[];
+}
+export interface DiscoveredGlobalHooks {
+    before: string[];
+    after: string[];
+}
+export interface SuiteHooks {
+    before: HookEntry[];
+    beforeEach: HookEntry[];
+    afterEach: HookEntry[];
+    after: HookEntry[];
+}
+export interface GlobalHooks {
+    before: HookEntry[];
+    after: HookEntry[];
+}
+export declare function discoverGlobalHooks(cwd: string, platform?: PlatformTarget): DiscoveredGlobalHooks;
+export declare function discoverSuiteHooks(suiteDir: string, platform?: PlatformTarget): DiscoveredSuiteHooks;

package/dist/lifecycle/hook-discovery.js

@@ -0,0 +1,60 @@
+import fs from 'fs';
+import path from 'path';
+import { PLATFORM_HIERARCHY } from '../generator/type-generator.js';
+function resolveHookFilesForType(dir, platform = 'web') {
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const hierarchy = PLATFORM_HIERARCHY[platform] || ['common'];
+    const matched = [];
+    // Group files by base name if applicable or collect directly
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.hook.ts'))
+            continue;
+        const parts = entry.name.split('.');
+        // Formats:
+        // 1. web.hook.ts -> parts = ['web', 'hook', 'ts']
+        // 2. auth.web.hook.ts -> parts = ['auth', 'web', 'hook', 'ts']
+        // 3. auth.hook.ts -> parts = ['auth', 'hook', 'ts']
+        let filePlatform = 'common';
+        if (parts.length === 3) {
+            filePlatform = parts[0];
+        }
+        else if (parts.length >= 4) {
+            filePlatform = parts[parts.length - 3];
+        }
+        if (hierarchy.includes(filePlatform) || filePlatform === 'common') {
+            matched.push(path.join(dir, entry.name));
+        }
+    }
+    // Sort by hierarchy priority
+    matched.sort((a, b) => {
+        const getPriority = (filePath) => {
+            const base = path.basename(filePath);
+            for (let i = 0; i < hierarchy.length; i++) {
+                if (base.includes(`.${hierarchy[i]}.`) || base.startsWith(`${hierarchy[i]}.`)) {
+                    return i;
+                }
+            }
+            return hierarchy.length;
+        };
+        return getPriority(a) - getPriority(b);
+    });
+    return matched;
+}
+export function discoverGlobalHooks(cwd, platform = 'web') {
+    const globalHooksDir = path.join(cwd, 'global-hooks');
+    return {
+        before: resolveHookFilesForType(path.join(globalHooksDir, 'before'), platform),
+        after: resolveHookFilesForType(path.join(globalHooksDir, 'after'), platform),
+    };
+}
+export function discoverSuiteHooks(suiteDir, platform = 'web') {
+    const hooksDir = path.join(suiteDir, 'hooks');
+    return {
+        before: resolveHookFilesForType(path.join(hooksDir, 'before'), platform),
+        beforeEach: resolveHookFilesForType(path.join(hooksDir, 'beforeEach'), platform),
+        afterEach: resolveHookFilesForType(path.join(hooksDir, 'afterEach'), platform),
+        after: resolveHookFilesForType(path.join(hooksDir, 'after'), platform),
+    };
+}

package/dist/lifecycle/hook-dispatcher.d.ts

@@ -0,0 +1,34 @@
+import { SuiteHooks, GlobalHooks } from './hook-discovery.js';
+export type TestCaseStatus = 'PASSED' | 'FAILED' | 'SKIPPED' | 'ERROR';
+export interface TestCaseResult {
+    id: string;
+    title: string;
+    status: TestCaseStatus;
+    error?: Error;
+    durationMs: number;
+}
+export interface SuiteExecutionResult {
+    suiteName: string;
+    results: TestCaseResult[];
+    status: 'PASSED' | 'FAILED' | 'ERROR';
+    error?: Error;
+}
+export type HookFn = () => Promise<void> | void;
+export declare class HookExecutionError extends Error {
+    phase: 'before' | 'beforeEach' | 'afterEach' | 'after' | 'globalBefore' | 'globalAfter';
+    originalError: any;
+    constructor(phase: 'before' | 'beforeEach' | 'afterEach' | 'after' | 'globalBefore' | 'globalAfter', originalError: any);
+}
+export declare function runHook(hookPathOrFn: string | HookFn, timeoutMs?: number): Promise<void>;
+export declare class LifecycleDispatcher {
+    mode: 'single' | 'global';
+    globalHooks: GlobalHooks;
+    constructor(mode?: 'single' | 'global', globalHooks?: GlobalHooks);
+    runGlobalBefore(): Promise<void>;
+    runGlobalAfter(): Promise<void>;
+    executeSuite(suiteName: string, suiteHooks: SuiteHooks, testCases: Array<{
+        id: string;
+        title: string;
+        fn: () => Promise<void>;
+    }>): Promise<SuiteExecutionResult>;
+}

package/dist/lifecycle/hook-dispatcher.js

@@ -0,0 +1,190 @@
+import { pathToFileURL } from 'url';
+export class HookExecutionError extends Error {
+    phase;
+    originalError;
+    constructor(phase, originalError) {
+        super(`Hook failure during [${phase}]: ${originalError?.message || String(originalError)}`);
+        this.phase = phase;
+        this.originalError = originalError;
+        this.name = 'HookExecutionError';
+    }
+}
+export async function runHook(hookPathOrFn, timeoutMs = 10000) {
+    let fn;
+    if (typeof hookPathOrFn === 'function') {
+        fn = hookPathOrFn;
+    }
+    else {
+        try {
+            const fileUrl = pathToFileURL(hookPathOrFn).href;
+            const mod = await import(fileUrl);
+            fn = mod.default || mod;
+            if (typeof fn !== 'function') {
+                throw new Error(`Hook file ${hookPathOrFn} does not export a default function`);
+            }
+        }
+        catch (err) {
+            throw new Error(`Failed to load hook from ${hookPathOrFn}: ${err.message}`);
+        }
+    }
+    let timeoutId = null;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new Error(`Hook execution timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        await Promise.race([Promise.resolve(fn()), timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}
+export class LifecycleDispatcher {
+    mode;
+    globalHooks;
+    constructor(mode = 'single', globalHooks = { before: [], after: [] }) {
+        this.mode = mode;
+        this.globalHooks = globalHooks;
+    }
+    async runGlobalBefore() {
+        if (this.mode !== 'global')
+            return;
+        for (const hook of this.globalHooks.before) {
+            try {
+                await runHook(hook);
+            }
+            catch (err) {
+                throw new HookExecutionError('globalBefore', err);
+            }
+        }
+    }
+    async runGlobalAfter() {
+        if (this.mode !== 'global')
+            return;
+        let firstError = null;
+        for (const hook of this.globalHooks.after) {
+            try {
+                await runHook(hook);
+            }
+            catch (err) {
+                if (!firstError)
+                    firstError = err;
+            }
+        }
+        if (firstError) {
+            throw new HookExecutionError('globalAfter', firstError);
+        }
+    }
+    async executeSuite(suiteName, suiteHooks, testCases) {
+        const results = [];
+        let suiteLevelError;
+        // 1. Run suite before hook
+        let beforeSuiteFailed = false;
+        for (const hook of suiteHooks.before) {
+            try {
+                await runHook(hook);
+            }
+            catch (err) {
+                beforeSuiteFailed = true;
+                suiteLevelError = new HookExecutionError('before', err);
+                break;
+            }
+        }
+        if (beforeSuiteFailed) {
+            // All test cases in suite are skipped / marked ERROR
+            for (const tc of testCases) {
+                results.push({
+                    id: tc.id,
+                    title: tc.title,
+                    status: 'ERROR',
+                    error: suiteLevelError,
+                    durationMs: 0,
+                });
+            }
+            // Always execute suite after hook even on before failure
+            for (const hook of suiteHooks.after) {
+                try {
+                    await runHook(hook);
+                }
+                catch { }
+            }
+            return {
+                suiteName,
+                results,
+                status: 'ERROR',
+                error: suiteLevelError,
+            };
+        }
+        // 2. Run each test case with beforeEach and afterEach
+        for (const tc of testCases) {
+            const startTime = Date.now();
+            let tcStatus = 'PASSED';
+            let tcError;
+            let beforeEachFailed = false;
+            // Run beforeEach hooks
+            for (const hook of suiteHooks.beforeEach) {
+                try {
+                    await runHook(hook);
+                }
+                catch (err) {
+                    beforeEachFailed = true;
+                    tcStatus = 'ERROR';
+                    tcError = new HookExecutionError('beforeEach', err);
+                    break;
+                }
+            }
+            // Run test body if beforeEach passed
+            if (!beforeEachFailed) {
+                try {
+                    await tc.fn();
+                    tcStatus = 'PASSED';
+                }
+                catch (err) {
+                    tcStatus = 'FAILED';
+                    tcError = err instanceof Error ? err : new Error(String(err));
+                }
+            }
+            // afterEach is GUARANTEED to execute even if beforeEach or test body failed
+            for (const hook of suiteHooks.afterEach) {
+                try {
+                    await runHook(hook);
+                }
+                catch (err) {
+                    // If test passed or failed, an afterEach failure transitions it to ERROR (Teardown Failure)
+                    tcStatus = 'ERROR';
+                    if (!tcError) {
+                        tcError = new HookExecutionError('afterEach', err);
+                    }
+                }
+            }
+            results.push({
+                id: tc.id,
+                title: tc.title,
+                status: tcStatus,
+                error: tcError,
+                durationMs: Date.now() - startTime,
+            });
+        }
+        // 3. Run suite after hook
+        for (const hook of suiteHooks.after) {
+            try {
+                await runHook(hook);
+            }
+            catch (err) {
+                if (!suiteLevelError) {
+                    suiteLevelError = new HookExecutionError('after', err);
+                }
+            }
+        }
+        const hasErrors = results.some((r) => r.status === 'ERROR') || !!suiteLevelError;
+        const hasFailures = results.some((r) => r.status === 'FAILED');
+        return {
+            suiteName,
+            results,
+            status: hasErrors ? 'ERROR' : hasFailures ? 'FAILED' : 'PASSED',
+            error: suiteLevelError,
+        };
+    }
+}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,3 @@
+export * from './hook-discovery.js';
+export * from './hook-dispatcher.js';
+export * from './parallel-grouping.js';

package/dist/lifecycle/index.js

@@ -0,0 +1,3 @@
+export * from './hook-discovery.js';
+export * from './hook-dispatcher.js';
+export * from './parallel-grouping.js';

package/dist/lifecycle/parallel-grouping.d.ts

@@ -0,0 +1,27 @@
+export type ParallelizationMode = 'suite' | 'testcase';
+export interface WorkerSizingOptions {
+    maxWorkersCap?: number;
+    userConcurrency?: number;
+    cpuQuotaOverride?: number;
+    memoryBytesOverride?: number;
+}
+/**
+ * Detects actual CPU quota available to the process, accounting for
+ * Docker and Kubernetes cgroup v1 and cgroup v2 container limits.
+ */
+export declare function detectContainerCpuQuota(): number;
+/**
+ * Detects available memory in bytes, respecting container cgroup memory limits
+ * to prevent Linux OOM (Out of Memory) kills.
+ */
+export declare function detectAvailableMemoryBytes(): number;
+/**
+ * Dynamically computes optimal worker concurrency respecting:
+ * 1. Explicit user concurrency flag (--concurrency <N> or config)
+ * 2. Real container cgroups CPU quota & host CPU count
+ * 3. Low-CPU safety ratio (clamping <=2 CPUs to 1 worker, 3-4 CPUs to 2 workers)
+ * 4. Memory-aware guard (~600MB RAM budget per Chromium instance to prevent OOM kills)
+ * 5. Target items count & maximum worker cap
+ */
+export declare function calculateWorkerCount(targetItems: any[], options?: WorkerSizingOptions | number): number;
+export declare function groupSpecs(specPaths: string[], mode?: ParallelizationMode): (string | string[])[];