model-eol 0.2.3 → 0.3.0

package/bot.yml.example

@@ -0,0 +1,112 @@
+name: model-eol bot
+
+on:
+  schedule:
+    - cron: '17 4 * * 1'
+  workflow_dispatch:
+
+concurrency:
+  group: model-eol-bot
+  cancel-in-progress: false
+
+env:
+  # Major-line pin: receives compatible fixes and refreshed bundled feeds.
+  MODEL_EOL_PACKAGE: model-eol@0
+
+jobs:
+  plan:
+    name: plan and evaluate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      # The eval job must never hold write tokens.
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Build the versioned plan
+        run: |
+          PLAN_ARGS=(plan .)
+          if [ ! -f .model-eol.json ]; then PLAN_ARGS+=(--days 90 --scope direct); fi
+          npx --yes --package="$MODEL_EOL_PACKAGE" model-eol "${PLAN_ARGS[@]}" > model-eol-plan.json
+      - name: Run the configured eval harness
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          MODEL_EOL_EVAL_COMMAND: ${{ vars.MODEL_EOL_EVAL_COMMAND }}
+          MODEL_EOL_PLAN: ${{ github.workspace }}/model-eol-plan.json
+          MODEL_EOL_REPORT: ${{ github.workspace }}/model-eol-report.md
+        run: |
+          # The workflow variable is an explicit override. Otherwise, use the
+          # eval.command already validated from .model-eol.json by the plan step.
+          if [ -z "${MODEL_EOL_EVAL_COMMAND:-}" ] && [ -f .model-eol.json ]; then
+            MODEL_EOL_EVAL_COMMAND="$(node --input-type=module -e '
+              import fs from "node:fs"
+              const config = JSON.parse(fs.readFileSync(".model-eol.json", "utf8"))
+              if (typeof config.eval?.command === "string") process.stdout.write(config.eval.command)
+            ')"
+          fi
+          # Supply a provider-backed harness for this repository. It may read the
+          # plan and write Markdown to MODEL_EOL_REPORT, but this job has read-only
+          # contents permission and the publish job receives no provider keys.
+          if [ -n "${MODEL_EOL_EVAL_COMMAND:-}" ]; then
+            set +e
+            sh -c "$MODEL_EOL_EVAL_COMMAND"
+            eval_status=$?
+            set -e
+            printf '%s\n' "$eval_status" > model-eol-eval-exit-code
+          else
+            : > "$MODEL_EOL_REPORT"
+            printf '0\n' > model-eol-eval-exit-code
+          fi
+      - name: Upload plan and eval report
+        uses: actions/upload-artifact@v4
+        with:
+          name: model-eol-plan-and-report
+          path: |
+            model-eol-plan.json
+            model-eol-report.md
+            model-eol-eval-exit-code
+
+  publish:
+    name: publish migration work
+    needs: plan
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # model-eol-bot authenticates its own temporary HTTPS clones and
+          # pushes with GITHUB_TOKEN; no checkout credential is persisted.
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Download the plan and eval report
+        uses: actions/download-artifact@v4
+        with:
+          name: model-eol-plan-and-report
+      - name: Publish model-eol PRs and issues
+        env:
+          GITHUB_TOKEN: ${{ secrets.MODEL_EOL_BOT_TOKEN || secrets.GITHUB_TOKEN }}
+          MODEL_EOL_PLAN_FILE: ${{ github.workspace }}/model-eol-plan.json
+          MODEL_EOL_EVAL_REPORT_FILE: ${{ github.workspace }}/model-eol-report.md
+          MODEL_EOL_EVAL_STATUS_FILE: ${{ github.workspace }}/model-eol-eval-exit-code
+          MODEL_EOL_TOKEN_KIND: ${{ secrets.MODEL_EOL_BOT_TOKEN && 'external-token' || 'github-token' }}
+        run: npx --yes --package="$MODEL_EOL_PACKAGE" model-eol-bot --repo "${{ github.repository }}" --target-dir .
+
+# Security and checks note:
+# A PR made with GITHUB_TOKEN does not trigger pull_request workflows, so checks
+# may be skipped even though this job has opened the PR. For required checks, use
+# a narrowly scoped fine-grained PAT or a GitHub App installation token in the
+# optional MODEL_EOL_BOT_TOKEN secret instead.
+# Keep provider API keys only in the read-only plan/eval job and never pass them to
+# the publish job.
+# Set feeds.allow_vendored_fallback: true in .model-eol.json only for degraded report-only runs; the default is false.
+# Independent concurrent invocations need external mutual exclusion; this tool does not lock.

