patina-cli 3.11.0

package/scripts/lint.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// No-dependency lint smoke for CI: syntax-check every committed JS/MJS file.
+
+import { spawnSync } from 'node:child_process';
+import { readdirSync, statSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+const ROOTS = ['bin', 'scripts', 'src', 'tests'];
+const EXT_RE = /\.(?:js|mjs)$/;
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    const path = resolve(dir, entry);
+    const st = statSync(path);
+    if (st.isDirectory()) walk(path, out);
+    else if (EXT_RE.test(entry)) out.push(path);
+  }
+  return out;
+}
+
+const files = ROOTS.flatMap((dir) => walk(resolve(REPO_ROOT, dir))).sort();
+let failed = false;
+for (const file of files) {
+  const result = spawnSync(process.execPath, ['--check', file], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    failed = true;
+    console.error(`node --check failed: ${relative(REPO_ROOT, file)}`);
+    if (result.stdout) console.error(result.stdout.trim());
+    if (result.stderr) console.error(result.stderr.trim());
+  }
+}
+
+if (failed) process.exitCode = 1;
+else console.log(`Syntax OK (${files.length} files)`);

package/scripts/precommit-score.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { formatMarkdownReport, scoreFiles, summarizeRows } from './prose-score.mjs';
+
+function parseArgs(argv) {
+  const out = { files: [], gate: 30, lang: 'auto', maxFiles: 200 };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--gate' || arg === '--score-threshold') out.gate = Number(argv[++i]);
+    else if (arg === '--lang') out.lang = argv[++i] || 'auto';
+    else if (arg === '--max-files') out.maxFiles = Number(argv[++i]);
+    else if (!arg.startsWith('-')) out.files.push(arg);
+  }
+  if (!Number.isFinite(out.gate) || out.gate < 0 || out.gate > 100) {
+    throw new Error(`--gate expects a number from 0 to 100, got ${out.gate}`);
+  }
+  return out;
+}
+
+try {
+  const opts = parseArgs(process.argv.slice(2));
+  const rows = scoreFiles(opts.files, opts);
+  const summary = summarizeRows(rows);
+  console.log(formatMarkdownReport(rows, { gate: opts.gate, title: 'Patina pre-commit prose score' }));
+  if (summary.failedCount > 0) {
+    console.error(`\npatina-score: ${summary.failedCount}/${summary.fileCount} file(s) exceeded gate ${opts.gate}.`);
+    process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(`patina-score: ${error.message}`);
+  process.exitCode = 2;
+}

package/scripts/prose-score.mjs

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { analyzeText } from '../src/features/index.js';
+import { loadLexicon } from '../src/features/lexicon.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const DEFAULT_REPO_ROOT = resolve(__dirname, '..');
+export const DEFAULT_PROSE_EXTENSIONS = ['.md', '.mdx', '.txt', '.rst', '.adoc'];
+
+const lexiconCache = new Map();
+
+export function parseBoolean(value, defaultValue = false) {
+  if (value === undefined || value === null || value === '') return defaultValue;
+  return ['1', 'true', 'yes', 'on'].includes(String(value).trim().toLowerCase());
+}
+
+export function parseFileList(value = '') {
+  return String(value)
+    .split(/[\n,]+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function isProsePath(file, extensions = DEFAULT_PROSE_EXTENSIONS) {
+  const lower = file.toLowerCase();
+  return extensions.some((ext) => lower.endsWith(ext));
+}
+
+export function stripNonProse(markdown) {
+  return String(markdown || '')
+    .replace(/^---\n[\s\S]*?\n---\s*/, '\n')
+    .replace(/```[\s\S]*?```/g, '\n')
+    .replace(/~~~[\s\S]*?~~~/g, '\n')
+    .replace(/`[^`]*`/g, ' ')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/<svg[\s\S]*?<\/svg>/gi, '\n')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/^\s*\|.*\|\s*$/gm, '\n')
+    .replace(/^\s{0,3}#{1,6}\s+/gm, '')
+    .replace(/^\s{0,3}>\s?/gm, '')
+    .replace(/^\s*[-*+]\s+\[[ xX]\]\s+/gm, '')
+    .replace(/^\s*[-*+]\s+/gm, '')
+    .replace(/^\s*\d+[.)]\s+/gm, '')
+    .replace(/[ \t]{2,}/g, ' ')
+    .trim();
+}
+
+export function detectLanguage(file, text = '', requested = 'auto') {
+  const normalized = String(requested || 'auto').toLowerCase();
+  if (['ko', 'en', 'zh', 'ja'].includes(normalized)) return normalized;
+
+  const path = String(file || '').toLowerCase();
+  if (/(^|[._/-])kr([._/-]|$)|(^|[._/-])ko([._/-]|$)|korean/.test(path)) return 'ko';
+  if (/(^|[._/-])ja([._/-]|$)|japanese/.test(path)) return 'ja';
+  if (/(^|[._/-])zh([._/-]|$)|chinese/.test(path)) return 'zh';
+
+  const sample = String(text || '').slice(0, 12000);
+  const hangul = (sample.match(/[\uac00-\ud7af]/g) || []).length;
+  const kana = (sample.match(/[\u3040-\u30ff]/g) || []).length;
+  const cjk = (sample.match(/[\u4e00-\u9fff]/g) || []).length;
+  const latin = (sample.match(/[A-Za-z]/g) || []).length;
+  const cjkTotal = hangul + kana + cjk;
+  if (latin >= 80 && latin > cjkTotal * 2) return 'en';
+  if (hangul >= 8 && hangul >= kana && hangul >= cjk) return 'ko';
+  if (kana >= 8) return 'ja';
+  if (cjk >= 8) return 'zh';
+  return 'en';
+}
+
+function getLexicon(lang, repoRoot) {
+  const key = `${repoRoot}\0${lang}`;
+  if (!lexiconCache.has(key)) lexiconCache.set(key, loadLexicon(lang, repoRoot));
+  return lexiconCache.get(key);
+}
+
+export function scoreText(text, { file = '', lang = 'auto', gate = 30, repoRoot = DEFAULT_REPO_ROOT } = {}) {
+  const prose = stripNonProse(text);
+  const resolvedLang = detectLanguage(file, prose, lang);
+  const result = analyzeText(prose, {
+    lang: resolvedLang,
+    repoRoot,
+    lexicon: getLexicon(resolvedLang, repoRoot),
+  });
+  const paragraphCount = result.paragraphs.length;
+  const hotCount = result.paragraphs.filter((p) => p.hot).length;
+  const score = paragraphCount ? (hotCount / paragraphCount) * 100 : 0;
+  return {
+    file,
+    lang: resolvedLang,
+    paragraphCount,
+    hotCount,
+    score,
+    gate,
+    overGate: score > gate,
+    skipped: paragraphCount === 0,
+  };
+}
+
+function isInside(base, candidate) {
+  const rel = relative(base, candidate);
+  return rel === '' || (!rel.startsWith('..') && !rel.includes(`..${sep}`));
+}
+
+export function normalizeFiles(files, {
+  cwd = process.cwd(),
+  extensions = DEFAULT_PROSE_EXTENSIONS,
+  maxFiles = 50,
+} = {}) {
+  const base = resolve(cwd);
+  const seen = new Set();
+  const out = [];
+  for (const raw of files) {
+    if (!raw) continue;
+    const absolute = resolve(base, raw);
+    if (!isInside(base, absolute)) continue;
+    if (seen.has(absolute)) continue;
+    seen.add(absolute);
+    if (!existsSync(absolute)) continue;
+    if (!statSync(absolute).isFile()) continue;
+    const rel = relative(base, absolute);
+    if (!isProsePath(rel, extensions)) continue;
+    out.push(rel);
+    if (out.length >= maxFiles) break;
+  }
+  return out;
+}
+
+export function scoreFiles(files, {
+  cwd = process.cwd(),
+  repoRoot = DEFAULT_REPO_ROOT,
+  lang = 'auto',
+  gate = 30,
+  extensions = DEFAULT_PROSE_EXTENSIONS,
+  maxFiles = 50,
+} = {}) {
+  return normalizeFiles(files, { cwd, extensions, maxFiles }).map((file) => {
+    const body = readFileSync(resolve(cwd, file), 'utf8');
+    return scoreText(body, { file, lang, gate, repoRoot });
+  });
+}
+
+function statusIcon(row) {
+  if (row.skipped) return 'skip';
+  return row.overGate ? 'fail' : 'pass';
+}
+
+export function formatMarkdownReport(rows, { gate = 30, title = 'Patina prose hotspot report' } = {}) {
+  const lines = [
+    `# ${title}`,
+    '',
+    `Gate: **${Number(gate).toFixed(0)}%** hot prose paragraphs. This deterministic check flags editing hotspots; it is not an authorship verdict.`,
+    '',
+  ];
+
+  if (rows.length === 0) {
+    lines.push('No changed prose files were found.');
+    return lines.join('\n');
+  }
+
+  lines.push('| status | file | lang | paragraphs | hot | score |');
+  lines.push('|---|---|---:|---:|---:|---:|');
+  for (const row of rows) {
+    lines.push(
+      `| ${statusIcon(row)} | ${escapeCell(row.file)} | ${row.lang} | ${row.paragraphCount} | ${row.hotCount} | ${row.score.toFixed(1)}% |`
+    );
+  }
+  return lines.join('\n');
+}
+
+export function summarizeRows(rows) {
+  const maxScore = rows.reduce((max, row) => Math.max(max, row.score), 0);
+  const failed = rows.filter((row) => row.overGate);
+  return {
+    fileCount: rows.length,
+    failedCount: failed.length,
+    maxScore,
+    failed,
+  };
+}
+
+function escapeCell(value) {
+  return String(value).replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim();
+}

package/scripts/update-benchmark-ranges.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Refresh deterministic metric ranges for suspect-zone benchmark fixtures.
+//
+// This script intentionally does not call tests/quality/benchmark.mjs, because
+// the benchmark itself validates these ranges. It reads fixtures, runs the
+// in-tree analyzer, and writes a tight but reviewable regression baseline.
+
+import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+
+import { analyzeText } from '../src/features/index.js';
+import { loadLexicon } from '../src/features/lexicon.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+const FIXTURES_ROOT = resolve(REPO_ROOT, 'tests/fixtures/suspect-zones');
+const OUT_PATH = resolve(FIXTURES_ROOT, 'expected-ranges.json');
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
+const TOLERANCES = {
+  cv: 0.025,
+  mattr: 0.03,
+  lexiconDensity: 5,
+};
+
+function parseFixture(path) {
+  const raw = readFileSync(path, 'utf8');
+  const m = raw.match(FRONTMATTER_RE);
+  if (!m) throw new Error(`Missing frontmatter: ${path}`);
+  return { meta: yaml.load(m[1]), body: m[2].trim(), path };
+}
+
+function listFixtures() {
+  const out = [];
+  for (const lang of readdirSync(FIXTURES_ROOT)) {
+    const langDir = resolve(FIXTURES_ROOT, lang);
+    if (!statSync(langDir).isDirectory()) continue;
+    for (const cls of readdirSync(langDir)) {
+      const clsDir = resolve(langDir, cls);
+      if (!statSync(clsDir).isDirectory()) continue;
+      for (const file of readdirSync(clsDir)) {
+        if (file.endsWith('.md')) out.push(resolve(clsDir, file));
+      }
+    }
+  }
+  return out.sort();
+}
+
+function round(n, digits = 3) {
+  return Math.round(n * 10 ** digits) / 10 ** digits;
+}
+
+function range(value, tolerance, floor = 0) {
+  const low = Math.max(floor, round(value - tolerance));
+  const high = round(value + tolerance);
+  return [low, high];
+}
+
+function detectorHot(result) {
+  return {
+    burstiness: result.paragraphs.some((p) => p.burstiness?.band === 'low'),
+    mattr: result.paragraphs.some((p) => p.mattr?.band === 'low'),
+    lexicon: result.paragraphs.some((p) => p.lexicon?.hot),
+  };
+}
+
+function main() {
+  const lexicons = {};
+  const metrics = {};
+  for (const path of listFixtures()) {
+    const { meta, body } = parseFixture(path);
+    const lang = meta.language;
+    if (!lexicons[lang]) lexicons[lang] = loadLexicon(lang, REPO_ROOT);
+    const result = analyzeText(body, { lang, lexicon: lexicons[lang] });
+    const p = result.paragraphs[0] || {};
+    const cv = round(p.burstiness?.cv ?? 0);
+    const mattr = round(p.mattr?.value ?? 0);
+    const lexiconDensity = round(p.lexicon?.density ?? 0);
+    metrics[meta.fixture_id] = {
+      path: relative(REPO_ROOT, path),
+      lang,
+      class: meta.class,
+      expected_hot: meta.expected_hot,
+      predicted_hot: result.hot,
+      detectors: detectorHot(result),
+      cv_band: p.burstiness?.band,
+      cv_range: range(cv, TOLERANCES.cv),
+      mattr_band: p.mattr?.band,
+      mattr_range: range(mattr, TOLERANCES.mattr),
+      lexicon_density_range: range(lexiconDensity, TOLERANCES.lexiconDensity),
+      lexicon_hits: p.lexicon?.hits ?? [],
+    };
+  }
+
+  const out = {
+    schemaVersion: 1,
+    generatedBy: 'node scripts/update-benchmark-ranges.mjs',
+    generatedAt: new Date().toISOString(),
+    fixtureCount: Object.keys(metrics).length,
+    tolerances: TOLERANCES,
+    metrics,
+  };
+  writeFileSync(OUT_PATH, `${JSON.stringify(out, null, 2)}\n`);
+  console.log(`Wrote ${relative(REPO_ROOT, OUT_PATH)} (${out.fixtureCount} fixtures)`);
+}
+
+main();

package/src/api.js

@@ -0,0 +1,330 @@
+import { validateBaseURL } from './security.js';
+
+const DEFAULT_TIMEOUT = 120000;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_BASE_BACKOFF_MS = 1000;
+const DEFAULT_MAX_BACKOFF_MS = 30000;
+export const DEFAULT_TEMPERATURE = 0.7;
+
+// Status codes that warrant a retry. Network errors (no status, AbortError)
+// are also retryable; auth / validation 4xxs are not.
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+// Subclassed error so the retry loop can read `.status` + `.retryAfter`
+// without re-parsing strings.
+export class HttpError extends Error {
+  constructor(status, body, retryAfter) {
+    super(`HTTP ${status}: ${truncate(body)}`);
+    this.name = 'HttpError';
+    this.status = status;
+    this.body = body;
+    this.retryAfter = retryAfter;
+  }
+}
+
+function truncate(text, max = 256) {
+  if (typeof text !== 'string') return '';
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+function abortError(message = 'The operation was aborted') {
+  const err = new Error(message);
+  err.name = 'AbortError';
+  return err;
+}
+
+function remainingBudgetMs(deadline, now) {
+  if (deadline === undefined || deadline === null) return Infinity;
+  return Math.max(0, deadline - now());
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw abortError('External abort signal canceled LLM API call');
+  }
+}
+
+function sleepWithSignal(sleep, ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  if (!signal) return sleep(ms);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      reject(abortError('External abort signal canceled LLM API retry sleep'));
+    };
+    const cleanup = () => signal.removeEventListener('abort', onAbort);
+    signal.addEventListener('abort', onAbort, { once: true });
+    sleep(ms).then(
+      () => {
+        cleanup();
+        resolve();
+      },
+      (err) => {
+        cleanup();
+        reject(err);
+      }
+    );
+  });
+}
+
+export function isRetryable(err) {
+  if (!err) return false;
+  if (err.name === 'AbortError') return true;
+  if (typeof err.status === 'number') return RETRYABLE_STATUS.has(err.status);
+  // Heuristic for fetch network errors (no status set).
+  return err.name === 'TypeError' || err.code === 'ECONNRESET' || err.code === 'ECONNREFUSED';
+}
+
+// Honors Retry-After (seconds or HTTP-date). Falls back to exponential
+// backoff with up to 50% jitter, capped at maxDelay.
+export function computeBackoffMs(attempt, retryAfter, opts = {}) {
+  const {
+    base = DEFAULT_BASE_BACKOFF_MS,
+    max = DEFAULT_MAX_BACKOFF_MS,
+    now = () => Date.now(),
+    random = Math.random,
+  } = opts;
+
+  if (retryAfter) {
+    const asNumber = Number(retryAfter);
+    if (Number.isFinite(asNumber) && asNumber >= 0) {
+      return Math.min(asNumber * 1000, max);
+    }
+    const asDateMs = Date.parse(retryAfter);
+    if (Number.isFinite(asDateMs)) {
+      return Math.max(0, Math.min(asDateMs - now(), max));
+    }
+  }
+
+  const exp = Math.min(base * 2 ** attempt, max);
+  const jitter = random() * exp * 0.5;
+  return Math.min(exp + jitter, max);
+}
+
+// Bounded-concurrency semaphore. `max <= 0` yields a no-op gate for callers
+// that explicitly opt into unlimited fanout.
+export function createSemaphore(max) {
+  if (!max || max <= 0) {
+    return { acquire: () => Promise.resolve(() => {}) };
+  }
+  let active = 0;
+  const queue = [];
+  const drain = () => {
+    if (active < max && queue.length) {
+      active++;
+      const resolve = queue.shift();
+      resolve(() => {
+        active--;
+        drain();
+      });
+    }
+  };
+  return {
+    acquire() {
+      return new Promise((resolve) => {
+        queue.push(resolve);
+        if (active < max) drain();
+      });
+    },
+  };
+}
+
+export async function callLLM({
+  prompt,
+  apiKey,
+  baseURL = 'https://api.openai.com/v1',
+  model = 'gpt-4o',
+  temperature = DEFAULT_TEMPERATURE,
+  seed,
+  timeout = DEFAULT_TIMEOUT,
+  maxRetries = DEFAULT_MAX_RETRIES,
+  deadline,
+  signal,
+  allowInsecureBaseURL = false,
+  onResponse,
+  cache,
+  // Allows tests to inject a deterministic delay function.
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+}) {
+  validateBaseURL(baseURL, { allowInsecure: allowInsecureBaseURL });
+  const url = `${baseURL}/chat/completions`;
+  const body = {
+    model,
+    messages: [{ role: 'user', content: prompt }],
+    temperature,
+  };
+  if (seed !== undefined && seed !== null) body.seed = seed;
+
+  const cached = cache?.get?.({ prompt, model, temperature, baseURL });
+  if (cached) {
+    onResponse?.({
+      provider: 'cache',
+      model: cached.responseModel ?? cached.model ?? model,
+      requestedModel: model,
+      temperature,
+      seed: seed ?? null,
+      usage: cached.usage ?? null,
+      rawResponse: null,
+      content: cached.content,
+      cache: { hit: true, key: cached.key, path: cached.path },
+    });
+    return cached.content;
+  }
+
+  let lastError;
+  let attemptsMade = 0;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      throwIfAborted(signal);
+    } catch (err) {
+      lastError = err;
+      break;
+    }
+    const remainingBeforeAttempt = remainingBudgetMs(deadline, now);
+    if (remainingBeforeAttempt <= 0) {
+      lastError = new Error('LLM API deadline exceeded before the next retry attempt');
+      break;
+    }
+
+    const controller = new AbortController();
+    let timer;
+    let signalCleanup = () => {};
+    try {
+      const attemptTimeout = Math.min(timeout, remainingBeforeAttempt);
+      timer = setTimeout(() => controller.abort(), attemptTimeout);
+      if (signal) {
+        const onAbort = () => controller.abort();
+        signal.addEventListener('abort', onAbort, { once: true });
+        signalCleanup = () => signal.removeEventListener('abort', onAbort);
+      }
+      attemptsMade++;
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new HttpError(
+          response.status,
+          errorText,
+          response.headers.get('retry-after')
+        );
+      }
+
+      const data = await response.json();
+      const content = data.choices?.[0]?.message?.content;
+      if (!content) {
+        throw new Error('Empty response from LLM API');
+      }
+
+      const metadata = {
+        provider: 'openai-http',
+        model: data.model ?? model,
+        requestedModel: model,
+        temperature,
+        seed: seed ?? null,
+        usage: data.usage ?? null,
+        rawResponse: data,
+        content,
+        cache: cache ? { hit: false } : null,
+      };
+      cache?.set?.({ prompt, model, temperature, baseURL }, content, metadata);
+      onResponse?.(metadata);
+
+      return content;
+    } catch (err) {
+      lastError = err;
+      if (signal?.aborted) break;
+      const remainingAfterAttempt = remainingBudgetMs(deadline, now);
+      if (remainingAfterAttempt <= 0) {
+        lastError = new Error(`LLM API deadline exceeded after attempt ${attempt + 1}: ${err.message}`);
+        break;
+      }
+      if (attempt < maxRetries && isRetryable(err)) {
+        const delay = computeBackoffMs(attempt, err.retryAfter, {
+          max: Math.min(DEFAULT_MAX_BACKOFF_MS, remainingAfterAttempt),
+          now,
+        });
+        await sleepWithSignal(sleep, delay, signal);
+        continue;
+      }
+      // Non-retryable or out of attempts — bail out.
+      break;
+    } finally {
+      clearTimeout(timer);
+      signalCleanup();
+    }
+  }
+
+  const err = new Error(`LLM API failed after ${attemptsMade || 1} attempts: ${lastError?.message ?? 'unknown'}`);
+  if (lastError?.name === 'AbortError') err.name = 'AbortError';
+  if (typeof lastError?.status === 'number') err.status = lastError.status;
+  throw err;
+}
+
+export async function callLLMMultiple({
+  prompt,
+  models,
+  apiKey,
+  baseURL = 'https://api.openai.com/v1',
+  temperature = DEFAULT_TEMPERATURE,
+  seed,
+  timeout = DEFAULT_TIMEOUT,
+  allowInsecureBaseURL = false,
+  deadline,
+  signal,
+  maxConcurrency,
+  onStart,
+  onComplete,
+  onResponse,
+  cache,
+  callLLM: callLLMImpl = callLLM,
+  sleep,
+  now = () => Date.now(),
+}) {
+  validateBaseURL(baseURL, { allowInsecure: allowInsecureBaseURL });
+  const effectiveMaxConcurrency =
+    maxConcurrency === undefined || maxConcurrency === null
+      ? Math.min(models.length, 3)
+      : maxConcurrency;
+  const sem = createSemaphore(effectiveMaxConcurrency);
+  const promises = models.map(async (model) => {
+    const release = await sem.acquire();
+    if (onStart) onStart(model);
+    try {
+      const result = await callLLMImpl({
+        prompt,
+        apiKey,
+        baseURL,
+        model,
+        temperature,
+        seed,
+        timeout,
+        deadline,
+        signal,
+        allowInsecureBaseURL,
+        onResponse,
+        cache,
+        sleep,
+        now,
+      });
+      if (onComplete) onComplete(model, true);
+      return { model, result, ok: true };
+    } catch (err) {
+      if (onComplete) onComplete(model, false);
+      return { model, error: err.message, ok: false };
+    } finally {
+      release();
+    }
+  });
+
+  return Promise.all(promises);
+}