model-eol 0.2.4 → 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,7 +34,44 @@ 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'])
@@ -46,6 +85,7 @@ try {
     args,
     options: {
       days: { type: 'string' },
+      config: { type: 'string' },
       feeds: { type: 'string' },
       via: { type: 'string' },
       scope: { type: 'string' },
@@ -69,10 +109,6 @@ try {
 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
@@ -86,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:
@@ -109,6 +145,10 @@ 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.
@@ -132,6 +172,23 @@ if (command === 'apply') {
   }
 }
 
+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')
   return 2
@@ -172,6 +229,10 @@ 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}`)

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))

package/lib/scanner.mjs

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 
 import { buildModelPattern } from './feeds.mjs'
+import { matchesAnyGlob, matchesGlob, normalizeRepoPath } from './glob.mjs'
 
 export const CODE_EXT = new Set([
   '.c', '.cc', '.cjs', '.cpp', '.cs', '.cxx', '.go', '.h', '.hpp', '.java', '.js',
@@ -122,6 +123,7 @@ const classifyRef = ({ file, line, lines, publisher }) => {
 
 const isScannable = (file, includeDocs) => {
   const basename = path.basename(file)
+  if (basename === '.model-eol.json') return false
   if (basename === '.env' || basename.startsWith('.env.')) return true
   const ext = path.extname(file)
   return CODE_EXT.has(ext) || (includeDocs && DOC_EXT.has(ext))
@@ -241,17 +243,58 @@ export const addedLinesForTargets = (targets, baseRef) => {
 export const filterFindingsToChanged = (findings, addedLines) =>
   findings.filter(finding => addedLines.has(changedKey(finding.file, finding.line)))
 
-const collectFilesDetailed = (targets, { includeDocs = false } = {}) => {
+const collectFilesDetailed = (targets, {
+  includeDocs = false,
+  ignorePaths = [],
+  ignoreRoots = [],
+  ignoredFiles = [],
+} = {}) => {
   const files = []
   const notes = []
   const validTargets = []
   const seen = new Set()
+  const canonicalPath = value => {
+    const resolved = path.resolve(value)
+    try {
+      return fs.realpathSync(resolved)
+    } catch {
+      return resolved
+    }
+  }
+  const excludedFiles = new Set(ignoredFiles.map(canonicalPath))
+  const roots = ignoreRoots.map(canonicalPath)
   let fileLimitWarned = false
   let stopped = false
 
   const note = value => notes.push(value)
+  const repoPathsFor = absolute => {
+    const resolved = canonicalPath(absolute)
+    const repoPaths = []
+    for (const root of roots) {
+      const relative = path.relative(root, resolved)
+      if (relative === '' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) continue
+      repoPaths.push(normalizeRepoPath(relative))
+    }
+    return repoPaths
+  }
+  const matchesIgnoredRepoPath = repoPath => matchesAnyGlob(repoPath, ignorePaths) ||
+    ignorePaths.some(pattern => {
+      const normalizedPattern = normalizeRepoPath(pattern).replace(/\/+$/, '')
+      return normalizedPattern && !/[*?]/.test(normalizedPattern) && repoPath.startsWith(`${normalizedPattern}/`)
+    })
+  const isIgnoredFile = absolute => {
+    const resolved = canonicalPath(absolute)
+    return excludedFiles.has(resolved) || repoPathsFor(resolved).some(matchesIgnoredRepoPath)
+  }
+  const isIgnoredDirectoryTree = absolute => repoPathsFor(absolute).some(repoPath =>
+    ignorePaths.some(pattern => {
+      const normalizedPattern = normalizeRepoPath(pattern)
+      const literalDirectory = !/[*?]/.test(normalizedPattern) && normalizedPattern.replace(/\/+$/, '') === repoPath
+      const subtreeGlob = normalizedPattern.endsWith('/**') && matchesGlob(repoPath, normalizedPattern.slice(0, -3))
+      return literalDirectory || subtreeGlob
+    }))
   const addFile = absolute => {
-    if (stopped || seen.has(absolute)) return
+    if (stopped || seen.has(absolute) || isIgnoredFile(absolute)) return
     seen.add(absolute)
 
     let st
@@ -288,7 +331,7 @@ const collectFilesDetailed = (targets, { includeDocs = false } = {}) => {
   }
 
   const walk = absolute => {
-    if (stopped) return
+    if (stopped || excludedFiles.has(canonicalPath(absolute))) return
     let st
     try {
       st = fs.lstatSync(absolute)
@@ -301,6 +344,7 @@ const collectFilesDetailed = (targets, { includeDocs = false } = {}) => {
       addFile(absolute)
       return
     }
+    if (isIgnoredDirectoryTree(absolute)) return
     if (SKIP_DIRS.has(path.basename(absolute))) return
     let names
     try {
@@ -373,11 +417,24 @@ const collectFilesDetailed = (targets, { includeDocs = false } = {}) => {
 
 export const collectFiles = (targets, options = {}) => collectFilesDetailed(targets, options).files
 
-export const scanTargets = ({ targets, entries, keys, includeDocs = false }) => {
-  const collected = collectFilesDetailed(targets, { includeDocs })
+export const scanTargets = ({
+  targets,
+  entries,
+  keys,
+  includeDocs = false,
+  ignoreModels = [],
+  ignorePaths = [],
+  ignoreRoots = [],
+  ignoredFiles = [],
+}) => {
+  const collected = collectFilesDetailed(targets, { includeDocs, ignorePaths, ignoreRoots, ignoredFiles })
   if (collected.validTargets.length === 0) throw new Error('no valid targets remain')
   const { files } = collected
   const pattern = buildModelPattern(keys)
+  const ignoredModelKeys = new Set(ignoreModels)
+  const ignoredCanonicalIds = new Set(ignoreModels.map(key => entries.get(key)?.entry.id ?? key))
+  const ignoresModel = (matched, id = null) =>
+    ignoredModelKeys.has(matched) || (id !== null && ignoredCanonicalIds.has(id))
   const modelRefs = []
   const candidateRefs = []
   const integrationHints = []
@@ -424,6 +481,7 @@ export const scanTargets = ({ targets, entries, keys, includeDocs = false }) =>
       let m
       while ((m = pattern.exec(lineText)) !== null) {
         const record = entries.get(m[1])
+        if (ignoresModel(m[1], record.entry.id)) continue
         const occurrence = [...lineText.matchAll(new RegExp(escapeRegExp(m[1]), 'g'))]
           .findIndex(match => match.index === m.index)
         const classification = classifyRef({
@@ -453,6 +511,7 @@ export const scanTargets = ({ targets, entries, keys, includeDocs = false }) =>
       }
 
       for (const candidate of findCandidates(lineText, entries)) {
+        if (ignoresModel(candidate)) continue
         const classification = classifyRef({
           file,
           line: i + 1,

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "model-eol",
-  "version": "0.2.4",
-  "description": "A machine-readable deprecation feed format for AI models, plus a zero-dependency checker and inventory CLI.",
+  "version": "0.3.0",
+  "description": "AI model deprecation feeds with a zero-dependency checker, inventory CLI, and migration bot.",
   "type": "module",
   "bin": {
-    "model-eol": "check.mjs"
+    "model-eol": "check.mjs",
+    "model-eol-bot": "bot/bot.mjs"
   },
   "scripts": {
-    "test": "node test/run.mjs && node refresh/test/run.mjs && node bot/test/run.mjs && node scripts/test-feed-changelog.mjs"
+    "test": "node test/run.mjs && node refresh/test/run.mjs && node bot/test/run.mjs && node scripts/test-action-contract.mjs && node bot/test/package.mjs && node scripts/test-feed-changelog.mjs"
   },
   "repository": {
     "type": "git",
@@ -31,7 +32,10 @@
   ],
   "files": [
     "check.mjs",
+    "bot.yml.example",
     "lib/",
+    "bot/bot.mjs",
+    "bot/lib/",
     "feeds/",
     "schema/",
     "SPEC.md",

package/schema/model-eol.bot-config.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://example.invalid/model-eol/0.1/bot-config.schema.json",
-  "title": "model-eol bot configuration",
-  "description": "Optional .model-eol.json configuration for the zero-dependency GitHub bot adapter.",
+  "title": "model-eol repository configuration",
+  "description": "Optional strict .model-eol.json configuration shared by the zero-dependency CLI, Action, and GitHub bot adapter.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -15,10 +15,11 @@
     "scope": {
       "enum": ["direct", "all"],
       "default": "direct",
-      "description": "Use direct API references only, or include generic model references."
+      "description": "Use the direct-first scope (direct API plus generic model references, leaving cloud/gateway references as hints), or include all tracked references."
     },
     "via": {
       "type": ["string", "null"],
+      "minLength": 1,
       "default": null,
       "description": "Optional distributor lifecycle clock, such as azure-ai-foundry."
     },
@@ -42,13 +43,13 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 },
           "default": [],
-          "description": "Canonical IDs or aliases to ignore. A canonical ID ignores all of its aliases."
+          "description": "Canonical IDs or aliases to ignore across CLI, Action, and bot. Either form ignores every alias of the canonical feed entry."
         },
         "paths": {
           "type": "array",
           "items": { "type": "string", "minLength": 1 },
           "default": [],
-          "description": "Repo-relative simple globs supporting *, **, and ?."
+          "description": "Repo-relative simple globs supporting *, **, and ?. Matching paths are excluded before file coverage checks where possible."
         }
       },
       "default": { "models": [], "paths": [] }
@@ -71,17 +72,20 @@
       "properties": {
         "command": {
           "type": ["string", "null"],
+          "minLength": 1,
           "default": null,
-          "description": "Opt-in command run in the temporary clone for changed patches."
+          "description": "Opt-in evaluation command. Direct bot --eval runs it per changed patch in a temporary clone; the split example workflow runs it once as a read-only plan preflight."
         },
         "timeout_ms": {
           "type": "integer",
-          "minimum": 1,
+          "minimum": 1000,
+          "maximum": 3600000,
           "default": 600000
         },
         "max_report_bytes": {
           "type": "integer",
-          "minimum": 0,
+          "minimum": 1,
+          "maximum": 8388608,
           "default": 65536
         },
         "pass_env": {