package/check.mjs

@@ -2,7 +2,7 @@
 // model-eol reference CLI - zero dependencies.
 //
 // Default mode preserves the original CI gate:
-//   node check.mjs [paths...] [--days N] [--feeds DIR] [--via DISTRIBUTOR] [--scope all|direct] [--json] [--include-docs] [--allow-incomplete]
+//   node check.mjs [paths...] [--config FILE] [--days N] [--feeds DIR] [--via DISTRIBUTOR] [--scope all|direct] [--json] [--include-docs] [--allow-incomplete]
 //
 // New inventory modes:
 //   node check.mjs inventory [paths...] [--json|--format json|cyclonedx|text]
@@ -14,10 +14,12 @@
 // exit codes: check/alert 0 = clear, 1 = finding, 2 = usage error;
 // apply 0 = all items applied, 1 = item refused, 2 = usage or plan error.
 
+import fs from 'node:fs'
 import path from 'node:path'
 
 import { applyPlan } from './lib/apply.mjs'
 import { parseCliArgs } from './lib/cli.mjs'
+import { CLI_DEFAULT_CONFIG, DEFAULT_CONFIG, loadConfig, normalizeConfig } from './lib/config.mjs'
 import { findingFromRef, isBad, loadFeeds } from './lib/feeds.mjs'
 import { buildPlan } from './lib/plan.mjs'
 import {
@@ -32,8 +34,46 @@ import {
   formatInventoryCycloneDX,
   formatSchedule,
 } from './lib/reports.mjs'
-import { addedLinesForTargets, filterFindingsToChanged, incompleteScanNotes, scanTargets } from './lib/scanner.mjs'
+import { addedLinesForTargets, filterFindingsToChanged, gitRootFor, incompleteScanNotes, scanTargets } from './lib/scanner.mjs'
 
+const rootForTarget = target => {
+  const absolute = path.resolve(target)
+  let stat
+  try {
+    stat = fs.lstatSync(absolute)
+  } catch {
+    return null
+  }
+  let resolved = absolute
+  try {
+    resolved = fs.realpathSync(absolute)
+  } catch {
+  }
+  try {
+    const gitRoot = gitRootFor(resolved)
+    if (gitRoot) return gitRoot
+  } catch {
+  }
+  return stat.isDirectory() ? resolved : path.dirname(resolved)
+}
+
+const configForTargets = ({ targets, explicit }) => {
+  const roots = [...new Set(targets.map(rootForTarget).filter(Boolean))]
+  if (explicit !== null) {
+    if (!explicit) throw new Error('--config must be a non-empty path')
+    return { file: path.resolve(explicit), roots }
+  }
+
+  const files = [...new Set(roots
+    .map(root => path.join(root, '.model-eol.json'))
+    .filter(file => fs.existsSync(file)))]
+  if (files.length > 1) {
+    throw new Error(`multiple .model-eol.json files found (${files.join(', ')}); use --config FILE to choose one`)
+  }
+  return { file: files[0] ?? null, roots }
+}
+
+const main = () => {
 const COMMANDS = new Set(['check', 'inventory', 'schedule', 'alert', 'plan', 'apply', 'help'])
 const args = process.argv.slice(2)
 
@@ -45,6 +85,7 @@ try {
     args,
     options: {
       days: { type: 'string' },
+      config: { type: 'string' },
       feeds: { type: 'string' },
       via: { type: 'string' },
       scope: { type: 'string' },
@@ -62,16 +103,12 @@ try {
   })
 } catch (error) {
   console.error(error.message)
-  process.exit(2)
+  return 2
 }
 
 const { values, positionals } = parsed
 if (values.help) command = 'help'
 
-const DAYS = Number(values.days ?? '90')
-const FEEDS_DIR = values.feeds ?? path.join(import.meta.dirname, 'feeds')
-const VIA = values.via ?? null // e.g. azure-ai-foundry, aws-bedrock
-const SCOPE = values.scope ?? 'all'
 const FORMAT = values.format ?? null
 const PLAN_FILE = values.plan ?? null
 const AS_JSON = values.json ?? false
@@ -85,12 +122,12 @@ if (command === 'help') {
   console.log(`model-eol
 
 Usage:
-  node check.mjs [paths...] [--days N] [--feeds DIR] [--via DISTRIBUTOR] [--scope all|direct] [--json] [--include-docs] [--allow-incomplete]
-  node check.mjs check [paths...] [--days N] [--scope all|direct] [--json] [--changed BASE_REF] [--allow-incomplete]
-  node check.mjs inventory [paths...] [--json] [--format json|cyclonedx|text]
-  node check.mjs schedule [paths...] [--days N] [--json]
-  node check.mjs alert [paths...] [--days N] [--scope all|direct] [--format github|markdown|badge] [--json]
-  node check.mjs plan [paths...] [--days N] [--scope all|direct] [--via DISTRIBUTOR] [--feeds DIR] [--allow-incomplete]
+  node check.mjs [paths...] [--config FILE] [--days N] [--feeds DIR] [--via DISTRIBUTOR] [--scope all|direct] [--json] [--include-docs] [--allow-incomplete]
+  node check.mjs check [paths...] [--config FILE] [--days N] [--scope all|direct] [--json] [--changed BASE_REF] [--allow-incomplete]
+  node check.mjs inventory [paths...] [--config FILE] [--json] [--format json|cyclonedx|text]
+  node check.mjs schedule [paths...] [--config FILE] [--days N] [--json]
+  node check.mjs alert [paths...] [--config FILE] [--days N] [--scope all|direct] [--format github|markdown|badge] [--json]
+  node check.mjs plan [paths...] [--config FILE] [--days N] [--scope all|direct] [--via DISTRIBUTOR] [--feeds DIR] [--allow-incomplete]
   node check.mjs apply --plan plan.json [--dry-run]
 
 Commands:
@@ -107,43 +144,70 @@ Commands:
 Scopes:
   all        Check every tracked model ID found. This preserves the original behavior.
   direct     Check direct API and generic model references; leave cloud/gateway refs in inventory.
+
+Configuration:
+  .model-eol.json is loaded automatically from the target repository root.
+  --config FILE selects an explicit config. Explicit CLI flags override config values.
+
+Exit codes:
+  0  Clean, or report generated successfully.
+  1  Findings, alert errors, or refused apply items.
+  2  Usage, feed, scan, or plan errors.
+  3  Output stream failure other than EPIPE.
 `)
-  process.exit(0)
+  return 0
 }
 
 if (command === 'apply') {
   if (!PLAN_FILE || positionals.length) {
     console.error('apply requires --plan plan.json and accepts no target paths')
-    process.exit(2)
+    return 2
   }
   try {
     const result = applyPlan({ planPath: PLAN_FILE, dryRun: DRY_RUN, rootDir: process.cwd() })
-    process.exit(result.failed ? 1 : 0)
+    return result.failed ? 1 : 0
   } catch (e) {
     console.error(`failed to apply plan ${PLAN_FILE}: ${e.message}`)
-    process.exit(2)
+    return 2
   }
 }
 
+let configLocation
+let repositoryConfig
+try {
+  configLocation = configForTargets({ targets, explicit: values.config ?? null })
+  repositoryConfig = configLocation.file
+    ? loadConfig(configLocation.file, { defaults: DEFAULT_CONFIG, allowMissing: false })
+    : normalizeConfig({}, { defaults: CLI_DEFAULT_CONFIG })
+} catch (e) {
+  console.error(`failed to load repository config: ${e.message}`)
+  return 2
+}
+
+const DAYS = Number(values.days ?? repositoryConfig.days)
+const FEEDS_DIR = values.feeds ?? path.join(import.meta.dirname, 'feeds')
+const VIA = values.via ?? repositoryConfig.via // e.g. azure-ai-foundry, aws-bedrock
+const SCOPE = values.scope ?? repositoryConfig.scope
+
 if (!Number.isFinite(DAYS) || !Number.isInteger(DAYS) || DAYS < 0) {
   console.error('--days must be a finite non-negative integer')
-  process.exit(2)
+  return 2
 }
 if (!['all', 'direct'].includes(SCOPE)) {
   console.error('--scope must be all or direct')
-  process.exit(2)
+  return 2
 }
 if (CHANGED_BASE !== null && command !== 'check') {
   console.error('--changed is only supported by the check command')
-  process.exit(2)
+  return 2
 }
 if (command === 'alert' && FORMAT !== null && !['github', 'markdown', 'badge', 'json'].includes(FORMAT)) {
   console.error('--format must be github, markdown, badge, or json for alert')
-  process.exit(2)
+  return 2
 }
 if (command === 'inventory' && FORMAT !== null && !['json', 'cyclonedx', 'text'].includes(FORMAT)) {
   console.error('--format must be json, cyclonedx, or text for inventory')
-  process.exit(2)
+  return 2
 }
 
 let feedData
@@ -151,11 +215,11 @@ try {
   feedData = loadFeeds(FEEDS_DIR)
 } catch (e) {
   console.error(`failed to load feeds from ${FEEDS_DIR}: ${e.message}`)
-  process.exit(2)
+  return 2
 }
 if (feedData.entries.size === 0) {
   console.error(`no feed entries loaded from ${FEEDS_DIR}`)
-  process.exit(2)
+  return 2
 }
 
 let scan
@@ -165,10 +229,14 @@ try {
     entries: feedData.entries,
     keys: feedData.keys,
     includeDocs: INCLUDE_DOCS,
+    ignoreModels: repositoryConfig.ignore.models,
+    ignorePaths: repositoryConfig.ignore.paths,
+    ignoreRoots: configLocation.roots,
+    ignoredFiles: configLocation.file ? [configLocation.file] : [],
   })
 } catch (e) {
   console.error(`scan failed: ${e.message}`)
-  process.exit(2)
+  return 2
 }
 
 const incompleteNotes = incompleteScanNotes(scan.notes)
@@ -179,23 +247,22 @@ if (incompleteNotes.length && (command === 'check' || command === 'plan')) {
     const location = note.file ? ` (${note.file})` : ''
     console.error(`  ${note.reason}${location}${note.message ? `: ${note.message}` : ''}`)
   }
-  if (!ALLOW_INCOMPLETE) process.exit(2)
+  if (!ALLOW_INCOMPLETE) return 2
 }
 
 const findings = scan.modelRefs.map(ref => findingFromRef(ref, { days: DAYS, via: VIA }))
 const checkFindings = SCOPE === 'direct'
   ? findings.filter(f => f.usage === 'direct-api' || f.usage === 'model-reference')
   : findings
-const changedFindings = CHANGED_BASE === null
-  ? checkFindings
-  : (() => {
-      try {
-        return filterFindingsToChanged(checkFindings, addedLinesForTargets(targets, CHANGED_BASE))
-      } catch (e) {
-        console.error(`--changed failed: ${e.message}`)
-        process.exit(2)
-      }
-    })()
+let changedFindings = checkFindings
+if (CHANGED_BASE !== null) {
+  try {
+    changedFindings = filterFindingsToChanged(checkFindings, addedLinesForTargets(targets, CHANGED_BASE))
+  } catch (e) {
+    console.error(`--changed failed: ${e.message}`)
+    return 2
+  }
+}
 const bad = changedFindings.filter(isBad)
 const inventory = () => buildInventory({ scan, findings, days: DAYS, via: VIA, scope: SCOPE, targets })
 const schedule = () => buildSchedule(inventory())
@@ -210,7 +277,7 @@ if (command === 'plan') {
     via: VIA,
     scope: SCOPE,
   }), null, 2))
-  process.exit(0)
+  return 0
 }
 
 if (command === 'check') {
@@ -219,7 +286,7 @@ if (command === 'check') {
   } else {
     console.log(formatCheck({ findings: changedFindings, bad, scannedFiles: scan.files.length, days: DAYS, scope: SCOPE }))
   }
-  process.exit(bad.length ? 1 : 0)
+  return bad.length ? 1 : 0
 }
 
 if (command === 'inventory') {
@@ -232,7 +299,7 @@ if (command === 'inventory') {
   } else {
     console.log(formatInventory(inv, DAYS))
   }
-  process.exit(0)
+  return 0
 }
 
 if (command === 'schedule') {
@@ -242,7 +309,7 @@ if (command === 'schedule') {
   } else {
     console.log(formatSchedule(sched, DAYS))
   }
-  process.exit(0)
+  return 0
 }
 
 if (command === 'alert') {
@@ -256,8 +323,46 @@ if (command === 'alert') {
   } else {
     console.log(formatAlertGithub(payload, DAYS))
   }
-  process.exit(payload.errors.length ? 1 : 0)
+  return payload.errors.length ? 1 : 0
 }
 
 console.error(`unknown command: ${command}`)
-process.exit(2)
+return 2
+}
+
+const writeAndCapture = (stream, chunk) => new Promise(resolve => {
+  let error = null
+  let settling = false
+  const settle = nextError => {
+    if (nextError && !error) error = nextError
+    if (settling) return
+    settling = true
+    setImmediate(() => {
+      stream.off('error', onError)
+      resolve(error)
+    })
+  }
+  const onError = nextError => settle(nextError)
+  stream.on('error', onError)
+  try {
+    stream.write(chunk, settle)
+  } catch (writeError) {
+    settle(writeError)
+  }
+})
+const drainStream = stream => writeAndCapture(stream, '')
+
+const exitCode = main()
+const [stdoutError, stderrError] = await Promise.all([
+  drainStream(process.stdout),
+  drainStream(process.stderr),
+])
+const outputError = [stdoutError, stderrError].find(error => error && error.code !== 'EPIPE')
+let finalExitCode = exitCode
+if (exitCode === 0 && outputError) {
+  finalExitCode = 3
+  const diagnosticStream = stderrError ? (stdoutError ? null : process.stdout) : process.stderr
+  const detail = String(outputError.code ?? outputError.message ?? 'unknown error').replace(/[\r\n]+/g, ' ')
+  if (diagnosticStream) await writeAndCapture(diagnosticStream, `model-eol: output failed: ${detail}\n`)
+}
+process.exit(finalExitCode)

package/lib/config.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs'
+
+import { MAX_REPORT_BYTES, MAX_TIMEOUT_MS, MIN_TIMEOUT_MS } from './validate-feed.mjs'
+
+const frozenArray = () => Object.freeze([])
+
+export const DEFAULT_CONFIG = Object.freeze({
+  days: 90,
+  scope: 'direct',
+  via: null,
+  feeds: Object.freeze({ allow_vendored_fallback: false }),
+  ignore: Object.freeze({ models: frozenArray(), paths: frozenArray() }),
+  issues: Object.freeze({ enabled: true }),
+  eval: Object.freeze({ command: null, timeout_ms: 600000, max_report_bytes: 65536, pass_env: frozenArray() }),
+})
+
+export const CLI_DEFAULT_CONFIG = Object.freeze({
+  ...DEFAULT_CONFIG,
+  scope: 'all',
+})
+
+const copyDefaults = defaults => ({
+  days: defaults.days,
+  scope: defaults.scope,
+  via: defaults.via,
+  feeds: { allow_vendored_fallback: defaults.feeds.allow_vendored_fallback },
+  ignore: {
+    models: [...defaults.ignore.models],
+    paths: [...defaults.ignore.paths],
+  },
+  issues: { enabled: defaults.issues.enabled },
+  eval: {
+    command: defaults.eval.command,
+    timeout_ms: defaults.eval.timeout_ms,
+    max_report_bytes: defaults.eval.max_report_bytes,
+    pass_env: [...defaults.eval.pass_env],
+  },
+})
+
+const assert = (condition, message) => {
+  if (!condition) throw new Error(`invalid .model-eol.json: ${message}`)
+}
+
+const assertKnownKeys = (value, label, allowed) => {
+  for (const key of Object.keys(value)) {
+    const fullKey = label ? `${label}.${key}` : key
+    assert(allowed.has(key), `unknown key "${fullKey}"`)
+  }
+}
+
+const stringArray = (value, label) => {
+  assert(Array.isArray(value), `${label} must be an array`)
+  assert(value.every(item => typeof item === 'string' && item.length > 0), `${label} must contain non-empty strings`)
+  return value.slice()
+}
+
+const CREDENTIAL_ENV_PATTERN = /^(?:GITHUB_|GH_|ACTIONS_|SSH_|AWS_SECRET)|(?:TOKEN|SECRET|PASSWORD|CREDENTIAL)/i
+
+export const normalizeConfig = (raw, { defaults = DEFAULT_CONFIG } = {}) => {
+  assert(raw && typeof raw === 'object' && !Array.isArray(raw), 'root must be an object')
+  assertKnownKeys(raw, '', new Set(['days', 'scope', 'via', 'feeds', 'ignore', 'issues', 'eval']))
+  const config = copyDefaults(defaults)
+
+  if (raw.days !== undefined) {
+    assert(Number.isInteger(raw.days) && raw.days >= 0, 'days must be a non-negative integer')
+    config.days = raw.days
+  }
+  if (raw.scope !== undefined) {
+    assert(raw.scope === 'all' || raw.scope === 'direct', 'scope must be all or direct')
+    config.scope = raw.scope
+  }
+  if (raw.via !== undefined) {
+    assert(raw.via === null || (typeof raw.via === 'string' && raw.via.length > 0), 'via must be null or a non-empty string')
+    config.via = raw.via
+  }
+  if (raw.feeds !== undefined) {
+    assert(raw.feeds && typeof raw.feeds === 'object' && !Array.isArray(raw.feeds), 'feeds must be an object')
+    assertKnownKeys(raw.feeds, 'feeds', new Set(['allow_vendored_fallback']))
+    if (raw.feeds.allow_vendored_fallback !== undefined) {
+      assert(typeof raw.feeds.allow_vendored_fallback === 'boolean', 'feeds.allow_vendored_fallback must be boolean')
+      config.feeds.allow_vendored_fallback = raw.feeds.allow_vendored_fallback
+    }
+  }
+  if (raw.ignore !== undefined) {
+    assert(raw.ignore && typeof raw.ignore === 'object' && !Array.isArray(raw.ignore), 'ignore must be an object')
+    assertKnownKeys(raw.ignore, 'ignore', new Set(['models', 'paths']))
+    if (raw.ignore.models !== undefined) config.ignore.models = stringArray(raw.ignore.models, 'ignore.models')
+    if (raw.ignore.paths !== undefined) config.ignore.paths = stringArray(raw.ignore.paths, 'ignore.paths')
+  }
+  if (raw.issues !== undefined) {
+    assert(raw.issues && typeof raw.issues === 'object' && !Array.isArray(raw.issues), 'issues must be an object')
+    assertKnownKeys(raw.issues, 'issues', new Set(['enabled']))
+    if (raw.issues.enabled !== undefined) assert(typeof raw.issues.enabled === 'boolean', 'issues.enabled must be boolean')
+    if (raw.issues.enabled !== undefined) config.issues.enabled = raw.issues.enabled
+  }
+  if (raw.eval !== undefined) {
+    assert(raw.eval && typeof raw.eval === 'object' && !Array.isArray(raw.eval), 'eval must be an object')
+    assertKnownKeys(raw.eval, 'eval', new Set(['command', 'timeout_ms', 'max_report_bytes', 'pass_env']))
+    if (raw.eval.command !== undefined) {
+      assert(raw.eval.command === null || (typeof raw.eval.command === 'string' && raw.eval.command.length > 0), 'eval.command must be null or a non-empty string')
+      config.eval.command = raw.eval.command
+    }
+    if (raw.eval.timeout_ms !== undefined) {
+      assert(Number.isSafeInteger(raw.eval.timeout_ms) && raw.eval.timeout_ms >= MIN_TIMEOUT_MS && raw.eval.timeout_ms <= MAX_TIMEOUT_MS, `eval.timeout_ms must be a safe integer between ${MIN_TIMEOUT_MS} and ${MAX_TIMEOUT_MS}`)
+      config.eval.timeout_ms = raw.eval.timeout_ms
+    }
+    if (raw.eval.max_report_bytes !== undefined) {
+      assert(Number.isSafeInteger(raw.eval.max_report_bytes) && raw.eval.max_report_bytes > 0 && raw.eval.max_report_bytes <= MAX_REPORT_BYTES, `eval.max_report_bytes must be a safe positive integer <= ${MAX_REPORT_BYTES}`)
+      config.eval.max_report_bytes = raw.eval.max_report_bytes
+    }
+    if (raw.eval.pass_env !== undefined) {
+      const passEnv = stringArray(raw.eval.pass_env, 'eval.pass_env')
+      for (const name of passEnv) assert(!CREDENTIAL_ENV_PATTERN.test(name), `eval.pass_env variable "${name}" is not allowed`)
+      config.eval.pass_env = passEnv
+    }
+  }
+
+  return config
+}
+
+export const loadConfig = (file, { defaults = DEFAULT_CONFIG, allowMissing = true } = {}) => {
+  if (!fs.existsSync(file)) {
+    if (allowMissing) return normalizeConfig({}, { defaults })
+    throw new Error(`could not read config ${file}: file not found`)
+  }
+  let value
+  try {
+    value = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`could not read config ${file}: ${error.message}`)
+  }
+  return normalizeConfig(value, { defaults })
+}

package/lib/glob.mjs

@@ -0,0 +1,35 @@
+const escapeRegExp = value => value.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+
+export const normalizeRepoPath = value => String(value ?? '')
+  .replaceAll('\\', '/')
+  .replace(/^\.\//, '')
+  .replace(/^\/+/, '')
+
+export const globRegex = pattern => {
+  let source = ''
+  const value = normalizeRepoPath(pattern)
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i]
+    if (char === '*' && value[i + 1] === '*') {
+      if (value[i + 2] === '/') {
+        source += '(?:.*/)?'
+        i += 2
+      } else {
+        source += '.*'
+        i++
+      }
+    } else if (char === '*') {
+      source += '[^/]*'
+    } else if (char === '?') {
+      source += '[^/]'
+    } else {
+      source += escapeRegExp(char)
+    }
+  }
+  return new RegExp(`^${source}$`)
+}
+
+export const matchesGlob = (file, pattern) => globRegex(pattern).test(normalizeRepoPath(file))
+
+export const matchesAnyGlob = (file, patterns = []) =>
+  patterns.some(pattern => matchesGlob(file, pattern))